@journeykit/canon 0.34.0 → 0.36.0

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

@@ -6,7 +6,7 @@ brief the human answers once. You build nothing. Declare the role with
 then show your steps and count the rest under `waitingOn`. The approvals are
 the human's: `brief approve`, `policy approve`, `divergence accept` and the
 `migrate --commit` that re-binds `Approved:` lines refuse every agent role
-(`HUMAN_ONLY`, `retryable: false`) unless you record the answer the human gave
+(`ACTOR_DENIED`, `retryable: false`) unless you record the answer the human gave
 you in the conversation, with `--relayed-via <tool>` (step 4). Without a human's
 explicit answer you never run them, and you never remove or unset your role
 (`env -u CANON_ROLE`, dropping `--as`) to get past the refusal.
@@ -20,152 +20,152 @@ 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-planner 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 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`).
+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; none is the key left out, `[]` is refused), 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.
+A `usage:` line shows the syntax and is not itself a command to run (the runnable example under it is): `<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
 # Read the brief against the rules
-canon brief check [<CHANGE_ID>]
+usage: canon brief check [<CHANGE_ID>]
 ```
 ```bash
 canon brief check --json
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>] [--body]
+usage: canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show --json
 ```
 ```text
 # Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
-canon change new <CHANGE_ID> --subject <SUBJECT_ID> --title <TEXT> [--change-kind <feature|chore>] [--input]
+usage: canon change new <CHANGE_ID> --subject <SUBJECT_ID> --title <TEXT> [--change-kind <feature|chore>] [--input]
 ```
 ```bash
 canon change new add-search --subject demo --title "Add search" --json
 ```
 ```text
 # Write the shell completion script for canon (bash, zsh or fish)
-canon completion <SHELL>
+usage: canon completion <SHELL>
 ```
 ```bash
 canon completion zsh --json
 ```
 ```text
 # Show what you can author here: record kinds, fields, enums, policies
-canon context [--fields <FIELDS>]
+usage: canon context [--fields <FIELDS>]
 ```
 ```bash
 canon context --json
 ```
 ```text
 # List the current divergence burn-down state
-canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon divergence list --as-of 2030-01-01 --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]
+usage: canon feature new <SURFACE> --title <TEXT> [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
 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>]
+usage: canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon finding list --change add-login --json
 ```
 ```text
 # Validate a spec/artifact corpus against canon's format
-canon format [<DIR>]
+usage: canon format [<DIR>]
 ```
 ```bash
 canon format .canon/specs --json
 ```
 ```text
 # Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
-canon gate check [--release]
+usage: canon gate check [--release]
 ```
 ```bash
 canon gate check --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>]
+usage: 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 --json
 ```
 ```text
 # Fetch role-scoped strategy guidance
-canon retrieve --for-role <ROLE> (--regime <KEY> | --domain <NAME>) [--subject <SUBJECT_ID> (with --domain)] [--limit <N>]
+usage: 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 --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]
+usage: 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 --json
 ```
 ```text
 # Describe canon's own commands
-canon schema [<PATH>]* [--errors | --error <CODE> | --warning <CODE> | --warnings]
+usage: canon schema [<PATH>]* [--schemas | --error <CODE> | --errors | --warning <CODE> | --warnings]
 ```
 ```bash
 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>]
+usage: 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 --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]
+usage: canon skills show [<NAME>] [--full]
 ```
 ```bash
 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>]
+usage: canon status [--fields <FIELDS>]
 ```
 ```bash
 canon status --json
 ```
 ```text
 # Link an imported plan change to a subject (adopting it under another subject adds that subject; a change may belong to several)
-canon subject adopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
+usage: canon subject adopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
 ```
 ```bash
 canon subject adopt demo --change add-login --json
 ```
 ```text
 # Author a new subject at status `proposed`
-canon subject new <SUBJECT_ID> --domain <NAME> --title <TEXT> [--summary <TEXT>] [--owner-role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--input]
+usage: canon subject new <SUBJECT_ID> --domain <NAME> --title <TEXT> [--summary <TEXT>] [--owner-role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--input]
 ```
 ```bash
 canon subject new payments --domain dev --title Payments --json
 ```
 ```text
 # Take a change back out of a subject (the mirror of adopt; refused for a change whose brief is approved)
