@loworbitstudio/visor 1.14.0 → 1.15.0

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync28 } from "fs";
-import { dirname as dirname10, join as join25 } from "path";
+import { readFileSync as readFileSync32 } from "fs";
+import { dirname as dirname11, join as join30 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
@@ -1191,10 +1191,10 @@ function checkCommand() {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync4, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync7 } from "fs";
-import { join as join6, dirname as dirname3 } from "path";
+import { existsSync as existsSync6, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync9 } from "fs";
+import { join as join8, dirname as dirname4, basename as basename2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as childProcess from "child_process";
+import * as childProcess2 from "child_process";
 
 // src/config/config.ts
 import { readFileSync as readFileSync5, writeFileSync, existsSync as existsSync2 } from "fs";
@@ -1378,6 +1378,156 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 `;
 }
 
+// src/commands/init-plays/registry.ts
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync7, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, join as join6 } from "path";
+
+// src/commands/init-plays/pattern-build.ts
+var patternBuildPlay = {
+  id: "pattern-build",
+  loSubdir: "pattern-builds",
+  label: "Pattern build",
+  description: "Design + converge a reusable Borealis pattern (admin-ui, forms, ...)."
+};
+
+// src/commands/init-plays/new-web-app.ts
+var newWebAppPlay = {
+  id: "new-web-app",
+  loSubdir: "new-web-apps",
+  label: "New web app",
+  description: "A fresh NextJS app entering the Playbook lifecycle."
+};
+
+// src/commands/init-plays/feature-addition.ts
+var featureAdditionPlay = {
+  id: "feature-addition",
+  loSubdir: "feature-additions",
+  label: "Feature addition",
+  description: "An existing project onboarding into the Playbook mid-stream (safe, idempotent)."
+};
+
+// src/commands/init-plays/registry.ts
+var KNOWN_PLAYS = [
+  patternBuildPlay,
+  newWebAppPlay,
+  featureAdditionPlay
+];
+function getPlay(id) {
+  return KNOWN_PLAYS.find((p) => p.id === id);
+}
+function knownPlayIds() {
+  return KNOWN_PLAYS.map((p) => p.id);
+}
+function playStatePaths(cwd, def, name) {
+  const relDir = join6(".lo", def.loSubdir, name);
+  const dir = join6(cwd, relDir);
+  return {
+    dir,
+    statePath: join6(dir, "state.json"),
+    relStatePath: join6(relDir, "state.json")
+  };
+}
+function readPlayState(statePath) {
+  if (!existsSync4(statePath)) return null;
+  try {
+    return JSON.parse(readFileSync7(statePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function writePlayState(statePath, state) {
+  mkdirSync(dirname3(statePath), { recursive: true });
+  writeFileSync2(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+// src/lib/lo-ports-bridge.ts
+import * as childProcess from "child_process";
+var LO_PORTS_COMMAND = "lo-ports";
+var LO_PORTS_ARGS = ["next", "--json"];
+var FALLBACK_RANGE_START = 4200;
+var FALLBACK_RANGE_SIZE = 100;
+function allocatePort(name, options = {}) {
+  const runCommand = options.runCommand ?? defaultRunCommand;
+  const stdout = safeRun(runCommand);
+  const fromRegistry = stdout != null ? parsePort(stdout) : null;
+  if (fromRegistry != null) {
+    return { port: fromRegistry, source: "lo-ports" };
+  }
+  const port = heuristicPort(name);
+  return {
+    port,
+    source: "fallback",
+    warning: `Could not allocate a dev port via /lo-ports (no \`${LO_PORTS_COMMAND}\` command found). Used heuristic port ${port} instead \u2014 register it with \`/lo-ports\` when convenient.`
+  };
+}
+function safeRun(runCommand) {
+  try {
+    return runCommand();
+  } catch {
+    return null;
+  }
+}
+function defaultRunCommand() {
+  const result = childProcess.spawnSync(LO_PORTS_COMMAND, LO_PORTS_ARGS, {
+    encoding: "utf-8"
+  });
+  if (result.error) return null;
+  if (typeof result.status === "number" && result.status !== 0) return null;
+  return result.stdout ?? null;
+}
+function parsePort(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed === "number" && isValidPort(parsed)) return parsed;
+    if (parsed != null && typeof parsed === "object" && "port" in parsed && isValidPort(parsed.port)) {
+      return parsed.port;
+    }
+  } catch {
+  }
+  const bare = Number(trimmed);
+  return isValidPort(bare) ? bare : null;
+}
+function isValidPort(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 && value < 65536;
+}
+function heuristicPort(name) {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = hash * 31 + name.charCodeAt(i) >>> 0;
+  }
+  return FALLBACK_RANGE_START + hash % FALLBACK_RANGE_SIZE;
+}
+
+// src/lib/lo-play-checklist.ts
+import { existsSync as existsSync5, readFileSync as readFileSync8 } from "fs";
+import { homedir } from "os";
+import { join as join7 } from "path";
+function defaultChecklistRoot() {
+  return join7(homedir(), ".claude", "skills", "lo-play");
+}
+function readEntryChecklist(playType, options = {}) {
+  const root = options.root ?? defaultChecklistRoot();
+  const path2 = join7(root, playType, "entry-checklist.md");
+  if (!existsSync5(path2)) {
+    return {
+      found: false,
+      path: path2,
+      fallbackMessage: `Entry checklist not found at ${path2}. Run the play manually from \`/lo-play ${playType}\`.`
+    };
+  }
+  try {
+    return { found: true, path: path2, content: readFileSync8(path2, "utf-8") };
+  } catch {
+    return {
+      found: false,
+      path: path2,
+      fallbackMessage: `Entry checklist at ${path2} could not be read. Run the play manually from \`/lo-play ${playType}\`.`
+    };
+  }
+}
+
 // src/commands/init.ts
 import { generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
 import { nextjsAdapter } from "@loworbitstudio/visor-theme-engine/adapters";
@@ -1390,7 +1540,27 @@ function initCommand(cwd, options) {
     emitError(json, `Unknown template: ${options.template}. Available templates: nextjs`);
     process.exit(1);
   }
-  if (options?.template === "nextjs" && existsSync4(join6(cwd, "package.json"))) {
+  let playDef;
+  let playName = "";
+  if (options?.for) {
+    playDef = getPlay(options.for);
+    if (!playDef) {
+      emitError(
+        json,
+        `Unknown play: ${options.for}. Known plays: ${knownPlayIds().join(", ")}`
+      );
+      process.exit(1);
+    }
+    playName = options.playName ?? basename2(cwd);
+    if (!/^[a-z0-9][a-z0-9-_]*$/i.test(playName)) {
+      emitError(
+        json,
+        `Invalid play name '${playName}'. Use letters, digits, '-' or '_' (e.g. --play-name organization-management).`
+      );
+      process.exit(1);
+    }
+  }
+  if (options?.template === "nextjs" && existsSync6(join8(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"
@@ -1431,6 +1601,10 @@ function initCommand(cwd, options) {
       }
     }
   }
+  let playResult;
+  if (playDef) {
+    playResult = runPlayInit(cwd, playDef, playName, options ?? {}, json, warnings);
+  }
   if (json) {
     const nextSteps = buildNextSteps(options, warnings);
     const result = {
@@ -1438,12 +1612,91 @@ function initCommand(cwd, options) {
       config: DEFAULT_CONFIG,
       files: { created: filesCreated, skipped: filesSkipped },
       warnings,
-      nextSteps
+      nextSteps,
+      ...playResult ? { play: playResult } : {}
     };
     console.log(JSON.stringify(result, null, 2));
     process.exit(0);
   }
 }
+function runPlayInit(cwd, def, name, options, json, warnings) {
+  const { statePath, relStatePath } = playStatePaths(cwd, def, name);
+  const existing = readPlayState(statePath);
+  const checklist = readEntryChecklist(def.id);
+  if (existing) {
+    if (!json) {
+      logger.blank();
+      logger.warn(
+        `Play '${def.id}' / '${name}' already initialized at ${relStatePath} (phase ${existing.phase}${existing.devPort ? `, port ${existing.devPort}` : ""}). Nothing to do.`
+      );
+      printChecklist(def.id, checklist);
+    }
+    return {
+      play: def.id,
+      name,
+      statePath: relStatePath,
+      phase: existing.phase,
+      devPort: existing.devPort,
+      portSource: existing.portSource,
+      theme: existing.theme,
+      from: existing.from,
+      alreadyInitialized: true,
+      checklist: { found: checklist.found, path: checklist.path }
+    };
+  }
+  const port = allocatePort(name);
+  if (port.warning) warnings.push(port.warning);
+  const state = {
+    play: def.id,
+    name,
+    phase: 0,
+    ...options.theme ? { theme: options.theme } : {},
+    ...options.from ? { from: options.from } : {},
+    devPort: port.port,
+    portSource: port.source,
+    createdWith: `@loworbitstudio/visor@${readVisorCliVersion()}`,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writePlayState(statePath, state);
+  if (!json) {
+    logger.blank();
+    if (options.template === "nextjs") {
+      logger.success("Visor scaffold: NextJS + tokens + FOWT layout");
+    }
+    logger.success(`Playbook state: ${relStatePath} (phase 0)`);
+    if (port.source === "lo-ports") {
+      logger.success(`Dev port allocated: ${port.port} (via /lo-ports)`);
+    } else {
+      logger.warn(port.warning ?? `Dev port ${port.port} (heuristic fallback)`);
+      logger.success(`Dev port: ${port.port} (heuristic fallback)`);
+    }
+    if (options.theme) logger.success(`Theme recorded: ${options.theme}`);
+    printChecklist(def.id, checklist);
+  }
+  return {
+    play: def.id,
+    name,
+    statePath: relStatePath,
+    phase: 0,
+    devPort: port.port,
+    portSource: port.source,
+    theme: options.theme,
+    from: options.from,
+    alreadyInitialized: false,
+    checklist: { found: checklist.found, path: checklist.path }
+  };
+}
+function printChecklist(playId, checklist) {
+  logger.blank();
+  if (checklist.found) {
+    logger.info(`Next steps (from ${checklist.path}):`);
+    for (const line of checklist.content.split("\n")) {
+      logger.item(line);
+    }
+  } else {
+    logger.warn(checklist.fallbackMessage);
+  }
+}
 function buildNextSteps(options, warnings) {
   const steps = [];
   if (options?.template === "nextjs") {
@@ -1473,14 +1726,14 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   }
   runCreateNextApp(cwd, json);
   runInstallVisorDeps(cwd, json);
-  const yamlPath = join6(cwd, ".visor.yaml");
-  if (existsSync4(yamlPath)) {
+  const yamlPath = join8(cwd, ".visor.yaml");
+  if (existsSync6(yamlPath)) {
     filesSkipped.push(".visor.yaml");
     if (!json) {
       logger.warn(".visor.yaml already exists. Skipping.");
     }
   } else {
-    writeFileSync2(yamlPath, NEXTJS_STARTER_YAML, "utf-8");
+    writeFileSync3(yamlPath, NEXTJS_STARTER_YAML, "utf-8");
     filesCreated.push(".visor.yaml");
     if (!json) {
       logger.success("Created .visor.yaml");
@@ -1492,40 +1745,40 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
     tokens: data.tokens,
     config: data.config
   });
-  const globalsPath = join6(cwd, "app", "globals.css");
-  const globalsDir = dirname3(globalsPath);
-  mkdirSync(globalsDir, { recursive: true });
-  if (existsSync4(globalsPath)) {
-    writeFileSync2(globalsPath, css, "utf-8");
+  const globalsPath = join8(cwd, "app", "globals.css");
+  const globalsDir = dirname4(globalsPath);
+  mkdirSync2(globalsDir, { recursive: true });
+  if (existsSync6(globalsPath)) {
+    writeFileSync3(globalsPath, css, "utf-8");
     filesCreated.push("app/globals.css");
   } else {
-    writeFileSync2(globalsPath, css, "utf-8");
+    writeFileSync3(globalsPath, css, "utf-8");
     filesCreated.push("app/globals.css");
   }
   if (!json) {
     logger.success("Created app/globals.css with theme tokens");
   }
-  const layoutPath = join6(cwd, "app", "layout.tsx");
+  const layoutPath = join8(cwd, "app", "layout.tsx");
   const colorScheme = extractColorScheme(NEXTJS_STARTER_YAML);
-  writeFileSync2(layoutPath, generateNextjsLayout(colorScheme), "utf-8");
+  writeFileSync3(layoutPath, generateNextjsLayout(colorScheme), "utf-8");
   filesCreated.push("app/layout.tsx");
   if (!json) {
     logger.success("Wired app/layout.tsx with FOWT prevention and theme tokens");
   }
-  const stampDir = join6(cwd, ".lo");
-  const stampPath = join6(stampDir, "borealis.json");
-  if (existsSync4(stampPath)) {
+  const stampDir = join8(cwd, ".lo");
+  const stampPath = join8(stampDir, "borealis.json");
+  if (existsSync6(stampPath)) {
     filesSkipped.push(".lo/borealis.json");
     if (!json) {
       logger.warn(".lo/borealis.json already exists. Skipping.");
     }
   } else {
-    mkdirSync(stampDir, { recursive: true });
+    mkdirSync2(stampDir, { recursive: true });
     const stamp = {
       visorVersion: readVisorCliVersion(),
       initializedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    writeFileSync2(stampPath, JSON.stringify(stamp, null, 2) + "\n", "utf-8");
+    writeFileSync3(stampPath, JSON.stringify(stamp, null, 2) + "\n", "utf-8");
     filesCreated.push(".lo/borealis.json");
     if (!json) {
       logger.success("Stamped .lo/borealis.json");
@@ -1546,7 +1799,7 @@ function runCreateNextApp(cwd, json) {
   if (!json) {
     logger.info(`Running create-next-app@${NEXTJS_PINNED_VERSION}...`);
   }
-  const result = childProcess.spawnSync(
+  const result = childProcess2.spawnSync(
     "npx",
     [`create-next-app@${NEXTJS_PINNED_VERSION}`, ".", ...CREATE_NEXT_APP_FLAGS],
     { cwd, stdio: json ? "ignore" : "inherit" }
@@ -1557,7 +1810,7 @@ function runInstallVisorDeps(cwd, json) {
   if (!json) {
     logger.info("Installing @loworbitstudio/visor-core and visor-theme-engine...");
   }
-  const result = childProcess.spawnSync(
+  const result = childProcess2.spawnSync(
     "npm",
     [
       "install",
@@ -1578,12 +1831,12 @@ function assertSpawnSuccess(result, label) {
 }
 function readVisorCliVersion() {
   try {
-    const here = dirname3(fileURLToPath2(import.meta.url));
+    const here = dirname4(fileURLToPath2(import.meta.url));
     for (let i = 0; i < 5; i++) {
       const segments = new Array(i).fill("..");
-      const candidate = join6(here, ...segments, "package.json");
+      const candidate = join8(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync7(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync9(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) {
           return pkg2.version;
         }
@@ -1597,53 +1850,53 @@ function readVisorCliVersion() {
 
 // src/utils/fs.ts
 import {
-  writeFileSync as writeFileSync3,
-  readFileSync as readFileSync8,
-  existsSync as existsSync5,
-  mkdirSync as mkdirSync2
+  writeFileSync as writeFileSync4,
+  readFileSync as readFileSync10,
+  existsSync as existsSync7,
+  mkdirSync as mkdirSync3
 } from "fs";
-import { dirname as dirname4, join as join7 } from "path";
+import { dirname as dirname5, join as join9 } from "path";
 function resolveOutputPath(registryPath, type, config, cwd) {
   let relativePath;
   if (type === "registry:block") {
     relativePath = registryPath.replace(/^blocks\//, "");
-    return join7(cwd, config.paths.blocks, relativePath);
+    return join9(cwd, config.paths.blocks, relativePath);
   }
   if (type === "registry:ui") {
     if (registryPath.startsWith("components/deck/")) {
       relativePath = registryPath.replace(/^components\/deck\//, "");
-      return join7(cwd, config.paths.deckComponents, relativePath);
+      return join9(cwd, config.paths.deckComponents, relativePath);
     }
     if (registryPath.startsWith("components/flutter/")) {
       relativePath = registryPath.replace(/^components\/flutter\//, "");
-      return join7(cwd, config.paths.flutterComponents, relativePath);
+      return join9(cwd, config.paths.flutterComponents, relativePath);
     }
     relativePath = registryPath.replace(/^components\/ui\//, "");
-    return join7(cwd, config.paths.components, relativePath);
+    return join9(cwd, config.paths.components, relativePath);
   }
   if (type === "registry:hook") {
     relativePath = registryPath.replace(/^hooks\//, "");
-    return join7(cwd, config.paths.hooks, relativePath);
+    return join9(cwd, config.paths.hooks, relativePath);
   }
   if (type === "registry:lib") {
     relativePath = registryPath.replace(/^lib\//, "");
-    return join7(cwd, config.paths.lib, relativePath);
+    return join9(cwd, config.paths.lib, relativePath);
   }
-  return join7(cwd, registryPath);
+  return join9(cwd, registryPath);
 }
 function writeFile(filePath, content) {
-  const dir = dirname4(filePath);
-  if (!existsSync5(dir)) {
-    mkdirSync2(dir, { recursive: true });
+  const dir = dirname5(filePath);
+  if (!existsSync7(dir)) {
+    mkdirSync3(dir, { recursive: true });
   }
-  writeFileSync3(filePath, content, "utf-8");
+  writeFileSync4(filePath, content, "utf-8");
 }
 function readFile(filePath) {
-  if (!existsSync5(filePath)) return null;
-  return readFileSync8(filePath, "utf-8");
+  if (!existsSync7(filePath)) return null;
+  return readFileSync10(filePath, "utf-8");
 }
 function fileExists(filePath) {
-  return existsSync5(filePath);
+  return existsSync7(filePath);
 }
 
 // src/commands/list.ts
@@ -1784,8 +2037,8 @@ function listCommand(cwd, options = {}) {
 }
 
 // src/utils/pubspec.ts
-import { existsSync as existsSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
+import { join as join10 } from "path";
 import { parseDocument, YAMLMap } from "yaml";
 function mergePubspec(pubspecText, deps) {
   const doc = parseDocument(pubspecText);
@@ -1807,14 +2060,14 @@ function mergePubspec(pubspecText, deps) {
   return { text: doc.toString(), added, skipped };
 }
 function pubspecPath(cwd) {
-  return join8(cwd, "pubspec.yaml");
+  return join10(cwd, "pubspec.yaml");
 }
 function pubspecExists(cwd) {
-  return existsSync6(pubspecPath(cwd));
+  return existsSync8(pubspecPath(cwd));
 }
 function isPubPackageInstalled(packageName, cwd) {
   if (!pubspecExists(cwd)) return false;
-  const text = readFileSync9(pubspecPath(cwd), "utf-8");
+  const text = readFileSync11(pubspecPath(cwd), "utf-8");
   const doc = parseDocument(text);
   const depsNode = doc.get("dependencies");
   if (!(depsNode instanceof YAMLMap)) return false;
@@ -1825,24 +2078,24 @@ function getUninstalledPubDeps(deps, cwd) {
 }
 function addPubDependencies(deps, cwd) {
   const path2 = pubspecPath(cwd);
-  if (!existsSync6(path2)) {
+  if (!existsSync8(path2)) {
     throw new Error(
       `No pubspec.yaml found at ${path2}. Run this command from a Flutter project root.`
     );
   }
-  const text = readFileSync9(path2, "utf-8");
+  const text = readFileSync11(path2, "utf-8");
   const result = mergePubspec(text, deps);
   if (result.added.length > 0) {
-    writeFileSync4(path2, result.text, "utf-8");
+    writeFileSync5(path2, result.text, "utf-8");
   }
   return result;
 }
 
 // src/utils/flutter.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import { existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
-import { homedir } from "os";
-import { join as join9 } from "path";
+import { existsSync as existsSync9, readdirSync as readdirSync3, statSync as statSync4 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join11 } from "path";
 function isExecutable(path2) {
   try {
     const s = statSync4(path2);
@@ -1857,20 +2110,20 @@ function fromPath(env) {
   const bin = process.platform === "win32" ? "flutter.bat" : "flutter";
   for (const dir of pathVar.split(sep2)) {
     if (!dir) continue;
-    const candidate = join9(dir, bin);
+    const candidate = join11(dir, bin);
     if (isExecutable(candidate)) return candidate;
   }
   return null;
 }
 function fromFvm(home) {
-  const fvmDefault = join9(home, "fvm", "default", "bin", "flutter");
+  const fvmDefault = join11(home, "fvm", "default", "bin", "flutter");
   if (isExecutable(fvmDefault)) return fvmDefault;
-  const versionsDir = join9(home, "fvm", "versions");
-  if (!existsSync7(versionsDir)) return null;
+  const versionsDir = join11(home, "fvm", "versions");
+  if (!existsSync9(versionsDir)) return null;
   let best = null;
   try {
     for (const name of readdirSync3(versionsDir)) {
-      const candidate = join9(versionsDir, name, "bin", "flutter");
+      const candidate = join11(versionsDir, name, "bin", "flutter");
       if (!isExecutable(candidate)) continue;
       if (!best || compareSemver(name, best.version) > 0) {
         best = { version: name, path: candidate };
@@ -1893,10 +2146,10 @@ function compareSemver(a, b) {
 }
 function findFlutterBin(options = {}) {
   const env = options.env ?? process.env;
-  const home = options.home ?? homedir();
+  const home = options.home ?? homedir2();
   const envRoot = env.FLUTTER_ROOT;
   if (envRoot) {
-    const bin = join9(envRoot, "bin", "flutter");
+    const bin = join11(envRoot, "bin", "flutter");
     if (isExecutable(bin)) return bin;
   }
   const fromPathBin = fromPath(env);
@@ -2539,8 +2792,8 @@ function infoCommand(name, cwd, options = {}) {
 }
 
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
-import { resolve as resolve5, dirname as dirname5, join as join10 } from "path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4 } from "fs";
+import { resolve as resolve5, dirname as dirname6, join as join12 } from "path";
 import { generateTheme, generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
@@ -2573,7 +2826,7 @@ function themeApplyCommand(file, cwd, options) {
   const filePath = resolve5(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync10(filePath, "utf-8");
+    yamlContent = readFileSync12(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2655,12 +2908,12 @@ function themeApplyCommand(file, cwd, options) {
   const outputPath = resolve5(cwd, outputTarget);
   if (fileMap) {
     try {
-      mkdirSync3(outputPath, { recursive: true });
+      mkdirSync4(outputPath, { recursive: true });
       let totalBytes = 0;
       for (const [relPath, content] of Object.entries(fileMap.files)) {
-        const filePath2 = join10(outputPath, relPath);
-        mkdirSync3(dirname5(filePath2), { recursive: true });
-        writeFileSync5(filePath2, content, "utf-8");
+        const filePath2 = join12(outputPath, relPath);
+        mkdirSync4(dirname6(filePath2), { recursive: true });
+        writeFileSync6(filePath2, content, "utf-8");
         totalBytes += content.length;
       }
       if (options.json) {
@@ -2697,10 +2950,10 @@ function themeApplyCommand(file, cwd, options) {
   if (css === null) {
     process.exit(1);
   }
-  const outputDir = dirname5(outputPath);
+  const outputDir = dirname6(outputPath);
   try {
-    mkdirSync3(outputDir, { recursive: true });
-    writeFileSync5(outputPath, css, "utf-8");
+    mkdirSync4(outputDir, { recursive: true });
+    writeFileSync6(outputPath, css, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2741,7 +2994,7 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync11 } from "fs";
+import { readFileSync as readFileSync13 } from "fs";
 import { resolve as resolve6 } from "path";
 import {
   parseConfig,
@@ -2753,7 +3006,7 @@ function themeExportCommand(file, cwd, options) {
   const filePath = resolve6(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync11(filePath, "utf-8");
+    yamlContent = readFileSync13(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2805,7 +3058,7 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync14 } from "fs";
 import { resolve as resolve7 } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
@@ -2814,7 +3067,7 @@ function themeValidateCommand(file, cwd, options) {
   const filePath = resolve7(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync12(filePath, "utf-8");
+    fileContent = readFileSync14(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2903,7 +3156,7 @@ function printIssue(issue) {
 
 // src/commands/theme-verify.ts
 import { spawnSync as _spawnSync } from "child_process";
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 import { resolve as resolve8 } from "path";
 function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
   const target = options.target ?? "flutter";
@@ -2927,7 +3180,7 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
     process.exit(1);
   }
   const dirPath = resolve8(cwd, dir);
-  if (!existsSync8(dirPath)) {
+  if (!existsSync10(dirPath)) {
     if (options.json) {
       console.log(
         JSON.stringify({
@@ -3014,8 +3267,8 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
 }
 
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync6, existsSync as existsSync9, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
-import { resolve as resolve9, join as join11, basename as basename2, extname as extname3, relative } from "path";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync7, existsSync as existsSync11, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
+import { resolve as resolve9, join as join13, basename as basename3, extname as extname3, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -3045,7 +3298,7 @@ var CSS_DIRS = [
 ];
 function themeExtractCommand(cwd, options) {
   const targetDir = resolve9(cwd, options.from ?? ".");
-  if (!existsSync9(targetDir)) {
+  if (!existsSync11(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
     } else {
@@ -3099,16 +3352,16 @@ function collectCSSFiles(targetDir) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
   for (const pattern2 of CSS_FILE_PATTERNS) {
-    const rootPath = join11(targetDir, pattern2);
+    const rootPath = join13(targetDir, pattern2);
     addFileIfExists(rootPath, files, seen);
     for (const dir of CSS_DIRS) {
-      const dirPath = join11(targetDir, dir, pattern2);
+      const dirPath = join13(targetDir, dir, pattern2);
       addFileIfExists(dirPath, files, seen);
     }
   }
   for (const dir of CSS_DIRS) {
-    const dirPath = join11(targetDir, dir);
-    if (existsSync9(dirPath) && statSync5(dirPath).isDirectory()) {
+    const dirPath = join13(targetDir, dir);
+    if (existsSync11(dirPath) && statSync5(dirPath).isDirectory()) {
       scanDirForCSS(dirPath, files, seen, 2);
     }
   }
@@ -3118,9 +3371,9 @@ function collectCSSFiles(targetDir) {
 function addFileIfExists(filePath, files, seen) {
   const resolved = resolve9(filePath);
   if (seen.has(resolved)) return;
-  if (!existsSync9(resolved)) return;
+  if (!existsSync11(resolved)) return;
   try {
-    const content = readFileSync13(resolved, "utf-8");
+    const content = readFileSync15(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -3129,7 +3382,7 @@ function addFileIfExists(filePath, files, seen) {
   }
 }
 function scanDirForCSS(dir, files, seen, maxDepth) {
-  if (!existsSync9(dir)) return;
+  if (!existsSync11(dir)) return;
   const SKIP_DIRS = /* @__PURE__ */ new Set([
     "node_modules",
     ".next",
@@ -3148,10 +3401,10 @@ function scanDirForCSS(dir, files, seen, maxDepth) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
         if (maxDepth > 0) {
-          scanDirForCSS(join11(dir, entry.name), files, seen, maxDepth - 1);
+          scanDirForCSS(join13(dir, entry.name), files, seen, maxDepth - 1);
         }
       } else if (entry.isFile() && extname3(entry.name) === ".css") {
-        addFileIfExists(join11(dir, entry.name), files, seen);
+        addFileIfExists(join13(dir, entry.name), files, seen);
       }
     }
   } catch {
@@ -3233,10 +3486,10 @@ function extractVarName(varExpr) {
 function parseNextFontFromLayouts(targetDir) {
   const fontMap = /* @__PURE__ */ new Map();
   for (const relPath of LAYOUT_FILE_PATHS) {
-    const fullPath = join11(targetDir, relPath);
-    if (!existsSync9(fullPath)) continue;
+    const fullPath = join13(targetDir, relPath);
+    if (!existsSync11(fullPath)) continue;
     try {
-      const content = readFileSync13(fullPath, "utf-8");
+      const content = readFileSync15(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -3283,7 +3536,7 @@ function parseNextFontDeclarations(content, fontMap) {
       const srcMatch = block.match(/src\s*:\s*["']([^"']+)["']/);
       if (srcMatch) {
         const srcPath = srcMatch[1];
-        const fileName = basename2(srcPath, extname3(srcPath));
+        const fileName = basename3(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);
@@ -3321,10 +3574,10 @@ var MONO_FONT_NAMES = /* @__PURE__ */ new Set([
   "IBM Plex Mono"
 ]);
 function extractFontHints(targetDir) {
-  const pkgPath = join11(targetDir, "package.json");
-  if (!existsSync9(pkgPath)) return void 0;
+  const pkgPath = join13(targetDir, "package.json");
+  if (!existsSync11(pkgPath)) return void 0;
   try {
-    const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+    const pkg2 = JSON.parse(readFileSync15(pkgPath, "utf-8"));
     const allDeps = { ...pkg2.dependencies, ...pkg2.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -3360,10 +3613,10 @@ function extractFontHints(targetDir) {
   }
 }
 function inferThemeName(targetDir) {
-  const pkgPath = join11(targetDir, "package.json");
-  if (existsSync9(pkgPath)) {
+  const pkgPath = join13(targetDir, "package.json");
+  if (existsSync11(pkgPath)) {
     try {
-      const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+      const pkg2 = JSON.parse(readFileSync15(pkgPath, "utf-8"));
       if (pkg2.name) {
         const name = pkg2.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -3371,7 +3624,7 @@ function inferThemeName(targetDir) {
     } catch {
     }
   }
-  return `${basename2(targetDir)}-theme`;
+  return `${basename3(targetDir)}-theme`;
 }
 function confidenceComment(confidence) {
   return `# confidence: ${confidence}`;
@@ -3428,7 +3681,7 @@ function outputYAML(result, outputPath, cwd, validationResult) {
     }
     logger.blank();
   }
-  writeFileSync6(outFile, yamlStr, "utf-8");
+  writeFileSync7(outFile, yamlStr, "utf-8");
   logger.success(`Theme written to ${relative(cwd, outFile)}`);
   if (validationResult) {
     logger.blank();
@@ -3486,14 +3739,14 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync15, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync11 } from "fs";
-import { resolve as resolve11, join as join13 } from "path";
+import { readFileSync as readFileSync17, writeFileSync as writeFileSync8, mkdirSync as mkdirSync5, existsSync as existsSync13 } from "fs";
+import { resolve as resolve11, join as join15 } from "path";
 import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
-import { existsSync as existsSync10, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync14, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
-import { resolve as resolve10, dirname as dirname6, join as join12 } from "path";
+import { existsSync as existsSync12, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync16, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
+import { resolve as resolve10, dirname as dirname7, join as join14 } from "path";
 import { execFileSync as execFileSync3 } from "child_process";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
@@ -3504,10 +3757,10 @@ function toLabel(name) {
 function findRepoRoot(startDir) {
   let current = resolve10(startDir);
   while (true) {
-    if (existsSync10(join12(current, "packages", "docs"))) {
+    if (existsSync12(join14(current, "packages", "docs"))) {
       return current;
     }
-    const parent = dirname6(current);
+    const parent = dirname7(current);
     if (parent === current) break;
     current = parent;
   }
@@ -3522,8 +3775,8 @@ function findMainRepoRoot(startDir) {
     }).trim();
     if (commonDir) {
       const absoluteCommonDir = resolve10(startDir, commonDir);
-      const candidate = dirname6(absoluteCommonDir);
-      if (existsSync10(join12(candidate, "packages", "docs"))) {
+      const candidate = dirname7(absoluteCommonDir);
+      if (existsSync12(join14(candidate, "packages", "docs"))) {
         return candidate;
       }
     }
@@ -3542,10 +3795,10 @@ var BrokenSymlinkError = class extends Error {
   code = "BROKEN_SYMLINK";
 };
 function assertNoBrokenSymlinks(dir) {
-  if (!existsSync10(dir)) return;
+  if (!existsSync12(dir)) return;
   const entries = readdirSync5(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const entryPath = join12(dir, entry.name);
+    const entryPath = join14(dir, entry.name);
     let lst;
     try {
       lst = lstatSync(entryPath);
@@ -3563,27 +3816,27 @@ function assertNoBrokenSymlinks(dir) {
   }
 }
 function scanParentForPrivateThemes(parentDir) {
-  if (!existsSync10(parentDir)) return [];
+  if (!existsSync12(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)) {
+    const candidate = join14(parentDir, entry.name, "visor-themes-private", "themes");
+    if (existsSync12(candidate)) {
       matches.push(candidate);
     }
   }
   return matches.sort();
 }
 function scanNestedThemeDir(dir) {
-  if (!existsSync10(dir)) return [];
+  if (!existsSync12(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)) {
+    const themeFile = join14(dir, entry.name, "theme.visor.yaml");
+    if (existsSync12(themeFile)) {
       out.push({ filePath: themeFile, slug: entry.name });
     }
   }
@@ -3592,10 +3845,10 @@ function scanNestedThemeDir(dir) {
 function detectVisorWorkspace(cwd) {
   let current = resolve10(cwd);
   while (true) {
-    const pkgPath = join12(current, "package.json");
-    if (existsSync10(pkgPath)) {
+    const pkgPath = join14(current, "package.json");
+    if (existsSync12(pkgPath)) {
       try {
-        const pkg2 = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync16(pkgPath, "utf-8"));
         const workspaces = pkg2.workspaces ?? [];
         const hasCli = workspaces.some((w) => w.includes("packages/cli"));
         const hasEngine = workspaces.some((w) => w.includes("packages/theme-engine"));
@@ -3605,7 +3858,7 @@ function detectVisorWorkspace(cwd) {
       } catch {
       }
     }
-    const parent = dirname6(current);
+    const parent = dirname7(current);
     if (parent === current) break;
     current = parent;
   }
@@ -3613,7 +3866,7 @@ function detectVisorWorkspace(cwd) {
 }
 function isLocalVisorBinary(workspaceRoot, scriptPath) {
   if (!scriptPath) return false;
-  const expectedPrefix = join12(workspaceRoot, "packages", "cli", "dist");
+  const expectedPrefix = join14(workspaceRoot, "packages", "cli", "dist");
   let resolvedScript;
   let resolvedPrefix;
   try {
@@ -3717,7 +3970,7 @@ function themeRegisterCommand(file, cwd, options) {
   const filePath = resolve11(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync15(filePath, "utf-8");
+    yamlContent = readFileSync17(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -3760,11 +4013,11 @@ function themeRegisterCommand(file, 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 (!existsSync11(docsAppDir)) {
+  const docsAppDir = join15(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join15(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join15(docsAppDir, "globals.css");
+  const themeConfigPath = join15(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync13(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -3777,8 +4030,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync15(globalsPath, "utf-8");
-    themeConfigContent = readFileSync15(themeConfigPath, "utf-8");
+    globalsContent = readFileSync17(globalsPath, "utf-8");
+    themeConfigContent = readFileSync17(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3789,8 +4042,8 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync11(cssFilePath);
-  const cssChanged = !cssExists || readFileSync15(cssFilePath, "utf-8") !== css;
+  const cssExists = existsSync13(cssFilePath);
+  const cssChanged = !cssExists || readFileSync17(cssFilePath, "utf-8") !== css;
   const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
@@ -3833,14 +4086,14 @@ function themeRegisterCommand(file, cwd, options) {
   }
   try {
     if (cssChanged) {
-      mkdirSync4(docsAppDir, { recursive: true });
-      writeFileSync7(cssFilePath, css, "utf-8");
+      mkdirSync5(docsAppDir, { recursive: true });
+      writeFileSync8(cssFilePath, css, "utf-8");
     }
     if (globalsChanged) {
-      writeFileSync7(globalsPath, newGlobals, "utf-8");
+      writeFileSync8(globalsPath, newGlobals, "utf-8");
     }
     if (themeConfigChanged) {
-      writeFileSync7(themeConfigPath, newThemeConfig, "utf-8");
+      writeFileSync8(themeConfigPath, newThemeConfig, "utf-8");
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -3874,8 +4127,8 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync16, writeFileSync as writeFileSync8, existsSync as existsSync12, unlinkSync } from "fs";
-import { join as join14 } from "path";
+import { readFileSync as readFileSync18, writeFileSync as writeFileSync9, existsSync as existsSync14, unlinkSync } from "fs";
+import { join as join16 } from "path";
 function removeGlobalsImport(content, slug2) {
   const importLine = `@import './${slug2}-theme.css';`;
   if (!content.includes(importLine)) {
@@ -3907,11 +4160,11 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  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 docsAppDir = join16(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join16(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join16(docsAppDir, "globals.css");
+  const themeConfigPath = join16(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync14(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -3924,8 +4177,8 @@ function themeUnregisterCommand(slug2, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync16(globalsPath, "utf-8");
-    themeConfigContent = readFileSync16(themeConfigPath, "utf-8");
+    globalsContent = readFileSync18(globalsPath, "utf-8");
+    themeConfigContent = readFileSync18(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3936,7 +4189,7 @@ function themeUnregisterCommand(slug2, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync12(cssFilePath);
+  const cssExists = existsSync14(cssFilePath);
   const { updated: newGlobals, changed: globalsChanged } = removeGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged } = removeThemeConfigEntry(themeConfigContent, slug2);
   if (!cssExists && !globalsChanged && !themeConfigChanged) {
@@ -3949,8 +4202,8 @@ function themeUnregisterCommand(slug2, cwd, options) {
   }
   try {
     if (cssExists) unlinkSync(cssFilePath);
-    if (globalsChanged) writeFileSync8(globalsPath, newGlobals, "utf-8");
-    if (themeConfigChanged) writeFileSync8(themeConfigPath, newThemeConfig, "utf-8");
+    if (globalsChanged) writeFileSync9(globalsPath, newGlobals, "utf-8");
+    if (themeConfigChanged) writeFileSync9(themeConfigPath, newThemeConfig, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
     if (options.json) {
@@ -3977,15 +4230,15 @@ function themeUnregisterCommand(slug2, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync17,
-  writeFileSync as writeFileSync9,
-  mkdirSync as mkdirSync5,
-  existsSync as existsSync13,
+  readFileSync as readFileSync19,
+  writeFileSync as writeFileSync10,
+  mkdirSync as mkdirSync6,
+  existsSync as existsSync15,
   readdirSync as readdirSync6,
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join15, basename as basename3, resolve as resolve12, sep, relative as relative2 } from "path";
+import { join as join17, basename as basename4, resolve as resolve12, sep, relative as relative2 } from "path";
 import { parse as parseYaml3 } from "yaml";
 import { generateThemeData as generateThemeData5, validateFontCoverage, formatFontCoverageError } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
@@ -3999,9 +4252,9 @@ var CUSTOM_OVERLAY_CSS_PATH = "packages/docs/app/custom-themes.generated.css";
 var CUSTOM_OVERLAY_TS_PATH = "packages/docs/lib/theme-config.custom.generated.ts";
 var CUSTOM_OVERLAY_IMPORT_LINE = "@import './custom-themes.generated.css';";
 function scanThemeDir(dir) {
-  if (!existsSync13(dir)) return [];
+  if (!existsSync15(dir)) return [];
   assertNoBrokenSymlinks(dir);
-  return readdirSync6(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join15(dir, f));
+  return readdirSync6(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join17(dir, f));
 }
 function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   const merged = /* @__PURE__ */ new Map();
@@ -4026,19 +4279,19 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   const envPath = process.env[PRIVATE_THEMES_ENV_VAR];
   if (envPath && envPath.trim() !== "") {
     const resolved = resolve12(envPath);
-    if (!existsSync13(resolved)) {
+    if (!existsSync15(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);
+  const siblingPath = join17(mainRepoRoot, "..", "visor-themes-private", "themes");
+  const siblingExists = existsSync15(siblingPath);
   if (siblingExists) {
     addNested(siblingPath, "sibling");
   }
-  const parentDir = join15(mainRepoRoot, "..");
+  const parentDir = join17(mainRepoRoot, "..");
   const parentGlobMatches = scanParentForPrivateThemes(parentDir).filter(
     (path2) => !path2.startsWith(mainRepoRoot + sep)
   );
@@ -4059,10 +4312,10 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
       }
     }
   }
-  const legacyDir = join15(repoRoot, "custom-themes");
+  const legacyDir = join17(repoRoot, "custom-themes");
   const legacyFiles = scanThemeDir(legacyDir);
   for (const legacyFile of legacyFiles) {
-    const slug2 = basename3(legacyFile).replace(/\.visor\.yaml$/, "");
+    const slug2 = basename4(legacyFile).replace(/\.visor\.yaml$/, "");
     const existing = merged.get(slug2);
     if (existing) {
       warn(
@@ -4116,14 +4369,14 @@ function reportBrokenSymlink(err, options) {
   }
 }
 function buildEmptySourcesMessage(mainRepoRoot) {
-  const expectedSibling = join15(mainRepoRoot, "..", "visor-themes-private");
+  const expectedSibling = join17(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)`,
+    `  3. One-level-deeper at ${join17(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:",
@@ -4328,14 +4581,14 @@ function themeSyncCommand(cwd, options) {
     return;
   }
   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);
+  const themesDir = join17(repoRoot, "themes");
+  const docsAppDir = join17(repoRoot, "packages", "docs", "app");
+  const docsLibDir = join17(repoRoot, "packages", "docs", "lib");
+  const docsPublicThemesDir = join17(repoRoot, "packages", "docs", "public", "themes");
+  const themeConfigPath = join17(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const globalsPath = join17(docsAppDir, "globals.css");
+  const customOverlayCssPath = join17(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
+  const customOverlayTsPath = join17(repoRoot, CUSTOM_OVERLAY_TS_PATH);
   let stockFiles;
   try {
     stockFiles = scanThemeDir(themesDir);
@@ -4392,7 +4645,7 @@ function themeSyncCommand(cwd, options) {
   const processFile = (filePath, isCustom, slugOverride) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync17(filePath, "utf-8");
+      yamlContent = readFileSync19(filePath, "utf-8");
     } catch {
       failures.push({ filePath, error: `Could not read: ${filePath}` });
       return;
@@ -4403,7 +4656,7 @@ function themeSyncCommand(cwd, options) {
     } catch (err) {
       failures.push({
         filePath,
-        error: `Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
+        error: `Failed to parse ${basename4(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
       });
       return;
     }
@@ -4417,12 +4670,12 @@ function themeSyncCommand(cwd, options) {
       for (const e of coverage.errors) {
         failures.push({
           filePath,
-          error: formatFontCoverageError(basename3(filePath), e.declaredAt, e.family)
+          error: formatFontCoverageError(basename4(filePath), e.declaredAt, e.family)
         });
       }
       return;
     }
-    const yamlFilename = slugOverride ?? basename3(filePath).replace(/\.visor\.yaml$/, "");
+    const yamlFilename = slugOverride ?? basename4(filePath).replace(/\.visor\.yaml$/, "");
     manifest.push({ slug: slug2, label, group, defaultMode, css, yamlFilename, isCustom });
   };
   for (const f of stockFiles) processFile(f, false);
@@ -4442,8 +4695,8 @@ function themeSyncCommand(cwd, options) {
   let globalsContent;
   let themeConfigContent;
   try {
-    globalsContent = readFileSync17(globalsPath, "utf-8");
-    themeConfigContent = readFileSync17(themeConfigPath, "utf-8");
+    globalsContent = readFileSync19(globalsPath, "utf-8");
+    themeConfigContent = readFileSync19(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -4458,12 +4711,12 @@ function themeSyncCommand(cwd, options) {
   const newThemeConfig = updateStockThemeConfigBlock(themeConfigContent, stockManifest);
   const newCustomOverlayCss = generateCustomOverlayCss(customManifest);
   const newCustomOverlayTs = generateCustomOverlayTs(customManifest);
-  const existingCssFiles = existsSync13(docsAppDir) ? readdirSync6(docsAppDir).filter(
+  const existingCssFiles = existsSync15(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 = existsSync13(docsPublicThemesDir) ? readdirSync6(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
+  const existingPublicYamls = existsSync15(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) {
@@ -4503,28 +4756,28 @@ function themeSyncCommand(cwd, options) {
     return;
   }
   try {
-    mkdirSync5(docsAppDir, { recursive: true });
-    mkdirSync5(docsLibDir, { recursive: true });
-    mkdirSync5(docsPublicThemesDir, { recursive: true });
+    mkdirSync6(docsAppDir, { recursive: true });
+    mkdirSync6(docsLibDir, { recursive: true });
+    mkdirSync6(docsPublicThemesDir, { recursive: true });
     for (const entry of manifest) {
-      writeFileSync9(join15(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
+      writeFileSync10(join17(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
     }
     for (const stale of staleCssFiles) {
-      unlinkSync2(join15(docsAppDir, stale));
+      unlinkSync2(join17(docsAppDir, stale));
     }
-    writeFileSync9(customOverlayCssPath, newCustomOverlayCss, "utf-8");
-    writeFileSync9(customOverlayTsPath, newCustomOverlayTs, "utf-8");
-    writeFileSync9(themeConfigPath, newThemeConfig, "utf-8");
-    writeFileSync9(globalsPath, newGlobals, "utf-8");
+    writeFileSync10(customOverlayCssPath, newCustomOverlayCss, "utf-8");
+    writeFileSync10(customOverlayTsPath, newCustomOverlayTs, "utf-8");
+    writeFileSync10(themeConfigPath, newThemeConfig, "utf-8");
+    writeFileSync10(globalsPath, newGlobals, "utf-8");
     for (const srcFile of stockFiles) {
-      copyFileSync(srcFile, join15(docsPublicThemesDir, basename3(srcFile)));
+      copyFileSync(srcFile, join17(docsPublicThemesDir, basename4(srcFile)));
     }
     for (const c of customSources) {
-      const targetName = c.origin === "legacy" ? basename3(c.filePath) : `${c.slug}.visor.yaml`;
-      copyFileSync(c.filePath, join15(docsPublicThemesDir, targetName));
+      const targetName = c.origin === "legacy" ? basename4(c.filePath) : `${c.slug}.visor.yaml`;
+      copyFileSync(c.filePath, join17(docsPublicThemesDir, targetName));
     }
     for (const stale of stalePublicYamls) {
-      unlinkSync2(join15(docsPublicThemesDir, stale));
+      unlinkSync2(join17(docsPublicThemesDir, stale));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -4577,19 +4830,19 @@ function themeSyncCommand(cwd, options) {
 
 // src/commands/theme-batch-apply-flutter.ts
 import {
-  readFileSync as readFileSync18,
-  writeFileSync as writeFileSync10,
-  mkdirSync as mkdirSync6,
-  existsSync as existsSync14,
+  readFileSync as readFileSync20,
+  writeFileSync as writeFileSync11,
+  mkdirSync as mkdirSync7,
+  existsSync as existsSync16,
   readdirSync as readdirSync7,
   rmSync
 } from "fs";
-import { join as join16, basename as basename4, dirname as dirname7 } from "path";
+import { join as join18, basename as basename5, dirname as dirname8 } from "path";
 import { generateThemeData as generateThemeData6 } from "@loworbitstudio/visor-theme-engine";
 import { flutterAdapter as flutterAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 function scanThemeDir2(dir) {
-  if (!existsSync14(dir)) return [];
-  return readdirSync7(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join16(dir, f)).sort();
+  if (!existsSync16(dir)) return [];
+  return readdirSync7(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join18(dir, f)).sort();
 }
 function slugToCamel(slug2) {
   return slug2.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
@@ -4722,9 +4975,9 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join16(repoRoot, "themes");
-  const customThemesDir = join16(repoRoot, "custom-themes");
-  const outputDir = join16(repoRoot, "packages", "visor_themes");
+  const themesDir = join18(repoRoot, "themes");
+  const customThemesDir = join18(repoRoot, "custom-themes");
+  const outputDir = join18(repoRoot, "packages", "visor_themes");
   const stockFiles = scanThemeDir2(themesDir);
   const customFiles = scanThemeDir2(customThemesDir);
   const allFiles = [...stockFiles, ...customFiles];
@@ -4745,7 +4998,7 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   for (const filePath of allFiles) {
     let yamlContent;
     try {
-      yamlContent = readFileSync18(filePath, "utf-8");
+      yamlContent = readFileSync20(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       continue;
@@ -4755,7 +5008,7 @@ function themeBatchApplyFlutterCommand(cwd, options) {
       data = generateThemeData6(yamlContent);
     } catch (err) {
       errors.push(
-        `Failed to parse ${basename4(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
+        `Failed to parse ${basename5(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
       );
       continue;
     }
@@ -4824,8 +5077,8 @@ function themeBatchApplyFlutterCommand(cwd, options) {
     return;
   }
   const slugs = processed.map((p) => p.slug);
-  const libSrcDir = join16(outputDir, "lib", "src");
-  if (existsSync14(libSrcDir)) {
+  const libSrcDir = join18(outputDir, "lib", "src");
+  if (existsSync16(libSrcDir)) {
     rmSync(libSrcDir, { recursive: true, force: true });
   }
   const packageFiles = {
@@ -4837,17 +5090,17 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   };
   let totalFiles = 0;
   for (const [relPath, content] of Object.entries(packageFiles)) {
-    const absPath = join16(outputDir, relPath);
-    mkdirSync6(dirname7(absPath), { recursive: true });
-    writeFileSync10(absPath, content, "utf-8");
+    const absPath = join18(outputDir, relPath);
+    mkdirSync7(dirname8(absPath), { recursive: true });
+    writeFileSync11(absPath, content, "utf-8");
     totalFiles++;
   }
   for (const { slug: slug2, tokenFiles } of processed) {
-    const themeBaseDir = join16(outputDir, "lib", "src", slug2);
+    const themeBaseDir = join18(outputDir, "lib", "src", slug2);
     for (const [relPath, content] of Object.entries(tokenFiles)) {
-      const absPath = join16(themeBaseDir, relPath);
-      mkdirSync6(dirname7(absPath), { recursive: true });
-      writeFileSync10(absPath, content, "utf-8");
+      const absPath = join18(themeBaseDir, relPath);
+      mkdirSync7(dirname8(absPath), { recursive: true });
+      writeFileSync11(absPath, content, "utf-8");
       totalFiles++;
     }
   }
@@ -4868,11 +5121,11 @@ function themeBatchApplyFlutterCommand(cwd, options) {
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync15, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync19 } from "fs";
-import { resolve as resolve13, basename as basename5, extname as extname4 } from "path";
+import { existsSync as existsSync17, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync21 } from "fs";
+import { resolve as resolve13, basename as basename6, extname as extname4 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
-  const name = basename5(filename, extname4(filename));
+  const name = basename6(filename, extname4(filename));
   const WEIGHT_STYLE_SUFFIXES = /* @__PURE__ */ new Set([
     "thin",
     "hairline",
@@ -4914,14 +5167,14 @@ function deriveFamilySlug(filename) {
 }
 function collectWoff2Files(inputPath) {
   const resolved = resolve13(inputPath);
-  if (!existsSync15(resolved)) {
+  if (!existsSync17(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
   const stat = statSync7(resolved);
   if (stat.isFile()) {
     if (extname4(resolved).toLowerCase() !== ".woff2") {
       throw new Error(
-        `Invalid file format: ${basename5(resolved)}. Only .woff2 files are accepted.`
+        `Invalid file format: ${basename6(resolved)}. Only .woff2 files are accepted.`
       );
     }
     return [resolved];
@@ -4943,7 +5196,7 @@ function collectWoff2Files(inputPath) {
 }
 function getNonWoff2Fonts(inputPath) {
   const resolved = resolve13(inputPath);
-  if (!existsSync15(resolved) || !statSync7(resolved).isDirectory()) {
+  if (!existsSync17(resolved) || !statSync7(resolved).isDirectory()) {
     return [];
   }
   return readdirSync8(resolved).filter((f) => {
@@ -4980,7 +5233,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync19(filePath);
+  const body = readFileSync21(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -4995,7 +5248,7 @@ async function fontsAddCommand(inputPath, options) {
   try {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
-    const familySlug = options.family ?? deriveFamilySlug(basename5(files[0]));
+    const familySlug = options.family ?? deriveFamilySlug(basename6(files[0]));
     const resolved = resolve13(inputPath);
     const nonWoff2 = statSync7(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
@@ -5015,7 +5268,7 @@ async function fontsAddCommand(inputPath, options) {
     const bucket = "visor-fonts";
     const results = [];
     for (const filePath of files) {
-      const filename = basename5(filePath);
+      const filename = basename6(filePath);
       const key = buildS3Key(org, familySlug, filename);
       if (!json) {
         logger.info(`Uploading ${filename}...`);
@@ -5284,27 +5537,27 @@ function findCssFiles(dir, maxDepth = 3) {
 }
 
 // src/utils/patterns.ts
-import { existsSync as existsSync17, readdirSync as readdirSync10, readFileSync as readFileSync21 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync19, readdirSync as readdirSync10, readFileSync as readFileSync23 } from "fs";
+import { join as join20 } from "path";
 import { parse as parseYAML } from "yaml";
 function loadPatternsFromYaml(repoRoot) {
-  const patternsDir = join18(repoRoot, "patterns");
-  if (!existsSync17(patternsDir)) return [];
+  const patternsDir = join20(repoRoot, "patterns");
+  if (!existsSync19(patternsDir)) return [];
   const files = readdirSync10(patternsDir).filter(
     (f) => f.endsWith(".visor-pattern.yaml")
   );
   return files.map((file) => {
-    const content = readFileSync21(join18(patternsDir, file), "utf-8");
+    const content = readFileSync23(join20(patternsDir, file), "utf-8");
     return parseYAML(content);
   }).filter(Boolean);
 }
 function findRepoRoot2(startDir) {
   let current = startDir;
   while (true) {
-    if (existsSync17(join18(current, "patterns"))) {
+    if (existsSync19(join20(current, "patterns"))) {
       return current;
     }
-    const parent = join18(current, "..");
+    const parent = join20(current, "..");
     if (parent === current) return null;
     current = parent;
   }
@@ -5683,8 +5936,8 @@ Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
 }
 
 // src/commands/migrate-token-substitution.ts
-import { readFileSync as readFileSync22, writeFileSync as writeFileSync11, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync18 } from "fs";
-import { resolve as resolve14, join as join19, relative as relative4 } from "path";
+import { readFileSync as readFileSync24, writeFileSync as writeFileSync12, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync20 } from "fs";
+import { resolve as resolve14, join as join21, relative as relative4 } from "path";
 import { parse as parseYaml4 } from "yaml";
 import pc4 from "picocolors";
 var V7_ENTR_SUBSTITUTION_MAP = {
@@ -5707,14 +5960,14 @@ var BUILT_IN_SUBSTITUTION_MAPS = {
 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`)
+    join21(cwd, "themes", `${themeId}.visor.yaml`),
+    join21(cwd, "custom-themes", `${themeId}.visor.yaml`),
+    join21(cwd, "packages", "docs", "public", "themes", `${themeId}.visor.yaml`)
   ];
   for (const candidate of candidates) {
-    if (existsSync18(candidate)) {
+    if (existsSync20(candidate)) {
       try {
-        const raw = readFileSync22(candidate, "utf-8");
+        const raw = readFileSync24(candidate, "utf-8");
         const parsed = parseYaml4(raw);
         if (parsed?.migrate?.["token-substitution"]) {
           return parsed.migrate["token-substitution"];
@@ -5770,7 +6023,7 @@ function collectCssFiles(dirPath) {
   function walk2(current) {
     const entries = readdirSync11(current, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join19(current, entry.name);
+      const fullPath = join21(current, entry.name);
       if (entry.isDirectory()) {
         if (["node_modules", ".git", ".next", "dist", "build", ".cache"].includes(entry.name)) {
           continue;
@@ -5798,7 +6051,7 @@ function runSubstitutionPass(targetPath, map, themeId) {
   const fileResults = [];
   let totalSubstitutions = 0;
   for (const file of files) {
-    const content = readFileSync22(file, "utf-8");
+    const content = readFileSync24(file, "utf-8");
     const { newContent, substitutions } = applySubstitutionsToContent(content, map);
     if (substitutions.length > 0) {
       fileResults.push({ file, substitutions, originalContent: content, newContent });
@@ -5860,7 +6113,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
   if (options.json) {
     if (apply) {
       for (const f of result.files) {
-        writeFileSync11(f.file, f.newContent, "utf-8");
+        writeFileSync12(f.file, f.newContent, "utf-8");
       }
       console.log(JSON.stringify({
         success: true,
@@ -5900,7 +6153,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     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");
+      writeFileSync12(f.file, f.newContent, "utf-8");
     }
     logger.heading(`visor migrate token-substitution \u2014 applied`);
     logger.blank();
@@ -5921,23 +6174,23 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
 }
 
 // src/commands/sandbox/init.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync9, readFileSync as readFileSync25, rmSync as rmSync2 } from "fs";
-import { isAbsolute as isAbsolute2, join as join22, resolve as resolve16, dirname as dirname9 } from "path";
+import { existsSync as existsSync23, mkdirSync as mkdirSync10, readFileSync as readFileSync27, rmSync as rmSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join24, resolve as resolve16, dirname as dirname10 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import * as childProcess2 from "child_process";
+import * as childProcess3 from "child_process";
 
 // src/commands/sandbox/parse-handoff.ts
-import { readFileSync as readFileSync23, existsSync as existsSync19 } from "fs";
-import { dirname as dirname8, resolve as resolve15, isAbsolute } from "path";
+import { readFileSync as readFileSync25, existsSync as existsSync21 } from "fs";
+import { dirname as dirname9, resolve as resolve15, isAbsolute } from "path";
 function parseHandoff(handoffPath) {
-  const text = readFileSync23(handoffPath, "utf-8");
+  const text = readFileSync25(handoffPath, "utf-8");
   const lines2 = text.split("\n");
   const warnings = [];
   const pattern2 = extractPatternSlug(lines2, warnings);
   const theme2 = extractMetaField(lines2, "Theme");
   const recipePath = extractRecipePath(text, handoffPath, warnings);
   const primitives = extractPrimitives(text, warnings);
-  const { screens, mockShapes } = recipePath && existsSync19(recipePath) ? extractRecipeArtifacts(recipePath, warnings) : { screens: [], mockShapes: [] };
+  const { screens, mockShapes } = recipePath && existsSync21(recipePath) ? extractRecipeArtifacts(recipePath, warnings) : { screens: [], mockShapes: [] };
   return { pattern: pattern2, theme: theme2, recipePath, primitives, screens, mockShapes, warnings };
 }
 function extractPatternSlug(lines2, warnings) {
@@ -5969,7 +6222,7 @@ function extractRecipePath(text, handoffPath, warnings) {
   }
   const href = m[2].trim();
   if (isAbsolute(href)) return href;
-  return resolve15(dirname8(handoffPath), href);
+  return resolve15(dirname9(handoffPath), href);
 }
 var STATUS_PATTERNS = [
   { re: /NEW\s+gap/i, status: "gap-new" },
@@ -6016,7 +6269,7 @@ function extractPrimitives(text, warnings) {
   return primitives;
 }
 function extractRecipeArtifacts(recipePath, warnings) {
-  const text = readFileSync23(recipePath, "utf-8");
+  const text = readFileSync25(recipePath, "utf-8");
   const screens = extractScreens(text);
   const mockShapes = extractMockFields(text, warnings);
   return { screens, mockShapes };
@@ -6090,8 +6343,8 @@ function tryPort(port) {
 }
 
 // src/commands/sandbox/scaffold.ts
-import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync12, existsSync as existsSync20, readdirSync as readdirSync12 } from "fs";
-import { join as join20 } from "path";
+import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync13, existsSync as existsSync22, readdirSync as readdirSync12 } from "fs";
+import { join as join22 } from "path";
 
 // src/commands/sandbox/templates.ts
 var SANDBOX_PACKAGE_VERSION = "16.2.6";
@@ -6591,12 +6844,12 @@ function toPascalCase(s) {
 
 // src/commands/sandbox/scaffold.ts
 function writeScaffold(sandboxDir, manifest, port, options = {}) {
-  mkdirSync7(sandboxDir, { recursive: true });
+  mkdirSync8(sandboxDir, { recursive: true });
   const created = [];
   const writeIfNew = (rel, contents) => {
-    const full = join20(sandboxDir, rel);
-    mkdirSync7(dirOf(full), { recursive: true });
-    writeFileSync12(full, contents, "utf-8");
+    const full = join22(sandboxDir, rel);
+    mkdirSync8(dirOf(full), { recursive: true });
+    writeFileSync13(full, contents, "utf-8");
     created.push(rel);
   };
   writeIfNew("package.json", packageJsonTemplate(manifest.pattern));
@@ -6622,7 +6875,7 @@ function writeScaffold(sandboxDir, manifest, port, options = {}) {
     }
   }
   writeIfNew("playwright.capture.mjs", captureScriptTemplate());
-  mkdirSync7(join20(sandboxDir, "captures", "approved"), { recursive: true });
+  mkdirSync8(join22(sandboxDir, "captures", "approved"), { recursive: true });
   return { created };
 }
 function dirOf(p) {
@@ -6656,10 +6909,10 @@ function writeSandboxConfig(sandboxDir, manifest, port, options) {
       stripChromeSelectors: options.prototypeImport.stripChromeSelectors
     } : null
   };
-  writeFileSync12(join20(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+  writeFileSync13(join22(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
 function sandboxIsEmpty(sandboxDir) {
-  if (!existsSync20(sandboxDir)) return true;
+  if (!existsSync22(sandboxDir)) return true;
   try {
     return readdirSync12(sandboxDir).filter((f) => !f.startsWith(".")).length === 0;
   } catch {
@@ -6668,8 +6921,8 @@ function sandboxIsEmpty(sandboxDir) {
 }
 
 // src/commands/sandbox/html-prototype.ts
-import { mkdirSync as mkdirSync8, readdirSync as readdirSync13, readFileSync as readFileSync24, statSync as statSync9, writeFileSync as writeFileSync13 } from "fs";
-import { join as join21 } from "path";
+import { mkdirSync as mkdirSync9, readdirSync as readdirSync13, readFileSync as readFileSync26, statSync as statSync9, writeFileSync as writeFileSync14 } from "fs";
+import { join as join23 } from "path";
 
 // src/commands/sandbox/strip-chrome.ts
 var DEFAULT_STRIP_SELECTORS = [
@@ -6853,8 +7106,8 @@ function stripDocumentaryChrome(html, selectors) {
 var SCREEN_FILE_PATTERN = /^screen-(\d+)-([^/.]+)\.html$/i;
 function copyHtmlPrototype(sourceDir, sandboxDir, manifest, options = {}) {
   const warnings = [];
-  const destAbs = join21(sandboxDir, "public", "prototype");
-  mkdirSync8(destAbs, { recursive: true });
+  const destAbs = join23(sandboxDir, "public", "prototype");
+  mkdirSync9(destAbs, { recursive: true });
   const stripChromeSelectors = options.stripChromeSelectors ?? [];
   const copiedFiles = copyTreeRelative(sourceDir, destAbs, "", stripChromeSelectors);
   const screenFiles = listOrderedScreenFiles(sourceDir);
@@ -6907,24 +7160,24 @@ function deriveStateCoverageScreen(file, existingNames) {
 }
 function copyTreeRelative(srcDir, destDir, relDir = "", stripChromeSelectors = []) {
   const out = [];
-  const entries = readdirSync13(join21(srcDir, relDir));
+  const entries = readdirSync13(join23(srcDir, relDir));
   for (const name of entries) {
     if (name.startsWith(".")) continue;
-    const srcPath = join21(srcDir, relDir, name);
-    const destPath = join21(destDir, relDir, name);
+    const srcPath = join23(srcDir, relDir, name);
+    const destPath = join23(destDir, relDir, name);
     const stat = statSync9(srcPath);
     if (stat.isDirectory()) {
-      mkdirSync8(destPath, { recursive: true });
-      out.push(...copyTreeRelative(srcDir, destDir, join21(relDir, name), stripChromeSelectors));
+      mkdirSync9(destPath, { recursive: true });
+      out.push(...copyTreeRelative(srcDir, destDir, join23(relDir, name), stripChromeSelectors));
     } else if (stat.isFile()) {
       if (stripChromeSelectors.length > 0 && name.toLowerCase().endsWith(".html")) {
-        const html = readFileSync24(srcPath, "utf-8");
+        const html = readFileSync26(srcPath, "utf-8");
         const stripped = stripDocumentaryChrome(html, stripChromeSelectors);
-        writeFileSync13(destPath, stripped);
+        writeFileSync14(destPath, stripped);
       } else {
-        writeFileSync13(destPath, readFileSync24(srcPath));
+        writeFileSync14(destPath, readFileSync26(srcPath));
       }
-      out.push(join21("public", "prototype", relDir, name).replace(/\\/g, "/"));
+      out.push(join23("public", "prototype", relDir, name).replace(/\\/g, "/"));
     }
   }
   return out;
@@ -6977,7 +7230,7 @@ async function runInit(name, cwd, options) {
     throw new Error(`Invalid sandbox name '${name}'. Use letters, digits, '-' or '_'.`);
   }
   const handoffPath = isAbsolute2(options.handoff) ? options.handoff : resolve16(cwd, options.handoff);
-  if (!existsSync21(handoffPath)) {
+  if (!existsSync23(handoffPath)) {
     throw new Error(`Handoff manifest not found: ${handoffPath}`);
   }
   const manifest = parseHandoff(handoffPath);
@@ -6986,7 +7239,7 @@ async function runInit(name, cwd, options) {
       `Handoff has no primitives \u2014 refusing to scaffold an empty sandbox. Check the manifest at ${handoffPath}`
     );
   }
-  const sandboxDir = join22(cwd, ".lo", "sandbox", name);
+  const sandboxDir = join24(cwd, ".lo", "sandbox", name);
   if (!sandboxIsEmpty(sandboxDir)) {
     if (!options.overwrite) {
       throw new Error(
@@ -6995,12 +7248,12 @@ async function runInit(name, cwd, options) {
     }
     rmSync2(sandboxDir, { recursive: true, force: true });
   }
-  mkdirSync9(sandboxDir, { recursive: true });
+  mkdirSync10(sandboxDir, { recursive: true });
   const port = await findOpenPort();
   let prototypeImport;
   if (options.fromHtmlPrototype) {
     const prototypeDir = isAbsolute2(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve16(cwd, options.fromHtmlPrototype);
-    if (!existsSync21(prototypeDir)) {
+    if (!existsSync23(prototypeDir)) {
       throw new Error(`HTML prototype directory not found: ${prototypeDir}`);
     }
     const stripChromeSelectors = resolveStripSelectors(
@@ -7064,17 +7317,17 @@ function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile
   candidates.push(isAbsolute2(theme2) ? theme2 : resolve16(cwd, theme2));
   const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
   if (privateRoot && privateRoot.length > 0) {
-    candidates.push(join22(privateRoot, "themes", theme2, "theme.visor.yaml"));
+    candidates.push(join24(privateRoot, "themes", theme2, "theme.visor.yaml"));
   }
   candidates.push(
-    join22(cwd, "themes", `${theme2}.visor.yaml`),
-    join22(cwd, "custom-themes", `${theme2}.visor.yaml`)
+    join24(cwd, "themes", `${theme2}.visor.yaml`),
+    join24(cwd, "custom-themes", `${theme2}.visor.yaml`)
   );
-  const yamlPath = candidates.find((p) => existsSync21(p));
+  const yamlPath = candidates.find((p) => existsSync23(p));
   if (!yamlPath) {
     const searched = candidates.join(", ");
     manifest.warnings.push(
-      `Theme '${theme2}' not found (searched: ${searched}) \u2014 sandbox uses placeholder globals.css. Run 'npx visor theme apply <path-to-theme.visor.yaml> --adapter nextjs -o ${join22(sandboxDir, "app", "globals.css")}' manually, or re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH to a directory containing themes/${theme2}/theme.visor.yaml.`
+      `Theme '${theme2}' not found (searched: ${searched}) \u2014 sandbox uses placeholder globals.css. Run 'npx visor theme apply <path-to-theme.visor.yaml> --adapter nextjs -o ${join24(sandboxDir, "app", "globals.css")}' manually, or re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH to a directory containing themes/${theme2}/theme.visor.yaml.`
     );
     if (!json) {
       logger.warn(`Theme '${theme2}' not found \u2014 leaving placeholder globals.css.`);
@@ -7082,12 +7335,12 @@ function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile
         `Re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH=<dir-containing-themes/${theme2}/theme.visor.yaml>.`
       );
       logger.item(
-        `Or apply manually: npx visor theme apply <path> --adapter nextjs -o ${join22(sandboxDir, "app", "globals.css")}`
+        `Or apply manually: npx visor theme apply <path> --adapter nextjs -o ${join24(sandboxDir, "app", "globals.css")}`
       );
     }
     return;
   }
-  const globalsOut = join22(sandboxDir, "app", "globals.css");
+  const globalsOut = join24(sandboxDir, "app", "globals.css");
   try {
     themeApplyCommand(yamlPath, sandboxDir, {
       output: globalsOut,
@@ -7118,7 +7371,7 @@ function tryAddPrimitive(primitive, sandboxDir, json) {
 }
 function runNpmInstall(sandboxDir, json) {
   if (!json) logger.info("Installing sandbox dependencies...");
-  const result = childProcess2.spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+  const result = childProcess3.spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
     cwd: sandboxDir,
     stdio: json ? "ignore" : "inherit"
   });
@@ -7140,12 +7393,12 @@ function loadKnownPrimitives() {
 }
 function readCliVersion() {
   try {
-    const here = dirname9(fileURLToPath3(import.meta.url));
+    const here = dirname10(fileURLToPath3(import.meta.url));
     for (let i = 0; i < 6; i++) {
       const segments = new Array(i).fill("..");
-      const candidate = join22(here, ...segments, "package.json");
+      const candidate = join24(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync25(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync27(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) return pkg2.version;
       } catch {
       }
@@ -7156,14 +7409,14 @@ function readCliVersion() {
 }
 
 // src/commands/sandbox/dev.ts
-import { existsSync as existsSync22, readFileSync as readFileSync26 } from "fs";
-import { join as join23 } from "path";
-import * as childProcess3 from "child_process";
+import { existsSync as existsSync24, readFileSync as readFileSync28 } from "fs";
+import { join as join25 } from "path";
+import * as childProcess4 from "child_process";
 function sandboxDevCommand(cwd, options) {
   const json = options.json ?? false;
-  const sandboxDir = join23(cwd, ".lo", "sandbox", options.name);
-  const configPath = join23(sandboxDir, "sandbox.json");
-  if (!existsSync22(configPath)) {
+  const sandboxDir = join25(cwd, ".lo", "sandbox", options.name);
+  const configPath = join25(sandboxDir, "sandbox.json");
+  if (!existsSync24(configPath)) {
     fail(
       json,
       `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init ${options.name} --handoff ... --theme ...' first.`
@@ -7172,7 +7425,7 @@ function sandboxDevCommand(cwd, options) {
   }
   let config;
   try {
-    config = JSON.parse(readFileSync26(configPath, "utf-8"));
+    config = JSON.parse(readFileSync28(configPath, "utf-8"));
   } catch (err) {
     fail(json, `Invalid sandbox.json at ${configPath}: ${err.message}`);
     return;
@@ -7199,7 +7452,7 @@ function sandboxDevCommand(cwd, options) {
   spawnNextDev(sandboxDir, config.port, json);
 }
 function spawnNextDev(sandboxDir, port, json) {
-  const child = childProcess3.spawn(
+  const child = childProcess4.spawn(
     "npx",
     ["--no-install", "next", "dev", "--port", String(port)],
     {
@@ -7230,20 +7483,20 @@ function fail(json, message) {
 // src/commands/sandbox/approve.ts
 import {
   copyFileSync as copyFileSync2,
-  existsSync as existsSync23,
-  mkdirSync as mkdirSync10,
-  readFileSync as readFileSync27,
+  existsSync as existsSync25,
+  mkdirSync as mkdirSync11,
+  readFileSync as readFileSync29,
   readdirSync as readdirSync14,
   rmSync as rmSync3,
-  writeFileSync as writeFileSync14
+  writeFileSync as writeFileSync15
 } from "fs";
-import { basename as basename6, join as join24 } from "path";
-import * as childProcess4 from "child_process";
+import { basename as basename7, join as join26 } from "path";
+import * as childProcess5 from "child_process";
 function sandboxApproveCommand(cwd, options) {
   const json = options.json ?? false;
-  const sandboxDir = join24(cwd, ".lo", "sandbox", options.name);
-  const configPath = join24(sandboxDir, "sandbox.json");
-  if (!existsSync23(configPath)) {
+  const sandboxDir = join26(cwd, ".lo", "sandbox", options.name);
+  const configPath = join26(sandboxDir, "sandbox.json");
+  if (!existsSync25(configPath)) {
     fail2(
       json,
       `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init' first.`
@@ -7257,11 +7510,11 @@ function sandboxApproveCommand(cwd, options) {
   runCapture(sandboxDir, configPath, options.name, json);
 }
 function runCapture(sandboxDir, configPath, sandboxName, json) {
-  const config = JSON.parse(readFileSync27(configPath, "utf-8"));
-  const captureScriptPath = join24(sandboxDir, "playwright.capture.mjs");
-  writeFileSync14(captureScriptPath, captureScriptTemplate(), "utf-8");
+  const config = JSON.parse(readFileSync29(configPath, "utf-8"));
+  const captureScriptPath = join26(sandboxDir, "playwright.capture.mjs");
+  writeFileSync15(captureScriptPath, captureScriptTemplate(), "utf-8");
   ensurePlaywrightInstalled(sandboxDir, json);
-  const result = childProcess4.spawnSync(
+  const result = childProcess5.spawnSync(
     "npx",
     ["--no-install", "node", "playwright.capture.mjs"],
     {
@@ -7280,9 +7533,9 @@ function runCapture(sandboxDir, configPath, sandboxName, json) {
 ${result.stderr}`);
     return;
   }
-  const pendingDir = join24(sandboxDir, "captures", "pending");
-  const diffsDir = join24(sandboxDir, "captures", "diffs");
-  const approvedDir = join24(sandboxDir, "captures", "approved");
+  const pendingDir = join26(sandboxDir, "captures", "pending");
+  const diffsDir = join26(sandboxDir, "captures", "diffs");
+  const approvedDir = join26(sandboxDir, "captures", "approved");
   const pendingFiles = safeListPngs(pendingDir);
   const diffFiles = safeListPngs(diffsDir);
   const hasBaseline = safeListPngs(approvedDir).length > 0;
@@ -7319,9 +7572,9 @@ ${result.stderr}`);
   }
 }
 function runPromotion(sandboxDir, sandboxName, json) {
-  const pendingDir = join24(sandboxDir, "captures", "pending");
-  const approvedDir = join24(sandboxDir, "captures", "approved");
-  const diffsDir = join24(sandboxDir, "captures", "diffs");
+  const pendingDir = join26(sandboxDir, "captures", "pending");
+  const approvedDir = join26(sandboxDir, "captures", "approved");
+  const diffsDir = join26(sandboxDir, "captures", "diffs");
   const pendingFiles = safeListPngs(pendingDir);
   if (pendingFiles.length === 0) {
     fail2(
@@ -7330,10 +7583,10 @@ function runPromotion(sandboxDir, sandboxName, json) {
     );
     return;
   }
-  mkdirSync10(approvedDir, { recursive: true });
+  mkdirSync11(approvedDir, { recursive: true });
   const promoted = [];
   for (const src of pendingFiles) {
-    const dest = join24(approvedDir, basename6(src));
+    const dest = join26(approvedDir, basename7(src));
     copyFileSync2(src, dest);
     promoted.push(dest);
   }
@@ -7353,10 +7606,10 @@ function runPromotion(sandboxDir, sandboxName, json) {
   }
 }
 function ensurePlaywrightInstalled(sandboxDir, json) {
-  const markerPath = join24(sandboxDir, ".playwright-installed");
-  if (existsSync23(markerPath)) return;
+  const markerPath = join26(sandboxDir, ".playwright-installed");
+  if (existsSync25(markerPath)) return;
   if (!json) logger.info("Installing Playwright Chromium (one-time)...");
-  const result = childProcess4.spawnSync(
+  const result = childProcess5.spawnSync(
     "npx",
     ["--no-install", "playwright", "install", "chromium"],
     {
@@ -7370,11 +7623,11 @@ function ensurePlaywrightInstalled(sandboxDir, json) {
   if (typeof result.status === "number" && result.status !== 0) {
     throw new Error(`playwright install exited with code ${result.status}`);
   }
-  writeFileSync14(markerPath, (/* @__PURE__ */ new Date()).toISOString(), "utf-8");
+  writeFileSync15(markerPath, (/* @__PURE__ */ new Date()).toISOString(), "utf-8");
 }
 function safeListPngs(dir) {
-  if (!existsSync23(dir)) return [];
-  return readdirSync14(dir).filter((f) => f.endsWith(".png")).map((f) => join24(dir, f));
+  if (!existsSync25(dir)) return [];
+  return readdirSync14(dir).filter((f) => f.endsWith(".png")).map((f) => join26(dir, f));
 }
 function tryParseJson(s) {
   try {
@@ -7392,15 +7645,372 @@ function fail2(json, message) {
   process.exit(1);
 }
 
+// src/commands/spawn.ts
+import {
+  cpSync,
+  existsSync as existsSync28,
+  mkdirSync as mkdirSync12,
+  readFileSync as readFileSync31,
+  readdirSync as readdirSync16,
+  rmSync as rmSync4,
+  writeFileSync as writeFileSync16
+} from "fs";
+import { basename as basename8, isAbsolute as isAbsolute3, join as join29, resolve as resolve17 } from "path";
+import { homedir as homedir3 } from "os";
+import * as childProcess6 from "child_process";
+import { parse as parseYaml5 } from "yaml";
+import { generateThemeData as generateThemeData7 } from "@loworbitstudio/visor-theme-engine";
+import { nextjsAdapter as nextjsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
+import { validate as validate3 } from "@loworbitstudio/visor-theme-engine";
+
+// src/lib/blessed-discovery.ts
+import { existsSync as existsSync27, readdirSync as readdirSync15 } from "fs";
+import { join as join28 } from "path";
+
+// src/lib/blessed-manifest.ts
+import { existsSync as existsSync26, readFileSync as readFileSync30 } from "fs";
+import { join as join27 } from "path";
+import { z } from "zod";
+var BLESSED_MANIFEST_FILENAME = "blessed-manifest.json";
+var blessedManifestSchema = z.object({
+  /** Blessed-build shape, e.g. `admin-ui`. Matched against the `{shape}` in `blessed:{shape}:{pattern}`. */
+  shape: z.string().min(1),
+  /** Pattern name within the shape, e.g. `organization-management`. */
+  pattern: z.string().min(1),
+  /** The theme the reference build was authored + captured against. */
+  base_theme: z.string().min(1),
+  /** Minimum Visor version this build is known to work with (semver range). */
+  requires_visor: z.string().min(1),
+  /** Path (relative to the build root) to the approved capture baseline. */
+  captures_baseline: z.string().min(1),
+  /** Three-gates disposition at the time the build was blessed. */
+  three_gates_status: z.string().min(1)
+}).strict();
+function parseBlessedManifest(buildDir) {
+  const manifestPath = join27(buildDir, BLESSED_MANIFEST_FILENAME);
+  if (!existsSync26(manifestPath)) {
+    return {
+      ok: false,
+      error: `this directory is not a blessed build (missing ${BLESSED_MANIFEST_FILENAME}); see docs/blessed-builds.md`
+    };
+  }
+  let raw;
+  try {
+    raw = readFileSync30(manifestPath, "utf-8");
+  } catch {
+    return { ok: false, error: `could not read ${manifestPath}` };
+  }
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "invalid JSON";
+    return { ok: false, error: `invalid JSON in ${manifestPath}: ${message}` };
+  }
+  const result = blessedManifestSchema.safeParse(json);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const path2 = issue.path.join(".") || "(root)";
+      return `${path2}: ${issue.message}`;
+    }).join("; ");
+    return {
+      ok: false,
+      error: `invalid ${BLESSED_MANIFEST_FILENAME} at ${manifestPath}: ${issues}`
+    };
+  }
+  return { ok: true, manifest: result.data };
+}
+
+// src/lib/blessed-discovery.ts
+var WALK_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  ".turbo",
+  "coverage",
+  ".cache"
+]);
+function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
+  const builds = [];
+  const errors = [];
+  if (!existsSync27(blessedDir)) {
+    return { builds, errors };
+  }
+  walk2(blessedDir, 0);
+  builds.sort((a, b) => {
+    if (a.manifest.shape !== b.manifest.shape) {
+      return a.manifest.shape.localeCompare(b.manifest.shape);
+    }
+    return a.manifest.pattern.localeCompare(b.manifest.pattern);
+  });
+  return { builds, errors };
+  function walk2(dir, depth) {
+    if (depth > maxDepth) return;
+    let entries;
+    try {
+      entries = readdirSync15(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const hasManifest = entries.some(
+      (entry) => entry.isFile() && entry.name === BLESSED_MANIFEST_FILENAME
+    );
+    if (hasManifest) {
+      const result = parseBlessedManifest(dir);
+      if (result.ok) {
+        builds.push({ dir, manifest: result.manifest });
+      } else {
+        errors.push({ dir, error: result.error });
+      }
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (WALK_EXCLUDE_DIRS.has(entry.name)) continue;
+      walk2(join28(dir, entry.name), depth + 1);
+    }
+  }
+}
+function resolveBlessedBuild(blessedDir, shape, pattern2) {
+  const { builds } = discoverBlessedBuilds(blessedDir);
+  const build = builds.find(
+    (candidate) => candidate.manifest.shape === shape && candidate.manifest.pattern === pattern2
+  );
+  return { build, available: builds };
+}
+
+// src/commands/spawn.ts
+var DEFAULT_BLESSED_DIR = join29(
+  homedir3(),
+  "Code",
+  "low-orbit",
+  "low-orbit-playbook",
+  "design-prototypes"
+);
+var FORK_EXCLUDE = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  ".turbo",
+  ".cache",
+  "coverage",
+  ".DS_Store",
+  "tsconfig.tsbuildinfo"
+]);
+function parseBlessedIdentifier(from) {
+  const PREFIX = "blessed:";
+  if (!from.startsWith(PREFIX)) {
+    throw new Error(
+      `Invalid --from '${from}'. Expected the form blessed:{shape}:{pattern} (e.g. blessed:admin-ui:organization-management).`
+    );
+  }
+  const rest = from.slice(PREFIX.length);
+  const parts = rest.split(":");
+  if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+    throw new Error(
+      `Invalid --from '${from}'. Expected the form blessed:{shape}:{pattern} (e.g. blessed:admin-ui:organization-management).`
+    );
+  }
+  return { shape: parts[0], pattern: parts[1] };
+}
+function resolveBlessedDir(cwd, options) {
+  const raw = options.blessedDir ?? (process.env.VISOR_BLESSED_DIR && process.env.VISOR_BLESSED_DIR.length > 0 ? process.env.VISOR_BLESSED_DIR : void 0) ?? DEFAULT_BLESSED_DIR;
+  return isAbsolute3(raw) ? raw : resolve17(cwd, raw);
+}
+function resolveThemeFile(theme2, cwd, themeFile) {
+  const candidates = [];
+  if (themeFile) {
+    candidates.push(isAbsolute3(themeFile) ? themeFile : resolve17(cwd, themeFile));
+  }
+  candidates.push(isAbsolute3(theme2) ? theme2 : resolve17(cwd, theme2));
+  const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
+  if (privateRoot && privateRoot.length > 0) {
+    candidates.push(join29(privateRoot, "themes", theme2, "theme.visor.yaml"));
+  }
+  candidates.push(
+    join29(cwd, "themes", `${theme2}.visor.yaml`),
+    join29(cwd, "custom-themes", `${theme2}.visor.yaml`)
+  );
+  const found = candidates.find((candidate) => existsSync28(candidate));
+  if (!found) {
+    throw new Error(
+      `Theme '${theme2}' not found (searched: ${candidates.join(", ")}). Pass --theme-file <path>, use a direct path, or set VISOR_THEMES_PRIVATE_PATH.`
+    );
+  }
+  return { path: found, searched: candidates };
+}
+function resolveGlobalsCssPath(outputDir) {
+  const candidates = [
+    join29(outputDir, "app", "globals.css"),
+    join29(outputDir, "src", "app", "globals.css")
+  ];
+  const existing = candidates.find((candidate) => existsSync28(candidate));
+  return existing ?? candidates[0];
+}
+function applyThemeToFork(themeFile, globalsOut) {
+  const yaml = readFileSync31(themeFile, "utf-8");
+  const data = generateThemeData7(yaml);
+  const css = nextjsAdapter3(
+    { primitives: data.primitives, tokens: data.tokens, config: data.config },
+    {}
+  );
+  mkdirSync12(join29(globalsOut, ".."), { recursive: true });
+  writeFileSync16(globalsOut, css, "utf-8");
+}
+function runNpmInstall2(outputDir, json) {
+  const result = childProcess6.spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+    cwd: outputDir,
+    stdio: json ? "ignore" : "inherit"
+  });
+  if (result.error) {
+    throw new Error(`npm install failed to start: ${result.error.message}`);
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    throw new Error(`npm install exited with code ${result.status}`);
+  }
+}
+function runSpawn(cwd, options) {
+  if (!options.from) throw new Error("Missing required --from blessed:{shape}:{pattern}.");
+  if (!options.theme) throw new Error("Missing required --theme <id>.");
+  if (!options.output) throw new Error("Missing required --output <path>.");
+  const { shape, pattern: pattern2 } = parseBlessedIdentifier(options.from);
+  const blessedDir = resolveBlessedDir(cwd, options);
+  const { build, available } = resolveBlessedBuild(blessedDir, shape, pattern2);
+  if (!build) {
+    const list = available.length > 0 ? available.map((b) => `  - blessed:${b.manifest.shape}:${b.manifest.pattern}`).join("\n") : "  (none found)";
+    throw new Error(
+      `No blessed build found for blessed:${shape}:${pattern2} under ${blessedDir}.
+Available builds:
+${list}`
+    );
+  }
+  const outputDir = isAbsolute3(options.output) ? options.output : resolve17(cwd, options.output);
+  if (existsSync28(outputDir) && readdirSync16(outputDir).length > 0) {
+    throw new Error(`Output directory already exists and is not empty: ${outputDir}`);
+  }
+  const { path: themeFile } = resolveThemeFile(options.theme, cwd, options.themeFile);
+  cpSync(build.dir, outputDir, {
+    recursive: true,
+    filter: (src) => !FORK_EXCLUDE.has(basename8(src))
+  });
+  let validated = false;
+  let installed = false;
+  try {
+    const globalsOut = resolveGlobalsCssPath(outputDir);
+    applyThemeToFork(themeFile, globalsOut);
+    if (options.validate) {
+      const parsed = parseYaml5(readFileSync31(themeFile, "utf-8"));
+      const result = validate3(parsed);
+      if (!result.valid) {
+        const messages = result.errors.map((e) => e.message).join("; ");
+        throw new Error(`Theme validation failed: ${messages}`);
+      }
+      validated = true;
+    }
+    if (options.install) {
+      runNpmInstall2(outputDir, options.json ?? false);
+      installed = true;
+    }
+  } catch (err) {
+    rmSync4(outputDir, { recursive: true, force: true });
+    throw err;
+  }
+  return {
+    success: true,
+    build: {
+      shape: build.manifest.shape,
+      pattern: build.manifest.pattern,
+      requiresVisor: build.manifest.requires_visor,
+      source: build.dir
+    },
+    output: outputDir,
+    themeApplied: options.theme,
+    themeFile,
+    installed,
+    validated
+  };
+}
+function listBlessed(cwd, options) {
+  const blessedDir = resolveBlessedDir(cwd, options);
+  const { builds, errors } = discoverBlessedBuilds(blessedDir);
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        success: true,
+        blessedDir,
+        builds: builds.map((b) => ({
+          from: `blessed:${b.manifest.shape}:${b.manifest.pattern}`,
+          shape: b.manifest.shape,
+          pattern: b.manifest.pattern,
+          base_theme: b.manifest.base_theme,
+          requires_visor: b.manifest.requires_visor,
+          three_gates_status: b.manifest.three_gates_status,
+          dir: b.dir
+        })),
+        errors
+      })
+    );
+    return;
+  }
+  logger.heading(`Blessed builds under ${blessedDir}`);
+  if (builds.length === 0) {
+    logger.info("  (none found)");
+  }
+  for (const b of builds) {
+    logger.success(`blessed:${b.manifest.shape}:${b.manifest.pattern}`);
+    logger.item(`base theme: ${b.manifest.base_theme}  \xB7  requires visor ${b.manifest.requires_visor}  \xB7  gates: ${b.manifest.three_gates_status}`);
+  }
+  for (const e of errors) {
+    logger.warn(`Skipped ${e.dir}: ${e.error}`);
+  }
+}
+function spawnCommand(cwd, options) {
+  const json = options.json ?? false;
+  if (options.listBlessed) {
+    try {
+      listBlessed(cwd, options);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (json) console.log(JSON.stringify({ success: false, error: message }));
+      else logger.error(message);
+      process.exit(1);
+    }
+    return;
+  }
+  try {
+    const result = runSpawn(cwd, options);
+    if (json) {
+      console.log(JSON.stringify(result));
+      return;
+    }
+    logger.success(
+      `Discovered blessed build: ${result.build.shape}/${result.build.pattern} (requires visor ${result.build.requiresVisor})`
+    );
+    logger.success(`Forked to ${result.output} (excluded node_modules, .next, .git)`);
+    logger.success(`Theme applied: ${result.themeApplied} \u2192 ${result.output}`);
+    if (result.validated) logger.success("Theme validated");
+    if (result.installed) logger.success("Installed dependencies");
+    logger.blank();
+    logger.info(`Next: cd ${result.output} && npm run dev`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) console.log(JSON.stringify({ success: false, error: message }));
+    else logger.error(message);
+    process.exit(1);
+  }
+}
+
 // src/index.ts
-var __dirname2 = dirname10(fileURLToPath4(import.meta.url));
+var __dirname2 = dirname11(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync28(join25(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync32(join30(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);
 program.addCommand(checkCommand());
-program.command("init").description("Initialize Visor \u2014 with --template nextjs, scaffolds a complete runnable Borealis-native Next.js app in one command").option("--template <name>", "scaffold a complete runnable app (templates: nextjs)").option("--json", "output structured JSON (for AI agents)").action((options) => {
+program.command("init").description("Initialize Visor \u2014 with --template nextjs, scaffolds a complete runnable Borealis-native Next.js app in one command").option("--template <name>", "scaffold a complete runnable app (templates: nextjs)").option("--for <play>", "bootstrap a Playbook play (pattern-build, new-web-app, feature-addition)").option("--play-name <name>", "name for the play instance (default: current directory name)").option("--theme <id>", "theme id to record in the play's state metadata").option("--from <ref>", "brief source for the play (e.g. a PL-N Linear ticket)").option("--json", "output structured JSON (for AI agents)").action((options) => {
   initCommand(process.cwd(), options);
 });
 program.command("list").description("List all available registry items").option("--json", "output structured JSON (for AI agents)").option("--category <name>", "filter items by category").action((options) => {
@@ -7585,4 +8195,9 @@ sandbox.command("approve").description(
     sandboxApproveCommand(process.cwd(), options);
   }
 );
+program.command("spawn").description(
+  "Fork a Playbook blessed reference build with atomic theme re-skinning \u2014 one command replaces cp -R + npm install + theme apply"
+).option("--from <identifier>", "blessed build to spawn: blessed:{shape}:{pattern}").option("--theme <id>", "theme id (or path to a .visor.yaml) to re-skin the fork with").option("--theme-file <path>", "explicit path to a theme.visor.yaml \u2014 bypasses --theme name resolution").option("--output <path>", "destination directory for the forked project").option("--blessed-dir <path>", "override the blessed-build root (default: VISOR_BLESSED_DIR or ~/Code/low-orbit/low-orbit-playbook/design-prototypes)").option("--install", "run npm install in the forked project (default: skip)").option("--validate", "validate the applied theme after forking (default: skip)").option("--list-blessed", "list all discoverable blessed builds and exit").option("--json", "output structured JSON (for AI agents)").action((options) => {
+  spawnCommand(process.cwd(), options);
+});
 program.parse();