@erclx/canon 4.49.0 → 4.51.0

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

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

package/claude/skills/docs-draft/REQUIREMENT.md

@@ -0,0 +1,35 @@
+---
+name: docs-draft
+description: Why a brand-new docs/*.md page needs a placement decision and a confirm step, not the rewrite path docs-sync already owns
+---
+
+# Docs draft requirement
+
+## Gap
+
+Without this skill, a session drafting documentation for a surface that has no page yet either invents structure from memory or reaches for `docs-sync`, which has nothing to diff a nonexistent page against and reports the topic as unrelated to any change. Either way the page ships with no read of `standards/docs.md` and no catalog placement decided against the folder's actual shelves.
+
+## Must
+
+- Read `standards/docs.md` before drafting, since the frontmatter contract and the four reader questions are what make the page arguable against a sibling
+- Decide placement from the existing catalog rather than guessing a folder, reusing a `category` value verbatim when one fits and defaulting to the `docs/` root when none does
+- Confirm the resolved path and the full content with the user before writing, since placement is a judgment call with no diff to preview it against
+- Run `canon indexes regen` on the containing folder after writing, so the folder's `index.md` picks up the new page immediately rather than drifting until the next unrelated regen
+
+## Must not
+
+- Rewrite an existing page. A topic already covered by a page refuses toward `docs-sync`.
+- Hand-edit an `index.md`. It regenerates from sibling frontmatter, and a hand edit is overwritten on the next regen.
+- Build a hand-drawn diagram-and-capture authoring loop. `standards/docs.md`'s Mermaid-fence permission is the only path to a diagram this skill takes.
+
+## Guards
+
+- No topic given: stop and ask what surface the page should cover.
+- The derived slug already resolves through `canon docs <slug>`: stop and point at `docs-sync` instead. This catches an exact-name collision only.
+- A page in the catalog already covers the topic under a different name: stop the same way, checked against the titles and descriptions Placement already reads.
+
+## Out of scope
+
+- Rewriting or syncing an existing `docs/*.md` section against a diff since main: `docs-sync`
+- The `.claude/` planning surface: `claude-docs`
+- Drafting a standard, a snippet, or a governance rule: `create-standard`, `create-snippet`, `create-rule`

package/claude/skills/docs-draft/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: docs-draft
+description: Drafts a brand-new `docs/*.md` page against `standards/docs.md`, decides its placement in the existing catalog, confirms with the user, then writes. Use when asked to "add a docs page for X", "write a new doc for X", "document X under docs/", or "create a docs page for X" where no existing page covers the topic. Do NOT use to rewrite or sync an existing `docs/*.md` section against a diff, which is `docs-sync`.
+---
+
+# Docs draft
+
+Drafts one brand-new `docs/*.md` page end to end: read the standard, decide where the page belongs in the existing catalog, confirm the draft with the user, then write.
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/docs.md`: the reader a page serves, its frontmatter, structure, and what it links out to rather than restates
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+
+## Guards
+
+- If no topic is given, stop: `❌ No topic given. Name the surface this page should cover.`
+- Derive a kebab-case slug from the topic and run `canon docs <slug>`. A resolved page means the topic is already covered under that exact name. Stop: `❌ <slug> already resolves to an existing page. Run canon:docs-sync instead.` This is a name match rather than a topic match. Placement below checks the wider case.
+
+## Placement
+
+- Read `docs/index.md` and its sub-catalogs for the closest existing `category`. <!-- canon-allow-reference: illustrates the target project's own docs/ tree, not a citation of this repository's own corpus -->
+- Check every page title and description this read surfaces against the topic. The Guards check above only catches an exact-slug collision, and a page already covering the same subject under a different slug still resolves here at no extra cost, since this read already runs. Stop the same way on a match: `❌ <path> already covers this topic under a different name. Run canon:docs-sync instead.`
+- Reuse a matching `category` value verbatim. A near-miss spelling opens a second shelf holding one page, per the docs standard.
+- Default to the `docs/` root with no `category` when nothing fits. A subfolder earns itself only once a shelf of pages already sits there, per the standard's splitting rule.
+
+## Draft
+
+- Draft `title`, `description`, and `category` (where one applies), then the page body, against `${CLAUDE_SKILL_DIR}/../../standards/docs.md`.
+- Write for a reader with no source open. The standard's four questions are the test: what the surface is, what to run or write, what it refuses, and where to go for the adjacent surface.
+
+## Confirm
+
+- Show the resolved path and the full drafted content before writing.
+- Confirm both with the user. This skill waits for that answer rather than treating the tool permission dialog as the gate, since placement here is a judgment call with no diff to preview it against.
+
+## Write
+
+- Write the file at the confirmed path, creating the folder when it is absent.
+- Run `canon markdown audit <path>`.
+- Run `canon indexes regen <folder>` on the containing folder, so its `index.md` picks up the new page.
+
+## Response format
+
+### Preview
+
+**Topic:** `<topic>`
+**Placement:** `<path>` (category: `<category-or-root>`)
+
+```markdown
+<drafted frontmatter and body>
+```
+
+### After confirmation
+
+```plaintext
+✅ Drafted: <path>
+```

package/docs/workflow/ai-workflow.md

@@ -290,6 +290,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:create-skill`       | For a new `SKILL.md`                                                  |
 | `canon:create-snippet`     | For a reusable prompt                                                 |
 | `canon:create-standard`    | For a new authoring convention                                        |
+| `canon:docs-draft`         | For a brand-new `docs/*.md` page, drafted against `standards/docs.md` |
 | `canon:bash-script`        | For an interactive, human-facing shell tool                           |
 | `canon:bash-cli-script`    | For a non-interactive automation, CI, or pipeline script              |
 | `canon:ci-workflow`        | For a GitHub Actions workflow file                                    |

package/package.json

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

package/src/claude/cases/authoring.ts

@@ -37,6 +37,11 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       "The docs folder and README are stale against what's on main, refresh them.",
     expect: 'docs-sync',
   },
+  {
+    prompt:
+      'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
+    expect: 'docs-draft',
+  },
   {
     prompt: 'Say what that dense answer actually means in plain terms.',
     expect: 'restate-plainly',

package/src/design/base.css

@@ -28,14 +28,22 @@
   --space-frame-top: 44px;
   --space-frame-inline: 52px;
   --space-frame-bottom: 38px;
+  --type-display-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-display-size: 34px;
   --type-display-lh: 1.3;
+  --type-page-display-family: Noto Sans, DejaVu Sans, sans-serif;
+  --type-page-display-size: 52px;
+  --type-page-display-lh: 1.1;
+  --type-heading-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-heading-size: 19px;
   --type-heading-lh: 1.3;
+  --type-body-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-body-size: 16px;
   --type-body-lh: 1.65;
+  --type-label-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-label-size: 12px;
   --type-label-lh: 1.45;
+  --type-code-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
   --type-code-size: 14.5px;
   --type-code-lh: 1.3;
   --radius-frame: 12px;

package/src/design/css.ts

@@ -76,6 +76,7 @@ function tokenProperties(tokens: DesignTokens): string[] {
   }
 
   for (const role of tokens.typography) {
+    lines.push(`  --type-${slug(role.role)}-family: ${role.family};`)
     lines.push(`  --type-${slug(role.role)}-size: ${role.size};`)
     lines.push(`  --type-${slug(role.role)}-lh: ${role.lineHeight};`)
   }

package/src/design/tokens.ts

@@ -68,9 +68,21 @@ export interface DesignTokens {
   readonly preamble: string
 }
 
-/** The one monospace stack every surface that renders text declares. */
+/** The monospace stack every surface but the landing page hero declares. */
 const MONO = 'Noto Sans Mono, DejaVu Sans Mono, monospace'
 
