@erclx/canon 5.41.0 → 5.42.0

package/claude/skills/draft-doc/references/context.md

@@ -13,12 +13,13 @@ A project the surface move has not reached keeps its context folder under `.clau
 
 ## Guards
 
-- Derive a kebab-case slug from the domain and check whether `<context-root>/<slug>.md` or `<context-root>/<slug>/index.md` already exists. Either resolving means the domain is already covered under that exact name. Stop: `❌ <slug> already has a context entry. Use context-fold to refresh it instead.`
+Derive a kebab-case slug from the domain and check whether `<context-root>/<slug>.md` or `<context-root>/<slug>/index.md` already exists. Either resolving means the domain is covered under that exact name, so stop: `❌ <slug> already has a context entry. Use context-fold to refresh it instead.`
 
 ## Placement
 
-- Read `<context-root>/index.md` and check every title and description it lists against the domain. Stop on a match: `❌ <path> already covers this domain under a different name. Use context-fold to refresh it instead.`
-- Default a brand-new entry to a flat file, `<context-root>/<slug>.md`. A domain starts as one page's worth of narrative, and the standard splits it into a folder only once the entry passes the 300-line ceiling, which a fresh domain never does on day one.
+- Read `<context-root>/index.md` and check every title and description it lists against the domain
+- Stop on a match: `❌ <path> already covers this domain under a different name. Use context-fold to refresh it instead.`
+- Default a brand-new entry to a flat file, `<context-root>/<slug>.md`, since the standard splits an entry into a folder only past the 300-line ceiling, which a fresh domain never reaches
 
 ## Draft
 

package/claude/skills/draft-doc/references/docs.md

@@ -9,12 +9,15 @@ description: The guard, placement, draft additions, and regen folder for a brand
 
 ## Guards
 
-- 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 checks the wider case.
+Derive a kebab-case slug from the topic and run `canon docs <slug>`. A resolved page means the topic is covered under that exact name, so stop: `❌ <slug> already resolves to an existing page. Run canon:docs-sync instead.`
+
+This is a name match rather than a topic match, and Placement 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 that read surfaces against the topic. Stop on a match: `❌ <path> already covers this topic under a different name. Run canon:docs-sync instead.`
+- Read `docs/index.md` and its sub-catalogs for the closest existing `category`. <!-- canon-allow-reference: the target project's own docs/ tree -->
+- Check every page title and description that read surfaces against the topic
+- Stop 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.
 

package/claude/skills/draft-doc/references/readme/agent-facing.md

@@ -13,11 +13,15 @@
 
 ### Requirements
 
+Install <what the machine needs> before setup.
+
 - <Agent tool and minimum version>
 - <Runtime the listing command needs>
 
 ### Set up
 
+Run these from <where to run them>.
+
 ```bash
 <clone command>
 <setup command, when a session needs one>
@@ -31,6 +35,8 @@
 
 ### List what the project exposes
 
+The listing shows <what it shows>.
+
 ```bash
 <command that lists skills, rules, or commands>
 ```

package/claude/skills/draft-doc/references/readme/application.md

@@ -22,11 +22,15 @@
 
 ### Requirements
 
+Install <what the machine needs> before setup.
+
 - <Runtime and version>
 - <Service the app depends on>
 
 ### Set up
 
+Run these from <where to run them>.
+
 ```bash
 <clone command>
 <dependency install command>
@@ -36,11 +40,13 @@
 
 ### Run locally
 
+The dev server runs <what it runs>.
+
 ```bash
 <dev server command>
 ```
 
-<Address the app serves on.>
+It serves on <address>.
 
 ### Configuration
 
@@ -50,7 +56,7 @@
 
 ### Deploy
 
-<Where the app deploys and the command or workflow that does it.>
+The app deploys to <where>, through <the command or workflow>.
 
 ## Support
 

package/claude/skills/draft-doc/references/readme/cli.md

@@ -27,12 +27,16 @@
 
 ### Run a command
 
+The most common invocation is <what it does>.
+
 ```bash
 <command> <argument>
 ```
 
 ### Flags
 
+Most runs need <the flags a reader reaches for first>.
+
 ```bash
 <command> --<flag> <value>
 <command> --<flag>
@@ -44,7 +48,7 @@
 
 ### Exit codes
 
