@erclx/canon 5.24.0 → 5.26.0

package/docs/workflow/skill-map.md

@@ -6,9 +6,9 @@ category: Workflow
 
 # Skill map
 
-Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
+Groups run in the order a project meets them. They reconcile the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, so every moment either one names has a group. Each row says when to reach for a skill, and its description says what it does.
 
-This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing. The landing page's skills field renders from this page, so its build refuses a skill with no row and a row naming no skill.
+This page and [skill map on request](skill-map-on-request.md) are the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row across the two. A skill serving two moments sits at the earlier one, this page counting as earlier than the sibling, and a mention on any other page is prose rather than routing. The sibling holds the groups that answer a request rather than mark a moment. The landing page's skills field renders from both pages, so its build refuses a skill with no row and a row naming no skill.
 
 ## Set up a project
 
@@ -18,7 +18,6 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                       |
 | `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs        |
 | `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                     |
-| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                        |
 | `canon:deploy-app`     | Once a project is ready to publish, to set up its Cloudflare or Vercel deploy and stop for token and domain |
 | `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README      |
 
@@ -32,6 +31,7 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:plan-groundwork`    | When the state is unmeasured and more than one approach is live                   |
 | `canon:decision-escalate`  | When open decisions turn on your preference and want batching into one set        |
 | `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side         |
+| `canon:canvas`             | When a direction should be drawn as frames the operator can see, select, and edit |
 | `canon:task-board`         | When a decided item needs a file on the board, or a shipped one needs archiving   |
 | `canon:plan-feature`       | When the approach is settled and the next step is a plan                          |
 | `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it    |
@@ -115,36 +115,3 @@ This page is the corpus the coverage claim is measured against: every name `cano
 | `canon:canon-feedback`        | When something in the toolkit is broken, missing, or off, to open an issue on it       |
 | `canon:canon-feedback-triage` | In the toolkit repo, to work through the open feedback issues                          |
 | `canon:canon-rollout`         | In the toolkit repo, to take one change out to every consuming project at once         |
-
-## Generate an artifact on demand
-
-| Skill                     | When to use                                                                                                                                    |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon:create-rule`       | For a project-specific governance rule the toolkit does not ship                                                                               |
-| `canon:create-skill`      | For a new `SKILL.md`                                                                                                                           |
-| `canon:create-standard`   | For a new authoring convention                                                                                                                 |
-| `canon:draft-doc`         | For a brand-new `docs/` page, context entry, wireframe surface, wiki reference page, or `README.md`, drafted against the standard for its kind |
-| `canon:draft-ready`       | For finished files a worker should copy, written as a ready folder with its overview, thin plan, and task                                      |
-| `canon:draft-figure`      | For a hand-drawn figure inside an existing doc, drafted against `standards/figures.md` in Mermaid or freehand SVG                              |
-| `canon:bash-cli-script`   | For a small non-interactive shell wrapper, stopping at 100 lines in favor of TypeScript on Bun                                                 |
-| `canon:ci-workflow`       | For a GitHub Actions workflow file                                                                                                             |
-| `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                                                                          |
-| `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                                                                  |
-| `canon:record-screencast` | For recording a screencast draft, then composing the take into a finished mp4 when the draft asks for a wrap                                   |
-| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop                                                    |
-
-## Answer a question at any point
-
-| Skill                       | When to use                                                                                                                                                            |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon:canon-cli`           | Before running an unfamiliar verb, a sync, or an install, to learn which command to run, which reference doc covers it, or what it overwrites, merges, or leaves alone |
-| `canon:index-lookup`        | To find where a topic is documented across the tracked `index.md` catalogs                                                                                             |
-| `canon:youtube-transcripts` | When a video transcript is wanted in the repo as context                                                                                                               |
-| `canon:read-frames`         | To read a recorded demo back frame by frame and report what each one shows, with no verdict on whether the recording looks right                                       |
-| `canon:teach-workspace`     | To learn a subject across sessions, in a workspace that holds the progress                                                                                             |
-| `canon:write-human`         | Before drafting or revising prose, for voice, rhythm, and density                                                                                                      |
-| `canon:restate-plainly`     | When an answer or a document has to be read again in plain words                                                                                                       |
-
-Every row answers a question rather than marking a point in a project's life, so a phase above would send a reader to the wrong group.
-
-A learning workspace produces two halves and only one of them leaves. A lesson is worked through once and stays in the workspace, and a reference page or a glossary carries no learner, so it belongs wherever the project already keeps prose on that subject. Asking `canon:teach-workspace` to promote sorts each durable page by who owns its subject, sending an Anthropic-owned subject to the wiki, an internal one to the matching context entry, and everything else, subject-neutral material included, to the public docs. It proposes and waits, because a promoted page is public prose that needs a line naming who owns the subject, and it writes nothing to a destination: each page the operator confirms goes to a handoff file that `canon:context-fold` folds in from a branch. A project with no wiki folder gets a refusal naming `canon wiki init` rather than a folder it never asked for.

package/docs/workflow/visual-design-workflow.md

@@ -41,6 +41,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
+- `canon:canvas` for a direction worked out over several turns, drawn as HTML frames you drag, select, and restyle in the browser while the session reads your changes back. Only the pick moves into `canon/DESIGN.md`, since the canvas folder is gitignored
 - `canon:ux-walkthrough` for a multi-finding inspection pass over a running app with the operator, drafting arms from the app's own markup and recording each pick for a builder
 - `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop. On an Astro project holding the card route scaffold, the card lands as a route the project keeps and is captured through a running server, so it reads the project's real stylesheet rather than typed copies of every color. Everywhere else it ships as a PNG and the run says so.
 - Anthropic's `frontend-design` plugin optional for light visual steering

