@erclx/canon 4.8.1 → 4.9.1

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.8.1",
+  "version": "4.9.1",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-teach/SKILL.md

@@ -95,12 +95,22 @@ canon teach lesson <topic> --json \
 It writes nothing and reports four things:
 
 - `lesson`, the numbered path the lesson takes. Write it there.
-- `stylesheet` with `stylesheetExists` and `stylesheetHref`. Write the stylesheet only when it reports absent, which is the first lesson in the workspace. Every lesson after that links the file already on disk and adds to it rather than replacing it, since overwriting discards what the last lesson put there.
+- `stylesheet` with `stylesheetExists` and `stylesheetHref`. Link it at `stylesheetHref` and seed it through the verb below when `stylesheetExists` is false, which is the first lesson in the workspace. Every lesson after that links the file already on disk and adds to it rather than replacing it, since overwriting discards what the last lesson put there.
 - `success`, the mission's success lines, carried here so Step 5 needs no second read.
 - `quiz`, one entry per question, carrying `order` and `answer`.
 
 Write the correct option first, then present the options in the order `order` reports, reading it as authored indices where `0` is the correct one. Take the order as given. Position drawn here rather than chosen is the whole reason the verb exists, and a lesson that reorders on its own judgment puts the answer back in the first slot.
 
+Seed the stylesheet through the verb rather than authoring a palette, on the first lesson in a workspace:
+
+```bash
+canon teach stylesheet <topic> --json
+```
+
+It writes the design tokens as custom properties and the components built on them, from the one source every other rendered surface reads. Add lesson rules under the seed and reach a value through its property rather than restating the hex, which is what let each workspace fork the palette from every other. It refuses to overwrite, so running it again on a workspace that has grown its own rules is safe and reports `written` as false.
+
+Report it rather than proceeding silently when the verb does not resolve, which is an installed CLI predating it. Do not fall back to writing a palette by hand.
+
 Add every term the lesson defines to `GLOSSARY.md` through the verb, which places the entries alphabetically in the shape the standard fixes:
 
 ```bash

package/docs/agents/commands.md

@@ -22,6 +22,10 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon indexes regen`         | Regenerate `index.md` files from sibling frontmatter                                                                                                                  |
 | `canon docs [topic]`          | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                              |
 | `canon design render`         | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                     |
+| `canon design regen`          | Rewrite this repository's `.claude/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                   |
+| `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 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)                                                                                                           |
 | `canon feedback`              | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`                                                                |
@@ -36,6 +40,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon teach open`            | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                                       |
 | `canon teach resource`        | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                                                 |
 | `canon teach glossary`        | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                                                   |
+| `canon teach stylesheet`      | Seed a workspace stylesheet from the design source, leaving an existing one alone without `--force` (`--json`)                                                        |
 | `canon records validate`      | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                                          |
 | `canon records migrate`       | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)                                                                        |
 | `canon records size`          | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                                          |
@@ -112,11 +117,11 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `demo`      | `compile`, `run`                                                                                                                      |
 | `inventory` | `run`                                                                                                                                 |
 | `wiki`      | `init`                                                                                                                                |
-| `design`    | `render`                                                                                                                              |
+| `design`    | `regen`, `css`, `render`, `install`, `sync`                                                                                           |
 | `slides`    | `render`, `list`                                                                                                                      |
 | `tasks`     | `archive`, `validate`                                                                                                                 |
 | `intake`    | `list`, `answer`                                                                                                                      |
-| `teach`     | `list`, `open`, `resource`, `glossary`                                                                                                |
+| `teach`     | `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`                                                                        |
 | `comments`  | `scan`                                                                                                                                |
 | `context`   | `audit`                                                                                                                               |
 | `markdown`  | `audit`                                                                                                                               |
@@ -137,7 +142,9 @@ Common patterns:
 
 `migrate rename` moves a project off the retired `aitk` name. It reports until `--write` is passed, and `--scope target` rewrites the toolkit-owned folders alone, reporting every other citation as one the project owns rather than editing prose somebody wrote. A project installing `canon` fresh never needs it.
 
-`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first. A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. Running it twice rewrites nothing, which is the check that the exclusions and the markers fired.
+`migrate records` moves a project's session records from `.claude/` to `.canon/` and rewrites every tracked file that cites one. It reports until `--write` is passed, and refuses outright when the project does not already ignore `.canon/`, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. Take the ignore entry with `canon tooling sync --write` first.
+
+A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
 ## Version skew
 

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

