@journeykit/canon 0.31.0 → 0.33.0

package/dist/skills/reference/role-orchestrator.md

@@ -4,9 +4,10 @@ You run the loop across agents and move the subject. You write no brief,
 code or review yourself. Declare the role with `CANON_ROLE=orchestrator` (or
 `--as orchestrator`); your `canon status` also lists the human's steps. The
 human's acts (`brief approve`, `policy approve`, `divergence accept`) refuse
-every agent role, you included (`HUMAN_ONLY`). You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
-dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
-wait; the human runs it (or uses `canon dashboard`).
+every agent role, you included (`HUMAN_ONLY`), unless you record the answer the
+human gave you in the conversation with `--relayed-via <tool>` (below). You never
+run them without that answer, and never remove or unset your role (`env -u CANON_ROLE`,
+dropping `--as`) to get past the refusal.
 
 ## Commands
 
@@ -227,7 +228,7 @@ canon ledger compact
 ```
 ```text
 # Bring a repo from an earlier canon up to date
-canon migrate [--commit --plan-digest <DIGEST>] [--revert] [--backup <DIR> (with --revert)] [--input]
+canon migrate [--commit --plan-digest <DIGEST>] [--revert | --relayed-via <NAME>] [--backup <DIR> (with --revert)] [--actor <ACTOR_ID> (with --relayed-via)] [--approver <NAME> (with --relayed-via)] [--note <TEXT> (with --relayed-via)] [--input]
 # a bare run previews and prints planDigest; `--commit --plan-digest <DIGEST>` with that digest acts
 ```
 ```bash
@@ -443,10 +444,10 @@ canon trace add-login_1_1
 ## Read the state
 
 `canon status` lists the next steps, each with the `role` that takes it
-(`null` for the human), and `waitingOn` counts the steps held by each other
+(`null` for the human), and `data.waitingOn` counts the steps held by each other
 owner, `human` included. Call it once at the start and when resuming, not
 after a write: after `subject move --to` or a spawned role's write, the
-write's `meta.next` and `meta.waitingOn` are the status for what it touched.
+write's `meta.next` and `data.waitingOn` are the status for what it touched.
 
 ## Spawn each role
 
@@ -491,14 +492,14 @@ text.
 | Harness | In-harness subagents | Isolation | Ask the human | Hooks | Skipped |
 |---|---|---|---|---|---|
 | claude (`.claude`) | yes, a subagent tool; a child shares your environment, so pass the role in the task | a subagent can run in its own git worktree | yes, a question tool | yes, in the harness settings; `scripts/canon-retrieve-pre-dispatch.sh` is a sidecar, not installed | none |
-| codex (`.agents`) | `verify`: none when #39 was filed; start the reviewer as a new `codex exec` run | none from canon: use a separate worktree you create | no in `codex exec`; stop and report | `verify` | in-harness spawn, unless a newer version provides it |
+| codex (`.agents`) | `verify`: none when #39 was filed; start the reviewer as a new `codex exec` run | none from canon: use a separate worktree you create | no in `codex exec`; ask in the chat | `verify` | in-harness spawn, unless a newer version provides it |
 | omp (`.omp`) | yes, the task tool | `verify` | yes, an ask tool | yes | none |
 | pi (`.pi`) | `verify`: assume none; start a new `pi` process | none from canon | `verify` | `verify` | in-harness spawn, isolation |
 
 Where a harness has no subagent tool, the reviewer is still a separate
 process with its own session id: start it from the shell with its own
-`CANON_ROLE=reviewer`. A harness that cannot ask the human means you stop
-and report in your final message; you never assume the answer.
+`CANON_ROLE=reviewer`. A harness that cannot ask the human means you ask
+in the chat and record only the reply; you never assume the answer.
 
 The reviewer is a separate process with its own session id, never your
 session or the implementer's under another label. Start it as a new process
