@journeykit/canon 0.27.0 → 0.28.0

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

@@ -5,7 +5,7 @@ that anyone other than the author looked at the work. Canon records that
 second look as two ledger kinds — a **Finding** per issue a reviewer
 raises, and a **Review** per scenario a reviewer signs off — and the
 opt-in `spec_coverage.require_review` policy makes `canon gate check` and
-`canon subject status` hold a subject until both are in order.
+`canon subject move` hold a subject until both are in order.
 
 Both records are attestations: canon never checks a finding's summary
 against the code, or that a reviewer actually read the scenario. What the
@@ -17,7 +17,8 @@ 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>`;
+   --scenario-id <id> --project-id <root-id> --session-id <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
    `write.promote: manual`). See `canon-gate`.
@@ -26,11 +27,11 @@ The order an agent follows to claim a subject done:
 
    ```bash
    canon finding add --change-id c-demo --round 1 --seq 1 \
-     --severity blocker --disposition open --reviewer reviewer-2 \
+     --severity blocker --disposition open --actor-id reviewer-2 \
      --summary "unbounded subprocess wait" --session-id review-session-1
    # ... fix, commit ...
-   canon finding close --change-id c-demo --round 1 --seq 1 \
-     --disposition fixed --resolution-sha "$(git rev-parse HEAD)"
+   canon finding close c-demo --round 1 --seq 1 \
+     --disposition fixed --resolution-rev HEAD
    ```
 
    Under `write.promote: manual` (or no `write:` key), run
@@ -41,23 +42,27 @@ The order an agent follows to claim a subject done:
    the evidence is in (the review pins what it saw):
 
    ```bash
-   canon review add --project-id root --scenario-id world.demo.01 \
-     --reviewer reviewer-2 --actor-id reviewer-2 --role reviewer \
+   canon review scenario world.demo.01 --project-id root \
+     --actor-id reviewer-2 --role reviewer \
      --session-id review-session-1 \
-     --pin "$(git rev-parse HEAD)" --upstream-ref "pr#41"
+     --rev HEAD --upstream-ref "pr#41"
    ```
 
-   `review add` writes directly; there is nothing to promote. If the
+   `review scenario` writes directly; there is nothing to promote. If the
    reviewer could not reach a verdict, record that instead of signing:
-   `--outcome indeterminate` (or `unavailable` when it could not run).
+   `--review-outcome indeterminate` (or `unavailable` when it could not run).
    Changing the scenario or re-attesting it afterwards makes the review
    stale; review it again. A reviewer of user-visible behavior attaches
    the screenshots or recordings it looked at with `--artifact <path>`
    (below).
 
-4. **Move the subject**: `canon subject status <id> --to verifying`, later
+4. **Move the subject**: `canon subject move <id> --to verifying`, later
    `shipped`. See `canon-subject`.
 
+**Done when:** `canon gate check` exits 0 (no `unreviewed-promotion`, no
+`open-blocker`) and `canon status` shows the subject with every scenario
+reviewed and `openBlockers: 0` (`data.subjects[]`).
+
 ## `canon finding add` / `canon finding close`
 
 A Finding's natural key is `(change_id, round, seq)`: the change under
@@ -66,14 +71,14 @@ round. `seq` is never auto-assigned; `finding add` refuses an occupied
 key, because two different findings under one key are two reviewers'
 work collapsed into one identity.
 
-```bash
+```text
 canon finding add --change-id <c> --round <n> --seq <n> \
   --severity blocker|should-fix|note --disposition open \
-  --reviewer <who> --summary "<one line>" \
-  [--reviewed-sha <sha>] [--file-ref path/to/file.rs:120-134] [--scenario-id <id> …] [--actor-id <id>] [--session-id <id>]
-canon finding close --change-id <c> --round <n> --seq <n> \
-  --disposition fixed --resolution-sha <sha> [--session-id <id>]   # or rejected / deferred / open
-canon finding close --change-id <c> --round <n> --seq <n> \
+  --actor-id <who> --summary "<one line>" \
+  [--rev <rev>] [--resolution-rev <rev>] [--introduced-rev <rev>] [--file-ref path/to/file.rs:120-134] [--scenario-id <id>] [--session-id <id>]
+canon finding close <c> --round <n> --seq <n> \
+  --disposition fixed --resolution-rev <rev> [--actor-id <id>] [--session-id <id>]   # or rejected / deferred / open
+canon finding close <c> --round <n> --seq <n> \
   --disposition rejected|deferred --reason "<why, one line>"
 ```
 
