@erclx/canon 4.78.0 → 4.79.0

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/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/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:',

package/src/commands/context.ts

@@ -455,13 +455,13 @@ function reportReferenceForm(
   const scoped = folders.filter(matchesSiblings)
   if (scoped.length === 0) {
     logInfo(
-      `Out of scope. A bare name is matched against the siblings of a domain split into a folder, and no audited folder under .claude/${PROVENANCE_FOLDER}/ is one.`,
+      `Out of scope. A bare name is matched against the siblings of a domain split into a folder, and no audited folder under canon/${PROVENANCE_FOLDER}/ is one.`,
     )
     return
   }
 
   logInfo(
-    `Covers ${plural(scoped.length, 'split folder')} under .claude/${PROVENANCE_FOLDER}/, whose standard asks a reference to spell its path.`,
+    `Covers ${plural(scoped.length, 'split folder')} under canon/${PROVENANCE_FOLDER}/, whose standard asks a reference to spell its path.`,
   )
   logInfo(
     'The flat folder is out of reach, since a domain filename there is shared by seeds and other trees.',
@@ -513,13 +513,13 @@ function reportSections(
   const governed = folders.filter(governsContent)
   if (governed.length === 0) {
     logInfo(
-      `Out of scope. The list is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+      `Out of scope. The list is stated in the standard governing canon/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
     )
     return
   }
 
   logInfo(
-    `Covers .claude/${PROVENANCE_FOLDER}/ alone, whose standard requires ${REQUIRED_SECTIONS.join(' and ')}.`,
+    `Covers canon/${PROVENANCE_FOLDER}/ alone, whose standard requires ${REQUIRED_SECTIONS.join(' and ')}.`,
   )
   logInfo(
     'A heading at any level counts. Each entry answers for itself, except in a domain split across a folder, where a sibling answers for the rest.',
@@ -635,13 +635,13 @@ function reportProvenance(
   const governed = folders.filter(governsContent)
   if (governed.length === 0) {
     logInfo(
-      `Out of scope. The rule is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+      `Out of scope. The rule is stated in the standard governing canon/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
     )
     return
   }
 
   logInfo(
-    `Covers .claude/${PROVENANCE_FOLDER}/ alone, whose standard carries the rule. The sibling standards do not restate it.`,
+    `Covers canon/${PROVENANCE_FOLDER}/ alone, whose standard carries the rule. The sibling standards do not restate it.`,
   )
   logInfo(
     'Fenced blocks are excluded, and so is a date whose clause stamps a measurement. A marker is a judgment, never a defect.',
@@ -697,7 +697,7 @@ function reportNarration(
   const governed = folders.filter(governsContent)
   if (governed.length === 0) {
     logInfo(
-      `Out of scope. The rule is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+      `Out of scope. The rule is stated in the standard governing canon/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
     )
     return
   }
@@ -710,7 +710,7 @@ function reportNarration(
   }
 
   logInfo(
-    `Covers .claude/${PROVENANCE_FOLDER}/ alone, reading ${plural(narration.pronouns.length, 'pronoun')} and ${plural(narration.verbs.length, 'verb')} from ${narration.source}.`,
+    `Covers canon/${PROVENANCE_FOLDER}/ alone, reading ${plural(narration.pronouns.length, 'pronoun')} and ${plural(narration.verbs.length, 'verb')} from ${narration.source}.`,
   )
   logInfo(
     'A rejected alternative is a legitimate hit, since the standard keeps what was tried and why it lost.',

package/src/commands/design.ts

@@ -28,7 +28,7 @@ export function register(program: Command): void {
   design
     .command('regen')
     .description(
-      'Rewrite .claude/DESIGN.md and the base stylesheet from src/design/tokens.ts',
+      'Rewrite canon/DESIGN.md and the base stylesheet from src/design/tokens.ts',
     )
     .addHelpText(
       'after',

package/src/commands/gov.ts

@@ -419,7 +419,7 @@ export function register(program: Command): void {
         '',
         'Not read, each a shape the corpus writes and none of them a citation:',
         '  a placeholder or glob segment, which describes a shape rather than',
-        '  naming a file, such as .claude/context/<domain>.md or app/**/route.ts',
+        '  naming a file, such as canon/context/<domain>.md or app/**/route.ts',
         '  a bare filename naming a convention, such as route.ts or manifest.toml',
         '  a span carrying no file extension, which is a folder or a module',
         '  specifier, such as src/pages/ , next/font , or claude/standards',

package/src/commands/migrate.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { listRepositoryFiles } from '@/git-files'
@@ -26,6 +26,10 @@ import {
   walkFlatRules,
 } from '@/migrate/rule-layout'
 import { SKILL_NAME_MAP, SKILL_NAME_RULES } from '@/migrate/skill-names'
+import {
+  planSurfaceRootsMove,
+  type SurfaceRootsPlan,
+} from '@/migrate/surface-roots'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -396,6 +400,143 @@ function toRecordsRecord(
   }
 }
 
+/**
+ * Moves the tracked toolkit surfaces to `canon/` and repoints what cites them.
+ *
+ * Every path here is tracked, so the write goes through `applyRename`'s
+ * `git mv` rather than the records move's plain rename, and the history
+ * follows each file. A destination already on disk refuses the whole plan,
+ * since `git mv` onto an existing path fails per file and leaves a tree split
+ * across both roots.
+ */
+async function runSurfaceRoots(opts: SweepOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const files = await listRepositoryFiles(root)
+  if (files === undefined) {
+    logError(`Could not list files under ${root}. Is it a git repository?`)
+    return 1
+  }
+
+  const toSweep = files.filter((path) => !isRecordArtifact(path))
+  const plan = planSurfaceRootsMove(await readSources(root, toSweep))
+  const taken = plan.entries
+    .map((entry) => entry.movesTo)
+    .filter((to): to is string => to !== undefined)
+    .filter((to) => existsSync(join(root, to)))
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toSurfaceRootsRecord(plan, taken, opts.write))}\n`,
+    )
+  }
+
+  reportSurfaceRoots(plan)
+
+  if (taken.length > 0) {
+    logError(
+      `${plural(taken.length, 'destination')} already exist under canon/. Merging two copies of a surface is not a call this verb takes.`,
+    )
+    for (const path of taken) logError(`  ${path}`)
+    return 1
+  }
+
+  if (plan.entries.length === 0) return 0
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRename(root, {
+    entries: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      ...(entry.text === undefined ? {} : { text: entry.text }),
+      renamed: entry.rewritten,
+      protectedCount: entry.kept,
+    })),
+    excluded: plan.excluded,
+    renamed: plan.rewritten,
+    protectedCount: plan.kept,
+    moves: plan.moves,
+  })
+  logStep(
+    `Rewrote ${plural(applied.written, 'file')} and moved ${plural(applied.moved, 'file')}.`,
+  )
+
+  if (applied.failed.length > 0) {
+    logError(`Could not move ${plural(applied.failed.length, 'path')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return 0
+}
+
+function reportSurfaceRoots(plan: SurfaceRootsPlan): void {
+  logInfo(`${plural(plan.moves, 'file')} to move.`)
+  logInfo(
+    `${plural(plan.entries.filter((entry) => entry.text !== undefined).length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
+  )
+  logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
+
+  if (plan.excluded.length > 0) {
+    logInfo(`${plural(plan.excluded.length, 'file')} excluded from the sweep:`)
+    for (const path of plan.excluded) logInfo(`  ${path}`)
+  }
+
+  if (plan.coupled.length > 0) {
+    logInfo(
+      `${plural(plan.coupled.length, 'file')} couple to an excluded path:`,
+    )
+    for (const path of plan.coupled) logInfo(`  ${path}`)
+  }
+
+  for (const [label, held] of [
+    ['a frontmatter paths: glob', plan.frontmatterGlobs],
+    ['a citation into another repository', plan.crossRepoCitations],
+    ['a dated citation', plan.datedCitations],
+  ] as const) {
+    if (held.length === 0) continue
+    logInfo(`${plural(held.length, 'file')} carry ${label}, left alone:`)
+    for (const entry of held) {
+      for (const line of entry.lines) {
+        logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+      }
+    }
+  }
+}
+
+function toSurfaceRootsRecord(
+  plan: SurfaceRootsPlan,
+  collisions: readonly string[],
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: collisions.length === 0,
+    wrote: wrote === true,
+    moves: plan.moves,
+    collisions,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    kept: plan.kept,
+    excluded: plan.excluded,
+    coupled: plan.coupled,
+    frontmatterGlobs: plan.frontmatterGlobs,
+    crossRepoCitations: plan.crossRepoCitations,
+    datedCitations: plan.datedCitations,
+    globs: plan.globs,
+    crossRepo: plan.crossRepo,
+    dated: plan.dated,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      ...(entry.movesTo === undefined ? {} : { movesTo: entry.movesTo }),
+      rewritten: entry.rewritten,
+    })),
+  }
+}
+
 interface RecordTreeOptions {
   readonly json?: boolean
   readonly write?: boolean
@@ -763,6 +904,46 @@ export function register(program: Command): void {
       process.exitCode = await runRecords(opts)
     })
 
+  migrate
+    .command('surface-roots')
+    .description('Move the tracked toolkit surfaces to canon/')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  nothing to move, or --write applied the whole plan',
+        '  1  refused, or a move failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Moves canon/context/, canon/wireframes/, and the ARCHITECTURE.md,',
+        'REQUIREMENTS.md, and DESIGN.md documents to canon/ with git mv, and',
+        'rewrites every tracked citation of them. .claude/canon/, rules/,',
+        'skills/, hooks/, and settings.json stay where the vendor reads them.',
+        '',
+        'A line carrying canon-keep-surface-root, or the nearest non-blank line',
+        'above it, keeps the old root. A frontmatter paths: glob, a citation',
+        'into another repository, and one inside a dated paragraph are reported',
+        'and left alone rather than rewritten.',
+        '',
+        'Examples:',
+        '  canon migrate surface-roots',
+        '  canon migrate surface-roots --write',
+        '  canon migrate surface-roots --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SweepOptions) => {
+      process.exitCode = await runSurfaceRoots(opts)
+    })
+
   migrate
     .command('record-tree')
     .description('Repoint old-root citations inside the records themselves')

package/src/context/audit.ts

@@ -19,7 +19,7 @@ import { isStubSeed } from '@/seed-marker'
  * Every reason `canon context audit` refuses for.
  *
  * `no-folders` is the one ordinary absence: a project that never adopted
- * `.claude/context/`, `.canon/diagrams/`, or `.claude/wireframes/` names no
+ * `canon/context/`, `.canon/diagrams/`, or `canon/wireframes/` names no
  * corpus this audit can measure, the same state `no-skills` reads for the
  * skill corpora. The other four are a malformed invocation or a checkout git
  * cannot read, which stay a break rather than an absence.

package/src/context/citations.ts

@@ -84,13 +84,15 @@ export function isFixture(rel: string): boolean {
  * A dotted root cannot be a suffix of a path segment, since a segment boundary
  * is a slash and a slash can never sit inside the dot itself, so a preceding
  * slash is not a false match to guard against and the boundary admits it. That
- * is what a relative link needs, since `../.claude/context/<entry>.md` carries
- * a slash immediately before `.claude`. A bare root has no such protection: it
- * is a suffix of a dotted root's own name and of any `/<root>/` path segment,
- * so its boundary rejects a slash along with a name character or a dot.
+ * is what a relative link into a dotted root needs. A bare root has no such
+ * protection: it is a suffix of a dotted root's own name and of any
+ * `/<root>/` path segment, such as a seed tree's own `canon/` folder, so its
+ * boundary rejects a name character, a dot, and a slash, except a slash that
+ * closes a `..` segment. That one exception is a relative link climbing out of
+ * a folder into the bare root, which is the form a moved docs page writes.
  */
 function rootBoundary(root: string): string {
-  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w./])'
+  return root.startsWith('.') ? '(?<![\\w.])' : '(?<![\\w.])(?<!(?<!\\.\\.)/)'
 }
 
 /**

package/src/context/folders.ts

@@ -61,7 +61,7 @@ export interface AuditedFolder {
    * The requested folder name this was resolved under, which is what says
    * which standard governs the entries. A nested split folder carries the name
    * of the folder it sits beneath rather than its own, so
-   * `.claude/context/claude-plugin` is governed as `context`.
+   * `canon/context/claude-plugin` is governed as `context`.
    */
   readonly name: string
   /**
@@ -90,7 +90,7 @@ export interface AuditedFolder {
  * Names the requested record-root folders that actually exist, which is the
  * citation check's scope.
  *
- * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
+ * A skill or seed pointing into `canon/wireframes/` is a live instruction for
  * a project that carries the folder and says nothing about one that does not.
  * Checking a path into an absent folder would fail eight shipped references
  * here for the sole reason that this repository has no wireframes.

package/src/counts/scan.ts

@@ -35,7 +35,7 @@ export type CountsReport =
 
 /**
  * A calendar date, which reads a sentence as a historical record rather than
- * a live claim about the tree. `.claude/ARCHITECTURE.md` and the context
+ * a live claim about the tree. `canon/ARCHITECTURE.md` and the context
  * entries carry a figure this way deliberately, and every one of them stays
  * correct forever, so a sentence carrying one is read past rather than
  * matched.
@@ -80,7 +80,7 @@ function sentencesOf(line: string): string[] {
  * the 290 showed removing all of them while keeping that one.
  *
  * `authors` joined the list on a corpus measurement rather than on the shape
- * argument above. `.claude/context/development/regeneration.md` states `the
+ * argument above. `canon/context/development/regeneration.md` states `the
  * toolkit authors 69 rules under governance/rules/`, which is the assertion
  * shape this list was built for with a verb the list did not carry, and the
  * word costs one further sentence across the whole corpus and no finding.
@@ -129,7 +129,7 @@ const QUANTIFIERS = ['all']
  * of the number.
  *
  * Found on this module's own first review, against a live instance the verb
- * gate alone reported clean: `.claude/context/development/gates.md` stated
+ * gate alone reported clean: `canon/context/development/gates.md` stated
  * `the twelve audits` while the tree held 20, sitting inside the plausibility
  * bound this design already carries, so nothing but the missing shape kept it
  * from reporting.
@@ -142,7 +142,7 @@ const QUANTIFIERS = ['all']
  * match at all. No syntactic rule tells a qualifier that narrows a catalog
  * from one that only restates it, and the sentence was true when written, so
  * the fix was not a narrower matcher: the clause was dated as a past state,
- * the way `.claude/ARCHITECTURE.md` dates its own figures, which is the class
+ * the way `canon/ARCHITECTURE.md` dates its own figures, which is the class
  * the date exclusion below already reads past.
  */
 const ARTICLES = ['the', 'a', 'an']