@@ -507,25 +508,39 @@ implementer's context, and have it record its real session id as
 `--session` (#39). A reviewer that cannot run the tests says so and does
 not sign off.
 
-## Relay the human stop
-
-When `status` or `meta.next` shows a step with `actor: human` (the brief's
-approval), stop everything for that scope, report the brief to the human in
-its language, and wait. Tell the human they can approve the clean briefs in
-`canon dashboard` (the briefs page) or run, in their own shell, the exact call
-with every slug filled in: `canon brief approve <slug> <slug> --approver <their name>
---note "<their own words>"` (several slugs take one answer; nothing is written if
-one is refused). You never click Approve, fill the form or run
-`brief approve` yourself: it refuses you (`HUMAN_ONLY`), and removing or
-unsetting your declared role (`env -u CANON_ROLE`, dropping `--as`) to get past
-that is the same act under another label. Report the call and wait. Do not start the
+## Relay the human's answer
+
+When `status` or `meta.next` shows a step with `x-canon.actor: human` (the brief's
+approval), stop everything for that scope and put the brief in front of the
+human in its language: `canon brief show <slug> --body` prints the brief and,
+last, its digest. Send the output to the human's own view, never retyped (omp:
+redirect it to `out://`, off for subagents and non-TUI sessions and capped at
+64 KiB; there, and where there is no such channel, leave the tool output
+visible). You are the session that talks to the human: a subagent has no
+question tool, so you show, ask and record for it. Ask with the harness question tool (`ask` in omp, `AskUserQuestion`
+in Claude Code, otherwise in the chat), approve or request changes, all the
+clean briefs in one question. Only an explicit approval counts; a question or a
+condition is a revision request for the planner, and no answer means you wait.
+They may also approve in `canon dashboard` (the briefs page); you never click
+Approve or fill the form. On their approval record it: `canon brief approve
+<slug> <slug> --approver <their name> --note "<their own words>" --relayed-via
+<ask|AskUserQuestion|chat> --actor <your actor id> --digest <slug>=<the digest
+shown>` (several slugs take one answer, each with its own `--digest`; nothing is written
+if one is refused). The record says you recorded it, with your role, actor and
+tool. `RELAY_DIGEST_MISMATCH` means the brief changed after they saw it: show it
+again. When `canon.yaml` has `approval: { relay: deny }` the call is refused
+(`HUMAN_ONLY`, naming the key): report the human's own call and wait for them to
+run it. Removing or unsetting your declared role (`env -u CANON_ROLE`,
+dropping `--as`) to get past a refusal is the same act under another label.
+`canon skills show role-planner` has the full procedure. Do not start the
 implementer before `canon brief show <slug>` reports `state: approved`.
 Never approve it yourself and never edit the policy to pass the gate. A
 policy that no longer matches the approval fails closed
 (`POLICY_CHANGED_SINCE_APPROVAL`, or `POLICY_APPROVAL_UNREADABLE`): the ship
 guard and the reopen refuse, and `--override-reason` does not waive it. Run
-`canon policy show`, then stop and ask the human to re-approve
-(the call `canon policy approve --approver <their name>` is theirs to run, never yours) or restore the
+`canon policy show`, then show the policy to the human, ask them to re-approve
+and record their explicit answer (`canon policy approve --approver <their name>
+--note "<their words>" --relayed-via <tool> --actor <your actor id>`), or restore the
 approved policy from git; never edit the policy yourself. Inside an
 approved scope never stop for a human: fixes, follow-ups and re-reviews go
 straight to the implementer and reviewer in the same change. A known gap the
@@ -548,7 +563,7 @@ holds the next command and the verified claims (`canon skills show canon-vocab`)
 After a timeout or a lost response, repeat the write only when its repeat is
 safe. `evidence add`, `review scenario`, `review change` and `finding add`
 are content-keyed: an identical repeat returns the existing record with