@@ -27,7 +27,29 @@ number bands behind that placement, where `900-999` is the range a
 project-authored rule takes and everything below it belongs to the toolkit.
 
 `canon sync --check` does not report an orphaned entry. It skips every one, so
-the destination reaches `canon gov sync` alone, the one domain sync verb left.
+the destination reaches `canon gov sync` alone among the two per-file domain
+syncs, since design's own orphans are the target's overrides and are meant to
+stay where they are.
+
+`canon design install` copies one toolkit-owned file to
+`.claude/design/base.css` and creates no override. A project overrides a value
+by writing `.claude/design/project/` itself, which `canon design sync` never
+touches, because that subfolder is project-authored by location the way
+`.claude/rules/project/` is. An override named exactly like the shipped file is
+still the project's.
+
+The override ships absent rather than empty. An empty file is one the project
+did not ask for and did not write, the reconciliation already handles a missing
+side, and an empty override invites a target to fill it before it has an
+opinion.
+
+Nothing arrives on a project that has not run `canon design install`. The
+domain is detected by that folder existing, so `canon sync` skips it entirely on
+a target that never installed it, and the unstamped line at the end of
+`canon sync --check` stays quiet about it for the same reason. Governance is
+named there when it is absent and design is not, because a managed project
+without governance has yet to install what every project carries, while one
+without design chose that.
 
 When the target's install recorded a stack, `canon gov sync` also reports a
 rule that stack lists and `.claude/rules/` does not hold, as a `missing` entry

package/docs/agents/teach.md

@@ -125,6 +125,8 @@ It reports four things. `lesson` is the numbered path the lesson takes, derived
 
 The stylesheet is reported rather than written. A verb that wrote it on every lesson would discard whatever the last lesson added, and the second lesson in a workspace is the one that needs the file the first one left.
 
+`canon teach stylesheet <topic>` is what writes it, seeded from the design source so a workspace renders in the system every other surface does. It refuses to overwrite, reporting `written` as false where the workspace already carries one, and `--force` takes the seed back over it. Each workspace used to carry a hand-authored palette, which is how the course styling forked once per workspace, so a lesson adds its own rules under the seed and reaches a value through its custom property rather than restating the hex.
+
 Each `quiz` entry carries `order`, the authored option indices in presentation order where index `0` is the correct answer, and `answer`, the one-based position that answer lands in. Both travel together because a caller deriving the position itself is a caller that can derive it wrongly.
 
 The order is drawn here rather than instructed, and that is the point of the verb. An author told to vary the position still varies it by judgment, and the judgment settles on the first slot, which is the defect this design departs from. The draw is uniform over the options, so the position carries no information about which answer is correct.

package/docs/target-projects.md

@@ -128,15 +128,17 @@ When the toolkit updates, target projects pull changes per domain. There is one
 
 Session records moved out of `.claude/` and into a root of their own. What is committed stays where it is, and everything gitignored, being the task board, the plans, the memory pen, the review reports, and the scratch folder, now lives under `.canon/`, which a single ignore entry covers.
 
-**`canon migrate records` is not in a published release yet.** It ships with the change that split the roots, so an installed binary answers `unknown command` until the next release carries it. Until then, run it out of a canon checkout against the project by path:
+`4.7.0` carries `canon migrate records`, so run these three lines from inside the project. Run `canon upgrade` first regardless of what you hold, since the sweep learned to pass over the records themselves after that release and a `4.7.0` binary rewrites them.
 
 ```bash
 canon tooling sync claude . --write
-bun src/cli.ts migrate records --root /path/to/project --json
-bun src/cli.ts migrate records --root /path/to/project --write --json
+canon migrate records --json
+canon migrate records --write --json
 ```
 
