@erclx/canon 4.118.0 → 4.119.0

package/claude/skills/ux-walkthrough/references/relay.md

@@ -4,7 +4,7 @@ Read when the operator calls a batch, and at the start of the walkthrough when a
 
 ## Where the batch goes
 
-- Send it to the controller where the session was dispatched by one, resolved per the Channel rule, matched by name through `canon gov list --rules --json` rather than a path a target may not have installed.
+- Send it to the controller where the session was dispatched by one, through `canon:session-relay`, which resolves the address and carries the send.
 - Give it to the operator as one list in the conversation where no controller exists. The walkthrough file is the handoff either way.
 
 ## When

package/docs/agents/commands.md

@@ -23,10 +23,10 @@ Full help: `canon <command> --help`. Bare `canon --help` lists every top-level c
 | `canon indexes list [path]`      | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`)                                                                                                                                                                                                                             |
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                                     |
 | `canon design render`            | Render `canon/DESIGN.md` tokens to HTML and CSS, declaring each vendored face the typography table names with `--embed-fonts`                                                                                                                                                                                                |
-| `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                            |
+| `canon design regen`             | Rewrite this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`                                                                                                                                                                                               |
 | `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, components, and references against a caller-resolved `--root` (`--out`), defaulting to the main worktree                                                                                                                                  |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                              |
-| `canon design install`           | Install the base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                                      |
+| `canon design install`           | Install the neutral base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                              |
 | `canon design sync`              | Update a base stylesheet already installed under `.claude/design/`                                                                                                                                                                                                                                                           |
 | `canon slides render`            | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                                                                                                                                                                                 |
 | `canon slides list`              | List the available slide layouts (`--json` for the catalog)                                                                                                                                                                                                                                                                  |

package/docs/agents/install-and-sync.md

@@ -19,10 +19,13 @@ removes a stale `.claude/GOV.md` from the retired build. Use
 
 Everything under `.claude/rules/canon/` belongs to the toolkit, so a rule
 there that the toolkit no longer ships is deleted on sync, edited or not. That
