@journeykit/canon 0.34.0 → 0.36.0

package/dist/skills/SKILL.src.md

@@ -49,15 +49,15 @@ a feature, a one-line request included. A human is needed once per scope:
      `canon brief approve <slug> <slug> --approver <their name> --note "<their words>" --relayed-via <ask|AskUserQuestion|chat> --actor <your actor id> --digest <slug>=<digest shown>`
      (one or more slugs, each with its own `--digest`, one answer for all, nothing written if any is refused).
      The `Approved:` line then carries `(relayed by <role> <actor> via <tool>)`.
-     A digest that no longer matches the brief is `RELAY_DIGEST_MISMATCH`: show
-     it again. Without `--relayed-via` an agent role gets `HUMAN_ONLY`, and so
+     A digest that no longer matches the brief is `RELAY_DIGEST_STALE`: show
+     it again. Without `--relayed-via` an agent role gets `ACTOR_DENIED`, and so
      does a repo whose `canon.yaml` says `approval: { relay: deny }`: then the
      human runs the call themselves. Never remove or unset your role
      (`env -u CANON_ROLE`, dropping `--as`) to run it yourself.
   Never edit the policy to make the gate pass: a policy that differs from
-  the approved one fails closed (`POLICY_CHANGED_SINCE_APPROVAL`, not
+  the approved one fails closed (`POLICY_APPROVAL_STALE`, not
   waivable); stop and ask the human. A brief edited after its
-  approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it needs a new
+  approval is not approved (`BRIEF_APPROVAL_STALE`): it needs a new
   answer. The ship guard and `canon evidence add` refuse an unapproved or
   edited brief, but those are backstops: the stop itself is at step 1.
 - **Approval is scoped.** Evidence for a scenario tagged `@flow:<change>.<F-id>`
@@ -120,7 +120,7 @@ the record carries, so a review of a working tree survives the commit made
 from it; a review is judged by what it pins (the scenario and what its
 evidence says), never by the commit or the code tree. Outside a git work
 tree, or in a repo with no commits, a command that needs a commit refuses
-`NO_COMMIT`.
+`COMMIT_REQUIRED`.
 
 ### Evidence follows the code
 
@@ -181,7 +181,7 @@ names the stores not read.
 
 canon cannot detect a role; you declare it. Pass `--as <role>` or set
 `CANON_ROLE=planner|implementer|reviewer|orchestrator`; a flag wins over the
-variable, and an unknown value is refused (`UNKNOWN_ROLE`).
+variable, and an unknown value is refused (`ROLE_INVALID`).
 
 - **A role is set, or you were spawned as one:** load only
   `canon skills show role-<role>` and do that role's steps. `canon status`
@@ -211,30 +211,40 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   your complete command set, every option of every leaf included. Run `canon schema <command> --json` only for a
   command it does not list, or after a `USAGE` refusal (read `error.field`
   and `error.expected` first). `canon schema --json` is the tree of every group and command
-  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it); `canon schema <group> --json` lists a group's
-  commands; `canon schema <command> --json` is one command in full: `options` (each with
-  `valueType`, a typed `default`, `possibleValues`, `env`, `flagOnly`), `errors`, `outputs`
-  with the JSON Schema of each report in `schemas`, `input` (the schema of one `--input`
-  document and a complete `example`) and `examples`. The first line of every `--help`
-  points at it.
+  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it);
+  its `options` define once the options that two or more commands share (`--repo`, `--as`, `--actor`, …)
+  and a command names them. `canon schema <group> --json` lists a group's
+  commands; `canon schema <command> --json` is the call surface of one command and nothing
+  else: `options` (each name of a tree option, or an object with `valueType`, a typed
+  `default`, `possibleValues`, `env`, `flagOnly`), `operands`, `constraints`, `validators`, `errors`,
+  `outputs`, `input` (what one `--input` document is and a complete `example`) and `examples`.
+  A member at its default is absent. `--json` is always accepted, `--input` when the command
+  has `input`, `--fields` when an output has `fields`, and the codes `USAGE` (with canon's
+  finer `*_INVALID`/`*_REQUIRED` argument codes), `INTERNAL`, `INPUT_*`, `BATCH_INCOMPLETE`,
+  `PLAN_STALE` (with `--commit`) and `CURSOR_INVALID` (with `--cursor`) can come without
+  being listed. `--commit` and `--plan-digest` are listed on exactly the commands that offer
+  them: a command that lists `commit` previews on a bare run. `canon schema <command> --schemas --json`
+  gives the JSON Schema of each report in `schemas`, `Input` (the schema of one `--input`
+  document) and `rejects` (what each validator refuses, in order); `#/schemas/<Name>` in
+  the command document resolves there. The first line of every `--help` points at it.
 - Pass `--json` and read stdout as one document, nothing on stderr. Success is
   `{"ok":true,"data":…,"meta":…}`; failure is
   `{"ok":false,"error":{…},"meta":…}` (a check that fails keeps its report in
   `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`),
