@erclx/canon 5.24.0 → 5.26.0

package/src/secrets/marker.ts

@@ -1,9 +1,9 @@
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 /**
  * The inline token exempting one line from the secret scan.
  *
- * Shaped on the `stub: true` precedent in `src/seed-marker.ts`, which answers
+ * Shaped on the `stub: true` precedent in `src/tooling/seed-marker.ts`, which answers
  * a check whose own comment records a false-positive class. The exemption
  * travels with the line it exempts rather than sitting in a path list away
  * from it, so a reader meeting a muted match finds the reason on the spot.

package/src/secrets/scan.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { listRepositoryFiles } from '@/git-files'
 import { isExempt } from '@/secrets/marker'
 import { matchLine } from '@/secrets/patterns'

package/src/shipped/references.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 /**
  * The corpora a target reader reaches, which is the `files` field less `src`.
@@ -113,7 +113,7 @@ const COMMIT_SHA = /(?<![0-9A-Za-z_@/#])([0-9a-f]{7,40})(?![0-9A-Za-z_])/g
  * one.
  *
  * The literal is hardcoded rather than read from `package.json` or
- * `git remote`, matching `src/github-format.ts` and `src/commands/repo.ts`,
+ * `git remote`, matching `src/feedback/github-format.ts` and `src/commands/repo.ts`,
  * which already hardcode it.
  *
  * Same word-boundary discipline as the two patterns above: a word character

package/src/slides/convert/export.ts

@@ -1,10 +1,4 @@
-import {
-  copyFileSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs'
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import JSZip from 'jszip'
@@ -42,6 +36,7 @@ import {
   type WalkedSlide,
   walkSlide,
 } from '@/slides/convert/walk'
+import { slideFiles } from '@/slides/decks'
 import { embedFonts, type FontNotice } from '@/slides/package/fonts'
 import {
   type EntranceSpec,
@@ -127,15 +122,6 @@ function refused(reason: ExportRefusal, message: string): ExportResult {
   return { status: 'refused', reason, message }
 }
 
-/** Every `.html` file directly in the folder, in filename order. */
-export function slideFiles(sourceDir: string): string[] {
-  return readdirSync(sourceDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
-    .map((entry) => entry.name)
-    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
-    .map((name) => join(sourceDir, name))
-}
-
 /** A picture whose bytes the post-write pass replaces or whose corners it rounds. */
 interface Patch {
   readonly slide: number

package/src/slides/decks.ts

@@ -0,0 +1,110 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { creationRel, recordDir } from '@/record-root'
+import { readDeck } from '@/slides/convert/deck'
+
+/**
+ * A deck is a folder under the record root's `slides/`, holding its `.html`
+ * slides, an optional `deck.json`, and its assets. `layouts/` beside the decks
+ * holds the project's shared layouts and is never a deck itself.
+ */
+export const SLIDES_FOLDER = 'slides'
+
+export const LAYOUTS_FOLDER = 'layouts'
+
+export interface Deck {
+  readonly name: string
+  /** From `deck.json`, falling back to the folder name as the export does. */
+  readonly title: string
+  readonly slides: number
+  /** Relative to the project root. */
+  readonly path: string
+}
+
+export type DeckRefusal = 'no-decks' | 'ambiguous' | 'no-deck'
+
+export type DeckResolution =
+  | { readonly status: 'resolved'; readonly dir: string }
+  | {
+      readonly status: 'refused'
+      readonly reason: DeckRefusal
+      readonly message: string
+    }
+
+/** Every `.html` file directly in the folder, in filename order. */
+export function slideFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .map((name) => join(dir, name))
+}
+
+export function listDecks(root: string): Deck[] {
+  const dir = recordDir(root, SLIDES_FOLDER)
+  if (!isDirectory(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== LAYOUTS_FOLDER)
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((name) => {
+      const deckDir = join(dir, name)
+      const slides = slideFiles(deckDir).length
+      if (slides === 0) return []
+      const read = readDeck(deckDir)
+      const title = read.status === 'read' ? read.deck.title : name
+      return [{ name, title, slides, path: relative(root, deckDir) }]
+    })
+}
+
+/**
+ * The folder `render` reads. A deck name wins over a folder of the same name
+ * relative to the root, and no name at all takes the only deck there is.
+ */
+export function resolveDeck(
+  root: string,
+  target: string | undefined,
+): DeckResolution {
+  const decks = listDecks(root)
+  const at = creationRel(root, SLIDES_FOLDER)
+
+  if (target === undefined) {
+    const [only, ...rest] = decks
+    if (only === undefined) {
+      return refuse('no-decks', `No deck under ${at}/. Draw one there first.`)
+    }
+    if (rest.length > 0) {
+      return refuse(
+        'ambiguous',
+        `${decks.length} decks under ${at}/, name one: ${names(decks)}`,
+      )
+    }
+    return { status: 'resolved', dir: join(root, only.path) }
+  }
+
+  const named = decks.find((deck) => deck.name === target)
+  if (named) return { status: 'resolved', dir: join(root, named.path) }
+
+  const folder = resolve(root, target)
+  if (isDirectory(folder)) return { status: 'resolved', dir: folder }
+
+  return refuse(
+    'no-deck',
+    decks.length === 0
+      ? `${target} is neither a deck under ${at}/ nor a folder`
+      : `${target} is neither a deck nor a folder. Decks: ${names(decks)}`,
+  )
+}
+
+function names(decks: readonly Deck[]): string {
+  return decks.map((deck) => deck.name).join(', ')
+}
+
+function refuse(reason: DeckRefusal, message: string): DeckResolution {
+  return { status: 'refused', reason, message }
+}
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory()
+}

package/src/standards/read.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
 
 export const INDEX_FILE = 'index.md'

package/src/sync/seeds-report.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { relative } from 'node:path'
 import { planSeeds, type Seed } from '@/claude/seeds'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 
 /**

package/src/tasks/answers.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
-import { isUnder } from '@/paths'
+import { isUnder } from '@/tasks/paths'
 import { recordDir, recordDirs } from '@/record-root'
 import {
   hasStagedBatches,

package/src/tasks/archive.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { regenOne } from '@/indexes/regen'
-import { isUnder } from '@/paths'
+import { isUnder } from '@/tasks/paths'
 import { recordDir, recordDirs } from '@/record-root'
 
 const TASKS = 'tasks'

package/src/teach/nav.ts

@@ -7,7 +7,7 @@ import {
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
 import { compileScript } from '@/teach/browser/compile'

package/src/tooling/inject.ts

@@ -3,7 +3,7 @@ import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import {

package/src/web/readme-citations.ts

@@ -1,4 +1,4 @@
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 export const README_PARAPHRASE_MARKER = 'canon-allow-readme-paraphrase'
 

package/standards/architecture.md

@@ -54,6 +54,7 @@ Use `## Overview`, `## Key technical decisions` with one named H3 per decision,
 
 - Rewrite a decision a later one changed rather than appending the change beside it. A reader should find the design that stands in one place, with the alternative that lost stated once.
 - Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it fills a slot and moving to the domain context entry it constrains when it does not.
+- Carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read the record whole for drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
 
 ## Verification anchors
 

package/standards/canvas.md

@@ -0,0 +1,112 @@
+---
+title: Canvas reference
+description: Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
+---
+
+# Canvas reference
+
+Applies to the canvas content under `.canon/canvas/`, where each page is a folder of HTML frames and a layout file placing them. A frame is a draft drawn to be looked at and picked from, so it changes whenever someone tries a direction, and the operator clears it once the direction lands where the project keeps its design.
+
+The folder is gitignored, so nothing in a repository checks its shape and nothing backs it up by default.
+
+## Scope
+
+Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
+
+Does not govern:
+
+- The design decisions a frame is drafting, such as type, color, and layout taste: the project's own design document
+- The project's design document and the token module it renders from, which a picked direction is carried into: `design.md`
+- The procedure that starts the canvas, reads the operator's selection, and carries a pick back, which belongs to the surface driving the canvas
+- Voice, rhythm, and sentence construction in any text a frame shows: the `write-human` skill
+
+## What a working canvas looks like
+
+A canvas works when the operator and a session can point at the same thing and see the same thing:
+
+- Which pages exist, and which frames sit on each?
+- Where does each frame sit on its page, and at what width does it render?
+- Does each frame show the project's own tokens rather than values copied into it?
+- Does a frame render the same in the live canvas as in a capture?
+
+A canvas failing these is non-conforming even when it satisfies every shape rule below.
+
+## Pages
+
+- Make one folder per page directly under `.canon/canvas/`. A page groups the frames compared side by side, such as the candidates for one decision.
+- Name a page as one path segment of letters, digits, dots, dashes, and underscores, starting with a letter or a digit. A name opening with a dot is hidden from every listing.
+- Never write a folder whose name opens with a dot. Those names are reserved for files the canvas generates and removes itself.
+- Rename a page rather than copying it under a new name, so its layout and frames stay together.
+
+## Frames
+
+- Write one frame as one `.html` file inside its page folder. The filename without its extension is the frame's name, and the name follows the page naming rule.
+- Write each frame as a whole document, with a doctype, a `head`, and a `body`. A fragment gets elements the browser builds around it, and an address the operator picks inside it can no longer be matched to the file.
+- Write every table with its `tbody` stated, for the same reason. A browser adds one the file leaves out.
+- Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
+- Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
+- Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
+
+## Layout
+
+- Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
+- Key each box by the frame's name, under one top-level `frames` object.
+- Give every box four finite numbers in pixels: `x` and `y` for its top-left corner on the page, `width` for the width the frame renders at, and `height` for the height it shows on the canvas.
+- Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
+- Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
+- Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
+
+The keys below are the ones a reader parses. The frame names are placeholders.
+
+```json
+{
+  "frames": {
+    "hero-a": { "x": 0, "y": 0, "width": 1440, "height": 900 },
+    "hero-b": { "x": 1520, "y": 0, "width": 1440, "height": 900 }
+  }
+}
+```
+
+## Tokens
+
+- Expect the token stylesheet first in every frame's `head` when it is served, ahead of anything the frame links. A stylesheet the frame links itself still wins the cascade.
+- Read where the tokens come from in this order: the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus anything in its project override folder, else none. A canvas with no token source renders unstyled and says so.
+- Never paste the token stylesheet into a frame. The injected copy follows the project, and a pasted one stops following it the moment it is written.
+
+## What a frame must not assume
+
+- Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
+- Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
+- Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
+- Do not assume a default font. Set `font-family` with an installed family first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
+- Do not assume the frame is the source. A picked direction is carried into the project's design document or its wireframes, and the operator clears the frame once it has been carried.
+- Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
+
+## Template
+
+A new frame starts from this skeleton. The names in it are placeholders.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>frame-name</title>
+    <style>
+      html {
+        font-family: installed-family, sans-serif;
+      }
+      main {
+        padding: var(--space-lg);
+        color: var(--color-text);
+        background: var(--color-background);
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>frame-name</h1>
+    </main>
+  </body>
+</html>
+```

package/standards/context.md

@@ -21,7 +21,8 @@ Does not govern:
 - Decisions filling a stack, delivery, boundary, layout, or build-principle slot, and system-wide risks: `architecture.md`
 - Product scope, goals, and non-goals: `requirements.md`
 - Path-scoped coding rules: `rule.md`
-- Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+- Wireframes, which answer layout questions an entry hands off: `wireframes.md`
+- Figures and architecture views, which answer structure questions an entry hands off: the `draft-figure` skill
 - The consumer-facing reference under `docs/`, whose reader is operating the project without the source open: `docs.md`
 
 ## Organizing principle

package/standards/figures.md

@@ -14,7 +14,6 @@ Governs a hand-drawn figure wherever one is authored, naming no path because an
 Does not govern:
 
 - Direction, layout, node and edge budgets, labels, and render verification for the Mermaid path: `mermaid.md`
-- The toolkit's own architecture-diagram surface at `.canon/diagrams/`, which shares no code, font, or visual language with this convention: `diagrams.md`
 - Language, word choice, punctuation, and formatting in the caption or surrounding prose: `markdown.md`
 - Voice, rhythm, and sentence construction in that prose: the `write-human` skill
 - Which document types may carry a figure, and what else they require: that document type's own standard

package/standards/index.md

@@ -10,10 +10,10 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Architecture reference](architecture.md): Shape and content rules for canon/ARCHITECTURE.md
 - [Board reference](board.md): Readiness groups, row cells, and ordering for priority.md, the unordered backlog.md beside it, and the generated index under .canon/tasks/
 - [Branch reference](branch.md): Branch naming format and type conventions
+- [Canvas reference](canvas.md): Page folders, frame files, the layout.json shape, token resolution, and what a frame must not assume on a local design canvas
 - [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
 - [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
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
 - [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries

package/standards/markdown.md

@@ -7,6 +7,7 @@ rule:
   - 'Read it before a substantial markdown edit. Do not work the banned characters from memory.'
   - 'Run `canon markdown audit <path>` after the edit, and rewrite the sentence carrying a hit rather than swapping the token for a near-synonym.'
   - 'Voice, rhythm, and sentence construction are a separate topic. `800-prose` routes them.'
+  - 'Load the `canon:draft-figure` skill before drafting or revising a Mermaid fence or a figure, and report it rather than proceeding silently when it does not resolve.'
 ---
 
 # Markdown reference

package/standards/mermaid.md

@@ -1,12 +1,6 @@
 ---
 title: Mermaid reference
 description: Direction and layout, node and edge budgets, accessibility fields, label punctuation, and render verification for a Mermaid diagram
-paths:
-  - '**/*.md'
-rule:
-  - 'Apply this rule only when the edit drafts or revises a Mermaid fence. Skip it on a markdown edit carrying no diagram.'
-  - 'Read it before drafting the fence. Do not work the layout or the budgets from memory.'
-  - 'Which diagram a document carries and what question it answers is a separate topic. The diagrams standard routes it.'
 ---
 
 # Mermaid reference
@@ -19,7 +13,7 @@ Governs the Mermaid attribute wherever a fence is written, naming no path becaus
 
 Does not govern:
 
-- Which diagram a document carries, what question it answers, its frontmatter, and the explanation prose beneath it: `diagrams.md`
+- Which architecture view a figure draws and what question it answers: the `draft-figure` skill's architecture set
 - Language, word choice, punctuation, and formatting in the prose around a fence: `markdown.md`
 - Voice, rhythm, and sentence construction in that prose: the `write-human` skill
 - The mechanism behind any component a diagram draws: `context.md`

package/standards/requirements.md

@@ -46,6 +46,8 @@ This file loads into every session, so its weight is paid before any work starts
 
 Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.
 
+The record may carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read it whole for identity drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
+
 Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness, so a section here states what is wanted and never when it lands.
 
 ## Distribution

package/standards/skill-practice.md

@@ -47,5 +47,6 @@ A practice skill failing any of these is non-conforming even when every heading
 ## Which skills are practice skills
 
 - `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
+- It keeps a wider ledger list beside it, holding every practice skill plus the skills that teach a craft drawn from outside sources without a practice's closing shape. A skill on the wider list alone owes the ledger and none of the three sections.
 - Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
-- The list names this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.
+- Both lists name this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/standards/skill.md

@@ -130,6 +130,7 @@ allowed-tools: <tools required>
 - Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
 - Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
 - Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+- Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
 - Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
 

package/tooling/claude/reference.md

@@ -23,7 +23,6 @@ canon/
 
 .canon/
 ├── tasks/             ← seeded. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
-├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── plans/             ← execution detail for multi-step tasks. `feature-*.md` entries swept by context-fold into `archive/`.
 ├── review/            ← one subfolder per producer. `branch/` for review-branch, `feedback/` for canon feedback, `memory/` for memory-review with its own `archive/`, `design/` for canon design render.
 ├── tmp/               ← ephemeral scratch space, safe to delete without loss
@@ -60,10 +59,6 @@ Convert by hand, once per project:
 2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
 3. Run `canon indexes regen --no-stage --root . .canon/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.
 
-## Upgrading from a single-file diagram set
-
-A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `draft-diagram` skill reads the flat file when `.canon/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
-
 ## Gitignore
 
 - `# Claude`: `.canon/`, `.claude/worktrees/`, `.claude/.tmp/` <!-- canon-keep-record-root -->

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

@@ -1,45 +0,0 @@
----
-name: draft-diagram
-description: Why diagrams are a folder of per-kind entries rather than one file, and why the verified marker is spent only on a render that was read back
----
-
-# Draft diagram requirement
-
-## Gap
-
-Without this skill, a session asked to refresh one view rewrites the whole surface, so four diagrams nobody checked change in the same commit and the reviewer cannot tell which one the pass was about. It picks a filename of its own, and the next refresh writes a duplicate beside the old entry instead of finding it. It reaches for C4, state, or class diagrams that render differently in every viewer.
-
-The verification failure is the expensive one. A mermaid source can satisfy every rule in the standard and still render as a picture that asserts something false about the system, so a session that judges the source and stamps the entry as verified has spent the only signal a reader has on a diagram nobody looked at. The standards hook toggles off inside a fenced block, so a banned character in a node label passes silently while the same character one line below is caught.
-
-## Must
-
-- Write one entry per kind under the filename and category the standard fixes, so a later refresh finds its target
-- Pick which entries this pass writes from whether the source signal exists and whether the pass has reason to touch it
-- Stay inside `flowchart` and `sequenceDiagram`
-- Render every entry this pass wrote and read the image back against what the entry means to say
-- Stamp the verified marker only on an entry whose render was read back and judged correct
-- Name every skipped render and every surviving defect in the output
-- Regenerate the catalog from sibling frontmatter after the last entry is written
-- Read the node labels by hand, since no hook checks inside a fence
-
-## Must not
-
-- Rewrite an entry this pass had no reason to touch, or report one as written when it was left alone
-- Stamp an untouched entry, a skipped render, or an entry whose defect survived
-- Report a clean verification when a check did not run
-- Commit a render, which is a verification artifact rather than a deliverable
-- Redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke it
-- Loop on a defect past two correction passes
-
-## Guards
-
-- No architecture file, no requirements file, and no folder structure to scan: stop, because nothing anchors a diagram
-- Render fails for any reason: continue to the output and name the skipped check. A missing renderer degrades the loop rather than failing it.
-- `canon` not on PATH: report the catalog as stale rather than hand-editing it
-
-## Out of scope
-
-- Design tokens and the visual system, which `design-extract` owns
-- UI roughness, which `ux-audit` owns
-- Writing the catalog file, which the index regen owns from frontmatter
-- Deleting a pre-split flat diagrams file after a migration, which stays the user's call