@journeykit/canon 0.34.0 → 0.36.0

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

@@ -105,9 +105,9 @@ canon query --kind trajectory --json
 
 # Page a long result and keep only the fields you need; `meta` carries
 # `page` = {returned, total, nextCursor} and `fields` = the paths kept; a present `nextCursor` means more, and
-# `meta.next` repeats the call with `--cursor <nextCursor>` (`--all` returns everything). A cursor is bound to the
-# call that issued it: change only `--limit`, `--all` or `--fields`; any other change is `CURSOR_INVALID`
-# (`error.reason` `ARGUMENTS_CHANGED`). A field path is the record's own key, written as it is.
+# `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 --fields at,kind --cursor <nextCursor>
 ```
@@ -122,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
@@ -287,12 +290,12 @@ 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
+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_CHECK_FAILED`) naming each orphan and `doctor` prints `orphan:` lines; `canon skills install
 --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,
@@ -311,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
@@ -332,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
@@ -350,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
@@ -370,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_LOCK_UNAVAILABLE` (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
@@ -384,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

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

@@ -40,7 +40,8 @@ Write (or update) the Subject before touching anything else, so every
 downstream artifact has a `subject_id` to pin to.
 
 ```bash
-canon context --repo .            # record kinds, enum domains, policy requirements
+# record kinds, enum domains, policy requirements
+canon context --repo .
 canon subject new subject-domain-loop \
   --domain dev --title "Subject domain loop" \
   --summary "The durable product unit + its per-domain loop" \
@@ -70,7 +71,8 @@ canon subject new subject-domain-loop \
   subjects at once: `--input` takes inline JSON, a file or `-`; an array (or
   NDJSON) is a batch validated before any write, with `operands` holding the
   id and the other keys the option names in camelCase (`canon schema subject
-  new --json` shows `input`: the schema of one document and a complete `example`). Writing an identical subject
+  new --json` shows `input`, its limits and a complete `example`; `canon schema subject new --schemas --json`
+  gives `Input`, the schema of one document). Writing an identical subject
   again is a no-op reported `unchanged` (`data.unchanged`).
 
 ### 2. Retrieve subject-scoped strategy memory BEFORE working
@@ -130,12 +132,13 @@ from anywhere). Any other transition is rejected by failure class, exits
 canon subject move subject-domain-loop --to specced
 canon subject move subject-domain-loop --to building
 canon subject move subject-domain-loop --to verifying
-canon subject move subject-domain-loop --to shipped   # gated — see below
+# gated — see below
+canon subject move subject-domain-loop --to shipped
 ```
 
 On success the status updates in place; `--json` prints the updated
 record. On a gate block it prints violations by failure class to stderr,
-exits 1, and the record is unchanged.
+exits 2 (the code names the condition: `SUBJECT_APPROVAL_REQUIRED`, `EVIDENCE_STALE`, `LAYOUT_MIGRATION_REQUIRED` or `SUBJECT_INVALID`; several causes are `error.details[]`), and the record is unchanged.
 
 **Corpus-wide, the same join:** `canon gate check` with
 `.canon/policy.yaml`'s opt-in `spec_coverage` section generalizes this
@@ -164,7 +167,7 @@ from shipping, until every evidenced scenario has evidence recorded after
 the close or the approval; the refusal names the scenarios and the
 `canon evidence add --all-scenarios` command. Each refusal prints by
 failure class (`uncovered-cell`), carries a `hint`,
-exits 1, and the status stays `verifying`. `retired` is not gated.
+exits 2, and the status stays `verifying`. `retired` is not gated.
 
 **The brief (0.16, 0.17, 0.19):** `verifying → shipped` also refuses where a brief
 exists and is not approved, read exactly as `canon status` reads it (one
@@ -172,7 +175,7 @@ shared check, so status says `ship` only when this passes): the subject's
 scope (every change the subject answers for, see below) has a canon `.canon/changes/<change>/brief.md`
 with no `Approved:` line outside HTML comments and code fences, whose
 `Approved:` line carries a digest the brief's text no longer matches
-(`BRIEF_CHANGED_SINCE_APPROVAL`; the brief was edited after the human
+(`BRIEF_APPROVAL_STALE`; the brief was edited after the human
 answered), or has no canon `brief.md` yet but comes from an external
 openspec plan with a `proposal.md` under the plan sources. It also
 refuses while `canon brief check` has blocker findings for that change,
@@ -182,8 +185,8 @@ a policy. The refusal is an `unreviewed-promotion` naming the subject, and
 says what to do:
 
 ```output
