@journeykit/canon 0.27.0 → 0.29.0

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

@@ -1,17 +1,17 @@
 # canon-artifact-ingest
 
-`canon ingest artifacts` turns a repo's canon-native ARTIFACTS — the
+`canon ingest records` turns a repo's canon-native ARTIFACTS — the
 outputs of review/divergence/task/handoff work — into the regime-keyed
 verdict trajectories that strategy memory and the reward gate consume
 (see `canon-learn`). One pass runs the four adapters, normalizes, derives
 verdicts, and writes idempotently.
 
-## `canon ingest artifacts [--repo <dir>] [--watch]`
+## `canon ingest records [--repo <dir>] [--watch]`
 
 ```bash
-canon ingest artifacts                # one pass over the repo's artifacts
-canon ingest artifacts --repo ../svc  # a specific repo
-canon ingest artifacts --watch        # poll loop
+canon ingest records                # one pass over the repo's artifacts
+canon ingest records --repo ../svc  # a specific repo
+canon ingest records --watch        # poll loop
 ```
 
 Source roots resolve from `canon.yaml`'s `artifacts.sources` config
@@ -19,6 +19,10 @@ Source roots resolve from `canon.yaml`'s `artifacts.sources` config
 hardcoded path; ordinarily the consumer repo's own roots. Unconfigured =
 no scan for that family.
 
+**Done when:** the pass exits `0` and reports no malformed artifact;
+`canon query --kind trajectory` lists the new trajectories. A rerun over an
+unchanged corpus writes nothing (`trajectories_skipped_duplicate`).
+
 ## The four adapters
 
 Each reads one artifact family and emits a normalized event keyed by that
@@ -58,7 +62,7 @@ new trajectories (reported as `trajectories_skipped_duplicate`).
 
 Verdicts persist regime-keyed (`<role>/<repo>/<area>/<hash>`), so a
 role-scoped agent reads only its own lane — the same regime namespacing
-`canon retrieve --role <r> --regime <k>` and `canon learn` query. This
+`canon retrieve --for-role <r> --regime <k>` and `canon strategy` query. This
 verdict stream is the evidence the reward gate scores when deciding
 promotion/demotion.
 
@@ -69,4 +73,4 @@ promotion/demotion.
 - Strategy promotion/demotion mechanics — see the `canon-learn` skill;
   this skill only produces the verdict evidence promotion reads.
 - The `regime_key` grammar itself — see `canon-retrieve`, which derives
-  the same key via the `canon regime-key` serializer.
+  the same key via the `canon regime show` serializer.

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

@@ -74,7 +74,7 @@ spec_coverage:
 
 Every feature surface (`<area>.<surface>`) with in-scope scenarios must
 then carry at least one scenario of each listed case, or `canon gate
-check` reports it as `uncovered-cell`, and `canon subject status <id>
+check` reports it as `uncovered-cell`, and `canon subject move <id>
 --to shipped` refuses for a subject that owns such a surface. An untagged
 scenario counts toward its surface but satisfies no case, so an
 untagged corpus reports every surface instead of passing silently. The
@@ -101,13 +101,23 @@ canon scenario new checkout.cart.04 --title "Adding an out-of-stock item is refu
 
 There is no format or sync step after these: the scaffold writes a
 format-clean scenario, and `canon status`, `canon gate check`,
-`canon evidence add`, `canon review add` and `canon subject status`
+`canon evidence add`, `canon review scenario` and `canon subject move`
 index added, edited and deleted `.feature` files before they read. When
 one of them prints `NOT refreshed`, the corpus has a format violation
 (for example a hand-written header with no `# canon:` line) or a
 duplicate id; `canon inventory sync` (or `canon format <root>`) names it.
 Fix it and the next command indexes the files (see `canon-inventory`).
 
+Many scenarios at once: `--input` takes inline JSON, a file or `-`. An
+array (or NDJSON) is a batch, validated whole before anything is written;
+each element holds `operands` (the scenario tag) and the other options as
+camelCase keys. `canon schema scenario new --json` shows the input schema
+and an example. There is no `--from`.
+
+```text
+canon scenario new --input '[{"operands":["checkout.cart.01"],"title":"Adding an item raises the count","subjectId":"checkout-core","lane":"behavior","case":"happy"},{"operands":["checkout.cart.04"],"title":"Adding an out-of-stock item is refused","subjectId":"checkout-core","lane":"behavior","case":"failure"}]'
+```
+
 - `--actor-id <id>` (or `CANON_ACTOR` in the environment) puts YOUR id on the
   provenance line. Default is `canon-scaffold`.
 - **Keep the `# canon:` lines when you fill in the scenario.** Dropping one
@@ -135,6 +145,10 @@ Fix it and the next command indexes the files (see `canon-inventory`).
 - Steps are yours to write; the scaffold's `Given a step` is a
   placeholder, not a spec.
 
+**Done when:** `canon status` shows no `@subject`-less scenario (`data.unowned`
+is empty) and no `NOT refreshed` line appears; the new scenarios then
+wait for evidence, which `canon gate check` reports.
+
 ## Anti-patterns, by name
 
 - **The grab-bag surface.** One `experience.feature` holding pointer

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

@@ -31,9 +31,16 @@ or has no `spec_coverage` section (the gate then requires no evidence,
 cases or review), or when that section is invalid (the gate refuses until
 it is fixed); it is omitted when coverage is in force. `context` describes what CAN be
 authored; `canon status` (see `canon-subject`) says where the repo stands
