@journeykit/canon 0.27.0 → 0.28.0

package/man/canon-context-pack.1

@@ -0,0 +1,50 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-context-pack 1  "context-pack 0.28.0" 
+.SH NAME
+canon\-context\-pack \- Create, inspect, and verify reproducible context packs
+.SH SYNOPSIS
+\fBcanon context\-pack\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Create, inspect, and verify reproducible context packs
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-context\-pack\-add(1)
+Create an immutable context pack from a repository\-local JSON manifest
+.TP
+canon\-context\-pack\-show(1)
+Show a context pack after verifying its manifest and content objects
+.TP
+canon\-context\-pack\-verify(1)
+Verify a context pack\*(Aqs manifest and immutable content objects
+.SH EXTRA
+Examples:
+  canon context\-pack add \-\-manifest .canon/context\-manifest.json
+  canon context\-pack show sha256:<pack\-digest> \-\-repo . \-\-json
+  canon context\-pack verify sha256:<pack\-digest>
+.SH VERSION
+v0.28.0

package/man/canon-context.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-context 1  "context 0.28.0" 
+.SH NAME
+canon\-context \- Show what you can author here: record kinds, fields, enums, policies
+.SH SYNOPSIS
+\fBcanon context\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-fields\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Show what you can author here: record kinds, fields, enums, policies
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-fields\fR \fI<FIELDS>\fR
+With \-\-json, keep only these top\-level surface sections (comma\-separated); an unknown field is refused (camelCase and snake_case both match)
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-dashboard.1

@@ -0,0 +1,50 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-dashboard 1  "dashboard 0.28.0" 
+.SH NAME
+canon\-dashboard \- Serve the local status dashboard
+.SH SYNOPSIS
+\fBcanon dashboard\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-snapshot\fR] [\fB\-\-port\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Serve the local status dashboard
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-snapshot\fR \fI<DIR>\fR
+Snapshot dir to serve (default: regenerated fresh each run)
+.TP
+\fB\-\-port\fR \fI<N>\fR [default: 4173]
+Local port to bind (0 = OS\-assigned free port)
+.TP
+\fB\-\-json\fR
+Print one JSON document naming the address it serves (`data.url`), then serve until stopped; the human lines go to stderr
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-demo-init.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-demo-init 1  "init 0.28.0" 
+.SH NAME
+canon\-demo\-init \- Scaffold the demo repo (gate starts RED)
+.SH SYNOPSIS
+\fBcanon demo init\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Scaffold the demo repo (gate starts RED)
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR [default: .]
+Directory to set up (used as\-is)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-demo-review.1

@@ -0,0 +1,44 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-demo-review 1  "review 0.28.0" 
+.SH NAME
+canon\-demo\-review \- Record the missing reviewer evidence (gate turns GREEN)
+.SH SYNOPSIS
+\fBcanon demo review\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Record the missing reviewer evidence (gate turns GREEN)
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-demo.1

@@ -0,0 +1,47 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-demo 1  "demo 0.28.0" 
+.SH NAME
+canon\-demo \- Try the evidence loop end\-to\-end in a throwaway demo repo
+.SH SYNOPSIS
+\fBcanon demo\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Try the evidence loop end\-to\-end in a throwaway demo repo
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-demo\-init(1)
+Scaffold the demo repo (gate starts RED)
+.TP
+canon\-demo\-review(1)
+Record the missing reviewer evidence (gate turns GREEN)
+.SH EXTRA
+Examples:
+  canon demo init \-\-repo /tmp/canon\-demo && cd /tmp/canon\-demo
+  canon gate check   # RED
+  canon demo review && canon gate check   # GREEN
+.SH VERSION
+v0.28.0

package/man/canon-dispatch-begin.1

@@ -0,0 +1,80 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-dispatch-begin 1  "begin 0.28.0" 
+.SH NAME
+canon\-dispatch\-begin \- Mint a Run manifest with retrieved guidance and context/policy lineage
+.SH SYNOPSIS
+\fBcanon dispatch begin\fR [\fB\-\-as\fR] [\fB\-\-role\fR] <\fB\-\-regime\fR> [\fB\-\-actor\-id\fR] [\fB\-\-session\-id\fR] [\fB\-\-provider\fR] [\fB\-\-model\fR] [\fB\-\-skill\-id\fR] [\fB\-\-skill\-digest\fR] [\fB\-\-manifest\fR] [\fB\-\-prompt\-bundle\fR] [\fB\-\-task\-id\fR] [\fB\-\-parent\-run\-id\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Mint a Run manifest with retrieved guidance and context/policy lineage
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+Role about to run; must equal \-\-regime\*(Aqs leading segment
+.TP
+\fB\-\-regime\fR \fI<KEY>\fR
+Full regime key (<role>/<repo>/<area>/<hash>) to retrieve guidance for
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR [default: canon]
+The dispatching agent\*(Aqs id (recorded as the run\*(Aqs actor)
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The acting session (recorded as actor.session_id); optional
+.TP
+\fB\-\-provider\fR \fI<NAME>\fR
+Declared provider metadata (copied verbatim; never inferred from \-\-actor\-id)
+.TP
+\fB\-\-model\fR \fI<NAME>\fR
+Declared model metadata (copied verbatim)
+.TP
+\fB\-\-skill\-id\fR \fI<ID>\fR
+Skill that contributed to this run
+.TP
+\fB\-\-skill\-digest\fR \fI<DIGEST>\fR
+Declared skill digest; requires \-\-skill\-id
+.TP
+\fB\-\-manifest\fR \fI<FILE>\fR
+Explicit repository\-relative ContextPack input manifest
+.TP
+\fB\-\-prompt\-bundle\fR \fI<NAME@VERSION>\fR
+Registered prompt bundle to select (`name@version`)
+.TP
+\fB\-\-task\-id\fR \fI<TASK_ID>\fR
+Plan task this run serves (<change_id>#<n>); validated against the plan corpus
+.TP
+\fB\-\-parent\-run\-id\fR \fI<RUN_ID>\fR
+RunId (ULID) of the run that dispatched this one
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-dispatch-diff.1

@@ -0,0 +1,41 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-dispatch-diff 1  "diff 0.28.0" 
+.SH NAME
+canon\-dispatch\-diff \- Diff the declared plan DAG against the observed execution graph
+.SH SYNOPSIS
+\fBcanon dispatch diff\fR [\fB\-\-as\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] 
+.SH DESCRIPTION
+Diff the declared plan DAG against the observed execution graph
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH VERSION
+v0.28.0

package/man/canon-dispatch-end.1

@@ -0,0 +1,60 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-dispatch-end 1  "end 0.28.0" 
+.SH NAME
+canon\-dispatch\-end \- Close a dispatched run with a terminal status and an ended_at
+.SH SYNOPSIS
+\fBcanon dispatch end\fR [\fB\-\-as\fR] <\fB\-\-run\-outcome\fR> [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIRUN_ID\fR> 
+.SH DESCRIPTION
+Close a dispatched run with a terminal status and an ended_at
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-run\-outcome\fR \fI<RUN_OUTCOME>\fR
+Terminal outcome: succeeded or failed
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+succeeded
+.IP \(bu 2
+failed
+.RE
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.TP
+<\fIRUN_ID\fR>
+The RunId (ULID) minted by `canon dispatch begin`
+.SH VERSION
+v0.28.0

package/man/canon-dispatch.1

@@ -0,0 +1,45 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-dispatch 1  "dispatch 0.28.0" 
+.SH NAME
+canon\-dispatch \- Begin an agent run with retrieved guidance recorded
+.SH SYNOPSIS
+\fBcanon dispatch\fR [\fB\-\-as\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Begin an agent run with retrieved guidance recorded
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+canon\-dispatch\-begin(1)
+Mint a Run manifest with retrieved guidance and context/policy lineage
+.TP
+canon\-dispatch\-end(1)
+Close a dispatched run with a terminal status and an ended_at
+.TP
+canon\-dispatch\-diff(1)
+Diff the declared plan DAG against the observed execution graph
+.SH VERSION
+v0.28.0

package/man/canon-divergence-accept.1

@@ -0,0 +1,68 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence-accept 1  "accept 0.28.0" 
+.SH NAME
+canon\-divergence\-accept \- Accept a divergent scenario as a tracked known gap (a reviewer step): its latest evidence must be divergent and not the accepting actor\*(Aqs or session\*(Aqs. The acceptance pins that evidence, so new evidence ends it, and lapses at \-\-expiry; until then the ship guard counts the cell as covered while `status` and `gate check` list it as `accepted\-divergence`
+.SH SYNOPSIS
+\fBcanon divergence accept\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] <\fB\-\-reason\fR> <\fB\-\-tracking\fR> [\fB\-\-expiry\fR] <\fB\-\-actor\-id\fR> [\fB\-\-role\fR] [\fB\-\-session\-id\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISCENARIO_ID\fR> 
+.SH DESCRIPTION
+Accept a divergent scenario as a tracked known gap (a reviewer step): its latest evidence must be divergent and not the accepting actor\*(Aqs or session\*(Aqs. The acceptance pins that evidence, so new evidence ends it, and lapses at \-\-expiry; until then the ship guard counts the cell as covered while `status` and `gate check` list it as `accepted\-divergence`
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id of the scenarios. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-reason\fR \fI<TEXT>\fR
+Why the gap is accepted
+.TP
+\fB\-\-tracking\fR \fI<TEXT>\fR
+Where the gap is tracked: an issue URL or reference
+.TP
+\fB\-\-expiry\fR \fI<TIMESTAMP>\fR
+The date (YYYY\-MM\-DD, UTC) the acceptance stops holding; none means it holds until new evidence
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer recording this (recorded as the divergence\*(Aqs reviewer and actor)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+Must be reviewer (default: the declared role, \-\-as / CANON_ROLE; required when none is declared)
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The accepting session (recorded as actor.session_id); it must not be one that attested the scenario\*(Aqs evidence
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.TP
+<\fISCENARIO_ID\fR>
+The accepted scenarios (`<area>.<surface>.<nn>`), one acceptance each, all or nothing
+.SH VERSION
+v0.28.0

package/man/canon-divergence-add.1

@@ -0,0 +1,97 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH canon-divergence-add 1  "add 0.28.0" 
+.SH NAME
+canon\-divergence\-add \- Add a divergence candidate, staged with no run_seq yet (commit it with `canon gate promote \-\-kind divergence`, or in the same run with \-\-promote / `write: { promote: auto }`)
+.SH SYNOPSIS
+\fBcanon divergence add\fR [\fB\-\-as\fR] [\fB\-\-project\-id\fR] [\fB\-\-rev\fR] [\fB\-\-state\fR] [\fB\-\-reason\fR] [\fB\-\-expiry\fR] [\fB\-\-round\fR] <\fB\-\-actor\-id\fR> [\fB\-\-session\-id\fR] [\fB\-\-detail\fR] [\fB\-\-role\fR] [\fB\-\-promote\fR] [\fB\-\-no\-promote\fR] [\fB\-\-repo\fR] [\fB\-\-json\fR] [\fB\-\-input\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fISCENARIO_ID\fR> 
+.SH DESCRIPTION
+Add a divergence candidate, staged with no run_seq yet (commit it with `canon gate promote \-\-kind divergence`, or in the same run with \-\-promote / `write: { promote: auto }`)
+.SH OPTIONS
+.TP
+\fB\-\-as\fR \fI<ROLE>\fR
+The role you act as: planner, implementer, reviewer or orchestrator. Overrides `CANON_ROLE`. `schema` and `context` list only the role\*(Aqs commands, `status` keeps its steps, and `\-\-role` on `evidence add` / `evidence audit` / `review scenario` / `review change` defaults to it
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+planner
+.IP \(bu 2
+implementer
+.IP \(bu 2
+reviewer
+.IP \(bu 2
+orchestrator
+.RE
+.TP
+\fB\-\-project\-id\fR \fI<PROJECT_ID>\fR
+Spec corpus id of the scenario. Required only when canon.yaml configures more than one spec root
+.TP
+\fB\-\-rev\fR \fI<REV>\fR [default: HEAD]
+The commit this record is about: any git revision (`HEAD~1`, a branch, a tag, a short sha); the full sha is recorded with the code tree it saw. The default HEAD records the working tree as it stands (uncommitted code included), and a commit made from it has the same code tree. Outside git, or with no commit, the command refuses (NO_COMMIT)
+.TP
+\fB\-\-state\fR \fI<STATE>\fR [default: open]
+The divergence state to record (deferred needs \-\-reason and \-\-expiry)
+.br
+
+.br
+\fIPossible values:\fR
+.RS 14
+.IP \(bu 2
+open
+.IP \(bu 2
+still\-divergent
+.IP \(bu 2
+resolved
+.IP \(bu 2
+deferred
+.RE
+.TP
+\fB\-\-reason\fR \fI<TEXT>\fR
+Why the divergence is recorded; required with `\-\-state deferred`
+.TP
+\fB\-\-expiry\fR \fI<TIMESTAMP>\fR
+When a deferral lapses (RFC3339 or YYYY\-MM\-DD, UTC); required with `\-\-state deferred`
+.TP
+\fB\-\-round\fR \fI<N>\fR [default: 1]
+The review round this version belongs to (1\-based)
+.TP
+\fB\-\-actor\-id\fR \fI<ACTOR_ID>\fR
+The reviewer recording this (recorded as the divergence\*(Aqs reviewer and actor)
+.TP
+\fB\-\-session\-id\fR \fI<SESSION_ID>\fR
+The acting session (recorded as actor.session_id); optional
+.TP
+\fB\-\-detail\fR \fI<TEXT>\fR
+Free\-text detail recorded on the version (optional)
+.TP
+\fB\-\-role\fR \fI<ROLE>\fR
+The role this record is attributed to (default: the role declared with \-\-as / CANON_ROLE)
+.TP
+\fB\-\-promote\fR
+Promote the record this run staged, in the same run; records others staged stay staged (the default under canon.yaml `write: { promote: auto }`)
+.TP
+\fB\-\-no\-promote\fR
+Keep this write staged even under canon.yaml `write: { promote: auto }`
+.TP
+\fB\-\-repo\fR \fI<DIR>\fR
+The repo to act on (default: the nearest ancestor directory holding a canon.yaml)
+.TP
+\fB\-\-json\fR
+Output JSON instead of the human\-readable form
+.TP
+\fB\-\-input\fR \fI<JSON|FILE|\->\fR
+The arguments as JSON: an object (one run) or an array / NDJSON file or `\-` (a batch); keys are the option names in camelCase, `operands` an array
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.TP
+<\fISCENARIO_ID\fR>
+The scenario (`<area>.<surface>.<nn>`)
+.SH VERSION
+v0.28.0