@erclx/canon 4.77.0 → 4.79.0

package/governance/rules/core/025-indexes.md

@@ -6,4 +6,4 @@ description: Check a folder's index before searching its contents
 
 ## Before searching
 
-- Check a folder's `index.md` before grepping its source or reading its files, starting with `.claude/context/` for a domain and `.claude/wireframes/` for a UI surface. It orients faster than a blind search.
+- Check a folder's `index.md` before grepping its source or reading its files, starting with `canon/context/` for a domain and `canon/wireframes/` for a UI surface. It orients faster than a blind search.

package/governance/rules/core/045-memory.md

@@ -7,6 +7,6 @@ description: Keep memory writes scoped to .canon/memory/ and out of context-owne
 ## Writing memory
 
 - Write all memory files to `.canon/memory/`, not `~/.claude/projects/`
-- A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `canon:memory-capture` routes it there and `canon:docs-fold` folds it in. Memory keeps only what no context entry owns. Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
+- A fact about a domain goes to that domain's `canon/context/` entry, not to memory. `canon:memory-capture` routes it there and `canon:docs-fold` folds it in. Memory keeps only what no context entry owns. Report it rather than proceeding silently when either skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
 - Never delete a memory entry. Retire one by moving it to `.canon/tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
 - Follow the memory standard for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Read it with `canon standards memory`. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.

package/package.json

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

package/scripts/core/check-ignore-parity.sh

@@ -19,7 +19,7 @@ SECTION="# Claude"
 # The diagrams divergence is the one that cost something. A target used to track
 # its diagrams and keep the context audit's default coverage of them, and it now
 # ignores them with the rest of its records, so that coverage is gone unless the
-# project names the folder itself. `.claude/context/tooling.md` carries the
+# project names the folder itself. `canon/context/tooling.md` carries the
 # narrative.
 #
 # An exception mechanism is not kept against a future divergence, because an

package/scripts/core/check-seed-independence.sh

@@ -23,7 +23,7 @@ fi
 # stages disagree about what the same condition means.
 seed_roots=$(collect_seed_roots)
 if [ -z "$seed_roots" ]; then
-  echo "No seed root carries .claude/, nothing to check." >&2
+  echo "No seed root carries .claude/ or canon/, nothing to check." >&2
   exit 0
 fi
 
@@ -36,9 +36,12 @@ measured=0
 while IFS= read -r seed_root; do
   while IFS= read -r file; do
     measured=$((measured + 1))
+    # A token followed by `/` is the tracked surface root, a folder the seed
+    # itself installs, rather than the binary. Every other spelling still
+    # reports, which keeps a verb, a plugin skill prefix, and a bare mention in.
     while IFS= read -r hit; do
       cited="$cited  ${file#"$PROJECT_ROOT/"}:$hit"$'\n'
-    done < <(grep -n "$TOOLKIT_TOKEN" "$file" || true)
+    done < <(grep -nE "${TOOLKIT_TOKEN}([^/]|$)" "$file" || true)
   done < <(find "$PROJECT_ROOT/$seed_root" -type f -name '*.md')
 done <<<"$seed_roots"
 

package/scripts/core/install-check.sh

@@ -95,7 +95,7 @@ log_step "Assert scaffold"
 # `@`-reference convention rule is the one snippets-domain file that still
 # installs, since `base` carries `governance/rules/snippets/` as a
 # folder-whole entry the same way it does `core` and `claude`.
-for path in "CLAUDE.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/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" ".canon/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/canon/core/000-constitution.md" ".claude/rules/canon/snippets/600-at-references.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/scripts/core/list-seed-roots.sh

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# Prints every seed root carrying a `.claude/`, one per line and relative to
-# the project root.
+# Prints every seed root carrying a `.claude/` or a `canon/`, one per line and
+# relative to the project root.
 #
 # The discovery rule has one definition, `collect_seed_roots` in
 # `scripts/lib/tooling.sh`, which `check-seed-independence.sh` already reads.
 # This file is the route a caller outside bash takes to that same answer, so a
-# stack seeding `.claude/` later reaches both readers and the two stages
+# stack seeding either root later reaches both readers and the two stages
 # measuring seed content cannot disagree about which roots exist.
 set -e
 set -o pipefail

package/scripts/core/regen-hero.sh

@@ -3,7 +3,7 @@
 # source, writing the .html beside each one.
 #
 # The name says hero because the hero was the only template when it was written
-# and every citation of it across docs/, .claude/context/, and src/ spells that
+# and every citation of it across docs/, canon/context/, and src/ spells that
 # name. Renaming the file is a sweep across roughly twenty surfaces for a
 # cosmetic gain, so the file keeps its name and the loop below covers whatever
 # templates the folder holds.

package/scripts/docs/list.sh

@@ -9,7 +9,7 @@ source "$PROJECT_ROOT/scripts/lib/ui.sh"
 source "$PROJECT_ROOT/scripts/lib/frontmatter.sh"
 
 DOCS_DIR="$PROJECT_ROOT/docs"
-CONTEXT_DIR="$PROJECT_ROOT/.claude/context"
+CONTEXT_DIR="$PROJECT_ROOT/canon/context"
 
 INTERNAL_TOPICS=" ci development sandbox "
 
@@ -97,7 +97,7 @@ collect_context() {
       [ "$name" = "index" ] && continue
       is_internal_topic "$name" && continue
       description=$(read_frontmatter_field "$file" "description")
-      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name.md"
+      printf '%s\t%s\t%s\n' "$name" "$description" "canon/context/$name.md"
     done < <(find "$CONTEXT_DIR" -maxdepth 1 -type f -name "*.md")
 
     # A split domain is named by its folder and described by its generated
@@ -106,7 +106,7 @@ collect_context() {
       name=$(basename "$(dirname "$file")")
       is_internal_topic "$name" && continue
       description=$(read_frontmatter_field "$file" "subtitle")
-      printf '%s\t%s\t%s\n' "$name" "$description" ".claude/context/$name/index.md"
+      printf '%s\t%s\t%s\n' "$name" "$description" "canon/context/$name/index.md"
     done < <(find "$CONTEXT_DIR" -mindepth 2 -maxdepth 2 -type f -name "index.md")
   } | sort
 }

package/scripts/lib/sandbox-git.sh

@@ -95,7 +95,7 @@ ensure_sandbox_anchor_repo() {
   # nine to a pass against something that is not the anchor. Refusing is the safe
   # default and creating is the opt-in, the shape `canon tooling sync --write`
   # already sets. `canon records push` refuses outright for the reason
-  # `.claude/context/development/scratch.md` records, so the two still differ.
+  # `canon/context/development/scratch.md` records, so the two still differ.
   # The sibling SANDBOX_ flags are presence tests, so any non-empty value turns
   # them on. This one allowlists instead, because a presence test would have
   # SANDBOX_ANCHOR_CREATE=false provisioning a repository. Both spellings are

package/scripts/lib/tooling.sh

@@ -23,13 +23,15 @@ list_tooling_stacks() {
   done < <(find "$tooling_dir" -mindepth 1 -maxdepth 1 -type d | sort)
 }
 
-# Seed roots that carry a `.claude/`, emitted relative to `PROJECT_ROOT`. Every
-# stage measuring seed content discovers through this rather than naming a stack,
-# so a stack seeding `.claude/` later arrives covered with no edit to any caller.
+# Seed roots that carry a `.claude/` or a `canon/`, emitted relative to
+# `PROJECT_ROOT`. Every stage measuring seed content discovers through this
+# rather than naming a stack, so a stack seeding either root later arrives
+# covered with no edit to any caller. A stack seeding only tracked surfaces
+# carries `canon/` alone, which a `.claude/` test would drop from both stages.
 collect_seed_roots() {
   local dir
   for dir in "$PROJECT_ROOT"/tooling/*/seeds; do
-    [ -d "$dir/.claude" ] || continue
+    [ -d "$dir/.claude" ] || [ -d "$dir/canon" ] || continue
     printf '%s\n' "${dir#"$PROJECT_ROOT"/}"
   done
 }

package/snippets/claude/figma-steps.md

@@ -1,4 +1,4 @@
-Read the relevant spec from `.claude/DESIGN.md` and any other design files needed. Write step-by-step Figma instructions to produce the component exactly.
+Read the relevant spec from `canon/DESIGN.md` and any other design files needed. Write step-by-step Figma instructions to produce the component exactly.
 
 For each step, specify:
 

package/src/audits/catalog.ts

@@ -490,8 +490,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 `.claude/context/`, `.canon/diagrams/`, and
-    // `.claude/wireframes/` all at once, so without the allowance every such
+    // target adopts `canon/context/`, `.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/autoship/paths.ts

