@erclx/canon 4.90.0 → 4.92.0

package/claude/skills/session-resume/SKILL.md

@@ -7,11 +7,11 @@ description: Resumes a previous session by reading the handoff it left behind, t
 
 ## Step 1: read tracked work
 
-Resolve `.canon/plans/`, `.canon/memory/`, and `.canon/tasks/` at the main worktree root the way `session-worktree` does.
+Resolve `.canon/plans/`, `.canon/memory/`, `.canon/compact/`, and `.canon/tasks/` at the main worktree root the way `session-worktree` does.
 
 Read these in parallel, skipping any that do not exist:
 
-- the newest `.canon/tasks/session-*.md`: the handoff a previous session wrote before a compaction, per `${CLAUDE_SKILL_DIR}/../../standards/session.md`. It leads the report rather than the reads.
+- the newest `.canon/compact/*.md`, then the newest `.canon/tasks/session-*.md`: the handoff a previous session wrote before a compaction. The first is the note `session-compact` writes, and the second is the board-side map per `${CLAUDE_SKILL_DIR}/../../standards/session.md`, which stays readable. Whichever exists leads the report rather than the reads, and both lead it when both exist.
 - `.canon/tasks/index.md`: the folder catalog. Read this before any individual task file, and take the task list from it by dropping the `index`, `priority`, `backlog`, and `session-` rows, which are siblings rather than tasks.
 - `.canon/plans/*.md`: execution detail for in-progress tasks
 - `.canon/memory/index.md` and any memory files relevant to the top backlog item
@@ -48,4 +48,4 @@ Memory is updated only when a recorded fact becomes wrong, never on resume. A do
 
 This skill reads a handoff and never writes one. Reading and writing are two jobs, and the write happens at the close of a session rather than at its start.
 
-Name the standard when the session asks how to leave a handoff behind, and let the session follow it directly. Any session may write one, whatever role it holds, so nothing here routes the request to another skill. A role carrying sections of its own adds them over the core per that role's own runbook.
+Route a session asking how to leave a handoff behind to `session-compact`, which writes a note under `.canon/compact/`. A session holding the orchestrator role takes `session-map` instead, which writes the board-side map the standard governs, and a role carrying sections of its own adds them over the core per that role's own runbook.

package/docs/agents/teach.md

@@ -27,7 +27,7 @@ canon teach list regular-expressions --json
 
 With no topic it reports one line per workspace, carrying the lesson, learning-record, reference-page, and glossary-term counts, plus `next`, the ordinal an open would take. With one it reports the filenames behind each count and the glossary entries themselves.
 
-A folder not named `NN-<topic>` is still listed rather than dropped, since dropping it hides the one folder that needs a fix. Its ordinal reads as absent, it sorts last, and it moves no ordinal, so a malformed name cannot push a new workspace into a number a reader already cites.
+A folder not named `NN-<topic>` is not a workspace, so the listing, `nav`, and every selector skip it and it moves no ordinal. That is what lets a teach root carry a sibling folder such as `evidence/` without it drawing as a stub row and receiving a contents page.
 
 The listing also names the required files a workspace does not carry, which is `MISSION.md`, `RESOURCES.md`, and `GLOSSARY.md`. That is a report rather than a refusal, because a workspace missing one is still a workspace a session can resume.
 
@@ -141,7 +141,7 @@ The order is drawn here rather than instructed, and that is the point of the ver
 
 ## Render
 
-`canon teach render` renders a lesson body's structural blocks to HTML, through the same components the fixture lesson under `examples/teach/00-fixture/` is generated from. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
+`canon teach render` renders a lesson body's structural blocks to HTML, through the components `src/teach/render-fixture.tsx` composes by hand. It takes no topic and no `--root`, since the verb is a stateless transform reading nothing off a workspace on disk.
 
 ```bash
 echo '[{"type":"heading","level":1,"text":"Compass bearings"}]' | canon teach render --json

package/docs/workflow/ai-workflow.md

@@ -280,7 +280,8 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:role-worker`       | To assert the worker role for a cold session building one branch under one plan |
 | `canon:session-relay`     | When a worker or planner owes its controller a message and holds no send tool   |
 | `canon:session-resume`    | At the start of a session, to pick up what a previous one left                  |
-| `canon:session-map`       | At the close of a session, to write the handoff a compaction would destroy      |
+| `canon:session-compact`   | Before a compaction, to write a plain session's handoff note outside the board  |
+| `canon:session-map`       | At the close of an orchestrating session, to write its board-side handoff       |
 
 ### Keep the project current with the toolkit
 
