@decantr/cli 1.0.0-beta.8 → 1.0.0

package/dist/index.js

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
+import {
+  RegistryClient,
+  syncRegistry
+} from "./chunk-PWTUBGGJ.js";
+import {
+  __require
+} from "./chunk-PDX44BCA.js";
 
 // src/index.ts
 import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
@@ -324,6 +331,38 @@ function mergeWithDefaults(flags, detected) {
     existing: flags.existing || detected.existingEssence
   };
 }
+async function runSimplifiedInit(blueprints) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+  console.log("\n? What blueprint would you like to scaffold?\n");
+  console.log("  1. Decantr default (recommended)");
+  console.log("  2. Search registry...\n");
+  const choice = await question("Enter choice (1 or 2): ");
+  if (choice === "1" || choice === "") {
+    rl.close();
+    return { choice: "default" };
+  }
+  const searchQuery = await question("Search: ");
+  const matches = blueprints.filter(
+    (b) => b.id.toLowerCase().includes(searchQuery.toLowerCase()) || b.name?.toLowerCase().includes(searchQuery.toLowerCase()) || b.description?.toLowerCase().includes(searchQuery.toLowerCase())
+  ).slice(0, 10);
+  if (matches.length === 0) {
+    console.log("\nNo matches found. Using Decantr default.");
+    rl.close();
+    return { choice: "default" };
+  }
+  console.log("\nResults:");
+  matches.forEach((b, i) => {
+    console.log(`  ${i + 1}. ${b.id} \u2014 ${b.description || b.name || ""}`);
+  });
+  const selection = await question("\nSelect (number): ");
+  const idx = parseInt(selection, 10) - 1;
+  rl.close();
+  if (idx >= 0 && idx < matches.length) {
+    return { choice: "search", selectedBlueprint: matches[idx].id };
+  }
+  return { choice: "default" };
+}
 
 // src/scaffold.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync, appendFileSync } from "fs";