-<What each non-zero exit means, when a script depends on it.>
+A non-zero exit means <what each code means>, when a script depends on it.
 
 ## Documentation
 

package/claude/skills/draft-doc/references/readme/library.md

@@ -29,12 +29,16 @@
 
 ### Quickstart
 
+The snippet shows <the core behavior>.
+
 ```<language>
 <Import and one call that shows the core behavior>
 ```
 
 ### <Second common task>
 
+Reach for this when <the reader's situation>.
+
 ```<language>
 <Snippet for the task>
 ```

package/claude/skills/draft-doc/references/readme/plugin.md

@@ -18,18 +18,24 @@
 
 ### <First channel name>
 
+Install through this channel when <who it suits>.
+
 ```bash
 <install command for this channel>
 ```
 
 ### <Second channel name>
 
+Install through this channel when <who it suits>.
+
 ```bash
 <install command for this channel>
 ```
 
 ### Update
 
+Update when <the trigger>, which replaces <what it replaces>.
+
 ```bash
 <update command>
 ```
@@ -38,6 +44,8 @@
 
 ### Invoke a skill
 
+Type the command in <where the user types it>.
+
 ```text
 /<plugin name>:<skill name> <argument>
 ```
@@ -50,7 +58,7 @@
 
 ### Configuration
 
-<Setting the plugin reads and where the user sets it, when one exists.>
+Set <the setting the plugin reads> in <where the user sets it>, when one exists.
 
 ## Support
 

package/claude/skills/draft-doc/references/readme.md

@@ -11,12 +11,21 @@ The readme standard claims the voice of a repository-root README. `write-human`
 
 ## Guards
 
-- Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README instead, which keeps the reference voice per the standard's `## Voice` section rather than the root voice.
-- Read the target if it exists.
-  - It carries an H1 naming the project: it is authored. Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.` Report rather than offering to overwrite it or to conform it to what this kind would draft, since the project's own citations into its README are invisible from here.
-  - It carries no H1, or its only headings restate the tool that scaffolded it rather than the project: it is unedited generator output. Continue, drafting over it rather than syncing its sections.
-  - It does not exist: continue.
-- A hand-authored README opening with a badge block, or a title in some other form the H1 test misses, falls into the no-H1 branch the same as a scaffold page. The Confirm step is what catches that case before the write happens, so treat it as load-bearing rather than a courtesy: never skip it on the reasoning that the guard already decided.
+Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README, which keeps the reference voice per the standard's `## Voice` section.
+
+### Reading an existing target
+
+Read the target if it exists, and branch on its headings.
+
+| Target                                                         | Reading          | Route                                                                                 |
+| -------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------- |
+| Carries an H1 naming the project                               | Authored         | Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.` |
+| Carries no H1, or only headings restating the scaffolding tool | Generator output | Continue, drafting over it rather than syncing its sections                           |
+| Does not exist                                                 | Nothing to read  | Continue                                                                              |
+
+- On the authored branch, report rather than offering to overwrite it or to conform it, since the project's own citations into its README are invisible from here
+- A hand-authored README opening with a badge block, or a title the H1 test misses, falls into the no-H1 branch the same as a scaffold page
+- The Confirm step catches that case before the write, so it is load-bearing. Never skip it on the reasoning that the guard already decided.
 
 ## Placement
 
@@ -26,15 +35,18 @@ The target path is the placement. A README keeps no catalog, so there is no coll
 
 Read the project's manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent) and the tree, then test each type on its own signal. Note every type that matches rather than stopping at the first, since a project is often several at once.
 
-- Library: an installable package name, counted only when no application, CLI, or plugin signal matches, since a named package is also what a site, a CLI, or a plugin carries. An agent-facing match leaves it in place, so a library with a `CLAUDE.md` still gets its quickstart.
+- Library: an installable package name, counted only when no application, CLI, or plugin signal matches, since a site, a CLI, or a plugin also carries a named package
 - CLI: a `bin` field, a `[project.scripts]` table in `pyproject.toml`, a `[[bin]]` table in `Cargo.toml`, or a CLI entry point.
 - Application: a site framework dependency, a site config file, or an app entry point.
 - Agent-facing: a `.claude/skills/` folder, or a file an agent loads such as `CLAUDE.md`.
 - Plugin: a `plugin.json` or a marketplace manifest.
 
-A match on no type falls back to the standard's generic template. Say so in the preview, and never force the nearest type.
+An agent-facing match leaves the library type in place, so a library with a `CLAUDE.md` still gets its quickstart. A match on no type falls back to the standard's generic template. Say so in the preview, and never force the nearest type.
+
+### Page, mark, and screenshot
+
+A site framework dependency or a site config file in the manifest or the tree marks a project as having a page. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
 
-- Check for a page. A dependency on a site framework or a site config file in the manifest or the tree marks a project as having one. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
 - A monorepo can carry a page in one package and a CLI in another, so both signals may fire. Report each rather than picking one.
 - Look for the mark and the screenshot among images the project already commits: scan the existing README for image references, then the asset and public folders.
 
@@ -61,13 +73,18 @@ Between agent-facing and plugin alone, a repository with no plugin manifest take
 
 ## Draft
 
-- Start from the picked or combined template. Draft the H1, a 2-3 sentence description in plain text, then the required sections, then whichever optional sections and per-type content Detect found. A README takes no frontmatter.
-- Open the page with the standard's header block, filling each slot from what Detect found: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot.
-- Fill the screenshot slot only with an image the project already commits, referenced with alt text naming what it depicts. This kind cannot capture one. Omit the slot when no such image exists and say so in the preview. Never write a placeholder path or invent a mark.
-- Omit the link and the screenshot for a project with no page, and the mark for a project with none, without a note in the drafted page. A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link.
+Start from the picked or combined template. Draft the H1, a 2-3 sentence description in plain text, the required sections, then whichever optional sections and per-type content Detect found. A README takes no frontmatter.
+
+- Open with the standard's header block, filled from Detect in order: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot
+- Fill the screenshot slot only with an image the project already commits, with alt text naming what it depicts, since this kind cannot capture one
+- With no such image, omit the slot and say so in the preview. Never write a placeholder path or invent a mark.
+- Omit the link and the screenshot for a project with no page, and the mark for a project with none, with no note in the page
+- A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link
 
 ### Types and badges
 
+A badge earns its place only once its rendered value is checked.
+
 - Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
 - Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
 - State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.

package/claude/skills/draft-doc/references/requirements.md

@@ -20,7 +20,8 @@ Does not govern:
 
 - The problem being solved and for whom, as the record's opening line under the title
 - User-facing goals stated as outcomes, not implementation
-- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded. A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence, and a non-goal resting on scope alone takes none.
+- Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded.
+- A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence. One resting on scope alone takes none.
 - Hard constraints that shape every decision, when the project has any
 
 ## What does not go in
@@ -32,17 +33,29 @@ Does not govern:
 
 ## Sections
 
-Require `## Goals` and `## Non-goals`. Add `## Constraints` when the project holds hard limits that shape every decision. Add `## Worldview` when the project holds beliefs that shape every decision, and keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list. Drop a section rather than pad it with filler.
+Require `## Goals` and `## Non-goals`, and drop any other section rather than pad it with filler.
+
+- Add `## Constraints` when the project holds hard limits that shape every decision
+- Add `## Worldview` when the project holds beliefs that shape every decision
+- Keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list
 
 ## Length
 
-This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. The template and the seed a new project installs state it at 600, and a project loosens it by editing the number in its own record. At the cap, cut a goal or a constraint that no longer changes a decision before adding one.
+This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter.
+
+- The cap is the record's own, so a record stating none is measured and never gated
+- The template and the seed a new project installs state 600, and a project loosens it by editing the number in its own record
+- At the cap, cut a goal or a constraint that no longer changes a decision before adding one
 
 ## Lifecycle
 
 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 goals. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Once every entry in it has shipped, delete the section, since version history keeps the old text and the document states the project as it stands. Nothing sequences a section 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.
+Later scope arrives as a new section rather than as an extension of the goals. Name it for what it delivers and state its entries as outcomes, the same way the goals are stated.
+
+- Once every entry in it has shipped, delete the section, since version history keeps the old text and the document states the project as it stands
+- Nothing sequences a section into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness.
+- A section states what is wanted and never when it lands
 
 ## Template
 

package/claude/skills/draft-doc/references/wiki-kind.md

@@ -11,35 +11,43 @@ The standard's `## Placement` section names the folder a page lands in and the v
 
 ## Guards
 
-- If `<wiki-root>` does not resolve, say so and ask whether to create it before drafting. A project carrying no such folder has never taken the standard's placement rule, so creating it is a decision rather than a step.
+If `<wiki-root>` does not resolve, say so and ask whether to create it before drafting. A project carrying no such folder has never taken the standard's placement rule, so creating it is a decision rather than a step.
 
 ## Placement
 
 The standard sets two tests and a page has to pass both. Run them before drafting anything, since a page failing either is non-conforming however well it is written.
 
-- **Owned outside this repository.** A subject describing how this repository works fails. Refuse and offer the docs or context kind of this skill: `❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run draft-doc naming that destination.`
-- **Owned by the vendor the folder split covers.** The standard names one owner and one subfolder. A third-party tool or a vendor-neutral concept fails, however reference-like it reads. Refuse: `❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.`
+| Test                                        | Fails on                                                                        | Refusal                                                                                                                                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Owned outside this repository               | A subject describing how this repository works                                  | `❌ <subject> is owned by this project, so it belongs in the docs surface or a context entry. Re-run draft-doc naming that destination.`   |
+| Owned by the vendor the folder split covers | A third-party tool or a vendor-neutral concept, however reference-like it reads | `❌ <subject> is outside the wiki's folder split. Route it to the docs surface or a skill body rather than adding a second folder for it.` |
+
+On the first test, offer the docs or context kind of this skill. The standard names one owner and one subfolder for the second.
 
 Do not widen the split to admit a subject. Adding a sibling folder is a change to the standard, argued there, rather than a placement this kind takes on its own.
 
 ## Collision
 
-- Derive the page slug per the standard's `## Naming` section and check whether `<wiki-root>/<vendor>/<slug>.md` already exists. If it does, stop: `❌ <path> already covers this subject. Edit that page against the standard instead of drafting a second one.`
-- Read `<wiki-root>/<vendor>/index.md` and check every title and description it lists against the subject. Stop on a match: `❌ <path> already covers this subject under a different name. Edit that page instead.`
+- Derive the page slug per the standard's `## Naming` section and check whether `<wiki-root>/<vendor>/<slug>.md` already exists
+- If it does, stop: `❌ <path> already covers this subject. Edit that page against the standard instead of drafting a second one.`
+- Read `<wiki-root>/<vendor>/index.md` and check every title and description it lists against the subject
+- Stop on a match: `❌ <path> already covers this subject under a different name. Edit that page instead.`
 
 ## Source
 
 The standard forbids working from training knowledge, so the draft is built on a read rather than on recall.
 
-- Fetch current information through the `claude-code-guide` agent for any subject that agent covers. Its answer is the source the page is written from.
-- Reach a subject the agent does not cover through the owner's own published documentation. Invoke `canon:search-craft` with the skill tool before searching for it, since finding the owner's documentation is the field-and-authority step that skill carries, and report it rather than proceeding silently when the skill does not resolve.
+Fetch current information through the `claude-code-guide` agent for any subject that agent covers, and write from its answer. Reach any other subject through the owner's own published documentation.
+
+- Invoke `canon:search-craft` with the skill tool before that search, since finding the owner's documentation is its field-and-authority step. Report it when it does not resolve.
 - Say the fetch failed and stop rather than substituting recall, even for a subject the session believes it knows. A page sourced from memory ships looking identical to one that was checked.
-- Close the intro with the `Source:` sentence the standard requires, linking the canonical page where one exists and naming the owner alone where the subject has no single URL.
+- Close the intro with the `Source:` sentence the standard requires, linking the canonical page, or naming the owner alone where the subject has no single URL
 - Stamp the read date on a source revised without notice, as `read <date>`. A claim traced to an undated read cannot be checked against what was actually read.
 
 ## Draft
 
-- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections. Let the read of the source decide what is a lesson: keep a fact only when the source page does not state it, and leave reference detail to the source.
+- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections
+- Let the read of the source decide what is a lesson. Keep a fact only when the source page does not state it, and leave reference detail to the source.
 - Write what the fetch returned rather than what the subject is assumed to do.
 - Answer one question per section and stop. A reader arrives to settle something specific rather than to read the page through.
 - Mark a claim the fetch left unsettled rather than smoothing over it. An unmarked gap reads as a checked fact.
@@ -50,4 +58,6 @@ Add `**Source:** <owner, and the read it came from>`, and confirm the source wit
 
 ## Write
 