@@ -7,7 +7,7 @@
  * application three times, so the set moved here and the body now calls a verb
  * that reads it. Being machine-parsed makes it permanently exempt from any
  * later design that folds a standard back into the surface citing it, per the
- * machine-parsed clause in `.claude/ARCHITECTURE.md`.
+ * machine-parsed clause in `canon/ARCHITECTURE.md`.
  */
 
 /**

package/src/capture/render.ts

@@ -37,12 +37,12 @@ export interface CaptureOptions {
 export type CaptureResult =
   | {
       status: 'rendered'
-      htmlPath: string
+      source: string
       pngPath: string
       width: number
       height: number
     }
-  | { status: 'failed'; htmlPath: string; reason: string }
+  | { status: 'failed'; source: string; reason: string }
 
 export async function captureSources(
   sourcePath: string,
@@ -74,7 +74,9 @@ async function captureOne(
     deviceScaleFactor: DEVICE_SCALE_FACTOR,
   })
   try {
-    await page.goto(pathToFileURL(source.htmlPath).href)
+    await page.goto(
+      source.kind === 'url' ? source.url : pathToFileURL(source.htmlPath).href,
+    )
     const element = page.locator(selector).first()
     if ((await element.count()) === 0) {
       return failed(source, `no element matched ${selector}`)
@@ -97,7 +99,7 @@ async function captureOne(
     writeStamp(source, png)
     return {
       status: 'rendered',
-      htmlPath: source.htmlPath,
+      source: sourceIdentifier(source),
       pngPath: source.pngPath,
       width: png.readUInt32BE(16),
       height: png.readUInt32BE(20),
@@ -118,8 +120,11 @@ async function captureOne(
  * caller's catch and reports the source as failed, which is correct: a PNG
  * whose stamp never landed is the state the verify stage exists to reject.
  *
- * The source is stored as a bare filename. An absolute path would record the
- * machine that ran the capture into a tracked file and differ per checkout.
+ * A file source is stored as a bare filename. An absolute path would record
+ * the machine that ran the capture into a tracked file and differ per
+ * checkout. A URL source is stored as the URL itself, and its digest hashes
+ * the URL string's UTF-8 bytes rather than any local file, since there is
+ * none to hash.
  *
  * The image digest is taken over the buffer the screenshot returned rather than
  * by reading the file back, so the stamp describes the bytes this run wrote.
@@ -128,15 +133,27 @@ function writeStamp(source: CaptureSource, png: Uint8Array): void {
   writeFileSync(
     stampPath(source.pngPath),
     formatStamp({
-      source: basename(source.htmlPath),
-      sourceSha256: hashSource(readFileSync(source.htmlPath)),
+      source: source.kind === 'url' ? source.url : basename(source.htmlPath),
+      sourceSha256:
+        source.kind === 'url'
+          ? hashSource(Buffer.from(source.url, 'utf8'))
+          : hashSource(readFileSync(source.htmlPath)),
       imageSha256: hashSource(png),
     }),
   )
 }
 
+/**
+ * The identifier a `CaptureResult` reports, kept as the full path for a file
+ * source so `displayPath` in `src/commands/capture.ts` can still show it
+ * relative to the working directory.
+ */
+function sourceIdentifier(source: CaptureSource): string {
+  return source.kind === 'url' ? source.url : source.htmlPath
+}
+
 function failed(source: CaptureSource, reason: string): CaptureResult {
-  return { status: 'failed', htmlPath: source.htmlPath, reason }
+  return { status: 'failed', source: sourceIdentifier(source), reason }
 }
 
 /**

package/src/capture/sources.ts

@@ -1,20 +1,45 @@
 import { readdirSync, statSync } from 'node:fs'
 import { basename, dirname, extname, join } from 'node:path'
 
-export interface CaptureSource {
-  htmlPath: string
-  pngPath: string
+const URL_SOURCE = /^https?:\/\//
+
+/**
+ * The one test for whether a source string names a URL rather than a
+ * filesystem path, shared with `src/commands/capture.ts` so the two never
+ * drift apart on what counts as a URL source.
+ */
+export function isUrlSource(source: string): boolean {
+  return URL_SOURCE.test(source)
 }
 
