@loworbitstudio/visor 0.1.0 → 0.4.0

package/dist/index.js

@@ -1,15 +1,535 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { Command as Command2 } from "commander";
+
+// src/commands/check.ts
 import { Command } from "commander";
 
+// src/registry/resolve.ts
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var cachedRegistry = null;
+var cachedManifest = null;
+function loadRegistry() {
+  if (cachedRegistry) return cachedRegistry;
+  const registryPath = join(__dirname, "registry.json");
+  const raw = readFileSync(registryPath, "utf-8");
+  cachedRegistry = JSON.parse(raw);
+  return cachedRegistry;
+}
+function loadManifest() {
+  if (cachedManifest) return cachedManifest;
+  const manifestPath = join(__dirname, "visor-manifest.json");
+  const raw = readFileSync(manifestPath, "utf-8");
+  cachedManifest = JSON.parse(raw);
+  return cachedManifest;
+}
+function findItem(registry, name) {
+  return registry.items.find((item) => item.name === name);
+}
+function resolveTransitiveDeps(registry, names, onWarning) {
+  const resolved = /* @__PURE__ */ new Map();
+  const queue = names.map((n) => ({
+    name: n,
+    ancestors: /* @__PURE__ */ new Set()
+  }));
+  while (queue.length > 0) {
+    const { name, ancestors } = queue.shift();
+    if (resolved.has(name)) continue;
+    const item = findItem(registry, name);
+    if (!item) {
+      throw new Error(`Registry item "${name}" not found.`);
+    }
+    resolved.set(name, item);
+    if (item.registryDependencies) {
+      const childAncestors = new Set(ancestors);
+      childAncestors.add(name);
+      for (const dep of item.registryDependencies) {
+        if (childAncestors.has(dep)) {
+          onWarning?.(`Circular registry dependency: ${name} \u2192 ${dep}`);
+        } else if (!resolved.has(dep)) {
+          queue.push({ name: dep, ancestors: childAncestors });
+        }
+      }
+    }
+  }
+  return Array.from(resolved.values());
+}
+function collectDependencies(items) {
+  const deps = /* @__PURE__ */ new Set();
+  const devDeps = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    if (item.dependencies) {
+      for (const dep of item.dependencies) {
+        deps.add(dep);
+      }
+    }
+    if (item.devDependencies) {
+      for (const dep of item.devDependencies) {
+        devDeps.add(dep);
+      }
+    }
+  }
+  return {
+    dependencies: Array.from(deps).sort(),
+    devDependencies: Array.from(devDeps).sort()
+  };
+}
+
+// src/check/catalog.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "with",
+  "for",
+  "and",
+  "or",
+  "to",
+  "in",
+  "of",
+  "is",
+  "that",
+  "this",
+  "it",
+  "as",
+  "at",
+  "by",
+  "on",
+  "be",
+  "are",
+  "was",
+  "were"
+]);
+function toKebab(s) {
+  return s.replace(/([A-Z])/g, (m) => `-${m.toLowerCase()}`).replace(/^-/, "").toLowerCase();
+}
+function tokenize(text) {
+  return text.toLowerCase().split(/[\s\-_,]+/).filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+function installCmd(name, type) {
+  if (type === "block") return `npx visor add ${name} --block`;
+  if (type === "pattern") return null;
+  return `npx visor add ${name}`;
+}
+function getAllCatalogItems(manifest) {
+  const items = [];
+  for (const [name, c] of Object.entries(manifest.components)) {
+    items.push({ type: "component", name, category: c.category, description: c.description });
+    for (const sub of c.sub_components ?? []) {
+      items.push({ type: "component", name: toKebab(sub.name), category: c.category, description: sub.description });
+    }
+  }
+  for (const [name, b] of Object.entries(manifest.blocks)) {
+    items.push({ type: "block", name, category: b.category, description: b.description });
+  }
+  for (const [name, h] of Object.entries(manifest.hooks)) {
+    items.push({ type: "hook", name, description: h.description });
+  }
+  for (const [name, p] of Object.entries(manifest.patterns)) {
+    items.push({ type: "pattern", name, description: p.description });
+  }
+  return items;
+}
+function findByName(manifest, pattern2) {
+  const normalized = toKebab(pattern2);
+  if (normalized in manifest.components) {
+    const c = manifest.components[normalized];
+    return { found: true, name: normalized, type: "component", category: c.category, description: c.description, installCmd: `npx visor add ${normalized}` };
+  }
+  if (normalized in manifest.blocks) {
+    const b = manifest.blocks[normalized];
+    return { found: true, name: normalized, type: "block", category: b.category, description: b.description, installCmd: `npx visor add ${normalized} --block` };
+  }
+  if (normalized in manifest.hooks) {
+    const h = manifest.hooks[normalized];
+    return { found: true, name: normalized, type: "hook", description: h.description, installCmd: `npx visor add ${normalized}` };
+  }
+  if (normalized in manifest.patterns) {
+    const p = manifest.patterns[normalized];
+    return { found: true, name: normalized, type: "pattern", description: p.description, installCmd: null };
+  }
+  for (const [parentName, c] of Object.entries(manifest.components)) {
+    for (const sub of c.sub_components ?? []) {
+      if (toKebab(sub.name) === normalized) {
+        return { found: true, name: toKebab(sub.name), type: "component", category: c.category, description: sub.description, installCmd: `npx visor add ${parentName}` };
+      }
+    }
+  }
+  return { found: false };
+}
+function fuzzyFind(manifest, query, limit = 5) {
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+  const results = [];
+  for (const item of getAllCatalogItems(manifest)) {
+    const searchText = [item.name, item.description].join(" ").toLowerCase();
+    const matched = queryTokens.filter((t) => searchText.includes(t));
+    if (matched.length > 0) {
+      results.push({
+        name: item.name,
+        type: item.type,
+        category: item.category,
+        description: item.description,
+        score: matched.length,
+        matchReason: `Matched: ${matched.join(", ")}`,
+        installCmd: installCmd(item.name, item.type)
+      });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+
+// src/check/jsx-scan.ts
+import { readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { resolve, extname, join as join2 } from "path";
+
+// src/check/native-map.ts
+var NATIVE_TO_VISOR = {
+  button: { visorName: "button", displayName: "Button" },
+  textarea: { visorName: "textarea", displayName: "Textarea" },
+  form: { visorName: "form", displayName: "Form" },
+  label: { visorName: "label", displayName: "Label" },
+  fieldset: { visorName: "fieldset", displayName: "Fieldset" },
+  select: { visorName: "select", displayName: "Select" },
+  table: { visorName: "table", displayName: "Table", notes: "use DataTable for full interactive features" },
+  img: { visorName: "image", displayName: "Image" },
+  dialog: { visorName: "dialog", displayName: "Dialog" },
+  details: { visorName: "accordion", displayName: "Accordion", notes: "or Collapsible for a single section" },
+  summary: { visorName: "accordion", displayName: "Accordion", notes: "wrap as Accordion trigger" }
+};
+var INPUT_TYPE_MAP = {
+  number: { visorName: "number-input", displayName: "NumberInput" },
+  password: { visorName: "password-input", displayName: "PasswordInput" },
+  search: { visorName: "search-input", displayName: "SearchInput" },
+  tel: { visorName: "phone-input", displayName: "PhoneInput" },
+  phone: { visorName: "phone-input", displayName: "PhoneInput" },
+  // All other input types (text, email, url, date, etc.) map to the base Input.
+  _default: { visorName: "input", displayName: "Input" }
+};
+
+// src/check/jsx-scan.ts
+async function getBabelParser() {
+  const { parse } = await import("@babel/parser");
+  return parse;
+}
+function walk(node, visit) {
+  if (!node || typeof node !== "object") return;
+  const obj = node;
+  visit(obj);
+  for (const key of Object.keys(obj)) {
+    if (key === "parent" || key === "tokens" || key === "errors") continue;
+    const val = obj[key];
+    if (Array.isArray(val)) {
+      for (const child of val) walk(child, visit);
+    } else if (val && typeof val === "object" && "type" in val) {
+      walk(val, visit);
+    }
+  }
+}
+function getInputType(attribs) {
+  for (const attr of attribs) {
+    const a = attr;
+    if (a.type !== "JSXAttribute") continue;
+    const nameNode = a.name;
+    if (nameNode?.name !== "type") continue;
+    const valueNode = a.value;
+    if (!valueNode) continue;
+    if (valueNode.type === "StringLiteral") {
+      return String(valueNode.value ?? "text");
+    }
+    if (valueNode.type === "JSXExpressionContainer") {
+      const expr = valueNode.expression;
+      if (expr?.type === "StringLiteral") return String(expr.value ?? "text");
+    }
+  }
+  return "_default";
+}
+function collectJsxFindings(source, filePath, parse) {
+  let ast;
+  try {
+    ast = parse(source, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return [];
+  }
+  const findings = [];
+  walk(ast, (node) => {
+    if (node.type !== "JSXOpeningElement") return;
+    const nameNode = node.name;
+    if (!nameNode) return;
+    const tagName = nameNode.type === "JSXIdentifier" ? String(nameNode.name ?? "") : "";
+    if (!tagName || tagName[0] !== tagName[0].toLowerCase()) return;
+    const loc = node.loc;
+    const line = loc?.start?.line ?? 0;
+    const column = loc?.start?.column ?? 0;
+    if (tagName === "input") {
+      const attribs = node.attributes ?? [];
+      const typeVal = getInputType(attribs);
+      const mapping2 = INPUT_TYPE_MAP[typeVal] ?? INPUT_TYPE_MAP["_default"];
+      findings.push({
+        file: filePath,
+        line,
+        column,
+        nativeTag: typeVal !== "_default" ? `input[type=${typeVal}]` : "input",
+        suggestedPrimitive: mapping2.displayName,
+        installCmd: `npx visor add ${mapping2.visorName}`
+      });
+      return;
+    }
+    const mapping = NATIVE_TO_VISOR[tagName];
+    if (!mapping) return;
+    const finding = {
+      file: filePath,
+      line,
+      column,
+      nativeTag: tagName,
+      suggestedPrimitive: mapping.displayName,
+      installCmd: `npx visor add ${mapping.visorName}`
+    };
+    if (mapping.notes) finding.rationale = mapping.notes;
+    findings.push(finding);
+  });
+  return findings;
+}
+function collectFiles(pathArg) {
+  const JSX_EXTS = /* @__PURE__ */ new Set([".jsx", ".tsx", ".js", ".ts"]);
+  try {
+    const s = statSync(pathArg);
+    if (s.isDirectory()) {
+      let recurse2 = function(dir) {
+        for (const entry of readdirSync(dir)) {
+          if (entry.startsWith(".") || entry === "node_modules") continue;
+          const full = join2(dir, entry);
+          const es = statSync(full);
+          if (es.isDirectory()) recurse2(full);
+          else if (JSX_EXTS.has(extname(full))) files.push(full);
+        }
+      };
+      var recurse = recurse2;
+      const files = [];
+      recurse2(pathArg);
+      return files;
+    }
+    if (JSX_EXTS.has(extname(pathArg))) return [pathArg];
+  } catch {
+  }
+  return [];
+}
+async function scanJsx(pathArg) {
+  const parse = await getBabelParser();
+  let files;
+  let stdinMode = false;
+  if (pathArg === "-") {
+    stdinMode = true;
+    files = ["<stdin>"];
+  } else {
+    files = collectFiles(resolve(pathArg));
+  }
+  const allFindings = [];
+  for (const file of files) {
+    let source;
+    if (stdinMode) {
+      source = readFileSync2(0, "utf-8");
+    } else {
+      try {
+        source = readFileSync2(file, "utf-8");
+      } catch {
+        continue;
+      }
+    }
+    allFindings.push(...collectJsxFindings(source, stdinMode ? "<stdin>" : file, parse));
+  }
+  return {
+    findings: allFindings,
+    summary: { scanned: files.length, hits: allFindings.length }
+  };
+}
+
+// src/utils/logger.ts
+import pc from "picocolors";
+var logger = {
+  info(message) {
+    console.log(message);
+  },
+  success(message) {
+    console.log(pc.green(`\u2713 ${message}`));
+  },
+  warn(message) {
+    console.log(pc.yellow(`\u26A0 ${message}`));
+  },
+  error(message) {
+    console.error(pc.red(`\u2717 ${message}`));
+  },
+  item(message) {
+    console.log(pc.dim(`  ${message}`));
+  },
+  heading(message) {
+    console.log(pc.bold(message));
+  },
+  blank() {
+    console.log();
+  }
+};
+
+// src/commands/check.ts
+var TYPE_FILTER = {
+  ui: "component",
+  blocks: "block",
+  hooks: "hook",
+  patterns: "pattern"
+};
+function checkListCommand(options) {
+  const manifest = loadManifest();
+  let items = getAllCatalogItems(manifest);
+  if (options.type && options.type !== "all") {
+    const filterType = TYPE_FILTER[options.type];
+    items = items.filter((i) => i.type === filterType);
+  }
+  const byType = {};
+  for (const item of items) {
+    byType[item.type] = (byType[item.type] ?? 0) + 1;
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          items: items.map((i) => ({ type: i.type, name: i.name, category: i.category ?? null, description: i.description })),
+          summary: { total: items.length, byType }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = item.type;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(item);
+  }
+  for (const [type, group] of groups) {
+    logger.heading(`${type}s (${group.length})`);
+    logger.blank();
+    for (const item of group) {
+      logger.info(`  ${item.name.padEnd(28)} ${item.description}`);
+    }
+    logger.blank();
+  }
+}
+function checkHasCommand(pattern2, options) {
+  const manifest = loadManifest();
+  if (options.fuzzy) {
+    const results = fuzzyFind(manifest, pattern2, 5);
+    if (results.length === 0) {
+      if (options.json) {
+        console.log(JSON.stringify({ success: false, found: false, query: pattern2, results: [] }, null, 2));
+      } else {
+        logger.warn(`No fuzzy matches for "${pattern2}"`);
+      }
+      process.exit(1);
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, found: true, query: pattern2, results }, null, 2));
+      process.exit(0);
+      return;
+    }
+    logger.heading(`Fuzzy matches for "${pattern2}":`);
+    logger.blank();
+    for (const r of results) {
+      const cmd2 = r.installCmd ? ` \u2014 ${r.installCmd}` : "";
+      logger.info(`  ${r.name} [${r.type}]${cmd2}`);
+      logger.info(`    ${r.description.slice(0, 80)}`);
+    }
+    return;
+  }
+  const result = findByName(manifest, pattern2);
+  if (!result.found) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, found: false, query: pattern2 }, null, 2));
+    } else {
+      logger.warn(`"${pattern2}" not found in Visor catalog. Try --fuzzy for partial matches.`);
+    }
+    process.exit(1);
+    return;
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          found: true,
+          name: result.name,
+          type: result.type,
+          category: result.category ?? null,
+          description: result.description,
+          installCmd: result.installCmd
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const cmd = result.installCmd ? ` \u2014 ${result.installCmd}` : "";
+  logger.success(`${result.name} [${result.type}]${cmd}`);
+  logger.info(`  ${result.description}`);
+}
+async function checkDiffCommand(pathArg, options) {
+  const result = await scanJsx(pathArg);
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, ...result }, null, 2));
+    if (options.failOnHits && result.summary.hits > 0) process.exit(1);
+    process.exit(0);
+    return;
+  }
+  if (result.summary.hits === 0) {
+    logger.success(`No native HTML primitives found \u2014 ${result.summary.scanned} file(s) scanned.`);
+    return;
+  }
+  logger.heading(`Found ${result.summary.hits} native HTML usage(s) in ${result.summary.scanned} file(s):
+`);
+  for (const f of result.findings) {
+    const loc = `${f.file}:${f.line}:${f.column}`;
+    const note = f.rationale ? ` (${f.rationale})` : "";
+    logger.warn(`  <${f.nativeTag}> \u2192 use <${f.suggestedPrimitive}>${note}`);
+    logger.item(`  ${loc}  ${f.installCmd}`);
+  }
+  logger.blank();
+  if (options.failOnHits) process.exit(1);
+}
+function checkCommand() {
+  const check = new Command("check").description("Check Visor catalog \u2014 list items, test existence, scan JSX for native HTML");
+  check.command("list").description("List all catalog items (components, blocks, hooks, patterns)").option("--type <type>", "filter by type: ui, blocks, hooks, patterns, all (default: all)").option("--json", "output structured JSON (for AI agents)").action((options) => {
+    checkListCommand(options);
+  });
+  check.command("has").description("Check whether a component, block, hook, or pattern exists in the Visor catalog").argument("<pattern>", "component name (kebab-case or PascalCase)").option("--fuzzy", "run fuzzy match and return top 5 results").option("--json", "output structured JSON (for AI agents)").action((pattern2, options) => {
+    checkHasCommand(pattern2, options);
+  });
+  check.command("diff").description("Scan JSX/TSX for native HTML elements that have Visor equivalents").argument("<path>", "file path, directory, or - for stdin").option("--fail-on-hits", "exit 1 if any native HTML usages are found (for CI use)").option("--json", "output structured JSON (for AI agents)").action(async (pathArg, options) => {
+    await checkDiffCommand(pathArg, options);
+  });
+  return check;
+}
+
 // src/commands/init.ts
 import { existsSync as existsSync3, writeFileSync as writeFileSync2, mkdirSync } from "fs";