@@ -101,24 +106,34 @@ appends a second version at the same natural key — the first stays. Its
 `--actor-id` and `--session-id` name who authored the transition; the
 raiser's stay on the first version.
 
-Every sha flag (`--reviewed-sha`, `--resolution-sha`, `--introduced-by`)
-takes a full 40-character sha or a short one (4 or more lowercase hex
-characters). A short sha is resolved with `git rev-parse --verify
-<sha>^{commit}` in the repo, and the record stores the full sha. It is
-refused (exit `2`) when it names no commit, when more than one commit
-starts with it (pass more characters), when it only resolves by peeling a
-tag, or outside a git work tree.
+Every commit option (`--rev`, `--resolution-rev`, `--introduced-rev`)
+takes any git revision (`HEAD~1`, a branch, a tag, a full or short sha),
+resolved with `git rev-parse --verify <rev>^{commit}`; the record stores
+the full sha. `--rev` (the commit the round reviewed) defaults to `HEAD`,
+and so does `--resolution-rev` on a `fixed` close; `--introduced-rev` has
+no default and is only sourced, never guessed. A revision that names no
+commit is refused (exit `2`). A finding recorded against uncommitted code
+is allowed: the record carries the `codeTree` it saw and `worktreeDirty`.
+Outside git, or in a repository with no commit, the write is refused with
+`NO_COMMIT`.
+
+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
+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`.
 
 ### 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 `--reviewer` and `--actor-id` set to your own id; never ask
+review, with `--actor-id` 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-by` names the commit that introduced the defect, not who
-found it: `--introduced-by self` is a usage error (exit 2) that points at
-`--reviewer`.
+`--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`.
 
 ### Severities
 
@@ -139,7 +154,7 @@ text in the summary, not a field.
 | Disposition | Meaning |
 |---|---|
 | `open` | Raised and not yet dealt with. The default on `finding add`; `finding close --disposition open` reopens. |
-| `fixed` | Fixed by a commit. Requires `--resolution-sha <sha>` naming a commit this repo holds; only `fixed` may carry one. |
+| `fixed` | Fixed by a commit. Carries `--resolution-rev <rev>` (default `HEAD`) naming a commit this repo holds; only `fixed` may carry one. |
 | `rejected` | The reviewer's point was considered and declined. Needs `--reason`. |
 | `deferred` | Accepted, but postponed to later work. Needs `--reason`. |
 
@@ -150,55 +165,68 @@ Every reader takes the **latest version per natural key**
 uses. A blocker raised `open` and later closed `fixed` counts as fixed; a
 fixed finding reopened with `--disposition open` counts as open again.
 
-## `canon review add`
+## `canon review scenario`
 
-```bash
-canon review add --project-id <root-id> --scenario-id <id> [--scenario-id <id>]... \
-  [--scenario-ids-from <file|->] \
-  --reviewer <who> --pin <sha-or-ref> --role <role> \
-  (--upstream-ref <ref> | --original-spec-ref <ref>) [--actor-id <id>] [--session-id <id>] \
-  [--outcome signed|indeterminate|unavailable] \
+```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>] \
+  [--review-outcome signed|indeterminate|unavailable] \
   [--reviewer-provider <p>] [--reviewer-model <m>] [--reviewer-harness <h>] \