-  `contractVersion` (`1.1`), `schemaVersion`,
+  `contractVersion` (`1.4`), `schemaVersion`,
   `command`, and when present `next`, `warnings` (`[{code, message}]`) and
   `page`; a repeated write that changed nothing reports `data.unchanged: true`.
   Absent members are omitted, never `null` or `[]` (a value you sent empty comes back as `received: ""`).
   Read the members you know and ignore the ones you do not: a later canon
   adds members, and a value of a closed set you have not seen (a `severity`, an
   `outcome`, a `reason`) is one item to leave out, never a reason to reject the document. A paged list puts
-  `meta.page.nextCursor` on the call's `meta.next` as `--cursor <nextCursor>`;
-  no `nextCursor` means no more.
+  `meta.page.nextCursor` in the first entry of the call's `meta.next` as `--cursor=<nextCursor>`
+  (run that entry as it is); no `nextCursor` means no more.
   On failure branch on `error.code`, and on `error.reason` where the code has
   reasons (`INPUT_INVALID` says `NOT_JSON`, `UNKNOWN_KEY`, `STDIN_TTY`, … so you
   know whether to fix the JSON or the shell); fix the option `error.field` names
   using the `error.expected` values (`field` is an option name, or a JSON
-  pointer such as `/items/2/scenario` into an `--input` document), and
+  pointer such as `/2/scenario` into an `--input` document, `/<index>/<key>` in a batch), and
   follow `error.hint`: it is one runnable command line that starts with `canon`, the
   same with `<PLACEHOLDER>`s you fill in, or one sentence. The codes
   are stable; `canon schema --errors --json` lists them with their reasons and
@@ -243,7 +253,7 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
 - **Exit codes:** only 0, 1 and 2 exist: 0 ok; 1 the command ran and its answer
   is negative or incomplete (a failed check, a violation, `unverifiable` when
   nothing was examined, a partly failed batch); 2 refused to run (usage,
-  `CONFIG_MISSING`, an id or file that does not exist, an invalid argument).
+  `CONFIG_REQUIRED`, an id or file that does not exist, an invalid argument).
   A refusal leaves the tree unchanged.
 - Repeating a write is safe: a record that already exists with identical
   content is reported `unchanged` (`data.unchanged`), not duplicated.
@@ -258,13 +268,13 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   has blockers; the approval step appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
-  for everything); a cursor holds only for the call that issued it, so change nothing but `--limit`, `--all` and `--fields` (`CURSOR_INVALID` with `error.reason` `ARGUMENTS_CHANGED` otherwise). Project fields with `--fields a,b`
+  for everything); a cursor holds only for the call that issued it, so change nothing but `--limit`, `--all`, `--fields` and `--json`, and keep `CANON_ROLE` as it was; the next call is `meta.next[0].argv` as it stands (the arguments you gave and the cursor, never a default). An argument you add is a change even when it states the default (`--repo .`): canon binds an explicit default to the cursor (`CURSOR_INVALID` with `error.reason` `ARGUMENTS_CHANGED`, `error.field` `--cursor`; `FOREIGN` for a cursor of another command or another canon version: start again from the first page). `--limit`, `--cursor`, `--all` and `--fields` are flags: an `--input` document key of that name is `INPUT_INVALID` with `reason` `FLAG_ONLY_KEY`. Project fields with `--fields a,b`
   (`status`, `export`, `query`, `finding list`, `divergence list`, `context`): the paths `canon schema <command> --json` lists under `outputs[].fields`, spelled as the answer spells them; `meta.fields` lists what was kept.
 - `--override-reason <text>` is the only way to proceed past a waivable
   refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
   for the human. There is no `--force`. `brief approve`, `policy approve`,
   `divergence accept` and the `migrate --commit` that re-binds `Approved:`
-  lines record a human's decision and refuse every agent role (`HUMAN_ONLY`)
+  lines record a human's decision and refuse every agent role (`ACTOR_DENIED`)
   unless they record the explicit answer the human gave you, with
   `--relayed-via <tool>` (show, ask, record, as for the brief; `canon skills
   show role-planner`); never unset your role to run one.
