@erclx/canon 5.29.0 → 5.31.0

package/docs/agents/upstream.md

@@ -0,0 +1,70 @@
+---
+title: Upstream
+description: The fetch, catalog, and advance verbs that read Claude Code releases against the toolkit, the cursor record, and each refusal reason
+---
+
+# Upstream
+
+`canon upstream` reads the Claude Code release feed from a stored cursor and lists canon's own mechanisms beside it, so a triage can match a release line to something canon does. The verbs ship in the published CLI as `canon gate` and `canon sandbox` do, and only this repository has the skill that drives them. A target has no use for them.
+
+Run them as `bun src/cli.ts upstream ...` from this repository's root. The global `canon` resolves to the installed package, which lacks the verbs until a release ships them.
+
+## Verbs
+
+| Verb                                | Behavior                                                                     |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| `fetch [--since <version>]`         | List the release lines since the cursor, with the mechanical noise dropped   |
+| `catalog`                           | List the skills, verbs, hooks, and gate stages the tree holds, one line each |
+| `advance <version> --intake <slug>` | Move the cursor to a version, and store the current `llms.txt` beside it     |
+
+Every verb takes `--root <path>` for the repository to read and `--json` for a record on stdout. `fetch` and `catalog` write nothing. `advance` is the only writer, and the digest skill runs it after the findings are filed, so a run that dies midway reads the same range next time.
+
+## fetch
+
+```bash
+bun src/cli.ts upstream fetch --json
+bun src/cli.ts upstream fetch --since 2.1.256 --json
+```
+
+The range runs from the cursor, or from `--since` when given, to the newest release. The walk stops at the first release whose version is not newer than the cursor, so a cursor naming a version the feed never carried still bounds the range, and a range crossing a page boundary is read whole.
+
+A line survives when it opens with `Added`, `Changed`, `Removed`, `Improved`, or `Deprecated` and carries none of the dropped surfaces: `[VSCode]`, `[Claude Tag]`, `[Code Review]`, `Windows:`, `Self-hosted`, the apps gateway, managed settings, OpenTelemetry, Bedrock, Vertex, and screen reader. A nested bullet and a `*` bullet are read as well as a `-` one.
+
+Without `--json`, stdout carries one `version<TAB>text` row per line. With it, stdout carries one record:
+
+| Field      | Holds                                                                      |
+| ---------- | -------------------------------------------------------------------------- |
+| `from`     | The cursor version the range starts after                                  |
+| `to`       | The newest release version, or `from` when nothing is newer                |
+| `releases` | How many releases the range spans                                          |
+| `lines`    | Each kept line as `version`, `date`, `text`, and `identifiers`             |
+| `llms`     | `added` and `removed` lines of `llms.txt` against the stored copy, or null |
+
+An identifier is a backticked name on a `Changed`, `Removed`, or `Deprecated` line that holds a dash, a slash, a dot, or a capital. It carries up to three tracked files naming it, and one with no hit is left out. `llms` is null when the page could not be fetched, and every line reads as added until `advance` has stored a first copy.
+
+The request sends `GH_TOKEN` or `GITHUB_TOKEN` when either is set. Unauthenticated, GitHub allows 60 requests an hour, and a range takes about three.
+
+## catalog
+
+Prints a heading per section and a line per entry. With `--json` it prints one record whose fields are `skills`, `internalSkills`, `verbs`, `hooks`, `gate`, and `gaps`, each entry as `name` and `text`. A skill folder with no `SKILL.md` or no description appears in `gaps` rather than dropping out. A hook's text is the first comment line after its shebang.
+
+## advance
+
+Writes `cursor.json` and the fetched `llms.txt` under the upstream record folder at the main worktree root, each through a temp file and a rename. `--no-llms` keeps the stored `llms.txt` and fetches nothing. The record is `version`, `intake`, `advanced`, and `llms`, which reads `stored` when a fresh copy was written and `kept` when the stored one stayed, whether by `--no-llms` or because the fetch failed.
+
+The cursor file holds `version`, `date`, and `intake`. The folder is a backed record folder, so `canon records push` carries it.
+
+## Refusals
+
+A refusal exits 1, prints the reason on stderr, and with `--json` adds `reason` and `message` to stdout. Branch on `reason`.
+
+| Reason              | Verb      | Meaning                                                             |
+| ------------------- | --------- | ------------------------------------------------------------------- |
+| `no-cursor`         | `fetch`   | No cursor is stored and no `--since` was given. Pass the flag.      |
+| `bad-since`         | `fetch`   | `--since` is not a dotted version                                   |
+| `cursor-missing`    | `fetch`   | Every release the feed returned is newer than the cursor            |
+| `rate-limited`      | `fetch`   | GitHub refused the request. Set `GH_TOKEN` or `GITHUB_TOKEN`.       |
+| `network`           | `fetch`   | The feed could not be reached                                       |
+| `http`              | `fetch`   | GitHub answered with an error status                                |
+| `invalid-version`   | `advance` | The version is not a dotted number                                  |
+| `older-than-cursor` | `advance` | The version is older than the stored cursor, which never moves back |

