@journeykit/canon 0.27.0 → 0.29.0

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

@@ -13,18 +13,18 @@ trajectories into retrievable, promotable insights. Two tiers:
 ## Rebuilding strategy memory
 
 Strategy memory is re-derived from the current trajectory set as part of
-`canon ingest artifacts` (see `canon-artifact-ingest`): after it
+`canon ingest records` (see `canon-artifact-ingest`): after it
 persists a repo's verdict trajectories, it re-derives the distilled
 strategies. This is NON-DESTRUCTIVE — a rebuild never drops a
 hand-promoted strategy the trajectory rows don't touch. There is no
-standalone `canon learn` rebuild command; the only subcommand is
-`promote`.
+standalone rebuild command under `canon strategy`; its subcommands are
+`promote`, `approval-payload` and `rollback`.
 
-# `canon learn promote <strategy_id> [--repo <dir>] [--evaluation <path> --approval <path>] [--signature <path>] [--dry-run]`
+# `canon strategy promote <strategy_id> [--repo <dir>] [--evaluation <path> --approval <path>] [--signature-file <path>] [--dry-run]`
 
 The production activation path is a signed, paired-evaluation workflow:
 
-1. Run `canon ingest artifacts`. Ingest resolves covering verdicts and rebuilds
+1. Run `canon ingest records`. Ingest resolves covering verdicts and rebuilds
    newly distilled strategies as `lifecycle: quarantined`.
 2. Check eligibility with the configured `occurrence` or `crn` gate. This is
    only a prerequisite; occurrence alone MUST NOT activate a strategy.
@@ -44,14 +44,14 @@ The production activation path is a signed, paired-evaluation workflow:
 5. Produce the unsigned approval payload:
 
    ```bash
-   canon learn approve <strategy_id> --evaluation evaluation.json \
-     --principal alice --repo .
+   canon strategy approval-payload 01J8ZQ4W7K2M5N6P8R0S3T9VXY --evaluation evaluation.json \
+     --approver alice --approval-at 2026-10-02T12:00:00Z --repo .
    ```
 
    With `--json` the payload is `.data` of the `{ "data", "meta" }` envelope, and
    `meta.next` names the human signing step. The `data` contains the evaluation digest, RFC3339 `approved_at`,
    subject `strategy:<strategy_id>`, namespace
-   `canon-learning-approval-v1`, and `payload_hex`. `approve` never
+   `canon-learning-approval-v1`, and `payload_hex`. `approval-payload` never
    reads a private key and never sets `verified`.
 6. Decode `payload_hex` to the exact canonical JSON bytes. The signed object
    is:
@@ -97,12 +97,12 @@ The production activation path is a signed, paired-evaluation workflow:
 8. Activate only with both evidence files:
 
    ```bash
-   canon learn promote <strategy_id> --repo . \
+   canon strategy promote 01J8ZQ4W7K2M5N6P8R0S3T9VXY --repo . \
      --evaluation evaluation.json --approval approval.json
    # Or attach an armored signature file and recompute the approval digest:
-   canon learn promote <strategy_id> --repo . \
+   canon strategy promote 01J8ZQ4W7K2M5N6P8R0S3T9VXY --repo . \
      --evaluation evaluation.json --approval approval.json \
-     --signature approval.sig
+     --signature-file approval.sig
    ```
 
    `--evaluation` and `--approval` MUST be supplied together. A quarantined
@@ -123,6 +123,10 @@ An unknown `strategy_id` fails nonzero. A candidate's lifecycle defaults to
 The old public writer is retained only for already-`active` items; it is not a
 way to activate new or legacy candidates.
 
+**Done when:** `canon strategy promote <strategy_id>` exits `0` and
+`canon retrieve` returns the strategy for its regime (a quarantined
+candidate stays out of retrieval).
+
 ### The eligibility gates: `crn` vs `occurrence`
 
 A role's eligibility gate is a `canon.yaml` `learn:`-section choice:
@@ -160,11 +164,11 @@ A role with no explicit `promotion.<role>` entry defaults to
 
 Both gates read resolved `verdict_record.outcome`, not raw verdict rows.
 `Pending` trajectories neither corroborate nor contradict. `canon ingest
-artifacts` is therefore always first:
+records` is therefore always first:
 
 ```bash