-is how a retired or renamed rule stops loading in a target. The sync lists each
-deletion by path before it applies, and the target's git diff is the record
-afterwards. `canon sync --check` lists the same file as `retired` before any
-sync runs. A project's own rules belong under `.claude/rules/project/`, where
+is how a retired rule stops loading in a target. A renamed or renumbered rule
+the toolkit declares in `governance/renames.toml` moves instead: the sync
+installs the rule under its new name and deletes the old file, whether or not
+the target's stamp records a stack. Local edits to the old file are not
+carried, and the sync says so. The sync lists each change by path before it
+applies, and the target's git diff is the record afterwards. `canon sync
+--check` lists the same file as `retired` or `renamed` before any sync runs. A project's own rules belong under `.claude/rules/project/`, where
 `canon standards rule` reserves `900-999` for them, and a rule placed under
 `canon/` instead is lost on the next sync.
 
@@ -164,9 +167,11 @@ matches what the toolkit installed, `customized` when the project edited it,
 `stranded` when it sits at a path the toolkit no longer installs to, `orphaned`
 when the project authored it, or `drifted` when no stamp covers it. Governance
 also reports `missing`, for a rule the target's recorded stack lists that its
-tree does not hold at all, and `retired`, for a rule under
+tree does not hold at all, `retired`, for a rule under
 `.claude/rules/canon/` the toolkit no longer ships, which the next sync
-deletes. A `retired` file counts toward `--exit-code`, since one sync clears it.
+deletes, and `renamed`, for one the toolkit ships under a new name, which the
+next sync moves. A `retired` or `renamed` file counts toward `--exit-code`,
+since one sync clears it.
 
 Use `--json` for the machine-readable report and `--exit-code` to fail a CI job. Orphaned
 and missing files are both excluded from that exit code: a project-authored

package/docs/agents/tasks.md

@@ -50,7 +50,7 @@ canon tasks archive --pull-request 673 --json
 | `--json`             | Emit a machine-readable record on stdout                     |
 | `--root <path>`      | Board root, defaulting to the main worktree                  |
 
-Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, or `bad-input`.
+Exit codes: `0` archived, `1` refused. Every gate is a refusal rather than a warning, because `.husky/post-merge` calls this with nobody watching. The `reason` field carries which gate fired: `no-board`, `no-match`, `ambiguous`, `no-outcomes`, `open-outcomes`, `earlier-slice`, or `bad-input`. `earlier-slice` fires when `--pull-request` names a number that is not the last on the task's `Pull request:` line, since outcomes are ticked at ship time and only the last slice's merge closes the task.
 
 An outcome whose body is struck reads as cut rather than open or closed, whatever its checkbox holds: `- ~~<outcome>~~ <why>`. A task carrying only cut outcomes archives, since the gate refuses `no-outcomes` only when both the closed and the cut counts are zero. The success record carries `closed` and `cut` as counts, so a reader tells a shipped task from an abandoned one without opening the file.
 
@@ -245,13 +245,13 @@ canon tasks plan-link v28.1-trigger-escalation .canon/plans/feature-dispatch-ans
 
 The plan resolves the same way `canon tasks plan-answers` resolves one, against the project root first and `.canon/tasks/` second, so a bare slug and a board-relative path both work. A reference resolving to no file refuses as `no-plan`, naming every base it looked under.
 
-The write mirrors `canon tasks pull-request`'s add/correct/unchanged shape, anchored on the H1 rather than on the last origin line, since `Plan:` is the first origin line a task carries rather than the last. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same plan safe.
+The write adds the line when it is absent and corrects the target in place when it exists, anchored on the H1 rather than on the last origin line, since `Plan:` is the first origin line a task carries rather than the last. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same plan safe.
 
 Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, `no-plan`, or `bad-input`.
 
 ## Pull request
 
-`canon tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds, and corrects the number in place when the line exists.
+`canon tasks pull-request` records the number a branch's pull request carries onto the task that branch closes. It adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already holds. When the line exists it appends `, #NNN` rather than replacing it, so a task shipped in slices lists every pull request oldest first, and a number already listed leaves the line alone. A line that does not read as a comma-separated list of `#NNN` entries is replaced whole.
 
 Name the task by its filename stem, or by the plan its `Plan:` line points at:
 
@@ -266,7 +266,7 @@ canon tasks pull-request 673 --plan worktree-scratch-routing --json
 | `--json`        | Emit a machine-readable record on stdout           |
 | `--root <path>` | Board root, defaulting to the main worktree        |
 
-A plan is matched on the token both spellings share, so `worktree-scratch-routing`, `feature-worktree-scratch-routing`, and `.canon/plans/feature-worktree-scratch-routing.md` all select the same task. The `action` field reports `added`, `corrected`, or `unchanged`, which makes a rerun against the same number safe.
+A plan is matched on the token both spellings share, so `worktree-scratch-routing`, `feature-worktree-scratch-routing`, and `.canon/plans/feature-worktree-scratch-routing.md` all select the same task. The `action` field reports `added`, `appended`, `corrected`, or `unchanged`, which makes a rerun against the same number safe.
 
 Exit codes: `0` recorded, `1` refused. The `reason` field carries `no-board`, `no-match`, or `ambiguous`. `git-pr` skips silently on those three, because each is a case where a guessed write would archive the wrong task once the branch merges.
 

package/docs/target-projects.md

@@ -225,7 +225,7 @@ The report opens by naming the binary running it. The installed version reads ag
 
 #### Then the causes
 
