@erclx/canon 4.50.0 → 4.52.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.50.0",
+  "version": "4.52.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.50.0",
+  "version": "4.52.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -40,7 +40,12 @@
     "snapshot": "./scripts/core/snapshot.sh",
     "bootstrap": "./scripts/core/bootstrap.sh",
     "canon:sandbox": "canon sandbox",
-    "canon:sandbox:reset": "canon sandbox reset"
+    "canon:sandbox:reset": "canon sandbox reset",
+    "web:tokens": "canon design css --no-components > web/src/styles/tokens.css.new && (echo '/* Generated by `canon design css --no-components`. Regenerate with `bun run web:tokens`. Do not hand-edit. */'; cat web/src/styles/tokens.css.new) > web/src/styles/tokens.css && rm web/src/styles/tokens.css.new",
+    "web:dev": "cd web && astro dev",
+    "web:build": "bun run web:tokens && cd web && astro check && astro build",
+    "web:preview": "cd web && astro preview",
+    "web:e2e": "cd web && playwright test"
   },
   "dependencies": {
     "commander": "^13.1.0",
@@ -61,6 +66,7 @@
     "cspell": "^8.17.1",
     "husky": "^9.1.7",
     "prettier": "^3.8.1",
+    "prettier-plugin-astro": "^0.14.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5"

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/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`.