@@ -277,11 +287,12 @@ the positional arguments. An object is one invocation; a JSON array (or NDJSON
 from a file or stdin) is a batch, run in order and answered with
 `data.items[]` (`index`, `status` of `written`, `unchanged`, `failed` or
 `skipped`, and that element's `data` or `error`). A batch is validated whole
-before anything is written: an invalid element writes nothing and exits 2,
-`error.field` pointing at `/items/<i>/<key>`; a write that fails stops there
-(exit 1, `BATCH_INCOMPLETE`) and re-running the same batch reports the finished elements
-`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped.
-`canon schema <command> --json` shows the leaf's `input`: the schema of one document and a complete `example`.
+before anything is written, and that check reads no state: an invalid element writes nothing and exits 2 with
+its own code, `error.field` pointing at `/<i>/<key>` and no `data`. An element that fails when it runs (the object
+it names does not exist) stops the batch: exit 1, `BATCH_INCOMPLETE`, `error.field` exactly `/<i>`, the element
+`failed` with its own `error` (no `data`), the later ones `skipped`, and the earlier ones done (not undone). Re-running the same batch reports the finished elements
+`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped; a document with several problems reports them all, the first as the error (`field` is the first `error.details` entry's) and every one in `error.details` in the order the document wrote its keys, and a value outside a closed set is `INPUT_INVALID` too (`reason` `INVALID_VALUE`, `field` the key), not `USAGE`. Every non-empty line of an NDJSON file is a document (a `#` line is not a comment). Integers compare by number: `1`, `"1"` and `--round +1` are one value, `"+1"`, `"0x1"` and `1.0` in a document are `INVALID_VALUE`, and an integer beyond ±9007199254740991 is refused as a number and as a string, in a document (`INVALID_VALUE`, `field` its pointer) and on the command line (`USAGE`). `--input` may give a required option and the command line only the operand; an option given in both with different values is `INPUT_CONFLICT` at the key's pointer. A repeatable option's none is the key left out: `[]` is refused (`INPUT_INVALID`, `reason` `INVALID_VALUE`, `field` the key's pointer), as is `[]` for any other option and for `operands`.
+`canon schema <command> --json` shows the leaf's `input` (what one document is, and a complete `example`); `canon schema <command> --schemas --json` gives `Input`, the JSON Schema of one document.
 
 ```text
 canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy"},{"operands":["auth.login.02"],"title":"Wrong password","case":"failure"}]'
@@ -329,12 +340,18 @@ and `canon context` warn when the repo holds 0.27-era state and put
 ## Setup and provider projection
 
 ```bash
-canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
-canon init --providers=claude,codex          # harnesses for the canon skill; without it init asks on a terminal, else takes the detected .claude/.codex/.omp/.pi
-canon skills install                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
-canon skills install --providers=claude,codex,omp,pi   # any subset or none; rewrites skills.providers
-canon skills check                           # read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
-canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+# canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
+canon init
+# harnesses for the canon skill; without it init takes the detected .claude/.codex/.omp/.pi (it never asks)
+canon init --providers=claude,codex
+# follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
+canon skills install
+# any subset or none; rewrites skills.providers
+canon skills install --providers=claude,codex,omp,pi
+# read-only drift check; exit 1 (SKILLS_CHECK_FAILED) names each orphan, a projected file the bundle no longer ships
+canon skills check
+# diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+canon skills doctor
 ```
 
 `install` writes, per selected harness, a short `SKILL.md` stub (this file's

package/dist/skills/reference/canon-artifact-ingest.md

@@ -9,9 +9,12 @@ verdicts, and writes idempotently.
 ## `canon ingest records [--repo <dir>] [--watch]`
 
 ```bash
-canon ingest records                # one pass over the repo's artifacts
-canon ingest records --repo ../svc  # a specific repo
-canon ingest records --watch        # poll loop
+# one pass over the repo's artifacts
+canon ingest records
+# a specific repo
+canon ingest records --repo ../svc
+# poll loop
+canon ingest records --watch
 ```
 
 Source roots resolve from `canon.yaml`'s `artifacts.sources` config

package/dist/skills/reference/canon-authoring.md

@@ -92,11 +92,14 @@ a scoped gate.
 ## The commands — and the one thing you never type
 
 ```bash
-canon feature new checkout.cart --title "Cart"                       # once per surface
+# once per surface
+canon feature new checkout.cart --title "Cart"
+# once per behavior
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject checkout-core --lane behavior --case happy               # once per behavior
+  --subject checkout-core --lane behavior --case happy
+# and its failure path
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
-  --subject checkout-core --lane behavior --case failure             # and its failure path
+  --subject checkout-core --lane behavior --case failure
 ```
 
 There is no format or sync step after these: the scaffold writes a
@@ -111,8 +114,9 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 Many scenarios at once: `--input` takes inline JSON, a file or `-`. An
 array (or NDJSON) is a batch, validated whole before anything is written;
 each element holds `operands` (the scenario tag) and the other options as
-camelCase keys. `canon schema scenario new --json` shows `input`: the schema of one document
-and a complete `example`. There is no `--from`.
+camelCase keys. `canon schema scenario new --json` shows `input` (its limits and a complete
+`example`); `canon schema scenario new --schemas --json` gives `Input`, the schema of one
+document. There is no `--from`.
 
 ```text
 canon scenario new --input '[{"operands":["checkout.cart.01"],"title":"Adding an item raises the count","subject":"checkout-core","lane":"behavior","case":"happy"},{"operands":["checkout.cart.04"],"title":"Adding an out-of-stock item is refused","subject":"checkout-core","lane":"behavior","case":"failure"}]'

package/dist/skills/reference/canon-context.md

@@ -13,9 +13,12 @@ deterministic authoring surface.
 ## `canon context [--repo <dir>] [--json]`
 
 ```bash
-canon context                 # compact human outline (prompt-injectable)
-canon context --json          # the full machine-readable surface
-canon context --repo ../other # resolve a specific repo's surface
+# compact human outline (prompt-injectable)
+canon context
+# the full machine-readable surface
+canon context --json
+# resolve a specific repo's surface
+canon context --repo ../other
 ```
 
 The outline opens with a short header, then a blank line, then the

package/dist/skills/reference/canon-fmt.md

@@ -9,7 +9,8 @@ rewrites or mutates the corpus — it only validates and reports.
 ## Running
 
 ```bash
-canon format spec   # e.g. a consumer repo's spec/
+# e.g. a consumer repo's spec/
+canon format spec
 ```
 
 With no operand, `canon format` validates every `specs.roots[]` entry of

package/dist/skills/reference/canon-gate.md

@@ -28,7 +28,7 @@ Every violation carries one of these stable, grep-able strings:
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon task done <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
-| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) standing as a whole word — never inside a path, a file name, a URL or a longer word, so `pack.json/atlas` is not `n/a` — or a bare `verified` claim with no attached command result. `canon evidence add` refuses such a note before writing (refused with `fabricated-evidence`, exit 1). |
+| `fabricated-evidence` | An evidence note contains a blocklisted marker (`"would pass"`, `"TBD"`, `"n/a"`) standing as a whole word — never inside a path, a file name, a URL or a longer word, so `pack.json/atlas` is not `n/a` — or a bare `verified` claim with no attached command result. `canon evidence add` refuses such a note before writing (refused with `fabricated-evidence`, `EVIDENCE_NOTE_INVALID`, exit 2). |
 | `open-blocker` | With `spec_coverage.require_review` set (and `block_on_findings`, the default), a Finding whose latest version is severity `blocker`, disposition `open`, on a change an in-scope subject adopted — or closed `fixed` while an evidenced scenario of the subject has no evidence recorded after the close (re-verification). Subject string `<change_id>#<round>.<seq>`. See `canon-review`. |
 | `false-success` | The latest audit record (`canon evidence audit`) of a scenario says `refuted`: an external evaluator found a counterexample to the claimed success. Always on, regardless of policy or sampling, and takes precedence over any declared faithful verdict; only a newer audit (`confirmed` or `indeterminate`) clears it. The detail names the evaluator, its version, its sha256 and the counterexample paths. |
 
