@journeykit/canon 0.33.0 → 0.35.0

package/dist/skills/SKILL.src.md

@@ -210,22 +210,36 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
 - Your role guide's **Commands** block (`canon skills show role-<role>`) is
   your complete command set, every option of every leaf included. Run `canon schema <command> --json` only for a
   command it does not list, or after a `USAGE` refusal (read `error.field`
-  and `error.expected` first). `canon schema` alone lists every command.
+  and `error.expected` first). `canon schema --json` is the tree of every group and command
+  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it); `canon schema <group> --json` lists a group's
+  commands; `canon schema <command> --json` is one command in full: `options` (each with
+  `valueType`, a typed `default`, `possibleValues`, `env`, `flagOnly`), `errors`, `outputs`
+  with the JSON Schema of each report in `schemas`, `input` (the schema of one `--input`
+  document and a complete `example`) and `examples`. The first line of every `--help`
+  points at it.
 - Pass `--json` and read stdout as one document, nothing on stderr. Success is
   `{"ok":true,"data":…,"meta":…}`; failure is
   `{"ok":false,"error":{…},"meta":…}` (a check that fails keeps its report in
-  `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`), `schemaVersion`,
+  `data`). `meta` carries `tool`, `toolVersion`, `contract` (`atip/1`),
+  `contractVersion` (`1.2`), `schemaVersion`,
   `command`, and when present `next`, `warnings` (`[{code, message}]`) and
   `page`; a repeated write that changed nothing reports `data.unchanged: true`.
-  Absent members are omitted, never `null` or `[]`. A paged list puts
-  `meta.page.nextCursor` on the call's `meta.next` as `--cursor <nextCursor>`;
-  no `nextCursor` means no more.
-  On failure branch on `error.code`, fix the option `error.field` names
+  Absent members are omitted, never `null` or `[]` (a value you sent empty comes back as `received: ""`).
+  Read the members you know and ignore the ones you do not: a later canon
+  adds members, and a value of a closed set you have not seen (a `severity`, an
+  `outcome`, a `reason`) is one item to leave out, never a reason to reject the document. A paged list puts
+  `meta.page.nextCursor` in the first entry of the call's `meta.next` as `--cursor=<nextCursor>`
+  (run that entry as it is); no `nextCursor` means no more.
+  On failure branch on `error.code`, and on `error.reason` where the code has
+  reasons (`INPUT_INVALID` says `NOT_JSON`, `UNKNOWN_KEY`, `STDIN_TTY`, … so you
+  know whether to fix the JSON or the shell); fix the option `error.field` names
   using the `error.expected` values (`field` is an option name, or a JSON
-  pointer such as `/items/2/scenario` into an `--input` document), and
-  follow `error.hint`: every refusal carries a working invocation. The codes
-  are stable; `canon schema --errors --json` lists them and
-  `canon schema --error <CODE>` explains one.
+  pointer such as `/2/scenario` into an `--input` document, `/<index>/<key>` in a batch), and
+  follow `error.hint`: it is one runnable command line that starts with `canon`, the
+  same with `<PLACEHOLDER>`s you fill in, or one sentence. The codes
+  are stable; `canon schema --errors --json` lists them with their reasons and
+  `canon schema --error <CODE>` explains one. A warning code (`meta.warnings`) is in
+  `canon schema --warnings --json`; `canon schema --warning <CODE>` explains one.
 - **Exit codes:** only 0, 1 and 2 exist: 0 ok; 1 the command ran and its answer
   is negative or incomplete (a failed check, a violation, `unverifiable` when
   nothing was examined, a partly failed batch); 2 refused to run (usage,
@@ -244,8 +258,8 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   has blockers; the approval step appears only when the brief is clean and
   unapproved.
 - Page long lists with `--limit <n>` and `--cursor <nextCursor>` (`--all`
-  for everything), and project fields with `--fields a,b` (`status`, `export`,
-  `query`, `finding list`, `divergence list`, `context`).
+  for everything); a cursor holds only for the call that issued it, so change nothing but `--limit`, `--all`, `--fields` and `--json`, and keep `CANON_ROLE` as it was (`CURSOR_INVALID` with `error.reason` `ARGUMENTS_CHANGED` otherwise; `FOREIGN` for a cursor of another command or another canon version: start again from the first page). `--limit`, `--cursor`, `--all` and `--fields` are flags: an `--input` document key of that name is `INPUT_INVALID` with `reason` `FLAG_ONLY_KEY`. Project fields with `--fields a,b`
+  (`status`, `export`, `query`, `finding list`, `divergence list`, `context`): the paths `canon schema <command> --json` lists under `outputs[].fields`, spelled as the answer spells them; `meta.fields` lists what was kept.
 - `--override-reason <text>` is the only way to proceed past a waivable
   refusal; it is recorded, echoed in `data.overrides[]` and listed by `status`
   for the human. There is no `--force`. `brief approve`, `policy approve`,
