basalt-ui 1.23.0 → 1.24.0

package/src/cli/index.ts

@@ -365,8 +365,14 @@ function readBasaltConfig(cwd: string): BasaltConfig {
  * Extensions the walker collects. `html?`/`webmanifest` close argo's finding that raw hex ships in
  * `index.html`'s `theme-color` and the webmanifest's `theme_color`/`background_color` — the two
  * places whose colors nothing re-derives on a scheme change, and which the scan never reached.
+ *
+ * `astro`/`jsx`/`vue` close the same gap one component layer up. rollhook's marketing site is
+ * Astro: `apps/marketing/src` holds two `.astro` templates that are its ENTIRE markup layer, and
+ * check-theme reported a clean 4-file scan without ever opening either. The colour and typography
+ * kinds apply to them exactly as they do to `.html`, which was already scanned; `.jsx` and `.vue`
+ * were missing from the same regex, so a plain-JS or Vue consumer was unguarded end to end.
  */
-const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/
+const SCANNABLE_EXT = /\.(?:tsx?|jsx|astro|vue|css|html?|webmanifest)$/
 
 /**
  * Recursively collect scannable files under a root, skipping dependency/build dirs. Node+Bun-safe.
@@ -539,6 +545,36 @@ function descendantProjects(cwd: string, depth = 2): string[] {
   return out
 }
 
+/**
+ * The nearest ANCESTOR of `cwd`, within the same repo, that is a basalt project — or null.
+ *
+ * The descend direction was handled and announced; ascend was not, and it fabricated instead. From
+ * `apps/demo` in a two-root repo, `readBasaltConfig` answered `{}`, `resolveRoots` substituted the
+ * built-in `['src']`, and check-theme scanned 22 of the repo's 44 guarded files, reported
+ * `✓ no off-palette colors`, and printed the invention back as `basalt.roots (src)`. Its
+ * `--audit-allows` then reported `0 live` for a repo carrying a live waiver — a clean slate from
+ * the one command whose entire job is to deny one. `doctor`, standing in that same directory,
+ * already resolved the parent install and named it, so the two commands disagreed about the same
+ * repo.
+ *
+ * Bounded by {@link findRepoRoot}, inclusive: an ancestor outside the repo is not this project's
+ * config. `repoRoot === cwd` means either cwd IS the root (nothing above it to ascend to) or there
+ * is no `.git` anywhere (no bound to walk within) — both answer null, which leaves a standalone
+ * unconfigured consumer on the built-in defaults exactly as before.
+ */
+function ascendantProject(cwd: string): string | null {
+  const repoRoot = findRepoRoot(cwd)
+  if (repoRoot === cwd) return null
+  let current = dirname(cwd)
+  for (;;) {
+    if (hasBasaltProject(current)) return current
+    if (current === repoRoot) return null
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
 function resolveProjectDir(cwd: string): ProjectResolution {
   const override = process.env['BASALT_CWD']
   if (override !== undefined && override.length > 0) {
@@ -558,6 +594,13 @@ function resolveProjectDir(cwd: string): ProjectResolution {
     return { dir: candidates[0] as string, relocatedFrom: cwd, ambiguous: null }
   }
   if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates }
+
+  // Nothing at cwd and nothing below it: look UP before falling back to a default. See
+  // {@link ascendantProject} — the fabricated `roots: ['src']` this replaces is what let a scan
+  // pass over half a repo and an audit report zero waivers for a repo that has one.
+  const above = ascendantProject(cwd)
+  if (above !== null) return { dir: above, relocatedFrom: cwd, ambiguous: null }
+
   return { dir: cwd, relocatedFrom: null, ambiguous: null }
 }
 
@@ -1352,10 +1395,25 @@ function readFrameworkVersion(pkgRoot: string): string {
   }
 }
 
+/**
+ * How a seeded script, a seeded CI step, or a piece of doctor advice should invoke the CLI.
+ *
+ * The LOCAL bin wherever basalt actually resolved; `bunx basalt-ui` only as the pre-install
+ * fallback. `bunx` does not re-resolve a package it has cached, so a seeded `bunx basalt-ui` lets a
+ * consumer pin one version and be gated by another — which is exactly what happened across three
+ * consumer repos, in CI, in package.json scripts and in a `.claude` PreToolUse hook, all of them
+ * placed here. Every emitted invocation goes through this function so there is one place for it to
+ * be right.
+ */
+function basaltBinCommand(install: BasaltInstall, cwd: string): string {
+  if (install.dir === null) return 'bunx basalt-ui'
+  const binDir = resolve(install.dir, '..', '.bin')
+  return `${relativePosix(cwd, binDir).replace(/^\.\//, '')}/basalt-ui`
+}
+
 /** Build the template-variable map from the framework root + consumer cwd/config. */
 function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): TemplateVars {
   const install = findBasaltInstall(cwd)
-  const binDir = install.dir === null ? null : resolve(install.dir, '..', '.bin')
   return {
     APP_NAME: readPackageName(cwd),
     BASALT_VERSION: readFrameworkVersion(pkgRoot),
@@ -1364,10 +1422,7 @@ function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): Tem
     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`,
+    BASALT_BIN: basaltBinCommand(install, cwd),
   }
 }
 
@@ -2542,7 +2597,7 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
       `    "PreToolUse": [\n` +
       `      {\n` +
       `        "matcher": "Write|Edit|MultiEdit",\n` +
-      `        "hooks": [{ "type": "command", "command": "bunx basalt-ui guard-hook" }]\n` +
+      `        "hooks": [{ "type": "command", "command": "${ctx.vars.BASALT_BIN} guard-hook" }]\n` +
       `      }\n` +
       `    ]\n` +
       `  }`,
@@ -2603,6 +2658,21 @@ type SyncOptions = {
  * install lives at the repo root above it. Nothing walks up, so `sync` read "no manifest here" as
  * "nothing scaffolded yet" and wrote a complete second consumer beside the real one.
  */
+/**
+ * The sentence `sync` prints when the cwd carries no install but an ancestor does.
+ *
+ * Shared with `doctor` deliberately. The two commands already share `resolveProjectDir`, but not
+ * the ADVICE: `sync` named the parent install (1.22.0's "stop scaffolding a second consumer" fix)
+ * while `doctor`, in the same directory, kept prescribing `basalt-ui init` — so following doctor
+ * literally performed the exact mistake that fix exists to prevent. One function, one sentence.
+ */
+function parentInstallAdvice(cwd: string, parent: string, verb: string): string {
+  return (
+    `This repo's install is at ${relativePosix(cwd, parent)} (${parent}) — run ${verb} there, ` +
+    'or set BASALT_CWD to it.'
+  )
+}
+
 function findManifestAbove(dir: string): string | null {
   let current = resolve(dir, '..')
   for (;;) {
@@ -2681,8 +2751,7 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
         (elsewhere === null
           ? ' No manifest exists at any ancestor either — run `basalt-ui init` here if this ' +
             'package really is meant to be a consumer.'
-          : ` This repo's install is at ${relativePosix(cwd, elsewhere)} (${elsewhere}) — run ` +
-            'sync there, or set BASALT_CWD to it.'),
+          : ` ${parentInstallAdvice(cwd, elsewhere, 'sync')}`),
     )
     return 1
   }