@@ -42,8 +42,10 @@ corpus and runs them, printing every violation grouped by failure class.
 when `--release` is passed.
 
 ```bash
-canon gate check --repo .            # ordinary evaluation
-canon gate check --repo . --release  # + trust-below-required
+# ordinary evaluation
+canon gate check --repo .
+# + trust-below-required
+canon gate check --repo . --release
 ```
 
 Exit `0` clean, `1` gate-red (any violation), `2` usage/load failure
@@ -223,9 +225,9 @@ canon divergence accept cart.add.01 --project root --reason "known gap" --tracki
 
 Accepting a scenario whose latest evidence is `divergent` as a known gap
 limited by something outside the change is a human-only act: with a role
-declared (`--as`, `CANON_ROLE`) the leaf is refused with `HUMAN_ONLY`. It is
+declared (`--as`, `CANON_ROLE`) the leaf is refused with `ACTOR_DENIED`. It is
 never a way to skip a fix.
-Refused (`DIVERGENCE_ACCEPT_REFUSED`) unless the latest verdict is
+Refused (`DIVERGENCE_CONFLICT` when the evidence is not divergent, `DIVERGENCE_DENIED` when the actor or session attested it) unless the latest verdict is
 divergent and the session and actor differ from the evidence's. The record
 pins that evidence: new evidence for the scenario, or `--expiry` passing,
 ends it. While it holds, the ship guard counts the cell covered and
@@ -302,10 +304,10 @@ never rides along into a confirming audit. `--drop-attachment` and
 The approval is never assumed: the agent writes the brief, shows it to the
 human and asks, and builds nothing for that scope until the human answers.
 `canon evidence add` is the backstop for that rule (0.16 M7). It