+/**
+ * The proportional stack the landing page hero declares and nothing else does.
+ * Noto Sans is the proportional sibling of the mono above rather than a face
+ * picked for taste, so the pairing is one superfamily rather than two systems.
+ *
+ * The stack stops at two names and a generic because `src/design/base.css` is
+ * written by `canon design regen` and formatted by prettier, and a declaration
+ * past 80 columns is wrapped by the second and flattened by the first. Every
+ * emitted line stays inside the width so the two writers never disagree.
+ */
+const SANS = 'Noto Sans, DejaVu Sans, sans-serif'
+
 const DARK_GROUNDS = ['background', 'surface'] as const
 const LIGHT_GROUNDS = ['light-background', 'light-surface'] as const
 
@@ -87,6 +99,8 @@ export const TOKENS: DesignTokens = {
 
   personality: [
     'Warm neutrals carry the frame under a single rust accent, rendered in the same monospace the terminal uses. The subject picks the register rather than taste: a toolkit whose primary surface is a shell has no proportional voice available, so the rendered surfaces match the terminal instead of the reverse. One accent carries every count, link, and primary action. Promoting a second and third into structural roles is what reads as a generated interface, so the palette stays at one.',
+    '',
+    'One surface is carved out of the sentence above, and it is the landing page hero. A rendered surface here shows a reader what the terminal did, so matching the terminal is what makes it legible. A public page addresses somebody who has never opened the terminal at all, and the shell has no voice available for that, which is the reverse of the case the rule was written for. The `page-display` role below is the whole of the carve-out. Every other role on that page stays monospace, including its body, its controls, and every frame it embeds, so the page reads as two families rather than as a second design system.',
   ].join('\n'),
 
   colorNote: [
@@ -193,7 +207,9 @@ export const TOKENS: DesignTokens = {
   ],
 
   typographyNote: [
-    'One family covers every role. The size scale runs from 11.5 to 34 pixels across ten values, and five of them map onto a role. The other five are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    'One family covers every role but `page-display`, which is the landing page hero and takes the proportional sibling of the same superfamily. The size scale runs from 11.5 to 52 pixels, and six values map onto a role. Five further values are adjustments inside a single component and get no role here, since a scale with five invented steps reads as a system the surfaces do not implement. They are 11.5, 12.5, 13, 14, and 15 pixels.',
+    '',
+    'The 52 pixel step sits above the 34 the rest of the scale tops out at, and it is the one size no other surface reaches. A hero headline set at the display cap reads as a section heading rather than an opening, which four rendered arms measured on 2026-09-04 before the step was added.',
     '',
     'A tagged cell is one no rendering surface exercises yet, which is a declaration the system has not tested rather than one it has.',
     '',
@@ -208,6 +224,14 @@ export const TOKENS: DesignTokens = {
       size: '34px',
       lineHeight: '1.3',
     },
+    {
+      role: 'page-display',
+      family: SANS,
+      weight: '700',
+      size: '52px',
+      lineHeight: '1.1',
+      verify: ['family', 'size', 'lineHeight'],
+    },
     {
       role: 'heading',
       family: MONO,

package/src/tasks/archive.ts

@@ -400,7 +400,8 @@ export async function planCitations(
 
   const stems = await listTaskStems(dir)
   if (!stems.includes(stem)) {
-    return refuse('no-match', `No task named ${stem} on the board.`, stems)
+    const unmatched = describeUnmatchedStem(stems, stem)
+    return refuse(unmatched.reason, unmatched.message, unmatched.detail)
   }
 
   const target = readPlanTarget(await readFile(join(dir, `${stem}.md`), 'utf8'))
@@ -488,6 +489,45 @@ function refuse(
   return { ok: false, reason, message, detail }
 }
 
+export interface UnmatchedStem {
+  readonly reason: 'no-match' | 'ambiguous'
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * The three-way refusal a bare stem earns once it fails an exact match:
+ * exactly one task starts with it, several do, or none does. `archive.ts`'s
+ * own `resolveStem`, `planCitations`, and `record.ts`'s `resolveStem` all
+ * refuse a stem this way, so the wording lives once rather than three times.
+ */
+export function describeUnmatchedStem(
+  stems: readonly string[],
+  name: string,
+): UnmatchedStem {
+  const prefixed = stems.filter((stem) => stem.startsWith(name))
+  if (prefixed.length === 1) {
+    const [match] = prefixed
+    return {
+      reason: 'no-match',
+      message: `${name} does not name a task by itself. One task starts with it: ${match}. Pass the full name instead.`,
+      detail: [match],
+    }
+  }
+  if (prefixed.length > 1) {
+    return {
+      reason: 'ambiguous',
+      message: `${name} does not name a task by itself. ${prefixed.length} tasks start with it. Pass the full name instead.`,
+      detail: prefixed,
+    }
+  }
+  return {
+    reason: 'no-match',
+    message: `No task named ${name} on the board.`,
+    detail: stems,
+  }
+}
+
 async function resolveStem(
   dir: string,
   selector: TaskSelector,
@@ -496,27 +536,11 @@ async function resolveStem(
 
   if (selector.kind === 'stem') {
     if (!stems.includes(selector.stem)) {
-      const prefixed = stems.filter((stem) => stem.startsWith(selector.stem))
-      if (prefixed.length === 1) {
-        const [match] = prefixed
-        return refuse(
-          'no-match',
-          `${selector.stem} does not name a task by itself. One task starts with it: ${match}. Pass the full name to archive it.`,
-          [match],
-        )
-      }
-      if (prefixed.length > 1) {
-        return refuse(
-          'ambiguous',
-          `${selector.stem} does not name a task by itself. ${prefixed.length} tasks start with it. Pass the full name to archive one.`,
-          prefixed,
-        )
-      }
-      return refuse(
-        'no-match',
-        `No task named ${selector.stem} on the board.`,
+      const { reason, message, detail } = describeUnmatchedStem(
         stems,
+        selector.stem,
       )
+      return refuse(reason, message, detail)
     }
     return selector.stem
   }

package/src/tasks/record.ts

@@ -3,6 +3,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 import { planCandidates } from '@/tasks/answers'
 import {
+  describeUnmatchedStem,
   fenceMask,
   linkTo,
   listTaskStems,
@@ -241,11 +242,11 @@ async function resolveStem(
 
   if (selector.kind === 'stem') {
     if (!stems.includes(selector.stem)) {
-      return refuse(
-        'no-match',
-        `No task named ${selector.stem} on the board.`,
+      const { reason, message, detail } = describeUnmatchedStem(
         stems,
+        selector.stem,
       )
+      return refuse(reason, message, detail)
     }
     return selector.stem
   }

package/tooling/astro/configs/playwright.config.ts

@@ -22,5 +22,6 @@ export default defineConfig({
     command: 'bun run build && bun run preview',
     url: baseURL,
     reuseExistingServer: false,
+    env: { ASTRO_PREVIEW_BACKGROUND: '0' },
   },
 })

package/tooling/web/manifest.toml

@@ -49,6 +49,7 @@ packages = [
 "check:full" = "./scripts/verify.sh && bun run test:e2e"
 
 [scripts.override]
+"lint" = "eslint . --max-warnings 0"
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
 
 [gitignore]

package/tooling/web/reference.md

@@ -53,6 +53,7 @@ Sticky negative knowledge. Do not relearn.
 
 - Do NOT use `tsc -b` in a Vite project. Composite mode emits `.js` next to `.ts` and ESLint lints the emitted files. Use `tsc --noEmit`.
 - Do NOT accept `eslint@^10` alongside `typescript-eslint@^8`. Chain breaks with `TypeError: Class extends value undefined` from `LegacyESLint`. Pin `eslint@^9` until `typescript-eslint@^9` with ESLint 10 support ships.
+- Do NOT trust `vite-react`'s scaffolded `lint` script. It ships its own `"lint": "oxlint"` under a bare `.oxlintrc.json`, which runs a different rule set from the stack's ESLint config and never gates on it. `[scripts.override]` forces the stack's own eslint invocation back over it.
 - Do NOT rely on bare-folder exclude globs like `exclude: ["e2e"]`. Use `"e2e/**/*"`.
 - Do NOT ship Vitest with no-tests-fail. Fresh scaffolds have zero tests. Use `passWithNoTests: true` or equivalent until the project has at least one test.
 - Do NOT put Playwright `trace` at the top level of `defineConfig`. It lives under `use`.