basalt-ui 1.33.0 → 1.34.1

package/src/cli/guard-hook.ts

@@ -5,12 +5,12 @@
  */
 import { isAbsolute, relative, resolve } from 'node:path'
 
-import { DEFAULT_GUARD_CONFIG } from '../guard'
-import type { GuardConfig } from '../guard'
 import { evaluateGuardHook } from '../guard/guard-hook'
-import { SKIP, declaredProfile, defaultExempt, readBasaltConfig, resolveExemptRules } from './index'
+import { SKIP, declaredProfile, defaultExempt, readBasaltConfig, resolveGuardConfig } from './index'
 import { DEFAULT_ROOTS } from './config'
 
+const ALLOW = '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
+
 /**
  * guard-hook — PreToolUse stdin adapter.
  *
@@ -31,9 +31,7 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     }
   } catch {
     // Unreadable stdin → allow
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
     return 0
   }
 
@@ -42,36 +40,13 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     payload = JSON.parse(raw)
   } catch {
     // Malformed JSON → allow (never block on a bad payload)
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
     return 0
   }
 
   const cfg = readBasaltConfig(cwd)
-  const guardCfg: GuardConfig = {
-    spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
-    rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
-    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
-    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
-    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
-    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
-    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
-    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
-    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
-    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
-    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
-    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
-    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
-    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
-    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
-    allowComment: 'theme-allow',
-    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 } : {}),
-  }
+  // Same profile as check-theme: never block an edit over advice a no-Mantine app cannot take.
+  const guardCfg = resolveGuardConfig(cfg, declaredProfile(cfg, []))
 
   // Honor the consumer's roots / exempt / skip config so the hook never blocks edits to exempted
   // palette source or files outside the guarded roots (mirrors checkTheme's file-walk scoping).
@@ -101,9 +76,7 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
       }) + '\n',
     )
   } else {
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
   }
   return 0
 }

package/src/cli/index.ts

@@ -1,18 +1,9 @@
 /**
- * basalt-ui CLI — `init`, `sync`, `check-theme`, `doctor`.
- *
- * `checkTheme` is a thin FS walker over the headless guard core (`../guard`). It reads the
- * BasaltConfig, builds a GuardConfig, walks the source roots, calls `checkSource` per file,
- * collects Finding[], groups/reports findings, and returns an exit code.
- *
- * `init` / `sync` scaffold and reconcile the framework's *agentic* surface into a consumer repo:
- * Claude Code rules + skills, a managed CLAUDE.md block, a DESIGN.md seed, and the toolchain
- * seeds (oxlint / oxfmt / lefthook / CI). Both are sha256-manifest driven for safe,
- * idempotent three-way reconciliation. Dependency-free — Node/Bun built-ins only.
- *
- * Runtime-agnostic (Node or Bun) — built-ins only, no `bun`-module import, so the exported API is
- * safe to import under plain Node. Config is read from the consuming package.json `"basalt"` key;
- * argo's hardcoded values are the DEFAULTS.
+ * basalt-ui CLI — the dispatcher plus the plumbing `init`, `sync`, `check-theme` and `doctor` (each
+ * in its own file) share. `init`/`sync` reconcile the agentic surface and the toolchain seeds into
+ * a consumer repo through a sha256 manifest (three-way, idempotent). Runtime-agnostic and
+ * dependency-free — Node/Bun built-ins only, no `bun`-module import. Config is the consuming
+ * package.json's `"basalt"` key; argo's values are the defaults.
  */
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
@@ -43,17 +34,53 @@ import { DEFAULT_ROOT, exemptRulePaths, resolveRoots } from './config'
 import type { BasaltConfig } from './config'
 
 /**
- * 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.
+ * The consumer's `GuardConfig`: every `basalt` key the guard knows, over `DEFAULT_GUARD_CONFIG`.
+ * One builder for `check-theme` and `guard-hook`, so the hook never judges an edit by a different
+ * config than the build. `exemptRules` reaches the guard as paths only — the reason the object form
+ * carries is accountability for a human and for `--audit-allows`, not a second shape to scan.
+ */
+type PassthroughKey = Exclude<keyof GuardConfig, 'allowComment' | 'exemptRules' | 'profile'>
+
+/**
+ * The `basalt` keys that reach the guard verbatim — named, never matched by name at runtime.
+ * `satisfies Record<…>` makes a GuardConfig key missing here, or one that is not a key, a tsc error.
  */
