npm - @erclx/canon - Versions diffs - 4.80.0 → 4.82.0 - Mend

@erclx/canon 4.80.0 → 4.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/claude/.claude-plugin/plugin.json +1 -1
package/claude/skills/design-extract/SKILL.md +5 -1
package/claude/skills/sketch-design/REQUIREMENT.md +38 -0
package/claude/skills/sketch-design/SKILL.md +92 -0
package/claude/skills/teach-workspace/SKILL.md +23 -1
package/claude/skills/teach-workspace/references/lesson-craft.md +11 -0
package/docs/agents/commands.md +11 -5
package/docs/agents/context-audit.md +1 -1
package/docs/agents/context-classify.md +99 -0
package/docs/agents/design-board.md +13 -11
package/docs/agents/index.md +2 -1
package/docs/agents/teach.md +16 -0
package/docs/target-projects.md +15 -0
package/docs/workflow/ai-workflow.md +4 -2
package/docs/workflow/visual-design-workflow.md +1 -0
package/governance/rules/claude/545-decisions.md +12 -0
package/package.json +1 -1
package/src/claude/cases/misc.ts +5 -0
package/src/claude/seeds.ts +1 -0
package/src/commands/claude.ts +26 -5
package/src/commands/context.ts +425 -0
package/src/commands/design.ts +24 -8
package/src/commands/teach.ts +118 -0
package/src/context/classify/extract.ts +450 -0
package/src/context/classify/ollama.ts +172 -0
package/src/context/classify/patterns.ts +114 -0
package/src/context/classify/prompts.ts +73 -0
package/src/context/classify/run.ts +348 -0
package/src/context/classify/settings.ts +196 -0
package/src/context/folders.ts +1 -0
package/src/design/board.ts +130 -47
package/src/project-root.ts +16 -0
package/src/surface-root.ts +1 -0
package/src/teach/render.ts +126 -0
package/standards/decisions.md +100 -0
package/standards/index.md +1 -0
package/tooling/claude/reference.md +1 -0
package/tooling/claude/seeds/CLAUDE.md +1 -0
package/tooling/claude/seeds/canon/decisions/index.md +8 -0

package/src/design/board.ts CHANGED Viewed

@@ -11,13 +11,17 @@ import { join, relative, sep } from 'node:path'
 import { DESIGN_DOCUMENT } from '@/design/regen'
 import { renderDesignDoc } from '@/design/render'
 import { colorValue } from '@/design/tokens'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { recordDir } from '@/record-root'
+import { surfaceDir } from '@/surface-root'
 /**
- * The one named site for this repository's wireframe corpus, so the surface
- * move retargets a single constant rather than a literal repeated per panel.
- * The board reads this checkout alone, which has moved, so the new root is
- * spelled directly rather than resolved.
+ * The wireframes panel's creation-root spelling, used in its own empty-state
+ * message and by this module's tests to seed a fixture. The panel itself
+ * resolves its actual read path through `surfaceDir`, which also reads
+ * `.claude/wireframes/` for a target that has not run the surface-roots
+ * migration, so this constant names where a fresh file lands rather than
+ * where every root's corpus necessarily sits.
  */
 export const WIREFRAME_DIR = join('canon', 'wireframes')
@@ -34,26 +38,6 @@ const WEB_DIST_ENTRY = 'index.html'
 const WEB_GALLERY_DIST = join('web', 'gallery-dist')
 const WEB_GALLERY_DIST_ENTRY = 'index.html'
