@loworbitstudio/visor 1.21.0 → 1.23.0

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync33 } from "fs";
-import { dirname as dirname14, join as join33 } from "path";
+import { readFileSync as readFileSync34 } from "fs";
+import { dirname as dirname16, join as join34 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
 // src/commands/check.ts
 import { Command } from "commander";
-import { statSync as statSync3 } from "fs";
-import { resolve as resolve4, dirname as dirname3 } from "path";
+import { statSync as statSync4 } from "fs";
+import { resolve as resolve5, dirname as dirname4 } from "path";
 
 // src/registry/resolve.ts
 import { readFileSync } from "fs";
@@ -395,13 +395,160 @@ async function scanJsx(pathArg) {
 }
 
 // src/check/design.ts
-import { readFileSync as readFileSync3, readdirSync as readdirSync2, statSync as statSync2, existsSync } from "fs";
-import { resolve as resolve2, extname as extname2, join as join3, basename, dirname as dirname2 } from "path";
+import { readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync3, existsSync as existsSync2 } from "fs";
+import { resolve as resolve3, extname as extname2, join as join4, basename, dirname as dirname3 } from "path";
+
+// src/check/jsx-ast.ts
+import { parse as babelParse } from "@babel/parser";
+function parseJsx(source) {
+  try {
+    return babelParse(source, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return null;
+  }
+}
+
+// src/check/taxonomy.ts
+import { readFileSync as readFileSync3, existsSync, statSync as statSync2 } from "fs";
+import { resolve as resolve2, join as join3, dirname as dirname2, isAbsolute } from "path";
+var DISCOVERY_CANDIDATES = [
+  "taxonomy.json",
+  join3(".visor", "taxonomy.json"),
+  join3("design-prototypes", "admin-ui", "taxonomy.json")
+];
+function slugToIdentifier(slug2) {
+  const bare = slug2.includes("/") ? slug2.slice(slug2.lastIndexOf("/") + 1) : slug2;
+  return bare.split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function refToSlug(ref) {
+  const bare = ref.includes("/") ? ref.slice(ref.lastIndexOf("/") + 1) : ref;
+  if (!/^[a-z][a-z0-9-]*$/.test(bare)) return null;
+  return bare;
+}
+function parseTaxonomy(data, path2) {
+  const root = data;
+  const tiers = Array.isArray(root?.tiers) ? root.tiers : null;
+  if (!tiers) {
+    throw new Error(`taxonomy.json at ${path2} has no "tiers" array \u2014 not a kit taxonomy.`);
+  }
+  const slugs = /* @__PURE__ */ new Set();
+  for (const tier of tiers) {
+    const families = tier.families;
+    if (!Array.isArray(families)) continue;
+    for (const family of families) {
+      const rows = family.rows;
+      if (!Array.isArray(rows)) continue;
+      for (const row of rows) {
+        const entries = row?.visor?.entries;
+        if (!Array.isArray(entries)) continue;
+        for (const entry of entries) {
+          if (entry?.kind !== "component" && entry?.kind !== "block") continue;
+          if (typeof entry.ref !== "string") continue;
+          const slug2 = refToSlug(entry.ref);
+          if (slug2) slugs.add(slug2);
+        }
+      }
+    }
+  }
+  if (slugs.size === 0) {
+    throw new Error(`taxonomy.json at ${path2} declares no component or block elements.`);
+  }
+  const identifiers = /* @__PURE__ */ new Set();
+  for (const slug2 of slugs) identifiers.add(slugToIdentifier(slug2));
+  return { path: path2, slugs, identifiers };
+}
+function loadFrom(path2) {
+  const raw = readFileSync3(path2, "utf-8");
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new Error(`taxonomy.json at ${path2} is not valid JSON.`);
+  }
+  return parseTaxonomy(data, path2);
+}
+function discover(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    for (const candidate of DISCOVERY_CANDIDATES) {
+      const full = join3(dir, candidate);
+      if (existsSync(full)) return full;
+    }
+    if (existsSync(join3(dir, ".git"))) return null;
+    const parent = dirname2(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function resolveTaxonomy(options) {
+  const { explicitPath, visorrcPath, scanPath, env = process.env } = options;
+  const scanAbs = resolve2(scanPath);
+  let scanDir = scanAbs;
+  try {
+    if (!statSync2(scanAbs).isDirectory()) scanDir = dirname2(scanAbs);
+  } catch {
+    scanDir = dirname2(scanAbs);
+  }
+  const envPath = env.VISOR_TAXONOMY;
+  const configured = [];
+  if (explicitPath) configured.push({ path: resolve2(explicitPath), source: "flag" });
+  else if (envPath) configured.push({ path: resolve2(envPath), source: "env" });
+  else if (visorrcPath) {
+    configured.push({
+      path: isAbsolute(visorrcPath) ? visorrcPath : resolve2(scanDir, visorrcPath),
+      source: "visorrc"
+    });
+  }
+  if (configured.length > 0) {
+    const { path: path2, source } = configured[0];
+    if (!existsSync(path2)) {
+      return {
+        taxonomy: null,
+        path: path2,
+        source,
+        error: `Kit taxonomy not found at ${path2}.`,
+        requested: true
+      };
+    }
+    try {
+      return { taxonomy: loadFrom(path2), path: path2, source, error: null, requested: true };
+    } catch (err) {
+      return {
+        taxonomy: null,
+        path: path2,
+        source,
+        error: err instanceof Error ? err.message : String(err),
+        requested: true
+      };
+    }
+  }
+  const found = discover(scanDir);
+  if (!found) {
+    return { taxonomy: null, path: null, source: null, error: null, requested: false };
+  }
+  try {
+    return { taxonomy: loadFrom(found), path: found, source: "discovered", error: null, requested: false };
+  } catch (err) {
+    return {
+      taxonomy: null,
+      path: found,
+      source: "discovered",
+      error: err instanceof Error ? err.message : String(err),
+      requested: false
+    };
+  }
+}
+
+// src/check/design.ts
 function loadVisorRc(dir) {
-  const rcPath = join3(dir, ".visorrc.json");
-  if (!existsSync(rcPath)) return {};
+  const rcPath = join4(dir, ".visorrc.json");
+  if (!existsSync2(rcPath)) return {};
   try {
-    const raw = readFileSync3(rcPath, "utf-8");
+    const raw = readFileSync4(rcPath, "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -411,15 +558,15 @@ var CODE_EXTS = /* @__PURE__ */ new Set([".tsx", ".jsx", ".ts", ".js"]);
 var STYLE_EXTS = /* @__PURE__ */ new Set([".css", ".module.css"]);
 var ALL_EXTS = /* @__PURE__ */ new Set([...CODE_EXTS, ...STYLE_EXTS]);
 function collectFiles2(pathArg) {
-  const abs = resolve2(pathArg);
+  const abs = resolve3(pathArg);
   try {
-    const s = statSync2(abs);
+    const s = statSync3(abs);
     if (s.isDirectory()) {
       let recurse2 = function(dir) {
         for (const entry of readdirSync2(dir)) {
           if (entry.startsWith(".") || entry === "node_modules" || entry === "dist") continue;
-          const full = join3(dir, entry);
-          const es = statSync2(full);
+          const full = join4(dir, entry);
+          const es = statSync3(full);
           if (es.isDirectory()) recurse2(full);
           else if (ALL_EXTS.has(extname2(full))) files.push(full);
         }
@@ -493,6 +640,93 @@ function ruleHardcodedHex(source, filePath) {
   return found;
 }
 var PX_WHITELIST = /* @__PURE__ */ new Set(["0px", "1px", "2px", "3px"]);
+var LEGACY_PX_CONTEXT_RE = /margin|padding|width|height|gap|top:|left:|right:|bottom:|font-size|line-height|min-width|max-width|min-height|max-height/;
+var SIZING_PROPS = /* @__PURE__ */ new Set([
+  // box model
+  "margin",
+  "margintop",
+  "marginright",
+  "marginbottom",
+  "marginleft",
+  "marginblock",
+  "marginblockstart",
+  "marginblockend",
+  "margininline",
+  "margininlinestart",
+  "margininlineend",
+  "padding",
+  "paddingtop",
+  "paddingright",
+  "paddingbottom",
+  "paddingleft",
+  "paddingblock",
+  "paddingblockstart",
+  "paddingblockend",
+  "paddinginline",
+  "paddinginlinestart",
+  "paddinginlineend",
+  // intrinsic size
+  "width",
+  "minwidth",
+  "maxwidth",
+  "height",
+  "minheight",
+  "maxheight",
+  "size",
+  "blocksize",
+  "minblocksize",
+  "maxblocksize",
+  "inlinesize",
+  "mininlinesize",
+  "maxinlinesize",
+  // position
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "inset",
+  "insetblock",
+  "insetinline",
+  // layout gaps
+  "gap",
+  "rowgap",
+  "columngap",
+  "gridgap",
+  "gridrowgap",
+  "gridcolumngap",
+  // typographic metrics
+  "fontsize",
+  "lineheight",
+  "letterspacing",
+  "wordspacing",
+  "textindent",
+  // corner radius
+  "borderradius",
+  "bordertopleftradius",
+  "bordertoprightradius",
+  "borderbottomleftradius",
+  "borderbottomrightradius",
+  "borderstartstartradius",
+  "borderstartendradius",
+  "borderendstartradius",
+  "borderendendradius",
+  // flex + scroll boxes
+  "flexbasis",
+  "scrollmargin",
+  "scrollpadding"
+]);
+var PROP_NAME_RE = /(^|[^\w$])(-{0,2}[A-Za-z][\w-]*)\s*:/g;
+function normalizeProp(name) {
+  return name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+}
+function hasSizingProp(line) {
+  PROP_NAME_RE.lastIndex = 0;
+  let m;
+  while ((m = PROP_NAME_RE.exec(line)) !== null) {
+    if (SIZING_PROPS.has(normalizeProp(m[2]))) return true;
+  }
+  return false;
+}
 function ruleHardcodedPx(source, filePath) {
   const found = [];
   const PX_RE = /\b(\d+(?:\.\d+)?)px\b/g;
@@ -500,24 +734,134 @@ function ruleHardcodedPx(source, filePath) {
   for (let i = 0; i < src.length; i++) {
     const l = src[i];
     if (l.trim().startsWith("//") || l.trim().startsWith("*") || l.trim().startsWith("/*")) continue;
-    if (!/margin|padding|width|height|gap|top:|left:|right:|bottom:|font-size|line-height|min-width|max-width|min-height|max-height/.test(l)) continue;
+    const legacy = LEGACY_PX_CONTEXT_RE.test(l);
+    if (!legacy && !hasSizingProp(l)) continue;
     let m;
     PX_RE.lastIndex = 0;
     while ((m = PX_RE.exec(l)) !== null) {
       const full = m[0];
       if (PX_WHITELIST.has(full)) continue;
-      found.push(finding(
+      found.push(legacy ? finding(
         filePath,
         i + 1,
         "hardcoded-px",
         "error",
         `Hardcoded pixel value "${full}" in spacing/sizing bypasses the Borealis spacing token system.`,
         "Replace with a semantic spacing token: var(--space-1), var(--space-2), var(--space-4), etc."
+      ) : finding(
+        filePath,
+        i + 1,
+        "hardcoded-px",
+        "warn",
+        `Hardcoded pixel value "${full}" in spacing/sizing bypasses the Borealis spacing token system. Reported as a warning because this property spelling was previously skipped (VI-631) \u2014 it will graduate to an error in a future major.`,
+        "Replace with a semantic spacing token: var(--space-1), var(--space-2), var(--space-4), etc."
       ));
     }
   }
   return found;
 }
+var activeKit = null;
+function ruleInlineStyleObject(source, filePath) {
+  if (!CODE_EXTS.has(extname2(filePath))) return [];
+  const ast = parseJsx(source);
+  if (!ast) return [];
+  const found = [];
+  walk(ast, (node) => {
+    if (node.type !== "JSXAttribute") return;
+    const nameNode = node.name;
+    if (nameNode?.type !== "JSXIdentifier" || nameNode.name !== "style") return;
+    const valueNode = node.value;
+    if (!valueNode || valueNode.type !== "JSXExpressionContainer") return;
+    const expr = valueNode.expression;
+    if (expr?.type !== "ObjectExpression") return;
+    const declared = [];
+    for (const raw of expr.properties ?? []) {
+      const prop = raw;
+      if (prop.type !== "ObjectProperty") continue;
+      if (prop.computed === true) continue;
+      const key = prop.key;
+      let keyName = null;
+      if (key?.type === "Identifier") keyName = String(key.name ?? "");
+      else if (key?.type === "StringLiteral") keyName = String(key.value ?? "");
+      if (!keyName) continue;
+      if (keyName.startsWith("--")) continue;
+      declared.push(keyName);
+    }
+    if (declared.length === 0) return;
+    const loc = node.loc;
+    found.push(finding(
+      filePath,
+      loc?.start?.line ?? 1,
+      "inline-style-object",
+      "warn",
+      `Inline style object declares ${declared.map((d) => `"${d}"`).join(", ")}. Inline styles introduce styling outside the kit \u2014 untokenized, unthemeable, and invisible to the design system.`,
+      `Move these declarations into the component's CSS Module and reference tokens, or pass a CSS-variable bridge: style={{ "--my-token": value }}.`
+    ));
+  });
+  return found;
+}
+function ruleKitElementRedeclared(source, filePath) {
+  const kit = activeKit;
+  if (!kit) return [];
+  if (!CODE_EXTS.has(extname2(filePath))) return [];
+  if (isOwnedKitSource(filePath, kit)) return [];
+  const ast = parseJsx(source);
+  if (!ast) return [];
+  const program2 = ast.program;
+  const body = program2?.body ?? [];
+  const found = [];
+  for (const raw of body) {
+    for (const decl of moduleScopeDeclarations(raw)) {
+      if (!kit.identifiers.has(decl.name)) continue;
+      found.push(finding(
+        filePath,
+        decl.line,
+        "kit-element-redeclared",
+        "warn",
+        `Local re-declaration of the kit element "${decl.name}". This surface builds its own copy of a kit element instead of composing the kit's \u2014 the styling it introduces is outside the kit by construction.`,
+        `Compose the kit element instead (\`npx visor add ${identifierToSlug(decl.name)}\`), or rename this local component so it does not shadow a kit element.`
+      ));
+    }
+  }
+  return found;
+}
+function moduleScopeDeclarations(raw) {
+  let node = raw;
+  if (!node) return [];
+  if (node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") {
+    node = node.declaration;
+    if (!node) return [];
+  }
+  const line = node.loc?.start?.line ?? 1;
+  if (node.type === "FunctionDeclaration" || node.type === "ClassDeclaration") {
+    const id = node.id;
+    const name = id?.name;
+    return typeof name === "string" ? [{ name, line }] : [];
+  }
+  if (node.type === "VariableDeclaration") {
+    const out = [];
+    for (const d of node.declarations ?? []) {
+      const declarator = d;
+      const id = declarator.id;
+      if (id?.type !== "Identifier" || typeof id.name !== "string") continue;
+      const init = declarator.init;
+      const initType = init?.type;
+      if (initType !== "ArrowFunctionExpression" && initType !== "FunctionExpression" && initType !== "CallExpression") continue;
+      const dLine = declarator.loc?.start?.line ?? line;
+      out.push({ name: id.name, line: dLine });
+    }
+    return out;
+  }
+  return [];
+}
+function identifierToSlug(identifier) {
+  return identifier.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function isOwnedKitSource(filePath, kit) {
+  const base = basename(filePath).replace(/\.(tsx|ts|jsx|js)$/, "").replace(/\.module$/, "");
+  if (kit.slugs.has(base)) return true;
+  return kit.slugs.has(basename(dirname3(filePath)));
+}
 function ruleMissingDarkModeBlock(source, filePath) {
   const ext = extname2(filePath);
   if (!STYLE_EXTS.has(ext)) return [];
@@ -836,10 +1180,10 @@ function resetBaseLayerCache() {
   baseLayerReported.clear();
 }
 function findProjectRoot(filePath) {
-  let dir = dirname2(resolve2(filePath));
+  let dir = dirname3(resolve3(filePath));
   for (; ; ) {
-    if (existsSync(join3(dir, "package.json"))) return dir;
-    const parent = dirname2(dir);
+    if (existsSync2(join4(dir, "package.json"))) return dir;
+    const parent = dirname3(dir);
     if (parent === dir) return null;
     dir = parent;
   }
@@ -856,10 +1200,10 @@ function collectStylesheets(root) {
     }
     for (const entry of entries) {
       if (entry === "node_modules" || entry === "dist" || entry.startsWith(".")) continue;
-      const full = join3(dir, entry);
+      const full = join4(dir, entry);
       let s;
       try {
-        s = statSync2(full);
+        s = statSync3(full);
       } catch {
         continue;
       }
@@ -878,7 +1222,7 @@ function baseLayerState(root) {
   for (const sheet of collectStylesheets(root)) {
     let css;
     try {
-      css = readFileSync3(sheet, "utf-8");
+      css = readFileSync4(sheet, "utf-8");
     } catch {
       continue;
     }
@@ -886,12 +1230,12 @@ function baseLayerState(root) {
     if (PREFLIGHT_RE.test(css)) hasPreflight = true;
     if (hasReset && hasPreflight) break;
   }
-  const corePath = join3(root, "node_modules", "@loworbitstudio", "visor-core");
+  const corePath = join4(root, "node_modules", "@loworbitstudio", "visor-core");
   const state = {
     hasReset,
     hasPreflight,
-    visorCoreInstalled: existsSync(corePath),
-    visorCoreExportsReset: existsSync(join3(corePath, "dist", "reset.css"))
+    visorCoreInstalled: existsSync2(corePath),
+    visorCoreExportsReset: existsSync2(join4(corePath, "dist", "reset.css"))
   };
   baseLayerStateCache.set(root, state);
   return state;
@@ -954,12 +1298,35 @@ var RULES = [
   { name: "line-length-over-75ch", severity: "warn", fn: ruleLineLengthOver75ch },
   { name: "gradient-text", severity: "warn", fn: ruleGradientText },
   { name: "excessive-card-nesting", severity: "warn", fn: ruleExcessiveCardNesting },
-  { name: "missing-visor-base-layer", severity: "warn", fn: ruleMissingVisorBaseLayer }
+  { name: "missing-visor-base-layer", severity: "warn", fn: ruleMissingVisorBaseLayer },
+  // Composition (VI-631) — warning-only by default (D3) so the camelCase fix and
+  // the two new assertions can be adopted without escalating an existing
+  // project's exit code on first run.
+  { name: "inline-style-object", severity: "warn", fn: ruleInlineStyleObject },
+  { name: "kit-element-redeclared", severity: "warn", fn: ruleKitElementRedeclared }
 ];
+var COMPOSITION_SCOPE = {
+  scope: "composition-only",
+  asserts: "this surface introduced no styling outside the kit",
+  doesNotAssert: [
+    "arrangement (right elements, wrong order)",
+    "content (wrong icon, dropped hint)",
+    "data / reachability"
+  ],
+  limit: "Green means this surface introduced no styling outside the kit. It does NOT mean the surface is on-design. Arrangement (right elements, wrong order), content (wrong icon, dropped hint), and data/reachability are not checked here and still need a human."
+};
 function scanDesign(pathArg, options = {}) {
   const files = collectFiles2(pathArg);
   const { disabledRules = [], errorsOnly = false } = options;
   resetBaseLayerCache();
+  const resolution = resolveTaxonomy({
+    explicitPath: options.taxonomyPath,
+    visorrcPath: options.visorrcTaxonomyPath,
+    scanPath: pathArg,
+    env: options.env
+  });
+  const engaged = options.composition === true || resolution.requested || resolution.path !== null;
+  activeKit = resolution.taxonomy;
   const activeRules = RULES.filter((r) => {
     if (disabledRules.includes(r.name)) return false;
     if (errorsOnly && r.severity !== "error") return false;
@@ -967,20 +1334,35 @@ function scanDesign(pathArg, options = {}) {
   });
   const errors = [];
   const warnings = [];
-  for (const file of files) {
-    let source;
-    try {
-      source = readFileSync3(file, "utf-8");
-    } catch {
-      continue;
-    }
-    for (const rule of activeRules) {
-      const ruleFindings = rule.fn(source, file);
-      for (const f of ruleFindings) {
-        if (f.severity === "error") errors.push(f);
-        else warnings.push(f);
+  try {
+    for (const file of files) {
+      let source;
+      try {
+        source = readFileSync4(file, "utf-8");
+      } catch {
+        continue;
+      }
+      for (const rule of activeRules) {
+        const ruleFindings = rule.fn(source, file);
+        for (const f of ruleFindings) {
+          if (errorsOnly && f.severity !== "error") continue;
+          if (f.severity === "error") errors.push(f);
+          else warnings.push(f);
+        }
       }
     }
+  } finally {
+    activeKit = null;
+  }
+  if (engaged && !resolution.taxonomy && !disabledRules.includes("kit-taxonomy-missing")) {
+    errors.push(finding(
+      resolve3(pathArg),
+      1,
+      "kit-taxonomy-missing",
+      "error",
+      resolution.error ?? "Kit membership could not be asserted: no taxonomy.json resolved. The composition lint fails closed rather than reporting a green it did not earn.",
+      'Point the lint at the kit definition: --taxonomy <path/to/taxonomy.json>, the VISOR_TAXONOMY environment variable, or a "taxonomy" key in .visorrc.json.'
+    ));
   }
   return {
     errors,
@@ -989,13 +1371,34 @@ function scanDesign(pathArg, options = {}) {
       errorCount: errors.length,
       warningCount: warnings.length,
       filesScanned: files.length
+    },
+    composition: {
+      scope: COMPOSITION_SCOPE.scope,
+      asserts: COMPOSITION_SCOPE.asserts,
+      doesNotAssert: [...COMPOSITION_SCOPE.doesNotAssert],
+      limit: COMPOSITION_SCOPE.limit,
+      kitMembership: {
+        asserted: resolution.taxonomy !== null,
+        taxonomyPath: resolution.path,
+        source: resolution.source,
+        elementCount: resolution.taxonomy?.slugs.size ?? 0,
+        reason: resolution.taxonomy ? `resolved from ${resolution.source} (${resolution.taxonomy.slugs.size} kit elements)` : resolution.error ?? "no taxonomy.json resolved; pass --taxonomy <path> to assert kit membership"
+      }
     }
   };
 }
+function compositionScopeNotice() {
+  return [
+    "Composition scope \u2014 this check asserts one thing:",
+    `  ${COMPOSITION_SCOPE.asserts}.`,
+    "It does NOT assert the surface is on-design. Uncovered residue:",
+    ...COMPOSITION_SCOPE.doesNotAssert.map((r) => `  \xB7 ${r}`)
+  ];
+}
 
 // src/check/theme-mode.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync5 } from "fs";
+import { resolve as resolve4 } from "path";
 import {
   generateThemeData,
   parseColor,
@@ -1044,8 +1447,8 @@ function checkThemeModeSource(yamlSource, threshold = LUMINANCE_THRESHOLD) {
   };
 }
 function checkThemeModeFile(filePath, threshold = LUMINANCE_THRESHOLD) {
-  const abs = resolve3(filePath);
-  const source = readFileSync4(abs, "utf-8");
+  const abs = resolve4(filePath);
+  const source = readFileSync5(abs, "utf-8");
   return checkThemeModeSource(source, threshold);
 }
 
@@ -1184,16 +1587,21 @@ function checkHasCommand(pattern2, options) {
   logger.success(`${result.name} [${result.type}]${cmd}`);
   logger.info(`  ${result.description}`);
 }
+function printCompositionScope() {
+  logger.blank();
+  for (const line of compositionScopeNotice()) logger.item(line);
+  logger.blank();
+}
 async function checkDiffCommand(pathArg, options) {
   const result = await scanJsx(pathArg);
   if (options.json) {
-    console.log(JSON.stringify({ success: true, ...result }, null, 2));
-    if (options.failOnHits && result.summary.hits > 0) process.exit(1);
-    process.exit(0);
+    console.log(JSON.stringify({ success: true, ...result, composition: COMPOSITION_SCOPE }, null, 2));
+    if (options.failOnHits && result.summary.hits > 0) process.exitCode = 1;
     return;
   }
   if (result.summary.hits === 0) {
     logger.success(`No native HTML primitives found \u2014 ${result.summary.scanned} file(s) scanned.`);
+    printCompositionScope();
     return;
   }
   logger.heading(`Found ${result.summary.hits} native HTML usage(s) in ${result.summary.scanned} file(s):
@@ -1204,27 +1612,40 @@ async function checkDiffCommand(pathArg, options) {
     logger.warn(`  <${f.nativeTag}> \u2192 use <${f.suggestedPrimitive}>${note}`);
     logger.item(`  ${loc}  ${f.installCmd}`);
   }
-  logger.blank();
+  printCompositionScope();
   if (options.failOnHits) process.exit(1);
 }
 function checkDesignCommand(pathArg, options) {
-  const absPath = resolve4(pathArg);
-  const rcDir = statSync3(absPath).isDirectory() ? absPath : dirname3(absPath);
+  const absPath = resolve5(pathArg);
+  const rcDir = statSync4(absPath).isDirectory() ? absPath : dirname4(absPath);
   const rc = loadVisorRc(rcDir);
   const result = scanDesign(absPath, {
     disabledRules: rc.disabledRules ?? [],
-    errorsOnly: options.errorsOnly ?? false
+    errorsOnly: options.errorsOnly ?? false,
+    taxonomyPath: options.taxonomy,
+    visorrcTaxonomyPath: rc.taxonomy,
+    composition: options.composition ?? false
   });
   const useJson = options.json || options.format === "json";
   if (useJson) {
     console.log(JSON.stringify({ success: true, ...result }, null, 2));
-    if (!options.noFail && result.summary.errorCount > 0) process.exit(1);
-    process.exit(0);
+    if (!options.noFail && result.summary.errorCount > 0) process.exitCode = 1;
     return;
   }
-  const { errors, warnings, summary } = result;
+  const { errors, warnings, summary, composition } = result;
+  const printKitMembership = () => {
+    const km = composition.kitMembership;
+    if (km.asserted) {
+      logger.item(`Kit membership: asserted against ${km.taxonomyPath} (${km.elementCount} element(s), via ${km.source}).`);
+    } else {
+      logger.item(`Kit membership: NOT asserted \u2014 ${km.reason}`);
+    }
+  };
   if (summary.errorCount === 0 && summary.warningCount === 0) {
     logger.success(`No design anti-patterns found \u2014 ${summary.filesScanned} file(s) scanned.`);
+    printCompositionScope();
+    printKitMembership();
+    logger.blank();
     process.exit(0);
     return;
   }
@@ -1256,6 +1677,8 @@ function checkDesignCommand(pathArg, options) {
   } else {
     logger.warn(`${summary.warningCount} warning(s) (0 errors)`);
   }
+  printCompositionScope();
+  printKitMembership();
   logger.blank();
   if (!options.noFail && summary.errorCount > 0) process.exit(1);
 }
@@ -1307,7 +1730,7 @@ function checkCommand() {
   check.command("diff").description("Scan JSX/TSX for native HTML elements that have Visor equivalents").argument("<path>", "file path, directory, or - for stdin").option("--fail-on-hits", "exit 1 if any native HTML usages are found (for CI use)").option("--json", "output structured JSON (for AI agents)").action(async (pathArg, options) => {
     await checkDiffCommand(pathArg, options);
   });
-  check.command("design").description("Scan frontend code for Borealis design anti-patterns (deterministic, no LLM)").argument("<path>", "file path or directory to scan").option("--format <format>", "output format: json or human (default: human when TTY, json otherwise)").option("--errors-only", "report only error-severity rules (skip warnings)").option("--no-fail", "do not exit 1 on errors (advisory mode)").option("--json", "shorthand for --format json").action((pathArg, options) => {
+  check.command("design").description("Scan frontend code for Borealis design anti-patterns (deterministic, no LLM). Asserts composition \u2014 that the surface introduced no styling outside the kit \u2014 never arrangement.").argument("<path>", "file path or directory to scan").option("--format <format>", "output format: json or human (default: human when TTY, json otherwise)").option("--errors-only", "report only error-severity rules (skip warnings)").option("--no-fail", "do not exit 1 on errors (advisory mode)").option("--json", "shorthand for --format json").option("--taxonomy <path>", "path to the kit's taxonomy.json \u2014 the definition kit membership is asserted against").option("--composition", "require the kit-membership assertion: fail closed when no taxonomy.json resolves").action((pathArg, options) => {
     checkDesignCommand(pathArg, options);
   });
   check.command("theme-mode").description("Assert a theme's rendered app-root background matches its declared color-scheme (dark-only/light-only/adaptive)").argument("<path>", "path to a .visor.yaml theme file").option("--format <format>", "output format: json or human (default: human)").option("--no-fail", "do not exit 1 on a mode mismatch (advisory mode)").option("--json", "shorthand for --format json").action((pathArg, options) => {
@@ -1317,14 +1740,14 @@ function checkCommand() {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync6, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync9 } from "fs";
-import { join as join8, dirname as dirname5, basename as basename2 } from "path";
+import { existsSync as existsSync7, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync10 } from "fs";
+import { join as join9, dirname as dirname6, basename as basename2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import * as childProcess2 from "child_process";
 
 // src/config/config.ts
-import { readFileSync as readFileSync5, writeFileSync, existsSync as existsSync2 } from "fs";
-import { join as join4 } from "path";
+import { readFileSync as readFileSync6, writeFileSync, existsSync as existsSync3 } from "fs";
+import { join as join5 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
@@ -1341,19 +1764,19 @@ var CONFIG_FILE = "visor.json";
 
 // src/config/config.ts
 function getConfigPath(cwd) {
-  return join4(cwd, CONFIG_FILE);
+  return join5(cwd, CONFIG_FILE);
 }
 function configExists(cwd) {
-  return existsSync2(getConfigPath(cwd));
+  return existsSync3(getConfigPath(cwd));
 }
 function loadConfig(cwd) {
   const configPath = getConfigPath(cwd);
-  if (!existsSync2(configPath)) {
+  if (!existsSync3(configPath)) {
     throw new Error(
       `No ${CONFIG_FILE} found. Run "visor init" first.`
     );
   }
-  const raw = readFileSync5(configPath, "utf-8");
+  const raw = readFileSync6(configPath, "utf-8");
   const parsed = JSON.parse(raw);
   const knownKeys = /* @__PURE__ */ new Set(["paths"]);
   for (const key of Object.keys(parsed)) {
@@ -1390,12 +1813,12 @@ function writeConfig(cwd, config) {
 
 // src/utils/packages.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { join as join6 } from "path";
 function readPackageJson(cwd) {
-  const pkgPath = join5(cwd, "package.json");
-  if (!existsSync3(pkgPath)) return null;
-  return JSON.parse(readFileSync6(pkgPath, "utf-8"));
+  const pkgPath = join6(cwd, "package.json");
+  if (!existsSync4(pkgPath)) return null;
+  return JSON.parse(readFileSync7(pkgPath, "utf-8"));
 }
 function isPackageInstalled(packageName, cwd) {
   const pkg2 = readPackageJson(cwd);
@@ -1505,8 +1928,8 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 }
 
 // src/commands/init-plays/registry.ts
-import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname4, join as join6 } from "path";
+import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync8, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname5, join as join7 } from "path";
 
 // src/commands/init-plays/pattern-build.ts
 var patternBuildPlay = {
@@ -1545,24 +1968,24 @@ function knownPlayIds() {
   return KNOWN_PLAYS.map((p) => p.id);
 }
 function playStatePaths(cwd, def, name) {
-  const relDir = join6(".lo", def.loSubdir, name);
-  const dir = join6(cwd, relDir);
+  const relDir = join7(".lo", def.loSubdir, name);
+  const dir = join7(cwd, relDir);
   return {
     dir,
-    statePath: join6(dir, "state.json"),
-    relStatePath: join6(relDir, "state.json")
+    statePath: join7(dir, "state.json"),
+    relStatePath: join7(relDir, "state.json")
   };
 }
 function readPlayState(statePath) {
-  if (!existsSync4(statePath)) return null;
+  if (!existsSync5(statePath)) return null;
   try {
-    return JSON.parse(readFileSync7(statePath, "utf-8"));
+    return JSON.parse(readFileSync8(statePath, "utf-8"));
   } catch {
     return null;
   }
 }
 function writePlayState(statePath, state) {
-  mkdirSync(dirname4(statePath), { recursive: true });
+  mkdirSync(dirname5(statePath), { recursive: true });
   writeFileSync2(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 
@@ -1627,16 +2050,16 @@ function heuristicPort(name) {
 }
 
 // src/lib/lo-play-checklist.ts
-import { existsSync as existsSync5, readFileSync as readFileSync8 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync9 } from "fs";
 import { homedir } from "os";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 function defaultChecklistRoot() {
-  return join7(homedir(), ".claude", "skills", "lo-play");
+  return join8(homedir(), ".claude", "skills", "lo-play");
 }
 function readEntryChecklist(playType, options = {}) {
   const root = options.root ?? defaultChecklistRoot();
-  const path2 = join7(root, playType, "entry-checklist.md");
-  if (!existsSync5(path2)) {
+  const path2 = join8(root, playType, "entry-checklist.md");
+  if (!existsSync6(path2)) {
     return {
       found: false,
       path: path2,
@@ -1644,7 +2067,7 @@ function readEntryChecklist(playType, options = {}) {
     };
   }
   try {
-    return { found: true, path: path2, content: readFileSync8(path2, "utf-8") };
+    return { found: true, path: path2, content: readFileSync9(path2, "utf-8") };
   } catch {
     return {
       found: false,
@@ -1686,34 +2109,17 @@ function initCommand(cwd, options) {
       process.exit(1);
     }
   }
-  if (options?.template === "nextjs" && existsSync6(join8(cwd, "package.json"))) {
+  if (options?.template === "nextjs" && existsSync7(join9(cwd, "package.json"))) {
     emitError(
       json,
       "package.json already exists in this directory. visor init --template nextjs only scaffolds into empty directories. For an existing app, see the retrofit flow: https://visor.loworbit.studio/docs/guides/migration"
     );
     process.exit(1);
   }
-  if (configExists(cwd)) {
-    filesSkipped.push("visor.json");
-    if (!json) {
-      logger.warn("visor.json already exists. Skipping config creation.");
-    }
-  } else {
-    writeConfig(cwd, DEFAULT_CONFIG);
-    filesCreated.push("visor.json");
-    if (!json) {
-      logger.success("Created visor.json");
-      logger.blank();
-      logger.info("Default paths:");
-      logger.item(`components      \u2192 ${DEFAULT_CONFIG.paths.components}`);
-      logger.item(`deck components \u2192 ${DEFAULT_CONFIG.paths.deckComponents}`);
-      logger.item(`blocks          \u2192 ${DEFAULT_CONFIG.paths.blocks}`);
-      logger.item(`hooks           \u2192 ${DEFAULT_CONFIG.paths.hooks}`);
-      logger.item(`lib             \u2192 ${DEFAULT_CONFIG.paths.lib}`);
-    }
-  }
   if (options?.template === "nextjs") {
     scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings);
+  } else {
+    writeVisorConfig(cwd, json, filesCreated, filesSkipped);
   }
   if (options?.template !== "nextjs") {
     const missingTokens = !hasVisorTokens(cwd);
@@ -1845,15 +2251,37 @@ function emitError(json, message) {
     logger.error(message);
   }
 }
+function writeVisorConfig(cwd, json, filesCreated, filesSkipped) {
+  if (configExists(cwd)) {
+    filesSkipped.push("visor.json");
+    if (!json) {
+      logger.warn("visor.json already exists. Skipping config creation.");
+    }
+    return;
+  }
+  writeConfig(cwd, DEFAULT_CONFIG);
+  filesCreated.push("visor.json");
+  if (!json) {
+    logger.success("Created visor.json");
+    logger.blank();
+    logger.info("Default paths:");
+    logger.item(`components      \u2192 ${DEFAULT_CONFIG.paths.components}`);
+    logger.item(`deck components \u2192 ${DEFAULT_CONFIG.paths.deckComponents}`);
+    logger.item(`blocks          \u2192 ${DEFAULT_CONFIG.paths.blocks}`);
+    logger.item(`hooks           \u2192 ${DEFAULT_CONFIG.paths.hooks}`);
+    logger.item(`lib             \u2192 ${DEFAULT_CONFIG.paths.lib}`);
+  }
+}
 function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   if (!json) {
     logger.blank();
     logger.info("Scaffolding a Borealis-native Next.js app...");
   }
   runCreateNextApp(cwd, json);
+  writeVisorConfig(cwd, json, filesCreated, filesSkipped);
   runInstallVisorDeps(cwd, json);
-  const yamlPath = join8(cwd, ".visor.yaml");
-  if (existsSync6(yamlPath)) {
+  const yamlPath = join9(cwd, ".visor.yaml");
+  if (existsSync7(yamlPath)) {
     filesSkipped.push(".visor.yaml");
     if (!json) {
       logger.warn(".visor.yaml already exists. Skipping.");
@@ -1871,10 +2299,10 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
     tokens: data.tokens,
     config: data.config
   });
-  const globalsPath = join8(cwd, "app", "globals.css");
-  const globalsDir = dirname5(globalsPath);
+  const globalsPath = join9(cwd, "app", "globals.css");
+  const globalsDir = dirname6(globalsPath);
   mkdirSync2(globalsDir, { recursive: true });
-  if (existsSync6(globalsPath)) {
+  if (existsSync7(globalsPath)) {
     writeFileSync3(globalsPath, css, "utf-8");
     filesCreated.push("app/globals.css");
   } else {
@@ -1884,16 +2312,16 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   if (!json) {
     logger.success("Created app/globals.css with theme tokens");
   }
-  const layoutPath = join8(cwd, "app", "layout.tsx");
+  const layoutPath = join9(cwd, "app", "layout.tsx");
   const colorScheme = extractColorScheme(NEXTJS_STARTER_YAML);
   writeFileSync3(layoutPath, generateNextjsLayout(colorScheme), "utf-8");
   filesCreated.push("app/layout.tsx");
   if (!json) {
     logger.success("Wired app/layout.tsx with FOWT prevention and theme tokens");
   }
-  const stampDir = join8(cwd, ".lo");
-  const stampPath = join8(stampDir, "borealis.json");
-  if (existsSync6(stampPath)) {
+  const stampDir = join9(cwd, ".lo");
+  const stampPath = join9(stampDir, "borealis.json");
+  if (existsSync7(stampPath)) {
     filesSkipped.push(".lo/borealis.json");
     if (!json) {
       logger.warn(".lo/borealis.json already exists. Skipping.");
@@ -1957,12 +2385,12 @@ function assertSpawnSuccess(result, label) {
 }
 function readVisorCliVersion() {
   try {
-    const here = dirname5(fileURLToPath2(import.meta.url));
+    const here = dirname6(fileURLToPath2(import.meta.url));
     for (let i = 0; i < 5; i++) {
       const segments = new Array(i).fill("..");
-      const candidate = join8(here, ...segments, "package.json");
+      const candidate = join9(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync9(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync10(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) {
           return pkg2.version;
         }
@@ -1977,52 +2405,52 @@ function readVisorCliVersion() {
 // src/utils/fs.ts
 import {
   writeFileSync as writeFileSync4,
-  readFileSync as readFileSync10,
-  existsSync as existsSync7,
+  readFileSync as readFileSync11,
+  existsSync as existsSync8,
   mkdirSync as mkdirSync3
 } from "fs";
-import { dirname as dirname6, join as join9 } from "path";
+import { dirname as dirname7, join as join10 } from "path";
 function resolveOutputPath(registryPath, type, config, cwd) {
   let relativePath;
   if (type === "registry:block") {
     relativePath = registryPath.replace(/^blocks\//, "");
-    return join9(cwd, config.paths.blocks, relativePath);
+    return join10(cwd, config.paths.blocks, relativePath);
   }
   if (type === "registry:ui") {
     if (registryPath.startsWith("components/deck/")) {
       relativePath = registryPath.replace(/^components\/deck\//, "");
-      return join9(cwd, config.paths.deckComponents, relativePath);
+      return join10(cwd, config.paths.deckComponents, relativePath);
     }
     if (registryPath.startsWith("components/flutter/")) {
       relativePath = registryPath.replace(/^components\/flutter\//, "");
-      return join9(cwd, config.paths.flutterComponents, relativePath);
+      return join10(cwd, config.paths.flutterComponents, relativePath);
     }
     relativePath = registryPath.replace(/^components\/ui\//, "");
-    return join9(cwd, config.paths.components, relativePath);
+    return join10(cwd, config.paths.components, relativePath);
   }
   if (type === "registry:hook") {
     relativePath = registryPath.replace(/^hooks\//, "");
-    return join9(cwd, config.paths.hooks, relativePath);
+    return join10(cwd, config.paths.hooks, relativePath);
   }
   if (type === "registry:lib") {
     relativePath = registryPath.replace(/^lib\//, "");
-    return join9(cwd, config.paths.lib, relativePath);
+    return join10(cwd, config.paths.lib, relativePath);
   }
-  return join9(cwd, registryPath);
+  return join10(cwd, registryPath);
 }
 function writeFile(filePath, content) {
-  const dir = dirname6(filePath);
-  if (!existsSync7(dir)) {
+  const dir = dirname7(filePath);
+  if (!existsSync8(dir)) {
     mkdirSync3(dir, { recursive: true });
   }
   writeFileSync4(filePath, content, "utf-8");
 }
 function readFile(filePath) {
-  if (!existsSync7(filePath)) return null;
-  return readFileSync10(filePath, "utf-8");
+  if (!existsSync8(filePath)) return null;
+  return readFileSync11(filePath, "utf-8");
 }
 function fileExists(filePath) {
-  return existsSync7(filePath);
+  return existsSync8(filePath);
 }
 
 // src/commands/list.ts
@@ -2163,8 +2591,8 @@ function listCommand(cwd, options = {}) {
 }
 
 // src/utils/pubspec.ts
-import { existsSync as existsSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync5 } from "fs";
+import { join as join11 } from "path";
 import { parseDocument, YAMLMap } from "yaml";
 function mergePubspec(pubspecText, deps) {
   const doc = parseDocument(pubspecText);
@@ -2186,14 +2614,14 @@ function mergePubspec(pubspecText, deps) {
   return { text: doc.toString(), added, skipped };
 }
 function pubspecPath(cwd) {
-  return join10(cwd, "pubspec.yaml");
+  return join11(cwd, "pubspec.yaml");
 }
 function pubspecExists(cwd) {
-  return existsSync8(pubspecPath(cwd));
+  return existsSync9(pubspecPath(cwd));
 }
 function isPubPackageInstalled(packageName, cwd) {
   if (!pubspecExists(cwd)) return false;
-  const text = readFileSync11(pubspecPath(cwd), "utf-8");
+  const text = readFileSync12(pubspecPath(cwd), "utf-8");
   const doc = parseDocument(text);
   const depsNode = doc.get("dependencies");
   if (!(depsNode instanceof YAMLMap)) return false;
@@ -2204,12 +2632,12 @@ function getUninstalledPubDeps(deps, cwd) {
 }
 function addPubDependencies(deps, cwd) {
   const path2 = pubspecPath(cwd);
-  if (!existsSync8(path2)) {
+  if (!existsSync9(path2)) {
     throw new Error(
       `No pubspec.yaml found at ${path2}. Run this command from a Flutter project root.`
     );
   }
-  const text = readFileSync11(path2, "utf-8");
+  const text = readFileSync12(path2, "utf-8");
   const result = mergePubspec(text, deps);
   if (result.added.length > 0) {
     writeFileSync5(path2, result.text, "utf-8");
@@ -2219,12 +2647,12 @@ function addPubDependencies(deps, cwd) {
 
 // src/utils/flutter.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync9, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
+import { existsSync as existsSync10, readdirSync as readdirSync3, statSync as statSync5 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 function isExecutable(path2) {
   try {
-    const s = statSync4(path2);
+    const s = statSync5(path2);
     return s.isFile();
   } catch {
     return false;
@@ -2236,20 +2664,20 @@ function fromPath(env) {
   const bin = process.platform === "win32" ? "flutter.bat" : "flutter";
   for (const dir of pathVar.split(sep2)) {
     if (!dir) continue;
-    const candidate = join11(dir, bin);
+    const candidate = join12(dir, bin);
     if (isExecutable(candidate)) return candidate;
   }
   return null;
 }
 function fromFvm(home) {
-  const fvmDefault = join11(home, "fvm", "default", "bin", "flutter");
+  const fvmDefault = join12(home, "fvm", "default", "bin", "flutter");
   if (isExecutable(fvmDefault)) return fvmDefault;
-  const versionsDir = join11(home, "fvm", "versions");
-  if (!existsSync9(versionsDir)) return null;
+  const versionsDir = join12(home, "fvm", "versions");
+  if (!existsSync10(versionsDir)) return null;
   let best = null;
   try {
     for (const name of readdirSync3(versionsDir)) {
-      const candidate = join11(versionsDir, name, "bin", "flutter");
+      const candidate = join12(versionsDir, name, "bin", "flutter");
       if (!isExecutable(candidate)) continue;
       if (!best || compareSemver(name, best.version) > 0) {
         best = { version: name, path: candidate };
@@ -2275,7 +2703,7 @@ function findFlutterBin(options = {}) {
   const home = options.home ?? homedir2();
   const envRoot = env.FLUTTER_ROOT;
   if (envRoot) {
-    const bin = join11(envRoot, "bin", "flutter");
+    const bin = join12(envRoot, "bin", "flutter");
     if (isExecutable(bin)) return bin;
   }
   const fromPathBin = fromPath(env);
@@ -2938,8 +3366,8 @@ function infoCommand(name, cwd, options = {}) {
 }
 
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync8, mkdirSync as mkdirSync6 } from "fs";
-import { resolve as resolve7, dirname as dirname8, join as join15 } from "path";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync8, mkdirSync as mkdirSync6 } from "fs";
+import { resolve as resolve8, dirname as dirname9, join as join16 } from "path";
 import { generateTheme, generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
@@ -2950,8 +3378,8 @@ import {
 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/lib/blessed-manifest.ts
-import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync13 } from "fs";
+import { join as join13 } from "path";
 import { z } from "zod";
 var BLESSED_MANIFEST_FILENAME = "blessed-manifest.json";
 var themeApplyTargetSchema = z.discriminatedUnion("kind", [
@@ -2983,8 +3411,8 @@ var blessedManifestSchema = z.object({
   theme_apply_target: themeApplyTargetSchema.optional()
 }).strict();
 function parseBlessedManifest(buildDir) {
-  const manifestPath = join12(buildDir, BLESSED_MANIFEST_FILENAME);
-  if (!existsSync10(manifestPath)) {
+  const manifestPath = join13(buildDir, BLESSED_MANIFEST_FILENAME);
+  if (!existsSync11(manifestPath)) {
     return {
       ok: false,
       error: `this directory is not a blessed build (missing ${BLESSED_MANIFEST_FILENAME}); see docs/blessed-builds.md`
@@ -2992,7 +3420,7 @@ function parseBlessedManifest(buildDir) {
   }
   let raw;
   try {
-    raw = readFileSync12(manifestPath, "utf-8");
+    raw = readFileSync13(manifestPath, "utf-8");
   } catch {
     return { ok: false, error: `could not read ${manifestPath}` };
   }
@@ -3018,31 +3446,31 @@ function parseBlessedManifest(buildDir) {
 }
 
 // src/lib/theme-apply-targets/globals-css.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "fs";
-import { dirname as dirname7, isAbsolute, join as join13, resolve as resolve5 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname8, isAbsolute as isAbsolute2, join as join14, resolve as resolve6 } from "path";
 function applyGlobalsCss(input) {
   const outFile = input.path !== void 0 ? resolveInsideBuild(input.buildDir, input.path) : resolveDefaultGlobalsCss(input.buildDir);
-  mkdirSync4(dirname7(outFile), { recursive: true });
+  mkdirSync4(dirname8(outFile), { recursive: true });
   writeFileSync6(outFile, input.adapterCss, "utf-8");
   return outFile;
 }
 function resolveDefaultGlobalsCss(buildDir) {
   const candidates = [
-    join13(buildDir, "app", "globals.css"),
-    join13(buildDir, "src", "app", "globals.css")
+    join14(buildDir, "app", "globals.css"),
+    join14(buildDir, "src", "app", "globals.css")
   ];
-  return candidates.find((candidate) => existsSync11(candidate)) ?? candidates[0];
+  return candidates.find((candidate) => existsSync12(candidate)) ?? candidates[0];
 }
 function resolveInsideBuild(buildDir, relativeOrAbsolute) {
-  return isAbsolute(relativeOrAbsolute) ? relativeOrAbsolute : resolve5(buildDir, relativeOrAbsolute);
+  return isAbsolute2(relativeOrAbsolute) ? relativeOrAbsolute : resolve6(buildDir, relativeOrAbsolute);
 }
 
 // src/lib/theme-apply-targets/themes-css-dir.ts
 import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync7 } from "fs";
-import { isAbsolute as isAbsolute2, join as join14, resolve as resolve6 } from "path";
+import { isAbsolute as isAbsolute3, join as join15, resolve as resolve7 } from "path";
 function applyThemesCssDir(input) {
-  const dir = isAbsolute2(input.path) ? input.path : resolve6(input.buildDir, input.path);
-  const outFile = join14(dir, `${input.themeId}.css`);
+  const dir = isAbsolute3(input.path) ? input.path : resolve7(input.buildDir, input.path);
+  const outFile = join15(dir, `${input.themeId}.css`);
   mkdirSync5(dir, { recursive: true });
   writeFileSync7(outFile, input.adapterCss, "utf-8");
   return outFile;
@@ -3106,10 +3534,10 @@ function defaultOutputPath(adapter, themeName) {
   }
 }
 function themeApplyCommand(file, cwd, options) {
-  const filePath = resolve7(cwd, file);
+  const filePath = resolve8(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync13(filePath, "utf-8");
+    yamlContent = readFileSync14(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -3203,7 +3631,7 @@ function themeApplyCommand(file, cwd, options) {
       else logger.error(message);
       process.exit(1);
     }
-    const buildDir = resolve7(cwd, options.targetPath);
+    const buildDir = resolve8(cwd, options.targetPath);
     const manifestResult = parseBlessedManifest(buildDir);
     if (!manifestResult.ok) {
       if (options.json) {
@@ -3246,14 +3674,14 @@ function themeApplyCommand(file, cwd, options) {
     return;
   }
   const outputTarget = options.output ?? defaultOutputPath(options.adapter, themeName);
-  const outputPath = resolve7(cwd, outputTarget);
+  const outputPath = resolve8(cwd, outputTarget);
   if (fileMap) {
     try {
       mkdirSync6(outputPath, { recursive: true });
       let totalBytes = 0;
       for (const [relPath, content] of Object.entries(fileMap.files)) {
-        const filePath2 = join15(outputPath, relPath);
-        mkdirSync6(dirname8(filePath2), { recursive: true });
+        const filePath2 = join16(outputPath, relPath);
+        mkdirSync6(dirname9(filePath2), { recursive: true });
         writeFileSync8(filePath2, content, "utf-8");
         totalBytes += content.length;
       }
@@ -3291,7 +3719,7 @@ function themeApplyCommand(file, cwd, options) {
   if (css === null) {
     process.exit(1);
   }
-  const outputDir = dirname8(outputPath);
+  const outputDir = dirname9(outputPath);
   try {
     mkdirSync6(outputDir, { recursive: true });
     writeFileSync8(outputPath, css, "utf-8");
@@ -3335,8 +3763,8 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { resolve as resolve8 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { resolve as resolve9 } from "path";
 import {
   parseConfig,
   resolveConfig,
@@ -3344,10 +3772,10 @@ import {
   exportTheme
 } from "@loworbitstudio/visor-theme-engine";
 function themeExportCommand(file, cwd, options) {
-  const filePath = resolve8(cwd, file ?? ".visor.yaml");
+  const filePath = resolve9(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync14(filePath, "utf-8");
+    yamlContent = readFileSync15(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -3399,16 +3827,16 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync15 } from "fs";
-import { resolve as resolve9 } from "path";
+import { readFileSync as readFileSync16 } from "fs";
+import { resolve as resolve10 } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
 import pc3 from "picocolors";
 function themeValidateCommand(file, cwd, options) {
-  const filePath = resolve9(cwd, file);
+  const filePath = resolve10(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync15(filePath, "utf-8");
+    fileContent = readFileSync16(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -3497,8 +3925,8 @@ function printIssue(issue) {
 
 // src/commands/theme-verify.ts
 import { spawnSync as _spawnSync } from "child_process";
-import { existsSync as existsSync12 } from "fs";
-import { resolve as resolve10 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { resolve as resolve11 } from "path";
 function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
   const target = options.target ?? "flutter";
   if (target !== "flutter") {
@@ -3520,8 +3948,8 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
     }
     process.exit(1);
   }
-  const dirPath = resolve10(cwd, dir);
-  if (!existsSync12(dirPath)) {
+  const dirPath = resolve11(cwd, dir);
+  if (!existsSync13(dirPath)) {
     if (options.json) {
       console.log(
         JSON.stringify({
@@ -3608,8 +4036,8 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
 }
 
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync16, writeFileSync as writeFileSync9, existsSync as existsSync13, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
-import { resolve as resolve11, join as join16, basename as basename3, extname as extname3, relative } from "path";
+import { readFileSync as readFileSync17, writeFileSync as writeFileSync9, existsSync as existsSync14, readdirSync as readdirSync4, statSync as statSync6 } from "fs";
+import { resolve as resolve12, join as join17, basename as basename3, extname as extname3, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -3638,8 +4066,8 @@ var CSS_DIRS = [
   "packages/design-tokens"
 ];
 function themeExtractCommand(cwd, options) {
-  const targetDir = resolve11(cwd, options.from ?? ".");
-  if (!existsSync13(targetDir)) {
+  const targetDir = resolve12(cwd, options.from ?? ".");
+  if (!existsSync14(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
     } else {
@@ -3693,16 +4121,16 @@ function collectCSSFiles(targetDir) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
   for (const pattern2 of CSS_FILE_PATTERNS) {
-    const rootPath = join16(targetDir, pattern2);
+    const rootPath = join17(targetDir, pattern2);
     addFileIfExists(rootPath, files, seen);
     for (const dir of CSS_DIRS) {
-      const dirPath = join16(targetDir, dir, pattern2);
+      const dirPath = join17(targetDir, dir, pattern2);
       addFileIfExists(dirPath, files, seen);
     }
   }
   for (const dir of CSS_DIRS) {
-    const dirPath = join16(targetDir, dir);
-    if (existsSync13(dirPath) && statSync5(dirPath).isDirectory()) {
+    const dirPath = join17(targetDir, dir);
+    if (existsSync14(dirPath) && statSync6(dirPath).isDirectory()) {
       scanDirForCSS(dirPath, files, seen, 2);
     }
   }
@@ -3710,11 +4138,11 @@ function collectCSSFiles(targetDir) {
   return files;
 }
 function addFileIfExists(filePath, files, seen) {
-  const resolved = resolve11(filePath);
+  const resolved = resolve12(filePath);
   if (seen.has(resolved)) return;
-  if (!existsSync13(resolved)) return;
+  if (!existsSync14(resolved)) return;
   try {
-    const content = readFileSync16(resolved, "utf-8");
+    const content = readFileSync17(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -3723,7 +4151,7 @@ function addFileIfExists(filePath, files, seen) {
   }
 }
 function scanDirForCSS(dir, files, seen, maxDepth) {
-  if (!existsSync13(dir)) return;
+  if (!existsSync14(dir)) return;
   const SKIP_DIRS = /* @__PURE__ */ new Set([
     "node_modules",
     ".next",
@@ -3742,10 +4170,10 @@ function scanDirForCSS(dir, files, seen, maxDepth) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
         if (maxDepth > 0) {
-          scanDirForCSS(join16(dir, entry.name), files, seen, maxDepth - 1);
+          scanDirForCSS(join17(dir, entry.name), files, seen, maxDepth - 1);
         }
       } else if (entry.isFile() && extname3(entry.name) === ".css") {
-        addFileIfExists(join16(dir, entry.name), files, seen);
+        addFileIfExists(join17(dir, entry.name), files, seen);
       }
     }
   } catch {
@@ -3827,10 +4255,10 @@ function extractVarName(varExpr) {
 function parseNextFontFromLayouts(targetDir) {
   const fontMap = /* @__PURE__ */ new Map();
   for (const relPath of LAYOUT_FILE_PATHS) {
-    const fullPath = join16(targetDir, relPath);
-    if (!existsSync13(fullPath)) continue;
+    const fullPath = join17(targetDir, relPath);
+    if (!existsSync14(fullPath)) continue;
     try {
-      const content = readFileSync16(fullPath, "utf-8");
+      const content = readFileSync17(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -3915,10 +4343,10 @@ var MONO_FONT_NAMES = /* @__PURE__ */ new Set([
   "IBM Plex Mono"
 ]);
 function extractFontHints(targetDir) {
-  const pkgPath = join16(targetDir, "package.json");
-  if (!existsSync13(pkgPath)) return void 0;
+  const pkgPath = join17(targetDir, "package.json");
+  if (!existsSync14(pkgPath)) return void 0;
   try {
-    const pkg2 = JSON.parse(readFileSync16(pkgPath, "utf-8"));
+    const pkg2 = JSON.parse(readFileSync17(pkgPath, "utf-8"));
     const allDeps = { ...pkg2.dependencies, ...pkg2.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -3954,10 +4382,10 @@ function extractFontHints(targetDir) {
   }
 }
 function inferThemeName(targetDir) {
-  const pkgPath = join16(targetDir, "package.json");
-  if (existsSync13(pkgPath)) {
+  const pkgPath = join17(targetDir, "package.json");
+  if (existsSync14(pkgPath)) {
     try {
-      const pkg2 = JSON.parse(readFileSync16(pkgPath, "utf-8"));
+      const pkg2 = JSON.parse(readFileSync17(pkgPath, "utf-8"));
       if (pkg2.name) {
         const name = pkg2.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -3994,7 +4422,7 @@ function outputJSON(result, validationResult) {
 }
 function outputYAML(result, outputPath, cwd, validationResult) {
   const yamlStr = buildAnnotatedYAML(result);
-  const outFile = resolve11(cwd, outputPath ?? ".visor.yaml");
+  const outFile = resolve12(cwd, outputPath ?? ".visor.yaml");
   const high = result.tokens.filter((t) => t.confidence === "high").length;
   const med = result.tokens.filter((t) => t.confidence === "medium").length;
   const low = result.tokens.filter((t) => t.confidence === "low").length;
@@ -4080,14 +4508,14 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync18, writeFileSync as writeFileSync10, mkdirSync as mkdirSync7, existsSync as existsSync15 } from "fs";
-import { resolve as resolve13, join as join18 } from "path";
+import { readFileSync as readFileSync19, writeFileSync as writeFileSync10, mkdirSync as mkdirSync7, existsSync as existsSync16 } from "fs";
+import { resolve as resolve14, join as join19 } from "path";
 import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
-import { existsSync as existsSync14, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync17, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
-import { resolve as resolve12, dirname as dirname9, join as join17 } from "path";
+import { existsSync as existsSync15, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync18, readlinkSync, realpathSync, statSync as statSync7 } from "fs";
+import { resolve as resolve13, dirname as dirname10, join as join18 } from "path";
 import { execFileSync as execFileSync3 } from "child_process";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
@@ -4096,12 +4524,12 @@ function toLabel(name) {
   return name.split(/[\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function findRepoRoot(startDir) {
-  let current = resolve12(startDir);
+  let current = resolve13(startDir);
   while (true) {
-    if (existsSync14(join17(current, "packages", "docs"))) {
+    if (existsSync15(join18(current, "packages", "docs"))) {
       return current;
     }
-    const parent = dirname9(current);
+    const parent = dirname10(current);
     if (parent === current) break;
     current = parent;
   }
@@ -4115,9 +4543,9 @@ function findMainRepoRoot(startDir) {
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     if (commonDir) {
-      const absoluteCommonDir = resolve12(startDir, commonDir);
-      const candidate = dirname9(absoluteCommonDir);
-      if (existsSync14(join17(candidate, "packages", "docs"))) {
+      const absoluteCommonDir = resolve13(startDir, commonDir);
+      const candidate = dirname10(absoluteCommonDir);
+      if (existsSync15(join18(candidate, "packages", "docs"))) {
         return candidate;
       }
     }
@@ -4136,10 +4564,10 @@ var BrokenSymlinkError = class extends Error {
   code = "BROKEN_SYMLINK";
 };
 function assertNoBrokenSymlinks(dir) {
-  if (!existsSync14(dir)) return;
+  if (!existsSync15(dir)) return;
   const entries = readdirSync5(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const entryPath = join17(dir, entry.name);
+    const entryPath = join18(dir, entry.name);
     let lst;
     try {
       lst = lstatSync(entryPath);
@@ -4149,7 +4577,7 @@ function assertNoBrokenSymlinks(dir) {
     if (lst.isSymbolicLink()) {
       const target = readlinkSync(entryPath);
       try {
-        statSync6(entryPath);
+        statSync7(entryPath);
       } catch {
         throw new BrokenSymlinkError(entryPath, target);
       }
@@ -4157,39 +4585,39 @@ function assertNoBrokenSymlinks(dir) {
   }
 }
 function scanParentForPrivateThemes(parentDir) {
-  if (!existsSync14(parentDir)) return [];
+  if (!existsSync15(parentDir)) return [];
   const entries = readdirSync5(parentDir, { withFileTypes: true });
   const matches = [];
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const candidate = join17(parentDir, entry.name, "visor-themes-private", "themes");
-    if (existsSync14(candidate)) {
+    const candidate = join18(parentDir, entry.name, "visor-themes-private", "themes");
+    if (existsSync15(candidate)) {
       matches.push(candidate);
     }
   }
   return matches.sort();
 }
 function scanNestedThemeDir(dir) {
-  if (!existsSync14(dir)) return [];
+  if (!existsSync15(dir)) return [];
   assertNoBrokenSymlinks(dir);
   const entries = readdirSync5(dir, { withFileTypes: true });
   const out = [];
   for (const entry of entries) {
     if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const themeFile = join17(dir, entry.name, "theme.visor.yaml");
-    if (existsSync14(themeFile)) {
+    const themeFile = join18(dir, entry.name, "theme.visor.yaml");
+    if (existsSync15(themeFile)) {
       out.push({ filePath: themeFile, slug: entry.name });
     }
   }
   return out;
 }
 function detectVisorWorkspace(cwd) {
-  let current = resolve12(cwd);
+  let current = resolve13(cwd);
   while (true) {
-    const pkgPath = join17(current, "package.json");
-    if (existsSync14(pkgPath)) {
+    const pkgPath = join18(current, "package.json");
+    if (existsSync15(pkgPath)) {
       try {
-        const pkg2 = JSON.parse(readFileSync17(pkgPath, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync18(pkgPath, "utf-8"));
         const workspaces = pkg2.workspaces ?? [];
         const hasCli = workspaces.some((w) => w.includes("packages/cli"));
         const hasEngine = workspaces.some((w) => w.includes("packages/theme-engine"));
@@ -4199,7 +4627,7 @@ function detectVisorWorkspace(cwd) {
       } catch {
       }
     }
-    const parent = dirname9(current);
+    const parent = dirname10(current);
     if (parent === current) break;
     current = parent;
   }
@@ -4207,18 +4635,18 @@ function detectVisorWorkspace(cwd) {
 }
 function isLocalVisorBinary(workspaceRoot, scriptPath) {
   if (!scriptPath) return false;
-  const expectedPrefix = join17(workspaceRoot, "packages", "cli", "dist");
+  const expectedPrefix = join18(workspaceRoot, "packages", "cli", "dist");
   let resolvedScript;
   let resolvedPrefix;
   try {
     resolvedScript = realpathSync(scriptPath);
   } catch {
-    resolvedScript = resolve12(scriptPath);
+    resolvedScript = resolve13(scriptPath);
   }
   try {
     resolvedPrefix = realpathSync(expectedPrefix);
   } catch {
-    resolvedPrefix = resolve12(expectedPrefix);
+    resolvedPrefix = resolve13(expectedPrefix);
   }
   return resolvedScript.startsWith(resolvedPrefix + "/") || resolvedScript === resolvedPrefix;
 }
@@ -4308,10 +4736,10 @@ ${indent}${newEntry},
   return { updated, changed: true };
 }
 function themeRegisterCommand(file, cwd, options) {
-  const filePath = resolve13(cwd, file);
+  const filePath = resolve14(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync18(filePath, "utf-8");
+    yamlContent = readFileSync19(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -4354,11 +4782,11 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join18(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join18(docsAppDir, `${slug2}-theme.css`);
-  const globalsPath = join18(docsAppDir, "globals.css");
-  const themeConfigPath = join18(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync15(docsAppDir)) {
+  const docsAppDir = join19(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join19(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join19(docsAppDir, "globals.css");
+  const themeConfigPath = join19(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync16(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -4371,8 +4799,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync18(globalsPath, "utf-8");
-    themeConfigContent = readFileSync18(themeConfigPath, "utf-8");
+    globalsContent = readFileSync19(globalsPath, "utf-8");
+    themeConfigContent = readFileSync19(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -4383,8 +4811,8 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync15(cssFilePath);
-  const cssChanged = !cssExists || readFileSync18(cssFilePath, "utf-8") !== css;
+  const cssExists = existsSync16(cssFilePath);
+  const cssChanged = !cssExists || readFileSync19(cssFilePath, "utf-8") !== css;
   const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
@@ -4468,8 +4896,8 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync19, writeFileSync as writeFileSync11, existsSync as existsSync16, unlinkSync } from "fs";
-import { join as join19 } from "path";
+import { readFileSync as readFileSync20, writeFileSync as writeFileSync11, existsSync as existsSync17, unlinkSync } from "fs";
+import { join as join20 } from "path";
 function removeGlobalsImport(content, slug2) {
   const importLine = `@import './${slug2}-theme.css';`;
   if (!content.includes(importLine)) {
@@ -4501,11 +4929,11 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join19(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join19(docsAppDir, `${slug2}-theme.css`);
-  const globalsPath = join19(docsAppDir, "globals.css");
-  const themeConfigPath = join19(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync16(docsAppDir)) {
+  const docsAppDir = join20(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join20(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join20(docsAppDir, "globals.css");
+  const themeConfigPath = join20(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync17(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -4518,8 +4946,8 @@ function themeUnregisterCommand(slug2, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync19(globalsPath, "utf-8");
-    themeConfigContent = readFileSync19(themeConfigPath, "utf-8");
+    globalsContent = readFileSync20(globalsPath, "utf-8");
+    themeConfigContent = readFileSync20(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -4530,7 +4958,7 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync16(cssFilePath);
+  const cssExists = existsSync17(cssFilePath);
   const { updated: newGlobals, changed: globalsChanged } = removeGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged } = removeThemeConfigEntry(themeConfigContent, slug2);
   if (!cssExists && !globalsChanged && !themeConfigChanged) {
@@ -4571,15 +4999,15 @@ function themeUnregisterCommand(slug2, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync20,
+  readFileSync as readFileSync21,
   writeFileSync as writeFileSync12,
   mkdirSync as mkdirSync8,
-  existsSync as existsSync17,
+  existsSync as existsSync18,
   readdirSync as readdirSync6,
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join20, basename as basename4, resolve as resolve14, sep, relative as relative2 } from "path";
+import { join as join21, basename as basename4, resolve as resolve15, sep, relative as relative2 } from "path";
 import { parse as parseYaml3 } from "yaml";
 import { generateThemeData as generateThemeData5, validateFontCoverage, formatFontCoverageError } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
@@ -4593,9 +5021,9 @@ var CUSTOM_OVERLAY_CSS_PATH = "packages/docs/app/custom-themes.generated.css";
 var CUSTOM_OVERLAY_TS_PATH = "packages/docs/lib/theme-config.custom.generated.ts";
 var CUSTOM_OVERLAY_IMPORT_LINE = "@import './custom-themes.generated.css';";
 function scanThemeDir(dir) {
-  if (!existsSync17(dir)) return [];
+  if (!existsSync18(dir)) return [];
   assertNoBrokenSymlinks(dir);
-  return readdirSync6(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join20(dir, f));
+  return readdirSync6(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join21(dir, f));
 }
 function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   const merged = /* @__PURE__ */ new Map();
@@ -4619,20 +5047,20 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   };
   const envPath = process.env[PRIVATE_THEMES_ENV_VAR];
   if (envPath && envPath.trim() !== "") {
-    const resolved = resolve14(envPath);
-    if (!existsSync17(resolved)) {
+    const resolved = resolve15(envPath);
+    if (!existsSync18(resolved)) {
       throw new Error(
         `${PRIVATE_THEMES_ENV_VAR} is set to "${envPath}" but the path does not exist. Expected a directory containing {slug}/theme.visor.yaml entries.`
       );
     }
     addNested(resolved, "env");
   }
-  const siblingPath = join20(mainRepoRoot, "..", "visor-themes-private", "themes");
-  const siblingExists = existsSync17(siblingPath);
+  const siblingPath = join21(mainRepoRoot, "..", "visor-themes-private", "themes");
+  const siblingExists = existsSync18(siblingPath);
   if (siblingExists) {
     addNested(siblingPath, "sibling");
   }
-  const parentDir = join20(mainRepoRoot, "..");
+  const parentDir = join21(mainRepoRoot, "..");
   const parentGlobMatches = scanParentForPrivateThemes(parentDir).filter(
     (path2) => !path2.startsWith(mainRepoRoot + sep)
   );
@@ -4653,7 +5081,7 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
       }
     }
   }
-  const legacyDir = join20(repoRoot, "custom-themes");
+  const legacyDir = join21(repoRoot, "custom-themes");
   const legacyFiles = scanThemeDir(legacyDir);
   for (const legacyFile of legacyFiles) {
     const slug2 = basename4(legacyFile).replace(/\.visor\.yaml$/, "");
@@ -4710,14 +5138,14 @@ function reportBrokenSymlink(err, options) {
   }
 }
 function buildEmptySourcesMessage(mainRepoRoot) {
-  const expectedSibling = join20(mainRepoRoot, "..", "visor-themes-private");
+  const expectedSibling = join21(mainRepoRoot, "..", "visor-themes-private");
   return [
     "No theme sources discovered. Cannot proceed \u2014 refusing to wipe generated CSS.",
     "",
     "Resolution order checked:",
     `  1. Env var ${PRIVATE_THEMES_ENV_VAR} (unset or empty)`,
     `  2. Sibling checkout at ${expectedSibling}/themes/ (not found)`,
-    `  3. One-level-deeper at ${join20(mainRepoRoot, "..")}/<parent>/visor-themes-private/themes/ (not found)`,
+    `  3. One-level-deeper at ${join21(mainRepoRoot, "..")}/<parent>/visor-themes-private/themes/ (not found)`,
     "  4. Legacy custom-themes/ (no .visor.yaml files)",
     "",
     "To fix, clone the private themes repo as a sibling:",
@@ -4922,14 +5350,14 @@ function themeSyncCommand(cwd, options) {
     return;
   }
   const mainRepoRoot = findMainRepoRoot(cwd) ?? repoRoot;
-  const themesDir = join20(repoRoot, "themes");
-  const docsAppDir = join20(repoRoot, "packages", "docs", "app");
-  const docsLibDir = join20(repoRoot, "packages", "docs", "lib");
-  const docsPublicThemesDir = join20(repoRoot, "packages", "docs", "public", "themes");
-  const themeConfigPath = join20(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  const globalsPath = join20(docsAppDir, "globals.css");
-  const customOverlayCssPath = join20(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
-  const customOverlayTsPath = join20(repoRoot, CUSTOM_OVERLAY_TS_PATH);
+  const themesDir = join21(repoRoot, "themes");
+  const docsAppDir = join21(repoRoot, "packages", "docs", "app");
+  const docsLibDir = join21(repoRoot, "packages", "docs", "lib");
+  const docsPublicThemesDir = join21(repoRoot, "packages", "docs", "public", "themes");
+  const themeConfigPath = join21(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const globalsPath = join21(docsAppDir, "globals.css");
+  const customOverlayCssPath = join21(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
+  const customOverlayTsPath = join21(repoRoot, CUSTOM_OVERLAY_TS_PATH);
   let stockFiles;
   try {
     stockFiles = scanThemeDir(themesDir);
@@ -4986,7 +5414,7 @@ function themeSyncCommand(cwd, options) {
   const processFile = (filePath, isCustom, slugOverride) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync20(filePath, "utf-8");
+      yamlContent = readFileSync21(filePath, "utf-8");
     } catch {
       failures.push({ filePath, error: `Could not read: ${filePath}` });
       return;
@@ -5036,8 +5464,8 @@ function themeSyncCommand(cwd, options) {
   let globalsContent;
   let themeConfigContent;
   try {
-    globalsContent = readFileSync20(globalsPath, "utf-8");
-    themeConfigContent = readFileSync20(themeConfigPath, "utf-8");
+    globalsContent = readFileSync21(globalsPath, "utf-8");
+    themeConfigContent = readFileSync21(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -5052,12 +5480,12 @@ function themeSyncCommand(cwd, options) {
   const newThemeConfig = updateStockThemeConfigBlock(themeConfigContent, stockManifest);
   const newCustomOverlayCss = generateCustomOverlayCss(customManifest);
   const newCustomOverlayTs = generateCustomOverlayTs(customManifest);
-  const existingCssFiles = existsSync17(docsAppDir) ? readdirSync6(docsAppDir).filter(
+  const existingCssFiles = existsSync18(docsAppDir) ? readdirSync6(docsAppDir).filter(
     (f) => f.endsWith("-theme.css") && f !== "custom-themes.generated.css"
   ) : [];
   const newCssSet = new Set(allSlugs.map((s) => `${s}-theme.css`));
   const staleCssFiles = existingCssFiles.filter((f) => !newCssSet.has(f));
-  const existingPublicYamls = existsSync17(docsPublicThemesDir) ? readdirSync6(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
+  const existingPublicYamls = existsSync18(docsPublicThemesDir) ? readdirSync6(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
   const newPublicYamlSet = new Set(manifest.map((e) => `${e.yamlFilename}.visor.yaml`));
   const stalePublicYamls = existingPublicYamls.filter((f) => !newPublicYamlSet.has(f));
   if (options.dryRun) {
@@ -5101,24 +5529,24 @@ function themeSyncCommand(cwd, options) {
     mkdirSync8(docsLibDir, { recursive: true });
     mkdirSync8(docsPublicThemesDir, { recursive: true });
     for (const entry of manifest) {
-      writeFileSync12(join20(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
+      writeFileSync12(join21(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
     }
     for (const stale of staleCssFiles) {
-      unlinkSync2(join20(docsAppDir, stale));
+      unlinkSync2(join21(docsAppDir, stale));
     }
     writeFileSync12(customOverlayCssPath, newCustomOverlayCss, "utf-8");
     writeFileSync12(customOverlayTsPath, newCustomOverlayTs, "utf-8");
     writeFileSync12(themeConfigPath, newThemeConfig, "utf-8");
     writeFileSync12(globalsPath, newGlobals, "utf-8");
     for (const srcFile of stockFiles) {
-      copyFileSync(srcFile, join20(docsPublicThemesDir, basename4(srcFile)));
+      copyFileSync(srcFile, join21(docsPublicThemesDir, basename4(srcFile)));
     }
     for (const c of customSources) {
       const targetName = c.origin === "legacy" ? basename4(c.filePath) : `${c.slug}.visor.yaml`;
-      copyFileSync(c.filePath, join20(docsPublicThemesDir, targetName));
+      copyFileSync(c.filePath, join21(docsPublicThemesDir, targetName));
     }
     for (const stale of stalePublicYamls) {
-      unlinkSync2(join20(docsPublicThemesDir, stale));
+      unlinkSync2(join21(docsPublicThemesDir, stale));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -5171,19 +5599,19 @@ function themeSyncCommand(cwd, options) {
 
 // src/commands/theme-batch-apply-flutter.ts
 import {
-  readFileSync as readFileSync21,
+  readFileSync as readFileSync22,
   writeFileSync as writeFileSync13,
   mkdirSync as mkdirSync9,
-  existsSync as existsSync18,
+  existsSync as existsSync19,
   readdirSync as readdirSync7,
   rmSync
 } from "fs";
-import { join as join21, basename as basename5, dirname as dirname10 } from "path";
+import { join as join22, basename as basename5, dirname as dirname11 } from "path";
 import { generateThemeData as generateThemeData6 } from "@loworbitstudio/visor-theme-engine";
 import { flutterAdapter as flutterAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 function scanThemeDir2(dir) {
-  if (!existsSync18(dir)) return [];
-  return readdirSync7(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join21(dir, f)).sort();
+  if (!existsSync19(dir)) return [];
+  return readdirSync7(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join22(dir, f)).sort();
 }
 function slugToCamel(slug2) {
   return slug2.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -5316,9 +5744,9 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join21(repoRoot, "themes");
-  const customThemesDir = join21(repoRoot, "custom-themes");
-  const outputDir = join21(repoRoot, "packages", "visor_themes");
+  const themesDir = join22(repoRoot, "themes");
+  const customThemesDir = join22(repoRoot, "custom-themes");
+  const outputDir = join22(repoRoot, "packages", "visor_themes");
   const stockFiles = scanThemeDir2(themesDir);
   const customFiles = scanThemeDir2(customThemesDir);
   const allFiles = [...stockFiles, ...customFiles];
@@ -5339,7 +5767,7 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   for (const filePath of allFiles) {
     let yamlContent;
     try {
-      yamlContent = readFileSync21(filePath, "utf-8");
+      yamlContent = readFileSync22(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       continue;
@@ -5418,8 +5846,8 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     return;
   }
   const slugs = processed.map((p) => p.slug);
-  const libSrcDir = join21(outputDir, "lib", "src");
-  if (existsSync18(libSrcDir)) {
+  const libSrcDir = join22(outputDir, "lib", "src");
+  if (existsSync19(libSrcDir)) {
     rmSync(libSrcDir, { recursive: true, force: true });
   }
   const packageFiles = {
@@ -5431,16 +5859,16 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   };
   let totalFiles = 0;
   for (const [relPath, content] of Object.entries(packageFiles)) {
-    const absPath = join21(outputDir, relPath);
-    mkdirSync9(dirname10(absPath), { recursive: true });
+    const absPath = join22(outputDir, relPath);
+    mkdirSync9(dirname11(absPath), { recursive: true });
     writeFileSync13(absPath, content, "utf-8");
     totalFiles++;
   }
   for (const { slug: slug2, tokenFiles } of processed) {
-    const themeBaseDir = join21(outputDir, "lib", "src", slug2);
+    const themeBaseDir = join22(outputDir, "lib", "src", slug2);
     for (const [relPath, content] of Object.entries(tokenFiles)) {
-      const absPath = join21(themeBaseDir, relPath);
-      mkdirSync9(dirname10(absPath), { recursive: true });
+      const absPath = join22(themeBaseDir, relPath);
+      mkdirSync9(dirname11(absPath), { recursive: true });
       writeFileSync13(absPath, content, "utf-8");
       totalFiles++;
     }
@@ -5462,8 +5890,8 @@ function themeBatchApplyFlutterCommand(cwd, options) {
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync19, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync22 } from "fs";
-import { resolve as resolve15, basename as basename6, extname as extname4 } from "path";
+import { existsSync as existsSync20, statSync as statSync8, readdirSync as readdirSync8, readFileSync as readFileSync23 } from "fs";
+import { resolve as resolve16, basename as basename6, extname as extname4 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
   const name = basename6(filename, extname4(filename));
@@ -5507,11 +5935,11 @@ function deriveFamilySlug(filename) {
   return parts.join("-").toLowerCase();
 }
 function collectWoff2Files(inputPath) {
-  const resolved = resolve15(inputPath);
-  if (!existsSync19(resolved)) {
+  const resolved = resolve16(inputPath);
+  if (!existsSync20(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
-  const stat = statSync7(resolved);
+  const stat = statSync8(resolved);
   if (stat.isFile()) {
     if (extname4(resolved).toLowerCase() !== ".woff2") {
       throw new Error(
@@ -5521,7 +5949,7 @@ function collectWoff2Files(inputPath) {
     return [resolved];
   }
   if (stat.isDirectory()) {
-    const files = readdirSync8(resolved).filter((f) => extname4(f).toLowerCase() === ".woff2").map((f) => resolve15(resolved, f));
+    const files = readdirSync8(resolved).filter((f) => extname4(f).toLowerCase() === ".woff2").map((f) => resolve16(resolved, f));
     if (files.length === 0) {
       throw new Error(
         `No .woff2 files found in directory: ${resolved}`
@@ -5536,8 +5964,8 @@ function collectWoff2Files(inputPath) {
   throw new Error(`Path is neither a file nor a directory: ${resolved}`);
 }
 function getNonWoff2Fonts(inputPath) {
-  const resolved = resolve15(inputPath);
-  if (!existsSync19(resolved) || !statSync7(resolved).isDirectory()) {
+  const resolved = resolve16(inputPath);
+  if (!existsSync20(resolved) || !statSync8(resolved).isDirectory()) {
     return [];
   }
   return readdirSync8(resolved).filter((f) => {
@@ -5574,7 +6002,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync22(filePath);
+  const body = readFileSync23(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -5590,8 +6018,8 @@ async function fontsAddCommand(inputPath, options) {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
     const familySlug = options.family ?? deriveFamilySlug(basename6(files[0]));
-    const resolved = resolve15(inputPath);
-    const nonWoff2 = statSync7(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
+    const resolved = resolve16(inputPath);
+    const nonWoff2 = statSync8(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
       logger.heading("Visor Font Upload");
       logger.info(`Organization: ${org}`);
@@ -5615,7 +6043,7 @@ async function fontsAddCommand(inputPath, options) {
         logger.info(`Uploading ${filename}...`);
       }
       await uploadFile(client, bucket, key, filePath);
-      const size = statSync7(filePath).size;
+      const size = statSync8(filePath).size;
       results.push({ file: filename, key, size });
       if (!json) {
         logger.success(`Uploaded: ${key} (${formatBytes(size)})`);
@@ -5878,27 +6306,27 @@ function findCssFiles(dir, maxDepth = 3) {
 }
 
 // src/utils/patterns.ts
-import { existsSync as existsSync21, readdirSync as readdirSync10, readFileSync as readFileSync24 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync22, readdirSync as readdirSync10, readFileSync as readFileSync25 } from "fs";
+import { join as join24 } from "path";
 import { parse as parseYAML } from "yaml";
 function loadPatternsFromYaml(repoRoot) {
-  const patternsDir = join23(repoRoot, "patterns");
-  if (!existsSync21(patternsDir)) return [];
+  const patternsDir = join24(repoRoot, "patterns");
+  if (!existsSync22(patternsDir)) return [];
   const files = readdirSync10(patternsDir).filter(
     (f) => f.endsWith(".visor-pattern.yaml")
   );
   return files.map((file) => {
-    const content = readFileSync24(join23(patternsDir, file), "utf-8");
+    const content = readFileSync25(join24(patternsDir, file), "utf-8");
     return parseYAML(content);
   }).filter(Boolean);
 }
 function findRepoRoot2(startDir) {
   let current = startDir;
   while (true) {
-    if (existsSync21(join23(current, "patterns"))) {
+    if (existsSync22(join24(current, "patterns"))) {
       return current;
     }
-    const parent = join23(current, "..");
+    const parent = join24(current, "..");
     if (parent === current) return null;
     current = parent;
   }
@@ -6277,8 +6705,8 @@ Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
 }
 
 // src/commands/migrate-token-substitution.ts
-import { readFileSync as readFileSync25, writeFileSync as writeFileSync14, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync22 } from "fs";
-import { resolve as resolve16, join as join24, relative as relative4 } from "path";
+import { readFileSync as readFileSync26, writeFileSync as writeFileSync14, readdirSync as readdirSync11, statSync as statSync9, existsSync as existsSync23 } from "fs";
+import { resolve as resolve17, join as join25, relative as relative4 } from "path";
 import { parse as parseYaml4 } from "yaml";
 import pc4 from "picocolors";
 var V7_ENTR_SUBSTITUTION_MAP = {
@@ -6301,14 +6729,14 @@ var BUILT_IN_SUBSTITUTION_MAPS = {
 var DEFAULT_THEME_ID = "entr";
 function readMapFromThemeFile(themeId, cwd) {
   const candidates = [
-    join24(cwd, "themes", `${themeId}.visor.yaml`),
-    join24(cwd, "custom-themes", `${themeId}.visor.yaml`),
-    join24(cwd, "packages", "docs", "public", "themes", `${themeId}.visor.yaml`)
+    join25(cwd, "themes", `${themeId}.visor.yaml`),
+    join25(cwd, "custom-themes", `${themeId}.visor.yaml`),
+    join25(cwd, "packages", "docs", "public", "themes", `${themeId}.visor.yaml`)
   ];
   for (const candidate of candidates) {
-    if (existsSync22(candidate)) {
+    if (existsSync23(candidate)) {
       try {
-        const raw = readFileSync25(candidate, "utf-8");
+        const raw = readFileSync26(candidate, "utf-8");
         const parsed = parseYaml4(raw);
         if (parsed?.migrate?.["token-substitution"]) {
           return parsed.migrate["token-substitution"];
@@ -6364,7 +6792,7 @@ function collectCssFiles(dirPath) {
   function walk2(current) {
     const entries = readdirSync11(current, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join24(current, entry.name);
+      const fullPath = join25(current, entry.name);
       if (entry.isDirectory()) {
         if (["node_modules", ".git", ".next", "dist", "build", ".cache"].includes(entry.name)) {
           continue;
@@ -6383,7 +6811,7 @@ function collectCssFiles(dirPath) {
 }
 function runSubstitutionPass(targetPath, map, themeId) {
   let files;
-  const stat = statSync8(targetPath);
+  const stat = statSync9(targetPath);
   if (stat.isFile()) {
     files = [targetPath];
   } else {
@@ -6392,7 +6820,7 @@ function runSubstitutionPass(targetPath, map, themeId) {
   const fileResults = [];
   let totalSubstitutions = 0;
   for (const file of files) {
-    const content = readFileSync25(file, "utf-8");
+    const content = readFileSync26(file, "utf-8");
     const { newContent, substitutions } = applySubstitutionsToContent(content, map);
     if (substitutions.length > 0) {
       fileResults.push({ file, substitutions, originalContent: content, newContent });
@@ -6426,9 +6854,9 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     process.exit(1);
     return;
   }
-  const targetPath = resolve16(cwd, targetArg ?? ".");
+  const targetPath = resolve17(cwd, targetArg ?? ".");
   try {
-    statSync8(targetPath);
+    statSync9(targetPath);
   } catch {
     if (options.json) {
       console.log(JSON.stringify({
@@ -6515,23 +6943,23 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
 }
 
 // src/commands/sandbox/init.ts
-import { existsSync as existsSync25, mkdirSync as mkdirSync12, readFileSync as readFileSync28, rmSync as rmSync2 } from "fs";
-import { isAbsolute as isAbsolute4, join as join27, resolve as resolve18, dirname as dirname12 } from "path";
+import { existsSync as existsSync26, mkdirSync as mkdirSync12, readFileSync as readFileSync29, rmSync as rmSync2 } from "fs";
+import { isAbsolute as isAbsolute5, join as join28, resolve as resolve19, dirname as dirname13 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import * as childProcess3 from "child_process";
 
 // src/commands/sandbox/parse-handoff.ts
-import { readFileSync as readFileSync26, existsSync as existsSync23 } from "fs";
-import { dirname as dirname11, resolve as resolve17, isAbsolute as isAbsolute3 } from "path";
+import { readFileSync as readFileSync27, existsSync as existsSync24 } from "fs";
+import { dirname as dirname12, resolve as resolve18, isAbsolute as isAbsolute4 } from "path";
 function parseHandoff(handoffPath) {
-  const text = readFileSync26(handoffPath, "utf-8");
+  const text = readFileSync27(handoffPath, "utf-8");
   const lines2 = text.split("\n");
   const warnings = [];
   const pattern2 = extractPatternSlug(lines2, warnings);
   const theme2 = extractMetaField(lines2, "Theme");
   const recipePath = extractRecipePath(text, handoffPath, warnings);
   const primitives = extractPrimitives(text, warnings);
-  const { screens, mockShapes } = recipePath && existsSync23(recipePath) ? extractRecipeArtifacts(recipePath, warnings) : { screens: [], mockShapes: [] };
+  const { screens, mockShapes } = recipePath && existsSync24(recipePath) ? extractRecipeArtifacts(recipePath, warnings) : { screens: [], mockShapes: [] };
   return { pattern: pattern2, theme: theme2, recipePath, primitives, screens, mockShapes, warnings };
 }
 function extractPatternSlug(lines2, warnings) {
@@ -6562,8 +6990,8 @@ function extractRecipePath(text, handoffPath, warnings) {
     return void 0;
   }
   const href = m[2].trim();
-  if (isAbsolute3(href)) return href;
-  return resolve17(dirname11(handoffPath), href);
+  if (isAbsolute4(href)) return href;
+  return resolve18(dirname12(handoffPath), href);
 }
 var STATUS_PATTERNS = [
   { re: /NEW\s+gap/i, status: "gap-new" },
@@ -6610,7 +7038,7 @@ function extractPrimitives(text, warnings) {
   return primitives;
 }
 function extractRecipeArtifacts(recipePath, warnings) {
-  const text = readFileSync26(recipePath, "utf-8");
+  const text = readFileSync27(recipePath, "utf-8");
   const screens = extractScreens(text);
   const mockShapes = extractMockFields(text, warnings);
   return { screens, mockShapes };
@@ -6684,8 +7112,8 @@ function tryPort(port) {
 }
 
 // src/commands/sandbox/scaffold.ts
-import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync15, existsSync as existsSync24, readdirSync as readdirSync12 } from "fs";
-import { join as join25 } from "path";
+import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync15, existsSync as existsSync25, readdirSync as readdirSync12 } from "fs";
+import { join as join26 } from "path";
 
 // src/commands/sandbox/templates.ts
 var SANDBOX_PACKAGE_VERSION = "16.2.6";
@@ -7188,7 +7616,7 @@ function writeScaffold(sandboxDir, manifest, port, options = {}) {
   mkdirSync10(sandboxDir, { recursive: true });
   const created = [];
   const writeIfNew = (rel, contents) => {
-    const full = join25(sandboxDir, rel);
+    const full = join26(sandboxDir, rel);
     mkdirSync10(dirOf(full), { recursive: true });
     writeFileSync15(full, contents, "utf-8");
     created.push(rel);
@@ -7216,7 +7644,7 @@ function writeScaffold(sandboxDir, manifest, port, options = {}) {
     }
   }
   writeIfNew("playwright.capture.mjs", captureScriptTemplate());
-  mkdirSync10(join25(sandboxDir, "captures", "approved"), { recursive: true });
+  mkdirSync10(join26(sandboxDir, "captures", "approved"), { recursive: true });
   return { created };
 }
 function dirOf(p) {
@@ -7250,10 +7678,10 @@ function writeSandboxConfig(sandboxDir, manifest, port, options) {
       stripChromeSelectors: options.prototypeImport.stripChromeSelectors
     } : null
   };
-  writeFileSync15(join25(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+  writeFileSync15(join26(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 function sandboxIsEmpty(sandboxDir) {
-  if (!existsSync24(sandboxDir)) return true;
+  if (!existsSync25(sandboxDir)) return true;
   try {
     return readdirSync12(sandboxDir).filter((f) => !f.startsWith(".")).length === 0;
   } catch {
@@ -7262,8 +7690,8 @@ function sandboxIsEmpty(sandboxDir) {
 }
 
 // src/commands/sandbox/html-prototype.ts
-import { mkdirSync as mkdirSync11, readdirSync as readdirSync13, readFileSync as readFileSync27, statSync as statSync9, writeFileSync as writeFileSync16 } from "fs";
-import { join as join26 } from "path";
+import { mkdirSync as mkdirSync11, readdirSync as readdirSync13, readFileSync as readFileSync28, statSync as statSync10, writeFileSync as writeFileSync16 } from "fs";
+import { join as join27 } from "path";
 
 // src/commands/sandbox/strip-chrome.ts
 var DEFAULT_STRIP_SELECTORS = [
@@ -7447,7 +7875,7 @@ function stripDocumentaryChrome(html, selectors) {
 var SCREEN_FILE_PATTERN = /^screen-(\d+)-([^/.]+)\.html$/i;
 function copyHtmlPrototype(sourceDir, sandboxDir, manifest, options = {}) {
   const warnings = [];
-  const destAbs = join26(sandboxDir, "public", "prototype");
+  const destAbs = join27(sandboxDir, "public", "prototype");
   mkdirSync11(destAbs, { recursive: true });
   const stripChromeSelectors = options.stripChromeSelectors ?? [];
   const copiedFiles = copyTreeRelative(sourceDir, destAbs, "", stripChromeSelectors);
@@ -7501,24 +7929,24 @@ function deriveStateCoverageScreen(file, existingNames) {
 }
 function copyTreeRelative(srcDir, destDir, relDir = "", stripChromeSelectors = []) {
   const out = [];
-  const entries = readdirSync13(join26(srcDir, relDir));
+  const entries = readdirSync13(join27(srcDir, relDir));
   for (const name of entries) {
     if (name.startsWith(".")) continue;
-    const srcPath = join26(srcDir, relDir, name);
-    const destPath = join26(destDir, relDir, name);
-    const stat = statSync9(srcPath);
+    const srcPath = join27(srcDir, relDir, name);
+    const destPath = join27(destDir, relDir, name);
+    const stat = statSync10(srcPath);
     if (stat.isDirectory()) {
       mkdirSync11(destPath, { recursive: true });
-      out.push(...copyTreeRelative(srcDir, destDir, join26(relDir, name), stripChromeSelectors));
+      out.push(...copyTreeRelative(srcDir, destDir, join27(relDir, name), stripChromeSelectors));
     } else if (stat.isFile()) {
       if (stripChromeSelectors.length > 0 && name.toLowerCase().endsWith(".html")) {
-        const html = readFileSync27(srcPath, "utf-8");
+        const html = readFileSync28(srcPath, "utf-8");
         const stripped = stripDocumentaryChrome(html, stripChromeSelectors);
         writeFileSync16(destPath, stripped);
       } else {
-        writeFileSync16(destPath, readFileSync27(srcPath));
+        writeFileSync16(destPath, readFileSync28(srcPath));
       }
-      out.push(join26("public", "prototype", relDir, name).replace(/\\/g, "/"));
+      out.push(join27("public", "prototype", relDir, name).replace(/\\/g, "/"));
     }
   }
   return out;
@@ -7570,8 +7998,8 @@ async function runInit(name, cwd, options) {
   if (!name || !/^[a-z0-9][a-z0-9-_]*$/i.test(name)) {
     throw new Error(`Invalid sandbox name '${name}'. Use letters, digits, '-' or '_'.`);
   }
-  const handoffPath = isAbsolute4(options.handoff) ? options.handoff : resolve18(cwd, options.handoff);
-  if (!existsSync25(handoffPath)) {
+  const handoffPath = isAbsolute5(options.handoff) ? options.handoff : resolve19(cwd, options.handoff);
+  if (!existsSync26(handoffPath)) {
     throw new Error(`Handoff manifest not found: ${handoffPath}`);
   }
   const manifest = parseHandoff(handoffPath);
@@ -7580,7 +8008,7 @@ async function runInit(name, cwd, options) {
       `Handoff has no primitives \u2014 refusing to scaffold an empty sandbox. Check the manifest at ${handoffPath}`
     );
   }
-  const sandboxDir = join27(cwd, ".lo", "sandbox", name);
+  const sandboxDir = join28(cwd, ".lo", "sandbox", name);
   if (!sandboxIsEmpty(sandboxDir)) {
     if (!options.overwrite) {
       throw new Error(
@@ -7593,8 +8021,8 @@ async function runInit(name, cwd, options) {
   const port = await findOpenPort();
   let prototypeImport;
   if (options.fromHtmlPrototype) {
-    const prototypeDir = isAbsolute4(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve18(cwd, options.fromHtmlPrototype);
-    if (!existsSync25(prototypeDir)) {
+    const prototypeDir = isAbsolute5(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve19(cwd, options.fromHtmlPrototype);
+    if (!existsSync26(prototypeDir)) {
       throw new Error(`HTML prototype directory not found: ${prototypeDir}`);
     }
     const stripChromeSelectors = resolveStripSelectors(
@@ -7653,22 +8081,22 @@ async function runInit(name, cwd, options) {
 function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile) {
   const candidates = [];
   if (themeFile) {
-    candidates.push(isAbsolute4(themeFile) ? themeFile : resolve18(cwd, themeFile));
+    candidates.push(isAbsolute5(themeFile) ? themeFile : resolve19(cwd, themeFile));
   }
-  candidates.push(isAbsolute4(theme2) ? theme2 : resolve18(cwd, theme2));
+  candidates.push(isAbsolute5(theme2) ? theme2 : resolve19(cwd, theme2));
   const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
   if (privateRoot && privateRoot.length > 0) {
-    candidates.push(join27(privateRoot, "themes", theme2, "theme.visor.yaml"));
+    candidates.push(join28(privateRoot, "themes", theme2, "theme.visor.yaml"));
   }
   candidates.push(
-    join27(cwd, "themes", `${theme2}.visor.yaml`),
-    join27(cwd, "custom-themes", `${theme2}.visor.yaml`)
+    join28(cwd, "themes", `${theme2}.visor.yaml`),
+    join28(cwd, "custom-themes", `${theme2}.visor.yaml`)
   );
-  const yamlPath = candidates.find((p) => existsSync25(p));
+  const yamlPath = candidates.find((p) => existsSync26(p));
   if (!yamlPath) {
     const searched = candidates.join(", ");
     manifest.warnings.push(
-      `Theme '${theme2}' not found (searched: ${searched}) \u2014 sandbox uses placeholder globals.css. Run 'npx visor theme apply <path-to-theme.visor.yaml> --adapter nextjs -o ${join27(sandboxDir, "app", "globals.css")}' manually, or re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH to a directory containing themes/${theme2}/theme.visor.yaml.`
+      `Theme '${theme2}' not found (searched: ${searched}) \u2014 sandbox uses placeholder globals.css. Run 'npx visor theme apply <path-to-theme.visor.yaml> --adapter nextjs -o ${join28(sandboxDir, "app", "globals.css")}' manually, or re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH to a directory containing themes/${theme2}/theme.visor.yaml.`
     );
     if (!json) {
       logger.warn(`Theme '${theme2}' not found \u2014 leaving placeholder globals.css.`);
@@ -7676,12 +8104,12 @@ function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile
         `Re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH=<dir-containing-themes/${theme2}/theme.visor.yaml>.`
       );
       logger.item(
-        `Or apply manually: npx visor theme apply <path> --adapter nextjs -o ${join27(sandboxDir, "app", "globals.css")}`
+        `Or apply manually: npx visor theme apply <path> --adapter nextjs -o ${join28(sandboxDir, "app", "globals.css")}`
       );
     }
     return;
   }
-  const globalsOut = join27(sandboxDir, "app", "globals.css");
+  const globalsOut = join28(sandboxDir, "app", "globals.css");
   try {
     themeApplyCommand(yamlPath, sandboxDir, {
       output: globalsOut,
@@ -7734,12 +8162,12 @@ function loadKnownPrimitives() {
 }
 function readCliVersion() {
   try {
-    const here = dirname12(fileURLToPath3(import.meta.url));
+    const here = dirname13(fileURLToPath3(import.meta.url));
     for (let i = 0; i < 6; i++) {
       const segments = new Array(i).fill("..");
-      const candidate = join27(here, ...segments, "package.json");
+      const candidate = join28(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync28(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync29(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) return pkg2.version;
       } catch {
       }
@@ -7750,14 +8178,14 @@ function readCliVersion() {
 }
 
 // src/commands/sandbox/dev.ts
-import { existsSync as existsSync26, readFileSync as readFileSync29 } from "fs";
-import { join as join28 } from "path";
+import { existsSync as existsSync27, readFileSync as readFileSync30 } from "fs";
+import { join as join29 } from "path";
 import * as childProcess4 from "child_process";
 function sandboxDevCommand(cwd, options) {
   const json = options.json ?? false;
-  const sandboxDir = join28(cwd, ".lo", "sandbox", options.name);
-  const configPath = join28(sandboxDir, "sandbox.json");
-  if (!existsSync26(configPath)) {
+  const sandboxDir = join29(cwd, ".lo", "sandbox", options.name);
+  const configPath = join29(sandboxDir, "sandbox.json");
+  if (!existsSync27(configPath)) {
     fail(
       json,
       `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init ${options.name} --handoff ... --theme ...' first.`
@@ -7766,7 +8194,7 @@ function sandboxDevCommand(cwd, options) {
   }
   let config;
   try {
-    config = JSON.parse(readFileSync29(configPath, "utf-8"));
+    config = JSON.parse(readFileSync30(configPath, "utf-8"));
   } catch (err) {
     fail(json, `Invalid sandbox.json at ${configPath}: ${err.message}`);
     return;
@@ -7824,20 +8252,20 @@ function fail(json, message) {
 // src/commands/sandbox/approve.ts
 import {
   copyFileSync as copyFileSync2,
-  existsSync as existsSync27,
+  existsSync as existsSync28,
   mkdirSync as mkdirSync13,
-  readFileSync as readFileSync30,
+  readFileSync as readFileSync31,
   readdirSync as readdirSync14,
   rmSync as rmSync3,
   writeFileSync as writeFileSync17
 } from "fs";
-import { basename as basename7, join as join29 } from "path";
+import { basename as basename7, join as join30 } from "path";
 import * as childProcess5 from "child_process";
 function sandboxApproveCommand(cwd, options) {
   const json = options.json ?? false;
-  const sandboxDir = join29(cwd, ".lo", "sandbox", options.name);
-  const configPath = join29(sandboxDir, "sandbox.json");
-  if (!existsSync27(configPath)) {
+  const sandboxDir = join30(cwd, ".lo", "sandbox", options.name);
+  const configPath = join30(sandboxDir, "sandbox.json");
+  if (!existsSync28(configPath)) {
     fail2(
       json,
       `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init' first.`
@@ -7851,8 +8279,8 @@ function sandboxApproveCommand(cwd, options) {
   runCapture(sandboxDir, configPath, options.name, json);
 }
 function runCapture(sandboxDir, configPath, sandboxName, json) {
-  const config = JSON.parse(readFileSync30(configPath, "utf-8"));
-  const captureScriptPath = join29(sandboxDir, "playwright.capture.mjs");
+  const config = JSON.parse(readFileSync31(configPath, "utf-8"));
+  const captureScriptPath = join30(sandboxDir, "playwright.capture.mjs");
   writeFileSync17(captureScriptPath, captureScriptTemplate(), "utf-8");
   ensurePlaywrightInstalled(sandboxDir, json);
   const result = childProcess5.spawnSync(
@@ -7874,9 +8302,9 @@ function runCapture(sandboxDir, configPath, sandboxName, json) {
 ${result.stderr}`);
     return;
   }
-  const pendingDir = join29(sandboxDir, "captures", "pending");
-  const diffsDir = join29(sandboxDir, "captures", "diffs");
-  const approvedDir = join29(sandboxDir, "captures", "approved");
+  const pendingDir = join30(sandboxDir, "captures", "pending");
+  const diffsDir = join30(sandboxDir, "captures", "diffs");
+  const approvedDir = join30(sandboxDir, "captures", "approved");
   const pendingFiles = safeListPngs(pendingDir);
   const diffFiles = safeListPngs(diffsDir);
   const hasBaseline = safeListPngs(approvedDir).length > 0;
@@ -7913,9 +8341,9 @@ ${result.stderr}`);
   }
 }
 function runPromotion(sandboxDir, sandboxName, json) {
-  const pendingDir = join29(sandboxDir, "captures", "pending");
-  const approvedDir = join29(sandboxDir, "captures", "approved");
-  const diffsDir = join29(sandboxDir, "captures", "diffs");
+  const pendingDir = join30(sandboxDir, "captures", "pending");
+  const approvedDir = join30(sandboxDir, "captures", "approved");
+  const diffsDir = join30(sandboxDir, "captures", "diffs");
   const pendingFiles = safeListPngs(pendingDir);
   if (pendingFiles.length === 0) {
     fail2(
@@ -7927,7 +8355,7 @@ function runPromotion(sandboxDir, sandboxName, json) {
   mkdirSync13(approvedDir, { recursive: true });
   const promoted = [];
   for (const src of pendingFiles) {
-    const dest = join29(approvedDir, basename7(src));
+    const dest = join30(approvedDir, basename7(src));
     copyFileSync2(src, dest);
     promoted.push(dest);
   }
@@ -7947,8 +8375,8 @@ function runPromotion(sandboxDir, sandboxName, json) {
   }
 }
 function ensurePlaywrightInstalled(sandboxDir, json) {
-  const markerPath = join29(sandboxDir, ".playwright-installed");
-  if (existsSync27(markerPath)) return;
+  const markerPath = join30(sandboxDir, ".playwright-installed");
+  if (existsSync28(markerPath)) return;
   if (!json) logger.info("Installing Playwright Chromium (one-time)...");
   const result = childProcess5.spawnSync(
     "npx",
@@ -7967,8 +8395,8 @@ function ensurePlaywrightInstalled(sandboxDir, json) {
   writeFileSync17(markerPath, (/* @__PURE__ */ new Date()).toISOString(), "utf-8");
 }
 function safeListPngs(dir) {
-  if (!existsSync27(dir)) return [];
-  return readdirSync14(dir).filter((f) => f.endsWith(".png")).map((f) => join29(dir, f));
+  if (!existsSync28(dir)) return [];
+  return readdirSync14(dir).filter((f) => f.endsWith(".png")).map((f) => join30(dir, f));
 }
 function tryParseJson(s) {
   try {
@@ -7989,13 +8417,13 @@ function fail2(json, message) {
 // src/commands/spawn.ts
 import {
   cpSync,
-  existsSync as existsSync29,
-  readFileSync as readFileSync31,
+  existsSync as existsSync30,
+  readFileSync as readFileSync32,
   readdirSync as readdirSync16,
-  rmSync as rmSync4
+  rmSync as rmSync4,
+  statSync as statSync12
 } from "fs";
-import { basename as basename8, isAbsolute as isAbsolute5, join as join31, resolve as resolve19 } from "path";
-import { homedir as homedir3 } from "os";
+import { basename as basename8, dirname as dirname14, isAbsolute as isAbsolute6, join as join32, resolve as resolve20 } from "path";
 import * as childProcess6 from "child_process";
 import { parse as parseYaml5 } from "yaml";
 import { generateThemeData as generateThemeData7 } from "@loworbitstudio/visor-theme-engine";
@@ -8003,8 +8431,8 @@ import { nextjsAdapter as nextjsAdapter3 } from "@loworbitstudio/visor-theme-eng
 import { validate as validate3 } from "@loworbitstudio/visor-theme-engine";
 
 // src/lib/blessed-discovery.ts
-import { existsSync as existsSync28, readdirSync as readdirSync15 } from "fs";
-import { join as join30 } from "path";
+import { existsSync as existsSync29, readdirSync as readdirSync15, statSync as statSync11 } from "fs";
+import { join as join31 } from "path";
 var WALK_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".next",
@@ -8014,11 +8442,15 @@ var WALK_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "coverage",
   ".cache"
 ]);
+var REFERENCE_BUILD_DIRNAME = "reference-build";
+var APPROVED_CAPTURES_SUBPATH = join31("captures", "approved");
+var MISSING_MANIFEST_REASON = `missing ${BLESSED_MANIFEST_FILENAME}`;
 function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
   const builds = [];
+  const incomplete = [];
   const errors = [];
-  if (!existsSync28(blessedDir)) {
-    return { builds, errors };
+  if (!existsSync29(blessedDir)) {
+    return { builds, incomplete, errors };
   }
   walk2(blessedDir, 0);
   builds.sort((a, b) => {
@@ -8027,7 +8459,8 @@ function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
     }
     return a.manifest.pattern.localeCompare(b.manifest.pattern);
   });
-  return { builds, errors };
+  incomplete.sort((a, b) => a.dir.localeCompare(b.dir));
+  return { builds, incomplete, errors };
   function walk2(dir, depth) {
     if (depth > maxDepth) return;
     let entries;
@@ -8048,13 +8481,30 @@ function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
       }
       return;
     }
+    if (isNearMissRoot(dir, entries)) {
+      incomplete.push({ dir, reason: MISSING_MANIFEST_REASON });
+      return;
+    }
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (WALK_EXCLUDE_DIRS.has(entry.name)) continue;
-      walk2(join30(dir, entry.name), depth + 1);
+      walk2(join31(dir, entry.name), depth + 1);
     }
   }
 }
+function isNearMissRoot(dir, entries) {
+  const hasReferenceBuild = entries.some(
+    (entry) => entry.isDirectory() && entry.name === REFERENCE_BUILD_DIRNAME
+  );
+  if (!hasReferenceBuild) return false;
+  const approved = join31(dir, APPROVED_CAPTURES_SUBPATH);
+  try {
+    if (!statSync11(approved).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return !existsSync29(join31(dir, REFERENCE_BUILD_DIRNAME, BLESSED_MANIFEST_FILENAME));
+}
 function resolveBlessedBuild(blessedDir, shape, pattern2) {
   const { builds } = discoverBlessedBuilds(blessedDir);
   const build = builds.find(
@@ -8064,13 +8514,18 @@ function resolveBlessedBuild(blessedDir, shape, pattern2) {
 }
 
 // src/commands/spawn.ts
-var DEFAULT_BLESSED_DIR = join31(
-  homedir3(),
-  "Code",
-  "low-orbit",
-  "low-orbit-playbook",
-  "design-prototypes"
-);
+var BLESSED_ROOT_DIRNAME = "design-prototypes";
+var NO_BLESSED_ROOT_ERROR = `No blessed-build root configured. Pass --blessed-dir <path>, set VISOR_BLESSED_DIR, or run from a checkout that contains a '${BLESSED_ROOT_DIRNAME}/' directory. See docs/blessed-builds.md.`;
+function discoverBlessedRoot(cwd) {
+  let dir = resolve20(cwd);
+  for (; ; ) {
+    const candidate = join32(dir, BLESSED_ROOT_DIRNAME);
+    if (existsSync30(candidate) && statSync12(candidate).isDirectory()) return candidate;
+    const parent = dirname14(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
 var FORK_EXCLUDE = /* @__PURE__ */ new Set([
   "node_modules",
   ".next",
@@ -8099,24 +8554,27 @@ function parseBlessedIdentifier(from) {
   return { shape: parts[0], pattern: parts[1] };
 }
 function resolveBlessedDir(cwd, options) {
-  const raw = options.blessedDir ?? (process.env.VISOR_BLESSED_DIR && process.env.VISOR_BLESSED_DIR.length > 0 ? process.env.VISOR_BLESSED_DIR : void 0) ?? DEFAULT_BLESSED_DIR;
-  return isAbsolute5(raw) ? raw : resolve19(cwd, raw);
+  const explicit = options.blessedDir ?? (process.env.VISOR_BLESSED_DIR && process.env.VISOR_BLESSED_DIR.length > 0 ? process.env.VISOR_BLESSED_DIR : void 0);
+  if (explicit !== void 0) {
+    return isAbsolute6(explicit) ? explicit : resolve20(cwd, explicit);
+  }
+  return discoverBlessedRoot(cwd);
 }
 function resolveThemeFile(theme2, cwd, themeFile) {
   const candidates = [];
   if (themeFile) {
-    candidates.push(isAbsolute5(themeFile) ? themeFile : resolve19(cwd, themeFile));
+    candidates.push(isAbsolute6(themeFile) ? themeFile : resolve20(cwd, themeFile));
   }
-  candidates.push(isAbsolute5(theme2) ? theme2 : resolve19(cwd, theme2));
+  candidates.push(isAbsolute6(theme2) ? theme2 : resolve20(cwd, theme2));
   const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
   if (privateRoot && privateRoot.length > 0) {
-    candidates.push(join31(privateRoot, "themes", theme2, "theme.visor.yaml"));
+    candidates.push(join32(privateRoot, "themes", theme2, "theme.visor.yaml"));
   }
   candidates.push(
-    join31(cwd, "themes", `${theme2}.visor.yaml`),
-    join31(cwd, "custom-themes", `${theme2}.visor.yaml`)
+    join32(cwd, "themes", `${theme2}.visor.yaml`),
+    join32(cwd, "custom-themes", `${theme2}.visor.yaml`)
   );
-  const found = candidates.find((candidate) => existsSync29(candidate));
+  const found = candidates.find((candidate) => existsSync30(candidate));
   if (!found) {
     throw new Error(
       `Theme '${theme2}' not found (searched: ${candidates.join(", ")}). Pass --theme-file <path>, use a direct path, or set VISOR_THEMES_PRIVATE_PATH.`
@@ -8125,7 +8583,7 @@ function resolveThemeFile(theme2, cwd, themeFile) {
   return { path: found, searched: candidates };
 }
 function applyThemeToFork(themeFile, outputDir, manifest) {
-  const yaml = readFileSync31(themeFile, "utf-8");
+  const yaml = readFileSync32(themeFile, "utf-8");
   const data = generateThemeData7(yaml);
   const themeId = data.config.name;
   if (!themeId || themeId.length === 0) {
@@ -8162,6 +8620,7 @@ function runSpawn(cwd, options) {
   if (!options.output) throw new Error("Missing required --output <path>.");
   const { shape, pattern: pattern2 } = parseBlessedIdentifier(options.from);
   const blessedDir = resolveBlessedDir(cwd, options);
+  if (blessedDir === void 0) throw new Error(NO_BLESSED_ROOT_ERROR);
   const { build, available } = resolveBlessedBuild(blessedDir, shape, pattern2);
   if (!build) {
     const list = available.length > 0 ? available.map((b) => `  - blessed:${b.manifest.shape}:${b.manifest.pattern}`).join("\n") : "  (none found)";
@@ -8171,8 +8630,8 @@ Available builds:
 ${list}`
     );
   }
-  const outputDir = isAbsolute5(options.output) ? options.output : resolve19(cwd, options.output);
-  if (existsSync29(outputDir) && readdirSync16(outputDir).length > 0) {
+  const outputDir = isAbsolute6(options.output) ? options.output : resolve20(cwd, options.output);
+  if (existsSync30(outputDir) && readdirSync16(outputDir).length > 0) {
     throw new Error(`Output directory already exists and is not empty: ${outputDir}`);
   }
   const { path: themeFile } = resolveThemeFile(options.theme, cwd, options.themeFile);
@@ -8185,7 +8644,7 @@ ${list}`
   try {
     applyThemeToFork(themeFile, outputDir, build.manifest);
     if (options.validate) {
-      const parsed = parseYaml5(readFileSync31(themeFile, "utf-8"));
+      const parsed = parseYaml5(readFileSync32(themeFile, "utf-8"));
       const result = validate3(parsed);
       if (!result.valid) {
         const messages = result.errors.map((e) => e.message).join("; ");
@@ -8218,7 +8677,8 @@ ${list}`
 }
 function listBlessed(cwd, options) {
   const blessedDir = resolveBlessedDir(cwd, options);
-  const { builds, errors } = discoverBlessedBuilds(blessedDir);
+  if (blessedDir === void 0) throw new Error(NO_BLESSED_ROOT_ERROR);
+  const { builds, incomplete, errors } = discoverBlessedBuilds(blessedDir);
   if (options.json) {
     console.log(
       JSON.stringify({
@@ -8233,6 +8693,7 @@ function listBlessed(cwd, options) {
           three_gates_status: b.manifest.three_gates_status,
           dir: b.dir
         })),
+        incomplete,
         errors
       })
     );
@@ -8246,6 +8707,14 @@ function listBlessed(cwd, options) {
     logger.success(`blessed:${b.manifest.shape}:${b.manifest.pattern}`);
     logger.item(`base theme: ${b.manifest.base_theme}  \xB7  requires visor ${b.manifest.requires_visor}  \xB7  gates: ${b.manifest.three_gates_status}`);
   }
+  if (incomplete.length > 0) {
+    logger.blank();
+    logger.heading(`Near-miss builds (not spawnable) \u2014 ${incomplete.length}`);
+    for (const i of incomplete) {
+      logger.warn(i.dir);
+      logger.item(i.reason);
+    }
+  }
   for (const e of errors) {
     logger.warn(`Skipped ${e.dir}: ${e.error}`);
   }
@@ -8287,8 +8756,8 @@ function spawnCommand(cwd, options) {
 }
 
 // src/commands/render.ts
-import { existsSync as existsSync30, mkdirSync as mkdirSync14, readFileSync as readFileSync32 } from "fs";
-import { dirname as dirname13, isAbsolute as isAbsolute6, resolve as resolve20 } from "path";
+import { existsSync as existsSync31, mkdirSync as mkdirSync14, readFileSync as readFileSync33 } from "fs";
+import { dirname as dirname15, isAbsolute as isAbsolute7, resolve as resolve21 } from "path";
 var FIXTURES = {
   "stat-card": {
     default: {
@@ -8440,28 +8909,28 @@ function pascalCase(kebab) {
 }
 function firstExisting(candidates) {
   for (const c of candidates) {
-    if (existsSync30(c)) return c;
+    if (existsSync31(c)) return c;
   }
   return null;
 }
 function resolveComponentFile(cwd, name) {
   return firstExisting([
-    resolve20(cwd, "components", "ui", name, `${name}.tsx`),
-    resolve20(cwd, "components", "devtools", name, `${name}.tsx`),
-    resolve20(cwd, "components", "ui", name, "index.tsx")
+    resolve21(cwd, "components", "ui", name, `${name}.tsx`),
+    resolve21(cwd, "components", "devtools", name, `${name}.tsx`),
+    resolve21(cwd, "components", "ui", name, "index.tsx")
   ]);
 }
 function resolveThemeCssFile(cwd, slug2) {
   return firstExisting([
-    resolve20(cwd, "packages", "docs", "app", `${slug2}-theme.css`),
-    resolve20(cwd, "app", `${slug2}-theme.css`),
-    resolve20(cwd, `${slug2}-theme.css`)
+    resolve21(cwd, "packages", "docs", "app", `${slug2}-theme.css`),
+    resolve21(cwd, "app", `${slug2}-theme.css`),
+    resolve21(cwd, `${slug2}-theme.css`)
   ]);
 }
 function resolveTokensCssFile(cwd) {
   return firstExisting([
-    resolve20(cwd, "packages", "tokens", "dist", "tokens.css"),
-    resolve20(cwd, "node_modules", "@loworbitstudio", "visor-core", "dist", "tokens.css")
+    resolve21(cwd, "packages", "tokens", "dist", "tokens.css"),
+    resolve21(cwd, "node_modules", "@loworbitstudio", "visor-core", "dist", "tokens.css")
   ]);
 }
 async function loadOptional(moduleName) {
@@ -8640,8 +9109,8 @@ async function renderCommand(component, cwd, options) {
   }
   const themeClass = `${options.theme}-theme`;
   const html = buildHtml({
-    tokensCss: readFileSync32(tokensCssFile, "utf-8"),
-    themeCss: readFileSync32(themeCssFile, "utf-8"),
+    tokensCss: readFileSync33(tokensCssFile, "utf-8"),
+    themeCss: readFileSync33(themeCssFile, "utf-8"),
     componentCss,
     bundleJs,
     themeClass,
@@ -8650,7 +9119,7 @@ async function renderCommand(component, cwd, options) {
   const width = Number(options.width ?? 720);
   const height = Number(options.height ?? 640);
   const outPath = resolveOutPath(cwd, options.out, component, options.theme, mode, state);
-  mkdirSync14(dirname13(outPath), { recursive: true });
+  mkdirSync14(dirname15(outPath), { recursive: true });
   const browser = await playwright.chromium.launch();
   let probe;
   try {
@@ -8706,7 +9175,7 @@ async function renderCommand(component, cwd, options) {
   } finally {
     await browser.close();
   }
-  const fileSize = existsSync30(outPath) ? statBytes(outPath) : 0;
+  const fileSize = existsSync31(outPath) ? statBytes(outPath) : 0;
   if (json) {
     console.log(
       JSON.stringify(
@@ -8742,14 +9211,14 @@ async function renderCommand(component, cwd, options) {
 }
 function resolveOutPath(cwd, out, component, theme2, mode, state) {
   if (out) {
-    return isAbsolute6(out) ? out : resolve20(cwd, out);
+    return isAbsolute7(out) ? out : resolve21(cwd, out);
   }
   const suffix = state === "default" ? "" : `__${state}`;
-  return resolve20(cwd, ".visor", "renders", `${component}__${theme2}__${mode}${suffix}.png`);
+  return resolve21(cwd, ".visor", "renders", `${component}__${theme2}__${mode}${suffix}.png`);
 }
 function statBytes(path2) {
   try {
-    return readFileSync32(path2).length;
+    return readFileSync33(path2).length;
   } catch {
     return 0;
   }
@@ -8762,9 +9231,9 @@ function formatBytes2(bytes) {
 }
 
 // src/index.ts
-var __dirname2 = dirname14(fileURLToPath4(import.meta.url));
+var __dirname2 = dirname16(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync33(join33(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync34(join34(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);
@@ -8959,7 +9428,7 @@ sandbox.command("approve").description(
 );
 program.command("spawn").description(
   "Fork a Playbook blessed reference build with atomic theme re-skinning \u2014 one command replaces cp -R + npm install + theme apply"
-).option("--from <identifier>", "blessed build to spawn: blessed:{shape}:{pattern}").option("--theme <id>", "theme id (or path to a .visor.yaml) to re-skin the fork with").option("--theme-file <path>", "explicit path to a theme.visor.yaml \u2014 bypasses --theme name resolution").option("--output <path>", "destination directory for the forked project").option("--blessed-dir <path>", "override the blessed-build root (default: VISOR_BLESSED_DIR or ~/Code/low-orbit/low-orbit-playbook/design-prototypes)").option("--install", "run npm install in the forked project (default: skip)").option("--validate", "validate the applied theme after forking (default: skip)").option("--list-blessed", "list all discoverable blessed builds and exit").option("--json", "output structured JSON (for AI agents)").action((options) => {
+).option("--from <identifier>", "blessed build to spawn: blessed:{shape}:{pattern}").option("--theme <id>", "theme id (or path to a .visor.yaml) to re-skin the fork with").option("--theme-file <path>", "explicit path to a theme.visor.yaml \u2014 bypasses --theme name resolution").option("--output <path>", "destination directory for the forked project").option("--blessed-dir <path>", "override the blessed-build root (default: VISOR_BLESSED_DIR, else the nearest design-prototypes/ directory found by walking up from the cwd)").option("--install", "run npm install in the forked project (default: skip)").option("--validate", "validate the applied theme after forking (default: skip)").option("--list-blessed", "list all discoverable blessed builds and exit").option("--json", "output structured JSON (for AI agents)").action((options) => {
   spawnCommand(process.cwd(), options);
 });
 program.command("render").description(