@erclx/canon 5.24.0 → 5.26.0

package/docs/agents/commands.md

@@ -11,50 +11,50 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 
 One row per top-level command, in the order `canon --help` prints them. A domain's subcommands are in `## Domain commands` below.
 
-| Command                     | Purpose                                                                         |
-| --------------------------- | ------------------------------------------------------------------------------- |
-| `canon init [path]`         | Bootstrap a project with selected toolkit domains                               |
-| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`    |
-| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names      |
-| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write` |
-| `canon targets <verb>`      | Report the projects this toolkit installed into                                 |
-| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them              |
-| `canon standards <verb>`    | List, audit, or print a standard by name                                        |
-| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                           |
-| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                        |
-| `canon wiki <verb>`         | Scaffold the wiki pages                                                         |
-| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them           |
-| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                        |
-| `canon design <verb>`       | Render `canon/DESIGN.md` tokens, build the board, install the base stylesheet   |
-| `canon slides <verb>`       | Render a `.claude/SLIDES.md` deck, or list its layouts                          |
-| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved               |
-| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                  |
-| `canon demo <verb>`         | Compile and record a running app                                                |
-| `canon inventory [subject]` | Group every route's elements by one computed property, never gating             |
-| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                   |
-| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)           |
-| `canon teach <verb>`        | Open and author learning workspaces                                             |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them  |
-| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                      |
-| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive              |
-| `canon intake <verb>`       | Report intake folders and write answers into them                               |
-| `canon records <verb>`      | Validate, size, prune, and back up the session records                          |
-| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines     |
-| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                           |
-| `canon hooks <verb>`        | Run the steps a git hook drives                                                 |
-| `canon autoship <verb>`     | Decide whether a changed set needs the review pass                              |
-| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence     |
-| `canon feedback`            | Write toolkit feedback from stdin, or open an issue with `--github`             |
-| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline      |
-| `canon gate <verb>`         | Run every stage that guards a branch here                                       |
-| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                   |
-| `canon deps <verb>`         | Report published advisories against the resolved dependency set                 |
-| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text            |
-| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git             |
-| `canon context <verb>`      | Report context folder health, and classify changed or stale sections            |
-| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure    |
-| `canon repo <verb>`         | Propose and apply the remote's description, homepage, and topics                |
-| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries       |
+| Command                     | Purpose                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `canon init [path]`         | Bootstrap a project with selected toolkit domains                                          |
+| `canon sync [path]`         | Sync every installed domain, or report drift and version skew with `--check`               |
+| `canon upgrade`             | Reinstall the CLI globally with the package manager the install path names                 |
+| `canon migrate <verb>`      | Move a project off a retired name or layout, reporting the plan until `--write`            |
+| `canon targets <verb>`      | Report the projects this toolkit installed into                                            |
+| `canon gov <verb>`          | Install and sync governance rules, and audit the tree against them                         |
+| `canon standards <verb>`    | List, audit, or print a standard by name                                                   |
+| `canon tooling <verb>`      | Sync, diff, and verify tooling stacks                                                      |
+| `canon claude <verb>`       | Install the Claude workflow and audit both skill corpora                                   |
+| `canon wiki <verb>`         | Scaffold the wiki pages                                                                    |
+| `canon indexes <verb>`      | Regenerate `index.md` files from sibling frontmatter, or flatten them                      |
+| `canon docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                   |
+| `canon design <verb>`       | Render or regenerate `canon/DESIGN.md` tokens, emit their CSS, install the base stylesheet |
+| `canon slides <verb>`       | Render a deck folder of HTML slides, or list the decks                                     |
+| `canon capture [source]`    | Render HTML or a URL to PNG and prove each declared font resolved                          |
+| `canon serve [dir]`         | Serve a directory on loopback and print the link that opens it                             |
+| `canon demo <verb>`         | Compile and record a running app                                                           |
+| `canon inventory [subject]` | Group every route's elements by one computed property, never gating                        |
+| `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                              |
+| `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                      |
+| `canon teach <verb>`        | Open and author learning workspaces                                                        |
+| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them             |
+| `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                                 |
+| `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive                         |
+| `canon intake <verb>`       | Report intake folders and write answers into them                                          |
+| `canon records <verb>`      | Validate, size, prune, and back up the session records                                     |
+| `canon sessions <verb>`     | Resolve live sessions to worktree and branch, and move one between machines                |
+| `canon worktrees <verb>`    | Report and remove worktrees whose pull request merged                                      |
+| `canon hooks <verb>`        | Run the steps a git hook drives                                                            |
+| `canon autoship <verb>`     | Decide whether a changed set needs the review pass                                         |
+| `canon pr <verb>`           | Read a pull request's diff, head, checks, and review, and post its evidence                |
+| `canon feedback`            | Write toolkit feedback from stdin, or open an issue with `--github`                        |
+| `canon audits <verb>`       | Run every audit as one set under one verdict against the recorded baseline                 |
+| `canon gate <verb>`         | Run every stage that guards a branch here                                                  |
+| `canon secrets <verb>`      | Report credential-shaped values in the tree the package ships                              |
+| `canon deps <verb>`         | Report published advisories against the resolved dependency set                            |
+| `canon labels <verb>`       | Read a changed set against the label map, and scan pull request text                       |
+| `canon comments <verb>`     | Measure comment density by language and kind, with a trend from git                        |
+| `canon context <verb>`      | Report context folder health, and classify changed or stale sections                       |
+| `canon markdown <verb>`     | Fail markdown on a banned character or a dead link, and report its structure               |
+| `canon repo <verb>`         | Propose and apply the remote's description, homepage, and topics                           |
+| `canon census [path]`       | Report tracked file count, extensions, and a line total skipping binaries                  |
 
 `canon serve` drives no browser, which is what separates it from the four that do. All four ship now that `capture` does, so the line between them is the engine rather than the package. A generated page loses its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. A teach lesson's stylesheet is embedded rather than linked, so only its script still needs a server. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
 
@@ -91,7 +91,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `wiki`, in `scripting.md`: `init`
 - `indexes`, in `indexes.md`: `regen`, `list`
 - `docs`, in `docs.md`: `list`, `<topic>`
-- `design`, in `design-board.md`: `render`, `regen`, `board`, `css`, `install`, `sync`
+- `design`, in `install-and-sync.md` for `install` and `sync`, and described below for the rest: `render`, `regen`, `css`, `install`, `sync`
 - `slides`, described below: `render`, `list`
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`
@@ -128,8 +128,8 @@ Subcommands no other page describes:
 - `claude plugin-update` matches the installed marketplace plugin against `claude/.claude-plugin/plugin.json`'s own name and runs `claude plugin update` on it, reading the version back off `claude plugin list --json`, since the update call reports none of its own (`--json`).
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
-- `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
-- `slides render --source <folder>` lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
+- `slides list --json` emits one row per deck under `.canon/slides/`, carrying `name`, `title`, `slides`, and `path`.
+- `slides render [deck]` takes a deck name or a folder, defaulting to the only deck, and lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
 - A deck folder's `deck.json` and the faces it embeds, its per-slide `<body>` attributes, transitions and entrances, speaker notes, and charts are described in `slides.md`.
 - `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).