package/governance/renames.toml

@@ -38,13 +38,11 @@
 "557-intake" = "657-intake"
 "558-plan" = "658-plan"
 "559-memory" = "659-memory"
-"560-diagrams" = "660-diagrams"
 "561-teach" = "661-teach"
 "562-session" = "662-session"
 "563-ready" = "663-ready"
 "500-prose" = "800-prose"
 "501-markdown" = "801-markdown"
-"502-mermaid" = "802-mermaid"
 "580-readme" = "880-readme"
 "591-standard-authoring" = "891-standard-authoring"
 "065-spelling" = "765-spelling"
@@ -61,13 +59,11 @@
 "656-groundwork" = "groundwork"
 "657-intake" = "intake"
 "659-memory" = "memory"
-"660-diagrams" = "diagrams"
 "661-teach" = "teach"
 "662-session" = "session"
 "663-ready" = "ready"
 "570-skill" = "skill"
 "590-rule-authoring" = "rule"
 "801-markdown" = "markdown"
-"802-mermaid" = "mermaid"
 "880-readme" = "readme"
 "891-standard-authoring" = "standard"

package/governance/rules/standards/markdown.md

@@ -13,3 +13,4 @@ paths:
 - 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.24.0",
+  "version": "5.26.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -45,7 +45,6 @@
     "web:favicon": "bun scripts/core/regen-web-favicon.ts",
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
-    "web:gallery": "cd web && astro build --config gallery.config.mjs",
     "web:card": "cd web && astro dev --config card.config.mjs",
     "web:card:check": "PROJECT_ROOT=web bash tooling/astro/configs/scripts/check-card-exclusion.sh",
     "web:preview": "cd web && astro preview",

package/scripts/core/install-check.sh

@@ -101,7 +101,7 @@ log_step "Assert scaffold"
 # scaffold reads a standard through `canon standards <name>`, resolving against
 # the toolkit rather than a copy this gate could assert on. The two
 # rule paths stand for the `claude` and `canon` groups `base` takes whole.
-for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" ".canon/diagrams/index.md" \
+for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" "canon/context/index.md" "canon/wireframes/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/canon/claude/565-behavior.md" ".claude/rules/canon/canon/604-scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/scripts/lib/sandbox-dispatch.sh

@@ -11,7 +11,7 @@
 #
 # Three mechanisms sit here rather than in `sandbox/run.sh`, which is the
 # only caller. Each is reachable from a test that never launches a session:
