Skip to content

docs: align v1.1.0 Commons docs to flat schema contract#4

Merged
GsCommand merged 1 commit intomainfrom
codex/update-documentation-for-v1.1.0-consistency
Mar 18, 2026
Merged

docs: align v1.1.0 Commons docs to flat schema contract#4
GsCommand merged 1 commit intomainfrom
codex/update-documentation-for-v1.1.0-consistency

Conversation

@GsCommand
Copy link
Contributor

Motivation

  • Make repository documentation authoritative and presentation-ready for the v1.1.0 flat Commons schema family by removing legacy/x402/trace framing and stale examples.
  • Ensure quickstart and validation guidance are accurate and point to the actual working commands and schema layout.
  • Clarify the trust model to match the schemas' hash+signature receipts and explicitly mark v1.0.0 as legacy.

Description

  • Updated README.md to remove legacy trace/x402 framing, replace stale examples with real v1.1.0 request/receipt fields, change CID: PENDING to CID: TBD (pre-release), and replace the broken npx cl-validate guidance with working npm/node validation commands and examples.
  • Added a dedicated Commons v1.1.0 section to SPEC.md that defines the flat request shape and the proof-oriented receipt shape (fields: verb, version, status, timestamp, request_hash, optional result_hash/result_cid, summary on success, signature, error on failure), and marked v1.0.0 as legacy and structurally different.
  • Rewrote SCHEMAS.md to document the current flat schemas/v1.1.0/commons/<verb>/ layout, update deterministic $id examples to the v1.1.0 pattern, remove references that implied nested requests/ and receipts/ in v1.1.0, and align validation guidance with the repository scripts.
  • Files modified: README.md, SPEC.md, SCHEMAS.md.
  • Noted remaining inconsistencies: manifest.json still contains "schemas_cid": "PENDING" and checksum-generation scripts default to schemas/v1.0.0, which may be surprising given v1.1.0 is the current layout.

Testing

  • Ran repository validation: npm run validate (this runs validate:schemas and validate:examples); result: all schemas compiled and all examples for both v1.0.0 and v1.1.0 validated successfully (no failures).
  • Verified scripts/validate-all.mjs and scripts/validate-examples.mjs run cleanly in Ajv 2020-12 strict-style configuration; outcome: success.

Codex Task

@GsCommand GsCommand merged commit a48dc23 into main Mar 18, 2026
1 check passed
@GsCommand GsCommand deleted the codex/update-documentation-for-v1.1.0-consistency branch March 20, 2026 01:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant