@erclx/canon 4.53.0 → 4.54.0

package/README.md

@@ -10,6 +10,14 @@ canon is a CLI and Claude Code plugin that stops your AI conventions drifting ap
 
 The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today.
 
+## It runs on itself
+
+The workflow this toolkit ships is the workflow that built it. Several Claude Code sessions run at once, each in its own git worktree on its own branch, and each opens its own pull request.
+
+![The canon landing page's session list, with the orchestrator pinned above bands of working and completed sessions, workers and planners in both, each naming what it is doing and the pull request it opened, and one row moving from Working into Completed](demos/agent-view.gif)
+
+That is the landing page's own agent view, recorded from a local build by `canon demo run`. The session rows behind it are a real `canon sessions list --json` read. The activity text and the pull request number are transcribed, because no verb here reports either.
+
 ## Why
 
 If you work across more than one repository and your AI setup has started to drift between them, this is for you. Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.53.0",
+  "version": "4.54.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-feature/SKILL.md

@@ -93,7 +93,7 @@ Omit empty sections. Do not print `None identified.` in chat.
 
 Derive a 2-to-4-word kebab-case slug from the feature description. Write the full plan to `.canon/plans/feature-<slug>.md` at the main worktree root, not the current worktree. Resolve that root the way `claude-worktree` does. Create the directory if it does not exist.
 
-From a linked worktree the file-editing tools refuse that path, so the plan goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
+From a linked worktree, or from a background session sitting at the main root with none entered, the file-editing tools refuse that path, so the plan goes out through `Bash`. Send the `mkdir -p` and the heredoc as two plain commands rather than joining them with `&&`, which is refused as compound.
 
 The file follows the template in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. Copy the shape from there rather than from this body, so one edit to the standard moves every plan.
 

package/claude/skills/claude-orchestrate/references/orchestrator-dispatch.md

@@ -227,6 +227,9 @@ build shape above reaches `claude-worker`.
 No branch and no worktree exist here and none is created. A planner writes one
 gitignored file at the main worktree root, so this shape names the row's task
 file rather than a branch and opens with the role instead of a worktree call.
+That write meets the isolation guard the same way a linked worktree's
+main-root write does, with no worktree here to redirect it to, so
+`claude-planner` sends it as a `Bash` heredoc rather than through `Write`.
 
 ```bash
 claude --bg --model <model> -n "planner-<project>-<slug>" "Run /canon:claude-planner, then /canon:claude-feature <task>. Your controller is the session whose sessionId is <dispatcher-id>. Resolve its current name from that id through canon sessions list --json, which carries sessionId per row, at the moment you send, and never resolve an addressee by name prefix. Message it when the plan lands, carrying the path and what the task file got wrong, and message it again if you stop on a question."

package/claude/skills/claude-planner/SKILL.md

@@ -21,7 +21,7 @@ from here.
 
 ## Where the session stands
 
-- Write one file, the plan, at `.canon/plans/feature-<slug>.md` on the main worktree root. Everything else this session touches is a read.
+- Write one file, the plan, at `.canon/plans/feature-<slug>.md` on the main worktree root. Everything else this session touches is a read. This session holds no worktree, so send the file as a plain `Bash` heredoc past the same main-root refusal a linked worktree meets. The route skips the write-matched hooks, and they are no-ops on a plan file.
 - Never enter a worktree, never create a branch, and never write a tracked file. A planner that builds has stopped being one, and the row loses the independent read the worker's own session was going to bring to it.
 - Resolve `.canon/plans/`, `.canon/tasks/`, and `.canon/review/` at the main worktree root. Those folders are gitignored, so a copy beside a linked worktree is absent rather than empty.
 - Plan the row the launch named. Report a second row met while reading rather than planning it, since which rows run is the controller's call.

package/docs/agents/commands.md

@@ -20,6 +20,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon sandbox check`         | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                                                                                                                             |
 | `canon sandbox coverage`      | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                                                                                                                                    |
 | `canon indexes regen`         | Regenerate `index.md` files from sibling frontmatter                                                                                                                                                                                              |
+| `canon indexes list [path]`   | Flatten every folder index under a path into one `{path, title, description}` catalog (`--json`)                                                                                                                                                  |
 | `canon docs [topic]`          | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                          |
 | `canon design render`         | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                 |
 | `canon design regen`          | Rewrite this repository's `.claude/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                               |

package/docs/agents/demo.md

@@ -38,19 +38,22 @@ A step's caption from the draft renders as an overlay while its hold plays, so t
 
 When `ffmpeg` is on PATH, the run also writes an mp4 beside the webm, since webm plays in a `<video>` tag but nothing else accepts it. A target without `ffmpeg` still gets the webm and a line naming what to install, and the run does not fail over the missing converter.
 
-| Option           | Behavior                                                    |
-| ---------------- | ----------------------------------------------------------- |
-| `--out <dir>`    | Directory to write into, overriding what the plan names     |
-| `--cursor <dir>` | Cursor theme folder to draw the pointer from                |
-| `--no-video`     | Write only the still                                        |
-| `--no-still`     | Write only the recording                                    |
-| `--json`         | Add a record on stdout carrying both paths and the duration |
+`--gif` adds a third file from the same converter, and it is opt-in where the mp4 is not. A gif runs several times the size of the webm it derives from, and the destination that needs one is a README on a host that strips `<video>`, which GitHub does. The filter generates a palette from the source and then applies it, rather than quantizing per frame, since a per-frame palette is what makes a recording of flat interface colors band and shimmer. It applies that palette without dithering, because the command records applications rather than photographs and the dither writes noise the encoder then stores. One recording measured 3,193,715 bytes dithered against 2,701,941 without, with the same text region cropped from both and read as identical. A missing converter is reported the same way it is for the mp4, so an absent `ffmpeg` costs the gif and not the run.
+
+| Option           | Behavior                                                            |
+| ---------------- | ------------------------------------------------------------------- |
+| `--out <dir>`    | Directory to write into, overriding what the plan names             |
+| `--cursor <dir>` | Cursor theme folder to draw the pointer from                        |
+| `--no-video`     | Write only the still                                                |
+| `--no-still`     | Write only the recording                                            |
+| `--gif`          | Also write a gif, for a host that strips video                      |
+| `--json`         | Add a record on stdout carrying every path written and the duration |
 
 A step waits on its `waitFor` selector becoming visible and then holds for its own `holdMs`, which is what puts a finished state on screen long enough to read. `navigate` uses the plan's URL unless the step names its own.
 
 ## The pointer is painted inside the page
 
-The browser engine's own annotation draws a red dot at the moment of a click and an action label in a corner. It paints no cursor, so a run without more looks like the pointer teleports between targets.
+The browser engine offers an annotation of its own that draws a dot on the interacted element and a title naming the API call it made, and this recorder does not turn it on. It paints no cursor, so a run relying on it looks like the pointer teleports between targets, and the two overlays below supersede it: a real cursor where the dot is a marker, and the beat's narration where the title reads `Mouse move`. Running both put four overlays on the frame, and the two the engine drew were the two a viewer reads as noise.
 
 The recorder injects a pointer element before navigation and moves it through the engine's pointer with interpolated steps rather than through the element-clicking helper, which resolves a target and jumps to it. The step count is the whole difference between a cursor that travels and one that appears, and how many steps a move takes is derived from the machine's own round-trip cost rather than fixed, so the same plan glides at roughly the same pace on a loaded machine as an idle one. It also reads the element under it on every move and switches between an arrow, a hand, and a text beam, so it reflects the page the way a real cursor does.
 

package/docs/agents/index.md

@@ -20,7 +20,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Docs](docs.md): How canon docs resolves the toolkit's own reference surface from an install root, and how a split domain is named
 - [Driver](driver.md): Walking a page through named interactions, the probe catalog and the false finding each one carries, why viewport heights are never defaulted, and what each refusal reports
 - [Merge gate](gate.md): Running the gate this repository verifies a branch with, what the stage table holds and what stays a script, how the changed set scopes three stages, and why a stage that cannot read its input reports rather than passing