-Regenerate `<wiki-root>/<vendor>`, naming the folder the page landed in rather than the root above it. The verb rewrites the `index.md` in the folder it is given and does not walk down, so regenerating at the root leaves the vendor catalog untouched. A page absent there is invisible to the next run's Collision step, which then drafts a second page on the same subject.
+Regenerate `<wiki-root>/<vendor>`, naming the folder the page landed in rather than the root above it. The verb rewrites the `index.md` in the folder it is given and does not walk down, so regenerating at the root leaves the vendor catalog untouched.
+
+A page absent from that catalog is invisible to the next run's Collision step, which then drafts a second page on the same subject.

package/claude/skills/draft-figure/references/architecture-set.md

@@ -25,11 +25,15 @@ Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams
 
 ## Sources
 
-- Read `canon/REQUIREMENTS.md`, `canon/context/index.md`, `CLAUDE.md`, and the language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`) when present, plus the top-level folder layout through `ls`. Do not recurse speculatively.
+- Read `canon/REQUIREMENTS.md`, `canon/context/index.md`, `CLAUDE.md`, and the language manifest (`package.json`, `pyproject.toml`, `Cargo.toml`) when present
+- Read the top-level folder layout through `ls`, and do not recurse speculatively
 - When neither planning file exists and no folder structure names a boundary, stop: `❌ No source signal for <view>. Add canon/REQUIREMENTS.md or run inside a project folder.`
 - When the view came from a code scan rather than planning prose, open the caption with `Source: code.` and add `Fidelity is lower than prose-driven figures. Verify against the project's intent.`
 
 ## Caption and prose
 
-- Name one or two code paths a reader can open, in the caption or the prose beside the figure. Cite only paths that exist and spell each one exactly, since a reader deciding whether the figure still holds starts by opening them.
-- Keep implementation detail out of the figure: function names and call signatures, library versions, config keys and environment variable names, retry counts and timeouts, and workarounds needing more than a sentence. That detail belongs in a `canon/context/` entry, which the caption points at by path when a reader needs the mechanism.
+Name one or two code paths a reader can open, in the caption or the prose beside the figure. Cite only paths that exist and spell each one exactly, since a reader deciding whether the figure still holds starts by opening them.
+
+- Keep implementation detail out of the figure, being function names and call signatures, library versions, config keys and environment variable names, retry counts and timeouts
+- A workaround needing more than a sentence stays out too
+- That detail belongs in a `canon/context/` entry, which the caption points at by path when a reader needs the mechanism

package/claude/skills/draft-figure/references/figures.md

@@ -9,7 +9,7 @@ Applies to every hand-drawn figure, wherever it is authored. A figure sits insid
 
 ## Scope
 
-Governs a hand-drawn figure wherever one is authored, naming no path because an attribute standard governs a fragment rather than a document type: when it earns its place, the render-first policy routing a graph-shaped subject through Mermaid, the wrapping and caption every figure carries, and its color and accessibility rules. It carries no template, since a figure has no document shape of its own and sits inside one another standard sets.
+Governs a hand-drawn figure wherever one is authored, being when it earns its place, the render-first policy routing a graph-shaped subject through Mermaid, the wrapping and caption every figure carries, and its color and accessibility rules. It names no path and carries no template, since it governs a fragment rather than a document type.
 
 Does not govern:
 
@@ -35,10 +35,12 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 ## The render-first policy
 
-- Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
-- Reserve freehand inline SVG, plain shapes and lines authored directly in the markup, for a subject that is not graph-shaped. A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent one drawn by hand, so the hatch stays open rather than forcing every figure through the renderer.
-- Draw a figure in a teach lesson freehand whatever its shape. A lesson letters its figures in a hand font the renderer cannot load, so Mermaid measures every label in a narrower fallback face, and the page then clips the wider text it actually shows.
-- State this as a render-first policy rather than a ban on a tool-exported drawing. Routing a graph-shaped figure through Mermaid is itself running it through an external tool, so a rule banning any diagram "exported from a diagramming tool" would forbid the path this policy requires.
+Route a graph-shaped subject, one whose relationship, boundary, or path a flowchart already expresses, through Mermaid's own hand-drawn look rather than through model-authored SVG coordinates. `mermaid.md` governs the fence itself.
+
+- Reserve freehand inline SVG, plain shapes and lines authored in the markup, for a subject that is not graph-shaped
+- A figure that cannot express its subject through the deterministic path is a worse failure than an inconsistent hand-drawn one, so the hatch stays open
+- Draw a figure in a teach lesson freehand whatever its shape. Its hand font cannot load in the renderer, so Mermaid measures labels in a narrower fallback face and the page clips them.
+- State this as a render-first policy rather than a ban on a tool-exported drawing, since routing through Mermaid is itself running an external tool
 
 ## Wrapping and captioning
 
