docs: tighten contributor and validation guidance (#26)

Author: GsCommand

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# CONTRIBUTING — Protocol-Commercial
+
+This document defines the contributor workflow for the current release line. Keep changes minimal, validation-preserving, and explicit about whether they affect the current line (`v1.1.0`) or retained legacy artifacts.
+
+## Pull request expectations
+
+- Describe the exact problem being fixed and the exact files changed.
+- Keep protocol semantics unchanged unless the change is intentionally normative and documented.
+- Prefer deletion over vestigial compatibility scaffolding.
+- When docs change, keep them precise and avoid restating the full validation command block outside `README.md#validation-commands`.
+- If you touch checksum-covered machine artifacts (`schemas/v1.1.0/`, `examples/v1.1.0/`, `manifest.json`), regenerate `checksums.txt` before merge.
+
+## Commit convention
+
+Use concise, imperative commit subjects. Prefer a scope when it clarifies intent, for example:
+
+- `docs: clarify current-line validation policy`
+- `tooling: route npm test through validation aggregate`
+- `validation: reuse strict JSON loader across scripts`
+
+Avoid mixed-purpose commits when a focused change is practical.
+
+## Required validation before merge
+
+Run the canonical commands from `README.md#validation-commands` that match your change set. In normal contributor flow, this means at least:
+
+```bash
+npm test
+npm run validate:schemas
+npm run validate:examples
+npm run validate:integrity
+```
+
+Also run `sha256sum -c checksums.txt` whenever you changed checksum-covered artifacts or regenerated the checksum ledger.
+
+## When changing schemas, examples, or docs
+
+### Schemas
+
+- Preserve flat, self-contained `v1.1.0` schemas; do not reintroduce current-line cross-file schema dependencies.
+- Keep file paths and `$id` values aligned exactly.
+- Treat same-named local `$defs` as canonical repeated shapes and keep them consistent across verbs.
+
+### Examples
+
+- Keep valid fixtures conformant and invalid fixtures narrowly targeted.
+- Ensure request and receipt coverage remains present in both `valid/` and `invalid/` for each current-line verb.
+- Do not add a current-line `examples/v1.1.0/**/ts/` surface unless the repository deliberately restores and governs it.
+
+### Documentation
+
+- Keep onboarding content orientation-focused and contributor policy in this file.
+- Use explicit JSON path imports in examples by default, with any bare-package import labeled as environment-dependent.
+- State clearly when guidance applies only to the current line and when legacy `v1.0.0` artifacts are mentioned for compatibility or audit history.

INTEGRATOR.md

@@ -4,13 +4,13 @@ This document is the external-consumer quickstart for the current commercial rel
 
 ## What to import
 
-Use the package root or the current index directly:
+Use the explicit current-line JSON path export by default:
 
 ```js
-import commercialIndex from '@commandlayer/commercial';
+import commercialIndex from '@commandlayer/commercial/schemas/v1.1.0/index.json';
 ```
 
-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.
+That path is the current machine-readable map of every canonical verb schema in the release and is the most portable documented import for ESM-first consumers. The bare package import `@commandlayer/commercial` currently resolves to the same file, but treat it as an environment-dependent shortcut rather than the default example.
 
 ## What is normative vs illustrative
 
@@ -37,11 +37,7 @@ Normative interpretive docs:
 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
-   ```
+4. Run checksum verification before mirroring or vendoring artifacts using the canonical commands in `README.md#validation-commands`.
 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
@@ -65,4 +61,4 @@ The checksum-covered payload for this release is intentionally narrow:
 
 ## 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.
+There is no current-line TypeScript compile target or public `examples/v1.1.0/**/ts/` teaching surface in this release. The retained `v1.0.0` TypeScript example files are legacy compatibility artifacts, not an active build surface. If a future release restores a TypeScript surface, it should be explicitly governed, validated, and documented before it is treated as part of the public implementer surface.

ONBOARDING.md

@@ -1,10 +1,10 @@
 # ONBOARDING — Protocol-Commercial
 
-This document describes both the external-consumer path and the maintainer workflow for the active v1.1.0 release line.
+This document is an orientation guide for the active v1.1.0 release line. Contributor policy and pre-merge workflow live in `CONTRIBUTING.md`.
 
 ## Document scope
 
-This document is the operational workflow for the current release line.
+Use this document to understand the repository shape, release line, and maintainer intent before editing.
 
 ## External consumer workflow
 
@@ -24,32 +24,15 @@ This document is the operational workflow for the current release line.
 
 ## Maintainer workflow
 
-1. Install dependencies.
-   ```bash
-   npm install
-   ```
-2. Edit schemas, examples, metadata, scripts, and docs coherently.
-3. Run validation.
-   ```bash
-   npm run validate
-   npm run validate:schemas
-   npm run validate:examples
-   npm run validate:integrity
-   ```
-4. Regenerate checksums when checksum-covered machine artifacts change.
-   ```bash
-   npm run generate:checksums
-   ```
-5. Re-run validation and checksum verification.
-   ```bash
-   npm run validate
-   npm run validate:schemas
-   npm run validate:examples
-   npm run validate:integrity
-   sha256sum -c checksums.txt
-   ```
+For contribution workflow, pull request expectations, commit convention, and required pre-merge validation, use `CONTRIBUTING.md`.
+
+High-level maintainer sequence:
 
-When editing only prose docs outside the checksum surface, do not regenerate `checksums.txt` unless a checksum-covered machine artifact also changed.
+1. Install dependencies with `npm install`.
+2. Edit schemas, examples, metadata, scripts, and docs coherently.
+3. Run the canonical validation commands referenced from `README.md#validation-commands`.
+4. Regenerate `checksums.txt` only when checksum-covered machine artifacts change.
+5. Keep current-line teaching focused on `v1.1.0` and mark `v1.0.0` as retained legacy.
 
 ## Adding a new commercial verb
 

README.md

@@ -56,21 +56,18 @@ The stack story is singular:
 
 For consumers who need the shortest safe path:
 
-1. Install the package and import the current index entrypoint.
+1. Install the package and import the current index entrypoint using the explicit JSON path export.
    ```bash
    npm install @commandlayer/commercial
    ```
    ```js
-   import commercialIndex from '@commandlayer/commercial';
+   import commercialIndex from '@commandlayer/commercial/schemas/v1.1.0/index.json';
    ```
+   The bare package import `@commandlayer/commercial` resolves to the same file today, but treat that shortcut as environment-dependent rather than the default documentation path.
 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.
+4. Verify the machine-artifact set before mirroring or vendoring using the canonical command surface in [Validation commands](#validation-commands).
+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.
 
 A longer external-consumer workflow lives in `INTEGRATOR.md`.
@@ -159,6 +156,15 @@ protocol-commercial/
 
 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.
 
+### Browsing large self-contained schemas
+
+To navigate the flat schema line efficiently without reintroducing cross-file dependencies:
+
+- Start at `schemas/v1.1.0/index.json` to locate the request and receipt pair for the verb you need.
+- Read a verb directory as a pair: request first for caller obligations, receipt second for canonical outcome and audit references.
+- Use the local `$defs` section in each schema as the file-scoped glossary for repeated structures such as actors, money, and payment evidence.
+- Compare same-named `$defs` across verbs only when checking consistency; the validator enforces those shared shapes without making readers chase external files.
+
 Current-line example governance is equally explicit:
 
 - `valid/` contains illustrative conforming request and receipt fixtures.
@@ -223,19 +229,21 @@ This repository does not define:
 }
 ```
 
-## Validation and integrity
+## Validation commands
+
+This README is the canonical command surface for repository validation. Other docs should reference this section instead of duplicating the full command block.
 
 ```bash
 npm install
-npm run validate
+npm test
 npm run validate:schemas
 npm run validate:examples
 npm run validate:integrity
 npm run generate:checksums
 sha256sum -c checksums.txt
 ```
 
-- `npm run validate` runs the full validation suite for the current release line.
+- `npm test` runs the full current-line validation aggregate (`npm run validate`).
 - `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.
 - `npm run validate:integrity` verifies the checksum file scope and hash coverage for the current release artifact set.

SECURITY.md

@@ -31,14 +31,6 @@ Protocol-Commercial provides schema-level security properties, not transaction o
 
 ## Verification commands
 
-```bash
-npm run validate
-npm run validate:schemas
-npm run validate:examples
-npm run validate:integrity
-sha256sum -c checksums.txt
-```
-
-`npm run validate:schemas` is the direct schema/metadata drift check. `sha256sum -c checksums.txt` verifies only the checksum-covered machine-artifact surface, not release prose docs.
+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`

SPEC.md

@@ -147,7 +147,9 @@ A conformant release MUST satisfy all of the following:
 - every declared verb has valid and invalid examples for both request and receipt artifacts
 - every current schema path matches its `$id`
 - `manifest.json` and `schemas/v1.1.0/index.json` agree on the current verb set and path inventory
-- `npm run validate` passes
+- `npm test` passes as the current-line validation aggregate
 - `npm run validate:schemas` passes
 - `sha256sum -c checksums.txt` passes for the checksum-covered machine-artifact set
 - repository metadata does not drift from the published current line
+
+The canonical command list lives in `README.md#validation-commands`.

package.json

@@ -66,7 +66,8 @@
     "validate:integrity": "node scripts/validate-integrity.mjs",
     "validate:all": "npm run validate:schemas && npm run validate:examples && npm run validate:integrity",
     "validate": "npm run validate:all",
-    "generate:checksums": "node scripts/generate-checksums.mjs"
+    "generate:checksums": "node scripts/generate-checksums.mjs",
+    "test": "npm run validate"
   },
   "devDependencies": {
     "ajv": "^8.17.1",

scripts/validate-examples.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import fs from "fs/promises";
+import { readdir } from "fs/promises";
 import path from "path";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";