-`meta.unchanged: true` (a batch reports the element `unchanged`).
+`data.unchanged: true` (a batch reports the element `unchanged`).
 `finding close`, `subject adopt`, `inventory sync`, `ingest *`, `gate
 promote` and `task done` are replay-safe the same way. `subject new`,
 `change new`, `feature new`, `scenario new`, `subject move` and `dispatch
@@ -563,9 +578,9 @@ its preview, never from an old digest.
 |---|---|
 | "Edit the policy so the gate passes." | A changed policy fails closed (`POLICY_CHANGED_SINCE_APPROVAL`); ask the human to re-approve or restore it from git. |
 | "The reviewer can be me under another label." | The reviewer is a separate process with its own real session id (#39). |
-| "Approve the brief; the human said they are busy." | `brief approve` refuses agent roles. Report the brief and wait. |
+| "Approve the brief; the human said they are busy." | An answer they did not give is not recorded. Show the brief, ask, and record only an explicit approval with `--relayed-via`. |
 | "Override the refusal to ship." | Fix the gap the refusal names; `--override-reason` waives only the `require_review` gaps and the brief gap, is recorded on the subject, and is for the human's call, not a shortcut. |
-| "Run the commit now, the preview looked fine earlier." | A bare run previews; `--commit --plan-digest` acts only on the plan you just previewed (`PLAN_CHANGED` otherwise). Preview again, then act. |
+| "Run the commit now, the preview looked fine earlier." | A bare run previews; `--commit --plan-digest` acts only on the plan you just previewed (`PLAN_STALE` otherwise). Preview again, then act. |
 | "I have corrected this agent before." | A correction repeated across runs belongs in a scenario, the policy or a gate, not more prose. Tell the human. |
 
 ## Move the subject
@@ -608,10 +623,10 @@ read the refusal in `error` of `canon subject move demo --to shipped --json`.
 move` and `canon migrate` delete or rewrite existing data. A bare run only
 previews: exit 0, nothing written, a report with `planDigest` and
 `effects[]`. Read the effects, then act with `--commit --plan-digest
-<planDigest>`; it refuses (`PLAN_CHANGED`, exit 2) when the plan recomputed
+<planDigest>`; it refuses (`PLAN_STALE`, exit 2) when the plan recomputed
 now differs from the one you previewed. A document passed with `--input`
 never carries `--commit` or `--plan-digest`, and these five leaves take one
-object only (`INPUT_BATCH_UNSUPPORTED`).
+object only (`INPUT_INVALID`).
 
 ```bash
 canon purge --kind session --before 2026-01-01
@@ -663,6 +678,6 @@ git-ignored, and `canon migrate --revert` needs it (keep it until you are sure).
 **Done when:** `canon migrate` reports nothing left to move, `canon skills
 check` exits 0, and `canon status` and `canon gate check` no longer warn
 about 0.27 state; read the first in `data` of `canon migrate --json`, the
-others in `meta.warnings`.
+others in `meta.warnings` (`[{code, message}]`).
 
 Reference: `canon skills show canon-subject`.

package/dist/skills/reference/role-planner.md

@@ -4,10 +4,12 @@ You turn a request into an approved scope: a subject, a change and a PRD
 brief the human answers once. You build nothing. Declare the role with
 `CANON_ROLE=planner` (or `--as planner`); `canon status` and `meta.next`
 then show your steps and count the rest under `waitingOn`. The approvals are
-the human's: `brief approve`, `policy approve` and `divergence accept` refuse
-every agent role (`HUMAN_ONLY`, `retryable: false`), and no flag grants them. You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
-dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
-wait; the human runs it (or uses `canon dashboard`).
+the human's: `brief approve`, `policy approve`, `divergence accept` and the
+`migrate --commit` that re-binds `Approved:` lines refuse every agent role
+(`HUMAN_ONLY`, `retryable: false`) unless you record the answer the human gave
+you in the conversation, with `--relayed-via <tool>` (step 4). Without a human's
+explicit answer you never run them, and you never remove or unset your role
+(`env -u CANON_ROLE`, dropping `--as`) to get past the refusal.
 
 ## Commands
 
