docs: tighten repo docs and validation entrypoints

Author: GsCommand

CHANGELOG.md

@@ -10,3 +10,9 @@
 - Established Commons v1.1.0 as the active in-repo schema surface for new integrations
 - Retained v1.0.0 as the last pinned canonical release until v1.1.0 pinning is completed
 - Preserved earlier schema versions for compatibility and historical reference
+
+## 1.0.0
+
+- Initial Protocol-Commons release with versioned Commons schemas, shared primitives, and example vectors under `schemas/v1.0.0` and `examples/v1.0.0`
+- Introduced the canonical Commons verb set and request/receipt validation model for cross-runtime interoperability
+- Established the historical pinned release line that `v1.1.0` now extends as the current in-repo schema family

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing — Protocol Commons
+
+Protocol-Commons contributions must be small, traceable, and validation-complete.
+
+## Pull Request Spine
+
+Every PR should:
+
+1. Open from a focused branch for one change set
+2. Explain the semantic, schema, or documentation impact
+3. Include schema/example updates together when contracts change
+4. Pass the required validation commands before review
+5. Update release notes when the visible contract changes
+
+## Commit Convention
+
+Use a clear imperative subject line. Prefer conventional-style prefixes when they fit, for example:
+
+- `docs: tighten README contract language`
+- `feat: add new commons verb schema family`
+- `fix: correct receipt validation example`
+
+## Required Checks
+
+Run the canonical validation command before opening a PR:
+
+```bash
+npm install
+npm run validate
+```
+
+Run additional checks when packaging behavior changes:
+
+```bash
+npm run test:smoke:import
+npm run test:smoke:pack
+```
+
+## When Schemas Change
+
+If you change a schema or semantic contract, you must also:
+
+- Add or update matching examples/tests
+- Preserve immutability of published version directories unless the change is explicitly historical documentation only
+- Review `SCHEMAS.md` and `SPEC.md` for versioning implications
+- Update `CHANGELOG.md` when the externally visible contract changes
+- Update `RESOLUTION.md`, provenance, or checksum artifacts if the release process requires it
+
+## Versioning Expectations
+
+- Treat published release lines as append-only history
+- Use a new version directory for semantic changes
+- Keep `v1.1.0` documented as the current in-repo line until a newer line is intentionally introduced
+
+## Review Standard
+
+A contribution is ready for review when a maintainer can understand the intent quickly, reproduce validation locally, and see exact schema/example/doc alignment without extra interpretation.

ONBOARDING.md

@@ -72,21 +72,16 @@ If a change is not reflected here → **not canonical.**
 Protocol-Commons governs TXT keys that resolve schema semantics.  
 Canonical definitions → `SPEC.md`.
 
-## 4. Contribution Flow
-1. Open an Issue describing context + verb(s)
-2. Design change per `SCHEMAS.md`
-3. Update schemas + examples
-4. Validate:
+## 4. Working Norms
 
-```
-npm install
-npm run validate
-npm run validate:examples
-```
-5. Update `RESOLUTION.md`, provenance
-6. Submit PR with version class (MAJOR/MINOR/PATCH)
+Before changing schemas or examples:
+
+- Read `SCHEMAS.md` for layout and versioning rules
+- Read `SPEC.md` for the contract you are changing
+- Treat published version folders as immutable unless governance explicitly opens a new release line
+- Use `npm run validate` as the default repo-wide verification command
 
-Once approved → tagged + pinned.
+If you are preparing a contribution, follow `CONTRIBUTING.md`.
 
 ## 5. What “Good” Looks Like
 

README.md

@@ -59,6 +59,28 @@ If agents cannot agree on what actions mean, interoperability breaks.
 
 ---
 
