@erclx/canon 4.78.0 → 4.79.0

package/src/record-root.ts

@@ -52,10 +52,12 @@ const CANON_SCRATCH = 'tmp'
  * writes back. `worktrees` is absent because the harness creates a worktree
  * under `.claude/` and requires its target to sit there.
  *
- * Everything absent from this list is committed and stays where it is, which is
- * the rule the move ran on. `context`, `rules`, `skills`, `hooks`, `wireframes`,
- * and the loose documents at the root are all in that set, which is why a seed
- * and a superseded-layout report each ask this rather than assuming a root.
+ * Everything absent from this list is committed and never lands under the
+ * record root, which is the rule the move ran on. `rules`, `skills`, and
+ * `hooks` stay under `.claude/` because the vendor reads them there, while
+ * `context`, `wireframes`, and the loose documents are tracked surfaces that
+ * `surface-root.ts` resolves under `canon/` instead. A seed and a
+ * superseded-layout report each ask this rather than assuming a root.
  */
 export const RECORD_ENTRIES: readonly string[] = [
   '.records.git',

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
+ * `<category>-<command>` is the rule `canon/context/sandbox/coverage.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two

package/src/shipped/references.ts

@@ -139,10 +139,10 @@ const SAME_REPOSITORY =
  * named a target's own tree, measured on 2026-09-03. Resolving against `root`
  * is what turns that 124-hit pattern into the four-hit gate.
  *
- * `.claude/context/` carries no equivalent pattern. The same resolution test
+ * `canon/context/` carries no equivalent pattern. The same resolution test
  * cannot separate a path every scaffolded project holds, such as
- * `.claude/context/index.md`, from this repository's own domain entry, such
- * as `.claude/context/indexes.md`, since both resolve here and only the
+ * `canon/context/index.md`, from this repository's own domain entry, such
+ * as `canon/context/indexes.md`, since both resolve here and only the
  * second is a defect. That is a semantic read no pattern makes, so it stays
  * with the rule and the review checklist rather than joining this reader.
  */

package/src/surface-root.ts

@@ -23,13 +23,13 @@ export type SurfaceRoot = (typeof SURFACE_ROOTS)[number]
 /**
  * The root a surface is created at when neither root carries it yet.
  *
- * Disagreeing with the head of the read order for exactly one release: read
- * precedence is new-first so a tree that has moved is never answered from the
- * copy left behind, while creation stays at the old root so nothing writes a
- * fresh tracked file under a root a target's installed binary may not resolve
- * yet. A later batch flips this once a release carries the read side.
+ * It agrees with the head of the read precedence. While the two disagreed,
+ * creation stayed at `.claude/` so nothing wrote a fresh tracked file under a
+ * root a target's installed binary could not resolve. A release carries the
+ * read side now, so a fresh project scaffolds one root and an unmoved one keeps
+ * resolving its own surfaces through the fallback above.
  */
-export const CREATION_ROOT: SurfaceRoot = '.claude'
+export const CREATION_ROOT: SurfaceRoot = 'canon'
 
 /**
  * Every tracked surface this module resolves, at the name `.claude/` gives it.
@@ -55,6 +55,18 @@ export function spell(root: SurfaceRoot, entry: string): string {
   return root === 'canon' && entry === 'canon' ? 'config' : entry
 }
 
+/**
+ * The creation default for one entry.
+ *
+ * The stamp folder keeps creating under `.claude/` until its own move lands,
+ * since the install stamp and the audits baseline still write there by a
+ * fixed path. A read resolving to `canon/config/` in a fresh project would
+ * answer from a folder nothing writes.
+ */
+function creationRootFor(entry: string): SurfaceRoot {
+  return entry === 'canon' ? '.claude' : CREATION_ROOT
+}
+
 /**
  * The root a surface resolves at: the first that carries it, and the creation
  * default when neither does.
@@ -63,7 +75,7 @@ function rootOf(root: string, entry: string): SurfaceRoot {
   return (
     SURFACE_ROOTS.find((candidate) =>
       existsSync(join(root, candidate, spell(candidate, entry))),
-    ) ?? CREATION_ROOT
+    ) ?? creationRootFor(entry)
   )
 }
 
@@ -82,6 +94,26 @@ export function surfaceDir(
   return join(root, at, spell(at, entry), ...rest)
 }
 
+/**
+ * Where a path authored at the `canon/` spelling lands under `root`.
+ *
+ * A seed tree authors every surface once, at the new root, while a target may
+ * still hold that surface under `.claude/`. Writing the literal path there
+ * would open a `canon/` copy that wins read precedence and hides every entry
+ * the target already wrote, so the entry resolves the way a read does. A path
+ * naming no surface entry is joined as written.
+ */
+export function resolveSurfacePath(root: string, rel: string): string {
+  const [head, entry, ...rest] = rel.split(/[\\/]/)
+
+  if (head !== 'canon' || entry === undefined || entry === 'canon') {
+    return join(root, rel)
+  }
+  if (!SURFACE_ENTRIES.includes(entry)) return join(root, rel)
+
+  return surfaceDir(root, entry, ...rest)
+}
+
 /**
  * Every root a surface would be read at, in precedence order, whether or not
  * it is on disk.

package/src/sync/layout.ts

@@ -1,7 +1,8 @@
 import { existsSync, statSync } from 'node:fs'
-import { basename, join } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { SUBDIRS } from '@/claude/seeds'
 import { creationRel, isRecordEntry } from '@/record-root'
+import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
 import type { StampDomain } from '@/sync/stamp'
 
 const CLAUDE_DIR = '.claude'
@@ -70,13 +71,16 @@ export function collectSuperseded(target: string): SupersededEntry[] {
     const rel = join(CLAUDE_DIR, `${subdir.toUpperCase()}.md`)
     if (!isFile(join(target, rel))) continue
 
-    // A record subdir now lives under the record root, so the replacement this
-    // names is resolved against the target rather than fixed at `.claude/`.
-    // Naming a folder the target does not have sends a person to migrate their
-    // legacy file into a path nothing reads.
+    // A record subdir lives under the record root and a tracked surface under
+    // the surface root, so the replacement this names is resolved against the
+    // target rather than fixed at `.claude/`. Naming a folder the target does
+    // not have sends a person to migrate their legacy file into a path nothing
+    // reads.
     const replacedBy = isRecordEntry(subdir)
       ? creationRel(target, subdir)
-      : join(CLAUDE_DIR, subdir)
+      : SURFACE_ENTRIES.includes(subdir)
+        ? relative(target, surfaceDir(target, subdir))
+        : join(CLAUDE_DIR, subdir)
 
     entries.push({ rel, replacedBy })
   }

package/src/sync/reverse.ts

@@ -234,7 +234,7 @@ export function detectMigrations(target: string): MigrationCandidate[] {
   if (docs > 0 && context === 0) {
     found.push({
       skill: 'migration-context',
-      reason: `${docs} markdown files under docs/ with no .claude/context/ tier`,
+      reason: `${docs} markdown files under docs/ with no canon/context/ tier`,
     })
   }
 

package/src/tooling/inject.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
 import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -92,8 +93,9 @@ export async function injectSeeds(
 
     logStep(`Applying ${manifest.name} seeds`)
     for (const rel of files) {
-      await mergeSeedFile(join(manifest.seedsDir, rel), join(target, rel))
-      logAdd(rel)
+      const dest = resolveSurfacePath(target, rel)
+      await mergeSeedFile(join(manifest.seedsDir, rel), dest)
+      logAdd(relative(target, dest))
       applied.push(rel)
     }
   }

package/src/tooling/scan.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections } from '@/tooling/gitignore'
 import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
@@ -79,7 +80,9 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
       seeds.push({
         rel,
-        state: existsSync(join(target, rel)) ? 'present' : 'missing',
+        state: existsSync(resolveSurfacePath(target, rel))
+          ? 'present'
+          : 'missing',
       })
     }
   }

package/standards/architecture.md

@@ -1,15 +1,15 @@
 ---
 title: Architecture reference
-description: Shape and content rules for .claude/ARCHITECTURE.md
+description: Shape and content rules for canon/ARCHITECTURE.md
 ---
 
 # Architecture reference
 
-Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
+Applies to `canon/ARCHITECTURE.md`. Describes the system shape and the decisions behind it, not a tutorial, setup guide, or implementation walkthrough. Pair it with `CLAUDE.md`: principles live there, patterns and decisions live here. Update when a decision is made or a risk is resolved.
 
 ## Scope
 
-Governs the system-shape document at `.claude/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
+Governs the system-shape document at `canon/ARCHITECTURE.md`: the overview, the decision entries, and the open risks.
 
 Does not govern:
 
@@ -27,7 +27,7 @@ Does not govern:
 
 - How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
-- A measurement paragraph specific to one domain's own mechanism. Route it to that domain's `.claude/context/<domain>.md` entry instead. The choice and its rejected alternative stay here whatever their reach, since reach is what makes a decision cross-domain, not how many domains its supporting measurement happens to touch.
+- A measurement paragraph specific to one domain's own mechanism. Route it to that domain's `canon/context/<domain>.md` entry instead. The choice and its rejected alternative stay here whatever their reach, since reach is what makes a decision cross-domain, not how many domains its supporting measurement happens to touch.
 
 ## Sections
 

package/standards/context.md

@@ -1,15 +1,15 @@
 ---
 title: Context entry reference
-description: Shape and content rules for .claude/context/<domain>.md entries
+description: Shape and content rules for canon/context/<domain>.md entries
 ---
 
 # Context entry reference
 
-Applies to per-domain narrative entries under `.claude/context/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+Applies to per-domain narrative entries under `canon/context/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
 
 ## Scope
 
-Governs per-domain narrative entries under `.claude/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
+Governs per-domain narrative entries under `canon/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
 
 Does not govern:
 
@@ -42,7 +42,7 @@ An entry that fails these is non-conforming regardless of whether it satisfies e
 - `title` (required): sentence case, names the domain (`Web`, `API`, `Agents`).
 - `description` (required): one line describing what the domain covers.
 
-Both fields feed `.claude/context/index.md` when regenerated.
+Both fields feed `canon/context/index.md` when regenerated.
 
 ## Required sections
 
@@ -81,7 +81,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## What goes in
 
 - Per-domain narrative on how the code is structured and why
-- Decisions specific to the domain. Broader cross-domain decisions belong in `.claude/ARCHITECTURE.md`.
+- Decisions specific to the domain. Broader cross-domain decisions belong in `canon/ARCHITECTURE.md`.
 - Constraints, gotchas, things tried and rejected
 - Domain-specific conventions that do not fit a `paths:`-scoped rule
 - A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
@@ -95,7 +95,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Rules. Those go in `.claude/rules/<scope>.md` with a `paths:` glob.
 - Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
 - Generated content (API references). Generate, do not write by hand.
-- Anything already in `.claude/REQUIREMENTS.md` or `.claude/ARCHITECTURE.md`.
+- Anything already in `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`.
 - The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
 - A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
 
@@ -107,7 +107,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
 - Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
-- Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Split into a folder (`canon/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
 - Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
 

package/standards/design.md

@@ -1,15 +1,15 @@
 ---
 title: Design reference
-description: Shape and content rules for .claude/DESIGN.md
+description: Shape and content rules for canon/DESIGN.md
 ---
 
 # Design reference
 
-Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
+Applies to `canon/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
 
 ## Scope
 
-Governs the visual-intent document at `.claude/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
+Governs the visual-intent document at `canon/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
 
 Does not govern:
 

package/standards/diagrams.md

@@ -7,7 +7,7 @@ description: Shape and content rules for .canon/diagrams/<kind>.md files
 
 Applies to per-kind entries under `.canon/diagrams/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
 
-A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
+A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `canon/context/`.
 
 ## Scope
 
@@ -50,8 +50,8 @@ One writer touches `verified`, which is the pass that renders an entry and reads
 
 Five kinds, each with a fixed filename and a fixed `category` value. Write a kind only when its source signal exists, and leave the rest absent rather than padding the folder.
 
-- `system-context.md`, category `System context` (`flowchart TB`): who uses the system, what it talks to, and where its boundary sits. Drawn from `.claude/REQUIREMENTS.md`. This is the entry a reader outside the team opens first, and the only kind that draws the world outside the boundary.
-- `components.md`, category `Components` (`flowchart TB` with `subgraph` boundaries): the layered structure inside the boundary. Drawn from `.claude/ARCHITECTURE.md`.
+- `system-context.md`, category `System context` (`flowchart TB`): who uses the system, what it talks to, and where its boundary sits. Drawn from `canon/REQUIREMENTS.md`. This is the entry a reader outside the team opens first, and the only kind that draws the world outside the boundary.
+- `components.md`, category `Components` (`flowchart TB` with `subgraph` boundaries): the layered structure inside the boundary. Drawn from `canon/ARCHITECTURE.md`.
 - `request-flow.md`, category `Request flow` (`sequenceDiagram`): a request lifecycle, an agent loop, or an interaction between actors.
 - `data-pipeline.md`, category `Data pipeline` (`flowchart TB`): retrieval, ranking, queues, or ETL.
 - `deployment.md`, category `Deployment` (`flowchart TB`): hosts, services, and infrastructure config.
@@ -78,9 +78,9 @@ A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and
 
 This section states the voice for the surface, which is what claims the yield the `write-human` skill grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the language bans, punctuation, and formatting in `markdown.md`, which grants no yield at all.
 
-## What moves to .claude/context/
+## What moves to canon/context/
 
-Implementation detail that answers how a component is built belongs in a `.claude/context/` entry, not a diagram:
+Implementation detail that answers how a component is built belongs in a `canon/context/` entry, not a diagram:
 
 - Function names, call signatures, and lifecycle ordering
 - Library versions, config keys, and environment variable names
@@ -93,7 +93,7 @@ Reference the context entry by path when a reader needs the mechanism. The diagr
 
 - When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
 - A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
-- `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- `System context` has no named source signal beyond `canon/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
 - Nothing watches the folder for you. The entries are redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind the branch is due a read, and no pass is going to name which one.
 
 ## Template

package/standards/index.md

@@ -7,11 +7,11 @@ subtitle: Reference docs for consistent authoring across the toolkit and target
 
 Reference docs for consistent authoring across the toolkit and target projects.
 
-- [Architecture reference](architecture.md): Shape and content rules for .claude/ARCHITECTURE.md
+- [Architecture reference](architecture.md): Shape and content rules for canon/ARCHITECTURE.md
 - [Branch reference](branch.md): Branch naming format and type conventions
 - [Commit reference](commit.md): Commit message format and type conventions
-- [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
-- [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
+- [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
+- [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
 - [Figure reference](figures.md): When a figure earns its place, the render-first policy for a graph-shaped subject, freehand SVG as the escape hatch, and its wrapping, color, and accessibility rules
@@ -26,7 +26,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
-- [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
+- [Requirements reference](requirements.md): Shape and content rules for canon/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
@@ -37,4 +37,4 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wiki reference](wiki.md): Folder split, frontmatter, naming convention, and sourcing for a wiki reference page
-- [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files
+- [Wireframe reference](wireframes.md): Shape and content rules for canon/wireframes/<surface>.md files

package/standards/markdown.md

@@ -108,8 +108,8 @@ When frontmatter carries a short `title` or `description` used for catalog displ
 Each pair shows a banned pattern and its fix.
 
 ```markdown
-Bad: See [.claude/context/retrieval.md](.claude/context/retrieval.md) for the retrieval flow.
-Good: See `.claude/context/retrieval.md` for the retrieval flow.
+Bad: See [canon/context/retrieval.md](canon/context/retrieval.md) for the retrieval flow.
+Good: See `canon/context/retrieval.md` for the retrieval flow.
 ```
 
 ```markdown

package/standards/publish.md

@@ -42,7 +42,7 @@ A phase label is one way text names the board, and a path under a record root is
 
 Two shapes get past a reader scanning for a bare label. A code span quoting a label is still the label, so read a span whose whole content is one as a hit and leave a longer token inside a span alone, which is a fixture name rather than a reference. The second shape is a path under a record root, gitignored and therefore absent from every clone, so `.canon/review/feedback/` names a folder the remote's reader cannot open.
 
-Under `.claude/`'s own tracked folders there is no hit, since `.claude/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
+Under the tracked `canon/` and `.claude/` folders there is no hit, since `canon/context/governance/rules.md` resolves everywhere. `.canon/` carries no such carve-out: one ignore line covers the root whole, so every path beneath it is a hit regardless of which folder names it.
 
 Rewrite a hit to name what the reader can reach rather than deleting it. A row's subject stated plainly replaces its label, and what a record folder holds, said in a sentence, replaces its path.
 
@@ -66,11 +66,11 @@ Text published to a remote is the auto-linking half: a pull request body, an iss
 
 Content that installs into another repository is the third destination, and it splits on which repository the number names. A skill body loads from a plugin cache, a docs page is read through `canon docs`, and a standard through `canon standards`, so the reader holds their own repository rather than the one a bare number belongs to. Qualifying a number against a different, resolvable repository fixes that, since the reader can open that repository even without this one.
 
-Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `.claude/context/` entry that owns the surface.
+Qualifying it against `erclx/canon` fixes nothing, because a reader holding only the plugin cache or the published package still cannot open this repository's own history. A same-repository citation takes no number here at all, bare or qualified. State the fact the citation was standing in for instead, and where the identifier is the only trace of a one-off incident rather than a reproducible count, carry it into the `canon/context/` entry that owns the surface.
 
 Write `owner/repo#123` and `owner/repo@abc1234` for a citation of a different, resolvable repository, across every such surface. `canon gate run` fails a push on a bare reference there, and a line whose bare form is the point carries `canon-allow-reference: <reason>` on itself or on the line above.
 
-Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape `.claude/ARCHITECTURE.md` already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
+Choose the number over the sha where the citation names a decided change, since a pull request number resolves to the diff and the review behind it. Take the sha only for a tree or measurement state, the `Measured at <sha>` shape `canon/ARCHITECTURE.md` already uses. The choice holds for both spellings this section fixes, the bare form a remote auto-links and the qualified form a cross-repository citation carries.
 
 A commit message takes the bare form even though it is also read through the log, where nothing links. The remote is what the form is chosen for, since a reader in the log loses only a link that plain text never carried.
 

package/standards/readme.md

@@ -46,7 +46,7 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
 - Do not include extensive troubleshooting guides. Use a wiki or separate documentation.
-- A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `.claude/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
+- A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `canon/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
 - A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
 
 ### Badges

package/standards/requirements.md

@@ -1,15 +1,15 @@
 ---
 title: Requirements reference
-description: Shape and content rules for .claude/REQUIREMENTS.md
+description: Shape and content rules for canon/REQUIREMENTS.md
 ---
 
 # Requirements reference
 
-Applies to `.claude/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
+Applies to `canon/REQUIREMENTS.md`. Describes what the product does and why, not how it works. Update when scope changes, goals shift, or a non-goal is promoted to a feature.
 
 ## Scope
 
-Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
+Governs the product-scope document at `canon/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
 
 Does not govern:
 
@@ -45,7 +45,7 @@ Later scope arrives as a new section rather than as an extension of the MVP list
 
 Include `## Distribution` only when the project ships to consumers outside its own repository. An internal service or a monorepo application has nothing to put in it, and a section every project is told to fill is one most projects pad. Place it after `## MVP features`.
 
-State each entry as an outcome the consumer reaches, never as the mechanism that delivers it. A registry name, a manifest format, a version scheme, or a release tool is implementation and belongs in `.claude/ARCHITECTURE.md`. Distribution pulls harder toward mechanism than any other section, which is why the rule is repeated here.
+State each entry as an outcome the consumer reaches, never as the mechanism that delivers it. A registry name, a manifest format, a version scheme, or a release tool is implementation and belongs in `canon/ARCHITECTURE.md`. Distribution pulls harder toward mechanism than any other section, which is why the rule is repeated here.
 
 ## Template
 

package/standards/skill.md

@@ -210,7 +210,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 ### Output and tuning
 
 - Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
-- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, or `teach/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `.claude/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
+- Before a skill writes anything, decide whether the output is a deliverable the project keeps or a toolkit session record. A deliverable lands among the project's own tracked files. A session record lands under `.canon/`, in the named subfolder for its kind (`tasks/`, `plans/`, `review/`, `memory/`, `groundwork/`, `intake/`, `proposals/`, `diagrams/`, or `teach/`, with `tmp/` for scratch nothing else claims), never in a folder the body invents. `canon/ARCHITECTURE.md`'s per-folder decisions are the precedent for which kind takes which folder.
 - Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.
@@ -228,7 +228,7 @@ Without this skill, a session <observed failure>, <observed failure>.
 A skill reads from two roots. Know which one a file lives under before referencing it.
 
 - Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory in the source clone. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, so a plugin skill running from another project still finds them.
-- Installed shared docs (`.claude/rules/`, `.claude/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
+- Installed shared docs (`.claude/rules/`, `canon/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
 - Do not hand-copy a standard into a skill. A hand-copied file drifts from its source and belongs to no owner. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
 
 ### Citing a standard

package/standards/tasks.md

@@ -244,7 +244,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
 
 - Class names, file paths, function names, or prop names in any entry or title
 - Code-level steps or implementation detail. Behavioral specifics are fine.
-- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
+- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `canon/ARCHITECTURE.md`.
 - Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
 - "In progress" or "Blocked" headings. Note status inline on the outcome instead.
 - Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Rationale wider than one row has no home at all, so cut it rather than filing it here.

package/standards/wiki.md

@@ -27,7 +27,7 @@ A page failing either is non-conforming even when it satisfies every shape rule
 
 ## Placement
 
-- Write a page here only when its subject is owned outside this repository. Route anything about how this repository works to `docs/`, `.claude/context/`, or a skill body instead.
+- Write a page here only when its subject is owned outside this repository. Route anything about how this repository works to `docs/`, `canon/context/`, or a skill body instead.
 - File the page under `wiki/claude/`. A subject Anthropic does not own, whether a third-party tool or a vendor-neutral concept, is out of scope for this folder split. Route it to `docs/` or a skill body instead of adding a second wiki folder for it.
 
 ## Frontmatter

package/standards/wireframes.md

@@ -1,17 +1,17 @@
 ---
 title: Wireframe reference
-description: Shape and content rules for .claude/wireframes/<surface>.md files
+description: Shape and content rules for canon/wireframes/<surface>.md files
 ---
 
 # Wireframe reference
 
-Applies to per-surface entries under `.claude/wireframes/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+Applies to per-surface entries under `canon/wireframes/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
 
-A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `.claude/context/`.
+A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `canon/context/`.
 
 ## Scope
 
-Governs per-surface wireframe entries under `.claude/wireframes/`: layout, variants, on-screen copy, and interaction intent.
+Governs per-surface wireframe entries under `canon/wireframes/`: layout, variants, on-screen copy, and interaction intent.
 
 Does not govern:
 
@@ -36,14 +36,14 @@ A wireframe regenerated from an already-built surface's own render code may carr
 
 A drafted-ahead wireframe states intent in role terms because nothing exists yet to check it against. A regenerated one is checkable against the code it mirrors, and a role label standing in for the real class name would throw that check away. The two documents answer different questions, so one set of rules cannot govern both.
 
-Route detail the source citation does not already carry to `.claude/context/` as usual: algorithms, event-handler code, workarounds, and rejected approaches stay out of the wireframe regardless of which mode it is written in.
+Route detail the source citation does not already carry to `canon/context/` as usual: algorithms, event-handler code, workarounds, and rejected approaches stay out of the wireframe regardless of which mode it is written in.
 
 ## Frontmatter
 
 - `title` (required): sentence case, names the surface (`Header`, `Section nav`, `Footer`).
 - `description` (required): one line on when and where the surface appears.
 
-Both fields feed `.claude/wireframes/index.md` when regenerated.
+Both fields feed `canon/wireframes/index.md` when regenerated.
 
 ## Layout
 
@@ -70,9 +70,9 @@ Both fields feed `.claude/wireframes/index.md` when regenerated.
 - State the rule, not the mechanism. `The rail tracks the active section as the visitor scrolls` is intent. The scroll handler, throttle, and observer margins are not.
 - Keep it to a short list. A Behavior section longer than the layout is a sign implementation detail has leaked in.
 
-## What moves to .claude/context/
+## What moves to canon/context/
 
-This section does not govern a transcription wireframe's citation of its own source. See `## Transcription wireframes`. Implementation detail that answers how the surface is built belongs in a `.claude/context/` entry, not the wireframe:
+This section does not govern a transcription wireframe's citation of its own source. See `## Transcription wireframes`. Implementation detail that answers how the surface is built belongs in a `canon/context/` entry, not the wireframe:
 
 - Algorithms, event-handler code, and lifecycle ordering
 - Framework component names, props, and CSS class or token names

package/tooling/astro/reference.md

@@ -12,7 +12,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 2. Add React integration: `bunx astro add react`. Do not use `astro add tailwind`. That command installs the v3 integration. Tailwind v4 arrives via the web manifest.
 3. Install web tooling: `canon tooling sync web . --write`
 4. Install astro adapter: `canon tooling sync astro . --write`
-5. Extend the `ci` and `development` context entries under `.claude/context/` per the web reference's extend sections plus the astro rows below.
+5. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the astro rows below.
 6. Run `bun run lint:fix` then `bun run check`.
 
 ## What ships as golden configs
@@ -21,7 +21,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
-- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `.claude/context/tooling.md` for the measurement.
+- `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling.md` for the measurement.
 
 ## Typecheck
 
@@ -57,7 +57,7 @@ Append to the `## Scripts` table:
 
 ## CI docs (extend)
 
-In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
+In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
 
 ## Gitignore (extend)
 

package/tooling/base/reference.md

@@ -28,7 +28,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.cspell/project-terms.txt` and `.cspell/tech-stack.txt`: one word per line, sorted alphabetically.
 - `.lintstagedrc`: the glob map below.
 - `.prettierignore`: created empty. Projects add their own entries.
-- `.claude/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
+- `canon/context/`: extend the `ci` and `development` entries with project-specific commands, workflows, or deploy steps. Canonical rationale stays in this reference.
 
 ## Tool pairing
 
@@ -42,8 +42,8 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 ## File layout
 
 - All shell scripts live in `scripts/`. Do not place a `.sh` file outside it.
-- Dictionaries live in `.cspell/`, hooks in `.husky/`, seeded context docs in `.claude/context/`.
-- The `.claude/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md`, `.claude/REQUIREMENTS.md`, and `.claude/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `.claude/context/`. Indexes stay opt-in.
+- Dictionaries live in `.cspell/`, hooks in `.husky/`, seeded context docs in `canon/context/`.
+- The `canon/context/` location matches the three-tier context model: project-wide invariants in `CLAUDE.md`, `canon/REQUIREMENTS.md`, and `canon/ARCHITECTURE.md`, path-scoped rules in `.claude/rules/`, and on-demand domain narrative in `canon/context/`. Indexes stay opt-in.
 
 ## Hooks