-Once the release lands, the same three lines read `canon migrate records` from inside the project. Either way the first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+The first line takes the `.canon/` ignore entry, and the verb refuses until the project has it, since every folder it relocates is ignored where it stands and landing one under a tracked root commits the memory pen. The second reports the plan and the third applies it, moving the folders and repointing every tracked file that cites one.
+
+Order matters between the first line and the two under it. The sync prunes the twelve old `.claude/` ignore entries down to the one `.canon/` line, which leaves every record still at the old root visible to git and therefore to the verb. The sweep passes over them on purpose, reporting a count of what it left alone rather than reading the memory pen and the groundwork trails as source.
 
 Read the `ok` field out of the `--json` record rather than the exit code. A shell profile that wraps `canon` in a function takes its status from whatever the function runs last, so an absent subcommand and a clean run can both exit 0, and a reader watching the exit alone concludes the move happened.
 

package/docs/visual-design-workflow.md

@@ -24,6 +24,8 @@ The toolkit seed in `tooling/claude/seeds/.claude/DESIGN.md` ships a token-table
 
 The `canon:claude-design-extract` skill drafts the file, sourcing tokens from a project's existing prose and CLI UI surfaces, or proposing them from `.claude/REQUIREMENTS.md` and a `## Personality` paragraph when no UI code exists yet. `canon design render` writes an HTML plus CSS preview to `.canon/review/design/` for eyeballing the current system without leaving Claude Code. See `.claude/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 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.
 
 ### Tools

package/package.json

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

package/src/commands/design.ts

@@ -1,14 +1,80 @@
-import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs'
+import { basename, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
-import { creationRel } from '@/record-root'
+import {
+  createDesignAdapter,
+  DESIGN_INSTALL_DIR,
+  DESIGN_PROJECT_SUBDIR,
+} from '@/design/adapter'
+import { buildDesignCss } from '@/design/css'
 import { renderDesignDoc } from '@/design/render'
-import { palette } from '@/ui'
+import { DESIGN_BASE_CSS, DESIGN_DOCUMENT, regenDesign } from '@/design/regen'
+import { PROJECT_ROOT } from '@/project-root'
+import { creationRel } from '@/record-root'
+import { recordStamp, runDomainSync } from '@/sync/engine'
+import { resolveTarget } from '@/target'
+import { intro, logAdd, logError, logInfo, outro, palette } from '@/ui'
 
 export function register(program: Command): void {
   const design = program
     .command('design')
-    .description('Design system commands (render)')
+    .description('Design system commands (regen, css, render, install, sync)')
+
+  design
+    .command('regen')
+    .description(
+      'Rewrite .claude/DESIGN.md and the base stylesheet from src/design/tokens.ts',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Unlike install and sync, this runs against the toolkit checkout rather',
+        'than a target. It rewrites the record and the base stylesheet from the',
+        'token module and refuses where the record is absent, which is what the',
+        'CLI installed into a project as a dependency looks like.',
+        '',
+      ].join('\n'),
+    )
+    .action(() => {
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
+
+      // Both outputs resolve from `PROJECT_ROOT`, which is the installed
+      // package directory when the CLI runs out of a target's `node_modules`.
+      // The record is the one output that is already committed here and ships
+      // with no package, so its absence is what separates the two.
+      if (!existsSync(join(PROJECT_ROOT, DESIGN_DOCUMENT))) {
+        process.stderr.write(
+          `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} No ${DESIGN_DOCUMENT} at ${PROJECT_ROOT}. Regen runs in the toolkit checkout, not against a target.\n${GREY}└${NC}\n`,
+        )
+        process.exitCode = 1
+        return
+      }
+
+      process.stderr.write(
+        `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Regenerate design source${NC}\n`,
+      )
+      const result = regenDesign(PROJECT_ROOT)
+      for (const path of [result.documentPath, result.cssPath]) {
+        process.stderr.write(
+          `${GREY}│${NC} ${GREEN}✓${NC} ${relative(PROJECT_ROOT, path)}\n`,
+        )
+      }
+      process.stderr.write(`${GREY}└${NC}\n`)
+    })
+
+  design
+    .command('css')
+    .description('Emit the design tokens and components as CSS on stdout')
+    .option(
+      '--no-components',
+      'Custom properties only, without the component rules',
+    )
+    .action((opts: { components: boolean }) => {
+      process.stdout.write(
+        buildDesignCss(undefined, { components: opts.components }),
+      )
+    })
 
   design
     .command('render')
@@ -38,4 +104,80 @@ export function register(program: Command): void {
         `${GREY}│${NC} ${GREEN}✓${NC} ${result.htmlPath}\n${GREY}│${NC} ${GREEN}✓${NC} ${result.cssPath}\n${GREY}└${NC}\n`,
       )
     })