-canon ingest artifacts
-canon learn promote <id> --evaluation evaluation.json --approval approval.json
+canon ingest records
+canon strategy promote 01J8ZQ4W7K2M5N6P8R0S3T9VXY --evaluation evaluation.json --approval approval.json
 ```
 
 ### Demotion versus authenticated rollback
@@ -178,15 +182,15 @@ record.
 
 An operator-requested rollback is a distinct authenticated action:
 
-```bash
-canon learn rollback <strategy_id> --reason "<reason>" --actor-id alice \
-  --signature-file rollback.sig --approved-at 2026-10-02T12:00:00Z \
+```text
+canon strategy rollback <strategy_id> --reason "<reason>" --actor-id alice \
+  --signature-file rollback.sig --approval-at 2026-10-02T12:00:00Z \
   [--contradicting-trajectory-id <trajectory_id>] --repo .
 ```
 
 `--signature-file` is an armored SSH detached signature over the
 `canon-learning-approval-v1` payload bound to
-`strategy:<id>:rollback:<sha256(reason)>`, actor, and `--approved-at`.
+`strategy:<id>:rollback:<sha256(reason)>`, actor, and `--approval-at`.
 `actor` MUST be listed in policy-pinned `approval.allowed_signers`; verification
 uses that file and `ssh-keygen -Y verify`. Successful rollback writes durable
 provenance, sets lifecycle `rolled_back`, and records the optional contradicting
@@ -203,7 +207,7 @@ not upgrade legacy rows or establish measured uplift.
 
 ## How verdicts feed scoring
 
-Verdicts arrive from `canon ingest artifacts` (see
+Verdicts arrive from `canon ingest records` (see
 `canon-artifact-ingest`), persisted regime-keyed
 (`<role>/<repo>/<area>/<hash>`). Each verdict scores its covering
 trajectory into `Success` / `Failure` / `RolledBack` / `Pending`; 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 gate task`, `canon evidence add --task`,
-`canon dispatch --task`, `canon status` and the brief check — reads it
+`canon ingest plans`, `canon task done`, `canon evidence add --task-id`,
+`canon dispatch begin --task-id`, `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`).
@@ -27,7 +27,7 @@ document and holds the human's `Approved:` line, written by
 skips that directory and the external source keeps the change id.
 
 `plans.sources` lists only EXTERNAL plans — documents you prepare outside
-canon, which canon only reads. The one exception: `canon gate task`
+canon, which canon only reads. The one exception: `canon task done`
 flips the task's checkbox in an external plan's `tasks.md` (see
 `canon-gate`). Their briefs and approvals live in
 `.canon/changes/<change>/brief.md`, never in the external document.
@@ -58,7 +58,7 @@ single ad hoc import, reading only the source it names; either flag alone
 fails loud):
 
 ```bash
-canon ingest plans --dialect openspec --source ../other-repo
+canon ingest plans --dialect openspec --plan-source ../other-repo
 ```
 
 ## 2. Run the import
@@ -78,11 +78,14 @@ the adapter's `unmapped` drop counts, and `malformed` (structurally
 broken constructs). A source whose content is byte-identical to its last
 successful run is `skipped_unchanged` — re-importing writes zero records.
 
+**Done when:** `canon ingest plans` exits `0` with `malformed` and
+`changes_unwritten` at `0` for every source; step 3 lists the imported rows.
+
 ## 3. Read the imported rows
 
 ```bash
-canon query --kind change [--json]
-canon query --kind task [--json]
+canon query --kind change --json
+canon query --kind task --json
 ```
 
 No dialect/plugin filter exists or is needed — an imported `change`/
@@ -181,7 +184,7 @@ downstream reader's job.
   `.canon/changes/<slug>/brief.md` (no `tasks.md`) and adopts the change
   into a subject (see `canon-subject`); it never scaffolds an openspec
   change dir. This skill covers IMPORTING plans.
-- **`canon gate check`/`canon gate task`** (the hand-authored one-task-at-
+- **`canon gate check`/`canon task done`** (the hand-authored one-task-at-
   a-time path this complements at bulk) — see `canon-gate`.
 - **Wiring an imported `Task`/`Change` into a `canon gate` decision** —
   out of scope; needs its own reviewed change.

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

@@ -61,17 +61,21 @@ matching; no field outside envelope ∪ join-key ∪ declared), then writes.
 The on-disk path is derived from the join-key field values in declared
 order plus a body digest — a byte-identical resubmission dedupes to the
 same path; a different body for the same join key appends at a new path,
-never overwriting.
+never overwriting. `--dry-run` validates and reports what would be written
+without writing; an identical rerun writes nothing and reports `unchanged`.
+
+**Done when:** `canon plugin sync <plugin-id>` exits `0` with no validation
+error; the next step (3) reads the overlay back.
 
 ## 3. Project a read
 
 ```bash
-canon query --kind scenario --plugin porting          # human table, projected fields appended
-canon query --kind scenario --plugin porting --json   # merged record bodies
-canon query --kind scenario                           # no --plugin: byte-identical to the core view
+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
 ```
 
-`--plugin <id>` folds the plugin's overlay records (latest-by-
+`--plugin-id <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
@@ -81,9 +85,12 @@ canon query --kind scenario                           # no --plugin: byte-identi
   SKIPPED + diagnosed; siblings still project.
 - An absent plugin/manifest → the unmodified core view + a diagnostic,
   never a process error.
-- Omitting `--plugin` is byte-identical to `canon query`'s output without
+- Omitting `--plugin-id` 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
+scenarios you synced.
+
 ## The `porting` worked example
 
 `porting` moves the `covered`/`surface_ref` fields off the core
@@ -91,7 +98,7 @@ canon query --kind scenario                           # no --plugin: byte-identi
 
 1. `.canon/plugins/porting/plugin.yaml` — the manifest above.
 2. Its overlay source reads a spec root's `inventory/**/*.yaml` (the same
-   inventory files `canon format --check` covers) and, for every
+   inventory files `canon format` covers) and, for every
    `(project_id, scenario_id)` `canon inventory sync` would index, emits
    one candidate: `covered = true` iff that `scenario_id` appears in ANY
    inventory entry's `covered_by` list; `surface_ref` = every inventory-