-canon subject move: SUBJECT_GATE_VIOLATION — unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
-canon subject move: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
+output: canon subject move: SUBJECT_INVALID — unreviewed-promotion demo-subject — verifying → shipped: brief not approved — .canon/changes/c-demo/brief.md has no `Approved:` line; a human must answer the brief, and only from that answer the agent will record their words with `canon brief approve c-demo --approver <the human> --note "<their words>"`
+output: canon subject move: refused — get the human's answer to the brief and record it with `canon brief approve`, or pass --override-reason <text> to move anyway; the waiver is recorded on the subject
 ```
 
 For an external change with no canon brief yet, the reason reads
@@ -209,7 +212,7 @@ This refusal is a backstop, and so is the evidence one: shipping is not
 the first thing an unapproved brief stops. The agent writes the brief,
 runs `canon brief check` until it has no blockers, then shows it to the
 human and asks, and nothing is built or attested for the subject until the human
-answers. `canon evidence add` refuses (exit 1, nothing staged) a
+answers. `canon evidence add` refuses (exit 2, nothing staged) a
 scenario whose `@subject` owner, or a task whose change
 an adopting subject, has an enforced, unapproved brief, through the same
 check; see `canon-gate`.
@@ -221,7 +224,7 @@ check; see `canon-gate`.
 edited since, and even if the tags were removed; or (3) a *chore*, which has
 no scenario to tag and so governs from the moment it is adopted. They pass
 only when every one of them reads as approved now; an unapproved one and one
-edited after its approval (`BRIEF_CHANGED_SINCE_APPROVAL`) are named for
+edited after its approval (`BRIEF_APPROVAL_STALE`) are named for
 different reasons, and the answer does not depend on the order the changes
 were adopted or approved. The ship guard's brief-structure check runs over
 all of them. When several block, the hint is one
@@ -243,7 +246,7 @@ answers only to the changes its tags name (counting only changes the subject
 adopted); another change's edit after its approval never blocks it. An untagged
 scenario (one whose tags were removed reads the same) answers to every adopted
 change with an `Approved:` line, a chore included, so an approved change edited
-since refuses it (`BRIEF_CHANGED_SINCE_APPROVAL`); an unapproved chore blocks
+since refuses it (`BRIEF_APPROVAL_STALE`); an unapproved chore blocks
 reopen and ship, never evidence. When no adopted change has an approved line,
 a scenario with evidence recorded before the subject first adopted a change
 (and without a brief override) needs no brief, and one without answers to the
@@ -259,7 +262,7 @@ When `.canon/policy.yaml` sets `spec_coverage.require_review` (see
 prints on stderr which it ran or skipped:
 
 ```output
-canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
+output: canon subject move: review guard for building → verifying (spec_coverage.require_review, scope: verifying, shipped)
   ran unreviewed-promotion — every owned scenario needs a review by an actor, and from a session, other than its evidence's
   ran open-blocker — 1 adopted change(s) checked for open blocker findings
 ```
@@ -268,7 +271,7 @@ A target outside `require_review.scope` prints `skipped
 unreviewed-promotion — `specced` is not in require_review.scope`. A
 transition INTO an in-scope status with gaps — an owned scenario with no
 qualifying review (`unreviewed-promotion`), or an open blocker finding
-on an adopted change (`open-blocker`) — prints the violations, exits 1,
+on an adopted change (`open-blocker`) — prints the violations, exits 2,
 leaves the record unchanged, and names `--override-reason`. `shipped`
 also refuses a `false-success` (a scenario whose latest audit is
 `refuted`) and, when `require_audit.scope` covers `shipped`, an owed
@@ -316,8 +319,8 @@ canon subject move demo-subject --to verifying \
 ```
 
 ```output
-canon subject move: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; keep the follow-up in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
-canon subject move: demo-subject → verifying — written directly; nothing to promote
+output: canon subject move: reopened `demo-subject` from shipped, recorded by `impl`: follow-up: the retry path leaks a file handle; keep the follow-up in its approved change `c-demo`, then scenario, evidence and review; shipping again runs every guard
+output: canon subject move: demo-subject → verifying — written directly; nothing to promote
 ```
 
 - `--reason "<one line>"` is required for `shipped → verifying` (exit 2
@@ -330,14 +333,14 @@ canon subject move: demo-subject → verifying — written directly; nothing to
 - Inside the approved scope it needs no human: every change the subject
   answers for (tagged, approved or chore) has an approved brief, or there
   is no brief to answer.
-  Otherwise it refuses, exit 1, naming the brief to approve, and
+  Otherwise it refuses, exit 2, naming the brief to approve, and
   `--override-reason` does not waive it:
   ``unreviewed-promotion demo-subject — shipped → verifying: reopening needs the approved scope, and the brief is not approved — .canon/changes/c-next/brief.md has no `Approved:` line; …``.
 - The review guard does not run on a reopen (it prints `skipped … — a
   reopen moves the subject back to fix its gaps; shipping again runs
   it`). `verifying → shipped` afterwards runs every guard above again.
-- A policy that fails closed (`POLICY_CHANGED_SINCE_APPROVAL`,
-  `POLICY_APPROVAL_UNREADABLE`: see `canon-policy`) refuses the reopen and
+- A policy that fails closed (`POLICY_APPROVAL_STALE`,
+  `POLICY_APPROVAL_CORRUPT`, `POLICY_APPROVAL_DENIED`: see `canon-policy`) refuses the reopen and
   the ship, and `--override-reason` does not waive it.
 - `canon change new` on a shipped subject prints the reopen command
   (`canon subject move <id> --to verifying --reason "<why it reopens>"`)
@@ -353,9 +356,11 @@ Planning docs written outside canon become change/task records via
 `canon subject adopt` lifts an imported change into a managed Subject:
 
 ```bash
-canon ingest plans --repo .                          # import → change/task rows
+# import → change/task rows
+canon ingest plans --repo .
+# link change → subject
 canon subject adopt subject-domain-loop \
-  --change subject-domain-loop-plan                      # link change → subject
+  --change subject-domain-loop-plan
 ```
 
 A change made with `canon change new` (below) is recorded and adopted
@@ -377,7 +382,7 @@ second subject adds that subject, never re-points the change, and says
 so:
 
 ```output
-canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
+output: canon subject adopt: linked change `refactor-core` to subject `editing` as well; the change now belongs to `perception` and `editing` — written directly; nothing to promote
 ```
 
 Every reader joins a subject to its changes from both sides (the
@@ -418,7 +423,7 @@ canon subject unadopt <S> --change <change> --json
 
 Removes the link on both records and keeps the change and its brief, so the
 draft can be adopted elsewhere (a `proposed` holding subject, say) while the
-live subject keeps shipping. It is refused with `SUBJECT_UNADOPT_REFUSED`
+live subject keeps shipping. It is refused with `SUBJECT_CONFLICT` (reason `APPROVED_BRIEF` or `FLOW_TAGGED`)
 for a change whose brief carries an `Approved:` line, and while a scenario
 the subject owns carries a `@flow:<change>.*` tag (it would fall back to an
 older approval; remove or retag those scenarios first, the hint names them);
@@ -434,8 +439,8 @@ canon change new add-login --subject auth --title "Add login"
 ```
 
 ```output
-canon change new: wrote .canon/changes/add-login/brief.md
-canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
+output: canon change new: wrote .canon/changes/add-login/brief.md
+output: canon change new: recorded change `add-login` adopted into subject `auth` — written directly; nothing to promote
 ```
 
 - **Writes** canon's own change dir, `.canon/changes/<slug>/`, holding
@@ -493,8 +498,10 @@ brief (`data.next`, `meta.next`).
 ### The brief: `canon brief show`, `canon brief check`, `canon brief approve`
 
 ```text
-canon brief show [<slug>]                       # state and the next one to three steps; never edits
-canon brief check [<slug>] [--json]            # findings; exit 0 clean, 2 blockers, 1 error
+# state and the next one to three steps; never edits
+canon brief show [<slug>]
+# findings; exit 0 clean, 2 blockers, 1 error
+canon brief check [<slug>] [--json]
 canon brief approve <slug> <slug> --approver <the human> --note "<their words>"
 ```
 
@@ -503,12 +510,12 @@ same answer and one timestamp on every brief and on the policy approval
 (0.31). Every slug is checked before anything is written (a brief that
 exists and reads, no blocker, a one-line name and answer, a body that does not
 end inside an open code fence); one refused slug refuses the call, exit 2
-`BRIEF_APPROVE_REFUSED` naming each refused slug with its own code, and
-nothing is written. A repeated slug counts once. With one slug the output is as
+with the first refused slug's own code (`BRIEF_INVALID`, `BRIEF_NOT_FOUND`) and an
+`error.details` entry for each refused slug, and nothing is written. A repeated slug counts once. With one slug the output is as
 before; with several, `--json` carries one entry per slug (`written`,
 `unchanged`, `failed`, `skipped`). A disk error while writing exits 1 and
 leaves the slugs already written approved. The call is human-only for every
-slug; the `HUMAN_ONLY` hint gives the human one line with all the slugs.
+slug; the `ACTOR_DENIED` hint gives the human one line with all the slugs.
 
 Without the change operand, the repo's only live change is read. The brief is the
 PRD `canon change new` writes; sections are found by their English `##`
@@ -518,7 +525,7 @@ before. A brief with `<!-- canon:… -->` comments or Korean headings is in the
 0.30 format: `brief check` gives it one blocker (`brief.old-format`) and
 `canon migrate` rewrites it; `status`, `gate check`, `context` and `brief show`
 warn, and a command that writes and judges it is refused
-(`OLD_BRIEF_FORMAT`).
+(`BRIEF_MIGRATION_REQUIRED`).
 
 - **Blockers (structure, `brief.*`)**: a missing, duplicated or
   out-of-order section; a flow with no steps or a duplicate step id;
@@ -543,7 +550,7 @@ warn, and a command that writes and judges it is refused
   `Approved: <who> <when> — "<words>" (brief sha256:<digest>)` into the
   brief and records the policy approval in the same call. It refuses
   (exit 2) while the check has structure blockers. Edit the brief
-  afterwards and every reader says `BRIEF_CHANGED_SINCE_APPROVAL` until a
+  afterwards and every reader says `BRIEF_APPROVAL_STALE` until a
   human answers again and `approve` runs again. Run it only from the
   human's answer, with their words as `--note`.
 
@@ -567,8 +574,10 @@ step that writes it.
 ## Where are we: `canon status`
 
 ```bash
-canon status                 # subjects by status, their gaps, next commands
-canon status --json          # the same report, stable shape
+# subjects by status, their gaps, next commands
+canon status
+# the same report, stable shape
+canon status --json
 canon status --repo ../other
 ```
 
@@ -611,7 +620,7 @@ uses, so status and the gate cannot disagree about a gap:
   `Approved: <who> <when> — "<the human's words>" (brief sha256:<digest>)`,
   the digest covering the brief without its `Approved:` lines. A brief
   edited after that reads `brief: not approved (<brief> changed after its
-  approval (BRIEF_CHANGED_SINCE_APPROVAL))` and names the re-approval
+  approval (BRIEF_APPROVAL_STALE))` and names the re-approval
   command: the changed brief needs a new human answer. A line with no
   digest (written before 0.19) stays approved, with an `advisory:` to
   re-approve so it binds to the text. Fixes and follow-ups
@@ -818,7 +827,8 @@ and `canon gate check` exits `0`; read `data.subjects[]` for the counts and
 
 ```bash
 canon query --kind subject --domain dev --status building
-canon report build --repo .  # renders the "Subjects" panel
+# renders the "Subjects" panel
+canon report build --repo .
 ```
 
 - `canon query --kind subject [--domain <d>] [--status <s>]` — the