package/docs/agents/context-audit-checks.md

@@ -85,9 +85,9 @@ All three wireframe findings are printed under a bare run. The states-mismatch f
 
 The provenance check covers `canon/context/` alone, the reference-form check covers the split folders inside it, the required-section check covers `canon/context/` and `canon/wireframes/`, length and the table finding reach every audited folder, and the wireframe states check covers `canon/wireframes/` alone.
 
-What narrows the provenance check is stated in `standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
+What narrows the provenance check is stated in `standards/context.md`, which opens its scope by handing figures to the `draft-figure` skill and wireframes to `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram or wireframe entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder, and what decides it is which tier states the rule rather than what the check measures.
 
-Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: each list is one standard's own, so it reaches the folder that standard governs. The context and wireframe standards each state a set, and the diagram standard states none.
+Length and the table finding generalize as judgments about how far a reader travels, so both reach wherever the audit is pointed. Required sections narrow for a plainer reason: each list is one standard's own, so it reaches the folder that standard governs. The context and wireframe standards each state a set, and an older install's diagrams folder has no standard to state one.
 
 The same test is what moved depth and bullet weight out of this command entirely. A rule stated at the attribute tier reaches every markdown file, and a check reaching every markdown file has no reason to require a folder that resolves.
 

package/docs/agents/index.md

@@ -20,7 +20,6 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Doc classifier](context-classify.md): Classifying canonical-doc content as keep, replace/rewrite, history, or move in diff and sweep mode, the classifier setting pair, the record shape, and the exit codes
 - [Self-stated counts](counts.md): Reading a sentence that asserts a closed catalog's size, how a match is decided, the plausibility filter that keeps a generic word from matching a subset, and why the sweep reports rather than gates
 - [Demo](demo.md): Compiling a screencast draft into a runnable plan, driving a served application to a recording and a still, reading numbered frames back out of a recording, the pointer the recording paints, and what each refusal reports