-  [--artifact <path>]... [--max-artifact-mib <MiB>]
-canon review add --project-id <root> --change-id <slug> --reviewer <who> --pin <sha-or-ref> \
-  --role reviewer (--upstream-ref <ref> | --original-spec-ref <ref>) …   # a chore, below
+  [--artifact <path>] [--artifact <path>] [--max-artifact-mib <MiB>]
+canon review change <slug> --project-id <root> --actor-id <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` defaults to `canon`; `--session-id` fills `actor.session_id`.
+`--actor-id` is the reviewer and is required; `--session-id` 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 reviewer's `canon divergence
+own (a `Divergent` one passes only while a human's `canon divergence
 accept` holds). It is written directly to the ledger, with no staging step, and says
-so: `canon review add: wrote <path> (new) — written directly; nothing to
+so: `canon review scenario: wrote <path> (new) — written directly; nothing to
 promote`.
 
+`--rev` is the commit the review is about: any git revision, default
+`HEAD`. The review records the full sha and the `codeTree` of the code it
+saw (the tree with `.canon/`, the spec roots and `code.exclude` removed), and
+`worktreeDirty` when that code is uncommitted. Reviewing uncommitted code is
+allowed, and the commit made from it has the same code tree, so committing it
+afterwards leaves the review as it was: a review is judged by its pins (the
+scenario and what its evidence says), not by the commit. Outside git, or
+with no commit, the write is refused with `NO_COMMIT`. An identical review
+written again is `unchanged` (`meta.unchanged` under `--json`) and adds no
+record.
+
+**Done when:** `canon gate check` reports no `unreviewed-promotion` for the
+scenarios you reviewed; a review that does not count shows up there with
+its reason.
+
 ### Several scenarios in one call (0.18)
 
-`--scenario-id` is repeatable, and `--scenario-ids-from <file>` (`-` reads
-stdin) adds one id per line; `#` starts a comment and blank lines are
-skipped. One reviewer, pin, provenance ref and set of artifacts cover
+The scenario operand is repeatable, and an `--input` array (see
+`canon schema review scenario`) batches several calls. One reviewer, pin, provenance ref and set of artifacts cover
 every review; each review pins its own scenario and evidence, and each
 gets its own `pinned` and `wrote` line. The artifacts are stored once.
-It is all or nothing: a scenario with no record, or a line in the file
+It is all or nothing: a scenario with no record, or an operand
 that is not a scenario id, refuses the call (exit 2) and writes no review.
 This is also the batch re-pin after `canon evidence add` reports reviews
 it made stale (see `canon-gate`).
 
-### A chore is reviewed as a change (`--change-id`, 0.23)
+### A chore is reviewed as a change (`review change`, 0.23)
 
 A chore adds no scenarios, and recording the suite again after it leaves
 every scenario review current (a review pins the evidence's verdict and
 checks, so the same verdicts from the same cases change nothing). What the
 chore needs instead is one change-level review: the reviewer signs its
-invariants and checks against the diff with `canon review add --change-id
-<slug> …`, in place of `--scenario-id`. The review pins the chore's brief
+invariants and checks against the diff with `canon review change
+<slug>`, in place of `review scenario`. The review pins the chore's brief
 (its digest, less the `Approved:` line), so an edit to the brief stales it,
 and `--to shipped` refuses a chore with no signed, current change-level
 review (`spec_coverage.require_review.distinct_actor` asks it of a reviewer
-and session that did not attest the subject's evidence). `--change-id` takes a
+and session that did not attest the subject's evidence). `review change` takes a
 chore's slug and refuses a feature change.
 
 ### What the reviewer looked at (artifacts)
@@ -218,8 +246,8 @@ review records each distinct file once, in the order given:
 "artifacts": [{"path": "reports/title.png", "sha256": "<64 hex>"}]
 ```
 
-The field is absent when no `--artifact` is given. `review add` prints
-`canon review add: artifact store holds <n> bound file(s) under
+The field is absent when no `--artifact` is given. `review scenario` prints
+`canon review scenario: artifact store holds <n> bound file(s) under
 .canon/artifacts/sha256/ (<k> newly stored) — commit them with the
 ledger`.
 
@@ -227,13 +255,13 @@ ledger`.
 review (the latest per `(project_id, scenario_id, reviewer)`, unless it
 went stale against its scenario) by the evidence rule (see `canon-gate`,
 "Bound evidence stays provable"). A missing blob whose working-tree file
-still matches is an advisory naming `canon evidence vault`, which stores
+still matches is an advisory naming `canon artifacts store`, which stores
 it back. A missing blob with a changed or missing working-tree file, or
 an altered blob, is `stale-evidence` on the review's scenario, naming
 the review:
 
 ```
-stale-evidence world.demo.01 — review by `reviewer-2` (actor `reviewer-2`, 2026-10-11T09:00:00Z) bound file `reports/title.png` recorded sha256 <hex>; stored blob .canon/artifacts/sha256/<hex>: missing; working tree: <other hex> — the bound bytes are gone, look again and re-record the review with `canon review add --artifact <path>`
+stale-evidence world.demo.01 — review by `reviewer-2` (actor `reviewer-2`, 2026-10-11T09:00:00Z) bound file `reports/title.png` recorded sha256 <hex>; stored blob .canon/artifacts/sha256/<hex>: missing; working tree: <other hex> — the bound bytes are gone, look again and re-record the review with `canon review scenario <scenario-id> --artifact <path>`
 ```
 
 The reviewer's later review replaces the earlier one, so its files are
@@ -245,7 +273,7 @@ screenshot shows.
 
 ### What the review saw (pins)
 
-`review add` reads the corpus and records `pins` on the review; the
+`review scenario` reads the corpus and records `pins` on the review; the
 reviewer never types them:
 
 - `scenario_digest` — the scenario record's `scenario_digest`: a sha256
@@ -268,7 +296,7 @@ reviewer never types them:
   verdict from the same checks again leaves the review current. A scenario
   with no evidence yet is pinned with an empty list.
 
-It prints `canon review add: pinned <id> at scenario digest <12 hex> and the
+It prints `canon review scenario: pinned <id> at scenario digest <12 hex> and the
 verdict and checks of its <n> role(s) of evidence; …` (`at source digest` for
 a file pin). A
 scenario with no record (never synced) is refused with exit 2 and nothing
@@ -284,15 +312,15 @@ final.
 
 ### The reviewer's outcome and runtime
 
-`--outcome` records how the reviewer's run ended: `signed` (the default:
+`--review-outcome` records how the reviewer's run ended: `signed` (the default:
 an approval), `indeterminate` (it ran and reached no verdict) or
 `unavailable` (it could not run). Only `signed` counts; the other two
 are recorded so a failed review is visible, never mistaken for a
-sign-off or a rejection, and `review add` says so. `--reviewer-provider`,
+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 add`, `finding add` and
+`--session-id` (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.
@@ -361,8 +389,8 @@ A review written before 0.23 pins something the gate no longer compares: a
 count until `canon migrate` rewrites it to what the evidence says (see
 `canon-gate`). A review that was current under the rule it was written under
 becomes a current review; one that was stale stays stale, and its scenario
-needs a new `canon review add`, which pins what it saw and replaces the
-reviewer's earlier one. The gate, `canon status` and `canon subject status`
+needs a new `canon review scenario`, which pins what it saw and replaces the
+reviewer's earlier one. The gate, `canon status` and `canon subject move`
 print one advisory naming how many scenarios are waiting for `canon
 migrate`. In CI, check out full history (`fetch-depth: 0`) for the job that
 runs `canon migrate`, or a pre-0.15 review whose commit is missing is pinned
@@ -376,7 +404,7 @@ counting: a current signed review failing only `distinct_actor`, then a
 stale review, then non-signed outcomes.
 
 ```
-unreviewed-promotion world.demo.01 — no review record for this scenario; spec_coverage.require_review wants an independent review (`canon review add`) once its subject is claimed done
+unreviewed-promotion world.demo.01 — no review record for this scenario; spec_coverage.require_review wants an independent review (`canon review scenario`) once its subject is claimed done
 ```
 
 or, when the only reviews are self-reviews:
@@ -397,13 +425,13 @@ review (`its spec changed`, `its evidence changed`, `its spec and its
 evidence changed`):
 
 ```
-unreviewed-promotion world.demo.01 — stale review by `reviewer-2`: its evidence changed (the latest evidence records are not the pinned ones) since the review; a pinned review counts only while what it saw is current — review it again (`canon review add`)
+unreviewed-promotion world.demo.01 — stale review by `reviewer-2`: its evidence changed (the latest evidence records are not the pinned ones) since the review; a pinned review counts only while what it saw is current — review it again (`canon review scenario`)
 ```
 
 or, when every latest review recorded no sign-off:
 
 ```
-unreviewed-promotion world.demo.01 — no signed review: the latest review recorded no sign-off (`reviewer-2` indeterminate); an indeterminate or unavailable review is a gap, never an approval — run the review again and record `--outcome signed`
+unreviewed-promotion world.demo.01 — no signed review: the latest review recorded no sign-off (`reviewer-2` indeterminate); an indeterminate or unavailable review is a gap, never an approval — run the review again and record `--review-outcome signed`
 ```
 
 A non-signed review is a gap even without `distinct_actor`.
@@ -416,7 +444,7 @@ subject's `change_ids` (`canon subject adopt`). The subject string is
 `<change_id>#<round>.<seq>`:
 
 ```
-open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close --disposition fixed --resolution-sha <sha>`, or close it as rejected or deferred
+open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close <change> --round <n> --seq <n> --disposition fixed`, or close it as rejected or deferred
 ```
 
 Findings on changes no in-scope subject has adopted do not block.
@@ -435,11 +463,11 @@ review waivers: 1 advisory(ies) — not failing the gate:
 
 ## The status guard
 
-With `require_review` present, `canon subject status <id> --to <state>`
+With `require_review` present, `canon subject move <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
-```
-canon subject status: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
+```stderr
+canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
   ran unreviewed-promotion — every owned scenario needs a signed review, current with the spec and evidence it pinned, by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```

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

@@ -15,7 +15,7 @@ no live database. Swap `hot` to postgres (the commented stanza `canon
 init` ships beside the sqlite one) once team-scale multi-agent
 concurrency outgrows sqlite's single-writer mode.
 
-## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--canon-yaml <path>] [--full] [--all-workspaces]`
+## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--full] [--all-workspaces]`
 
 ```bash
 canon ingest sessions                   # one pass over this project's sources
@@ -25,6 +25,10 @@ canon ingest sessions --all-workspaces  # machine-wide scan
 canon ingest sessions --home /custom    # override the scan-root home ($HOME)
 ```
 
+**Done when:** the run summary (below) ends with `malformed records … : 0`
+and `canon query --kind session` lists the sessions; a rerun reports the
+files as `skipped unchanged (watermark)` and writes nothing.
+
 ## The four adapters
 
 Registered in order: **`omp`** (omp/pi sessions), **`hermes`**,
@@ -179,7 +183,7 @@ canon query --kind event   # filter detail.label == "user_directive"
 Each pass prints the active scope, one line per adapter, then totals:
 
 ```
-scope: project /Users/me/Workspace/canon (2 roots)
+scope: project /path/to/repo (2 roots)
 omp: 3 file(s) scanned, 1 reparsed, 2 skipped unchanged (watermark), 4 row(s) parsed, 0 malformed record(s)
 claude-code: 1 file(s) scanned, 0 reparsed, 1 skipped unchanged (watermark), 0 row(s) parsed, 0 malformed record(s)
 sessions normalized: 4
@@ -208,7 +212,7 @@ events written: 37
 
 ## What this skill does NOT cover
 
-- Artifact/verdict ingestion (`canon ingest artifacts`) — a different
+- Artifact/verdict ingestion (`canon ingest records`) — a different
   pipeline; see the `canon-artifact-ingest` skill.
 - Cost-parity computation — omp/pi's own cost is `0.0`/`Unknown` per the
   ported behavior.

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

@@ -79,18 +79,22 @@ re-selects the record but the destination write is a no-op. A kind
 split across two rungs (some aged, some not) still reads correctly —
 `canon query` fans out.
 
+**Done when:** after `canon tier age --commit --plan-digest <digest from the
+preview>`, a bare `canon tier age` previews no effect (`moved` is `0`).
+
 ## Running `canon tier age` / `canon query`
 
-Both take `--canon-yaml <path>` (default `canon.yaml` in the current
-directory).
+Both read the `canon.yaml` of `--repo <dir>` (default: the nearest ancestor
+directory holding one).
 
 ```bash
-# Preview what would move (read-only; writes/deletes nothing).
-canon tier age --dry-run
-
-# Apply every `aging:` rule once (the destructive move+delete).
+# Preview what would move (the bare run is read-only; writes/deletes nothing).
 canon tier age
 
+# Apply every `aging:` rule once (the destructive move+delete), with the
+# `planDigest` the preview printed.
+canon tier age --commit --plan-digest "$PLAN_DIGEST"
+
 # Read a kind, fanning out across its routed rung AND its aging
 # destination, merged by time. --kind is the kind wire string — the
 # same vocabulary as routing:/aging: (`change`, `handoff`, …).
@@ -116,8 +120,8 @@ read the ledger only.
 
 ```bash
 canon query --kind evidence --history   # every version, archive included
-canon ledger compact --dry-run                 # report; writes nothing
-canon ledger compact                           # pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
+canon ledger compact                           # preview; writes nothing
+canon ledger compact --commit --plan-digest "$PLAN_DIGEST"   # pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
 ```
 
 A crash between the write and the move leaves a readable ledger that the next
@@ -125,6 +129,9 @@ append or `canon ledger compact` finishes. The archive is local, not routed
 through `tiers:`; a `tiers.local.root` whose directory is not named `ledger`
 has no archive and keeps every version.
 
+**Done when:** after `canon ledger compact --commit --plan-digest <digest
+from the preview>`, a bare `canon ledger compact` previews no effect.
+
 ## Where artifact bytes live (`artifact_store:`)
 
 ```yaml
@@ -133,40 +140,40 @@ artifact_store: { backend: local }                  # default
 ```
 
 `local` is `.canon/artifacts/sha256/`, git-tracked and credential-free. An
-object-store tier gets `evidence add`, `review add` and `evidence vault`
+object-store tier gets `evidence add`, `review scenario` and `artifacts store`
 uploads under `<prefix>sha256/<digest>` and keeps nothing locally. The gate
 and `canon artifacts verify [--full]` ask the store and refuse, never pass,
-when it cannot be reached. `canon artifacts migrate --to <tier> [--dry-run]`
+when it cannot be reached. `canon artifacts move --tier <tier>` (a preview; `--commit --plan-digest <digest>` acts)
 uploads, reads back and verifies every local blob, then writes the
 `artifact_store:` block, removes the local copies and ignores
 `.canon/artifacts/`; commit the removals, `.gitignore` and `canon.yaml`. It is
 resumable and a second run finds nothing to do.
 
-## What `canon report` does and doesn't read
+## What `canon report build` does and doesn't read
 
-canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report`
+canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report build`
 builds its numbers from the `mart_` views. Those read ONLY local roots
 — the git ledger, the sqlite `hot` db file (local, no credential; read
-since 0.18) and a LOCAL `.canon/r2` parquet mirror. `canon report`
+since 0.18) and a LOCAL `.canon/r2` parquet mirror. `canon report build`
 never opens a live DB connection or the live bucket, so:
 
