basalt-ui 1.19.1 → 1.21.0

package/src/cli/index.ts

@@ -32,7 +32,16 @@ import {
 import { dirname, isAbsolute, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { checkSource, DEFAULT_GUARD_CONFIG, GUARD_RULES } from '../guard'
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
+  guardKindRemedy,
+  GUARD_RULES,
+  guardWaiverHint,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns,
+} from '../guard'
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from '../guard'
 import { evaluateGuardHook } from '../guard/guard-hook'
 import { RULE_NAMES, SKILL_NAMES, SURFACES, TOKEN_LAYER_BOUNDARY_SURFACES } from '../surfaces'
@@ -45,6 +54,28 @@ export type BasaltConfig = {
   roots?: string[]
   /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
   exempt?: string[]
+  /**
+   * Declares this package a tokens-only consumer: it uses the `--vx-*` layer and no Mantine. Turns
+   * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
+   * factory, leaving the color and typography kinds live. Default: `'mantine'`.
+   *
+   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
+   * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
+   * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
+   * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
+   */
+  profile?: 'mantine' | 'tokens-only'
+  /**
+   * Extra files to scan, named individually and relative to this package — for a design surface
+   * that lives outside every root and outside the `index.html` / `public/` conventions the walker
+   * already derives. Also the ONLY way a `.json` is ever scanned: the guard understands JSON as
+   * markup, but a consumer repo's JSON is overwhelmingly config, fixtures and lockfiles, so
+   * blanket-scanning it is a false-positive generator rather than a guard.
+   *
+   * @example
+   * { include: ['app/manifest.json', 'emails/template.html'] }
+   */
+  include?: string[]
   /** Named spacing-scale steps (px) flagged when used as a raw spacing prop. Default: 10/12/16/20/32. */
   spacingSteps?: number[]
   /** Per-kind severity override — `'warn'` reports without failing, `'error'` fails the build.
@@ -156,15 +187,27 @@ export type BasaltConfig = {
   /**
    * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
    * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
-   * only). Each value is a list of path-segment patterns matched against a finding's relative
-   * path: a pattern matches when the path split on `/` includes it as a WHOLE segment (`'agent'`
-   * matches `src/agent/x.tsx` but not `src/agenting.ts`; a trailing `/` is stripped, so `'agent'`
-   * and `'agent/'` are equivalent). Default: `{}` (no exemptions).
+   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
+   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
+   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
+   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
+   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
+   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
+   *
+   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
+   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
+   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
+   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
+   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
+   * still suppresses. The array form stays supported and unchanged; nothing here is required.
    *
    * @example
    * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
+   * @example
+   * { exemptRules: { 'raw-hex': { paths: ['site.webmanifest'],
+   *   reason: 'a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var' } } }
    */
-  exemptRules?: Partial<Record<GuardKind, string[]>>
+  exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
   /**
    * Declares an intentional `ai` package major-version skew across workspace packages, exempting
    * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
@@ -186,6 +229,38 @@ export type BasaltConfig = {
   aiMajorSkewReason?: string
 }
 
+/**
+ * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
+ * it exists. See `BasaltConfig.exemptRules`.
+ */
+type ExemptRuleEntry = string[] | { paths: string[]; reason: string }
+
+/** The paths half of an exemption entry, whichever form it was written in. */
+function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[] {
+  if (entry === undefined) return []
+  return Array.isArray(entry) ? entry : entry.paths
+}
+
+/** The recorded reason for an exemption entry, or null for the bare-array form. */
+function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null {
+  if (entry === undefined || Array.isArray(entry)) return null
+  return entry.reason.trim().length > 0 ? entry.reason.trim() : null
+}
+
+/**
+ * The guard-shaped `exemptRules` — paths only. The reason the object form carries never reaches
+ * the guard: it is accountability for a human reading a diff and for `--audit-allows`, and giving
+ * the scan a second shape to understand would only be a way for the two to disagree.
+ */
+function resolveExemptRules(cfg: BasaltConfig): GuardConfig['exemptRules'] {
+  if (cfg.exemptRules === undefined) return DEFAULT_GUARD_CONFIG.exemptRules
+  const out: Partial<Record<GuardKind, string[]>> = {}
+  for (const [kind, entry] of Object.entries(cfg.exemptRules)) {
+    out[kind as GuardKind] = exemptRulePaths(entry)
+  }
+  return out
+}
+
 const DEFAULT_ROOT = 'src'
 const DEFAULT_ROOTS = [DEFAULT_ROOT]
 
@@ -284,10 +359,22 @@ function readBasaltConfig(cwd: string): BasaltConfig {
 }
 
 /**
- * Recursively collect .ts/.tsx/.css files under a root, skipping dependency/build dirs.
- * Node+Bun-safe. `.css` is included so the theme guard reaches CSS modules / `styles.css` —
+ * 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.
+ */
+const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/
+
+/**
+ * Recursively collect scannable files under a root, skipping dependency/build dirs. Node+Bun-safe.
  * `checkSource` is already syntax-aware per extension (`guardSyntaxFor`); the walker was the only
- * gap.
+ * gap, twice over — `.css` (CSS modules / `styles.css`) and now `.html`/`.webmanifest`.
+ *
+ * `.json` is deliberately NOT here even though the guard resolves it as markup: a consumer repo is
+ * full of JSON that is configuration, fixtures and lockfiles, and blanket-scanning it produces
+ * exactly the class of false positive already reported against a `data.json` test fixture. A JSON
+ * that IS a design surface (a `manifest.json` rather than a `*.webmanifest`) is reachable by naming
+ * it in `basalt.include`.
  */
 function walkSourceFiles(dir: string, out: string[] = []): string[] {
   let entries: string[]
@@ -306,71 +393,293 @@ function walkSourceFiles(dir: string, out: string[] = []): string[] {
       continue
     }
     if (isDir) walkSourceFiles(abs, out)
-    else if (/\.(?:tsx?|css)$/.test(name)) out.push(abs)
+    else if (SCANNABLE_EXT.test(name)) out.push(abs)
   }
   return out
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Resolution — where basalt is installed, and where the consumer's basalt config lives
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** A path relative to `fromDir`, POSIX-separated and always explicitly relative (`./` / `../`). */
+function relativePosix(fromDir: string, toPath: string): string {
+  const rel = relative(fromDir, toPath).replace(/\\/g, '/')
+  if (rel === '') return '.'
+  return rel.startsWith('.') ? rel : `./${rel}`
+}
+
 /**
- * One-line fix guidance per guard kind, printed in the check-theme "Fix:" epilogue — only for the
- * kinds actually present in a given run's findings, so the epilogue never dumps all 16+ rules on a
- * single-kind violation. Kinds without an entry here (e.g. `localstorage-theme`,
- * `chart-missing-aria-label`) fall back to the generic `theme-allow` closer only.
- */
-const GUARD_KIND_EXPLANATIONS: Partial<Record<GuardKind, string>> = {
-  'raw-hex':
-    'raw-hex: route color through VX.* / the Mantine theme instead of a hardcoded hex literal.',
-  'raw-color-fn':
-    'raw-color-fn: route color through VX.* / the Mantine theme instead of a hardcoded rgb()/hsl() literal.',
-  'off-identity-accent':
-    'off-identity-accent: use blue/gray or a status hue (red/green/orange/yellow) instead.',
-  'raw-spacing': 'raw-spacing: use the spacing scale token instead of a raw literal.',
-  'raw-radius': 'raw-radius: use the radius scale token instead of a raw literal.',
-  'raw-surface':
-    'raw-surface: use `VX.surface.*` / a `radius` token / `var(--vx-radius-card)` instead of an ' +
-    'inline border/radius/shadow.',
-  'card-with-border':
-    'card-with-border: `withBorder` on a Card/Paper double-draws the edge — card depth is ' +
-    '`--vx-shadow-card`, which already bakes a 1px ring into the shadow. Drop the prop.',
-  'off-system-surface-var':
-    'off-system-surface-var: raw Mantine ramp step bypasses the basalt surface tokens — use ' +
-    'VX.surface.* / --vx-surface-* (border/panel/subtle/bg) instead.',
-  'raw-html-layout':
-    'raw-html-layout: raw HTML element with inline layout/surface styling — use a Mantine layout ' +
-    'primitive (Box/Flex/Grid/Stack/Group).',
-  'inline-spacing':
-    'inline-spacing: inline spacing literal — use the Mantine spacing prop/token (p/m/gap with xs..xl).',
-  'inline-display':
-    'inline-display: use <Flex>/<Grid>/<Group> instead of an inline display:flex/grid.',
-  'raw-visx-axis':
-    'raw-visx-axis: raw <AxisLeft>/<AxisBottom>/<AxisRight> in a chart file — use ' +
-    'AxisLeftNumeric / AxisBottomDate / AxisRightNumeric from the charts primitives.',
-  'raw-motion-value':
-    'raw-motion-value: hardcoded duration/spring/ease in `transition={{...}}` — use ' +
-    'MOTION_DURATION / MOTION_SPRING / MOTION_EASE_STANDARD instead.',
-  'unframed-chart':
-    'unframed-chart: hand-rolled ChartLegend built from an inline array literal — pass a derived ' +
-    'legend (deriveLegend(series)), or compose ChartFrame, which derives it for you.',
-  'raw-form-control':
-    'raw-form-control: raw <input>/<select>/<textarea> bypasses the entire theme — use ' +
-    'TextInput / NumberInput / Select / Textarea from @mantine/core.',
-  'sub-16-input-font':
-    'sub-16-input-font: fontSize below 16 on a form control is dead code against the `!important` ' +
-    'iOS floor in styles.css — drop the override or be honest about 16px.',
-  'raw-font-family':
-    'raw-font-family: route the font stack through createBasaltTheme(overrides, { fonts }) / the ' +
-    '--basalt-font-sans|head|mono vars instead of a hardcoded fontFamily literal.',
+ * Where `basalt-ui` actually resolves from, seen from a consumer directory.
+ *
+ * Every toolchain seam basalt seeds (`.oxlintrc.json`'s `extends`, `lefthook.yml`'s `extends`, the
+ * CI `run:` steps) used to hardcode `./node_modules/basalt-ui` at the repo ROOT. Under bun's
+ * isolated linker a library package that declares basalt a peer + devDependency gets
+ * `<pkg>/node_modules/basalt-ui` and NOTHING at the root, so all three silently failed to resolve
+ * and `bunx` fetched a second, different copy from npm instead. Resolution therefore walks
+ * OUTWARD from the consumer dir first, then across the workspace packages — and every caller
+ * renders its paths from the answer rather than assuming the root.
+ */
+type BasaltInstall = {
+  /** Absolute path of the resolved `node_modules/basalt-ui` directory, or null when unresolvable. */
+  dir: string | null
+  /** The resolved copy's own version, or null. */
+  version: string | null
+  /** How it was found — `null` when unresolved. `'workspace'` is the isolated-linker case. */
+  how: 'cwd' | 'ancestor' | 'workspace' | null
+}
+
+const UNRESOLVED_INSTALL: BasaltInstall = { dir: null, version: null, how: null }
+
+/** `<dir>/node_modules/basalt-ui` when it holds a readable package.json, else null. */
+function basaltInstallAt(dir: string): { dir: string; version: string | null } | null {
+  const installDir = resolve(dir, 'node_modules', 'basalt-ui')
+  const raw = readIfExists(resolve(installDir, 'package.json'))
+  if (raw === null) return null
+  try {
+    const pkg = JSON.parse(raw) as { version?: string }
+    return { dir: installDir, version: pkg.version ?? null }
+  } catch {
+    return { dir: installDir, version: null }
+  }
+}
+
+/** Resolve the installed basalt-ui: cwd, then every ancestor, then the workspace packages. */
+function findBasaltInstall(cwd: string): BasaltInstall {
+  const own = basaltInstallAt(cwd)
+  if (own !== null) return { ...own, how: 'cwd' }
+
+  let current = dirname(cwd)
+  for (;;) {
+    const found = basaltInstallAt(current)
+    if (found !== null) return { ...found, how: 'ancestor' }
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+
+  for (const pkg of collectWorkspacePackages(cwd).packages) {
+    if (pkg.dir === cwd) continue
+    const found = basaltInstallAt(pkg.dir)
+    if (found !== null) return { ...found, how: 'workspace' }
+  }
+  return UNRESOLVED_INSTALL
+}
+
+/**
+ * The `extends`/`run:` path a seeded config should carry to reach a shipped asset — rendered from
+ * where basalt ACTUALLY resolves, relative to the directory the config lives in. Falls back to the
+ * root-relative form when nothing resolves (a pre-install `init`), so the seed is still the shape a
+ * later `bun install` makes true.
+ */
+function shippedAssetPath(install: BasaltInstall, fromDir: string, asset: string): string {
+  if (install.dir === null) return `./node_modules/basalt-ui/${asset}`
+  return `${relativePosix(fromDir, install.dir)}/${asset}`
+}
+
+/** True when `dir` is a basalt-configured project — it carries the manifest or a `basalt` key. */
+function hasBasaltProject(dir: string): boolean {
+  if (existsSync(resolve(dir, MANIFEST_PATH))) return true
+  const raw = readIfExists(resolve(dir, 'package.json'))
+  if (raw === null) return false
+  try {
+    return (JSON.parse(raw) as { basalt?: unknown }).basalt !== undefined
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Which directory a project-scoped command (`check-theme`, `doctor`) should actually read.
+ *
+ * The shipped lefthook preset and every `bunx basalt-ui …` in the seeded CI run at the REPO ROOT,
+ * while in a monorepo the `basalt` config and the manifest live in a package below it — verified to
+ * produce `0 files scanned` and a `manifest missing` failure, i.e. a gate that never gates. Rather
+ * than make every consumer hand-write a `--cwd`, a command with no basalt project at its own cwd
+ * relocates to the single workspace package that has one, and says so. Two or more candidates is
+ * genuinely ambiguous and reported as such; `BASALT_CWD` is the explicit override.
+ */
+type ProjectResolution = {
+  /** The directory to read. Equals the invocation cwd unless a relocation happened. */
+  dir: string
+  /** The invocation cwd when the command relocated away from it, else null. */
+  relocatedFrom: string | null
+  /** Candidate project dirs when relocation was impossible because several exist, else null. */
+  ambiguous: string[] | null
+}
+
+function resolveProjectDir(cwd: string): ProjectResolution {
+  const override = process.env['BASALT_CWD']
+  if (override !== undefined && override.length > 0) {
+    const dir = isAbsolute(override) ? override : resolve(cwd, override)
+    return { dir, relocatedFrom: dir === cwd ? null : cwd, ambiguous: null }
+  }
+  if (hasBasaltProject(cwd)) return { dir: cwd, relocatedFrom: null, ambiguous: null }
+
+  const candidates = collectWorkspacePackages(cwd)
+    .packages.filter((pkg) => pkg.dir !== cwd && hasBasaltProject(pkg.dir))
+    .map((pkg) => pkg.dir)
+  if (candidates.length === 1) {
+    return { dir: candidates[0] as string, relocatedFrom: cwd, ambiguous: null }
+  }
+  if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates }
+  return { dir: cwd, relocatedFrom: null, ambiguous: null }
+}
+
+/**
+ * Which shape of consumer a project-scoped command is looking at.
+ *
+ * A tokens-only consumer took the `--vx-*` layer and nothing else. Every guard kind whose remedy is
+ * a Mantine component or the React theme factory is meaningless there — telling a Mantine-free app
+ * to swap its `<select>` for `@mantine/core`'s `Select` is advice it must not take.
+ *
+ * DECLARED, never inferred, when the answer SILENCES something. The two callers want opposite
+ * failure directions and so do not share a default:
+ *
+ * - `check-theme` (`declaredProfile`) turns 17 kinds OFF, so it moves on an explicit signal only —
+ *   `--tokens-only`, or `"basalt": { "profile": "tokens-only" }`. Inferring it from the ABSENCE of
+ *   `@mantine/core` would silence the Mantine half of the guard on any repo that keeps its Mantine
+ *   dependency in a workspace package rather than the one holding the basalt config, which is
+ *   precisely this round's "reports green while enforcing nothing" failure with the guard's own
+ *   hand on the switch.
+ * - `doctor` ({@link inferredProfile}) only changes which ADVICE it prints, never what it enforces,
+ *   so it may infer from absence and then tell the consumer to write the key down.
+ */
+function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
+  if (flags.includes('--tokens-only')) return 'tokens-only'
+  if (flags.includes('--framework')) return 'framework'
+  return cfg.profile === 'tokens-only' ? 'tokens-only' : 'framework'
+}
+
+/**
+ * `--tokens-only` and `--framework` are alternatives, so passing both is a contradiction rather
+ * than a precedence question — the same reading `tokens:css` already applies to `--selector-class`
+ * vs `--selector-attribute`. Silently preferring one meant a CI step that accumulated both flags
+ * enforced whichever the code happened to test first.
+ */
+function conflictingProfileFlags(flags: readonly string[]): boolean {
+  return flags.includes('--tokens-only') && flags.includes('--framework')
+}
+
+/** True when nothing anywhere in the workspace declares Mantine — see {@link inferredProfile}. */
+function workspaceHasMantine(cwd: string): boolean {
+  if (hasDependency(cwd, '@mantine/core')) return true
+  return collectWorkspacePackages(cwd).packages.some((pkg) =>
+    hasDependency(pkg.dir, '@mantine/core'),
+  )
+}
+
+/**
+ * `doctor`'s profile: the declaration if there is one, else inferred from no scaffold manifest and
+ * no `@mantine/core` anywhere in the workspace. Advice only — see {@link declaredProfile}.
+ */
+function inferredProfile(cwd: string, cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
+  if (
+    flags.includes('--tokens-only') ||
+    flags.includes('--framework') ||
+    cfg.profile !== undefined
+  ) {
+    return declaredProfile(cfg, flags)
+  }
+  return !existsSync(resolve(cwd, MANIFEST_PATH)) && !workspaceHasMantine(cwd)
+    ? 'tokens-only'
+    : 'framework'
+}
+
+/**
+ * The relative paths `check-theme` would actually scan for a given config — the ONE place the walk
+ * + `SKIP` + `exempt` filtering lives, so `doctor`'s "the guard sees zero files" check can never
+ * disagree with what `check-theme` does.
+ */
+function scannableFiles(cwd: string, cfg: BasaltConfig): string[] {
+  const exempt = new Set(cfg.exempt ?? defaultExempt(cfg))
+  const seen = new Set<string>()
+  const out: string[] = []
+  const add = (abs: string): void => {
+    // Normalize to forward slashes so path matching (SKIP, exempt, isChartFile) is
+    // identical on Windows (where `relative` yields backslashes) and POSIX.
+    const rel = relative(cwd, abs).replace(/\\/g, '/')
+    if (rel.startsWith('..') || SKIP.test(rel) || exempt.has(rel) || seen.has(rel)) return
+    seen.add(rel)
+    out.push(rel)
+  }
+
+  for (const root of resolveRoots(cfg)) {
+    const rootAbs = resolve(cwd, root)
+    for (const f of walkSourceFiles(rootAbs)) add(f)
+    for (const f of appShellFiles(rootAbs)) add(f)
+  }
+  // Explicitly named files, the one route by which a `.json` is ever scanned.
+  for (const rel of cfg.include ?? []) add(resolve(cwd, rel))
+  return out
+}
+
+/**
+ * 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.
+ */
+function appShellFiles(rootAbs: string): string[] {
+  const appDir = dirname(rootAbs)
+  const out: string[] = []
+  for (const name of ['index.html', 'index.htm']) {
+    const abs = resolve(appDir, name)
+    if (existsSync(abs)) out.push(abs)
+  }
+  out.push(...walkSourceFiles(resolve(appDir, 'public')))
+  return out
 }
 
 /**
  * Theme guard — thin FS walker over the headless `../guard` core. Reads BasaltConfig, builds a
  * GuardConfig, walks roots, calls checkSource per file, collects Finding[], groups/reports, returns
  * 0 (clean) / 1 (violations). A `theme-allow` comment exempts a line.
+ *
+ * Runs against `resolveProjectDir(cwd)`, not `cwd` — see that type's doc for why a root-invoked
+ * hook or CI step has to find the package the config lives in rather than scan nothing and pass.
  */
-export function checkTheme(cwd: string = process.cwd()): number {
+export function checkTheme(
+  invocationCwd: string = process.cwd(),
+  flags: readonly string[] = [],
+): number {
+  if (conflictingProfileFlags(flags)) {
+    console.error(
+      'basalt-ui check-theme: --tokens-only and --framework are alternatives — pass one.',
+    )
+    return 1
+  }
+  const project = resolveProjectDir(invocationCwd)
+  if (project.ambiguous !== null) {
+    console.error(
+      `✖ basalt-ui check-theme: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} ` +
+        `workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
+        'run it from one of them, or set BASALT_CWD to pick.',
+    )
+    return 1
+  }
+  const cwd = project.dir
+  if (project.relocatedFrom !== null) {
+    console.log(
+      `basalt-ui check-theme: no basalt config at ${project.relocatedFrom} — running in ` +
+        `${relativePosix(project.relocatedFrom, cwd)}, where it lives.`,
+    )
+  }
   const cfg = readBasaltConfig(cwd)
-  const roots = cfg.roots ?? DEFAULT_ROOTS
-  const exempt = new Set(cfg.exempt ?? defaultExempt(cfg))
+  const roots = resolveRoots(cfg)
+  const profile = declaredProfile(cfg, flags)
+  if (profile === 'tokens-only') {
+    console.log(
+      'basalt-ui check-theme: tokens-only profile — ' +
+        `${TOKENS_ONLY_DISABLED_KINDS.size} Mantine-coupled kinds are off; the color and typography ` +
+        'kinds still apply. Pass --framework to force the full set.',
+    )
+  }
 
   const guardCfg: GuardConfig = {
     spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
@@ -390,25 +699,18 @@ export function checkTheme(cwd: string = process.cwd()): number {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: 'theme-allow',
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
+    exemptRules: resolveExemptRules(cfg),
     severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    ...(profile === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
   }
 
   const findings: Finding[] = []
-  let scannedCount = 0
-  for (const root of roots) {
-    for (const f of walkSourceFiles(resolve(cwd, root))) {
-      // Normalize to forward slashes so path matching (SKIP, exempt, isChartFile) is
-      // identical on Windows (where `relative` yields backslashes) and POSIX.
-      const rel = relative(cwd, f).replace(/\\/g, '/')
-      if (SKIP.test(rel) || exempt.has(rel)) continue
-      scannedCount += 1
-      const text = readFileSync(f, 'utf8')
-      findings.push(...checkSource(text, rel, guardCfg))
-    }
+  const scanned = scannableFiles(cwd, cfg)
+  for (const rel of scanned) {
+    findings.push(...checkSource(readFileSync(resolve(cwd, rel), 'utf8'), rel, guardCfg))
   }
 
-  if (scannedCount === 0) {
+  if (scanned.length === 0) {
     // A configured-but-wrong root is never intentional, and silently scanning 0 files under the
     // built-in defaults (argo's pre-migration layout) is the same failure mode for every other
     // consumer — both cases fail loud instead of warn-plus-green.
@@ -427,6 +729,25 @@ export function checkTheme(cwd: string = process.cwd()): number {
     return 1
   }
 
+  // The audit is a REPORT over the same scan, not a second scan with different rules — it runs
+  // after the 0-files gate so "every waiver is dead" can never mean "nothing was read".
+  if (flags.includes('--audit-allows')) return auditAllows(cwd, cfg, guardCfg, scanned)
+
+  // An exemption that matched nothing is reported, never silently honoured. A WARNING rather than a
+  // failure: the entry enforced exactly nothing before this line existed, so failing on it would
+  // break a green build at upgrade time over config that was already inert — `--audit-allows` is
+  // the lane that exits non-zero on a dead waiver, for a consumer who opts into that gate.
+  for (const unmatched of unmatchedExemptPatterns(guardCfg, scanned)) {
+    console.error(
+      `⚠ basalt-ui check-theme: "basalt.exemptRules" entry ${unmatched.kind}: ` +
+        `"${unmatched.pattern}" ` +
+        (unmatched.reason === 'unknown-kind'
+          ? 'names no guard kind — it exempts nothing at all (a typo, or a kind that was renamed).'
+          : 'matched none of the scanned files — it suppresses nothing, and reads as coverage in a ' +
+            'config review while enforcing as much as an empty object.'),
+    )
+  }
+
   if (findings.length === 0) {
     console.log('✓ Theme guard: no off-palette colors.')
     return 0
@@ -469,16 +790,14 @@ export function checkTheme(cwd: string = process.cwd()): number {
     report(errors, `✖ Theme guard: ${errors.length} off-palette / off-identity violation(s)\n`)
   }
 
-  const presentKinds = new Set(findings.map((f) => f.kind))
-  const explanations = (Object.keys(GUARD_KIND_EXPLANATIONS) as GuardKind[])
-    .filter((kind) => presentKinds.has(kind))
-    .map((kind) => GUARD_KIND_EXPLANATIONS[kind])
-  const fixLine = [
-    'Fix:',
-    ...explanations,
-    'Add a `theme-allow` comment for a deliberate exception.',
-  ]
-  console.error(fixLine.join(' '))
+  // Remedies come from the guard's own rule registry, never from a copy kept here: the local table
+  // this replaced had no entry for any of the five kinds 1.20.0 added, so exactly the new findings
+  // — the ones whose whole argument is "this looks correct and is not" — printed no argument.
+  const presentKinds = [...new Set(findings.map((f) => f.kind))].toSorted()
+  // And the closer is per FILE CLASS: prescribing a `theme-allow` comment to a .webmanifest (which
+  // has no comment syntax) is what pushed two consumers into a blanket exemption instead.
+  const waiverHints = [...new Set(findings.map((f) => guardWaiverHint(f.relPath)))].toSorted()
+  console.error(['Fix:', ...presentKinds.map(guardKindRemedy), ...waiverHints].join(' '))
 
   // A violation in a file that looks like the palette source itself is likely intentional — point
   // at the exempt escape hatch instead of leaving the author to search for it.
@@ -493,6 +812,201 @@ export function checkTheme(cwd: string = process.cwd()): number {
   return errors.length > 0 ? 1 : 0
 }
 
+// ── check-theme --audit-allows — every waiver, and whether it still suppresses anything ─────────
+
+/** The token an audit probe substitutes for `theme-allow`. Contains no substring of it, on purpose. */
+const AUDIT_NEUTRALIZED_TOKEN = 'basalt-audit-neutralized'
+
+/** `relPath:line:kind` — a finding's identity for set arithmetic across two runs of the same file. */
+function findingKey(f: Finding): string {
+  return `${f.relPath}:${f.line}:${f.kind}`
+}
+
+/**
+ * Everything allowed between a comment opener (or the start of the line) and the token, for it to
+ * be an ANNOTATION rather than prose mentioning one.
+ *
+ * Mirrors the guard's `ANNOTATION_PREFIX`, which is module-private. It decides only which lines
+ * this REPORT lists — what each one suppresses is answered by re-running `checkSource`, so the two
+ * cannot disagree about enforcement, only about whether a doc sentence gets a line in the audit.
+ * Worth an export from the guard if it ever gains a third caller.
+ */
+const AUDIT_ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/
+
+/**
+ * The rule ids an annotation NAMES, as written. Classification only — what it actually waives is
+ * decided by re-running the guard.
+ *
+ * It exists for one distinction the behavioural probe cannot make: an annotation scoped to an
+ * oxlint PLUGIN rule (`hand-rolled-plot`, `raw-scroll-container`, …) suppresses nothing `checkSource`
+ * can see, because those rules live in the plugin. Calling it dead would tell someone to delete a
+ * live waiver — the exact failure this command exists to prevent, pointed the other way.
+ */
+function annotationRuleIds(rest: string): string[] {
+  const head = (rest.replace(/^-file\b/, '').split(/—|–|:|\s-\s/)[0] ?? '').trim()
+  return head
+    .split(',')
+    .map((word) => word.trim().replace(/^basalt\//, ''))
+    .filter((word) => /^[a-z][a-z0-9-]*$/.test(word))
+}
+
+/** True when the token on this line opens an annotation — comment form, or the JSON member form. */
+function isAllowAnnotationLine(line: string, token: string): boolean {
+  const at = line.indexOf(token)
+  if (at === -1) return false
+  if (line.includes(`"basalt:${token}`)) return true
+  return AUDIT_ANNOTATION_PREFIX.test(line.slice(0, at))
+}
+
+/**
+ * `check-theme --audit-allows` — list every active waiver and prove, per waiver, whether it still
+ * suppresses anything.
+ *
+ * The accountability release shipped `theme-allow-unscoped`, which reports a waiver that names no
+ * rule — but a waiver that is perfectly well written and covers a finding that no longer exists is
+ * invisible to it, and to everything else. Two consumers found five of those by hand, by editing
+ * the token out and re-running the guard. This is that method, automated: for each annotation the
+ * file is re-checked with THAT occurrence neutralized, and the findings that appear are exactly
+ * what it suppresses. Nothing is inferred from the annotation's text, so the audit cannot disagree
+ * with the scan — it IS the scan, run twice.
+ *
+ * `basalt.exemptRules` entries are audited the same way, one pattern at a time. That also answers
+ * the question the key could never answer for itself: a pattern that matches no scanned file (a
+ * real relative path, say, where the matcher takes whole path SEGMENTS) suppresses nothing and is
+ * reported as dead rather than passing silently.
+ *
+ * Exit 1 when anything is dead, so it can be wired into CI as a gate. A waiver nobody re-checks is
+ * how a rule quietly stops applying to the file that needed the exception most.
+ */
+function auditAllows(
+  cwd: string,
+  cfg: BasaltConfig,
+  guardCfg: GuardConfig,
+  scanned: string[],
+): number {
+  const token = guardCfg.allowComment
+  const lines: string[] = [`\nbasalt-ui check-theme --audit-allows — ${cwd}\n`]
+  let dead = 0
+  let live = 0
+  let outOfReach = 0
+  let unaccountable = 0
+
+  // ── theme-allow annotations ─────────────────────────────────────────────────
+  const waiverLines: string[] = []
+  const sources = new Map<string, string>()
+  for (const rel of scanned) sources.set(rel, readFileSync(resolve(cwd, rel), 'utf8'))
+
+  for (const rel of scanned) {
+    const text = sources.get(rel) ?? ''
+    if (!text.includes(token)) continue
+    const baseline = checkSource(text, rel, guardCfg)
+    const baselineKeys = new Set(
+      baseline.filter((f) => f.kind !== 'theme-allow-unscoped').map(findingKey),
+    )
+    const unscopedAt = new Map(
+      baseline.filter((f) => f.kind === 'theme-allow-unscoped').map((f) => [f.line, f.token]),
+    )
+    const fileLines = text.split('\n')
+    for (const [index, line] of fileLines.entries()) {
+      if (!isAllowAnnotationLine(line ?? '', token)) continue
+      const probe = [...fileLines]
+      probe[index] = (line ?? '').replaceAll(token, AUDIT_NEUTRALIZED_TOKEN)
+      const revealed = checkSource(probe.join('\n'), rel, guardCfg)
+        .filter((f) => f.kind !== 'theme-allow-unscoped' && !baselineKeys.has(findingKey(f)))
+        .map((f) => `${f.kind}@${f.line}`)
+      const note = unscopedAt.get(index + 1)
+      if (note !== undefined) unaccountable++
+      const site = `  ${rel}:${index + 1}`.padEnd(52)
+      const suffix = note === undefined ? '' : ` [${note}]`
+      const ids = annotationRuleIds((line ?? '').slice((line ?? '').indexOf(token) + token.length))
+      if (revealed.length > 0) {
+        live++
+        waiverLines.push(`${site} suppresses ${[...new Set(revealed)].join(', ')}${suffix}`)
+      } else if (ids.length > 0 && !ids.some((id) => Object.hasOwn(GUARD_RULES, id))) {
+        outOfReach++
+        waiverLines.push(
+          `${site} scoped to ${ids.join(', ')} — not a check-theme kind, so this audit cannot ` +
+            `judge it (an oxlint plugin rule, or a typo theme-allow-unscoped would report)${suffix}`,
+        )
+      } else {
+        dead++
+        waiverLines.push(`${site} SUPPRESSES NOTHING — dead, delete it${suffix}`)
+      }
+    }
+  }
+
+  lines.push(`${token} annotations (${waiverLines.length}):`)
+  lines.push(...(waiverLines.length === 0 ? ['  (none)'] : waiverLines))
+
+  // ── basalt.exemptRules entries ──────────────────────────────────────────────
+  const exemptLines: string[] = []
+  let exemptCount = 0
+  const declared = Object.entries(cfg.exemptRules ?? {}) as [GuardKind, ExemptRuleEntry][]
+  if (declared.length > 0) {
+    const baselineKeys = new Set<string>()
+    for (const rel of scanned) {
+      for (const f of checkSource(sources.get(rel) ?? '', rel, guardCfg))
+        baselineKeys.add(findingKey(f))
+    }
+    for (const [kind, entry] of declared) {
+      const reason = exemptRuleReason(entry)
+      for (const pattern of exemptRulePaths(entry)) {
+        exemptCount++
+        const probeCfg: GuardConfig = {
+          ...guardCfg,
+          exemptRules: {
+            ...guardCfg.exemptRules,
+            [kind]: exemptRulePaths(entry).filter((p) => p !== pattern),
+          },
+        }
+        const revealed = new Set<string>()
+        for (const rel of scanned) {
+          for (const f of checkSource(sources.get(rel) ?? '', rel, probeCfg)) {
+            if (!baselineKeys.has(findingKey(f))) revealed.add(f.relPath)
+          }
+        }
+        const site = `  ${kind}: "${pattern}"`.padEnd(52)
+        const why = reason === null ? ' [no reason recorded]' : ` — ${reason}`
+        if (revealed.size === 0) {
+          dead++
+          const unmatched = unmatchedExemptPatterns(guardCfg, scanned).find(
+            (u) => u.kind === kind && u.pattern === pattern,
+          )
+          exemptLines.push(
+            `${site} SUPPRESSES NOTHING — ` +
+              (unmatched === undefined
+                ? 'the files it matches have no such finding; delete it'
+                : unmatched.reason === 'unknown-kind'
+                  ? 'it names no guard kind (a typo, or a renamed kind)'
+                  : 'it matches no scanned file at all') +
+              why,
+          )
+        } else {
+          live++
+          exemptLines.push(
+            `${site} suppresses findings in ${[...revealed].toSorted().join(', ')}${why}`,
+          )
+        }
+      }
+    }
+  }
+  lines.push(`\nbasalt.exemptRules entries (${exemptCount}):`)
+  lines.push(...(exemptLines.length === 0 ? ['  (none)'] : exemptLines))
+
+  lines.push(
+    `\n${live} live, ${dead} dead, ${outOfReach} outside check-theme's reach, ${unaccountable} ` +
+      'unaccountable (reported as theme-allow-unscoped by a normal run).',
+  )
+  if (dead > 0) {
+    lines.push(
+      'A dead waiver is not harmless: it is an exception nobody re-checked, and it will silently ' +
+        'cover the next real finding on that line.',
+    )
+  }
+  console.log(lines.join('\n'))
+  return dead > 0 ? 1 : 0
+}
+
 // ──────────────────────────────────────────────────────────────────────────────
 // init / sync — managed-files engine
 // ──────────────────────────────────────────────────────────────────────────────
@@ -557,6 +1071,16 @@ type TemplateVars = {
   SERIES_MODULE_PATH: string
   /** The consumer's configured roots as space-separated quoted oxfmt globs, e.g. `'apps/web/src/**'`. */
   ROOTS_GLOBS: string
+  /** Path to the shipped oxlint preset from the consumer dir — RESOLVED, never assumed at the root. */
+  OXLINT_PRESET_PATH: string
+  /** Path to the shipped lefthook preset from the consumer dir — same resolution. */
+  LEFTHOOK_PRESET_PATH: string
+  /**
+   * How a seeded script or CI step invokes the CLI. The locally-installed bin when basalt resolves
+   * (so the step can never silently run a DIFFERENT version that `bunx` fetched from npm), and
+   * `bunx basalt-ui` only as the pre-install fallback.
+   */
+  BASALT_BIN: string
 }
 
 // The block markers the CLAUDE.md template emits. The begin marker carries the framework version
@@ -603,12 +1127,20 @@ function readFrameworkVersion(pkgRoot: string): string {
 
 /** Build the template-variable map from the framework root + consumer cwd/config. */
 function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): TemplateVars {
+  const install = findBasaltInstall(cwd)
+  const binDir = install.dir === null ? null : resolve(install.dir, '..', '.bin')
   return {
     APP_NAME: readPackageName(cwd),
     BASALT_VERSION: readFrameworkVersion(pkgRoot),
     ACCENT_HUE: cfg.accentHue ?? 'blue',
     SERIES_MODULE_PATH: resolveSeriesModulePath(cfg),
     ROOTS_GLOBS: resolveRoots(cfg).map(toRootGlob).join(' '),
+    OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/oxlint.json'),
+    LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/lefthook.yml'),
+    BASALT_BIN:
+      binDir === null
+        ? 'bunx basalt-ui'
+        : `${relativePosix(cwd, binDir).replace(/^\.\//, '')}/basalt-ui`,
   }
 }
 
@@ -658,7 +1190,12 @@ function applyBlock(host: string, block: string): string {
  * 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).
  */
-type ScaffoldFlags = { withRouter?: boolean; withQuery?: boolean }
+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. */
 type PeerFlags = { hasRouter: boolean; hasQuery: boolean }
@@ -854,12 +1391,31 @@ function managedFiles(peers: PeerFlags, placement: PlacementFlags = ROOT_PLACEME
     dest: 'lefthook.yml',
     mode: 'seed',
     source: 'configs/lefthook.yml',
-    render: () =>
+    render: (ctx) =>
       '# Seeded by basalt-ui init — you own this file; sync never touches it again.\n' +
       '# The extends target supplies oxlint + oxfmt + check-theme pre-commit jobs and\n' +
       '# auto-updates with the basalt-ui package. Add your own commands alongside.\n' +
+      '# The path is RESOLVED from where basalt-ui actually installed, not assumed at the\n' +
+      '# repo root — under an isolated linker it lives beside the package that depends on it.\n' +
+      '# Run `lefthook install` once: the file is inert until the git hooks are written.\n' +
+      '#\n' +
+      '# NOTE: an extends target WINS on a colliding key — a `run:`/`glob:` you write under one of\n' +
+      "# the preset's command names is discarded silently. `env:`, `exclude:`, `skip:` and your own\n" +
+      '# command names merge. See the preset itself for the sanctioned override seams.\n' +
       'extends:\n' +
-      '  - node_modules/basalt-ui/configs/lefthook.yml\n',
+      `  - ${ctx.vars.LEFTHOOK_PRESET_PATH.replace(/^\.\//, '')}\n` +
+      // The one seam that has to be RENDERED rather than documented: the preset is read in place
+      // out of node_modules, so it cannot template the resolved bin the way check.yml does. Its
+      // default (`bunx --no-install basalt-ui`) fails loudly rather than fetching a stranger's
+      // copy; this pins it to the local one whenever basalt actually resolved.
+      (ctx.vars.BASALT_BIN.startsWith('bunx ')
+        ? ''
+        : '\n# The theme guard runs the LOCAL bin, not a copy `bunx` fetches from npm.\n' +
+          'pre-commit:\n' +
+          '  commands:\n' +
+          '    check-theme:\n' +
+          '      env:\n' +
+          `        BASALT_BIN: ${ctx.vars.BASALT_BIN}\n`),
   }
 
   // CI is inherently repo-shaped (a monorepo's check.yml needs its own scripts), and GitHub Actions
@@ -885,7 +1441,7 @@ function managedFiles(peers: PeerFlags, placement: PlacementFlags = ROOT_PLACEME
     dest: '.oxlintrc.json',
     mode: 'seed',
     source: 'configs/oxlint.json',
-    render: () => '{\n  "extends": ["./node_modules/basalt-ui/configs/oxlint.json"]\n}\n',
+    render: (ctx) => `{\n  "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"]\n}\n`,
   }
 
   // ── Seed scaffolds: written by init, never overwritten by sync ─────────────
@@ -1157,17 +1713,385 @@ function renderContext(cwd: string): RenderContext {
   return { pkgRoot, vars: buildTemplateVars(pkgRoot, cwd, readBasaltConfig(cwd)) }
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// init — describing the repo it is actually in
+// ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Read → mutate → write the consumer's package.json, preserving its own indentation and trailing
+ * newline. `mutate` returns false to abort the write (nothing to change). Returns whether a write
+ * happened. Deliberately a JSON round-trip rather than a textual splice: key ORDER is preserved by
+ * `JSON.parse`/`stringify`, and anything fancier would be a formatter this CLI has no business being.
+ */
+function patchPackageJson(cwd: string, mutate: (pkg: Record<string, unknown>) => boolean): boolean {
+  const abs = resolve(cwd, 'package.json')
+  const raw = readIfExists(abs)
+  if (raw === null) return false
+  let pkg: Record<string, unknown>
+  try {
+    pkg = JSON.parse(raw) as Record<string, unknown>
+  } catch {
+    return false
+  }
+  if (!mutate(pkg)) return false
+  const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? '  '
+  writeFileSync(abs, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''))
+  return true
+}
+
+/**
+ * The source roots for THIS repo, inferred from its actual layout — the fix for the single most
+ * reported false-green: without `basalt.roots` a workspace repo scaffolds a `check-theme` that
+ * scans zero files and a CI `oxfmt 'src/**'` that matches nothing, while `doctor` reports green.
+ *
+ * A workspace repo resolves to the `src/` of every workspace package that depends on basalt or
+ * Mantine (a backend package's `src/` has nothing for a design guard to say); with no such package
+ * it falls back to every workspace `src/`, and a single-package repo to plain `src`. Empty when
+ * nothing plausible exists — `init` says so rather than writing a root that matches nothing.
+ */
+function detectRoots(cwd: string): string[] {
+  const workspacePackages = collectWorkspacePackages(cwd).packages.filter((pkg) => pkg.dir !== cwd)
+  const withSrc = workspacePackages.filter((pkg) => existsSync(resolve(pkg.dir, 'src')))
+  const uiPackages = withSrc.filter(
+    (pkg) => hasDependency(pkg.dir, 'basalt-ui') || hasDependency(pkg.dir, '@mantine/core'),
+  )
+  const chosen = uiPackages.length > 0 ? uiPackages : withSrc
+  if (chosen.length > 0) {
+    return chosen.map((pkg) => relativePosix(cwd, resolve(pkg.dir, 'src')).replace(/^\.\//, ''))
+  }
+  return existsSync(resolve(cwd, DEFAULT_ROOT)) ? [DEFAULT_ROOT] : []
+}
+
+/** What `reconcileRoots` found — the one roots decision `init` and `sync` both report from. */
+type RootsState =
+  /** The key was absent and has just been written. */
+  | { readonly kind: 'wrote'; readonly roots: string[] }
+  /** The key is absent and nothing plausible could be inferred. */
+  | { readonly kind: 'undetectable' }
+  /** The key is already declared. `unscanned` names inferable roots it does not cover. */
+  | { readonly kind: 'declared'; readonly declared: string[]; readonly unscanned: string[] }
+
+/** True when `root` is `detected` itself or an ancestor of it. */
+function rootCovers(root: string, detected: string): boolean {
+  const r = root.replace(/\/+$/, '')
+  return detected === r || detected.startsWith(`${r}/`)
+}
+
+/**
+ * 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.
+ */
+function reconcileRoots(cwd: string, opts: { write: boolean }): RootsState {
+  const declared = readBasaltConfig(cwd).roots
+  const detected = detectRoots(cwd)
+  if (declared !== undefined) {
+    const unscanned = detected.filter((d) => !declared.some((r) => rootCovers(r, d)))
+    return { kind: 'declared', declared, unscanned }
+  }
+  if (detected.length === 0) return { kind: 'undetectable' }
+  if (!opts.write) return { kind: 'declared', declared: [], unscanned: detected }
+  const wrote = patchPackageJson(cwd, (pkg) => {
+    const basalt = (pkg['basalt'] ?? {}) as Record<string, unknown>
+    if (basalt['roots'] !== undefined) return false
+    pkg['basalt'] = { ...basalt, roots: detected }
+    return true
+  })
+  return wrote ? { kind: 'wrote', roots: detected } : { kind: 'undetectable' }
+}
+
+/** The lines `init`/`sync` print for a roots reconciliation. Empty when there is nothing to say. */
+function rootsNotices(state: RootsState): { log: string[]; error: string[] } {
+  if (state.kind === 'wrote') {
+    return {
+      log: [
+        `wrote "basalt": { "roots": ${JSON.stringify(state.roots)} } to package.json — ` +
+          'check-theme, the CI oxfmt globs and the default scan exemption all derive from it. ' +
+          'Correct it if your sources live elsewhere.',
+      ],
+      error: [],
+    }
+  }
+  if (state.kind === 'undetectable') {
+    return {
+      log: [],
+      error: [
+        'could not infer "basalt.roots" — no src/ here and no workspace package with one. Set ' +
+          '"basalt": { "roots": [...] } in package.json by hand, or check-theme will fail with ' +
+          '"0 files scanned".',
+      ],
+    }
+  }
+  if (state.unscanned.length === 0) return { log: [], error: [] }
+  if (state.declared.length === 0) {
+    return {
+      log: [],
+      error: [
+        `"basalt.roots" is not set — the guard is running on the built-in default ("${DEFAULT_ROOT}"). ` +
+          `This layout suggests ${JSON.stringify(state.unscanned)}; declare it in package.json.`,
+      ],
+    }
+  }
+  return {
+    log: [
+      `keeping your "basalt.roots" (${JSON.stringify(state.declared)}) — never overwritten. The ` +
+        `layout also has ${JSON.stringify(state.unscanned)}, which nothing scans; add it if it ` +
+        'should be guarded, or leave it if the exclusion is deliberate.',
+    ],
+    error: [],
+  }
+}
+
+/**
+ * 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".
+ */
+function stripJsonc(text: string): string {
+  let out = ''
+  let inString = false
+  let escaped = false
+  let i = 0
+  while (i < text.length) {
+    const ch = text[i] as string
+    if (inString) {
+      out += ch
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      i += 1
+      continue
+    }
+    if (ch === '"') {
+      inString = true
+      out += ch
+      i += 1
+      continue
+    }
+    if (ch === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1
+      continue
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      i += 2
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1
+      i += 2
+      continue
+    }
+    out += ch
+    i += 1
+  }
+  return out.replace(/,(\s*[}\]])/g, '$1')
+}
+
+/** Parse a JSONC document, or null when it does not parse at all. */
+function parseJsonc(text: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(stripJsonc(text)) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+/** Outcome of splicing the shipped preset into an `.oxlintrc.json` the consumer already had. */
+type MergeLintResult = 'added' | 'already' | 'absent' | 'unreadable' | 'has-comments'
+
+/**
+ * The `extends` entry pointing at the shipped oxlint preset, or null when none does.
+ *
+ * Returns the ENTRY rather than a boolean because the string alone proves nothing: a consumer that
+ * upgraded (or moved to an isolated linker) keeps a perfectly well-shaped
+ * `./node_modules/basalt-ui/configs/oxlint.json` that resolves to nothing, and oxlint then refuses
+ * to start with `NotFound` while a check built to prove the framework is ON reports green. The
+ * caller resolves this against the config's own directory — see `extendsSeam`.
+ */
+function basaltPresetEntry(entries: unknown): string | null {
+  if (!Array.isArray(entries)) return null
+  const match = entries.find(
+    (entry): entry is string =>
+      typeof entry === 'string' && entry.endsWith('basalt-ui/configs/oxlint.json'),
+  )
+  return match ?? null
+}
+
+// ── The two `extends` seams init writes once and nothing ever revisits ───────────────────────────
+//
+// `.oxlintrc.json` and `lefthook.yml` are consumer-owned after the first write: `sync` never
+// touches either. So 1.20.0's path-resolution fix reached NEW scaffolds only — every existing
+// monorepo consumer kept a root-relative `extends` that resolves to nothing. oxlint at least
+// hard-errors (`NotFound`). lefthook does not: a missing extends target merges to ZERO commands and
+// exits 0, so `lefthook dump` is clean and the repo silently has no pre-commit gate at all.
+//
+// Both seams therefore need a checker that resolves the path rather than pattern-matching the
+// string, and both `doctor` (the gate) and `sync` (the command an upgrade actually runs) report
+// through it.
+
+const LEFTHOOK_CONFIG_NAMES = ['lefthook.yml', 'lefthook.yaml', '.lefthook.yml', '.lefthook.yaml']
+
+/** The lefthook config present at `dir` (repo-root-relative name), or null when there is none. */
+function findLefthookConfig(dir: string): string | null {
+  return LEFTHOOK_CONFIG_NAMES.find((name) => existsSync(resolve(dir, name))) ?? null
+}
+
+/**
+ * The `extends:` entries of a lefthook YAML — the block-sequence form init seeds and the inline
+ * array form a consumer may write instead.
+ *
+ * A three-line reader rather than a YAML dependency: this parses ONE top-level key whose value is a
+ * list of plain scalars, and a wrong answer costs a diagnostic, never a write.
+ */
+function yamlUnquote(raw: string): string {
+  return raw.trim().replace(/^['"]|['"]$/g, '')
+}
+
+function yamlExtendsEntries(text: string): string[] {
+  const lines = text.split('\n')
+  const out: string[] = []
+  for (const [index, line] of lines.entries()) {
+    const inline = /^extends:\s*\[(.*)\]\s*$/.exec(line ?? '')
+    if (inline !== null) {
+      out.push(...(inline[1] ?? '').split(',').map(yamlUnquote).filter(Boolean))
+      continue
+    }
+    if (!/^extends:\s*(#.*)?$/.test(line ?? '')) continue
+    for (const next of lines.slice(index + 1)) {
+      if (/^\s*(#.*)?$/.test(next ?? '')) continue
+      const item = /^\s*-\s*(.+?)\s*$/.exec(next ?? '')
+      if (item === null) break
+      out.push(yamlUnquote(item[1] ?? ''))
+    }
+  }
+  return out
+}
+
+/** The state of one shipped-preset `extends` seam in a consumer-owned config. */
+type ExtendsSeam =
+  /** No such config file — nothing is wired, and that is a legitimate consumer choice. */
+  | { readonly kind: 'no-file' }
+  /** The file exists but names no basalt preset. */
+  | { readonly kind: 'unwired'; readonly file: string }
+  /** It names one, and the path resolves to nothing — the silent-gate case. */
+  | { readonly kind: 'broken'; readonly file: string; readonly entry: string }
+  | { readonly kind: 'ok'; readonly file: string; readonly entry: string }
+
+/**
+ * Resolve a lefthook config's basalt `extends` entry against the directory the config lives in —
+ * which is how lefthook itself resolves it.
+ */
+function inspectLefthookSeam(repoRoot: string): ExtendsSeam {
+  const file = findLefthookConfig(repoRoot)
+  if (file === null) return { kind: 'no-file' }
+  const raw = readIfExists(resolve(repoRoot, file))
+  if (raw === null) return { kind: 'no-file' }
+  const entry = yamlExtendsEntries(raw).find((e) => e.endsWith('basalt-ui/configs/lefthook.yml'))
+  if (entry === undefined) return { kind: 'unwired', file }
+  return existsSync(resolve(repoRoot, entry))
+    ? { kind: 'ok', file, entry }
+    : { kind: 'broken', file, entry }
+}
+
+/**
+ * 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.
+ */
+function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintResult {
+  const abs = resolve(cwd, '.oxlintrc.json')
+  const raw = readIfExists(abs)
+  if (raw === null) return 'absent'
+  const cfg = parseJsonc(raw)
+  if (cfg === null) return 'unreadable'
+  if (basaltPresetEntry(cfg['extends']) !== null) return 'already'
+  // Rewriting a JSONC config through JSON.stringify would silently delete the consumer's comments,
+  // which in a lint config are usually the WHY of every disabled rule. Refuse and say so.
+  if (stripJsonc(raw) !== raw) return 'has-comments'
+  const existing = Array.isArray(cfg['extends'])
+    ? (cfg['extends'] as unknown[]).filter((entry) => typeof entry === 'string')
+    : []
+  // Rebuild rather than spread, so `extends` keeps its original position when it was already there
+  // and lands first when it wasn't — a diff a human reviews should not reshuffle the whole file.
+  const merged: Record<string, unknown> = 'extends' in cfg ? {} : { extends: [presetPath] }
+  for (const [key, value] of Object.entries(cfg)) {
+    merged[key] = key === 'extends' ? [presetPath, ...existing] : value
+  }
+  const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? '  '
+  writeFileSync(abs, JSON.stringify(merged, null, indent) + (raw.endsWith('\n') ? '\n' : ''))
+  return 'added'
+}
+
+/**
+ * What a consumer LOSES by `init` keeping a file it already had — the half the aggregate
+ * `20 written, 2 kept` never said. A kept `.oxlintrc.json` is the headline case: the framework's
+ * whole lint half stays off, and every gate downstream reports green over it.
+ */
+const KEPT_FILE_COST: Record<string, string> = {
+  '.oxlintrc.json':
+    'the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / ' +
+    'unicorn plugins) is NOT active — nothing else turns it on, and every gate stays green ' +
+    'without it. Re-run with `--merge-lint` to splice the extends in, or add it by hand.',
+  'lefthook.yml':
+    'the pre-commit oxlint / oxfmt / check-theme jobs are not wired — add `extends: ' +
+    '[<preset>]` to your own file.',
+  '.github/workflows/check.yml':
+    'CI does not run check-theme or the sync drift gate — copy those steps into your own workflow.',
+  '.oxfmtrc.json': 'your existing formatter config stands; basalt formats nothing on its own.',
+  'DESIGN.md': 'the design brief Claude reads is yours, not the seeded one.',
+}
+
 /** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
 export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags = {}): number {
+  // ── Describe the repo BEFORE rendering anything ───────────────────────────
+  // Every roots-derived seed (the CI oxfmt globs, DESIGN.md's series path, the default scan
+  // exemption) renders from `basalt.roots`, so the key has to exist first. Writing it is what
+  // stops a workspace repo scaffolding a guard that scans zero files while doctor reports green.
+  const install = findBasaltInstall(cwd)
+  if (install.dir === null) {
+    console.error(
+      `⚠ basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it — the ` +
+        'seeded `extends` paths and CI steps are being written against the repo root by assumption. ' +
+        'Install basalt-ui here (or at the repo root) and re-run `basalt-ui init` so they resolve.',
+    )
+  }
+
+  const rootsState = reconcileRoots(cwd, { write: true })
+
+  // Built AFTER the roots patch — every roots-derived template variable reads the key just written.
   const ctx = renderContext(cwd)
+
+  // `basalt-tokens.md` tells the consumer to wire `oxlint . && basalt-ui check-theme` into their
+  // lint, and init's own closing message says to run check-theme next — but nothing ever added a
+  // script, so the guard stayed manual for exactly as long as someone remembered it.
+  const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`
+  const seededLintScript = patchPackageJson(cwd, (pkg) => {
+    const scripts = (pkg['scripts'] ?? {}) as Record<string, unknown>
+    if (scripts['lint:basalt'] !== undefined) return false
+    pkg['scripts'] = { ...scripts, 'lint:basalt': lintScript }
+    return true
+  })
+
   const manifest = readManifest(cwd)
   migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
   const peers = resolvePeerFlags(cwd, scaffoldFlags)
   const placement = resolvePlacement(cwd)
   const files = managedFiles(peers, placement)
 
-  let written = 0
-  let skipped = 0
+  const writtenFiles: string[] = []
+  const keptFiles: string[] = []
   const missingSources: string[] = []
 
   for (const file of files) {
@@ -1186,25 +2110,59 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
       // as locally drifted (skip unless --force), never silently clobbering a file the consumer
       // authored before init.
       manifest.files[file.dest] = sha256(normalizeForLedger(state.desired))
-      skipped++
+      keptFiles.push(file.dest)
       continue
     }
 
     const hash = writeUnit(file, cwd, state.desired)
     manifest.files[file.dest] = hash
-    written++
+    writtenFiles.push(file.dest)
   }
 
+  const mergeLint: MergeLintResult | null =
+    scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null
+
   manifest.basaltVersion = ctx.vars.BASALT_VERSION
   manifest.spacingScale = { ...deriveSpacing(0).scale }
   writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}\n`)
 
-  console.log(`basalt-ui init: ${written} written, ${skipped} kept, manifest at ${MANIFEST_PATH}`)
+  console.log(
+    `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`,
+  )
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
     )
   }
+  // Naming the kept files is the fix for the report's headline false-green: `20 written, 2 kept`
+  // named neither the file nor the consequence, so a repo that already had an `.oxlintrc.json`
+  // ended up with the framework's lint half off and every gate downstream reporting green.
+  if (keptFiles.length > 0) {
+    console.log(`\nKept (already present — basalt did not touch them):`)
+    for (const dest of keptFiles) {
+      const cost = KEPT_FILE_COST[dest]
+      console.log(cost === undefined ? `  · ${dest}` : `  · ${dest} — ${cost}`)
+    }
+  }
+  if (mergeLint !== null) {
+    const mergeMessage: Record<MergeLintResult, string> = {
+      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+      already: '.oxlintrc.json already extends the shipped preset — nothing to do',
+      absent:
+        'no existing .oxlintrc.json to merge into (the seeded one already extends the preset)',
+      unreadable: '.oxlintrc.json is not valid JSON — merge the extends entry by hand',
+      'has-comments':
+        '.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each ' +
+        `rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`,
+    }
+    console.log(`basalt-ui init: --merge-lint — ${mergeMessage[mergeLint]}`)
+  }
+  const rootsMessages = rootsNotices(rootsState)
+  for (const line of rootsMessages.log) console.log(`basalt-ui init: ${line}`)
+  for (const line of rootsMessages.error) console.error(`⚠ basalt-ui init: ${line}`)
+  if (seededLintScript) {
+    console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`)
+  }
   // lefthook.yml / .github/workflows/check.yml are repo-root-shaped — neither lefthook nor GitHub
   // Actions reads config from anywhere but the repo root, so a package living in a subdirectory
   // skips both rather than relocating them into a spot nothing reads.
@@ -1212,12 +2170,15 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
     console.log(
       `basalt-ui init: skipped lefthook.yml (this package is not the repo root — repo root ` +
         `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
-        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
+        `${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its ` +
+        `check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` ` +
+        'so the guard runs where your basalt config actually lives.',
     )
     console.log(
       `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root — ` +
         `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
-        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
+        `repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, 'configs/check.yml')} ` +
+        'into your root CI workflow instead.',
     )
   }
   if (placement.relocatedQueryClient !== null) {
@@ -1254,15 +2215,46 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
       `    ]\n` +
       `  }`,
   )
+  // `init` on an existing app is a LINT-DEBT EVENT, not a no-op — the shipped preset turns on whole
+  // oxlint plugins the repo was never linted against, so previously-clean code lands with real
+  // findings on the first run. Naming the plugins (derived from the preset, so the count can't
+  // drift) is what turns that from a nasty surprise into a scheduled triage.
+  const presetPlugins = readOxlintPresetPlugins(ctx.pkgRoot)
+  if (presetPlugins.length > 0) {
+    console.log(
+      `\nLint debt: adopting the shipped oxlint preset on an EXISTING app is not a no-op — it turns ` +
+        `on ${presetPlugins.length} plugins (${presetPlugins.join(', ')}) plus the basalt/* design ` +
+        'rules, on code never linted against them. Run `oxlint .` now and triage the count before ' +
+        'your next commit; turn a rule off in your own .oxlintrc.json with a written reason rather ' +
+        'than blanket-disabling a plugin.',
+    )
+  }
+  console.log(
+    'Activate the hooks: `lefthook install` — the seeded lefthook.yml is inert until the git hooks ' +
+      'are written, and looks configured either way.',
+  )
   // First adoption on a previously guard-clean repo can surface a wall of findings (the 1.0 guard
   // adds several rule kinds beyond a legacy local guard) — steer toward tuning config, not mass-allow.
   console.log(
-    '\nFirst run: run `basalt-ui check-theme` next, then tune the per-rule `basalt.*` config keys ' +
-      'in package.json for anything that fires — do not mass-`theme-allow` findings.',
+    `\nFirst run: run \`${ctx.vars.BASALT_BIN} check-theme\` next (or \`bun run lint:basalt\`), then ` +
+      'tune the per-rule `basalt.*` config keys in package.json for anything that fires — do not ' +
+      'mass-`theme-allow` findings. Then `basalt-ui doctor` to confirm the wiring actually took.',
   )
   return 0
 }
 
+/** The oxlint plugins the shipped preset switches on — read from the preset, never restated. */
+function readOxlintPresetPlugins(pkgRoot: string): string[] {
+  const raw = readSource(pkgRoot, 'configs/oxlint.json')
+  if (raw === null) return []
+  try {
+    const plugins = (JSON.parse(raw) as { plugins?: unknown }).plugins
+    return isStringArray(plugins) ? plugins : []
+  } catch {
+    return []
+  }
+}
+
 type SyncOptions = { force?: boolean; check?: boolean }
 
 /**
@@ -1273,6 +2265,8 @@ type SyncOptions = { force?: boolean; check?: boolean }
  * - `--force` overwrites locally-drifted files instead of skipping them.
  */
 export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): number {
+  // Before renderContext, which reads `basalt.roots` for the roots-derived template variables.
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true })
   const ctx = renderContext(cwd)
   const manifest = readManifest(cwd)
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
@@ -1350,6 +2344,35 @@ export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): numbe
     )
   }
 
+  const rootsMessages = rootsNotices(rootsState)
+  for (const line of rootsMessages.log) console.log(`basalt-ui sync: ${line}`)
+  for (const line of rootsMessages.error) console.error(`⚠ basalt-ui sync: ${line}`)
+
+  // The two `extends` seams sync does NOT own. Reported here because sync is the command an
+  // UPGRADE runs, and an upgrade is exactly when a resolved path goes stale — 1.20.0 fixed the
+  // paths `init` renders and reached no existing consumer at all. Informational: these are
+  // consumer-owned files, and `doctor` is the gate that fails on them.
+  const install = findBasaltInstall(cwd)
+  const lefthookSeam = inspectLefthookSeam(placement.repoRoot)
+  if (lefthookSeam.kind === 'broken') {
+    console.error(
+      `⚠ basalt-ui sync: ${lefthookSeam.file} extends "${lefthookSeam.entry}", which does not ` +
+        'exist — lefthook merges a missing extends target into ZERO commands and still exits 0, ' +
+        'so there is no pre-commit gate. Repoint it at ' +
+        `"${shippedAssetPath(install, placement.repoRoot, 'configs/lefthook.yml')}".`,
+    )
+  }
+  const oxlintrcRaw = readIfExists(resolve(cwd, '.oxlintrc.json'))
+  const oxlintEntry =
+    oxlintrcRaw === null ? null : basaltPresetEntry(parseJsonc(oxlintrcRaw)?.['extends'])
+  if (oxlintEntry !== null && !existsSync(resolve(cwd, oxlintEntry))) {
+    console.error(
+      `⚠ basalt-ui sync: .oxlintrc.json extends "${oxlintEntry}", which does not exist — oxlint ` +
+        'refuses to start on a missing extends target (`NotFound`). Repoint it at ' +
+        `"${shippedAssetPath(install, cwd, 'configs/oxlint.json')}".`,
+    )
+  }
+
   if (opts.check) {
     if (driftLines.length > 0) {
       console.error('basalt-ui sync --check: locally-drifted managed files:')
@@ -1480,7 +2503,7 @@ export function checkCoverage(): number {
   for (const exportKey of pkgExports) {
     if (exportKey === '.' || exportKey === './styles.css' || exportKey.startsWith('./configs/'))
       continue
-    if (!(exportKey in SURFACES)) {
+    if (!Object.hasOwn(SURFACES, exportKey)) {
       failures.push(`package.json exports key '${exportKey}' has no matching SURFACES entry`)
     }
   }
@@ -1577,8 +2600,25 @@ type DoctorResult = {
   hardFailures: number
   /** Number of warnings (informational only). */
   warnings: number
+  /**
+   * Number of checks that could not RUN (as opposed to ran and passed). Counted separately and
+   * exits non-zero on its own: under bun's isolated linker `doctor` used to drop two of its five
+   * checks and still print "All checks passed", which is the same false-green this whole surface
+   * exists to remove. A check that cannot run is not a check that passed.
+   */
+  skipped: number
 }
 
+/**
+ * Which shape of consumer `doctor` is looking at.
+ *
+ * `framework` — the Mantine app the scaffold is for. `tokens-only` — a consumer that took the
+ * `--vx-*` layer and nothing else (rollhook: no Mantine, no manifest, `tokens:css` output). Telling
+ * the second to "run `basalt-ui init`" is the wrong instruction: init scaffolds Mantine rules,
+ * skills and a DESIGN.md it will never read. Auto-detected, forced by `--framework` / `--tokens-only`.
+ */
+type DoctorProfile = 'framework' | 'tokens-only'
+
 type WorkspacePackage = { readonly name: string; readonly dir: string }
 
 /** {@link collectWorkspacePackages}'s return: the walked packages plus whether a `workspaces`
@@ -1783,9 +2823,27 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  * .basalt/manifest.json at the last init/sync. File-level drift is `sync --check`'s job, not
  * doctor's.
  *
+ * The checks are numbered in the order they run and print — there is no gap, and the number in a
+ * section header below is the number in the report.
+ *
  * Hard failures (exit non-zero):
  *   1. .basalt/manifest.json exists (init was run).
- *   6. `ai-major-parity`: every workspace package that declares the `ai` package agrees on its
+ *   2. `basalt-resolves`: basalt-ui resolves from here. Unresolvable used to make checks silently
+ *      VANISH from the report (5 checks became 3) while the footer still read "All checks passed".
+ *      It is also the moment `bunx basalt-ui` stops using the pinned copy.
+ *   6. `guard-scan`: `check-theme` would scan MORE than zero files. `check-theme` already exits 1
+ *      on "0 files scanned"; doctor disagreeing with it in the same repo is the bug.
+ *   7. `oxlint-preset`: the consumer's `.oxlintrc.json` actually `extends` the shipped preset AND
+ *      that path RESOLVES. `init` keeps an existing config, so the framework's whole lint half can
+ *      be off with nothing to say so — one repo carried six real violations invisibly across five
+ *      minors that way. Matching the string alone reproduced the same false green one layer in: a
+ *      well-shaped entry pointing at a path that no longer exists passed this check in the very
+ *      tree where oxlint refused to start with `NotFound`.
+ *   8. `lefthook-preset`: the repo-root lefthook config's `extends` target resolves. lefthook
+ *      merges a MISSING target into zero commands and exits 0 — no error, a clean `lefthook dump`,
+ *      and no pre-commit gate. Nothing but a check can see that. Not-extending-at-all is a warning
+ *      (a consumer may run their own hooks); extending a path that isn't there is a hard failure.
+ *   10. `ai-major-parity`: every workspace package that declares the `ai` package agrees on its
  *      major version. `basalt/ai-sdk-major` (the oxlint plugin rule) cannot catch this — it checks
  *      a linted file's NEAREST package.json, so a lint run scoped to one workspace package only
  *      ever sees that package's own `ai` major and is perfectly happy; the cross-package skew (one
@@ -1798,24 +2856,52 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      or invalid (empty/non-string) still hard-fails exactly as if the key were absent.
  *
  * Warnings (non-fatal):
- *   2. The installed node_modules/basalt-ui version matches the manifest's basaltVersion
+ *   3. The installed node_modules/basalt-ui version matches the manifest's basaltVersion
  *      (a mismatch means the package was upgraded but `sync` never ran — the placed doctrine is
  *      stale).
- *   3. The spacing scale still matches the one stamped into the manifest at the last init/sync
- *      (skipped when this CLI is demonstrably not the installed package — see the check).
- *   4. The running CLI's own version matches the installed basalt-ui (catches a stale
+ *   4. The spacing scale still matches the one stamped into the manifest at the last init/sync
+ *      (skipped when there is no manifest to compare against; a neutral pass when this CLI is
+ *      demonstrably not the installed package — see the check).
+ *   5. The running CLI's own version matches the installed basalt-ui (catches a stale
  *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
- *   5. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
+ *   9. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
  *      a public/ dir exists at all — skipped otherwise).
- *   7. A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the exemption is
- *      stale and can be deleted; an exemption nobody revisits is how a real, later skew slips
- *      through unnoticed.
+ *   10 (second half). A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the
+ *      exemption is stale and can be deleted; an exemption nobody revisits is how a real, later
+ *      skew slips through unnoticed.
+ *
+ * An AMBIGUOUS project (no config here, several workspace packages carrying one) short-circuits
+ * before any of them, exactly as `check-theme` does: running the remaining checks against the wrong
+ * root buries the one real error under spurious ones.
  *
- * Returns the exit code: 0 = all good, 1 = one or more hard failures.
+ * SKIPPED is now a third outcome beside pass/warn/fail and exits non-zero on its own — a check that
+ * cannot run is not a check that passed. "Not applicable to this profile" is a pass, not a skip.
+ *
+ * Returns the exit code: 0 = all good, 1 = one or more hard failures or unrunnable checks.
  */
-export function doctor(cwd: string = process.cwd()): number {
+export function doctor(invocationCwd: string = process.cwd(), flags: string[] = []): number {
+  if (conflictingProfileFlags(flags)) {
+    console.error('basalt-ui doctor: --tokens-only and --framework are alternatives — pass one.')
+    return 1
+  }
+  const project = resolveProjectDir(invocationCwd)
+  // Ambiguity is terminal, exactly as it is for check-theme. Falling back to `invocationCwd` ran
+  // every remaining check against the WRONG root and buried the one real error under spurious
+  // ones — guard-scan reporting 0 files, .oxlintrc.json "missing" — which is this round's own
+  // false-report bug class reappearing inside the fix for it.
+  if (project.ambiguous !== null) {
+    console.error(
+      `\nbasalt-ui doctor — ${invocationCwd}\n\n` +
+        `  ✖ no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace ` +
+        `packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
+        'run doctor from one of them, or set BASALT_CWD to pick.\n\n' +
+        '1 hard failure(s), 0 warning(s).\n',
+    )
+    return 1
+  }
+  const cwd = project.dir
   const cfg = readBasaltConfig(cwd)
-  const result: DoctorResult = { hardFailures: 0, warnings: 0 }
+  const result: DoctorResult = { hardFailures: 0, warnings: 0, skipped: 0 }
   const lines: string[] = [`\nbasalt-ui doctor — ${cwd}\n`]
 
   function pass(msg: string): void {
@@ -1825,32 +2911,85 @@ export function doctor(cwd: string = process.cwd()): number {
     lines.push(`  ⚠ ${msg}`)
     result.warnings++
   }
+  function skip(msg: string): void {
+    lines.push(`  ⊘ SKIPPED — ${msg}`)
+    result.skipped++
+  }
   function fail(msg: string): void {
     lines.push(`  ✖ ${msg}`)
     result.hardFailures++
   }
 
-  // ── Hard check 1: manifest exists ──────────────────────────────────────────
+  if (project.relocatedFrom !== null) {
+    lines.push(
+      `  → no basalt config at ${project.relocatedFrom} — reporting on ` +
+        `${relativePosix(project.relocatedFrom, cwd)}, where it lives.\n`,
+    )
+  }
+
+  // ── Profile ────────────────────────────────────────────────────────────────
   const manifestAbs = resolve(cwd, MANIFEST_PATH)
   const manifestExists = existsSync(manifestAbs)
-  if (manifestExists) {
+  const profile = inferredProfile(cwd, cfg, flags)
+  if (profile === 'tokens-only') {
+    lines.push(
+      '  profile: tokens-only — checking the token layer only. The scaffold checks below are not\n' +
+        '  applicable; `basalt-ui init` is NOT the fix here, it places a Mantine doctrine you have no\n' +
+        '  use for. Pass --framework to force the full profile.\n',
+    )
+    // check-theme will NOT infer this — it silences 17 kinds, so it moves only on a declaration.
+    // Doctor is the surface that can safely detect the shape, so it is the one that has to say so.
+    if (cfg.profile === undefined) {
+      lines.push(
+        '  → inferred (no .basalt/manifest.json and no @mantine/core in this workspace). Write it\n' +
+          '    down as "basalt": { "profile": "tokens-only" } in package.json — check-theme does not\n' +
+          '    infer it, so today it still reports the Mantine-only kinds against this repo.\n',
+      )
+    }
+  }
+
+  // ── Hard check 1: manifest exists ──────────────────────────────────────────
+  if (profile === 'tokens-only') {
+    pass(`${MANIFEST_PATH}: n/a — a tokens-only consumer has no scaffold to reconcile`)
+  } else if (manifestExists) {
     pass(`${MANIFEST_PATH} exists`)
   } else {
     fail(`${MANIFEST_PATH} missing — run \`basalt-ui init\` to scaffold the consumer repo`)
   }
 
-  // ── Warn check 2: installed basalt-ui version matches the manifest ─────────
+  // ── Hard check 2: basalt-ui resolves from here ─────────────────────────────
+  // Unresolvable used to make checks 3 and 5 VANISH from the report while the footer still read
+  // "All checks passed" — 5 checks silently became 3. It is also the moment `bunx basalt-ui`
+  // stops using the pinned copy and quietly downloads a different one from npm, so the failure
+  // has to be loud rather than absent.
+  const install = findBasaltInstall(cwd)
+  const installedVersion = install.version
+  if (install.dir === null) {
+    fail(
+      `basalt-ui does not resolve from ${cwd}, any directory above it, or any workspace package — ` +
+        'so every version check below is unrunnable, `extends: [<preset>]` cannot resolve, and ' +
+        '`bunx basalt-ui` will silently fetch a DIFFERENT copy from npm instead of your pinned ' +
+        'one. Add basalt-ui as a dependency here (or at the repo root) and re-run.',
+    )
+  } else if (install.how === 'cwd') {
+    pass(
+      `basalt-ui resolves at ./node_modules/basalt-ui (${installedVersion ?? 'unknown version'})`,
+    )
+  } else {
+    pass(
+      `basalt-ui resolves at ${relativePosix(cwd, install.dir)} (${installedVersion ?? 'unknown version'}, ` +
+        `found via the ${install.how}) — seeded \`extends\` paths and CI steps must use that path, ` +
+        'not ./node_modules/basalt-ui.',
+    )
+  }
+
+  // ── Warn check 3: installed basalt-ui version matches the manifest ─────────
   // THE one version axis. The manifest records the version whose init/sync placed the doctrine;
   // node_modules is what the app actually resolves. A mismatch means "upgrade landed, sync didn't".
-  const consumerPkgRaw = readIfExists(resolve(cwd, 'node_modules', 'basalt-ui', 'package.json'))
-  let installedVersion: string | null = null
-  if (consumerPkgRaw !== null) {
-    try {
-      const consumerPkg = JSON.parse(consumerPkgRaw) as { version?: string }
-      installedVersion = consumerPkg.version ?? null
-    } catch {
-      warn('could not parse node_modules/basalt-ui/package.json — version checks skipped')
-    }
+  if (profile === 'framework' && manifestExists && installedVersion === null) {
+    skip(
+      'installed-vs-manifest version — basalt-ui did not resolve, so there is nothing to compare',
+    )
   }
   if (manifestExists && installedVersion !== null) {
     const manifestVersion = readManifest(cwd).basaltVersion
@@ -1871,7 +3010,7 @@ export function doctor(cwd: string = process.cwd()): number {
 
   const cliVersion = readFrameworkVersion(packageRoot())
 
-  // ── Warn check 3: the spacing scale has not moved under the app ────────────
+  // ── Warn check 4: the spacing scale has not moved under the app ────────────
   // The only check here that reports a change in RENDERED OUTPUT rather than in placed files. A
   // retune of the spacing bases moves every surface in an app calling `createBasaltTheme()` bare,
   // and majors are banned by design, so nothing in the version number says so — 1.2.0's retune
@@ -1883,14 +3022,23 @@ export function doctor(cwd: string = process.cwd()): number {
   // `deriveSpacing` here is the RUNNING CLI's, which a stale `bunx basalt-ui` fetch makes a
   // different package. Rather than load the installed tokens entry (async, and doctor is sync),
   // the comparison is skipped whenever the two versions are known to disagree: a false "matches"
-  // is worse than no answer. Check 4 below names that disagreement, so this stays a neutral note.
+  // is worse than no answer. Check 5 below names that disagreement, so this stays a neutral note.
   const cliIsTheInstall = installedVersion === null || installedVersion === cliVersion
-  if (manifestExists && !cliIsTheInstall) {
+  if (profile === 'tokens-only') {
+    pass('spacing scale: n/a — a tokens-only consumer renders no basalt Mantine theme')
+  } else if (!manifestExists) {
+    // Printing NOTHING is the failure SKIPPED exists to end: the check simply vanished from the
+    // report whenever there was no manifest, which is precisely when it is least safe to assume.
+    skip(
+      `spacing scale — no ${MANIFEST_PATH} records the scale this app last synced with, so there ` +
+        'is nothing to compare against',
+    )
+  } else if (!cliIsTheInstall) {
     pass(
       `spacing scale not compared — this CLI (${cliVersion}) is not the installed basalt-ui ` +
         `(${installedVersion}), so its scale is not the one the app renders with`,
     )
-  } else if (manifestExists) {
+  } else {
     const recorded = readManifest(cwd).spacingScale
     const current = deriveSpacing(0).scale as Record<string, number>
     if (recorded === undefined) {
@@ -1916,29 +3064,137 @@ export function doctor(cwd: string = process.cwd()): number {
     }
   }
 
-  // ── Warn check 4: running CLI version matches the consumer's installed basalt-ui ────
+  // ── Warn check 5: running CLI version matches the consumer's installed basalt-ui ────
   // Catches the failure mode where bunx fetches a stale published package instead of the local
   // install — the CLI that ran doctor and the package resolved from the consumer's node_modules
   // silently disagree.
-  if (installedVersion !== null) {
-    if (installedVersion !== cliVersion) {
-      warn(
-        `running CLI version (${cliVersion}) differs from the installed basalt-ui version in ` +
-          `node_modules (${installedVersion}) — likely a stale \`bunx basalt-ui\` fetch from npm; ` +
-          'add basalt-ui as a root devDependency so the bin hoists from your workspace.',
+  if (installedVersion === null) {
+    skip('CLI-vs-installed version — basalt-ui did not resolve, so there is no installed version')
+  } else if (installedVersion !== cliVersion) {
+    warn(
+      `running CLI version (${cliVersion}) differs from the installed basalt-ui version at ` +
+        `${install.dir === null ? 'node_modules' : relativePosix(cwd, install.dir)} (${installedVersion}) — ` +
+        'likely a stale `bunx basalt-ui` fetch from npm; run the local bin ' +
+        '(`node_modules/.bin/basalt-ui`, or a package.json script) so the pinned copy is the one ' +
+        'that runs.',
+    )
+  } else {
+    pass(`CLI version (${cliVersion}) matches the installed basalt-ui`)
+  }
+
+  // ── Hard check 6: the guard would actually scan something ──────────────────
+  // `check-theme` exits 1 on "0 files scanned" — doctor reporting all-green in the SAME repo is
+  // the disagreement consumers reported: init ran, doctor passed, and the palette guard was a
+  // no-op the whole time because no `basalt.roots` described the workspace layout.
+  if (profile === 'tokens-only') {
+    pass('guard-scan: n/a — the theme guard is a Mantine-app check')
+  } else {
+    const scanned = scannableFiles(cwd, cfg)
+    if (scanned.length === 0) {
+      fail(
+        `guard-scan: check-theme would scan 0 files — the roots (${resolveRoots(cfg).join(', ')}) ` +
+          `match nothing under ${cwd}, so the palette guard is a no-op that still exits green in ` +
+          'every gate that does not run it. Set "basalt": { "roots": [...] } in package.json.',
       )
     } else {
-      pass(`CLI version (${cliVersion}) matches the installed basalt-ui in node_modules`)
+      pass(
+        `guard-scan: check-theme covers ${scanned.length} file(s) under ${resolveRoots(cfg).join(', ')}`,
+      )
     }
   }
 
-  // ── Warn check 5: basaltAppPlugin's default icon files exist in public/ ────
+  // ── Hard check 7: the consumer's oxlint config extends the shipped preset ──
+  // `init` KEEPS an existing `.oxlintrc.json`, so a repo can carry the whole scaffold with the
+  // framework's lint half switched off and nothing anywhere saying so. One repo ran five minors
+  // that way and surfaced six real `basalt/no-raw-font-size` errors the moment it was wired.
+  if (profile === 'tokens-only') {
+    pass('oxlint-preset: n/a — the shipped preset is a Mantine/React preset')
+  } else {
+    const oxlintrcRaw = readIfExists(resolve(cwd, '.oxlintrc.json'))
+    if (oxlintrcRaw === null) {
+      fail(
+        '.oxlintrc.json missing — the shipped oxlint preset (the basalt/* design rules) is not ' +
+          'active. Run `basalt-ui init` to seed it.',
+      )
+    } else {
+      // JSONC: oxlint accepts comments and real consumer configs carry them.
+      const parsed = parseJsonc(oxlintrcRaw)
+      if (parsed === null) {
+        skip(
+          '.oxlintrc.json does not parse as JSON/JSONC — cannot tell whether it extends the preset',
+        )
+      } else {
+        const entry = basaltPresetEntry(parsed['extends'])
+        const correct = shippedAssetPath(install, cwd, 'configs/oxlint.json')
+        if (entry === null) {
+          fail(
+            '.oxlintrc.json does NOT extend the shipped preset — every basalt/* design rule is off ' +
+              `and oxlint reports green without them. Add "extends": ["${correct}"], or re-run ` +
+              '`basalt-ui init --merge-lint` to splice it in.',
+          )
+        } else if (!existsSync(resolve(cwd, entry)) && entry === correct && install.dir !== null) {
+          // The path is the one basalt resolves from and the asset still isn't there — a partial
+          // or corrupted install, not a stale path. Saying "repoint it at <the same string>" would
+          // be the unhelpful shape of a correct diagnosis.
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) — ` +
+              'basalt-ui resolves there but ships no `configs/oxlint.json` at that path, so oxlint ' +
+              'refuses to start (`NotFound`) and nothing is linted. Reinstall basalt-ui.',
+          )
+        } else if (!existsSync(resolve(cwd, entry))) {
+          // The string is right and the file is not there. oxlint refuses to start at all
+          // (`invalid config file … NotFound`), so a green line here is a check that proves the
+          // framework is ON while the linter is dead — the same false-green class this check was
+          // added to close, one layer in. `install` already computed the true path in this run.
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) — ` +
+              'oxlint refuses to start on a missing extends target (`NotFound`), so nothing is ' +
+              `linted at all. Repoint it at "${correct}", where basalt-ui actually resolves.`,
+          )
+        } else {
+          pass(`.oxlintrc.json extends the shipped basalt-ui oxlint preset (${entry})`)
+        }
+      }
+    }
+  }
+
+  // ── Hard check 8: the lefthook preset's extends target actually exists ─────
+  // The loudest silent failure in the toolchain: lefthook merges a MISSING extends target into
+  // zero commands and exits 0 — `lefthook dump` prints the extends line, no commands, and a clean
+  // exit — so a repo whose path went stale has no pre-commit gate and nothing anywhere says so.
+  // Unlike oxlint there is no error to notice, which is why this has to be a check rather than a
+  // remedy line someone reads after a failure.
+  const repoRoot = findRepoRoot(cwd)
+  const lefthookSeam =
+    profile === 'tokens-only' ? { kind: 'n/a' as const } : inspectLefthookSeam(repoRoot)
+  const lefthookCorrect = shippedAssetPath(install, repoRoot, 'configs/lefthook.yml')
+  if (lefthookSeam.kind === 'n/a') {
+    pass('lefthook-preset: n/a — a tokens-only consumer wires its own hooks')
+  } else if (lefthookSeam.kind === 'no-file') {
+    pass(`lefthook-preset: n/a — no lefthook config at ${repoRoot}`)
+  } else if (lefthookSeam.kind === 'unwired') {
+    warn(
+      `${lefthookSeam.file} does not extend the shipped lefthook preset — the oxlint / oxfmt / ` +
+        `check-theme pre-commit jobs are not wired. Add "extends: [${lefthookCorrect}]" to it.`,
+    )
+  } else if (lefthookSeam.kind === 'broken') {
+    fail(
+      `${lefthookSeam.file} extends "${lefthookSeam.entry}", which does not exist ` +
+        `(${resolve(repoRoot, lefthookSeam.entry)}) — lefthook merges a missing extends ` +
+        'target into ZERO commands and still exits 0, so this repo has no pre-commit gate and ' +
+        `\`lefthook dump\` looks clean. Repoint it at "${lefthookCorrect}".`,
+    )
+  } else {
+    pass(`${lefthookSeam.file} extends the shipped lefthook preset (${lefthookSeam.entry})`)
+  }
+
+  // ── Warn check 8: basaltAppPlugin's default icon files exist in public/ ────
   // basalt-ui/vite's basaltAppPlugin (head/manifest metadata) references these filenames by
   // default (the realfavicongenerator convention). Only runs when a public/ dir exists at all —
   // apps that don't use the plugin, or don't use Vite's public-dir convention, get no false
   // warning. Best-effort: a custom `icons.dir` isn't visible here, so this checks the root only.
   const publicDir = resolve(cwd, 'public')
-  if (existsSync(publicDir)) {
+  if (profile === 'framework' && existsSync(publicDir)) {
     const iconFiles = [
       'favicon.ico',
       'favicon.svg',
@@ -1958,7 +3214,7 @@ export function doctor(cwd: string = process.cwd()): number {
     }
   }
 
-  // ── Hard check 6: ai package major version parity across workspace packages ─
+  // ── Hard check 9: ai package major version parity across workspace packages ─
   // basalt/ai-sdk-major (the lint rule) is per-file against the NEAREST package.json, so a lint
   // run scoped to one workspace package only ever sees that package's own `ai` major and is
   // perfectly happy. The real defect is CROSS-package (argo defect 1: apps/api on ai@5 producing a
@@ -2014,17 +3270,22 @@ export function doctor(cwd: string = process.cwd()): number {
   }
 
   // ── Report ──────────────────────────────────────────────────────────────────
+  // "All checks passed" is only printable when every check ran AND passed. A skipped check counts
+  // against the exit code on its own — the report that dropped two of five checks and still
+  // claimed green is the bug this footer exists to make impossible.
   lines.push('')
-  if (result.hardFailures === 0 && result.warnings === 0) {
+  if (result.hardFailures === 0 && result.warnings === 0 && result.skipped === 0) {
     lines.push('All checks passed.')
   } else {
-    if (result.hardFailures > 0)
-      lines.push(`${result.hardFailures} hard failure(s), ${result.warnings} warning(s).`)
-    else lines.push(`${result.warnings} warning(s).`)
+    const parts: string[] = []
+    if (result.hardFailures > 0) parts.push(`${result.hardFailures} hard failure(s)`)
+    if (result.skipped > 0) parts.push(`${result.skipped} check(s) SKIPPED (could not run)`)
+    parts.push(`${result.warnings} warning(s)`)
+    lines.push(`${parts.join(', ')}.`)
   }
   lines.push('')
 
-  if (result.hardFailures > 0) {
+  if (result.hardFailures > 0 || result.skipped > 0) {
     console.error(lines.join('\n'))
     return 1
   }
@@ -2164,6 +3425,99 @@ function flagValue(flags: string[], name: string): string | undefined {
   return value === undefined || value.startsWith('--') ? undefined : value
 }
 
+/**
+ * The generated-file header: the canonical marker line (imported from the guard, which owns it),
+ * then the version + invocation that produced the file.
+ *
+ * Both lines are load-bearing, not decoration — `checkSource` only exempts a stylesheet whose line
+ * 1 is the marker verbatim AND whose line 2 parses as this provenance line. Reword either half and
+ * basalt starts reporting its own output again (116 findings in rollhook's token sheet).
+ */
+function generatedHeader(version: string, command: string, flags: string[]): string {
+  const shown = flags.filter((f) => f !== '--check')
+  const invocation = shown.length === 0 ? command : `${command} ${shown.join(' ')}`
+  return `${GENERATED_HEADER_LINE}\n/* basalt-ui ${version} — \`basalt-ui ${invocation}\` */\n`
+}
+
+/**
+ * Space- and number-normalize the argument list of a legacy color function so the emitted file
+ * survives a normal repo's formatter.
+ *
+ * This is FORMATTING ONLY and deliberately the CLI's single deviation from "print exactly what
+ * `buildPaletteCss` returned": `rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
+ * colour, the shipped palette emits the first form on the dark side and the second on the light
+ * side, and a consumer committing the output ate a lint-ignore entry for the difference. The token
+ * VALUES are untouched — nothing here can change what basalt's tokens are.
+ *
+ * Trailing zeros go the same way and for the same reason: prettier rewrites `0.10` → `0.1`, so the
+ * two `rgba(28, 25, 23, 0.10)` alphas in the light shadow tokens were the whole reason the one
+ * framework-free consumer still could not lint its committed sheet — `--fix` and `tokens:css
+ * --check` disagreed forever, and the lint-ignore entry survived two releases. Only a bare decimal
+ * literal is touched (never a `%`, a `var()` or a unit), and `0.10`/`0.1` are the same number.
+ *
+ * Exported for tests, so the expectation can be computed rather than restated.
+ */
+export function normalizeColorFunctions(css: string): string {
+  return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn: string, args: string) => {
+    const parts = args.split(',').map((part) => normalizeCssNumber(part.trim()))
+    return `${fn}(${parts.join(', ')})`
+  })
+}
+
+/** `0.10` → `0.1`, `1.0` → `1`; anything that is not a bare decimal literal is returned verbatim. */
+function normalizeCssNumber(arg: string): string {
+  if (!/^\d+\.\d+$/.test(arg)) return arg
+  return arg.replace(/\.?0+$/, '')
+}
+
+/** A scheme-class emission uses this sentinel attribute, then rewrites it to a class selector. */
+const SCHEME_CLASS_SENTINEL = 'data-basalt-scheme-class'
+
+/**
+ * Write (or drift-check) a generated stylesheet. `--check` makes no writes and exits 1 when the
+ * file on disk differs from what would be emitted — the CI gate for a committed `tokens:css`
+ * artifact, mirroring `sync --check`. Without `--out` the content goes to stdout unchanged.
+ */
+function emitGeneratedCss(content: string, flags: string[], cwd: string, command: string): number {
+  const out = flagValue(flags, '--out')
+  const check = flags.includes('--check')
+  if (out === undefined) {
+    if (check) {
+      console.error(
+        `${command}: --check needs --out <path> — there is nothing to compare stdout to.`,
+      )
+      return 1
+    }
+    process.stdout.write(content)
+    return 0
+  }
+  const target = isAbsolute(out) ? out : resolve(cwd, out)
+  const shown = relative(cwd, target) || target
+  if (check) {
+    const onDisk = readIfExists(target)
+    if (onDisk === null) {
+      console.error(
+        `✖ ${command} --check: ${shown} does not exist — run without --check to write it.`,
+      )
+      return 1
+    }
+    if (onDisk === content) {
+      console.log(`✓ ${command} --check: ${shown} is up to date.`)
+      return 0
+    }
+    console.error(
+      `✖ ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today ` +
+        `(on disk ${onDisk.split('\n').length} lines, emitted ${content.split('\n').length}) — ` +
+        're-run the same command without --check and commit the result.',
+    )
+    return 1
+  }
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, content)
+  console.log(`wrote ${content.split('\n').length} lines → ${shown}`)
+  return 0
+}
+
 /**
  * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted.
  *
@@ -2173,12 +3527,16 @@ function flagValue(flags: string[], name: string): string | undefined {
  * same artifact for a consumer that does install; this command exists for the ones that shouldn't
  * have to just to change a selector.
  *
- * It parses flags and calls `buildPaletteCss` — nothing else. No emission logic, no post-processing
- * of the returned string: the CLI and the API must not be able to disagree about what basalt's
- * tokens are.
+ * It parses flags and calls `buildPaletteCss` for the token VALUES — the CLI and the API must not
+ * be able to disagree about what basalt's tokens are. What it adds is strictly file framing for an
+ * artifact a consumer COMMITS: the `@generated` header (the guard's skip marker), a trailing
+ * newline, and `rgba()` argument spacing. All three were reported by the one framework-free
+ * consumer as the reasons the output could not simply be committed.
  */
 export function tokensCss(flags: string[], cwd: string = process.cwd()): number {
   const attribute = flagValue(flags, '--selector-attribute')
+  const schemeClass = flagValue(flags, '--selector-class')
+  const lightClass = flagValue(flags, '--light-class')
   const darkValue = flagValue(flags, '--dark-value')
   const lightValue = flagValue(flags, '--light-value')
   const defaultScheme = flagValue(flags, '--default-scheme')
@@ -2195,14 +3553,39 @@ export function tokensCss(flags: string[], cwd: string = process.cwd()): number
     console.error(`tokens:css: --only must be core or all (got '${only}')`)
     return 1
   }
+  if (schemeClass !== undefined && attribute !== undefined) {
+    console.error(
+      'tokens:css: --selector-class and --selector-attribute are alternatives — pass one.',
+    )
+    return 1
+  }
+  if (schemeClass !== undefined && /[^\w-]/.test(schemeClass)) {
+    console.error(
+      `tokens:css: --selector-class must be a plain CSS class name (got '${schemeClass}')`,
+    )
+    return 1
+  }
+  if (lightClass !== undefined && /[^\w-]/.test(lightClass)) {
+    console.error(`tokens:css: --light-class must be a plain CSS class name (got '${lightClass}')`)
+    return 1
+  }
+
+  // A class selector is Tailwind's universal dark convention (`<html class="dark">`) and was
+  // reachable before only by parking dark on the bare `:root` via --default-scheme. `buildPaletteCss`
+  // emits attribute selectors, so the class form is produced by emitting against a sentinel
+  // attribute this CLI chose itself and rewriting exactly those selectors — a rewrite of strings
+  // the command generated deterministically, never of a token value.
+  const resolvedDarkValue = schemeClass !== undefined ? schemeClass : darkValue
+  const resolvedLightValue = schemeClass !== undefined ? (lightClass ?? 'light') : lightValue
+  const resolvedAttribute = schemeClass !== undefined ? SCHEME_CLASS_SENTINEL : attribute
 
   const scheme = {
-    ...(attribute === undefined ? {} : { attribute }),
-    ...(darkValue === undefined ? {} : { darkValue }),
-    ...(lightValue === undefined ? {} : { lightValue }),
+    ...(resolvedAttribute === undefined ? {} : { attribute: resolvedAttribute }),
+    ...(resolvedDarkValue === undefined ? {} : { darkValue: resolvedDarkValue }),
+    ...(resolvedLightValue === undefined ? {} : { lightValue: resolvedLightValue }),
   }
 
-  const css = buildPaletteCss({
+  let css = buildPaletteCss({
     ...(Object.keys(scheme).length === 0 ? {} : { scheme }),
     ...(defaultScheme === undefined
       ? {}
@@ -2216,16 +3599,59 @@ export function tokensCss(flags: string[], cwd: string = process.cwd()): number
     ...(flags.includes('--no-legacy-aliases') ? { legacyAliases: false } : {}),
   })
 
-  const out = flagValue(flags, '--out')
-  if (out === undefined) {
-    process.stdout.write(`${css}\n`)
-    return 0
+  if (schemeClass !== undefined) {
+    css = css.replace(
+      new RegExp(`\\[${SCHEME_CLASS_SENTINEL}='([\\w-]+)'\\]`, 'g'),
+      (_match, value: string) => `.${value}`,
+    )
   }
-  const target = isAbsolute(out) ? out : resolve(cwd, out)
-  mkdirSync(dirname(target), { recursive: true })
-  writeFileSync(target, css)
-  console.log(`wrote ${css.split('\n').length} lines → ${relative(cwd, target) || target}`)
-  return 0
+
+  const version = readFrameworkVersion(packageRoot())
+  const content = `${generatedHeader(version, 'tokens:css', flags)}${normalizeColorFunctions(css)}\n`
+  return emitGeneratedCss(content, flags, cwd, 'tokens:css')
+}
+
+/** Every `--basalt-font-*` declaration in the shipped stylesheet, in source order. */
+function readShippedFontDecls(pkgRoot: string): { name: string; value: string }[] {
+  const css = readSource(pkgRoot, 'dist/styles.css') ?? readSource(pkgRoot, 'src/styles.css')
+  if (css === null) return []
+  const decls: { name: string; value: string }[] = []
+  for (const match of css.matchAll(/(--basalt-font[\w-]*)\s*:\s*([^;]+);/g)) {
+    decls.push({
+      name: match[1] as string,
+      value: (match[2] as string).replace(/\s+/g, ' ').trim(),
+    })
+  }
+  return decls
+}
+
+/**
+ * fonts:css — emit the shipped `--basalt-font-*` stacks as plain CSS.
+ *
+ * The typeface half of the framework-free route, which had no supported path at all: `tokens.css`
+ * emits no font vars, `styles.css` is the one place the defaults live and a framework-free consumer
+ * is told not to import it, and `buildFontsCss` returns `''` unless the caller already knows the
+ * stacks. The one non-Mantine consumer lost its font identity entirely and hardcoded the stacks —
+ * which the theme guard then flagged as `raw-font-family`.
+ *
+ * The declarations are READ from the shipped stylesheet rather than restated here, so this command
+ * and `basalt-ui/styles.css` can never name different typefaces. Note the fonts themselves are
+ * `@fontsource-variable/*` packages: without them the stacks fall through to their own system
+ * fallbacks, which is the intended framework-free behaviour.
+ */
+export function fontsCss(flags: string[], cwd: string = process.cwd()): number {
+  const pkgRoot = packageRoot()
+  const decls = readShippedFontDecls(pkgRoot)
+  if (decls.length === 0) {
+    console.error(
+      'fonts:css: could not read the shipped font stacks from styles.css — this is a packaging ' +
+        'bug in basalt-ui, not a config error.',
+    )
+    return 1
+  }
+  const body = `:root {\n${decls.map((d) => `  ${d.name}: ${d.value};`).join('\n')}\n}\n`
+  const header = generatedHeader(readFrameworkVersion(pkgRoot), 'fonts:css', flags)
+  return emitGeneratedCss(`${header}${body}`, flags, cwd, 'fonts:css')
 }
 
 /**
@@ -2284,8 +3710,11 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: 'theme-allow',
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
+    exemptRules: resolveExemptRules(cfg),
     severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    // Same detection check-theme uses: the hook must never block an edit over advice the app
+    // cannot take ("use @mantine/core's Select") in a repo with no Mantine.
+    ...(declaredProfile(cfg, []) === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
   }
 
   // Honor the consumer's roots / exempt / skip config so the hook never blocks edits to exempted
@@ -2325,14 +3754,32 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
 
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 const USAGE =
-  'Usage: basalt-ui <init [--with-router] [--with-query] | sync [--force] [--check] | ' +
-  'check-theme | check-coverage | info [--json] | doctor | guard-hook | tokens:css | help>\n\n' +
-  'tokens:css [--out <path>] [--selector-attribute <attr>] [--dark-value <v>] [--light-value <v>]\n' +
+  'Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] | sync [--force] [--check] |\n' +
+  '                  check-theme [--audit-allows] | check-coverage | info [--json] |\n' +
+  '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
+  'check-theme [--tokens-only|--framework] [--audit-allows]\n' +
+  '  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n' +
+  '  `basalt.exemptRules` entry, with what each one still suppresses — proved by re-running the\n' +
+  '  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n' +
+  '  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\n' +
+  'tokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n' +
+  '           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n' +
   '           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n' +
   '           [--no-legacy-aliases]\n' +
   '  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n' +
+  '  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n' +
+  '  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n' +
   '  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n' +
   '  which are emitted by default as aliases of the canonical kebab-case names.\n\n' +
+  'fonts:css [--out <path>] [--check]\n' +
+  '  Emit the shipped --basalt-font-* stacks as plain CSS — the typeface half of the token layer,\n' +
+  '  otherwise reachable only by importing styles.css.\n\n' +
+  'doctor [--tokens-only|--framework]\n' +
+  '  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n' +
+  '  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\n' +
+  'check-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\n' +
+  'basalt config when invoked from a repo root that has none — several carrying one is ambiguous\n' +
+  'and exits 1 in BOTH. --tokens-only and --framework are alternatives; passing both is an error.\n\n' +
   'Every subcommand accepts --help / -h to print this message and exit without running.'
 
 /**
@@ -2363,21 +3810,24 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
       return init(cwd, {
         withRouter: flags.includes('--with-router'),
         withQuery: flags.includes('--with-query'),
+        mergeLint: flags.includes('--merge-lint'),
       })
     case 'sync':
       return sync({ force: flags.includes('--force'), check: flags.includes('--check') }, cwd)
     case 'check-theme':
-      return checkTheme(cwd)
+      return checkTheme(cwd, flags)
     case 'check-coverage':
       return checkCoverage()
     case 'info':
       return info(flags)
     case 'doctor':
-      return doctor(cwd)
+      return doctor(cwd, flags)
     case 'guard-hook':
       return guardHook(cwd)
     case 'tokens:css':
       return tokensCss(flags, cwd)
+    case 'fonts:css':
+      return fontsCss(flags, cwd)
     default:
       console.error(USAGE)
       return 1