@@ -47,5 +49,5 @@ A figure failing these is non-conforming even when it satisfies every shape rule
 
 ## Color and accessibility
 
-- Color every fill and stroke through a custom property the surrounding document's own stylesheet defines, never a literal hex value. The figure then re-colors itself on the same switch that re-colors the page.
+- Color every fill and stroke through a custom property the surrounding document's stylesheet defines, never a literal hex value, so the figure re-colors on the switch that re-colors the page
 - Give the drawing an accessible name: `role="img"` with `aria-label` for one short line, or `aria-labelledby` pointing at a `<title>` element inside it for a longer one.

package/claude/skills/draft-figure/references/hand-drawn.md

@@ -12,7 +12,9 @@ description: Authoring a freehand SVG, its color and accessibility audit, and th
 - Author the SVG by hand: plain shapes and lines authored directly in the markup.
 - Follow the `## Color and accessibility` section of `${CLAUDE_SKILL_DIR}/references/figures.md` for every fill, stroke, and accessible name.
 
-There is no external render to verify a freehand drawing against before it is written. The check here is the stroke-and-fill audit above and a read of the markup against what the subject means to show, done once rather than looped. Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes the in-page capture below.
+There is no external render to verify a freehand drawing against before it is written. The check is the stroke-and-fill audit above and one read of the markup against what the subject means to show, done once rather than looped.
+
+Hand-placed coordinates can drift out of line where a layout engine would not, so a freehand figure bound for a rendered page also takes the in-page capture below.
 
 ## Capture in the page
 

package/claude/skills/draft-figure/references/mermaid-path.md

@@ -9,8 +9,11 @@ description: The hand-drawn render config, the SVG and PNG pair, the hex rewrite
 
 ## Draft the fence
 
-- Draft the fence against `${CLAUDE_SKILL_DIR}/references/mermaid.md` for direction, node and edge budgets, `accTitle` and `accDescr`, and quoted labels. Do not work the layout or the budgets from memory.
-- Read every node and subgraph label against the banned characters `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` lists. The audit hook skips every line inside a fence, so a label carrying a banned character passes silently while the same character in the caption is caught. Reading the labels is the only gate they have. A colon works as a replacement inside a label.
+Draft the fence against `${CLAUDE_SKILL_DIR}/references/mermaid.md` for direction, node and edge budgets, `accTitle` and `accDescr`, and quoted labels. Do not work the layout or the budgets from memory.
+
+- Read every node and subgraph label against the banned characters `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md` lists
+- The audit hook skips every line inside a fence, so a banned character in a label passes silently while the same one in the caption is caught. Reading the labels is their only gate.
+- A colon works as a replacement inside a label
 
 ## Render
 