-export 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)
+const GUARD_PASSTHROUGH = {
+  spacingSteps: true,
+  rawRadius: true,
+  forbiddenAccents: true,
+  mantineShadeIndex: true,
+  rawSurface: true,
+  cardWithBorder: true,
+  offSystemSurfaceVar: true,
+  rawHtmlLayout: true,
+  inlineSpacing: true,
+  inlineDisplay: true,
+  rawVisxAxis: true,
+  rawMotionValue: true,
+  chartMissingAriaLabel: true,
+  rawFormControl: true,
+  sub16InputFont: true,
+  severity: true,
+} as const satisfies Record<PassthroughKey, true>
+
+export function resolveGuardConfig(cfg: BasaltConfig, profile: DoctorProfile): GuardConfig {
+  const exemptRules: Partial<Record<GuardKind, string[]>> = {}
+  for (const [kind, entry] of Object.entries(cfg.exemptRules ?? {})) {
+    exemptRules[kind as GuardKind] = exemptRulePaths(entry)
+  }
+  // Typed as the guard's shape, so a BasaltConfig field whose type drifts from it fails to compile.
+  const from: Partial<Pick<GuardConfig, PassthroughKey>> = cfg
+  const set = (Object.keys(GUARD_PASSTHROUGH) as PassthroughKey[]).filter(
+    (k) => (from[k] ?? null) !== null,
+  )
+  return {
+    ...DEFAULT_GUARD_CONFIG,
+    ...Object.fromEntries(set.map((k) => [k, from[k]])),
+    allowComment: 'theme-allow',
+    exemptRules,
+    ...(profile === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
   }
-  return out
 }
 
 /**
@@ -211,13 +238,12 @@ export function relativePosix(fromDir: string, toPath: string): string {
 /**
  * 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.
+ * Every seam basalt seeds (oxlint/lefthook `extends`, the CI `run:` steps) used to hardcode
+ * `./node_modules/basalt-ui` at the repo ROOT; under bun's isolated linker a package that declares
+ * basalt a peer + devDependency gets it at `<pkg>/node_modules` and NOTHING at the root, so all three
+ * silently failed to resolve and `bunx` fetched a second, different copy. Resolution therefore walks
+ * OUTWARD from the consumer dir, then across the workspace packages — and every caller renders its
+ * paths from the answer rather than assuming the root.
  */
 export type BasaltInstall = {
   /** Absolute path of the resolved `node_modules/basalt-ui` directory, or null when unresolvable. */
@@ -310,23 +336,9 @@ export function resolveProjectDir(cwd: string): ProjectResolution {
 }
 
 /**
- * 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` no longer infers a profile at all (workspace-wide Mantine detection was deleted along
- *   with the rest of the multi-repo discovery); it reads the same declaration `check-theme` does.
+ * Which shape of consumer a project-scoped command is looking at — DECLARED, never inferred
+ * (`--tokens-only`, or `"basalt": { "profile": "tokens-only" }`), because the answer switches the
+ * Mantine-remedy guard kinds off. Why that direction: package CLAUDE.md § CLI.
  */
 export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
   if (flags.includes('--tokens-only')) return 'tokens-only'
@@ -340,8 +352,21 @@ export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): Do
  * vs `--selector-attribute`. Silently preferring one meant a CI step that accumulated both flags
  * enforced whichever the code happened to test first.
  */
-export function conflictingProfileFlags(flags: readonly string[]): boolean {
-  return flags.includes('--tokens-only') && flags.includes('--framework')
+export function conflictingProfileFlags(command: string, flags: readonly string[]): boolean {
+  const both = flags.includes('--tokens-only') && flags.includes('--framework')
+  if (both)
+    console.error(
+      `basalt-ui ${command}: --tokens-only and --framework are alternatives — pass one.`,
+    )
+  return both
+}
+
+/** Says so when `BASALT_CWD` moved the command off the directory it was invoked in. */
+export function noteRelocation(command: string, project: ProjectResolution): void {
+  if (project.relocatedFrom === null) return
+  console.log(
+    `basalt-ui ${command}: BASALT_CWD relocated from ${project.relocatedFrom} to ${project.dir}.`,
+  )
 }
 
 /**
@@ -401,19 +426,11 @@ function appShellFiles(rootAbs: string): string[] {
 const PLAIN_JSON_HINT_PATH = 'manifest.json'
 
 /**
- * The waiver closer for a file, gated on the profile.
- *
- * `guardWaiverHint` keys off the file class, and for a `.webmanifest` it leads with
- * `basaltAppPlugin` — right for a Mantine app, since a hex in a manifest can never be *right* and
- * the plugin removes the hand-copy entirely. A `profile: tokens-only` consumer has definitionally
- * opted out of that layer: rollhook's Astro site has no `index.html` for the plugin to transform,
- * imports no basalt JavaScript at all, and owns maskable icons the plugin does not emit. Leading
- * with the plugin there is advice the consumer cannot take, in the one release that finally gave
- * that file class a remedy.
- *
- * So under tokens-only a manifest is treated as what it is to that consumer — plain JSON, with the
- * member as the whole answer — plus one sentence saying which remedy is being withheld and why.
- * The remedy text still comes from the guard's own registry; only the class mapping is decided here.
+ * The waiver closer for a file, gated on the profile. `guardWaiverHint` leads a `.webmanifest` with
+ * `basaltAppPlugin` — right for a Mantine app, advice a `profile: tokens-only` consumer cannot take
+ * (rollhook's Astro site has no `index.html` for the plugin and owns its maskable icons). There the
+ * manifest is plain JSON — the member is the whole answer, plus one sentence on the withheld remedy.
+ * The remedy text still comes from the guard's registry; only the class mapping is decided here.
  */
 export function waiverHintFor(relPath: string, profile: DoctorProfile): string {
   if (profile !== 'tokens-only' || !relPath.endsWith('.webmanifest')) {
@@ -568,7 +585,7 @@ function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): Tem
     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'),
+    OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, OXLINT_FILES.preset),
     LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/lefthook.yml'),
     BASALT_BIN: basaltBinCommand(install, cwd),
   }
@@ -706,6 +723,17 @@ export function findRepoRoot(dir: string): string {
   }
 }
 
