@journeykit/canon 0.34.0 → 0.35.0

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

@@ -26,193 +26,193 @@ in your ids. Use only the options on a line; never guess one. Ask `canon schema
 
 <!-- canon:generated commands-implementer begin -->
 Every leaf takes `--as <ROLE>` and `--json`; `--repo <DIR>` too, except `completion`, `schema`, `skills show`. `--input <JSON|FILE|->` runs a leaf from one JSON document (an array is a batch) and is only on the lines ending `[--input]`. Its document keys are the option names in camelCase, singular even when the option repeats (the value is then an array), and `operands` holds the operands. `--fields <FIELDS>` is a comma list of the paths `canon schema <COMMAND> --json` declares under `outputs[].fields.paths`; a path is the record's own key, spelled as the answer spells it.
-In a syntax line `<X>` is a value, `[x]` optional, `a | b` a choice, `(a | b)` exactly one is required, `[--x <V>]*` may repeat, `<X>+` is one or more, `[--a --b <V>]` go together. An option that is not on the line does not exist: it is refused (`USAGE`).
+A `usage:` line shows the syntax and is not itself a command to run (the runnable example under it is): `<X>` is a value, `[x]` optional, `a | b` a choice, `(a | b)` exactly one is required, `[--x <V>]*` may repeat, `<X>+` is one or more, `[--a --b <V>]` go together. An option that is not on the line does not exist: it is refused (`USAGE`).
 
 ```text
 # Write the shell completion script for canon (bash, zsh or fish)
-canon completion <SHELL>
+usage: canon completion <SHELL>
 ```
 ```bash
 canon completion zsh --json
 ```
 ```text
 # Show what you can author here: record kinds, fields, enums, policies
-canon context [--fields <FIELDS>]
+usage: canon context [--fields <FIELDS>]
 ```
 ```bash
 canon context --json
 ```
 ```text
 # Create an immutable context pack from a repository-local JSON manifest
-canon context-pack add --manifest <FILE> [--input]
+usage: canon context-pack add --manifest <FILE> [--input]
 ```
 ```bash
 canon context-pack add --manifest .canon/context-manifest.json --json
 ```
 ```text
 # Show a context pack after verifying its manifest and content objects
-canon context-pack show <PACK_ID>
+usage: canon context-pack show <PACK_ID>
 ```
 ```bash
 canon context-pack show sha256:0000000000000000000000000000000000000000000000000000000000000000 --json
 ```
 ```text
 # Verify a context pack's manifest and immutable content objects
-canon context-pack verify <PACK_ID>
+usage: canon context-pack verify <PACK_ID>
 ```
 ```bash
 canon context-pack verify sha256:0000000000000000000000000000000000000000000000000000000000000000 --json
 ```
 ```text
 # Add a divergence candidate, staged with no run_seq yet
-canon divergence add <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
+usage: canon divergence add <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--state <open|still-divergent|resolved|deferred>] [--reason <TEXT>] [--expiry <TIMESTAMP>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon divergence add auth.login.01 --actor alice --role reviewer --json
 ```
 ```text
 # Directly record a deferred divergence (requires --reason/--expiry)
-canon divergence defer <SCENARIO_ID> --actor <ACTOR_ID> --reason <TEXT> --expiry <TIMESTAMP> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--role <ROLE>] [--input]
+usage: canon divergence defer <SCENARIO_ID> --actor <ACTOR_ID> --reason <TEXT> --expiry <TIMESTAMP> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--role <ROLE>] [--input]
 ```
 ```bash
 canon divergence defer auth.login.01 --actor alice --reason "waiting on the vendor" --expiry 2030-01-01T00:00:00Z --role reviewer --json
 ```
 ```text
 # List the current divergence burn-down state
-canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon divergence list [--as-of <TIMESTAMP>] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon divergence list --as-of 2030-01-01 --json
 ```
 ```text
 # Directly record a resolved divergence
-canon divergence resolve <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--input]
+usage: canon divergence resolve <SCENARIO_ID> --actor <ACTOR_ID> [--project <PROJECT_ID>] [--rev <REV>] [--round <N>] [--session <SESSION_ID>] [--detail <TEXT>] [--role <ROLE>] [--input]
 ```
 ```bash
 canon divergence resolve auth.login.01 --actor alice --role reviewer --json
 ```
 ```text
 # Record one attributed EvidenceRecord for a task or scenario
-canon evidence add [--task <TASK_ID> | --all-scenarios] [--project <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--scenario <SCENARIO_ID> | --all-scenarios] [--run <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--approver <NAME> | --all-scenarios] [--approval-role <human> | --all-scenarios] [--signature-file <FILE> | --all-scenarios] [--approval-at <TIMESTAMP> | --all-scenarios] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> | --all-scenarios]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+usage: canon evidence add [--task <TASK_ID> | --all-scenarios] [--project <PROJECT_ID>] [--class <CLASS>] [--ref <TEXT>] [--verdict <faithful|not-applicable|divergent>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--scenario <SCENARIO_ID> | --all-scenarios] [--run <RUN_ID>] [--surface-ref <PATH_OR_EFFECT>]* [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--approver <NAME> | --all-scenarios] [--approval-role <human> | --all-scenarios] [--signature-file <FILE> | --all-scenarios] [--approval-at <TIMESTAMP> | --all-scenarios] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> | --all-scenarios]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon evidence add --scenario auth.login.01 --class test-run --ref "npm test" --role implementer --json
 ```
 ```text
 # Emit exact bytes for external `ssh-keygen -Y sign -n canon-approval-v1`
-canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task <TASK_ID>] [--project <PROJECT_ID>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
+usage: canon evidence approval-payload --approver <NAME> --approval-at <TIMESTAMP> [--task <TASK_ID>] [--project <PROJECT_ID>] [--scenario <SCENARIO_ID>] [--run <RUN_ID>] [--rev <REV>] [--surface-ref <PATH_OR_EFFECT>]*
 ```
 ```bash
 canon evidence approval-payload --scenario auth.login.01 --project root --approver alice --approval-at 2030-01-01T00:00:00Z --json
 ```
 ```text
 # Record an external evaluator's re-audit of one scenario (class `audit`; the verdict follows --audit-result; canon never runs the evaluator)
-canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+usage: canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer --json
 ```
 ```text
 # Create a fresh .feature file for a new area.surface
-canon feature new <SURFACE> --title <TEXT> [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--project <PROJECT_ID>] [--input]
+usage: canon feature new <SURFACE> --title <TEXT> [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
 canon feature new billing.invoice --title Invoices --json
 ```
 ```text
 # List a change's committed findings at their latest version
-canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon finding list --change <CHANGE_ID> [--open] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon finding list --change add-login --json
 ```
 ```text
 # Validate a spec/artifact corpus against canon's format
-canon format [<DIR>]
+usage: canon format [<DIR>]
 ```
 ```bash
 canon format .canon/specs --json
 ```
 ```text
 # Run the coverage/ledger/staleness/trust checks (0 clean, 1 red, 2 usage)
-canon gate check [--release]
+usage: canon gate check [--release]
 ```
 ```bash
 canon gate check --json
 ```
 ```text
 # Promote staged records (evidence, findings, divergences) to the committed ledger
-canon gate promote [--kind <evidence|finding|divergence>] [--dry-run] [--input]
+usage: canon gate promote [--kind <evidence|finding|divergence>] [--dry-run] [--input]
 ```
 ```bash
 canon gate promote --kind evidence --json
 ```
 ```text
 # Validate each spec root, then materialize scenario index records
-canon inventory sync [--spec-root <DIR>] [--dry-run] [--input]
+usage: canon inventory sync [--spec-root <DIR>] [--dry-run] [--input]
 ```
 ```bash
 canon inventory sync --json
 ```
 ```text
 # Read stored records across every storage tier
-canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon query --kind evidence --json
 ```
 ```text
 # Fetch role-scoped strategy guidance
-canon retrieve --for-role <ROLE> (--regime <KEY> | --domain <NAME>) [--subject <SUBJECT_ID> (with --domain)] [--limit <N>]
+usage: canon retrieve --for-role <ROLE> (--regime <KEY> | --domain <NAME>) [--subject <SUBJECT_ID> (with --domain)] [--limit <N>]
 ```
 ```bash
 canon retrieve --for-role reviewer --domain dev --limit 20 --json
 ```
 ```text
 # Append a tagged scenario stub to its .feature file (created if missing); many at once with `--input`
-canon scenario new <SCENARIO_ID> --title <TEXT> [--subject <SUBJECT_ID>] [--lane <NAME>] [--case <NAME>] [--flow <FLOW_ID>] [--change <CHANGE_ID> (with --flow)] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--feature <FILE>] [--project <PROJECT_ID>] [--input]
+usage: canon scenario new <SCENARIO_ID> --title <TEXT> [--subject <SUBJECT_ID>] [--lane <NAME>] [--case <NAME>] [--flow <FLOW_ID>] [--change <CHANGE_ID> (with --flow)] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--feature <FILE>] [--project <PROJECT_ID>] [--input]
 ```
 ```bash
 canon scenario new auth.login.02 --title "Sign out" --feature .canon/specs/kind=feature/area=auth/login.feature --json
 ```
 ```text
 # Describe canon's own commands
-canon schema [<PATH>]* [--errors | --error <CODE> | --warning <CODE> | --warnings]
+usage: canon schema [<PATH>]* [--errors | --error <CODE> | --warning <CODE> | --warnings]
 ```
 ```bash
 canon schema evidence add --json
 ```
 ```text
 # Search records, brief sections and scenario text, with each hit's neighbors in the record graph
-canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
+usage: canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
 ```
 ```bash
 canon search timeout --kind finding --json
 ```
 ```text
 # Print a guide built into this binary (markdown on stdout); the installed SKILL.md is a stub that points here
-canon skills show <NAME> [--full]
+usage: canon skills show [<NAME>] [--full]
 ```
 ```bash
 canon skills show canon --full --json
 ```
 ```text
 # Show where this repo stands: subjects by status, their gaps, and the next commands
-canon status [--fields <FIELDS>]
+usage: canon status [--fields <FIELDS>]
 ```
 ```bash
 canon status --json
 ```
 ```text
 # Flip one task checkbox, gated on real evidence (fails closed)
-canon task done <TASK_ID> [--input]
+usage: canon task done <TASK_ID> [--input]
 ```
 ```bash
 canon task done add-login#1 --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-canon trace <ID>
+usage: canon trace <ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -252,7 +252,7 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    JSON array: inline, a file or `-` for stdin, one object per scenario whose
    keys are the option names in camelCase plus `operands` (the scenario id);
    every element is validated before the first write, so a bad element
-   writes nothing and `error.field` names it (`/items/1/case`).
+   writes nothing and `error.field` names it (`/1/case`).
    `canon schema scenario new --json` shows `input`: the schema of one document and a complete `example`.
    (`scenario new --from` is gone.) When the gate asks for a missing case
    (`require_cases`), add a new scenario; never retag an existing one. Every