-canon subject unadopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
+usage: canon subject unadopt <SUBJECT_ID> --change <CHANGE_ID> [--dry-run] [--input]
 ```
 ```bash
 canon subject unadopt demo --change add-login --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-canon trace <ID>
+usage: canon trace <ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -183,7 +183,7 @@ lists N blockers`); then, while prose advisories remain, to the polish pass
 (`polish the brief in <path> (canon skills show brief-polish), then run canon
 brief check <slug>`, with the advisory count and the top rule
 ids); the human step comes after it. A policy that no longer matches its approval fails closed
-(`POLICY_CHANGED_SINCE_APPROVAL`): never edit it; the human re-approves.
+(`POLICY_APPROVAL_STALE`): never edit it; the human re-approves.
 
 ## Steps
 
@@ -286,9 +286,9 @@ ids); the human step comes after it. A policy that no longer matches its approva
    show` and the dashboard name it. Never approve in their name without their
    answer, never write the answer for them, and never edit the policy to make
    the gate pass. A digest that differs from the brief now
-   (`RELAY_DIGEST_MISMATCH`) means the brief changed after they saw it: show
+   (`RELAY_DIGEST_STALE`) means the brief changed after they saw it: show
    it again and ask again; nothing was written. Without `--relayed-via` the call is
-   `HUMAN_ONLY`; with it and no role declared, `USAGE`. When `canon.yaml`
+   `ACTOR_DENIED`; with it and no role declared, `USAGE`. When `canon.yaml`
    turns relaying off (`approval: { relay: deny }`), the refusal names that key:
    report the human's call (`canon brief approve add-login --approver <their
    name> --note "<their own words>"`) and wait for them to run it. Never
@@ -300,7 +300,7 @@ ids); the human step comes after it. A policy that no longer matches its approva
    evidence with its reason and tracking reference, the migrate plan), ask,
    count only an explicit approval, then record with the relay option.
    `canon brief show <slug>` then reports `state: approved`. A brief edited
-   after its approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it
+   after its approval is not approved (`BRIEF_APPROVAL_STALE`): it
    needs a new answer, shown and asked again, and a new `brief approve`. A follow-up that
    adds or changes a step of the brief is a scope change and needs a new
    answer.

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

@@ -3,7 +3,7 @@
 You are the independent second look. Declare the role with
 `CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review scenario`,
 `review change` and `finding add` then defaults to `reviewer`. The human's
-acts refuse you (`HUMAN_ONLY`): `brief approve`, `policy approve` and
+acts refuse you (`ACTOR_DENIED`): `brief approve`, `policy approve` and
 `divergence accept`, unless you record the answer the human gave you in the
 conversation with `--relayed-via <tool>` (the divergence acceptance below).
 Name what the human has to decide; never look for another flag that grants it.
@@ -19,159 +19,159 @@ 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-reviewer 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 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`).
+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; none is the key left out, `[]` is refused), 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.
+A `usage:` line shows the syntax and is not itself a command to run (the runnable example under it is): `<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
 # Read the brief against the rules
-canon brief check [<CHANGE_ID>]
+usage: canon brief check [<CHANGE_ID>]
 ```
 ```bash
 canon brief check --json
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>] [--body]
+usage: canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show --json
 ```
 ```text
 # Write the shell completion script for canon (bash, zsh or fish)
-canon completion <SHELL>
+usage: canon completion <SHELL>
 ```
 ```bash
 canon completion zsh --json
 ```
 ```text
 # Show what you can author here: record kinds, fields, enums, policies
-canon context [--fields <FIELDS>]
+usage: canon context [--fields <FIELDS>]
 ```
 ```bash
 canon context --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]
+usage: 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 --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]
+usage: 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 --json
 ```
 ```text
 # List the current divergence burn-down state
-canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 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]
+usage: 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 --json
 ```
 ```text
 # Record one code-review finding
-canon finding add --change <CHANGE_ID> --round <N> --seq <N> --severity <blocker|should-fix|note> --actor <ACTOR_ID> --summary <TEXT> [--disposition <open|fixed|rejected|deferred>] [--rev <REV>] [--resolution-rev <REV> (with --disposition)] [--introduced-rev <REV> | --introduced-unknown] [--review <REVIEW_ID>] [--file-ref <TEXT>] [--scenario <SCENARIO_ID>]* [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
+usage: canon finding add --change <CHANGE_ID> --round <N> --seq <N> --severity <blocker|should-fix|note> --actor <ACTOR_ID> --summary <TEXT> [--disposition <open|fixed|rejected|deferred>] [--rev <REV>] [--resolution-rev <REV> (with --disposition)] [--introduced-rev <REV> | --introduced-unknown] [--review <REVIEW_ID>] [--file-ref <TEXT>] [--scenario <SCENARIO_ID>]* [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon finding add --change add-login --round 1 --seq 2 --severity should-fix --introduced-unknown --actor alice --summary "Token is logged" --json
 ```
 ```text
 # Move an already-committed finding's disposition
-canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
+usage: canon finding close <CHANGE_ID> --round <N> --seq <N> --disposition <open|fixed|rejected|deferred> [--resolution-rev <REV>] [--reason <TEXT>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon finding close add-login --round 1 --seq 1 --disposition rejected --reason "works as designed" --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>]
+usage: canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon finding list --change add-login --json
 ```
 ```text
 # Validate a spec/artifact corpus against canon's format
-canon format [<DIR>]
+usage: canon format [<DIR>]
 ```
 ```bash
 canon format .canon/specs --json
 ```
 ```text
 # Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
-canon gate check [--release]
+usage: canon gate check [--release]
 ```
 ```bash
 canon gate check --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>]
+usage: 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 --json
 ```
 ```text
 # Fetch role-scoped strategy guidance
-canon retrieve --for-role <ROLE> (--regime <KEY> | --domain <NAME>) [--subject <SUBJECT_ID> (with --domain)] [--limit <N>]
+usage: 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 --json
 ```
 ```text
 # Write one attributed Review record for a chore change directly to the ledger (exactly one provenance ref required)
-canon review change <CHANGE_ID> --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+usage: canon review change <CHANGE_ID> --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
 ```
 ```bash
 canon review change add-login --actor alice --role reviewer --original-spec-ref docs/prd.md --json
 ```
 ```text
 # Write one attributed Review record per scenario directly to the ledger, nothing to promote (exactly one provenance ref required)
-canon review scenario <SCENARIO_ID>+ --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
+usage: canon review scenario <SCENARIO_ID>+ --actor <ACTOR_ID> (--upstream-ref <TEXT> | --original-spec-ref <TEXT>) [--project <PROJECT_ID>] [--rev <REV>] [--role <ROLE>] [--session <SESSION_ID>] [--review-outcome <signed|indeterminate|unavailable>] [--reviewer-provider <NAME>] [--reviewer-model <NAME>] [--reviewer-harness <NAME>] [--artifact <PATH>]* [--max-artifact-mib <N>] [--input]
 ```
 ```bash
 canon review scenario auth.login.01 --actor alice --role reviewer --original-spec-ref docs/prd.md --json
 ```
 ```text
 # Describe canon's own commands
-canon schema [<PATH>]* [--errors | --error <CODE> | --warning <CODE> | --warnings]
+usage: canon schema [<PATH>]* [--schemas | --error <CODE> | --errors | --warning <CODE> | --warnings]
 ```
 ```bash
 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>]
+usage: 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 --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]
+usage: canon skills show [<NAME>] [--full]
 ```
 ```bash
 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>]
+usage: canon status [--fields <FIELDS>]
 ```
 ```bash
 canon status --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-canon trace <ID>
+usage: canon trace <ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -288,7 +288,7 @@ sign.
 `divergence accept` is for a scenario whose honest evidence is `divergent`
 and whose gap is limited by something outside this change (an upstream
 limit, a platform bug) and is tracked there. It records a human's decision,
-so it refuses every agent role (`HUMAN_ONLY`), you included, unless it records
+so it refuses every agent role (`ACTOR_DENIED`), you included, unless it records
 the answer the human gave you. What you do: confirm the evidence really is
 divergent and the limit is outside this change, then put to the human the
 scenario ids, the reason, the tracking reference and an expiry when the limit
@@ -297,11 +297,11 @@ Ask with the harness question tool (`ask` in omp, `AskUserQuestion` in Claude
 Code, otherwise in the chat): accept the gap, or not. Only an explicit
 approval counts; a question or a condition is not one, and no answer records
 nothing. Then record it from a session that did not attest the evidence
-(`DIVERGENCE_ACCEPT_REFUSED` otherwise): `canon divergence accept <ids> --actor
+(`DIVERGENCE_DENIED` otherwise): `canon divergence accept <ids> --actor
 <your actor id> --reason "<why>" --tracking <ref> --approver <their name> --note
 "<their answer>" --relayed-via <tool>`; the record carries the relay, the
 approver and their answer. When `canon.yaml` has `approval: { relay: deny }` the