@@ -331,6 +370,40 @@ import { join as join2, dirname } from "path";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var CLI_VERSION = "1.0.0";
+function serializeLayoutItem(item) {
+  if (typeof item === "string") {
+    return item;
+  }
+  if (typeof item === "object" && item !== null) {
+    const obj = item;
+    if (typeof obj.pattern === "string") {
+      const preset = obj.preset ? ` (${obj.preset})` : "";
+      const alias = obj.as ? ` as ${obj.as}` : "";
+      return `${obj.pattern}${preset}${alias}`;
+    }
+    if (Array.isArray(obj.cols)) {
+      const cols = obj.cols.map(serializeLayoutItem).join(" | ");
+      const breakpoint = obj.at ? ` @${obj.at}` : "";
+      return `[${cols}]${breakpoint}`;
+    }
+  }
+  return "custom";
+}
+function extractPatternNames(item) {
+  if (typeof item === "string") {
+    return [item];
+  }
+  if (typeof item === "object" && item !== null) {
+    const obj = item;
+    if (typeof obj.pattern === "string") {
+      return [obj.pattern];
+    }
+    if (Array.isArray(obj.cols)) {
+      return obj.cols.flatMap(extractPatternNames);
+    }
+  }
+  return [];
+}
 function loadTemplate(name) {
   const fromDist = join2(__dirname, "..", "src", "templates", name);
   if (existsSync2(fromDist)) {
@@ -349,30 +422,56 @@ function renderTemplate(template, vars) {
   }
   return result;
 }
-function buildEssence(options, blueprint) {
+function resolvePatternAlias(item, patterns) {
+  if (!patterns) return item;
+  if (typeof item === "string") {
+    const patternDef = patterns.find((p) => p.as === item);
+    if (patternDef) {
+      if (patternDef.preset) {
+        return { pattern: patternDef.pattern, preset: patternDef.preset };
+      }
+      return patternDef.pattern;
+    }
+    return item;
+  }
+  if (typeof item === "object" && item !== null) {
+    const obj = item;
+    if (Array.isArray(obj.cols)) {
+      return {
+        ...obj,
+        cols: obj.cols.map((col) => resolvePatternAlias(col, patterns))
+      };
+    }
+  }
+  return item;
+}
+function buildEssence(options, archetypeData) {
   let structure = [
-    { id: "home", shell: options.shell, layout: [] }
+    { id: "home", shell: options.shell, layout: ["hero"] }
   ];
   let features = options.features;
-  if (blueprint?.pages) {
-    structure = blueprint.pages.map((p) => ({
-      id: p.id,
-      shell: p.shell || options.shell,
-      layout: p.default_layout || []
-    }));
+  if (archetypeData?.pages) {
+    structure = archetypeData.pages.map((p) => {
+      const resolvedLayout = (p.default_layout?.length ? p.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, p.patterns));
+      return {
+        id: p.id,
+        shell: p.shell || options.shell,
+        layout: resolvedLayout
+      };
+    });
   }
-  if (blueprint?.features) {
-    features = [.../* @__PURE__ */ new Set([...features, ...blueprint.features])];
+  if (archetypeData?.features) {
+    features = [.../* @__PURE__ */ new Set([...features, ...archetypeData.features])];
   }
   const contentGapMap = {
     compact: "_gap2",
     comfortable: "_gap4",
     spacious: "_gap6"
   };
-  return {
+  const archetype = options.archetype || "custom";
+  const essence = {
     version: "2.0.0",
-    archetype: options.archetype,
-    blueprint: options.blueprint,
+    archetype,
     theme: {
       style: options.theme,
       mode: options.mode,
@@ -398,14 +497,105 @@ function buildEssence(options, blueprint) {
     },
     target: options.target
   };
+  if (options.accessibility) {
+    essence.accessibility = options.accessibility;
+  }
+  return essence;
 }
-function generateDecantrMd(essence, detected) {
+function generateAccessibilitySection(essence, themeData) {
+  const accessibility = essence.accessibility;
+  if (!accessibility?.wcag_level || accessibility.wcag_level === "none") {
+    return "";
+  }
+  const wcagLevel = accessibility.wcag_level;
+  const cvdPreference = accessibility.cvd_preference || "none";
+  const cvdSupport = themeData?.cvd_support || [];
+  let section = `---
+
+## Accessibility
+
+**WCAG Level:** ${wcagLevel}
+`;
+  if (cvdSupport.length > 0) {
+    section += `**CVD Support:** Theme supports ${cvdSupport.join(", ")}
+**CVD Preference:** ${cvdPreference}
+`;
+  }
+  section += `
+### What This Means
+
+This project requires WCAG 2.1 Level ${wcagLevel} compliance. You already know these rules \u2014 apply them:
+
+- Semantic HTML structure
+- Sufficient color contrast (4.5:1 for normal text, 3:1 for large text)
+- Keyboard navigability for all interactive elements
+- Visible focus indicators
+- Meaningful alt text for images
+- Proper heading hierarchy
+`;
+  if (cvdSupport.length > 0) {
+    section += `
+### CVD Implementation
+
+The theme provides these data attributes:
+
+\`\`\`html
+<html data-theme="${essence.theme.style}" data-mode="${essence.theme.mode}" data-cvd="none">
+\`\`\`
+
+Valid \`data-cvd\` values for this theme: \`none\`, ${cvdSupport.map((m) => `\`${m}\``).join(", ")}
+`;
+    if (cvdPreference === "auto") {
+      section += `
+Detect user preference via \`prefers-contrast\` or user settings and apply accordingly.
+`;
+    }
+  }
+  section += `
+---
+`;
+  return section;
+}
+function generateSeoSection(essence, archetypeData) {
+  const seoHints = archetypeData?.seo_hints;
+  if (!seoHints) {
+    return "";
+  }
+  const schemaOrg = seoHints.schema_org || [];
+  const metaPriorities = seoHints.meta_priorities || [];
+  if (schemaOrg.length === 0 && metaPriorities.length === 0) {
+    return "";
+  }
+  let section = `---
+
+## SEO Guidance
+
+This archetype (\`${essence.archetype}\`) typically benefits from:
+
+`;
+  if (schemaOrg.length > 0) {
+    section += `- **Schema.org:** ${schemaOrg.join(", ")}
+`;
+  }
+  if (metaPriorities.length > 0) {
+    section += `- **Meta priorities:** ${metaPriorities.join(", ")}
+`;
+  }
+  section += `
+These are suggestions, not requirements. Apply where appropriate for the page content.
+
+---
+`;
+  return section;
+}
+function generateDecantrMd(essence, detected, themeData, recipeData, archetypeData) {
   const template = loadTemplate("DECANTR.md.template");
-  const pagesTable = essence.structure.map(
-    (p) => `| ${p.id} | ${p.shell} | ${p.layout.join(", ") || "none"} |`
-  ).join("\n");
-  const allPatterns = [...new Set(essence.structure.flatMap((p) => p.layout))];
-  const patternsList = allPatterns.length > 0 ? allPatterns.map((p) => `- \`${p}\``).join("\n") : "- No patterns specified yet";
+  const pagesTable = essence.structure.map((p) => {
+    const layoutStr = p.layout.map(serializeLayoutItem).join(", ") || "none";
+    return `| ${p.id} | ${p.shell} | ${layoutStr} |`;
+  }).join("\n");
+  const allPatternNames = [...new Set(essence.structure.flatMap((p) => p.layout.flatMap(extractPatternNames)))];
+  const patternsList = allPatternNames.length > 0 ? allPatternNames.map((p) => `- \`${p}\``).join("\n") : "- No patterns specified yet";
   const projectSummary = [
     `**Archetype:** ${essence.archetype || "custom"}`,
     `**Target:** ${essence.target}`,
@@ -422,6 +612,29 @@ function generateDecantrMd(essence, detected) {
   };
   const defaultShell = essence.structure[0]?.shell || "sidebar-main";
   const shellStructure = shellStructures[defaultShell] || "Custom shell layout";
+  let themeQuickRef = "";
+  if (themeData?.seed) {
+    const colors = Object.entries(themeData.seed).map(([name, hex]) => `- **${name}:** \`${hex}\``).join("\n");
+    themeQuickRef = `**Seed Colors:**
+${colors}`;
+  }
+  if (recipeData?.decorators) {
+    const decorators = Object.entries(recipeData.decorators).slice(0, 5).map(([name, desc]) => `- \`${name}\` \u2014 ${desc}`).join("\n");
+    if (themeQuickRef) {
+      themeQuickRef += `
+
+**Key Decorators:**
+${decorators}`;
+    } else {
+      themeQuickRef = `**Key Decorators:**
+${decorators}`;
+    }
+  }
+  if (!themeQuickRef) {
+    themeQuickRef = `See \`decantr get theme ${essence.theme.style}\` for details.`;
+  }
+  const accessibilitySection = generateAccessibilitySection(essence, themeData);
+  const seoSection = generateSeoSection(essence, archetypeData);
   const vars = {
     GUARD_MODE: essence.guard.mode,
     PROJECT_SUMMARY: projectSummary,
@@ -440,7 +653,10 @@ ${pagesTable}`,
     AVAILABLE_PATTERNS: "(See registry or .decantr/cache/patterns/)",
     AVAILABLE_THEMES: "(See registry or .decantr/cache/themes/)",
     AVAILABLE_SHELLS: "sidebar-main, top-nav-main, centered, full-bleed, minimal-header",
-    VERSION: CLI_VERSION
+    VERSION: CLI_VERSION,
+    THEME_QUICK_REFERENCE: themeQuickRef,
+    ACCESSIBILITY_SECTION: accessibilitySection,
+    SEO_SECTION: seoSection
   };
   return renderTemplate(template, vars);
 }
@@ -489,10 +705,10 @@ function buildFlagsString(options) {
 function generateTaskContext(templateName, essence) {
   const template = loadTemplate(templateName);
   const defaultShell = essence.structure[0]?.shell || "sidebar-main";
-  const layout = essence.structure[0]?.layout.join(", ") || "none";
+  const layout = essence.structure[0]?.layout.map(serializeLayoutItem).join(", ") || "none";
   const scaffoldStructure = essence.structure.map((p) => {
     const patterns = p.layout.length > 0 ? `
-  - Patterns: ${p.layout.join(", ")}` : "";
+  - Patterns: ${p.layout.map(serializeLayoutItem).join(", ")}` : "";
     return `- **${p.id}** (${p.shell})${patterns}`;
   }).join("\n");
   const vars = {
@@ -513,7 +729,7 @@ function generateEssenceSummary(essence) {
   const template = loadTemplate("essence-summary.md.template");
   const pagesTable = `| Page | Shell | Layout |
 |------|-------|--------|
-${essence.structure.map((p) => `| ${p.id} | ${p.shell} | ${p.layout.join(", ") || "none"} |`).join("\n")}`;
+${essence.structure.map((p) => `| ${p.id} | ${p.shell} | ${p.layout.map(serializeLayoutItem).join(", ") || "none"} |`).join("\n")}`;
   const featuresList = essence.features.length > 0 ? essence.features.map((f) => `- ${f}`).join("\n") : "- No features specified";
   const vars = {
     ARCHETYPE: essence.archetype || "custom",
@@ -555,8 +771,8 @@ ${cacheEntry}
     return true;
   }
 }
-function scaffoldProject(projectRoot, options, detected, blueprint, registrySource = "bundled") {
-  const essence = buildEssence(options, blueprint);
+function scaffoldProject(projectRoot, options, detected, archetypeData, registrySource = "bundled", themeData, recipeData) {
+  const essence = buildEssence(options, archetypeData);
   const decantrDir = join2(projectRoot, ".decantr");
   const contextDir = join2(decantrDir, "context");
   const cacheDir = join2(decantrDir, "cache");
@@ -565,7 +781,7 @@ function scaffoldProject(projectRoot, options, detected, blueprint, registrySour
   const essencePath = join2(projectRoot, "decantr.essence.json");
   writeFileSync(essencePath, JSON.stringify(essence, null, 2) + "\n");
   const decantrMdPath = join2(projectRoot, "DECANTR.md");
-  writeFileSync(decantrMdPath, generateDecantrMd(essence, detected));
+  writeFileSync(decantrMdPath, generateDecantrMd(essence, detected, themeData, recipeData, archetypeData));
   const projectJsonPath = join2(decantrDir, "project.json");
   writeFileSync(projectJsonPath, generateProjectJson(detected, options, registrySource));
   const contextFiles = [];
@@ -591,268 +807,225 @@ function scaffoldProject(projectRoot, options, detected, blueprint, registrySour
   };
 }
 
-// src/registry.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, readdirSync } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-var DEFAULT_API_URL = "https://decantr-registry.fly.dev/v1";
-function getBundledContentRoot() {
-  const bundled = join3(__dirname2, "..", "..", "..", "content");
-  if (existsSync3(bundled)) return bundled;
-  const distBundled = join3(__dirname2, "..", "..", "..", "..", "content");
-  if (existsSync3(distBundled)) return distBundled;
-  return bundled;
-}
-async function fetchWithTimeout(url, timeoutMs = 5e3) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetch(url, { signal: controller.signal });
-    return response;
-  } finally {
-    clearTimeout(timeout);
-  }
+// src/theme-commands.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2, readdirSync, rmSync } from "fs";
+import { join as join3 } from "path";
+
+// src/theme-templates.ts
+function getThemeSkeleton(id, name) {
+  return {
+    $schema: "https://decantr.ai/schemas/style-metadata.v1.json",
+    id,
+    name,
+    description: "",
+    tags: [],
+    seed: {
+      primary: "#6366F1",
+      secondary: "#8B5CF6",
+      accent: "#EC4899",
+      background: "#0F172A"
+    },
+    palette: {},
+    modes: ["dark"],
+    shapes: ["rounded"],
+    decantr_compat: ">=1.0.0",
+    source: "custom"
+  };
 }
-async function tryApi(endpoint, apiUrl = DEFAULT_API_URL) {
-  try {
-    const url = `${apiUrl}/${endpoint}`;
-    const response = await fetchWithTimeout(url);
-    if (!response.ok) return null;
-    const data = await response.json();
-    return {
-      data,
-      source: { type: "api", url: apiUrl }
-    };
-  } catch {
-    return null;
+function getHowToThemeDoc() {
+  return `# Custom Themes
+
+Create custom themes for your Decantr project.
+
+## Quick Start
+
+\`\`\`bash
+decantr theme create mytheme
+\`\`\`
+
+## Theme Structure
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| id | Yes | Unique identifier (matches filename) |
+| name | Yes | Display name |
+| description | No | Brief description |
+| tags | No | Searchable tags |
+| seed | Yes | Core colors: primary, secondary, accent, background |
+| palette | No | Extended color palette |
+| modes | Yes | Supported modes: ["light"], ["dark"], or both |
+| shapes | Yes | Supported shapes: sharp, rounded, pill |
+| decantr_compat | Yes | Version compatibility (e.g., ">=1.0.0") |
+| source | Yes | Must be "custom" |
+
+## Using Your Theme
+
+In \`decantr.essence.json\`:
+
+\`\`\`json
+{
+  "theme": {
+    "style": "custom:mytheme",
+    "mode": "dark"
   }
 }
-function loadFromCache(cacheDir, contentType, id) {
-  const cachePath = id ? join3(cacheDir, contentType, `${id}.json`) : join3(cacheDir, contentType, "index.json");
-  if (!existsSync3(cachePath)) return null;
-  try {
-    const data = JSON.parse(readFileSync3(cachePath, "utf-8"));
-    return {
-      data,
-      source: { type: "cache" }
-    };
-  } catch {
-    return null;
-  }
+\`\`\`
+
+## Validation
+
+\`\`\`bash
+decantr theme validate mytheme
+\`\`\`
+
+## Reference
+
+See registry themes for examples:
+
+\`\`\`bash
+decantr get theme auradecantism
+\`\`\`
+`;
 }
-function loadFromBundled(contentType, id) {
-  const contentRoot = getBundledContentRoot();
-  if (id) {
-    const itemPath = join3(contentRoot, contentType, `${id}.json`);
-    if (!existsSync3(itemPath)) return null;
-    try {
-      const data = JSON.parse(readFileSync3(itemPath, "utf-8"));
-      return {
-        data,
-        source: { type: "bundled" }
-      };
-    } catch {
-      return null;
-    }
-  } else {
-    const dir = join3(contentRoot, contentType);
-    if (!existsSync3(dir)) return null;
-    try {
-      const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
-      const items = files.map((f) => {
-        const content = JSON.parse(readFileSync3(join3(dir, f), "utf-8"));
-        return { id: content.id || f.replace(".json", ""), ...content };
-      });
-      return {
-        data: { items, total: items.length },
-        source: { type: "bundled" }
-      };
-    } catch {
-      return null;
+
+// src/theme-commands.ts
+var REQUIRED_FIELDS = ["id", "name", "seed", "modes", "shapes", "decantr_compat", "source"];
+var REQUIRED_SEED = ["primary", "secondary", "accent", "background"];
+var VALID_MODES = ["light", "dark"];
+var VALID_SHAPES = ["sharp", "rounded", "pill"];
+function validateCustomTheme(theme) {
+  const errors = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (!(field in theme)) {
+      errors.push(`Missing required field: ${field}`);
     }
   }
-}
-function saveToCache(cacheDir, contentType, id, data) {
-  const dir = join3(cacheDir, contentType);
-  mkdirSync2(dir, { recursive: true });
-  const cachePath = id ? join3(dir, `${id}.json`) : join3(dir, "index.json");
-  writeFileSync2(cachePath, JSON.stringify(data, null, 2));
-}
-var RegistryClient = class {
-  cacheDir;
-  apiUrl;
-  offline;
-  constructor(options = {}) {
-    this.cacheDir = options.cacheDir || join3(process.cwd(), ".decantr", "cache");
-    this.apiUrl = options.apiUrl || DEFAULT_API_URL;
-    this.offline = options.offline || false;
-  }
-  /**
-   * Fetch archetypes list.
-   */
-  async fetchArchetypes() {
-    if (!this.offline) {
-      const apiResult = await tryApi("archetypes", this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "archetypes", null, apiResult.data);
-        return apiResult;
+  if (theme.seed && typeof theme.seed === "object") {
+    const seed = theme.seed;
+    for (const color of REQUIRED_SEED) {
+      if (!(color in seed)) {
+        errors.push(`Missing seed color: ${color}`);
       }
     }
-    const cacheResult = loadFromCache(
-      this.cacheDir,
-      "archetypes"
-    );
-    if (cacheResult) return cacheResult;
-    const bundledResult = loadFromBundled("archetypes");
-    if (bundledResult) return bundledResult;
-    return {
-      data: { items: [], total: 0 },
-      source: { type: "bundled" }
-    };
   }
-  /**
-   * Fetch a single archetype.
-   */
-  async fetchArchetype(id) {
-    if (!this.offline) {
-      const apiResult = await tryApi(`archetypes/${id}`, this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "archetypes", id, apiResult.data);
-        return apiResult;
+  if (Array.isArray(theme.modes)) {
+    for (const mode of theme.modes) {
+      if (!VALID_MODES.includes(mode)) {
+        errors.push(`Invalid mode "${mode}" - must be "light" or "dark"`);
       }
     }
-    const cacheResult = loadFromCache(this.cacheDir, "archetypes", id);
-    if (cacheResult) return cacheResult;
-    return loadFromBundled("archetypes", id);
-  }
-  /**
-   * Fetch blueprints list.
-   */
-  async fetchBlueprints() {
-    if (!this.offline) {
-      const apiResult = await tryApi("blueprints", this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "blueprints", null, apiResult.data);
-        return apiResult;
+  }
+  if (Array.isArray(theme.shapes)) {
+    for (const shape of theme.shapes) {
+      if (!VALID_SHAPES.includes(shape)) {
+        errors.push(`Invalid shape "${shape}" - use: sharp, rounded, pill`);
       }
     }
-    const cacheResult = loadFromCache(
-      this.cacheDir,
-      "blueprints"
-    );
-    if (cacheResult) return cacheResult;
-    const bundledResult = loadFromBundled("blueprints");
-    if (bundledResult) return bundledResult;
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function createTheme(projectRoot, id, name) {
+  const customThemesDir = join3(projectRoot, ".decantr", "custom", "themes");
+  const themePath = join3(customThemesDir, `${id}.json`);
+  const howToPath = join3(customThemesDir, "how-to-theme.md");
+  mkdirSync2(customThemesDir, { recursive: true });
+  if (existsSync3(themePath)) {
     return {
-      data: { items: [], total: 0 },
-      source: { type: "bundled" }
+      success: false,
+      error: `Theme "${id}" already exists at ${themePath}`
     };
   }
-  /**
-   * Fetch a single blueprint.
-   */
-  async fetchBlueprint(id) {
-    if (!this.offline) {
-      const apiResult = await tryApi(`blueprints/${id}`, this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "blueprints", id, apiResult.data);
-        return apiResult;
-      }
-    }
-    const cacheResult = loadFromCache(this.cacheDir, "blueprints", id);
-    if (cacheResult) return cacheResult;
-    return loadFromBundled("blueprints", id);
-  }
-  /**
-   * Fetch themes list.
-   */
-  async fetchThemes() {
-    if (!this.offline) {
-      const apiResult = await tryApi("themes", this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "themes", null, apiResult.data);
-        return apiResult;
+  const skeleton = getThemeSkeleton(id, name);
+  writeFileSync2(themePath, JSON.stringify(skeleton, null, 2));
+  if (!existsSync3(howToPath)) {
+    writeFileSync2(howToPath, getHowToThemeDoc());
+  }
+  return {
+    success: true,
+    path: themePath
+  };
+}
+function listCustomThemes(projectRoot) {
+  const customThemesDir = join3(projectRoot, ".decantr", "custom", "themes");
+  if (!existsSync3(customThemesDir)) {
+    return [];
+  }
+  const themes = [];
+  try {
+    const files = readdirSync(customThemesDir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      const filePath = join3(customThemesDir, file);
+      try {
+        const data = JSON.parse(readFileSync3(filePath, "utf-8"));
+        themes.push({
+          id: data.id || file.replace(".json", ""),
+          name: data.name || data.id,
+          description: data.description,
+          path: filePath
+        });
+      } catch {
       }
     }
-    const cacheResult = loadFromCache(
-      this.cacheDir,
-      "themes"
-    );
-    if (cacheResult) return cacheResult;
-    const bundledResult = loadFromBundled("themes");
-    if (bundledResult) return bundledResult;
+  } catch {
+  }
+  return themes;
+}
+function deleteTheme(projectRoot, id) {
+  const themePath = join3(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
+  if (!existsSync3(themePath)) {
     return {
-      data: { items: [], total: 0 },
-      source: { type: "bundled" }
+      success: false,
+      error: `Theme "${id}" not found at ${themePath}`
     };
   }
-  /**
-   * Fetch patterns list.
-   */
-  async fetchPatterns() {
-    if (!this.offline) {
-      const apiResult = await tryApi("patterns", this.apiUrl);
-      if (apiResult) {
-        saveToCache(this.cacheDir, "patterns", null, apiResult.data);
-        return apiResult;
-      }
-    }
-    const cacheResult = loadFromCache(
-      this.cacheDir,
-      "patterns"
-    );
-    if (cacheResult) return cacheResult;
-    const bundledResult = loadFromBundled("patterns");
-    if (bundledResult) return bundledResult;
+  try {
+    rmSync(themePath);
+    return { success: true };
+  } catch (e) {
     return {
-      data: { items: [], total: 0 },
-      source: { type: "bundled" }
+      success: false,
+      error: `Failed to delete: ${e.message}`
     };
   }
-  /**
-   * Check if API is available.
-   */
-  async checkApiAvailability() {
-    if (this.offline) return false;
-    try {
-      const response = await fetchWithTimeout(`${this.apiUrl.replace("/v1", "")}/health`, 3e3);
-      return response.ok;
-    } catch {
-      return false;
-    }
+}
+function importTheme(projectRoot, sourcePath) {
+  if (!existsSync3(sourcePath)) {
+    return {
+      success: false,
+      errors: [`Source file not found: ${sourcePath}`]
+    };
   }
-  /**
-   * Get the source used for the last fetch.
-   */
-  getSourceType() {
-    return this.offline ? "bundled" : "api";
-  }
-};
-async function syncRegistry(cacheDir, apiUrl = DEFAULT_API_URL) {
-  const client = new RegistryClient({ cacheDir, apiUrl, offline: false });
-  const synced = [];
-  const failed = [];
-  const apiAvailable = await client.checkApiAvailability();
-  if (!apiAvailable) {
-    return { synced: [], failed: ["API unavailable"], source: "bundled" };
-  }
-  const types = ["archetypes", "blueprints", "themes", "patterns"];
-  for (const type of types) {
-    try {
-      const fetchMethod = `fetch${type.charAt(0).toUpperCase()}${type.slice(1)}`;
-      const result = await client[fetchMethod]();
-      if (result.source.type === "api") {
-        synced.push(type);
-      }
-    } catch {
-      failed.push(type);
-    }
+  let theme;
+  try {
+    theme = JSON.parse(readFileSync3(sourcePath, "utf-8"));
+  } catch (e) {
+    return {
+      success: false,
+      errors: [`Invalid JSON: ${e.message}`]
+    };
+  }
+  const validation = validateCustomTheme(theme);
+  if (!validation.valid) {
+    return {
+      success: false,
+      errors: validation.errors
+    };
+  }
+  theme.source = "custom";
+  const id = theme.id;
+  const customThemesDir = join3(projectRoot, ".decantr", "custom", "themes");
+  const destPath = join3(customThemesDir, `${id}.json`);
+  mkdirSync2(customThemesDir, { recursive: true });
+  const howToPath = join3(customThemesDir, "how-to-theme.md");
+  if (!existsSync3(howToPath)) {
+    writeFileSync2(howToPath, getHowToThemeDoc());
   }
+  writeFileSync2(destPath, JSON.stringify(theme, null, 2));
   return {
-    synced,
-    failed,
-    source: synced.length > 0 ? "api" : "bundled"
+    success: true,
+    path: destPath
   };
 }
 
@@ -881,6 +1054,61 @@ function dim(text) {
 function cyan(text) {
   return `${CYAN2}${text}${RESET2}`;
 }
+function extractPatternName(item) {
+  if (typeof item === "string") return item;
+  if (typeof item === "object" && item !== null) {
+    const obj = item;
+    if (typeof obj.pattern === "string") return obj.pattern;
+    if (Array.isArray(obj.cols)) {
+      return obj.cols.map(extractPatternName).join(" | ");
+    }
+  }
+  return "custom";
+}
+function generateCuratedPrompt(ctx) {
+  const lines = [];
+  lines.push(`I'm building a ${ctx.archetype} application using ${ctx.target}.`);
+  lines.push("");
+  if (ctx.blueprint) {
+    lines.push(`Blueprint: ${ctx.blueprint}`);
+  }
+  lines.push(`Theme: ${ctx.theme} (${ctx.mode} mode)`);
+  lines.push(`Personality: ${ctx.personality.join(", ")}`);
+  lines.push(`Guard mode: ${ctx.guard}`);
+  lines.push("");
+  lines.push("Pages to build:");
+  for (const page of ctx.pages) {
+    const patternNames = page.layout.map(extractPatternName);
+    const patterns = patternNames.length > 0 ? patternNames.join(", ") : "custom";
+    lines.push(`  - ${page.id}: ${page.shell} shell with ${patterns}`);
+  }
+  if (ctx.features.length > 0) {
+    lines.push("");
+    lines.push(`Features: ${ctx.features.join(", ")}`);
+  }
+  lines.push("");
+  lines.push("Please read DECANTR.md for the full design spec and methodology.");
+  lines.push("Follow the guard rules and use the patterns from decantr.essence.json.");
+  return lines.join("\n");
+}
+function boxedPrompt(content, title) {
+  const lines = content.split("\n");
+  const maxLen = Math.max(...lines.map((l) => l.length), title.length + 4);
+  const width = maxLen + 4;
+  const top = `\u250C${"\u2500".repeat(width - 2)}\u2510`;
+  const titleLine = `\u2502 ${BOLD2}${title}${RESET2}${" ".repeat(width - title.length - 4)} \u2502`;
+  const sep = `\u251C${"\u2500".repeat(width - 2)}\u2524`;
+  const bottom = `\u2514${"\u2500".repeat(width - 2)}\u2518`;
+  const body = lines.map((line) => {
+    const padding = " ".repeat(width - line.length - 4);
+    return `\u2502 ${line}${padding} \u2502`;
+  }).join("\n");
+  return `${top}
+${titleLine}
+${sep}
+${body}
+${bottom}`;
+}
 function getContentRoot() {
   const bundled = join4(import.meta.dirname, "..", "..", "..", "content");
   return process.env.DECANTR_CONTENT_ROOT || bundled;
@@ -902,13 +1130,58 @@ async function cmdSearch(query, type) {
     console.log("");
   }
 }
+async function cmdSuggest(query, type) {
+  const client = createRegistryClient();
+  const searchType = type || "pattern";
+  const results = await client.search(query, searchType);
+  if (results.length === 0) {
+    console.log(dim(`No suggestions for "${query}"`));
+    console.log("");
+    console.log("Try:");
+    console.log(`  ${cyan("decantr list patterns")} - see all patterns`);
+    console.log(`  ${cyan("decantr search <broader-term>")} - broaden your search`);
+    return;
+  }
+  console.log(heading(`Suggestions for "${query}"`));
+  const queryLower = query.toLowerCase();
+  const exact = results.filter((r) => r.id.toLowerCase().includes(queryLower));
+  const related = results.filter((r) => !r.id.toLowerCase().includes(queryLower));
+  if (exact.length > 0) {
+    console.log(`${BOLD2}Direct matches:${RESET2}`);
+    for (const r of exact.slice(0, 3)) {
+      console.log(`  ${cyan(r.id)} - ${r.description || ""}`);
+    }
+    console.log("");
+  }
+  if (related.length > 0) {
+    console.log(`${BOLD2}Related:${RESET2}`);
+    for (const r of related.slice(0, 5)) {
+      console.log(`  ${cyan(r.id)} - ${r.description || ""}`);
+    }
+    console.log("");
+  }
+  console.log(dim(`Use "decantr get pattern <id>" for full details`));
+}
 async function cmdGet(type, id) {
-  const validTypes = ["pattern", "archetype", "recipe", "theme", "blueprint"];
+  const validTypes = ["pattern", "archetype", "recipe", "theme", "blueprint", "shell"];
   if (!validTypes.includes(type)) {
     console.error(error(`Invalid type "${type}". Must be one of: ${validTypes.join(", ")}`));
     process.exitCode = 1;
     return;
   }
+  if (type === "shell") {
+    const registryClient = new RegistryClient({
+      cacheDir: join4(process.cwd(), ".decantr", "cache")
+    });
+    const shellResult = await registryClient.fetchShell(id);
+    if (shellResult) {
+      console.log(JSON.stringify(shellResult.data, null, 2));
+      return;
+    }
+    console.error(error(`shell "${id}" not found.`));
+    process.exitCode = 1;
+    return;
+  }
   const resolver = getResolver();
   let result = await resolver.resolve(type, id);
   if (!result) {
@@ -930,6 +1203,53 @@ async function cmdGet(type, id) {
   }
   console.log(JSON.stringify(result.item, null, 2));
 }
+function buildRegistryContext() {
+  const { readdirSync: readdirSync2 } = __require("fs");
+  const themeRegistry = /* @__PURE__ */ new Map();
+  const patternRegistry = /* @__PURE__ */ new Map();
+  const contentRoot = getContentRoot();
+  const themeDirs = [join4(contentRoot, "themes"), join4(contentRoot, "core", "themes")];
+  for (const dir of themeDirs) {
+    try {
+      if (existsSync4(dir)) {
+        for (const f of readdirSync2(dir).filter((f2) => f2.endsWith(".json"))) {
+          const data = JSON.parse(readFileSync4(join4(dir, f), "utf-8"));
+          if (data.id && !themeRegistry.has(data.id)) {
+            themeRegistry.set(data.id, { modes: data.modes || ["light", "dark"] });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const customThemesDir = join4(process.cwd(), ".decantr", "custom", "themes");
+  try {
+    if (existsSync4(customThemesDir)) {
+      for (const f of readdirSync2(customThemesDir).filter((f2) => f2.endsWith(".json"))) {
+        const data = JSON.parse(readFileSync4(join4(customThemesDir, f), "utf-8"));
+        if (data.id) {
+          themeRegistry.set(`custom:${data.id}`, { modes: data.modes || ["light", "dark"] });
+        }
+      }
+    }
+  } catch {
+  }
+  const patternDirs = [join4(contentRoot, "patterns"), join4(contentRoot, "core", "patterns")];
+  for (const dir of patternDirs) {
+    try {
+      if (existsSync4(dir)) {
+        for (const f of readdirSync2(dir).filter((f2) => f2.endsWith(".json"))) {
+          const data = JSON.parse(readFileSync4(join4(dir, f), "utf-8"));
+          if (data.id && !patternRegistry.has(data.id)) {
+            patternRegistry.set(data.id, data);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return { themeRegistry, patternRegistry };
+}
 async function cmdValidate(path) {
   const essencePath = path || join4(process.cwd(), "decantr.essence.json");
   let raw;
@@ -959,12 +1279,16 @@ async function cmdValidate(path) {
     process.exitCode = 1;
   }
   try {
-    const violations = evaluateGuard(essence, {});
+    const { themeRegistry, patternRegistry } = buildRegistryContext();
+    const violations = evaluateGuard(essence, { themeRegistry, patternRegistry });
     if (violations.length > 0) {
       console.log(heading("Guard violations:"));
       for (const v of violations) {
         const vr = v;
         console.log(`  ${YELLOW2}[${vr.rule}]${RESET2} ${vr.message}`);
+        if (vr.suggestion) {
+          console.log(`    ${DIM2}Suggestion: ${vr.suggestion}${RESET2}`);
+        }
       }
     } else if (result.valid) {
       console.log(success("No guard violations."));
@@ -973,42 +1297,116 @@ async function cmdValidate(path) {
   }
 }
 async function cmdList(type) {
-  const validTypes = ["patterns", "archetypes", "recipes", "themes", "blueprints"];
+  const validTypes = ["patterns", "archetypes", "recipes", "themes", "blueprints", "shells"];
   if (!validTypes.includes(type)) {
     console.error(error(`Invalid type "${type}". Must be one of: ${validTypes.join(", ")}`));
     process.exitCode = 1;
     return;
   }
-  const { readdirSync: readdirSync2 } = await import("fs");
-  const dir = join4(getContentRoot(), type);
-  let found = false;
+  if (type === "shells") {
+    const registryClient = new RegistryClient({
+      cacheDir: join4(process.cwd(), ".decantr", "cache")
+    });
+    const shellsResult = await registryClient.fetchShells();
+    for (const item of shellsResult.data.items) {
+      console.log(`  ${item.id}${item.description ? ` \u2014 ${item.description}` : ""}`);
+    }
+    console.log(`
+${shellsResult.data.total} shells found`);
+    return;
+  }
+  const { readdirSync: readdirSync2, existsSync: existsSync5 } = await import("fs");
+  const contentRoot = getContentRoot();
+  const mainDir = join4(contentRoot, type);
+  const coreDir = join4(contentRoot, "core", type);
+  const items = [];
+  try {
+    if (existsSync5(mainDir)) {
+      const files = readdirSync2(mainDir).filter((f) => f.endsWith(".json"));
+      for (const f of files) {
+        const data = JSON.parse(readFileSync4(join4(mainDir, f), "utf-8"));
+        items.push({ id: data.id || f.replace(".json", ""), description: data.description, name: data.name });
+      }
+    }
+  } catch {
+  }
   try {
-    const files = readdirSync2(dir).filter((f) => f.endsWith(".json"));
-    if (files.length > 0) {
-      found = true;
-      console.log(heading(`${files.length} ${type}`));
+    if (existsSync5(coreDir)) {
+      const files = readdirSync2(coreDir).filter((f) => f.endsWith(".json"));
+      const existingIds = new Set(items.map((i) => i.id));
       for (const f of files) {
-        const data = JSON.parse(readFileSync4(join4(dir, f), "utf-8"));
-        console.log(`  ${cyan(data.id || f.replace(".json", ""))}  ${dim(data.description || data.name || "")}`);
+        const data = JSON.parse(readFileSync4(join4(coreDir, f), "utf-8"));
+        const itemId = data.id || f.replace(".json", "");
+        if (!existingIds.has(itemId)) {
+          items.push({ id: itemId, description: data.description, name: data.name });
+        }
       }
     }
   } catch {
   }
-  if (!found) {
+  const customItems = [];
+  if (type === "themes") {
     try {
-      const res = await fetch(`https://decantr-registry.fly.dev/v1/${type}`);
-      if (res.ok) {
-        const data = await res.json();
+      const custom = listCustomThemes(process.cwd());
+      for (const theme of custom) {
+        customItems.push({
+          id: `custom:${theme.id}`,
+          description: theme.description,
+          name: theme.name,
+          source: "custom"
+        });
+      }
+    } catch {
+    }
+  }
+  if (items.length > 0 || customItems.length > 0) {
+    if (type === "themes") {
+      console.log(heading(`Registry themes (${items.length}):`));
+      for (const item of items) {
+        console.log(`  ${cyan(item.id)}  ${dim(item.description || item.name || "")}`);
+      }
+      if (customItems.length > 0) {
+        console.log("");
+        console.log(heading(`Custom themes (${customItems.length}):`));
+        for (const item of customItems) {
+          console.log(`  ${cyan(item.id)}  ${dim(item.description || item.name || "")}`);
+        }
+      } else {
+        console.log("");
+        console.log(dim("Custom themes (0):"));
+        console.log(dim('  Run "decantr theme create <name>" to create a custom theme.'));
+      }
+    } else {
+      console.log(heading(`${items.length} ${type}`));
+      for (const item of items) {
+        console.log(`  ${cyan(item.id)}  ${dim(item.description || item.name || "")}`);
+      }
+    }
+    return;
+  }
+  try {
+    const res = await fetch(`https://decantr-registry.fly.dev/v1/${type}`);
+    if (res.ok) {
+      const data = await res.json();
+      if (type === "themes") {
+        console.log(heading(`Registry themes (${data.total}):`));
+        for (const item of data.items) {
+          console.log(`  ${cyan(item.id)}  ${dim(item.description || item.name || "")}`);
+        }
+        console.log("");
+        console.log(dim("Custom themes (0):"));
+        console.log(dim('  Run "decantr theme create <name>" to create a custom theme.'));
+      } else {
         console.log(heading(`${data.total} ${type}`));
         for (const item of data.items) {
           console.log(`  ${cyan(item.id)}  ${dim(item.description || item.name || "")}`);
         }
-        return;
       }
-    } catch {
+      return;
     }
-    console.log(dim(`No ${type} found.`));
+  } catch {
   }
+  console.log(dim(`No ${type} found.`));
 }
 async function cmdInit(args) {
   const projectRoot = process.cwd();
@@ -1027,31 +1425,73 @@ async function cmdInit(args) {
     apiUrl: args.registry,
     offline: args.offline
   });
-  console.log(dim("Fetching registry content..."));
+  const apiAvailable = await registryClient.checkApiAvailability();
+  let selectedBlueprint = "default";
+  let registrySource = "bundled";
+  if (args.yes) {
+    selectedBlueprint = args.blueprint || "default";
+  } else if (!apiAvailable) {
+    console.log(`
+${YELLOW2}You're offline. Scaffolding Decantr default.${RESET2}`);
+    console.log(dim("Run `decantr upgrade` when online, or visit decantr.ai/registry\n"));
+    selectedBlueprint = "default";
+  } else {
+    console.log(dim("Fetching registry content..."));
+    const blueprintsResult2 = await registryClient.fetchBlueprints();
+    registrySource = blueprintsResult2.source.type === "api" ? "api" : "bundled";
+    const { selectedBlueprint: selected } = await runSimplifiedInit(
+      blueprintsResult2.data.items
+    );
+    selectedBlueprint = selected || "default";
+  }
   const [archetypesResult, blueprintsResult, themesResult] = await Promise.all([
     registryClient.fetchArchetypes(),
     registryClient.fetchBlueprints(),
     registryClient.fetchThemes()
   ]);
-  const registrySource = archetypesResult.source.type;
-  if (registrySource === "bundled") {
-    console.log(dim("Using bundled content (API unavailable)"));
+  if (archetypesResult.source.type === "api") {
+    registrySource = "api";
   }
   const archetypes = archetypesResult.data.items;
   const blueprints = blueprintsResult.data.items;
   const themes = themesResult.data.items;
   let options;
-  if (args.yes) {
+  if (args.yes || selectedBlueprint !== "default") {
     const flags = parseFlags(args, detected);
+    flags.blueprint = selectedBlueprint !== "default" ? selectedBlueprint : flags.blueprint;
     options = mergeWithDefaults(flags, detected);
   } else {
     options = await runInteractivePrompts(detected, archetypes, blueprints, themes);
   }
-  let blueprintData;
+  let archetypeData;
   if (options.blueprint) {
-    const result2 = await registryClient.fetchBlueprint(options.blueprint);
-    if (result2) {
-      blueprintData = result2.data;
+    const blueprintResult = await registryClient.fetchBlueprint(options.blueprint);
+    if (blueprintResult) {
+      const blueprint = blueprintResult.data;
+      const primaryArchetype = blueprint.compose?.[0];
+      if (primaryArchetype) {
+        const archetypeResult = await registryClient.fetchArchetype(primaryArchetype);
+        if (archetypeResult) {
+          archetypeData = archetypeResult.data;
+          options.archetype = primaryArchetype;
+        }
+      }
+    }
+  } else if (options.archetype) {
+    const archetypeResult = await registryClient.fetchArchetype(options.archetype);
+    if (archetypeResult) {
+      archetypeData = archetypeResult.data;
+    }
+  }
+  let themeData;
+  let recipeData;
+  if (options.theme) {
+    const themeResult = await registryClient.fetchTheme(options.theme);
+    if (themeResult) {
+      const theme = themeResult.data;
+      if (theme.seed) {
+        themeData = { seed: theme.seed };
+      }
     }
   }
   console.log(heading("Scaffolding project..."));
@@ -1059,31 +1499,52 @@ async function cmdInit(args) {
     projectRoot,
     options,
     detected,
-    blueprintData,
-    registrySource
+    archetypeData,
+    registrySource,
+    themeData,
+    recipeData
   );
-  console.log(success("\nProject scaffolded successfully!"));
-  console.log("");
-  console.log(`  ${cyan("decantr.essence.json")}  Design specification`);
-  console.log(`  ${cyan("DECANTR.md")}            LLM instructions`);
-  console.log(`  ${cyan(".decantr/project.json")} Project state`);
-  console.log(`  ${cyan(".decantr/context/")}     Task-specific guides`);
+  console.log(success("\nProject scaffolded!\n"));
+  console.log("  Files created:");
+  console.log(`    ${cyan("decantr.essence.json")}    Design specification`);
+  console.log(`    ${cyan("DECANTR.md")}              LLM instructions`);
+  console.log(`    ${cyan(".decantr/")}               Project state & cache`);
   if (result.gitignoreUpdated) {
-    console.log(`  ${dim(".gitignore updated to exclude .decantr/cache/")}`);
+    console.log(`    ${dim(".gitignore updated")}`);
   }
+  console.log("");
+  console.log("  Next steps:");
+  console.log("    1. Review DECANTR.md for methodology");
+  console.log("    2. Explore more at decantr.ai/registry");
+  console.log("");
+  console.log("  Commands:");
+  console.log(`    ${cyan("decantr status")}     Project health`);
+  console.log(`    ${cyan("decantr search")}     Search registry`);
+  console.log(`    ${cyan("decantr get")}        Fetch content details`);
+  console.log(`    ${cyan("decantr validate")}   Check essence file`);
+  console.log(`    ${cyan("decantr upgrade")}    Update to latest patterns`);
+  console.log(`    ${cyan("decantr heal")}       Fix drift issues`);
   const essenceContent = readFileSync4(result.essencePath, "utf-8");
   const essence = JSON.parse(essenceContent);
   const validation = validateEssence(essence);
-  if (validation.valid) {
-    console.log(success("\nValidation passed."));
-  } else {
+  if (!validation.valid) {
     console.log(error(`
 Validation warnings: ${validation.errors.join(", ")}`));
   }
-  console.log(heading("Next steps"));
-  console.log("1. Review DECANTR.md to understand the methodology");
-  console.log("2. Share DECANTR.md with your AI assistant");
-  console.log("3. Start building! The AI will follow the essence spec.");
+  console.log("");
+  const promptCtx = {
+    archetype: options.archetype || "custom",
+    blueprint: options.blueprint,
+    theme: options.theme,
+    mode: options.mode,
+    target: options.target,
+    pages: essence.structure || [{ id: "home", shell: options.shell, layout: ["hero"] }],
+    personality: options.personality,
+    features: options.features,
+    guard: options.guard
+  };
+  const curatedPrompt = generateCuratedPrompt(promptCtx);
+  console.log(boxedPrompt(curatedPrompt, "Copy this prompt for your AI assistant"));
   console.log("");
   if (registrySource === "bundled") {
     console.log(dim('Run "decantr sync" when online to get the latest registry content.'));
@@ -1173,13 +1634,17 @@ async function cmdAudit() {
       return;
     }
     console.log(success("Essence is valid."));
-    const violations = evaluateGuard(essence, {});
+    const { themeRegistry, patternRegistry } = buildRegistryContext();
+    const violations = evaluateGuard(essence, { themeRegistry, patternRegistry });
     if (violations.length > 0) {
       console.log("");
       console.log(`${YELLOW2}Guard violations:${RESET2}`);
       for (const v of violations) {
         const vr = v;
         console.log(`  ${YELLOW2}[${vr.rule}]${RESET2} ${vr.message}`);
+        if (vr.suggestion) {
+          console.log(`    ${DIM2}Suggestion: ${vr.suggestion}${RESET2}`);
+        }
       }
     } else {
       console.log(success("No guard violations."));
@@ -1194,6 +1659,135 @@ async function cmdAudit() {
     process.exitCode = 1;
   }
 }
+async function cmdTheme(args) {
+  const subcommand = args[0];
+  const projectRoot = process.cwd();
+  if (!subcommand || subcommand === "help") {
+    console.log(`
+${BOLD2}decantr theme${RESET2} \u2014 Manage custom themes
+
+${BOLD2}Commands:${RESET2}
+  ${cyan("create")} <name>        Create a new custom theme
+  ${cyan("create")} <name> --guided   Interactive theme creation
+  ${cyan("list")}                 List custom themes
+  ${cyan("validate")} <name>      Validate a custom theme
+  ${cyan("delete")} <name>        Delete a custom theme
+  ${cyan("import")} <path>        Import theme from JSON file
+
+${BOLD2}Examples:${RESET2}
+  decantr theme create mytheme
+  decantr theme list
+  decantr theme validate mytheme
+  decantr theme import ./external-theme.json
+`);
+    return;
+  }
+  switch (subcommand) {
+    case "create": {
+      const name = args[1];
+      if (!name) {
+        console.error(error("Usage: decantr theme create <name>"));
+        process.exitCode = 1;
+        return;
+      }
+      const displayName = name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, " ");
+      const result = createTheme(projectRoot, name, displayName);
+      if (result.success) {
+        console.log(success(`Created custom theme "${name}"`));
+        console.log(dim(`  Path: ${result.path}`));
+        console.log("");
+        console.log(`Use in essence: ${cyan(`"style": "custom:${name}"`)}`);
+      } else {
+        console.error(error(result.error || "Failed to create theme"));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "list": {
+      const themes = listCustomThemes(projectRoot);
+      if (themes.length === 0) {
+        console.log(dim("No custom themes found."));
+        console.log(dim('Run "decantr theme create <name>" to create one.'));
+      } else {
+        console.log(heading(`${themes.length} custom theme(s)`));
+        for (const theme of themes) {
+          console.log(`  ${cyan(`custom:${theme.id}`)}  ${dim(theme.description || theme.name)}`);
+        }
+      }
+      break;
+    }
+    case "validate": {
+      const name = args[1];
+      if (!name) {
+        console.error(error("Usage: decantr theme validate <name>"));
+        process.exitCode = 1;
+        return;
+      }
+      const themePath = join4(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
+      if (!existsSync4(themePath)) {
+        console.error(error(`Theme "${name}" not found at ${themePath}`));
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const theme = JSON.parse(readFileSync4(themePath, "utf-8"));
+        const result = validateCustomTheme(theme);
+        if (result.valid) {
+          console.log(success(`Custom theme "${name}" is valid`));
+        } else {
+          console.error(error("Validation failed:"));
+          for (const err of result.errors) {
+            console.error(`  ${RED}${err}${RESET2}`);
+          }
+          process.exitCode = 1;
+        }
+      } catch (e) {
+        console.error(error(`Invalid JSON: ${e.message}`));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "delete": {
+      const name = args[1];
+      if (!name) {
+        console.error(error("Usage: decantr theme delete <name>"));
+        process.exitCode = 1;
+        return;
+      }
+      const result = deleteTheme(projectRoot, name);
+      if (result.success) {
+        console.log(success(`Deleted custom theme "${name}"`));
+      } else {
+        console.error(error(result.error || "Failed to delete theme"));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "import": {
+      const sourcePath = args[1];
+      if (!sourcePath) {
+        console.error(error("Usage: decantr theme import <path>"));
+        process.exitCode = 1;
+        return;
+      }
+      const result = importTheme(projectRoot, sourcePath);
+      if (result.success) {
+        console.log(success("Theme imported successfully"));
+        console.log(dim(`  Path: ${result.path}`));
+      } else {
+        console.error(error("Import failed:"));
+        for (const err of result.errors || []) {
+          console.error(`  ${RED}${err}${RESET2}`);
+        }
+        process.exitCode = 1;
+      }
+      break;
+    }
+    default:
+      console.error(error(`Unknown theme command: ${subcommand}`));
+      process.exitCode = 1;
+  }
+}
 function cmdHelp() {
   console.log(`
 ${BOLD2}decantr${RESET2} \u2014 Design intelligence for AI-generated UI
@@ -1204,9 +1798,11 @@ ${BOLD2}Usage:${RESET2}
   decantr sync
   decantr audit
   decantr search <query> [--type <type>]
+  decantr suggest <query> [--type <type>]
   decantr get <type> <id>
   decantr list <type>
   decantr validate [path]
+  decantr theme <subcommand>
   decantr help
 
 ${BOLD2}Init Options:${RESET2}
@@ -1229,9 +1825,11 @@ ${BOLD2}Commands:${RESET2}
   ${cyan("sync")}      Sync registry content from API
   ${cyan("audit")}     Validate essence and check for drift
   ${cyan("search")}    Search the registry
+  ${cyan("suggest")}   Suggest patterns or alternatives for a query
   ${cyan("get")}       Get full details of a registry item
   ${cyan("list")}      List items by type
   ${cyan("validate")}  Validate essence file
+  ${cyan("theme")}     Manage custom themes (create, list, validate, delete, import)
   ${cyan("help")}      Show this help
 
 ${BOLD2}Examples:${RESET2}
@@ -1241,6 +1839,8 @@ ${BOLD2}Examples:${RESET2}
   decantr sync
   decantr audit
   decantr search dashboard
+  decantr suggest leaderboard
+  decantr suggest ranking --type pattern
   decantr list patterns
 `);
 }
@@ -1286,6 +1886,16 @@ async function main() {
       await cmdSync();
       break;
     }
+    case "upgrade": {
+      const { cmdUpgrade } = await import("./upgrade-FWICWIQW.js");
+      await cmdUpgrade(process.cwd());
+      break;
+    }
+    case "heal": {
+      const { cmdHeal } = await import("./heal-2OPN63OT.js");
+      await cmdHeal(process.cwd());
+      break;
+    }
     case "audit": {
       await cmdAudit();
       break;
@@ -1302,6 +1912,18 @@ async function main() {
       await cmdSearch(query, type);
       break;
     }
+    case "suggest": {
+      const query = args[1];
+      if (!query) {
+        console.error(error("Usage: decantr suggest <query> [--type <type>]"));
+        process.exitCode = 1;
+        return;
+      }
+      const typeIdx = args.indexOf("--type");
+      const type = typeIdx !== -1 ? args[typeIdx + 1] : void 0;
+      await cmdSuggest(query, type);
+      break;
+    }
     case "get": {
       const type = args[1];
       const id = args[2];
@@ -1327,6 +1949,10 @@ async function main() {
       await cmdValidate(args[1]);
       break;
     }
+    case "theme": {
+      await cmdTheme(args.slice(1));
+      break;
+    }
     default:
       console.error(error(`Unknown command: ${command}`));
       cmdHelp();