+
+  design
+    .command('install')
+    .description('Install the base stylesheet into a project')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Installs one toolkit-owned file and creates no override. A project',
+        `overrides a value by writing ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/`,
+        'itself, which sync never touches. Nothing arrives on a project that',
+        'has not run this, so a design value reaches a target on an install',
+        'rather than on the next sync.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string) => {
+      process.exitCode = await runInstall(target)
+    })
+
+  design
+    .command('sync')
+    .description(
+      'Update the base stylesheet already installed under .claude/design/',
+    )
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runDomainSync(
+        createDesignAdapter(PROJECT_ROOT),
+        target,
+        { protectedRoot: PROJECT_ROOT },
+      )
+    })
+}
+
+/**
+ * Copies the base and stops. The override folder is deliberately not created:
+ * an empty override is a file the project did not ask for and did not write,
+ * the three-way merge already handles a missing side, and an empty file invites
+ * a target to fill it before it has an opinion.
+ */
+async function runInstall(target: string): Promise<number> {
+  intro('canon design install')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') {
+    outro()
+    return resolved
+  }
+
+  const source = join(PROJECT_ROOT, DESIGN_BASE_CSS)
+  if (!existsSync(source)) {
+    logError(
+      `No base stylesheet at ${DESIGN_BASE_CSS}. Run canon design regen.`,
+    )
+    outro()
+    return 1
+  }
+
+  const dir = join(resolved, DESIGN_INSTALL_DIR)
+  mkdirSync(dir, { recursive: true })
+
+  const dest = join(dir, basename(source))
+  copyFileSync(source, dest)
+  logAdd(relative(resolved, dest))
+
+  await recordStamp(createDesignAdapter(PROJECT_ROOT), resolved, new Date())
+
+  logInfo(
+    `Override a value in ${join(DESIGN_INSTALL_DIR, DESIGN_PROJECT_SUBDIR)}/, which sync leaves alone.`,
+  )
+  outro()
+  return 0
 }

package/src/commands/migrate.ts

@@ -6,6 +6,7 @@ import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
 import {
   ignoresDestination,
+  isRecordArtifact,
   planRecordsMove,
   type RecordsPlan,
 } from '@/migrate/records'
@@ -176,17 +177,24 @@ async function runRecords(opts: RecordsOptions): Promise<number> {
     return 1
   }
 
-  const plan = planRecordsMove(root, await readSources(root, files))
+  // Filtered before the read rather than inside the planner, because the
+  // records are the largest thing in the tree and `readSources` awaits one file
+  // at a time. This repository's own record tree is 9,744 files at 83M, and the
+  // backup history under it is object files read whole and discarded as binary.
+  const toSweep = files.filter((path) => !isRecordArtifact(path))
+  const records = files.length - toSweep.length
+
+  const plan = planRecordsMove(root, await readSources(root, toSweep))
 
   // stdout, so the record pipes clean. `pipeOutput` frames to stderr, which is
   // where this command's report belongs and where a JSON record does not.
   if (opts.json) {
     process.stdout.write(
-      `${JSON.stringify(toRecordsRecord(plan, opts.write))}\n`,
+      `${JSON.stringify(toRecordsRecord(plan, records, opts.write))}\n`,
     )
   }
 
