@journeykit/canon 0.30.0 → 0.32.0

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

@@ -129,11 +129,11 @@ A present section, even `require_evidence: false` or a malformed one
 
 - **Unimplemented** — no `EvidenceRecord` carries the scenario's
   `(project_id, scenario_id)`. Author one with
-  `canon evidence add --scenario-id <id> --project-id <root-id>`; the
+  `canon evidence add --scenario <id> --project <root-id>`; the
   root id is needed once more than one spec root is configured, because
   two roots may carry the same scenario id. `--summary` is allowed here too (scanned for fabrication
   markers like a task's); it is a row suffix only when the record also
-  names a `--task-id`. A record carrying both `--task-id` and `--scenario-id`
+  names a `--task`. A record carrying both `--task` and `--scenario`
   is one attestation answering both joins: it counts for the task cell
   and for the scenario cell (verdicts, the shipped gate, the review gate).
 - **Mismatched** — the folded divergence state is `open`,
@@ -161,7 +161,7 @@ A present section, even `require_evidence: false` or a malformed one
   (a review written before 0.15 has no pins and skips this check), and,
   when `distinct_actor` (default `true`), is by a reviewer and actor
   other than the scenario's evidence actor and from a session other than
-  any evidence session when both carry one (`--session-id`);
+  any evidence session when both carry one (`--session`);
   gaps are `unreviewed-promotion`, and the detail says whether the
   review is missing, a self-review, stale (naming whether the spec, the
   evidence or both changed), or not signed. With `block_on_findings`
@@ -218,7 +218,7 @@ report such files.
 ### Accepted divergence and re-verification
 
 ```bash
-canon divergence accept cart.add.01 --project-id root --reason "known gap" --tracking "issue#12" --expiry 2026-12-31 --actor-id reviewer-2 --role reviewer --session-id review-session-1
+canon divergence accept cart.add.01 --project root --reason "known gap" --tracking "issue#12" --expiry 2026-12-31 --actor reviewer-2 --role reviewer --session review-session-1
 ```
 
 Accepting a scenario whose latest evidence is `divergent` as a known gap
@@ -240,10 +240,10 @@ Re-verification is one rule with two triggers: a blocker whose latest
 disposition is `fixed`, and a chore change once approved, keep the subject
 from shipping until every one of its evidenced scenarios has evidence
 recorded after the close or the approval. A blocker that names its
-scenarios (`finding add --scenario-id`) asks only those, and the refusal
-names them with the per-scenario command (`canon evidence add --project-id
-<root-id> --scenario-id <id> --report <format>:<path>` plus `--class`, `--role` and `--ref`). Otherwise the
-refusal names the scenarios and the batch command: `canon evidence add --project-id <root-id>
+scenarios (`finding add --scenario`) asks only those, and the refusal
+names them with the per-scenario command (`canon evidence add --project
+<root-id> --scenario <id> --report <format>:<path>` plus `--class`, `--role` and `--ref`). Otherwise the
+refusal names the scenarios and the batch command: `canon evidence add --project <root-id>
 --all-scenarios --report <format>:<path> --class test-run --role
 implementer --ref "<test command>"`. Reviews pin what the evidence says
 (its verdict and the identity of its checks), not which record it is, so
@@ -259,17 +259,17 @@ canon never generates or runs an audit. An external evaluator does, and
 canon records its result:
 
 ```bash
-canon evidence audit cart.add.01 --project-id root \
+canon evidence audit cart.add.01 --project root \
   --ref "judge run 42" --role reviewer \
-  --evaluator-id judge --evaluator-version 1.2 \
+  --evaluator judge --evaluator-version 1.2 \
   --evaluator-digest 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 \
   --audit-result refuted --report junit:audit/counterexample.xml
 ```
 
-- `evidence audit` requires the scenario operand, `--ref`, `--evaluator-id`,
+- `evidence audit` requires the scenario operand, `--ref`, `--evaluator`,
   `--evaluator-version`, `--evaluator-digest` (sha256, 64 lowercase hex)
-  and `--audit-result confirmed|refuted|indeterminate`, with `--project-id`
-  where several spec roots exist. It takes no `--task-id`, `--verdict`,
+  and `--audit-result confirmed|refuted|indeterminate`, with `--project`
+  where several spec roots exist. It takes no `--task`, `--verdict`,
   `--surface-ref` or `--approval-*`; the evaluator flags exist on no other
   command. All refusals exit `2`.
 - The record carries `audit: {evaluator_id, evaluator_version,
@@ -299,23 +299,23 @@ never rides along into a confirming audit. `--drop-attachment` and
 
 ### Nothing is attested before the brief is approved (`--override-reason`)
 
-The approval is never assumed: the agent writes the brief, stops and
-reports it, and builds nothing for that scope until the human answers.
-`canon evidence add` is the backstop for that stop (0.16 M7). It
+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
-attests for has an enforced, unapproved brief: the newest adopted
-change's canon `.canon/changes/<change>/brief.md` has no `Approved:`
+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
 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
 `canon-subject`; which changes a scenario answers to is scoped by its `@flow:<change>.<F-id>` tags, described there). The subjects are the scenario's `@subject` owner for
-`--scenario-id`, and every subject adopting the task's change for
-`--task-id`:
+`--scenario`, and every subject adopting the task's change for
+`--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, report the brief to the human and wait for their answer: nothing is built or attested for a subject before its brief is approved. Record their answer with `canon brief approve --approver <the human> --note "<their words>"` only from that answer; to attest anyway, pass --override-reason <text>, which is recorded on the evidence record
+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
@@ -341,7 +341,7 @@ brief_override:
   reason: the human approved in chat; the line follows
   waived:
     - { class: unreviewed-promotion, subject: demo-subject }
-  actor: { agent_id: lead }   # from --actor-id
+  actor: { agent_id: lead }   # from --actor
 ```
 
 Under `--json` the same waiver is `data.overrides[]` (`code` of the waived
@@ -376,8 +376,9 @@ review waivers: 1 advisory(ies) — not failing the gate:
 The waiver lasts only until the subject's next status write.
 
 `canon subject move <id> --to shipped` also refuses where a brief exists and
-is not approved (the subject's scope, its newest adopted change walking back past pending drafts
-no scenario is tagged `@flow:<change>.*` for, has a canon
+is not approved (a change the subject answers for, that is one a scenario of
+the subject is tagged `@flow:<change>.*` for, one with an `Approved:` line,
+or a chore, has a canon
 `brief.md` with no `Approved:` line or one the brief's text no longer
 matches, or an external `proposal.md` and no canon `brief.md` yet;
 see `canon-subject`), as an `unreviewed-promotion` naming
@@ -437,14 +438,14 @@ what backed the claim:
 
 ```bash
 # any file: a Playwright trace, screenshots, an agent QA log — by sha256
-canon evidence add --scenario-id cart.add.04 --project-id root \
+canon evidence add --scenario cart.add.04 --project root \
   --class agent-qa --ref "stagehand run 7" --role implementer \
   --artifact test-results/cart-trace.zip
 # a JUnit XML or Cucumber JSON report: also records the matched case + outcome
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "cargo nextest run" --role implementer --report junit:target/nextest/default/junit.xml
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "cucumber-js" --role implementer --report cucumber:reports/cucumber.json
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "cargo nextest run" --role implementer --report junit:target/nextest/default/junit.xml
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "cucumber-js" --role implementer --report cucumber:reports/cucumber.json
 # a Swift Testing event stream (swift test --experimental-event-stream-output <path>)
-canon evidence add --scenario-id cart.add.04 --project-id root --class test-run --ref "swift test" --role implementer --report swift-testing:.build/events.jsonl
+canon evidence add --scenario cart.add.04 --project root --class test-run --ref "swift test" --role implementer --report swift-testing:.build/events.jsonl
 ```
 
 A case is bound when the scenario id is its OWN: the first
@@ -496,12 +497,12 @@ not close it.
 One test run proves many scenarios. Bind it once:
 
 ```bash
-canon evidence add --project-id root --all-scenarios \
+canon evidence add --project root --all-scenarios \
   --report junit:target/nextest/default/junit.xml \
   --class test-run --ref "cargo nextest run" --role implementer
 ```
 
-Each indexed scenario of `--project-id` that owns a case (the rule above)
+Each indexed scenario of `--project` that owns a case (the rule above)
 gets its own record, with only its own cases. Its verdict comes from
 them: `faithful` when every case passed, `divergent` when one failed,
 `not-applicable` when one was skipped and none failed. `--verdict <v>`
@@ -521,18 +522,18 @@ It is all or nothing: a claimed `faithful` verdict over a failed case,
 a fabrication marker in `--summary`, an unapproved brief for any
 scenario's subject refuses the whole batch, and nothing is written. Each
 record binds only what the batch names (nothing is carried forward).
-`--scenario-id`, `--task-id`,
+`--scenario`, `--task`,
 `--report-case`, `canon evidence audit` and the approval flags name one subject
 and are refused with `--all-scenarios`.
 
-A task's evidence with `--report` and no `--scenario-id` binds EVERY case
+A task's evidence with `--report` and no `--scenario` binds EVERY case
 in the report, so a `faithful` verdict needs all of them to pass.
 
 Many records at once without a report: `--input` takes inline JSON, a file
 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
-`scenarioId`, `class`, `ref` and `role`. `canon schema evidence add --json`
+`scenario`, `class`, `ref` and `role`. `canon schema evidence add --json`
 shows the input schema and an example. Each element reports `written`,
 `unchanged` or `failed` in `data.items[]`.
 
@@ -552,7 +553,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-id root --actor-id reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
+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
@@ -684,7 +685,7 @@ task at all is a loud failure naming every source consulted. A repo with
 no `.canon/changes/` and `sources: []` is refused: "this repo configures
 no plan sources (no `.canon/changes` and no `plans.sources` entries in
 canon.yaml) … write the change with `canon change new`, or list your
-external plans under `plans.sources`" (`canon dispatch begin --task-id` says the
+external plans under `plans.sources`" (`canon dispatch begin --task` says the
 same).
 It requires
 a matching non-`Divergent` evidence record, and flips `- [ ]` → `- [x]`
@@ -706,7 +707,7 @@ A flip on evidence that cannot prove the task still succeeds, but warns
 on stderr: when none of the task's evidence records binds a file and one
 of them cites a canon command as its `--ref` (`canon gate check`,
 `canon status`), the warning says to bind the artifact or report that
-proves the task (`canon evidence add --task-id <id> --artifact <path>` or
+proves the task (`canon evidence add --task <id> --artifact <path>` or
 `--report <format>:<path>`). A canon command reports on canon's own
 records, so it is never the proof of a task.
 
@@ -779,6 +780,14 @@ canon gate install-hooks --repo .
 canon gate install-hooks --repo . --event PreToolUse --matcher Edit --command "canon gate check" --timeout 30
 ```
 
+It installs no git hook: copy the script into git's `pre-commit` hook
+(`.git/hooks/pre-commit`) or call it from a hook runner. The output names the two
+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.
+
 Prefer this over hand-editing `settings.json`/`hooks.json`.
 
 ## `canon selftest --suite trust-spine-gate`

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

@@ -183,9 +183,9 @@ record.
 An operator-requested rollback is a distinct authenticated action:
 
 ```text
-canon strategy rollback <strategy_id> --reason "<reason>" --actor-id alice \
+canon strategy rollback <strategy_id> --reason "<reason>" --actor alice \
   --signature-file rollback.sig --approval-at 2026-10-02T12:00:00Z \
-  [--contradicting-trajectory-id <trajectory_id>] --repo .
+  [--contradicting-trajectory <trajectory_id>] --repo .
 ```
 
 `--signature-file` is an armored SSH detached signature over the

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

@@ -13,8 +13,8 @@ one, and neither can `canon gate`.
 one `<slug>/` directory per change holding `brief.md` (and a `tasks.md`
 only when someone adds one: an optional work note), written by
 `canon change new` (see `canon-subject`). Every plan reader —
-`canon ingest plans`, `canon task done`, `canon evidence add --task-id`,
-`canon dispatch begin --task-id`, `canon status` and the brief check — reads it
+`canon ingest plans`, `canon task done`, `canon evidence add --task`,
+`canon dispatch begin --task`, `canon status` and the brief check — reads it
 first whenever the directory exists, with no `plans:` entry. Being first,
 it owns a change id an external source also carries (the external copy
 is the later duplicate, skipped and counted under `duplicate_change_id`).

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

@@ -70,12 +70,12 @@ error; the next step (3) reads the overlay back.
 ## 3. Project a read
 
 ```bash
-canon query --kind scenario --plugin-id porting          # human table, projected fields appended
-canon query --kind scenario --plugin-id porting --json   # merged record bodies
-canon query --kind scenario                           # no --plugin-id: byte-identical to the core view
+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
 ```
 
-`--plugin-id <id>` folds the plugin's overlay records (latest-by-
+`--plugin <id>` folds the plugin's overlay records (latest-by-
 `(join_key, at)`) onto each queried core record. Fail-soft everywhere:
 
 - No overlay record for a core key → that record projects UNMODIFIED (no
@@ -85,7 +85,7 @@ canon query --kind scenario                           # no --plugin-id: byte-ide
   SKIPPED + diagnosed; siblings still project.
 - An absent plugin/manifest → the unmodified core view + a diagnostic,
   never a process error.
-- Omitting `--plugin-id` is byte-identical to `canon query`'s output without
+- Omitting `--plugin` is byte-identical to `canon query`'s output without
   plugins — it's a purely additive layer.
 
 **Done when:** the projected table or JSON shows the plugin's fields on the
@@ -108,7 +108,7 @@ scenarios you synced.
    (zero new files) and a genuine coverage edit supersedes the prior
    overlay via latest-`at`-wins.
 3. `canon plugin sync porting` writes/dedupes those candidates.
-4. `canon query --kind scenario --plugin-id porting [--json]` projects
+4. `canon query --kind scenario --plugin porting [--json]` projects
    `covered`/`surface_ref` back onto each scenario.
 
 `canon gate check`'s verdicts are byte-identical with and without a

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

@@ -75,10 +75,13 @@ canon policy approve --approver <who> [--note <text>] [--repo <dir>]
 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-only leaf: with a role declared (`--as` or `CANON_ROLE`)
-it is refused with `HUMAN_ONLY` (exit 2, not retryable), and no flag grants
-it to an agent. The human runs it themselves, for a policy-only change or
-after the brief answer, supplying `--approver` and `--note`. It
+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
+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`
+(role, actor, tool). The human may run it themselves, for a policy-only change
+or after the brief answer, supplying `--approver` and `--note`. It
 writes `.canon/policy.approval.json` directly (nothing to promote):
 
 ```json

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

@@ -151,18 +151,25 @@ canon dashboard --snapshot /tmp/canon-snap --port 8080
 `/briefs.html` lists every live change whose brief awaits the human (no
 `Approved:` line, or edited since) with its intent, outcome, flow steps,
 acceptance, questions and assumptions, and its `canon brief check`
-blockers and advisories. The human types their name and their answer and
-clicks Approve: that records exactly what `canon brief approve
-<id> --approver <name> --note <text>` records, the `Approved:` line bound to the
-brief digest and the policy approval. It is refused when the brief changed
-after the page loaded (`BRIEF_CHANGED_SINCE_PAGE_LOAD`: reload) or while it
-has blockers (`BRIEF_APPROVE_REFUSED`). The server is localhost only and
+blockers and advisories. Each brief that has no blocker has a selection box
+and the page shows how many are selected. The human types their name and their
+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
+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`).
 
-For an agent the human stop is unchanged: when clean briefs are waiting,
-tell the human they can approve them in `canon dashboard` (briefs page) or
-answer in chat. An agent never clicks Approve or fills the form, and runs
-`canon brief approve` only from the human's own words.
+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
+can approve them in `canon dashboard` (briefs page) instead. An agent never
+clicks Approve or fills the form; it runs `canon brief approve` only from the
+human's explicit answer, with `--relayed-via`. The page lists the approvals an
+agent recorded for the human under "Approved through an agent" (`relayed` in
+`GET /api/briefs`), with the role, actor and tool of each.
 
 The dashboard renders SEVEN panels — trust matrix, session costs, role
 memory, flywheel funnel, review burn-down, review rounds, review totals.

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

@@ -17,7 +17,7 @@ state they are in.
 The order an agent follows to claim a subject done:
 
 1. **Test-run evidence** per owned scenario (`canon evidence add
-   --scenario-id <id> --project-id <root-id> --session-id <session>` and the
+   --scenario <id> --project <root-id> --session <session>` and the
    rest of its options;
    final when it returns under `write: { promote: auto }`, which
    `canon init` writes, and followed by `canon gate promote` only under
@@ -26,9 +26,9 @@ The order an agent follows to claim a subject done:
    each issue the reviewer raises as a Finding, fix it, then close it:
 
    ```bash
-   canon finding add --change-id c-demo --round 1 --seq 1 \
-     --severity blocker --introduced-unknown --disposition open --actor-id reviewer-2 \
-     --summary "unbounded subprocess wait" --session-id review-session-1
+   canon finding add --change c-demo --round 1 --seq 1 \
+     --severity blocker --introduced-unknown --disposition open --actor reviewer-2 \
+     --summary "unbounded subprocess wait" --session review-session-1
    # ... fix, commit ...
    canon finding close c-demo --round 1 --seq 1 \
      --disposition fixed --resolution-rev HEAD
@@ -42,9 +42,9 @@ The order an agent follows to claim a subject done:
    the evidence is in (the review pins what it saw):
 
    ```bash
-   canon review scenario world.demo.01 --project-id root \
-     --actor-id reviewer-2 --role reviewer \
-     --session-id review-session-1 \
+   canon review scenario world.demo.01 --project root \
+     --actor reviewer-2 --role reviewer \
+     --session review-session-1 \
      --rev HEAD --upstream-ref "pr#41"
    ```
 
@@ -72,12 +72,12 @@ key, because two different findings under one key are two reviewers'
 work collapsed into one identity.
 
 ```text
-canon finding add --change-id <c> --round <n> --seq <n> \
+canon finding add --change <c> --round <n> --seq <n> \
   --severity blocker|should-fix|note --disposition open \
-  --actor-id <who> --summary "<one line>" \
-  [--rev <rev>] [--resolution-rev <rev>] [--introduced-rev <rev> | --introduced-unknown] [--file-ref path/to/file.rs:120-134] [--scenario-id <id>] [--session-id <id>]
+  --actor <who> --summary "<one line>" \
+  [--rev <rev>] [--resolution-rev <rev>] [--introduced-rev <rev> | --introduced-unknown] [--file-ref path/to/file.rs:120-134] [--scenario <id>] [--session <id>]
 canon finding close <c> --round <n> --seq <n> \
-  --disposition fixed --resolution-rev <rev> [--actor-id <id>] [--session-id <id>]   # or rejected / deferred / open
+  --disposition fixed --resolution-rev <rev> [--actor <id>] [--session <id>]   # or rejected / deferred / open
 canon finding close <c> --round <n> --seq <n> \
   --disposition rejected|deferred --reason "<why, one line>"
 ```
@@ -88,7 +88,7 @@ on the closing version, shown by `finding list` as `[reason: …]` and carried
 in the JSON. Give the reason when you reject or defer: it is the only record
 of why the finding was not fixed.
 
-`--scenario-id` (repeatable, each a scenario the index knows; refused with
+`--scenario` (repeatable, each a scenario the index knows; refused with
 `FINDING_UNKNOWN_SCENARIO` 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
@@ -103,7 +103,7 @@ run; nothing to promote``); under `write.promote: manual`
 changes only the disposition (and `resolution_sha` with it); severity,
 reviewer, summary, and refs are copied from the committed record. It
 appends a second version at the same natural key — the first stays. Its
-`--actor-id` and `--session-id` name who authored the transition; the
+`--actor` and `--session` name who authored the transition; the
 raiser's stay on the first version.
 
 Every commit option (`--rev`, `--resolution-rev`, `--introduced-rev`)
@@ -120,7 +120,7 @@ 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 (`changeId`, `actorId`, `resolutionRev`); `canon schema
+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 under an occupied key is `FINDING_SEQ_OCCUPIED`.
@@ -128,13 +128,13 @@ finding under an occupied key is `FINDING_SEQ_OCCUPIED`.
 ### A defect the author found in its own work
 
 Record it like any other finding, at the moment you find it and before
-review, with `--actor-id` set to your own id; never ask
+review, with `--actor` set to your own id; never ask
 the reviewer to record it later under theirs. Nothing refuses a finding
 whose reviewer is also the implementer, and an open `blocker` the author
 raised blocks under `block_on_findings` exactly like a reviewer's.
 `--introduced-rev` names the commit that introduced the defect, not who
 found it: `--introduced-rev self` is a usage error (exit 2) that points at
-`--actor-id`.
+`--actor`.
 
 ### Severities
 
@@ -169,20 +169,20 @@ fixed finding reopened with `--disposition open` counts as open again.
 ## `canon review scenario`
 
 ```text
-canon review scenario <scenario-id> [<scenario-id>] --project-id <root-id> \
-  --actor-id <who> [--rev <rev>] --role <role> \
-  (--upstream-ref <ref> | --original-spec-ref <ref>) [--session-id <id>] \
+canon review scenario <scenario-id> [<scenario-id>] --project <root-id> \
+  --actor <who> [--rev <rev>] --role <role> \
+  (--upstream-ref <ref> | --original-spec-ref <ref>) [--session <id>] \
   [--review-outcome signed|indeterminate|unavailable] \
   [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>] \
   [--artifact <path>] [--artifact <path>] [--max-artifact-mib <MiB>]
-canon review change <slug> --project-id <root> --actor-id <who> [--rev <rev>] \
+canon review change <slug> --project <root> --actor <who> [--rev <rev>] \
   --role reviewer (--upstream-ref <ref> | --original-spec-ref <ref>)   # a chore, below
 ```
 
 One attributed Review record per scenario, joined on
 `(project_id, scenario_id)` — both are required because two spec roots
 may carry the same scenario id. Exactly one provenance ref is required.
-`--actor-id` is the reviewer and is required; `--session-id` fills `actor.session_id`.
+`--actor` is the reviewer and is required; `--session` fills `actor.session_id`.
 A Review carries no verdict about the behavior; the `verifying → shipped`
 ship gate still refuses missing or `Divergent` evidence verdicts on its
 own (a `Divergent` one passes only while a human's `canon divergence
@@ -321,7 +321,7 @@ sign-off or a rejection, and `review scenario` says so. `--reviewer-provider`,
 `--reviewer-model` and `--reviewer-harness` record the runtime that
 produced the review, as given. An empty or padded label is a usage error.
 
-`--session-id` (on `evidence add`, `review scenario`, `finding add` and
+`--session` (on `evidence add`, `review scenario`, `finding add` and
 `finding close`) takes one opaque token: non-empty, no surrounding
 whitespace, no control characters. Anything else is a usage error
 (exit 2) and nothing is written.
@@ -346,7 +346,7 @@ spec_coverage:
   `spec_coverage.scope`. `spec_coverage.exclude_lanes` also exempts
   scenarios from review.
 - **`distinct_actor`** — a review only counts when both its `reviewer`
-  and its actor (`--actor-id`) differ from every actor on that
+  and its actor (`--actor`) differ from every actor on that
   scenario's evidence records, and, when the review carries a session,
   that session differs from every session on those evidence records. An
   agent cannot review its own attested work, under another id or from
@@ -484,7 +484,7 @@ routing. The new Subject record lists exactly the violations it let
 through:
 `status_override: {to, reason, waived: [{class, subject}], actor: {agent_id}}`
 (`subject` is the scenario id, or `<change_id>#<round>.<seq>` for a
-blocker; actor from `--actor-id`, default `canon`). The command prints
+blocker; actor from `--actor`, default `canon`). The command prints
 the `waived ...` lines and `override recorded by `lead` for the N
 violation(s) above: <reason>`. A blank or multi-line reason exits 2. The
 waiver covers only what it recorded, and clears on the subject's next

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

@@ -265,8 +265,8 @@ write:
 `--promote` / `--no-promote` decide for one write and win over the config
 without reading it; both at once is a usage error (exit `2`). If the
 promotion refuses the command's own record, the record stays staged, the
-line ends ``— run `canon gate promote` to commit it`` (`canon divergence
-promote` for a divergence), and the command exits `1`. With neither flag,
+line ends ``— run `canon gate promote` to commit it`` (`canon gate promote
+--kind divergence` for a divergence), and the command exits `1`. With neither flag,
 a malformed `write:` section (anything but `promote: auto | manual`)
 refuses the write, exit `2`, before anything is staged. `canon init
 --check` reports `[PASS] write (promote: auto)`, `[not configured]