-- Kinds routed to a postgres `hot` rung do NOT appear in `canon
-  report`; kinds routed to `canon init`'s default sqlite `hot` rung do.
+- Kinds routed to a postgres `hot` rung do NOT appear in `canon report
+  build`; kinds routed to `canon init`'s default sqlite `hot` rung do.
 - Kinds routed to `cold` (s3) appear only if a local `.canon/r2` mirror
   has been separately materialized — there is no automatic sync.
 
 These kinds are not lost: read them with `canon query --kind <kind>`.
 The gap is named loud, not under-counted — when any routed kind isn't
-report-readable, `canon report` renders a `## Kinds not read directly`
+report-readable, `canon report build` renders a `## Kinds not read directly`
 section listing them and emits a matching stderr `WARN`.
 
 ## Retention, export, and access audit
 
-`canon purge --kind <kind> --before <RFC3339> (--plan | --confirm <planDigest>) [--repo <dir>] [--json]`
-is the canonical data-lifecycle boundary: `--plan` prints the removal set and
-its `planDigest` and deletes nothing; `--confirm <planDigest>` deletes only if
+`canon purge --kind <kind> --before <RFC3339> [--commit --plan-digest <planDigest>] [--repo <dir>] [--json]`
+is the canonical data-lifecycle boundary: the bare run previews: it prints the removal set and
+its `planDigest` and deletes nothing; `--commit --plan-digest <planDigest>` deletes only if
 the plan recomputed now has the same digest (`PLAN_CHANGED`, exit 2, when the
-data moved), and a bare `purge` is refused (`PURGE_PLAN_REQUIRED`). The only purgeable kinds are
+data moved). The only purgeable kinds are
 `session`, `run`, `event`, and `trajectory`; the cutoff applies to every
 routed rung and every configured aging destination, including retained
 historical versions. For `trajectory`, the command also purges the