@@ -304,6 +305,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:create-snippet`    | For a reusable prompt                                                                                                               |
 | `canon:create-standard`   | For a new authoring convention                                                                                                      |
 | `canon:draft-docs`        | For a brand-new `docs/*.md` page, drafted against `standards/docs.md`                                                               |
+| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                           |
 | `canon:draft-context`     | For a brand-new `canon/context/<domain>.md` entry, drafted against `standards/context.md`                                           |
 | `canon:draft-wireframes`  | For a brand-new `canon/wireframes/<surface>.md` file, drafted against `standards/wireframes.md`                                     |
 | `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` and rendered through Mermaid or freehand SVG |

package/governance/rules/claude/563-ready.md

@@ -6,6 +6,10 @@ paths:
 
 # Ready standards
 
+## Writing a ready folder
+
+- Load the `canon:draft-ready` skill to write a ready folder, its overview, the thin plan, and the task row. It owns the procedure. Report it rather than proceeding silently when it does not resolve, since it ships with the plugin and this rule ships with the CLI.
+
 ## Authority
 
 - Follow the ready standard for the folder layout, ordinal naming, the overview frontmatter, the mirrored tree, and the thin-plan contract. It is the single source. Read it with `canon standards ready`.

package/governance/rules/ui/410-a11y.md

@@ -24,6 +24,12 @@ paths:
 - Arrow keys: navigate within composite widgets. Do not let them exit the widget.
 - Escape: closes any overlay, popover, dialog, or dropdown. Cancels in-progress edits.
 - Do not introduce non-standard key bindings for common actions.
+- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.2 Dragging Movements, 2.5.7).
+
+## Pointer targets
+
+- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.2 Target Size Minimum, 2.5.8).
+- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android. Do not apply the web figure to native, and do not apply the native figure as the web minimum.
 
 ## Composite widgets
 
@@ -34,6 +40,7 @@ paths:
 
 - Move focus into any overlay, popover, or dialog on open. Return focus to the trigger on close.
 - Never move focus on hover. Only on keyboard input or explicit pointer activation.
+- Do not let a sticky header, footer, or overlay fully cover the focused control. Scroll it into view clear of them (WCAG 2.2 Focus Not Obscured, 2.4.11).
 
 ## ARIA semantics
 
@@ -46,3 +53,5 @@ paths:
 - Always provide `alt` on `<img>`. Use `alt=""` for decorative images.
 - Describe the content or function of the image, not its appearance. Do not prefix with "Image of" or "Photo of".
 - Alt text for functional images (icons, buttons) should describe the action, not the graphic.
+- Give the visual boundary of a control and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG Non-text Contrast, 1.4.11).
+- Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG Use of Color, 1.4.1).

package/governance/rules/ui/420-forms.md

@@ -26,6 +26,15 @@ paths:
 - Show the error directly under the field that caused it, not under an unrelated field.
 - When a change to field A causes a conflict involving field B, show the error under field A (the field the user edited), not under field B.
 
+## Submission errors
+
+- When a failed submission carries several errors, move focus to a summary that links to each failing field. Keep the inline error beside each field.
+
+## Authentication and re-entry
+
+- Let a password manager fill sign-in fields and accept a pasted value. Do not block paste or autofill on a password or code field (WCAG 2.2 Accessible Authentication, 3.3.8).
+- Do not ask for information the user already gave earlier in the same flow. Prefill it or offer it for selection (WCAG 2.2 Redundant Entry, 3.3.7).
+
 ## Input sanitization
 
 - Trim leading and trailing whitespace from text inputs on blur or submit, not on every keystroke.

package/governance/rules/ui/460-design-taste.md

@@ -0,0 +1,29 @@
+---
+description: Route edits that decide how a surface looks to the design-taste skill for the layer ordering, the coherence locks, and the defaults a model reaches for
+paths:
+  - '**/*.css'
+  - '**/*.scss'
+  - 'canon/DESIGN.md'
+---
+
+# Design taste standards
+
+## Authority
+
+- Load the `canon:design-taste` skill for which design decision settles first, what must stay constant across a surface, and the defaults to reach past. It is the single source for all three.
+- Load it before drafting, not after revising. A revision recovers a color and never recovers the composition a draft already settled.
+- Report it rather than proceeding silently when the skill does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
+- Do not work the layer ordering or the coherence locks from memory.
+
+## When this fires and when it does not
+
+- This rule scopes to the files where an undecided visual choice lands, which is the stylesheet and the design document. Building a surface somebody already decided is implementation rather than design, and the rules below carry what implementation owes.
+- Load the skill by name when a component edit makes a visual choice nobody has taken yet, such as a new section's shape, a spacing relationship, or a radius. The glob cannot see that intent and no glob can.
+- Do not load it to ship a decided design. A worker wiring a picked composition pays the read and gets nothing back.
+
+## Boundaries
+
+- Accessibility, keyboard interaction and ARIA are a separate topic. `410-a11y` routes them, on every rendered path.
+- States, empty and loading coverage, and destructive confirmation are a separate topic. `430-ux-completeness` routes them.
+- Rendered copy casing, button labels and error wording are a separate topic. `400-ui` routes them.
+- The floor those three carry is not restated in the skill, and it is not traded against a preference where the two collide.