-A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs. A `retired` rule is one under `.claude/rules/canon/` the toolkit no longer ships, and the next `canon gov sync` deletes it.
+A `stale` file still matches what the toolkit installed, so the update is mechanical. A `customized` file carries local edits, so taking the upstream version is a decision and `canon:seed-sync` is the tool for it. A `stranded` file sits where an older toolkit installed it and the toolkit has since moved, which is a relocation the report names but no command runs. A `retired` rule is one under `.claude/rules/canon/` the toolkit no longer ships, and the next `canon gov sync` deletes it. A `renamed` rule is one the toolkit now ships under a new name, and the next sync installs the new name and deletes the old file.
 
 That attribution comes from `canon/config/config.json`, which every install and sync now writes, falling back to `.claude/canon/config.json` for a target stamped before that move. A target stamped before that path shipped is read from the retired `.claude/canon.json` instead, reported rather than migrated. Governance records a hash per installed file, plus the stack `canon gov install` was given, and tooling records the stack chain it resolved instead of any file hash, since its install runs no per-file walk to attribute.
 

package/docs/workflow/ai-workflow.md

@@ -224,15 +224,15 @@ This section is the corpus the coverage claim is measured against: every name `c
 
 ### Build the feature
 
-| Skill                        | When to use                                                                     |
-| ---------------------------- | ------------------------------------------------------------------------------- |
-| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch             |
-| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR               |
-| `canon:project-commands`     | When the project's own command needs running                                    |
-| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor |
-| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                  |
-| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested        |
+| Skill                        | When to use                                                                                                |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`     | When the project's own command needs running                                                               |
+| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
 
 ### Check the work before it leaves the branch
 

package/docs/workflow/visual-design-workflow.md

@@ -24,7 +24,7 @@ The toolkit seed in `tooling/claude/seeds/canon/DESIGN.md` ships a token-table t
 
 The `canon:design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `canon/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.canon/tmp/render/design/` for eyeballing the current system without leaving Claude Code. See `canon/context/design.md`.
 
-A project wanting the toolkit's own values rather than its own runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying the token set as custom properties and two components built on them. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record drafted by the extract skill is the project's own, and the installed stylesheet is the toolkit's.
+A project wanting a neutral starting point to override runs `canon design install`, which copies one stylesheet to `.claude/design/base.css` carrying an achromatic token set as custom properties and two components built on them. Greys run from near-black to near-white and the accent is monochrome, so the only palette the project renders is one it writes itself. That file is toolkit-owned and `canon design sync` refreshes it, so a project overrides a value in `.claude/design/project/` instead, which sync never touches. Nothing arrives without that install, and the two channels are independent: a record drafted by the extract skill is the project's own, and the installed stylesheet is the toolkit's.
 
 A cell no source anchors ends in `? verify`, and the preview shows that marker beside the value rather than folding it in, so a swatch and a font sample stay built from the value alone. A confidence line above the sections names how many cells are anchored against how many are tagged, which is what tells a reader whether they are looking at a record of the code or a proposal about it. It reads the columns a source could anchor and leaves out the row names, so the ratio is not diluted by cells no tag could ever reach. The proposal path tags nearly all of them, so that count reads low on day one by design.
 

package/governance/renames.toml

@@ -0,0 +1,13 @@
+# Rule renames a sync carries a target across. Each key under [renamed] is an
+# old rule basename and its value the basename the same rule ships under now,
+# so `canon gov sync` replaces a held old file with the rule under its new name
+# rather than only deleting it.
+#
+# An entry declares one-to-one identity and nothing else. A fold of several
+# rules into one, or a split of one into several, is a retirement plus an
+# addition and takes no entry here. Add the entry in the same change as the
+# rename or renumber, and never prune one: a target can sit any number of
+# releases behind, and a chain A to B to C resolves A only while both links
+# stay. A key must name no live rule and every chain must end on one, which
+# `src/gov/renames.test.ts` checks against this file.
+[renamed]

package/governance/rules/core/085-worktrees.md

@@ -1,5 +1,5 @@
 ---
-description: Route tracked-file writes and shared session scratch correctly from a linked worktree
+description: Enter a linked worktree for implementation, resolve shared session scratch at the main root, and route a refused main-root write through session-worktree
 ---
 
 # Worktrees standards
@@ -11,10 +11,4 @@ description: Route tracked-file writes and shared session scratch correctly from
 ## Shared session scratch
 
 - Shared session scratch (`.canon/plans/`, `.canon/review/`, `.canon/memory/`, `.canon/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