@@ -101,7 +108,7 @@ canon query --kind scenario                           # no --plugin: byte-identi
    (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 porting [--json]` projects
+4. `canon query --kind scenario --plugin-id 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

@@ -69,15 +69,16 @@ statuses (see `canon-gate`).
 ## Approving the policy
 
 ```bash
-canon policy approve --by <who> [--note <text>] [--repo <dir>]
+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, so the agent does
-not run this command next to it. Run `canon policy approve` alone for a
-policy-only change, as the human, or as the agent right after that answer
-(`canon policy approve --by <the human> --note "<their words>"`). It
+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
 writes `.canon/policy.approval.json` directly (nothing to promote):
 
 ```json
@@ -91,34 +92,37 @@ writes `.canon/policy.approval.json` directly (nothing to promote):
 
 Commit it with the policy: the file is tracked, and neither canon's
 `.gitignore` nor the one `canon init` writes ignores it. Running the
-command again replaces the record. With no `.canon/policy.yaml` it is
-refused (exit `2`), and so is an empty `--by`.
+command again replaces the one approval file (replay-safe). With no
+`.canon/policy.yaml` it is
+refused (exit `2`), and so is an empty `--approver`.
+
+**Done when:** `canon policy show` reports `approval: approved` and
+`canon gate check` no longer prints `policy not approved`.
 
 While a policy exists with no approval, `canon gate check` prints after
 its result:
 
 ```
-advisory: policy not approved: .canon/policy.yaml has no approval record (.canon/policy.approval.json); a human reviews it and runs `canon policy approve --by <who>`
+advisory: policy not approved: .canon/policy.yaml has no approval record (.canon/policy.approval.json); a human reviews it and runs `canon policy approve --approver <who>`
 ```
 
 Once the policy's bytes no longer match the approved digest, or the
 approval file cannot be read, the gate fails closed instead:
 
 ```
-unreviewed-promotion policy — policy changed since approval: .canon/policy.yaml is sha256:<now>, but `<who>` approved sha256:<then> at <time>; … (--override-reason does not waive it); the human re-approves the policy in force with `canon policy approve --by <human> --note "<words>"`, or restore the approved .canon/policy.yaml (and .canon/policy.approval.json) from git
+unreviewed-promotion policy — policy changed since approval: .canon/policy.yaml is sha256:<now>, but `<who>` approved sha256:<then> at <time>; … (--override-reason does not waive it); the human re-approves the policy in force with `canon policy approve --approver <human> --note "<words>"`, or restore the approved .canon/policy.yaml (and .canon/policy.approval.json) from git
 ```
 
-`canon gate check` exits `1`; `canon subject status` (the ship guard and
+`canon gate check` exits `1`; `canon subject move` (the ship guard and
 the reopen) refuses with `POLICY_CHANGED_SINCE_APPROVAL`, or
 `POLICY_APPROVAL_UNREADABLE` for an unreadable approval, and
 `--override-reason` does not waive either. A policy never approved stays
 an advisory. `canon status` prints the same text as a `warning:` line (and
-in `--json` `warnings`). canon cannot tell whether a human or an agent
-ran `policy approve`, so the record names who approved which bytes and
-the gate fails when that no longer holds. An agent never edits the policy
+in `--json` `warnings`). The record names who approved which bytes and
+the gate fails when that no longer holds, whoever ran `policy approve`.
+An agent never edits the policy
 to pass the gate: it stops and asks the human, who re-approves or restores
-it. An agent runs `canon policy approve` only to record a human's answer,
-never without one and never on its own behalf.
+it.
 
 ## `canon policy show [--json]`
 
@@ -251,7 +255,7 @@ read as a big-endian u64, are less than `rate · 2^64` — computed exactly,
 as a comparison against `ceil(rate · 2^64)`, so `rate: 0` samples nothing
 and `rate: 1` samples everything. A sampled in-scope scenario whose
 latest audit is missing or `indeterminate` is `uncovered-cell`; with
-`shipped` in `scope`, `canon subject status <id> --to shipped` also refuses
+`shipped` in `scope`, `canon subject move <id> --to shipped` also refuses
 it. `canon context` and the `canon status` policy line show
 `require_audit=(rate=… seed=`…` scope=…)`.
 

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

@@ -1,7 +1,7 @@
 # canon-report-dashboard
 
-canon's single status surface: `canon report` renders TEN panels to
-markdown, `canon report --snapshot` exports the same ten marts to
+canon's single status surface: `canon report build` renders TEN panels to
+markdown, `canon report snapshot` exports the same ten marts to
 Parquet, and `canon dashboard` serves a small zero-network web app that
 renders SEVEN of them from such a snapshot. Neither surface computes an
 aggregate itself — both read canon's precomputed
@@ -24,24 +24,24 @@ file to those literals. Copy a claim; do not paraphrase it.
 
 `.canon/REPORT.md` carries a leading `<!-- GENERATED by \`canon report\` …
 DO NOT EDIT. -->` comment. If it looks stale or wrong, the fix is
-**always** re-running `canon report` (or fixing the underlying
+**always** re-running `canon report build` (or fixing the underlying
 ledger/policy it renders) — never hand-editing the file. The report
 header embeds only input-derived digests (corpus hash, policy hash,
 ledger-head hash) and **no timestamp, no `source_git_sha`**, so a
 committed report is reproducible from named inputs and `canon report
---check` can byte-diff it deterministically. `source_git_sha` belongs
-only in `--snapshot`'s `manifest.json` (below), which is never
+check` can byte-diff it deterministically. `source_git_sha` belongs
+only in `report snapshot`'s `manifest.json` (below), which is never
 drift-checked.
 
-## `canon report [--repo <dir>]`
+## `canon report build [--repo <dir>]`
 
 Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
 `--repo` resolves through the nearest-`canon.yaml`-ancestor walk every
 subcommand uses — omit it (or pass `.`) to run from any subdirectory.
 
 ```bash
-canon report                 # writes .canon/REPORT.md
-canon report --repo /path/to/repo
+canon report build           # writes .canon/REPORT.md
+canon report build --repo /path/to/repo
 ```
 
 Between the digest header and the first panel, the report may also
@@ -51,26 +51,35 @@ probe, and an empty set renders NO section at all — so a repo routing
 nothing to a not-directly-readable backend renders exactly as before
 the section existed.
 
-## `canon report --check` — the CI drift gate
+**Done when:** `canon report build` exits `0` and `canon report check`
+then exits `0` (no `DRIFT`).
+
+## `canon report check` — the CI drift gate
 
 Regenerates the report in memory and byte-compares it against the
 committed `.canon/REPORT.md`:
 
-- `MISSING` (exit 1) — no report has ever been written; run `canon report` first.
+- `MISSING` (exit 1) — no report has ever been written; run `canon report build` first.
 - no drift (exit 0) — the committed file is byte-identical to what the
   current inputs would render now.
 - `DRIFT` (exit 1) — the committed file disagrees with current inputs
   (hand-edited, or the corpus/policy/ledger moved and nobody re-ran
-  `canon report`).
+  `canon report build`).
 
 ```bash
-canon report --check   # wire into CI exactly like canon format --check / canon gate check
+canon report check   # wire into CI exactly like canon format / canon gate check
 ```
 
 Wire it as a CI step or pre-push hook the same way `canon gate
-install-hooks` wires `canon gate check`; run `canon report --check`
+install-hooks` wires `canon gate check`; run `canon report check`
 directly wherever CI already runs those.
 
+**Done when:** `canon report check` exits `0` in CI on the committed
+`.canon/REPORT.md`; `DRIFT` or `MISSING` means run `canon report build`
+and commit the result.
+
+## `canon report snapshot <dir>`
+
 Exports all ten views to `<dir>/<table>.parquet` plus a
 `<dir>/manifest.json`. One explicit `COPY` per view — the exported
 columns are each view's own `SELECT` list, wider than the curated column
@@ -107,9 +116,11 @@ corpus/policy/ledger digests the report header renders, so a snapshot's
 provenance is comparable to a report's without re-deriving anything.
 
 ```bash
-canon report --snapshot /tmp/canon-snap
+canon report snapshot /tmp/canon-snap
 ```
 
+**Done when:** `<dir>/manifest.json` exists and lists the exported tables.
+
 ## `canon dashboard [--repo <dir>] [--snapshot <dir>] [--port <n>]`
 
 Serves the dashboard web app locally, pointed at a real snapshot:
@@ -119,7 +130,7 @@ canon dashboard                       # regenerates a fresh snapshot every run,
 canon dashboard --snapshot /tmp/canon-snap --port 8080
 ```
 
-- `--snapshot` omitted: `canon dashboard` calls `canon report --snapshot`
+- `--snapshot` omitted: `canon dashboard` calls `canon report snapshot`
   itself every run, into the conventional `.canon/dashboard-snapshot`
   scratch directory — always fresh.
 - `--snapshot <dir>` given: served AS-IS when `<dir>` already has a
@@ -141,11 +152,11 @@ canon dashboard --snapshot /tmp/canon-snap --port 8080
 `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 --change-id
-<id> --by <name> --note <text>` records, the `Approved:` line bound to the
+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_HAS_BLOCKERS`). The server is localhost only and
+has blockers (`BRIEF_APPROVE_REFUSED`). 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,
@@ -220,7 +231,7 @@ computes it; nothing here is derived a second time.
   window down by `EvidenceRecord.verdict`. `divergence_open_running_total` is
   a running `opened - resolved` event count, NOT the number open now —
   the two differ whenever one `resolved` record closes several findings on a
-  scenario. For current state per scenario, run `canon divergence status`.
+  scenario. For current state per scenario, run `canon divergence list`.
 
 - **Scope status** (`mart_scope_status`) —
   Every specified scenario × evidence-verified × plan-carried × spec-covered (`mart_scope_status`). Driven by the spec corpus, so a scenario no plan task declares still appears — with a NULL `task_id`, which is the worklist entry.

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

@@ -4,30 +4,30 @@
 `canon-learn`) at task-dispatch time. It is a fail-soft, advisory-only
 read: it NEVER blocks a dispatch and NEVER gates reproducibility.
 
