basalt-ui 1.41.0 → 2.0.1

package/src/cli/index.ts

@@ -57,9 +57,7 @@ const GUARD_PASSTHROUGH = {
   rawHtmlLayout: true,
   inlineSpacing: true,
   inlineDisplay: true,
-  rawVisxAxis: true,
   rawMotionValue: true,
-  chartMissingAriaLabel: true,
   rawFormControl: true,
   sub16InputFont: true,
   severity: true,
@@ -85,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
@@ -126,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
@@ -180,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.
@@ -237,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. */
@@ -304,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. */
@@ -399,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)
@@ -448,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?**
- *
- * - `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 AGENTS.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.
+ * 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.
  *
- * A managed file with `markers: true` is spliced as a `<!-- basalt:begin -->…<!-- basalt:end -->`
- * region inside a host file the consumer otherwise owns (AGENTS.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'
 
@@ -526,7 +483,7 @@ 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'
-/** Where the block lived before it moved to {@link AGENTS_MD} — read only to migrate out of it. */
+/** 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 {
@@ -534,8 +491,11 @@ export function sha256(text: string): string {
 }
 
 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. */
@@ -566,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'
@@ -655,8 +610,7 @@ export function hasManagedBlock(host: string | null): boolean {
 
 /**
  * The block region of a host, or why it cannot be read: duplicate begin markers, or a begin marker
- * with no end. The ONE detector `migrateBlockToAgentsMd` and `doctor` share, so they cannot disagree
- * about whether a `CLAUDE.md` is well-formed.
+ * with no end. Read by `doctor` to say whether a leftover `CLAUDE.md` is well-formed.
  */
 export function scanBlock(host: string): {
   region: { start: number; end: number } | null
@@ -690,117 +644,15 @@ export function importsAgentsMd(text: string): boolean {
   return text.split(/\r?\n/).some(isAgentsImportLine)
 }
 
-export type BlockMigration = {
-  /** The legacy host (`CLAUDE.md`) carried a managed block that has to move. */
-  pending: boolean
-  /** The legacy host was left empty (or `@AGENTS.md` only) and removed. */
-  deletedHost: boolean
-  /** Why nothing was moved and the run must fail: malformed markers, or two differing blocks. */
-  problem: string | null
-}
-
-/**
- * Move the managed block out of `CLAUDE.md` into `AGENTS.md` (an install from before the move).
- * Idempotent: a second run finds nothing and returns `pending: false`.
- *  1. The ledger entry is re-keyed `CLAUDE.md` → `AGENTS.md` in memory (the caller persists it), so
- *     an unedited legacy block classifies `unchanged`, not untracked.
- *  2. The region is cut out of `CLAUDE.md` and — unless `AGENTS.md` already has one — spliced into
- *     `AGENTS.md` AS IT IS, not as the new rendering: the normal three-way classify then sees a
- *     hand-edit and skips it like any drifted unit. The rest of `CLAUDE.md` is consumer-owned and
- *     stays, except the file is deleted when nothing but whitespace or `@AGENTS.md` is left.
- *  3. Nothing is discarded silently: if `AGENTS.md` already has a block that differs (normalized,
- *     as the ledger compares) from the legacy one, or either file's markers are malformed, BOTH
- *     files are left byte-identical and `problem` says what to resolve by hand.
- * `dryRun` (`sync --check`) writes nothing but still reports `pending` and `problem`.
- */
-export function migrateBlockToAgentsMd(
-  cwd: string,
-  manifest: Manifest,
-  opts: { dryRun?: boolean } = {},
-): BlockMigration {
-  const legacyHash = manifest.files[LEGACY_BLOCK_HOST]
-  if (legacyHash !== undefined) {
-    manifest.files[AGENTS_MD] ??= legacyHash
-    delete manifest.files[LEGACY_BLOCK_HOST]
-  }
-  const none: BlockMigration = { pending: false, deletedHost: false, problem: null }
-  const legacyAbs = resolve(cwd, LEGACY_BLOCK_HOST)
-  const agentsAbs = resolve(cwd, AGENTS_MD)
-  const legacy = readIfExists(legacyAbs)
-  if (legacy === null) return none
-  // A symlinked pair is one file: cutting the block out of "CLAUDE.md" would cut AGENTS.md too.
-  // Fail closed when that cannot be proven (EACCES, ELOOP, …) — and say so, not a stack trace.
-  try {
-    if (sameFile(legacyAbs, agentsAbs)) return none
-  } catch (error) {
-    const why = (error as NodeJS.ErrnoException).code ?? (error as Error).message
-    return { ...none, problem: `cannot tell whether ${LEGACY_BLOCK_HOST} is ${AGENTS_MD} (${why})` }
-  }
-  const legacyScan = scanBlock(legacy)
-  const { region } = legacyScan
-  if (legacyScan.problem !== null) {
-    return { ...none, problem: `${LEGACY_BLOCK_HOST}: ${legacyScan.problem}` }
-  }
-  if (region === null) return none
-
-  const agents = readIfExists(agentsAbs) ?? ''
-  const agentsScan = scanBlock(agents)
-  if (agentsScan.problem !== null)
-    return { ...none, problem: `${AGENTS_MD}: ${agentsScan.problem}` }
-  const legacyBlock = legacy.slice(region.start, region.end)
-  if (
-    agentsScan.region !== null &&
-    normalizeForLedger(agents.slice(agentsScan.region.start, agentsScan.region.end)) !==
-      normalizeForLedger(legacyBlock)
-  ) {
-    return {
-      ...none,
-      problem:
-        `${LEGACY_BLOCK_HOST} and ${AGENTS_MD} each carry a basalt block and they differ — ` +
-        `delete the stale block from ${LEGACY_BLOCK_HOST} (or the one in ${AGENTS_MD}, if ` +
-        `${LEGACY_BLOCK_HOST}'s is the one you want kept), then re-run.`,
-    }
-  }
-
-  const before = legacy.slice(0, region.start).trimEnd()
-  const after = legacy.slice(region.end).trimStart()
-  const remainder = before === '' || after === '' ? `${before}${after}` : `${before}\n\n${after}`
-  const deletedHost = remainder
-    .split(/\r?\n/)
-    .every((l) => l.trim() === '' || isAgentsImportLine(l))
-  if (opts.dryRun === true) return { pending: true, deletedHost, problem: null }
-
-  if (agentsScan.region === null) writeFileEnsuringDir(agentsAbs, applyBlock(agents, legacyBlock))
-  if (deletedHost) unlinkSync(legacyAbs)
-  else writeFileSync(legacyAbs, `${remainder.trimEnd()}\n`)
-  return { pending: true, deletedHost, problem: null }
-}
-
-/**
- * The refusal `init` and `sync` run BEFORE any side effect (roots patch, package.json script,
- * manifest): a dry-run migration against a scratch manifest, so a block that cannot be moved
- * safely stops the command with nothing written. Null = safe to proceed.
- */
-export function blockMigrationProblem(cwd: string): string | null {
-  const { problem } = migrateBlockToAgentsMd(cwd, { version: 1, files: {} }, { dryRun: true })
-  return problem === null
-    ? null
-    : `${problem.replace(/\.$/, '')}. Nothing else was reconciled — resolve this by hand, then re-run.`
-}
+/** Scaffold options. `noMergeLint`: `--no-merge-lint` leaves an existing `.oxlintrc.json` untouched. */
+export type ScaffoldFlags = { noMergeLint?: boolean }
 