-interface WireframeEntry {
-  readonly path: string
-  readonly describes: string
-}
-/**
- * The six files the wireframes panel renders, each beside the surface it
- * describes. `index.md` at either level is a catalog rather than a wireframe
- * and is excluded, which is why this list holds six rather than the eight
- * files the corpus carries today.
- */
-const WIREFRAMES: readonly WireframeEntry[] = [
-  { path: 'landing-page.md', describes: 'The canon.erclx.dev landing page' },
-  { path: 'slides.md', describes: 'The SLIDES.md render' },
-  { path: 'teach/root.md', describes: 'A teach workspace root listing' },
-  { path: 'teach/contents.md', describes: 'A workspace contents page' },
-  { path: 'teach/lesson.md', describes: 'A lesson page and quiz stepper' },
-  { path: 'teach/chrome.md', describes: 'The shared teach chrome' },
-]
 const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.svg', '.webp']
 export interface BoardPanel {
@@ -233,7 +217,8 @@ iframe { width: 100%; height: 480px; border: 1px solid var(--board-border); bord
 <body>
 <header>
 <h1>Design board</h1>
-<p class="meta">Generated by <code>canon design board</code>. Repository-local, never installed into a target.</p>
+<p class="meta">Generated by <code>canon design board</code>. Reads from a caller-resolved root, never installed or synced.</p>
+<p class="meta">Drafting a new candidate: <code>canon:draft-and-pick</code>. Auditing a rendered surface: <code>canon:ux-audit</code>.</p>
 </header>
 <nav>${navLinks}${THEME_TOGGLE_BUTTON}</nav>
 <main>
@@ -282,7 +267,7 @@ ${body}
 }
 function writeTokensPanel(root: string, outDir: string): void {
-  const sourcePath = join(root, DESIGN_DOCUMENT)
+  const sourcePath = surfaceDir(root, 'DESIGN.md')
   const dir = join(outDir, 'tokens')
   if (!existsSync(sourcePath)) {
@@ -300,18 +285,56 @@ function writeTokensPanel(root: string, outDir: string): void {
   renderDesignDoc(sourcePath, dir)
 }
+interface WireframeFile {
+  readonly relPath: string
+  readonly text: string
+  readonly description: string | undefined
+}
+/**
+ * Every wireframe under whichever root the corpus resolves at, sorted for a
+ * stable render order across runs. `surfaceDir` reads `.claude/wireframes/`
+ * for a target that has not run the surface-roots migration, the same
+ * fallback `recordDir` already gives the surfaces panel's teach half.
+ * `index.md` at any depth is a catalog rather than a wireframe and is
+ * excluded. A glob emits OS-native separators, and the corpus nests one
+ * level deep, so the label always reads with forward slashes regardless of
+ * platform.
+ */
+function listWireframes(root: string): readonly WireframeFile[] {
+  const dir = surfaceDir(root, 'wireframes')
+  if (!existsSync(dir)) return []
+  const glob = new Bun.Glob('**/*.md')
+  const relPaths = [...glob.scanSync({ cwd: dir })]
+    .filter((relPath) => relPath.split(sep).pop() !== 'index.md')
+    .map((relPath) => relPath.split(sep).join('/'))
+    .sort()
+  return relPaths.map((relPath) => {
+    const text = readFileSync(join(dir, relPath), 'utf8')
+    return {
+      relPath,
+      text,
+      description: readField(parseFrontmatter(text), 'description'),
+    }
+  })
+}
 function writeWireframesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'wireframes')
   mkdirSync(dir, { recursive: true })
-  const sections = WIREFRAMES.map((entry) => {
-    const sourcePath = join(root, WIREFRAME_DIR, entry.path)
-    if (!existsSync(sourcePath)) {
-      return `<h2>${escapeHtml(entry.path)}</h2>\n<p class="empty">Missing from ${WIREFRAME_DIR}/.</p>`
-    }
-    const text = readFileSync(sourcePath, 'utf8')
-    return `<h2>${escapeHtml(entry.path)}</h2>\n<p>${escapeHtml(entry.describes)}</p>\n<pre>${escapeHtml(text)}</pre>`
-  }).join('\n')
+  const files = listWireframes(root)
+  const sections =
+    files.length === 0
+      ? `<p class="empty">No wireframe files under ${WIREFRAME_DIR}/.</p>`
+      : files
+          .map((file) => {
+            const description = file.description ?? file.relPath
+            return `<h2>${escapeHtml(file.relPath)}</h2>\n<p>${escapeHtml(description)}</p>\n<pre>${escapeHtml(file.text)}</pre>`
+          })
+          .join('\n')
   writeFileSync(join(dir, 'index.html'), panelPage('Wireframes', sections))
 }
@@ -322,15 +345,21 @@ function copyBuilt(source: string, dest: string): void {
   cpSync(source, dest, { recursive: true })
 }
-function writeSurfacesPanel(root: string, outDir: string): void {
+function writeSurfacesPanel(
+  root: string,
+  outDir: string,
+  isToolkitCheckout: boolean,
+): void {
   const dir = join(outDir, 'surfaces')
   mkdirSync(dir, { recursive: true })
   const distSource = join(root, WEB_DIST)
-  const landingBody = existsSync(join(distSource, WEB_DIST_ENTRY))
-    ? (copyBuilt(distSource, join(dir, 'landing')),
-      '<iframe src="landing/index.html" loading="lazy"></iframe>')
-    : `<p class="empty">No ${WEB_DIST}/ build. Run bun run web:build, then regenerate the board.</p>`
+  const landingBody = !isToolkitCheckout
+    ? `<p class="empty">The landing page panel only renders in this toolkit's own checkout.</p>`
+    : existsSync(join(distSource, WEB_DIST_ENTRY))
+      ? (copyBuilt(distSource, join(dir, 'landing')),
+        '<iframe src="landing/index.html" loading="lazy"></iframe>')
+      : `<p class="empty">No ${WEB_DIST}/ build. Run bun run web:build, then regenerate the board.</p>`
   const teachSource = recordDir(root, 'teach')
   const teachBody = existsSync(join(teachSource, 'index.html'))
@@ -347,15 +376,21 @@ function writeSurfacesPanel(root: string, outDir: string): void {
   )
 }
-function writeComponentsPanel(root: string, outDir: string): void {
+function writeComponentsPanel(
+  root: string,
+  outDir: string,
+  isToolkitCheckout: boolean,
+): void {
   const dir = join(outDir, 'components')
   mkdirSync(dir, { recursive: true })
   const gallerySource = join(root, WEB_GALLERY_DIST)
-  const body = existsSync(join(gallerySource, WEB_GALLERY_DIST_ENTRY))
-    ? (copyBuilt(gallerySource, join(dir, 'gallery')),
-      '<iframe src="gallery/index.html" loading="lazy"></iframe>')
-    : `<p class="empty">No ${WEB_GALLERY_DIST}/ build. Run bun run web:gallery, then regenerate the board.</p>`
+  const body = !isToolkitCheckout
+    ? `<p class="empty">The components panel only renders in this toolkit's own checkout.</p>`
+    : existsSync(join(gallerySource, WEB_GALLERY_DIST_ENTRY))
+      ? (copyBuilt(gallerySource, join(dir, 'gallery')),
+        '<iframe src="gallery/index.html" loading="lazy"></iframe>')
+      : `<p class="empty">No ${WEB_GALLERY_DIST}/ build. Run bun run web:gallery, then regenerate the board.</p>`
   writeFileSync(join(dir, 'index.html'), panelPage('Components', body))
 }
@@ -416,13 +451,54 @@ function writeCandidatesPanel(root: string, outDir: string): void {
   const sections = found
     .map(
       ({ folder, images }) =>
-        `<h2>${escapeHtml(folder)}</h2>\n${images.map((image) => `<img src="${folder}/${image}" alt="${escapeHtml(image)}">`).join('\n')}`,
+        `<h2>${escapeHtml(folder)}</h2>\n${images.map((image) => `<img src="${escapeHtml(`${folder}/${image}`)}" alt="${escapeHtml(image)}">`).join('\n')}`,
     )
     .join('\n')
   writeFileSync(join(dir, 'index.html'), panelPage('Past candidates', sections))
 }
+function writeReferencesPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'references')
+  mkdirSync(dir, { recursive: true })
+  const referencesDir = recordDir(root, 'review', 'references')
+  if (!existsSync(referencesDir)) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'References',
+        `<p class="empty">No ${relative(root, referencesDir)} folder yet.</p>`,
+      ),
+    )
+    return
+  }
+  const images = imagesIn(referencesDir)
+  if (images.length === 0) {
+    writeFileSync(
+      join(dir, 'index.html'),
+      panelPage(
+        'References',
+        `<p class="empty">${relative(root, referencesDir)} exists but carries no image yet.</p>`,
+      ),
+    )
+    return
+  }
+  for (const image of images) {
+    cpSync(join(referencesDir, image), join(dir, image))
+  }
+  const sections = images
+    .map(
+      (image) => `<img src="${escapeHtml(image)}" alt="${escapeHtml(image)}">`,
+    )
+    .join('\n')
+  writeFileSync(join(dir, 'index.html'), panelPage('References', sections))
+}
 /**
  * Generates the board's page set into `outDir`, clearing whatever was there.
  *
@@ -433,11 +509,16 @@ function writeCandidatesPanel(root: string, outDir: string): void {
  * `cwd` is the caller's own working directory, resolved and passed in
  * explicitly rather than read here, so a test can exercise the checkout-
  * mismatch case without touching the process's real cwd.
+ *
+ * `isToolkitCheckout` gates the surfaces panel's landing-page half and the
+ * whole components panel, both of which read this repository's own build
+ * output rather than anything a target project produces.
  */
 export function generateBoard(
   root: string,
   outDir: string,
   cwd: string,
+  isToolkitCheckout: boolean,
 ): BoardOutcome {
   if (wouldDeleteRoot([root, cwd], outDir)) {
     return {
@@ -460,13 +541,15 @@ export function generateBoard(
       path: 'candidates/index.html',
     },
     { id: 'components', title: 'Components', path: 'components/index.html' },
+    { id: 'references', title: 'References', path: 'references/index.html' },
   ]
   writeTokensPanel(root, outDir)
-  writeSurfacesPanel(root, outDir)
+  writeSurfacesPanel(root, outDir, isToolkitCheckout)
   writeWireframesPanel(root, outDir)
   writeCandidatesPanel(root, outDir)
-  writeComponentsPanel(root, outDir)
+  writeComponentsPanel(root, outDir, isToolkitCheckout)
+  writeReferencesPanel(root, outDir)
   const indexPath = join(outDir, 'index.html')
   writeFileSync(indexPath, shellHtml(panels))

package/src/project-root.ts CHANGED Viewed

@@ -28,6 +28,22 @@ const readPackageName = (root: string): string | undefined => {
   }
 }
+/**
+ * Whether `root` is a checkout of this same package, judged by package name
+ * rather than by path equality against `PROJECT_ROOT`.
+ *
+ * A linked worktree tracks the identical `package.json` the main worktree
+ * does, so this reads true for either. Comparing `root` against `PROJECT_ROOT`
+ * directly reads true only for the one directory this process happened to
+ * load its own source from, which is wrong for a caller whose CLI runs out of
+ * a linked worktree while `root` correctly points at the main one, or at
+ * another worktree of the same repository.
+ */
+export function isOwnCheckout(root: string): boolean {
+  const ownName = readPackageName(PROJECT_ROOT)
+  return ownName !== undefined && readPackageName(root) === ownName
+}
 /**
  * Walks upward from `startDir` for the nearest ancestor `package.json`
  * sharing this package's own `name`, and reports its path when that ancestor

package/src/surface-root.ts CHANGED Viewed

@@ -43,6 +43,7 @@ export const SURFACE_ENTRIES: readonly string[] = [
   'DESIGN.md',
   'context',
   'wireframes',
+  'decisions',
   'canon',
 ]

package/src/teach/render.ts ADDED Viewed

@@ -0,0 +1,126 @@
+import { Heading } from '@/teach/components/heading'
+import { List } from '@/teach/components/list'
+import { Paragraph } from '@/teach/components/paragraph'
+import { render } from '@/teach/html/jsx-runtime'
+import type { TeachRefused } from '@/teach/workspace'
+export type LessonBlock =
+  | { readonly type: 'heading'; readonly level: 1 | 2; readonly text: string }
+  | {
+      readonly type: 'paragraph'
+      readonly text: string
+      readonly lede?: boolean
+    }
+  | {
+      readonly type: 'list'
+      readonly items: readonly string[]
+      readonly ordered?: boolean
+    }
+  | { readonly type: 'raw'; readonly html: string }
+export interface RenderRendered {
+  readonly ok: true
+  readonly html: string
+}
+export type RenderOutcome = RenderRendered | TeachRefused
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+function isBlockType(value: unknown): value is LessonBlock['type'] {
+  return (BLOCK_TYPES as readonly string[]).includes(value as string)
+}
+function badBlock(index: number, message: string): TeachRefused {
+  return {
+    ok: false,
+    reason: 'bad-input',
+    message: `Block ${index}: ${message}`,
+    detail: [],
+  }
+}
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every(isString)
+}
+function renderBlock(
+  block: unknown,
+  index: number,
+): { readonly html: string } | TeachRefused {
+  if (typeof block !== 'object' || block === null || !('type' in block)) {
+    return badBlock(index, 'not an object carrying a type')
+  }
+  const type = (block as { readonly type: unknown }).type
+  if (!isBlockType(type)) {
+    return badBlock(index, `unrecognized type ${JSON.stringify(type)}`)
+  }
+  const fields = block as Record<string, unknown>
+  switch (type) {
+    case 'heading': {
+      if (fields.level !== 1 && fields.level !== 2) {
+        return badBlock(index, 'heading needs level 1 or 2')
+      }
+      if (!isString(fields.text)) {
+        return badBlock(index, 'heading needs a string text')
+      }
+      return {
+        html: render(Heading({ level: fields.level, children: fields.text })),
+      }
+    }
+    case 'paragraph': {
+      if (!isString(fields.text)) {
+        return badBlock(index, 'paragraph needs a string text')
+      }
+      if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
+        return badBlock(index, 'paragraph lede must be a boolean')
+      }
+      return {
+        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+      }
+    }
+    case 'list': {
+      if (!isStringArray(fields.items)) {
+        return badBlock(index, 'list needs an items array of strings')
+      }
+      if (fields.ordered !== undefined && typeof fields.ordered !== 'boolean') {
+        return badBlock(index, 'list ordered must be a boolean')
+      }
+      return {
+        html: render(List({ ordered: fields.ordered, items: fields.items })),
+      }
+    }
+    case 'raw': {
+      if (!isString(fields.html)) {
+        return badBlock(index, 'raw needs a string html')
+      }
+      return { html: fields.html }
+    }
+  }
+}
+/**
+ * Renders a lesson body's structural blocks through the same components
+ * `render-fixture.tsx` composes by hand, so a real lesson and the committed
+ * fixture share one rendering mechanism. Every block past the first refusal
+ * goes unread, matching how a malformed JSON parse refuses the whole call.
+ */
+export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
+  const rendered: string[] = []
+  for (const [index, block] of blocks.entries()) {
+    const result = renderBlock(block, index)
+    if ('ok' in result) return result
+    rendered.push(result.html)
+  }
+  return { ok: true, html: rendered.join('\n') }
+}