package/docs/workflow/skill-map-on-request.md

@@ -30,10 +30,10 @@ These two groups hold the skills no single moment in a project's life calls for,
 | 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:markdown-craft`      | Before a substantial markdown edit, for the format and structure rules and the audit that follows                                                                      |
 | `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                                                                                                       |
 

package/governance/renames.toml

@@ -18,10 +18,7 @@
 # standard is a rename too: the generated rule keeps every glob and bullet, so
 # the pair is one-to-one identity under the standard's name.
 [renamed]
-"005-behavior" = "565-behavior"
 "015-output" = "566-output"
-"070-planning" = "567-planning"
-"025-indexes" = "601-indexes"
 "035-tasks" = "602-tasks"
 "045-memory" = "603-memory"
 "055-scratch" = "604-scratch"
@@ -41,7 +38,6 @@
 "561-teach" = "661-teach"
 "562-session" = "662-session"
 "563-ready" = "663-ready"
-"500-prose" = "800-prose"
 "501-markdown" = "801-markdown"
 "580-readme" = "880-readme"
 "591-standard-authoring" = "891-standard-authoring"

package/governance/rules/standards/plan.md

@@ -13,6 +13,7 @@ paths:
 - Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
 - Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
 - Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`.
+- Fetch the source a decision rests on and quote the passage under `**Sources:**`, or mark the entry `unverified`. Never cite an outside source from recall.
 - Move a shipped plan to `.canon/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
 - Follow the plan lifecycle standard for when a plan is written, how it is amended, and its move to the archive. Read it with `canon standards plan-lifecycle`.

package/governance/rules/writing/markdown.md

@@ -0,0 +1,23 @@
+---
+description: Route markdown edits to the markdown-craft skill for format and structure, the write-human skill for voice, and the audit after the edit
+paths:
+  - '**/*.md'
+---
+
+# Markdown standards
+
+## Format
+
+- Never write an em dash or a semicolon. `canon markdown audit` reads the full ban list from the package.
+- Load the `canon:markdown-craft` skill before a substantial markdown edit for headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, American spelling, and frontmatter wording. Report it rather than proceeding silently when the skill does not resolve.
+- 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
+
+- Load the `canon:write-human` skill for voice, rhythm, sentence construction, and information density. Load it before drafting a passage, not after revising one.
+- Report it rather than proceeding silently when the skill does not resolve.
+- Do not work these rules from memory.
+
+## Figures
+
+- 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.29.0",
+  "version": "5.31.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/install-check.sh

@@ -103,7 +103,7 @@ log_step "Assert scaffold"
 # 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" \
   ".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
+  ".claude/rules/canon/claude/566-output.md" ".claude/rules/canon/canon/604-scratch.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then
     log_error "Missing after canon init: $path"
   fi