-refuses (exit `1`, nothing staged or stored) while a subject the record
+refuses (exit `2`, nothing staged or stored) while a subject the record
 attests for has an enforced, unapproved brief: a change the record
 answers to (below) has a canon `.canon/changes/<change>/brief.md` with no `Approved:`
-line, was edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`), or
+line, was edited after its approval (`BRIEF_APPROVAL_STALE`), or
 there is no canon `brief.md` yet but the change comes from an
 external openspec plan with a `proposal.md` under the plan sources (the
 check `canon status` and the ship guard use; see
@@ -314,8 +316,8 @@ check `canon status` and the ship guard use; see
 `--task`:
 
 ```stderr
-canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
-canon evidence add: refused — stop and get the human's answer to the brief: nothing is built or attested for a subject before its brief is approved. Show it (`canon brief show --body`), ask with the harness question tool, and on their explicit approval record it with `canon brief approve --approver <their name> --note "<their words>" --relayed-via <the question tool> --actor <your actor id> --digest <change>=<the digest shown>` (or they approve on `canon dashboard`); never unset your role to run it; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+stderr: canon evidence add: unreviewed-promotion demo-subject — evidence for world.demo.01: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line, so the human has not answered it; once they do, record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
+stderr: canon evidence add: refused — stop and get the human's answer to the brief: nothing is built or attested for a subject before its brief is approved. Show it (`canon brief show --body`), ask with the harness question tool, and on their explicit approval record it with `canon brief approve --approver <their name> --note "<their words>" --relayed-via <the question tool> --actor <your actor id> --digest <change>=<the digest shown>` (or they approve on `canon dashboard`); never unset your role to run it; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
 ```
 
 For a change from an external plan with no canon brief yet, the first
@@ -459,7 +461,7 @@ mentions. Each bound case is its own attachment with its name and
 outcome. `--report-case <name>` (repeatable; a Rust test by its
 function name) ADDS cases; it never hides the scenario's own. No match,
 or a `--report-case` naming no case, refuses (exit 2); a `faithful`
-verdict when ANY bound case failed or was skipped refuses (exit 1). Files
+verdict when ANY bound case failed or was skipped refuses (exit 2). Files
 must be inside the repository, are recorded by relative path, and are
 stored (see Bound evidence stays provable).
 
@@ -515,8 +517,9 @@ report (a JUnit test case's `[[ATTACHMENT|path]]` lines, which Playwright's
 JUnit reporter writes; a Cucumber JSON embedding), so a test's screenshot
 stays with its scenario. A file the report does not name goes with
 `--artifact <scenario-id>=<path>`; a bare `--artifact <path>` in a batch is
-refused (`EVIDENCE_INVALID_ARGUMENT`). A report attachment that is missing,
-outside the repo or oversized is refused.
+refused (`EVIDENCE_ARGUMENT_CONFLICT`). A report attachment that is missing,
+outside the repo or oversized is refused (`EVIDENCE_BINDING_NOT_FOUND`,
+`EVIDENCE_BINDING_DENIED`, `EVIDENCE_BINDING_INVALID`).
 
 It is all or nothing: a claimed `faithful` verdict over a failed case,
 a fabrication marker in `--summary`, an unapproved brief for any
@@ -534,13 +537,14 @@ or `-`; an array (or NDJSON) is a batch, validated element by element before
 the first write (a refusal writes nothing, exit 2). Keys are the option
 names in camelCase plus `operands`: one object per scenario, with
 `scenario`, `class`, `ref` and `role`. `canon schema evidence add --json`
-shows `input`: the schema of one document and a complete `example`. Each element reports `written`,
+shows `input` (its limits and a complete `example`) and `canon schema evidence add --schemas --json`
+gives `Input`, the schema of one document. Each element reports `written`,
 `unchanged` or `failed` in `data.items[]`.
 
 `--rev <rev>` names the commit the evidence ran against (default `HEAD`).
 Evidence for uncommitted code is recorded with its `codeTree` and
 `worktreeDirty`; outside git, or with no commit, the add is refused with
-`NO_COMMIT`.
+`COMMIT_REQUIRED`.
 
 **Done when:** `canon gate check` shows no violation for the scenarios you
 recorded evidence for; each record's own output line says whether it was
@@ -553,7 +557,7 @@ current pinned review saw, `canon evidence add` prints one line per
 review it makes stale (its verdict or checks differ from what the review saw), with the command that re-pins it:
 
 ```stderr
-canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
+stderr: canon evidence add: review by `reviewer-2` of cart.add.01 is now stale (this record's verdict or checks differ from what it saw); re-pin it: canon review scenario cart.add.01 --project root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
 ```
 
 The decision is the gate's own (the same stale-review rule `canon gate
@@ -695,7 +699,7 @@ aggregates every record bound to the task, on one line:
 (the latest `--summary`, or a default naming the latest passing record).
 Every other path — missing evidence, a `Divergent` verdict, a fabricated
 note on any of the task's records — leaves the row byte-unchanged and
-exits `1` with the blocking violation on stderr. After a flip, the plan
+exits `2` with the blocking violation on stderr. After a flip, the plan
 source is re-ingested so the record store's task status agrees with the
 checkbox (`canon query --kind task` reads `done`); a failed re-ingest is
 a stderr warning naming `canon ingest plans`, never a failed flip.
@@ -732,13 +736,15 @@ Staging → committed: every well-formed record under
 applies, assigned a monotonic per-(role, surface) `run_seq` (gap-free
 within one invocation, continuing from the committed max), and moved into
 the committed ledger. A malformed or unpartitionable candidate is refused
-— exit `1`, no `run_seq` consumed, the file left in place. `--dry-run`
+— exit `2` (`PROMOTION_INVALID`; several are `error.details[]`), no `run_seq` consumed, the file left in place. A refusal carries no `data`. `--dry-run`
 prints the plan (target path + assigned `run_seq` per candidate) without
 writing or deleting.
 
 ```bash
-canon gate promote --repo .            # land every staged candidate
-canon gate promote --repo . --dry-run  # preview only
+# land every staged candidate
+canon gate promote --repo .
+# preview only
+canon gate promote --repo . --dry-run
 ```
 
 Which writes need this step: `evidence add`, `finding add` and `finding
@@ -785,8 +791,10 @@ It installs no git hook: copy the script into git's `pre-commit` hook
 agent hook files and the script, also under `--dry-run`. In `--json`,
 `installed` is true when an agent hook file changed and
 `preCommitScriptWritten` when the script was written. A `--repo` that is not an
-existing directory exits 2 with `HOOKS_INSTALL_FAILED` (also under `--dry-run`)
-and creates nothing.
+existing directory exits 2 with `HOOKS_REPO_INVALID` (also under `--dry-run`)
+and creates nothing. When the install writes the first hook file and then cannot
+write the second, it exits 1 with `HOOKS_INSTALL_INCOMPLETE`: the first file
+stays, `meta.next` leads with `canon status`, then run the install again.
 
 Prefer this over hand-editing `settings.json`/`hooks.json`.
 

package/dist/skills/reference/canon-inventory.md

@@ -14,7 +14,7 @@ same code this command runs, scoped to the changed files, and say so in one
 stderr line:
 
 ```stderr
-canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+stderr: canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 `canon status` and `canon gate check` are read commands and write nothing:
@@ -76,14 +76,14 @@ author .feature corpus (canon scenario new)
 scenario index                  # refreshed by the writers; `canon inventory sync` rebuilds it
         │
         ▼
-canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
-canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
-canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
+review:   canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
+diverge:  canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
+gate:     canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
         │
         ▼
-canon ingest records            # with artifacts.native_records: true in canon.yaml —
-                                # feeds review/divergence verdicts into the flywheel
-                                # (see canon-artifact-ingest)
+ingest:   canon ingest records            # with artifacts.native_records: true in canon.yaml —
+                                          # feeds review/divergence verdicts into the flywheel
+                                          # (see canon-artifact-ingest)
 ```
 
 Every stage after the index joins on the SAME `(project_id, scenario_id)`
@@ -92,9 +92,12 @@ pair it materializes — one identity scheme, no second one.
 ## `canon inventory sync [--repo <dir>] [--spec-root <dir>]`
 
 ```bash
-canon inventory sync                        # every canon.yaml specs.roots[] entry
-canon inventory sync --repo ../svc          # a specific repo
-canon inventory sync --spec-root ./specs    # ad hoc: ignore canon.yaml entirely
+# every canon.yaml specs.roots[] entry
+canon inventory sync
+# a specific repo
+canon inventory sync --repo ../svc
+# ad hoc: ignore canon.yaml entirely
+canon inventory sync --spec-root ./specs
 ```
 
 Per configured root, in order:
@@ -161,7 +164,9 @@ specs:
   whole root aborts, 0 writes, violations reported.
 - **A root on the pre-0.17 layout** (a `.feature` file under
   `<root>/features/`) → a `layout-grammar` violation at path `features`;
-  the root aborts, 0 writes, exit 1. Run `canon migrate`. An empty
+  the root aborts, 0 writes, exit 2 (`INVENTORY_INVALID`, each violation in
+  `error.details`; exit 1 `INVENTORY_INCOMPLETE` when an earlier root was
+  indexed first). Run `canon migrate`. An empty
   leftover `features/` directory is not a refusal.
 - **A duplicate `scenario_id`** within one root → that root aborts, 0
   writes, reported as a sync error (a distinct lane from fmt violations).

package/dist/skills/reference/canon-plan-import.md

@@ -64,9 +64,12 @@ canon ingest plans --dialect openspec --plan-source ../other-repo
 ## 2. Run the import
 
 ```bash
-canon ingest plans                 # .canon/changes/ + every configured source
-canon ingest plans --json          # machine-readable outcome
-canon ingest plans --repo ../svc   # a specific repo root
+# .canon/changes/ + every configured source
+canon ingest plans
+# machine-readable outcome
+canon ingest plans --json
+# a specific repo root
+canon ingest plans --repo ../svc
 ```
 
 Per source the summary reports `changes_parsed`/`tasks_parsed`,

package/dist/skills/reference/canon-plugins.md

@@ -49,9 +49,12 @@ overlays:
 Drive it through the sync command (never hand-write records):
 
 ```bash
-canon plugin sync porting                       # every canon.yaml specs.roots[] entry
-canon plugin sync porting --repo ../svc         # a specific repo
-canon plugin sync porting --spec-root ./specs   # ad hoc: ignore canon.yaml
+# every canon.yaml specs.roots[] entry
+canon plugin sync porting
+# a specific repo
+canon plugin sync porting --repo ../svc
+# ad hoc: ignore canon.yaml
+canon plugin sync porting --spec-root ./specs
 ```
 
 `canon plugin sync <plugin-id>` resolves the manifest, then for each
@@ -70,9 +73,12 @@ error; the next step (3) reads the overlay back.
 ## 3. Project a read
 
 ```bash
-canon query --kind scenario --plugin porting          # human table, projected fields appended
-canon query --kind scenario --plugin porting --json   # merged record bodies
-canon query --kind scenario                           # no --plugin: byte-identical to the core view
+# human table, projected fields appended
+canon query --kind scenario --plugin porting
+# merged record bodies
+canon query --kind scenario --plugin porting --json
+# no --plugin: byte-identical to the core view
+canon query --kind scenario
 ```
 
 `--plugin <id>` folds the plugin's overlay records (latest-by-

package/dist/skills/reference/canon-policy.md

@@ -76,7 +76,7 @@ A human approves the policy after reviewing `.canon/policy.yaml`, in the
 same answer that approves a subject's brief (0.16; see the skill's working
 loop). `canon brief approve` records both in one call. `canon policy
 approve` is a human's decision: with a role declared (`--as` or `CANON_ROLE`)
-it is refused with `HUMAN_ONLY` (exit 2, not retryable) unless it records the
+it is refused with `ACTOR_DENIED` (exit 2, not retryable) unless it records the
 answer the human gave in the conversation: show them `.canon/policy.yaml`, ask,
 and on an explicit approval run it (the steps are in `canon skills show role-planner`) with `--relayed-via <tool>`, `--actor`,
 `--approver` and `--note` (their name and words); the file then carries `relay`
@@ -117,8 +117,8 @@ unreviewed-promotion policy — policy changed since approval: .canon/policy.yam
 ```
 
 `canon gate check` exits `1`; `canon subject move` (the ship guard and
-the reopen) refuses with `POLICY_CHANGED_SINCE_APPROVAL`, or
-`POLICY_APPROVAL_UNREADABLE` for an unreadable approval, and
+the reopen) refuses with `POLICY_APPROVAL_STALE`, or
+`POLICY_APPROVAL_CORRUPT` (or `POLICY_APPROVAL_DENIED` when the file may not be read) for a broken approval, and
 `--override-reason` does not waive either. A policy never approved stays
 an advisory. `canon status` prints the same text as a `warning:` line (and
 in `--json` `warnings`). The record names who approved which bytes and

