basalt-ui 1.25.0 → 1.26.0

package/dist/cli/index.d.ts

@@ -1,5 +1,6 @@
 import type { GuardKind, GuardSeverity } from '../guard/index.js';
 import { RULE_NAMES, SKILL_NAMES } from '../surfaces.js';
+import type { RuleName } from '../surfaces.js';
 /** Shape of the optional `"basalt"` key in a consumer's package.json. */
 export type BasaltConfig = {
     /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
@@ -324,6 +325,8 @@ type Manifest = {
      */
     spacingScale?: Record<string, number>;
 };
+/** A tracked dest inside a derived namespace that this basalt version no longer ships. */
+export declare function retiredManagedDests(manifest: Manifest, files: readonly ManagedFile[]): readonly string[];
 /**
  * Normalize a managed unit's rendered bytes for the ledger comparison below — makes a delta that is
  * PURELY formatting or a version bump invisible to drift detection, while a real prose/content edit
@@ -368,11 +371,57 @@ type SyncOptions = {
  * `sync` does not get to make silently.
  */
 export declare function sync(opts?: SyncOptions, invocationCwd?: string): number;
+/** The block's delimiters. Both are HTML comments, so the block renders as nothing in a viewer. */
+export declare const COVERAGE_BLOCK_OPEN = "<!-- basalt:coverage -->";
+export declare const COVERAGE_BLOCK_CLOSE = "<!-- /basalt:coverage -->";
 /**
- * Assert the 8 SURFACES invariants against the live SURFACES + GUARD_RULES + plugin.json.
- * Returns 0 when all pass; 1 when any fail (console.error each failure).
+ * What actually enforces one rule file's doctrine, as the file itself should state it.
  *
- * Eight assertions:
+ * Derived from SURFACES — the union over every doctrine surface carrying that `rule`, because
+ * `rule` is many-to-one (`data` covers `./data`, `./data/table`, `./data/virtual`; `mantine` covers
+ * `.` and `./connectivity`). Naming only one surface's coverage would understate the rule.
+ */
+export declare function coverageFor(rule: RuleName): {
+    guardKinds: string[];
+    pluginRules: string[];
+    advisoryLaws: string[];
+};
+/**
+ * The generated block for one rule, verbatim — HTML comments only, one claim per line so a diff
+ * points at the claim that changed rather than at a reflowed paragraph.
+ *
+ * `not guarded` is printed even when empty, and that is the point: a rule file whose block says
+ * `not guarded: —` is claiming full coverage, which is a claim someone can check. A block that
+ * simply omitted the section would read as "nothing to declare" whether or not anyone had looked
+ * (D8 — see docs/CONTROLS-SPEC.md §6 "Honest coverage").
+ */
+export declare function coverageBlock(rule: RuleName): string;
+/** The block a rule file currently carries, or null when it has none yet. */
+export declare function readCoverageBlock(text: string): string | null;
+/**
+ * `text` with `block` in it — replacing the existing block, or inserted directly below the YAML
+ * frontmatter (the rule files' `paths:` header is load-bearing and must stay first).
+ */
+export declare function applyCoverageBlock(text: string, block: string): string;
+/**
+ * Reconcile every rule file's coverage block against SURFACES.
+ *
+ * `'write'` refreshes them; `'check'` is the CI gate. A rule file with NO block yet is REPORTED,
+ * never failed — the blocks are inserted by the agent-layer wave that rewrites those files, and a
+ * gate that failed before they exist would have to be landed disabled, which is how a gate stays
+ * disabled. A block that exists and DISAGREES is a hard failure: that is drift, and drift in a
+ * coverage claim is the defect the block was added for.
+ */
+export declare function reconcileCoverageBlocks(pkgRoot: string, mode: 'write' | 'check'): {
+    failures: string[];
+    notes: string[];
+};
+/**
+ * Assert the 11 invariants against the live SURFACES + GUARD_RULES + the shipped agent layer, and
+ * (with `--write` / `--check`) reconcile the generated `<!-- basalt:coverage -->` header of every
+ * rule file against SURFACES. Returns 0 when all pass; 1 when any fail (console.error each failure).
+ *
+ * Eleven assertions:
  *  1. Every doctrine spec's guardKinds ⊆ keyof GUARD_RULES.
  *  2. Every doctrine rule (deduped) maps to agent/rules/basalt-{rule}.md on disk.
  *  3. Every doctrine skill (deduped) maps to agent/skills/{skill}/SKILL.md on disk.
@@ -386,12 +435,26 @@ export declare function sync(opts?: SyncOptions, invocationCwd?: string): number
  *     the assertion's own comment below for why); basalt's own CI does
  *     (`tests/surfaces-coverage.test.ts`).
  *  8. Every doctrine optionalPeers entry exists in peerDependencies AND peerDependenciesMeta.
+ *  9. Every registered oxlint plugin rule (PLUGIN_RULE_ID_LIST) maps to EXACTLY ONE surface's
+ *     `pluginRules` — so a new rule cannot ship homeless, and one rule cannot be counted twice as
+ *     coverage. Like assertion 7 this reads SURFACES only: whether the plugin really registers
+ *     those ids is asserted against the plugin itself in `configs/oxlint-plugin.test.ts`, which a
+ *     shipped CLI running from a consumer's node_modules cannot do.
+ * 10. Every shipped agent-layer file is inside its line budget, and the six rules are inside the
+ *     whole-layer total (`AGENT_LINE_BUDGETS` / `AGENT_RULE_TOTAL_BUDGET`).
+ * 11. Every `GUARD_RULES` kind appears on at least one doctrine surface — assertion 9's twin for
+ *     the text lane. Without it a kind could ship, be documented as a law in the spec, and be
+ *     omitted from every generated coverage header, which is how two wave-6 kinds left
+ *     `agent/rules/basalt-controls.md` printing "guard kinds — none" (D8). Unlike 9 this is
+ *     one-directional: a kind may legitimately appear on SEVERAL surfaces (`raw-hex` is on
+ *     `./charts` and `./tokens`), because a text scan is not partitioned by subpath the way a
+ *     plugin rule id is.
  *
  * Tooling surfaces are exempt from assertions 1–3 by the discriminant.
  * Synthetic #-keys participate in assertions 1 and 2 but feed assertion 3 only
  * via the deduped skill union (no independent per-#-surface skill row).
  */
-export declare function checkCoverage(): number;
+export declare function checkCoverage(flags?: readonly string[]): number;
 type DoctorResult = {
     /** Number of hard failures (exit non-zero). */
     hardFailures: number;

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -5,6 +5,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmdirSync,
   statSync,
   unlinkSync,
   writeFileSync
@@ -24,7 +25,13 @@ import {
   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 {
+  PLUGIN_RULE_ID_LIST,
+  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 [];
@@ -890,6 +897,55 @@ function migrateLegacyOxfmt(cwd, pkgRoot, manifest) {
   const shipped = readSource(pkgRoot, "configs/oxfmt.json");
   if (shipped !== null && onDisk === shipped) unlinkSync(legacyAbs);
 }
+const RETIREABLE_DEST_PATTERNS = [
+  /^\.claude\/rules\/basalt-[a-z0-9-]+\.md$/,
+  /^\.claude\/skills\/basalt-[a-z0-9-]+\/SKILL\.md$/
+];
+function retiredManagedDests(manifest, files) {
+  const shipped = new Set(files.map((f) => f.dest));
+  return Object.keys(manifest.files).filter((dest) => !shipped.has(dest)).filter((dest) => RETIREABLE_DEST_PATTERNS.some((re) => re.test(dest))).toSorted();
+}
+function reportPrune(pruned) {
+  if (pruned.removed.length > 0) {
+    console.log(
+      `
+Retired by this basalt-ui version (deleted \u2014 they no longer ship):
+` + pruned.removed.map((dest) => `  \xB7 ${dest}`).join("\n")
+    );
+  }
+  if (pruned.drifted.length === 0) return;
+  console.log(
+    `
+Retired but locally edited, so left in place \u2014 your agent still loads them. Delete them, or run \`basalt-ui sync --force\`:
+` + pruned.drifted.map((dest) => `  \xB7 ${dest}`).join("\n")
+  );
+}
+function pruneRetiredManagedFiles(cwd, manifest, files, opts = {}) {
+  const result = { removed: [], drifted: [] };
+  for (const dest of retiredManagedDests(manifest, files)) {
+    const abs = resolve(cwd, dest);
+    const current = readIfExists(abs);
+    const recorded = manifest.files[dest];
+    const untouched = current === null || sha256(current) === recorded || sha256(normalizeForLedger(current)) === recorded;
+    if (!untouched && opts.force !== true) {
+      result.drifted.push(dest);
+      continue;
+    }
+    result.removed.push(dest);
+    if (opts.dryRun === true) continue;
+    delete manifest.files[dest];
+    if (current !== null) unlinkSync(abs);
+    removeEmptyParentDir(abs);
+  }
+  return result;
+}
+function removeEmptyParentDir(fileAbs) {
+  const dir = dirname(fileAbs);
+  try {
+    if (readdirSync(dir).length === 0) rmdirSync(dir);
+  } catch {
+  }
+}
 const DESIGN_VERSION_LINE = /^(> Managed by basalt-ui) \(\d+\.\d+\.\d+\)\./m;
 function migrateDesignVersionLine(cwd) {
   const dest = resolve(cwd, "DESIGN.md");
@@ -1219,6 +1275,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     manifest.files[file.dest] = hash;
     writtenFiles.push(file.dest);
   }
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files);
   const mergeLint = scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null;
   manifest.basaltVersion = ctx.vars.BASALT_VERSION;
   manifest.spacingScale = { ...deriveSpacing(0).scale };
@@ -1227,6 +1284,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
   console.log(
     `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`
   );
+  reportPrune(pruned);
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`
@@ -1412,6 +1470,11 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     else if (tracked) recreated++;
     else created++;
   }
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files, {
+    dryRun: opts.check === true,
+    force: opts.force === true
+  });
+  staleForCheck += pruned.removed.length + pruned.drifted.length;
   if (!placement.isPackageRepoRoot) {
     console.log(
       `basalt-ui sync: 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.`
@@ -1447,6 +1510,12 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
       console.error("basalt-ui sync --check: locally-drifted managed files:");
       for (const l of driftLines) console.error(l);
     }
+    const retired = [...pruned.removed, ...pruned.drifted];
+    if (retired.length > 0) {
+      console.error(
+        `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ${retired.join(", ")} \u2014 run \`basalt-ui sync\`.`
+      );
+    }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`);
       return 1;
@@ -1459,8 +1528,9 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
   writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
 `);
   console.log(
-    `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift).`
+    `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`
   );
