basalt-ui 1.19.1 → 1.21.0

package/dist/cli/index.js

@@ -10,10 +10,35 @@ import {
 } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkSource, DEFAULT_GUARD_CONFIG, GUARD_RULES } from "../guard/index.js";
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
+  guardKindRemedy,
+  GUARD_RULES,
+  guardWaiverHint,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns
+} from "../guard/index.js";
 import { evaluateGuardHook } from "../guard/guard-hook.js";
 import { RULE_NAMES, SKILL_NAMES, SURFACES, TOKEN_LAYER_BOUNDARY_SURFACES } from "../surfaces.js";
 import { buildPaletteCss, deriveSpacing } from "../tokens/index.js";
+function exemptRulePaths(entry) {
+  if (entry === void 0) return [];
+  return Array.isArray(entry) ? entry : entry.paths;
+}
+function exemptRuleReason(entry) {
+  if (entry === void 0 || Array.isArray(entry)) return null;
+  return entry.reason.trim().length > 0 ? entry.reason.trim() : null;
+}
+function resolveExemptRules(cfg) {
+  if (cfg.exemptRules === void 0) return DEFAULT_GUARD_CONFIG.exemptRules;
+  const out = {};
+  for (const [kind, entry] of Object.entries(cfg.exemptRules)) {
+    out[kind] = exemptRulePaths(entry);
+  }
+  return out;
+}
 const DEFAULT_ROOT = "src";
 const DEFAULT_ROOTS = [DEFAULT_ROOT];
 function resolveRoots(cfg) {
@@ -61,6 +86,7 @@ function readBasaltConfig(cwd) {
     return {};
   }
 }