-- `.canon/tmp/` is mixed rather than main-root by default: it stays worktree-local per `055-scratch.md`, and a skill that resolves a write there at the main root instead states so in its own body.
-- From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
-- From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
-- `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.
-- Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through a command that resolves the main root in-process, because the shell route for that case is the stream editor this file bans.
-- A background session that entered no worktree at all meets the identical refusal writing to the main root, since the guard gates on isolation rather than on sitting inside a linked worktree. A planner writing its plan file from no worktree takes the same heredoc route for that reason.
-- The heredoc route costs nothing on `.canon/plans/` and `.canon/review/`, which no `PostToolUse` hook watches, and costs the index on `.canon/tasks/` and `.canon/memory/`, since a hook matching `Write|Edit|MultiEdit` never fires on `Bash`. Regenerate positionally: in-process where a verb such as `canon tasks archive` already calls it, elsewhere by an explicit `canon indexes regen` call.
+- From a linked worktree, or from a background session that entered none, `Edit` and `Write` refuse a main-root path and redirect to a worktree copy no later session reads. Never take that redirect. Route the write the way the `session-worktree` skill states, and report it rather than proceeding silently when that skill does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.118.0",
+  "version": "4.119.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/workflow.ts

@@ -163,11 +163,21 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Get me set up in a fresh Claude Code worktree for this branch.',
     expect: 'session-worktree',
   },
+  {
+    prompt:
+      'My Write to the plan file at the main root got refused for session isolation. How do I land it there?',
+    expect: 'session-worktree',
+  },
   {
     prompt:
       'Relay this over to the session that dispatched me. It gave me a sessionId rather than a name, so work out who that is and send it.',
     expect: 'session-relay',
   },
+  {
+    prompt:
+      'I am stuck on a question only the operator can answer. Before I stop and ask it, tell the session that dispatched me, it gave me a sessionId.',
+    expect: 'session-relay',
+  },
 
   // Negatives: pairs whose bodies already carry an explicit Do NOT boundary.
   {

package/src/commands/sync.ts

@@ -133,9 +133,17 @@ function renderCheck(report: CheckReport): void {
       logWarn(entry.notice ?? `${entry.rel} (${entry.state})`)
     }
 
-    const { stale, customized, drifted, stranded, retired, orphaned, missing } =
-      domain.counts
-    if (stale + customized + drifted + stranded + retired === 0) {
+    const {
+      stale,
+      customized,
+      drifted,
+      stranded,
+      retired,
+      renamed,
+      orphaned,
+      missing,
+    } = domain.counts
+    if (stale + customized + drifted + stranded + retired + renamed === 0) {
       logInfo(orphaned === 0 ? 'up to date' : `up to date (${orphaned} local)`)
     }
     // A local file is not a deficiency and a missing rule is, so this never

package/src/commands/tasks.ts

@@ -409,12 +409,14 @@ export function register(program: Command): void {
       [
         '',
         'Exit codes:',
-        '  0  the line was added, corrected, or already correct',
+        '  0  the line was added, appended to, corrected, or already correct',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'It adds Pull request: #NNN under the origin lines the task carries,',
-        'and corrects the number in place when the line exists. The board is',
-        'shared scratch, so a linked worktree records against the same board.',
+        'and appends the number to the line when one exists, so a task shipped',
+        'in slices lists every pull request. A line that does not read as a',
+        'list is replaced. The board is shared scratch, so a linked worktree',
+        'records against the same board.',
         '',
         'Examples:',
         '  canon tasks pull-request 673 v28.1-trigger-escalation',
@@ -448,11 +450,10 @@ export function register(program: Command): void {
         '  0  the line was added, corrected, or already correct',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
-        'It writes Plan: [<label>](<target>) right after the H1, the same',
-        'add/correct/unchanged shape canon tasks pull-request writes with, and',
-        'resolves both a bare slug and a board-relative path the way',
-        'canon tasks plan-answers does. Safe from a linked worktree, since it',
-        'resolves the board root in-process.',
+        'It writes Plan: [<label>](<target>) right after the H1, corrects the',
+        'target in place when the line exists, and resolves both a bare slug',
+        'and a board-relative path the way canon tasks plan-answers does. Safe',
+        'from a linked worktree, since it resolves the board root in-process.',
         '',
         'Examples:',
         '  canon tasks plan-link v28.1-trigger-escalation dispatch-answer-gate',

package/src/design/base.css

@@ -1,29 +1,29 @@
-/* Generated by `canon design regen` from src/design/tokens.ts. Do not edit.
+/* Generated by `canon design regen` from src/design/neutral.ts. Do not edit.
    This is the base half of a design install. A target overrides a value in
    .claude/design/project/, which the three-way merge leaves alone, so this
    file changes freely and nothing a project wrote lives in it. */
 
 :root {
-  --color-background: #0f0e0c;
-  --color-surface: #151412;
-  --color-chrome: #1b1a18;
-  --color-border: #2a2926;
-  --color-text: #d9d7d4;
-  --color-text-body: #aeada9;
-  --color-text-secondary: #8c8b86;
-  --color-muted: #7f7f7c;
-  --color-accent: #c76b5f;
+  --color-background: #0e0e0e;
+  --color-surface: #141414;
+  --color-chrome: #1a1a1a;
+  --color-border: #292929;
+  --color-text: #dddddd;
+  --color-text-body: #b2b2b2;
+  --color-text-secondary: #8e8e8e;
+  --color-muted: #7f7f7f;
+  --color-accent: #ececec;
   --color-success: #61c454;
-  --color-light-background: #fbfaf8;
-  --color-light-surface: #f1f1ee;
-  --color-light-chrome: #e9e8e5;
-  --color-light-text: #2c2c29;
-  --color-light-text-body: #4b4947;
-  --color-light-text-secondary: #666561;
-  --color-light-muted: #6e6d6c;
-  --color-light-accent: #ad4a4b;
+  --color-light-background: #fafafa;
+  --color-light-surface: #f1f1f1;
+  --color-light-chrome: #e8e8e8;
+  --color-light-text: #252525;
+  --color-light-text-body: #444444;
+  --color-light-text-secondary: #5f5f5f;
+  --color-light-muted: #6c6c6c;
+  --color-light-accent: #191919;
   --color-light-success: #2d6b22;
-  --color-light-border: #d5d4d1;
+  --color-light-border: #d4d4d4;
   --space-xs: 0.25rem;
   --space-sm: 0.5rem;
   --space-md: 0.875rem;

package/src/design/board.ts

@@ -10,6 +10,7 @@ import {
 import { join, relative, sep } from 'node:path'
 import { DESIGN_DOCUMENT } from '@/design/regen'
 import { renderDesignDoc } from '@/design/render'
+import { NEUTRAL_TOKENS } from '@/design/neutral'
 import { colorValue } from '@/design/tokens'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { recordDir } from '@/record-root'
@@ -131,6 +132,16 @@ const SCROLLSPY_SCRIPT = [
   '})();</script>',
 ].join('')
 
+/**
+ * A role's toolkit value, falling back to the neutral install base's where the
+ * toolkit record drops the role, so the board never restates a hex of its own.
+ */
+function roleColor(role: string): string {
+  const value = colorValue(role) ?? colorValue(role, NEUTRAL_TOKENS)
+  if (value === undefined) throw new Error(`No design token declares ${role}`)
+  return value
+}
+
 /**
  * The same brand mark `src/design/render.ts` embeds in its own preview,
  * colored with the dark accent since the board's default chrome is dark
@@ -139,7 +150,7 @@ const SCROLLSPY_SCRIPT = [
  * copies rather than a shared icon helper for the first second caller.
  */
 function faviconLink(): string {
-  const color = colorValue('accent') ?? '#e0724b'
+  const color = roleColor('accent')
   const href = `data:image/svg+xml,${encodeURIComponent(
     `<svg xmlns="http://www.w3.org/2000/svg" viewBox="10 10 80 80"><path d="M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z" fill="${color}" /><rect x="44" y="15" width="12" height="70" rx="2" fill="${color}" /></svg>`,
   )}`
@@ -232,12 +243,12 @@ ${SCROLLSPY_SCRIPT}
 }
 
 function panelPage(title: string, body: string): string {
-  const accent = colorValue('light-accent') ?? '#a4471c'
-  const surface = colorValue('light-surface') ?? '#f4efe6'
-  const border = colorValue('light-border') ?? '#e4dcd0'
-  const muted = colorValue('light-muted') ?? '#726b62'
-  const text = colorValue('light-text') ?? '#1a1815'
-  const background = colorValue('light-background') ?? '#faf7f2'
+  const accent = roleColor('light-accent')
+  const surface = roleColor('light-surface')
+  const border = roleColor('light-border')
+  const muted = roleColor('light-muted')
+  const text = roleColor('light-text')
+  const background = roleColor('light-background')
 
   return `<!doctype html>
 <html lang="en">