+  reportPrune(pruned);
   if (driftLines.length > 0) {
     console.log("Locally-edited files were skipped (run with --force to overwrite):");
     for (const l of driftLines) console.log(l);
@@ -1472,9 +1542,98 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
   }
   return 0;
 }
-function checkCoverage() {
+const COVERAGE_BLOCK_OPEN = "<!-- basalt:coverage -->";
+const COVERAGE_BLOCK_CLOSE = "<!-- /basalt:coverage -->";
+const COVERAGE_BLOCK_RE = /<!-- basalt:coverage -->[\s\S]*?<!-- \/basalt:coverage -->/;
+function coverageFor(rule) {
+  const specs = Object.values(SURFACES).filter(
+    (s) => s.kind === "doctrine" && s.rule === rule
+  );
+  const unique = (values) => [...new Set(values)].toSorted();
+  return {
+    guardKinds: unique(specs.flatMap((s) => [...s.guardKinds])),
+    pluginRules: unique(specs.flatMap((s) => [...s.pluginRules])),
+    // NOT sorted, and not deduped across surfaces by content: an advisory law is a sentence, and
+    // its order is the order the spec argues it in.
+    advisoryLaws: specs.flatMap((s) => [...s.advisoryLaws ?? []])
+  };
+}
+function coverageBlock(rule) {
+  const { guardKinds, pluginRules, advisoryLaws } = coverageFor(rule);
+  const backedBy = [
+    guardKinds.length > 0 ? `guard kinds \u2014 ${guardKinds.join(", ")}` : "guard kinds \u2014 none",
+    pluginRules.length > 0 ? `oxlint rules \u2014 ${pluginRules.map((id) => `basalt/${id}`).join(", ")}` : "oxlint rules \u2014 none"
+  ].join(" \xB7 ");
+  const lines = [
+    COVERAGE_BLOCK_OPEN,
+    "<!-- GENERATED from src/surfaces.ts \u2014 `basalt-ui check-coverage --write`. Do not hand-edit. -->",
+    `<!-- backed by: ${backedBy} -->`
+  ];
+  if (advisoryLaws.length === 0) lines.push("<!-- not guarded: \u2014 -->");
+  else for (const law of advisoryLaws) lines.push(`<!-- not guarded: ${law} -->`);
+  lines.push(COVERAGE_BLOCK_CLOSE);
+  return lines.join("\n");
+}
+function readCoverageBlock(text) {
+  return COVERAGE_BLOCK_RE.exec(text)?.[0] ?? null;
+}
+function applyCoverageBlock(text, block) {
+  if (COVERAGE_BLOCK_RE.test(text)) return text.replace(COVERAGE_BLOCK_RE, block);
+  const frontmatter = /^---\n[\s\S]*?\n---\n/.exec(text);
+  if (frontmatter === null) return `${block}
+
+${text}`;
+  const end = frontmatter[0].length;
+  return `${text.slice(0, end)}
+${block}
+${text.slice(end)}`;
+}
+function reconcileCoverageBlocks(pkgRoot, mode) {
+  const failures = [];
+  const notes = [];
+  for (const rule of RULE_NAMES) {
+    const rel = `agent/rules/basalt-${rule}.md`;
+    const path = resolve(pkgRoot, rel);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, "utf8");
+    const current = readCoverageBlock(text);
+    const expected = coverageBlock(rule);
+    if (mode === "check") {
+      if (current === null) notes.push(`${rel}: no <!-- basalt:coverage --> block yet`);
+      else if (current !== expected) {
+        failures.push(
+          `${rel}: coverage block is out of sync with SURFACES (check-coverage --write)`
+        );
+      }
+      continue;
+    }
+    if (current === expected) {
+      notes.push(`${rel}: unchanged`);
+      continue;
+    }
+    writeFileSync(path, applyCoverageBlock(text, expected), "utf8");
+    notes.push(`${rel}: ${current === null ? "block inserted" : "block updated"}`);
+  }
+  return { failures, notes };
+}
+const AGENT_LINE_BUDGETS = {
+  "agent/rules/basalt-tokens.md": 160,
+  "agent/rules/basalt-mantine.md": 180,
+  "agent/rules/basalt-charts.md": 140,
+  "agent/rules/basalt-state.md": 160,
+  "agent/rules/basalt-controls.md": 160,
+  "agent/rules/basalt-batteries.md": 220,
+  "agent/skills/basalt-app/SKILL.md": 100,
+  "agent/skills/basalt-design/SKILL.md": 100,
+  "agent/skills/basalt-charts/SKILL.md": 100,
+  "agent/templates/CLAUDE-block.md.tpl": 40,
+  "agent/templates/DESIGN.md.tpl": 45
+};
+const AGENT_RULE_TOTAL_BUDGET = 1050;
+function checkCoverage(flags = []) {
   const pkgRoot = packageRoot();
   const failures = [];
+  const notes = [];
   const allSpecs = Object.entries(SURFACES);
   const doctrineSpecs = Object.values(SURFACES).filter(
     (s) => s.kind === "doctrine"
@@ -1573,8 +1732,59 @@ function checkCoverage() {
       }
     }
   }
