@journeykit/canon 0.32.0 → 0.34.0

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/index.ts
 import { spawnSync, execSync } from "node:child_process";
 import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { constants as osConstants } from "node:os";
 import { resolve, join, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 var binaryName = process.platform === "win32" ? "canon.exe" : "canon";
@@ -165,4 +166,7 @@ var result = spawnSync(binary, process.argv.slice(2), {
 if (result.error) {
   console.error(`canon: failed to run ${binary}: ${result.error.message}`);
 }
+if (result.status === null && result.signal) {
+  process.exit(128 + (osConstants.signals[result.signal] ?? 0));
+}
 process.exit(result.status ?? 1);

package/dist/skills/SKILL.src.md

@@ -186,7 +186,7 @@ variable, and an unknown value is refused (`UNKNOWN_ROLE`).
 - **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`
   and `meta.next` then show only your role's steps, and count the others in
-  `waitingOn`; `canon schema --as <role>` lists only your role's commands.
+  `data.waitingOn`; `canon schema --as <role>` lists only your role's commands.
   Do not load another role's guide.
 - **No role (one agent doing everything):** follow `canon status` and load
   each role guide as its phase starts: planner for steps 1–2,
@@ -201,30 +201,52 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
 
 - Start a session with `canon status`: where each subject stands and the next
   commands. After that, do not call it only to learn the next step: every
-  write returns `meta.next` (`[{command, argv, why, actor, role}]`), the same
-  steps `status` would give, narrowed to what the write touched. `actor: human`
+  write returns `meta.next` (`[{command, argv, reason, x-canon: {actor, role}}]`), the same
+  steps `status` would give, narrowed to what the write touched. Each entry is
+  runnable: `argv` is the command without `canon` (with `--json` when you
+  called in JSON mode). Guidance that needs a value you must fill in is not a
+  next entry; it is in the error `hint` or the report text. `x-canon.actor: human`
   marks a step only the human takes.
 - Your role guide's **Commands** block (`canon skills show role-<role>`) is
   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` alone lists every command.
+  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.
 - 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 `command`, `schemaVersion`, `canonVersion`, `next`,
-  `warnings` and, for a repeated write that changed nothing, `unchanged: true`.
-  On failure branch on `error.code`, fix the option `error.field` names
+  `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`),
+  `contractVersion` (`1.1`), `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.
+  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
-  follow `error.hint`: every refusal carries a working invocation. The codes
-  are stable; `canon schema --errors --json` lists them and
-  `canon schema --error <CODE>` explains one.
-- **Exit codes:** 0 ok; 1 the command's own finding (a failed check, a
-  violation, or `unverifiable` when nothing was examined); 2 refused (usage,
+  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
+  `canon schema --error <CODE>` explains one. A warning code (`meta.warnings`) is in
+  `canon schema --warnings --json`; `canon schema --warning <CODE>` explains one.
+- **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).
   A refusal leaves the tree unchanged.
 - Repeating a write is safe: a record that already exists with identical
-  content is reported `unchanged` (`meta.unchanged`), not duplicated.
+  content is reported `unchanged` (`data.unchanged`), not duplicated.
 - An option that takes an id is the bare noun (`--change add-login`,
   `--scenario auth.login.01`, `--actor reviewer-1`, `--project root`,
   `--session s-1`), and an `--input` document key is that name without `Id`
@@ -236,8 +258,8 @@ 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), and project fields with `--fields a,b` (`status`, `export`,
-  `query`, `finding list`, `divergence list`, `context`).
+  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`
+  (`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`,
@@ -257,9 +279,9 @@ from a file or stdin) is a batch, run in order and answered with
 `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) and re-running the same batch reports the finished elements
-`unchanged`. A typo in a key is refused (`INPUT_UNKNOWN_FIELD`), never dropped.
-`canon schema <command> --json` shows the leaf's input schema and an example.
+(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`.
 
 ```text
 canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy"},{"operands":["auth.login.02"],"title":"Wrong password","case":"failure"}]'
@@ -276,7 +298,7 @@ The five commands that delete or rewrite existing data (`canon purge`,
 `canon tier age`, `canon ledger compact`, `canon artifacts move`,
 `canon migrate`) act in two steps. The bare run previews: it writes nothing,
 exits 0 and prints the effects and a `planDigest`. Read the effects, then act
-with `--commit --plan-digest <planDigest>`. It refuses (`PLAN_CHANGED`) when
+with `--commit --plan-digest <planDigest>`. It refuses (`PLAN_STALE`) when
 the plan differs from the one you previewed, so run the preview again. Appends
 and state transitions (`gate promote`, `subject move`) run directly. Where a
 preview helps elsewhere (`init`, `skills install`, `export`, `inventory sync`,

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

@@ -111,8 +111,8 @@ 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 the input schema
-and an example. There is no `--from`.
+camelCase keys. `canon schema scenario new --json` shows `input`: the schema of one document
+and a complete `example`. 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

@@ -34,8 +34,8 @@ authored; `canon status` (see `canon-subject`) says where the repo stands
 and what to run next. `--json` prints the `{ok, data, meta}` envelope: the
 header adds no field, and `policy.spec_coverage`/`policy.diagnostics`
 already carry the same fact. `--fields <list>` keeps only the named
-top-level fields (`kinds`, `enums`, `policy`, `review`, …); an unknown name is
-`UNKNOWN_FIELD` (exit 2).
+top-level fields (`kinds`, `enums`, `policy`, `review`, …), spelled as the report spells them; an unknown name is
+`USAGE` (exit 2; `field` is `--fields`, `expected` lists the selectable fields), and `meta.fields` lists the kept ones.
 
 On a repository that still holds 0.27 canon state, `canon context` warns
 and puts `canon migrate --json` first in `meta.next`: run `canon migrate`

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

@@ -347,7 +347,7 @@ brief_override:
 Under `--json` the same waiver is `data.overrides[]` (`code` of the waived
 refusal, `reason` verbatim), so a caller sees what its `--override-reason`
 let through; a repeat of an identical record is `unchanged`
-(`meta.unchanged`) and records no second override. `--override-reason`
+(`data.unchanged`) and records no second override. `--override-reason`
 exists on `subject move` too (see `canon-subject`).
 
 A blank or multi-line reason exits 2; an override when nothing refused is
@@ -534,7 +534,7 @@ 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 the input schema and an example. Each element reports `written`,
+shows `input`: the schema of one document and a complete `example`. Each element reports `written`,
 `unchanged` or `failed` in `data.items[]`.
 
 `--rev <rev>` names the commit the evidence ran against (default `HEAD`).

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

@@ -121,8 +121,8 @@ Outside git, or in a repository with no commit, the write is refused with
 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 the input schema and an example. An identical
-repeat is `unchanged` (`meta.unchanged`) and writes nothing; a different
+finding add --json` shows `input`: the schema of one document and a complete `example`. An identical
+repeat is `unchanged` (`data.unchanged`) and writes nothing; a different
 finding under an occupied key is `FINDING_SEQ_OCCUPIED`.
 
 ### A defect the author found in its own work
@@ -198,7 +198,7 @@ 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
-written again is `unchanged` (`meta.unchanged` under `--json`) and adds no
+written again is `unchanged` (`data.unchanged` under `--json`) and adds no
 record.
 
 **Done when:** `canon gate check` reports no `unreviewed-promotion` for the

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

@@ -104,9 +104,12 @@ canon query --kind handoff --since 2026-06-01T00:00:00Z
 canon query --kind trajectory --json
 
 # Page a long result and keep only the fields you need; `meta` carries
-# returned, total, hasMore and nextCursor (`--all` returns everything).
+# `page` = {returned, total, nextCursor} and `fields` = the paths kept; a present `nextCursor` means more, and
+# `meta.next` repeats the call with `--cursor <nextCursor>` (`--all` returns everything). A cursor is bound to the
+# call that issued it: change only `--limit`, `--all` or `--fields`; any other change is `CURSOR_INVALID`
+# (`error.reason` `ARGUMENTS_CHANGED`). A field path is the record's own key, written as it is.
 canon query --kind trajectory --json --limit 50 --fields at,kind
-canon query --kind trajectory --json --limit 50 --cursor <nextCursor>
+canon query --kind trajectory --json --limit 50 --fields at,kind --cursor <nextCursor>
 ```
 
 ## The ledger is latest-only; the archive holds history
@@ -189,7 +192,7 @@ section listing them and emits a matching stderr `WARN`.
 `canon purge --kind <kind> --before <RFC3339> [--commit --plan-digest <planDigest>] [--repo <dir>] [--json]`
 is the canonical data-lifecycle boundary: the bare run previews: it prints the removal set and
 its `planDigest` and deletes nothing; `--commit --plan-digest <planDigest>` deletes only if
-the plan recomputed now has the same digest (`PLAN_CHANGED`, exit 2, when the
+the plan recomputed now has the same digest (`PLAN_STALE`, exit 2, when the
 data moved). The only purgeable kinds are
 `session`, `run`, `event`, and `trajectory`; the cutoff applies to every
 routed rung and every configured aging destination, including retained
@@ -210,7 +213,7 @@ arguments previews an empty removal set.
 With `--json`, `purge` and `export` answer `{ "data", "meta" }` like every other
 command: `data` is the plan or manifest, `meta.next` the step after (a plan's is the
 human's review and `--commit --plan-digest`), and an export's page state (`total`, `returned`,
-`nextCursor`) sits in `meta`. `export --json --output <file>` writes the manifest to the
+`nextCursor`) sits in `meta.page`. `export --json --output <file>` writes the manifest to the
 file and answers with `data: { output, kind, recordCount }`; `--dry-run`
 answers with what it would write and writes nothing.
 

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

@@ -70,8 +70,8 @@ canon subject new subject-domain-loop \
   subjects at once: `--input` takes inline JSON, a file or `-`; an array (or
   NDJSON) is a batch validated before any write, with `operands` holding the
   id and the other keys the option names in camelCase (`canon schema subject
-  new --json` shows the schema and an example). Writing an identical subject
-  again is a no-op reported `unchanged` (`meta.unchanged`).
+  new --json` shows `input`: the schema of one document and a complete `example`). Writing an identical subject
+  again is a no-op reported `unchanged` (`data.unchanged`).
 
 ### 2. Retrieve subject-scoped strategy memory BEFORE working
 
@@ -747,21 +747,23 @@ Status fails closed rather than suggest progress the gate would refuse:
 ```
 
 The steps that follow are not in `data`: they are `meta.next`, most useful
-first, with `meta.nextOmitted` counting what was cut and `meta.waitingOn`
+first, with `data.nextOmitted` counting what was cut and `data.waitingOn`
 (with a declared role, `--as`) counting the steps each other owner holds:
 
 ```json
 "next": [
-  { "command": "show the brief in openspec/changes/c-promo/proposal.md; build and attest nothing for promo until the human answers; then record their words with `canon brief approve c-promo --approver <the human> --note \"<their words>\"`", "argv": [], "why": "promo: the brief is not approved", "actor": "human", "role": null },
-  { "command": "canon finding close c-cart --round 1 --seq 1 --disposition fixed --actor <unit> --session <session>", "argv": [], "why": "cart: 1 open blocker finding(s); fix it, commit, then close it", "actor": "agent", "role": "implementer" },
-  { "command": "canon status", "argv": ["canon", "status"], "why": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again", "actor": "agent", "role": "planner" }
+  { "command": "canon brief show c-promo --json", "argv": ["brief", "show", "c-promo", "--json"], "reason": "promo: the brief is not approved; build and attest nothing for promo until the human answers", "x-canon": { "actor": "human" } },
+  { "command": "canon gate check --json", "argv": ["gate", "check", "--json"], "reason": "cart: 1 open blocker finding(s); fix it, commit, then close it with `canon finding close`", "x-canon": { "actor": "agent", "role": "implementer" } },
+  { "command": "canon status --json", "argv": ["status", "--json"], "reason": "1 scenario(s) carry no @subject tag (first: cart.promo.01); add `@subject:<id>` above each in its .feature file, then check again", "x-canon": { "actor": "agent", "role": "planner" } }
 ]
 ```
 
-`argv` is the command split into words, and is empty when the command still
-holds a `<placeholder>` for what only the agent knows (or is not a canon
-command at all). On a repository that still holds 0.27 canon state,
-`canon status` warns (`data.warnings`, `meta.warnings`) and puts `canon
+`argv` is the command without the executable (`canon` + `argv` is the call),
+and carries `--json` when you called in JSON mode. Every next entry is
+runnable as it stands: guidance that needs a value only you know (an actor id,
+a session, the human's words) is not a next entry, it is in the error `hint`
+or the report text. On a repository that still holds 0.27 canon state,
+`canon status` warns (`data.warnings`, `meta.warnings` as `[{code, message}]`) and puts `canon
 migrate --json` first in `meta.next`: run `canon migrate`, then `canon
 migrate --commit --plan-digest <digest from the preview>`, then `canon
 skills install`.
@@ -792,14 +794,14 @@ only the pending drafts, and `flow` lists each flow step of every tagged
 change as `{ "id", "change", "scenarios": [{ id, title, failure, evidenced,
 review }], "gaps" }`.
 
-Each `meta.next` entry's `actor` is `agent` (its `command` is a canon command
-line) or `human` (its `command` says what to get from the human).
+Each `meta.next` entry's `x-canon.actor` is `agent` or `human` (a step only the
+human takes; its `reason` says what to get from them).
 
 `policy.spec_coverage` has the shape `canon context --json` prints
 (`null` when absent, `{"invalid": …}` when unusable). `statusVersion`
 changes only when a field changes meaning or is removed. It became `2`
 in 0.16, when `next[].command` stopped always being a command line
-(`actor` tells which), and `brief` was added alongside. It is `3` since
+(`actor` told which), and `brief` was added alongside. It is `3` since
 0.17, when `brief.proposal` was removed: the canon `brief.md` is
 `brief.brief`, with `briefExists` and `source`. It is `4` since 0.31, when the
 `brief` object became the `briefs` list.

package/dist/skills/reference/role-implementer.md

@@ -25,7 +25,7 @@ in your ids. Use only the options on a line; never guess one. Ask `canon schema
 <command> --json` only for a leaf this block does not list, or after a `USAGE` refusal.
 
 <!-- canon:generated commands-implementer begin -->
-Every leaf takes `--as <ROLE>` and `--json`; `--repo <DIR>` too, except `completion`, `schema`, `skills show`. `--input <JSON|FILE|->` runs a leaf from one JSON document (an array is a batch) and is only on the lines ending `[--input]`. Its document keys are the option names in camelCase, singular even when the option repeats (the value is then an array), and `operands` holds the operands. `--fields <FIELDS>` is a comma list; camelCase and snake_case both match.
+Every leaf takes `--as <ROLE>` and `--json`; `--repo <DIR>` too, except `completion`, `schema`, `skills show`. `--input <JSON|FILE|->` runs a leaf from one JSON document (an array is a batch) and is only on the lines ending `[--input]`. Its document keys are the option names in camelCase, singular even when the option repeats (the value is then an array), and `operands` holds the operands. `--fields <FIELDS>` is a comma list of the paths `canon schema <COMMAND> --json` declares under `outputs[].fields.paths`; a path is the record's own key, spelled as the answer spells it.
 In a syntax line `<X>` is a value, `[x]` optional, `a | b` a choice, `(a | b)` exactly one is required, `[--x <V>]*` may repeat, `<X>+` is one or more, `[--a --b <V>]` go together. An option that is not on the line does not exist: it is refused (`USAGE`).
 
 ```text
@@ -33,194 +33,194 @@ In a syntax line `<X>` is a value, `[x]` optional, `a | b` a choice, `(a | b)` e
 canon completion <SHELL>
 ```
 ```bash
-canon completion zsh
+canon completion zsh --json
 ```
 ```text
 # Show what you can author here: record kinds, fields, enums, policies
 canon context [--fields <FIELDS>]
 ```
 ```bash
-canon context
+canon context --json
 ```
 ```text
 # Create an immutable context pack from a repository-local JSON manifest
 canon context-pack add --manifest <FILE> [--input]
 ```
 ```bash
-canon context-pack add --manifest .canon/context-manifest.json
+canon context-pack add --manifest .canon/context-manifest.json --json
 ```
 ```text
 # Show a context pack after verifying its manifest and content objects
 canon context-pack show <PACK_ID>
 ```
 ```bash
-canon context-pack show sha256:0000000000000000000000000000000000000000000000000000000000000000
+canon context-pack show sha256:0000000000000000000000000000000000000000000000000000000000000000 --json
 ```
 ```text
 # Verify a context pack's manifest and immutable content objects
 canon context-pack verify <PACK_ID>
 ```
 ```bash
-canon context-pack verify sha256:0000000000000000000000000000000000000000000000000000000000000000
+canon context-pack verify sha256:0000000000000000000000000000000000000000000000000000000000000000 --json
 ```
 ```text
 # Add a divergence candidate, staged with no run_seq yet
 canon divergence add <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon divergence add auth.login.01 --actor alice --role reviewer
+canon divergence add auth.login.01 --actor alice --role reviewer --json
 ```
 ```text
 # Directly record a deferred divergence (requires --reason/--expiry)
 canon divergence defer <SCENARIO_ID> --actor <ACTOR_ID> --reason <TEXT> --expiry <TIMESTAMP> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--role <ROLE>] [--input]
 ```
 ```bash
-canon divergence defer auth.login.01 --actor alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer
+canon divergence defer auth.login.01 --actor alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer --json
 ```
 ```text
 # List the current divergence burn-down state
 canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
-canon divergence list --as-of 2030-01-01
+canon divergence list --as-of 2030-01-01 --json
 ```
 ```text
 # Directly record a resolved divergence
 canon divergence resolve <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--input]
 ```
 ```bash
-canon divergence resolve auth.login.01 --actor alice --role reviewer
+canon divergence resolve auth.login.01 --actor alice --role reviewer --json
 ```
 ```text
 # Record one attributed EvidenceRecord for a task or scenario
-canon evidence add [--task <TASK_ID>] [--project <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--approver <NAME>] [--approval-role <human>] [--signature-file <FILE>] [--approval-at <TIMESTAMP>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--all-scenarios] [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+canon evidence add [--task <TASK_ID> | --all-scenarios] [--project <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--scenario <SCENARIO_ID> | --all-scenarios] [--run <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--approver <NAME> | --all-scenarios] [--approval-role <human> | --all-scenarios] [--signature-file <FILE> | --all-scenarios] [--approval-at <TIMESTAMP> | --all-scenarios] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> | --all-scenarios]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon evidence add --scenario auth.login.01 --class test-run --ref "npm test" --role implementer
+canon evidence add --scenario auth.login.01 --class test-run --ref "npm test" --role implementer --json
 ```
 ```text
 # Emit exact bytes for external `ssh-keygen -Y sign -n canon-approval-v1`
 canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task <TASK_ID>] [--project <PROJECT_ID>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
 ```
 ```bash
-canon evidence approval-payload --scenario auth.login.01 --project root --approver alice --approval-at 2030-01-01T00:00:00Z
+canon evidence approval-payload --scenario auth.login.01 --project root --approver alice --approval-at 2030-01-01T00:00:00Z --json
 ```
 ```text
 # Record an external evaluator's re-audit of one scenario (class `audit`; the verdict follows --audit-result; canon never runs the evaluator)
-canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT>] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME>]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
-canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer
+canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer --json
 ```
 ```text
 # Create a fresh .feature file for a new area.surface
 canon feature new <SURFACE> --title <TEXT> [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
-canon feature new billing.invoice --title Invoices
+canon feature new billing.invoice --title Invoices --json
 ```
 ```text
 # List a change's committed findings at their latest version
 canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
-canon finding list --change add-login
+canon finding list --change add-login --json
 ```
 ```text
 # Validate a spec/artifact corpus against canon's format
 canon format [<DIR>]
 ```
 ```bash
-canon format .canon/specs
+canon format .canon/specs --json
 ```
 ```text
 # Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
 canon gate check [--release]
 ```
 ```bash
-canon gate check
+canon gate check --json
 ```
 ```text
 # Promote staged records (evidence, findings, divergences) to the committed ledger
 canon gate promote [--kind <evidence|finding|divergence>] [--dry-run] [--input]
 ```
 ```bash
-canon gate promote --kind evidence
+canon gate promote --kind evidence --json
 ```
 ```text
 # Validate each spec root, then materialize scenario index records
 canon inventory sync [--spec-root <DIR>] [--dry-run] [--input]
 ```
 ```bash
-canon inventory sync
+canon inventory sync --json
 ```
 ```text
 # Read stored records across every storage tier
 canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
-canon query --kind evidence
+canon query --kind evidence --json
 ```
 ```text
 # Fetch role-scoped strategy guidance
-canon retrieve --for-role <ROLE> [--regime <KEY>] [--domain <NAME>] [--subject <SUBJECT_ID>] [--limit <N>]
+canon retrieve --for-role <ROLE> (--regime <KEY> | --domain <NAME>) [--subject <SUBJECT_ID> (with --domain)] [--limit <N>]
 ```
 ```bash
-canon retrieve --for-role reviewer --domain dev --limit 20
+canon retrieve --for-role reviewer --domain dev --limit 20 --json
 ```
 ```text
 # Append a tagged scenario stub to its .feature file (created if missing); many at once with `--input`
 canon scenario new <SCENARIO_ID> --title <TEXT> [--subject <SUBJECT_ID>] [--lane <NAME>] [--case <NAME>] [--flow <FLOW_ID>] [--change <CHANGE_ID> (with --flow)] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--feature <FILE>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
-canon scenario new auth.login.02 --title "Sign out" --feature .canon/specs/kind=feature/area=auth/login.feature
+canon scenario new auth.login.02 --title "Sign out" --feature .canon/specs/kind=feature/area=auth/login.feature --json
 ```
 ```text
 # Describe canon's own commands
-canon schema [<PATH>]* [--errors | --error <CODE>]
+canon schema [<PATH>]* [--errors | --error <CODE> | --warning <CODE> | --warnings]
 ```
 ```bash
-canon schema evidence add
+canon schema evidence add --json
 ```
 ```text
 # Search records, brief sections and scenario text, with each hit's neighbors in the record graph
 canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
 ```
 ```bash
-canon search timeout --kind finding
+canon search timeout --kind finding --json
 ```
 ```text
 # Print a guide built into this binary (markdown on stdout); the installed SKILL.md is a stub that points here
 canon skills show <NAME> [--full]
 ```
 ```bash
-canon skills show canon --full
+canon skills show canon --full --json
 ```
 ```text
 # Show where this repo stands: subjects by status, their gaps, and the next commands
 canon status [--fields <FIELDS>]
 ```
 ```bash
-canon status
+canon status --json
 ```
 ```text
 # Flip one task checkbox, gated on real evidence (fails closed)
 canon task done <TASK_ID> [--input]
 ```
 ```bash
-canon task done add-login#1
+canon task done add-login#1 --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
 canon trace <ID>
 ```
 ```bash
-canon trace add-login_1_1
+canon trace add-login_1_1 --json
 ```
 <!-- canon:generated commands-implementer end -->
 
 After the first `status`, follow `meta.next` of each write; do not call
-`canon status` again to learn the next step. Every record you write takes
+`canon status` again to learn the next step. Each `meta.next` entry is runnable: run `canon` + its `argv`; guidance that needs a value you must fill in is in the error `hint` or the report text, not in `meta.next`. Every record you write takes
 the commit it is about from `--rev` (default `HEAD`, any git revision). You
 need not commit first: code that is not committed yet is recorded with its
 `codeTree` and `worktreeDirty: true`, never refused. Outside git, or in a
@@ -253,7 +253,7 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    keys are the option names in camelCase plus `operands` (the scenario id);
    every element is validated before the first write, so a bad element
    writes nothing and `error.field` names it (`/items/1/case`).
-   `canon schema scenario new --json` shows the input schema and an example.
+   `canon schema scenario new --json` shows `input`: the schema of one document and a complete `example`.
    (`scenario new --from` is gone.) When the gate asks for a missing case
    (`require_cases`), add a new scenario; never retag an existing one. Every
    bug fix adds or extends a scenario. Canon indexes added, edited or deleted
@@ -371,7 +371,7 @@ not another evidence step.
 ## Retry safety
 
 `evidence add` is content-keyed: repeating it with identical input returns
-the existing record with `meta.unchanged: true` instead of a duplicate (a
+the existing record with `data.unchanged: true` instead of a duplicate (a
 batch reports that element `unchanged`). After a timeout or a lost
 response, run the same command again. `scenario new` is not: an existing
 scenario id is refused (`SCENARIO_TAG_EXISTS`) and nothing changes, so check