npm - @decantr/cli - Versions diffs - 1.0.0-beta.10 → 1.0.0-beta.11 - Mend

@decantr/cli 1.0.0-beta.10 → 1.0.0-beta.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/dist/index.js +903 -75
package/package.json +1 -1
package/src/templates/DECANTR.md.template +142 -3

package/dist/index.js CHANGED Viewed

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 // src/index.ts
-import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
-import { join as join4 } from "path";
+import { readFileSync as readFileSync5, existsSync as existsSync5 } from "fs";
+import { join as join5 } from "path";
 import { validateEssence, evaluateGuard } from "@decantr/essence-spec";
 import { createResolver, createRegistryClient } from "@decantr/registry";
@@ -331,6 +337,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)) {
@@ -371,7 +411,7 @@ function buildEssence(options, archetypeData) {
     spacious: "_gap6"
   };
   const archetype = options.archetype || "custom";
-  return {
+  const essence = {
     version: "2.0.0",
     archetype,
     theme: {
@@ -399,14 +439,105 @@ function buildEssence(options, archetypeData) {
     },
     target: options.target
   };
+  if (options.accessibility) {
+    essence.accessibility = options.accessibility;
+  }
+  return essence;
+}
+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) {
+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}`,
@@ -423,6 +554,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,
@@ -441,7 +595,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);
 }
@@ -490,10 +647,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 = {
@@ -514,7 +671,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",
@@ -556,7 +713,7 @@ ${cacheEntry}
     return true;
   }
 }
-function scaffoldProject(projectRoot, options, detected, archetypeData, registrySource = "bundled") {
+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");
@@ -566,7 +723,7 @@ function scaffoldProject(projectRoot, options, detected, archetypeData, registry
   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 = [];
@@ -645,33 +802,56 @@ function loadFromCache(cacheDir, contentType, id) {
 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;
+    const mainPath = join3(contentRoot, contentType, `${id}.json`);
+    if (existsSync3(mainPath)) {
+      try {
+        const data = JSON.parse(readFileSync3(mainPath, "utf-8"));
+        return { data, source: { type: "bundled" } };
+      } catch {
+      }
+    }
+    const corePath = join3(contentRoot, "core", contentType, `${id}.json`);
+    if (existsSync3(corePath)) {
+      try {
+        const data = JSON.parse(readFileSync3(corePath, "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;
+    const mainDir = join3(contentRoot, contentType);
+    const coreDir = join3(contentRoot, "core", contentType);
+    const items = [];
+    if (existsSync3(mainDir)) {
+      try {
+        const files = readdirSync(mainDir).filter((f) => f.endsWith(".json"));
+        for (const f of files) {
+          const content = JSON.parse(readFileSync3(join3(mainDir, f), "utf-8"));
+          items.push({ id: content.id || f.replace(".json", ""), ...content });
+        }
+      } catch {
+      }
+    }
+    if (existsSync3(coreDir)) {
+      try {
+        const files = readdirSync(coreDir).filter((f) => f.endsWith(".json"));
+        const existingIds = new Set(items.map((i) => i.id));
+        for (const f of files) {
+          const content = JSON.parse(readFileSync3(join3(coreDir, f), "utf-8"));
+          const itemId = content.id || f.replace(".json", "");
+          if (!existingIds.has(itemId)) {
+            items.push({ id: itemId, ...content });
+          }
+        }
+      } catch {
+      }
     }
+    if (items.length === 0) return null;
+    return {
+      data: { items, total: items.length },
+      source: { type: "bundled" }
+    };
   }
 }
 function saveToCache(cacheDir, contentType, id, data) {
@@ -684,11 +864,37 @@ var RegistryClient = class {
   cacheDir;
   apiUrl;
   offline;
+  projectRoot;
   constructor(options = {}) {
-    this.cacheDir = options.cacheDir || join3(process.cwd(), ".decantr", "cache");
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.cacheDir = options.cacheDir || join3(this.projectRoot, ".decantr", "cache");
     this.apiUrl = options.apiUrl || DEFAULT_API_URL;
     this.offline = options.offline || false;
   }
+  /**
+   * Load content from .decantr/custom/{contentType}/{id}.json
+   */
+  loadCustomContent(contentType, id) {
+    const customPath = join3(
+      this.projectRoot,
+      ".decantr",
+      "custom",
+      contentType,
+      `${id}.json`
+    );
+    if (!existsSync3(customPath)) {
+      return null;
+    }
+    try {
+      const data = JSON.parse(readFileSync3(customPath, "utf-8"));
+      return {
+        data,
+        source: { type: "custom", path: customPath }
+      };
+    } catch {
+      return null;
+    }
+  }
   /**
    * Fetch archetypes list.
    */
@@ -788,6 +994,24 @@ var RegistryClient = class {
       source: { type: "bundled" }
     };
   }
+  /**
+   * Fetch a single theme.
+   */
+  async fetchTheme(id) {
+    if (id.startsWith("custom:")) {
+      return this.loadCustomContent("themes", id.slice(7));
+    }
+    if (!this.offline) {
+      const apiResult = await tryApi(`themes/${id}`, this.apiUrl);
+      if (apiResult) {
+        saveToCache(this.cacheDir, "themes", id, apiResult.data);
+        return apiResult;
+      }
+    }
+    const cacheResult = loadFromCache(this.cacheDir, "themes", id);
+    if (cacheResult) return cacheResult;
+    return loadFromBundled("themes", id);
+  }
   /**
    * Fetch patterns list.
    */
@@ -857,6 +1081,228 @@ async function syncRegistry(cacheDir, apiUrl = DEFAULT_API_URL) {
   };
 }
+// src/theme-commands.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync3, readdirSync as readdirSync2, rmSync } from "fs";
+import { join as join4 } 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"
+  };
+}
+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"
+  }
+}
+\`\`\`
+## Validation
+\`\`\`bash
+decantr theme validate mytheme
+\`\`\`
+## Reference
+See registry themes for examples:
+\`\`\`bash
+decantr get theme auradecantism
+\`\`\`
+`;
+}
+// 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}`);
+    }
+  }
+  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}`);
+      }
+    }
+  }
+  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"`);
+      }
+    }
+  }
+  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`);
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function createTheme(projectRoot, id, name) {
+  const customThemesDir = join4(projectRoot, ".decantr", "custom", "themes");
+  const themePath = join4(customThemesDir, `${id}.json`);
+  const howToPath = join4(customThemesDir, "how-to-theme.md");
+  mkdirSync3(customThemesDir, { recursive: true });
+  if (existsSync4(themePath)) {
+    return {
+      success: false,
+      error: `Theme "${id}" already exists at ${themePath}`
+    };
+  }
+  const skeleton = getThemeSkeleton(id, name);
+  writeFileSync3(themePath, JSON.stringify(skeleton, null, 2));
+  if (!existsSync4(howToPath)) {
+    writeFileSync3(howToPath, getHowToThemeDoc());
+  }
+  return {
+    success: true,
+    path: themePath
+  };
+}
+function listCustomThemes(projectRoot) {
+  const customThemesDir = join4(projectRoot, ".decantr", "custom", "themes");
+  if (!existsSync4(customThemesDir)) {
+    return [];
+  }
+  const themes = [];
+  try {
+    const files = readdirSync2(customThemesDir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      const filePath = join4(customThemesDir, file);
+      try {
+        const data = JSON.parse(readFileSync4(filePath, "utf-8"));
+        themes.push({
+          id: data.id || file.replace(".json", ""),
+          name: data.name || data.id,
+          description: data.description,
+          path: filePath
+        });
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return themes;
+}
+function deleteTheme(projectRoot, id) {
+  const themePath = join4(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
+  if (!existsSync4(themePath)) {
+    return {
+      success: false,
+      error: `Theme "${id}" not found at ${themePath}`
+    };
+  }
+  try {
+    rmSync(themePath);
+    return { success: true };
+  } catch (e) {
+    return {
+      success: false,
+      error: `Failed to delete: ${e.message}`
+    };
+  }
+}
+function importTheme(projectRoot, sourcePath) {
+  if (!existsSync4(sourcePath)) {
+    return {
+      success: false,
+      errors: [`Source file not found: ${sourcePath}`]
+    };
+  }
+  let theme;
+  try {
+    theme = JSON.parse(readFileSync4(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 = join4(projectRoot, ".decantr", "custom", "themes");
+  const destPath = join4(customThemesDir, `${id}.json`);
+  mkdirSync3(customThemesDir, { recursive: true });
+  const howToPath = join4(customThemesDir, "how-to-theme.md");
+  if (!existsSync4(howToPath)) {
+    writeFileSync3(howToPath, getHowToThemeDoc());
+  }
+  writeFileSync3(destPath, JSON.stringify(theme, null, 2));
+  return {
+    success: true,
+    path: destPath
+  };
+}
 // src/index.ts
 var BOLD2 = "\x1B[1m";
 var DIM2 = "\x1B[2m";
@@ -882,8 +1328,63 @@ 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");
+  const bundled = join5(import.meta.dirname, "..", "..", "..", "content");
   return process.env.DECANTR_CONTENT_ROOT || bundled;
 }
 function getResolver() {
@@ -903,6 +1404,38 @@ 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"];
   if (!validTypes.includes(type)) {
@@ -931,11 +1464,58 @@ async function cmdGet(type, id) {
   }
   console.log(JSON.stringify(result.item, null, 2));
 }
+function buildRegistryContext() {
+  const { readdirSync: readdirSync3 } = __require("fs");
+  const themeRegistry = /* @__PURE__ */ new Map();
+  const patternRegistry = /* @__PURE__ */ new Map();
+  const contentRoot = getContentRoot();
+  const themeDirs = [join5(contentRoot, "themes"), join5(contentRoot, "core", "themes")];
+  for (const dir of themeDirs) {
+    try {
+      if (existsSync5(dir)) {
+        for (const f of readdirSync3(dir).filter((f2) => f2.endsWith(".json"))) {
+          const data = JSON.parse(readFileSync5(join5(dir, f), "utf-8"));
+          if (data.id && !themeRegistry.has(data.id)) {
+            themeRegistry.set(data.id, { modes: data.modes || ["light", "dark"] });
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  const customThemesDir = join5(process.cwd(), ".decantr", "custom", "themes");
+  try {
+    if (existsSync5(customThemesDir)) {
+      for (const f of readdirSync3(customThemesDir).filter((f2) => f2.endsWith(".json"))) {
+        const data = JSON.parse(readFileSync5(join5(customThemesDir, f), "utf-8"));
+        if (data.id) {
+          themeRegistry.set(`custom:${data.id}`, { modes: data.modes || ["light", "dark"] });
+        }
+      }
+    }
+  } catch {
+  }
+  const patternDirs = [join5(contentRoot, "patterns"), join5(contentRoot, "core", "patterns")];
+  for (const dir of patternDirs) {
+    try {
+      if (existsSync5(dir)) {
+        for (const f of readdirSync3(dir).filter((f2) => f2.endsWith(".json"))) {
+          const data = JSON.parse(readFileSync5(join5(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");
+  const essencePath = path || join5(process.cwd(), "decantr.essence.json");
   let raw;
   try {
-    raw = readFileSync4(essencePath, "utf-8");
+    raw = readFileSync5(essencePath, "utf-8");
   } catch {
     console.error(error(`Could not read ${essencePath}`));
     process.exitCode = 1;
@@ -960,12 +1540,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."));
@@ -980,36 +1564,98 @@ async function cmdList(type) {
     process.exitCode = 1;
     return;
   }
-  const { readdirSync: readdirSync2 } = await import("fs");
-  const dir = join4(getContentRoot(), type);
-  let found = false;
+  const { readdirSync: readdirSync3, existsSync: existsSync6 } = await import("fs");
+  const contentRoot = getContentRoot();
+  const mainDir = join5(contentRoot, type);
+  const coreDir = join5(contentRoot, "core", type);
+  const items = [];
   try {
-    const files = readdirSync2(dir).filter((f) => f.endsWith(".json"));
-    if (files.length > 0) {
-      found = true;
-      console.log(heading(`${files.length} ${type}`));
+    if (existsSync6(mainDir)) {
+      const files = readdirSync3(mainDir).filter((f) => f.endsWith(".json"));
       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(readFileSync5(join5(mainDir, f), "utf-8"));
+        items.push({ id: data.id || f.replace(".json", ""), description: data.description, name: data.name });
       }
     }
   } catch {
   }
-  if (!found) {
+  try {
+    if (existsSync6(coreDir)) {
+      const files = readdirSync3(coreDir).filter((f) => f.endsWith(".json"));
+      const existingIds = new Set(items.map((i) => i.id));
+      for (const f of files) {
+        const data = JSON.parse(readFileSync5(join5(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 {
+  }
+  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();
@@ -1024,7 +1670,7 @@ async function cmdInit(args) {
     }
   }
   const registryClient = new RegistryClient({
-    cacheDir: join4(projectRoot, ".decantr", "cache"),
+    cacheDir: join5(projectRoot, ".decantr", "cache"),
     apiUrl: args.registry,
     offline: args.offline
   });
@@ -1068,13 +1714,26 @@ async function cmdInit(args) {
       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..."));
   const result = scaffoldProject(
     projectRoot,
     options,
     detected,
     archetypeData,
-    registrySource
+    registrySource,
+    themeData,
+    recipeData
   );
   console.log(success("\nProject scaffolded successfully!"));
   console.log("");
@@ -1085,7 +1744,7 @@ async function cmdInit(args) {
   if (result.gitignoreUpdated) {
     console.log(`  ${dim(".gitignore updated to exclude .decantr/cache/")}`);
   }
-  const essenceContent = readFileSync4(result.essencePath, "utf-8");
+  const essenceContent = readFileSync5(result.essencePath, "utf-8");
   const essence = JSON.parse(essenceContent);
   const validation = validateEssence(essence);
   if (validation.valid) {
@@ -1096,25 +1755,39 @@ 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("2. Copy the prompt below and share it 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.'));
   }
 }
 async function cmdStatus() {
   const projectRoot = process.cwd();
-  const essencePath = join4(projectRoot, "decantr.essence.json");
-  const projectJsonPath = join4(projectRoot, ".decantr", "project.json");
+  const essencePath = join5(projectRoot, "decantr.essence.json");
+  const projectJsonPath = join5(projectRoot, ".decantr", "project.json");
   console.log(heading("Decantr Project Status"));
-  if (!existsSync4(essencePath)) {
+  if (!existsSync5(essencePath)) {
     console.log(`${RED}No decantr.essence.json found.${RESET2}`);
     console.log(dim('Run "decantr init" to create one.'));
     return;
   }
   try {
-    const essence = JSON.parse(readFileSync4(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync5(essencePath, "utf-8"));
     const validation = validateEssence(essence);
     console.log(`${BOLD2}Essence:${RESET2}`);
     if (validation.valid) {
@@ -1130,9 +1803,9 @@ async function cmdStatus() {
   }
   console.log("");
   console.log(`${BOLD2}Sync Status:${RESET2}`);
-  if (existsSync4(projectJsonPath)) {
+  if (existsSync5(projectJsonPath)) {
     try {
-      const projectJson = JSON.parse(readFileSync4(projectJsonPath, "utf-8"));
+      const projectJson = JSON.parse(readFileSync5(projectJsonPath, "utf-8"));
       const syncStatus = projectJson.sync?.status || "unknown";
       const lastSync = projectJson.sync?.lastSync || "never";
       const source = projectJson.sync?.registrySource || "unknown";
@@ -1150,7 +1823,7 @@ async function cmdStatus() {
 }
 async function cmdSync() {
   const projectRoot = process.cwd();
-  const cacheDir = join4(projectRoot, ".decantr", "cache");
+  const cacheDir = join5(projectRoot, ".decantr", "cache");
   console.log(heading("Syncing registry content..."));
   const result = await syncRegistry(cacheDir);
   if (result.source === "api") {
@@ -1168,15 +1841,15 @@ async function cmdSync() {
 }
 async function cmdAudit() {
   const projectRoot = process.cwd();
-  const essencePath = join4(projectRoot, "decantr.essence.json");
+  const essencePath = join5(projectRoot, "decantr.essence.json");
   console.log(heading("Auditing project..."));
-  if (!existsSync4(essencePath)) {
+  if (!existsSync5(essencePath)) {
     console.log(`${RED}No decantr.essence.json found.${RESET2}`);
     process.exitCode = 1;
     return;
   }
   try {
-    const essence = JSON.parse(readFileSync4(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync5(essencePath, "utf-8"));
     const validation = validateEssence(essence);
     if (!validation.valid) {
       console.log(`${RED}Essence validation failed:${RESET2}`);
@@ -1187,13 +1860,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."));
@@ -1208,6 +1885,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 = join5(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
+      if (!existsSync5(themePath)) {
+        console.error(error(`Theme "${name}" not found at ${themePath}`));
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const theme = JSON.parse(readFileSync5(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
@@ -1218,9 +2024,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}
@@ -1243,9 +2051,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}
@@ -1255,6 +2065,8 @@ ${BOLD2}Examples:${RESET2}
   decantr sync
   decantr audit
   decantr search dashboard
+  decantr suggest leaderboard
+  decantr suggest ranking --type pattern
   decantr list patterns
 `);
 }
@@ -1316,6 +2128,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];
@@ -1341,6 +2165,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();