package/governance/rules/ui/470-motion.md

@@ -0,0 +1,23 @@
+---
+description: Moving content controls and the reduced-motion preference for rendered UI
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.astro'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# Motion standards
+
+## Moving content
+
+- Give any content that moves, blinks, or scrolls automatically for more than five seconds a control to pause, stop, or hide it (WCAG Pause, Stop, Hide, 2.2.2).
+- Halt an auto-advancing carousel or ticker while it holds keyboard focus or pointer hover.
+- Do not flash content more than three times in any one second.
+
+## Reduced motion
+
+- Honor `prefers-reduced-motion: reduce` for every animation and transition that conveys no state. Remove it or replace it with an instant change.
+- Keep essential state changes visible under reduced motion, using a fade or a static indicator instead of movement.
+- Do not start video or animated backgrounds on their own when the preference is set.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]
+rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]

package/governance/stacks/react.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior"]
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "305-e2e-reliability", "306-test-scope", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture", "450-link-behavior", "460-design-taste", "470-motion"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.90.0",
+  "version": "4.92.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/authoring.ts

@@ -42,6 +42,11 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
     expect: 'draft-docs',
   },
+  {
+    prompt:
+      'I already wrote the finished skill files, package them as a ready folder with a plan and a task for a worker to copy.',
+    expect: 'draft-ready',
+  },
   {
     prompt: 'This project has no README.md at all, write one from scratch.',
     expect: 'draft-readme',

package/src/claude/cases/misc.ts

@@ -12,6 +12,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'Show me a few different treatments for this callout so I can pick one by looking.',
     expect: 'draft-and-pick',
   },
