@decantr/cli 1.0.0-beta.5 → 1.0.0-beta.8

package/dist/index.js

@@ -1,37 +1,888 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import { createInterface } from "readline";
+import { readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
+import { join as join4 } from "path";
 import { validateEssence, evaluateGuard } from "@decantr/essence-spec";
 import { createResolver, createRegistryClient } from "@decantr/registry";
+
+// src/detect.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var RULE_FILES = [
+  "CLAUDE.md",
+  ".cursorrules",
+  ".cursor/rules",
+  "AGENTS.md",
+  "GEMINI.md",
+  "copilot-instructions.md"
+];
+function detectProject(projectRoot = process.cwd()) {
+  const result = {
+    framework: "unknown",
+    packageManager: "unknown",
+    hasTypeScript: false,
+    hasTailwind: false,
+    existingRuleFiles: [],
+    existingEssence: false,
+    projectRoot
+  };
+  result.existingEssence = existsSync(join(projectRoot, "decantr.essence.json"));
+  for (const ruleFile of RULE_FILES) {
+    if (existsSync(join(projectRoot, ruleFile))) {
+      result.existingRuleFiles.push(ruleFile);
+    }
+  }
+  if (existsSync(join(projectRoot, "pnpm-lock.yaml"))) {
+    result.packageManager = "pnpm";
+  } else if (existsSync(join(projectRoot, "yarn.lock"))) {
+    result.packageManager = "yarn";
+  } else if (existsSync(join(projectRoot, "bun.lockb"))) {
+    result.packageManager = "bun";
+  } else if (existsSync(join(projectRoot, "package-lock.json"))) {
+    result.packageManager = "npm";
+  }
+  result.hasTypeScript = existsSync(join(projectRoot, "tsconfig.json"));
+  result.hasTailwind = existsSync(join(projectRoot, "tailwind.config.js")) || existsSync(join(projectRoot, "tailwind.config.ts")) || existsSync(join(projectRoot, "tailwind.config.mjs")) || existsSync(join(projectRoot, "tailwind.config.cjs"));
+  if (existsSync(join(projectRoot, "next.config.js")) || existsSync(join(projectRoot, "next.config.ts")) || existsSync(join(projectRoot, "next.config.mjs"))) {
+    result.framework = "nextjs";
+    result.version = getPackageVersion(projectRoot, "next");
+    return result;
+  }
+  if (existsSync(join(projectRoot, "nuxt.config.js")) || existsSync(join(projectRoot, "nuxt.config.ts"))) {
+    result.framework = "nuxt";
+    result.version = getPackageVersion(projectRoot, "nuxt");
+    return result;
+  }
+  if (existsSync(join(projectRoot, "astro.config.mjs")) || existsSync(join(projectRoot, "astro.config.ts"))) {
+    result.framework = "astro";
+    result.version = getPackageVersion(projectRoot, "astro");
+    return result;
+  }
+  if (existsSync(join(projectRoot, "svelte.config.js")) || existsSync(join(projectRoot, "svelte.config.ts"))) {
+    result.framework = "svelte";
+    result.version = getPackageVersion(projectRoot, "svelte");
+    return result;
+  }
+  if (existsSync(join(projectRoot, "angular.json"))) {
+    result.framework = "angular";
+    result.version = getPackageVersion(projectRoot, "@angular/core");
+    return result;
+  }
+  const packageJsonPath = join(projectRoot, "package.json");
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+      const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+      if (deps.next) {
+        result.framework = "nextjs";
+        result.version = deps.next.replace(/^\^|~/, "");
+      } else if (deps.nuxt) {
+        result.framework = "nuxt";
+        result.version = deps.nuxt.replace(/^\^|~/, "");
+      } else if (deps.astro) {
+        result.framework = "astro";
+        result.version = deps.astro.replace(/^\^|~/, "");
+      } else if (deps.svelte) {
+        result.framework = "svelte";
+        result.version = deps.svelte.replace(/^\^|~/, "");
+      } else if (deps["@angular/core"]) {
+        result.framework = "angular";
+        result.version = deps["@angular/core"].replace(/^\^|~/, "");
+      } else if (deps.vue) {
+        result.framework = "vue";
+        result.version = deps.vue.replace(/^\^|~/, "");
+      } else if (deps.react) {
+        result.framework = "react";
+        result.version = deps.react.replace(/^\^|~/, "");
+      }
+    } catch {
+    }
+  }
+  if (result.framework === "unknown" && !existsSync(packageJsonPath)) {
+    if (existsSync(join(projectRoot, "index.html"))) {
+      result.framework = "html";
+    }
+  }
+  return result;
+}
+function getPackageVersion(projectRoot, packageName) {
+  const packageJsonPath = join(projectRoot, "package.json");
+  if (!existsSync(packageJsonPath)) return void 0;
+  try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+    const version = deps[packageName];
+    return version?.replace(/^\^|~/, "");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/prompts.ts
+import { createInterface } from "readline";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
-var RED = "\x1B[31m";
 var GREEN = "\x1B[32m";
-var CYAN = "\x1B[36m";
 var YELLOW = "\x1B[33m";
+var CYAN = "\x1B[36m";
+function ask(question, defaultValue) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = defaultValue ? `${question} ${DIM}(${defaultValue})${RESET}: ` : `${question}: `;
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || "");
+    });
+  });
+}
+async function select(question, options, defaultIdx = 0, allowOther = false) {
+  console.log(`
+${BOLD}${question}${RESET}`);
+  for (let i = 0; i < options.length; i++) {
+    const marker = i === defaultIdx ? `${GREEN}>${RESET}` : " ";
+    const desc = options[i].description ? ` ${DIM}\u2014 ${options[i].description}${RESET}` : "";
+    console.log(`  ${marker} ${i + 1}. ${options[i].label}${desc}`);
+  }
+  if (allowOther) {
+    console.log(`    ${options.length + 1}. ${DIM}other (enter custom value)${RESET}`);
+  }
+  const maxIdx = allowOther ? options.length + 1 : options.length;
+  const answer = await ask(`Choose (1-${maxIdx})`, String(defaultIdx + 1));
+  const idx = parseInt(answer, 10) - 1;
+  if (allowOther && idx === options.length) {
+    const custom = await ask("Enter custom value");
+    return custom;
+  }
+  const validIdx = Math.max(0, Math.min(idx, options.length - 1));
+  return options[validIdx].value;
+}
+async function confirm(question, defaultYes = true) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const answer = await ask(`${question} [${hint}]`, defaultYes ? "y" : "n");
+  return answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+}
+function warn(message) {
+  console.log(`
+${YELLOW}  Warning: ${message}${RESET}`);
+}
+function showDetection(detected) {
+  console.log(`
+${CYAN}Detected project configuration:${RESET}`);
+  if (detected.framework !== "unknown") {
+    const version = detected.version ? ` ${detected.version}` : "";
+    console.log(`  Framework: ${detected.framework}${version}`);
+  }
+  if (detected.packageManager !== "unknown") {
+    console.log(`  Package manager: ${detected.packageManager}`);
+  }
+  if (detected.hasTypeScript) {
+    console.log(`  TypeScript: ${GREEN}yes${RESET}`);
+  }
+  if (detected.hasTailwind) {
+    console.log(`  Tailwind CSS: ${GREEN}yes${RESET}`);
+  }
+  if (detected.existingEssence) {
+    console.log(`  Existing essence: ${YELLOW}yes${RESET}`);
+  }
+}
+async function runInteractivePrompts(detected, archetypes, blueprints, themes) {
+  showDetection(detected);
+  const blueprintOptions = [
+    { value: "none", label: "none", description: "Start from scratch (blank canvas)" },
+    ...blueprints.map((b) => ({
+      value: b.id,
+      label: b.id,
+      description: b.description
+    }))
+  ];
+  const blueprint = await select("What are you building?", blueprintOptions, 0, true);
+  const isBlank = blueprint === "none";
+  const themeOptions = themes.map((t) => ({
+    value: t.id,
+    label: t.id,
+    description: t.description
+  }));
+  const defaultThemeIdx = themeOptions.findIndex((t) => t.value === "luminarum") || 0;
+  const theme = await select("Choose a theme", themeOptions, Math.max(0, defaultThemeIdx), true);
+  const mode = await select(
+    "Color mode",
+    [
+      { value: "dark", label: "dark", description: "Dark background" },
+      { value: "light", label: "light", description: "Light background" },
+      { value: "auto", label: "auto", description: "Follow system preference" }
+    ],
+    0
+  );
+  const shape = await select(
+    "Border shape",
+    [
+      { value: "pill", label: "pill", description: "Fully rounded corners" },
+      { value: "rounded", label: "rounded", description: "Moderately rounded" },
+      { value: "sharp", label: "sharp", description: "No border radius" }
+    ],
+    0,
+    true
+  );
+  const frameworkOptions = [
+    { value: "react", label: "react", description: "React / Create React App" },
+    { value: "nextjs", label: "nextjs", description: "Next.js" },
+    { value: "vue", label: "vue", description: "Vue.js" },
+    { value: "nuxt", label: "nuxt", description: "Nuxt" },
+    { value: "svelte", label: "svelte", description: "Svelte / SvelteKit" },
+    { value: "astro", label: "astro", description: "Astro" },
+    { value: "angular", label: "angular", description: "Angular" },
+    { value: "html", label: "html", description: "Plain HTML/CSS/JS" }
+  ];
+  let defaultFrameworkIdx = frameworkOptions.findIndex((f) => f.value === detected.framework);
+  if (defaultFrameworkIdx < 0) defaultFrameworkIdx = 0;
+  const target = await select("Target framework", frameworkOptions, defaultFrameworkIdx, true);
+  if (detected.framework !== "unknown" && target !== detected.framework) {
+    warn(`This project appears to be ${detected.framework} but you selected ${target}.`);
+    const proceed = await confirm("Continue anyway?", false);
+    if (!proceed) {
+      console.log(`${DIM}Using detected framework: ${detected.framework}${RESET}`);
+    }
+  }
+  const guardMode = await select(
+    "Guard enforcement level",
+    [
+      { value: "creative", label: "creative", description: "Advisory only (new projects)" },
+      { value: "guided", label: "guided", description: "Style, structure, recipe enforced" },
+      { value: "strict", label: "strict", description: "All 5 rules enforced exactly" }
+    ],
+    detected.existingEssence ? 1 : 2
+    // Default to guided for existing, strict for new
+  );
+  const density = await select(
+    "Spacing density",
+    [
+      { value: "compact", label: "compact", description: "Dense UI, minimal spacing" },
+      { value: "comfortable", label: "comfortable", description: "Balanced spacing" },
+      { value: "spacious", label: "spacious", description: "Generous whitespace" }
+    ],
+    1
+  );
+  const shellOptions = [
+    { value: "sidebar-main", label: "sidebar-main", description: "Collapsible sidebar with main content" },
+    { value: "top-nav-main", label: "top-nav-main", description: "Horizontal nav with full-width content" },
+    { value: "centered", label: "centered", description: "Centered card (auth flows)" },
+    { value: "full-bleed", label: "full-bleed", description: "No persistent nav (landing pages)" },
+    { value: "minimal-header", label: "minimal-header", description: "Slim header with centered content" }
+  ];
+  let defaultShellIdx = 0;
+  if (["nextjs", "nuxt", "astro"].includes(target)) {
+    defaultShellIdx = shellOptions.findIndex((s) => s.value === "top-nav-main");
+  }
+  const shell = await select("Default page shell (layout)", shellOptions, Math.max(0, defaultShellIdx), true);
+  return {
+    blueprint: isBlank ? void 0 : blueprint,
+    archetype: void 0,
+    // Will be derived from blueprint
+    theme,
+    mode,
+    shape,
+    target,
+    guard: guardMode,
+    density,
+    shell,
+    personality: ["professional"],
+    features: [],
+    existing: detected.existingEssence
+  };
+}
+function parseFlags(args, detected) {
+  const options = {};
+  if (typeof args.blueprint === "string") options.blueprint = args.blueprint;
+  if (typeof args.archetype === "string") options.archetype = args.archetype;
+  if (typeof args.theme === "string") options.theme = args.theme;
+  if (args.mode === "dark" || args.mode === "light" || args.mode === "auto") options.mode = args.mode;
+  if (typeof args.shape === "string") options.shape = args.shape;
+  if (typeof args.target === "string") options.target = args.target;
+  if (args.guard === "creative" || args.guard === "guided" || args.guard === "strict") options.guard = args.guard;
+  if (args.density === "compact" || args.density === "comfortable" || args.density === "spacious") options.density = args.density;
+  if (typeof args.shell === "string") options.shell = args.shell;
+  if (typeof args.personality === "string") options.personality = args.personality.split(",").map((s) => s.trim());
+  if (typeof args.features === "string") options.features = args.features.split(",").map((s) => s.trim());
+  if (args.existing === true) options.existing = true;
+  return options;
+}
+function mergeWithDefaults(flags, detected) {
+  return {
+    blueprint: flags.blueprint,
+    archetype: flags.archetype,
+    theme: flags.theme || "luminarum",
+    mode: flags.mode || "dark",
+    shape: flags.shape || "rounded",
+    target: flags.target || (detected.framework !== "unknown" ? detected.framework : "react"),
+    guard: flags.guard || (detected.existingEssence ? "guided" : "strict"),
+    density: flags.density || "comfortable",
+    shell: flags.shell || "sidebar-main",
+    personality: flags.personality || ["professional"],
+    features: flags.features || [],
+    existing: flags.existing || detected.existingEssence
+  };
+}
+
+// src/scaffold.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync, appendFileSync } from "fs";
+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 loadTemplate(name) {
+  const fromDist = join2(__dirname, "..", "src", "templates", name);
+  if (existsSync2(fromDist)) {
+    return readFileSync2(fromDist, "utf-8");
+  }
+  const fromSrc = join2(__dirname, "templates", name);
+  if (existsSync2(fromSrc)) {
+    return readFileSync2(fromSrc, "utf-8");
+  }
+  throw new Error(`Template not found: ${name}`);
+}
+function renderTemplate(template, vars) {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+  }
+  return result;
+}
+function buildEssence(options, blueprint) {
+  let structure = [
+    { id: "home", shell: options.shell, layout: [] }
+  ];
+  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 (blueprint?.features) {
+    features = [.../* @__PURE__ */ new Set([...features, ...blueprint.features])];
+  }
+  const contentGapMap = {
+    compact: "_gap2",
+    comfortable: "_gap4",
+    spacious: "_gap6"
+  };
+  return {
+    version: "2.0.0",
+    archetype: options.archetype,
+    blueprint: options.blueprint,
+    theme: {
+      style: options.theme,
+      mode: options.mode,
+      recipe: options.theme,
+      // Recipe defaults to theme
+      shape: options.shape
+    },
+    personality: options.personality,
+    platform: {
+      type: "spa",
+      routing: "hash"
+    },
+    structure,
+    features,
+    guard: {
+      enforce_style: true,
+      enforce_recipe: true,
+      mode: options.guard
+    },
+    density: {
+      level: options.density,
+      content_gap: contentGapMap[options.density] || "_gap4"
+    },
+    target: options.target
+  };
+}
+function generateDecantrMd(essence, detected) {
+  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 projectSummary = [
+    `**Archetype:** ${essence.archetype || "custom"}`,
+    `**Target:** ${essence.target}`,
+    `**Theme:** ${essence.theme.style} (${essence.theme.mode} mode)`,
+    `**Guard Mode:** ${essence.guard.mode}`,
+    `**Pages:** ${essence.structure.map((s) => s.id).join(", ")}`
+  ].join("\n");
+  const shellStructures = {
+    "sidebar-main": "nav (left) | header (top) | body (scrollable)",
+    "top-nav-main": "header (full width) | body (scrollable)",
+    "centered": "body (centered card)",
+    "full-bleed": "header (floating) | body (full page sections)",
+    "minimal-header": "header (slim) | body (centered)"
+  };
+  const defaultShell = essence.structure[0]?.shell || "sidebar-main";
+  const shellStructure = shellStructures[defaultShell] || "Custom shell layout";
+  const vars = {
+    GUARD_MODE: essence.guard.mode,
+    PROJECT_SUMMARY: projectSummary,
+    THEME_STYLE: essence.theme.style,
+    THEME_MODE: essence.theme.mode,
+    THEME_RECIPE: essence.theme.recipe,
+    TARGET: essence.target,
+    PAGES_TABLE: `| Page | Shell | Layout |
+|------|-------|--------|
+${pagesTable}`,
+    PATTERNS_LIST: patternsList,
+    DEFAULT_SHELL: defaultShell,
+    SHELL_STRUCTURE: shellStructure,
+    PERSONALITY: essence.personality.join(", "),
+    DENSITY: essence.density.level,
+    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
+  };
+  return renderTemplate(template, vars);
+}
+function generateProjectJson(detected, options, registrySource) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const data = {
+    detected: {
+      framework: detected.framework,
+      version: detected.version || null,
+      packageManager: detected.packageManager,
+      hasTypeScript: detected.hasTypeScript,
+      hasTailwind: detected.hasTailwind,
+      existingRuleFiles: detected.existingRuleFiles
+    },
+    overrides: {
+      framework: options.target !== detected.framework ? options.target : null
+    },
+    sync: {
+      status: registrySource === "api" ? "synced" : "needs-sync",
+      lastSync: now,
+      registrySource,
+      cachedContent: {
+        archetypes: [],
+        patterns: [],
+        themes: [],
+        recipes: []
+      }
+    },
+    initialized: {
+      at: now,
+      via: "cli",
+      version: CLI_VERSION,
+      flags: buildFlagsString(options)
+    }
+  };
+  return JSON.stringify(data, null, 2);
+}
+function buildFlagsString(options) {
+  const flags = [];
+  if (options.blueprint) flags.push(`--blueprint=${options.blueprint}`);
+  if (options.theme) flags.push(`--theme=${options.theme}`);
+  if (options.mode) flags.push(`--mode=${options.mode}`);
+  if (options.guard) flags.push(`--guard=${options.guard}`);
+  return flags.join(" ");
+}
+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 scaffoldStructure = essence.structure.map((p) => {
+    const patterns = p.layout.length > 0 ? `
+  - Patterns: ${p.layout.join(", ")}` : "";
+    return `- **${p.id}** (${p.shell})${patterns}`;
+  }).join("\n");
+  const vars = {
+    TARGET: essence.target,
+    THEME_STYLE: essence.theme.style,
+    THEME_MODE: essence.theme.mode,
+    THEME_RECIPE: essence.theme.recipe,
+    DEFAULT_SHELL: defaultShell,
+    GUARD_MODE: essence.guard.mode,
+    LAYOUT: layout,
+    DENSITY: essence.density.level,
+    CONTENT_GAP: essence.density.content_gap,
+    SCAFFOLD_STRUCTURE: scaffoldStructure
+  };
+  return renderTemplate(template, vars);
+}
+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")}`;
+  const featuresList = essence.features.length > 0 ? essence.features.map((f) => `- ${f}`).join("\n") : "- No features specified";
+  const vars = {
+    ARCHETYPE: essence.archetype || "custom",
+    BLUEPRINT: essence.blueprint || "none",
+    PERSONALITY: essence.personality.join(", "),
+    TARGET: essence.target,
+    THEME_STYLE: essence.theme.style,
+    THEME_MODE: essence.theme.mode,
+    THEME_RECIPE: essence.theme.recipe,
+    SHAPE: essence.theme.shape,
+    PAGES_TABLE: pagesTable,
+    FEATURES_LIST: featuresList,
+    GUARD_MODE: essence.guard.mode,
+    ENFORCE_STYLE: String(essence.guard.enforce_style),
+    ENFORCE_RECIPE: String(essence.guard.enforce_recipe),
+    DENSITY: essence.density.level,
+    CONTENT_GAP: essence.density.content_gap,
+    LAST_UPDATED: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return renderTemplate(template, vars);
+}
+function updateGitignore(projectRoot) {
+  const gitignorePath = join2(projectRoot, ".gitignore");
+  const cacheEntry = ".decantr/cache/";
+  if (existsSync2(gitignorePath)) {
+    const content = readFileSync2(gitignorePath, "utf-8");
+    if (!content.includes(cacheEntry)) {
+      appendFileSync(gitignorePath, `
+# Decantr cache
+${cacheEntry}
+`);
+      return true;
+    }
+    return false;
+  } else {
+    writeFileSync(gitignorePath, `# Decantr cache
+${cacheEntry}
+`);
+    return true;
+  }
+}
+function scaffoldProject(projectRoot, options, detected, blueprint, registrySource = "bundled") {
+  const essence = buildEssence(options, blueprint);
+  const decantrDir = join2(projectRoot, ".decantr");
+  const contextDir = join2(decantrDir, "context");
+  const cacheDir = join2(decantrDir, "cache");
+  mkdirSync(contextDir, { recursive: true });
+  mkdirSync(cacheDir, { recursive: true });
+  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));
+  const projectJsonPath = join2(decantrDir, "project.json");
+  writeFileSync(projectJsonPath, generateProjectJson(detected, options, registrySource));
+  const contextFiles = [];
+  const scaffoldPath = join2(contextDir, "task-scaffold.md");
+  writeFileSync(scaffoldPath, generateTaskContext("task-scaffold.md.template", essence));
+  contextFiles.push(scaffoldPath);
+  const addPagePath = join2(contextDir, "task-add-page.md");
+  writeFileSync(addPagePath, generateTaskContext("task-add-page.md.template", essence));
+  contextFiles.push(addPagePath);
+  const modifyPath = join2(contextDir, "task-modify.md");
+  writeFileSync(modifyPath, generateTaskContext("task-modify.md.template", essence));
+  contextFiles.push(modifyPath);
+  const summaryPath = join2(contextDir, "essence-summary.md");
+  writeFileSync(summaryPath, generateEssenceSummary(essence));
+  contextFiles.push(summaryPath);
+  const gitignoreUpdated = updateGitignore(projectRoot);
+  return {
+    essencePath,
+    decantrMdPath,
+    projectJsonPath,
+    contextFiles,
+    gitignoreUpdated
+  };
+}
+
+// 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);
+  }
+}
+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 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;
+  }
+}
+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;
+    }
+  }
+}
+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;
+      }
+    }
+    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;
+      }
+    }
+    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;
+      }
+    }
+    const cacheResult = loadFromCache(
+      this.cacheDir,
+      "blueprints"
+    );
+    if (cacheResult) return cacheResult;
+    const bundledResult = loadFromBundled("blueprints");
+    if (bundledResult) return bundledResult;
+    return {
+      data: { items: [], total: 0 },
+      source: { type: "bundled" }
+    };
+  }
+  /**
+   * 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 cacheResult = loadFromCache(
+      this.cacheDir,
+      "themes"
+    );
+    if (cacheResult) return cacheResult;
+    const bundledResult = loadFromBundled("themes");
+    if (bundledResult) return bundledResult;
+    return {
+      data: { items: [], total: 0 },
+      source: { type: "bundled" }
+    };
+  }
+  /**
+   * 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;
+    return {
+      data: { items: [], total: 0 },
+      source: { type: "bundled" }
+    };
+  }
+  /**
+   * 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;
+    }
+  }
+  /**
+   * 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);
+    }
+  }
+  return {
+    synced,
+    failed,
+    source: synced.length > 0 ? "api" : "bundled"
+  };
+}
+
+// src/index.ts
+var BOLD2 = "\x1B[1m";
+var DIM2 = "\x1B[2m";
+var RESET2 = "\x1B[0m";
+var RED = "\x1B[31m";
+var GREEN2 = "\x1B[32m";
+var CYAN2 = "\x1B[36m";
+var YELLOW2 = "\x1B[33m";
 function heading(text) {
   return `
-${BOLD}${text}${RESET}
+${BOLD2}${text}${RESET2}
 `;
 }
 function success(text) {
-  return `${GREEN}${text}${RESET}`;
+  return `${GREEN2}${text}${RESET2}`;
 }
 function error(text) {
-  return `${RED}${text}${RESET}`;
+  return `${RED}${text}${RESET2}`;
 }
 function dim(text) {
-  return `${DIM}${text}${RESET}`;
+  return `${DIM2}${text}${RESET2}`;
 }
 function cyan(text) {
-  return `${CYAN}${text}${RESET}`;
+  return `${CYAN2}${text}${RESET2}`;
 }
 function getContentRoot() {
-  const bundled = join(import.meta.dirname, "..", "..", "..", "content");
+  const bundled = join4(import.meta.dirname, "..", "..", "..", "content");
   return process.env.DECANTR_CONTENT_ROOT || bundled;
 }
 function getResolver() {
@@ -46,7 +897,7 @@ async function cmdSearch(query, type) {
   }
   console.log(heading(`${results.length} result(s) for "${query}"`));
   for (const r of results) {
-    console.log(`  ${cyan(r.type.padEnd(12))} ${BOLD}${r.id}${RESET}`);
+    console.log(`  ${cyan(r.type.padEnd(12))} ${BOLD2}${r.id}${RESET2}`);
     console.log(`  ${dim(r.description || "")}`);
     console.log("");
   }
@@ -80,10 +931,10 @@ async function cmdGet(type, id) {
   console.log(JSON.stringify(result.item, null, 2));
 }
 async function cmdValidate(path) {
-  const essencePath = path || join(process.cwd(), "decantr.essence.json");
+  const essencePath = path || join4(process.cwd(), "decantr.essence.json");
   let raw;
   try {
-    raw = readFileSync(essencePath, "utf-8");
+    raw = readFileSync4(essencePath, "utf-8");
   } catch {
     console.error(error(`Could not read ${essencePath}`));
     process.exitCode = 1;
@@ -103,7 +954,7 @@ async function cmdValidate(path) {
   } else {
     console.error(error("Validation failed:"));
     for (const err of result.errors) {
-      console.error(`  ${RED}${err}${RESET}`);
+      console.error(`  ${RED}${err}${RESET2}`);
     }
     process.exitCode = 1;
   }
@@ -113,7 +964,7 @@ async function cmdValidate(path) {
       console.log(heading("Guard violations:"));
       for (const v of violations) {
         const vr = v;
-        console.log(`  ${YELLOW}[${vr.rule}]${RESET} ${vr.message}`);
+        console.log(`  ${YELLOW2}[${vr.rule}]${RESET2} ${vr.message}`);
       }
     } else if (result.valid) {
       console.log(success("No guard violations."));
@@ -128,16 +979,16 @@ async function cmdList(type) {
     process.exitCode = 1;
     return;
   }
-  const { readdirSync } = await import("fs");
-  const dir = join(getContentRoot(), type);
+  const { readdirSync: readdirSync2 } = await import("fs");
+  const dir = join4(getContentRoot(), type);
   let found = false;
   try {
-    const files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+    const files = readdirSync2(dir).filter((f) => f.endsWith(".json"));
     if (files.length > 0) {
       found = true;
       console.log(heading(`${files.length} ${type}`));
       for (const f of files) {
-        const data = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+        const data = JSON.parse(readFileSync4(join4(dir, f), "utf-8"));
         console.log(`  ${cyan(data.id || f.replace(".json", ""))}  ${dim(data.description || data.name || "")}`);
       }
     }
@@ -159,169 +1010,238 @@ async function cmdList(type) {
     console.log(dim(`No ${type} found.`));
   }
 }
-function ask(question, defaultValue) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const prompt = defaultValue ? `${question} ${dim(`(${defaultValue})`)}: ` : `${question}: `;
-  return new Promise((resolve) => {
-    rl.question(prompt, (answer) => {
-      rl.close();
-      resolve(answer.trim() || defaultValue || "");
-    });
-  });
-}
-async function select(question, options, defaultIdx = 0) {
-  console.log(`
-${BOLD}${question}${RESET}`);
-  for (let i = 0; i < options.length; i++) {
-    const marker = i === defaultIdx ? `${GREEN}>${RESET}` : " ";
-    console.log(`  ${marker} ${i + 1}. ${options[i]}`);
-  }
-  const answer = await ask(`Choose (1-${options.length})`, String(defaultIdx + 1));
-  const idx = parseInt(answer, 10) - 1;
-  return options[Math.max(0, Math.min(idx, options.length - 1))];
-}
-async function cmdInit() {
-  console.log(heading("Create a new Decantr project"));
-  const essencePath = join(process.cwd(), "decantr.essence.json");
-  if (existsSync(essencePath)) {
-    const overwrite = await ask("decantr.essence.json already exists. Overwrite?", "n");
-    if (overwrite.toLowerCase() !== "y") {
+async function cmdInit(args) {
+  const projectRoot = process.cwd();
+  console.log(heading("Decantr Project Setup"));
+  const detected = detectProject(projectRoot);
+  if (detected.existingEssence && !args.existing) {
+    console.log(`${YELLOW2}Warning: decantr.essence.json already exists.${RESET2}`);
+    const overwrite = await confirm("Overwrite existing configuration?", false);
+    if (!overwrite) {
       console.log(dim("Cancelled."));
       return;
     }
   }
-  let archetypes = [];
-  try {
-    const res = await fetch("https://decantr-registry.fly.dev/v1/archetypes");
-    if (res.ok) {
-      const data = await res.json();
-      archetypes = data.items;
-    }
-  } catch {
+  const registryClient = new RegistryClient({
+    cacheDir: join4(projectRoot, ".decantr", "cache"),
+    apiUrl: args.registry,
+    offline: args.offline
+  });
+  console.log(dim("Fetching registry content..."));
+  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 (archetypes.length === 0) {
-    archetypes = [
-      { id: "saas-dashboard", description: "Analytics dashboard with KPIs and data tables" },
-      { id: "ecommerce", description: "Online store with product catalog" },
-      { id: "portfolio", description: "Personal or agency portfolio site" },
-      { id: "marketing-landing", description: "Product marketing landing page" },
-      { id: "gaming-platform", description: "Gaming community hub" },
-      { id: "content-site", description: "Blog or content site" }
-    ];
-  }
-  const archetypeOptions = archetypes.map((a) => `${a.id} ${dim(`\u2014 ${a.description || ""}`)}`);
-  const selectedArchetype = await select("What are you building?", archetypeOptions);
-  const archetypeId = selectedArchetype.split(" ")[0];
-  let themes = [];
-  try {
-    const res = await fetch("https://decantr-registry.fly.dev/v1/themes");
-    if (res.ok) {
-      const data = await res.json();
-      themes = data.items;
-    }
-  } catch {
+  const archetypes = archetypesResult.data.items;
+  const blueprints = blueprintsResult.data.items;
+  const themes = themesResult.data.items;
+  let options;
+  if (args.yes) {
+    const flags = parseFlags(args, detected);
+    options = mergeWithDefaults(flags, detected);
+  } else {
+    options = await runInteractivePrompts(detected, archetypes, blueprints, themes);
   }
-  if (themes.length === 0) {
-    themes = [
-      { id: "luminarum", description: "Dark geometric canvas with vibrant accents" },
-      { id: "clean", description: "Professional, minimal, universal" },
-      { id: "glassmorphism", description: "Frosted glass aesthetic" }
-    ];
-  }
-  const themeOptions = themes.map((t) => `${t.id} ${dim(`\u2014 ${t.description || ""}`)}`);
-  const selectedTheme = await select("Choose a theme", themeOptions);
-  const themeId = selectedTheme.split(" ")[0];
-  const mode = await select("Mode", ["dark", "light"], 0);
-  const shape = await select("Shape", ["pill", "rounded", "sharp"], 0);
-  const target = await select("Target framework", ["react", "vue", "svelte", "html"], 0);
-  let pages = [];
-  try {
-    const res = await fetch(`https://decantr-registry.fly.dev/v1/archetypes/${archetypeId}`);
-    if (res.ok) {
-      const data = await res.json();
-      if (data.pages) pages = data.pages;
+  let blueprintData;
+  if (options.blueprint) {
+    const result2 = await registryClient.fetchBlueprint(options.blueprint);
+    if (result2) {
+      blueprintData = result2.data;
     }
-  } catch {
   }
-  const structure = pages.length > 0 ? pages.map((p) => ({
-    id: p.id,
-    shell: p.shell || "sidebar-main",
-    layout: p.default_layout || []
-  })) : [{ id: "home", shell: "full-bleed", layout: ["hero-split"] }];
-  let features = [];
-  try {
-    const res = await fetch(`https://decantr-registry.fly.dev/v1/archetypes/${archetypeId}`);
-    if (res.ok) {
-      const data = await res.json();
-      if (data.features) features = data.features;
-    }
-  } catch {
+  console.log(heading("Scaffolding project..."));
+  const result = scaffoldProject(
+    projectRoot,
+    options,
+    detected,
+    blueprintData,
+    registrySource
+  );
+  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`);
+  if (result.gitignoreUpdated) {
+    console.log(`  ${dim(".gitignore updated to exclude .decantr/cache/")}`);
   }
-  const essence = {
-    version: "2.0.0",
-    archetype: archetypeId,
-    theme: {
-      style: themeId,
-      mode,
-      recipe: themeId,
-      shape
-    },
-    personality: ["professional"],
-    platform: { type: "spa", routing: "hash" },
-    structure,
-    features,
-    guard: { enforce_style: true, enforce_recipe: true, mode: "strict" },
-    density: { level: "comfortable", content_gap: "_gap4" },
-    target
-  };
-  writeFileSync(essencePath, JSON.stringify(essence, null, 2) + "\n");
-  console.log(success(`
-Created decantr.essence.json`));
-  console.log(dim(`  Archetype: ${archetypeId}`));
-  console.log(dim(`  Theme: ${themeId} (${mode})`));
-  console.log(dim(`  Pages: ${structure.map((s) => s.id).join(", ")}`));
-  console.log(dim(`  Target: ${target}`));
+  const essenceContent = readFileSync4(result.essencePath, "utf-8");
+  const essence = JSON.parse(essenceContent);
   const validation = validateEssence(essence);
   if (validation.valid) {
-    console.log(success("  Validation: passed"));
+    console.log(success("\nValidation passed."));
   } else {
-    console.log(error(`  Validation: ${validation.errors.join(", ")}`));
+    console.log(error(`
+Validation warnings: ${validation.errors.join(", ")}`));
   }
   console.log(heading("Next steps"));
-  console.log(`  1. Open your AI assistant (Claude, Cursor, etc.)`);
-  console.log(`  2. Tell it to read ${cyan("decantr.essence.json")} before generating code`);
-  console.log(`  3. The essence file defines your theme, pages, and patterns`);
-  console.log(`  4. Run ${cyan("decantr validate")} after changes to check for drift
-`);
+  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("");
+  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");
+  console.log(heading("Decantr Project Status"));
+  if (!existsSync4(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 validation = validateEssence(essence);
+    console.log(`${BOLD2}Essence:${RESET2}`);
+    if (validation.valid) {
+      console.log(`  ${GREEN2}Valid${RESET2}`);
+    } else {
+      console.log(`  ${RED}Invalid: ${validation.errors.join(", ")}${RESET2}`);
+    }
+    console.log(`  Theme: ${essence.theme?.style || "unknown"} (${essence.theme?.mode || "unknown"})`);
+    console.log(`  Guard: ${essence.guard?.mode || "unknown"}`);
+    console.log(`  Pages: ${(essence.structure || []).length}`);
+  } catch (e) {
+    console.log(`  ${RED}Error reading essence: ${e.message}${RESET2}`);
+  }
+  console.log("");
+  console.log(`${BOLD2}Sync Status:${RESET2}`);
+  if (existsSync4(projectJsonPath)) {
+    try {
+      const projectJson = JSON.parse(readFileSync4(projectJsonPath, "utf-8"));
+      const syncStatus = projectJson.sync?.status || "unknown";
+      const lastSync = projectJson.sync?.lastSync || "never";
+      const source = projectJson.sync?.registrySource || "unknown";
+      const statusColor = syncStatus === "synced" ? GREEN2 : YELLOW2;
+      console.log(`  Status: ${statusColor}${syncStatus}${RESET2}`);
+      console.log(`  Last sync: ${dim(lastSync)}`);
+      console.log(`  Source: ${dim(source)}`);
+    } catch {
+      console.log(`  ${YELLOW2}Could not read project.json${RESET2}`);
+    }
+  } else {
+    console.log(`  ${YELLOW2}No .decantr/project.json found${RESET2}`);
+    console.log(dim('  Run "decantr init" to create project files.'));
+  }
+}
+async function cmdSync() {
+  const projectRoot = process.cwd();
+  const cacheDir = join4(projectRoot, ".decantr", "cache");
+  console.log(heading("Syncing registry content..."));
+  const result = await syncRegistry(cacheDir);
+  if (result.source === "api") {
+    console.log(success("Sync completed successfully."));
+    if (result.synced.length > 0) {
+      console.log(`  Synced: ${result.synced.join(", ")}`);
+    }
+    if (result.failed.length > 0) {
+      console.log(`  ${YELLOW2}Failed: ${result.failed.join(", ")}${RESET2}`);
+    }
+  } else {
+    console.log(`${YELLOW2}Could not sync: API unavailable${RESET2}`);
+    console.log(dim("Using bundled content."));
+  }
+}
+async function cmdAudit() {
+  const projectRoot = process.cwd();
+  const essencePath = join4(projectRoot, "decantr.essence.json");
+  console.log(heading("Auditing project..."));
+  if (!existsSync4(essencePath)) {
+    console.log(`${RED}No decantr.essence.json found.${RESET2}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const essence = JSON.parse(readFileSync4(essencePath, "utf-8"));
+    const validation = validateEssence(essence);
+    if (!validation.valid) {
+      console.log(`${RED}Essence validation failed:${RESET2}`);
+      for (const err of validation.errors) {
+        console.log(`  ${RED}${err}${RESET2}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    console.log(success("Essence is valid."));
+    const violations = evaluateGuard(essence, {});
+    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}`);
+      }
+    } else {
+      console.log(success("No guard violations."));
+    }
+    console.log("");
+    console.log(`${BOLD2}Summary:${RESET2}`);
+    console.log(`  Pages defined: ${essence.structure.length}`);
+    console.log(`  Guard mode: ${essence.guard.mode}`);
+    console.log(`  Theme: ${essence.theme.style}`);
+  } catch (e) {
+    console.log(`${RED}Error: ${e.message}${RESET2}`);
+    process.exitCode = 1;
+  }
 }
 function cmdHelp() {
   console.log(`
-${BOLD}decantr${RESET} \u2014 Design intelligence for AI-generated UI
+${BOLD2}decantr${RESET2} \u2014 Design intelligence for AI-generated UI
 
-${BOLD}Usage:${RESET}
-  decantr init
-  decantr search <query> [--type pattern|archetype|recipe|theme]
+${BOLD2}Usage:${RESET2}
+  decantr init [options]
+  decantr status
+  decantr sync
+  decantr audit
+  decantr search <query> [--type <type>]
   decantr get <type> <id>
   decantr list <type>
   decantr validate [path]
   decantr help
 
-${BOLD}Commands:${RESET}
-  ${cyan("init")}      Create a new decantr.essence.json \u2014 pick an archetype, theme, and target
-  ${cyan("search")}    Search the registry for patterns, archetypes, recipes, themes
-  ${cyan("get")}       Get full details of a registry item as JSON
-  ${cyan("list")}      List all items of a type (patterns, archetypes, recipes, themes, blueprints)
-  ${cyan("validate")}  Validate a decantr.essence.json file against the schema and guard rules
-  ${cyan("help")}      Show this help message
+${BOLD2}Init Options:${RESET2}
+  --blueprint, -b    Blueprint ID
+  --theme            Theme ID
+  --mode             Color mode: dark | light | auto
+  --shape            Border shape: pill | rounded | sharp
+  --target           Framework: react | vue | svelte | nextjs | html
+  --guard            Guard mode: creative | guided | strict
+  --density          Spacing: compact | comfortable | spacious
+  --shell            Default shell layout
+  --existing         Initialize in existing project
+  --offline          Force offline mode
+  --yes, -y          Accept defaults, skip confirmations
+  --registry         Custom registry URL
 
-${BOLD}Examples:${RESET}
+${BOLD2}Commands:${RESET2}
+  ${cyan("init")}      Initialize a new Decantr project with full scaffolding
+  ${cyan("status")}    Show project status and sync state
+  ${cyan("sync")}      Sync registry content from API
+  ${cyan("audit")}     Validate essence and check for drift
+  ${cyan("search")}    Search the registry
+  ${cyan("get")}       Get full details of a registry item
+  ${cyan("list")}      List items by type
+  ${cyan("validate")}  Validate essence file
+  ${cyan("help")}      Show this help
+
+${BOLD2}Examples:${RESET2}
   decantr init
+  decantr init --blueprint=saas-dashboard --theme=luminarum --yes
+  decantr status
+  decantr sync
+  decantr audit
   decantr search dashboard
-  decantr search kpi --type pattern
-  decantr get pattern kpi-grid
-  decantr get recipe luminarum
   decantr list patterns
-  decantr validate
 `);
 }
 async function main() {
@@ -333,7 +1253,41 @@ async function main() {
   }
   switch (command) {
     case "init": {
-      await cmdInit();
+      const initArgs = {};
+      for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--yes" || arg === "-y") {
+          initArgs.yes = true;
+        } else if (arg === "--offline") {
+          initArgs.offline = true;
+        } else if (arg === "--existing") {
+          initArgs.existing = true;
+        } else if (arg.startsWith("--")) {
+          const [key, value] = arg.slice(2).split("=");
+          if (value) {
+            initArgs[key] = value;
+          } else if (args[i + 1] && !args[i + 1].startsWith("-")) {
+            initArgs[key] = args[++i];
+          }
+        } else if (arg.startsWith("-")) {
+          const key = arg.slice(1);
+          if (key === "b" && args[i + 1]) initArgs.blueprint = args[++i];
+          if (key === "y") initArgs.yes = true;
+        }
+      }
+      await cmdInit(initArgs);
+      break;
+    }
+    case "status": {
+      await cmdStatus();
+      break;
+    }
+    case "sync": {
+      await cmdSync();
+      break;
+    }
+    case "audit": {
+      await cmdAudit();
       break;
     }
     case "search": {