-- [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen, plus when it auto-stages what it rewrote
+- [Indexes](indexes.md): Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
 - [Install and sync](install-and-sync.md): What each install and sync verb writes, refuses, or leaves alone, and how drift is attributed in a target project
 - [Intake](intake.md): Reading intake folder counts and items, the three read states an item can be in, landing a batch of selections in one cluster, the refusal reasons, and why a call is scoped to one file
 - [Key Changes bijection](key-changes.md): Comparing the files a pull request body's Key Changes names against its own diff, the two directions and the split inside each that decides what is worth raising, the span rules the extractor was measured into, and the three refusals that separate a clean pass from a read that produced nothing

package/docs/agents/indexes.md

@@ -1,6 +1,6 @@
 ---
 title: Indexes
-description: Flags, exit codes, and JSON shape for canon indexes regen, plus when it auto-stages what it rewrote
+description: Flags, exit codes, and JSON shape for canon indexes regen and canon indexes list, plus when regen auto-stages what it rewrote
 ---
 
 # Indexes
@@ -32,4 +32,20 @@ Skills can parse drift without branching on exit code:
 canon indexes regen --dry-run --json | jq '.results[] | select(.action == "would-write")'
 ```
 
+## List
+
+`canon indexes list [path]` walks every folder index under `path` (default: cwd) and flattens each folder's own `title`/`subtitle` plus every sibling's `title`/`description` into one catalog, sorted by path relative to the walk root.
+
+| Option   | Behavior                                   |
+| -------- | ------------------------------------------ |
+| `--json` | Emit `{ root, entries, errors }` on stdout |
+
+Each entry is `{ path, title, description }`. `path` is relative to the resolved root, and an `index.md` file's own row uses its `subtitle` as `description`.
+
+A folder failing frontmatter validation lands its message in `errors` and drops out of `entries` rather than failing the whole walk, matching `regen`'s per-folder isolation. Every mode writes one `ERROR:` line per error to stderr.
+
+Exit codes: `0` no errors, `1` root not a directory, or a folder failed frontmatter validation.
+
+A git-ignored indexed folder, such as `.canon/tasks/` or `.canon/memory/`, never appears in the output. `listIndexes` filters candidates through `git check-ignore` the same way `regen`'s whole-repo walk does, which is the right default for a documentation lookup since those rows are session scratch, but it is a gap against `regen`'s positional-path mode, which bypasses that filter for those two folders.
+
 For the system rationale, frontmatter contract, when to adopt, and bootstrap path, see `.claude/context/indexes.md`.

package/governance/rules/core/085-worktrees.md

@@ -15,3 +15,5 @@ description: Route tracked-file writes and shared session scratch correctly from
 - From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
 - `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.
 - Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through a command that resolves the main root in-process, because the shell route for that case is the stream editor this file bans.
+- A background session that entered no worktree at all meets the identical refusal writing to the main root, since the guard gates on isolation rather than on sitting inside a linked worktree. A planner writing its plan file from no worktree takes the same heredoc route for that reason.
+- The heredoc route costs nothing on `.canon/plans/` and `.canon/review/`, which no `PostToolUse` hook watches, and costs the index on `.canon/tasks/` and `.canon/memory/`, since a hook matching `Write|Edit|MultiEdit` never fires on `Bash`. Regenerate positionally: in-process where a verb such as `canon tasks archive` already calls it, elsewhere by an explicit `canon indexes regen` call.

package/package.json

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

package/scripts/core/regen-agent-fixture.sh

@@ -0,0 +1,235 @@
+#!/usr/bin/env bash
+# Writes web/src/fixtures/agent-view.json from a real `canon sessions list
+# --json` read of this repository's own sessions.
+#
+# The page it feeds re-creates an orchestrator dispatching workers, which is the
+# one thing this toolkit does that no other surface here shows. A re-creation
+# earns nothing if the rows behind it are invented, so the session half is a
+# live listing and never a literal.
+#
+# Every role in the roster appears, not the workers alone. The controlling
+# session is pinned above the bands and planners sit in them beside workers,
+# which is what the surface being re-created does. An earlier version of this
+# script filtered the listing down to sessions holding a feature branch, and
+# that dropped the orchestrator and every planner, since a controlling session
+# and a planning session both sit on the default branch. A page about a dispatch
+# that excludes the dispatcher is the defect that filter shipped.
+#
+# Two fields cannot come from the listing and are transcribed by hand into the
+# table below. The activity text is written by Claude Code into its own status
+# line and no verb here reports it. The pull request number sits on a task file
+# with nothing joining a session record to it, which the plan behind this script
+# took as a trade rather than building the join. Both are recorded as
+# transcribed in the fixture's own header, so a reader of the committed file can
+# tell which half was measured and which was typed.
+#
+# The honesty cost this leaves open is the one assets/captures/install.html.tmpl
+# already documents for the terminal frames: a hand-edit after generation
+# defeats the discipline silently, and nothing here detects one.
+#
+# Clone-only. It reads this repository's own sessions, and a registry install
+# carries no such listing.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+OUT="$PROJECT_ROOT/web/src/fixtures/agent-view.json"
+
+# Transcribed half, keyed by session name. The name is the only key that reaches
+# every row: a controlling session and a planning session both sit on the
+# default branch, so a branch cannot tell them apart or from each other. A
+# dispatched session is named `<role>-<project>-<slug>` after the work it was
+# given rather than after what it turned out to be doing, which is what makes
+# the name stable enough to key on here.
+#
+# Each row is `name|activity|pullRequest|state|age`. The state is `pinned`,
+# `working`, or `completed`, and it is where the row renders. An empty pull
+# request field is a session that had not reached its ship step when the
+# snapshot was taken.
+#
+# A pinned or working row has to appear in the live listing or this refuses, and
+# its age comes from the listing rather than the table, so the trailing field is
+# empty for those. A completed row names a session that has already exited, so
+# no listing carries it, its age is transcribed with the rest of the row, and
+# leaving that field blank would print an empty column on half the list.
+# Re-transcribe this table against a fresh listing rather than editing the
+# generated file.
+#
+# A planner belongs in this table as much as a worker does. `claude-planner`
+# forbids entering a worktree, so a planner registers on the default branch at
+# launch and stays there for its whole life, which is why the branch filter this
+# script used to carry dropped every one of them permanently rather than
+# occasionally.
+ROWS=(
+  "orchestrator-canon-lead|dispatching the planners that need a plan||pinned|"
+  "worker-canon-agent-view-and-deploy|PR #1510 open (landing page)|1510|working|" # canon-allow-reference: transcribed status text
+  "planner-canon-context-wireframe-draft|drafting the context and wireframe plan||working|"
+  "planner-canon-skill-coverage-pointers|reading the skill coverage pointers||working|"
+  "planner-canon-screenshot-trap-guard|planning the screenshot trap guard||working|"
+  "planner-canon-write-route-hook-bypass|plan written; tested write probe||completed|32m"
+  "planner-canon-indexes-list-lookup|plan and task board consistent||completed|13m"
+  "worker-canon-labels-scan-body-file|address-review pass finished|1508|completed|21m"
+  "worker-canon-web-context-entry|PR #1507 addressed with commit|1507|completed|20m" # canon-allow-reference: transcribed status text
+)
+
+# The listing reports a session's repository as the main `.git` directory, which
+# is what this resolves whether the script runs from the main checkout or from a
+# linked worktree. Comparing against PROJECT_ROOT instead would match nothing
+# from a worktree, where the two differ.
+MAIN_GIT_DIR="$(cd "$PROJECT_ROOT" && git rev-parse --path-format=absolute --git-common-dir)"
+
+# `bun src/cli.ts` rather than `canon`, since a globally linked binary resolves
+# to the main checkout no matter which worktree is running, and this script is
+# run from a worktree as often as not.
+SESSIONS_JSON="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts sessions list --json 2>/dev/null)"
+
+if [ -z "$SESSIONS_JSON" ]; then
+  echo "regen-agent-fixture: the session listing returned nothing, refusing to write an empty fixture" >&2
+  exit 1
+fi
+
+# The listing crosses into the eval as a file rather than an environment entry,
+# for the reason regen-hero.sh records: Linux caps a single env string at 128KB
+# and a machine running many sessions can cross it, which fails the exec with
+# E2BIG before any check can report a thing.
+SESSIONS_FILE="$(mktemp)"
+trap 'rm -f "$SESSIONS_FILE"' EXIT
+printf '%s' "$SESSIONS_JSON" >"$SESSIONS_FILE"
+
+TRANSCRIBED_ROWS="$(printf '%s\n' "${ROWS[@]}")"
+READ_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+export SESSIONS_FILE OUT PROJECT_ROOT READ_AT TRANSCRIBED_ROWS MAIN_GIT_DIR
+
+bun --eval '
+const { readFileSync } = require("node:fs")
+
+const { SESSIONS_FILE, OUT, PROJECT_ROOT, READ_AT, TRANSCRIBED_ROWS, MAIN_GIT_DIR } =
+  process.env
+
+const listing = JSON.parse(readFileSync(SESSIONS_FILE, "utf8"))
+
+const rows = TRANSCRIBED_ROWS.split("\n")
+  .map((line) => line.replace(/\s*#\s*canon-allow-reference:.*$/, "").trim())
+  .filter((line) => line !== "")
+  .map((line) => {
+    const [name, activity, pullRequest, state, age] = line.split("|")
+    return {
+      name,
+      activity,
+      pullRequest: pullRequest ? Number(pullRequest) : null,
+      state,
+      age: age || null,
+    }
+  })
+
+// Narrowed to this repository, and the reason is disclosure rather than scope.
+// `canon sessions list` is machine-wide, so an unfiltered read carries the
+// session names and worktree paths of every other project on the machine, which
+// here includes paths under a folder named `private` and several client names.
+// This fixture renders on a public page, so the filter is what keeps them off
+// it. The cost is a fidelity gap stated plainly: the real surface is
+// machine-wide and the depiction is one repository, and that is a deliberate
+// narrowing rather than an oversight.
+//
+// Keyed by name for the reason the shell comment gives: a session on the
+// default branch has no other identity, and the orchestrator and every planner
+// sit there.
+const live = new Map(
+  listing.sessions
+    .filter((session) => session.repository === MAIN_GIT_DIR)
+    .map((session) => [session.name, session]),
+)
+
+// The real surface shows an age per row, so the fixture carries one. It is
+// frozen at the read rather than live, which the rendered provenance line dates
+// so a reader is never told a stale figure is current.
+const ageLabel = (startedAt) => {
+  const minutes = Math.round(
+    (Date.parse(READ_AT) - Date.parse(startedAt)) / 60000,
+  )
+  if (!Number.isFinite(minutes) || minutes < 1) return "now"
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.round(minutes / 60)
+  return hours < 24 ? `${hours}h` : `${Math.round(hours / 24)}d`
+}
+
+// A row the page shows as running has to be running. Transcribing one that is
+// not is the failure the live half exists to prevent, so it refuses rather than
+// rendering.
+const absent = rows.filter(
+  (row) => row.state !== "completed" && !live.has(row.name),
+)
+if (absent.length > 0) {
+  console.error(
+    "regen-agent-fixture: no live session for " +
+      absent.map((row) => row.name).join(", ") +
+      ". Re-transcribe the table in this script against a fresh listing rather than editing the generated fixture.",
+  )
+  process.exit(1)
+}
+
+const sessions = rows.map((row) => {
+  const session = live.get(row.name)
+  return {
+    name: row.name,
+    branch: session ? session.branch : null,
+    state: row.state,
+    activity: row.activity,
+    pullRequest: row.pullRequest,
+    age: session ? ageLabel(session.startedAt) : row.age,
+  }
+})
+
+const ageless = sessions.filter((entry) => !entry.age)
+if (ageless.length > 0) {
+  console.error(
+    "regen-agent-fixture: no age for " +
+      ageless.map((entry) => entry.name).join(", ") +
+      ". A completed row carries its age in the table, since the session has exited and no listing reports one.",
+  )
+  process.exit(1)
+}
+
+// What the real surface prints above its own list. The remainder is every
+// session on the machine this page has no room to show, which is a real count.
+const summary = {
+  working: sessions.filter((entry) => entry.state === "working").length,
+  completed: sessions.filter((entry) => entry.state === "completed").length,
+  more: Math.max(0, listing.sessions.length - live.size),
+}
+
+const fixture = {
+  // Read by web/src/components/AgentView.astro. Every field below is either a
+  // live read or a hand transcription, and this header is what says which.
+  generatedBy: "scripts/core/regen-agent-fixture.sh",
+  readAt: READ_AT,
+  source: {
+    command: "canon sessions list --json",
+    live: [
+      "name",
+      "branch",
+      "age",
+      "that every pinned and working row is running",
+      "the remainder count",
+    ],
+    transcribed: {
+      activity:
+        "written by Claude Code into its own status line, which no verb here reports",
+      pullRequest:
+        "read off a task file by hand, since nothing joins a session record to one",
+      state:
+        "a completed session has already exited, so no listing carries the row at all",
+    },
+  },
+  summary,
+  sessions,
+}
+
+await Bun.write(OUT, JSON.stringify(fixture, null, 2) + "\n")
+console.error(
+  `regen-agent-fixture: wrote ${sessions.length} session rows to ${OUT.replace(PROJECT_ROOT + "/", "")}`,
+)
+'

package/src/commands/demo.ts

@@ -4,7 +4,7 @@ import type { Command } from 'commander'
 import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
 import { parseDraft } from '@/demo/beats'
 import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
-import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
+import { convertToGif, convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
 import { DEFAULT_CURSORS } from '@/demo/cursors'
 import { loadCursorTheme } from '@/demo/theme'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
@@ -30,6 +30,7 @@ interface RunOptions {
   readonly cursor?: string
   readonly video: boolean
   readonly still: boolean
+  readonly gif?: boolean
   readonly json?: boolean
 }
 
@@ -82,6 +83,7 @@ export function register(program: Command): void {
     )
     .option('--no-video', 'Skip the recording and write only the still')
     .option('--no-still', 'Skip the still and write only the recording')
+    .option('--gif', 'Also write a gif, for a host that strips video')
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -93,6 +95,9 @@ export function register(program: Command): void {
         'Writes mp4 beside the webm when ffmpeg is on PATH, and skips it',
         `otherwise without failing the run. Install it with: ${INSTALL_CONVERTER}`,
         '',
+        'A gif is opt-in behind --gif, since it is far larger than the webm',
+        'and only a host that strips video needs one. GitHub is that host.',
+        '',
         'Exit codes:',
         '  0  the recording and the still were written',
         '  1  refused, with the reason on stderr',
@@ -306,16 +311,35 @@ async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
     }
   }
 
+  let gifPath: string | undefined
+  let gifReason: string | undefined
+  if (result.videoPath && opts.gif) {
+    const converted = await convertToGif(result.videoPath)
+    if (converted.status === 'converted') {
+      gifPath = converted.gifPath
+      logInfo(display(gifPath))
+    } else if (converted.status === 'skipped') {
+      gifReason = converted.reason
+      logWarn('ffmpeg is not installed, so no gif was written.')
+      logWarn(`Install it with: ${INSTALL_CONVERTER}`)
+    } else {
+      gifReason = converted.reason
+      logWarn(`gif conversion failed: ${converted.reason}`)
+    }
+  }
+
   outro()
 
   emit(opts.json, {
     plan: source,
     video: result.videoPath ?? null,
     mp4: mp4Path ?? null,
+    gif: gifPath ?? null,
     still: result.stillPath ?? null,
     steps: result.steps,
     durationMs: result.durationMs,
     ...(mp4Reason ? { mp4Reason } : {}),
+    ...(gifReason ? { gifReason } : {}),
   })
   return 0
 }

package/src/commands/indexes.ts

@@ -2,6 +2,7 @@ import { stat } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
+import { buildIndexCatalog } from '@/indexes/list'
 import { exitCodeFor, type RegenResult, regenOne } from '@/indexes/regen'
 import { gitEnv } from '@/git-env'
 import { findIndexedAncestor, isIgnored, listIndexes } from '@/indexes/walk'
@@ -14,6 +15,10 @@ interface RegenCommandOptions {
   readonly stage?: boolean
 }
 
+interface ListCommandOptions {
+  readonly json?: boolean
+}
+
 export function register(program: Command): void {
   const indexes = program
     .command('indexes')
@@ -51,6 +56,30 @@ export function register(program: Command): void {
     .action(async (paths: string[], opts: RegenCommandOptions) => {
       process.exitCode = await runRegen(paths, opts)
     })
+
+  indexes
+    .command('list')
+    .description('Flatten every folder index under a path into one catalog')
+    .argument('[path]', 'Folder to walk (default: cwd)')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit a machine-readable catalog on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  no frontmatter errors',
+        '  1  root not a directory, or a folder failed frontmatter validation',
+        '',
+        'Examples:',
+        '  canon indexes list',
+        '  canon indexes list --json docs/',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ListCommandOptions) => {
+      process.exitCode = await runList(path, opts)
+    })
 }
 
 async function runRegen(
@@ -115,6 +144,44 @@ async function runRegen(
   return exitCodeFor(results, { dryRun })
 }
 
+async function runList(
+  path: string | undefined,
+  opts: ListCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  if (!(await isDirectory(root))) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ error: `root not a directory: ${root}` })}\n`,
+      )
+      return 1
+    }
+    process.stderr.write(`Root is not a directory: ${root}\n`)
+    return 1
+  }
+
+  const catalog = await buildIndexCatalog(root)
+
+  for (const message of catalog.errors) {
+    process.stderr.write(`ERROR: ${message}\n`)
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...catalog })}\n`)
+  } else {
+    intro('canon indexes list')
+    logStep('Catalog')
+    for (const entry of catalog.entries) {
+      logInfo(`${entry.path}: ${entry.title} — ${entry.description}`)
+    }
+    outro()
+  }
+
+  return catalog.errors.length > 0 ? 1 : 0
+}
+
 function collectFromPaths(paths: string[], root: string): string[] {
   const dirs: string[] = []
 

package/src/demo/container.ts

@@ -15,6 +15,11 @@ export type ContainerResult =
   | { status: 'skipped'; reason: 'converter-missing' }
   | { status: 'failed'; reason: string }
 
+export type GifResult =
+  | { status: 'converted'; gifPath: string }
+  | { status: 'skipped'; reason: 'converter-missing' }
+  | { status: 'failed'; reason: string }
+
 /**
  * Writes mp4 beside the webm rather than instead of it, since both stated use
  * cases are a `<video>` tag on a page the operator controls, where webm
@@ -61,3 +66,59 @@ export async function convertToMp4(
   }
   return { status: 'converted', mp4Path }
 }
+
+/**
+ * Opt-in rather than written beside every recording, because a gif is an order
+ * of magnitude larger than the webm it derives from and only one destination
+ * needs one: a README on a host that strips `<video>`, which GitHub does. The
+ * mp4 above is unconditional for the opposite reason, being cheap and wanted
+ * wherever the webm already plays.
+ *
+ * A palette is generated from the source and then applied, rather than letting
+ * ffmpeg quantize per frame. A per-frame palette is what makes a screen
+ * recording of flat UI colors band and shimmer, which is precisely the artifact
+ * that would make a page look worse in the README than it does in a browser.
+ *
+ * Dithering is off because this command records applications rather than
+ * photographs. A global palette already covers flat interface colors, so the
+ * dither only writes noise the encoder then has to store: measured at 3.19MB
+ * against 2.70MB on one recording, with the same text region cropped from both
+ * and read as visually identical. Width is the larger lever at 2.38MB for 800
+ * pixels, and it is not taken, since the terminal rows are what the recording
+ * exists to have read. Frame rate is almost no lever at all.
+ *
+ * The missing-binary and failure handling matches `convertToMp4` exactly: the
+ * recording already succeeded by the time this runs, so an optional step never
+ * fails the run.
+ */
+export async function convertToGif(
+  webmPath: string,
+  bin: string = CONVERTER_BIN,
+): Promise<GifResult> {
+  const { dir, name } = parse(webmPath)
+  const gifPath = join(dir, `${name}.gif`)
+
+  const result = await execa(
+    bin,
+    [
+      '-y',
+      '-i',
+      webmPath,
+      '-filter_complex',
+      '[0:v] fps=12,scale=960:-1:flags=lanczos,split [a][b];[a] palettegen [p];[b][p] paletteuse=dither=none',
+      gifPath,
+    ],
+    { reject: false },
+  )
+
+  if (result.failed && result.code === 'ENOENT') {
+    return { status: 'skipped', reason: 'converter-missing' }
+  }
+  if (result.exitCode !== 0) {
+    return {
+      status: 'failed',
+      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
+    }
+  }
+  return { status: 'converted', gifPath }
+}

package/src/demo/drive.ts

@@ -38,6 +38,27 @@ const POINTER_SIZE = 32
  * first target. A corner keeps that first move out of the way of the content.
  */
 const START = { x: 8, y: 8 }
+
+/**
+ * Whether any step will move the pointer. The injected element installs on
+ * `DOMContentLoaded` and paints itself off-screen, so it costs nothing until
+ * something moves it, and seeding `START` is what first makes it visible.
+ *
+ * A plan that only navigates, scrolls and holds has nothing to point at, and
+ * seeding it anyway parked a cursor in the corner for the whole recording. That
+ * reads as a stuck artifact rather than a pointer, which is the same defect as
+ * resting it on a row of text, moved to a corner rather than fixed.
+ *
+ * `scroll` is absent deliberately. It is a targeted verb the compiler groups
+ * with the rest, and it stopped moving the pointer when a scroll step began
+ * leaving it where it was.
+ */
+function movesPointer(plan: DemoPlan): boolean {
+  return plan.steps.some(
+    (step) =>
+      step.kind === 'click' || step.kind === 'fill' || step.kind === 'hover',
+  )
+}
 const SETTLE_MS = 250
 /** Round trips sampled to price one, on the page a step is actually about to move across. */
 const CALIBRATION_STEPS = 8
@@ -100,16 +121,22 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
       // Pointed the opposite way from a test. A recording wants the motion the
       // interface was designed with, where a test wants it suppressed.
       reducedMotion: 'no-preference',
+      // `showActions` is deliberately not passed. Playwright's annotation draws
+      // a dot on the interacted element and a title naming the API call it
+      // made, and this recorder already supersedes both: the injected pointer
+      // is a real cursor where the dot is a marker, and the caption bar carries
+      // the beat's narration where the title carries `Mouse move`. Leaving it
+      // on ran four overlays where two were wanted, and the two redundant ones
+      // were the two a viewer reads as noise. `plan.annotations` survives as a
+      // shape the type still carries and nothing now reads. It is not a record
+      // of what a committed plan configured, because `parsePlan` has always
+      // replaced it with the `ANNOTATIONS` constant rather than reading the
+      // file's own values, so that path never existed to preserve.
       ...(videoDir
         ? {
             recordVideo: {
               dir: videoDir,
               size: plan.viewport,
-              showActions: {
-                duration: plan.annotations.durationMs,
-                position: plan.annotations.position,
-                fontSize: plan.annotations.fontSize,
-              },
             },
           }
         : {}),
@@ -137,7 +164,9 @@ export async function drive(options: DriveOptions): Promise<DriveResult> {
     // step for the same URL and the second load is a visible reload.
     if (plan.steps[0]?.kind !== 'navigate') {
       await page.goto(plan.url)
-      await page.mouse.move(START.x, START.y, { steps: 2 })
+      if (movesPointer(plan)) {
+        await page.mouse.move(START.x, START.y, { steps: 2 })
+      }
     }
 
     for (const step of plan.steps) {
@@ -217,7 +246,9 @@ export async function runStep(
   switch (step.kind) {
     case 'navigate':
       await page.goto(step.target || plan.url)
-      await page.mouse.move(START.x, START.y, { steps: 2 })
+      if (movesPointer(plan)) {
+        await page.mouse.move(START.x, START.y, { steps: 2 })
+      }
       break
     case 'click':
       await moveTo(page, plan, step, pace)
@@ -234,9 +265,36 @@ export async function runStep(
       await moveTo(page, plan, step, pace)
       break
     case 'scroll':
-      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      // Centred rather than `scrollIntoViewIfNeeded`, which scrolls the least
+      // it can and leaves a target taller than the remaining space flush
+      // against the bottom edge. Measured on this repository's own recording at
+      // 225 pixels of dead space above the content and 2 below, where centring
+      // splits it 114 and 113. A recording frames its subject, so the least
+      // scroll that technically reveals it is the wrong amount.
+      await page
+        .locator(step.target)
+        .first()
+        .evaluate((node) =>
+          node.scrollIntoView({
+            block: 'center',
+            inline: 'nearest',
+            // Explicit, because this runs in the page where
+            // `scrollIntoViewIfNeeded` ran through the debugging protocol and
+            // was always instant. An in-page scroll honours the document's own
+            // `scroll-behavior`, so a project setting it to `smooth` gets a
+            // call that returns before the scroll finishes, with only
+            // `SETTLE_MS` behind it. Nothing in this repository sets it, which
+            // is exactly why the recorder cannot catch this on its own pages.
+            behavior: 'instant',
+          }),
+        )
       await page.waitForTimeout(SETTLE_MS)
-      await moveTo(page, plan, step, pace)
+      // The pointer stays where it was. A scroll is not a pointing action, so
+      // gliding the cursor to the target's centre parks it on top of whatever
+      // the scroll just revealed and covers a row of it. A real session scrolls
+      // with a wheel and leaves the cursor alone. On a plan that points at
+      // nothing, `movesPointer` then keeps it off-screen for the whole run
+      // rather than parked in a corner.
       break
     case 'wait':
     case 'hold':

package/src/indexes/list.ts

@@ -0,0 +1,64 @@
+import { dirname, relative, resolve } from 'node:path'
+import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import { collectEntries } from '@/indexes/render'
+import { listIndexes } from '@/indexes/walk'
+
+export interface CatalogEntry {
+  readonly path: string
+  readonly title: string
+  readonly description: string
+}
+
+export interface IndexCatalog {
+  readonly entries: CatalogEntry[]
+  readonly errors: string[]
+}
+
+/**
+ * Flattens every folder index under `root` into one queryable catalog.
+ *
+ * A folder's own frontmatter error lands in `errors` without dropping the
+ * rest of the walk, the same isolation `regenOne` gives one folder.
+ */
+export async function buildIndexCatalog(root: string): Promise<IndexCatalog> {
+  const indexPaths = await listIndexes(root)
+  const entries: CatalogEntry[] = []
+  const errors: string[] = []
+
+  for (const indexPath of indexPaths) {
+    const dir = dirname(indexPath)
+    const frontmatter = await readFrontmatter(indexPath)
+    const title = readField(frontmatter, 'title')
+    const subtitle = readField(frontmatter, 'subtitle')
+
+    if (!title || !subtitle) {
+      errors.push(
+        `missing frontmatter field "title" or "subtitle" in ${indexPath}`,
+      )
+    } else {
+      entries.push({
+        path: relative(root, indexPath),
+        title,
+        description: subtitle,
+      })
+    }
+
+    const collected = await collectEntries(dir)
+    if (!collected.ok) {
+      errors.push(...collected.errors)
+      continue
+    }
+
+    for (const entry of collected.entries) {
+      entries.push({
+        path: relative(root, resolve(dir, entry.name)),
+        title: entry.title,
+        description: entry.description,
+      })
+    }
+  }
+
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  return { entries, errors }
+}

package/src/indexes/render.ts

@@ -64,7 +64,7 @@ async function readIndexHead(
   return { ok: true, head: { raw: frontmatter.raw, title, subtitle } }
 }
 
-async function collectEntries(
+export async function collectEntries(
   dir: string,
 ): Promise<
   { ok: true; entries: IndexEntry[] } | { ok: false; errors: string[] }

package/tooling/web/configs/scripts/screenshot.sh

@@ -11,7 +11,7 @@ fi
 bun run build
 bun run preview >/dev/null 2>&1 &
 PREVIEW_PID=$!
-trap 'kill "$PREVIEW_PID" 2>/dev/null; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+trap 'kill "$PREVIEW_PID" 2>/dev/null || true; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
 
 for _ in $(seq 1 40); do
   if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then