+const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
   let entries;
   try {
@@ -78,33 +104,149 @@ function walkSourceFiles(dir, out = []) {
       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;
 }
-const GUARD_KIND_EXPLANATIONS = {
-  "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 \u2014 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 \u2014 use VX.surface.* / --vx-surface-* (border/panel/subtle/bg) instead.",
-  "raw-html-layout": "raw-html-layout: raw HTML element with inline layout/surface styling \u2014 use a Mantine layout primitive (Box/Flex/Grid/Stack/Group).",
-  "inline-spacing": "inline-spacing: inline spacing literal \u2014 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 \u2014 use AxisLeftNumeric / AxisBottomDate / AxisRightNumeric from the charts primitives.",
-  "raw-motion-value": "raw-motion-value: hardcoded duration/spring/ease in `transition={{...}}` \u2014 use MOTION_DURATION / MOTION_SPRING / MOTION_EASE_STANDARD instead.",
-  "unframed-chart": "unframed-chart: hand-rolled ChartLegend built from an inline array literal \u2014 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 \u2014 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 \u2014 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."
-};
-function checkTheme(cwd = process.cwd()) {
-  const cfg = readBasaltConfig(cwd);
-  const roots = cfg.roots ?? DEFAULT_ROOTS;
+function relativePosix(fromDir, toPath) {
+  const rel = relative(fromDir, toPath).replace(/\\/g, "/");
+  if (rel === "") return ".";
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+const UNRESOLVED_INSTALL = { dir: null, version: null, how: null };
+function basaltInstallAt(dir) {
+  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);
+    return { dir: installDir, version: pkg.version ?? null };
+  } catch {
+    return { dir: installDir, version: null };
+  }
+}
+function findBasaltInstall(cwd) {
+  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;
+}
+function shippedAssetPath(install, fromDir, asset) {
+  if (install.dir === null) return `./node_modules/basalt-ui/${asset}`;
+  return `${relativePosix(fromDir, install.dir)}/${asset}`;
+}
+function hasBasaltProject(dir) {
+  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).basalt !== void 0;
+  } catch {
+    return false;
+  }
+}
+function resolveProjectDir(cwd) {
+  const override = process.env["BASALT_CWD"];
+  if (override !== void 0 && 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], relocatedFrom: cwd, ambiguous: null };
+  }
+  if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates };
+  return { dir: cwd, relocatedFrom: null, ambiguous: null };
+}
+function declaredProfile(cfg, flags) {
+  if (flags.includes("--tokens-only")) return "tokens-only";
+  if (flags.includes("--framework")) return "framework";
+  return cfg.profile === "tokens-only" ? "tokens-only" : "framework";
+}
+function conflictingProfileFlags(flags) {
+  return flags.includes("--tokens-only") && flags.includes("--framework");
+}
+function workspaceHasMantine(cwd) {
+  if (hasDependency(cwd, "@mantine/core")) return true;
+  return collectWorkspacePackages(cwd).packages.some(
+    (pkg) => hasDependency(pkg.dir, "@mantine/core")
+  );
+}
+function inferredProfile(cwd, cfg, flags) {
+  if (flags.includes("--tokens-only") || flags.includes("--framework") || cfg.profile !== void 0) {
+    return declaredProfile(cfg, flags);
+  }
+  return !existsSync(resolve(cwd, MANIFEST_PATH)) && !workspaceHasMantine(cwd) ? "tokens-only" : "framework";
+}
+function scannableFiles(cwd, cfg) {
   const exempt = new Set(cfg.exempt ?? defaultExempt(cfg));
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (abs) => {
+    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);
+  }
+  for (const rel of cfg.include ?? []) add(resolve(cwd, rel));
+  return out;
+}
+function appShellFiles(rootAbs) {
+  const appDir = dirname(rootAbs);
+  const out = [];
+  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;
+}
+function checkTheme(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error(
+      "basalt-ui check-theme: --tokens-only and --framework are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `\u2716 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(", ")}) \u2014 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} \u2014 running in ${relativePosix(project.relocatedFrom, cwd)}, where it lives.`
+    );
+  }
+  const cfg = readBasaltConfig(cwd);
+  const roots = resolveRoots(cfg);
+  const profile = declaredProfile(cfg, flags);
+  if (profile === "tokens-only") {
+    console.log(
+      `basalt-ui check-theme: tokens-only profile \u2014 ${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 = {
     spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
     rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
@@ -123,21 +265,16 @@ function checkTheme(cwd = process.cwd()) {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity
+    exemptRules: resolveExemptRules(cfg),
+    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    ...profile === "tokens-only" ? { profile: "tokens-only" } : {}
   };
   const findings = [];
-  let scannedCount = 0;
-  for (const root of roots) {
-    for (const f of walkSourceFiles(resolve(cwd, root))) {
-      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) {
     if (cfg.roots === void 0) {
       console.error(
         `\u2716 basalt-ui check-theme: 0 files scanned \u2014 no "basalt.roots" configured in package.json, and the built-in default roots (${DEFAULT_ROOTS.join(", ")}) matched zero files. Set "basalt": { "roots": [...] } in package.json to point at your source directories.`
@@ -149,6 +286,12 @@ function checkTheme(cwd = process.cwd()) {
     }
     return 1;
   }
+  if (flags.includes("--audit-allows")) return auditAllows(cwd, cfg, guardCfg, scanned);
+  for (const unmatched of unmatchedExemptPatterns(guardCfg, scanned)) {
+    console.error(
+      `\u26A0 basalt-ui check-theme: "basalt.exemptRules" entry ${unmatched.kind}: "${unmatched.pattern}" ` + (unmatched.reason === "unknown-kind" ? "names no guard kind \u2014 it exempts nothing at all (a typo, or a kind that was renamed)." : "matched none of the scanned files \u2014 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("\u2713 Theme guard: no off-palette colors.");
     return 0;
@@ -185,14 +328,9 @@ function checkTheme(cwd = process.cwd()) {
     report(errors, `\u2716 Theme guard: ${errors.length} off-palette / off-identity violation(s)
 `);
   }
-  const presentKinds = new Set(findings.map((f) => f.kind));
-  const explanations = Object.keys(GUARD_KIND_EXPLANATIONS).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(" "));
+  const presentKinds = [...new Set(findings.map((f) => f.kind))].toSorted();
+  const waiverHints = [...new Set(findings.map((f) => guardWaiverHint(f.relPath)))].toSorted();
+  console.error(["Fix:", ...presentKinds.map(guardKindRemedy), ...waiverHints].join(" "));
   if (findings.some((f) => SERIES_MODULE_HINT_RE.test(f.relPath))) {
     console.error(
       'Hint: if a flagged file IS your palette/series source, exempt it via "basalt": { "exempt": ["<path>"] } in package.json.'
@@ -200,6 +338,130 @@ function checkTheme(cwd = process.cwd()) {
   }
   return errors.length > 0 ? 1 : 0;
 }
+const AUDIT_NEUTRALIZED_TOKEN = "basalt-audit-neutralized";
+function findingKey(f) {
+  return `${f.relPath}:${f.line}:${f.kind}`;
+}
+const AUDIT_ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/;
+function annotationRuleIds(rest) {
+  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));
+}
+function isAllowAnnotationLine(line, token) {
+  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));
+}
+function auditAllows(cwd, cfg, guardCfg, scanned) {
+  const token = guardCfg.allowComment;
+  const lines = [`
+basalt-ui check-theme --audit-allows \u2014 ${cwd}
+`];
+  let dead = 0;
+  let live = 0;
+  let outOfReach = 0;
+  let unaccountable = 0;
+  const waiverLines = [];
+  const sources = /* @__PURE__ */ new Map();
+  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 !== void 0) unaccountable++;
+      const site = `  ${rel}:${index + 1}`.padEnd(52);
+      const suffix = note === void 0 ? "" : ` [${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(", ")} \u2014 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 \u2014 dead, delete it${suffix}`);
+      }
+    }
+  }
+  lines.push(`${token} annotations (${waiverLines.length}):`);
+  lines.push(...waiverLines.length === 0 ? ["  (none)"] : waiverLines);
+  const exemptLines = [];
+  let exemptCount = 0;
+  const declared = Object.entries(cfg.exemptRules ?? {});
+  if (declared.length > 0) {
+    const baselineKeys = /* @__PURE__ */ new Set();
+    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 = {
+          ...guardCfg,
+          exemptRules: {
+            ...guardCfg.exemptRules,
+            [kind]: exemptRulePaths(entry).filter((p) => p !== pattern)
+          }
+        };
+        const revealed = /* @__PURE__ */ new Set();
+        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]" : ` \u2014 ${reason}`;
+        if (revealed.size === 0) {
+          dead++;
+          const unmatched = unmatchedExemptPatterns(guardCfg, scanned).find(
+            (u) => u.kind === kind && u.pattern === pattern
+          );
+          exemptLines.push(
+            `${site} SUPPRESSES NOTHING \u2014 ` + (unmatched === void 0 ? "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(`
+basalt.exemptRules entries (${exemptCount}):`);
+  lines.push(...exemptLines.length === 0 ? ["  (none)"] : exemptLines);
+  lines.push(
+    `
+${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;
+}
 const BLOCK_BEGIN_PREFIX = "<!-- basalt:begin";
 const BLOCK_END = "<!-- basalt:end -->";
 const MANIFEST_PATH = ".basalt/manifest.json";
@@ -230,12 +492,17 @@ function readFrameworkVersion(pkgRoot) {
   }
 }
 function buildTemplateVars(pkgRoot, cwd, cfg) {
+  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(" ")
+    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`
   };
 }
 function fillTemplate(tpl, vars) {
@@ -383,7 +650,30 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     dest: "lefthook.yml",
     mode: "seed",
     source: "configs/lefthook.yml",
-    render: () => "# Seeded by basalt-ui init \u2014 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.\nextends:\n  - node_modules/basalt-ui/configs/lefthook.yml\n"
+    render: (ctx) => `# Seeded by basalt-ui init \u2014 you own this file; sync never touches it again.
+# The extends target supplies oxlint + oxfmt + check-theme pre-commit jobs and
+# auto-updates with the basalt-ui package. Add your own commands alongside.
+# The path is RESOLVED from where basalt-ui actually installed, not assumed at the
+# repo root \u2014 under an isolated linker it lives beside the package that depends on it.
+# Run \`lefthook install\` once: the file is inert until the git hooks are written.
+#
+# NOTE: an extends target WINS on a colliding key \u2014 a \`run:\`/\`glob:\` you write under one of
+# the preset's command names is discarded silently. \`env:\`, \`exclude:\`, \`skip:\` and your own
+# command names merge. See the preset itself for the sanctioned override seams.
+extends:
+  - ${ctx.vars.LEFTHOOK_PRESET_PATH.replace(/^\.\//, "")}
+` + // 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 ") ? "" : `
+# The theme guard runs the LOCAL bin, not a copy \`bunx\` fetches from npm.
+pre-commit:
+  commands:
+    check-theme:
+      env:
+        BASALT_BIN: ${ctx.vars.BASALT_BIN}
+`)
   };
   const ci = {
     dest: ".github/workflows/check.yml",
@@ -399,7 +689,10 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     dest: ".oxlintrc.json",
     mode: "seed",
     source: "configs/oxlint.json",
-    render: () => '{\n  "extends": ["./node_modules/basalt-ui/configs/oxlint.json"]\n}\n'
+    render: (ctx) => `{
+  "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"]
+}
+`
   };
   const queryClient = {
     dest: "src/query-client.ts",
@@ -510,15 +803,219 @@ function renderContext(cwd) {
   const pkgRoot = packageRoot();
   return { pkgRoot, vars: buildTemplateVars(pkgRoot, cwd, readBasaltConfig(cwd)) };
 }
+function patchPackageJson(cwd, mutate) {
+  const abs = resolve(cwd, "package.json");
+  const raw = readIfExists(abs);
+  if (raw === null) return false;
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } 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;
+}
+function detectRoots(cwd) {
+  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] : [];
+}
+function rootCovers(root, detected) {
+  const r = root.replace(/\/+$/, "");
+  return detected === r || detected.startsWith(`${r}/`);
+}
+function reconcileRoots(cwd, opts) {
+  const declared = readBasaltConfig(cwd).roots;
+  const detected = detectRoots(cwd);
+  if (declared !== void 0) {
+    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"] ?? {};
+    if (basalt["roots"] !== void 0) return false;
+    pkg["basalt"] = { ...basalt, roots: detected };
+    return true;
+  });
+  return wrote ? { kind: "wrote", roots: detected } : { kind: "undetectable" };
+}
+function rootsNotices(state) {
+  if (state.kind === "wrote") {
+    return {
+      log: [
+        `wrote "basalt": { "roots": ${JSON.stringify(state.roots)} } to package.json \u2014 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" \u2014 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 \u2014 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)}) \u2014 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: []
+  };
+}
+function stripJsonc(text) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    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");
+}
+function parseJsonc(text) {
+  try {
+    return JSON.parse(stripJsonc(text));
+  } catch {
+    return null;
+  }
+}
+function basaltPresetEntry(entries) {
+  if (!Array.isArray(entries)) return null;
+  const match = entries.find(
+    (entry) => typeof entry === "string" && entry.endsWith("basalt-ui/configs/oxlint.json")
+  );
+  return match ?? null;
+}
+const LEFTHOOK_CONFIG_NAMES = ["lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml"];
+function findLefthookConfig(dir) {
+  return LEFTHOOK_CONFIG_NAMES.find((name) => existsSync(resolve(dir, name))) ?? null;
+}
+function yamlUnquote(raw) {
+  return raw.trim().replace(/^['"]|['"]$/g, "");
+}
+function yamlExtendsEntries(text) {
+  const lines = text.split("\n");
+  const out = [];
+  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;
+}
+function inspectLefthookSeam(repoRoot) {
+  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 === void 0) return { kind: "unwired", file };
+  return existsSync(resolve(repoRoot, entry)) ? { kind: "ok", file, entry } : { kind: "broken", file, entry };
+}
+function mergeOxlintExtends(cwd, presetPath) {
+  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";
+  if (stripJsonc(raw) !== raw) return "has-comments";
+  const existing = Array.isArray(cfg["extends"]) ? cfg["extends"].filter((entry) => typeof entry === "string") : [];
+  const merged = "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";
+}
+const KEPT_FILE_COST = {
+  ".oxlintrc.json": "the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / unicorn plugins) is NOT active \u2014 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 \u2014 add `extends: [<preset>]` to your own file.",
+  ".github/workflows/check.yml": "CI does not run check-theme or the sync drift gate \u2014 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."
+};
 function init(cwd = process.cwd(), scaffoldFlags = {}) {
+  const install = findBasaltInstall(cwd);
+  if (install.dir === null) {
+    console.error(
+      `\u26A0 basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it \u2014 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 });
   const ctx = renderContext(cwd);
+  const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`;
+  const seededLintScript = patchPackageJson(cwd, (pkg) => {
+    const scripts = pkg["scripts"] ?? {};
+    if (scripts["lint:basalt"] !== void 0) 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 = [];
+  const keptFiles = [];
   const missingSources = [];
   for (const file of files) {
     const state = unitState(file, cwd, ctx);
@@ -529,29 +1026,56 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     const destExists = existsSync(resolve(cwd, file.dest));
     if (!file.markers && destExists) {
       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 = 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)}
 `);
-  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(", ")}`
     );
   }
+  if (keptFiles.length > 0) {
+    console.log(`
+Kept (already present \u2014 basalt did not touch them):`);
+    for (const dest of keptFiles) {
+      const cost = KEPT_FILE_COST[dest];
+      console.log(cost === void 0 ? `  \xB7 ${dest}` : `  \xB7 ${dest} \u2014 ${cost}`);
+    }
+  }
+  if (mergeLint !== null) {
+    const mergeMessage = {
+      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+      already: ".oxlintrc.json already extends the shipped preset \u2014 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 \u2014 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 \u2014 ${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(`\u26A0 basalt-ui init: ${line}`);
+  if (seededLintScript) {
+    console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`);
+  }
   if (!placement.isPackageRepoRoot) {
     console.log(
-      `basalt-ui init: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.`
+      `basalt-ui init: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend ${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 \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.`
+      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, "configs/check.yml")} into your root CI workflow instead.`
     );
   }
   if (placement.relocatedQueryClient !== null) {
@@ -581,12 +1105,34 @@ Theme guard hook: add to .claude/settings.json \u2192 hooks.PreToolUse to catch
     ]
   }`
   );
+  const presetPlugins = readOxlintPresetPlugins(ctx.pkgRoot);
+  if (presetPlugins.length > 0) {
+    console.log(
+      `
+Lint debt: adopting the shipped oxlint preset on an EXISTING app is not a no-op \u2014 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` \u2014 the seeded lefthook.yml is inert until the git hooks are written, and looks configured either way."
+  );
   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 \u2014 do not mass-`theme-allow` findings."
+    `
+First 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 \u2014 do not mass-\`theme-allow\` findings. Then \`basalt-ui doctor\` to confirm the wiring actually took.`
   );
   return 0;
 }
+function readOxlintPresetPlugins(pkgRoot) {
+  const raw = readSource(pkgRoot, "configs/oxlint.json");
+  if (raw === null) return [];
+  try {
+    const plugins = JSON.parse(raw).plugins;
+    return isStringArray(plugins) ? plugins : [];
+  } catch {
+    return [];
+  }
+}
 function sync(opts = {}, cwd = process.cwd()) {
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true });
   const ctx = renderContext(cwd);
   const manifest = readManifest(cwd);
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest);
@@ -642,6 +1188,23 @@ function sync(opts = {}, cwd = process.cwd()) {
       `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ${relative(cwd, placement.relocatedQueryClient)}) \u2014 import it from there instead of re-seeding at the original path.`
     );
   }
+  const rootsMessages = rootsNotices(rootsState);
+  for (const line of rootsMessages.log) console.log(`basalt-ui sync: ${line}`);
+  for (const line of rootsMessages.error) console.error(`\u26A0 basalt-ui sync: ${line}`);
+  const install = findBasaltInstall(cwd);
+  const lefthookSeam = inspectLefthookSeam(placement.repoRoot);
+  if (lefthookSeam.kind === "broken") {
+    console.error(
+      `\u26A0 basalt-ui sync: ${lefthookSeam.file} extends "${lefthookSeam.entry}", which does not exist \u2014 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(
+      `\u26A0 basalt-ui sync: .oxlintrc.json extends "${oxlintEntry}", which does not exist \u2014 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:");
@@ -725,7 +1288,7 @@ function checkCoverage() {
   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`);
     }
   }
@@ -880,9 +1443,27 @@ function resolveAiMajorSkewReason(cfg) {
   }
   return { reason: null, presentButInvalid: true };
 }
-function doctor(cwd = process.cwd()) {
+function doctor(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error("basalt-ui doctor: --tokens-only and --framework are alternatives \u2014 pass one.");
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `
+basalt-ui doctor \u2014 ${invocationCwd}
+
+  \u2716 no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run doctor from one of them, or set BASALT_CWD to pick.
+
+1 hard failure(s), 0 warning(s).
+`
+    );
+    return 1;
+  }
+  const cwd = project.dir;
   const cfg = readBasaltConfig(cwd);
-  const result = { hardFailures: 0, warnings: 0 };
+  const result = { hardFailures: 0, warnings: 0, skipped: 0 };
   const lines = [`
 basalt-ui doctor \u2014 ${cwd}
 `];
@@ -893,26 +1474,59 @@ basalt-ui doctor \u2014 ${cwd}
     lines.push(`  \u26A0 ${msg}`);
     result.warnings++;
   }
+  function skip(msg) {
+    lines.push(`  \u2298 SKIPPED \u2014 ${msg}`);
+    result.skipped++;
+  }
   function fail(msg) {
     lines.push(`  \u2716 ${msg}`);
     result.hardFailures++;
   }
+  if (project.relocatedFrom !== null) {
+    lines.push(
+      `  \u2192 no basalt config at ${project.relocatedFrom} \u2014 reporting on ${relativePosix(project.relocatedFrom, cwd)}, where it lives.
+`
+    );
+  }
   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 \u2014 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"
+    );
+    if (cfg.profile === void 0) {
+      lines.push(
+        '  \u2192 inferred (no .basalt/manifest.json and no @mantine/core in this workspace). Write it\n    down as "basalt": { "profile": "tokens-only" } in package.json \u2014 check-theme does not\n    infer it, so today it still reports the Mantine-only kinds against this repo.\n'
+      );
+    }
+  }
+  if (profile === "tokens-only") {
+    pass(`${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile`);
+  } else if (manifestExists) {
     pass(`${MANIFEST_PATH} exists`);
   } else {
     fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
   }
-  const consumerPkgRaw = readIfExists(resolve(cwd, "node_modules", "basalt-ui", "package.json"));
-  let installedVersion = null;
-  if (consumerPkgRaw !== null) {
-    try {
-      const consumerPkg = JSON.parse(consumerPkgRaw);
-      installedVersion = consumerPkg.version ?? null;
-    } catch {
-      warn("could not parse node_modules/basalt-ui/package.json \u2014 version checks skipped");
-    }
+  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 \u2014 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}) \u2014 seeded \`extends\` paths and CI steps must use that path, not ./node_modules/basalt-ui.`
+    );
+  }
+  if (profile === "framework" && manifestExists && installedVersion === null) {
+    skip(
+      "installed-vs-manifest version \u2014 basalt-ui did not resolve, so there is nothing to compare"
+    );
   }
   if (manifestExists && installedVersion !== null) {
     const manifestVersion = readManifest(cwd).basaltVersion;
@@ -930,11 +1544,17 @@ basalt-ui doctor \u2014 ${cwd}
   }
   const cliVersion = readFrameworkVersion(packageRoot());
   const cliIsTheInstall = installedVersion === null || installedVersion === cliVersion;
-  if (manifestExists && !cliIsTheInstall) {
+  if (profile === "tokens-only") {
+    pass("spacing scale: n/a \u2014 a tokens-only consumer renders no basalt Mantine theme");
+  } else if (!manifestExists) {
+    skip(
+      `spacing scale \u2014 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 \u2014 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;
     if (recorded === void 0) {
@@ -951,17 +1571,84 @@ basalt-ui doctor \u2014 ${cwd}
       }
     }
   }
-  if (installedVersion !== null) {
-    if (installedVersion !== cliVersion) {
-      warn(
-        `running CLI version (${cliVersion}) differs from the installed basalt-ui version in node_modules (${installedVersion}) \u2014 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 \u2014 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}) \u2014 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`);
+  }
+  if (profile === "tokens-only") {
+    pass("guard-scan: n/a \u2014 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 \u2014 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(
+        `guard-scan: check-theme covers ${scanned.length} file(s) under ${resolveRoots(cfg).join(", ")}`
+      );
+    }
+  }
+  if (profile === "tokens-only") {
+    pass("oxlint-preset: n/a \u2014 the shipped preset is a Mantine/React preset");
+  } else {
+    const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
+    if (oxlintrcRaw === null) {
+      fail(
+        ".oxlintrc.json missing \u2014 the shipped oxlint preset (the basalt/* design rules) is not active. Run `basalt-ui init` to seed it."
       );
     } else {
-      pass(`CLI version (${cliVersion}) matches the installed basalt-ui in node_modules`);
+      const parsed = parseJsonc(oxlintrcRaw);
+      if (parsed === null) {
+        skip(
+          ".oxlintrc.json does not parse as JSON/JSONC \u2014 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 \u2014 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) {
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) \u2014 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))) {
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) \u2014 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})`);
+        }
+      }
     }
   }
