@loworbitstudio/visor 0.6.0 → 0.9.0

package/dist/index.js

@@ -5,6 +5,8 @@ import { Command as Command2 } from "commander";
 
 // src/commands/check.ts
 import { Command } from "commander";
+import { statSync as statSync3 } from "fs";
+import { resolve as resolve3, dirname as dirname2 } from "path";
 
 // src/registry/resolve.ts
 import { readFileSync } from "fs";
@@ -310,7 +312,7 @@ function collectJsxFindings(source, filePath, parse) {
     }
     const mapping = NATIVE_TO_VISOR[tagName];
     if (!mapping) return;
-    const finding = {
+    const finding2 = {
       file: filePath,
       line,
       column,
@@ -318,8 +320,8 @@ function collectJsxFindings(source, filePath, parse) {
       suggestedPrimitive: mapping.displayName,
       installCmd: `npx visor add ${mapping.visorName}`
     };
-    if (mapping.notes) finding.rationale = mapping.notes;
-    findings.push(finding);
+    if (mapping.notes) finding2.rationale = mapping.notes;
+    findings.push(finding2);
   });
   return findings;
 }
@@ -377,6 +379,491 @@ 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 } from "path";
+function loadVisorRc(dir) {
+  const rcPath = join3(dir, ".visorrc.json");
+  if (!existsSync(rcPath)) return {};
+  try {
+    const raw = readFileSync3(rcPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+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);
+  try {
+    const s = statSync2(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);
+          if (es.isDirectory()) recurse2(full);
+          else if (ALL_EXTS.has(extname2(full))) files.push(full);
+        }
+      };
+      var recurse = recurse2;
+      const files = [];
+      recurse2(abs);
+      return files;
+    }
+    if (ALL_EXTS.has(extname2(abs))) return [abs];
+  } catch {
+  }
+  return [];
+}
+function lines(source) {
+  return source.split("\n");
+}
+function finding(file, line, rule, severity, message, fix) {
+  return { file, line, rule, severity, message, ...fix ? { fix } : {} };
+}
+var TIER1_PREFIXES = [
+  "--primitive-",
+  "--raw-",
+  "--base-color-",
+  "--palette-"
+];
+function ruleTier1TokenDirectUsage(source, filePath) {
+  const found = [];
+  const ext = extname2(filePath);
+  if (STYLE_EXTS.has(ext)) return found;
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    for (const prefix of TIER1_PREFIXES) {
+      if (l.includes(prefix)) {
+        found.push(finding(
+          filePath,
+          i + 1,
+          "tier-1-token-direct-usage",
+          "error",
+          `Direct use of Tier-1 primitive token "${prefix}..." detected. Use a Tier-2 semantic token instead.`,
+          "Replace with the equivalent semantic token from the Borealis token registry."
+        ));
+        break;
+      }
+    }
+  }
+  return found;
+}
+function ruleHardcodedHex(source, filePath) {
+  const found = [];
+  const HEX_RE = /#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6,8})\b/g;
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (l.trim().startsWith("//") || l.trim().startsWith("*") || l.trim().startsWith("/*")) continue;
+    if (basename(filePath).startsWith(".")) continue;
+    let m;
+    HEX_RE.lastIndex = 0;
+    while ((m = HEX_RE.exec(l)) !== null) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "hardcoded-hex",
+        "error",
+        `Hardcoded hex color "${m[0]}" bypasses the Borealis token system.`,
+        "Replace with the appropriate semantic token: var(--color-surface), var(--color-text-primary), etc."
+      ));
+    }
+  }
+  return found;
+}
+var PX_WHITELIST = /* @__PURE__ */ new Set(["0px", "1px", "2px", "3px"]);
+function ruleHardcodedPx(source, filePath) {
+  const found = [];
+  const PX_RE = /\b(\d+(?:\.\d+)?)px\b/g;
+  const src = lines(source);
+  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;
+    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(
+        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."
+      ));
+    }
+  }
+  return found;
+}
+function ruleMissingDarkModeBlock(source, filePath) {
+  const ext = extname2(filePath);
+  if (!STYLE_EXTS.has(ext)) return [];
+  if (source.trim().length < 20) return [];
+  const hasDarkMediaQuery = /@media\s*\(\s*prefers-color-scheme\s*:\s*dark\s*\)/.test(source);
+  const hasDarkAttribute = /\[data-theme\s*=\s*["']?dark["']?\]/.test(source);
+  const hasDarkClass = /\.dark\b/.test(source);
+  if (!hasDarkMediaQuery && !hasDarkAttribute && !hasDarkClass) {
+    return [finding(
+      filePath,
+      1,
+      "missing-dark-mode-block",
+      "error",
+      "CSS file has no dark mode block. Borealis requires dark + light support from day one.",
+      'Add @media (prefers-color-scheme: dark) { ... } or [data-theme="dark"] { ... } with dark-mode token overrides.'
+    )];
+  }
+  return [];
+}
+function ruleMissingHoverTransition(source, filePath) {
+  const ext = extname2(filePath);
+  if (!STYLE_EXTS.has(ext)) return [];
+  const hasHover = /:hover/.test(source);
+  if (!hasHover) return [];
+  const hasTransition = /\btransition\b/.test(source);
+  if (!hasTransition) {
+    const hoverLine = source.split("\n").findIndex((l) => /:hover/.test(l));
+    return [finding(
+      filePath,
+      hoverLine + 1,
+      "missing-hover-transition",
+      "error",
+      ":hover selector found but no transition property in this file. Borealis requires CSS transitions for hover states.",
+      "Add a transition property to the element's base styles, e.g. transition: color 150ms ease, background 150ms ease."
+    )];
+  }
+  return [];
+}
+function ruleDivAsInput(source, filePath) {
+  const ext = extname2(filePath);
+  if (!CODE_EXTS.has(ext)) return [];
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (/<div\b[^>]*onClick/.test(l) && !/role=|type=/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "div-as-input",
+        "error",
+        "<div onClick> used without role= \u2014 this is a div masquerading as an interactive element.",
+        'Use a <button> element or add role="button" and tabIndex={0} with keyboard handlers.'
+      ));
+    }
+    if (/<div\b[^>]*onChange/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "div-as-input",
+        "error",
+        "<div onChange> detected. Real form elements only \u2014 no div-as-input.",
+        "Use <input>, <select>, or <textarea> with appropriate Visor wrapper components."
+      ));
+    }
+  }
+  return found;
+}
+function ruleSetStateHover(source, filePath) {
+  const ext = extname2(filePath);
+  if (!CODE_EXTS.has(ext)) return [];
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (/onMouseEnter|onMouseLeave/.test(l) && /set[A-Z]/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "setstate-hover",
+        "error",
+        "onMouseEnter/onMouseLeave used to manage hover state via setState. Use CSS :hover instead.",
+        "Remove the mouse event handlers and hover state variable. Apply hover styles via CSS :hover."
+      ));
+    }
+    if (/\buse[Ss]tate\b/.test(l) && /[Hh]overed|hover[Ss]tate|isHover/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "setstate-hover",
+        "error",
+        "useState used to track hover state. CSS :hover is zero-cost and more correct.",
+        "Delete this state variable and replace with CSS :hover selector."
+      ));
+    }
+  }
+  return found;
+}
+function ruleMissingAriaPressed(source, filePath) {
+  const ext = extname2(filePath);
+  if (!CODE_EXTS.has(ext)) return [];
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (/<button\b[^>]*(isActive|isOpen|isSelected|isToggled|active=|selected=|toggled=)/.test(l) && !/aria-pressed/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "missing-aria-pressed",
+        "error",
+        "Toggle button appears to be missing aria-pressed. Toggleable buttons must expose their state to assistive technology.",
+        "Add aria-pressed={isActive} (or equivalent) to the button element."
+      ));
+    }
+  }
+  return found;
+}
+var BANNED_FONT_LIST = ["Inter", "Roboto", "Arial", "system-ui", "'Arial'", '"Arial"', "'Roboto'", '"Roboto"', "'Inter'", '"Inter"'];
+function ruleBannedFonts(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (l.trim().startsWith("//") || l.trim().startsWith("*")) continue;
+    for (const font of BANNED_FONT_LIST) {
+      if (l.includes(font)) {
+        found.push(finding(
+          filePath,
+          i + 1,
+          "banned-fonts",
+          "warn",
+          `Banned font "${font}" detected. Borealis projects use Satoshi (or the project's designated typeface).`,
+          "Remove this font reference and use the Borealis font stack via var(--font-sans)."
+        ));
+        break;
+      }
+    }
+  }
+  return found;
+}
+function rulePurpleGradientOnWhite(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  const PURPLE_RE = /gradient.*?(?:purple|violet|#[89abcde][0-9a-f]|#[6-9][0-9a-f]{5})/i;
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (PURPLE_RE.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "purple-gradient-on-white",
+        "warn",
+        "Purple gradient detected \u2014 this is a generic SaaS visual cliche.",
+        "Replace with a gradient using your project's actual brand tokens."
+      ));
+    }
+  }
+  return found;
+}
+function rulePureBlackUntinted(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (l.trim().startsWith("//") || l.trim().startsWith("*")) continue;
+    if (/#000000\b|#000\b|rgb\(\s*0\s*,\s*0\s*,\s*0\s*\)/.test(l) || /:\s*black\b/.test(l) || /color:\s*["']?black["']?/.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "pure-black-untinted",
+        "warn",
+        "Pure black (#000) detected. Use a near-black tinted token for softer, more intentional contrast.",
+        "Replace with var(--color-text-primary) or the project's near-black token."
+      ));
+    }
+  }
+  return found;
+}
+function ruleBounceEasing(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  const BOUNCE_RE = /cubic-bezier\s*\([^)]*(?:1\.[1-9]|[-]0\.\d+)[^)]*\)/;
+  const KEYWORD_RE = /\bease-in-back\b|\bease-out-back\b|\bease-in-out-back\b|\bbounce\b/;
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (BOUNCE_RE.test(l) || KEYWORD_RE.test(l)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "bounce-easing",
+        "warn",
+        "Bounce/overshoot easing detected. Bouncy transitions feel playful/cheap in most UI contexts.",
+        "Use ease, ease-out, or a subtle cubic-bezier like cubic-bezier(0.4, 0, 0.2, 1)."
+      ));
+    }
+  }
+  return found;
+}
+function ruleSub44pxTouchTarget(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  const SMALL_RE = /(?:width|height|min-width|min-height)\s*:\s*(?:[1-9]|[1-3][0-9]|4[0-3])px\b/;
+  const INTERACTIVE_SELECTOR_RE = /button|btn|icon|touch|tap/i;
+  let currentSelector = "";
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (l.trim().startsWith("//") || l.trim().startsWith("*")) continue;
+    if (/\{/.test(l) && !l.trim().startsWith("@")) {
+      currentSelector = l;
+    }
+    const interactiveContext = INTERACTIVE_SELECTOR_RE.test(l) || INTERACTIVE_SELECTOR_RE.test(currentSelector);
+    if (SMALL_RE.test(l) && interactiveContext) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "sub-44px-touch-target",
+        "warn",
+        "Potential sub-44px touch target detected on an interactive element.",
+        "Ensure all interactive elements have a minimum 44x44px touch target (WCAG 2.5.5)."
+      ));
+    }
+  }
+  return found;
+}
+function ruleLineLengthOver75ch(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  const CH_RE = /max-width\s*:\s*(\d+)ch/;
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    const m = CH_RE.exec(l);
+    if (m && parseInt(m[1], 10) > 75) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "line-length-over-75ch",
+        "warn",
+        `Text container max-width of ${m[1]}ch exceeds the 75ch readability limit.`,
+        "Cap text container max-width at 65-75ch for optimal reading comfort."
+      ));
+    }
+  }
+  return found;
+}
+function ruleGradientText(source, filePath) {
+  const found = [];
+  const src = lines(source);
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (/background-clip\s*:\s*text/.test(l) && /(?:transparent|-webkit-text-fill-color)/.test(source)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "gradient-text",
+        "warn",
+        "Gradient text (background-clip: text) detected. Often illegible at small sizes.",
+        "Use a solid semantic text color token. Reserve gradient text for display/hero headings only."
+      ));
+    }
+    if (/-webkit-text-fill-color\s*:\s*transparent/.test(l) && /gradient/.test(source)) {
+      found.push(finding(
+        filePath,
+        i + 1,
+        "gradient-text",
+        "warn",
+        "Gradient text via -webkit-text-fill-color: transparent detected.",
+        "Use a solid semantic text color token. Reserve gradient text for display/hero headings only."
+      ));
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return found.filter((f) => {
+    if (seen.has(f.line)) return false;
+    seen.add(f.line);
+    return true;
+  });
+}
+function ruleExcessiveCardNesting(source, filePath) {
+  const ext = extname2(filePath);
+  if (!CODE_EXTS.has(ext)) return [];
+  const found = [];
+  const src = lines(source);
+  let depth = 0;
+  const CARD_OPEN_RE = /<(?:Card|Panel|Box|Surface|Tile|Widget)\b/;
+  const CARD_CLOSE_RE = /<\/(?:Card|Panel|Box|Surface|Tile|Widget)>/;
+  for (let i = 0; i < src.length; i++) {
+    const l = src[i];
+    if (CARD_OPEN_RE.test(l)) {
+      depth++;
+      if (depth >= 3) {
+        found.push(finding(
+          filePath,
+          i + 1,
+          "excessive-card-nesting",
+          "warn",
+          `Card/Panel nested ${depth} levels deep. Deep nesting creates visual noise and unclear hierarchy.`,
+          "Flatten the layout. Use spacing, dividers, or type scale to create hierarchy instead of nested containers."
+        ));
+      }
+    }
+    if (CARD_CLOSE_RE.test(l)) depth = Math.max(0, depth - 1);
+  }
+  return found;
+}
+var RULES = [
+  // Errors — Borealis non-negotiables
+  { name: "tier-1-token-direct-usage", severity: "error", fn: ruleTier1TokenDirectUsage },
+  { name: "hardcoded-hex", severity: "error", fn: ruleHardcodedHex },
+  { name: "hardcoded-px", severity: "error", fn: ruleHardcodedPx },
+  { name: "missing-dark-mode-block", severity: "error", fn: ruleMissingDarkModeBlock },
+  { name: "missing-hover-transition", severity: "error", fn: ruleMissingHoverTransition },
+  { name: "div-as-input", severity: "error", fn: ruleDivAsInput },
+  { name: "setstate-hover", severity: "error", fn: ruleSetStateHover },
+  { name: "missing-aria-pressed", severity: "error", fn: ruleMissingAriaPressed },
+  // Warns — general anti-patterns
+  { name: "banned-fonts", severity: "warn", fn: ruleBannedFonts },
+  { name: "purple-gradient-on-white", severity: "warn", fn: rulePurpleGradientOnWhite },
+  { name: "pure-black-untinted", severity: "warn", fn: rulePureBlackUntinted },
+  { name: "bounce-easing", severity: "warn", fn: ruleBounceEasing },
+  { name: "sub-44px-touch-target", severity: "warn", fn: ruleSub44pxTouchTarget },
+  { name: "line-length-over-75ch", severity: "warn", fn: ruleLineLengthOver75ch },
+  { name: "gradient-text", severity: "warn", fn: ruleGradientText },
+  { name: "excessive-card-nesting", severity: "warn", fn: ruleExcessiveCardNesting }
+];
+function scanDesign(pathArg, options = {}) {
+  const files = collectFiles2(pathArg);
+  const { disabledRules = [], errorsOnly = false } = options;
+  const activeRules = RULES.filter((r) => {
+    if (disabledRules.includes(r.name)) return false;
+    if (errorsOnly && r.severity !== "error") return false;
+    return true;
+  });
+  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);
+      }
+    }
+  }
+  return {
+    errors,
+    warnings,
+    summary: {
+      errorCount: errors.length,
+      warningCount: warnings.length,
+      filesScanned: files.length
+    }
+  };
+}
+
 // src/utils/logger.ts
 import pc from "picocolors";
 var logger = {
@@ -404,6 +891,7 @@ var logger = {
 };
 
 // src/commands/check.ts
+import pc2 from "picocolors";
 var TYPE_FILTER = {
   ui: "component",
   blocks: "block",
@@ -534,6 +1022,58 @@ async function checkDiffCommand(pathArg, options) {
   logger.blank();
   if (options.failOnHits) process.exit(1);
 }
+function checkDesignCommand(pathArg, options) {
+  const absPath = resolve3(pathArg);
+  const rcDir = statSync3(absPath).isDirectory() ? absPath : dirname2(absPath);
+  const rc = loadVisorRc(rcDir);
+  const result = scanDesign(absPath, {
+    disabledRules: rc.disabledRules ?? [],
+    errorsOnly: options.errorsOnly ?? 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);
+    return;
+  }
+  const { errors, warnings, summary } = result;
+  if (summary.errorCount === 0 && summary.warningCount === 0) {
+    logger.success(`No design anti-patterns found \u2014 ${summary.filesScanned} file(s) scanned.`);
+    process.exit(0);
+    return;
+  }
+  logger.blank();
+  logger.heading(`visor check design \u2014 ${summary.filesScanned} file(s) scanned`);
+  logger.blank();
+  const byFile = /* @__PURE__ */ new Map();
+  const allFindings = [...errors, ...warnings];
+  for (const f of allFindings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+  for (const [file, fileFindings] of byFile) {
+    logger.heading(`  ${file}`);
+    for (const f of fileFindings) {
+      const loc = pc2.dim(`${f.line}:`);
+      const badge = f.severity === "error" ? pc2.red("error") : pc2.yellow("warn ");
+      const ruleName = pc2.dim(`[${f.rule}]`);
+      console.log(`    ${loc} ${badge}  ${f.message}  ${ruleName}`);
+      if (f.fix) {
+        console.log(`           ${pc2.dim("fix:")} ${pc2.cyan(f.fix)}`);
+      }
+    }
+    logger.blank();
+  }
+  logger.blank();
+  if (summary.errorCount > 0) {
+    logger.error(`${summary.errorCount} error(s), ${summary.warningCount} warning(s)`);
+  } else {
+    logger.warn(`${summary.warningCount} warning(s) (0 errors)`);
+  }
+  logger.blank();
+  if (!options.noFail && summary.errorCount > 0) process.exit(1);
+}
 function checkCommand() {
   const check = new Command("check").description("Check Visor catalog \u2014 list items, test existence, scan JSX for native HTML");
   check.command("list").description("List all catalog items (components, blocks, hooks, patterns)").option("--type <type>", "filter by type: ui, blocks, hooks, patterns, all (default: all)").option("--json", "output structured JSON (for AI agents)").action((options) => {
@@ -545,18 +1085,21 @@ 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) => {
+    checkDesignCommand(pathArg, options);
+  });
   return check;
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync3, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync5 } from "fs";
-import { join as join5, dirname as dirname2 } from "path";
+import { existsSync as existsSync4, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync6 } from "fs";
+import { join as join6, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import * as childProcess from "child_process";
 
 // src/config/config.ts
-import { readFileSync as readFileSync3, writeFileSync, existsSync } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
@@ -573,19 +1116,19 @@ var CONFIG_FILE = "visor.json";
 
 // src/config/config.ts
 function getConfigPath(cwd) {
-  return join3(cwd, CONFIG_FILE);
+  return join4(cwd, CONFIG_FILE);
 }
 function configExists(cwd) {
-  return existsSync(getConfigPath(cwd));
+  return existsSync2(getConfigPath(cwd));
 }
 function loadConfig(cwd) {
   const configPath = getConfigPath(cwd);
-  if (!existsSync(configPath)) {
+  if (!existsSync2(configPath)) {
     throw new Error(
       `No ${CONFIG_FILE} found. Run "visor init" first.`
     );
   }
-  const raw = readFileSync3(configPath, "utf-8");
+  const raw = readFileSync4(configPath, "utf-8");
   const parsed = JSON.parse(raw);
   const knownKeys = /* @__PURE__ */ new Set(["paths"]);
   for (const key of Object.keys(parsed)) {
@@ -622,12 +1165,12 @@ function writeConfig(cwd, config) {
 
 // src/utils/packages.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join5 } from "path";
 function readPackageJson(cwd) {
-  const pkgPath = join4(cwd, "package.json");
-  if (!existsSync2(pkgPath)) return null;
-  return JSON.parse(readFileSync4(pkgPath, "utf-8"));
+  const pkgPath = join5(cwd, "package.json");
+  if (!existsSync3(pkgPath)) return null;
+  return JSON.parse(readFileSync5(pkgPath, "utf-8"));
 }
 function isPackageInstalled(packageName, cwd) {
   const pkg = readPackageJson(cwd);
@@ -704,7 +1247,7 @@ function initCommand(cwd, options) {
     emitError(json, `Unknown template: ${options.template}. Available templates: nextjs`);
     process.exit(1);
   }
-  if (options?.template === "nextjs" && existsSync3(join5(cwd, "package.json"))) {
+  if (options?.template === "nextjs" && existsSync4(join6(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"
@@ -787,8 +1330,8 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   }
   runCreateNextApp(cwd, json);
   runInstallVisorDeps(cwd, json);
-  const yamlPath = join5(cwd, ".visor.yaml");
-  if (existsSync3(yamlPath)) {
+  const yamlPath = join6(cwd, ".visor.yaml");
+  if (existsSync4(yamlPath)) {
     filesSkipped.push(".visor.yaml");
     if (!json) {
       logger.warn(".visor.yaml already exists. Skipping.");
@@ -806,10 +1349,10 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
     tokens: data.tokens,
     config: data.config
   });
-  const globalsPath = join5(cwd, "app", "globals.css");
-  const globalsDir = dirname2(globalsPath);
+  const globalsPath = join6(cwd, "app", "globals.css");
+  const globalsDir = dirname3(globalsPath);
   mkdirSync(globalsDir, { recursive: true });
-  if (existsSync3(globalsPath)) {
+  if (existsSync4(globalsPath)) {
     writeFileSync2(globalsPath, css, "utf-8");
     filesCreated.push("app/globals.css");
   } else {
@@ -819,15 +1362,15 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   if (!json) {
     logger.success("Created app/globals.css with theme tokens");
   }
-  const layoutPath = join5(cwd, "app", "layout.tsx");
+  const layoutPath = join6(cwd, "app", "layout.tsx");
   writeFileSync2(layoutPath, generateNextjsLayout(), "utf-8");
   filesCreated.push("app/layout.tsx");
   if (!json) {
     logger.success("Wired app/layout.tsx with FOWT prevention and theme tokens");
   }
-  const stampDir = join5(cwd, ".lo");
-  const stampPath = join5(stampDir, "borealis.json");
-  if (existsSync3(stampPath)) {
+  const stampDir = join6(cwd, ".lo");
+  const stampPath = join6(stampDir, "borealis.json");
+  if (existsSync4(stampPath)) {
     filesSkipped.push(".lo/borealis.json");
     if (!json) {
       logger.warn(".lo/borealis.json already exists. Skipping.");
@@ -891,12 +1434,12 @@ function assertSpawnSuccess(result, label) {
 }
 function readVisorCliVersion() {
   try {
-    const here = dirname2(fileURLToPath2(import.meta.url));
+    const here = dirname3(fileURLToPath2(import.meta.url));
     for (let i = 0; i < 5; i++) {
       const segments = new Array(i).fill("..");
-      const candidate = join5(here, ...segments, "package.json");
+      const candidate = join6(here, ...segments, "package.json");
       try {
-        const pkg = JSON.parse(readFileSync5(candidate, "utf-8"));
+        const pkg = JSON.parse(readFileSync6(candidate, "utf-8"));
         if (pkg.name === "@loworbitstudio/visor" && pkg.version) {
           return pkg.version;
         }
@@ -911,52 +1454,52 @@ function readVisorCliVersion() {
 // src/utils/fs.ts
 import {
   writeFileSync as writeFileSync3,
-  readFileSync as readFileSync6,
-  existsSync as existsSync4,
+  readFileSync as readFileSync7,
+  existsSync as existsSync5,
   mkdirSync as mkdirSync2
 } from "fs";
-import { dirname as dirname3, join as join6 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 function resolveOutputPath(registryPath, type, config, cwd) {
   let relativePath;
   if (type === "registry:block") {
     relativePath = registryPath.replace(/^blocks\//, "");
-    return join6(cwd, config.paths.blocks, relativePath);
+    return join7(cwd, config.paths.blocks, relativePath);
   }
   if (type === "registry:ui") {
     if (registryPath.startsWith("components/deck/")) {
       relativePath = registryPath.replace(/^components\/deck\//, "");
-      return join6(cwd, config.paths.deckComponents, relativePath);
+      return join7(cwd, config.paths.deckComponents, relativePath);
     }
     if (registryPath.startsWith("components/flutter/")) {
       relativePath = registryPath.replace(/^components\/flutter\//, "");
-      return join6(cwd, config.paths.flutterComponents, relativePath);
+      return join7(cwd, config.paths.flutterComponents, relativePath);
     }
     relativePath = registryPath.replace(/^components\/ui\//, "");
-    return join6(cwd, config.paths.components, relativePath);
+    return join7(cwd, config.paths.components, relativePath);
   }
   if (type === "registry:hook") {
     relativePath = registryPath.replace(/^hooks\//, "");
-    return join6(cwd, config.paths.hooks, relativePath);
+    return join7(cwd, config.paths.hooks, relativePath);
   }
   if (type === "registry:lib") {
     relativePath = registryPath.replace(/^lib\//, "");
-    return join6(cwd, config.paths.lib, relativePath);
+    return join7(cwd, config.paths.lib, relativePath);
   }
-  return join6(cwd, registryPath);
+  return join7(cwd, registryPath);
 }
 function writeFile(filePath, content) {
-  const dir = dirname3(filePath);
-  if (!existsSync4(dir)) {
+  const dir = dirname4(filePath);
+  if (!existsSync5(dir)) {
     mkdirSync2(dir, { recursive: true });
   }
   writeFileSync3(filePath, content, "utf-8");
 }
 function readFile(filePath) {
-  if (!existsSync4(filePath)) return null;
-  return readFileSync6(filePath, "utf-8");
+  if (!existsSync5(filePath)) return null;
+  return readFileSync7(filePath, "utf-8");
 }
 function fileExists(filePath) {
-  return existsSync4(filePath);
+  return existsSync5(filePath);
 }
 
 // src/commands/list.ts
@@ -1097,8 +1640,8 @@ function listCommand(cwd, options = {}) {
 }
 
 // src/utils/pubspec.ts
-import { existsSync as existsSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { join as join8 } from "path";
 import { parseDocument, YAMLMap } from "yaml";
 function mergePubspec(pubspecText, deps) {
   const doc = parseDocument(pubspecText);
@@ -1120,14 +1663,14 @@ function mergePubspec(pubspecText, deps) {
   return { text: doc.toString(), added, skipped };
 }
 function pubspecPath(cwd) {
-  return join7(cwd, "pubspec.yaml");
+  return join8(cwd, "pubspec.yaml");
 }
 function pubspecExists(cwd) {
-  return existsSync5(pubspecPath(cwd));
+  return existsSync6(pubspecPath(cwd));
 }
 function isPubPackageInstalled(packageName, cwd) {
   if (!pubspecExists(cwd)) return false;
-  const text = readFileSync7(pubspecPath(cwd), "utf-8");
+  const text = readFileSync8(pubspecPath(cwd), "utf-8");
   const doc = parseDocument(text);
   const depsNode = doc.get("dependencies");
   if (!(depsNode instanceof YAMLMap)) return false;
@@ -1138,12 +1681,12 @@ function getUninstalledPubDeps(deps, cwd) {
 }
 function addPubDependencies(deps, cwd) {
   const path2 = pubspecPath(cwd);
-  if (!existsSync5(path2)) {
+  if (!existsSync6(path2)) {
     throw new Error(
       `No pubspec.yaml found at ${path2}. Run this command from a Flutter project root.`
     );
   }
-  const text = readFileSync7(path2, "utf-8");
+  const text = readFileSync8(path2, "utf-8");
   const result = mergePubspec(text, deps);
   if (result.added.length > 0) {
     writeFileSync4(path2, result.text, "utf-8");
@@ -1153,12 +1696,12 @@ function addPubDependencies(deps, cwd) {
 
 // src/utils/flutter.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
 import { homedir } from "os";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 function isExecutable(path2) {
   try {
-    const s = statSync2(path2);
+    const s = statSync4(path2);
     return s.isFile();
   } catch {
     return false;
@@ -1166,24 +1709,24 @@ function isExecutable(path2) {
 }
 function fromPath(env) {
   const pathVar = env.PATH ?? "";
-  const sep = process.platform === "win32" ? ";" : ":";
+  const sep2 = process.platform === "win32" ? ";" : ":";
   const bin = process.platform === "win32" ? "flutter.bat" : "flutter";
-  for (const dir of pathVar.split(sep)) {
+  for (const dir of pathVar.split(sep2)) {
     if (!dir) continue;
-    const candidate = join8(dir, bin);
+    const candidate = join9(dir, bin);
     if (isExecutable(candidate)) return candidate;
   }
   return null;
 }
 function fromFvm(home) {
-  const fvmDefault = join8(home, "fvm", "default", "bin", "flutter");
+  const fvmDefault = join9(home, "fvm", "default", "bin", "flutter");
   if (isExecutable(fvmDefault)) return fvmDefault;
-  const versionsDir = join8(home, "fvm", "versions");
-  if (!existsSync6(versionsDir)) return null;
+  const versionsDir = join9(home, "fvm", "versions");
+  if (!existsSync7(versionsDir)) return null;
   let best = null;
   try {
-    for (const name of readdirSync2(versionsDir)) {
-      const candidate = join8(versionsDir, name, "bin", "flutter");
+    for (const name of readdirSync3(versionsDir)) {
+      const candidate = join9(versionsDir, name, "bin", "flutter");
       if (!isExecutable(candidate)) continue;
       if (!best || compareSemver(name, best.version) > 0) {
         best = { version: name, path: candidate };
@@ -1209,7 +1752,7 @@ function findFlutterBin(options = {}) {
   const home = options.home ?? homedir();
   const envRoot = env.FLUTTER_ROOT;
   if (envRoot) {
-    const bin = join8(envRoot, "bin", "flutter");
+    const bin = join9(envRoot, "bin", "flutter");
     if (isExecutable(bin)) return bin;
   }
   const fromPathBin = fromPath(env);
@@ -1852,8 +2395,8 @@ function infoCommand(name, cwd, options = {}) {
 }
 
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
-import { resolve as resolve2, dirname as dirname4, join as join9 } from "path";
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
+import { resolve as resolve4, dirname as dirname5, join as join10 } from "path";
 import { generateTheme, generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
@@ -1883,10 +2426,10 @@ function defaultOutputPath(adapter, themeName) {
   }
 }
 function themeApplyCommand(file, cwd, options) {
-  const filePath = resolve2(cwd, file);
+  const filePath = resolve4(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync8(filePath, "utf-8");
+    yamlContent = readFileSync9(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -1963,14 +2506,14 @@ function themeApplyCommand(file, cwd, options) {
     process.exit(1);
   }
   const outputTarget = options.output ?? defaultOutputPath(options.adapter, themeName);
-  const outputPath = resolve2(cwd, outputTarget);
+  const outputPath = resolve4(cwd, outputTarget);
   if (fileMap) {
     try {
       mkdirSync3(outputPath, { recursive: true });
       let totalBytes = 0;
       for (const [relPath, content] of Object.entries(fileMap.files)) {
-        const filePath2 = join9(outputPath, relPath);
-        mkdirSync3(dirname4(filePath2), { recursive: true });
+        const filePath2 = join10(outputPath, relPath);
+        mkdirSync3(dirname5(filePath2), { recursive: true });
         writeFileSync5(filePath2, content, "utf-8");
         totalBytes += content.length;
       }
@@ -2008,7 +2551,7 @@ function themeApplyCommand(file, cwd, options) {
   if (css === null) {
     process.exit(1);
   }
-  const outputDir = dirname4(outputPath);
+  const outputDir = dirname5(outputPath);
   try {
     mkdirSync3(outputDir, { recursive: true });
     writeFileSync5(outputPath, css, "utf-8");
@@ -2052,8 +2595,8 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync9 } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { resolve as resolve5 } from "path";
 import {
   parseConfig,
   resolveConfig,
@@ -2061,10 +2604,10 @@ import {
   exportTheme
 } from "@loworbitstudio/visor-theme-engine";
 function themeExportCommand(file, cwd, options) {
-  const filePath = resolve3(cwd, file ?? ".visor.yaml");
+  const filePath = resolve5(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync9(filePath, "utf-8");
+    yamlContent = readFileSync10(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2116,16 +2659,16 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { resolve as resolve4 } from "path";
+import { readFileSync as readFileSync11 } from "fs";
+import { resolve as resolve6 } from "path";
 import { parse as parseYaml } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
-import pc2 from "picocolors";
+import pc3 from "picocolors";
 function themeValidateCommand(file, cwd, options) {
-  const filePath = resolve4(cwd, file);
+  const filePath = resolve6(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync10(filePath, "utf-8");
+    fileContent = readFileSync11(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2205,15 +2748,127 @@ function themeValidateCommand(file, cwd, options) {
   }
 }
 function printIssue(issue) {
-  const prefix = issue.severity === "error" ? pc2.red("  ERROR") : pc2.yellow("  WARN ");
-  const code = pc2.dim(`[${issue.code}]`);
-  const path2 = issue.path ? pc2.dim(` (${issue.path})`) : "";
+  const prefix = issue.severity === "error" ? pc3.red("  ERROR") : pc3.yellow("  WARN ");
+  const code = pc3.dim(`[${issue.code}]`);
+  const path2 = issue.path ? pc3.dim(` (${issue.path})`) : "";
   console.log(`${prefix} ${code} ${issue.message}${path2}`);
 }
 
+// src/commands/theme-verify.ts
+import { spawnSync as _spawnSync } from "child_process";
+import { existsSync as existsSync8 } from "fs";
+import { resolve as resolve7 } from "path";
+function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
+  const target = options.target ?? "flutter";
+  if (target !== "flutter") {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          valid: false,
+          target,
+          errors: [
+            {
+              code: "UNSUPPORTED_TARGET",
+              message: `Unsupported target: "${target}". Only "flutter" is supported.`
+            }
+          ]
+        })
+      );
+    } else {
+      logger.error(`Unsupported target: "${target}". Only "flutter" is supported.`);
+    }
+    process.exit(1);
+  }
+  const dirPath = resolve7(cwd, dir);
+  if (!existsSync8(dirPath)) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          valid: false,
+          target,
+          dir: dirPath,
+          errors: [
+            {
+              code: "DIR_NOT_FOUND",
+              message: `Directory not found: ${dirPath}`
+            }
+          ]
+        })
+      );
+    } else {
+      logger.error(`Directory not found: ${dirPath}`);
+      logger.info("Make sure the path exists and is readable.");
+    }
+    process.exit(1);
+  }
+  const flutterBin = findFlutterBin();
+  if (!flutterBin) {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          valid: false,
+          target,
+          dir: dirPath,
+          errors: [
+            {
+              code: "FLUTTER_NOT_FOUND",
+              message: "Flutter binary not found. Set FLUTTER_ROOT, add flutter to PATH, or install via FVM."
+            }
+          ]
+        })
+      );
+    } else {
+      logger.error("Flutter binary not found.");
+      logger.info(
+        "Set FLUTTER_ROOT, add flutter to PATH, or install via FVM."
+      );
+    }
+    process.exit(1);
+  }
+  if (!options.json) {
+    logger.info(`Verifying Flutter output at: ${dirPath}`);
+    logger.item(`Using Flutter binary: ${flutterBin}`);
+  }
+  const result = _spawnFn(flutterBin, ["analyze", "--no-pub"], {
+    cwd: dirPath,
+    stdio: options.json ? "pipe" : "inherit",
+    encoding: "utf-8"
+  });
+  if (options.json) {
+    const stdout = (result.stdout ?? "").toString();
+    const stderr = (result.stderr ?? "").toString();
+    const success = result.status === 0;
+    console.log(
+      JSON.stringify({
+        valid: success,
+        target,
+        dir: dirPath,
+        exitCode: result.status,
+        stdout: stdout.trim() || void 0,
+        stderr: stderr.trim() || void 0,
+        errors: success ? [] : [
+          {
+            code: "DART_ANALYZE_FAILED",
+            message: stderr.trim() || stdout.trim() || "dart analyze reported errors"
+          }
+        ]
+      })
+    );
+    process.exit(success ? 0 : 1);
+  }
+  if (result.status === 0) {
+    logger.success("Flutter output is clean \u2014 dart analyze passed.");
+    process.exit(0);
+  } else {
+    logger.error("dart analyze reported errors in the generated output.");
+    logger.info("Fix the errors above, then re-run: visor theme apply --target flutter");
+    process.exit(1);
+  }
+}
+
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
-import { resolve as resolve5, join as join10, basename, extname as extname2, relative } from "path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync6, existsSync as existsSync9, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
+import { resolve as resolve8, join as join11, basename as basename2, extname as extname3, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -2242,8 +2897,8 @@ var CSS_DIRS = [
   "packages/design-tokens"
 ];
 function themeExtractCommand(cwd, options) {
-  const targetDir = resolve5(cwd, options.from ?? ".");
-  if (!existsSync7(targetDir)) {
+  const targetDir = resolve8(cwd, options.from ?? ".");
+  if (!existsSync9(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
     } else {
@@ -2297,16 +2952,16 @@ function collectCSSFiles(targetDir) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
   for (const pattern2 of CSS_FILE_PATTERNS) {
-    const rootPath = join10(targetDir, pattern2);
+    const rootPath = join11(targetDir, pattern2);
     addFileIfExists(rootPath, files, seen);
     for (const dir of CSS_DIRS) {
-      const dirPath = join10(targetDir, dir, pattern2);
+      const dirPath = join11(targetDir, dir, pattern2);
       addFileIfExists(dirPath, files, seen);
     }
   }
   for (const dir of CSS_DIRS) {
-    const dirPath = join10(targetDir, dir);
-    if (existsSync7(dirPath) && statSync3(dirPath).isDirectory()) {
+    const dirPath = join11(targetDir, dir);
+    if (existsSync9(dirPath) && statSync5(dirPath).isDirectory()) {
       scanDirForCSS(dirPath, files, seen, 2);
     }
   }
@@ -2314,11 +2969,11 @@ function collectCSSFiles(targetDir) {
   return files;
 }
 function addFileIfExists(filePath, files, seen) {
-  const resolved = resolve5(filePath);
+  const resolved = resolve8(filePath);
   if (seen.has(resolved)) return;
-  if (!existsSync7(resolved)) return;
+  if (!existsSync9(resolved)) return;
   try {
-    const content = readFileSync11(resolved, "utf-8");
+    const content = readFileSync12(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -2327,7 +2982,7 @@ function addFileIfExists(filePath, files, seen) {
   }
 }
 function scanDirForCSS(dir, files, seen, maxDepth) {
-  if (!existsSync7(dir)) return;
+  if (!existsSync9(dir)) return;
   const SKIP_DIRS = /* @__PURE__ */ new Set([
     "node_modules",
     ".next",
@@ -2341,15 +2996,15 @@ function scanDirForCSS(dir, files, seen, maxDepth) {
     ".vercel"
   ]);
   try {
-    const entries = readdirSync3(dir, { withFileTypes: true });
+    const entries = readdirSync4(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
         if (maxDepth > 0) {
-          scanDirForCSS(join10(dir, entry.name), files, seen, maxDepth - 1);
+          scanDirForCSS(join11(dir, entry.name), files, seen, maxDepth - 1);
         }
-      } else if (entry.isFile() && extname2(entry.name) === ".css") {
-        addFileIfExists(join10(dir, entry.name), files, seen);
+      } else if (entry.isFile() && extname3(entry.name) === ".css") {
+        addFileIfExists(join11(dir, entry.name), files, seen);
       }
     }
   } catch {
@@ -2431,10 +3086,10 @@ function extractVarName(varExpr) {
 function parseNextFontFromLayouts(targetDir) {
   const fontMap = /* @__PURE__ */ new Map();
   for (const relPath of LAYOUT_FILE_PATHS) {
-    const fullPath = join10(targetDir, relPath);
-    if (!existsSync7(fullPath)) continue;
+    const fullPath = join11(targetDir, relPath);
+    if (!existsSync9(fullPath)) continue;
     try {
-      const content = readFileSync11(fullPath, "utf-8");
+      const content = readFileSync12(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -2481,7 +3136,7 @@ function parseNextFontDeclarations(content, fontMap) {
       const srcMatch = block.match(/src\s*:\s*["']([^"']+)["']/);
       if (srcMatch) {
         const srcPath = srcMatch[1];
-        const fileName = basename(srcPath, extname2(srcPath));
+        const fileName = basename2(srcPath, extname3(srcPath));
         const fontBaseName = fileName.replace(/[-_](Variable|Regular|Bold|Light|Medium|SemiBold|ExtraBold|Thin|Black|Italic).*$/i, "").replace(/[-_]/g, " ").trim();
         if (fontBaseName) {
           fontMap.set(varName, fontBaseName);
@@ -2519,10 +3174,10 @@ var MONO_FONT_NAMES = /* @__PURE__ */ new Set([
   "IBM Plex Mono"
 ]);
 function extractFontHints(targetDir) {
-  const pkgPath = join10(targetDir, "package.json");
-  if (!existsSync7(pkgPath)) return void 0;
+  const pkgPath = join11(targetDir, "package.json");
+  if (!existsSync9(pkgPath)) return void 0;
   try {
-    const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -2558,10 +3213,10 @@ function extractFontHints(targetDir) {
   }
 }
 function inferThemeName(targetDir) {
-  const pkgPath = join10(targetDir, "package.json");
-  if (existsSync7(pkgPath)) {
+  const pkgPath = join11(targetDir, "package.json");
+  if (existsSync9(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
       if (pkg.name) {
         const name = pkg.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -2569,7 +3224,7 @@ function inferThemeName(targetDir) {
     } catch {
     }
   }
-  return `${basename(targetDir)}-theme`;
+  return `${basename2(targetDir)}-theme`;
 }
 function confidenceComment(confidence) {
   return `# confidence: ${confidence}`;
@@ -2598,7 +3253,7 @@ function outputJSON(result, validationResult) {
 }
 function outputYAML(result, outputPath, cwd, validationResult) {
   const yamlStr = buildAnnotatedYAML(result);
-  const outFile = resolve5(cwd, outputPath ?? ".visor.yaml");
+  const outFile = resolve8(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;
@@ -2651,11 +3306,11 @@ function buildAnnotatedYAML(result) {
   for (const token of result.tokens) {
     confidenceMap.set(token.name, token.confidence);
   }
-  const lines = baseYaml.split("\n");
+  const lines2 = baseYaml.split("\n");
   const annotated = [];
   let inColors = false;
   let inColorsDark = false;
-  for (const line of lines) {
+  for (const line of lines2) {
     if (/^colors:/.test(line)) {
       inColors = true;
       inColorsDark = false;
@@ -2684,14 +3339,15 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync9 } from "fs";
-import { resolve as resolve7, join as join12 } from "path";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync11 } from "fs";
+import { resolve as resolve10, join as join13 } from "path";
 import { generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
-import { existsSync as existsSync8 } from "fs";
-import { resolve as resolve6, dirname as dirname5, join as join11 } from "path";
+import { existsSync as existsSync10, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync13, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
+import { resolve as resolve9, dirname as dirname6, join as join12 } from "path";
+import { execFileSync as execFileSync3 } from "child_process";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
 }
@@ -2699,17 +3355,132 @@ function toLabel(name) {
   return name.split(/[\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function findRepoRoot(startDir) {
-  let current = resolve6(startDir);
+  let current = resolve9(startDir);
   while (true) {
-    if (existsSync8(join11(current, "packages", "docs"))) {
+    if (existsSync10(join12(current, "packages", "docs"))) {
       return current;
     }
-    const parent = dirname5(current);
+    const parent = dirname6(current);
     if (parent === current) break;
     current = parent;
   }
   return null;
 }
+function findMainRepoRoot(startDir) {
+  try {
+    const commonDir = execFileSync3("git", ["rev-parse", "--git-common-dir"], {
+      cwd: startDir,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (commonDir) {
+      const absoluteCommonDir = resolve9(startDir, commonDir);
+      const candidate = dirname6(absoluteCommonDir);
+      if (existsSync10(join12(candidate, "packages", "docs"))) {
+        return candidate;
+      }
+    }
+  } catch {
+  }
+  return findRepoRoot(startDir);
+}
+var BrokenSymlinkError = class extends Error {
+  constructor(path2, target) {
+    super(`Broken symlink: ${path2} \u2192 ${target}`);
+    this.path = path2;
+    this.target = target;
+  }
+  path;
+  target;
+  code = "BROKEN_SYMLINK";
+};
+function assertNoBrokenSymlinks(dir) {
+  if (!existsSync10(dir)) return;
+  const entries = readdirSync5(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = join12(dir, entry.name);
+    let lst;
+    try {
+      lst = lstatSync(entryPath);
+    } catch {
+      continue;
+    }
+    if (lst.isSymbolicLink()) {
+      const target = readlinkSync(entryPath);
+      try {
+        statSync6(entryPath);
+      } catch {
+        throw new BrokenSymlinkError(entryPath, target);
+      }
+    }
+  }
+}
+function scanParentForPrivateThemes(parentDir) {
+  if (!existsSync10(parentDir)) return [];
+  const entries = readdirSync5(parentDir, { withFileTypes: true });
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const candidate = join12(parentDir, entry.name, "visor-themes-private", "themes");
+    if (existsSync10(candidate)) {
+      matches.push(candidate);
+    }
+  }
+  return matches.sort();
+}
+function scanNestedThemeDir(dir) {
+  if (!existsSync10(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 = join12(dir, entry.name, "theme.visor.yaml");
+    if (existsSync10(themeFile)) {
+      out.push({ filePath: themeFile, slug: entry.name });
+    }
+  }
+  return out;
+}
+function detectVisorWorkspace(cwd) {
+  let current = resolve9(cwd);
+  while (true) {
+    const pkgPath = join12(current, "package.json");
+    if (existsSync10(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+        const workspaces = pkg.workspaces ?? [];
+        const hasCli = workspaces.some((w) => w.includes("packages/cli"));
+        const hasEngine = workspaces.some((w) => w.includes("packages/theme-engine"));
+        if (pkg.name === "visor" && hasCli && hasEngine) {
+          return current;
+        }
+      } catch {
+      }
+    }
+    const parent = dirname6(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+function isLocalVisorBinary(workspaceRoot, scriptPath) {
+  if (!scriptPath) return false;
+  const expectedPrefix = join12(workspaceRoot, "packages", "cli", "dist");
+  let resolvedScript;
+  let resolvedPrefix;
+  try {
+    resolvedScript = realpathSync(scriptPath);
+  } catch {
+    resolvedScript = resolve9(scriptPath);
+  }
+  try {
+    resolvedPrefix = realpathSync(expectedPrefix);
+  } catch {
+    resolvedPrefix = resolve9(expectedPrefix);
+  }
+  return resolvedScript.startsWith(resolvedPrefix + "/") || resolvedScript === resolvedPrefix;
+}
 
 // src/commands/theme-register.ts
 function insertGlobalsImport(content, slug2) {
@@ -2717,32 +3488,32 @@ function insertGlobalsImport(content, slug2) {
   if (content.includes(importLine)) {
     return { updated: content, changed: false };
   }
-  const lines = content.split("\n");
+  const lines2 = content.split("\n");
   const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';/;
   const themeImportIndices = [];
-  for (let i = 0; i < lines.length; i++) {
-    if (themeImportPattern.test(lines[i])) {
+  for (let i = 0; i < lines2.length; i++) {
+    if (themeImportPattern.test(lines2[i])) {
       themeImportIndices.push(i);
     }
   }
   if (themeImportIndices.length === 0) {
-    const lastImportIdx = lines.reduce(
+    const lastImportIdx = lines2.reduce(
       (last, line, i) => line.startsWith("@import") ? i : last,
       -1
     );
     const insertAt2 = lastImportIdx + 1;
-    lines.splice(insertAt2, 0, importLine);
-    return { updated: lines.join("\n"), changed: true };
+    lines2.splice(insertAt2, 0, importLine);
+    return { updated: lines2.join("\n"), changed: true };
   }
   let insertAt = themeImportIndices[themeImportIndices.length - 1] + 1;
   for (const idx of themeImportIndices) {
-    if (importLine < lines[idx]) {
+    if (importLine < lines2[idx]) {
       insertAt = idx;
       break;
     }
   }
-  lines.splice(insertAt, 0, importLine);
-  return { updated: lines.join("\n"), changed: true };
+  lines2.splice(insertAt, 0, importLine);
+  return { updated: lines2.join("\n"), changed: true };
 }
 function insertThemeConfig(content, slug2, label, group) {
   if (content.includes(`value: "${slug2}"`)) {
@@ -2796,10 +3567,10 @@ ${indent}${newEntry},
   return { updated, changed: true };
 }
 function themeRegisterCommand(file, cwd, options) {
-  const filePath = resolve7(cwd, file);
+  const filePath = resolve10(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync12(filePath, "utf-8");
+    yamlContent = readFileSync14(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -2842,11 +3613,11 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join12(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join12(docsAppDir, `${slug2}-theme.css`);
-  const globalsPath = join12(docsAppDir, "globals.css");
-  const themeConfigPath = join12(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync9(docsAppDir)) {
+  const docsAppDir = join13(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join13(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join13(docsAppDir, "globals.css");
+  const themeConfigPath = join13(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync11(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -2859,8 +3630,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync12(globalsPath, "utf-8");
-    themeConfigContent = readFileSync12(themeConfigPath, "utf-8");
+    globalsContent = readFileSync14(globalsPath, "utf-8");
+    themeConfigContent = readFileSync14(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -2871,8 +3642,8 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync9(cssFilePath);
-  const cssChanged = !cssExists || readFileSync12(cssFilePath, "utf-8") !== css;
+  const cssExists = existsSync11(cssFilePath);
+  const cssChanged = !cssExists || readFileSync14(cssFilePath, "utf-8") !== css;
   const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
@@ -2956,8 +3727,8 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync8, existsSync as existsSync10, unlinkSync } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync8, existsSync as existsSync12, unlinkSync } from "fs";
+import { join as join14 } from "path";
 function removeGlobalsImport(content, slug2) {
   const importLine = `@import './${slug2}-theme.css';`;
   if (!content.includes(importLine)) {
@@ -2989,11 +3760,11 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join13(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join13(docsAppDir, `${slug2}-theme.css`);
-  const globalsPath = join13(docsAppDir, "globals.css");
-  const themeConfigPath = join13(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync10(docsAppDir)) {
+  const docsAppDir = join14(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join14(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join14(docsAppDir, "globals.css");
+  const themeConfigPath = join14(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync12(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -3006,8 +3777,8 @@ function themeUnregisterCommand(slug2, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync13(globalsPath, "utf-8");
-    themeConfigContent = readFileSync13(themeConfigPath, "utf-8");
+    globalsContent = readFileSync15(globalsPath, "utf-8");
+    themeConfigContent = readFileSync15(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3018,7 +3789,7 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync10(cssFilePath);
+  const cssExists = existsSync12(cssFilePath);
   const { updated: newGlobals, changed: globalsChanged } = removeGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged } = removeThemeConfigEntry(themeConfigContent, slug2);
   if (!cssExists && !globalsChanged && !themeConfigChanged) {
@@ -3059,30 +3830,150 @@ function themeUnregisterCommand(slug2, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync14,
+  readFileSync as readFileSync16,
   writeFileSync as writeFileSync9,
   mkdirSync as mkdirSync5,
-  existsSync as existsSync11,
-  readdirSync as readdirSync4,
+  existsSync as existsSync13,
+  readdirSync as readdirSync6,
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join14, basename as basename2 } from "path";
+import { join as join15, basename as basename3, resolve as resolve11, sep } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
+var PRIVATE_THEMES_REPO_URL = "git@github.com:low-orbit-studio/visor-themes-private.git";
+var PRIVATE_THEMES_ENV_VAR = "VISOR_THEMES_PRIVATE_PATH";
 var GLOBALS_BEGIN_MARKER = "/* BEGIN visor-theme-imports \u2014 managed by `visor theme sync` */";
 var GLOBALS_END_MARKER = "/* END visor-theme-imports */";
 var STOCK_GROUPS_BEGIN_MARKER = "/* BEGIN visor-stock-themes \u2014 managed by `visor theme sync` */";
 var STOCK_GROUPS_END_MARKER = "/* END visor-stock-themes */";
-var GITIGNORE_BEGIN_MARKER = "# BEGIN visor-custom-theme-css (managed by `visor theme sync` \u2014 do not edit manually)";
-var GITIGNORE_END_MARKER = "# END visor-custom-theme-css";
 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 (!existsSync11(dir)) return [];
-  return readdirSync4(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join14(dir, f));
+  if (!existsSync13(dir)) return [];
+  assertNoBrokenSymlinks(dir);
+  return readdirSync6(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join15(dir, f));
+}
+function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
+  const merged = /* @__PURE__ */ new Map();
+  const deprecationWarnings = [];
+  const addNested = (dir, origin) => {
+    const entries = scanNestedThemeDir(dir);
+    for (const entry of entries) {
+      const existing = merged.get(entry.slug);
+      if (existing) {
+        warn(
+          `Duplicate theme slug "${entry.slug}" \u2014 keeping ${existing.origin} source (${existing.filePath}); ignoring ${origin} source (${entry.filePath}).`
+        );
+        continue;
+      }
+      merged.set(entry.slug, {
+        filePath: entry.filePath,
+        slug: entry.slug,
+        origin
+      });
+    }
+  };
+  const envPath = process.env[PRIVATE_THEMES_ENV_VAR];
+  if (envPath && envPath.trim() !== "") {
+    const resolved = resolve11(envPath);
+    if (!existsSync13(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 = join15(mainRepoRoot, "..", "visor-themes-private", "themes");
+  const siblingExists = existsSync13(siblingPath);
+  if (siblingExists) {
+    addNested(siblingPath, "sibling");
+  }
+  const parentDir = join15(mainRepoRoot, "..");
+  const parentGlobMatches = scanParentForPrivateThemes(parentDir).filter(
+    (path2) => !path2.startsWith(mainRepoRoot + sep)
+  );
+  if (parentGlobMatches.length > 0) {
+    if (siblingExists) {
+      for (const path2 of parentGlobMatches) {
+        warn(
+          `Found one-level-deeper theme source ${path2} but using true-sibling at ${siblingPath} (preferred per BO-29 D2).`
+        );
+      }
+    } else {
+      const [first, ...rest] = parentGlobMatches;
+      addNested(first, "parent-glob");
+      for (const other of rest) {
+        warn(
+          `Multiple one-level-deeper theme sources found; using ${first} and ignoring ${other}. Set ${PRIVATE_THEMES_ENV_VAR} to override.`
+        );
+      }
+    }
+  }
+  const legacyDir = join15(repoRoot, "custom-themes");
+  const legacyFiles = scanThemeDir(legacyDir);
+  for (const legacyFile of legacyFiles) {
+    const slug2 = basename3(legacyFile).replace(/\.visor\.yaml$/, "");
+    const existing = merged.get(slug2);
+    if (existing) {
+      warn(
+        `Duplicate theme slug "${slug2}" \u2014 keeping ${existing.origin} source (${existing.filePath}); ignoring legacy source (${legacyFile}).`
+      );
+      continue;
+    }
+    deprecationWarnings.push(
+      `Deprecated legacy custom-themes/ source: ${legacyFile} \u2014 migrate to visor-themes-private (see docs).`
+    );
+    merged.set(slug2, {
+      filePath: legacyFile,
+      slug: slug2,
+      origin: "legacy"
+    });
+  }
+  return { files: [...merged.values()], deprecationWarnings };
+}
+function reportBrokenSymlink(err, options) {
+  const msg = `Broken symlink in theme source: ${err.path} \u2192 ${err.target}`;
+  if (options.json) {
+    console.log(JSON.stringify({ success: false, error: msg, path: err.path, target: err.target }));
+  } else {
+    logger.error(msg);
+  }
+}
+function buildEmptySourcesMessage(mainRepoRoot) {
+  const expectedSibling = join15(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 ${join15(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:",
+    `  git clone ${PRIVATE_THEMES_REPO_URL} ${expectedSibling}`,
+    "",
+    `Or set ${PRIVATE_THEMES_ENV_VAR} to a directory containing {slug}/theme.visor.yaml entries.`
+  ].join("\n");
+}
+function enforceWorkspaceGuard(cwd) {
+  if (process.env.VITEST) return null;
+  if (process.env.VISOR_SKIP_WORKSPACE_GUARD) return null;
+  const workspaceRoot = detectVisorWorkspace(cwd);
+  if (!workspaceRoot) return null;
+  if (isLocalVisorBinary(workspaceRoot, process.argv[1])) return null;
+  return [
+    `Detected Visor workspace at ${workspaceRoot}.`,
+    "The global `visor` CLI bundles a published theme-engine that lags HEAD and",
+    "can regress stock theme CSS files. Run the workspace command instead:",
+    "",
+    "  npm run theme:sync",
+    "",
+    `(Override with VISOR_SKIP_WORKSPACE_GUARD=1 if you really know what you're doing.)`
+  ].join("\n");
 }
 function extractGroup(yamlContent) {
   const parsed = parseYaml2(yamlContent);
@@ -3119,28 +4010,28 @@ ${GLOBALS_END_MARKER}`;
     updated = content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GLOBALS_END_MARKER.length);
   } else {
     const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';\n?/gm;
-    const lines = content.split("\n");
+    const lines2 = content.split("\n");
     let firstThemeIdx = -1;
     let lastThemeIdx = -1;
-    for (let i = 0; i < lines.length; i++) {
-      if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines[i])) {
+    for (let i = 0; i < lines2.length; i++) {
+      if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines2[i])) {
         if (firstThemeIdx === -1) firstThemeIdx = i;
         lastThemeIdx = i;
       }
     }
     if (firstThemeIdx !== -1) {
-      const before = lines.slice(0, firstThemeIdx);
-      const after = lines.slice(lastThemeIdx + 1);
+      const before = lines2.slice(0, firstThemeIdx);
+      const after = lines2.slice(lastThemeIdx + 1);
       updated = [...before, newBlock, ...after].join("\n");
     } else {
       void themeImportPattern;
-      const lastImportIdx = lines.reduce(
+      const lastImportIdx = lines2.reduce(
         (last, line, i) => line.startsWith("@import") ? i : last,
         -1
       );
       const insertAt = lastImportIdx + 1;
-      lines.splice(insertAt, 0, newBlock);
-      updated = lines.join("\n");
+      lines2.splice(insertAt, 0, newBlock);
+      updated = lines2.join("\n");
     }
   }
   updated = ensureCustomOverlayImport(updated);
@@ -3241,19 +4132,17 @@ ${groupsTs}
 ];
 `;
 }
-function updateGitignoreBlock(content, customSlugs) {
-  const cssLines = customSlugs.sort().map((slug2) => `packages/docs/app/${slug2}-theme.css`).join("\n");
-  const newBlock = `${GITIGNORE_BEGIN_MARKER}
-${cssLines}
-${GITIGNORE_END_MARKER}`;
-  const beginIdx = content.indexOf(GITIGNORE_BEGIN_MARKER);
-  const endIdx = content.indexOf(GITIGNORE_END_MARKER);
-  if (beginIdx !== -1 && endIdx !== -1) {
-    return content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GITIGNORE_END_MARKER.length);
-  }
-  return content.trimEnd() + "\n\n" + newBlock + "\n";
-}
 function themeSyncCommand(cwd, options) {
+  const guardError = enforceWorkspaceGuard(cwd);
+  if (guardError) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: guardError }));
+    } else {
+      logger.error(guardError);
+    }
+    process.exit(1);
+    return;
+  }
   const repoRoot = findRepoRoot(cwd);
   if (!repoRoot) {
     const msg = "Could not locate repo root (packages/docs/ not found). Run from within the visor repo.";
@@ -3265,33 +4154,72 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join14(repoRoot, "themes");
-  const customThemesDir = join14(repoRoot, "custom-themes");
-  const docsAppDir = join14(repoRoot, "packages", "docs", "app");
-  const docsLibDir = join14(repoRoot, "packages", "docs", "lib");
-  const docsPublicThemesDir = join14(repoRoot, "packages", "docs", "public", "themes");
-  const themeConfigPath = join14(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  const globalsPath = join14(docsAppDir, "globals.css");
-  const gitignorePath = join14(repoRoot, ".gitignore");
-  const customOverlayCssPath = join14(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
-  const customOverlayTsPath = join14(repoRoot, CUSTOM_OVERLAY_TS_PATH);
-  const stockFiles = scanThemeDir(themesDir);
-  const customFiles = scanThemeDir(customThemesDir);
-  if (stockFiles.length === 0 && customFiles.length === 0) {
-    const msg = `No .visor.yaml files found in themes/ or custom-themes/. Nothing to sync.`;
+  const mainRepoRoot = findMainRepoRoot(cwd) ?? repoRoot;
+  const themesDir = join15(repoRoot, "themes");
+  const docsAppDir = join15(repoRoot, "packages", "docs", "app");
+  const docsLibDir = join15(repoRoot, "packages", "docs", "lib");
+  const docsPublicThemesDir = join15(repoRoot, "packages", "docs", "public", "themes");
+  const themeConfigPath = join15(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const globalsPath = join15(docsAppDir, "globals.css");
+  const customOverlayCssPath = join15(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
+  const customOverlayTsPath = join15(repoRoot, CUSTOM_OVERLAY_TS_PATH);
+  let stockFiles;
+  try {
+    stockFiles = scanThemeDir(themesDir);
+  } catch (err) {
+    if (err instanceof BrokenSymlinkError) {
+      reportBrokenSymlink(err, options);
+      process.exit(1);
+      return;
+    }
+    throw err;
+  }
+  let customSources = [];
+  let deprecationWarnings = [];
+  const discoveryWarnings = [];
+  try {
+    const result = resolveCustomSources(
+      repoRoot,
+      mainRepoRoot,
+      (msg) => discoveryWarnings.push(msg)
+    );
+    customSources = result.files;
+    deprecationWarnings = result.deprecationWarnings;
+  } catch (err) {
+    if (err instanceof BrokenSymlinkError) {
+      reportBrokenSymlink(err, options);
+      process.exit(1);
+      return;
+    }
+    const msg = err instanceof Error ? err.message : "Custom theme discovery failed";
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
     } else {
-      logger.warn(msg);
+      logger.error(msg);
+    }
+    process.exit(1);
+    return;
+  }
+  if (stockFiles.length === 0 && customSources.length === 0) {
+    const msg = buildEmptySourcesMessage(mainRepoRoot);
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: msg }));
+    } else {
+      logger.error(msg);
     }
+    process.exit(1);
     return;
   }
+  if (!options.json) {
+    for (const w of deprecationWarnings) logger.warn(w);
+    for (const w of discoveryWarnings) logger.warn(w);
+  }
   const manifest = [];
   const errors = [];
-  const processFile = (filePath, isCustom) => {
+  const processFile = (filePath, isCustom, slugOverride) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync14(filePath, "utf-8");
+      yamlContent = readFileSync16(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       return;
@@ -3300,19 +4228,22 @@ function themeSyncCommand(cwd, options) {
     try {
       data = generateThemeData4(yamlContent);
     } catch (err) {
-      errors.push(`Failed to parse ${basename2(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`);
+      errors.push(`Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`);
       return;
     }
-    const slug2 = toSlug(data.config.name);
+    const slug2 = slugOverride ?? toSlug(data.config.name);
     const label = extractLabel(yamlContent) ?? toLabel(data.config.name);
     const group = extractGroup(yamlContent) ?? (isCustom ? "Custom" : "Visor");
     const defaultMode = extractDefaultMode(yamlContent);
     const css = docsAdapter3({ primitives: data.primitives, tokens: data.tokens, config: data.config });
-    const yamlFilename = basename2(filePath).replace(/\.visor\.yaml$/, "");
+    const yamlFilename = slugOverride ?? basename3(filePath).replace(/\.visor\.yaml$/, "");
     manifest.push({ slug: slug2, label, group, defaultMode, css, yamlFilename, isCustom });
   };
   for (const f of stockFiles) processFile(f, false);
-  for (const f of customFiles) processFile(f, true);
+  for (const c of customSources) {
+    const isNested = c.origin !== "legacy";
+    processFile(c.filePath, true, isNested ? c.slug : void 0);
+  }
   if (errors.length > 0) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, errors }));
@@ -3325,15 +4256,12 @@ function themeSyncCommand(cwd, options) {
   const stockManifest = manifest.filter((e) => !e.isCustom);
   const customManifest = manifest.filter((e) => e.isCustom);
   const stockSlugs = stockManifest.map((e) => e.slug);
-  const customSlugs = customManifest.map((e) => e.slug);
   const allSlugs = manifest.map((e) => e.slug);
   let globalsContent;
   let themeConfigContent;
-  let gitignoreContent;
   try {
-    globalsContent = readFileSync14(globalsPath, "utf-8");
-    themeConfigContent = readFileSync14(themeConfigPath, "utf-8");
-    gitignoreContent = existsSync11(gitignorePath) ? readFileSync14(gitignorePath, "utf-8") : "";
+    globalsContent = readFileSync16(globalsPath, "utf-8");
+    themeConfigContent = readFileSync16(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3346,15 +4274,14 @@ function themeSyncCommand(cwd, options) {
   }
   const newGlobals = updateGlobalsImports(globalsContent, stockSlugs);
   const newThemeConfig = updateStockThemeConfigBlock(themeConfigContent, stockManifest);
-  const newGitignore = customSlugs.length > 0 ? updateGitignoreBlock(gitignoreContent, customSlugs) : gitignoreContent;
   const newCustomOverlayCss = generateCustomOverlayCss(customManifest);
   const newCustomOverlayTs = generateCustomOverlayTs(customManifest);
-  const existingCssFiles = existsSync11(docsAppDir) ? readdirSync4(docsAppDir).filter(
+  const existingCssFiles = existsSync13(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 = existsSync11(docsPublicThemesDir) ? readdirSync4(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
+  const existingPublicYamls = existsSync13(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) {
@@ -3366,7 +4293,6 @@ function themeSyncCommand(cwd, options) {
       globalsCSS: globalsPath,
       customOverlayCss: CUSTOM_OVERLAY_CSS_PATH,
       customOverlayTs: CUSTOM_OVERLAY_TS_PATH,
-      gitignore: gitignorePath,
       publicYamlsCopied: manifest.map((e) => `packages/docs/public/themes/${e.yamlFilename}.visor.yaml`),
       publicYamlsDeleted: stalePublicYamls.map((f) => `packages/docs/public/themes/${f}`)
     };
@@ -3386,25 +4312,24 @@ function themeSyncCommand(cwd, options) {
     mkdirSync5(docsLibDir, { recursive: true });
     mkdirSync5(docsPublicThemesDir, { recursive: true });
     for (const entry of manifest) {
-      writeFileSync9(join14(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
+      writeFileSync9(join15(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
     }
     for (const stale of staleCssFiles) {
-      unlinkSync2(join14(docsAppDir, stale));
+      unlinkSync2(join15(docsAppDir, stale));
     }
     writeFileSync9(customOverlayCssPath, newCustomOverlayCss, "utf-8");
     writeFileSync9(customOverlayTsPath, newCustomOverlayTs, "utf-8");
     writeFileSync9(themeConfigPath, newThemeConfig, "utf-8");
     writeFileSync9(globalsPath, newGlobals, "utf-8");
-    if (existsSync11(gitignorePath)) {
-      writeFileSync9(gitignorePath, newGitignore, "utf-8");
+    for (const srcFile of stockFiles) {
+      copyFileSync(srcFile, join15(docsPublicThemesDir, basename3(srcFile)));
     }
-    const allSourceFiles = [...stockFiles, ...customFiles];
-    for (const srcFile of allSourceFiles) {
-      const filename = basename2(srcFile);
-      copyFileSync(srcFile, join14(docsPublicThemesDir, filename));
+    for (const c of customSources) {
+      const targetName = c.origin === "legacy" ? basename3(c.filePath) : `${c.slug}.visor.yaml`;
+      copyFileSync(c.filePath, join15(docsPublicThemesDir, targetName));
     }
     for (const stale of stalePublicYamls) {
-      unlinkSync2(join14(docsPublicThemesDir, stale));
+      unlinkSync2(join15(docsPublicThemesDir, stale));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -3417,6 +4342,7 @@ function themeSyncCommand(cwd, options) {
     return;
   }
   if (options.json) {
+    const warnings = [...deprecationWarnings, ...discoveryWarnings];
     console.log(JSON.stringify({
       success: true,
       themes: manifest.length,
@@ -3424,7 +4350,8 @@ function themeSyncCommand(cwd, options) {
       custom: customManifest.length,
       staleCssDeleted: staleCssFiles.length,
       staleYamlsDeleted: stalePublicYamls.length,
-      slugs: allSlugs
+      slugs: allSlugs,
+      ...warnings.length > 0 ? { warnings } : {}
     }));
   } else {
     logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
@@ -3440,19 +4367,19 @@ function themeSyncCommand(cwd, options) {
 
 // src/commands/theme-batch-apply-flutter.ts
 import {
-  readFileSync as readFileSync15,
+  readFileSync as readFileSync17,
   writeFileSync as writeFileSync10,
   mkdirSync as mkdirSync6,
-  existsSync as existsSync12,
-  readdirSync as readdirSync5,
+  existsSync as existsSync14,
+  readdirSync as readdirSync7,
   rmSync
 } from "fs";
-import { join as join15, basename as basename3, dirname as dirname6 } from "path";
+import { join as join16, basename as basename4, dirname as dirname7 } from "path";
 import { generateThemeData as generateThemeData5 } from "@loworbitstudio/visor-theme-engine";
 import { flutterAdapter as flutterAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 function scanThemeDir2(dir) {
-  if (!existsSync12(dir)) return [];
-  return readdirSync5(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join15(dir, f)).sort();
+  if (!existsSync14(dir)) return [];
+  return readdirSync7(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join16(dir, f)).sort();
 }
 function slugToCamel(slug2) {
   return slug2.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -3515,7 +4442,7 @@ function slugToDartPrefix(slug2) {
   return slug2.replace(/-/g, "_") + "_t";
 }
 function emitMetaBarrel(slugs) {
-  const lines = [
+  const lines2 = [
     `// GENERATED BY visor \u2014 DO NOT EDIT.`,
     `// Regenerate with \`npm run themes:apply-flutter\`.`,
     `//`,
@@ -3531,37 +4458,37 @@ function emitMetaBarrel(slugs) {
   ];
   for (const slug2 of slugs) {
     const prefix = slugToDartPrefix(slug2);
-    lines.push(`import 'src/${slug2}/theme/visor_theme.dart' as ${prefix};`);
-  }
-  lines.push(``);
-  lines.push(`/// A light/dark [ThemeData] pair for a single Visor theme.`);
-  lines.push(`class VisorThemePair {`);
-  lines.push(`  final ThemeData light;`);
-  lines.push(`  final ThemeData dark;`);
-  lines.push(`  const VisorThemePair({required this.light, required this.dark});`);
-  lines.push(`}`);
-  lines.push(``);
-  lines.push(`/// Static access to all Visor-generated Flutter themes.`);
-  lines.push(`///`);
-  lines.push(`/// Usage:`);
-  lines.push(`/// \`\`\`dart`);
-  lines.push(`/// MaterialApp(`);
-  lines.push(`///   theme: VisorThemes.blackout.light,`);
-  lines.push(`///   darkTheme: VisorThemes.blackout.dark,`);
-  lines.push(`/// );`);
-  lines.push(`/// \`\`\``);
-  lines.push(`sealed class VisorThemes {`);
+    lines2.push(`import 'src/${slug2}/theme/visor_theme.dart' as ${prefix};`);
+  }
+  lines2.push(``);
+  lines2.push(`/// A light/dark [ThemeData] pair for a single Visor theme.`);
+  lines2.push(`class VisorThemePair {`);
+  lines2.push(`  final ThemeData light;`);
+  lines2.push(`  final ThemeData dark;`);
+  lines2.push(`  const VisorThemePair({required this.light, required this.dark});`);
+  lines2.push(`}`);
+  lines2.push(``);
+  lines2.push(`/// Static access to all Visor-generated Flutter themes.`);
+  lines2.push(`///`);
+  lines2.push(`/// Usage:`);
+  lines2.push(`/// \`\`\`dart`);
+  lines2.push(`/// MaterialApp(`);
+  lines2.push(`///   theme: VisorThemes.blackout.light,`);
+  lines2.push(`///   darkTheme: VisorThemes.blackout.dark,`);
+  lines2.push(`/// );`);
+  lines2.push(`/// \`\`\``);
+  lines2.push(`sealed class VisorThemes {`);
   for (const slug2 of slugs) {
     const camel = slugToCamel(slug2);
     const prefix = slugToDartPrefix(slug2);
-    lines.push(`  static VisorThemePair get ${camel} => VisorThemePair(`);
-    lines.push(`    light: ${prefix}.VisorAppTheme.light,`);
-    lines.push(`    dark: ${prefix}.VisorAppTheme.dark,`);
-    lines.push(`  );`);
+    lines2.push(`  static VisorThemePair get ${camel} => VisorThemePair(`);
+    lines2.push(`    light: ${prefix}.VisorAppTheme.light,`);
+    lines2.push(`    dark: ${prefix}.VisorAppTheme.dark,`);
+    lines2.push(`  );`);
   }
-  lines.push(`}`);
-  lines.push(``);
-  return lines.join("\n");
+  lines2.push(`}`);
+  lines2.push(``);
+  return lines2.join("\n");
 }
 function emitGitignore() {
   return [
@@ -3585,9 +4512,9 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join15(repoRoot, "themes");
-  const customThemesDir = join15(repoRoot, "custom-themes");
-  const outputDir = join15(repoRoot, "packages", "visor_themes");
+  const themesDir = join16(repoRoot, "themes");
+  const customThemesDir = join16(repoRoot, "custom-themes");
+  const outputDir = join16(repoRoot, "packages", "visor_themes");
   const stockFiles = scanThemeDir2(themesDir);
   const customFiles = scanThemeDir2(customThemesDir);
   const allFiles = [...stockFiles, ...customFiles];
@@ -3608,7 +4535,7 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   for (const filePath of allFiles) {
     let yamlContent;
     try {
-      yamlContent = readFileSync15(filePath, "utf-8");
+      yamlContent = readFileSync17(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       continue;
@@ -3618,7 +4545,7 @@ function themeBatchApplyFlutterCommand(cwd, options) {
       data = generateThemeData5(yamlContent);
     } catch (err) {
       errors.push(
-        `Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
+        `Failed to parse ${basename4(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
       );
       continue;
     }
@@ -3687,8 +4614,8 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     return;
   }
   const slugs = processed.map((p) => p.slug);
-  const libSrcDir = join15(outputDir, "lib", "src");
-  if (existsSync12(libSrcDir)) {
+  const libSrcDir = join16(outputDir, "lib", "src");
+  if (existsSync14(libSrcDir)) {
     rmSync(libSrcDir, { recursive: true, force: true });
   }
   const packageFiles = {
@@ -3700,16 +4627,16 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   };
   let totalFiles = 0;
   for (const [relPath, content] of Object.entries(packageFiles)) {
-    const absPath = join15(outputDir, relPath);
-    mkdirSync6(dirname6(absPath), { recursive: true });
+    const absPath = join16(outputDir, relPath);
+    mkdirSync6(dirname7(absPath), { recursive: true });
     writeFileSync10(absPath, content, "utf-8");
     totalFiles++;
   }
   for (const { slug: slug2, tokenFiles } of processed) {
-    const themeBaseDir = join15(outputDir, "lib", "src", slug2);
+    const themeBaseDir = join16(outputDir, "lib", "src", slug2);
     for (const [relPath, content] of Object.entries(tokenFiles)) {
-      const absPath = join15(themeBaseDir, relPath);
-      mkdirSync6(dirname6(absPath), { recursive: true });
+      const absPath = join16(themeBaseDir, relPath);
+      mkdirSync6(dirname7(absPath), { recursive: true });
       writeFileSync10(absPath, content, "utf-8");
       totalFiles++;
     }
@@ -3731,11 +4658,11 @@ function themeBatchApplyFlutterCommand(cwd, options) {
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync13, statSync as statSync4, readdirSync as readdirSync6, readFileSync as readFileSync16 } from "fs";
-import { resolve as resolve8, basename as basename4, extname as extname3 } from "path";
+import { existsSync as existsSync15, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync18 } from "fs";
+import { resolve as resolve12, basename as basename5, extname as extname4 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
-  const name = basename4(filename, extname3(filename));
+  const name = basename5(filename, extname4(filename));
   const WEIGHT_STYLE_SUFFIXES = /* @__PURE__ */ new Set([
     "thin",
     "hairline",
@@ -3776,28 +4703,28 @@ function deriveFamilySlug(filename) {
   return parts.join("-").toLowerCase();
 }
 function collectWoff2Files(inputPath) {
-  const resolved = resolve8(inputPath);
-  if (!existsSync13(resolved)) {
+  const resolved = resolve12(inputPath);
+  if (!existsSync15(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
-  const stat = statSync4(resolved);
+  const stat = statSync7(resolved);
   if (stat.isFile()) {
-    if (extname3(resolved).toLowerCase() !== ".woff2") {
+    if (extname4(resolved).toLowerCase() !== ".woff2") {
       throw new Error(
-        `Invalid file format: ${basename4(resolved)}. Only .woff2 files are accepted.`
+        `Invalid file format: ${basename5(resolved)}. Only .woff2 files are accepted.`
       );
     }
     return [resolved];
   }
   if (stat.isDirectory()) {
-    const files = readdirSync6(resolved).filter((f) => extname3(f).toLowerCase() === ".woff2").map((f) => resolve8(resolved, f));
+    const files = readdirSync8(resolved).filter((f) => extname4(f).toLowerCase() === ".woff2").map((f) => resolve12(resolved, f));
     if (files.length === 0) {
       throw new Error(
         `No .woff2 files found in directory: ${resolved}`
       );
     }
-    const nonWoff2Fonts = readdirSync6(resolved).filter((f) => {
-      const ext = extname3(f).toLowerCase();
+    const nonWoff2Fonts = readdirSync8(resolved).filter((f) => {
+      const ext = extname4(f).toLowerCase();
       return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
     });
     return files.sort();
@@ -3805,12 +4732,12 @@ function collectWoff2Files(inputPath) {
   throw new Error(`Path is neither a file nor a directory: ${resolved}`);
 }
 function getNonWoff2Fonts(inputPath) {
-  const resolved = resolve8(inputPath);
-  if (!existsSync13(resolved) || !statSync4(resolved).isDirectory()) {
+  const resolved = resolve12(inputPath);
+  if (!existsSync15(resolved) || !statSync7(resolved).isDirectory()) {
     return [];
   }
-  return readdirSync6(resolved).filter((f) => {
-    const ext = extname3(f).toLowerCase();
+  return readdirSync8(resolved).filter((f) => {
+    const ext = extname4(f).toLowerCase();
     return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
   });
 }
@@ -3843,7 +4770,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync16(filePath);
+  const body = readFileSync18(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -3858,9 +4785,9 @@ async function fontsAddCommand(inputPath, options) {
   try {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
-    const familySlug = options.family ?? deriveFamilySlug(basename4(files[0]));
-    const resolved = resolve8(inputPath);
-    const nonWoff2 = statSync4(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
+    const familySlug = options.family ?? deriveFamilySlug(basename5(files[0]));
+    const resolved = resolve12(inputPath);
+    const nonWoff2 = statSync7(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
       logger.heading("Visor Font Upload");
       logger.info(`Organization: ${org}`);
@@ -3878,13 +4805,13 @@ async function fontsAddCommand(inputPath, options) {
     const bucket = "visor-fonts";
     const results = [];
     for (const filePath of files) {
-      const filename = basename4(filePath);
+      const filename = basename5(filePath);
       const key = buildS3Key(org, familySlug, filename);
       if (!json) {
         logger.info(`Uploading ${filename}...`);
       }
       await uploadFile(client, bucket, key, filePath);
-      const size = statSync4(filePath).size;
+      const size = statSync7(filePath).size;
       results.push({ file: filename, key, size });
       if (!json) {
         logger.success(`Uploaded: ${key} (${formatBytes(size)})`);
@@ -3934,7 +4861,7 @@ function formatBytes(bytes) {
 // src/commands/doctor.ts
 import * as fs from "fs";
 import * as path from "path";
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 async function doctorCommand(cwd, options, cliVersion) {
   const checks = [];
   const visorJsonPath = path.join(cwd, "visor.json");
@@ -4069,9 +4996,9 @@ async function doctorCommand(cwd, options, cliVersion) {
   }
   if (process.platform !== "win32") {
     try {
-      const globalPath = execFileSync3("which", ["visor"], { encoding: "utf-8" }).trim();
+      const globalPath = execFileSync4("which", ["visor"], { encoding: "utf-8" }).trim();
       if (globalPath) {
-        const globalVersionRaw = execFileSync3(globalPath, ["--version"], { encoding: "utf-8" }).trim();
+        const globalVersionRaw = execFileSync4(globalPath, ["--version"], { encoding: "utf-8" }).trim();
         const globalVersion = globalVersionRaw.split(/\s+/).pop() ?? "";
         if (isOlder(globalVersion, cliVersion)) {
           checks.push({
@@ -4147,27 +5074,27 @@ function findCssFiles(dir, maxDepth = 3) {
 }
 
 // src/utils/patterns.ts
-import { existsSync as existsSync15, readdirSync as readdirSync8, readFileSync as readFileSync18 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync17, readdirSync as readdirSync10, readFileSync as readFileSync20 } from "fs";
+import { join as join18 } from "path";
 import { parse as parseYAML } from "yaml";
 function loadPatternsFromYaml(repoRoot) {
-  const patternsDir = join17(repoRoot, "patterns");
-  if (!existsSync15(patternsDir)) return [];
-  const files = readdirSync8(patternsDir).filter(
+  const patternsDir = join18(repoRoot, "patterns");
+  if (!existsSync17(patternsDir)) return [];
+  const files = readdirSync10(patternsDir).filter(
     (f) => f.endsWith(".visor-pattern.yaml")
   );
   return files.map((file) => {
-    const content = readFileSync18(join17(patternsDir, file), "utf-8");
+    const content = readFileSync20(join18(patternsDir, file), "utf-8");
     return parseYAML(content);
   }).filter(Boolean);
 }
 function findRepoRoot2(startDir) {
   let current = startDir;
   while (true) {
-    if (existsSync15(join17(current, "patterns"))) {
+    if (existsSync17(join18(current, "patterns"))) {
       return current;
     }
-    const parent = join17(current, "..");
+    const parent = join18(current, "..");
     if (parent === current) return null;
     current = parent;
   }
@@ -4545,6 +5472,244 @@ Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
   );
 }
 
+// src/commands/migrate-token-substitution.ts
+import { readFileSync as readFileSync21, writeFileSync as writeFileSync11, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync18 } from "fs";
+import { resolve as resolve13, join as join19, relative as relative3 } from "path";
+import { parse as parseYaml3 } from "yaml";
+import pc4 from "picocolors";
+var V7_ENTR_SUBSTITUTION_MAP = {
+  "--panel": "--surface-card",
+  "--panel-2": "--surface-interactive-default",
+  "--panel-3": "--surface-interactive-active",
+  "--text": "--text-primary",
+  "--text-2": "--text-secondary",
+  "--text-3": "--text-tertiary",
+  "--text-4": "--text-tertiary",
+  "--mint": "--accent-primary",
+  "--mint-soft": "--surface-accent-subtle",
+  "--warn": "--text-warning",
+  "--warn-soft": "--surface-warning-subtle"
+};
+var BUILT_IN_SUBSTITUTION_MAPS = {
+  "entr": V7_ENTR_SUBSTITUTION_MAP
+  // future themes: "kaiah": KAIAH_SUBSTITUTION_MAP, etc.
+};
+var DEFAULT_THEME_ID = "entr";
+function readMapFromThemeFile(themeId, cwd) {
+  const candidates = [
+    join19(cwd, "themes", `${themeId}.visor.yaml`),
+    join19(cwd, "custom-themes", `${themeId}.visor.yaml`),
+    join19(cwd, "packages", "docs", "public", "themes", `${themeId}.visor.yaml`)
+  ];
+  for (const candidate of candidates) {
+    if (existsSync18(candidate)) {
+      try {
+        const raw = readFileSync21(candidate, "utf-8");
+        const parsed = parseYaml3(raw);
+        if (parsed?.migrate?.["token-substitution"]) {
+          return parsed.migrate["token-substitution"];
+        }
+      } catch {
+      }
+    }
+  }
+  return void 0;
+}
+function resolveSubstitutionMap(themeId, cwd) {
+  const fromYaml = readMapFromThemeFile(themeId, cwd);
+  if (fromYaml) return fromYaml;
+  return BUILT_IN_SUBSTITUTION_MAPS[themeId];
+}
+function applySubstitutionsToContent(content, map) {
+  const substitutions = [];
+  const lines2 = content.split("\n");
+  const newLines = lines2.map((line, lineIndex) => {
+    let newLine = line;
+    for (const [from, to] of Object.entries(map)) {
+      const pattern2 = new RegExp(`var\\(\\s*${escapeRegex(from)}\\s*(?:,[^)]*)?\\)`, "g");
+      let match;
+      while ((match = pattern2.exec(newLine)) !== null) {
+        const column = match.index;
+        const originalLine = line;
+        const fullMatch = match[0];
+        const replaced = fullMatch.replace(
+          new RegExp(escapeRegex(from)),
+          to
+        );
+        newLine = newLine.slice(0, match.index) + replaced + newLine.slice(match.index + fullMatch.length);
+        substitutions.push({
+          line: lineIndex + 1,
+          column,
+          from,
+          to,
+          originalLine,
+          replacedLine: newLine
+        });
+        pattern2.lastIndex = match.index + replaced.length;
+      }
+    }
+    return newLine;
+  });
+  return { newContent: newLines.join("\n"), substitutions };
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function collectCssFiles(dirPath) {
+  const results = [];
+  function walk2(current) {
+    const entries = readdirSync11(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join19(current, entry.name);
+      if (entry.isDirectory()) {
+        if (["node_modules", ".git", ".next", "dist", "build", ".cache"].includes(entry.name)) {
+          continue;
+        }
+        walk2(fullPath);
+      } else if (entry.isFile()) {
+        const name = entry.name;
+        if (name.endsWith(".module.css") || name.endsWith(".scss") || name.endsWith(".css")) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+  walk2(dirPath);
+  return results;
+}
+function runSubstitutionPass(targetPath, map, themeId) {
+  let files;
+  const stat = statSync8(targetPath);
+  if (stat.isFile()) {
+    files = [targetPath];
+  } else {
+    files = collectCssFiles(targetPath);
+  }
+  const fileResults = [];
+  let totalSubstitutions = 0;
+  for (const file of files) {
+    const content = readFileSync21(file, "utf-8");
+    const { newContent, substitutions } = applySubstitutionsToContent(content, map);
+    if (substitutions.length > 0) {
+      fileResults.push({ file, substitutions, originalContent: content, newContent });
+      totalSubstitutions += substitutions.length;
+    }
+  }
+  return {
+    themeId,
+    targetPath,
+    filesScanned: files.length,
+    filesChanged: fileResults.length,
+    totalSubstitutions,
+    files: fileResults
+  };
+}
+function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
+  const themeId = options.themeId ?? DEFAULT_THEME_ID;
+  const apply = options.apply ?? false;
+  const dryRun = !apply;
+  const map = resolveSubstitutionMap(themeId, cwd);
+  if (!map) {
+    const available = Object.keys(BUILT_IN_SUBSTITUTION_MAPS).join(", ");
+    if (options.json) {
+      console.log(JSON.stringify({
+        success: false,
+        error: `Unknown theme-id: "${themeId}". Available: ${available}`
+      }));
+      process.exit(1);
+    }
+    logger.error(`Unknown theme-id: "${themeId}". Available: ${available}`);
+    process.exit(1);
+    return;
+  }
+  const targetPath = resolve13(cwd, targetArg ?? ".");
+  try {
+    statSync8(targetPath);
+  } catch {
+    if (options.json) {
+      console.log(JSON.stringify({
+        success: false,
+        error: `Target path not found: ${targetPath}`
+      }));
+      process.exit(1);
+    }
+    logger.error(`Target path not found: ${targetPath}`);
+    process.exit(1);
+    return;
+  }
+  const result = runSubstitutionPass(targetPath, map, themeId);
+  if (result.filesChanged === 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, ...result, message: "No V7 primitives found \u2014 already up to date." }));
+      process.exit(0);
+    }
+    logger.success(`No V7 primitives found \u2014 ${result.filesScanned} file(s) scanned. Already up to date.`);
+    process.exit(0);
+    return;
+  }
+  if (options.json) {
+    if (apply) {
+      for (const f of result.files) {
+        writeFileSync11(f.file, f.newContent, "utf-8");
+      }
+      console.log(JSON.stringify({
+        success: true,
+        applied: true,
+        ...result
+      }));
+    } else {
+      console.log(JSON.stringify({
+        success: true,
+        dryRun: true,
+        ...result
+      }));
+    }
+    process.exit(0);
+    return;
+  }
+  const relTarget = relative3(cwd, targetPath) || ".";
+  if (dryRun) {
+    logger.heading(`visor migrate token-substitution \u2014 dry run`);
+    logger.blank();
+    logger.info(`  Theme:   ${pc4.bold(themeId)}`);
+    logger.info(`  Target:  ${pc4.dim(relTarget)}`);
+    logger.info(`  Scanned: ${result.filesScanned} file(s)`);
+    logger.blank();
+    logger.heading(`Proposed changes (${result.filesChanged} file(s), ${result.totalSubstitutions} substitution(s)):`);
+    logger.blank();
+    for (const f of result.files) {
+      const relFile = relative3(cwd, f.file);
+      logger.info(pc4.bold(`  ${relFile}`));
+      for (const sub of f.substitutions) {
+        logger.info(
+          `    line ${String(sub.line).padEnd(4)} ${pc4.red(`var(${sub.from})`)} \u2192 ${pc4.green(`var(${sub.to})`)}`
+        );
+      }
+      logger.blank();
+    }
+    logger.warn(`Dry run \u2014 no files written. Re-run with ${pc4.bold("--apply")} to commit changes.`);
+  } else {
+    for (const f of result.files) {
+      writeFileSync11(f.file, f.newContent, "utf-8");
+    }
+    logger.heading(`visor migrate token-substitution \u2014 applied`);
+    logger.blank();
+    logger.info(`  Theme:   ${pc4.bold(themeId)}`);
+    logger.info(`  Target:  ${pc4.dim(relTarget)}`);
+    logger.info(`  Scanned: ${result.filesScanned} file(s)`);
+    logger.blank();
+    for (const f of result.files) {
+      const relFile = relative3(cwd, f.file);
+      logger.success(`  ${relFile} (${f.substitutions.length} substitution(s))`);
+    }
+    logger.blank();
+    logger.success(
+      `Done \u2014 ${result.filesChanged} file(s) updated, ${result.totalSubstitutions} substitution(s) applied.`
+    );
+  }
+  process.exit(0);
+}
+
 // src/index.ts
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version("0.3.0");
@@ -4618,6 +5783,11 @@ theme.command("validate").description("Run full validation ruleset on a .visor.y
     themeValidateCommand(file, process.cwd(), options);
   }
 );
+theme.command("verify").description("Verify generated theme output for a target platform").argument("<dir>", "path to generated output directory").option("--target <platform>", "target platform (flutter)", "flutter").option("--json", "output structured JSON (for AI agents)").action(
+  (dir, options) => {
+    themeVerifyCommand(dir, process.cwd(), options);
+  }
+);
 theme.command("extract").description(
   "Scan an existing project's CSS and produce a best-effort .visor.yaml theme file"
 ).option("--from <path>", "path to project directory to scan").option("--json", "output structured JSON (for AI agents)").option("-o, --output <path>", "output file path (default: .visor.yaml)").option("--validate", "run validator on the extracted theme").action(
@@ -4676,4 +5846,16 @@ var tokens = program.command("tokens").description("Explore design tokens");
 tokens.command("list").description("List all design tokens").option("--json", "output as JSON (for AI agents)").option("--category <category>", "filter by tier: primitives, semantic, adaptive").action(async (options) => {
   await tokensListCommand(process.cwd(), options);
 });
+var migrate = program.command("migrate").description("Migration helpers \u2014 mechanically transform source files during design-system adoption");
+migrate.command("token-substitution").description(
+  "Apply the \xA73.1 V7-primitive \u2192 Visor-semantic substitution table across a target directory. Dry-run by default; use --apply to commit changes. Idempotent \u2014 running twice is a no-op."
+).argument("[path]", "path to file or directory to migrate (default: current directory)").option("--theme-id <id>", "theme whose substitution map to apply (default: entr)", "entr").option("--dry-run", "preview proposed changes without writing files (default when --apply is omitted)").option("--apply", "write changes to disk").option("--json", "output structured JSON (for AI agents)").action(
+  (pathArg, options) => {
+    migrateTokenSubstitutionCommand(pathArg, process.cwd(), {
+      themeId: options.themeId,
+      apply: options.apply,
+      json: options.json
+    });
+  }
+);
 program.parse();