-## `canon retrieve --role <r> --regime <k> [--k <n>] [--repo <dir>] [--json]`
+## `canon retrieve --for-role <r> --regime <k> [--limit <n>] [--repo <dir>] [--json]`
 
 Prints the top-`k` retrievable strategies stored for `regime_key = <k>`
 (active strategies plus backward-compatible legacy rows without a lifecycle;
 guardrails are just strategies distilled from a failure-polarity verdict),
-newest-distilled first, capped at `--k` (default 5). Demoted,
+newest-distilled first, capped at `--limit` (default 5). Demoted,
 quarantined, rejected, and rolled-back rows are not retrievable.
 
 ```bash
-canon retrieve --role dev --regime dev/canon/join-spine/9c93d024b1a2
-canon retrieve --role dev --regime dev/canon/join-spine/9c93d024b1a2 --k 3 --json
+canon retrieve --for-role dev --regime dev/canon/join-spine/9c93d024b1a2
+canon retrieve --for-role dev --regime dev/canon/join-spine/9c93d024b1a2 --limit 3 --json
 ```
 
 - `--regime` is the FULL `regime_key` string
   (`<role>/<repo>/<area>/<hash>`) — the same serialization the write side
   produces.
-- Assembling `--regime` in a script or hook? Use `canon regime-key
-  --role <r> --repo <r> --area <a> --hash <h>`: it runs canon's ONE
+- Assembling `--regime` in a script or hook? Use `canon regime show
+  --role-segment <r> --repo-name <r> --area <a> --hash <h>`: it runs canon's ONE
   canonical `regime_key` serializer and prints the validated key, so a
   caller routes through the exact normalizer the write path uses instead
   of a drifting shell slug. Exits `2` with empty stdout on a malformed
   result (empty segment / bad `<hash>`) — a clean fail-soft branch for
   `|| exit 0` callers.