@@ -30,7 +32,7 @@ canon brief check
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>]
+canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show
@@ -170,7 +172,7 @@ canon trace add-login_1_1
 ```
 <!-- canon:generated commands-planner end -->
 
-After the first `status`, follow `meta.next` of each write. `brief check`
+After the first `status`, follow `meta.next` of each write. Each `meta.next` entry is runnable: run `canon` + its `argv`; guidance that needs a value you must fill in is in the error `hint` or the report text, not in `meta.next`. `brief check`
 lists blockers and advisories and exits 1 when it finds blockers; `canon
 brief show --as planner` names the next steps. The change is an optional
 operand of both (`canon brief check add-login`); without it they read the
@@ -243,26 +245,63 @@ ids); the human step comes after it. A policy that no longer matches its approva
    the advisories are gone or each remaining one is waived with a reason.
    It never blocks approval, but you do not hand the human a brief with
    unexamined advisories.
-4. **Stop for the human.** Report the brief to the human, in the brief's
-   language, asking once, and say they can approve it in `canon dashboard`
-   (the briefs page, `/briefs.html`) or answer in chat. You never click
-   Approve or fill that form yourself. Build nothing for that scope (no scenarios, code
-   or evidence) until the human answers. The approval is never assumed, even
-   when the human said they cannot answer until you report: the brief is
-   that report. The one answer approves the brief and the policy
+4. **Show, ask, count only an explicit approval.** Build nothing for that
+   scope (no scenarios, code or evidence) until the human has answered. The
+   approval is never assumed, even when the human said they cannot answer
+   until you show the brief. The one answer approves the brief and the policy
    (`.canon/policy.yaml`, written by `canon init`), which is what the gate
    grades the work against.
-5. **The human records the answer.** `brief approve` is the human's leaf: run
-   by an agent role it is refused (`HUMAN_ONLY`) with a hint addressed to the
-   human. Report the exact call, slug filled in, and wait: `canon brief approve
-   add-login --approver <their name> --note "<their own words>"`; the human
-   runs it in their own shell (`--approver` and `--note` are theirs to supply)
-   or approves in the dashboard. Never approve in their name, never remove or
-   unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it, and never
-   edit the policy to make the gate pass.
+   - **Show.** `canon brief show <slug> --body` prints the brief file's bytes
+     as they are and, as its last line, `digest: sha256:<hex>`, the value
+     `brief approve` records. Send that output to the human's own view; never
+     retype or paraphrase the brief into the conversation. In omp, redirect it
+     to `out://` (`canon brief show add-login --body > out://add-login`).
+     `out://` is off for subagents and non-TUI sessions (the redirect then
+     errors) and caps a reply at 64 KiB: there, and in a harness with no such
+     channel, leave the tool output visible, which is the same. Read the digest alone with `canon brief show add-login --body |
+     tail -n 1`. Show every brief of one request, each with its digest.
+   - **Ask.** Use the harness's question tool: `ask` in omp, `AskUserQuestion`
+     in Claude Code; a harness without one, ask in the chat and wait for the
+     reply. Two choices: approve, or request changes. Several briefs are one
+     question. Say in the brief's language what is approved: the brief and
+     the policy.
+   - **Count only an explicit approval.** The approve choice, or the human
+     saying in the chat that they approve. A question, a condition ("yes, if
+     …") or an approval of part of it is a revision request: change the brief,
+     `brief check` until clean, show it again and ask again. No answer means
+     nothing is recorded: wait.
+   A subagent has no question tool and no human in front of it: the
+   orchestrator (the session talking to the human) shows, asks and records.
+   They may also approve on `canon dashboard` (the briefs page,
+   `/briefs.html`); you never click Approve or fill that form yourself.
+5. **Record the answer you were given.** Run `brief approve` with the relay
+   option: `canon brief approve add-login --approver <their name> --note "<their
+   answer, as they gave it>" --relayed-via <ask|AskUserQuestion|chat> --actor
+   <your actor id> --digest add-login=<the digest you showed>` (several slugs:
+   one `--digest <slug>=<digest>` each, one answer for all, nothing written if
+   any is refused). `--actor` may be `CANON_ACTOR` instead. The record keeps
+   their name and words and says that you, with your role and actor, recorded
+   them through that tool: the `Approved:` line gains `(relayed by <role>
+   <actor> via <tool>)`, which is outside the digest, and `status`, `brief
+   show` and the dashboard name it. Never approve in their name without their
+   answer, never write the answer for them, and never edit the policy to make
+   the gate pass. A digest that differs from the brief now
+   (`RELAY_DIGEST_MISMATCH`) means the brief changed after they saw it: show
+   it again and ask again; nothing was written. Without `--relayed-via` the call is
+   `HUMAN_ONLY`; with it and no role declared, `USAGE`. When `canon.yaml`
+   turns relaying off (`approval: { relay: deny }`), the refusal names that key:
+   report the human's call (`canon brief approve add-login --approver <their
+   name> --note "<their own words>"`) and wait for them to run it. Never
+   remove or unset your role (`env -u CANON_ROLE`, dropping `--as`) to run it.
+   `canon policy approve`, `canon divergence accept` and `canon migrate
+   --commit --plan-digest <d>` follow the same procedure, each taking
+   `--approver <their name> --note "<their answer>" --relayed-via <tool>` (and
+   `--actor <your actor id>`, which `divergence accept` already requires): show what is approved (the policy file, the divergent
+   evidence with its reason and tracking reference, the migrate plan), ask,
+   count only an explicit approval, then record with the relay option.
    `canon brief show <slug>` then reports `state: approved`. A brief edited
    after its approval is not approved (`BRIEF_CHANGED_SINCE_APPROVAL`): it
-   needs a new answer and a new `brief approve` by the human. A follow-up that
+   needs a new answer, shown and asked again, and a new `brief approve`. A follow-up that
    adds or changes a step of the brief is a scope change and needs a new
    answer.
 
@@ -273,17 +312,17 @@ approval.
 
 **Done when:** `canon brief check add-login` exits 0 (no blockers, and the
 prose advisories are gone or waived with a reason) and `canon brief show
-add-login` reports `state: ready`: the brief is handed to the human and you
-stop. The scope is approved when the same command reports `state:
-approved`; read it in `data.state` of `canon brief show add-login --json`.
-Nothing else starts before that.
+add-login` reports `state: ready`: show it to the human and ask (step 4). The scope is approved
+when you have recorded their explicit approval (step 5) and the same command
+reports `state: approved`; read it in `data.state` of `canon brief show
+add-login --json`. Nothing else starts before that.
 
 ## Non-behavior work is a chore
 
 A refactor, dependency, build, CI or infra change that alters nothing a user
 can observe: `change new --change-kind chore`. Its brief is short (intent,
 category, invariants, checks, out of scope) and approved like any brief, one
-human stop. A chore adds no scenarios: the
+human answer. A chore adds no scenarios: the
 implementer runs the subject's suite again where the code changed and binds
 it with `canon evidence add --all-scenarios` (a docs-only chore changes no
 code and needs no new evidence), then the reviewer records one
@@ -310,9 +349,9 @@ old column, delete the old format) in its own later change.
 
 | The thought | The reality |
 |---|---|