+/** The AST lane's other half: an `oxlint` bin in `node_modules/.bin`, `dir` up to the repo root. */
+export const OXLINT_NO_BIN =
+  'oxlint config found but no oxlint binary — the AST lane never runs; add oxlint as a devDependency'
+export function oxlintBinResolves(dir: string): boolean {
+  const root = findRepoRoot(dir)
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(resolve(d, 'node_modules/.bin/oxlint'))) return true
+    if (d === root || dirname(d) === d) return false
+  }
+}
+
 /**
  * First path under `dir` (recursive) whose basename is `filename`, or null. Skips dependency/build
  * dirs, mirroring `walkSourceFiles`'s scoping.
@@ -873,7 +901,7 @@ export function managedFiles(
   const oxlintrc: ManagedFile = {
     dest: '.oxlintrc.json',
     mode: 'seed',
-    source: 'configs/oxlint.json',
+    source: OXLINT_FILES.preset,
     render: (ctx) => `{\n  "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"]\n}\n`,
   }
 
@@ -1191,16 +1219,9 @@ export function normalizeForLedger(text: string): string {
 
 /**
  * Write a managed unit to disk (whole file, or marker-spliced region). Returns the unit's hash —
- * `sha256(normalizeForLedger(desired))`, NOT the raw bytes.
- *
- * This is the ledger: the manifest already records "what basalt shipped last sync", one entry per
- * dest — a stored NORMALIZED hash makes that same single entry survive both a downstream formatter
- * (the consumer's own lefthook oxfmt reformatting the written file/block after this function has
- * already returned) and a version bump that changed the template's own words since the recorded
- * entry — the argo cross-version case: current is v1.0.0's block, post-oxfmt; desired is v1.0.1's
- * (different words, e.g. the CLI bin rename). Recording the raw hash can never reconcile that;
- * recording the normalized hash lets `classify()` normalize `state.current` the same way and
- * compare directly against it, no separate historical-hash storage required.
+ * `sha256(normalizeForLedger(desired))`, NOT the raw bytes: the normalized hash is what lets one
+ * manifest entry survive a downstream formatter and a cross-version template change (`classify`'s
+ * path 2 is the reader).
  */
 export function writeUnit(file: ManagedFile, cwd: string, desired: string): string {
   const destAbs = resolve(cwd, file.dest)
@@ -1217,29 +1238,16 @@ export function writeUnit(file: ManagedFile, cwd: string, desired: string): stri
  * Classify a managed file against the manifest for a sync run.
  * - missing  : the managed unit is absent on disk → recreate.
  * - current  : on disk == desired → nothing to do.
- * - unchanged: on disk matches a KNOWN-SHIPPED rendering of this template, checked three ways (any
- *              one is sufficient) — but != desired as-is → safe overwrite:
- *              1. `sha256(current) === manifestHash` — legacy raw-hash path. An existing consumer
- *                 manifest (written before this fix, or by a still-running older CLI) holds the RAW
- *                 hash of what was written, not the normalized one; keep matching it directly so an
- *                 upgrade never mass-classifies a pristine tree as drifted.
- *                 Residual transitional gap: a manifest written by a pre-1.0.2 CLI holds a raw hash
- *                 of the exact old bytes, so if the on-disk block was ALSO reformatted by a
- *                 downstream formatter AND the template body changed cross-version in the same
- *                 upgrade, none of the three paths above match and it classifies `drifted`, needing
- *                 one `--force`. Once any sync since writes a normalized entry (path 2/3 or a
- *                 healed write), the gap is closed for good for that file. Deliberately not solved
- *                 by keeping a historical per-version ledger — that's a real but bounded tradeoff.
- *              2. `sha256(normalizeForLedger(current)) === manifestHash` — the ledger proper.
- *                 `manifestHash` normally holds `sha256(normalizeForLedger(<bytes written at the
- *                 last sync>))` (see `writeUnit`); normalizing `current` the same way and comparing
- *                 survives a downstream formatter reformatting the file AND a version bump that
- *                 changed the template's own words between the sync that wrote this manifest entry
- *                 and the version being synced now — the argo cross-version false positive.
+ * - unchanged: on disk matches a KNOWN-SHIPPED rendering of this template (any one is sufficient) —
+ *              but != desired as-is → safe overwrite:
+ *              1. `sha256(current) === manifestHash` — legacy raw-hash path (manifests written before
+ *                 the ledger normalized hold the RAW hash; keep matching so an upgrade never
+ *                 mass-classifies a pristine tree as drifted).
+ *              2. `sha256(normalizeForLedger(current)) === manifestHash` — the ledger proper (see
+ *                 `writeUnit`): survives a downstream formatter AND a version bump that changed the
+ *                 template's own words since the manifest entry was written (the argo false positive).
  *              3. `normalizeForLedger(current) === normalizeForLedger(desired)` — same-version
- *                 fallback for when there is no manifest entry to compare against at all (e.g. it
- *                 was dropped), but the on-disk bytes still match today's rendering modulo
- *                 formatting noise.
+ *                 fallback when no manifest entry exists at all.
  * - drifted  : on disk matches NONE of the above (a real, word-level local edit) → skip unless
  *              --force.
  */
@@ -1461,22 +1469,26 @@ export function parseJsonc(text: string): Record<string, unknown> | null {
 /** Outcome of splicing the shipped preset into an `.oxlintrc.json` the consumer already had. */
 export type MergeLintResult = 'added' | 'already' | 'absent' | 'unreadable' | 'has-comments'
 
+/** The shipped oxlint files, package-relative — the one spelling every reader of them uses. */
+export const OXLINT_FILES = {
+  preset: 'configs/oxlint.json',
+  guards: 'configs/oxlint-basalt.json',
+  plugin: 'configs/oxlint-plugin.js',
+} as const
+
+/** Whether an `extends`/`jsPlugins` entry names that shipped basalt-ui file. */
+export const namesShipped = (entry: unknown, file: string): entry is string =>
+  typeof entry === 'string' && entry.endsWith(`basalt-ui/${file}`)
+
 /**
- * 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`.
+ * The `extends` entry naming a shipped preset (full or guards-only), or null. The ENTRY, not a
+ * boolean: a well-shaped `./node_modules/basalt-ui/configs/oxlint.json` can resolve to nothing
+ * (an upgrade, an isolated linker), and oxlint then dies `NotFound` while a check built to prove the
+ * lane is ON reports green — callers resolve it against the config's own directory.
  */
 export 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
+  const presets = [OXLINT_FILES.preset, OXLINT_FILES.guards]
+  return [entries].flat().find((e): e is string => presets.some((f) => namesShipped(e, f))) ?? null
 }
 
 // ── The lefthook gate — checked via `lefthook dump`, not hand-rolled YAML parsing ────────────────
@@ -1557,13 +1569,14 @@ export function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintRe
   if (raw === null) return 'absent'
   const cfg = parseJsonc(raw)
   if (cfg === null) return 'unreadable'
-  if (basaltPresetEntry(cfg['extends']) !== null) return 'already'
+  if ([cfg['extends']].flat().some((e) => namesShipped(e, OXLINT_FILES.preset))) 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')
-    : []
+  // The guards-only preset is a subset of the full one — upgrading replaces it, never stacks it.
+  const existing = [cfg['extends']]
+    .flat()
+    .filter((e): e is string => typeof e === 'string' && !namesShipped(e, OXLINT_FILES.guards))
   // 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] }

package/src/cli/sync.ts

@@ -20,6 +20,8 @@ import {
   isStringArray,
   managedFiles,
   normalizeForLedger,
+  noteRelocation,
+  OXLINT_FILES,
   parseJsonc,
   placementNotices,
   pruneRetiredManagedFiles,
@@ -44,14 +46,8 @@ import {
 
 /** The oxlint plugins the shipped preset switches on — read from the preset, never restated. */
 export 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 []
-  }
+  const plugins = parseJsonc(readSource(pkgRoot, OXLINT_FILES.preset) ?? 'null')?.['plugins']
+  return isStringArray(plugins) ? plugins : []
 }
 
 export type SyncOptions = {
@@ -111,15 +107,10 @@ export function findManifestAbove(dir: string): string | null {
  */
 export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd()): number {
   const syncFlags = opts.flags ?? []
-  if (conflictingProfileFlags(syncFlags)) {
-    console.error('basalt-ui sync: --tokens-only and --framework are alternatives — pass one.')
-    return 1
-  }
+  if (conflictingProfileFlags('sync', syncFlags)) return 1
   const project = resolveProjectDir(invocationCwd)
   const cwd = project.dir
-  if (project.relocatedFrom !== null) {
-    console.log(`basalt-ui sync: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`)
-  }
+  noteRelocation('sync', project)
 
   // Profile before the refusal, because in a tokens-only consumer the refusal's own advice is
   // wrong: it names `basalt-ui init`, and `doctor` in the same directory at the same version says
@@ -265,7 +256,7 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     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')}".`,
+        `"${shippedAssetPath(install, cwd, OXLINT_FILES.preset)}".`,
     )
   }
 

package/src/common/vx-families.ts

@@ -0,0 +1,36 @@
+// GENERATED by scripts/gen-vx-names.ts — do not edit. `vx-names.test.ts` fails on drift.
+
+/**
+ * The families every emitted `--vx-*` name lives in (`basaltVxFamilies`) — basalt-owned:
+ * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` warn on a
+ * consumer ref there.
+ */
+export const BASALT_VX_FAMILIES: readonly string[] = [
+  'accent',
+  'area',
+  'axis',
+  'bad',
+  'crosshair',
+  'divider',
+  'dot',
+  'faint',
+  'fill',
+  'good',
+  'grid',
+  'hit',
+  'ink',
+  'keyboard',
+  'legend',
+  'line',
+  'muted',
+  'neutral',
+  'prose',
+  'radius',
+  'shadow',
+  'space',
+  'status',
+  'surface',
+  'text',
+  'tooltip',
+  'warn',
+]

package/src/common/vx-family.ts

@@ -0,0 +1,22 @@
+/**
+ * A `--vx-*` name's FAMILY — its leading lowercase run: `--vx-surface-bg` → `surface`, `--vx-ink2`
+ * → `ink`, `--vx-tooltipBg` → `tooltip`, `--vx-fillHover-cyan` → `fill`. Dependency-free, because
+ * three sides must agree on it byte for byte: the generator that writes `BASALT_VX_FAMILIES`, the
+ * guard that judges every name inside one of those families, and the token factories that refuse a
+ * consumer name inside one — the refusal is what makes the guard's judgement honest.
+ */
+export function vxFamilyOf(name: string): string {
+  return /^--vx-([a-z]*)/.exec(name)?.[1] ?? ''
+}
+
+/**
+ * Families a consumer extends without any factory: the theme emits `--vx-on-<color>` for EVERY
+ * `theme.colors` entry, a consumer's own colors included, so `on` is never basalt's alone.
+ */
+const CONSUMER_EXTENSIBLE_FAMILIES: ReadonlySet<string> = new Set(['on'])
+
+/** The basalt-owned families among `names` — run over every name basalt emits (`collectVxNames`). */
+export function basaltVxFamilies(names: readonly string[]): string[] {
+  const families = new Set(names.map(vxFamilyOf))
+  return [...families].filter((f) => f !== '' && !CONSUMER_EXTENSIBLE_FAMILIES.has(f)).toSorted()
+}

package/src/guard/index.ts

@@ -5,6 +5,8 @@
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
+import { vxFamilyOf } from '../common/vx-family'
+import { BASALT_VX_FAMILIES } from '../common/vx-families'
 import { BASALT_VX_NAMES } from './vx-names'
 
 export type { Finding, GuardConfig, GuardKind, GuardSeverity }
@@ -327,21 +329,16 @@ const REMOVED_VX_NAMES: Readonly<Record<string, string | null>> = {
 const KNOWN_VX_NAMES: ReadonlySet<string> = new Set(BASALT_VX_NAMES)
 
 /**
- * The bare family roots basalt never emits — `--vx-space`, `--vx-surface`, `--vx-status`, … — derived
- * from the `--vx-<family>-` prefixes of the emitted names, minus any root that is itself a token
- * (`--vx-hit`, `--vx-accent`). Nobody emits one: basalt only ever writes `<root>-<key>`, and so does
- * `groupTokens`. It is the one shape of unknown name basalt can judge WITHOUT seeing the consumer's
- * palette.
+ * The families basalt owns (`vxFamilyOf`: `surface`, `space`, `ink`, `keyboard`, …), which the
+ * generator reads off every name basalt emits. Every name inside one is judged against the exact
+ * emitted set, so `--vx-surface-2` and a bare root like `--vx-space` are both findings.
  *
- * An unknown name INSIDE a family (`--vx-surface-2`) is deliberately not judged. `groupTokens(name,
- * map)` takes any `name`, so `--vx-surface-custom` may be a consumer group declared in a file this
- * scan cannot see, and a per-file guard has no honest way to tell that from a typo.
+ * That judgement is honest only because no consumer ref may point into these families:
+ * `groupTokens`/`seriesTokens` warn on a name inside one (and throw once this kind promotes). A name in any OTHER family (argo's
+ * `--vx-activity-*`, rb's `--vx-confidence-*`) may be a consumer group declared in a file this scan
+ * cannot see, and is never judged.
  */
-const BASALT_VX_FAMILY_ROOTS: ReadonlySet<string> = new Set(
-  BASALT_VX_NAMES.map((n) => /^(--vx-[A-Za-z0-9]+)-/.exec(n)?.[1]).filter(
-    (root): root is string => root !== undefined && !KNOWN_VX_NAMES.has(root),
-  ),
-)
+const BASALT_VX_FAMILY_SET: ReadonlySet<string> = new Set(BASALT_VX_FAMILIES)
 
 // Raw Mantine ramp step used for surface color — gray/dark + a step digit.
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g
@@ -919,13 +916,13 @@ export type GraceEntry = { since: string; promote: string; why: string }
  */
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'unknown-vx-token': {
-    since: '1.33.0',
-    promote: '1.34.0',
+    since: '1.34.0',
+    promote: '1.35.0',
     why:
-      'New kind (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
-      '`var(--vx-space-touch-target)` that nothing reported. A new kind rejects code every previous ' +
-      'release accepted, so it lands warn for one minor. Measured at ship time: argo, linewatch, rb, ' +
-      'rollhook, obsidian, weatherorb, image-share, email-gateway, image-gen 0.',
+      'New kind at 1.33.0 (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
+      '`var(--vx-space-touch-target)` that nothing reported. WIDENED at 1.34.0 (image-gen r4: ' +
+      '`var(--vx-surface-2)` rendered transparent, unreported) to every unemitted name inside a ' +
+      'basalt-owned family, so the grace restarts: warn through 1.34.x, error at 1.35.0.',
   },
 }
 
@@ -2105,7 +2102,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Card withBorder>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      '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 (docs/DESIGN-SPEC.md doctrine inversion #1).',
+      '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 (docs/DESIGN-SPEC.md doctrine inversion #1) — and fix the inset in the same edit: an explicit p/padding or radius on that Card/Paper is the other half of the idiom, which only the oxlint lane sees (basalt/card-inset); leave both to the theme or use py="xs" px="sm".',
   },
   'off-system-surface-var': {
     kind: 'off-system-surface-var',
@@ -2257,14 +2254,14 @@ export const GUARD_RULES = {
   },
   'unknown-vx-token': {
     kind: 'unknown-vx-token',
-    pattern: VX_VAR_REF, // handled inline (removed map + family roots); entry keeps the registry complete
-    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Two shapes are judged, the only two basalt can judge without seeing your palette: a REMOVED name — ${Object.entries(
+    pattern: VX_VAR_REF, // handled inline (basalt-owned families); entry keeps the registry complete
+    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens warns on one inside basalt's). Removed names and their replacements: ${Object.entries(
       REMOVED_VX_NAMES,
     )
       .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)
       .join(
         '; ',
-      )} — and a bare family root nothing emits (${[...BASALT_VX_FAMILY_ROOTS].join(', ')}): name the token under it from basalt-ui/tokens.css. Any other unknown name is never judged, because defineSeries/groupTokens may declare it in a file this scan cannot see.`,
+      )}. A name in any other family is never judged, because groupTokens may declare it in a file this scan cannot see.`,
   },
 } as const satisfies Record<GuardKind, GuardRule>
 
@@ -2445,13 +2442,13 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     [...codeText.matchAll(VX_LOCAL_DECLARATION)].map((m) => m[1] ?? m[3] ?? m[4] ?? ''),
   )
 
-  // unknown-vx-token: a removed name, or a bare family root nothing emits — see the roots' doc.
+  // unknown-vx-token: any unemitted name inside a basalt-owned family — see BASALT_VX_FAMILY_SET.
   // Scanned over the whole comment-stripped text rather than per line, so a formatter-wrapped
   // `var(\n  --vx-x\n)` is seen; the finding lands on the line the NAME is on.
   for (const m of codeText.matchAll(VX_VAR_REF)) {
     const name = m[1] ?? ''
     if (locallyDeclaredVx.has(name)) continue
-    if (!Object.hasOwn(REMOVED_VX_NAMES, name) && !BASALT_VX_FAMILY_ROOTS.has(name)) continue
+    if (KNOWN_VX_NAMES.has(name) || !BASALT_VX_FAMILY_SET.has(vxFamilyOf(name))) continue
     const at = (m.index ?? 0) + m[0].length - name.length
     push('unknown-vx-token', lineStarts.findLastIndex((start) => start <= at) + 1, name)
   }