docs: add consolidated schema reference

[aryansk]

Summary

Add a consolidated, linked field reference for CiteSeal's tweet.json, agent-bundle, and manifest data surfaces.

Type of change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Test / fixture improvement

Changes

• Add docs/schema-reference.md with required, optional, and nested fields for all three versioned surfaces.
• Link the new reference from the README documentation index.
• Keep the reference aligned with the checked-in schemas and the structural tweet.json validator.

Testing

• python tools/citeseal.py lint passes (no new pyflakes issues)
• python tools/scripts/tweet_validate.py tests/fixtures/... passes
• python -m pytest tests/ passes (242 passed)
• Tested manually (describe below)

Manual testing details:

The documentation was checked against the schema files and validator source; no runtime behavior changed.

Checklist

• My code follows the existing style and structure.
• I have not introduced new dependencies without justification.
• I have removed any personal credentials, session tokens, or third-party media from my changes.
• My changes do not enable bulk-scraping or bypassing platform access controls.
• If I added/modified tweet.json fields, I updated the schema and validation accordingly. (Not applicable: no fields changed.)
• I have updated relevant documentation.

Closes #2

[atomize-lab]

Maintainer review — changes requested

The schema tables and README link are well scoped, and the deterministic checks pass. One acceptance item remains blocking:

CS-17-001 — Blocking — missing the #12 minimum tweet.json example

Location: docs/schema-reference.md (the tweet.json section, before the field table is a natural placement)

#12 was explicitly folded into #2's acceptance criteria, requiring a copy-pasteable minimum tweet.json example. This diff contains no fenced JSON example, so a reader still cannot copy a minimal document from the new reference page.

Please add a valid fenced json object containing at least the four required fields (tweet_id, tweet_url, author_handle, datetime_utc), with concrete placeholder values. Including the recommended fields with minimal values is preferable if the example is intended to validate without warnings.

Deterministic verification performed at c902e280199c

• Environment: pytest 9.1.1; pyflakes 3.4.0 import succeeded from the repository .venv.
• Full suite: 242 passed, 1 warning.
• CLI lint: passed using the repository .venv/bin/pyflakes.
• Fixture validation: 1 directory, 0 errors, 0 warnings.
• Schema coverage: tweet top-level 10/10, agent bundle 35/35, manifest 41/41; all three required table headers exist; all relative links resolve.
• #12 acceptance probe: failed (0 fenced JSON blocks / no minimum example).

Please update the draft and re-request review; no maintainer edits were made to the contributor branch.

[atomize-lab]

Review summary

Verdict: changes requested — deterministic tests and schema-field coverage pass, but docs/schema-reference.md is missing the copy-pasteable minimum tweet.json example required by #12 as part of #2. See the formal review for finding CS-17-001 and the exact verification results.

The PR remains the sole authoritative implementation for #2. Please push the documentation fix to this branch and re-request review.

[aryansk]

Thanks for the review. I added the requested copy-pasteable minimum tweet.json example to docs/schema-reference.md. It includes all four required fields plus every recommended top-level field, with empty arrays for optional collections.

Validation completed on the updated branch: python tools/citeseal.py lint passes with pyflakes, and python -m pytest tests/ -q passes with 242 tests and 1 warning. The fix is pushed at c5a94f1. Please re-review when convenient.

[atomize-lab]

Maintainer re-review — approved

The new commit resolves CS-17-001: docs/schema-reference.md now contains a copy-pasteable fenced JSON example with all four required and all six recommended top-level tweet.json fields. The example passes the real validator with 0 errors and 0 warnings.

Deterministic verification at c5a94f10f447

• Repository environment: pytest 9.1.1; pyflakes 3.4.0 import succeeded from the repository .venv.
• Full suite: 242 passed, 1 warning.
• CLI lint: passed using the repository .venv/bin/pyflakes.
• Fixture validation: 1 directory, 0 errors, 0 warnings.
• Schema coverage: tweet top-level 10/10, agent bundle 35/35, manifest 41/41; required flags match both JSON Schemas.
• Documentation gates: all three table headers present, README link present, relative links resolve.
• Minimum example: one fenced JSON block, all 10 expected top-level keys, validator 0 errors / 0 warnings.

No blocking correctness, compatibility, security, or maintainability findings remain in the PR diff. No maintainer edits were made to the contributor branch. The PR is still a draft, so please mark it ready for review when you consider it complete.

[atomize-lab]

Re-review summary

Verdict: acceptance checks pass; latest commit approved.

• CS-17-001 resolved: the minimum tweet.json example is present, copy-pasteable, complete, and validates cleanly.
• Full local verification at c5a94f10f447: 242 passed, 1 warning; CLI lint passed; fixture validation reported 0 errors / 0 warnings; schema/reference coverage and links passed.
• No new blocking findings were identified.

The PR was not merged because it remains a draft. GitHub also currently reports no CI/check runs for this head. @aryansk, please mark the PR ready for review when ready; the existing claimed implementation remains authoritative for #2.

[aryansk]

Thanks for the detailed re-review and approval. I’ve marked the existing PR ready for review as requested.

The authoritative head remains c5a94f10f447f841cd90a2fc47d5b856427082cf; I’m not changing the scoped implementation. I’ve recorded the reported validation: 242 tests passed, CLI lint passed, fixture validation reported 0 errors and 0 warnings, and the schema/documentation checks passed. GitHub currently reports no CI runs for this head.

[atomize-lab]

CI trigger note

The PR was marked ready after its latest commit, but this repository’s current workflow does not include the pull_request.ready_for_review activity, so GitHub created no checks for the approved head. I am closing and immediately reopening the PR solely to trigger the standard pull_request.reopened CI event. No code changes are requested and the authoritative head remains c5a94f10f447f841cd90a2fc47d5b856427082cf.

[atomize-lab]

Merged

Thank you, @aryansk. The approved head c5a94f10f447f841cd90a2fc47d5b856427082cf has been merged into main.

• PR-head CI: Ubuntu and Windows passed — run 31455779166
• Merge commit: 3826c0026e381dab204bdb12f5d8a79bdec4b96a
• Post-merge main CI: Ubuntu and Windows passed — run 31456272275
• Linked issue [good first issue] Add a schema reference page to docs/ #2 was closed as completed.

[aryansk]

Confirmed on my side: the approved head c5a94f1 is merged into main at 3826c002 with issue #2 closed. Thanks for the merge receipt.