+export type CaptureSource =
+  | {
+      readonly kind: 'file'
+      readonly htmlPath: string
+      readonly pngPath: string
+    }
+  | { readonly kind: 'url'; readonly url: string; readonly pngPath: string }
+
 /**
  * Pairs each HTML source with the PNG it renders to. A directory expands to
  * every `.html` directly inside it, so adding a capture is a file drop rather
  * than a flag. Omitting `outDir` writes the PNG beside its source.
+ *
+ * A `http(s)://` source has no directory to walk and no basename on disk to
+ * name the PNG from, so `outDir` there is read as the destination file
+ * itself rather than a directory, and the caller is what requires it.
  */
 export function resolveCaptureSources(
   sourcePath: string,
   outDir?: string,
 ): CaptureSource[] {
+  if (isUrlSource(sourcePath)) {
+    if (!outDir) {
+      throw new Error('a URL source needs --out naming the destination PNG')
+    }
+    return [{ kind: 'url', url: sourcePath, pngPath: outDir }]
+  }
+
   const htmlPaths = statSync(sourcePath).isDirectory()
     ? readdirSync(sourcePath)
         .filter((name) => extname(name) === '.html')
@@ -23,6 +48,7 @@ export function resolveCaptureSources(
     : [sourcePath]
 
   return htmlPaths.map((htmlPath) => ({
+    kind: 'file',
     htmlPath,
     pngPath: join(
       outDir ?? dirname(htmlPath),

package/src/claude/cases/authoring.ts

@@ -48,12 +48,12 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   },
   {
     prompt:
-      'Write a context entry for the payments domain, there is no .claude/context page for it yet.',
+      'Write a context entry for the payments domain, there is no canon/context page for it yet.',
     expect: 'draft-context',
   },
   {
     prompt:
-      'Draft a wireframe for the settings panel, nothing under .claude/wireframes covers that surface yet.',
+      'Draft a wireframe for the settings panel, nothing under canon/wireframes covers that surface yet.',
     expect: 'draft-wireframes',
   },
   {

package/src/claude/cases/setup.ts

@@ -72,7 +72,7 @@ export const SETUP_CASES: readonly SkillCase[] = [
   },
   // The performing skill wins a phrase naming its operation over the front
   // door's own routing framing, even though canon-operator's description
-  // quotes a phrase near this one. See .claude/context/cli/audits.md.
+  // quotes a phrase near this one. See canon/context/cli/audits.md.
   {
     prompt:
       "Whatever the right toolkit command is, get this project's rules installed.",

package/src/claude/routing.ts

@@ -82,7 +82,7 @@ export function namedPaths(line: string): string[] {
  * The openable part of a token, which for a shape is the folder above the
  * placeholder.
  *
- * `.claude/context/<domain>.md` names `.claude/context/` and nothing narrower,
+ * `canon/context/<domain>.md` names `canon/context/` and nothing narrower,
  * so dropping the whole token would report the section that carries it as
  * naming no path at all. A token whose placeholder sits in the first segment
  * has no openable prefix and is dropped.

package/src/claude/seeds-list.ts

@@ -19,7 +19,7 @@ export interface SeedListingWithContent {
 /**
  * Reads the same plan `canon claude init` applies. The bash re-globbed the seeds
  * directory with its own hard-coded subdirectory list, which had drifted: it
- * never listed `.claude/context/`, so a seed init installs went unreported.
+ * never listed `canon/context/`, so a seed init installs went unreported.
  *
  * The target is irrelevant to a listing, so it resolves against the source
  * root and only the source-side fields are read.

package/src/claude/seeds.ts

@@ -1,18 +1,21 @@
 import { existsSync } from 'node:fs'
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { copyPreservingMode } from '@/copy'
 import { creationRel, isRecordEntry } from '@/record-root'
 import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 
 const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
+const SURFACE_DIR = 'canon'
 const CLAUDE_MD = 'CLAUDE.md'
 const HOOKS = 'hooks'
 /**
- * Seed subdirectories under `.claude/`. Exported because each one replaced a
- * single file of the same stem in an older layout, which is what
- * `@/sync/layout` pairs a target against to find a superseded artifact.
+ * Seed subdirectories, authored under `.claude/` or, for a tracked surface,
+ * under `canon/`. Exported because each one replaced a single file of the same
+ * stem in an older layout, which is what `@/sync/layout` pairs a target against
+ * to find a superseded artifact.
  */
 export const SUBDIRS: readonly string[] = [
   HOOKS,
@@ -48,10 +51,26 @@ function seedsRoot(root: string): string {
   return join(root, SEEDS_DIR)
 }
 
+function isSurfaceEntry(name: string): boolean {
+  return SURFACE_ENTRIES.includes(name)
+}
+
+/**
+ * Where a surface seed installs, relative to the target.
+ *
+ * Resolved the way a read resolves rather than fixed at `canon/`. A target that
+ * still holds the surface under `.claude/` receives the seed beside the copy it
+ * has, since a fresh `canon/` folder there would win read precedence and hide
+ * every entry that target already wrote.
+ */
+function surfaceRel(target: string, entry: string): string {
+  return relative(target, surfaceDir(target, entry))
+}
+
 /**
  * Lists a single directory level, sorted the way `find -maxdepth 1 -type f |
- * sort` was. Bun.Glob skips dotfiles without `dot`, and every path here sits
- * under `.claude`, so omitting it would match nothing.
+ * sort` was. Bun.Glob skips dotfiles without `dot`, and the `.claude` source
+ * sits under a dotted name, so omitting it would match nothing there.
  */
 function listLevel(dir: string): string[] {
   if (!existsSync(dir)) return []
@@ -61,19 +80,19 @@ function listLevel(dir: string): string[] {
 }
 
 /**
- * Builds the seed list in the order the bash scanned it: the `.claude` root
- * level, then each subdirectory, then the project-level `CLAUDE.md`. Order is
- * load-bearing because it is also the order the timeline prints.
+ * Builds the seed list in the order the timeline prints it: the `.claude` root
+ * level, the `canon` root level, then each subdirectory from whichever source
+ * authors it, then the project-level `CLAUDE.md`.
  */
 export function planSeeds(root: string, target: string): SeedEntry[] {
-  const source = join(seedsRoot(root), CLAUDE_DIR)
-  const destDir = join(target, CLAUDE_DIR)
+  const claudeSource = join(seedsRoot(root), CLAUDE_DIR)
+  const surfaceSource = join(seedsRoot(root), SURFACE_DIR)
   const seeds: Seed[] = []
 
-  for (const name of listLevel(source)) {
+  for (const name of listLevel(claudeSource)) {
     seeds.push({
-      src: join(source, name),
-      dest: join(destDir, name),
+      src: join(claudeSource, name),
+      dest: join(target, CLAUDE_DIR, name),
       scanLabel: name,
       applyLabel: join(CLAUDE_DIR, name),
       scope: 'claude',
@@ -81,23 +100,38 @@ export function planSeeds(root: string, target: string): SeedEntry[] {
     })
   }
 
+  for (const name of listLevel(surfaceSource)) {
+    const rel = surfaceRel(target, name)
+    seeds.push({
+      src: join(surfaceSource, name),
+      dest: join(target, rel),
+      scanLabel: name,
+      applyLabel: rel,
+      scope: 'claude',
+      executable: false,
+    })
+  }
+
   for (const subdir of SUBDIRS) {
-    // The seed tree authors every subdirectory under `.claude/`, and three of
-    // them are record folders that install under the record root instead. A
-    // target that has not migrated resolves back to `.claude/`, so the same seed
-    // lands beside the records already there rather than opening a second root.
-    // Scaffolding one under `.claude/` now would also land it outside the single
-    // `.canon/` ignore entry a target receives, which tracks the memory pen.
-    const installRel = isRecordEntry(subdir)
-      ? creationRel(target, subdir)
-      : join(CLAUDE_DIR, subdir)
-
-    for (const name of listLevel(join(source, subdir))) {
-      const rel = `${subdir}/${name}`
+    const surface = isSurfaceEntry(subdir)
+    const source = join(surface ? surfaceSource : claudeSource, subdir)
+
+    // Three of the `.claude/` subdirectories are record folders that install
+    // under the record root instead. A target that has not migrated resolves
+    // back to `.claude/`, so the same seed lands beside the records already
+    // there rather than opening a second root, and never outside the single
+    // `.canon/` ignore entry a target receives.
+    const installRel = surface
+      ? surfaceRel(target, subdir)
+      : isRecordEntry(subdir)
+        ? creationRel(target, subdir)
+        : join(CLAUDE_DIR, subdir)
+
+    for (const name of listLevel(source)) {
       seeds.push({
-        src: join(source, subdir, name),
+        src: join(source, name),
         dest: join(target, installRel, name),
-        scanLabel: rel,
+        scanLabel: `${subdir}/${name}`,
         applyLabel: join(installRel, name),
         scope: 'claude',
         executable: subdir === HOOKS,

package/src/claude/skills-reach.ts

@@ -17,7 +17,7 @@ import { SURFACE_ROOTS } from '@/surface-root'
  * `docs/agents/` is the exception, being the CLI contract pages that exist
  * here alone.
  *
- * `.claude/context/` carries both surface-root spellings, since this list
+ * The context folder carries both surface-root spellings, since this list
  * decides whether a shipped body names this repository's own tree and a body
  * naming either root is doing that regardless of which root a given checkout
  * carries.
@@ -51,7 +51,7 @@ const TOKEN = /`([^`\s]+)`/g
  * A path a reader could open, which is the only kind worth measuring.
  *
  * Requires an extension and a separator, and admits no `<`, `$`, or `*`. A
- * body writes `.claude/context/<domain>.md` to name a shape rather than a
+ * body writes `canon/context/<domain>.md` to name a shape rather than a
  * file, and `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` to resolve
  * against the plugin root, which is self-contained by construction.
  */
@@ -88,7 +88,7 @@ export function isQualified(line: string): boolean {
  * The roots that belong to the toolkit rather than to the reader, read
  * against the corpus being measured.
  *
- * A target's `.claude/context/` is the reader's own tree. A seed put the
+ * A target's `canon/context/` is the reader's own tree. A seed put the
  * entries there and the project owns them afterward, so a body under
  * `.claude/skills/` citing one names a file its reader holds. Measuring it
  * would report a correct citation on every run, which is exactly why `src/`

package/src/commands/capture.ts

@@ -6,6 +6,7 @@ import {
   isBrowserMissing,
   isEngineMissing,
 } from '@/browser/engine'
+import { isUrlSource } from '@/capture/sources'
 import {
   frameError,
   intro,
@@ -42,8 +43,15 @@ export function register(program: Command): void {
   program
     .command('capture')
     .description('Render HTML capture sources to PNG')
-    .argument('[source]', 'HTML file or a directory of them', DEFAULT_SOURCE)
-    .option('-o, --out <dir>', 'Output directory, defaults beside the source')
+    .argument(
+      '[source]',
+      'HTML file, a directory of them, or an http(s):// URL',
+      DEFAULT_SOURCE,
+    )
+    .option(
+      '-o, --out <path>',
+      'Output directory for a file source, or the destination PNG for a URL source; defaults beside the source',
+    )
     .option('-s, --selector <selector>', 'Element to capture')
     .action(
       async (
@@ -66,8 +74,9 @@ export function register(program: Command): void {
         }
         const selector = opts.selector
 
-        const sourcePath = resolve(process.cwd(), source)
-        if (!existsSync(sourcePath)) {
+        const isUrl = isUrlSource(source)
+        const sourcePath = isUrl ? source : resolve(process.cwd(), source)
+        if (!isUrl && !existsSync(sourcePath)) {
           frameError(`${source} not found`)
           process.exitCode = 1
           return
@@ -100,7 +109,7 @@ export function register(program: Command): void {
               `${displayPath(result.pngPath)} ${result.width}x${result.height}`,
             )
           } else {
-            logError(`${displayPath(result.htmlPath)}: ${result.reason}`)
+            logError(`${displayPath(result.source)}: ${result.reason}`)
           }
         }
         outro()
@@ -141,9 +150,11 @@ function reportInFrame(error: unknown): void {
 /**
  * Keeps a path clickable in the operator's terminal. A source outside the
  * project reports absolute, since a relative path to it is a run of `..`
- * segments no editor resolves.
+ * segments no editor resolves. A URL is not a filesystem path at all, so it
+ * reports as given.
  */
 function displayPath(path: string): string {
+  if (isUrlSource(path)) return path
   const fromCwd = relative(process.cwd(), path)
   return fromCwd.startsWith('..') ? path : fromCwd
 }

package/src/commands/claude.ts

@@ -435,7 +435,7 @@ export function register(program: Command): void {
         '  carrying that corpus alone. A cited path counts when it sits under',
         '  an authoring root no install channel delivers and the project',
         '  holds it. A path under src/, scripts/, or bare docs/ names the',
-        "  reader's own tree and is not measured, and .claude/context/ joins",
+        "  reader's own tree and is not measured, and canon/context/ joins",
         "  them when the corpus read is a project's own.",
         '',
         'Exit codes:',