@@ -179,14 +186,19 @@ an explicit `partial` result with matched/deleted counts and a nonzero
 status. Purge never rewrites Git history or deletes source transcript
 files.
 
+**Done when:** after `canon purge --kind <kind> --before <time> --commit
+--plan-digest <digest from the preview>`, a bare `canon purge` with the same
+arguments previews an empty removal set.
+
 With `--json`, `purge` and `export` answer `{ "data", "meta" }` like every other
 command: `data` is the plan or manifest, `meta.next` the step after (a plan's is the
-human's review and `--confirm`), and an export's page state (`total`, `returned`,
-`nextCursor`) sits in `meta`. `export --json --out <file>` writes the manifest to the
-file and answers with `data: { out, kind, recordCount }`.
+human's review and `--commit --plan-digest`), and an export's page state (`total`, `returned`,
+`nextCursor`) sits in `meta`. `export --json --output <file>` writes the manifest to the
+file and answers with `data: { output, kind, recordCount }`; `--dry-run`
+answers with what it would write and writes nothing.
 
 `canon export --kind <kind> [--before <RFC3339>] [--after <RFC3339>]
-[--out <file>] [--json] [--limit <n> | --all] [--cursor <c>]` emits a versioned manifest containing source scope,
+[--output <file>] [--json] [--limit <n> | --all] [--cursor <c>]` emits a versioned manifest containing source scope,
 counts, digests, and redacted metadata. It does not authorize backend access;
 credentials remain an operator prerequisite. New output files are mode
 `0600`. Raw event detail text is excluded unless `--include-sensitive` is
@@ -199,7 +211,7 @@ query:
 
 Every query, export, and purge appends an actor-stamped record to
 `.canon/audit/access.jsonl` (mode `0600` on creation) in the repository
-whose `canon.yaml` it read (through `--repo` or `--canon-yaml`), never in
+whose `canon.yaml` it read (through `--repo`), never in
 the current directory; with no `canon.yaml` there is no audit and nothing
 is written. The log is local operator state: `canon init` keeps
 `.canon/audit/` out of git (below). `CANON_ACTOR` takes
@@ -212,7 +224,7 @@ record bodies.
 Four writes stage their record instead of committing it: `canon evidence
 add`, `canon finding add`, `canon finding close` and `canon divergence add`
 (under `.canon/ledger/_staging/`, one staging shape for every kind,
-committed by `canon gate promote`; `canon divergence promote` commits only
+committed by `canon gate promote`; `canon gate promote --kind divergence` commits only
 the staged divergences). `canon divergence resolve|defer|accept` stage and
 promote their own record in the same run. `canon.yaml`'s
 `write:` section decides whether they promote in the same run:
@@ -240,7 +252,7 @@ line ends ``— run `canon gate promote` to commit it`` (`canon divergence
 promote` 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-config` reports `[PASS] write (promote: auto)`, `[not configured]
+--check` reports `[PASS] write (promote: auto)`, `[not configured]
 write (promote: manual)`, or `[FAIL] write: …`. `canon gate promote` still
 works under `auto` and is idempotent: with nothing staged it prints
 `nothing staged` and exits `0`.
@@ -264,7 +276,7 @@ install|check|doctor` follow the section; `install` prunes projected files the b
 --providers=<list>` rewrites it in place. Without the section they use the
 install lock's providers, then the detected ones; nothing undetected is ever
 added. A present section that is not this shape, or names another harness,
-fails those commands (exit `1`), and `canon init --check-config` reports
+fails those commands (exit `1`), and `canon init --check` reports
 `[PASS] skills (providers: …)`, `[not configured] skills (…)`, or
 `[FAIL] skills: …`.
 
@@ -278,13 +290,13 @@ or one whose recorded source digest differs from the file's current bytes,
 or when the index holds a scenario of a spec root that no `.feature` file
 of it declares any more.
 
-The commands that write records (`canon subject status`, `canon review
-add` and `canon evidence add`) rebuild a stale index on disk first: they
+The commands that write records (`canon subject move`, `canon review
+scenario`, `canon evidence add` and `canon artifacts store`) rebuild a stale index on disk first: they
 run `canon inventory sync`'s code on the changed files (validation still
 covers the whole root) and print one stderr line:
 
