basalt-ui 1.40.3 → 2.0.0

package/src/cli/index.ts

@@ -14,6 +14,7 @@ import {
   readFileSync,
   rmdirSync,
   statSync,
+  realpathSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs'
@@ -56,9 +57,7 @@ const GUARD_PASSTHROUGH = {
   rawHtmlLayout: true,
   inlineSpacing: true,
   inlineDisplay: true,
-  rawVisxAxis: true,
   rawMotionValue: true,
-  chartMissingAriaLabel: true,
   rawFormControl: true,
   sub16InputFont: true,
   severity: true,
@@ -84,13 +83,9 @@ export function resolveGuardConfig(cfg: BasaltConfig, profile: DoctorProfile): G
 }
 
 /**
- * The one consumer series path — the DESIGN.md template's `{{SERIES_MODULE_PATH}}`, the default
- * scan exemption, and the skills' prose all resolve through this single function.
- *
- * Derived from the FIRST configured root (argo's convention: `<root>/lib/series.ts`), not a fixed
- * `src/lib/series.ts` — a monorepo that correctly sets `roots: ['apps/web/src']` has no top-level
- * `src/`, so a hardcoded default would seed a DESIGN.md pointing at a path that cannot exist and
- * silently exempt nothing. `seriesModulePath` still overrides for a layout that isn't `<root>/lib/`.
+ * The one consumer series path (DESIGN.md's `{{SERIES_MODULE_PATH}}`, the default scan exemption,
+ * the skills' prose). Derived from the FIRST configured root (`<root>/lib/series.ts`), since a
+ * monorepo with `roots: ['apps/web/src']` has no top-level `src/`. `seriesModulePath` overrides.
  */
 function resolveSeriesModulePath(cfg: BasaltConfig): string {
   if (cfg.seriesModulePath !== undefined) return cfg.seriesModulePath
@@ -125,14 +120,8 @@ export const SERIES_MODULE_HINT_RE = /(series|palette)\.tsx?$/i
 const SEVERITY_VALUES: readonly string[] = ['warn', 'error']
 
 /**
- * Drop `basalt.severity` entries whose value is not `'warn'` / `'error'`, loudly.
- *
- * This is the one config field where a typo REMOVES enforcement rather than failing: package.json
- * is untyped at runtime, and `"warning"` would stamp findings with a value matching neither the
- * error bucket (which fails the build) nor the warn bucket (which prints them) — the kind would
- * vanish and `check-theme` would exit 0 as if the tree were clean. Dropping the entry falls the
- * kind back to its default, so the failure direction of a typo is "stricter than you meant, and
- * told about it" instead of "silently unguarded".
+ * Drop `basalt.severity` entries whose value is not `'warn'` / `'error'`, loudly: a typo there would
+ * silently REMOVE enforcement. The kind falls back to its default instead (stricter, and told about).
  */
 function sanitizeSeverity(cfg: BasaltConfig): BasaltConfig {
   const raw: unknown = cfg.severity
@@ -179,17 +168,10 @@ export function readBasaltConfig(cwd: string): BasaltConfig {
 }
 
 /**
- * Extensions the walker collects. `html?`/`webmanifest` close argo's finding that raw hex ships in
- * `index.html`'s `theme-color` and the webmanifest's `theme_color`/`background_color` — the two
- * places whose colors nothing re-derives on a scheme change, and which the scan never reached.
- *
- * `astro`/`jsx`/`vue` close the same gap one component layer up. rollhook's marketing site is
- * Astro: `apps/marketing/src` holds two `.astro` templates that are its ENTIRE markup layer, and
- * check-theme reported a clean 4-file scan without ever opening either. The colour and typography
- * kinds apply to them exactly as they do to `.html`, which was already scanned; `.jsx` and `.vue`
- * were missing from the same regex, so a plain-JS or Vue consumer was unguarded end to end.
+ * Extensions the walker collects: source (`.astro`/`.jsx`/`.vue` and the `.mjs`/`.cjs`/`.mts`/`.cts`
+ * module spellings) plus `html?`/`webmanifest`, where raw hex ships in `theme-color` and friends.
  */
-const SCANNABLE_EXT = /\.(?:tsx?|jsx|astro|vue|css|html?|webmanifest)$/
+const SCANNABLE_EXT = /\.(?:tsx?|jsx|[cm][jt]s|astro|vue|css|html?|webmanifest)$/
 
 /**
  * Recursively collect scannable files under a root, skipping dependency/build dirs. Node+Bun-safe.
@@ -236,14 +218,10 @@ export function relativePosix(fromDir: string, toPath: string): string {
 }
 
 /**
- * Where `basalt-ui` actually resolves from, seen from a consumer directory.
- *
- * Every seam basalt seeds (oxlint/lefthook `extends`, the CI `run:` steps) used to hardcode
- * `./node_modules/basalt-ui` at the repo ROOT; under bun's isolated linker a package that declares
- * basalt a peer + devDependency gets it at `<pkg>/node_modules` and NOTHING at the root, so all three
- * silently failed to resolve and `bunx` fetched a second, different copy. Resolution therefore walks
- * OUTWARD from the consumer dir, then across the workspace packages — and every caller renders its
- * paths from the answer rather than assuming the root.
+ * Where `basalt-ui` actually resolves from, seen from a consumer directory. Under bun's isolated
+ * linker a package that declares basalt gets it at `<pkg>/node_modules` and nothing at the root, so
+ * resolution walks OUTWARD from the consumer dir, then across workspace packages, and every caller
+ * renders its paths from the answer rather than assuming the root.
  */
 export type BasaltInstall = {
   /** Absolute path of the resolved `node_modules/basalt-ui` directory, or null when unresolvable. */
@@ -303,14 +281,9 @@ export function shippedAssetPath(install: BasaltInstall, fromDir: string, asset:
 }
 
 /**
- * Which directory a project-scoped command (`check-theme`, `doctor`) should actually read.
- *
- * One resolver, nothing inferred: `BASALT_CWD` when set, else the invocation cwd. A monorepo
- * package whose install lives elsewhere sets `BASALT_CWD` explicitly (or the invoking script's
- * `root:`/`cwd` does) rather than relying on workspace-glob discovery or an ancestor/descendant
- * walk — both were deleted (see `resolveProjectDir`'s own doc below) as multi-repo speculation for
- * a single-owner fleet where every consumer already runs its own commands from its own directory.
- * The scan scope within that directory is `basalt.roots` in `package.json` (default `src`).
+ * Which directory a project-scoped command (`check-theme`, `doctor`) reads: `BASALT_CWD` when set,
+ * else the invocation cwd. Nothing is inferred (workspace discovery was deleted). The scan scope
+ * within it is `basalt.roots` in `package.json` (default `src`).
  */
 type ProjectResolution = {
   /** The directory to read. Equals the invocation cwd unless BASALT_CWD relocated it. */
@@ -338,7 +311,7 @@ export function resolveProjectDir(cwd: string): ProjectResolution {
 /**
  * Which shape of consumer a project-scoped command is looking at — DECLARED, never inferred
  * (`--tokens-only`, or `"basalt": { "profile": "tokens-only" }`), because the answer switches the
- * Mantine-remedy guard kinds off. Why that direction: package CLAUDE.md § CLI.
+ * Mantine-remedy guard kinds off. Why that direction: package MAINTAINING.md § CLI.
  */
 export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
   if (flags.includes('--tokens-only')) return 'tokens-only'
@@ -398,15 +371,9 @@ export function scannableFiles(cwd: string, cfg: BasaltConfig): string[] {
 }
 
 /**
- * The app-shell files that sit BESIDE a source root rather than inside it — `index.html` and
- * anything under `public/`.
- *
- * Widening the walker's extension filter alone would still have missed every one of them: argo
- * configures `roots: ['apps/dashboard/src']`, while the raw hex lives in `apps/dashboard/index.html`
- * and `apps/dashboard/public/site.webmanifest`. Both locations are the Vite convention basalt's own
- * `basaltViteConfig`/`basaltAppPlugin` assume, so deriving them from each root's parent needs no
- * config and holds for a monorepo package the same way it holds at a repo root. Nothing else in the
- * parent is walked — a sibling `docs/` full of throwaway HTML stays unscanned.
+ * The app-shell files that sit BESIDE a source root rather than inside it: `index.html` and anything
+ * under `public/` (argo's raw hex lives in `apps/dashboard/index.html`, with `roots` on `…/src`).
+ * Nothing else in the parent is walked.
  */
 function appShellFiles(rootAbs: string): string[] {
   const appDir = dirname(rootAbs)
@@ -447,23 +414,14 @@ export function waiverHintFor(relPath: string, profile: DoctorProfile): string {
 // ──────────────────────────────────────────────────────────────────────────────
 
 /**
- * How a file the framework writes into a consumer repo is owned. Two modes, one question:
- * **does Claude read this file?**
+ * How a file the framework writes into a consumer repo is owned:
+ * - `managed`: basalt owns it (what Claude reads: .claude/rules/*, .claude/skills/*, the AGENTS.md
+ *   block). sync refreshes it; a local edit is skipped and reported (`--force` overwrites); `--check`
+ *   exits 1 on drift.
+ * - `seed`: written once if absent, then the consumer's. sync never overwrites it or reports drift.
  *
- * - `managed` : basalt owns it. sync refreshes it to the shipped version; a local edit is skipped
- *               and reported (`--force` overwrites); `--check` exits 1 on drift. Applies to exactly
- *               what Claude reads (.claude/rules/*, .claude/skills/*, the CLAUDE.md block) —
- *               Claude Code cannot load rules or skills from node_modules, and that platform limit
- *               is the only reason anything is copied at all. The sync diff is the review gate.
- * - `seed`    : written once if absent, then owned entirely by the consumer. sync never overwrites
- *               it and never reports drift (a starting point, not a managed mirror). Everything a
- *               machine reads is a seed, and a good seed's content is a REFERENCE (`extends` into
- *               node_modules/basalt-ui/configs/*), not a copy, so the toolchain auto-updates with
- *               the package while the consumer still owns the file.
- *
- * A managed file with `markers: true` is spliced as a `<!-- basalt:begin -->…<!-- basalt:end -->`
- * region inside a host file the consumer otherwise owns (CLAUDE.md) — not a third mode, just
- * managed ownership scoped to a region.
+ * `markers: true` splices a managed `<!-- basalt:begin -->…<!-- basalt:end -->` region into a host
+ * file the consumer otherwise owns (AGENTS.md).
  */
 type Mode = 'managed' | 'seed'
 
@@ -518,19 +476,26 @@ type TemplateVars = {
   BASALT_BIN: string
 }
 
-// The block markers the CLAUDE.md template emits. The begin marker carries the framework version
+// The block markers the AGENTS.md template emits. The begin marker carries the framework version
 // (`<!-- basalt:begin 1.0.0 -->`), so the region is matched by the begin PREFIX, not an exact string.
 const BLOCK_BEGIN_PREFIX = '<!-- basalt:begin'
 const BLOCK_END = '<!-- basalt:end -->'
 export const MANIFEST_PATH = '.basalt/manifest.json'
+/** The host file the managed block is spliced into (and its manifest key). */
+export const AGENTS_MD = 'AGENTS.md'
+/** A `CLAUDE.md` shadows {@link AGENTS_MD} unless it imports it — `doctor` warns on one. */
+export const LEGACY_BLOCK_HOST = 'CLAUDE.md'
 
 export function sha256(text: string): string {
   return createHash('sha256').update(text, 'utf8').digest('hex')
 }
 
 export function readIfExists(abs: string): string | null {
-  if (!existsSync(abs)) return null
-  return readFileSync(abs, 'utf8')
+  try {
+    return readFileSync(abs, 'utf8')
+  } catch {
+    return null // absent, a directory, unreadable or raced away: callers treat all four as "not there"
+  }
 }
 
 /** Read a shipped source asset from the package root; null if the sibling hasn't authored it yet. */
@@ -561,14 +526,9 @@ export function readFrameworkVersion(pkgRoot: string): string {
 }
 
 /**
- * How a seeded script, a seeded CI step, or a piece of doctor advice should invoke the CLI.
- *
- * The LOCAL bin wherever basalt actually resolved; `bunx basalt-ui` only as the pre-install
- * fallback. `bunx` does not re-resolve a package it has cached, so a seeded `bunx basalt-ui` lets a
- * consumer pin one version and be gated by another — which is exactly what happened across three
- * consumer repos, in CI, in package.json scripts and in a `.claude` PreToolUse hook, all of them
- * placed here. Every emitted invocation goes through this function so there is one place for it to
- * be right.
+ * How a seeded script, CI step or piece of doctor advice invokes the CLI: the LOCAL bin wherever
+ * basalt resolved, `bunx basalt-ui` only as the pre-install fallback (`bunx` does not re-resolve a
+ * cached package, so it lets a consumer pin one version and be gated by another).
  */
 export function basaltBinCommand(install: BasaltInstall, cwd: string): string {
   if (install.dir === null) return 'bunx basalt-ui'
@@ -633,19 +593,66 @@ function applyBlock(host: string, block: string): string {
   return base.length === 0 ? `${block.trim()}\n` : `${base}\n\n${block.trim()}\n`
 }
 
+/** True when both paths resolve to one file (a symlinked pair). A missing path is simply "no". */
+export function sameFile(a: string, b: string): boolean {
+  try {
+    return realpathSync(a) === realpathSync(b)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** True when the host text carries a managed block (begin marker present). */
+export function hasManagedBlock(host: string | null): boolean {
+  return host !== null && host.includes(BLOCK_BEGIN_PREFIX)
+}
+
 /**
- * Explicit `--with-router` / `--with-query` CLI flags force-include a router/query scaffold even
- * when the peer isn't detected in the consumer's package.json yet (e.g. it's about to be added).
+ * The block region of a host, or why it cannot be read: duplicate begin markers, or a begin marker
+ * with no end. Read by `doctor` to say whether a leftover `CLAUDE.md` is well-formed.
  */
-export type ScaffoldFlags = {
-  withRouter?: boolean
-  withQuery?: boolean
-  /** `--merge-lint`: splice the shipped preset's `extends` into an `.oxlintrc.json` init would keep. */
-  mergeLint?: boolean
+export function scanBlock(host: string): {
+  region: { start: number; end: number } | null
+  problem: string | null
+} {
+  const begin = hasManagedBlock(host)
+  if (!begin && !host.includes(BLOCK_END)) return { region: null, problem: null }
+  const bad = (problem: string): { region: null; problem: string } => ({ region: null, problem })
+  if (!begin) return bad(`\`${BLOCK_END}\` with no \`${BLOCK_BEGIN_PREFIX}\``)
+  let region: { start: number; end: number } | null
+  try {
+    region = findBlockRegion(host)
+  } catch (error) {
+    return bad((error as Error).message)
+  }
+  if (region === null) return bad(`\`${BLOCK_BEGIN_PREFIX}\` has no matching \`${BLOCK_END}\``)
+  // Exactly one end marker, after the begin: an orphan or extra one means the region is a guess.
+  if (host.indexOf(BLOCK_END) < region.start || host.indexOf(BLOCK_END, region.end) !== -1) {
+    return bad(`an extra or misplaced \`${BLOCK_END}\` outside the basalt block`)
+  }
+  return { region, problem: null }
 }
 
-/** Router/query peer presence, resolved from detection + explicit flags. */
-export type PeerFlags = { hasRouter: boolean; hasQuery: boolean }
+/** One line that is exactly the `@AGENTS.md` import — not a prose or code-span mention, not `.bak`. */
+export function isAgentsImportLine(line: string): boolean {
+  return line.trim() === `@${AGENTS_MD}`
+}
+
+/** Whether a `CLAUDE.md` imports `AGENTS.md`, so Claude Code still loads it. */
+export function importsAgentsMd(text: string): boolean {
+  return text.split(/\r?\n/).some(isAgentsImportLine)
+}
+
+/** Scaffold options. `noMergeLint`: `--no-merge-lint` leaves an existing `.oxlintrc.json` untouched. */
+export type ScaffoldFlags = { noMergeLint?: boolean }
+
+/** The router seeds (TanStack Router and Query are required peers of `.`, so they are always written). */
+export const ROUTER_SEED_DESTS = {
+  nav: 'src/lib/nav.tsx',
+  root: 'src/routes/__root.tsx',
+  main: 'src/main.tsx',
+} as const
 
 /** True when `pkgName` appears in the consumer's dependencies, devDependencies, or peerDependencies. */
 function hasDependency(cwd: string, pkgName: string): boolean {
@@ -665,19 +672,6 @@ function hasDependency(cwd: string, pkgName: string): boolean {
   }
 }
 
-/**
- * Resolves whether the consumer has the optional TanStack router/query peers — auto-detected from
- * package.json, or forced via `--with-router` / `--with-query`. Both `basalt-ui init` (for gating
- * which seed scaffolds to write) and `basalt-ui sync` (so it doesn't silently re-seed a scaffold whose
- * peer was never installed) call this once, up front.
- */
-export function resolvePeerFlags(cwd: string, flags: ScaffoldFlags): PeerFlags {
-  return {
-    hasRouter: flags.withRouter === true || hasDependency(cwd, '@tanstack/react-router'),
-    hasQuery: flags.withQuery === true || hasDependency(cwd, '@tanstack/react-query'),
-  }
-}
-
 /**
  * Where the seed engine is running relative to the consumer's git repo — decides which
  * repo-root-shaped seeds are safe to write. `init`/`sync` compute it once per run via
@@ -693,18 +687,12 @@ export type PlacementFlags = {
   /** Absolute path of the detected repo root. Meaningful only when `isPackageRepoRoot` is false —
    *  otherwise it equals the package dir and is never read. */
   repoRoot: string
-  /** Absolute path of a `query-client.ts` already present elsewhere under the package's `src/` (the
-   *  consumer relocated it — e.g. to `src/lib/query-client.ts`), or null. The seed's OWN
-   *  destination is deliberately excluded here — that exact-path case is handled by the ordinary
-   *  skip-if-exists logic every seed file already goes through, unchanged. */
-  relocatedQueryClient: string | null
 }
 
 /** The default placement — today's single-package-at-repo-root behaviour, unconditionally. */
 export const ROOT_PLACEMENT: PlacementFlags = {
   isPackageRepoRoot: true,
   repoRoot: '',
-  relocatedQueryClient: null,
 }
 
 /**
@@ -734,63 +722,17 @@ export function oxlintBinResolves(dir: string): boolean {
   }
 }
 
-/**
- * First path under `dir` (recursive) whose basename is `filename`, or null. Skips dependency/build
- * dirs, mirroring `walkSourceFiles`'s scoping.
- */
-function findFileNamed(dir: string, filename: string): string | null {
-  let entries: string[]
-  try {
-    entries = readdirSync(dir)
-  } catch {
-    return null
-  }
-  for (const name of entries) {
-    if (name === 'node_modules' || name === '.git' || name === 'dist') continue
-    const abs = resolve(dir, name)
-    let isDir: boolean
-    try {
-      isDir = statSync(abs).isDirectory()
-    } catch {
-      continue
-    }
-    if (isDir) {
-      const found = findFileNamed(abs, filename)
-      if (found !== null) return found
-    } else if (name === filename) {
-      return abs
-    }
-  }
-  return null
-}
-
-/**
- * Absolute path of a `query-client.ts` living elsewhere under the package's `src/`, or null. The
- * seed's own destination is excluded — reseeding on top of a RELOCATED client (the failure this
- * exists to prevent) is a different case from the seed's own path already being occupied, which the
- * ordinary skip-if-exists logic handles unchanged.
- */
-function findRelocatedQueryClient(cwd: string): string | null {
-  const seedAbs = resolve(cwd, 'src/query-client.ts')
-  const found = findFileNamed(resolve(cwd, 'src'), 'query-client.ts')
-  return found !== null && found !== seedAbs ? found : null
-}
-
 /** Resolve a run's placement flags once, from the consumer cwd. */
 export function resolvePlacement(cwd: string): PlacementFlags {
   const repoRoot = findRepoRoot(cwd)
   return {
     isPackageRepoRoot: repoRoot === cwd,
     repoRoot,
-    relocatedQueryClient: findRelocatedQueryClient(cwd),
   }
 }
 
 /** The full managed-file manifest. Stable, declarative — the single source of truth for init/sync. */
-export function managedFiles(
-  peers: PeerFlags,
-  placement: PlacementFlags = ROOT_PLACEMENT,
-): ManagedFile[] {
+export function managedFiles(placement: PlacementFlags = ROOT_PLACEMENT): ManagedFile[] {
   // ── managed: exactly what Claude reads ──────────────────────────────────────
   const rules: ManagedFile[] = RULE_NAMES.map((name) => ({
     dest: `.claude/rules/basalt-${name}.md`,
@@ -809,15 +751,17 @@ export function managedFiles(
     render: (ctx: RenderContext) => readSource(ctx.pkgRoot, `agent/skills/${name}/SKILL.md`),
   }))
 
-  const claudeBlock: ManagedFile = {
-    dest: 'CLAUDE.md',
+  // AGENTS.md, not CLAUDE.md: Claude Code loads a repo-root AGENTS.md directly, but ANY CLAUDE.md
+  // in or above the cwd suppresses it — so the block must not be the reason a CLAUDE.md exists.
+  const agentsBlock: ManagedFile = {
+    dest: AGENTS_MD,
     mode: 'managed',
     markers: true,
-    source: 'agent/templates/CLAUDE-block.md.tpl',
+    source: 'agent/templates/AGENTS-block.md.tpl',
     // With markers, render() returns the fully-rendered region INCLUDING its begin/end markers.
-    // The writer splices it into the consumer's host CLAUDE.md at apply time.
+    // The writer splices it into the consumer's host AGENTS.md at apply time.
     render: (ctx) => {
-      const tpl = readSource(ctx.pkgRoot, 'agent/templates/CLAUDE-block.md.tpl')
+      const tpl = readSource(ctx.pkgRoot, 'agent/templates/AGENTS-block.md.tpl')
       if (tpl === null) return null
       return fillTemplate(tpl, ctx.vars).trim()
     },
@@ -908,21 +852,9 @@ export function managedFiles(
   // ── Seed scaffolds: written by init, never overwritten by sync ─────────────
   // These are starting-point files owned entirely by the consumer after first write.
 
-  /** TanStack Query client bootstrap (seed — consumer-owned after init). */
-  const queryClient: ManagedFile = {
-    dest: 'src/query-client.ts',
-    mode: 'seed',
-    source: 'agent/templates/query-client.ts.tpl',
-    render: (ctx) => {
-      const tpl = readSource(ctx.pkgRoot, 'agent/templates/query-client.ts.tpl')
-      if (tpl === null) return null
-      return fillTemplate(tpl, ctx.vars)
-    },
-  }
-
   /** TanStack Router root route with QueryClient context wiring (seed — consumer-owned after init). */
   const rootRoute: ManagedFile = {
-    dest: 'src/routes/__root.tsx',
+    dest: ROUTER_SEED_DESTS.root,
     mode: 'seed',
     source: 'agent/templates/__root.tpl',
     render: (ctx) => {
@@ -932,13 +864,22 @@ export function managedFiles(
     },
   }
 
-  // `query-client.ts` only needs @tanstack/react-query; `__root.tsx` imports BOTH
-  // @tanstack/react-router (createRootRouteWithContext) and @tanstack/react-query (the QueryClient
-  // type) — both are documented optional peers, so seeding either scaffold without its peer(s)
-  // installed would ship a file with an unresolved import.
-  const scaffolds: ManagedFile[] = []
-  if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient)
-  if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute)
+  /** The leaf `NAV` module `__root.tsx` imports (seed — consumer-owned after init). */
+  const navModule: ManagedFile = {
+    dest: ROUTER_SEED_DESTS.nav,
+    mode: 'seed',
+    source: 'agent/templates/nav.tpl',
+    render: (ctx) => readSource(ctx.pkgRoot, 'agent/templates/nav.tpl'),
+  }
+
+  /** The 2.0 entry: mounts the router and declares the `Register` augmentation `defineNav` needs. */
+  const mainEntry: ManagedFile = {
+    dest: ROUTER_SEED_DESTS.main,
+    mode: 'seed',
+    source: 'agent/templates/main.tpl',
+    render: (ctx) => readSource(ctx.pkgRoot, 'agent/templates/main.tpl'),
+  }
+  const scaffolds: ManagedFile[] = [navModule, rootRoute, mainEntry]
 
   // lefthook.yml / .github/workflows/check.yml are repo-root-shaped: lefthook and GitHub Actions
   // only ever read config at the repo root, so a package living in a subdirectory (a monorepo's
@@ -946,7 +887,7 @@ export function managedFiles(
   // lefthook/CI config, and writing over or beside it is worse than not writing at all.
   const rootTooling: ManagedFile[] = placement.isPackageRepoRoot ? [lefthook, ci] : []
 
-  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
+  return [...rules, ...skills, agentsBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
 /**
@@ -977,13 +918,6 @@ export function placementNotices(cwd: string, placement: PlacementFlags): string
         'performs for lefthook, and needed for the same reason.',
     )
   }
-  if (placement.relocatedQueryClient !== null) {
-    out.push(
-      `skipped src/query-client.ts (found an existing query client at ` +
-        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
-        're-seeding at the original path.',
-    )
-  }
   return out
 }
 
@@ -994,16 +928,9 @@ export type Manifest = {
   /** dest path → sha256 of the managed unit (file bytes, block body, or stanza) at last write. */
   files: Record<string, string>
   /**
-   * The resolved level-0 spacing scale (`xs`..`xl`, px) at last write — `doctor`'s second
-   * reconciliation axis, and the only one that reports a change in RENDERED OUTPUT rather than in
-   * placed files.
-   *
-   * A retune of the spacing bases moves every surface in every consumer calling
-   * `createBasaltTheme()` bare. basalt-ui bans majors by design, so the changelog is the only
-   * channel that carries that, and a one-line `feat:` subject cannot convey blast radius: the
-   * 1.2.0 retune shipped as "tighten the sidebar, open up components" and went unverified in
-   * production for a day because nothing said "every padding moved". Recording the scale makes the
-   * move mechanically visible on the next `doctor` run instead of depending on a subject line.
+   * The resolved level-0 spacing scale (`xs`..`xl`, px) at last write: `doctor`'s second axis, and
+   * the only one that reports a change in RENDERED OUTPUT. A retune of the spacing bases moves every
+   * surface in every consumer, which a one-line `feat:` subject cannot convey.
    */
   spacingScale?: Record<string, number>
 }
@@ -1042,8 +969,7 @@ export function readManifest(cwd: string): Manifest {
  *
  * Scoped to these two patterns on purpose, and never applied to the manifest wholesale: several
  * managed/seed entries are legitimately absent from `managedFiles()` for a run (`lefthook.yml` and
- * `check.yml` when the package is not the repo root, `src/query-client.ts` when it was relocated,
- * the scaffolds without their peers). Deleting a dest just because this run did not place it would
+ * `check.yml` when the package is not the repo root). Deleting a dest just because this run did not place it would
  * remove a consumer's CI workflow on a monorepo.
  */
 const RETIREABLE_DEST_PATTERNS: readonly RegExp[] = [
@@ -1088,17 +1014,9 @@ export function reportPrune(pruned: PruneResult): void {
 
 /**
  * Delete the managed rule/skill files this basalt version retired, and drop their manifest entries.
- *
- * The 13→6 rule merge (`docs/CONTROLS-SPEC.md` §7) is the case this exists for: nine
- * `.claude/rules/basalt-*.md` files stopped shipping in one minor, and without this a consumer's
- * agent would go on reading `basalt-router.md`'s superseded placement doctrine forever, with
- * `sync --check` reporting green because nothing in the ledger asks about a dest the run no longer
- * places.
- *
- * Same three-way discipline as every other managed unit, so a consumer edit is never discarded
- * silently: an untouched file (matching its recorded hash, raw or normalized) is deleted and its
- * entry dropped; a locally-edited one is LEFT in place, reported, and keeps its entry so
- * `sync --check` stays red and `--force` can still finish the job. `dryRun` is `--check`.
+ * Same three-way discipline as every managed unit: an untouched file is deleted; a locally-edited
+ * one is LEFT in place, reported, and keeps its entry so `sync --check` stays red and `--force` can
+ * finish. `dryRun` is `--check`.
  */
 export function pruneRetiredManagedFiles(
   cwd: string,
@@ -1187,25 +1105,9 @@ export function unitState(file: ManagedFile, cwd: string, ctx: RenderContext): U
 type Classification = 'unchanged' | 'drifted' | 'missing' | 'current'
 
 /**
- * Normalize a managed unit's rendered bytes for the ledger comparison below — makes a delta that is
- * PURELY formatting or a version bump invisible to drift detection, while a real prose/content edit
- * stays fully visible:
- *
- *  - Blank out the per-release `BASALT_VERSION` token in a marker's begin line
- *    (`<!-- basalt:begin 1.0.1 -->` → `<!-- basalt:begin -->`). It changes on every release and is
- *    the only per-release variable that lands INSIDE the hashed region (the rest of
- *    `CLAUDE-block.md.tpl` has no other `{{…}}` placeholders today), so stripping it is what lets
- *    one normalized rendering stand in for every version of a given template body instead of
- *    needing one ledger entry per release. If a future marker template interpolates another
- *    per-release var inside its region, extend this normalization the same way.
- *  - Trim trailing whitespace per line and collapse every run of blank lines to none. This is the
- *    fix for the actual argo repro: lefthook's oxfmt reformats a spliced block (or a whole managed
- *    file) AFTER `writeUnit` has already exited and the manifest hash was recorded, so the manifest
- *    can never account for the reformat up front — normalizing it away here is the only place that
- *    can.
- *
- * Deliberately whitespace-only — word content is untouched, so a genuine hand-edit inside the block
- * still changes the normalized text and still classifies `drifted`.
+ * Normalize a managed unit's rendered bytes for the ledger comparison: blank the per-release version
+ * in a marker's begin line, trim trailing whitespace per line and collapse blank-line runs. A
+ * formatter run or a version bump is invisible to drift detection; a real content edit is not.
  */
 export function normalizeForLedger(text: string): string {
   return text
@@ -1235,21 +1137,12 @@ export function writeUnit(file: ManagedFile, cwd: string, desired: string): stri
 }
 
 /**
- * Classify a managed file against the manifest for a sync run.
- * - missing  : the managed unit is absent on disk → recreate.
+ * Classify a managed file against the manifest for a sync run:
+ * - missing  : absent on disk → recreate.
  * - current  : on disk == desired → nothing to do.
- * - unchanged: on disk matches a KNOWN-SHIPPED rendering of this template (any one is sufficient) —
- *              but != desired as-is → safe overwrite:
- *              1. `sha256(current) === manifestHash` — legacy raw-hash path (manifests written before
- *                 the ledger normalized hold the RAW hash; keep matching so an upgrade never
- *                 mass-classifies a pristine tree as drifted).
- *              2. `sha256(normalizeForLedger(current)) === manifestHash` — the ledger proper (see
- *                 `writeUnit`): survives a downstream formatter AND a version bump that changed the
- *                 template's own words since the manifest entry was written (the argo false positive).
- *              3. `normalizeForLedger(current) === normalizeForLedger(desired)` — same-version
- *                 fallback when no manifest entry exists at all.
- * - drifted  : on disk matches NONE of the above (a real, word-level local edit) → skip unless
- *              --force.
+ * - unchanged: on disk matches a KNOWN-SHIPPED rendering (raw manifest hash, normalized manifest
+ *              hash, or normalized == normalized desired when no entry exists) → safe overwrite.
+ * - drifted  : matches none of them (a real local edit) → skip unless --force.
  */
 export function classify(state: UnitState, manifestHash: string | undefined): Classification {
   if (state.current === null) return 'missing'
@@ -1348,19 +1241,9 @@ function rootCovers(root: string, detected: string): boolean {
 }
 
 /**
- * Read — and when absent and `write` is set, seed — `basalt.roots`.
- *
- * Shared by `init` and `sync` because the key going missing is the SAME false green in both: the
- * built-in `src` default happens to resolve from a package cwd, so `guard-scan` passes, `check-theme`
- * scans something, and the repo is silently guarding a subset of itself. `init` wrote it and `sync`
- * did not — which meant the fix reached new scaffolds only, while every existing consumer (the ones
- * who by definition upgrade rather than scaffold) stayed on the undeclared default.
- *
- * A DECLARED value is never overwritten, not even when the layout disagrees with it. `roots` is a
- * subset by construction in a monorepo — a React-free package deliberately left out is the normal
- * case, not drift — so a disagreement is reported as one line naming what is not covered, and the
- * consumer decides. Silently widening someone's deliberate scope would turn an upgrade into an
- * unplanned lint debt.
+ * Read — and when absent and `write` is set, seed — `basalt.roots`. Shared by `init` and `sync`: a
+ * missing key silently guards a subset of the repo. A DECLARED value is never overwritten (a subset
+ * is normal in a monorepo); a disagreement is reported as one line and the consumer decides.
  */
 export function reconcileRoots(cwd: string, opts: { write: boolean }): RootsState {
   const declared = readBasaltConfig(cwd).roots
@@ -1423,13 +1306,8 @@ export function rootsNotices(state: RootsState): { log: string[]; error: string[
 }
 
 /**
- * Strip JSONC comments (and trailing commas) so `.oxlintrc.json` can be READ. oxlint accepts JSONC
- * and real consumer configs use it — a plain `JSON.parse` there reported "not valid JSON" on a
- * perfectly good config. String-aware, so a `//` inside a value survives.
- *
- * Only ever used for reading. The trailing-comma pass is a plain regex and could in principle mangle
- * a `, }` sequence inside a string; the failure direction is a parse error, which the caller already
- * treats as "cannot tell", never as "passes".
+ * Strip JSONC comments and trailing commas so oxlint/tsconfig files can be READ (string-aware). A
+ * mangled string fails as a parse error, which callers treat as "cannot tell", never as a pass.
  */
 function stripJsonc(text: string): string {
   let out = ''
@@ -1460,7 +1338,7 @@ function stripJsonc(text: string): string {
 /** Parse a JSONC document, or null when it does not parse at all. */
 export function parseJsonc(text: string): Record<string, unknown> | null {
   try {
-    return JSON.parse(stripJsonc(text)) as Record<string, unknown>
+    return JSON.parse(stripJsonc(text.replace(/^\uFEFF/, ''))) as Record<string, unknown>
   } catch {
     return null
   }
@@ -1557,11 +1435,13 @@ export function inspectLefthookGate(repoRoot: string): LefthookGate {
   return wired ? { kind: 'wired', file } : { kind: 'absent', file }
 }
 
+const ONLY_EXPORT_COMPONENTS = 'react/only-export-components'
+
 /**
- * Splice the shipped preset into an EXISTING `.oxlintrc.json` (`init --merge-lint`). Opt-in, not
- * automatic: turning the framework on adds real lint debt to previously-clean code (see the
- * lint-debt notice `init` prints), and that is a decision, not a scaffold step. Prepends the preset
- * so the consumer's own `extends` entries still win.
+ * Splice the shipped preset into an EXISTING `.oxlintrc.json` (`init` does this unless
+ * `--no-merge-lint`; the lint-debt notice says what it switches on). Prepends the preset so the
+ * consumer's own `extends` entries still win. Only `extends` is rewritten; the config's own `plugins`
+ * are untouched, and oxlint (1.87, checked with `--print-config`) unions them with the preset's.
  */
 export function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintResult {
   const abs = resolve(cwd, '.oxlintrc.json')
@@ -1583,6 +1463,16 @@ export function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintRe
   for (const [key, value] of Object.entries(cfg)) {
     merged[key] = key === 'extends' ? [presetPath, ...existing] : value
   }
+  // A consumer-set only-export-components (create-vite) replaces the preset's options: re-add `Route`.
+  const rules = merged['rules'] as Record<string, unknown> | undefined
+  if (rules !== undefined && ONLY_EXPORT_COMPONENTS in rules) {
+    const [level, options] = [rules[ONLY_EXPORT_COMPONENTS]].flat()
+    const opts = (typeof options === 'object' && options !== null ? options : {}) as {
+      allowExportNames?: string[]
+    }
+    const allowExportNames = [...new Set([...(opts.allowExportNames ?? []), 'Route'])]
+    rules[ONLY_EXPORT_COMPONENTS] = [level, { ...opts, allowExportNames }]
+  }
   const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? '  '
   writeFileSync(abs, JSON.stringify(merged, null, indent) + (raw.endsWith('\n') ? '\n' : ''))
   return 'added'
@@ -1772,10 +1662,7 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
     console.log(USAGE)
     return 0
   }
-  // Before dispatch, for the same reason --help is: this answers "which basalt-ui is running" and
-  // must never run a command to do it. `bunx` does not re-resolve a cached package, so a consumer
-  // can pin 1.23.0, invoke `bunx basalt-ui`, and be gated by a months-old copy — the version is the
-  // only thing that catches it, and it has to be one bare line an agent can compare.
+  // Before dispatch, like --help: it answers "which basalt-ui is running" as one bare line.
   if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
     console.log(readFrameworkVersion(packageRoot()))
     return 0
@@ -1794,9 +1681,7 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
   switch (cmd) {
     case 'init':
       return init(cwd, {
-        withRouter: flags.includes('--with-router'),
-        withQuery: flags.includes('--with-query'),
-        mergeLint: flags.includes('--merge-lint'),
+        noMergeLint: flags.includes('--no-merge-lint'),
       })
     case 'sync':
       return sync(