@@ -25,9 +28,9 @@ bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/f
 bunx -y @mermaid-js/mermaid-cli -i .canon/tmp/figures/<slug>.mmd -o .canon/tmp/figures/<slug>.png -c .canon/tmp/figures/<slug>.json
 ```
 
-Render both formats in one pass. The SVG is what ships inside the `<figure>`, and the PNG is what the read-back below judges, since an SVG's markup carries no recoverable spatial meaning.
+Render both formats in one pass. The SVG ships inside the `<figure>`, and the PNG is what the read-back below judges, since an SVG's markup carries no recoverable spatial meaning.
 
-Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
+- Use `bunx` when bun is available, falling back to `npx -y @mermaid-js/mermaid-cli ...` otherwise
 
 Before the first render in a project, say what is about to block:
 
@@ -42,14 +45,21 @@ Rewrite every stroke, fill, and text color the renderer wrote as a literal hex v
 ## Clipped titles
 
 - Expect a group title or a long label to clip once the destination shows it in the hand font, since the renderer sized its box in a fallback face.
-- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id, that sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly. The style hides the mismatch for a title and does nothing for a node label crowding its box, which takes a shorter label instead.
+- When the in-page check shows a clipped title, add a `<style>` inside the SVG, scoped to that SVG's own id
+- The style sets `overflow: visible` on the clipped label's `foreignObject` and centers the label within it, so the wider text spills past both edges evenly
+- It does nothing for a node label crowding its box, which takes a shorter label instead
 
 ## Fonts
 
-Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships unconditionally either way, but that flag alone embeds the Virgil and Excalifont font files. Without it, the figure falls back to the browser's own generic `cursive` face rather than the intended hand-drawn font, and the output names that gap when the flag was not passed.
+Check whether the project ran `canon design css --figures`. The figure and figcaption styling ships either way, but that flag alone embeds the Virgil and Excalifont font files.
+
+Without it, the figure falls back to the browser's generic `cursive` face rather than the hand-drawn font, and the output names that gap.
 
 ## Read the render back
 
-- Read the rendered PNG and judge it against what the figure means to say, applying the verification properties in the mermaid standard. A source satisfying every rule there can still render as a picture asserting something false, so the image is what gets judged.
-- Fix the Mermaid source and re-render on a defect. Stop after two correction passes. When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification.
-- When the render fails for any reason, no browser engine, no network, no package manager, continue to the confirm step and name the skipped check. A missing renderer degrades the loop rather than failing it.
+Read the rendered PNG and judge it against what the figure means to say, applying the verification properties in the mermaid standard. A source satisfying every rule there can still render as a picture asserting something false, so the image is what gets judged.
+
+- Fix the Mermaid source and re-render on a defect, stopping after two correction passes
+- When a defect survives, keep the figure and name the defect in the output rather than reporting a false verification
+- When the render fails for any reason, such as no browser engine, network, or package manager, continue to the confirm step and name the skipped check
+- A missing renderer degrades the loop rather than failing it

package/claude/skills/draft-figure/references/mermaid.md

@@ -9,7 +9,7 @@ Applies to every Mermaid fence, wherever it is written. A fence sits inside a do
 
 ## Scope
 
-Governs the Mermaid attribute wherever a fence is written, naming no path because an attribute standard governs a drawing rather than a document type: direction and layout, node and edge budgets, the accessibility fields, how punctuation reaches a label, and how a rendered diagram is verified. It carries no template, since a fence has no document shape of its own and sits inside one another standard sets.
+Governs the Mermaid attribute wherever a fence is written, being direction and layout, node and edge budgets, the accessibility fields, how punctuation reaches a label, and how a rendered diagram is verified. It names no path and carries no template, since it governs a drawing rather than a document type.
 
 Does not govern:
 
@@ -31,17 +31,21 @@ A diagram failing these is non-conforming even when it satisfies every shape rul
 
 ## Layout
 
-- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
+- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction when it links outward, as an architecture diagram normally does, so top-bottom is a declaration, not a guarantee.
 - Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
 - Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
 
 ### Rows and edges
 
+A row or a bundle asserts something about the system, so each is drawn only where it is true.
+
 - Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
 - Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
 
 ### Labels and subgraphs
 
+A label names a node, and the paragraph below the diagram carries the detail.
+
 - Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
 - Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
 - Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
@@ -51,12 +55,13 @@ A diagram failing these is non-conforming even when it satisfies every shape rul
 - Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
 - Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
 - Treat a diagram that cannot be described in one sentence as two diagrams.
-- Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement against a corpus, so a hard refusal on them will be wrong sometimes and unarguable when it is.
+- Warn rather than refuse on a budget, and name the split that would fix it
+- These numbers come from published Mermaid practice rather than a measurement, so a hard refusal on them would be wrong sometimes and unarguable when it is
 
 ## Labels
 
-- Apply the punctuation bans in `markdown.md` to node and subgraph labels. A label is not prose, so a check scoped to prose does not reach it, and reading the labels before shipping is the only gate they have.
-- Treat the prose around a fence and the text inside it as two surfaces. The paragraphs are prose and follow `markdown.md` and the `write-human` skill. The fenced block is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- Apply the punctuation bans in `markdown.md` to node and subgraph labels. A check scoped to prose does not reach a label, so reading the labels before shipping is their only gate.
+- Treat the prose around a fence and the text inside it as two surfaces. The paragraphs follow `markdown.md` and the `write-human` skill, and a prose check does not reach the fenced block.
 
 ## Accessibility