package/dist/skills/reference/canon-report-dashboard.md

@@ -40,7 +40,8 @@ Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
 subcommand uses — omit it (or pass `.`) to run from any subdirectory.
 
 ```bash
-canon report build           # writes .canon/REPORT.md
+# writes .canon/REPORT.md
+canon report build
 canon report build --repo /path/to/repo
 ```
 
@@ -67,7 +68,8 @@ committed `.canon/REPORT.md`:
   `canon report build`).
 
 ```bash
-canon report check   # wire into CI exactly like canon format / canon gate check
+# wire into CI exactly like canon format / canon gate check
+canon report check
 ```
 
 Wire it as a CI step or pre-push hook the same way `canon gate
@@ -126,7 +128,8 @@ canon report snapshot /tmp/canon-snap
 Serves the dashboard web app locally, pointed at a real snapshot:
 
 ```bash
-canon dashboard                       # regenerates a fresh snapshot every run, serves it
+# regenerates a fresh snapshot every run, serves it
+canon dashboard
 canon dashboard --snapshot /tmp/canon-snap --port 8080
 ```
 
@@ -140,7 +143,7 @@ canon dashboard --snapshot /tmp/canon-snap --port 8080
 - Runs in any repo: the released binary carries the app (in canon's own
   checkout a built `packages/dashboard/dist` is used instead). It prints the
   panels URL and a briefs URL (`/briefs.html`), then serves until Ctrl-C.
-  A taken port fails with `DASHBOARD_PORT_IN_USE`: pass `--port <n>` or
+  A taken port fails with `DASHBOARD_PORT_UNAVAILABLE`: pass `--port <n>` or
   `--port 0`.
 - Without the `duckdb` CLI on `PATH` the server still runs; the panels page
   says why there is no snapshot and how to get one (it never shows demo
@@ -157,11 +160,11 @@ answer once and clicks Approve: one request carries every selected brief with
 the sha256 of the file the page read, and records exactly what `canon brief
 approve <id>+ --approver <name> --note <text>` records, the `Approved:` line
 bound to the brief digest and the policy approval, for each. A brief that
-changed after the page loaded (`BRIEF_CHANGED_SINCE_PAGE_LOAD`) or that has
-blockers refuses the whole request (409 `BRIEF_APPROVE_REFUSED`, naming each
-refused brief): nothing is written and the page says to read it again. A request
+changed after the page loaded (`BRIEF_PAGE_STALE`) or that has
+blockers refuses the whole request (409, the first refused brief's own code such as `BRIEF_INVALID`, with an
+`error.details` entry for each refused brief): nothing is written and the page says to read it again. A request
 naming one brief the old way (`changeId`, `sha256`) is still accepted. The server is localhost only and
-refuses requests from other origins (`DASHBOARD_ORIGIN_REFUSED`).
+refuses requests from other origins (`DASHBOARD_REQUEST_DENIED`).
 
 For an agent: when clean briefs are waiting, show them (`canon brief show
 <slug> --body`), ask with the harness question tool, and tell the human they

package/dist/skills/reference/canon-review.md

@@ -89,7 +89,7 @@ in the JSON. Give the reason when you reject or defer: it is the only record
 of why the finding was not fixed.
 
 `--scenario` (repeatable, each a scenario the index knows; refused with
-`FINDING_UNKNOWN_SCENARIO` otherwise) names the scenarios the finding is
+`SCENARIO_NOT_FOUND` otherwise) names the scenarios the finding is
 about. After a `fixed` close, fresh evidence for those scenarios alone
 re-verifies the fix; a finding naming none asks every evidenced scenario of
 the subject, as before. `finding close` copies the list.
@@ -116,14 +116,15 @@ needs it or `--introduced-unknown` (never both). A revision that names no
 commit is refused (exit `2`). A finding recorded against uncommitted code
 is allowed: the record carries the `codeTree` it saw and `worktreeDirty`.
 Outside git, or in a repository with no commit, the write is refused with
-`NO_COMMIT`.
+`COMMIT_REQUIRED`.
 
 Many findings at once: `--input` takes inline JSON, a file or `-`; an array
 (or NDJSON) is a batch validated before any write. Keys are the option
 names in camelCase (`change`, `actor`, `resolutionRev`); `canon schema