+  const surfacesPerPluginRule = /* @__PURE__ */ new Map();
+  for (const [key, spec] of allSpecs) {
+    if (spec.kind !== "doctrine") continue;
+    for (const id of spec.pluginRules) {
+      surfacesPerPluginRule.set(id, [...surfacesPerPluginRule.get(id) ?? [], key]);
+    }
+  }
+  for (const id of PLUGIN_RULE_ID_LIST) {
+    const owners = surfacesPerPluginRule.get(id) ?? [];
+    if (owners.length === 1) continue;
+    failures.push(
+      owners.length === 0 ? `Plugin rule 'basalt/${id}' maps to no surface \u2014 add it to one surface's pluginRules` : `Plugin rule 'basalt/${id}' maps to ${owners.length} surfaces (${owners.join(", ")}) \u2014 exactly one`
+    );
+  }
+  for (const [rel, budget] of Object.entries(AGENT_LINE_BUDGETS)) {
+    const abs = resolve(pkgRoot, rel);
+    if (!existsSync(abs)) continue;
+    const lines = readFileSync(abs, "utf8").split("\n").length - 1;
+    if (lines > budget) failures.push(`${rel}: ${lines} lines exceeds its ${budget}-line budget`);
+  }
+  const ruleTotal = RULE_NAMES.reduce((sum, rule) => {
+    const abs = resolve(pkgRoot, `agent/rules/basalt-${rule}.md`);
+    return existsSync(abs) ? sum + readFileSync(abs, "utf8").split("\n").length - 1 : sum;
+  }, 0);
+  if (ruleTotal > AGENT_RULE_TOTAL_BUDGET) {
+    failures.push(
+      `agent/rules/*.md: ${ruleTotal} lines total exceeds the ${AGENT_RULE_TOTAL_BUDGET}-line budget`
+    );
+  }
+  const surfacedGuardKinds = /* @__PURE__ */ new Set();
+  for (const spec of doctrineSpecs) {
+    for (const kind of spec.guardKinds) surfacedGuardKinds.add(kind);
+  }
+  for (const kind of Object.keys(GUARD_RULES)) {
+    if (surfacedGuardKinds.has(kind)) continue;
+    failures.push(
+      `Guard kind '${kind}' maps to no surface \u2014 add it to one surface's guardKinds so the generated coverage headers name it`
+    );
+  }
+  const write = flags.includes("--write");
+  const check = flags.includes("--check");
+  if (write && check) {
+    failures.push("--write and --check are alternatives; pass one");
+  } else if (write || check) {
+    const result = reconcileCoverageBlocks(pkgRoot, write ? "write" : "check");
+    failures.push(...result.failures);
+    notes.push(...result.notes);
+  }
+  for (const note of notes) {
+    console.log(`  ${note}`);
+  }
   if (failures.length === 0) {
-    console.log("\u2713 check-coverage: all 8 assertions pass.");
+    console.log("\u2713 check-coverage: all 11 assertions pass.");
     return 0;
   }
   console.error(`\u2716 check-coverage: ${failures.length} failure(s)`);