+  const repoRoot = findRepoRoot(cwd);
+  const lefthookSeam = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookSeam(repoRoot);
+  const lefthookCorrect = shippedAssetPath(install, repoRoot, "configs/lefthook.yml");
+  if (lefthookSeam.kind === "n/a") {
+    pass("lefthook-preset: n/a \u2014 a tokens-only consumer wires its own hooks");
+  } else if (lefthookSeam.kind === "no-file") {
+    pass(`lefthook-preset: n/a \u2014 no lefthook config at ${repoRoot}`);
+  } else if (lefthookSeam.kind === "unwired") {
+    warn(
+      `${lefthookSeam.file} does not extend the shipped lefthook preset \u2014 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)}) \u2014 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})`);
+  }
   const publicDir = resolve(cwd, "public");
-  if (existsSync(publicDir)) {
+  if (profile === "framework" && existsSync(publicDir)) {
     const iconFiles = [
       "favicon.ico",
       "favicon.svg",
@@ -1013,15 +1700,17 @@ basalt-ui doctor \u2014 ${cwd}
     pass("ai-major-parity: no workspace package declares the ai dependency \u2014 nothing to compare");
   }
   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 = [];
+    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;
   }
@@ -1101,8 +1790,65 @@ function flagValue(flags, name) {
   const value = flags[i + 1];
   return value === void 0 || value.startsWith("--") ? void 0 : value;
 }
+function generatedHeader(version, command, flags) {
+  const shown = flags.filter((f) => f !== "--check");
+  const invocation = shown.length === 0 ? command : `${command} ${shown.join(" ")}`;
+  return `${GENERATED_HEADER_LINE}
+/* basalt-ui ${version} \u2014 \`basalt-ui ${invocation}\` */
+`;
+}
+function normalizeColorFunctions(css) {
+  return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
+    const parts = args.split(",").map((part) => normalizeCssNumber(part.trim()));
+    return `${fn}(${parts.join(", ")})`;
+  });
+}
+function normalizeCssNumber(arg) {
+  if (!/^\d+\.\d+$/.test(arg)) return arg;
+  return arg.replace(/\.?0+$/, "");
+}
+const SCHEME_CLASS_SENTINEL = "data-basalt-scheme-class";
+function emitGeneratedCss(content, flags, cwd, command) {
+  const out = flagValue(flags, "--out");
+  const check = flags.includes("--check");
+  if (out === void 0) {
+    if (check) {
+      console.error(
+        `${command}: --check needs --out <path> \u2014 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(
+        `\u2716 ${command} --check: ${shown} does not exist \u2014 run without --check to write it.`
+      );
+      return 1;
+    }
+    if (onDisk === content) {
+      console.log(`\u2713 ${command} --check: ${shown} is up to date.`);
+      return 0;
+    }
+    console.error(
+      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${onDisk.split("\n").length} lines, emitted ${content.split("\n").length}) \u2014 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 \u2192 ${shown}`);
+  return 0;
+}
 function tokensCss(flags, cwd = process.cwd()) {
   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");
@@ -1117,12 +1863,31 @@ function tokensCss(flags, cwd = process.cwd()) {
     console.error(`tokens:css: --only must be core or all (got '${only}')`);
     return 1;
   }
+  if (schemeClass !== void 0 && attribute !== void 0) {
+    console.error(
+      "tokens:css: --selector-class and --selector-attribute are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  if (schemeClass !== void 0 && /[^\w-]/.test(schemeClass)) {
+    console.error(
+      `tokens:css: --selector-class must be a plain CSS class name (got '${schemeClass}')`
+    );
+    return 1;
+  }
+  if (lightClass !== void 0 && /[^\w-]/.test(lightClass)) {
+    console.error(`tokens:css: --light-class must be a plain CSS class name (got '${lightClass}')`);
+    return 1;
+  }
+  const resolvedDarkValue = schemeClass !== void 0 ? schemeClass : darkValue;
+  const resolvedLightValue = schemeClass !== void 0 ? lightClass ?? "light" : lightValue;
+  const resolvedAttribute = schemeClass !== void 0 ? SCHEME_CLASS_SENTINEL : attribute;
   const scheme = {
-    ...attribute === void 0 ? {} : { attribute },
-    ...darkValue === void 0 ? {} : { darkValue },
-    ...lightValue === void 0 ? {} : { lightValue }
+    ...resolvedAttribute === void 0 ? {} : { attribute: resolvedAttribute },
+    ...resolvedDarkValue === void 0 ? {} : { darkValue: resolvedDarkValue },
+    ...resolvedLightValue === void 0 ? {} : { lightValue: resolvedLightValue }
   };
-  const css = buildPaletteCss({
+  let css = buildPaletteCss({
     ...Object.keys(scheme).length === 0 ? {} : { scheme },
     ...defaultScheme === void 0 ? {} : { defaultScheme },
     ...flags.includes("--media-fallback") ? { mediaFallback: true } : {},
@@ -1133,17 +1898,44 @@ function tokensCss(flags, cwd = process.cwd()) {
     // are, which is the one thing this command is documented never to allow.
     ...flags.includes("--no-legacy-aliases") ? { legacyAliases: false } : {}
   });
-  const out = flagValue(flags, "--out");
-  if (out === void 0) {
-    process.stdout.write(`${css}
-`);
-    return 0;
+  if (schemeClass !== void 0) {
+    css = css.replace(
+      new RegExp(`\\[${SCHEME_CLASS_SENTINEL}='([\\w-]+)'\\]`, "g"),
+      (_match, value) => `.${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 \u2192 ${relative(cwd, target) || target}`);
-  return 0;
+  const version = readFrameworkVersion(packageRoot());
+  const content = `${generatedHeader(version, "tokens:css", flags)}${normalizeColorFunctions(css)}
+`;
+  return emitGeneratedCss(content, flags, cwd, "tokens:css");
+}
+function readShippedFontDecls(pkgRoot) {
+  const css = readSource(pkgRoot, "dist/styles.css") ?? readSource(pkgRoot, "src/styles.css");
+  if (css === null) return [];
+  const decls = [];
+  for (const match of css.matchAll(/(--basalt-font[\w-]*)\s*:\s*([^;]+);/g)) {
+    decls.push({
+      name: match[1],
+      value: match[2].replace(/\s+/g, " ").trim()
+    });
+  }
+  return decls;
+}
+function fontsCss(flags, cwd = process.cwd()) {
+  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 \u2014 this is a packaging bug in basalt-ui, not a config error."
+    );
+    return 1;
+  }
+  const body = `:root {
+${decls.map((d) => `  ${d.name}: ${d.value};`).join("\n")}
+}
+`;
+  const header = generatedHeader(readFrameworkVersion(pkgRoot), "fonts:css", flags);
+  return emitGeneratedCss(`${header}${body}`, flags, cwd, "fonts:css");
 }
 async function guardHook(cwd = process.cwd()) {
   let raw;
@@ -1189,8 +1981,11 @@ async function guardHook(cwd = process.cwd()) {
     rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
-    exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity
+    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" } : {}
   };
   const roots = cfg.roots ?? DEFAULT_ROOTS;
   const exempt = new Set(cfg.exempt ?? defaultExempt(cfg));
@@ -1222,7 +2017,7 @@ async function guardHook(cwd = process.cwd()) {
   }
   return 0;
 }
-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\ntokens:css [--out <path>] [--selector-attribute <attr>] [--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  --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\nEvery subcommand accepts --help / -h to print this message and exit without running.";
+const USAGE = "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\ncheck-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 \u2014 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\ntokens: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\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--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\ncheck-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\nbasalt config when invoked from a repo root that has none \u2014 several carrying one is ambiguous\nand exits 1 in BOTH. --tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.";
 function run(argv, cwd = process.cwd()) {
   const [cmd, ...flags] = argv;
   if (cmd === "help" || cmd === "--help" || cmd === "-h" || flags.includes("--help") || flags.includes("-h")) {
@@ -1233,22 +2028,25 @@ function run(argv, cwd = process.cwd()) {
     case "init":
       return init(cwd, {
         withRouter: flags.includes("--with-router"),
-        withQuery: flags.includes("--with-query")
+        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;
@@ -1261,10 +2059,12 @@ export {
   checkCoverage,
   checkTheme,
   doctor,
+  fontsCss,
   guardHook,
   info,
   init,
   managedFiles,
+  normalizeColorFunctions,
   normalizeForLedger,
   run,
   sync,