-import { join as join3, dirname } from "path";
+import { join as join5, dirname as dirname2 } from "path";
 
 // src/config/config.ts
-import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
+import { readFileSync as readFileSync3, writeFileSync, existsSync } from "fs";
+import { join as join3 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
@@ -25,7 +545,7 @@ var CONFIG_FILE = "visor.json";
 
 // src/config/config.ts
 function getConfigPath(cwd) {
-  return join(cwd, CONFIG_FILE);
+  return join3(cwd, CONFIG_FILE);
 }
 function configExists(cwd) {
   return existsSync(getConfigPath(cwd));
@@ -37,8 +557,29 @@ function loadConfig(cwd) {
       `No ${CONFIG_FILE} found. Run "visor init" first.`
     );
   }
-  const raw = readFileSync(configPath, "utf-8");
+  const raw = readFileSync3(configPath, "utf-8");
   const parsed = JSON.parse(raw);
+  const knownKeys = /* @__PURE__ */ new Set(["paths"]);
+  for (const key of Object.keys(parsed)) {
+    if (!knownKeys.has(key)) {
+      console.warn(`Warning: unknown key "${key}" in visor.json`);
+    }
+  }
+  if (parsed.paths !== void 0) {
+    if (typeof parsed.paths !== "object" || parsed.paths === null || Array.isArray(parsed.paths)) {
+      throw new Error(
+        `Invalid visor.json: paths must be an object, got ${Array.isArray(parsed.paths) ? "array" : typeof parsed.paths}`
+      );
+    }
+    const paths = parsed.paths;
+    for (const [key, value] of Object.entries(paths)) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `Invalid visor.json: paths.${key} must be a string, got ${typeof value}`
+        );
+      }
+    }
+  }
   return {
     paths: {
       ...DEFAULT_CONFIG.paths,
@@ -53,12 +594,12 @@ function writeConfig(cwd, config) {
 
 // src/utils/packages.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 function readPackageJson(cwd) {
-  const pkgPath = join2(cwd, "package.json");
+  const pkgPath = join4(cwd, "package.json");
   if (!existsSync2(pkgPath)) return null;
-  return JSON.parse(readFileSync2(pkgPath, "utf-8"));
+  return JSON.parse(readFileSync4(pkgPath, "utf-8"));
 }
 function isPackageInstalled(packageName, cwd) {
   const pkg = readPackageJson(cwd);
@@ -82,32 +623,6 @@ function installPackages(packages, cwd, dev = false) {
   }
 }
 
-// src/utils/logger.ts
-import pc from "picocolors";
-var logger = {
-  info(message) {
-    console.log(message);
-  },
-  success(message) {
-    console.log(pc.green(`\u2713 ${message}`));
-  },
-  warn(message) {
-    console.log(pc.yellow(`\u26A0 ${message}`));
-  },
-  error(message) {
-    console.error(pc.red(`\u2717 ${message}`));
-  },
-  item(message) {
-    console.log(pc.dim(`  ${message}`));
-  },
-  heading(message) {
-    console.log(pc.bold(message));
-  },
-  blank() {
-    console.log();
-  }
-};
-
 // src/commands/templates/nextjs.ts
 var NEXTJS_STARTER_YAML = `name: my-app
 version: 1
@@ -203,7 +718,7 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped) {
     logger.blank();
     logger.info("Scaffolding NextJS theme...");
   }
-  const yamlPath = join3(cwd, ".visor.yaml");
+  const yamlPath = join5(cwd, ".visor.yaml");
   if (existsSync3(yamlPath)) {
     filesSkipped.push(".visor.yaml");
     if (!json) {
@@ -222,8 +737,8 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped) {
     tokens: data.tokens,
     config: data.config
   });
-  const globalsPath = join3(cwd, "app", "globals.css");
-  const globalsDir = dirname(globalsPath);
+  const globalsPath = join5(cwd, "app", "globals.css");
+  const globalsDir = dirname2(globalsPath);
   if (existsSync3(globalsPath)) {
     filesSkipped.push("app/globals.css");
     if (!json) {
@@ -246,95 +761,37 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped) {
   }
 }
 
-// src/registry/resolve.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join4, dirname as dirname2 } from "path";
-import { fileURLToPath } from "url";
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var cachedRegistry = null;
-function loadRegistry() {
-  if (cachedRegistry) return cachedRegistry;
-  const registryPath = join4(__dirname, "registry.json");
-  const raw = readFileSync3(registryPath, "utf-8");
-  cachedRegistry = JSON.parse(raw);
-  return cachedRegistry;
-}
-function findItem(registry, name) {
-  return registry.items.find((item) => item.name === name);
-}
-function resolveTransitiveDeps(registry, names) {
-  const resolved = /* @__PURE__ */ new Map();
-  const queue = [...names];
-  while (queue.length > 0) {
-    const name = queue.shift();
-    if (resolved.has(name)) continue;
-    const item = findItem(registry, name);
-    if (!item) {
-      throw new Error(`Registry item "${name}" not found.`);
-    }
-    resolved.set(name, item);
-    if (item.registryDependencies) {
-      for (const dep of item.registryDependencies) {
-        if (!resolved.has(dep)) {
-          queue.push(dep);
-        }
-      }
-    }
-  }
-  return Array.from(resolved.values());
-}
-function collectDependencies(items) {
-  const deps = /* @__PURE__ */ new Set();
-  const devDeps = /* @__PURE__ */ new Set();
-  for (const item of items) {
-    if (item.dependencies) {
-      for (const dep of item.dependencies) {
-        deps.add(dep);
-      }
-    }
-    if (item.devDependencies) {
-      for (const dep of item.devDependencies) {
-        devDeps.add(dep);
-      }
-    }
-  }
-  return {
-    dependencies: Array.from(deps).sort(),
-    devDependencies: Array.from(devDeps).sort()
-  };
-}
-
 // src/utils/fs.ts
 import {
   writeFileSync as writeFileSync3,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   existsSync as existsSync4,
   mkdirSync as mkdirSync2
 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { dirname as dirname3, join as join6 } from "path";
 function resolveOutputPath(registryPath, type, config, cwd) {
   let relativePath;
   if (type === "registry:block") {
     relativePath = registryPath.replace(/^blocks\//, "");
-    return join5(cwd, config.paths.blocks, relativePath);
+    return join6(cwd, config.paths.blocks, relativePath);
   }
   if (type === "registry:ui") {
     if (registryPath.startsWith("components/deck/")) {
       relativePath = registryPath.replace(/^components\/deck\//, "");
-      return join5(cwd, config.paths.deckComponents, relativePath);
+      return join6(cwd, config.paths.deckComponents, relativePath);
     }
     relativePath = registryPath.replace(/^components\/ui\//, "");
-    return join5(cwd, config.paths.components, relativePath);
+    return join6(cwd, config.paths.components, relativePath);
   }
   if (type === "registry:hook") {
     relativePath = registryPath.replace(/^hooks\//, "");
-    return join5(cwd, config.paths.hooks, relativePath);
+    return join6(cwd, config.paths.hooks, relativePath);
   }
   if (type === "registry:lib") {
     relativePath = registryPath.replace(/^lib\//, "");
-    return join5(cwd, config.paths.lib, relativePath);
+    return join6(cwd, config.paths.lib, relativePath);
   }
-  return join5(cwd, registryPath);
+  return join6(cwd, registryPath);
 }
 function writeFile(filePath, content) {
   const dir = dirname3(filePath);
@@ -345,7 +802,7 @@ function writeFile(filePath, content) {
 }
 function readFile(filePath) {
   if (!existsSync4(filePath)) return null;
-  return readFileSync4(filePath, "utf-8");
+  return readFileSync5(filePath, "utf-8");
 }
 function fileExists(filePath) {
   return existsSync4(filePath);
@@ -491,6 +948,8 @@ function listCommand(cwd, options = {}) {
 // src/commands/add.ts
 function addCommand(components, cwd, options = {}) {
   const json = options.json ?? false;
+  const dryRun = options.dryRun ?? false;
+  const prefix = dryRun ? "[dry-run] " : "";
   let autoInitialized = false;
   if (!configExists(cwd)) {
     writeConfig(cwd, DEFAULT_CONFIG);
@@ -618,9 +1077,12 @@ function addCommand(components, cwd, options = {}) {
     }
     process.exit(1);
   }
+  const circularWarnings = [];
   let items;
   try {
-    items = resolveTransitiveDeps(registry, itemNames);
+    items = resolveTransitiveDeps(registry, itemNames, (msg) => {
+      circularWarnings.push(msg);
+    });
   } catch (error) {
     if (json) {
       const message = error instanceof Error ? error.message : String(error);
@@ -629,6 +1091,11 @@ function addCommand(components, cwd, options = {}) {
     }
     throw error;
   }
+  if (circularWarnings.length > 0 && !json) {
+    for (const warning of circularWarnings) {
+      logger.warn(warning);
+    }
+  }
   if (!json) {
     logger.info(
       `Resolving ${itemNames.length} item(s) \u2192 ${items.length} total (with dependencies)`
@@ -645,16 +1112,18 @@ function addCommand(components, cwd, options = {}) {
         config,
         cwd
       );
-      if (fileExists(outputPath) && !options.overwrite) {
+      if (!dryRun && fileExists(outputPath) && !options.overwrite) {
         if (!json) {
-          logger.item(`skip ${file.path} (already exists)`);
+          logger.item(`${prefix}skip ${file.path} (already exists)`);
         }
         skippedFiles.push(file.path);
         continue;
       }
-      writeFile(outputPath, file.content);
+      if (!dryRun) {
+        writeFile(outputPath, file.content);
+      }
       if (!json) {
-        logger.success(file.path);
+        logger.success(`${prefix}${file.path}`);
       }
       writtenFiles.push(file.path);
     }
@@ -662,41 +1131,57 @@ function addCommand(components, cwd, options = {}) {
   if (!json) {
     logger.blank();
     logger.info(
-      `Files: ${writtenFiles.length} written, ${skippedFiles.length} skipped`
+      `${prefix}Files: ${writtenFiles.length} written, ${skippedFiles.length} skipped`
     );
   }
   const { dependencies, devDependencies } = collectDependencies(items);
-  const uninstalledDeps = getUninstalledDeps(dependencies, cwd);
-  const uninstalledDevDeps = getUninstalledDeps(devDependencies, cwd);
+  const uninstalledDeps = dryRun ? dependencies : getUninstalledDeps(dependencies, cwd);
+  const uninstalledDevDeps = dryRun ? devDependencies : getUninstalledDeps(devDependencies, cwd);
   const installedDeps = [];
   const failedDeps = [];
   if (uninstalledDeps.length > 0) {
-    if (!json) {
-      logger.blank();
-      logger.info("Installing dependencies...");
-    }
-    if (installPackages(uninstalledDeps, cwd)) {
+    if (dryRun) {
+      if (!json) {
+        logger.blank();
+        logger.info(`${prefix}Would install dependencies: ${uninstalledDeps.join(", ")}`);
+      }
       installedDeps.push(...uninstalledDeps);
     } else {
-      failedDeps.push(...uninstalledDeps);
       if (!json) {
-        logger.warn("Some dependencies failed to install. Install them manually:");
-        logger.info(`  npm install ${uninstalledDeps.join(" ")}`);
+        logger.blank();
+        logger.info("Installing dependencies...");
+      }
+      if (installPackages(uninstalledDeps, cwd)) {
+        installedDeps.push(...uninstalledDeps);
+      } else {
+        failedDeps.push(...uninstalledDeps);
+        if (!json) {
+          logger.warn("Some dependencies failed to install. Install them manually:");
+          logger.info(`  npm install ${uninstalledDeps.join(" ")}`);
+        }
       }
     }
   }
   if (uninstalledDevDeps.length > 0) {
-    if (!json) {
-      logger.blank();
-      logger.info("Installing dev dependencies...");
-    }
-    if (installPackages(uninstalledDevDeps, cwd, true)) {
+    if (dryRun) {
+      if (!json) {
+        logger.blank();
+        logger.info(`${prefix}Would install dev dependencies: ${uninstalledDevDeps.join(", ")}`);
+      }
       installedDeps.push(...uninstalledDevDeps);
     } else {
-      failedDeps.push(...uninstalledDevDeps);
       if (!json) {
-        logger.warn("Some dev dependencies failed to install. Install them manually:");
-        logger.info(`  npm install --save-dev ${uninstalledDevDeps.join(" ")}`);
+        logger.blank();
+        logger.info("Installing dev dependencies...");
+      }
+      if (installPackages(uninstalledDevDeps, cwd, true)) {
+        installedDeps.push(...uninstalledDevDeps);
+      } else {
+        failedDeps.push(...uninstalledDevDeps);
+        if (!json) {
+          logger.warn("Some dev dependencies failed to install. Install them manually:");
+          logger.info(`  npm install --save-dev ${uninstalledDevDeps.join(" ")}`);
+        }
       }
     }
   }
@@ -715,7 +1200,8 @@ function addCommand(components, cwd, options = {}) {
     console.log(
       JSON.stringify(
         {
-          success: true,
+          success: failedDeps.length === 0,
+          ...dryRun ? { dryRun: true } : {},
           autoInitialized,
           requested: itemNames,
           resolved: items.map((i) => i.name),
@@ -727,7 +1213,10 @@ function addCommand(components, cwd, options = {}) {
         2
       )
     );
-    process.exit(0);
+    process.exit(failedDeps.length > 0 ? 1 : 0);
+  }
+  if (failedDeps.length > 0) {
+    process.exit(1);
   }
 }
 
@@ -750,10 +1239,15 @@ function hasDifferences(localContent, registryContent) {
 // src/commands/diff.ts
 function diffCommand(componentName, cwd, options = {}) {
   const json = options.json ?? false;
+  const all = options.all ?? false;
   let config;
   let registry;
   try {
-    config = loadConfig(cwd);
+    if (all && !configExists(cwd)) {
+      config = DEFAULT_CONFIG;
+    } else {
+      config = loadConfig(cwd);
+    }
     registry = loadRegistry();
   } catch (error) {
     if (json) {
@@ -763,6 +1257,79 @@ function diffCommand(componentName, cwd, options = {}) {
     }
     throw error;
   }
+  if (all) {
+    const results = [];
+    for (const item of registry.items) {
+      const changedFiles = [];
+      let hasModified = false;
+      let hasAdded = false;
+      for (const file of item.files) {
+        const outputPath = resolveOutputPath(
+          file.path,
+          file.type,
+          config,
+          cwd
+        );
+        const localContent = readFile(outputPath);
+        if (localContent === null) {
+          hasAdded = true;
+          changedFiles.push(file.path);
+          continue;
+        }
+        if (hasDifferences(localContent, file.content)) {
+          hasModified = true;
+          changedFiles.push(file.path);
+        }
+      }
+      let changeType;
+      if (hasModified) {
+        changeType = "modified";
+      } else if (hasAdded && changedFiles.length === item.files.length) {
+        changeType = "added";
+      } else if (hasAdded) {
+        changeType = "modified";
+      } else {
+        changeType = "unchanged";
+      }
+      results.push({
+        component: item.name,
+        changeType,
+        files: changedFiles,
+        breakingChange: false,
+        migrationNote: null
+      });
+    }
+    const total = results.length;
+    const changed = results.filter((r) => r.changeType !== "unchanged").length;
+    const unchanged = total - changed;
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            success: true,
+            results,
+            summary: { total, changed, unchanged }
+          },
+          null,
+          2
+        )
+      );
+      process.exit(0);
+      return;
+    }
+    const changedItems = results.filter((r) => r.changeType !== "unchanged");
+    if (changedItems.length === 0) {
+      logger.success(`All ${total} components match the registry.`);
+    } else {
+      logger.heading(`${changed} component(s) with upstream changes`);
+      for (const r of changedItems) {
+        logger.info(`  ${r.component} [${r.changeType}]: ${r.files.join(", ")}`);
+      }
+      logger.blank();
+      logger.info(`Total: ${total} | Changed: ${changed} | Unchanged: ${unchanged}`);
+    }
+    return;
+  }
   const itemsToDiff = componentName ? (() => {
     const item = findItem(registry, componentName);
     if (!item) {
@@ -850,9 +1417,87 @@ function diffCommand(componentName, cwd, options = {}) {
   }
 }
 
+// src/commands/info.ts
+function infoCommand(name, cwd, options = {}) {
+  const json = options.json ?? false;
+  let manifest;
+  try {
+    manifest = loadManifest();
+  } catch (error) {
+    if (json) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(JSON.stringify({ success: false, error: message }, null, 2));
+      process.exit(1);
+    }
+    throw error;
+  }
+  let kind = null;
+  let data = null;
+  if (name in manifest.components) {
+    kind = "component";
+    data = manifest.components[name];
+  } else if (name in manifest.hooks) {
+    kind = "hook";
+    data = manifest.hooks[name];
+  } else if (name in manifest.blocks) {
+    kind = "block";
+    data = manifest.blocks[name];
+  } else if (name in manifest.patterns) {
+    kind = "pattern";
+    data = manifest.patterns[name];
+  }
+  if (kind === null || data === null) {
+    const errorPayload = {
+      success: false,
+      error: `Component ${name} not found. Run visor list --json to see available names.`
+    };
+    if (json) {
+      console.error(JSON.stringify(errorPayload, null, 2));
+    } else {
+      logger.error(errorPayload.error);
+    }
+    process.exit(1);
+    return;
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          name,
+          kind,
+          data
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const entry = data;
+  logger.heading(`${name} (${kind})`);
+  logger.blank();
+  if (entry.description) {
+    logger.info(String(entry.description));
+    logger.blank();
+  }
+  if (Array.isArray(entry.when_to_use) && entry.when_to_use.length > 0) {
+    logger.info("When to use:");
+    for (const item of entry.when_to_use) {
+      logger.info(`  \u2022 ${item}`);
+    }
+    logger.blank();
+  }
+  if (entry.example) {
+    logger.info("Example:");
+    logger.info(String(entry.example));
+  }
+}
+
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
-import { resolve, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
+import { resolve as resolve2, dirname as dirname4 } from "path";
 import { generateTheme, generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
@@ -879,10 +1524,10 @@ function defaultOutputPath(adapter, themeName) {
   }
 }
 function themeApplyCommand(file, cwd, options) {
-  const filePath = resolve(cwd, file);
+  const filePath = resolve2(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync5(filePath, "utf-8");
+    yamlContent = readFileSync6(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -947,7 +1592,7 @@ function themeApplyCommand(file, cwd, options) {
     process.exit(1);
   }
   const outputFile = options.output ?? defaultOutputPath(options.adapter, themeName);
-  const outputPath = resolve(cwd, outputFile);
+  const outputPath = resolve2(cwd, outputFile);
   const outputDir = dirname4(outputPath);
   try {
     mkdirSync3(outputDir, { recursive: true });
@@ -992,8 +1637,8 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { resolve as resolve2 } from "path";
+import { readFileSync as readFileSync7 } from "fs";
+import { resolve as resolve3 } from "path";
 import {
   parseConfig,
   resolveConfig,
@@ -1001,10 +1646,10 @@ import {
   exportTheme
 } from "@loworbitstudio/visor-theme-engine";
 function themeExportCommand(file, cwd, options) {
-  const filePath = resolve2(cwd, file ?? ".visor.yaml");
+  const filePath = resolve3(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync6(filePath, "utf-8");
+    yamlContent = readFileSync7(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -1056,16 +1701,16 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync8 } from "fs";
+import { resolve as resolve4 } from "path";
 import { parse as parseYaml } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
 import pc2 from "picocolors";
 function themeValidateCommand(file, cwd, options) {
-  const filePath = resolve3(cwd, file);
+  const filePath = resolve4(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync7(filePath, "utf-8");
+    fileContent = readFileSync8(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -1147,13 +1792,13 @@ function themeValidateCommand(file, cwd, options) {
 function printIssue(issue) {
   const prefix = issue.severity === "error" ? pc2.red("  ERROR") : pc2.yellow("  WARN ");
   const code = pc2.dim(`[${issue.code}]`);
-  const path = issue.path ? pc2.dim(` (${issue.path})`) : "";
-  console.log(`${prefix} ${code} ${issue.message}${path}`);
+  const path2 = issue.path ? pc2.dim(` (${issue.path})`) : "";
+  console.log(`${prefix} ${code} ${issue.message}${path2}`);
 }
 
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, existsSync as existsSync5, readdirSync, statSync } from "fs";
-import { resolve as resolve4, join as join6, basename, extname, relative } from "path";
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync5, existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { resolve as resolve5, join as join7, basename, extname as extname2, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -1182,7 +1827,7 @@ var CSS_DIRS = [
   "packages/design-tokens"
 ];
 function themeExtractCommand(cwd, options) {
-  const targetDir = resolve4(cwd, options.from ?? ".");
+  const targetDir = resolve5(cwd, options.from ?? ".");
   if (!existsSync5(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
@@ -1236,17 +1881,17 @@ function themeExtractCommand(cwd, options) {
 function collectCSSFiles(targetDir) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const pattern of CSS_FILE_PATTERNS) {
-    const rootPath = join6(targetDir, pattern);
+  for (const pattern2 of CSS_FILE_PATTERNS) {
+    const rootPath = join7(targetDir, pattern2);
     addFileIfExists(rootPath, files, seen);
     for (const dir of CSS_DIRS) {
-      const dirPath = join6(targetDir, dir, pattern);
+      const dirPath = join7(targetDir, dir, pattern2);
       addFileIfExists(dirPath, files, seen);
     }
   }
   for (const dir of CSS_DIRS) {
-    const dirPath = join6(targetDir, dir);
-    if (existsSync5(dirPath) && statSync(dirPath).isDirectory()) {
+    const dirPath = join7(targetDir, dir);
+    if (existsSync5(dirPath) && statSync2(dirPath).isDirectory()) {
       scanDirForCSS(dirPath, files, seen, 2);
     }
   }
@@ -1254,11 +1899,11 @@ function collectCSSFiles(targetDir) {
   return files;
 }
 function addFileIfExists(filePath, files, seen) {
-  const resolved = resolve4(filePath);
+  const resolved = resolve5(filePath);
   if (seen.has(resolved)) return;
   if (!existsSync5(resolved)) return;
   try {
-    const content = readFileSync8(resolved, "utf-8");
+    const content = readFileSync9(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -1281,15 +1926,15 @@ function scanDirForCSS(dir, files, seen, maxDepth) {
     ".vercel"
   ]);
   try {
-    const entries = readdirSync(dir, { withFileTypes: true });
+    const entries = readdirSync2(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
         if (maxDepth > 0) {
-          scanDirForCSS(join6(dir, entry.name), files, seen, maxDepth - 1);
+          scanDirForCSS(join7(dir, entry.name), files, seen, maxDepth - 1);
         }
-      } else if (entry.isFile() && extname(entry.name) === ".css") {
-        addFileIfExists(join6(dir, entry.name), files, seen);
+      } else if (entry.isFile() && extname2(entry.name) === ".css") {
+        addFileIfExists(join7(dir, entry.name), files, seen);
       }
     }
   } catch {
@@ -1371,10 +2016,10 @@ function extractVarName(varExpr) {
 function parseNextFontFromLayouts(targetDir) {
   const fontMap = /* @__PURE__ */ new Map();
   for (const relPath of LAYOUT_FILE_PATHS) {
-    const fullPath = join6(targetDir, relPath);
+    const fullPath = join7(targetDir, relPath);
     if (!existsSync5(fullPath)) continue;
     try {
-      const content = readFileSync8(fullPath, "utf-8");
+      const content = readFileSync9(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -1421,7 +2066,7 @@ function parseNextFontDeclarations(content, fontMap) {
       const srcMatch = block.match(/src\s*:\s*["']([^"']+)["']/);
       if (srcMatch) {
         const srcPath = srcMatch[1];
-        const fileName = basename(srcPath, extname(srcPath));
+        const fileName = basename(srcPath, extname2(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);
@@ -1459,10 +2104,10 @@ var MONO_FONT_NAMES = /* @__PURE__ */ new Set([
   "IBM Plex Mono"
 ]);
 function extractFontHints(targetDir) {
-  const pkgPath = join6(targetDir, "package.json");
+  const pkgPath = join7(targetDir, "package.json");
   if (!existsSync5(pkgPath)) return void 0;
   try {
-    const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -1498,10 +2143,10 @@ function extractFontHints(targetDir) {
   }
 }
 function inferThemeName(targetDir) {
-  const pkgPath = join6(targetDir, "package.json");
+  const pkgPath = join7(targetDir, "package.json");
   if (existsSync5(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
       if (pkg.name) {
         const name = pkg.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -1538,7 +2183,7 @@ function outputJSON(result, validationResult) {
 }
 function outputYAML(result, outputPath, cwd, validationResult) {
   const yamlStr = buildAnnotatedYAML(result);
-  const outFile = resolve4(cwd, outputPath ?? ".visor.yaml");
+  const outFile = resolve5(cwd, outputPath ?? ".visor.yaml");
   const high = result.tokens.filter((t) => t.confidence === "high").length;
   const med = result.tokens.filter((t) => t.confidence === "medium").length;
   const low = result.tokens.filter((t) => t.confidence === "low").length;
@@ -1624,14 +2269,14 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync9, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4, existsSync as existsSync7 } from "fs";
-import { resolve as resolve6, join as join8 } from "path";
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4, existsSync as existsSync7 } from "fs";
+import { resolve as resolve7, join as join9 } from "path";
 import { generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
 import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve5, dirname as dirname5, join as join7 } from "path";
+import { resolve as resolve6, dirname as dirname5, join as join8 } from "path";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
 }
@@ -1639,9 +2284,9 @@ function toLabel(name) {
   return name.split(/[\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function findRepoRoot(startDir) {
-  let current = resolve5(startDir);
+  let current = resolve6(startDir);
   while (true) {
-    if (existsSync6(join7(current, "packages", "docs"))) {
+    if (existsSync6(join8(current, "packages", "docs"))) {
       return current;
     }
     const parent = dirname5(current);
@@ -1736,10 +2381,10 @@ ${indent}${newEntry},
   return { updated, changed: true };
 }
 function themeRegisterCommand(file, cwd, options) {
-  const filePath = resolve6(cwd, file);
+  const filePath = resolve7(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync9(filePath, "utf-8");
+    yamlContent = readFileSync10(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -1782,10 +2427,10 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join8(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join8(docsAppDir, `${slug}-theme.css`);
-  const globalsPath = join8(docsAppDir, "globals.css");
-  const themeConfigPath = join8(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const docsAppDir = join9(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join9(docsAppDir, `${slug}-theme.css`);
+  const globalsPath = join9(docsAppDir, "globals.css");
+  const themeConfigPath = join9(repoRoot, "packages", "docs", "lib", "theme-config.ts");
   if (!existsSync7(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
@@ -1799,8 +2444,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync9(globalsPath, "utf-8");
-    themeConfigContent = readFileSync9(themeConfigPath, "utf-8");
+    globalsContent = readFileSync10(globalsPath, "utf-8");
+    themeConfigContent = readFileSync10(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -1812,7 +2457,7 @@ function themeRegisterCommand(file, cwd, options) {
     return;
   }
   const cssExists = existsSync7(cssFilePath);
-  const cssChanged = !cssExists || readFileSync9(cssFilePath, "utf-8") !== css;
+  const cssChanged = !cssExists || readFileSync10(cssFilePath, "utf-8") !== css;
   const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
@@ -1896,8 +2541,8 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync7, existsSync as existsSync8, unlinkSync } from "fs";
-import { join as join9 } from "path";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync7, existsSync as existsSync8, unlinkSync } from "fs";
+import { join as join10 } from "path";
 function removeGlobalsImport(content, slug) {
   const importLine = `@import './${slug}-theme.css';`;
   if (!content.includes(importLine)) {
@@ -1929,10 +2574,10 @@ function themeUnregisterCommand(slug, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join9(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join9(docsAppDir, `${slug}-theme.css`);
-  const globalsPath = join9(docsAppDir, "globals.css");
-  const themeConfigPath = join9(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const docsAppDir = join10(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join10(docsAppDir, `${slug}-theme.css`);
+  const globalsPath = join10(docsAppDir, "globals.css");
+  const themeConfigPath = join10(repoRoot, "packages", "docs", "lib", "theme-config.ts");
   if (!existsSync8(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
@@ -1946,8 +2591,8 @@ function themeUnregisterCommand(slug, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync10(globalsPath, "utf-8");
-    themeConfigContent = readFileSync10(themeConfigPath, "utf-8");
+    globalsContent = readFileSync11(globalsPath, "utf-8");
+    themeConfigContent = readFileSync11(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -1999,32 +2644,47 @@ function themeUnregisterCommand(slug, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync11,
+  readFileSync as readFileSync12,
   writeFileSync as writeFileSync8,
   mkdirSync as mkdirSync5,
   existsSync as existsSync9,
-  readdirSync as readdirSync2,
+  readdirSync as readdirSync3,
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join10, basename as basename2 } from "path";
+import { join as join11, basename as basename2 } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
-var GLOBALS_BEGIN_MARKER = "/* BEGIN visor-theme-imports \u2014 generated by `visor theme sync` */";
+var GLOBALS_BEGIN_MARKER = "/* BEGIN visor-theme-imports \u2014 managed by `visor theme sync` */";
 var GLOBALS_END_MARKER = "/* END visor-theme-imports */";
+var STOCK_GROUPS_BEGIN_MARKER = "/* BEGIN visor-stock-themes \u2014 managed by `visor theme sync` */";
+var STOCK_GROUPS_END_MARKER = "/* END visor-stock-themes */";
 var GITIGNORE_BEGIN_MARKER = "# BEGIN visor-custom-theme-css (managed by `visor theme sync` \u2014 do not edit manually)";
 var GITIGNORE_END_MARKER = "# END visor-custom-theme-css";
-var THEME_CONFIG_HEADER = "// This file is auto-generated by `visor theme sync`. Do not edit manually.\n";
+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 (!existsSync9(dir)) return [];
-  return readdirSync2(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join10(dir, f));
+  return readdirSync3(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join11(dir, f));
 }
 function extractGroup(yamlContent) {
   const parsed = parseYaml2(yamlContent);
   if (typeof parsed?.group === "string") return parsed.group;
   return void 0;
 }
+function extractLabel(yamlContent) {
+  const parsed = parseYaml2(yamlContent);
+  if (typeof parsed?.label === "string") return parsed.label;
+  return void 0;
+}
+function extractDefaultMode(yamlContent) {
+  const parsed = parseYaml2(yamlContent);
+  const v = parsed?.["default-mode"];
+  if (v === "dark" || v === "light") return v;
+  return void 0;
+}
 function sortGroups(groups) {
   return [...groups].sort((a, b) => {
     if (a === "Visor") return -1;
@@ -2032,9 +2692,113 @@ function sortGroups(groups) {
     return a.localeCompare(b);
   });
 }
-function generateThemeConfig(entries) {
+function updateGlobalsImports(content, stockSlugs) {
+  const importLines = [...stockSlugs].sort().map((slug) => `@import './${slug}-theme.css';`).join("\n");
+  const newBlock = `${GLOBALS_BEGIN_MARKER}
+${importLines}
+${GLOBALS_END_MARKER}`;
+  let updated;
+  const beginIdx = content.indexOf(GLOBALS_BEGIN_MARKER);
+  const endIdx = content.indexOf(GLOBALS_END_MARKER);
+  if (beginIdx !== -1 && endIdx !== -1) {
+    updated = content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GLOBALS_END_MARKER.length);
+  } else {
+    const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';\n?/gm;
+    const lines = content.split("\n");
+    let firstThemeIdx = -1;
+    let lastThemeIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines[i])) {
+        if (firstThemeIdx === -1) firstThemeIdx = i;
+        lastThemeIdx = i;
+      }
+    }
+    if (firstThemeIdx !== -1) {
+      const before = lines.slice(0, firstThemeIdx);
+      const after = lines.slice(lastThemeIdx + 1);
+      updated = [...before, newBlock, ...after].join("\n");
+    } else {
+      void themeImportPattern;
+      const lastImportIdx = lines.reduce(
+        (last, line, i) => line.startsWith("@import") ? i : last,
+        -1
+      );
+      const insertAt = lastImportIdx + 1;
+      lines.splice(insertAt, 0, newBlock);
+      updated = lines.join("\n");
+    }
+  }
+  updated = ensureCustomOverlayImport(updated);
+  return updated;
+}
+function ensureCustomOverlayImport(content) {
+  const endMarkerIdx = content.indexOf(GLOBALS_END_MARKER);
+  if (endMarkerIdx === -1) return content;
+  const afterMarker = content.slice(endMarkerIdx + GLOBALS_END_MARKER.length);
+  if (afterMarker.trimStart().startsWith(CUSTOM_OVERLAY_IMPORT_LINE)) return content;
+  const withoutStale = content.replace(
+    new RegExp(`\\n?${CUSTOM_OVERLAY_IMPORT_LINE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+    ""
+  );
+  const markerEnd = withoutStale.indexOf(GLOBALS_END_MARKER) + GLOBALS_END_MARKER.length;
+  return withoutStale.slice(0, markerEnd) + "\n" + CUSTOM_OVERLAY_IMPORT_LINE + withoutStale.slice(markerEnd);
+}
+function updateStockThemeConfigBlock(content, stockEntries) {
+  const groupMap = /* @__PURE__ */ new Map();
+  for (const entry of stockEntries) {
+    if (!groupMap.has(entry.group)) groupMap.set(entry.group, []);
+    groupMap.get(entry.group).push(entry);
+  }
+  const sortedGroupNames = sortGroups([...groupMap.keys()]);
+  for (const [, groupEntries] of groupMap) {
+    groupEntries.sort((a, b) => a.slug.localeCompare(b.slug));
+  }
+  const groupsTs = sortedGroupNames.map((groupName) => {
+    const groupEntries = groupMap.get(groupName);
+    const themesTs = groupEntries.map((e) => {
+      const modePart = e.defaultMode ? `, defaultMode: "${e.defaultMode}"` : "";
+      return `      { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}"${modePart} },`;
+    }).join("\n");
+    return `  {
+    label: "${groupName}",
+    themes: [
+${themesTs}
+    ],
+  },`;
+  }).join("\n");
+  const newBlock = `${STOCK_GROUPS_BEGIN_MARKER}
+const STOCK_GROUPS: ThemeGroup[] = [
+${groupsTs}
+];
+${STOCK_GROUPS_END_MARKER}`;
+  const beginIdx = content.indexOf(STOCK_GROUPS_BEGIN_MARKER);
+  const endIdx = content.indexOf(STOCK_GROUPS_END_MARKER);
+  if (beginIdx !== -1 && endIdx !== -1) {
+    return content.slice(0, beginIdx) + newBlock + content.slice(endIdx + STOCK_GROUPS_END_MARKER.length);
+  }
+  const themeGroupsExportIdx = content.indexOf("export const THEME_GROUPS");
+  if (themeGroupsExportIdx !== -1) {
+    return content.slice(0, themeGroupsExportIdx) + newBlock + "\n\n" + content.slice(themeGroupsExportIdx);
+  }
+  return content + "\n\n" + newBlock;
+}
+function generateCustomOverlayCss(customEntries) {
+  if (customEntries.length === 0) {
+    return "/* generated by `visor theme sync` \u2014 empty when no custom themes are present */\n";
+  }
+  const importLines = [...customEntries].sort((a, b) => a.slug.localeCompare(b.slug)).map((e) => `@import './${e.slug}-theme.css';`).join("\n");
+  return `/* generated by \`visor theme sync\` \u2014 do not edit manually */
+${importLines}
+`;
+}
+function generateCustomOverlayTs(customEntries) {
+  if (customEntries.length === 0) {
+    return `import type { ThemeGroup } from "./theme-config";
+export const customThemeGroups: ThemeGroup[] = [];
+`;
+  }
   const groupMap = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
+  for (const entry of customEntries) {
     if (!groupMap.has(entry.group)) groupMap.set(entry.group, []);
     groupMap.get(entry.group).push(entry);
   }
@@ -2044,7 +2808,10 @@ function generateThemeConfig(entries) {
   }
   const groupsTs = sortedGroupNames.map((groupName) => {
     const groupEntries = groupMap.get(groupName);
-    const themesTs = groupEntries.map((e) => `    { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}" },`).join("\n");
+    const themesTs = groupEntries.map((e) => {
+      const modePart = e.defaultMode ? `, defaultMode: "${e.defaultMode}"` : "";
+      return `      { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}"${modePart} },`;
+    }).join("\n");
     return `  {
     label: "${groupName}",
     themes: [
@@ -2052,60 +2819,13 @@ ${themesTs}
     ],
   },`;
   }).join("\n");
-  return `${THEME_CONFIG_HEADER}
-export interface ThemeEntry {
-  value: string;
-  label: string;
-  /** Filename (without .visor.yaml extension) if a YAML config exists in /public/themes/ */
-  yamlFile?: string;
-}
-
-export interface ThemeGroup {
-  label: string;
-  themes: ThemeEntry[];
-}
-
-export const THEME_GROUPS: ThemeGroup[] = [
+  return `import type { ThemeGroup } from "./theme-config";
+// generated by \`visor theme sync\` \u2014 do not edit manually
+export const customThemeGroups: ThemeGroup[] = [
 ${groupsTs}
 ];
-
-export const ALL_THEMES = THEME_GROUPS.flatMap((g) => g.themes.map((t) => t.value));
 `;
 }
-function updateGlobalsImports(content, slugs) {
-  const importLines = [...slugs].sort().map((slug) => `@import './${slug}-theme.css';`).join("\n");
-  const newBlock = `${GLOBALS_BEGIN_MARKER}
-${importLines}
-${GLOBALS_END_MARKER}`;
-  const beginIdx = content.indexOf(GLOBALS_BEGIN_MARKER);
-  const endIdx = content.indexOf(GLOBALS_END_MARKER);
-  if (beginIdx !== -1 && endIdx !== -1) {
-    return content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GLOBALS_END_MARKER.length);
-  }
-  const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';\n?/gm;
-  const lines = content.split("\n");
-  let firstThemeIdx = -1;
-  let lastThemeIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines[i])) {
-      if (firstThemeIdx === -1) firstThemeIdx = i;
-      lastThemeIdx = i;
-    }
-  }
-  if (firstThemeIdx !== -1) {
-    const before = lines.slice(0, firstThemeIdx);
-    const after = lines.slice(lastThemeIdx + 1);
-    return [...before, newBlock, ...after].join("\n");
-  }
-  void themeImportPattern;
-  const lastImportIdx = lines.reduce(
-    (last, line, i) => line.startsWith("@import") ? i : last,
-    -1
-  );
-  const insertAt = lastImportIdx + 1;
-  lines.splice(insertAt, 0, newBlock);
-  return lines.join("\n");
-}
 function updateGitignoreBlock(content, customSlugs) {
   const cssLines = customSlugs.sort().map((slug) => `packages/docs/app/${slug}-theme.css`).join("\n");
   const newBlock = `${GITIGNORE_BEGIN_MARKER}
@@ -2130,13 +2850,16 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join10(repoRoot, "themes");
-  const customThemesDir = join10(repoRoot, "custom-themes");
-  const docsAppDir = join10(repoRoot, "packages", "docs", "app");
-  const docsPublicThemesDir = join10(repoRoot, "packages", "docs", "public", "themes");
-  const themeConfigPath = join10(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  const globalsPath = join10(docsAppDir, "globals.css");
-  const gitignorePath = join10(repoRoot, ".gitignore");
+  const themesDir = join11(repoRoot, "themes");
+  const customThemesDir = join11(repoRoot, "custom-themes");
+  const docsAppDir = join11(repoRoot, "packages", "docs", "app");
+  const docsLibDir = join11(repoRoot, "packages", "docs", "lib");
+  const docsPublicThemesDir = join11(repoRoot, "packages", "docs", "public", "themes");
+  const themeConfigPath = join11(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const globalsPath = join11(docsAppDir, "globals.css");
+  const gitignorePath = join11(repoRoot, ".gitignore");
+  const customOverlayCssPath = join11(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
+  const customOverlayTsPath = join11(repoRoot, CUSTOM_OVERLAY_TS_PATH);
   const stockFiles = scanThemeDir(themesDir);
   const customFiles = scanThemeDir(customThemesDir);
   if (stockFiles.length === 0 && customFiles.length === 0) {
@@ -2153,7 +2876,7 @@ function themeSyncCommand(cwd, options) {
   const processFile = (filePath, isCustom) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync11(filePath, "utf-8");
+      yamlContent = readFileSync12(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       return;
@@ -2166,11 +2889,12 @@ function themeSyncCommand(cwd, options) {
       return;
     }
     const slug = toSlug(data.config.name);
-    const label = toLabel(data.config.name);
+    const label = extractLabel(yamlContent) ?? toLabel(data.config.name);
     const group = extractGroup(yamlContent) ?? (isCustom ? "Custom" : "Visor");
+    const defaultMode = extractDefaultMode(yamlContent);
     const css = docsAdapter3({ primitives: data.primitives, tokens: data.tokens, config: data.config });
     const yamlFilename = basename2(filePath).replace(/\.visor\.yaml$/, "");
-    manifest.push({ slug, label, group, css, yamlFilename, isCustom });
+    manifest.push({ slug, label, group, defaultMode, css, yamlFilename, isCustom });
   };
   for (const f of stockFiles) processFile(f, false);
   for (const f of customFiles) processFile(f, true);
@@ -2183,14 +2907,18 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const newThemeConfig = generateThemeConfig(manifest);
+  const stockManifest = manifest.filter((e) => !e.isCustom);
+  const customManifest = manifest.filter((e) => e.isCustom);
+  const stockSlugs = stockManifest.map((e) => e.slug);
+  const customSlugs = customManifest.map((e) => e.slug);
   const allSlugs = manifest.map((e) => e.slug);
-  const customSlugs = manifest.filter((e) => e.isCustom).map((e) => e.slug);
   let globalsContent;
+  let themeConfigContent;
   let gitignoreContent;
   try {
-    globalsContent = readFileSync11(globalsPath, "utf-8");
-    gitignoreContent = existsSync9(gitignorePath) ? readFileSync11(gitignorePath, "utf-8") : "";
+    globalsContent = readFileSync12(globalsPath, "utf-8");
+    themeConfigContent = readFileSync12(themeConfigPath, "utf-8");
+    gitignoreContent = existsSync9(gitignorePath) ? readFileSync12(gitignorePath, "utf-8") : "";
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -2201,12 +2929,17 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const newGlobals = updateGlobalsImports(globalsContent, allSlugs);
+  const newGlobals = updateGlobalsImports(globalsContent, stockSlugs);
+  const newThemeConfig = updateStockThemeConfigBlock(themeConfigContent, stockManifest);
   const newGitignore = customSlugs.length > 0 ? updateGitignoreBlock(gitignoreContent, customSlugs) : gitignoreContent;
-  const existingCssFiles = existsSync9(docsAppDir) ? readdirSync2(docsAppDir).filter((f) => f.endsWith("-theme.css")) : [];
+  const newCustomOverlayCss = generateCustomOverlayCss(customManifest);
+  const newCustomOverlayTs = generateCustomOverlayTs(customManifest);
+  const existingCssFiles = existsSync9(docsAppDir) ? readdirSync3(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 = existsSync9(docsPublicThemesDir) ? readdirSync2(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
+  const existingPublicYamls = existsSync9(docsPublicThemesDir) ? readdirSync3(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) {
@@ -2216,6 +2949,8 @@ function themeSyncCommand(cwd, options) {
       cssFilesDeleted: staleCssFiles.map((f) => `packages/docs/app/${f}`),
       themeConfig: themeConfigPath,
       globalsCSS: globalsPath,
+      customOverlayCss: CUSTOM_OVERLAY_CSS_PATH,
+      customOverlayTs: CUSTOM_OVERLAY_TS_PATH,
       gitignore: gitignorePath,
       publicYamlsCopied: manifest.map((e) => `packages/docs/public/themes/${e.yamlFilename}.visor.yaml`),
       publicYamlsDeleted: stalePublicYamls.map((f) => `packages/docs/public/themes/${f}`)
@@ -2224,7 +2959,7 @@ function themeSyncCommand(cwd, options) {
       console.log(JSON.stringify({ success: true, dryRun: true, changes }));
     } else {
       logger.info("Dry run \u2014 no files written");
-      logger.item(`Themes discovered: ${manifest.length} (${manifest.filter((e) => !e.isCustom).length} stock, ${manifest.filter((e) => e.isCustom).length} custom)`);
+      logger.item(`Themes discovered: ${manifest.length} (${stockManifest.length} stock, ${customManifest.length} custom)`);
       manifest.forEach((e) => logger.item(`  ${e.slug} \u2014 group: ${e.group}`));
       if (staleCssFiles.length > 0) logger.item(`CSS files to delete: ${staleCssFiles.join(", ")}`);
       if (stalePublicYamls.length > 0) logger.item(`Public YAMLs to delete: ${stalePublicYamls.join(", ")}`);
@@ -2233,13 +2968,16 @@ function themeSyncCommand(cwd, options) {
   }
   try {
     mkdirSync5(docsAppDir, { recursive: true });
+    mkdirSync5(docsLibDir, { recursive: true });
     mkdirSync5(docsPublicThemesDir, { recursive: true });
     for (const entry of manifest) {
-      writeFileSync8(join10(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
+      writeFileSync8(join11(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
     }
     for (const stale of staleCssFiles) {
-      unlinkSync2(join10(docsAppDir, stale));
+      unlinkSync2(join11(docsAppDir, stale));
     }
+    writeFileSync8(customOverlayCssPath, newCustomOverlayCss, "utf-8");
+    writeFileSync8(customOverlayTsPath, newCustomOverlayTs, "utf-8");
     writeFileSync8(themeConfigPath, newThemeConfig, "utf-8");
     writeFileSync8(globalsPath, newGlobals, "utf-8");
     if (existsSync9(gitignorePath)) {
@@ -2248,10 +2986,10 @@ function themeSyncCommand(cwd, options) {
     const allSourceFiles = [...stockFiles, ...customFiles];
     for (const srcFile of allSourceFiles) {
       const filename = basename2(srcFile);
-      copyFileSync(srcFile, join10(docsPublicThemesDir, filename));
+      copyFileSync(srcFile, join11(docsPublicThemesDir, filename));
     }
     for (const stale of stalePublicYamls) {
-      unlinkSync2(join10(docsPublicThemesDir, stale));
+      unlinkSync2(join11(docsPublicThemesDir, stale));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -2267,17 +3005,17 @@ function themeSyncCommand(cwd, options) {
     console.log(JSON.stringify({
       success: true,
       themes: manifest.length,
-      stock: manifest.filter((e) => !e.isCustom).length,
-      custom: manifest.filter((e) => e.isCustom).length,
+      stock: stockManifest.length,
+      custom: customManifest.length,
       staleCssDeleted: staleCssFiles.length,
       staleYamlsDeleted: stalePublicYamls.length,
       slugs: allSlugs
     }));
   } else {
     logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
-    logger.item(`Stock: ${manifest.filter((e) => !e.isCustom).map((e) => e.slug).join(", ")}`);
-    if (manifest.filter((e) => e.isCustom).length > 0) {
-      logger.item(`Custom: ${manifest.filter((e) => e.isCustom).map((e) => e.slug).join(", ")}`);
+    logger.item(`Stock: ${stockManifest.map((e) => e.slug).join(", ")}`);
+    if (customManifest.length > 0) {
+      logger.item(`Custom: ${customManifest.map((e) => e.slug).join(", ")}`);
     }
     if (staleCssFiles.length > 0) {
       logger.item(`Removed stale CSS: ${staleCssFiles.join(", ")}`);
@@ -2286,11 +3024,11 @@ function themeSyncCommand(cwd, options) {
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync10, statSync as statSync2, readdirSync as readdirSync3, readFileSync as readFileSync12 } from "fs";
-import { resolve as resolve7, basename as basename3, extname as extname2 } from "path";
+import { existsSync as existsSync10, statSync as statSync3, readdirSync as readdirSync4, readFileSync as readFileSync13 } from "fs";
+import { resolve as resolve8, basename as basename3, extname as extname3 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
-  const name = basename3(filename, extname2(filename));
+  const name = basename3(filename, extname3(filename));
   const WEIGHT_STYLE_SUFFIXES = /* @__PURE__ */ new Set([
     "thin",
     "hairline",
@@ -2331,13 +3069,13 @@ function deriveFamilySlug(filename) {
   return parts.join("-").toLowerCase();
 }
 function collectWoff2Files(inputPath) {
-  const resolved = resolve7(inputPath);
+  const resolved = resolve8(inputPath);
   if (!existsSync10(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
-  const stat = statSync2(resolved);
+  const stat = statSync3(resolved);
   if (stat.isFile()) {
-    if (extname2(resolved).toLowerCase() !== ".woff2") {
+    if (extname3(resolved).toLowerCase() !== ".woff2") {
       throw new Error(
         `Invalid file format: ${basename3(resolved)}. Only .woff2 files are accepted.`
       );
@@ -2345,14 +3083,14 @@ function collectWoff2Files(inputPath) {
     return [resolved];
   }
   if (stat.isDirectory()) {
-    const files = readdirSync3(resolved).filter((f) => extname2(f).toLowerCase() === ".woff2").map((f) => resolve7(resolved, f));
+    const files = readdirSync4(resolved).filter((f) => extname3(f).toLowerCase() === ".woff2").map((f) => resolve8(resolved, f));
     if (files.length === 0) {
       throw new Error(
         `No .woff2 files found in directory: ${resolved}`
       );
     }
-    const nonWoff2Fonts = readdirSync3(resolved).filter((f) => {
-      const ext = extname2(f).toLowerCase();
+    const nonWoff2Fonts = readdirSync4(resolved).filter((f) => {
+      const ext = extname3(f).toLowerCase();
       return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
     });
     return files.sort();
@@ -2360,12 +3098,12 @@ function collectWoff2Files(inputPath) {
   throw new Error(`Path is neither a file nor a directory: ${resolved}`);
 }
 function getNonWoff2Fonts(inputPath) {
-  const resolved = resolve7(inputPath);
-  if (!existsSync10(resolved) || !statSync2(resolved).isDirectory()) {
+  const resolved = resolve8(inputPath);
+  if (!existsSync10(resolved) || !statSync3(resolved).isDirectory()) {
     return [];
   }
-  return readdirSync3(resolved).filter((f) => {
-    const ext = extname2(f).toLowerCase();
+  return readdirSync4(resolved).filter((f) => {
+    const ext = extname3(f).toLowerCase();
     return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
   });
 }
@@ -2398,7 +3136,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync12(filePath);
+  const body = readFileSync13(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -2414,8 +3152,8 @@ async function fontsAddCommand(inputPath, options) {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
     const familySlug = options.family ?? deriveFamilySlug(basename3(files[0]));
-    const resolved = resolve7(inputPath);
-    const nonWoff2 = statSync2(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
+    const resolved = resolve8(inputPath);
+    const nonWoff2 = statSync3(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
       logger.heading("Visor Font Upload");
       logger.info(`Organization: ${org}`);
@@ -2439,7 +3177,7 @@ async function fontsAddCommand(inputPath, options) {
         logger.info(`Uploading ${filename}...`);
       }
       await uploadFile(client, bucket, key, filePath);
-      const size = statSync2(filePath).size;
+      const size = statSync3(filePath).size;
       results.push({ file: filename, key, size });
       if (!json) {
         logger.success(`Uploaded: ${key} (${formatBytes(size)})`);
@@ -2486,23 +3224,644 @@ function formatBytes(bytes) {
   return `${mb.toFixed(1)} MB`;
 }
 
+// src/commands/doctor.ts
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync as execFileSync2 } from "child_process";
+async function doctorCommand(cwd, options, cliVersion) {
+  const checks = [];
+  const visorJsonPath = path.join(cwd, "visor.json");
+  try {
+    const content = fs.readFileSync(visorJsonPath, "utf-8");
+    JSON.parse(content);
+    checks.push({ name: "visor.json", pass: true, severity: "error", message: "visor.json exists and is valid JSON" });
+  } catch {
+    checks.push({
+      name: "visor.json",
+      pass: false,
+      severity: "error",
+      message: "visor.json missing or invalid",
+      fix: "Run `npx visor init` to initialize Visor in this project"
+    });
+  }
+  const visorCorePath = path.join(cwd, "node_modules", "@loworbitstudio", "visor-core");
+  if (fs.existsSync(visorCorePath)) {
+    checks.push({ name: "visor-core", pass: true, severity: "error", message: "@loworbitstudio/visor-core is installed" });
+  } else {
+    checks.push({
+      name: "visor-core",
+      pass: false,
+      severity: "error",
+      message: "@loworbitstudio/visor-core not found in node_modules",
+      fix: "Run `npm install @loworbitstudio/visor-core`"
+    });
+  }
+  const cssFiles = findCssFiles(cwd);
+  const hasVisorImport = cssFiles.some((f) => {
+    try {
+      const content = fs.readFileSync(f, "utf-8");
+      return content.includes("visor-core") || content.includes("@loworbitstudio/visor-core");
+    } catch {
+      return false;
+    }
+  });
+  if (hasVisorImport) {
+    checks.push({ name: "css-import", pass: true, severity: "warning", message: "visor-core CSS import found" });
+  } else {
+    checks.push({
+      name: "css-import",
+      pass: false,
+      severity: "warning",
+      message: "No visor-core CSS import found in CSS files",
+      fix: 'Add `@import "@loworbitstudio/visor-core/tokens.css"` to your global CSS file'
+    });
+  }
+  const pkgJsonPath = path.join(cwd, "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    const reactVersion = pkg.dependencies?.react ?? pkg.devDependencies?.react ?? "";
+    const versionNum = parseFloat(reactVersion.replace(/[^0-9.]/g, ""));
+    if (!reactVersion) {
+      checks.push({
+        name: "react-version",
+        pass: false,
+        severity: "error",
+        message: "React not found in dependencies",
+        fix: "Install React: `npm install react@latest react-dom@latest`"
+      });
+    } else if (versionNum >= 17 || reactVersion.includes("18") || reactVersion.includes("19")) {
+      checks.push({ name: "react-version", pass: true, severity: "error", message: `React ${reactVersion} satisfies peer dep requirement (>=17)` });
+    } else {
+      checks.push({
+        name: "react-version",
+        pass: false,
+        severity: "error",
+        message: `React version ${reactVersion} may not satisfy peer dep requirement (>=17)`,
+        fix: "Upgrade React to v17 or higher: `npm install react@latest react-dom@latest`"
+      });
+    }
+  } catch {
+    checks.push({
+      name: "react-version",
+      pass: false,
+      severity: "warning",
+      message: "Could not read package.json to check React version",
+      fix: "Ensure package.json exists in the project root"
+    });
+  }
+  const componentsDir = path.join(cwd, "components", "ui");
+  if (fs.existsSync(componentsDir) && fs.readdirSync(componentsDir).length > 0) {
+    const count = fs.readdirSync(componentsDir).length;
+    checks.push({ name: "components", pass: true, severity: "info", message: `${count} component(s) found under components/ui/` });
+  } else {
+    checks.push({
+      name: "components",
+      pass: false,
+      severity: "info",
+      message: "No components found under components/ui/",
+      fix: "Add components with `npx visor add <component-name>` (e.g. `npx visor add button`)"
+    });
+  }
+  const manifestPaths = [
+    path.join(cwd, "public", "r", "index.json"),
+    path.join(cwd, "registry", "index.json")
+  ];
+  const foundManifest = manifestPaths.find((p) => fs.existsSync(p));
+  if (foundManifest) {
+    try {
+      const manifestContent = JSON.parse(fs.readFileSync(foundManifest, "utf-8"));
+      const isEmpty = manifestContent === null || Array.isArray(manifestContent) && manifestContent.length === 0 || typeof manifestContent === "object" && Object.keys(manifestContent).length === 0;
+      if (!isEmpty) {
+        checks.push({ name: "registry-manifest", pass: true, severity: "info", message: `Registry manifest found at ${path.relative(cwd, foundManifest)}` });
+      } else {
+        checks.push({
+          name: "registry-manifest",
+          pass: false,
+          severity: "info",
+          message: "Registry manifest is empty",
+          fix: "Run `npx visor build` to regenerate the registry manifest"
+        });
+      }
+    } catch {
+      checks.push({
+        name: "registry-manifest",
+        pass: false,
+        severity: "info",
+        message: "Registry manifest found but could not be parsed",
+        fix: "Run `npx visor build` to regenerate the registry manifest"
+      });
+    }
+  } else {
+    checks.push({
+      name: "registry-manifest",
+      pass: false,
+      severity: "info",
+      message: "No registry manifest found (this is normal for consumer projects)",
+      fix: "If building a design system, run `npx visor build` to generate the registry manifest"
+    });
+  }
+  if (process.platform !== "win32") {
+    try {
+      const globalPath = execFileSync2("which", ["visor"], { encoding: "utf-8" }).trim();
+      if (globalPath) {
+        const globalVersionRaw = execFileSync2(globalPath, ["--version"], { encoding: "utf-8" }).trim();
+        const globalVersion = globalVersionRaw.split(/\s+/).pop() ?? "";
+        if (isOlder(globalVersion, cliVersion)) {
+          checks.push({
+            name: "stale-global-cli",
+            pass: false,
+            severity: "warning",
+            message: `Global visor ${globalVersion} is older than running CLI ${cliVersion}`,
+            fix: "Run npm uninstall -g @loworbitstudio/visor to remove the stale global"
+          });
+        } else {
+          checks.push({
+            name: "stale-global-cli",
+            pass: true,
+            severity: "warning",
+            message: `Global visor ${globalVersion} matches running CLI`
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const hasErrors = checks.some((c) => !c.pass && c.severity === "error");
+  const hasWarnings = checks.some((c) => !c.pass && c.severity === "warning");
+  const result = {
+    status: hasErrors ? "error" : hasWarnings ? "warning" : "ok",
+    checks
+  };
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(hasErrors ? 1 : 0);
+    return;
+  }
+  console.log("\nVisor Doctor\n============");
+  for (const check of checks) {
+    const icon = check.pass ? "\u2713" : check.severity === "error" ? "\u2717" : "\u26A0";
+    console.log(`${icon} ${check.name}: ${check.message}`);
+    if (!check.pass && check.fix) {
+      console.log(`  Fix: ${check.fix}`);
+    }
+  }
+  console.log(`
+Status: ${result.status.toUpperCase()}`);
+  process.exit(hasErrors ? 1 : 0);
+}
+function isOlder(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb) return true;
+    if (va > vb) return false;
+  }
+  return false;
+}
+function findCssFiles(dir, maxDepth = 3) {
+  const files = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isFile() && (entry.name.endsWith(".css") || entry.name.endsWith(".scss"))) {
+        files.push(fullPath);
+      } else if (entry.isDirectory() && maxDepth > 0) {
+        files.push(...findCssFiles(fullPath, maxDepth - 1));
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+
+// src/utils/patterns.ts
+import { existsSync as existsSync12, readdirSync as readdirSync6, readFileSync as readFileSync15 } from "fs";
+import { join as join13 } from "path";
+import { parse as parseYAML } from "yaml";
+function loadPatternsFromYaml(repoRoot) {
+  const patternsDir = join13(repoRoot, "patterns");
+  if (!existsSync12(patternsDir)) return [];
+  const files = readdirSync6(patternsDir).filter(
+    (f) => f.endsWith(".visor-pattern.yaml")
+  );
+  return files.map((file) => {
+    const content = readFileSync15(join13(patternsDir, file), "utf-8");
+    return parseYAML(content);
+  }).filter(Boolean);
+}
+function findRepoRoot2(startDir) {
+  let current = startDir;
+  while (true) {
+    if (existsSync12(join13(current, "patterns"))) {
+      return current;
+    }
+    const parent = join13(current, "..");
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+// src/commands/pattern.ts
+function patternListCommand(cwd, options = {}) {
+  const json = options.json ?? false;
+  const repoRoot = findRepoRoot2(cwd);
+  if (!repoRoot) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: "Could not find patterns/ directory." }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error("Could not find patterns/ directory.");
+    process.exit(1);
+    return;
+  }
+  const patterns = loadPatternsFromYaml(repoRoot);
+  if (json) {
+    const output = patterns.map((p) => ({
+      name: p.name,
+      description: p.description,
+      components_used: p.components_used,
+      when_to_use: p.when_to_use
+    }));
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          patterns: output,
+          summary: { total: output.length }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  logger.heading(`Composition Patterns (${patterns.length})`);
+  logger.blank();
+  for (const p of patterns) {
+    logger.info(`  ${p.name.padEnd(32)} ${p.description}`);
+  }
+  logger.blank();
+}
+function patternInfoCommand(name, cwd, options = {}) {
+  const json = options.json ?? false;
+  const repoRoot = findRepoRoot2(cwd);
+  if (!repoRoot) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: "Could not find patterns/ directory." }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error("Could not find patterns/ directory.");
+    process.exit(1);
+    return;
+  }
+  const patterns = loadPatternsFromYaml(repoRoot);
+  const pattern2 = patterns.find(
+    (p) => p.name.toLowerCase() === name.toLowerCase() || p.name.toLowerCase().replace(/\s+/g, "-") === name.toLowerCase()
+  );
+  if (!pattern2) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: `Pattern "${name}" not found.` }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error(`Pattern "${name}" not found.`);
+    process.exit(1);
+    return;
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          pattern: {
+            name: pattern2.name,
+            description: pattern2.description,
+            components_used: pattern2.components_used,
+            ...pattern2.related_blocks ? { related_blocks: pattern2.related_blocks } : {},
+            when_to_use: pattern2.when_to_use,
+            structure: pattern2.structure,
+            notes: pattern2.notes
+          }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  logger.heading(pattern2.name);
+  logger.blank();
+  logger.info(`Description: ${pattern2.description}`);
+  logger.blank();
+  logger.info(`Components used: ${pattern2.components_used.join(", ")}`);
+  logger.blank();
+  logger.info("When to use:");
+  for (const item of pattern2.when_to_use) {
+    logger.info(`  - ${item}`);
+  }
+  if (pattern2.related_blocks && pattern2.related_blocks.length > 0) {
+    logger.blank();
+    logger.info(`Related blocks: ${pattern2.related_blocks.join(", ")}`);
+  }
+  logger.blank();
+  logger.info("Structure:");
+  logger.blank();
+  console.log(pattern2.structure);
+  logger.blank();
+  logger.info("Notes:");
+  logger.blank();
+  console.log(pattern2.notes);
+  logger.blank();
+}
+
+// src/commands/suggest.ts
+var STOP_WORDS2 = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "with",
+  "for",
+  "and",
+  "or",
+  "to",
+  "in",
+  "of",
+  "is",
+  "that",
+  "this",
+  "it",
+  "as",
+  "at",
+  "by",
+  "on",
+  "be",
+  "are",
+  "was",
+  "were"
+]);
+function tokenize2(text) {
+  return text.toLowerCase().split(/[\s\-_,]+/).filter((t) => t.length > 1 && !STOP_WORDS2.has(t));
+}
+function scoreEntry(queryTokens, name, description, whenToUse) {
+  const searchText = [name, description, ...whenToUse].join(" ").toLowerCase();
+  const matchedTokens = queryTokens.filter((t) => searchText.includes(t));
+  return {
+    score: matchedTokens.length,
+    matchReason: matchedTokens.length > 0 ? `Matched: ${matchedTokens.join(", ")}` : ""
+  };
+}
+async function suggestCommand(_cwd, options) {
+  const query = options.for;
+  const queryTokens = tokenize2(query);
+  if (queryTokens.length === 0) {
+    const err = {
+      success: false,
+      error: "Query is too short or contains only stop words. Try more specific terms."
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err));
+      process.exit(1);
+    }
+    console.error(err.error);
+    process.exit(1);
+  }
+  const manifest = loadManifest();
+  const results = [];
+  for (const [name, entry] of Object.entries(manifest.components)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "component",
+        category: entry.category,
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name}`
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.blocks)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "block",
+        category: entry.category,
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name} --block`
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.patterns)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "pattern",
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: null
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.hooks)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "hook",
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name}`
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  const topResults = results.slice(0, 10);
+  if (topResults.length === 0) {
+    const err = {
+      success: false,
+      error: `No matches found for "${query}". Try broader terms.`
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err, null, 2));
+      process.exit(1);
+    }
+    console.error(err.error);
+    process.exit(1);
+  }
+  const totalSearched = Object.keys(manifest.components).length + Object.keys(manifest.blocks).length + Object.keys(manifest.patterns).length + Object.keys(manifest.hooks).length;
+  const output = {
+    success: true,
+    query,
+    results: topResults,
+    summary: {
+      total_searched: totalSearched,
+      total_matched: topResults.length
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+  }
+  console.log(`
+Suggestions for "${query}":
+`);
+  for (const r of topResults) {
+    const cmd = r.install_command ? ` (${r.install_command})` : "";
+    console.log(`  ${r.name} [${r.type}]${cmd}`);
+    console.log(`    ${r.description.slice(0, 80)}`);
+  }
+  console.log(
+    `
+${topResults.length} result${topResults.length !== 1 ? "s" : ""} from ${totalSearched} entries
+`
+  );
+}
+
+// src/commands/tokens.ts
+async function tokensListCommand(_cwd, options) {
+  const manifest = loadManifest();
+  if (!manifest.tokens) {
+    const err = {
+      success: false,
+      error: "Tokens section not found in manifest. Run npm run build:manifest to rebuild."
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err));
+    } else {
+      console.error(err.error);
+    }
+    process.exit(1);
+  }
+  const { primitives, semantic, adaptive, summary } = manifest.tokens;
+  let tokens2 = [...primitives, ...semantic, ...adaptive];
+  let categoryLabel = "all";
+  if (options.category) {
+    const cat = options.category.toLowerCase();
+    if (cat === "primitives") {
+      tokens2 = primitives;
+      categoryLabel = "primitives";
+    } else if (cat === "semantic") {
+      tokens2 = semantic;
+      categoryLabel = "semantic";
+    } else if (cat === "adaptive") {
+      tokens2 = adaptive;
+      categoryLabel = "adaptive";
+    } else {
+      const err = {
+        success: false,
+        error: `Unknown category "${options.category}". Use: primitives, semantic, adaptive`
+      };
+      if (options.json) {
+        console.error(JSON.stringify(err));
+      } else {
+        console.error(err.error);
+      }
+      process.exit(1);
+    }
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          tokens: tokens2,
+          summary: {
+            total: tokens2.length,
+            category: categoryLabel,
+            allTotal: summary.total
+          }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(
+    `
+Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
+`
+  );
+  for (const t of tokens2) {
+    console.log(`  ${t.name}  [${t.tier}]`);
+    if (t.description) {
+      console.log(`    ${t.description}`);
+    }
+    console.log(`    Light: ${t.defaultLight}`);
+    console.log(`    Dark:  ${t.defaultDark}`);
+  }
+  console.log(
+    `
+  Total: ${tokens2.length} tokens shown${categoryLabel !== "all" ? ` (${summary.total} total across all tiers)` : ""}`
+  );
+}
+
 // src/index.ts
-var program = new Command();
-program.name("visor").description("CLI for the Visor design system").version("0.1.0");
+var program = new Command2();
+program.name("visor").description("CLI for the Visor design system").version("0.3.0");
+program.addCommand(checkCommand());
 program.command("init").description("Initialize Visor in the current project").option("--template <name>", "scaffold a themed project (nextjs)").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) => {
   listCommand(process.cwd(), options);
 });
-program.command("add").description("Add components, hooks, blocks, or utilities to your project").argument("[items...]", "names of registry items to add").option("--overwrite", "overwrite existing files", false).option("--category <name>", "install all items from a category").option("--block", "install blocks instead of components").option("--json", "output structured JSON (for AI agents)").action((items, options) => {
-  addCommand(items, process.cwd(), { overwrite: options.overwrite, category: options.category, block: options.block, json: options.json });
+program.command("add").description("Add components, hooks, blocks, or utilities to your project").argument("[items...]", "names of registry items to add").option("--overwrite", "overwrite existing files", false).option("--category <name>", "install all items from a category").option("--block", "install blocks instead of components").option("--dry-run", "preview what would be added without writing files").option("--json", "output structured JSON (for AI agents)").action((items, options) => {
+  addCommand(items, process.cwd(), { overwrite: options.overwrite, category: options.category, block: options.block, dryRun: options.dryRun, json: options.json });
 });
 program.command("diff").description(
   "Show differences between local files and the registry"
-).argument("[component]", "component name to diff (all if omitted)").option("--json", "output structured JSON (for AI agents)").action((component, options) => {
+).argument("[component]", "component name to diff (all installed if omitted)").option("--all", "check all registry components for upstream changes").option("--json", "output structured JSON (for AI agents)").action((component, options) => {
   diffCommand(component, process.cwd(), options);
 });
+program.command("info").description("Show detailed metadata for a component, hook, block, or pattern").argument("<component>", "Name of the component to look up").option("--json", "Output as JSON").action(async (component, options) => {
+  await infoCommand(component, process.cwd(), options);
+});
+program.command("doctor").description("Run diagnostics on a Visor installation").option("--json", "Output as JSON (for AI agents)").action(async (options) => {
+  await doctorCommand(process.cwd(), options, program.version() ?? "0.0.0");
+});
 var theme = program.command("theme").description("Theme management commands");
 theme.command("apply").description(
   "Read a .visor.yaml file and generate full CSS token overrides"
@@ -2563,8 +3922,22 @@ theme.command("sync").description(
 );
 var fonts = program.command("fonts").description("Font library management commands");
 fonts.command("add").description("Upload woff2 font files to the Visor Font Library on R2").argument("<path>", "path to a .woff2 file or directory containing .woff2 files").requiredOption("--org <org>", "organization namespace (e.g. low-orbit)").option("--family <name>", "font family slug (auto-inferred from filename if omitted)").option("--json", "output structured JSON (for AI agents)").action(
-  (path, options) => {
-    fontsAddCommand(path, options);
+  (path2, options) => {
+    fontsAddCommand(path2, options);
   }
 );
+var pattern = program.command("pattern").description("Work with composition patterns");
+pattern.command("list").description("List all composition patterns").option("--json", "Output as JSON").action((options) => {
+  patternListCommand(process.cwd(), options);
+});
+pattern.command("info").argument("<name>", "Pattern name").description("Show full details for a composition pattern").option("--json", "Output as JSON").action((name, options) => {
+  patternInfoCommand(name, process.cwd(), options);
+});
+program.command("suggest").description("Suggest components, blocks, and patterns for a use case").requiredOption("--for <useCase>", 'Use case description (e.g. "dropdown with search")').option("--json", "Output as JSON").action(async (options) => {
+  await suggestCommand(process.cwd(), options);
+});
+var tokens = program.command("tokens").description("Explore design tokens");
+tokens.command("list").description("List all design tokens").option("--json", "output as JSON (for AI agents)").option("--category <category>", "filter by tier: primitives, semantic, adaptive").action(async (options) => {
+  await tokensListCommand(process.cwd(), options);
+});
 program.parse();