@journeykit/canon 0.6.0 → 0.8.0

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

@@ -0,0 +1,214 @@
+# canon-session-ingest
+
+`canon ingest sessions` turns every agent CLI's on-disk transcript store
+into `Session`/`Run`/`Event` records on canon's join spine, scanning four
+adapters, normalizing, and persisting through the same tier resolution
+`canon query` / `canon tier age` use. The default corpus is scoped to the
+current PROJECT; the watermark gate is per-file; user directives are
+metadata-only unless explicitly opted in by bounded privacy config.
+
+**Quick start needs zero docker/services.** `canon init` scaffolds `hot`
+as a local sqlite file (`.canon/hot.db`) with `session`/`run`/`event`
+already routed to it — a fresh repo's FIRST `canon ingest sessions`
+persists real records with no `docker compose` stack, no `CANON_PG_DSN`,
+no live database. Swap `hot` to postgres (the commented stanza `canon
+init` ships beside the sqlite one) once team-scale multi-agent
+concurrency outgrows sqlite's single-writer mode.
+
+## `canon ingest sessions [--watch] [--interval-secs N] [--home <dir>] [--canon-yaml <path>] [--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)
+```
+
+## The four adapters
+
+Registered in order: **`omp`** (omp/pi sessions), **`hermes`**,
+**`claude`** (`~/.claude/projects/**/*.jsonl`), **`codex`**
+(`${CODEX_HOME:-~/.codex}/sessions/` unioned with `archived_sessions/`).
+Each resolves its default root and honors an env override
+(`CANON_INGEST_OMP_SESSIONS_DIR`, `CANON_INGEST_CLAUDE_SESSIONS_DIR`,
+`CODEX_HOME`, `HERMES_HOME`). An absent source root is a zero-record,
+non-fatal skip.
+
+### Per-source root overrides (`canon.yaml`)
+
+```yaml
+ingest:
+  sources:
+    omp:
+      roots: [/data/omp-sessions]   # relative paths resolve against the canon.yaml dir
+    codex:
+      roots: []                      # explicit empty = scan ZERO (not the default)
+```
+
+A source with a **present** `roots` scans exactly those (explicit
+`roots: []` scans nothing); a source whose key or `roots` is **absent**
+keeps its env-override + default resolution. Unlike artifacts (where
+unconfigured = no scan), sessions default to their home roots when
+unconfigured. A PRESENT but broken `ingest:` section fails **loud** (a
+typo like `root:` for `roots:`, an unknown source id, or a non-YAML
+canon.yaml) rather than silently scanning the wrong corpus; a
+missing/unreadable canon.yaml stays a soft no-config.
+
+## Project scope — the default corpus
+
+`canon ingest sessions` defaults to THIS PROJECT's sessions, never the
+whole machine: the repo's main `git worktree` root plus every linked
+worktree (`git worktree list --porcelain`). Outside a git repo, the scope
+fails soft to the repo root alone.
+
+- **omp/pi and Claude Code are cwd-partitioned on disk** — one
+  subdirectory per project. Out-of-scope subdirectories are pruned at
+  enumerate time — never read or counted.
+- **Codex and Hermes are not partitioned** — rows are filtered
+  post-parse by workspace membership; a row with no captured workspace is
+  kept, fail-soft.
+- **`--all-workspaces`** restores the machine-wide scan. Scope is still
+  resolved (so `project_key` stamping stays correct); only the
+  pruning/filtering are disabled.
+- Every ingested session whose workspace resolves into the active project
+  gets `project_key` stamped to the MAIN worktree's key, so `canon query
+  --kind session` aggregates a whole project's sessions regardless of
+  which worktree recorded them.
+- The run summary's first line always names the active scope:
+  `scope: project /repo/root (2 roots)` or `scope: all workspaces`.
+
+### Provenance, digests, and parser generations
+
+The parser semantics are compared against Tokscale upstream at
+https://github.com/junhoyeo/tokscale (revision
+`fe72e1f9b5a2b1a927108b353a9730a5c631a196`); the cache-accounting comparison
+reference is commit
+[`2cd6c648df026fb43d37e492efa9c344e2d681ee`](https://github.com/junhoyeo/tokscale/commit/2cd6c648df026fb43d37e492efa9c344e2d681ee).
+Canon ports the selected parser semantics, including Claude's nested
+cache-write buckets, but does **not** vendor Tokscale's pricing or cache
+service.
+
+Three identities are intentionally distinct:
+
+* the raw file SHA-256 watermark identifies unchanged transcript bytes;
+* the normalized content digest is canonical JSON over the complete
+  normalized event and changes when normalized token detail changes; and
+* the parse-generation cursor identity combines adapter id and parse version,
+  forcing a re-read when parser semantics change even if raw bytes do not.
+
+## The watermark — per-file, incremental `--watch`
+
+Each pass content-digests every present (post-pruning) file and diffs it
+against its source's persisted cursor (under
+`<repo>/.canon/ingest/cursors/`, gitignored), written after a durable
+pass. A file whose digest matches its cursor is SKIPPED — never parsed; a
+new or changed file is (re-)parsed. One session derives from exactly one
+file, so a single growing transcript re-parses alone instead of dragging
+the whole source back through parse/persist.
+
+- The gate is sound: a file is skipped only when its digest matches the
+  cursor, so a new, changed, copied, or restored file is always
+  re-scanned.
+- Correctness never depends on the cursor: a missing/corrupt cursor
+  treats every present file as new, and the digest-idempotent write path
+  keeps any rescan from double-writing.
+- A cursor's identity carries its adapter's PARSE VERSION as well as its
+  files, so changing an adapter's normalization re-reads that adapter's
+  transcripts instead of reporting them unchanged — no `--full`, no
+  cursor deletion. Version `1` IS the bare `client_id` (`omp.json`), so a
+  cursor already on disk is never invalidated just by installing the
+  mechanism; a bump appends the suffix (`claude-code-v3.json`) and that
+  `omp` is at `2` because the logical adapter now deduplicates forks
+  across files; `hermes` remains at `1`; `codex` is at `2` because its
+  reasoning-token accounting is split; and `claude-code` is at `3` because
+  cache accounting now recognizes `cache_write_1h` buckets. Each changed
+  adapter re-reads once to backfill the normalization change that the old
+  watermark would otherwise hide.
+
+**`--full`** ignores the cursors and re-parses every present in-scope
+file (a full rescan / cursor reset) — safe because a byte-identical
+resubmission is a no-op; cursors re-advance afterward.
+
+## User directives
+
+Every adapter (except Hermes, whose format carries no user-turn text)
+emits one parsed `DirectiveRow` per USER-role message. Parsing retains
+source text only in memory; the shared post-adapter privacy boundary
+controls whether it becomes a durable event. The default when
+`ingest.sessions.privacy` is absent is metadata-only: no
+`user_directive` event reaches normalized output.
+
+Repositories that explicitly opt in MUST set a positive bound:
+
+```yaml
+ingest:
+  sessions:
+    privacy:
+      capture_user_directives: true
+      max_directive_chars: 4096
+```
+
+Captured text is classified and redacted BEFORE the Unicode-scalar capture
+bound is applied. The conservative classifier replaces known API
+key/token/password assignments, bearer credentials, PEM private keys, and
+email addresses with deterministic `[REDACTED_SECRET_N]` /
+`[REDACTED_PII_N]` placeholders and includes `redaction_counts`. The
+detail's `redacted` is true only when a known value was replaced;
+`truncated` is independent and may be true for otherwise unredacted text.
+This classifier is not a guarantee against every kind of secret or PII.
+`workspace_key`/`workspace_label` remain metadata. The source transcript
+remains the source of truth and is not rewritten, purged, or replaced by
+Canon's normalized event.
+
+The source cursor identity includes the privacy mode and positive bound, so
+toggling capture or changing its bound re-scans unchanged source bytes.
+Re-scans retain stable event sequence/key ordinals; they do not purge
+previously stored normalized records. Operators owning pre-existing raw
+data MUST handle purge/migration separately.
+
+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"
+```
+
+## Reading the run summary
+
+Each pass prints the active scope, one line per adapter, then totals:
+
+```
+scope: project /Users/me/Workspace/canon (2 roots)
+omp: 3 file(s) scanned, 1 reparsed, 2 skipped unchanged (watermark), 4 row(s) parsed, 0 malformed record(s)
+claude-code: 1 file(s) scanned, 0 reparsed, 1 skipped unchanged (watermark), 0 row(s) parsed, 0 malformed record(s)
+sessions normalized: 4
+malformed records (corrupt line/db, counted as violations): 0
+rows skipped (malformed session_id): 0
+runs written: 4
+events written: 37
+```
+
+- **scope** — the active project scope (`--all-workspaces` names it).
+- **file(s) scanned** — every present file this source matched, after
+  pruning, before the per-file gate.
+- **reparsed** — the subset actually (re-)parsed this pass (`0` on a
+  steady-state pass).
+- **skipped unchanged (watermark)** — files skipped because that file's
+  digest was byte-identical to its cursor entry.
+- **malformed records** — corrupt lines / dbs an adapter hit but could
+  not extract a row from (counted as a violation, never crashing).
+- **store tiers unreachable** — if `canon.yaml`'s tiers aren't reachable
+  (e.g. `tiers.pg` set but `CANON_PG_DSN` unset) or `session`/`run`/
+  `event` aren't routed, the pass prints a metadata-only JSON fallback
+  instead of persisting — never a partial write. The fallback contains
+  scope, adapter counts, record counts, IDs/digests, and a stable
+  routing/tier failure class/reason; it never contains directive text,
+  task/context prose, or raw event detail.
+
+## What this skill does NOT cover
+
+- Artifact/verdict ingestion (`canon ingest artifacts`) — a different
+  pipeline; see the `canon-artifact-ingest` skill.
+- Cost-parity computation — omp/pi's own cost is `0.0`/`Unknown` per the
+  ported behavior.

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