@@ -263,11 +277,12 @@ the positional arguments. An object is one invocation; a JSON array (or NDJSON
 from a file or stdin) is a batch, run in order and answered with
 `data.items[]` (`index`, `status` of `written`, `unchanged`, `failed` or
 `skipped`, and that element's `data` or `error`). A batch is validated whole
-before anything is written: an invalid element writes nothing and exits 2,
-`error.field` pointing at `/items/<i>/<key>`; a write that fails stops there
-(exit 1, `BATCH_INCOMPLETE`) and re-running the same batch reports the finished elements
-`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped.
-`canon schema <command> --json` shows the leaf's input schema and an example.
+before anything is written, and that check reads no state: an invalid element writes nothing and exits 2 with
+its own code, `error.field` pointing at `/<i>/<key>` and no `data`. An element that fails when it runs (the object
+it names does not exist) stops the batch: exit 1, `BATCH_INCOMPLETE`, `error.field` exactly `/<i>`, the element
+`failed` with its own `error` (no `data`), the later ones `skipped`, and the earlier ones done (not undone). Re-running the same batch reports the finished elements
+`unchanged`. A typo in a key is refused (`INPUT_INVALID`, `field` naming the key), never dropped; a document with several problems reports them all, the first as the error and every one in `error.details` in the order the document wrote its keys, and a value outside a closed set is `INPUT_INVALID` too (`reason` `INVALID_VALUE`, `field` the key), not `USAGE`. Every non-empty line of an NDJSON file is a document (a `#` line is not a comment). Integers compare by number: `1`, `"1"` and `--round +1` are one value, and `"+1"`, `"0x1"` and `1.0` in a document are `INVALID_VALUE`.
+`canon schema <command> --json` shows the leaf's `input`: the schema of one document and a complete `example`.
 
 ```text
 canon scenario new --input '[{"operands":["auth.login.01"],"title":"Logs in","case":"happy"},{"operands":["auth.login.02"],"title":"Wrong password","case":"failure"}]'
@@ -315,12 +330,18 @@ and `canon context` warn when the repo holds 0.27-era state and put
 ## Setup and provider projection
 
 ```bash
-canon init                                   # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
-canon init --providers=claude,codex          # harnesses for the canon skill; without it init asks on a terminal, else takes the detected .claude/.codex/.omp/.pi
-canon skills install                         # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
-canon skills install --providers=claude,codex,omp,pi   # any subset or none; rewrites skills.providers
-canon skills check                           # read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
-canon skills doctor                          # diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+# canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
+canon init
+# harnesses for the canon skill; without it init takes the detected .claude/.codex/.omp/.pi (it never asks)
+canon init --providers=claude,codex
+# follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
+canon skills install
+# any subset or none; rewrites skills.providers
+canon skills install --providers=claude,codex,omp,pi
+# read-only drift check; exit 1 (SKILLS_DRIFT) names each orphan, a projected file the bundle no longer ships
+canon skills check
+# diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+canon skills doctor
 ```
 
 `install` writes, per selected harness, a short `SKILL.md` stub (this file's

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

@@ -9,9 +9,12 @@ verdicts, and writes idempotently.
 ## `canon ingest records [--repo <dir>] [--watch]`
 
 ```bash
-canon ingest records                # one pass over the repo's artifacts
-canon ingest records --repo ../svc  # a specific repo
-canon ingest records --watch        # poll loop
+# one pass over the repo's artifacts
+canon ingest records
+# a specific repo
+canon ingest records --repo ../svc
+# poll loop
+canon ingest records --watch
 ```
 
 Source roots resolve from `canon.yaml`'s `artifacts.sources` config

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

@@ -92,11 +92,14 @@ a scoped gate.
 ## The commands — and the one thing you never type
 
 ```bash
-canon feature new checkout.cart --title "Cart"                       # once per surface
+# once per surface
+canon feature new checkout.cart --title "Cart"
+# once per behavior
 canon scenario new checkout.cart.01 --title "Adding an item raises the count" \
-  --subject checkout-core --lane behavior --case happy               # once per behavior
+  --subject checkout-core --lane behavior --case happy
+# and its failure path
 canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refused" \
-  --subject checkout-core --lane behavior --case failure             # and its failure path
+  --subject checkout-core --lane behavior --case failure
 ```
 
 There is no format or sync step after these: the scaffold writes a
@@ -111,8 +114,8 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 Many scenarios at once: `--input` takes inline JSON, a file or `-`. An
 array (or NDJSON) is a batch, validated whole before anything is written;
 each element holds `operands` (the scenario tag) and the other options as
-camelCase keys. `canon schema scenario new --json` shows the input schema
-and an example. There is no `--from`.
+camelCase keys. `canon schema scenario new --json` shows `input`: the schema of one document
+and a complete `example`. There is no `--from`.
 
 ```text
 canon scenario new --input '[{"operands":["checkout.cart.01"],"title":"Adding an item raises the count","subject":"checkout-core","lane":"behavior","case":"happy"},{"operands":["checkout.cart.04"],"title":"Adding an out-of-stock item is refused","subject":"checkout-core","lane":"behavior","case":"failure"}]'

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

@@ -13,9 +13,12 @@ deterministic authoring surface.
 ## `canon context [--repo <dir>] [--json]`
 
 ```bash
-canon context                 # compact human outline (prompt-injectable)
-canon context --json          # the full machine-readable surface
-canon context --repo ../other # resolve a specific repo's surface
+# compact human outline (prompt-injectable)
+canon context
+# the full machine-readable surface
+canon context --json
+# resolve a specific repo's surface
+canon context --repo ../other
 ```
 
 The outline opens with a short header, then a blank line, then the
@@ -34,8 +37,8 @@ authored; `canon status` (see `canon-subject`) says where the repo stands
 and what to run next. `--json` prints the `{ok, data, meta}` envelope: the
 header adds no field, and `policy.spec_coverage`/`policy.diagnostics`
 already carry the same fact. `--fields <list>` keeps only the named
-top-level fields (`kinds`, `enums`, `policy`, `review`, …); an unknown name is
-`USAGE` (exit 2; `field` is `--fields`, `expected` lists the selectable fields).
+top-level fields (`kinds`, `enums`, `policy`, `review`, …), spelled as the report spells them; an unknown name is
+`USAGE` (exit 2; `field` is `--fields`, `expected` lists the selectable fields), and `meta.fields` lists the kept ones.
 
 On a repository that still holds 0.27 canon state, `canon context` warns
 and puts `canon migrate --json` first in `meta.next`: run `canon migrate`

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

@@ -9,7 +9,8 @@ rewrites or mutates the corpus — it only validates and reports.
 ## Running
 
 ```bash
-canon format spec   # e.g. a consumer repo's spec/
+# e.g. a consumer repo's spec/
+canon format spec
 ```
 
 With no operand, `canon format` validates every `specs.roots[]` entry of

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

@@ -42,8 +42,10 @@ corpus and runs them, printing every violation grouped by failure class.
 when `--release` is passed.
 
 ```bash
-canon gate check --repo .            # ordinary evaluation
-canon gate check --repo . --release  # + trust-below-required
+# ordinary evaluation
+canon gate check --repo .
+# + trust-below-required
+canon gate check --repo . --release
 ```
 
 Exit `0` clean, `1` gate-red (any violation), `2` usage/load failure
@@ -314,8 +316,8 @@ check `canon status` and the ship guard use; see
 `--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 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
+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>"`
+stderr: 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
@@ -534,7 +536,7 @@ or `-`; an array (or NDJSON) is a batch, validated element by element before
 the first write (a refusal writes nothing, exit 2). Keys are the option
 names in camelCase plus `operands`: one object per scenario, with
 `scenario`, `class`, `ref` and `role`. `canon schema evidence add --json`
-shows the input schema and an example. Each element reports `written`,
+shows `input`: the schema of one document and a complete `example`. Each element reports `written`,
 `unchanged` or `failed` in `data.items[]`.
 
 `--rev <rev>` names the commit the evidence ran against (default `HEAD`).
@@ -553,7 +555,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 root --actor reviewer-2 --role reviewer --original-spec-ref specs/kind=feature/area=cart/add.feature
+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 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
@@ -737,8 +739,10 @@ prints the plan (target path + assigned `run_seq` per candidate) without
 writing or deleting.
 
 ```bash
-canon gate promote --repo .            # land every staged candidate
-canon gate promote --repo . --dry-run  # preview only
+# land every staged candidate
+canon gate promote --repo .
+# preview only
+canon gate promote --repo . --dry-run
 ```
 
 Which writes need this step: `evidence add`, `finding add` and `finding

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

@@ -14,7 +14,7 @@ same code this command runs, scoped to the changed files, and say so in one
 stderr line:
 
 ```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
+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
 ```
 
 `canon status` and `canon gate check` are read commands and write nothing:
@@ -76,14 +76,14 @@ author .feature corpus (canon scenario new)
 scenario index                  # refreshed by the writers; `canon inventory sync` rebuilds it
         │
         ▼
-canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
-canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
-canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
+review:   canon review scenario           # attests a review — see canon-inventory downstream / canon-gate
+diverge:  canon divergence add|resolve|defer|accept|list   # tracks/resolves a divergence
+gate:     canon gate check [--release]    # trust-ladder / staleness / coverage — see canon-gate
         │
         ▼
-canon ingest records            # with artifacts.native_records: true in canon.yaml —
-                                # feeds review/divergence verdicts into the flywheel
-                                # (see canon-artifact-ingest)
+ingest:   canon ingest records            # with artifacts.native_records: true in canon.yaml —
+                                          # feeds review/divergence verdicts into the flywheel
+                                          # (see canon-artifact-ingest)
 ```
 
 Every stage after the index joins on the SAME `(project_id, scenario_id)`
@@ -92,9 +92,12 @@ pair it materializes — one identity scheme, no second one.
 ## `canon inventory sync [--repo <dir>] [--spec-root <dir>]`
 
 ```bash
-canon inventory sync                        # every canon.yaml specs.roots[] entry
-canon inventory sync --repo ../svc          # a specific repo
-canon inventory sync --spec-root ./specs    # ad hoc: ignore canon.yaml entirely
+# every canon.yaml specs.roots[] entry
+canon inventory sync
+# a specific repo
+canon inventory sync --repo ../svc
+# ad hoc: ignore canon.yaml entirely
+canon inventory sync --spec-root ./specs
 ```
 
 Per configured root, in order:

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

@@ -64,9 +64,12 @@ canon ingest plans --dialect openspec --plan-source ../other-repo
 ## 2. Run the import
 
 ```bash
-canon ingest plans                 # .canon/changes/ + every configured source
-canon ingest plans --json          # machine-readable outcome
-canon ingest plans --repo ../svc   # a specific repo root
+# .canon/changes/ + every configured source
+canon ingest plans
+# machine-readable outcome
+canon ingest plans --json
+# a specific repo root
+canon ingest plans --repo ../svc
 ```
 
 Per source the summary reports `changes_parsed`/`tasks_parsed`,

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

@@ -49,9 +49,12 @@ overlays:
 Drive it through the sync command (never hand-write records):
 
 ```bash
-canon plugin sync porting                       # every canon.yaml specs.roots[] entry
-canon plugin sync porting --repo ../svc         # a specific repo
-canon plugin sync porting --spec-root ./specs   # ad hoc: ignore canon.yaml
+# every canon.yaml specs.roots[] entry
+canon plugin sync porting
+# a specific repo
+canon plugin sync porting --repo ../svc
+# ad hoc: ignore canon.yaml
+canon plugin sync porting --spec-root ./specs
 ```
 
 `canon plugin sync <plugin-id>` resolves the manifest, then for each
@@ -70,9 +73,12 @@ 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
+# human table, projected fields appended
+canon query --kind scenario --plugin porting
+# merged record bodies
+canon query --kind scenario --plugin porting --json
+# no --plugin: byte-identical to the core view
+canon query --kind scenario
 ```
 
 `--plugin <id>` folds the plugin's overlay records (latest-by-

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

@@ -40,7 +40,8 @@ Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
 subcommand uses — omit it (or pass `.`) to run from any subdirectory.
 
 ```bash
-canon report build           # writes .canon/REPORT.md
+# writes .canon/REPORT.md
+canon report build
 canon report build --repo /path/to/repo
 ```
 
@@ -67,7 +68,8 @@ committed `.canon/REPORT.md`:
   `canon report build`).
 
 ```bash
-canon report check   # wire into CI exactly like canon format / canon gate check
+# wire into CI exactly like canon format / canon gate check
+canon report check
 ```
 
 Wire it as a CI step or pre-push hook the same way `canon gate
@@ -126,7 +128,8 @@ canon report snapshot /tmp/canon-snap
 Serves the dashboard web app locally, pointed at a real snapshot:
 
 ```bash
-canon dashboard                       # regenerates a fresh snapshot every run, serves it
+# regenerates a fresh snapshot every run, serves it
+canon dashboard
 canon dashboard --snapshot /tmp/canon-snap --port 8080
 ```
 

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

@@ -121,7 +121,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 (`change`, `actor`, `resolutionRev`); `canon schema
-finding add --json` shows the input schema and an example. An identical
+finding add --json` shows `input`: the schema of one document and a complete `example`. An identical
 repeat is `unchanged` (`data.unchanged`) and writes nothing; a different
 finding under an occupied key is `FINDING_SEQ_OCCUPIED`.
 
@@ -468,7 +468,7 @@ With `require_review` present, `canon subject move <id> --to <state>`
 prints on stderr which review checks it ran or skipped:
 
 ```stderr
-canon subject move: 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

@@ -18,11 +18,16 @@ concurrency outgrows sqlite's single-writer mode.
 ## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--full] [--all-workspaces]`
 
 ```bash
-canon ingest sessions                   # one pass over this project's sources
-canon ingest sessions --watch           # poll every 30s (see --interval-secs)
-canon ingest sessions --full            # ignore the watermark; re-parse every in-scope file
-canon ingest sessions --all-workspaces  # machine-wide scan
-canon ingest sessions --home /custom    # override the scan-root home ($HOME)
+# one pass over this project's sources
+canon ingest sessions
+# poll every 30s (see --interval-secs)
+canon ingest sessions --watch
+# ignore the watermark; re-parse every in-scope file
+canon ingest sessions --full
+# machine-wide scan
+canon ingest sessions --all-workspaces
+# override the scan-root home ($HOME)
+canon ingest sessions --home /custom
 ```
 
 **Done when:** the run summary (below) ends with `malformed records … : 0`
@@ -175,7 +180,8 @@ These events interleave with `token_usage` events in one deterministic
 order (directive-before-token on a timestamp tie). Query them with:
 
 ```bash
-canon query --kind event   # filter detail.label == "user_directive"
+# filter detail.label == "user_directive"
+canon query --kind event
 ```
 
 ## Reading the run summary

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

@@ -104,10 +104,12 @@ canon query --kind handoff --since 2026-06-01T00:00:00Z
 canon query --kind trajectory --json
 
 # Page a long result and keep only the fields you need; `meta` carries
-# `page` = {returned, total, nextCursor}; a present `nextCursor` means more, and
-# `meta.next` repeats the call with `--cursor <nextCursor>` (`--all` returns everything).
+# `page` = {returned, total, nextCursor} and `fields` = the paths kept; a present `nextCursor` means more, and
+# `meta.next` repeats the call's explicit arguments with `--cursor=<nextCursor>` (`--all` returns everything). A cursor is bound to the
+# call that issued it, `CANON_ROLE` included: change only `--limit`, `--all`, `--fields` or `--json`; any other change is `CURSOR_INVALID`
+# (`error.reason` `ARGUMENTS_CHANGED`; `FOREIGN` for a cursor an older canon issued: start from the first page). A field path is the record's own key, written as it is.
 canon query --kind trajectory --json --limit 50 --fields at,kind
-canon query --kind trajectory --json --limit 50 --cursor <nextCursor>
+canon query --kind trajectory --json --limit 50 --fields at,kind --cursor <nextCursor>
 ```
 
 ## The ledger is latest-only; the archive holds history
@@ -120,9 +122,12 @@ file names, tracked in git. `status`, the gate, the guards and `canon query`
 read the ledger only.
 
 ```bash
-canon query --kind evidence --history   # every version, archive included
-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
+# every version, archive included
+canon query --kind evidence --history
+# preview; writes nothing
+canon ledger compact
+# pre-0.23 ledger or interrupted move; idempotent; `canon migrate` runs it
+canon ledger compact --commit --plan-digest "$PLAN_DIGEST"
 ```
 
 A crash between the write and the move leaves a readable ledger that the next
@@ -285,10 +290,10 @@ skills:
   providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
 ```
 
-`canon init` writes it: on a terminal it asks, with the harnesses whose
-`.claude`, `.codex`, `.omp` or `.pi` directory exists checked;
-`--providers a,b` (or `none`) answers without asking; with neither it takes
-the detected ones, and with none detected it writes only a commented example
+`canon init` writes it and never asks: `--providers a,b` (or `none`) is the
+answer; without it init takes the harnesses whose
+`.claude`, `.codex`, `.omp` or `.pi` directory exists, and with none detected
+it writes only a commented example
 and installs nothing. `.agents` alone never selects Codex. `canon skills
 install|check|doctor` follow the section; `install` prunes projected files the bundle no longer ships when their bytes match the lock (a modified one stays, reported as `kept:`), `check` exits 1 (`SKILLS_DRIFT`) naming each orphan and `doctor` prints `orphan:` lines; `canon skills install
 --providers=<list>` rewrites it in place. Without the section they use the
@@ -309,17 +314,22 @@ 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 move`, `canon review
-scenario`, `canon evidence add` and `canon artifacts store`) rebuild a stale index on disk first: they
+scenario`, `canon evidence add` and `canon artifacts store`) rebuild a stale index on disk, once nothing
+refuses the call (a refused call writes nothing, whatever the index; until then they read the index as the
+refresh would leave it, in memory): they
 run `canon inventory sync`'s code on the changed files (validation still