-- `--role` MUST equal `--regime`'s leading segment — a mismatch is a
+- `--for-role` MUST equal `--regime`'s leading segment — a mismatch is a
   clean usage error, exit `2` (mirroring `canon gate check`'s
   0-clean/1-red/2-usage convention), never a panic or a silently-ignored
   mismatch.
@@ -36,7 +36,7 @@ canon retrieve --role dev --regime dev/canon/join-spine/9c93d024b1a2 --k 3 --jso
   `canon.yaml` `learn:` section names the store root (`.canon/learn` by
   default); a repo with no `canon.yaml` still works, defaulting cleanly.
 
-**FAIL-SOFT, always exit `0`** once `--role`/`--regime` agree: a store
+**FAIL-SOFT, always exit `0`** once `--for-role`/`--regime` agree: a store
 outage, an empty/nonexistent store, or a malformed on-disk row all
 degrade to an empty guidance list — never a nonzero exit or an error a
 caller must handle.
@@ -46,8 +46,8 @@ caller must handle.
 A generic, fail-soft, advisory-only shell script that fires at a
 PreToolUse-equivalent point for a `task`-shaped dispatch (Claude Code's
 `Task` tool / Codex's equivalent). It reads the tool's `subagent_type`
-as `--role`, assembles `--regime` by routing its repo/area segments
-through `canon regime-key` (so it never re-derives the join key with a
+as `--for-role`, assembles `--regime` by routing its repo/area segments
+through `canon regime show` (so it never re-derives the join key with a
 drifting shell slug), calls `canon retrieve --json`, and emits the
 result as a `PreToolUse` `hookSpecificOutput.additionalContext` JSON
 envelope on stdout — Claude Code's convention for surfacing advisory
@@ -76,6 +76,9 @@ timeout}]}` entry into BOTH `<repo>/.claude/settings.json` and
 `<repo>/.codex/hooks.json`, additive and idempotent — see the
 `canon-gate` skill for `install-hooks`'s full contract.
 
+**Done when:** the hook entry is in both `settings.json` and `hooks.json`;
+running `canon gate install-hooks` again changes nothing.
+
 ## Replay vs. live retrieval
 
 A run manifest records `injected_guidance` — a full SNAPSHOT (each entry