@@ -0,0 +1,152 @@
+# canon-storage
+
+canon stores every record in one of three capability **rungs**:
+
+- `local` — diffable files in the repo (git-backed), zero network.
+- `hot` — live-queryable state (sqlite or postgres).
+- `cold` — bulk archive (s3).
+
+A rung is a *role*; which backend implements it is a separate
+declaration. `routing:`/`aging:` name a rung (`local`/`hot`/`cold`),
+never a backend name. `tiers.<rung>.backend:` names the backend.
+
+## Backends and their config
+
+| backend    | rung role | `tiers.<rung>` config              | credentials / network |
+| ---------- | --------- | ---------------------------------- | --------------------- |
+| `git`      | local     | `root:` (relative to canon.yaml)   | none — zero network   |
+| `sqlite`   | hot       | `path:` (relative to canon.yaml)   | none                  |
+| `postgres` | hot       | `dsn_env:` + `schema:`             | live network + creds  |
+| `s3`       | cold      | `bucket_env:` + `prefix:`          | live network + creds  |
+
+`canon init` scaffolds `sqlite` as the zero-dependency `hot` default
+(WAL journal + busy timeout, fine for one operator's batch ingest).
+sqlite is a **single-writer store**: for heavy multi-agent concurrent
+writers, swap the `hot` rung to `postgres` — same hot role, a one-block
+canon.yaml swap (the scaffold ships the postgres stanza commented right
+beside the sqlite one). A postgres/s3 rung that can't attach fails loud
+at startup — never a silent fallback to local files.
+
+```yaml
+tiers:
+  local: { backend: git, root: .canon/ledger }
+  hot:   { backend: sqlite, path: .canon/hot.db }
+  # hot: { backend: postgres, dsn_env: CANON_PG_DSN, schema: canon }
+  cold:  { backend: s3, bucket_env: CANON_BUCKET, prefix: canon/ }
+```
+
+Using a backend name (`git`/`pg`/`s3`) where a rung is expected is
+rejected with a hint:
+
+```
+canon.yaml TierPolicy: `git` is a BACKEND name, not a rung — canon.yaml's
+`routing`/`aging`/`tiers` keys now name a capability rung
+(local/hot/cold); declare the backend separately via
+`tiers.<rung>.backend: git`
+```
+
+## Routing a record kind
+
+`routing:` is the only place a kind's rung is decided. Keys are the
+stable snake_case kind wire strings (`change`, `evidence_record`,
+`strategy_item`, …) — the same string the record's own `kind` field
+serializes to. Values are `local`/`hot`/`cold`.
+
+```yaml
+routing:
+  scenario: local   # change this to move FUTURE `scenario` writes
+```
+
+Changing a routing value moves future writes only; re-run reads
+resolve the policy live. An unknown kind or rung name is a loud config
+parse error. Every record kind needs a `routing:` entry — an unrouted
+kind fails hard at its first write/query, never silently dropped.
+
+## Aging a kind to another rung
+
+`aging:` moves records from their routed rung to a `to:` rung once
+their age exceeds `after:`:
+
+```yaml
+aging:
+  handoff: { after: 30d, to: cold }   # <n>d/h/m/s — one integer, one unit
+```
+
+`canon tier age` applies every `aging:` rule once. It is
+content-digest idempotent: re-running finds nothing left to move
+(`moved == 0`); a partial run (destination written, source not deleted)
+re-selects the record but the destination write is a no-op. A kind
+split across two rungs (some aged, some not) still reads correctly —
+`canon query` fans out.
+
+## Running `canon tier age` / `canon query`
+
+Both take `--canon-yaml <path>` (default `canon.yaml` in the current
+directory).
+
+```bash
+# Preview what would move (read-only; writes/deletes nothing).
+canon tier age --dry-run
+
+# Apply every `aging:` rule once (the destructive move+delete).
+canon tier age
+
+# Read a kind, fanning out across its routed rung AND its aging
+# destination, merged by time. --kind is the kind wire string — the
+# same vocabulary as routing:/aging: (`change`, `handoff`, …).
+canon query --kind handoff --since 2026-06-01T00:00:00Z
+
+# Machine-readable output instead of the human table.
+canon query --kind trajectory --json
+```
+
+## What `canon report` does and doesn't read
+
+canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report`
+builds its numbers from the `mart_` views. Those read ONLY local roots
+— the git ledger and a LOCAL `.canon/r2` parquet mirror. `canon report`
+never opens a live DB connection or the live bucket, so:
+
+- Kinds routed to `hot` (sqlite/postgres) do NOT appear in `canon
+  report`.
+- Kinds routed to `cold` (s3) appear only if a local `.canon/r2` mirror
+  has been separately materialized — there is no automatic sync.
+
+These kinds are not lost: read them with `canon query --kind <kind>`.
+The gap is named loud, not under-counted — when any routed kind isn't
+report-readable, `canon report` renders a `## Kinds not read directly`
+section listing them and emits a matching stderr `WARN`.
+
+## Retention, export, and access audit
+
+`canon purge --kind <kind> --before <RFC3339> [--repo <dir>] [--dry-run] [--json]`
+is the canonical data-lifecycle boundary. The only purgeable kinds are
+`session`, `run`, `event`, and `trajectory`; the cutoff applies to every
+routed rung and every configured aging destination, including retained
+historical versions. For `trajectory`, the command also purges the
+operator-local Parquet learn store under `learn.root` in `canon.yaml`;
+an unavailable configured learn root is an explicit error, never a
+successful zero-row purge. The operation is idempotent. Apply mode
+preflights all attached destinations before the first delete, but storage
+backends are not one transaction: a failure after a prior delete returns
+an explicit `partial` result with matched/deleted counts and a nonzero
+status. Purge never rewrites Git history or deletes source transcript
+files.
+
+`canon export --kind <kind> [--before <RFC3339>] [--after <RFC3339>]
+[--out <file>] [--json]` emits a versioned manifest containing source scope,
+counts, digests, and redacted metadata. It does not authorize backend access;
+credentials remain an operator prerequisite. New output files are mode
+`0600`. Raw event detail text is excluded unless `--include-sensitive` is
+passed and `.canon/policy.yaml` explicitly contains:
+
+```yaml
+query:
+  allow_sensitive: true
+```
+
+Every query, export, and purge appends an actor-stamped record to
+`.canon/audit/access.jsonl` (mode `0600` on creation). `CANON_ACTOR` takes
+precedence over the OS username. Audit rows contain operation, kind, scope,
+sensitive flag, counts, and timestamp only—never query text, secrets, or
+record bodies.

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

@@ -0,0 +1,161 @@
+# canon-subject
+
+A **Subject** is canon's first-class handle on the durable product unit a
+team plans, designs, builds, verifies, and ships across MANY changes and
+MANY scenarios. This skill covers the subject-write-first contract every
+domain agent follows.
+
+## Vocabulary rule (non-negotiable)
+
+- **"feature docs" / ".feature files" = Gherkin behavior specs** — the
+  `.feature` corpus `canon format`/`canon inventory sync` validate. "Read
+  the feature docs" ALWAYS means the Gherkin files, never a Subject.
+- **"subject" = the management record** authored by `canon subject new`.
+  A Subject is the product unit; its `.feature` files are its behavior
+  specs. Never the same word.
+
+A Subject links, but does not contain, its work: `change_ids` (adopted
+plan units) and `scenario_ids` (behavior specs) are join links.
+
+## The 4-step loop
+
+Every substantial piece of work starts at a subject write.
+
+### 1. Context → author or update the Subject FIRST
+
+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
+canon subject new subject-domain-loop \
+  --domain dev --title "Subject domain loop" \
+  --summary "The durable product unit + its per-domain loop" \
+  --owner-role implementer
+```
+
+- `<id>` is a kebab-case slug (`[a-z0-9]+(-[a-z0-9]+)*`) — the durable
+  `subject_id` join key, never renumbered once assigned.
+- `--domain <d>` is checked twice at write: SHAPE (a kebab-case slug),
+  then MEMBERSHIP against the domain set THIS repo has activated.
+  Canon ships no opinion about how a team slices its work — the set is
+  resolved from the vocabulary, so a studio declaring
+  `combat`/`economy`/`live-ops` authors against those and canon's base
+  set (`planning`, `design`, `dev`, `data`, `test`, from `canon.core`)
+  carries no authority there. Extend or replace it in your own
+  `.canon/vocab/<id>/enums.yaml` under the `domain` key, activated by a
+  `canon.project.yaml` profile (see `canon-vocab`) — never a canon code
+  change. A non-member is refused with the legal set named
+  (`expected one of: …`), so a typo cannot silently mint a category that
+  then splits every `--domain`-filtered read. A repo that declares no
+  `domain` enum has no constraint and accepts any slug. Run
+  `canon context` to see the set in force.
+- `--summary` is optional; `--owner-role` defaults to `implementer`;
+  `--actor-id` defaults to `canon`. A freshly-authored Subject with no
+  `change_ids`/`scenario_ids` is a valid minimal record and starts at
+  status `proposed`. `--json` prints the written record.
+
+### 2. Retrieve subject-scoped strategy memory BEFORE working
+
+```bash
+canon retrieve --role dev --domain dev --subject subject-domain-loop --k 5
+```
+
+- `--regime <key>` XOR the derived pair `--domain <d> [--subject <id>]`:
+  give the full regime key directly, OR let retrieval derive it. Never both.
+- With `--domain`/`--subject`, retrieval tries `<domain>-<subject_id>`
+  first, then `<domain>` — a subject's own lessons win, falling back to
+  the domain's shared memory when the subject is new.
+- Fail-soft: an empty/missing store degrades to an empty guidance list,
+  never a nonzero exit. See `canon-retrieve` for the full contract.
+
+### 3. Work → pin every artifact to `subject_id`
+
+- **Scenarios**: `canon scenario new <tag> --subject <subject-id>` emits
+  the `@subject:<subject-id>` tag; `canon inventory sync` maps the tag
+  onto the scenario's `subject_id`. A malformed/absent tag leaves it
+  unset (fail-soft), never an error. See `canon-authoring`.
+- **Changes**: adopt imported plan changes under the Subject (see
+  [Adopt flow](#adopt-flow)).
+- **Reviews / evidence / divergences**: authored as usual (`canon review
+  add`, `canon gate`, `canon divergence …`) against the Subject's
+  scenarios — the join spine carries them back through `scenario_id`.
+
+### 4. Verdicts / trajectories → learn (knowledge out)
+
+As work is reviewed, verdicts ingest under the subject-scoped regime
+(`canon ingest artifacts`), so `canon learn` distills strategies keyed to
+this subject and domain — the exact memory step 2 retrieves next time.
+
+## Status lifecycle + the shipped evidence gate
+
+`canon subject status <id> <state>` performs a policy-gated transition.
+The legal chain:
+
+```
+proposed → specced → building → verifying → shipped
+```
+
+plus **any state → retired** (a subject can be retired from anywhere).
+Any other transition is rejected by failure class, exits 1, and leaves
+the record UNCHANGED (fail closed).
+
+```bash
+canon subject status subject-domain-loop specced
+canon subject status subject-domain-loop building
+canon subject status subject-domain-loop verifying
+canon subject status subject-domain-loop shipped   # gated — see below
+```
+
+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.
+
+**Corpus-wide, the same join:** `canon gate check` with
+`.canon/policy.yaml`'s opt-in `spec_coverage` section generalizes this
+gate past one transition — it left-joins the WHOLE Scenario corpus
+against evidence, so an unimplemented or mismatched spec is reported
+whether or not a Subject links it. `spec_coverage.scope` narrows
+blocking to subjects in named statuses, and `@subject:<id>` tagging is
+what brings a scenario into that scope. See `canon-gate`.
+
+**The `verifying → shipped` evidence gate:** shipping additionally
+requires that EVERY linked `scenario_ids` entry carries a latest,
+non-`Divergent` verdict in the ledger (the same last-wins rule `canon
+gate check` uses). If any linked scenario is uncovered or its latest
+verdict is `Divergent`, the transition prints the violating scenarios by
+failure class, exits 1, and the status stays `verifying`. `retired` is
+not gated.
+
+## Adopt flow
+
+Planning docs become change/task records via `canon ingest plans` (see
+`canon-plan-import`), but that stops at import. `canon subject adopt`
+lifts an imported change into a managed Subject:
+
+```bash
+canon ingest plans --repo .                          # import → change/task rows
+canon subject adopt subject-domain-loop-plan \
+  --subject subject-domain-loop                        # link change → subject
+```
+
+`adopt` stamps the change's `subject_id` and adds it to the Subject's
+`change_ids`, so `canon query --kind change --change-id …` and `canon
+query --kind subject` agree on the link from both ends.
+
+## Reading the per-domain management view
+
+```bash
+canon query --kind subject --domain dev --status building
+canon report --repo .        # renders the "Subjects" panel
+```
+
+- `canon query --kind subject [--domain <d>] [--status <s>]` — the
+  per-domain management view; `--domain`/`--status` are subject-only
+  filters.
+- `canon report`'s **Subjects** panel is a per-domain rollup: one row per
+  subject (`domain`, `subject_id`, `title`, `status`, `scenario_count`,
+  `covered_scenarios`), where `covered_scenarios` counts linked scenarios
+  carrying a latest non-`Divergent` verdict — the same coverage the
+  shipped gate enforces, surfaced read-only. Also exported by `canon
+  report --snapshot` (see `canon-report-dashboard`).

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

@@ -0,0 +1,115 @@
+# canon-vocab
+
+Canon's typed authoring layer replaces a freeform `tasks.md` checkbox's
+implicit evidence with a structured, checker-validated, policy-resolved
+attribute — and gives handoff bodies a declared, rendered template. You
+declare a vocabulary in a `.canon/vocab/<id>/` plugin, then author atoms
+that the checker validates against it.
+
+## Run `canon context` FIRST
+
+Before authoring any atom, run `canon context` (or `--json`) and read its
+`vocab` section: it lists every declarable directive + enum for the repo
+plus a content-hash version. Authoring against a directive/enum
+`canon context` does not list means the checker will reject it — the
+surface is the source of truth for "what can I declare here?" See
+`canon-context`.
+
+## Declaring a directive or enum
+
+A vocabulary plugin lives at `.canon/vocab/<id>/`:
+
+```yaml
+# .canon/vocab/<id>/plugin.yaml
+id: my.plugin
+version: "0.1.0"
+kind: project           # `core` for canon.core; `project` for a consumer plugin
+exports:
+  directives: directives/   # a dir of *.yaml directive files
+  enums: enums.yaml
+```
+
+```yaml
+# .canon/vocab/<id>/directives/thing.yaml
+directives:
+  - name: thing
+    attrs:
+      - name: desc
+        type: string           # scalar
+        required: true
+      - name: status
+        type: { domain: task-status }   # value must be a member of the enum
+        required: true
+      - name: tags
+        type: { list: string }          # a YAML list of that element type
+        required: false
+      - name: evidence
+        type: evidence           # SPECIAL: {kind, ref}; `kind`'s domain
+        required: true           # resolves LIVE from .canon/policy.yaml,
+                                 # never a locally-declared enum
+```
+
+```yaml
+# .canon/vocab/<id>/enums.yaml
+enums:
+  task-status: [open, done]
+```
+
+- **Type kinds**: `string`; `{ domain: <enum> }` (validated against
+  `enums.yaml`); `{ list: <type> }`; and `evidence` (the `{kind, ref}`
+  shape whose `kind` domain comes from `.canon/policy.yaml`'s evidence
+  kinds, NOT a local enum).
+- The evidence-kind domain is DELIBERATELY absent from `enums.yaml` — do
+  not add it there; it resolves dynamically from policy.
+
+## Authoring a typed task atom
+
+An atom file is a YAML list of `{ id, tag, attrs }` records. A task atom
+tags `task` and must satisfy the `task` directive's attrs:
+
+```yaml
+- id: my-change#12.3            # <change_id>#<n> (the task_id join key)
+  tag: task
+  attrs:
+    desc: "wire the checker against the real manifest"
+    owner: alice                # optional
+    status: open                # must be a task-status enum member
+    evidence:
+      kind: test-run            # must be a policy.yaml evidence kind
+      ref: "cargo test"
+```
+
+The atom is validated against the resolved vocabulary and compiled to a
+canon `Task`. A wrong tag, an unknown attr, a missing required attr, an
+out-of-domain `status`, or an evidence `kind` absent from `policy.yaml`
+each produces a checker diagnostic (the "expected one of: …" shape) — the
+atom is rejected at author time, never compiled into a malformed Task.
+
+## Authoring a vocabulary-defined handoff body
+
+A handoff body tags `handoff-<domain>` (the domain selects the directive,
+NOT an attr value) and satisfies that directive's attrs:
+
+```yaml
+- id: my-handoff-1
+  tag: handoff-dev              # dev | design | content | test (canon.core)
+  attrs:
+    title: "wire the vocabulary into the CLI"
+    summary: "the foundation is ready for CLI integration"
+    verification-steps:
+      - "cargo build"
+      - "cargo test"
+```
+
+It's validated and compiled to a canon handoff body. Each
+`handoff-<domain>` directive declares its own attrs (e.g. `design` /
+`content` domains may require `acceptance-criteria` instead of
+`verification-steps`) — read the domain's directive (or `canon context`)
+for the exact required set.
+
+## What this skill does NOT cover
+
+- The `canon context` surface itself — see `canon-context`; this skill
+  covers authoring AGAINST it.
+- `policy.yaml` / CEL evidence-requirement authoring — see `canon-policy`;
+  here you only reference an evidence `kind` policy already declares.