-covers the whole root) and print one stderr line:
+covers the whole root) and print one stderr line (in JSON mode the line is a `meta.warnings` entry,
+never a line on stderr):
 
 ```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
+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
 nothing: they grade a stale index as the refresh would leave it, built in
-memory, and print no refresh line. `canon query --kind scenario` and the
+memory, and print no refresh line. `canon subject show` is the one read
+command that declares the refresh, as a cache effect (its `effectNote`), after the subject is found.
+`canon query --kind scenario` and the
 report panels read the index on disk as it is.
 
 A deleted scenario is not erased: `canon inventory sync` — and a writer's
@@ -330,7 +340,7 @@ a live generation that supersedes the tombstone. A root that fails to
 sync writes no tombstone either.
 
 ```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
+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
@@ -348,7 +358,7 @@ the `verifying → shipped` guard refuses, and `canon status` lists only
 `canon inventory sync`:
 
 ```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
+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
@@ -368,6 +378,26 @@ released when its holder exits, however it exits, so it never goes stale;
 a writer gives up after 30 s with a message naming the file and saying to
 retry (the command exits `2` and writes no record).
 
+## The repository write lock
+
+A committed destructive command (`canon purge`, `canon tier age`, `canon ledger
+compact`, `canon artifacts move`, `canon migrate`) recomputes its plan, checks
+its digest and then makes the effects, and nothing may change the plan in
+between. It holds an OS file lock on `.canon/repo-write.lock` for the whole
+span, from before it recomputes the plan to after its last effect; a preview
+holds nothing. Every other command that writes what a plan reads (ledger
+appends, the artifact store, briefs, specs, hooks, skill files, `canon.yaml`)
+holds the same lock while it writes, so it waits for a commit and a commit
+waits for it; reads, `--dry-run` runs and previews hold nothing. The lock is
+the outermost one: it is taken before the scenario-index lock and the
+artifact-store lock. It is released when its holder exits, however it exits,
+so a killed commit never leaves it held, and the file is removed only by a
+call that made it to take the lock and then ended refused (a refusal leaves
+no file and no `.git/info/exclude` line behind). A
+command that waited 30 s for it starts nothing: it exits `2` with
+`REPO_WRITE_BUSY` (retryable; run it again in a moment). The first
+call that needs the lock makes the file, in any repository.
+
 ## What `canon init` keeps out of git
 
 A fresh `canon init` writes these lines to `.gitignore` (each under a
@@ -382,6 +412,8 @@ comment, only the missing ones):
 - `.canon/scenario-index.lock` — the lock serializing index rebuilds.
 - `.canon/artifact-store.lock` — the lock serializing artifact store
   writes.
+- `.canon/repo-write.lock` — the lock a committed destructive command and
+  every writer of what its plan reads hold.
 - `.canon/dashboard-snapshot/` — the snapshot `canon dashboard`
   regenerates on every run.
 - `.canon/learn/` and `.canon/r2/` — local learn scratch and the local