-```
-canon evidence add: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
+```stderr
+canon artifacts store: refreshed the scenario index from 1 changed feature file(s) (.canon/specs/kind=feature/area=cart/add.feature): 1 record(s) written
 ```
 
 The commands that only read (`canon gate check`, `canon status`) write
@@ -299,8 +311,8 @@ the report panels then treat it as absent; re-adding the scenario writes
 a live generation that supersedes the tombstone. A root that fails to
 sync writes no tombstone either.
 
-```
-canon evidence add: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
+```stderr
+canon artifacts store: refreshed the scenario index from 1 scenario(s) no longer in any feature file (cart.pay.01): 1 record(s) written
 ```
 
 `canon inventory sync` and every refresh hold an OS file lock on
@@ -317,8 +329,8 @@ still runs; `canon gate check` then fails with `uncovered-cell <root>`,
 the `verifying → shipped` guard refuses, and `canon status` lists only
 `canon inventory sync`:
 
-```
-canon evidence add: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
+```stderr
+canon artifacts store: found the scenario index stale for 1 changed feature file(s) (…): 0 record(s) written; NOT refreshed: root `root` (2 format violation(s), 0 sync error(s)) — `canon inventory sync` lists them
 ```
 
 Nothing is written in a directory without `canon.yaml`. `canon inventory