@@ -3299,8 +3368,10 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      demonstrably not the installed package — see the check).
  *   5. The running CLI's own version matches the installed basalt-ui (catches a stale
  *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
- *   9. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
- *      a public/ dir exists at all — skipped otherwise).
+ *   9. The icon files `basaltAppPlugin` (basalt-ui/vite) references exist under the app package's
+ *      public/ — the package found via `basalt.roots`, not just cwd, so a root-invoked run still
+ *      reaches it. Never silently omitted: no plugin call anywhere is a pass that says so, a
+ *      plugin call with no public/ beside it is a SKIPPED.
  *   10 (second half). A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the
  *      exemption is stale and can be deleted; an exemption nobody revisits is how a real, later
  *      skew slips through unnoticed.
@@ -3365,6 +3436,10 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
   // ── Profile ────────────────────────────────────────────────────────────────
   const manifestAbs = resolve(cwd, MANIFEST_PATH)
   const manifestExists = existsSync(manifestAbs)
+  // Non-null ⇒ this directory is a package UNDER a configured repo, not an unscaffolded consumer.
+  // Every remedy below that would otherwise say "run `basalt-ui init`" points at the parent
+  // instead — see {@link parentInstallAdvice}.
+  const parentInstall = manifestExists ? null : findManifestAbove(cwd)
   const profile = inferredProfile(cwd, cfg, flags)
   if (profile === 'tokens-only') {
     lines.push(
@@ -3388,6 +3463,12 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     pass(`${MANIFEST_PATH}: n/a — a tokens-only consumer has no scaffold to reconcile`)
   } else if (manifestExists) {
     pass(`${MANIFEST_PATH} exists`)
+  } else if (parentInstall !== null) {
+    fail(
+      `${MANIFEST_PATH} missing here, but this is not an unscaffolded consumer. ` +
+        `${parentInstallAdvice(cwd, parentInstall, 'doctor')} \`basalt-ui init\` is NOT the fix: ` +
+        'it would scaffold a SECOND consumer beside the real one.',
+    )
   } else {
     fail(`${MANIFEST_PATH} missing — run \`basalt-ui init\` to scaffold the consumer repo`)
   }
@@ -3549,7 +3630,11 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     if (oxlintrcRaw === null) {
       fail(
         '.oxlintrc.json missing — the shipped oxlint preset (the basalt/* design rules) is not ' +
-          'active. Run `basalt-ui init` to seed it.',
+          'active. ' +
+          (parentInstall === null
+            ? 'Run `basalt-ui init` to seed it.'
+            : `${parentInstallAdvice(cwd, parentInstall, 'doctor')} The preset is seeded once, at ` +
+              'the install — not per package.'),
       )
     } else {
       // JSONC: oxlint accepts comments and real consumer configs carry them.
@@ -3642,40 +3727,81 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
       `${lefthookGate.file}: \`lefthook dump\` resolves the merged config and NO pre-commit ` +
         'command runs check-theme — the theme guard is not gating commits. Either add ' +
         `"extends: [${lefthookCorrect}]", or add your own command running ` +
-        '`bunx basalt-ui check-theme` (with `root:` if it must run in a subdirectory).',
+        `\`${basaltBinCommand(install, cwd)} check-theme\` (with \`root:\` if it must run in a ` +
+        'subdirectory).',
     )
   } else {
     warn(
       `${lefthookGate.file} names no basalt gate and \`lefthook dump\` could not be run here, so ` +
         'this check cannot tell a missing gate from one wired through an `include:` or a remote ' +
         'config it never read — treat it as advisory. If the guard really is unwired, add ' +
-        `"extends: [${lefthookCorrect}]" or your own command running \`bunx basalt-ui check-theme\`.`,
+        `"extends: [${lefthookCorrect}]" or your own command running ` +
+        `\`${basaltBinCommand(install, cwd)} check-theme\`.`,
     )
   }
 