package/standards/decisions.md ADDED Viewed

@@ -0,0 +1,100 @@
+---
+title: Decisions reference
+description: Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
+---
+# Decisions reference
+Applies to `canon/decisions/`. Holds the history a canonical doc used to carry itself: pick rounds, superseded figures, and a decision's rejected alternatives, in a tracked folder nothing loads eagerly. A canonical doc points at a record from its own history section rather than restating it.
+## Scope
+Governs `canon/decisions/`: folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle.
+Does not govern:
+- Which canonical doc points here and when, and what stays behind in that doc's own body: `architecture.md`, `context.md`, `wireframes.md`, `design.md`, `requirements.md`, once each states its own retirement rule
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+## What a working record looks like
+A record works when a reader who has never opened the project can follow it from the file alone:
+- What was decided, stated once, without needing the canonical doc that points here
+- What else was considered, and why each alternative lost
+- Which claim rests on a measurement, and what commit that measurement was read against
+A record failing these is non-conforming even when it satisfies every shape rule below.
+## Folder name
+- `canon/decisions/`, resolved the way every tracked surface is: at `canon/decisions/` in a project that has moved, at `.claude/decisions/` in one that has not.
+- Never add `canon/decisions/index.md` to a `CLAUDE.md` `@` import. A log that loads eagerly rebuilds the bloat it exists to absorb. A canonical doc's own pointer is how a reader reaches a record, one file at a time.
+## Record filename
+- Name each record `<nn>-<slug>.md`, a two-digit zero-padded ordinal followed by a kebab-case slug, the same shape a groundwork track's folder takes.
+- The ordinal is the order the record was written in, which is what lets a listing sort by when a decision landed rather than alphabetically by subject.
+- Never renumber an existing record. A later reader cites it by that name, and a record whose number moved is a record a stale citation can no longer find.
+## Frontmatter
+- `title` (required): the decision in sentence case
+- `description` (required): one line naming what was decided
+## Sections
+Use `## Context`, `## Decision`, `## Alternatives`, and `## Measurements`.
+- `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
+- `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
+- `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
+- `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
+## Verification anchors
+A record's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
+- Close a `## Measurements` section with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
+- Anchor on the number alone. A record citing none carries no `## Measurements` section at all.
+- Read an absent section as unchecked rather than as current. A record with no measurements has nothing due a re-read.
+## Lifecycle
+- Append-only. A written record is never edited to reflect a later reversal.
+- Write a new record when a later decision supersedes an earlier one, naming the record it supersedes. The old record stays as it was written, since it is history rather than a live statement of the current shape.
+- Never auto-loaded. A canonical doc's own history section links to a record by relative path, and a reader reaches it by following that link, not by the folder loading with the session.
+## Citation
+- Never cite `.canon/`. A record restates what it needs, since a clone without the gitignored records folder resolves nothing there.
+- Cite a same-repository pull request or commit the way `publish.md` fixes for any tracked document.
+## Template
+```markdown
+---
+title: <Decision, in sentence case>
+description: <one line naming what was decided>
+---
+# <Decision title>
+## Context
+<The problem as it stood, self-contained.>
+## Decision
+<What was chosen, and why.>
+## Alternatives
+- **<Alternative>.** <Why it lost.>
+- **<Alternative>.** <Why it lost.>
+## Measurements
+<The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.
+```

package/standards/index.md CHANGED Viewed

@@ -11,6 +11,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Branch reference](branch.md): Branch naming format and type conventions
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
+- [Decisions reference](decisions.md): Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder

package/tooling/claude/reference.md CHANGED Viewed

@@ -14,6 +14,7 @@ canon/
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
+├── decisions/         ← seeded. Decision history a canonical doc points at, never loaded eagerly. `<nn>-<slug>.md` records.
 └── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
 .claude/

package/tooling/claude/seeds/CLAUDE.md CHANGED Viewed

@@ -22,3 +22,4 @@
 - `canon/DESIGN.md`: design tokens and the visual system
 - `canon/context/`: per-domain narrative (how a domain is structured, decisions, gotchas), indexed via `canon/context/index.md`
 - `canon/wireframes/`: per-surface ASCII layouts loaded on demand, indexed via `canon/wireframes/index.md`
+- `canon/decisions/`: decision history a project doc points at, never loaded eagerly

package/tooling/claude/seeds/canon/decisions/index.md ADDED Viewed

@@ -0,0 +1,8 @@
+---
+title: Decisions
+subtitle: Decision history a project doc points at, never loaded eagerly
+---
+# Decisions
+Decision history a project doc points at, never loaded eagerly