package/src/canvas/client/main.tsx

@@ -51,6 +51,15 @@ chrome.rel = 'stylesheet'
 chrome.href = '/api/chrome.css'
 document.head.prepend(chrome)
 
+/*
+ * The page declares an empty icon so the browser never asks for /favicon.ico,
+ * since the bundler cannot resolve a route the server answers, and this points
+ * it at the brand icon once the shell loads.
+ */
+document
+  .querySelector('link[rel="icon"]')
+  ?.setAttribute('href', '/api/icon.svg')
+
 const events = new EventSource('/api/events')
 events.addEventListener('message', (message) => {
   void applyChange(JSON.parse(message.data) as ChangeEvent)

package/src/canvas/server.ts

@@ -34,6 +34,7 @@ import {
   tokenGroups,
 } from '@/canvas/tokens'
 import { buildDesignCss } from '@/design/css'
+import { brandFavicon } from '@/design/brand-favicon'
 import {
   bindFirstFree,
   PORT_ATTEMPTS,
@@ -713,6 +714,12 @@ export function startCanvas(
                 },
               }),
           ),
+          '/api/icon.svg': guarded(
+            () =>
+              new Response(brandFavicon(), {
+                headers: { 'content-type': 'image/svg+xml' },
+              }),
+          ),
           '/api/events': guarded(() => changes.open()),
         },
         fetch: guarded((request) => {

package/src/claude/cases/authoring.ts

@@ -65,6 +65,11 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
     prompt: 'This passage reads flat and robotic, give it some real cadence.',
     expect: 'write-human',
   },
+  {
+    prompt:
+      'Which characters does the markdown standard ban, and how should I shape the headings in this doc?',
+    expect: 'markdown-craft',
+  },
   {
     prompt:
       'Pull the captions off this YouTube link and save them with metadata.',

package/src/claude/cases/misc.ts

@@ -108,10 +108,6 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',
   },
-  {
-    prompt: 'Is there a page anywhere in this repo that covers retries?',
-    expect: 'index-lookup',
-  },
   {
     prompt: 'Connect this repo to Cloudflare Pages and set up the deploy.',
     expect: 'deploy-app',

package/src/claude/skills-reach.ts

@@ -51,7 +51,7 @@ const TOKEN = /`([^`\s]+)`/g
  *
  * Requires an extension and a separator, and admits no `<`, `$`, or `*`. A
  * body writes `canon/context/<domain>.md` to name a shape rather than a
- * file, and `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` to resolve
+ * file, and `${CLAUDE_SKILL_DIR}/../../standards/<name>.md` to resolve
  * against the plugin root, which is self-contained by construction.
  */
 const CONCRETE = /^[.A-Za-z0-9_][A-Za-z0-9._/-]*\.[a-z]{1,4}$/

package/src/cli/help.ts

@@ -60,6 +60,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['hooks [cmd]', 'Run the steps a git hook drives (post-merge)'],
       ['autoship [cmd]', 'Decide whether a changed set needs review'],
       ['pr [cmd]', 'Read a pull request (key-changes, head, checks)'],
+      ['upstream [cmd]', 'Read Claude Code releases (fetch, catalog, advance)'],
       ['feedback', 'Write toolkit feedback from stdin'],
     ],
   },
@@ -132,6 +133,7 @@ const EXAMPLES = [
   'canon audits run --json',
   'canon gate run --all --no-write',
   'canon upgrade --json',
+  'canon upstream fetch --since 2.1.256 --json',
 ]
 
 // The frame follows stdout's TTY state rather than `palette`, whose blank

package/src/cli.ts

@@ -41,6 +41,7 @@ import { register as autoship } from '@/commands/autoship'
 import { register as pr } from '@/commands/pr'
 import { register as repo } from '@/commands/repo'
 import { register as census } from '@/commands/census'
+import { register as upstream } from '@/commands/upstream'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
@@ -102,6 +103,7 @@ autoship(program)
 pr(program)
 repo(program)
 census(program)
+upstream(program)
 audits(program)
 gate(program)
 upgrade(program)

package/src/commands/claude.ts

@@ -296,7 +296,7 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Reports rather than gates. Whether a bullet belongs in a rule is the',
-        'judgment 592-claude-md states, and naming a path is evidence for it',
+        'judgment canon/context/context-model/overview.md states, and naming a path is evidence for it',
         'rather than the answer.',
         '',
         'Examples:',

package/src/commands/gov.ts

@@ -239,8 +239,8 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Measures the rule in .claude/rules/canon/claude/567-planning.md that asks for',
-        'the test before the code. It reports and never gates, because pairing',
+        'Measures the test-first order the test-first skill and auto-ship hold: the',
+        'test before the code. It reports and never gates, because pairing',
         'a test to an implementation is a judgment.',
         '',
         'Coverage:',

package/src/commands/records.ts

@@ -57,6 +57,7 @@ import {
   plural,
 } from '@/cli/ui'
 import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { readLivePlans, stackFindings } from '@/tasks/stack'
 
 /** Returned when a record carries a finding, which is the gating result. */
 const EXIT_FINDINGS = 2
@@ -911,7 +912,24 @@ async function runValidate(
 
   const root = opts.root ?? (await defaultRoot(kind))
 
-  return report(await validateRecords(root, kind), emitJson, root)
+  return report(await validateWithStacks(root, kind), emitJson, root)
+}
+
+/**
+ * Appends the one plans finding that reads across files. It sits in the command
+ * layer because `src/records/` sits below `src/tasks/`, and `migrate` iterates
+ * `validateRecords` alone, so it never meets a finding with no safe repair.
+ */
+async function validateWithStacks(
+  root: string,
+  kind: RecordKind,
+): Promise<ValidateOutcome> {
+  const outcome = await validateRecords(root, kind)
+  if (!outcome.ok || kind !== 'plans') return outcome
+
+  const stacked = stackFindings(await readLivePlans(root))
+
+  return { ...outcome, findings: [...outcome.findings, ...stacked] }
 }
 
 function report(

package/src/commands/upstream.ts

@@ -0,0 +1,295 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
+import { currentWorktreeRoot, mainWorktreeRoot } from '@/git/worktree'
+import { buildCatalog, renderCatalog } from '@/upstream/catalog'
+import {
+  advanceCursor,
+  llmsDifference,
+  readCursor,
+  readLastLlms,
+} from '@/upstream/cursor'
+import { buildDigest } from '@/upstream/digest'
+import {
+  githubPageFetcher,
+  grepHint,
+  type FetchFailure,
+} from '@/upstream/releases'
+
+const LLMS_URL = 'https://code.claude.com/docs/llms.txt'
+const VERSION = /^\d+(\.\d+)*$/
+
+interface RootOption {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+interface FetchOptions extends RootOption {
+  readonly since?: string
+}
+
+interface AdvanceOptions extends RootOption {
+  readonly intake: string
+  readonly llms: boolean
+}
+
+type Refusal =
+  | 'no-cursor'
+  | 'bad-since'
+  | 'cursor-missing'
+  | FetchFailure
+  | 'older-than-cursor'
+  | 'invalid-version'
+
+const REFUSALS: Record<Refusal, string> = {
+  'no-cursor':
+    'No cursor is stored, so there is no range to read. Pass --since <version> with the last version a digest covered.',
+  'bad-since': 'The --since value is not a dotted version such as 2.1.256.',
+  'cursor-missing':
+    'The releases feed ran out before reaching a release at or below the cursor, so the range cannot be bounded. Pass --since with a more recent version.',
+  'rate-limited':
+    'GitHub refused the request. Set GH_TOKEN or GITHUB_TOKEN to lift the hourly limit.',
+  network: 'The releases feed could not be reached.',
+  http: 'GitHub answered with an error for the releases feed.',
+  'older-than-cursor':
+    'The version is older than the stored cursor, and the cursor never moves back.',
+  'invalid-version': 'The version is not a dotted number such as 2.1.289.',
+}
+
+export function register(program: Command): void {
+  const upstream = program
+    .command('upstream')
+    .description(
+      'Read Claude Code releases against the toolkit (fetch, catalog, advance)',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Ships in the published CLI as `canon gate` and `canon sandbox` do, but',
+        'only the toolkit repository has the skill that drives it, so a target',
+        'has no use for these verbs.',
+        '',
+      ].join('\n'),
+    )
+
+  upstream
+    .command('fetch')
+    .description(
+      'List the release lines since the cursor, with the mechanical noise dropped',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--since <version>', 'Read from this version instead of the cursor')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes nothing. The cursor moves only through `upstream advance`, so a',
+        'run that dies midway reads the same range next time.',
+        '',
+        'Exit codes:',
+        '  0  the range was read, possibly empty',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon upstream fetch --json',
+        '  canon upstream fetch --since 2.1.256 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: FetchOptions) => {
+      process.exitCode = await runFetch(opts)
+    })
+
+  upstream
+    .command('catalog')
+    .description("List the toolkit's own mechanisms, one line each")
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Emit the sections as a JSON record instead of text')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes nothing. Skills, verbs, hooks, and gate stages are read from the',
+        'tree, so the list cannot drift from it. A row that exists but cannot be',
+        'described is named under Gaps.',
+        '',
+        'Examples:',
+        '  canon upstream catalog',
+        '  canon upstream catalog --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOption) => {
+      process.exitCode = await runCatalog(opts)
+    })
+
+  upstream
+    .command('advance')
+    .description('Move the cursor to a version once its digest is filed')
+    .helpOption('-h, --help', 'Show this help message')
+    .argument('<version>', 'Last version the digest covered')
+    .requiredOption('--intake <slug>', 'Intake folder the digest was filed in')
+    .option('--no-llms', 'Keep the stored llms.txt rather than fetching it')
+    .option('--root <path>', 'Repository to write, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Writes the cursor and the current llms.txt under the upstream record',
+        'folder through a temp file and a rename. It refuses a version older than',
+        'the stored cursor.',
+        '',
+        'Exit codes:',
+        '  0  the cursor moved',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon upstream advance 2.1.289 --intake claude-code-2-1-257-to-2-1-289',
+        '',
+      ].join('\n'),
+    )
+    .action(async (version: string, opts: AdvanceOptions) => {
+      process.exitCode = await runAdvance(version, opts)
+    })
+}
+
+function refuse(
+  reason: Refusal,
+  extra: Record<string, unknown>,
+  emitJson: boolean,
+): number {
+  logStep('Refused')
+  logWarn(REFUSALS[reason])
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ...extra, reason, message: REFUSALS[reason] })}\n`,
+    )
+  }
+
+  return 1
+}
+
+async function fetchLlms(): Promise<string | null> {
+  try {
+    const response = await fetch(LLMS_URL)
+
+    return response.ok ? await response.text() : null
+  } catch {
+    return null
+  }
+}
+
+async function runFetch(opts: FetchOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const cursorRoot = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+  const readRoot = opts.root ? resolve(opts.root) : await currentWorktreeRoot()
+
+  intro('canon upstream fetch')
+
+  if (opts.since !== undefined && !VERSION.test(opts.since)) {
+    return refuse('bad-since', { since: opts.since }, emitJson)
+  }
+  const cursor = opts.since ?? readCursor(cursorRoot)?.version
+  if (!cursor) return refuse('no-cursor', {}, emitJson)
+
+  const digest = await buildDigest(cursor, githubPageFetcher(), (name) =>
+    grepHint(readRoot, name),
+  )
+  if (digest.kind === 'failed') {
+    return refuse(digest.reason, {}, emitJson)
+  }
+  if (digest.kind === 'cursor-missing') {
+    return refuse('cursor-missing', { cursor: digest.cursor }, emitJson)
+  }
+
+  const llms = await fetchLlms()
+  const difference =
+    llms === null ? null : llmsDifference(readLastLlms(cursorRoot), llms)
+
+  logStep('Range')
+  logInfo(
+    `${digest.from} to ${digest.to}, ${plural(digest.releases, 'release')}, ${plural(digest.lines.length, 'line')} kept`,
+  )
+  if (difference === null) logWarn('llms.txt could not be fetched')
+  outro()
+
+  if (!emitJson) {
+    for (const line of digest.lines) {
+      process.stdout.write(`${line.version}\t${line.text}\n`)
+    }
+  } else {
+    process.stdout.write(
+      `${JSON.stringify({
+        from: digest.from,
+        to: digest.to,
+        releases: digest.releases,
+        lines: digest.lines,
+        llms: difference,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+async function runCatalog(opts: RootOption): Promise<number> {
+  const root = opts.root ? resolve(opts.root) : await currentWorktreeRoot()
+  const catalog = buildCatalog(root)
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(catalog)}\n`)
+  } else {
+    process.stdout.write(`${renderCatalog(catalog)}\n`)
+  }
+
+  return 0
+}
+
+async function runAdvance(
+  version: string,
+  opts: AdvanceOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ? resolve(opts.root) : await mainWorktreeRoot()
+
+  intro('canon upstream advance')
+
+  const llms = opts.llms ? await fetchLlms() : null
+  const outcome = await advanceCursor(root, {
+    version,
+    intake: opts.intake,
+    today: new Date().toISOString().slice(0, 10),
+    llms,
+  })
+  if (outcome.kind === 'refused') {
+    return refuse(outcome.reason, { version }, emitJson)
+  }
+
+  logStep('Cursor')
+  logInfo(`Moved to ${version}, filed as ${opts.intake}`)
+  if (opts.llms && llms === null) {
+    logWarn('llms.txt could not be fetched, so the stored copy is unchanged')
+  }
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        version,
+        intake: opts.intake,
+        advanced: true,
+        llms: llms === null ? 'kept' : 'stored',
+      })}\n`,
+    )
+  }
+
+  return 0
+}

package/src/context/audit.ts

@@ -166,7 +166,7 @@ const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/
  * entry types while a rule about what an entry may say does not.
  *
  * What gates here is a rule only this standard states. Bullet weight does not,
- * since `standards/markdown.md` owns that checkpoint across document types and
+ * since `claude/skills/markdown-craft/references/markdown.md` owns that checkpoint across document types and
  * its remedy sends the overflow to prose, which any entry type can act on.
  * `standards/context.md` specializes that remedy for an entry carrying
  * decisions, and specializing a rule narrows the advice rather than the measure.

package/src/design/brand-favicon.ts

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { FAVICON_COLORS, renderFavicon } from '@/design/favicon'
+import { PROJECT_ROOT } from '@/roots/project'
+
+const BRAND_MARK = 'assets/brand/mark.svg'
+
+/**
+ * The brand icon, built from the mark and the favicon's own pair, the same two
+ * inputs `web/public/favicon.svg` is generated from. Every surface that shows
+ * the icon reads it here rather than keeping a copy that drifts from the mark.
+ * It sits apart from `favicon.ts` because the card build imports that module
+ * through an `@` alias pointed at `web/src`, so it must import nothing.
+ */
+export function brandFavicon(): string {
+  const mark = readFileSync(join(PROJECT_ROOT, BRAND_MARK), 'utf8')
+  return renderFavicon(mark, FAVICON_COLORS)
+}

package/src/gate/stages.ts

@@ -110,7 +110,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^governance/rules/',
   '^\\.claude/hooks/',
   '^tooling/claude/seeds/\\.claude/hooks/',
-  '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
 ]