-  // ── Warn check 8: basaltAppPlugin's default icon files exist in public/ ────
-  // basalt-ui/vite's basaltAppPlugin (head/manifest metadata) references these filenames by
-  // default (the realfavicongenerator convention). Only runs when a public/ dir exists at all —
-  // apps that don't use the plugin, or don't use Vite's public-dir convention, get no false
-  // warning. Best-effort: a custom `icons.dir` isn't visible here, so this checks the root only.
-  const publicDir = resolve(cwd, 'public')
-  if (profile === 'framework' && existsSync(publicDir)) {
-    const iconFiles = [
-      'favicon.ico',
-      'favicon.svg',
-      'favicon-96x96.png',
-      'apple-touch-icon.png',
-      'web-app-manifest-192x192.png',
-      'web-app-manifest-512x512.png',
-    ]
-    const missingIcons = iconFiles.filter((f) => !existsSync(resolve(publicDir, f)))
-    if (missingIcons.length > 0) {
-      warn(
-        `public/ is missing basaltAppPlugin icon file(s): ${missingIcons.join(', ')} — generate ` +
-          'them (e.g. via realfavicongenerator.net) and place them at the public/ root.',
+  // ── Warn check 8: the icon files basaltAppPlugin actually references exist ────
+  // basalt-ui/vite's basaltAppPlugin (head/manifest metadata) references six filenames by default
+  // (the realfavicongenerator convention), but since 1.23.0 an app can NAME its own — so the option
+  // is read (see {@link readAppIconsOption}) rather than assumed.
+  //
+  // It used to read `cwd` alone, and in a monorepo the vite config lives in the app PACKAGE while
+  // the only invocation that exits 0 is the repo root. The check therefore vanished from the root
+  // run with no line at all — the failure mode SKIPPED exists to eliminate — leaving no single
+  // invocation that both passes and checks the icons. It now resolves the app package the same way
+  // the scan does, off `basalt.roots`; see {@link findAppPluginDir}.
+  if (profile === 'framework') {
+    const appDir = findAppPluginDir(cwd, cfg)
+    const iconsIn = appDir ?? cwd
+    const icons = readAppIconsOption(iconsIn)
+    const here = appDir === null || appDir === cwd ? '' : `${relativePosix(cwd, appDir)}/`
+    const publicDir = resolve(iconsIn, 'public')
+    if (appDir === null && !existsSync(publicDir)) {
+      // No `basaltAppPlugin(` anywhere under the declared roots and no public/ here: nothing in
+      // this project references icon files, so there is nothing to check — and saying so is the
+      // point. A check that vanishes without a word is indistinguishable from one that passed.
+      pass('app icons: no `basaltAppPlugin(` under this project and no public/ — nothing to check')
+    } else if (icons.kind === 'none') {
+      pass('basaltAppPlugin is configured with no icons — nothing to check')
+    } else if (!existsSync(publicDir)) {
+      skip(
+        `app icons — ${here === '' ? 'this package' : here.replace(/\/$/, '')} configures ` +
+          'basaltAppPlugin, but there is no `public/` beside its vite config, so the files it ' +
+          "references cannot be located. Use Vite's public-dir convention, or set `icons: false` " +
+          'if this app ships none.',
       )
+    } else if (icons.kind === 'explicit') {
+      // The app NAMED its icons, so those are the only files it owes. Checking the six defaults
+      // here is what told 1.23.0's flagship adopter to generate five files it deliberately lacks.
+      const missing = icons.sources.filter(
+        (src) => !existsSync(resolve(publicDir, src.replace(/^\//, ''))),
+      )
+      if (missing.length > 0) {
+        warn(
+          `basaltAppPlugin declares icon(s) that are not in ${here}public/: ${missing.join(', ')} — ` +
+            'the manifest and the head links will point at a 404. Place them, or drop them from ' +
+            'the `icons` array.',
+        )
+      } else {
+        pass(
+          `${here}public/ has all ${icons.sources.length} icon file(s) basaltAppPlugin's ` +
+            '`icons` option names',
+        )
+      }
     } else {
-      pass("public/ has all of basaltAppPlugin's default icon files")
+      const dir = icons.kind === 'default' ? icons.dir : null
+      const iconRoot = dir === null ? publicDir : resolve(publicDir, dir.replace(/^\//, ''))
+      const shown = dir === null ? `${here}public/` : `${here}public/${dir.replace(/^\//, '')}`
+      const missingIcons = DEFAULT_APP_ICON_FILES.filter((f) => !existsSync(resolve(iconRoot, f)))
+      if (missingIcons.length > 0) {
+        warn(
+          `${shown} is missing basaltAppPlugin icon file(s): ${missingIcons.join(', ')} — generate ` +
+            `them (e.g. via realfavicongenerator.net) and place them at the ${shown} root, or name ` +
+            "the icons this app really has via the plugin's `icons` array.",
+        )
+      } else {
+        pass(`${shown} has all of basaltAppPlugin's default icon files`)
+      }
     }
   }
 
@@ -3882,6 +4008,137 @@ export function info(flags: string[]): number {
   return 0
 }
 
+/** The six filenames `basaltAppPlugin` references when `icons` is left at its default. */
+const DEFAULT_APP_ICON_FILES = [
+  'favicon.ico',
+  'favicon.svg',
+  'favicon-96x96.png',
+  'apple-touch-icon.png',
+  'web-app-manifest-192x192.png',
+  'web-app-manifest-512x512.png',
+] as const
+
+const VITE_CONFIG_FILES = [
+  'vite.config.ts',
+  'vite.config.mts',
+  'vite.config.cts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.cjs',
+] as const
+
+/**
+ * The directory whose vite config actually calls `basaltAppPlugin(` — cwd, or the app package the
+ * declared roots point into. Null when no vite config under this project calls it.
+ *
+ * `basalt.roots: ["apps/web/src"]` already names where the app is; the icon check just never used
+ * it, so from the repo root — the only invocation that can exit 0 on a monorepo layout — it found
+ * no vite config and silently emitted nothing. Each root is walked from its own directory up to
+ * cwd, nearest first, so `apps/web/src` resolves to `apps/web`, the package that owns both the
+ * vite config and the `public/` tree.
+ */
+function findAppPluginDir(cwd: string, cfg: BasaltConfig): string | null {
+  const seen = new Set<string>()
+  const candidates: string[] = []
+  const add = (dir: string): void => {
+    if (seen.has(dir)) return
+    seen.add(dir)
+    candidates.push(dir)
+  }
+  add(cwd)
+  for (const root of resolveRoots(cfg)) {
+    let current = resolve(cwd, root)
+    // A root that escapes cwd (`../shared`) is not this project's app package — never walk out.
+    while (current !== cwd && !relative(cwd, current).startsWith('..')) {
+      add(current)
+      const parent = dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+  }
+  for (const dir of candidates) {
+    const configPath = VITE_CONFIG_FILES.map((f) => resolve(dir, f)).find((f) => existsSync(f))
+    if (configPath === undefined) continue
+    if (readIfExists(configPath)?.includes('basaltAppPlugin(') === true) return dir
+  }
+  return null
+}
+
+/**
+ * What `basaltAppPlugin`'s `icons` option says this app actually has.
+ *
+ * `unknown` = no vite config, no `basaltAppPlugin(` call, or an `icons` value this bounded read
+ * cannot classify — all three fall back to the six-default check, so the gate can only ever get
+ * NARROWER than it was, never blinder.
+ */
+type AppIconsOption =
+  | { kind: 'default'; dir: string | null }
+  | { kind: 'none' }
+  | { kind: 'explicit'; sources: readonly string[] }
+  | { kind: 'unknown' }
+
+/** The balanced `(`…`)` / `{`…`}` / `[`…`]` span starting at `open`, or null if it never closes. */
+function balancedSpan(text: string, open: number): string | null {
+  const pairs: Record<string, string> = { '(': ')', '{': '}', '[': ']' }
+  const closer = pairs[text[open] as string]
+  if (closer === undefined) return null
+  let depth = 0
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i] as string
+    if (ch === text[open]) depth++
+    else if (ch === closer) {
+      depth--
+      if (depth === 0) return text.slice(open, i + 1)
+    }
+  }
+  return null
+}
+
+/**
+ * Read the `icons` option out of the consumer's vite config.
+ *
+ * 1.23.0 let `icons` name an app's REAL icon files; doctor's icon check kept demanding the six
+ * default filenames and never read the option, so adopting the release's headline feature produced
+ * a brand-new warning — on the very repo the feature was written for. A warning that fires BECAUSE
+ * you adopted the new API teaches people to ignore doctor.
+ *
+ * doctor does not run the build, so the plugin's resolved answer is not available to it; this is a
+ * bounded textual read of the config file, the same shape the guard uses on source. It is
+ * deliberately conservative: anything it cannot classify returns `unknown` and the old check runs.
+ */
+function readAppIconsOption(cwd: string): AppIconsOption {
+  const configPath = VITE_CONFIG_FILES.map((f) => resolve(cwd, f)).find((f) => existsSync(f))
+  if (configPath === undefined) return { kind: 'unknown' }
+  const text = readIfExists(configPath)
+  if (text === null) return { kind: 'unknown' }
+  const call = text.indexOf('basaltAppPlugin(')
+  if (call === -1) return { kind: 'unknown' }
+  const args = balancedSpan(text, call + 'basaltAppPlugin'.length)
+  if (args === null) return { kind: 'unknown' }
+  const key = args.search(/\bicons\s*:/)
+  if (key === -1) return { kind: 'default', dir: null }
+  const valueStart = args.indexOf(':', key) + 1
+  const rest = args.slice(valueStart).trimStart()
+  if (rest.startsWith('false')) return { kind: 'none' }
+  const offset = args.length - rest.length
+  if (rest.startsWith('[')) {
+    const list = balancedSpan(args, offset)
+    if (list === null) return { kind: 'unknown' }
+    const sources = [...list.matchAll(/\bsrc\s*:\s*['"`]([^'"`]+)['"`]/g)].map(
+      (m) => m[1] as string,
+    )
+    // An empty array means "this app has no icons" to the plugin, same as `false`.
+    return sources.length === 0 ? { kind: 'none' } : { kind: 'explicit', sources }
+  }
+  if (rest.startsWith('{')) {
+    const obj = balancedSpan(args, offset)
+    if (obj === null) return { kind: 'unknown' }
+    const dir = /\bdir\s*:\s*['"`]([^'"`]+)['"`]/.exec(obj)
+    return { kind: 'default', dir: dir === null ? null : (dir[1] as string) }
+  }
+  return { kind: 'unknown' }
+}
+
 /** Read the value that follows a `--flag` in an argv slice; `undefined` when absent or terminal. */
 function flagValue(flags: string[], name: string): string | undefined {
   const i = flags.indexOf(name)
@@ -3904,6 +4161,84 @@ function generatedHeader(version: string, command: string, flags: string[]): str
   return `${GENERATED_HEADER_LINE}\n/* basalt-ui ${version} — \`basalt-ui ${invocation}\` */\n`
 }
 
+/**
+ * The provenance line, split so only the VERSION token can be neutralized.
+ *
+ * Deliberately the same shape as the guard's `GENERATED_PROVENANCE_LINE` (`src/guard/index.ts`),
+ * which is what the `@generated` exemption tests line 2 against — the two must keep agreeing, so
+ * this is written to match, not to be lenient. A line that does not match is left VERBATIM, which
+ * is what makes a deleted, reworded or forged header fail `--check` instead of being blanked into
+ * agreement.
+ */
+const PROVENANCE_VERSION =
+  /^(\/\* basalt-ui )(\d+\.\d+\.\d+\S*)( — `basalt-ui (?:tokens:css|fonts:css)[^`]*` \*\/)$/
+
+/** The provenance line's version token, or null when line 2 is not a provenance line at all. */
+function provenanceVersion(css: string): string | null {
+  const match = PROVENANCE_VERSION.exec(css.split('\n')[1] ?? '')
+  return match === null ? null : (match[2] as string)
+}
+
+/**
+ * The generated file with only the provenance line's VERSION TOKEN neutralized — what `--check`
+ * actually compares.
+ *
+ * `--check` used to gate the whole file byte-for-byte, so every basalt-ui release forced a
+ * mandatory no-op commit in every consumer that commits a generated sheet. 1.23.1 fixed that by
+ * blanking the whole of line 2 — and line 2 is the line that carries the exact invocation, which
+ * line 1 tells the reader to regenerate with. The gate stopped verifying the one instruction it
+ * hands out: rollhook's header was rewritten from `--only core --no-legacy-aliases` to `--only all
+ * --with-legacy-aliases` and `--check` passed clean.
+ *
+ * So the version token is replaced by a sentinel and the rest of the line still gates. A release
+ * alone never trips the check; a changed flag, a reworded header, and a header that is simply gone
+ * all do.
+ *
+ * The version STAYS in the file rather than being dropped, because the consumer this command exists
+ * for — a framework-free site running `bunx basalt-ui tokens:css` with no basalt in its dependency
+ * tree at all — has no other record of which version emitted it, and no `doctor` to ask.
+ *
+ * Line-aligned, never dropped, so the reported line counts still match the files on disk. The
+ * `@generated` exemption is untouched by all of this: nothing here changes what
+ * {@link generatedHeader} emits, and {@link PROVENANCE_VERSION} is matched to the guard's own
+ * provenance regex rather than replacing it.
+ */
+function withoutProvenanceVersion(css: string): string {
+  const lines = css.split('\n')
+  const line = lines[1]
+  if (line === undefined) return css
+  const match = PROVENANCE_VERSION.exec(line)
+  if (match === null) return css
+  lines[1] = `${match[1] as string}<version>${match[3] as string}`
+  return lines.join('\n')
+}
+
+/** The leading `major.minor.patch` of a version string as numbers, or null when it has none. */
+function versionTriple(version: string): number[] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version)
+  return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+/**
+ * How the on-disk provenance version relates to the one that just ran — measured, not assumed.
+ *
+ * The success message asserted the file "still names an older basalt-ui" without ever reading the
+ * token, so `0.0.1-nonsense` got the same sentence. Both sides are parsed; the numeric triples are
+ * compared and anything that does not order cleanly is reported as merely different.
+ */
+function describeVersionSkew(onDisk: string, current: string): string {
+  const a = versionTriple(onDisk)
+  const b = versionTriple(current)
+  if (a === null || b === null) return 'a different'
+  for (let i = 0; i < 3; i++) {
+    const left = a[i] as number
+    const right = b[i] as number
+    if (left < right) return 'an older'
+    if (left > right) return 'a newer'
+  }
+  return 'a different'
+}
+
 /**
  * Space- and number-normalize the argument list of a legacy color function so the emitted file
  * survives a normal repo's formatter.
@@ -3966,14 +4301,46 @@ function emitGeneratedCss(content: string, flags: string[], cwd: string, command
       )
       return 1
     }
-    if (onDisk === content) {
-      console.log(`✓ ${command} --check: ${shown} is up to date.`)
+    if (withoutProvenanceVersion(onDisk) === withoutProvenanceVersion(content)) {
+      const diskVersion = provenanceVersion(onDisk)
+      const currentVersion = provenanceVersion(content)
+      const skew =
+        diskVersion !== null && currentVersion !== null && diskVersion !== currentVersion
+          ? ` (Its provenance line names basalt-ui ${diskVersion}, ` +
+            `${describeVersionSkew(diskVersion, currentVersion)} release than the ` +
+            `${currentVersion} that just ran — only that version token is excluded from the ` +
+            'comparison. Re-run without --check whenever you want it refreshed.)'
+          : ''
+      console.log(`✓ ${command} --check: ${shown} is up to date.${skew}`)
       return 0
     }
+    // Name the provenance line when it is the ONLY thing that moved: the diff is one line the
+    // reader is about to scroll past, and a rewritten invocation is the failure that bought this
+    // branch — line 1 tells them to regenerate with line 2, so line 2 has to be true.
+    const diskLines = onDisk.split('\n')
+    const wantLines = content.split('\n')
+    const provenanceOnly =
+      diskLines.length === wantLines.length &&
+      diskLines.every((line, i) => i === 1 || line === wantLines[i]) &&
+      diskLines[1] !== wantLines[1]
+    if (provenanceOnly) {
+      console.error(
+        `✖ ${command} --check: ${shown}'s \`@generated\` provenance line does not match the ` +
+          'command that produced this content — the token values agree, line 2 does not.\n' +
+          `  on disk: ${diskLines[1]}\n` +
+          `  emitted: ${wantLines[1]}\n` +
+          'Line 1 tells the reader to regenerate with line 2, so line 2 is gated: run the emitted ' +
+          'invocation without --check and commit the result, or change the flags this check runs ' +
+          'with to the ones the file was really built from. Only the version token is exempt.',
+      )
+      return 1
+    }
     console.error(
       `✖ ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today ` +
-        `(on disk ${onDisk.split('\n').length} lines, emitted ${content.split('\n').length}) — ` +
-        're-run the same command without --check and commit the result.',
+        `(on disk ${diskLines.length} lines, emitted ${wantLines.length}) — ` +
+        're-run the same command without --check and commit the result. Only the `@generated` ' +
+        "provenance line's VERSION token is excluded from this comparison, so a release alone " +
+        'never trips it — but its flags do.',
     )
     return 1
   }
@@ -4217,9 +4584,68 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
   return 0
 }
 
+/**
+ * Every flag each subcommand accepts — the table the unknown-flag gate reads.
+ *
+ * An unrecognized flag used to be SILENTLY IGNORED and the command exited 0: `check-theme
+ * --audit-allow` scanned normally and reported success, `doctor --json` printed the human report.
+ * That is the same fail-open shape `--version` had, and it is worse on a CLI agents drive
+ * programmatically, where a typo'd gate reads as a passing gate.
+ */
+const COMMAND_FLAGS: Record<string, readonly string[]> = {
+  init: ['--with-router', '--with-query', '--merge-lint'],
+  sync: ['--force', '--check', '--tokens-only', '--framework'],
+  'check-theme': ['--audit-allows', '--tokens-only', '--framework'],
+  'check-coverage': [],
+  info: ['--json'],
+  doctor: ['--tokens-only', '--framework'],
+  'guard-hook': [],
+  'tokens:css': [
+    '--out',
+    '--check',
+    '--selector-attribute',
+    '--selector-class',
+    '--light-class',
+    '--dark-value',
+    '--light-value',
+    '--default-scheme',
+    '--media-fallback',
+    '--only',
+    '--no-legacy-aliases',
+  ],
+  'fonts:css': ['--out', '--check'],
+}
+
+/** Flags whose VALUE is the next argv token — skipped by the gate so `--out dist/x.css` does not
+ * read `dist/x.css` as a second flag. */
+const VALUE_FLAGS = new Set([
+  '--out',
+  '--selector-attribute',
+  '--selector-class',
+  '--light-class',
+  '--dark-value',
+  '--light-value',
+  '--default-scheme',
+  '--only',
+])
+
+/** The first flag `cmd` does not accept, or null. Unknown commands return null — the dispatcher's
+ * default branch already names those. */
+function unknownFlag(cmd: string, flags: readonly string[]): string | null {
+  const allowed = COMMAND_FLAGS[cmd]
+  if (allowed === undefined) return null
+  for (let i = 0; i < flags.length; i++) {
+    const flag = flags[i] as string
+    if (!flag.startsWith('-')) continue
+    if (!allowed.includes(flag)) return flag
+    if (VALUE_FLAGS.has(flag)) i++
+  }
+  return null
+}
+
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 const USAGE =
-  'Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] |\n' +
+  'Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n' +
   '                  sync [--force] [--check] [--tokens-only|--framework] |\n' +
   '                  check-theme [--audit-allows] | check-coverage | info [--json] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
@@ -4250,7 +4676,10 @@ const USAGE =
   'relocate to the single package below the cwd carrying a basalt config when invoked from a repo\n' +
   'root that has none — several carrying one is ambiguous and exits 1 in ALL THREE.\n' +
   '--tokens-only and --framework are alternatives; passing both is an error.\n\n' +
-  'Every subcommand accepts --help / -h to print this message and exit without running.'
+  'Every subcommand accepts --help / -h to print this message and exit without running.\n' +
+  '--version / -v prints the resolved package version and exits 0 — the one command that proves\n' +
+  'WHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\n' +
+  'unrecognized flag exits 1 and names what it did not understand; neither is ever ignored.'
 
 /**
  * CLI dispatcher — parses argv (subcommand + flags) and returns the command's exit code. The bin
@@ -4275,6 +4704,24 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
     console.log(USAGE)
     return 0
   }
+  // Before dispatch, for the same reason --help is: this answers "which basalt-ui is running" and
+  // must never run a command to do it. `bunx` does not re-resolve a cached package, so a consumer
+  // can pin 1.23.0, invoke `bunx basalt-ui`, and be gated by a months-old copy — the version is the
+  // only thing that catches it, and it has to be one bare line an agent can compare.
+  if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+    console.log(readFrameworkVersion(packageRoot()))
+    return 0
+  }
+  if (cmd !== undefined) {
+    const bad = unknownFlag(cmd, flags)
+    if (bad !== null) {
+      console.error(
+        `basalt-ui ${cmd}: unrecognized flag '${bad}'. ` +
+          `Accepted: ${(COMMAND_FLAGS[cmd] ?? []).join(' ') || '(none)'} --help\n`,
+      )
+      return 1
+    }
+  }
   switch (cmd) {
     case 'init':
       return init(cwd, {
@@ -4302,6 +4749,14 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
     case 'fonts:css':
       return fontsCss(flags, cwd)
     default:
+      // Named, not just implied by a usage dump: a full-screen help block with no error line reads
+      // like the command ran and chose to print help. Reported by a consumer who passed
+      // `"check-theme --audit-allows"` as ONE argument and could not tell what had been rejected.
+      console.error(
+        cmd === undefined
+          ? 'basalt-ui: no command given.\n'
+          : `basalt-ui: unknown command '${cmd}'.\n`,
+      )
       console.error(USAGE)
       return 1
   }