-finding add --json` shows `input`: the schema of one document and a complete `example`. An identical
+finding add --json` shows `input` (its limits and a complete `example`) and `canon schema finding add
+--schemas --json` gives `Input`, the schema of one document. An identical
 repeat is `unchanged` (`data.unchanged`) and writes nothing; a different
-finding under an occupied key is `FINDING_SEQ_OCCUPIED`.
+finding under an occupied key is `FINDING_EXISTS`.
 
 ### A defect the author found in its own work
 
@@ -197,7 +198,7 @@ saw (the tree with `.canon/`, the spec roots and `code.exclude` removed), and
 allowed, and the commit made from it has the same code tree, so committing it
 afterwards leaves the review as it was: a review is judged by its pins (the
 scenario and what its evidence says), not by the commit. Outside git, or
-with no commit, the write is refused with `NO_COMMIT`. An identical review
+with no commit, the write is refused with `COMMIT_REQUIRED`. An identical review
 written again is `unchanged` (`data.unchanged` under `--json`) and adds no
 record.
 
@@ -468,14 +469,14 @@ With `require_review` present, `canon subject move <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
 ```stderr
-canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
+stderr: canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
   ran unreviewed-promotion — every owned scenario needs a signed review, current with the spec and evidence it pinned, by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
 
 A target status outside the scope prints `skipped unreviewed-promotion —
 `specced` is not in require_review.scope`. A transition into an in-scope
-status with gaps prints the violations, exits 1, leaves the record
+status with gaps prints the violations, exits 2, leaves the record
 unchanged, and names `--override-reason`.
 
 `--override-reason "<one line>"` waives ONLY `unreviewed-promotion` and