+## Table of Contents
+- [Real verbs. Real receipts.](#real-verbs-real-receipts)
+- [Quickstart](#quickstart)
+- [Commons v1.1.0](#commons-v110)
+- [What Commons enables](#what-commons-enables)
+- [Why this exists](#why-this-exists)
+- [Canonical Verbs](#canonical-verbs)
+- [Overview](#overview)
+- [Key Principles](#key-principles)
+- [This is not…](#this-is-not)
+- [CommandLayer Protocol Stack](#commandlayer-protocol-stack)
+- [Status](#status)
+- [Repository Structure](#repository-structure)
+- [Manifest](#manifest)
+- [Immutability & Checksums](#immutability--checksums)
+- [Validation](#validation)
+- [License](#license)
+- [Next Layers](#next-layers)
+- [References](#references)
+
+---
+
 ## Real verbs. Real receipts.
 
 ```jsonc
@@ -89,14 +111,13 @@ Every v1.1.0 Commons receipt uses the same evidence-oriented spine:
 
 - `status`
 - `timestamp`
-- `agent`
 - `request_hash`
-- `result_hash` *(optional)*
-- `result_cid` *(optional)*
 - `summary` *(required on success)*
 - `signature`
 - `error` *(required on error)*
 
+`result_hash` and `result_cid` are optional evidence fields. `agent` is optional and may be included when the actor/provider identity needs to be surfaced.
+
 ---
 
 ## Quickstart
@@ -194,7 +215,7 @@ The receipt contract is proof-oriented rather than transport-oriented:
   "version": "1.1.0",
   "status": "ok | error",
   "timestamp": "<RFC 3339 date-time>",
-  "agent": "<stable signer identity>",
+  "agent": "<optional stable signer identity>",
   "request_hash": "sha256:<64 lowercase hex chars>",
   "result_hash": "sha256:<64 lowercase hex chars>",
   "result_cid": "<optional content identifier>",
@@ -206,28 +227,6 @@ The receipt contract is proof-oriented rather than transport-oriented:
 
 These fields let consumers verify that a signer attested to a specific request hash and, when present, a specific result hash or result CID. Commons does not define transport settlement, execution proofs beyond these fields, or any x402-specific wrapping.
 
-## Table of Contents
-- [Real verbs. Real receipts.](#real-verbs-real-receipts)
-- [Quickstart](#quickstart)
-- [Commons v1.1.0](#commons-v110)
-- [What Commons enables](#what-commons-enables)
-- [Why this exists](#why-this-exists)
-- [Canonical Verbs](#canonical-verbs)
-- [Overview](#overview)
-- [Key Principles](#key-principles)
-- [This is not…](#this-is-not)
-- [CommandLayer Protocol Stack](#commandlayer-protocol-stack)
-- [Status](#status)
-- [Repository Structure](#repository-structure)
-- [Manifest](#manifest)
-- [Immutability & Checksums](#immutability--checksums)
-- [Validation](#validation)
-- [License](#license)
-- [Next Layers](#next-layers)
-- [References](#references)
-
----
-
 ## Why this exists
 
 Fragmented agents create isolated ecosystems and brittle automation.
@@ -384,7 +383,6 @@ Commons gives upper layers a stable meaning layer to build around.
 │           ├── <verb>.request.schema.json
 │           └── <verb>.receipt.schema.json
 └── scripts/
-    ├── ajv-run.mjs
     ├── validate-all.mjs
     └── validate-examples.mjs
 ```
@@ -418,12 +416,11 @@ Published version directories must not be edited in place.
 
 ## Validation
 
-Available commands:
+Use `npm run validate` as the canonical repo-wide validation command. For targeted checks, the repo also exposes:
 
 ```bash
 npm run validate:schemas
 npm run validate:examples
-npm run validate
 ```
 
 These commands compile schemas in strict Ajv mode and validate the shipped examples for both `v1.0.0` and `v1.1.0`.

package.json

@@ -49,7 +49,6 @@
     "ajv-formats": "^3.0.1"
   },
   "scripts": {
-    "validate:schema": "node scripts/ajv-run.mjs",
     "validate:schemas": "node scripts/validate-all.mjs",
     "validate:examples": "node scripts/validate-examples.mjs",
     "validate:all": "npm run validate:schemas && npm run validate:examples",