@@ -2425,7 +2635,7 @@ const COMMAND_FLAGS = {
   init: ["--with-router", "--with-query", "--merge-lint"],
   sync: ["--force", "--check", "--tokens-only", "--framework"],
   "check-theme": ["--audit-allows", "--tokens-only", "--framework"],
-  "check-coverage": [],
+  "check-coverage": ["--write", "--check"],
   info: ["--json"],
   doctor: ["--tokens-only", "--framework"],
   "guard-hook": [],
@@ -2465,7 +2675,7 @@ function unknownFlag(cmd, flags) {
   }
   return null;
 }
-const USAGE = "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\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\nsync [--force] [--check] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n\ncheck-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\nrelocate to the single package below the cwd carrying a basalt config when invoked from a repo\nroot that has none \u2014 several carrying one is ambiguous and exits 1 in ALL THREE.\n--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.\n--version / -v prints the resolved package version and exits 0 \u2014 the one command that proves\nWHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\nunrecognized flag exits 1 and names what it did not understand; neither is ever ignored.";
+const USAGE = "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 [--write|--check] |\n                  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\nsync [--force] [--check] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n\ncheck-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\nrelocate to the single package below the cwd carrying a basalt config when invoked from a repo\nroot that has none \u2014 several carrying one is ambiguous and exits 1 in ALL THREE.\n--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.\n--version / -v prints the resolved package version and exits 0 \u2014 the one command that proves\nWHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\nunrecognized flag exits 1 and names what it did not understand; neither is ever ignored.";
 function run(argv, cwd = process.cwd()) {
   const [cmd, ...flags] = argv;
   if (cmd === "help" || cmd === "--help" || cmd === "-h" || flags.includes("--help") || flags.includes("-h")) {
@@ -2501,7 +2711,7 @@ function run(argv, cwd = process.cwd()) {
     case "check-theme":
       return checkTheme(cwd, flags);
     case "check-coverage":
-      return checkCoverage();
+      return checkCoverage(flags);
     case "info":
       return info(flags);
     case "doctor":
@@ -2522,11 +2732,16 @@ function run(argv, cwd = process.cwd()) {
   }
 }
 export {
+  COVERAGE_BLOCK_CLOSE,
+  COVERAGE_BLOCK_OPEN,
   MANIFEST_PATH,
   RULE_NAMES,
   SKILL_NAMES,
+  applyCoverageBlock,
   checkCoverage,
   checkTheme,
+  coverageBlock,
+  coverageFor,
   doctor,
   fontsCss,
   guardHook,
@@ -2535,6 +2750,9 @@ export {
   managedFiles,
   normalizeColorFunctions,
   normalizeForLedger,
+  readCoverageBlock,
+  reconcileCoverageBlocks,
+  retiredManagedDests,
   run,
   sync,
   tokensCss

package/dist/connectivity/connectivity-indicator.d.ts

@@ -2,7 +2,10 @@
  * ConnectivityIndicator — clickable wifi icon that opens a per-signal detail popover.
  *
  * @example
- * <BasaltShell globalActions={<ConnectivityIndicator />} {...rest} />
+ * <BasaltShell
+ *   globalActions={[{ key: 'connectivity', node: <ConnectivityIndicator />, mobile: 'bar' }]}
+ *   {...rest}
+ * />
  */
 export declare function ConnectivityIndicator(): import("react").JSX.Element;
 //# sourceMappingURL=connectivity-indicator.d.ts.map

package/dist/connectivity/connectivity-indicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectivity-indicator.d.ts","sourceRoot":"","sources":["../../src/connectivity/connectivity-indicator.tsx"],"names":[],"mappings":"AA0KA;;;;;GAKG;AACH,wBAAgB,qBAAqB,gCA8EpC"}
+{"version":3,"file":"connectivity-indicator.d.ts","sourceRoot":"","sources":["../../src/connectivity/connectivity-indicator.tsx"],"names":[],"mappings":"AA6KA;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,gCA+EpC"}

package/dist/connectivity/connectivity-indicator.js

@@ -149,7 +149,7 @@ function ConnectivityIndicator() {
       {
         variant: "transparent",
         color: ICON_COLOR[status],
-        size: 28,
+        size: "ctl",
         onClick: toggle,
         onMouseEnter: scheduleOpen,
         onMouseLeave: scheduleClose,

package/dist/content/index.d.ts

@@ -7,7 +7,9 @@
  * remark-gfm + rehype-sanitize + remend, all optional peers) with its fence-renderer registry,
  * `MermaidDiagram` (beautiful-mermaid, optional peer), the MDX
  * component map, the docs-page frame (`ArticleLayout`), overview cards (`ArticleCard`/
- * `ArticleGrid`), and the contextual-help drawer (`GuideLink`/`GuideDrawer`). See
+ * `ArticleGrid`), the contextual-help drawer (`GuideLink`/`GuideDrawer`), and a re-export of the
+ * three `basalt-ui/controls` filters an article list needs (`FilterSet`/`ViewTabs`/
+ * `MultiSelectFilter`, which replaced the controlled `ArticleFilterBar`). See
  * `agent/rules/basalt-content.md` for the full doctrine + the content-collections recipe.
  */
 export { Prose } from './prose.js';
@@ -41,8 +43,8 @@ export { filterArticles, formatArticleDate, sortArticles } from './article-model
 export type { Article, ArticleFilterQuery, ArticleOrder } from './article-model.js';
 export { toArticleActions } from './article-actions.js';
 export type { ToArticleActionsOptions } from './article-actions.js';
-export { ArticleFilterBar } from './article-filter-bar.js';
-export type { ArticleFilterBarProps } from './article-filter-bar.js';
+export { FilterSet, MultiSelectFilter, ViewTabs } from '../controls/index.js';
+export type { FilterSetProps, MultiSelectFilterProps, ViewTabsOption, ViewTabsProps, } from '../controls/index.js';
 export { GuideDrawer, GuideLink } from './guide.js';
 export type { GuideDrawerProps, GuideLinkProps } from './guide.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/content/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/content/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAClD,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EACV,0BAA0B,EAC1B,cAAc,EACd,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1D,YAAY,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAE/F,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACzD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAExE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACjF,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEjE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAChD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/content/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AACvC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAClD,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,GACd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACxE,YAAY,EACV,0BAA0B,EAC1B,cAAc,EACd,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAC1D,YAAY,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAA;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAE/F,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACzD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAExE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACjF,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAQhE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACpE,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,aAAa,GACd,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAChD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA"}

package/dist/content/index.js

@@ -14,25 +14,27 @@ import { ArticleLayout } from "./article-layout.js";
 import { ArticleCard, ArticleGrid } from "./article-card.js";
 import { filterArticles, formatArticleDate, sortArticles } from "./article-model.js";
 import { toArticleActions } from "./article-actions.js";
-import { ArticleFilterBar } from "./article-filter-bar.js";
+import { FilterSet, MultiSelectFilter, ViewTabs } from "../controls/index.js";
 import { GuideDrawer, GuideLink } from "./guide.js";
 export {
   ArticleCard,
-  ArticleFilterBar,
   ArticleGrid,
   ArticleLayout,
   BASALT_SANITIZE_SCHEMA,
   Callout,
   CodeBlock,
+  FilterSet,
   GuideDrawer,
   GuideLink,
   HeadingAnchor,
   Markdown,
   MermaidDiagram,
+  MultiSelectFilter,
   Prose,
   ReadingProgress,
   SlugTracker,
   TableOfContents,
+  ViewTabs,
   blockSplit,
   createMdxComponents,
   filterArticles,

package/dist/content/prose.module.css

@@ -32,37 +32,16 @@
   margin-bottom: 0;
 }
 
-/* Fixed-header clearance so an anchor-jumped/TOC-navigated heading isn't hidden under a sticky
- * header. RESPONSIVE (docs/CONTENT-SPEC.md §5): BasaltShell's AppShell header itself switches
- * height at the `sm` breakpoint (`shell/index.tsx`'s `header={{ height: { base, sm } }}`), so the
- * clearance must too — the default below is the DESKTOP value (`>= sm`, the common path); the
- * `max-width: 47.99375em` override below swaps in the MOBILE value. `47.99375em` is Mantine's own
- * complement of a `min-width: 48em` breakpoint (`em(px - 0.1)` — verified against the installed
- * `@mantine/core`'s `MantineClasses.mjs`, the same formula behind `visibleFrom`/`hiddenFrom`), NOT
- * an independently hand-picked value — a plain `47.99em` leaves a viewport band (`47.99em` to just
- * under `48em`) matched by NEITHER this rule nor AppShell's own `(min-width: 48em)` override.
- * `48em` is a STATIC assumption, not a value this CSS module can read live: it is Mantine's default
- * `theme.breakpoints.sm` (unmodified by `baseTheme`, `theme/index.ts`), and `shell/index.tsx` reads
- * that theme value directly for its own `min-width` media query — but a media query condition
- * cannot resolve a CSS custom property (`@media (min-width: var(--x))` is not valid CSS), so this
- * static module has no way to follow a consumer's `createBasaltTheme(overrides)` that overrides
- * `breakpoints.sm`. A consumer doing so desyncs this file's breakpoint from AppShell's actual
- * header-switch point — the failure mode is a heading that scrolls to a clearance tuned for the
- * WRONG header on the mismatched viewport band, not a total breakage. Both values also assume
- * BasaltShell's own AppShell header heights — a `./content` consumer rendering Prose standalone (no
- * BasaltShell) overrides `--vx-space-sticky-header-clearance`/`-mobile` itself. */
+/* Sticky-header clearance for in-page anchors. One value on every viewport: since the
+ * controls waves the AppShell header is `appShellHeaderHeight` (48px) on phones too — the two-row
+ * mobile header and its `-mobile` clearance token are gone (docs/CONTROLS-SPEC.md §2.1, law C14).
+ * `--basalt-page-bar-h` (a sticky PageBar row 2, published by the shell) is added on top so a
+ * heading never lands under the filter row. A `./content` consumer rendering Prose standalone (no
+ * BasaltShell) overrides `--vx-space-sticky-header-clearance` itself. */
 .root h2,
 .root h3,
 .root h4 {
-  scroll-margin-top: var(--vx-space-sticky-header-clearance);
-}
-
-@media (max-width: 47.99375em) {
-  .root h2,
-  .root h3,
-  .root h4 {
-    scroll-margin-top: var(--vx-space-sticky-header-clearance-mobile);
-  }
+  scroll-margin-top: calc(var(--vx-space-sticky-header-clearance) + var(--basalt-page-bar-h, 0px));
 }
 
 /* Headings share family/weight/color across densities; size + margin differ below. */