package/src/design/neutral.ts

@@ -0,0 +1,127 @@
+import type { ColorToken, DesignTokens } from '@/design/tokens'
+import { TOKENS } from '@/design/tokens'
+
+/**
+ * The token set `canon design install` hands a target, achromatic so the only
+ * palette a target renders is one it wrote under `.claude/design/project/`.
+ * Type, spacing, and radii are this repository's by spread, and only the color
+ * list is a second copy, held to the same roles by `neutral.test.ts`.
+ *
+ * Grounds, surface, chrome, and border take the OKLCH lightness of the toolkit
+ * role they replace at chroma 0. Text roles are solved against `surface` for
+ * the contrast targets `TOKENS` records (13.5, 8.6, 5.6, 4.6), and the accent
+ * for 15.5, past `text` so it still reads apart from body copy. The state
+ * roles keep the toolkit's values, since a state color is a meaning rather
+ * than a palette.
+ */
+
+const DARK_GROUNDS = ['background', 'surface'] as const
+const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
+
+function toolkitRole(role: string): ColorToken {
+  const token = TOKENS.color.find((candidate) => candidate.role === role)
+  if (token === undefined) throw new Error(`TOKENS declares no ${role} role`)
+  return token
+}
+
+const NEUTRAL_COLOR: readonly ColorToken[] = [
+  { role: 'background', intent: 'page canvas', value: '#0e0e0e' },
+  {
+    role: 'surface',
+    intent: 'cards, panels, raised blocks',
+    value: '#141414',
+  },
+  {
+    role: 'chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#1a1a1a',
+  },
+  { role: 'border', intent: 'every rule and panel edge', value: '#292929' },
+  {
+    role: 'text',
+    intent: 'headings, counts, emphasized runs',
+    value: '#dddddd',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-body',
+    intent: 'default body copy',
+    value: '#b2b2b2',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'text-secondary',
+    intent: 'labels, captions, supporting copy',
+    value: '#8e8e8e',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'muted',
+    intent: 'the faintest step, trailing notes',
+    value: '#7f7f7f',
+    grounds: DARK_GROUNDS,
+  },
+  {
+    role: 'accent',
+    intent: 'install command, mark, primary action',
+    value: '#ececec',
+    grounds: DARK_GROUNDS,
+  },
+  toolkitRole('success'),
+  toolkitRole('warning'),
+  toolkitRole('error'),
+  {
+    role: 'light-background',
+    intent: 'page canvas on a light ground',
+    value: '#fafafa',
+  },
+  {
+    role: 'light-surface',
+    intent: 'cards and panels on a light ground',
+    value: '#f1f1f1',
+  },
+  {
+    role: 'light-chrome',
+    intent: 'the window titlebar, one step above the canvas',
+    value: '#e8e8e8',
+  },
+  {
+    role: 'light-text',
+    intent: 'primary text on a light ground',
+    value: '#252525',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-body',
+    intent: 'default body copy on a light ground',
+    value: '#444444',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-text-secondary',
+    intent: 'labels, captions, supporting copy on a light ground',
+    value: '#5f5f5f',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-muted',
+    intent: 'secondary text on a light ground',
+    value: '#6c6c6c',
+    grounds: LIGHT_GROUNDS,
+  },
+  {
+    role: 'light-accent',
+    intent: 'links and primary action on light',
+    value: '#191919',
+    grounds: LIGHT_GROUNDS,
+  },
+  toolkitRole('light-success'),
+  {
+    role: 'light-border',
+    intent: 'rules and panel edges on light',
+    value: '#d4d4d4',
+    verify: true,
+  },
+]
+
+export const NEUTRAL_TOKENS: DesignTokens = { ...TOKENS, color: NEUTRAL_COLOR }