-| "The human is unavailable; I will assume the approval." | Never. The brief is the report; stop, and put open questions into Questions and assumptions. |
+| "The human is unavailable; I will assume the approval." | Never. Show the brief and ask; without an explicit answer nothing is recorded and nothing is built. Put open questions into Questions and assumptions. |
 | "This could change policy, but I will decide it." | Anything that could change policy goes to the questions. |
-| "A small follow-up needs no new answer." | A follow-up that adds or changes a flow step is a scope change and needs a new `brief approve`. |
+| "A small follow-up needs no new answer." | A follow-up that adds or changes a flow step is a scope change and needs a new answer and a new `brief approve`. |
 | "This migration is just a chore." | Data, interface or output changes are feature changes. |
 | "Put the file and line in the brief so nobody has to look." | Paths rot; describe behavior. |
 

package/dist/skills/reference/role-reviewer.md

@@ -4,10 +4,11 @@ You are the independent second look. Declare the role with
 `CANON_ROLE=reviewer` (or `--as reviewer`); `--role` on `review scenario`,
 `review change` and `finding add` then defaults to `reviewer`. The human's
 acts refuse you (`HUMAN_ONLY`): `brief approve`, `policy approve` and
-`divergence accept`. Name what the human has to decide in your report; never
-look for a flag that grants it. You never run them, and never remove or unset your role (`env -u CANON_ROLE`,
-dropping `--as`) to get past the refusal: report the exact call, slug filled in, and
-wait; the human runs it (or uses `canon dashboard`).
+`divergence accept`, unless you record the answer the human gave you in the
+conversation with `--relayed-via <tool>` (the divergence acceptance below).
+Name what the human has to decide; never look for another flag that grants it.
+You never run them without that answer, and never remove or unset your role
+(`env -u CANON_ROLE`, dropping `--as`) to get past the refusal.
 
 ## Commands
 
@@ -30,7 +31,7 @@ canon brief check
 ```
 ```text
 # Show where the change stands and the next one to three steps; never edits
-canon brief show [<CHANGE_ID>]
+canon brief show [<CHANGE_ID>] [--body]
 ```
 ```bash
 canon brief show
@@ -219,7 +220,7 @@ advisory names it); that is the orchestrator's step, not yours.
 Run `gate check` once, before `review scenario`: its `unreviewed-promotion`
 violations are the subjects and scenarios that need your review. Do not loop
 it. After `review scenario`, read its `meta.next` instead of calling `gate check`
-or `status` again.
+or `status` again. Each `meta.next` entry is runnable: run `canon` + its `argv`; guidance that needs a value you must fill in is in the error `hint` or the report text, not in `meta.next`.
 
 ## Separate session
 
