docs: tighten release trust surfaces (#27)

Author: GsCommand

CHANGELOG.md

@@ -0,0 +1,17 @@
+# CHANGELOG — Protocol-Commercial
+
+## v1.1.0
+
+Current release.
+
+- adopts the flat per-verb schema layout under `schemas/v1.1.0/`
+- treats `v1.1.0` as the canonical line for new integrations
+- retains `v1.0.0` as a published legacy line for compatibility and audit
+- ships release metadata, examples, and checksum tooling aligned to the current line
+
+## v1.0.0
+
+Initial release.
+
+- published the original commercial schema and example surface
+- used the historical nested `requests/` and `receipts/` path model retained for compatibility

GOVERNANCE.md

@@ -24,3 +24,9 @@ Steward duties include:
 | New version line | Steward approval with release metadata refresh |
 | Public current-path model change | Steward approval with cross-repo doc alignment |
 | In-place published mutation | Prohibited |
+
+## Steward succession
+
+If the current steward becomes unavailable, they may designate a successor publicly in repository governance records or release metadata.
+
+If no prior designation exists, maintainers controlling the canonical repository may appoint a successor by public repository record, with the expectation that version immutability and published path continuity are preserved.

INTEGRATOR.md

@@ -34,7 +34,7 @@ Normative interpretive docs:
 
 ## Safe consumer path
 
-1. Confirm the package version is `1.1.0` and that `manifest.json` reports `status: current`.
+1. Confirm the release version is `1.1.0` and that `manifest.json` reports `status: current`.
 2. Load `schemas/v1.1.0/index.json` and select the request and receipt schema paths you need.
 3. Configure your validator from the flat per-verb schema files under `schemas/v1.1.0/commercial/<verb>/`.
 4. Run checksum verification before mirroring or vendoring artifacts using the canonical commands in `README.md#validation-commands`.
@@ -51,7 +51,7 @@ Do not teach `v1.0.0` paths as current implementation guidance.
 
 ## Checksums and provenance
 
-The checksum-covered payload for this release is intentionally narrow:
+The authoritative checksum-boundary and release-state rules live in `SPEC.md` and `POLICY.md`.
 
 - `schemas/v1.1.0/`
 - `examples/v1.1.0/`

ONBOARDING.md

@@ -6,19 +6,14 @@ This document is an orientation guide for the active v1.1.0 release line. Contri
 
 Use this document to understand the repository shape, release line, and maintainer intent before editing.
 
+For the authoritative version policy, checksum boundary, and validation requirements, see `POLICY.md` and `SPEC.md`.
+
 ## External consumer workflow
 
-1. Install dependencies or the published package.
-   ```bash
-   npm install @commandlayer/commercial
-   ```
+1. Use the repository contents directly, or a published distribution only after release metadata confirms it.
 2. Confirm the current line in `manifest.json` and use `schemas/v1.1.0/index.json` as the authoritative schema map.
 3. Choose flat schemas under `schemas/v1.1.0/commercial/<verb>/` for validator configuration.
-4. Verify the machine-artifact set before mirroring or vendoring.
-   ```bash
-   npm run validate:integrity
-   sha256sum -c checksums.txt
-   ```
+4. Run the maintained verification commands listed in `SPEC.md` before mirroring or vendoring.
 5. Treat `examples/v1.1.0/commercial/<verb>/valid/` and `invalid/` as conformance fixtures.
 6. Use `v1.0.0` only when compatibility with the historical nested path model is required.
 
@@ -51,13 +46,10 @@ High-level maintainer sequence:
 1. Never mutate a published version directory in place after release.
 2. Create a new `schemas/vX.Y.Z/` and `examples/vX.Y.Z/` tree.
 3. Update `package.json`, `manifest.json`, README, SPEC, policy docs, and workflow assumptions.
-4. Draft release notes for the new line before publication.
+4. Draft release notes and changelog updates for the new line before publication.
 5. Regenerate checksums for the new current line's machine-artifact set.
 
-For the current line, the canonical path model is flat:
-
-- `https://commandlayer.org/schemas/vX.Y.Z/commercial/<verb>/<verb>.request.schema.json`
-- `https://commandlayer.org/schemas/vX.Y.Z/commercial/<verb>/<verb>.receipt.schema.json`
+For the canonical path model and namespace rules, see `SPEC.md`.
 
 ## Manual publication follow-up
 
@@ -76,4 +68,4 @@ The repository does not automate publication, GitHub Release publication, IPFS p
 - Keep schema paths flat and mirror-safe.
 - Keep checksum scope explicit.
 - Keep GitHub Releases and repository docs in sync.
-- Prefer exactness over deduplication.
+- Prefer linking over duplication.

README.md

@@ -2,7 +2,7 @@
 
 Protocol-Commercial v1.1.0 is the current CommandLayer commercial schema line.
 
-This README describes the current v1.1.0 release line and its release packaging surface. Repo-wide governance, security posture, and checksum-boundary provenance live in the dedicated meta docs.
+This README is a release-orientation document for the current line. The normative specification lives in `SPEC.md`. Release policy, checksum-boundary policy, and version-lifecycle rules live in `POLICY.md`.
 
 It defines the canonical commercial overlays that sit on top of Protocol-Commons v1.1.0. Commons defines base semantic actions. Commercial defines the monetized, settlement-aware request and receipt contracts that agents and runtimes use when value moves.
 
@@ -24,11 +24,16 @@ This README is a repo-wide orientation document for the current release line and
 - **Current canonical schema root:** `https://commandlayer.org/schemas/v1.1.0/`
 - **Current package entrypoint:** `schemas/v1.1.0/index.json`
 - **Historical legacy line:** `v1.0.0`, retained under `schemas/v1.0.0/` and `examples/v1.0.0/`
+- **Changelog:** `CHANGELOG.md`
 - **Release note draft for GitHub Releases:** `releases/v1.1.0.md`
 
-`v1.1.0` is flat. Its canonical schema URIs are the exact file-mirror paths published under `https://commandlayer.org/schemas/v1.1.0/commercial/<verb>/`.
+For the authoritative version policy and checksum-boundary rules, see `POLICY.md`. For normative identity and path rules, see `SPEC.md`.
 
-`v1.0.0` is historical only. Its older nested `requests/` and `receipts/` directories remain published for compatibility and audit, not as current teaching.
+## Canonical namespace and source of truth
+
+The `commandlayer.org` `$id` namespace is canonical for published Protocol-Commercial schemas.
+
+This repository is the source of truth for those schema files and release metadata. Public mirrors or hosted copies under `commandlayer.org` may be unavailable temporarily; that does not change the canonical `$id` values or the repository-local release contents.
 
 ## Schema identity and trust
 
@@ -70,6 +75,8 @@ For consumers who need the shortest safe path:
 5. Ignore `v1.0.0` unless you are maintaining compatibility with historical nested paths. Current automated validation targets `v1.1.0`; retained `v1.0.0` artifacts remain published for compatibility and audit without equal current-line guarantees.
 6. Treat schemas and `manifest.json` as normative machine artifacts. Treat examples as illustrative conformance fixtures. Treat prose docs as normative interpretation and release-process guidance.
 
+Package-install instructions are intentionally omitted here because npm publication for `@commandlayer/commercial` could not be verified from this repository alone.
+
 A longer external-consumer workflow lives in `INTEGRATOR.md`.
 
 ## Commercial execution model
@@ -150,6 +157,7 @@ protocol-commercial/
 │   └── v1.1.0/commercial/<verb>/{valid,invalid}/
 ├── manifest.json
 ├── checksums.txt
+├── CHANGELOG.md
 ├── INTEGRATOR.md
 └── scripts/
 ```
@@ -262,19 +270,14 @@ Protocol-Commons and Protocol-Commercial therefore tell one coherent story:
 
 ## Checksum boundary and provenance summary
 
-The v1.1.0 checksum-covered machine-artifact set is intentionally limited to:
-
-- `schemas/v1.1.0/`
-- `examples/v1.1.0/`
-- `manifest.json`
+The checksum boundary is defined normatively in `SPEC.md` and governed by `POLICY.md`.
 
 `checksums.txt` is the generated hash ledger for that machine-artifact set; it describes that surface but is not itself part of the hashed payload, so checksum verification confirms covered files only relative to the checked-in `checksums.txt` ledger and does not independently authenticate that ledger. Release-defining prose docs such as `README.md`, `SPEC.md`, `POLICY.md`, `SECURITY_PROVENANCE.md`, `INTEGRATOR.md`, and `ONBOARDING.md` are authoritative guidance, but they are outside the checksum surface unless the tooling is expanded deliberately in a later release.
 
 For external verification, the minimal path is:
 
-1. Install or vendor the package.
-2. Inspect `manifest.json` to confirm the current line is `v1.1.0`.
-3. Validate checksum coverage with `npm run validate:integrity`.
-4. Verify local file hashes with `sha256sum -c checksums.txt`.
-5. Load `schemas/v1.1.0/index.json` and bind validators from the listed request and receipt schema paths.
-6. Ignore `v1.0.0` unless compatibility requires the historical line.
+1. Inspect `manifest.json` to confirm the current line is `v1.1.0`.
+2. Run `npm run validate:integrity`.
+3. Run `sha256sum -c checksums.txt`.
+4. Load `schemas/v1.1.0/index.json` and bind validators from the listed request and receipt schema paths.
+5. Ignore `v1.0.0` unless compatibility requires the historical line.

SECURITY.md

@@ -29,8 +29,10 @@ Protocol-Commercial provides schema-level security properties, not transaction o
 - keep x402 references typed and minimal
 - do not let current-line docs teach superseded path models
 
-## Verification commands
+## Verification summary
 
 Use the canonical validation command surface in `README.md#validation-commands`. For security review, `npm run validate:schemas` is the direct schema/metadata drift check, and `sha256sum -c checksums.txt` verifies only the checksum-covered machine-artifact surface, not release prose docs.
 
 Security contact: `dev@commandlayer.org`
+
+PGP: none currently provided for this repository.

SPEC.md

@@ -36,11 +36,13 @@ Release-defining prose docs remain normative for interpretation, but they are ou
 ## 3. Version and identity rules
 
 1. Every v1.1.0 schema MUST use a stable `$id` under `https://commandlayer.org/schemas/v1.1.0/...`.
-2. A schema file path and its `$id` MUST agree exactly.
-3. A v1.1.0 schema MUST NOT be mutated in place after release publication.
-4. Breaking or meaning-changing edits require a new version directory.
-5. `manifest.json` MUST identify the current release line and any retained legacy lines.
-6. `checksums.txt` MUST enumerate the canonical machine-verifiable release artifact set and MUST NOT be described as protecting prose docs it does not hash.
+2. The `commandlayer.org` namespace is canonical, but this repository is the source of truth for the corresponding schema files and release metadata.
+3. Public hosting or mirrors for `commandlayer.org` MAY be unavailable temporarily; that does not change canonical `$id` values or repository-local release contents.
+4. A schema file path and its `$id` MUST agree exactly.
+5. A v1.1.0 schema MUST NOT be mutated in place after release publication.
+6. Breaking or meaning-changing edits require a new version directory.
+7. `manifest.json` MUST identify the current release line and any retained legacy lines.
+8. `checksums.txt` MUST enumerate the canonical machine-verifiable release artifact set and MUST NOT be described as protecting prose docs it does not hash.
 
 ## 4. Current path model
 
@@ -149,6 +151,8 @@ A conformant release MUST satisfy all of the following:
 - `manifest.json` and `schemas/v1.1.0/index.json` agree on the current verb set and path inventory
 - `npm test` passes as the current-line validation aggregate
 - `npm run validate:schemas` passes
+- `npm run validate:examples` passes
+- `npm run validate:integrity` passes
 - `sha256sum -c checksums.txt` passes for the checksum-covered machine-artifact set
 - repository metadata does not drift from the published current line
 

package.json

@@ -45,6 +45,7 @@
     "checksums.txt",
     "manifest.json",
     "README.md",
+    "CHANGELOG.md",
     "SPEC.md",
     "POLICY.md",
     "GOVERNANCE.md",

schemas/v1.1.0/index.json

@@ -34,5 +34,7 @@
       "receipt_schema": "schemas/v1.1.0/commercial/verify/verify.receipt.schema.json",
       "examples": "examples/v1.1.0/commercial/verify"
     }
-  ]
+  ],
+  "document_type": "inventory",
+  "description": "Machine-readable inventory of the current Protocol-Commercial release line. This file is an index, not a validation schema."
 }