+  {
+    prompt:
+      'Which layer of this landing page should I settle first, and what has to stay constant across it?',
+    expect: 'design-taste',
+  },
   {
     prompt:
       'This project has no logo yet. Draft one and give me a social card to go with it.',
@@ -29,6 +34,11 @@ export const MISC_CASES: readonly SkillCase[] = [
   {
     prompt:
       "We're about to hit the context limit, write the handoff before we lose state.",
+    expect: 'session-compact',
+  },
+  {
+    prompt:
+      'I am the orchestrating session and about to compact, so write the board handoff as a session map on the task board.',
     expect: 'session-map',
   },
   {

package/src/commands/capture.ts

@@ -42,6 +42,7 @@ type CaptureResult = Awaited<ReturnType<Renderer['captureSources']>>[number]
 export function register(program: Command): void {
   program
     .command('capture')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Render HTML capture sources to PNG')
     .argument(
       '[source]',

package/src/commands/design.ts

@@ -26,12 +26,14 @@ import { mainWorktreeRoot } from '@/worktree'
 export function register(program: Command): void {
   const design = program
     .command('design')
+    .helpOption('-h, --help', 'Show this help message')
     .description(
       'Design system commands (regen, css, render, board, install, sync)',
     )
 
   design
     .command('regen')
+    .helpOption('-h, --help', 'Show this help message')
     .description(
       'Rewrite canon/DESIGN.md and the base stylesheet from src/design/tokens.ts',
     )
@@ -84,6 +86,7 @@ export function register(program: Command): void {
 
   design
     .command('css')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Emit the design tokens and components as CSS on stdout')
     .option(
       '--no-components',
@@ -104,6 +107,7 @@ export function register(program: Command): void {
 
   design
     .command('render')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Render DESIGN.md tokens to HTML and CSS preview')
     .option(
       '-s, --source <path>',
@@ -137,6 +141,7 @@ export function register(program: Command): void {
 
   design
     .command('board')
+    .helpOption('-h, --help', 'Show this help message')
     .description(
       'Generate the design board, an index over a project’s design surfaces',
     )

package/src/commands/feedback.ts

@@ -71,6 +71,7 @@ function writeLocal(body: string, mismatch: string | undefined): string {
 export function register(program: Command): void {
   program
     .command('feedback')
+    .helpOption('-h, --help', 'Show this help message')
     .description(
       'Write toolkit feedback from stdin to .canon/feedback/, or open a GitHub issue with --github',
     )

package/src/commands/slides.ts

@@ -11,10 +11,12 @@ import { intro, outro, palette } from '@/ui'
 export function register(program: Command): void {
   const slides = program
     .command('slides')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Slide deck commands (render, list)')
 
   slides
     .command('render')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Render a SLIDES.md source into a PowerPoint deck')
     .option('-s, --source <path>', 'Source SLIDES.md path', '.claude/SLIDES.md')
     .option(
@@ -82,6 +84,7 @@ export function register(program: Command): void {
 
   slides
     .command('list')
+    .helpOption('-h, --help', 'Show this help message')
     .description('List the available slide layouts')
     .option('--json', 'Output the layout catalog as JSON')
     .action((opts: { json?: boolean }) => {

package/src/commands/transcripts.ts

@@ -25,6 +25,7 @@ export async function resolveOutDir(opts: TranscriptOptions): Promise<string> {
 export function register(program: Command): void {
   program
     .command('transcripts <url>')
+    .helpOption('-h, --help', 'Show this help message')
     .description('Fetch a YouTube transcript with metadata frontmatter')
     .option(
       '-o, --out <path>',

package/src/design/base.css

@@ -24,31 +24,37 @@
   --color-light-accent: #ad4a4b;
   --color-light-success: #2d6b22;
   --color-light-border: #d5d4d1;
-  --space-xs: 6px;
-  --space-sm: 12px;
-  --space-md: 18px;
-  --space-lg: 24px;
-  --space-xl: 30px;
-  --space-frame-top: 44px;
-  --space-frame-inline: 52px;
-  --space-frame-bottom: 38px;
-  --type-display-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
-  --type-display-size: 34px;
+  --space-xs: 0.25rem;
+  --space-sm: 0.5rem;
+  --space-md: 0.875rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2.5rem;
+  --space-2xl: 4rem;
+  --space-3xl: 6rem;
+  --t0: 3.175rem;
+  --t1: 2.375rem;
+  --t2: 1.375rem;
+  --t3: 1.125rem;
+  --t4: 0.9375rem;
+  --t5: 0.8125rem;
+  --t6: 0.6875rem;
+  --type-display-family: Geist Variable, DejaVu Sans, sans-serif;
+  --type-display-size: 2.375rem;
   --type-display-lh: 1.3;
-  --type-page-display-family: Noto Sans, DejaVu Sans, sans-serif;
-  --type-page-display-size: 52px;
+  --type-page-display-family: Geist Variable, DejaVu Sans, sans-serif;
+  --type-page-display-size: 3.175rem;
   --type-page-display-lh: 1.1;
-  --type-heading-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
-  --type-heading-size: 19px;
+  --type-heading-family: Geist Variable, DejaVu Sans, sans-serif;
+  --type-heading-size: 1.375rem;
   --type-heading-lh: 1.3;
-  --type-body-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
-  --type-body-size: 16px;
+  --type-body-family: Geist Variable, DejaVu Sans, sans-serif;
+  --type-body-size: 0.9375rem;
   --type-body-lh: 1.65;
-  --type-label-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
-  --type-label-size: 12px;
+  --type-label-family: Geist Variable, DejaVu Sans, sans-serif;
+  --type-label-size: 0.8125rem;
   --type-label-lh: 1.45;
   --type-code-family: Noto Sans Mono, DejaVu Sans Mono, monospace;
-  --type-code-size: 14.5px;
+  --type-code-size: 0.8125rem;
   --type-code-lh: 1.3;
   --radius-frame: 12px;
   --radius-panel: 10px;

package/src/design/css.ts

@@ -77,6 +77,10 @@ function tokenProperties(tokens: DesignTokens): string[] {
     lines.push(`  --space-${slug(step.step)}: ${step.value};`)
   }
 
+  for (const step of tokens.typeScale) {
+    lines.push(`  --${slug(step.step)}: ${step.size};`)
+  }
+
   for (const role of tokens.typography) {
     lines.push(`  --type-${slug(role.role)}-family: ${role.family};`)
     lines.push(`  --type-${slug(role.role)}-size: ${role.size};`)