-call is refused (`HUMAN_ONLY`, naming the key) and the human runs it themselves.
+call is refused (`ACTOR_DENIED`, naming the key) and the human runs it themselves.
 You never unset your role to run it. Never suggest it to skip
 a fix the implementer can make in this change. The acceptance pins that
 evidence: new evidence for the scenario, or its expiry, ends it, and the
@@ -358,7 +358,7 @@ implementer owns. Your last write's `meta.next` names the next step.
 identical repeat is reported `unchanged` (`data.unchanged: true`, or the
 element's `status` in a batch), so after a timeout run the same command
 again. A different finding under an occupied round and seq is refused
-(`FINDING_SEQ_OCCUPIED`): take the next seq. `finding close` with the same
+(`FINDING_EXISTS`): take the next seq. `finding close` with the same
 disposition is a no-op too.
 
 ## Excuses that fail

package/man/canon-adapter-authorize.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-authorize 1  "authorize 0.34.0" 
+.TH canon-adapter-authorize 1  "authorize 0.36.0" 
 .SH NAME
 canon\-adapter\-authorize \- Authorize declared capabilities against repository policy (preflight only)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-adapter-validate.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-validate 1  "validate 0.34.0" 
+.TH canon-adapter-validate 1  "validate 0.36.0" 
 .SH NAME
 canon\-adapter\-validate \- Read and validate one provider\-neutral response envelope
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-adapter.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter 1  "adapter 0.34.0" 
+.TH canon-adapter 1  "adapter 0.36.0" 
 .SH NAME
 canon\-adapter \- Validate a provider\-neutral adapter response without executing a provider
 .SH SYNOPSIS
@@ -43,4 +43,4 @@ Examples:
   canon adapter validate \-\-response response.json
   canon adapter validate \-\-response response.json \-\-repo . \-\-json
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-artifacts-move.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-move 1  "move 0.34.0" 
+.TH canon-artifacts-move 1  "move 0.36.0" 
 .SH NAME
 canon\-artifacts\-move \- Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH SYNOPSIS
@@ -30,10 +30,10 @@ orchestrator
 The tier to move to: the name of an `s3` tier in canon.yaml (for example `cold`)
 .TP
 \fB\-\-commit\fR
-Act on the previewed plan; needs \-\-plan\-digest
+Make the change; without it the command only previews.
 .TP
-\fB\-\-plan\-digest\fR \fI<DIGEST>\fR
-The `planDigest` the preview printed; the run acts only if the plan recomputed now has this digest
+\fB\-\-plan\-digest\fR \fI<PLAN_DIGEST>\fR
+The digest of the preview this commit carries out.
 .TP
 \fB\-\-repo\fR \fI<DIR>\fR
 The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
@@ -52,7 +52,7 @@ Print version
 .SH EXTRA
 Examples:
   canon artifacts move \-\-tier cold
-  canon artifacts move \-\-tier cold \-\-commit \-\-plan\-digest <DIGEST>
+  canon artifacts move \-\-tier cold \-\-commit \-\-plan\-digest <PLAN_DIGEST>
 
 The bare run previews: it lists every upload and removal and prints a planDigest, and writes nothing. \-\-commit \-\-plan\-digest acts on exactly that plan (PLAN_STALE, exit 2, when it changed since).
 
@@ -60,4 +60,4 @@ The bare run previews: it lists every upload and removal and prints a planDigest
 
 Idempotent and resumable: a run stopped anywhere leaves a repo the gate still passes, and the next run finishes; a second run finds nothing to do. A blob whose bytes do not match its name is never moved. Moving back to local is refused; `\-\-tier local` on a local repo is a no\-op.
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-artifacts-store.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-store 1  "store 0.34.0" 
+.TH canon-artifacts-store 1  "store 0.36.0" 
 .SH NAME
 canon\-artifacts\-store \- Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 .SH SYNOPSIS
@@ -51,4 +51,4 @@ For records written before canon stored bound bytes (0.11\-0.13), and for any ev
 
 Exit 0 when the pass ran (the gate decides whether an unstored file matters), 2 when the ledger cannot be read or a write fails.
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-artifacts-verify.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-verify 1  "verify 0.34.0" 
+.TH canon-artifacts-verify 1  "verify 0.36.0" 
 .SH NAME
 canon\-artifacts\-verify \- Check that the artifact store holds every file the latest evidence and current reviews bind (\-\-full re\-hashes the stored bytes)
 .SH SYNOPSIS
@@ -45,4 +45,4 @@ Asks the store canon.yaml\*(Aqs `artifacts:` block selects (default: local, .can
 
 Exit 0 when every file is stored, 1 when one is missing or altered (data.problems names each), 2 when the store cannot be used or reached: an unreachable store is a refusal, never a pass.
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-artifacts.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts 1  "artifacts 0.34.0" 
+.TH canon-artifacts 1  "artifacts 0.36.0" 
 .SH NAME
 canon\-artifacts \- Check or move the evidence artifact store (local, or an object\-store tier)
 .SH SYNOPSIS
@@ -42,4 +42,4 @@ Store the bound files of existing evidence records and current reviews in the ar
 canon\-artifacts\-move(1)
 Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-brief-approve.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-approve 1  "approve 0.34.0" 
+.TH canon-brief-approve 1  "approve 0.36.0" 
 .SH NAME
 canon\-brief\-approve \- Record the human\*(Aqs approval of the brief, bound to its text; refused while `brief check` has blockers
 .SH SYNOPSIS
@@ -64,11 +64,12 @@ Examples:
   canon brief approve add\-login add\-search fix\-sync \-\-approver Ana \-\-note \*(AqAll three, go.\*(Aq
 
 Several ids take one name, one answer and one timestamp. Every id is checked
-first; one refused id refuses the call (BRIEF_APPROVE_REFUSED) and nothing is
+first; one refused id refuses the call (the first refused id\*(Aqs code, with a
+detail for each) and nothing is
 written. Writes `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
 brief (the digest covers the brief without its `Approved:` lines) and records
 `canon policy approve` in the same call. Edit the brief afterwards and it reads as
-not approved (BRIEF_CHANGED_SINCE_APPROVAL) until a human answers again and this
+not approved (BRIEF_APPROVAL_STALE) until a human answers again and this
 runs again. Run it only from the human\*(Aqs answer, with their words as \-\-note.
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-brief-check.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-check 1  "check 0.34.0" 
+.TH canon-brief-check 1  "check 0.36.0" 
 .SH NAME
 canon\-brief\-check \- Read the brief against the rules: blocker and advisory findings (exit 0 clean, 1 blockers, 2 refused)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 [\fICHANGE_ID\fR]
 The change to read (default: the repo\*(Aqs only live change)
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-brief-show.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-show 1  "show 0.34.0" 
+.TH canon-brief-show 1  "show 0.36.0" 
 .SH NAME
 canon\-brief\-show \- Show where the change stands and the next one to three steps; never edits
 .SH SYNOPSIS
@@ -50,4 +50,4 @@ Examples:
 
 The operand names the change; without it the repo\*(Aqs only live change is read.
 .SH VERSION
-v0.34.0
+v0.36.0

package/man/canon-brief.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief 1  "brief 0.34.0" 
+.TH canon-brief 1  "brief 0.36.0" 
 .SH NAME
 canon\-brief \- Check a change\*(Aqs brief (PRD format) and see the next steps; never edits
 .SH SYNOPSIS
@@ -61,4 +61,4 @@ gets one blocker, `brief.old\-format`: `canon migrate` rewrites it. A brief
 with fewer than two known headings (written before 0.19) checks as `brief.legacy`, an
 advisory. Without \-\-change, the repo\*(Aqs only live change is checked.
 .SH VERSION
-v0.34.0
+v0.36.0