-/**
- * 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).
- */
-export type ScaffoldFlags = {
-  withRouter?: boolean
-  withQuery?: boolean
-  /** `--merge-lint`: splice the shipped preset's `extends` into an `.oxlintrc.json` init would keep. */
-  mergeLint?: boolean
-}
-
-/** Router/query peer presence, resolved from detection + explicit flags. */
-export type PeerFlags = { hasRouter: boolean; hasQuery: 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 {
@@ -820,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
@@ -848,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,
 }
 
 /**
@@ -889,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`,
@@ -1065,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) => {
@@ -1089,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
@@ -1134,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
 }
 
@@ -1151,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>
 }
@@ -1199,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[] = [
@@ -1243,31 +1012,11 @@ export function reportPrune(pruned: PruneResult): void {
   )
 }
 
-/** Name what {@link migrateBlockToAgentsMd} did — a file leaving a consumer's tree is never silent. */
-export function reportBlockMigration(migration: BlockMigration, command: 'init' | 'sync'): void {
-  if (!migration.pending) return
-  const tail = migration.deletedHost
-    ? `${LEGACY_BLOCK_HOST} held nothing else and was deleted.`
-    : `the rest of ${LEGACY_BLOCK_HOST} is yours; while it exists Claude Code loads it INSTEAD of ` +
-      `${AGENTS_MD} unless it imports @${AGENTS_MD} — move your content over and delete it.`
-  console.log(
-    `\nbasalt-ui ${command}: moved the basalt block from ${LEGACY_BLOCK_HOST} to ${AGENTS_MD} — ${tail}`,
-  )
-}
-
 /**
  * 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,
@@ -1356,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
- *    `AGENTS-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
@@ -1404,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'
@@ -1517,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
@@ -1592,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 = ''
@@ -1629,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
   }
@@ -1726,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')
@@ -1752,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'
@@ -1941,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
@@ -1963,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(