@@ -287,14 +288,21 @@ sign.
 `divergence accept` is for a scenario whose honest evidence is `divergent`
 and whose gap is limited by something outside this change (an upstream
 limit, a platform bug) and is tracked there. It records a human's decision,
-so it refuses every agent role (`HUMAN_ONLY`), you included. What you do:
-confirm the evidence really is divergent and the limit is outside this
-change, then report to the human the scenario ids, the reason, the
-tracking reference and an expiry when the limit should be gone by a date.
-Give the exact call, ids filled in: the human runs `canon divergence accept
-<ids> --actor <name> --reason "<why>" --tracking <ref>` themselves in their
-own shell, from a session that did not attest the evidence
-(`DIVERGENCE_ACCEPT_REFUSED` otherwise); you never run it or unset your role to. Never suggest it to skip
+so it refuses every agent role (`HUMAN_ONLY`), you included, unless it records
+the answer the human gave you. What you do: confirm the evidence really is
+divergent and the limit is outside this change, then put to the human the
+scenario ids, the reason, the tracking reference and an expiry when the limit
+should be gone by a date, in their own view and not retyped (omp: `out://`).
+Ask with the harness question tool (`ask` in omp, `AskUserQuestion` in Claude
+Code, otherwise in the chat): accept the gap, or not. Only an explicit
+approval counts; a question or a condition is not one, and no answer records
+nothing. Then record it from a session that did not attest the evidence
+(`DIVERGENCE_ACCEPT_REFUSED` otherwise): `canon divergence accept <ids> --actor
+<your actor id> --reason "<why>" --tracking <ref> --approver <their name> --note
+"<their answer>" --relayed-via <tool>`; the record carries the relay, the
+approver and their answer. When `canon.yaml` has `approval: { relay: deny }` the
+call is refused (`HUMAN_ONLY`, naming the key) and the human runs it themselves.
+You never unset your role to run it. Never suggest it to skip
 a fix the implementer can make in this change. The acceptance pins that
 evidence: new evidence for the scenario, or its expiry, ends it, and the
 human accepts (or the implementer fixes) again. An accepted gap counts as
@@ -347,7 +355,7 @@ implementer owns. Your last write's `meta.next` names the next step.
 ## Retry safety
 
 `review scenario`, `review change` and `finding add` are content-keyed: an