package/src/design/regen.ts

@@ -2,10 +2,12 @@ import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { buildDesignCss } from '@/design/css'
 import { renderDesignDocument } from '@/design/document'
+import { NEUTRAL_TOKENS } from '@/design/neutral'
 
 /**
- * The two artifacts the token source produces, written by `canon design regen`
- * and asserted for drift by the `design` stage of `bun run check`.
+ * The two artifacts the token sources produce, written by `canon design regen`
+ * and asserted for drift by the `design` stage of `bun run check`. The
+ * document renders from `TOKENS` and the stylesheet from `NEUTRAL_TOKENS`.
  *
  * The document is what a person reads and the stylesheet is what a target
  * installs, and neither is edited by hand. That is the cost the operator took
@@ -26,7 +28,7 @@ export const DESIGN_DOCUMENT = join('canon', 'DESIGN.md')
 export const DESIGN_BASE_CSS = join('src', 'design', 'base.css')
 
 const BASE_BANNER = [
-  'Generated by `canon design regen` from src/design/tokens.ts. Do not edit.',
+  'Generated by `canon design regen` from src/design/neutral.ts. Do not edit.',
   'This is the base half of a design install. A target overrides a value in',
   '.claude/design/project/, which the three-way merge leaves alone, so this',
   'file changes freely and nothing a project wrote lives in it.',
@@ -50,7 +52,7 @@ export function regenDesign(root: string): RegenResult {
     cssPath: write(
       root,
       DESIGN_BASE_CSS,
-      buildDesignCss(undefined, { banner: BASE_BANNER }),
+      buildDesignCss(NEUTRAL_TOKENS, { banner: BASE_BANNER }),
     ),
   }
 }

package/src/design/tokens.ts

@@ -386,8 +386,11 @@ export const TOKENS: DesignTokens = {
 }
 
 /** A role's value, or `undefined` where the record declares no such role. */
-export function colorValue(role: string): string | undefined {
-  return TOKENS.color.find((token) => token.role === role)?.value
+export function colorValue(
+  role: string,
+  tokens: DesignTokens = TOKENS,
+): string | undefined {
+  return tokens.color.find((token) => token.role === role)?.value
 }
 
 /**

package/src/gate/stages.ts

@@ -209,10 +209,10 @@ export const STAGES: readonly Stage[] = [
     success: 'Hero clean',
   },
   {
-    // `canon/DESIGN.md`, the base stylesheet, the web stylesheet, and the
-    // tab icon are all written from `src/design/tokens.ts` and none is edited
-    // by hand. Four artifacts from one source is the cost of the token move,
-    // and a render step that has to run is only safe while something fails
+    // `canon/DESIGN.md`, the web stylesheet, and the tab icon are written
+    // from `src/design/tokens.ts`, the base stylesheet from
+    // `src/design/neutral.ts`, and none is edited by hand. Four artifacts
+    // from two token sources is the cost of the token move, and a render step that has to run is only safe while something fails
     // when it did not, which is this.
     id: 'design',
     label: 'Design',