-# `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
+# `src/sandbox/dispatch.test.ts` drives the shim against a stub binary and the
 # reap against a `sleep`, where proving either through `run.sh` would mean
 # spawning the thing the bound exists to prevent.
 

package/scripts/lib/sandbox-git.sh

@@ -60,7 +60,7 @@ configure_sandbox_git_identity() {
 SANDBOX_ANCHOR_REPO="canon-sandbox"
 
 # A scenario calls this from its own use_anchor hook rather than this file
-# defining the hook. manage-sandbox.sh keys off `type -t use_anchor`, so
+# defining the hook. sandbox-hook.sh keys off `type -t use_anchor`, so
 # declaring it here would hand an anchor to the scenarios that source this file
 # for the identity helpers alone.
 use_sandbox_anchor() {
@@ -112,14 +112,6 @@ ensure_sandbox_anchor_repo() {
   log_info "Created ${GITHUB_ORG}/${repo_name} as a private repository."
 }
 
-# Mirrors the merge-base resolution the diff-baseline port already carries
-# across five skill bodies, so a checkout whose local main trails origin/main
-# does not pull in skill bodies other merged branches changed.
-resolve_sandbox_skill_diff_base() {
-  git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null ||
-    git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null
-}
-
 # A remote is useless without an author, so the scenarios that reach one always
 # configure both. configure_sandbox_git_identity stays callable on its own for
 # the scenarios that never push. The probe runs first so an absent remote is

package/scripts/lib/sandbox-path.sh

@@ -13,7 +13,7 @@
 # Mints a short random per-run identifier the first time it is asked for, then
 # holds it in CANON_SANDBOX_RUN_ID for the rest of this process. A direct call
 # (not `$(...)`) exports it into the caller's own shell, which is what lets
-# `run.sh` mint once and have manage-sandbox.sh and the check it shells out to
+# `run.sh` mint once and have the provisioning and the check it shells out to
 # both inherit the same id as ordinary children. A call already carrying the
 # variable, inherited from such a parent, reuses it rather than minting a new one.
 #

package/scripts/sandbox-hook.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# No `-u`. Scenarios ran under the retired dispatcher without it and read unset
+# variables as empty, so turning it on here changes what they provision.
+set -e
+set -o pipefail
+
+# Runs one scenario's hooks for the provisioning order in
+# `src/sandbox/provision.ts`. Scenarios and the library they call stay bash, so
+# the harness reaches them through this entry and nothing else.
+#
+#   probe <scenario>         runs `use_config` and `use_anchor` when declared
+#                            and prints every export they changed, closed by an
+#                            `@anchor=<0|1>` record
+#   stage <scenario> <file>  re-runs both hooks, runs `stage_setup` inside the
+#                            tree, and writes the exports it changed to <file>,
+#                            or an `@exited` record when the shell exits first
+#
+# Pairs are NUL-separated `NAME=value`, since a value can hold a newline. The
+# retired dispatcher ran `stage_setup` in its own shell, so an export, an `exit`,
+# or an `exec` there reached the harness, and the report carries all three: an
+# `exec` skips the EXIT trap and leaves no report at all. The stage re-runs the
+# hooks rather than receiving the probe's pairs, since they only export.
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+export PROJECT_ROOT
+
+# Globals carry a prefix, since the scenario sourced below shares this shell.
+_hook_die() {
+  echo "sandbox-hook: $1" >&2
+  exit 2
+}
+_hook_mode="${1:-}"
+_hook_scenario="${2:-}"
+_hook_report="${3:-}"
+
+[[ "$_hook_mode" == "probe" || "$_hook_mode" == "stage" ]] || _hook_die "mode must be probe or stage, got: ${_hook_mode:-<empty>}"
+[ -f "$_hook_scenario" ] || _hook_die "no scenario file at: ${_hook_scenario:-<empty>}"
+[ "$_hook_mode" = "probe" ] || [ -n "$_hook_report" ] || _hook_die "stage needs a file to report its exports to"
+[ "$_hook_mode" = "probe" ] || trap 'printf "@exited\0" >"$_hook_report"' EXIT
+
+declare -A _hook_before
+_hook_snapshot() {
+  local name
+  _hook_before=()
+  for name in $(compgen -e); do
+    _hook_before[$name]="${!name}"
+  done
+}
+
+# The shell moves PWD and OLDPWD itself on every `cd`, and neither is state.
+_hook_changed() {
+  local name
+  for name in $(compgen -e); do
+    [[ "$name" == "PWD" || "$name" == "OLDPWD" ]] && continue
+    if [[ ! -v _hook_before[$name] ]] || [ "${_hook_before[$name]}" != "${!name}" ]; then
+      printf '%s=%s\0' "$name" "${!name}"
+    fi
+  done
+}
+
+# Taken before `config.sh`, so a `GITHUB_ORG` it derives from the remote reaches
+# the harness as an export like any other.
+_hook_snapshot
+
+source "$PROJECT_ROOT/scripts/config.sh"
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-path.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-git.sh"
+source "$PROJECT_ROOT/scripts/lib/sandbox-fixtures.sh"
+
+# Unexported, as the dispatcher held them, so a scenario reads both while a
+# child it spawns sees neither. Shellcheck cannot see the scenario reading them.
+# shellcheck disable=SC2034
+SANDBOX="$(resolve_sandbox_dir)" SANDBOX_DIR="$PROJECT_ROOT/sandbox"
+
+# shellcheck source=/dev/null
+source "$_hook_scenario"
+
+_hook_declared() { [[ "$(type -t "$1")" == "function" ]]; }
+_hook_run() {
+  if _hook_declared use_config; then use_config; fi
+  if _hook_declared use_anchor; then use_anchor; fi
+}
+
+if [ "$_hook_mode" = "probe" ]; then
+  # Stdout carries the pairs alone, so a hook that prints is moved off it.
+  _hook_run >&2
+  _hook_changed
+  if _hook_declared use_anchor; then printf '@anchor=1\0'; else printf '@anchor=0\0'; fi
+  exit 0
+fi
+
+_hook_run
+_hook_snapshot
+cd "$SANDBOX"
+stage_setup
+trap - EXIT
+_hook_changed >"$_hook_report"

package/src/audits/catalog.ts

@@ -587,8 +587,8 @@ export const AUDITS: readonly AuditSpec[] = [
     corpus: 'tracked',
     // The one reason this verb refuses for that is an absence rather than a
     // break, on the same test the reach check and the skill audit take: no
-    // target adopts `canon/context/`, `.canon/diagrams/`, and
-    // `canon/wireframes/` all at once, so without the allowance every such
+    // target adopts `canon/context/`, an older install's `.canon/diagrams/`,
+    // and `canon/wireframes/` all at once, so without the allowance every such
     // project reports the verb unmeasured on every run and never changes.
     absentReasons: ['no-folders'] satisfies ContextAuditRefusal[],
     counts: contextCounts,

package/src/canvas/capture.ts

@@ -196,14 +196,6 @@ async function serveFor<T>(
 /** The element a composite is captured by, holding every frame and no chrome. */
 export const COMPOSITE_SELECTOR = '#canvas-composite'
 
-/**
- * The container holds no text, so its family exists only for the engine's
- * font probe, which rejects a family the machine lacks. The browser default is
- * Times New Roman, which a Linux runner often lacks, and `system-ui` is the one
- * every platform maps. Each frame keeps its own fonts inside its iframe.
- */
-const COMPOSITE_FONT = 'system-ui'
-
 export interface Placement {
   readonly frame: string
   readonly url: string
@@ -255,7 +247,7 @@ export function buildComposite(
   const html = [
     '<!doctype html>',
     '<html><head><meta charset="utf-8">',
-    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative;font-family:${COMPOSITE_FONT}}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
+    `<style>html,body{margin:0;background:transparent}#canvas-composite{position:relative}#canvas-composite iframe{position:absolute;display:block;border:0;background:transparent}</style>`,
     '</head><body>',
     `<div id="canvas-composite" style="width:${width}px;height:${height}px">`,
     ...iframes,