-and what to run next. `--json` is unchanged: the header adds no field,
-and `policy.spec_coverage`/`policy.diagnostics` already carry the same
-fact.
+and what to run next. `--json` prints the `{ok, data, meta}` envelope: the
+header adds no field, and `policy.spec_coverage`/`policy.diagnostics`
+already carry the same fact. `--fields <list>` keeps only the named
+top-level fields (`kinds`, `enums`, `policy`, `review`, …); an unknown name is
+`UNKNOWN_FIELD` (exit 2).
+
+On a repository that still holds 0.27 canon state, `canon context` warns
+and puts `canon migrate --json` first in `meta.next`: run `canon migrate`
+(a preview), then `canon migrate --commit --plan-digest <digest from the
+preview>`, then `canon skills install`.
 
 ## Reproducible context packs and prompt bundles
 
@@ -43,13 +50,13 @@ an immutable content-addressed registry and records only metadata and digests
 in the pack manifest.
 
 ```bash
-canon context-pack new --manifest .canon/context-manifest.json
-canon context-pack new --manifest .canon/context-manifest.json --repo ../my-repo --json
+canon context-pack add --manifest .canon/context-manifest.json
+canon context-pack add --manifest .canon/context-manifest.json --repo ../my-repo --json
 canon context-pack show sha256:<pack-digest> --repo . --json
 canon context-pack verify sha256:<pack-digest>
 ```
 
-`create` prints only the pack id by default, so captured content is never
+`add` prints only the pack id by default, so captured content is never
 written to concise terminal output. `--json` prints the pack manifest,
 including selected-path metadata and content digests. `show` verifies the
 manifest and immutable content objects before returning it; `verify` exits
@@ -57,6 +64,9 @@ nonzero when the pack is missing, stale, or tampered. Manifest paths must be
 relative to the resolved repo, remain inside it, and contain no symlink;
 missing or unsafe paths are rejected by the context-pack module.
 
+**Done when:** `canon context-pack verify sha256:<pack-digest>` exits `0`;
+`canon context-pack show` returns the manifest you recorded.
+
 ## Provider-neutral adapter responses
 
 An execution provider may return a versioned response envelope for Canon to
@@ -87,9 +97,9 @@ Version prompt inputs separately when several runs should share the same
 prompt files:
 
 ```bash
-canon prompt add --name reviewer --version v1 \
+canon prompt add reviewer@v1 \
   --manifest .canon/reviewer-prompt.json
-canon prompt show --name reviewer --version v1 --json
+canon prompt show reviewer@v1 --json
 ```
 
 Prompt registration uses the same immutable content registry. `prompt show`
@@ -97,7 +107,7 @@ verifies the selected bundle and returns its metadata/digests; neither concise
 output form includes captured prompt bytes.
 
 - **A capability query, never validation:** `canon context` ALWAYS exits
-  `0` with the full surface — even when `canon format --check` or
+  `0` with the full surface — even when `canon format` or
   `canon gate` would report diagnostics against the same repo. It reads
   only the schema/policy/vocabulary registry, never the corpus or the
   evidence ledger.
@@ -154,7 +164,7 @@ AND `canon format`'s diagnostics from one edit site, never two.
 
 ## Reading an "expected one of: …" validator error
 
-When `canon format --check` rejects an out-of-domain enum value it emits:
+When `canon format` rejects an out-of-domain enum value it emits:
 
 ```
 `not-a-real-kind` is not a valid value for `kind` of `run` (expected one of: run, review, divergence, …)
@@ -167,7 +177,7 @@ same schema, no hand-maintained second copy.
 
 ## What this skill does NOT cover
 
-- `canon format --check`'s full violation taxonomy — see `canon-fmt`;
+- `canon format`'s full violation taxonomy — see `canon-fmt`;
   this skill only covers reading its enum diagnostic against the surface.
 - Authoring a typed task atom / handoff body — see
   `canon-vocab`; `canon context`'s `vocab`/`cel` sections

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

@@ -1,6 +1,6 @@
 # canon-fmt
 
-`canon format --check` is canon's read-only format validator over a
+`canon format` is canon's read-only format validator over a
 consumer-repo artifact corpus: ledger records (run/drill/review/clear/
 code-review/design-review), divergence events (manifest/review/
 remediation), `kind=feature/` spec files, `inventory/`, and `policy.yaml`. It never
@@ -9,9 +9,14 @@ rewrites or mutates the corpus — it only validates and reports.
 ## Running
 
 ```bash
-canon format --check <corpus-root>   # e.g. a consumer repo's spec/
+canon format spec   # e.g. a consumer repo's spec/
 ```
 
+With no operand, `canon format` validates every `specs.roots[]` entry of
+`canon.yaml`; a relative `<dir>` resolves under the repo root when `--repo`
+is given, else under the current directory. The old `fmt` spelling
+and the no-op `--check` are gone.
+
 Read-only, always. Exits nonzero if any violation is found, and prints
 a report grouped by failure class in this fixed order:
 
@@ -30,6 +35,9 @@ a report grouped by failure class in this fixed order:
 
 Every class is a stable string, safe to grep/diff across runs.
 
+**Done when:** `canon format` exits `0` and prints no violation; a
+violation names its class and file in the report.
+
 ## What it does NOT do
 
 - **Rewrite anything.** It only validates and reports; a one-shot