-  reportRecords(plan)
+  reportRecords(plan, records)
 
   if (plan.collisions.length > 0) {
     logError(
@@ -229,7 +237,7 @@ function readGitignore(root: string): string | undefined {
   }
 }
 
-function reportRecords(plan: RecordsPlan): void {
+function reportRecords(plan: RecordsPlan, records: number): void {
   logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
   for (const move of plan.moves) logInfo(`  ${move.from} -> ${move.to}`)
   logInfo(
@@ -237,6 +245,14 @@ function reportRecords(plan: RecordsPlan): void {
   )
   logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
 
+  // A count rather than a list, and its own line rather than a place in
+  // `excluded`. That field exists so a reader can go and check a handful by
+  // hand, and a record tree would bury them. The count is what answers the
+  // question a target actually has, which is where the rest of the files went.
+  if (records > 0) {
+    logInfo(`${plural(records, 'file')} under a record root, left alone.`)
+  }
+
   if (plan.excluded.length > 0) {
     logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep.`)
   }
@@ -244,6 +260,7 @@ function reportRecords(plan: RecordsPlan): void {
 
 function toRecordsRecord(
   plan: RecordsPlan,
+  records: number,
   wrote: boolean | undefined,
 ): unknown {
   return {
@@ -255,6 +272,7 @@ function toRecordsRecord(
     rewritten: plan.rewritten,
     kept: plan.kept,
     excluded: plan.excluded.length,
+    records,
     paths: plan.entries.map((entry) => ({
       path: entry.path,
       rewritten: entry.rewritten,
@@ -294,6 +312,11 @@ export function register(program: Command): void {
         'A line carrying canon-keep-record-root, or the line below it, keeps the',
         'old root. Prose that dates a decision needs it; a live path does not.',
         '',
+        'The records themselves are never swept. Everything under .canon/ and',
+        'every .claude/ record folder is left alone and reported as a count, so',
+        'a run after the ignore entries collapse touches the same files as one',
+        'before it.',
+        '',
         'Examples:',
         '  canon migrate records',
         '  canon migrate records --write',

package/src/commands/sync.ts

@@ -7,7 +7,7 @@ import {
   buildCheckReport,
   type CheckReport,
   hasDrift,
-  SCANNED_DOMAINS,
+  uncoveredDomains,
 } from '@/sync/check'
 import { createGitRunner, createPullRequestOpener, hasGh } from '@/sync/git'
 import {
@@ -35,6 +35,7 @@ import { describeSkew } from '@/version/skew'
 
 const SYNC_ARGS: Record<SyncDomain, readonly string[]> = {
   governance: ['gov', 'sync'],
+  design: ['design', 'sync'],
   claude: ['claude', 'sync'],
 }
 
@@ -195,10 +196,7 @@ function renderCheck(report: CheckReport): void {
   // naming it here repeats what that section already said under a second
   // remedy, where a scanned domain nobody installed has no section at all and
   // this line is the only place it appears.
-  const unmigrated = report.unmigrated.map((entry) => entry.domain)
-  const uncovered = SCANNED_DOMAINS.filter(
-    (domain) => !report.covers.includes(domain) && !unmigrated.includes(domain),
-  )
+  const uncovered = uncoveredDomains(report)
   if (uncovered.length === 0) return
 
   const { GREY, NC } = palette(process.stderr)

package/src/commands/teach.ts

@@ -16,6 +16,7 @@ import {
   type Term,
   type TermOutcome,
   type WorkspaceSummary,
+  writeStylesheet,
 } from '@/teach/workspace'
 import {
   intro,
@@ -276,6 +277,77 @@ export function register(program: Command): void {
     .action(async (topic: string, opts: LessonCommandOptions) => {
       process.exitCode = await runLesson(topic, opts)
     })
+
+  teach
+    .command('stylesheet')
+    .description('Seed a workspace stylesheet from the design source')
+    .argument('<topic>', 'Workspace folder or topic, as in regular-expressions')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--force', 'Rewrite a stylesheet the workspace already carries')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Teach root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the workspace carries a stylesheet, written now or already there',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'The file it writes carries the design tokens as custom properties and',
+        'the component rules built on them, so a workspace renders in the same',
+        'system every other surface does. Add lesson rules under the seed and',
+        'read a value through its property rather than restating the hex.',
+        '',
+        'An existing stylesheet is left alone, since a workspace adds to this',
+        'file as it goes. Pass --force to take the seed back over it.',
+        '',
+        'Examples:',
+        '  canon teach stylesheet regular-expressions --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string, opts: StylesheetCommandOptions) => {
+      process.exitCode = await runStylesheet(topic, opts)
+    })
+}
+
+interface StylesheetCommandOptions {
+  readonly force?: boolean
+  readonly json?: boolean
+  readonly root?: string
+}
+
+async function runStylesheet(
+  topic: string,
+  opts: StylesheetCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = await rootFor(opts.root)
+  const outcome = await writeStylesheet(root, topic, opts.force ?? false)
+
+  if (!outcome.ok) {
+    return reportRefusal('canon teach stylesheet', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        path: outcome.path,
+        written: outcome.written,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon teach stylesheet')
+  logStep(outcome.written ? 'Written' : 'Already present, left alone')
+  logInfo(outcome.path)
+  outro()
+  return 0
 }
 
 function collect(value: string, previous: string[]): string[] {

package/src/design/adapter.ts

@@ -0,0 +1,59 @@
+import { basename, join } from 'node:path'
+import { DESIGN_BASE_CSS } from '@/design/regen'
+import type { InstalledFile, SyncAdapter } from '@/sync/engine'
+
+/**
+ * The channel a design value reaches a target on.
+ *
+ * Base plus a target-owned override, reconciled by the three-way merge the sync
+ * engine already implements. Overwrite was dropped before this was built and
+ * the reason is a measurement rather than an argument: a headless sync in
+ * another domain deleted a deploy job, replaced a screenshot harness, and
+ * reverted a shipped fix, because naming a stack was read as consent to lose an
+ * edit inside it.
+ *
+ * Layering is what bounds what the merge has to arbitrate. Nothing a project
+ * wrote lives in the base, so the base changes freely, and the merge shrinks to
+ * the properties a target actually overrode.
+ */
+
+/** The folder a design install writes into, under the target's `.claude/`. */
+export const DESIGN_INSTALL_DIR = join('.claude', 'design')
+
+/**
+ * Where a target's own values go. `projectSubdir` makes every file here
+ * project-authored by location rather than by the name inference, so an
+ * override named `base.css` is still the target's and never overwritten.
+ *
+ * It ships absent rather than empty. An empty override is a file a project did
+ * not ask for and did not write, the merge already handles a missing side, and
+ * an empty file invites a target to fill it before it has an opinion.
+ */
+export const DESIGN_PROJECT_SUBDIR = 'project'
+
+export function designSourceDir(root: string): string {
+  return join(root, 'src', 'design')
+}
+
+export function createDesignAdapter(root: string): SyncAdapter {
+  const base = join(root, DESIGN_BASE_CSS)
+
+  return {
+    banner: 'canon design sync',
+    label: 'design',
+    missingMessage:
+      "No design surface found in target. Run 'canon design install' first.",
+    unit: 'changes',
+    installPattern: '**/*.css',
+    installedRoot: (target: string) => join(target, DESIGN_INSTALL_DIR),
+    /**
+     * One shipped file, matched by name the way the gov adapter matches a rule,
+     * so a base that moved inside the toolkit still syncs into the place the
+     * target already holds it.
+     */
+    locateSource: (file: InstalledFile) =>
+      basename(file.path) === basename(base) ? base : undefined,
+    projectSubdir: DESIGN_PROJECT_SUBDIR,
+    stamp: { domain: 'design', toolkitRoot: root },
+  }
+}