@@ -328,7 +340,7 @@ tag diagnostics.
 ## The artifact store lock
 
 Every write to the evidence artifact store (`.canon/artifacts/sha256/`:
-`canon evidence add`, `canon review add`, `canon evidence vault`) holds an
+`canon evidence add`, `canon review scenario`, `canon artifacts store`) holds an
 OS file lock on `.canon/artifact-store.lock` from its "already stored?"
 check through its last rename, so a write that fails and rolls back never
 removes a blob another writer published or counted as stored. A rollback
@@ -355,9 +367,23 @@ comment, only the missing ones):
 - `.canon/dashboard-snapshot/` — the snapshot `canon dashboard`
   regenerates on every run.
 - `.canon/learn/` and `.canon/r2/` — local learn scratch and the local
-  object-store stand-in `canon report` writes.
+  object-store stand-in `canon report build` writes.
 
 A rerun on a repo that already has `canon.yaml` only refreshes
 `AGENTS.md`; `canon migrate` adds the lines an existing `.gitignore`
-lacks, and `canon skills doctor` and `canon init --check-config` name a
+lacks, and `canon skills doctor` and `canon init --check` name a
 missing one.
+
+## Upgrading a 0.27 repository
+
+`canon status`, `canon gate check` and `canon context` warn on a repo that
+still holds 0.27 canon state and put `canon migrate --json` first in
+`meta.next`. `canon migrate` is destructive-class: the bare run is a
+preview (a report with `planDigest` and `effects[]`, exit 0, nothing
+written); `canon migrate --commit --plan-digest <digest from the preview>`
+acts, and only when the plan recomputed now has the same digest. Afterwards
+run `canon skills install`, which writes the stub guide; the guide itself is
+read with `canon skills show canon`.
+
+**Done when:** `canon status` no longer warns about 0.27 state and
+`canon migrate --json` is no longer the first step in `meta.next`.