-identical repeat is reported `unchanged` (`meta.unchanged: true`, or the
+identical repeat is reported `unchanged` (`data.unchanged: true`, or the
 element's `status` in a batch), so after a timeout run the same command
 again. A different finding under an occupied round and seq is refused
 (`FINDING_SEQ_OCCUPIED`): take the next seq. `finding close` with the same
@@ -362,6 +370,6 @@ disposition is a no-op too.
 | "I cannot run the tests, but the evidence looks right." | Say so and record `indeterminate` or `unavailable`; never sign what you could not run. |
 | "This is a minor defect; I will skip the finding." | Every defect is a finding; severity says how much it matters. |
 | "I will edit the brief to fix it." | A brief defect is a finding, not an edit. |
-| "I will accept the gap myself, the limit is real." | `divergence accept` refuses agent roles; report the gap to the human. |
+| "I will accept the gap myself, the limit is real." | The human accepts it: ask them, and record only their explicit answer with `--relayed-via`. |
 
 Reference: `canon skills show canon-review`.

package/man/canon-adapter-authorize.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-authorize 1  "authorize 0.31.0" 
+.TH canon-adapter-authorize 1  "authorize 0.33.0" 
 .SH NAME
 canon\-adapter\-authorize \- Authorize declared capabilities against repository policy (preflight only)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-adapter-validate.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter-validate 1  "validate 0.31.0" 
+.TH canon-adapter-validate 1  "validate 0.33.0" 
 .SH NAME
 canon\-adapter\-validate \- Read and validate one provider\-neutral response envelope
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print help
 \fB\-V\fR, \fB\-\-version\fR
 Print version
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-adapter.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-adapter 1  "adapter 0.31.0" 
+.TH canon-adapter 1  "adapter 0.33.0" 
 .SH NAME
 canon\-adapter \- Validate a provider\-neutral adapter response without executing a provider
 .SH SYNOPSIS
@@ -43,4 +43,4 @@ Examples:
   canon adapter validate \-\-response response.json
   canon adapter validate \-\-response response.json \-\-repo . \-\-json
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-artifacts-move.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-move 1  "move 0.31.0" 
+.TH canon-artifacts-move 1  "move 0.33.0" 
 .SH NAME
 canon\-artifacts\-move \- Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH SYNOPSIS
@@ -54,10 +54,10 @@ Examples:
   canon artifacts move \-\-tier cold
   canon artifacts move \-\-tier cold \-\-commit \-\-plan\-digest <DIGEST>
 
-The bare run previews: it lists every upload and removal and prints a planDigest, and writes nothing. \-\-commit \-\-plan\-digest acts on exactly that plan (PLAN_CHANGED, exit 2, when it changed since).
+The bare run previews: it lists every upload and removal and prints a planDigest, and writes nothing. \-\-commit \-\-plan\-digest acts on exactly that plan (PLAN_STALE, exit 2, when it changed since).
 
 \-\-tier names an `s3` tier of canon.yaml\*(Aqs `tiers:` (for example `cold`; its credentials are the tier\*(Aqs own). Every blob in .canon/artifacts/sha256 is hashed, uploaded under <prefix>sha256/<digest> (prefix artifacts/), and read back; only when all of them verified does canon.yaml gain `artifact_store: { backend: <tier>, prefix: artifacts/ }`, after which the local copies are removed and `.canon/artifacts/` is added to .gitignore. Commit the removal with the ledger.
 
 Idempotent and resumable: a run stopped anywhere leaves a repo the gate still passes, and the next run finishes; a second run finds nothing to do. A blob whose bytes do not match its name is never moved. Moving back to local is refused; `\-\-tier local` on a local repo is a no\-op.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-artifacts-store.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-store 1  "store 0.31.0" 
+.TH canon-artifacts-store 1  "store 0.33.0" 
 .SH NAME
 canon\-artifacts\-store \- Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 .SH SYNOPSIS
@@ -51,4 +51,4 @@ For records written before canon stored bound bytes (0.11\-0.13), and for any ev
 
 Exit 0 when the pass ran (the gate decides whether an unstored file matters), 2 when the ledger cannot be read or a write fails.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-artifacts-verify.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts-verify 1  "verify 0.31.0" 
+.TH canon-artifacts-verify 1  "verify 0.33.0" 
 .SH NAME
 canon\-artifacts\-verify \- Check that the artifact store holds every file the latest evidence and current reviews bind (\-\-full re\-hashes the stored bytes)
 .SH SYNOPSIS
@@ -45,4 +45,4 @@ Asks the store canon.yaml\*(Aqs `artifacts:` block selects (default: local, .can
 
 Exit 0 when every file is stored, 1 when one is missing or altered (data.problems names each), 2 when the store cannot be used or reached: an unreachable store is a refusal, never a pass.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-artifacts.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-artifacts 1  "artifacts 0.31.0" 
+.TH canon-artifacts 1  "artifacts 0.33.0" 
 .SH NAME
 canon\-artifacts \- Check or move the evidence artifact store (local, or an object\-store tier)
 .SH SYNOPSIS
@@ -42,4 +42,4 @@ Store the bound files of existing evidence records and current reviews in the ar
 canon\-artifacts\-move(1)
 Move the local artifact blobs to an object\-store tier, verify them, and remove the local copies
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-brief-approve.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-approve 1  "approve 0.31.0" 
+.TH canon-brief-approve 1  "approve 0.33.0" 
 .SH NAME
 canon\-brief\-approve \- Record the human\*(Aqs approval of the brief, bound to its text; refused while `brief check` has blockers
 .SH SYNOPSIS
-\fBcanon brief approve\fR <\fB\-\-approver\fR> [\fB\-\-as\fR] <\fB\-\-note\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANGE_ID\fR] 
+\fBcanon brief approve\fR <\fB\-\-approver\fR> [\fB\-\-as\fR] <\fB\-\-note\fR> [\fB\-\-relayed\-via\fR] [\fB\-\-actor\fR] [\fB\-\-digest\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANGE_ID\fR] 
 .SH DESCRIPTION
 Record the human\*(Aqs approval of the brief, bound to its text; refused while `brief check` has blockers
 .SH OPTIONS
@@ -32,6 +32,15 @@ orchestrator
 \fB\-\-note\fR \fI<TEXT>\fR
 The human\*(Aqs own words
 .TP
+\fB\-\-relayed\-via\fR \fI<NAME>\fR
+Record the human\*(Aqs answer on their behalf: the tool they were asked with (`ask`, `AskUserQuestion`, `chat`); an agent role may run the call only with it
+.TP
+\fB\-\-actor\fR \fI<ACTOR_ID>\fR
+With \-\-relayed\-via, the agent\*(Aqs actor id (default: the CANON_ACTOR environment variable)
+.TP
+\fB\-\-digest\fR \fI<DIGEST>\fR
+With \-\-relayed\-via, the digest `canon brief show \-\-body` showed the human, as `<change>=<sha256:digest>`, once per change; a brief whose digest differs is refused
+.TP
 \fB\-\-repo\fR \fI<DIR>\fR
 The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
 .TP
@@ -62,4 +71,4 @@ brief (the digest covers the brief without its `Approved:` lines) and records
 not approved (BRIEF_CHANGED_SINCE_APPROVAL) until a human answers again and this
 runs again. Run it only from the human\*(Aqs answer, with their words as \-\-note.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-brief-check.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-check 1  "check 0.31.0" 
+.TH canon-brief-check 1  "check 0.33.0" 
 .SH NAME
 canon\-brief\-check \- Read the brief against the rules: blocker and advisory findings (exit 0 clean, 1 blockers, 2 refused)
 .SH SYNOPSIS
@@ -41,4 +41,4 @@ Print version
 [\fICHANGE_ID\fR]
 The change to read (default: the repo\*(Aqs only live change)
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-brief-show.1

@@ -1,10 +1,10 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief-show 1  "show 0.31.0" 
+.TH canon-brief-show 1  "show 0.33.0" 
 .SH NAME
 canon\-brief\-show \- Show where the change stands and the next one to three steps; never edits
 .SH SYNOPSIS
-\fBcanon brief show\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANGE_ID\fR] 
+\fBcanon brief show\fR [\fB\-\-as\fR] [\fB\-\-body\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fICHANGE_ID\fR] 
 .SH DESCRIPTION
 Show where the change stands and the next one to three steps; never edits
 .SH OPTIONS
@@ -26,6 +26,9 @@ reviewer
 orchestrator
 .RE
 .TP
+\fB\-\-body\fR
+Print the brief file\*(Aqs bytes as they are, then a last line with the approval digest `brief approve` would record (with \-\-json: `body` and `digest` fields); what a human is shown before they answer
+.TP
 \fB\-\-repo\fR \fI<DIR>\fR
 The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
 .TP
@@ -47,4 +50,4 @@ Examples:
 
 The operand names the change; without it the repo\*(Aqs only live change is read.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-brief.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-brief 1  "brief 0.31.0" 
+.TH canon-brief 1  "brief 0.33.0" 
 .SH NAME
 canon\-brief \- Check a change\*(Aqs brief (PRD format) and see the next steps; never edits
 .SH SYNOPSIS
@@ -61,4 +61,4 @@ gets one blocker, `brief.old\-format`: `canon migrate` rewrites it. A brief
 with fewer than two known headings (written before 0.19) checks as `brief.legacy`, an
 advisory. Without \-\-change, the repo\*(Aqs only live change is checked.
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-change-new.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change-new 1  "new 0.31.0" 
+.TH canon-change-new 1  "new 0.33.0" 
 .SH NAME
 canon\-change\-new \- Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 .SH SYNOPSIS
@@ -63,4 +63,4 @@ Print version
 <\fICHANGE_ID\fR>
 The change\*(Aqs slug (its change_id)
 .SH VERSION
-v0.31.0
+v0.33.0

package/man/canon-change.1

@@ -1,6 +1,6 @@
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH canon-change 1  "change 0.31.0" 
+.TH canon-change 1  "change 0.33.0" 
 .SH NAME
 canon\-change \- Write a plan change (.canon/changes/<slug>/brief.md) and adopt it into a subject
 .SH SYNOPSIS
@@ -39,4 +39,4 @@ Write .canon/changes/<slug>/brief.md, import it, and adopt it into a subject
 Examples:
   canon change new add\-login \-\-subject auth \-\-title \*(AqAdd login\*(Aq
 .SH VERSION
-v0.31.0
+v0.33.0