Tighten public release surface (#23)

Author: GsCommand

INTEGRATOR.md

@@ -0,0 +1,68 @@
+# INTEGRATOR — Protocol-Commercial v1.1.0
+
+This document is the external-consumer quickstart for the current commercial release line.
+
+## What to import
+
+Use the package root or the current index directly:
+
+```js
+import commercialIndex from '@commandlayer/commercial';
+```
+
+The package root resolves to `schemas/v1.1.0/index.json`. That index is the current machine-readable map of every canonical verb schema in the release.
+
+## What is normative vs illustrative
+
+Normative machine artifacts:
+
+- `schemas/v1.1.0/`
+- `schemas/v1.1.0/index.json`
+- `manifest.json`
+
+Illustrative conformance fixtures:
+
+- `examples/v1.1.0/commercial/<verb>/valid/`
+- `examples/v1.1.0/commercial/<verb>/invalid/`
+
+Normative interpretive docs:
+
+- `README.md`
+- `SPEC.md`
+- `POLICY.md`
+- `SECURITY_PROVENANCE.md`
+
+## Safe consumer path
+
+1. Confirm the package 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:
+   ```bash
+   npm run validate:integrity
+   sha256sum -c checksums.txt
+   ```
+5. Use `examples/v1.1.0/` as conformance fixtures, not as a substitute for schema requirements.
+
+## Choosing between v1.1.0 and v1.0.0
+
+Choose `v1.1.0` unless you are maintaining compatibility with an older integration that still depends on the published historical nested `requests/` and `receipts/` paths.
+
+- `v1.1.0` is the current canonical flat line.
+- `v1.0.0` is retained legacy for compatibility and audit.
+
+Do not teach `v1.0.0` paths as current implementation guidance.
+
+## Checksums and provenance
+
+The checksum-covered payload for this release is intentionally narrow:
+
+- `schemas/v1.1.0/`
+- `examples/v1.1.0/`
+- `manifest.json`
+
+`checksums.txt` is the ledger for that payload. It is not itself inside the hashed set. Prose docs remain authoritative for interpretation and release process, but they are outside the checksum boundary.
+
+## TypeScript guidance
+
+There is no public `examples/v1.1.0/**/ts/` teaching surface in the current release. If a future release restores TypeScript examples, they should be explicitly governed, validated, and documented before they are treated as part of the public implementer surface.

ONBOARDING.md

@@ -1,10 +1,26 @@
 # ONBOARDING — Protocol-Commercial
 
-This document describes the current-line maintainer workflow for the active v1.1.0 release line.
+This document describes both the external-consumer path and the maintainer workflow for the active v1.1.0 release line.
 
 ## Document scope
 
-This document is the maintainer workflow for the current release line.
+This document is the operational workflow for the current release line.
+
+## External consumer workflow
+
+1. Install dependencies or the published package.
+   ```bash
+   npm install @commandlayer/commercial
+   ```
+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
+   ```
+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.
 
 ## Maintainer workflow
 
@@ -20,7 +36,7 @@ This document is the maintainer workflow for the current release line.
    npm run validate:examples
    npm run validate:integrity
    ```
-4. Regenerate checksums.
+4. Regenerate checksums when checksum-covered machine artifacts change.
    ```bash
    npm run generate:checksums
    ```
@@ -40,19 +56,20 @@ When editing only prose docs outside the checksum surface, do not regenerate `ch
 1. Create a new flat directory under `schemas/<new-version>/commercial/<verb>/`.
 2. Add exactly one request schema and one receipt schema.
 3. Create matching example folders under `examples/<new-version>/commercial/<verb>/valid` and `invalid`.
-4. Add at least one valid request, one valid receipt, one invalid request, and one invalid receipt.
+4. Add at least one valid request, one alternate valid request or receipt, one invalid request, and one invalid receipt.
 5. Make every invalid example isolate a single intended failure when practical.
-6. Do not add unvalidated TypeScript example directories to the current-line example tree.
+6. Do not add an ungoverned `examples/v1.1.0/**/ts/` surface to the current line.
 7. Update `manifest.json`, `schemas/<version>/index.json`, validation expectations, and checksums.
-8. Update README, SPEC, and any release-process docs if the normative surface changed.
+8. Update README, INTEGRATOR, SPEC, and release-process docs if the public teaching surface changed.
 9. Confirm public docs controlled by this repo still teach the exact current path model and current script names.
 
 ## Version bumps
 
 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. Regenerate checksums for the new current line's machine-artifact set.
+4. Draft release notes 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:
 
@@ -61,17 +78,19 @@ For the current line, the canonical path model is flat:
 
 ## Manual publication follow-up
 
-The repository does not automate publication, IPFS pinning, CID capture, or mirror updates. If your release process uses those steps, perform them manually after the new version line has passed validation:
+The repository does not automate publication, GitHub Release publication, IPFS pinning, CID capture, or mirror updates. If your release process uses those steps, perform them manually after the new version line has passed validation:
 
-1. Pin the checksum-covered release artifact set to IPFS, if that distribution channel is being used for the release.
-2. Capture resulting CIDs in the external release record if your publication process requires them.
-3. Update commandlayer.org mirrors to match the release paths exactly.
-4. Update any Agent Card schema bindings that reference the superseded version.
+1. Publish the GitHub Release using `releases/v1.1.0.md` or the corresponding new-version draft.
+2. Pin the checksum-covered release artifact set to IPFS, if that distribution channel is being used for the release.
+3. Capture resulting CIDs in the external release record if your publication process requires them.
+4. Update commandlayer.org mirrors to match the release paths exactly.
+5. Update any Agent Card schema bindings that reference the superseded version.
 
 ## Release hygiene
 
 - Keep the current line obvious.
 - Keep legacy lines explicitly marked as legacy.
 - Keep schema paths flat and mirror-safe.
 - Keep checksum scope explicit.
+- Keep GitHub Releases and repository docs in sync.
 - Prefer exactness over deduplication.

README.md

@@ -24,6 +24,7 @@ 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/`
+- **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>/`.
 
@@ -45,6 +46,29 @@ The stack story is singular:
 - Agent Cards point directly at the current commercial schema URIs.
 - Runtimes execute those contracts but do not redefine them.
 
+## Integrator quickstart
+
+For consumers who need the shortest safe path:
+
+1. Install the package and import the current index entrypoint.
+   ```bash
+   npm install @commandlayer/commercial
+   ```
+   ```js
+   import commercialIndex from '@commandlayer/commercial';
+   ```
+2. Treat `schemas/v1.1.0/index.json` as the authoritative map of current schemas and verb inventory.
+3. Prefer `schemas/v1.1.0/commercial/<verb>/<verb>.request.schema.json` and `...receipt.schema.json` directly for validator configuration.
+4. Verify the machine-artifact set before mirroring or vendoring:
+   ```bash
+   npm run validate:integrity
+   sha256sum -c checksums.txt
+   ```
+5. Ignore `v1.0.0` unless you are maintaining compatibility with historical nested paths.
+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.
+
+A longer external-consumer workflow lives in `INTEGRATOR.md`.
+
 ## Commercial execution model
 
 Protocol-Commercial is x402-first.
@@ -86,13 +110,13 @@ The verbs use those layers intentionally:
 
 ## Verb set
 
-| Verb | Purpose |
-| --- | --- |
-| `authorize` | Reserve payment authority before capture or settlement |
-| `checkout` | Finalize an order and request commercial capture |
-| `purchase` | Complete a one-step paid commercial action |
-| `ship` | Advance commercial fulfillment state for a settled checkout or purchase |
-| `verify` | Verify a commercial receipt, settlement, payment, or shipment target |
+| Verb | Purpose | Teaching note |
+| --- | --- | --- |
+| `authorize` | Reserve payment authority before capture or settlement | Teaches pre-capture approval, denial, and authorization evidence |
+| `checkout` | Finalize an order and request commercial capture | Teaches negotiated session state, amount binding, and settlement outcomes |
+| `purchase` | Complete a one-step paid commercial action | Teaches direct payment input without a separate checkout negotiation round |
+| `ship` | Advance commercial fulfillment state for a settled checkout or purchase | Teaches how fulfillment references upstream commercial settlement without replaying payment semantics |
+| `verify` | Verify a commercial receipt, settlement, payment, or shipment target | Teaches evidence-based attestation and inconclusive vs failed outcomes |
 
 ## Repository layout
 
@@ -120,14 +144,21 @@ protocol-commercial/
 │               └── verify.receipt.schema.json
 ├── examples/
 │   ├── v1.0.0/                     # published legacy line
-│   └── v1.1.0/commercial/<verb>/{valid,invalid,ts}/
+│   └── v1.1.0/commercial/<verb>/{valid,invalid}/
 ├── manifest.json
 ├── checksums.txt
+├── INTEGRATOR.md
 └── scripts/
 ```
 
 Protocol-Commercial v1.1.0 does **not** use a current-line `_shared/` tree. Every v1.1.0 request and receipt schema is self-contained, flat, and mirror-safe.
 
+Current-line example governance is equally explicit:
+
+- `valid/` contains illustrative conforming request and receipt fixtures.
+- `invalid/` contains isolated negative fixtures intended to fail validation cleanly.
+- No `examples/v1.1.0/**/ts/` tree is currently part of the public release surface.
+
 ## Scope boundaries
 
 This repository defines:
@@ -201,7 +232,6 @@ sha256sum -c checksums.txt
 - `npm run validate` runs the full validation suite for the current release line.
 - `npm run validate:schemas` checks current-line metadata, schema identity, layout, and manifest/index alignment expectations.
 - `npm run validate:examples` validates every current-line JSON valid and invalid example against the canonical schemas.
-- Current-line TypeScript example directories are intentionally excluded from the authoritative teaching surface; do not add `examples/v1.1.0/**/ts/` back without adding explicit validation and release governance for them.
 - `npm run validate:integrity` verifies the checksum file scope and hash coverage for the current release artifact set.
 - `checksums.txt` intentionally covers machine-validated release payloads only: `manifest.json`, `schemas/v1.1.0/index.json`, `schemas/v1.1.0/`, and `examples/v1.1.0/`.
 
@@ -211,12 +241,26 @@ Agent Cards v1.1.0 should bind directly to the current flat commercial schema UR
 
 Protocol-Commons and Protocol-Commercial therefore tell one coherent story:
 
+- Commons defines base actions.
+- Commercial defines monetized overlays.
+- Agent Cards point at the current flat commercial schema paths.
+- Legacy nested v1.0.0 paths remain published only for compatibility.
+
+## 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`
 
-`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. Release-defining prose docs such as `README.md`, `SPEC.md`, `POLICY.md`, `SECURITY_PROVENANCE.md`, and `ONBOARDING.md` are authoritative guidance, but they are outside the checksum surface unless the tooling is expanded deliberately in a later release.
+`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. 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:
 
-After any mutation to the checksum-covered set, regenerate `checksums.txt` and repin any release bundle that depends on those artifacts.
+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.

checksums.txt

@@ -1,26 +1,31 @@
 930cbbb3992d01385c1e5a64a4a04de5bac7c68a8b59a25a6c0e5507a1cea33f  examples/v1.1.0/commercial/authorize/invalid/001-authorize.request.invalid.json
 ef1e7e77e6c53ef918053918a1b9243505fef02a61b4899868cad36feebe42f3  examples/v1.1.0/commercial/authorize/invalid/900-authorize.receipt.invalid.json
 afbcee85906d0249ed0c60eecf40657832549ca8032a99154dd0e643b6d82884  examples/v1.1.0/commercial/authorize/valid/001-authorize.request.valid.json
+7f4a224807248e500a18544f209ad46fe8cd0d1c2ab34308d0d3087e96c76594  examples/v1.1.0/commercial/authorize/valid/002-authorize.request.valid.json
 c0ca42d7269f82c69cdcb24a0cd19d9bfc0a30cbf9b991e3f82b58c01ac16961  examples/v1.1.0/commercial/authorize/valid/900-authorize.receipt.valid.json
 45023d4bb512d36ee2543ffb9d3246a17f13021d7f9a115c79ae87860f391e00  examples/v1.1.0/commercial/authorize/valid/901-authorize.receipt.valid.json
 dec8708eda1a9da3d3f54731146b2b3cbd292ab718fcc6a763062d83014b4390  examples/v1.1.0/commercial/checkout/invalid/001-checkout.request.invalid.json
 a6fbf133ce4629ce3831d9a2929bcc5eef1844d5edf97428d20ce897d77e031e  examples/v1.1.0/commercial/checkout/invalid/900-checkout.receipt.invalid.json
 6607a0a6ceefd0ca978f7969cb1e6e326e9a8ceaedde17505d2be81a260b3c8c  examples/v1.1.0/commercial/checkout/valid/001-checkout.request.valid.json
+c0e61562d56f2c14161f805147b00524bcd08cffff86535c523b7492760b1089  examples/v1.1.0/commercial/checkout/valid/002-checkout.request.valid.json
 f8880c06f91c1d21a617fbe7f2b6a9d41d37db9f4fd5e9998689100c16f4000e  examples/v1.1.0/commercial/checkout/valid/900-checkout.receipt.valid.json
 ef376639e6129b14a8444c90e5a46ca4bd87a0b0f3b793e012f4839aa46b84a8  examples/v1.1.0/commercial/checkout/valid/901-checkout.receipt.valid.json
 0be8ae75fc24986bdf74f096995712b847a8cced75e33fe18095bca51282b773  examples/v1.1.0/commercial/purchase/invalid/001-purchase.request.invalid.json
 e70a205a9d6a4ec729161508a02b3d36d69b801408eec5cf54573ddfbbdfd44d  examples/v1.1.0/commercial/purchase/invalid/900-purchase.receipt.invalid.json
 2b235a6d567127c54da9c6c3eacf915c79a5c5127197a9aadbfb50289b122957  examples/v1.1.0/commercial/purchase/valid/001-purchase.request.valid.json
+b5e21819f5f9a8cd700841ad18abe45e1ff42e401648ded05c4dcfd89c350b3c  examples/v1.1.0/commercial/purchase/valid/002-purchase.request.valid.json
 3dd86d4ca05f8d3488ec1203d451a2f263b8e8eca388a0001850d7867314a187  examples/v1.1.0/commercial/purchase/valid/900-purchase.receipt.valid.json
 eeee667d742c165ba4fb08014cbcf9d45b5ee35bcc228764184ffe9a04530545  examples/v1.1.0/commercial/purchase/valid/901-purchase.receipt.valid.json
 bee0d3a0329f17125d0c1c287b870880b836cdb35faf8f2b06a820fa91ab6571  examples/v1.1.0/commercial/ship/invalid/001-ship.request.invalid.json
 7012d72e9641258bdebe3534e2f0faa771fbce63cb6a8b3c0828e9fe5ec521c5  examples/v1.1.0/commercial/ship/invalid/900-ship.receipt.invalid.json
 576924f554079213ce078d4be6c54e5ffc58839bde4182d73d02ba3412e47f3b  examples/v1.1.0/commercial/ship/valid/001-ship.request.valid.json
+abd0e8a97943c458a85d788b758206d05d9ccef3ba8635f613340ad526dfe496  examples/v1.1.0/commercial/ship/valid/002-ship.request.valid.json
 a004cb1385b1ca173b89df702e2b52d63f870521652f98f023359d30009b8df0  examples/v1.1.0/commercial/ship/valid/900-ship.receipt.valid.json
 f268080d0fadbd2b78ea0ab66348b137a07fe8764066af3337f8c7354335f4c7  examples/v1.1.0/commercial/ship/valid/901-ship.receipt.valid.json
 a2a5e61fa04e12786a848e03bbabbc3f9d066ca55a6f48cb1ae1140f6373bf94  examples/v1.1.0/commercial/verify/invalid/001-verify.request.invalid.json
 8933801c0b4fc007ead2e57d0a5f8e1a1b8a8b91a5c759e54778f65fff865c11  examples/v1.1.0/commercial/verify/invalid/900-verify.receipt.invalid.json
 56d02915471d62f7687e3f6258d75754c8e7a44ca717e4ca0906dd4bb6fc34fb  examples/v1.1.0/commercial/verify/valid/001-verify.request.valid.json
+9492d90ea14ad35eeb8acd03248ce6061ccdc04a7aff4ed538d8c42be3abc015  examples/v1.1.0/commercial/verify/valid/002-verify.request.valid.json
 50874f3eea69a51ac132873b05e39318e4c2241078ca5e258e466934935ec945  examples/v1.1.0/commercial/verify/valid/900-verify.receipt.valid.json
 455d19ad1b7ef98e436d8f1c675fee7f2716eb17d301da8d2cc4e2e2c51e624a  examples/v1.1.0/commercial/verify/valid/901-verify.receipt.valid.json
 80fa9124c1560d0e55b83554d83581dabf72505cc4d9c1354157f51fddd9686a  manifest.json

examples/v1.1.0/commercial/authorize/valid/002-authorize.request.valid.json

@@ -0,0 +1,47 @@
+{
+  "protocol": "commercial",
+  "version": "1.1.0",
+  "verb": "authorize",
+  "request_id": "authreq-002",
+  "requested_at": "2026-03-19T10:03:30Z",
+  "payer": {
+    "role": "payer",
+    "id": "buyer-007",
+    "kind": "account"
+  },
+  "payee": {
+    "role": "payee",
+    "id": "merchant-settlement",
+    "kind": "wallet"
+  },
+  "merchant": {
+    "role": "merchant",
+    "id": "merchant.example",
+    "kind": "organization"
+  },
+  "amount": {
+    "amount": "199.00",
+    "currency": "USDC",
+    "decimals": 2
+  },
+  "authorization_scope": {
+    "capture_mode": "automatic",
+    "valid_until": "2026-03-19T12:03:30Z",
+    "reusable": true
+  },
+  "payment_requirement": {
+    "scheme": "x402",
+    "resource": "https://merchant.example/x402/authorize/authreq-002",
+    "max_amount": {
+      "amount": "199.00",
+      "currency": "USDC",
+      "decimals": 2
+    },
+    "payment_request_id": "x402-auth-002"
+  },
+  "order_ref": {
+    "type": "order",
+    "id": "ord-1002"
+  },
+  "merchant_reference": "renewal-batch-1002"
+}