-- [Design board](design-board.md): Generating a static index over a project's design surfaces, what each panel reads, and which two stay toolkit-checkout-only
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Drift surfaces](drift-surfaces.md): The seven sections canon sync --check reports beside the per-domain scan, being seeds, superseded artifacts, unmigrated domains, surfaces at the old root, new rules and skills, and the reverse walk, with the managed-target gate and what counts toward the exit code
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
@@ -42,7 +41,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records push](records-push.md): Backing the record folders to a private remote and restoring them, which folders the payload carries, the one-time setup, the refusal reasons, and the hook that runs the push
-- [Records stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, and the exit codes and refusals
+- [Records stale](records-stale.md): Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements and architecture records were last reviewed, and the exit codes and refusals
 - [Records validate](records-validate.md): Validating the session records and the standards corpus, the per-kind checks, which root each kind defaults to, the exit codes, and the refusal reasons
 - [Records](records.md): The two roots a record folder resolves at, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, pruning stale scratch, and where validation, the memory review queue, and the private-remote backup are described
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
@@ -55,7 +54,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, reading which row is the caller, the liveness confidence field, what each session surface can see, and where moving a session to another machine is described
 - [Skill audit](skills-audit.md): Measuring both skill corpora against the skill standards, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
 - [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
-- [Slides](slides.md): What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+- [Slides](slides.md): Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 - [Standard success criteria](standards-audit.md): Reading the corpus against the success-criterion gate, the two headings it accepts, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
 - [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates

package/docs/agents/key-changes.md

@@ -26,9 +26,9 @@ The positional is the pull request to read, defaulting to the one open on this b
 
 `--base` names the far side of that range and never the commit the comparison runs against directly. The reader resolves the merge base between `HEAD` and the ref, so `--base origin/main` measures what the branch wrote rather than what the trunk gained while the branch was open. Passing the trunk as it stands today is therefore safe on a branch of any age, and a ref sharing no history with `HEAD` refuses as `bad-base`.
 
-Without `--body` the body, the file list, and the head commit come back from one `gh pr view` call, because the three have to describe the same commit and reading them apart leaves a window where a push between them compares a body against another head's files.
+Without `--body` the body and the head commit come off the REST pull read and the file list off the paginated files endpoint. Every read runs on REST, since a cloud session's GitHub proxy refuses the GraphQL that `gh pr view` runs on. A push landing between the two reads compares a body against the next head's files, a window the verb accepts for the cloud reach.
 
-That view caps its file list at 100 rows and says nothing about having done so, measured against a pull request carrying 101 files where the view reported 100. A pull request at the cap therefore takes a second read through the paginated endpoint, and a failure there refuses with `gh-truncated` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing.
+A failed page refuses as `gh-failed` rather than comparing against a set known to be short. A set silently one file short is the worst input this takes, since the missing file is exactly what a correct bullet would then be accused of inventing. With no number named, the verb reads the one pull request open on the checkout's branch, and refuses as `ambiguous-pull` when two are open against different bases.
 
 ## The two directions
 
@@ -91,7 +91,7 @@ Three refusals separate a clean pass from a read that produced nothing:
 
 An empty extraction read as a clean pass is the failure shape this repository has recorded twice, which is why the middle one is its own reason rather than a zero count.
 
-`gh-missing`, `gh-failed`, `gh-truncated`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
+`gh-missing`, `gh-failed`, `ambiguous-pull`, `unreadable-body`, `unreadable-tree`, `no-base`, `bad-base`, and `unreadable-changes` cover the reads that never reached a comparison.
 
 ## What it was measured against
 

package/docs/agents/pr-evidence.md

@@ -138,7 +138,7 @@ call, is what keeps two close-out comments from landing beside each other the
 way `review-pr` once posted, before that skill's own guard existed. It is
 also why this verb renders the whole comment body rather than handing each
 skill a record to format on its own: a fix to the table shape or the
-collapsed-details wrapper lands once, not twice.
+details wrapper lands once, not twice.
 
 ## The preview line
 
@@ -232,7 +232,16 @@ render needs, so it never refuses `no-base`. The orchestrator's draft lift is
 the caller, and lifts only on `settled`, so a refusal holds it the same as
 `owed` does.
 
-## What a collapsed comment still leaves to GitHub
+## When the comment opens
+
+The comment opens every state while it carries six images or fewer, counting one
+per row for the head plus one per row that is not new, and closes every state
+past that, so the whole comment is open or closed together. A line under
+`## Evidence` names the compared base and head as short shas, which tells a
+reader whether the images match the latest push. The base is the merge base the
+compare endpoint returns, not trunk's tip.
+
+## What the comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed
 tab for any tracked image that changed. This comment does not make that view

package/docs/agents/pr-reads.md

@@ -18,7 +18,7 @@ canon pr review-state 1341 --json
 
 ## The pull request object is not the authority for a head
 
-`gh pr view --json headRefOid` reads a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
+The pull request's head sha, `head.sha` on the REST pull read and `headRefOid` in `gh pr view`, is a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
 
 Two failures on 2026-09-01 came off that one field. A reviewing session posted a finding calling a pushed commit unpushed. A worker fired a green claim and retracted it on its own thread minutes later. Neither session did anything wrong with the value it was handed. The value was stale and said so nowhere.
 
@@ -74,7 +74,7 @@ Both empty cases report `pending` instead: a tip carrying no run yet, and a list
 
 The verb keeps the newest run per check name rather than rolling every matched run into the state. A workflow that fires twice on one commit used to leave its first, stale run beside the rerun, where a failing one could outvote a passing rerun. Grouping the matched set by name and keeping the highest `id` per group removes that stale run before the rollup runs. `collapsed` on the record counts what the fold discards, so a caller reading it against `matched` sees the dedupe directly, instead of reading a `matched` above the check count as the verb disagreeing with `gh pr checks`.
 
-A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. `mergeStateStatus` is the field that separates the two, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
+A conflicted branch produces no `pull_request` check runs rather than a failing one. GitHub builds no merge ref for it, so no `pull_request` workflow starts and a repository running only that trigger leaves the listing empty, which reads as `pending` and never leaves it. A workflow triggered by a push to the branch still runs on the tip, so `matched` rises above zero, `conflicted` stays false, and the wait ends on those runs rather than on the reading. The pull request's `mergeable_state` is the field that separates the two. The verb raises it to upper case, matching the GraphQL `mergeStateStatus` it replaced, and the record carries `conflicted: true` and `mergeState` when it reads `DIRTY` with no run belonging to the tip. A `DIRTY` reading beside runs on the tip leaves the state as those runs say, since a conflict arising after they completed does not unsay them. `UNKNOWN` is transient while GitHub computes the merge state, right after a push, so it reads as not conflicted and costs one more poll. A binary predating the field keeps answering `pending`.
 
 A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
 
@@ -90,6 +90,7 @@ Each refusal names a different repair:
 | -------------------- | ------------------------------------------------------------------------------------------ |
 | `gh-missing`         | `gh` is not on the path, so no pull request resolved                                       |
 | `gh-failed`          | `gh` could not answer for this branch, so name a number instead                            |
+| `ambiguous-pull`     | Two open pull requests share the branch against different bases, so name a number          |
 | `no-branch`          | The pull request carries no head branch name, so no ref could be read                      |
 | `unresolvable-ref`   | The remote read failed, which is not the same answer as an absent branch                   |
 | `no-remote-branch`   | The remote carries no branch by that name, so there is no tip to compare against           |
@@ -105,6 +106,6 @@ One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-
 
 One head-sensitive read is left on the object deliberately. `canon targets pulls` reads `statusCheckRollup` for every open pull request across every target, where resolving a tip per row would cost one remote read per pull request across a dozen projects, against a surface that reports a listing rather than gating a push.
 
-The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It now spends a third read per pull request per tick besides, since `canon pr review-state` makes its own `gh pr view` call beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
+The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. It reads over REST alone, one reviews read and one issue-comments read per pull request, plus a pull read only when `canon pr head` returns no tip. It spends a further read per pull request per tick besides, since `canon pr review-state` makes its own REST reviews read beside the payload the poll already fetched. That one is an API round trip rather than a remote ref read, and it buys a coverage test that answers about what a session read. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
 
-`canon pr key-changes` also stays on the object, for a different reason. It reads the body, the file list, and `headRefOid` in one call on purpose, so the three describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it.
+`canon pr key-changes` also stays on the object, for a different reason. It reads the body and the head off one pull read, so the two describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it. The file list comes off a second read, since only GraphQL returns it beside the body and a cloud session's proxy refuses GraphQL.

package/docs/agents/records-stale.md

@@ -1,25 +1,26 @@
 ---
 title: Records stale
-description: Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, and the exit codes and refusals
+description: Reading the memory pen as a review queue, what makes an entry due, how a cited path is read and resolved, the order entries come back in, counting the releases since the requirements and architecture records were last reviewed, and the exit codes and refusals
 ---
 
 # Records stale
 
-`canon records stale memory` reports each memory entry's review state and every backticked path it cites that the project no longer holds. It answers what a review of the pen should read next, so a skill takes the queue from the verb rather than re-deriving it by grep.
+`canon records stale memory` reports each memory entry's review state and every backticked path it cites that the project no longer holds. It answers what a review of the pen should read next, so a skill takes the queue from the verb rather than re-deriving it by grep. `canon records stale canonical` reports when the requirements and architecture records were last reviewed and how many releases have shipped since.
 
 ```bash
 canon records stale memory
 canon records stale memory --json
 canon records stale memory --days 60 --json
+canon records stale canonical --json
 ```
 
-| Option          | Behavior                                                      |
-| --------------- | ------------------------------------------------------------- |
-| `--json`        | Add a machine-readable record on stdout                       |
-| `--days <n>`    | Days after a review before an entry is due again (default 30) |
-| `--root <path>` | Project root, defaulting to the main worktree                 |
+| Option          | Behavior                                                                                            |
+| --------------- | --------------------------------------------------------------------------------------------------- |
+| `--json`        | Add a machine-readable record on stdout                                                             |
+| `--days <n>`    | Days after a review before a memory entry is due again (default 30)                                 |
+| `--root <path>` | Project root, defaulting to the main worktree for `memory` and the current worktree for `canonical` |
 
-`memory` is the only kind it reads, since a memory entry is the one record carrying a review date. Any other argument refuses as `unknown-kind`.
+`memory` and `canonical` are the two kinds it reads, since each is a record carrying a review date. Any other argument refuses as `unknown-kind`.
 
 It reports and never writes. It moves, archives, and rewrites no entry, matching `validate` and `size`.
 
@@ -53,10 +54,22 @@ canon records stale memory --json | jq -r '[.entries[] | select(.due)][0:20][] |
 
 The record carries `total`, `due`, `days`, the `folder` read relative to the root, and one `entries` row per entry with `name`, `category`, `reviewed`, `due`, and `unresolved`.
 
+## Canonical records
+
+`canonical` reads `REQUIREMENTS.md` and `ARCHITECTURE.md` at whichever surface root carries each, `canon/` ahead of `.claude/`, and omits one the project does not hold. Both are tracked, so `--root` defaults to the worktree the caller stands in rather than the main one, and a stamp a branch just wrote reads back from that branch.
+
+Each doc's review point is an optional `reviewed: YYYY-MM-DD` frontmatter field, set by whoever finishes a review, per `canon standards requirements` and `canon standards architecture`. It is a date rather than a commit, since a commit written on a feature branch never reaches a trunk that squash-merges. The field is read the way the memory field is, so a value that is not a calendar date comes back as `invalidReviewed`.
+
+The count is every release tag merged into `HEAD` whose creator date falls after the reviewed day. A release tag ends in a dotted version, bare as `v5.25.0` or behind a component prefix as `canon-v2.1.0`, so an eval, deploy, or snapshot tag on the trunk never inflates it. A lightweight tag's creator date is its commit's date and an annotated tag's is the tagging date, so a project mixing both counts by two clocks.
+
+The record carries `tagged`, false when `HEAD` has merged no release tag or the repository has no commit yet, and one `docs` row per doc with `path`, `reviewed`, `releasesSince`, and `latestRelease`. `releasesSince` is null on a doc never reviewed and `0` on one reviewed after every tag. With no tags it is also `0`, which is why `tagged` travels beside it.
+
+It gates nothing, and no hook, gate stage, or workflow runs it. `canon:document-health` reads it when asked to review the two records.
+
 ## Exit codes and refusals
 
 Exit codes: `0` the reading completed, whatever it found, and `1` refused. A due entry is a queue position rather than a failure, so nothing here gates.
 
-A `reason` field carries which gate fired: `no-folder` when the project holds no memory folder at either record root, `unknown-kind` for any kind but `memory`, and `bad-days` when `--days` is not a positive whole number. An empty pen is not a refusal. It reports an empty list and exits `0`.
+A `reason` field carries which gate fired: `no-folder` when the project holds no memory folder at either record root, `unknown-kind` for any kind but `memory` or `canonical`, `bad-days` when `--days` is not a positive whole number or is passed to `canonical`, and `unreadable-tags` when `canonical` cannot read the tags. An empty pen is not a refusal. It reports an empty list and exits `0`.
 
 The pen is shared scratch at the main worktree root, so `--root` defaults there, the same default `validate memory` takes. A pen at the legacy `.claude/memory/` root resolves the way every record verb resolves it, per `records.md`. <!-- canon-keep-record-root -->

package/docs/agents/records.md

@@ -118,7 +118,7 @@ Exit codes: `0` nothing to prune, or `--write` deleted every candidate. `1` refu
 
 ## Stale
 
-`canon records stale memory` reports which memory entries are due for review and which cite a path the tree no longer holds, ordered so a review takes the first N as a batch. What makes an entry due, how a cited path resolves, and the refusals are in `records-stale.md`.
+`canon records stale memory` reports which memory entries are due for review and which cite a path the tree no longer holds, ordered so a review takes the first N as a batch. `canon records stale canonical` reports when the requirements and architecture records were last reviewed and how many releases have shipped since. What makes an entry due, how a cited path resolves, how the release count is taken, and the refusals are in `records-stale.md`.
 
 ## Push and pull
 

package/docs/agents/sandbox.md

@@ -9,7 +9,7 @@ description: Scenario routing, the expectation scoring surface, and the coverage
 
 ## Scenarios
 
-Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so the picker and the coverage report both filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync canon sandbox infra:tooling

package/docs/agents/skills-audit.md

@@ -36,7 +36,8 @@ Each check traces to a line in the standard.
 - Folder name in kebab-case
 - Each `REQUIREMENT.md` declaring `Gap` and `Must`, matched at any heading level
 - No ISO date in `SKILL.md` or any file under `references/`, reported as `datedProvenance` in the JSON record's `findings`
-- Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and carrying `references/adopted.md`, reported as `practiceShape`
+- Each listed practice skill closing with `## Excuses and rebuttals`, `## Red flags`, and `## Before handing over`, and each skill on the wider ledger list carrying `references/adopted.md`, reported together as `practiceShape`
+- Each file under `references/` running over 100 lines opening with a `## Contents` H2, reported as `referenceContents`
 
 A body whose frontmatter does not parse reports as declaring neither field rather than ending the run, so one malformed file cannot hide the corpus behind it. A key present with an empty value reads as absent, since a blank `name` would otherwise report as a name disagreeing with every folder. A folder carrying no requirement is reported once under presence rather than counted again for the sections it therefore lacks.
 
@@ -44,7 +45,11 @@ The date check reads prose alone. A date inside a fence or a code span is exampl
 
 Each finding names the file and the line, such as `claude/skills/<name>/references/<file>.md  line 12: <date>`. A date after "measured" or "verified" reports like any other, unlike the context audit, because a skill body states the rule a session follows today rather than a reading of the tree.
 
-The practice check reads only the skills the audit lists, which the JSON record carries as `checkpoints.practiceSkills`. The list names folders under the toolkit's shipped `claude/skills/` corpus alone, so a project's own skill is never read as a practice skill and a same-named folder under `.claude/skills/` produces no finding. Where `claude/skills/` resolves, a listed folder it does not hold reports as a missing skill, so a renamed or misspelled entry cannot pass unread. Each closing section matches only as an exact H2 outside a fence, so an H3 or a heading carrying more words reports as missing.
+The practice check reads only the skills the audit lists, which the JSON record carries as `checkpoints.practiceSkills` for the closing sections and `checkpoints.ledgerSkills` for the ledger. The ledger list holds every practice skill plus the skills that cite outside sources without a practice's closing shape, so a skill on it alone owes the ledger and none of the sections.
+
+Both lists name folders under the toolkit's shipped `claude/skills/` corpus alone, so a project's own skill is never read as a practice skill and a same-named folder under `.claude/skills/` produces no finding. Where `claude/skills/` resolves, a listed folder it does not hold reports as a missing skill, so a renamed or misspelled entry cannot pass unread. Each closing section matches only as an exact H2 outside a fence, so an H3 or a heading carrying more words reports as missing.
+
+The contents check counts every line of a reference, frontmatter included, the way `wc -l` does, so a file of exactly 100 lines passes and one of 101 needs the list. `## Contents` matches the same way the closing sections do, as an exact H2 outside a fence. `SKILL.md` is never read for it, and the threshold travels in the JSON record as `checkpoints.contentsThreshold`.
 
 ## What it leaves alone
 
@@ -56,7 +61,9 @@ A check with no rule behind it prints an opinion as a defect, which is where the
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, and practice shape findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, two `bun run check` stages read the same report in-process and fail a push on dated provenance and on practice shape, since its own corpus is held at zero on both.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a skill folder carrying no `REQUIREMENT.md`. Only presence sets a failing code. Name, description, folder, requirement-section, dated-provenance, practice shape, and reference contents findings print and return `0`, because each is a judgment a reader settles and failing a push on one would make the check something to route around. In the toolkit, two `bun run check` stages read the same report in-process and fail a push on dated provenance and on practice shape, since its own corpus is held at zero on both.
+
+No stage reads reference contents, so a long reference without a list stays a report.
 
 ## The requirement gate
 

package/docs/agents/slides.md

@@ -1,16 +1,28 @@
 ---
 title: Slides
-description: What a folder of HTML slides declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
+description: Where a deck folder lives and what it holds, what it declares for the whole deck in deck.json, the faces it embeds, what each slide declares on its own body, transitions and entrances, the master built from the project's tokens, speaker notes, charts, and what each refusal reports
 ---
 
 # Slides
 
-`canon slides render --source <folder>` turns a folder of `.html` slides into an editable PowerPoint deck. Each slide describes its own shapes. What belongs to the whole deck, being the bands, the numbers, and the mark, sits in one file beside them, and the master that carries it takes the project's own colors and face.
+`canon slides render <deck>` turns a folder of `.html` slides into an editable PowerPoint deck. Each deck lives in its own folder under `.canon/slides/`, which `canon records push` backs and git ignores, and `canon slides list --json` lists them. Each slide describes its own shapes. What belongs to the whole deck, being the bands, the numbers, and the mark, sits in one file beside them, and the master that carries it takes the project's own colors and face.
 
 ```bash
-canon slides render --source slides/q3-review
+canon slides list --json
+canon slides render q3-review
 ```
 
+## The deck folder
+
+| Path                             | Holds                                                |
+| -------------------------------- | ---------------------------------------------------- |
+| `.canon/slides/<deck>/*.html`    | the slides, rendered in filename order               |
+| `.canon/slides/<deck>/deck.json` | what belongs to the whole deck, described below      |
+| `.canon/slides/<deck>/assets/`   | images the slides reference by a relative path       |
+| `.canon/slides/layouts/`         | the project's shared layouts, never listed as a deck |
+
+A folder holding no `.html` file is not a deck. `render` with no name takes the only deck there is, and refuses with the list when there are several. It also takes a folder path outside `.canon/slides/`.
+
 ## The deck file
 
 `deck.json` beside the slides is optional. Without it the deck gets its defaults.

package/docs/target/projects.md

@@ -73,14 +73,14 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `canon/REQUIREMENTS.md` and `canon/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write. Each seed states its own caps, 12 decisions of at most 150 words and 6 risk bullets for the architecture record and 600 words for the requirements, and `canon context audit` gates on them. Edit a number in the record to loosen it.
 2. For a UI project, invoke `canon:design-extract` to draft `canon/DESIGN.md`. With no UI code yet it takes the greenfield path and proposes tokens from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `canon:draft-diagram` to draft entries under `.canon/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
+3. Optionally invoke `canon:draft-figure` naming an architecture view, such as system context or components, and the document it belongs in. It draws the view from the architecture and the requirements and renders it to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds.
 4. Start the feature loop. See [AI workflow](../workflow/ai-workflow.md) for the per-feature sequence.
 
-A machine without a renderer still gets the diagrams and is told which check was skipped.
+A machine without a renderer still gets the figure and is told which check was skipped.
 
-Each diagram entry records the commit and date it was last verified against, and nothing maintains that record for you. The folder is redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind your branch is due a read, and no pass will name which one. Run `canon:draft-diagram` again when the code a kind is drawn from moves.
+Nothing watches a figure once it is drawn. Run `canon:draft-figure` again when the code a view is drawn from moves.
 
-`canon/ARCHITECTURE.md` carries the same mechanism on the same ship. `canon:context-fold` anchors a decision it amends to the paths that decision cites, and reports an anchored decision whose cited path the branch touched.
+`canon/ARCHITECTURE.md` is watched where a figure is not. `canon:context-fold` anchors a decision it amends to the paths that decision cites, and reports an anchored decision whose cited path the branch touched.
 
 ### Stack decision
 

package/docs/workflow/ai-workflow.md

@@ -26,7 +26,6 @@ canon/
 └── rules/           ← path-scoped governance rules, written by canon gov install
 
 .canon/
-├── diagrams/        ← one Mermaid entry per diagram kind with a generated index.md, redrawn on demand
 ├── tasks/           ← one file per task with a generated index.md, local scratch
 ├── plans/           ← one plan per feature, archived inside itself once it ships
 ├── memory/          ← durable session facts no context entry owns
@@ -137,7 +136,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 
 ## Skills
 
-The [skill map](skill-map.md) gives every skill the plugin ships one row saying when to reach for it, grouped by the moment a project meets it.
+The [skill map](skill-map.md) and its sibling [skill map on request](skill-map-on-request.md) give every skill the plugin ships one row saying when to reach for it. The first groups rows by the moment a project meets them, and the sibling holds the skills that answer a request.
 
 ## Feedback routing
 

package/docs/workflow/index.md

@@ -15,6 +15,7 @@ How a person and their agents run a feature, from the design tier through the pa
 
 - [Operating model](operating-model.md): Orchestrator, planner, and worker roles for building across parallel sessions
 - [Parallel features](parallel-features.md): Run independent features in parallel worktrees, with the records and board every session shares
+- [Skill map on request](skill-map-on-request.md): When to reach for the plugin skills that serve a request rather than a moment in a project's life
 - [Skill map](skill-map.md): When to reach for each plugin skill, grouped by the moment a project meets it
 - [Visual design workflow](visual-design-workflow.md): Tiered guide for design and wireframe authoring with Claude Code
 - [Zshrc aliases for Claude Code](zshrc-aliases.md): Shell aliases that shorten common Claude Code invocations

package/docs/workflow/parallel-features.md

@@ -54,7 +54,7 @@ A plan that ships is archived, never deleted. `canon tasks archive` moves it to
 
 A branch review report takes the other route and is swept rather than archived. `review-branch` writes it flat into `.canon/review/` as `branch-<slug>.md`, the session addressing it reads it once, and the durable record of what a review found is the comment `review-pr` posts on the pull request, so `context-fold` deletes any report whose branch is gone. The body that writes a report owns how long it lives, which leaves the shipping branch's own report on disk through the run that cites it and collects it a branch later. What that loses is a local-only review on a branch that never opened a pull request, which is why the report says so where a reader meets it.
 
-`canon:context-fold` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Requirements, architecture, and design stay session-sourced, because a diff cannot carry a judgment.
+`canon:context-fold` decides which task closed by reading the diff rather than the conversation. It resolves a merge base against `origin/main`, unions the committed diff with the working tree and untracked files, then matches unchecked outcomes on the board against what shipped. A task that shipped without ever being discussed still gets marked. Architecture and design stay session-sourced, because a diff cannot carry a judgment, and an architecture write further needs a folded plan naming the slot decision. The requirements record is never folded. A direction change gets one report line naming `canon:document-health`, which reviews that record only when asked.
 
 ## The task board
 

package/docs/workflow/skill-map-on-request.md

@@ -0,0 +1,42 @@
+---
+title: Skill map on request
+description: When to reach for the plugin skills that serve a request rather than a moment in a project's life
+category: Workflow
+---
+
+# Skill map on request
+
+These two groups hold the skills no single moment in a project's life calls for, so they sit apart from the moment-ordered groups in the [skill map](skill-map.md). The two pages together are the corpus the coverage claim is measured against, and a skill takes one row across both.
+
+## Generate an artifact on demand
+
+| Skill                     | When to use                                                                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                               |
+| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                           |
+| `canon:create-standard`   | For a new authoring convention                                                                                                                 |
+| `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
+| `canon:draft-figure`      | For a hand-drawn figure or an architecture view inside an existing doc, drafted in Mermaid or freehand SVG                                     |
+| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
+| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                             |
+| `canon:draft-slides`      | For a deck, drawn as HTML slides in its own folder and rendered to editable PowerPoint                                                         |
+| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                                                  |
+| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap                                   |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                                                    |
+
+## Answer a question at any point
+
+| Skill                       | When to use                                                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
+| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
+| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
+| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
+| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
+| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
+| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
+
+Every row answers a question rather than marking a point in a project's life, so filing one under a phase on the [skill map](skill-map.md) would send a reader to the wrong group.
+
+A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.