@erclx/canon 4.74.0 → 4.75.1

package/standards/figures.md

@@ -0,0 +1,51 @@
+---
+title: Figure reference
+description: 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
+---
+
+# Figure reference
+
+Applies to every hand-drawn figure, wherever it is authored. A figure sits inside a document some other standard shapes, so this file reaches the figure and stops at its closing `</figure>` tag.
+
+## 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.
+
+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
+
+## What a working figure looks like
+
+A figure works when a reader who cannot see it still gets what it was for, and one who can see it gets nothing a well-placed sentence could not carry:
+
+- Does the subject clear the bar: a relationship, a boundary, a path, or a before-and-after that prose or a list cannot carry as well?
+- Does the caption name what to take from the figure rather than what it shows?
+- Does the figure still read after every color and font it depends on is stripped to its fallback?
+
+A figure failing these is non-conforming even when it satisfies every shape rule below.
+
+## When a figure earns its place
+
+- Draw a figure only when a relationship, a boundary, a path, or a before-and-after is the point of the passage rather than decoration for it. Most passages do not clear that bar.
+- Leave the point in prose or a list when it already carries there. A figure reaching for every passage repeats the failure restraint already guards against elsewhere in the document.
+
+## 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.
+- 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.
+
+## Wrapping and captioning
+
+- Wrap a figure in a `<figure>` element holding its drawing and a `<figcaption>` that names what to take from the figure rather than what it shows.
+- Let the figure run wider than the surrounding prose column. A figure cramped to the reading measure loses the labels it needs.
+
+## 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.
+- 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/standards/groundwork.md

@@ -25,6 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
+- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
 - Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one already present across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.

package/standards/index.md

@@ -14,6 +14,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Design reference](design.md): Shape and content rules for .claude/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
 - [Groundwork reference](groundwork.md): Folder layout, ordinal naming, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, ordinal naming, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval

package/standards/intake.md

@@ -25,6 +25,7 @@ Does not govern:
 ## Folder name
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug. This is the folder's own ordinal, distinct from the `NN-<domain>.md` numbering a cluster file carries inside it.
+- The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
 - Claim the ordinal through `canon records ordinal intake <slug> --claim`, which reads the highest one already present across both `.canon/intake/` and `.canon/groundwork/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
 - With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a dump, which starts at `00` and disagrees with groundwork's own first required file.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.

package/standards/skill.md

@@ -156,7 +156,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 
 - `name` (required): kebab-case, matches folder name, no spaces or capitals
 - `description` (required): what it does + when to use it, under 1024 chars, no XML tags
-- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger
+- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger. Set it on a skill that starts a process the operator owns, never on one reachable by a matched trigger. The field marks that boundary, not a style preference.
 - `allowed-tools`: restrict tool access when the skill is active
 - `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)