@decantr/cli 1.3.0 → 1.4.0

package/dist/chunk-ZQ5FTYKG.js

@@ -0,0 +1,2019 @@
+// src/scaffold.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function composeArchetypes(composeEntries, archetypeResults) {
+  if (composeEntries.length === 0) {
+    return {
+      pages: [{ id: "home", layout: ["hero"] }],
+      features: [],
+      defaultShell: "sidebar-main"
+    };
+  }
+  const allPages = [];
+  const allFeatures = [];
+  let defaultShell = "sidebar-main";
+  for (let i = 0; i < composeEntries.length; i++) {
+    const entry = composeEntries[i];
+    const archetypeId = typeof entry === "string" ? entry : entry.archetype;
+    const data = archetypeResults.get(archetypeId);
+    if (!data?.pages) continue;
+    const isPrimary = i === 0;
+    if (isPrimary) {
+      defaultShell = data.pages[0]?.shell || defaultShell;
+      for (const page of data.pages) {
+        allPages.push({
+          id: page.id,
+          layout: page.default_layout?.length ? page.default_layout : ["hero"],
+          ...page.shell !== defaultShell ? { shell_override: page.shell } : {}
+        });
+      }
+    } else {
+      const prefix = typeof entry === "string" ? entry : entry.prefix;
+      for (const page of data.pages) {
+        allPages.push({
+          id: `${prefix}-${page.id}`,
+          layout: page.default_layout?.length ? page.default_layout : ["hero"],
+          ...page.shell !== defaultShell ? { shell_override: page.shell } : {}
+        });
+      }
+    }
+    if (data.features) {
+      allFeatures.push(...data.features);
+    }
+  }
+  if (allPages.length === 0) {
+    allPages.push({ id: "home", layout: ["hero"] });
+  }
+  return {
+    pages: allPages,
+    features: [...new Set(allFeatures)],
+    defaultShell
+  };
+}
+function composeSections(composeEntries, archetypeResults, overrides) {
+  if (composeEntries.length === 0) {
+    return {
+      sections: [{
+        id: "default",
+        role: "primary",
+        shell: "sidebar-main",
+        features: [],
+        description: "Default section",
+        pages: [{ id: "home", layout: ["hero"] }]
+      }],
+      features: [],
+      defaultShell: "sidebar-main"
+    };
+  }
+  const sections = [];
+  const allFeatures = [];
+  let defaultShell = "sidebar-main";
+  const pagesRemoveSet = new Set(overrides?.pages_remove ?? []);
+  for (let i = 0; i < composeEntries.length; i++) {
+    const entry = composeEntries[i];
+    const archetypeId = typeof entry === "string" ? entry : entry.archetype;
+    const data = archetypeResults.get(archetypeId);
+    if (!data?.pages) continue;
+    const isPrimary = i === 0;
+    if (isPrimary) {
+      defaultShell = data.pages[0]?.shell || defaultShell;
+    }
+    const pages = [];
+    for (const page of data.pages) {
+      if (pagesRemoveSet.has(page.id)) continue;
+      const overriddenPage = overrides?.pages?.[page.id];
+      pages.push({
+        id: page.id,
+        layout: page.default_layout?.length ? page.default_layout : ["hero"],
+        ...overriddenPage
+      });
+    }
+    sections.push({
+      id: archetypeId,
+      role: data.role ?? "primary",
+      shell: data.pages[0]?.shell || "sidebar-main",
+      features: data.features ?? [],
+      description: data.description ?? "",
+      pages
+    });
+    if (data.features) {
+      allFeatures.push(...data.features);
+    }
+  }
+  if (sections.length === 0) {
+    sections.push({
+      id: "default",
+      role: "primary",
+      shell: "sidebar-main",
+      features: [],
+      description: "Default section",
+      pages: [{ id: "home", layout: ["hero"] }]
+    });
+  }
+  if (overrides?.section_dna_overrides) {
+    for (const section of sections) {
+      const sectionOverrides = overrides.section_dna_overrides[section.id];
+      if (sectionOverrides) {
+        section.dna_overrides = { ...section.dna_overrides, ...sectionOverrides };
+      }
+    }
+  }
+  let features = [...new Set(allFeatures)];
+  if (overrides?.features_add) {
+    for (const f of overrides.features_add) {
+      if (!features.includes(f)) features.push(f);
+    }
+  }
+  if (overrides?.features_remove) {
+    const removeSet = new Set(overrides.features_remove);
+    features = features.filter((f) => !removeSet.has(f));
+  }
+  return { sections, features, defaultShell };
+}
+var ZONE_ORDER = ["public", "gateway", "primary", "auxiliary"];
+function deriveZones(inputs) {
+  const zoneMap = /* @__PURE__ */ new Map();
+  for (const input of inputs) {
+    const existing = zoneMap.get(input.role);
+    if (existing) {
+      existing.archetypes.push(input.archetypeId);
+      existing.features.push(...input.features);
+      existing.descriptions.push(input.description);
+    } else {
+      zoneMap.set(input.role, {
+        role: input.role,
+        archetypes: [input.archetypeId],
+        shell: input.shell,
+        features: [...input.features],
+        descriptions: [input.description]
+      });
+    }
+  }
+  for (const zone of zoneMap.values()) {
+    zone.features = [...new Set(zone.features)];
+  }
+  return ZONE_ORDER.filter((role) => zoneMap.has(role)).map((role) => zoneMap.get(role));
+}
+var GATEWAY_TRIGGER_MAP = {
+  auth: "authentication",
+  login: "authentication",
+  mfa: "authentication",
+  payment: "payment",
+  subscription: "payment",
+  checkout: "payment",
+  onboarding: "onboarding",
+  "setup-wizard": "onboarding",
+  welcome: "onboarding",
+  invite: "invitation",
+  "access-code": "invitation"
+};
+function resolveGatewayTrigger(features) {
+  for (const feature of features) {
+    const trigger = GATEWAY_TRIGGER_MAP[feature];
+    if (trigger) return trigger;
+  }
+  return "authentication";
+}
+function deriveTransitions(zones) {
+  const transitions = [];
+  const roles = new Set(zones.map((z) => z.role));
+  const gateway = zones.find((z) => z.role === "gateway");
+  const gatewayTrigger = gateway ? resolveGatewayTrigger(gateway.features) : "authentication";
+  const hasApp = roles.has("primary") || roles.has("auxiliary");
+  const hasGateway = roles.has("gateway");
+  const hasPublic = roles.has("public");
+  if (hasPublic && hasGateway) {
+    transitions.push({ from: "public", to: "gateway", type: "conversion", trigger: gatewayTrigger });
+  }
+  if (hasPublic && hasApp && !hasGateway) {
+    transitions.push({ from: "public", to: "app", type: "conversion", trigger: "navigation" });
+  }
+  if (hasGateway && hasApp) {
+    transitions.push({ from: "gateway", to: "app", type: "gate-pass", trigger: gatewayTrigger });
+    transitions.push({ from: "app", to: "gateway", type: "gate-return", trigger: gatewayTrigger });
+  }
+  if (hasApp && hasPublic) {
+    transitions.push({ from: "app", to: "public", type: "navigation", trigger: "external" });
+  }
+  return transitions;
+}
+var ZONE_LABELS = {
+  public: "Public",
+  gateway: "Gateway",
+  primary: "App",
+  auxiliary: "App (auxiliary)"
+};
+function generateTopologySection(data, personality) {
+  const lines = [];
+  lines.push("## Composition Topology");
+  lines.push("");
+  lines.push(`**Intent:** ${data.intent}`);
+  lines.push("");
+  lines.push("### Zones");
+  lines.push("");
+  for (const zone of data.zones) {
+    const label = ZONE_LABELS[zone.role] || zone.role;
+    lines.push(`**${label}** \u2014 ${zone.shell} shell`);
+    lines.push(`  Archetypes: ${zone.archetypes.join(", ")}`);
+    lines.push(`  Purpose: ${zone.descriptions.join(" ")}`);
+    if (personality.length > 0) {
+      lines.push(`  Tone: ${personality.join(", ")}`);
+    }
+    if (zone.features.length > 0) {
+      lines.push(`  Features: ${zone.features.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (data.transitions.length > 0) {
+    lines.push("### Zone Transitions");
+    lines.push("");
+    for (const t of data.transitions) {
+      const fromLabel = t.from.charAt(0).toUpperCase() + t.from.slice(1);
+      const toLabel = t.to.charAt(0).toUpperCase() + t.to.slice(1);
+      lines.push(`  ${fromLabel} \u2192 ${toLabel}: ${t.type} (${t.trigger})`);
+    }
+    lines.push("");
+  }
+  lines.push("### Default Entry Points");
+  lines.push("");
+  lines.push(`  Anonymous users enter: ${data.entryPoints.anonymous}`);
+  lines.push(`  Authenticated users enter: ${data.entryPoints.authenticated}`);
+  lines.push(`  Auth redirect target: ${data.entryPoints.authenticated}`);
+  lines.push("");
+  return lines.join("\n");
+}
+var CLI_VERSION = "1.0.0";
+function generateTokensCSS(themeData, mode) {
+  if (!themeData) {
+    return `/* No theme data available */
+:root {
+  --d-primary: #6366f1;
+  --d-secondary: #a1a1aa;
+  --d-accent: #f59e0b;
+  --d-bg: #18181b;
+  --d-surface: #1f1f23;
+  --d-surface-raised: #27272a;
+  --d-border: #3f3f46;
+  --d-text: #fafafa;
+  --d-text-muted: #a1a1aa;
+}
+`;
+  }
+  const seed = themeData.seed || {};
+  const palette = themeData.palette || {};
+  const resolvedMode = mode === "auto" ? "dark" : mode;
+  function buildTokens(tokenMode) {
+    return {
+      // Seed colors
+      "--d-primary": seed.primary || "#6366f1",
+      "--d-secondary": seed.secondary || "#a1a1aa",
+      "--d-accent": seed.accent || "#f59e0b",
+      // Palette colors (mode-aware)
+      "--d-bg": palette.background?.[tokenMode] || "#18181b",
+      "--d-surface": palette.surface?.[tokenMode] || "#1f1f23",
+      "--d-surface-raised": palette["surface-raised"]?.[tokenMode] || "#27272a",
+      "--d-border": palette.border?.[tokenMode] || "#3f3f46",
+      "--d-text": palette.text?.[tokenMode] || "#fafafa",
+      "--d-text-muted": palette["text-muted"]?.[tokenMode] || "#a1a1aa",
+      "--d-primary-hover": palette["primary-hover"]?.[tokenMode] || seed.primary || "#6366f1",
+      // Spacing scale
+      "--d-gap-1": "0.25rem",
+      "--d-gap-2": "0.5rem",
+      "--d-gap-3": "0.75rem",
+      "--d-gap-4": "1rem",
+      "--d-gap-6": "1.5rem",
+      "--d-gap-8": "2rem",
+      "--d-gap-12": "3rem",
+      // Radii
+      "--d-radius": "0.5rem",
+      "--d-radius-sm": "0.25rem",
+      "--d-radius-lg": "0.75rem",
+      "--d-radius-xl": "1rem",
+      "--d-radius-full": "9999px",
+      // Shadows
+      "--d-shadow-sm": "0 1px 2px rgba(0,0,0,0.05)",
+      "--d-shadow": "0 1px 3px rgba(0,0,0,0.1)",
+      "--d-shadow-md": "0 4px 6px rgba(0,0,0,0.1)",
+      "--d-shadow-lg": "0 10px 15px rgba(0,0,0,0.1)",
+      // Status colors
+      "--d-success": themeData.tokens?.base?.success || "#22c55e",
+      "--d-error": themeData.tokens?.base?.danger || "#ef4444",
+      "--d-warning": themeData.tokens?.base?.warning || "#f59e0b",
+      "--d-info": "#3b82f6"
+    };
+  }
+  const tokens = buildTokens(resolvedMode);
+  const lines = Object.entries(tokens).map(([key, value]) => `  ${key}: ${value};`).join("\n");
+  let css = `/* Generated by @decantr/cli */
+:root {
+${lines}
+}
+`;
+  if (mode === "auto") {
+    const lightTokens = buildTokens("light");
+    const paletteKeys = ["--d-bg", "--d-surface", "--d-surface-raised", "--d-border", "--d-text", "--d-text-muted", "--d-primary-hover"];
+    const lightLines = Object.entries(lightTokens).filter(([key]) => paletteKeys.includes(key)).map(([key, value]) => `    ${key}: ${value};`).join("\n");
+    css += `
+@media (prefers-color-scheme: light) {
+  :root {
+${lightLines}
+  }
+}
+`;
+  }
+  return css;
+}
+function generateDecoratorsCSS(recipeData, themeName) {
+  if (!recipeData?.decorators) {
+    return `/* No recipe decorators available */`;
+  }
+  const decorators = recipeData.decorators;
+  const css = [
+    `/* Generated by @decantr/cli from recipe: ${themeName} */`,
+    ""
+  ];
+  for (const [name, description] of Object.entries(decorators)) {
+    css.push(generateDecoratorRule(name, description));
+    css.push("");
+  }
+  css.push(`/* Animation keyframes */
+@keyframes decantr-fade-in {
+  from { opacity: 0; transform: translateY(8px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes decantr-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.5; }
+}
+`);
+  return css.join("\n");
+}
+function generateDecoratorRule(name, description) {
+  const rules = [];
+  const descLower = description.toLowerCase();
+  if (descLower.includes("surface background") || descLower.includes("surface elevation")) {
+    rules.push("background: var(--d-surface)");
+  } else if (descLower.includes("background") && descLower.includes("theme")) {
+    rules.push("background: var(--d-bg)");
+  } else if (descLower.includes("primary-tinted") || descLower.includes("primary background")) {
+    rules.push("background: color-mix(in srgb, var(--d-primary) 15%, var(--d-surface))");
+  }
+  if (descLower.includes("1px border") || descLower.includes("subtle border")) {
+    rules.push("border: 1px solid var(--d-border)");
+  } else if (descLower.includes("border") && !descLower.includes("radius")) {
+    rules.push("border: 1px solid var(--d-border)");
+  }
+  const radiusMatch = descLower.match(/(\d+)px radius/);
+  if (radiusMatch) {
+    rules.push(`border-radius: ${radiusMatch[1]}px`);
+  } else if (descLower.includes("radius") || descLower.includes("rounded")) {
+    rules.push("border-radius: var(--d-radius)");
+  }
+  if (descLower.includes("hover shadow") || descLower.includes("shadow transition")) {
+    rules.push("transition: box-shadow 0.15s ease");
+  }
+  if (descLower.includes("elevation") || descLower.includes("shadow")) {
+    rules.push("box-shadow: var(--d-shadow)");
+  }
+  if (descLower.includes("entrance animation") || descLower.includes("fade")) {
+    rules.push("animation: decantr-fade-in 0.2s ease-out");
+  }
+  if (descLower.includes("pulse animation") || descLower.includes("skeleton")) {
+    rules.push("animation: decantr-pulse 1.5s ease-in-out infinite");
+  }
+  if (descLower.includes("blur") || descLower.includes("glass")) {
+    rules.push("backdrop-filter: blur(8px)");
+  }
+  if (descLower.includes("right-aligned")) {
+    rules.push("margin-left: auto");
+  } else if (descLower.includes("left-aligned")) {
+    rules.push("margin-right: auto");
+  }
+  if (descLower.includes("message bubble") || descLower.includes("bubble")) {
+    rules.push("padding: var(--d-gap-3) var(--d-gap-4)");
+    rules.push("border-radius: var(--d-radius-lg)");
+    rules.push("max-width: 80%");
+  }
+  if (rules.length === 0) {
+    return `/* .${name}: ${description} */`;
+  }
+  return `.${name} {
+  ${rules.join(";\n  ")};
+}`;
+}
+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 = join(__dirname, "..", "src", "templates", name);
+  if (existsSync(fromDist)) {
+    return readFileSync(fromDist, "utf-8");
+  }
+  const fromSrc = join(__dirname, "templates", name);
+  if (existsSync(fromSrc)) {
+    return readFileSync(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 resolvePatternAlias(item, patterns) {
+  if (!patterns) return item;
+  if (typeof item === "string") {
+    const patternDef = patterns.find((p) => p.as === item);
+    if (patternDef) {
+      if (patternDef.preset) {
+        return { pattern: patternDef.pattern, preset: patternDef.preset };
+      }
+      return patternDef.pattern;
+    }
+    return item;
+  }
+  if (typeof item === "object" && item !== null) {
+    const obj = item;
+    if (Array.isArray(obj.cols)) {
+      return {
+        ...obj,
+        cols: obj.cols.map((col) => resolvePatternAlias(col, patterns))
+      };
+    }
+  }
+  return item;
+}
+function buildEssence(options, archetypeData) {
+  let structure = [
+    { id: "home", shell: options.shell, layout: ["hero"] }
+  ];
+  let features = options.features;
+  if (archetypeData?.pages) {
+    structure = archetypeData.pages.map((p) => {
+      const resolvedLayout = (p.default_layout?.length ? p.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, p.patterns));
+      return {
+        id: p.id,
+        shell: p.shell || options.shell,
+        layout: resolvedLayout
+      };
+    });
+  }
+  if (archetypeData?.features) {
+    features = [.../* @__PURE__ */ new Set([...features, ...archetypeData.features])];
+  }
+  const contentGapMap = {
+    compact: "_gap2",
+    comfortable: "_gap4",
+    spacious: "_gap6"
+  };
+  const archetype = options.archetype || "custom";
+  const essence = {
+    version: "2.0.0",
+    archetype,
+    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
+  };
+  if (options.accessibility) {
+    essence.accessibility = options.accessibility;
+  }
+  return essence;
+}
+function buildEssenceV3(options, archetypeData, themeHints, recipeHints) {
+  let pages = [
+    { id: "home", layout: ["hero"] }
+  ];
+  let features = options.features;
+  let defaultShell = options.shell || "sidebar-main";
+  if (archetypeData?.pages) {
+    defaultShell = archetypeData.pages[0]?.shell || defaultShell;
+    pages = archetypeData.pages.map((p) => {
+      const resolvedLayout = (p.default_layout?.length ? p.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, p.patterns));
+      return {
+        id: p.id,
+        ...p.shell !== defaultShell ? { shell_override: p.shell } : {},
+        layout: resolvedLayout
+      };
+    });
+  }
+  if (archetypeData?.features) {
+    features = [.../* @__PURE__ */ new Set([...features, ...archetypeData.features])];
+  }
+  const densityLevelMap = {
+    compact: "_gap2",
+    comfortable: "_gap4",
+    spacious: "_gap6"
+  };
+  const shapeRadiusMap = {
+    pill: 12,
+    rounded: 8,
+    sharp: 2
+  };
+  const guardModeMap = {
+    strict: { mode: "strict", dna_enforcement: "error", blueprint_enforcement: "warn" },
+    guided: { mode: "guided", dna_enforcement: "error", blueprint_enforcement: "off" },
+    creative: { mode: "creative", dna_enforcement: "off", blueprint_enforcement: "off" }
+  };
+  const dna = {
+    theme: {
+      style: options.theme,
+      mode: options.mode,
+      recipe: options.theme,
+      shape: options.shape
+    },
+    spacing: {
+      base_unit: 4,
+      scale: "linear",
+      density: options.density,
+      content_gap: densityLevelMap[options.density] || "_gap4"
+    },
+    typography: {
+      scale: themeHints?.typography_hints?.scale || "modular",
+      heading_weight: themeHints?.typography_hints?.heading_weight || 600,
+      body_weight: themeHints?.typography_hints?.body_weight || 400
+    },
+    color: {
+      palette: "semantic",
+      accent_count: 1,
+      cvd_preference: options.accessibility?.cvd_preference || "auto"
+    },
+    radius: {
+      philosophy: recipeHints?.radius_hints?.philosophy || options.shape,
+      base: recipeHints?.radius_hints?.base || shapeRadiusMap[options.shape] || 8
+    },
+    elevation: {
+      system: "layered",
+      max_levels: 3
+    },
+    motion: {
+      preference: recipeHints?.animation?.preference || themeHints?.motion_hints?.preference || "subtle",
+      duration_scale: 1,
+      reduce_motion: themeHints?.motion_hints?.reduce_motion_default ?? true
+    },
+    accessibility: {
+      wcag_level: options.accessibility?.wcag_level || "AA",
+      focus_visible: true,
+      skip_nav: true
+    },
+    personality: options.personality
+  };
+  const blueprint = {
+    shell: defaultShell,
+    pages,
+    features
+  };
+  const meta = {
+    archetype: options.archetype || "custom",
+    target: options.target,
+    platform: {
+      type: "spa",
+      routing: "hash"
+    },
+    guard: guardModeMap[options.guard] || guardModeMap.guided
+  };
+  return {
+    version: "3.0.0",
+    dna,
+    blueprint,
+    meta
+  };
+}
+var CSS_APPROACH_CONTENT = `## CSS Implementation
+
+This project uses **@decantr/css** for layout atoms and the generated CSS files for theme tokens and recipe decorators.
+
+### Setup
+
+\`\`\`javascript
+// 1. Import the atoms runtime
+import { css } from '@decantr/css';
+
+// 2. Import generated CSS files (created by decantr init)
+import './styles/tokens.css';      // Theme tokens (--d-primary, --d-surface, etc.)
+import './styles/decorators.css';  // Recipe decorators
+\`\`\`
+
+### Using Atoms
+
+The \`css()\` function processes atom strings and injects CSS at runtime:
+
+\`\`\`jsx
+// Layout atoms
+<div className={css('_flex _col _gap4 _p4')}>
+  <h1 className={css('_heading1')}>Title</h1>
+  <p className={css('_textsm _fgmuted')}>Description</p>
+</div>
+
+// Responsive prefixes (mobile-first)
+<div className={css('_gc1 _sm:gc2 _lg:gc4')}>
+  {/* 1 col -> 2 cols at 640px -> 4 cols at 1024px */}
+</div>
+\`\`\`
+
+### Atom Reference
+
+#### Display
+| Atom | CSS |
+|------|-----|
+| \`_flex\` | \`display:flex\` |
+| \`_grid\` | \`display:grid\` |
+| \`_block\` | \`display:block\` |
+| \`_inline\` | \`display:inline\` |
+| \`_inlineflex\` | \`display:inline-flex\` |
+| \`_none\` | \`display:none\` |
+| \`_contents\` | \`display:contents\` |
+
+#### Flexbox
+| Atom | CSS |
+|------|-----|
+| \`_col\` | \`flex-direction:column\` |
+| \`_row\` | \`flex-direction:row\` |
+| \`_colrev\` | \`flex-direction:column-reverse\` |
+| \`_wrap\` | \`flex-wrap:wrap\` |
+| \`_nowrap\` | \`flex-wrap:nowrap\` |
+| \`_flex1\` | \`flex:1\` |
+| \`_flex0\` | \`flex:none\` |
+| \`_flexauto\` | \`flex:auto\` |
+| \`_grow\` | \`flex-grow:1\` |
+| \`_grow0\` | \`flex-grow:0\` |
+| \`_shrink0\` | \`flex-shrink:0\` |
+
+#### Alignment
+| Atom | CSS |
+|------|-----|
+| \`_aic\` | \`align-items:center\` |
+| \`_aifs\` | \`align-items:flex-start\` |
+| \`_aife\` | \`align-items:flex-end\` |
+| \`_aist\` | \`align-items:stretch\` |
+| \`_aibl\` | \`align-items:baseline\` |
+| \`_jcc\` | \`justify-content:center\` |
+| \`_jcfs\` | \`justify-content:flex-start\` |
+| \`_jcfe\` | \`justify-content:flex-end\` |
+| \`_jcsb\` | \`justify-content:space-between\` |
+| \`_jcsa\` | \`justify-content:space-around\` |
+| \`_jcse\` | \`justify-content:space-evenly\` |
+| \`_pic\` | \`place-items:center\` |
+| \`_pcc\` | \`place-content:center\` |
+
+#### Spacing (scale: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, ...)
+| Atom | CSS | Notes |
+|------|-----|-------|
+| \`_gap{n}\` | \`gap:{scale}\` | e.g. \`_gap4\` = \`gap:1rem\` |
+| \`_gx{n}\` | \`column-gap:{scale}\` | horizontal gap |
+| \`_gy{n}\` | \`row-gap:{scale}\` | vertical gap |
+| \`_p{n}\` | \`padding:{scale}\` | all sides |
+| \`_pt{n}\`, \`_pr{n}\`, \`_pb{n}\`, \`_pl{n}\` | directional padding | top/right/bottom/left |
+| \`_px{n}\` | \`padding-inline:{scale}\` | horizontal |
+| \`_py{n}\` | \`padding-block:{scale}\` | vertical |
+| \`_m{n}\` | \`margin:{scale}\` | same as padding variants |
+| \`_mx{n}\`, \`_my{n}\` | inline/block margin | horizontal/vertical |
+
+#### Sizing
+| Atom | CSS |
+|------|-----|
+| \`_wfull\` / \`_w100\` | \`width:100%\` |
+| \`_hfull\` / \`_h100\` | \`height:100%\` |
+| \`_wscreen\` | \`width:100vw\` |
+| \`_hscreen\` | \`height:100vh\` |
+| \`_wfit\` | \`width:fit-content\` |
+| \`_hfit\` | \`height:fit-content\` |
+| \`_wauto\` | \`width:auto\` |
+| \`_minw0\` | \`min-width:0\` |
+| \`_minh0\` | \`min-height:0\` |
+| \`_w{n}\`, \`_h{n}\` | width/height from spacing scale |
+| \`_minw{n}\`, \`_maxw{n}\` | min/max width from scale |
+
+#### Text Size
+| Atom | Size | Line-height |
+|------|------|-------------|
+| \`_textxs\` | 0.75rem | 1rem |
+| \`_textsm\` | 0.875rem | 1.25rem |
+| \`_textbase\` | 1rem | 1.5rem |
+| \`_textlg\` | 1.125rem | 1.75rem |
+| \`_textxl\` | 1.25rem | 1.75rem |
+| \`_text2xl\` | 1.5rem | 2rem |
+| \`_text3xl\` | 1.875rem | 2.25rem |
+| \`_heading1\`-\`_heading6\` | Heading presets (size + weight) |
+
+#### Text Style
+| Atom | CSS |
+|------|-----|
+| \`_fontbold\` | \`font-weight:700\` |
+| \`_fontsemi\` | \`font-weight:600\` |
+| \`_fontmedium\` | \`font-weight:500\` |
+| \`_fontlight\` | \`font-weight:300\` |
+| \`_italic\` | \`font-style:italic\` |
+| \`_underline\` | \`text-decoration:underline\` |
+| \`_uppercase\` | \`text-transform:uppercase\` |
+| \`_truncate\` | overflow ellipsis + nowrap |
+| \`_textl\`, \`_textc\`, \`_textr\` | text-align left/center/right |
+
+#### Color (theme variable based)
+| Atom | CSS |
+|------|-----|
+| \`_bgprimary\` | \`background:var(--d-primary)\` |
+| \`_bgsurface\` | \`background:var(--d-surface)\` |
+| \`_bgsurface0\`-\`_bgsurface2\` | surface elevation layers |
+| \`_bgmuted\` | \`background:var(--d-muted)\` |
+| \`_bgbg\` | \`background:var(--d-bg)\` |
+| \`_bgsuccess\`, \`_bgerror\`, \`_bgwarning\`, \`_bginfo\` | status backgrounds |
+| \`_fgprimary\` | \`color:var(--d-primary)\` |
+| \`_fgtext\` | \`color:var(--d-text)\` |
+| \`_fgmuted\` | \`color:var(--d-text-muted)\` |
+| \`_fgsuccess\`, \`_fgerror\`, \`_fgwarning\`, \`_fginfo\` | status text |
+| \`_bcborder\` | \`border-color:var(--d-border)\` |
+
+#### Overflow & Whitespace
+| Atom | CSS |
+|------|-----|
+| \`_overhidden\` | \`overflow:hidden\` |
+| \`_overauto\` | \`overflow:auto\` |
+| \`_overscroll\` | \`overflow:scroll\` |
+| \`_overxauto\`, \`_overyauto\` | axis-specific overflow |
+| \`_nowraptext\` | \`white-space:nowrap\` |
+| \`_prewrap\` | \`white-space:pre-wrap\` |
+| \`_breakword\` | \`overflow-wrap:break-word\` |
+
+#### Cursor & Interaction
+| Atom | CSS |
+|------|-----|
+| \`_pointer\` | \`cursor:pointer\` |
+| \`_cursordefault\` | \`cursor:default\` |
+| \`_notallowed\` | \`cursor:not-allowed\` |
+| \`_grab\` | \`cursor:grab\` |
+| \`_selectnone\` | \`user-select:none\` |
+| \`_ptrnone\` | \`pointer-events:none\` |
+
+#### Position & Layout
+| Atom | CSS |
+|------|-----|
+| \`_rel\` | \`position:relative\` |
+| \`_abs\` | \`position:absolute\` |
+| \`_fixed\` | \`position:fixed\` |
+| \`_sticky\` | \`position:sticky\` |
+| \`_inset0\` | \`inset:0\` |
+| \`_top0\`, \`_right0\`, \`_bottom0\`, \`_left0\` | edge positioning |
+| \`_z10\`-\`_z50\` | z-index scale |
+
+#### Grid
+| Atom | CSS |
+|------|-----|
+| \`_gc1\`-\`_gc12\` | \`grid-template-columns:repeat(N,...)\` |
+| \`_gr1\`-\`_gr6\` | \`grid-template-rows:repeat(N,...)\` |
+| \`_span1\`-\`_span12\`, \`_spanfull\` | column span |
+| \`_rowspan1\`-\`_rowspan6\` | row span |
+
+#### Visual
+| Atom | CSS |
+|------|-----|
+| \`_rounded\` | \`border-radius:var(--d-radius)\` |
+| \`_roundedfull\` | \`border-radius:9999px\` |
+| \`_roundedsm\`, \`_roundedlg\`, \`_roundedxl\` | radius variants |
+| \`_shadow\`, \`_shadowmd\`, \`_shadowlg\` | box-shadow presets |
+| \`_bordernone\` | \`border:none\` |
+| \`_bw{n}\` | \`border-width:{n}px\` |
+| \`_op0\`-\`_op100\` | opacity (0, 25, 50, 75, 100) |
+| \`_trans\` | \`transition:all 0.15s ease\` |
+| \`_visible\`, \`_invisible\` | visibility |
+
+### CSS Architecture
+
+The CSS is organized into two parts:
+
+1. **Atoms (@decantr/css)** - Layout utilities injected at runtime into \`@layer d.atoms\`
+2. **Generated CSS files** - Theme tokens and recipe decorators created during scaffold
+
+\`\`\`
+src/styles/
+  tokens.css      # :root { --d-primary: #...; --d-surface: #...; }
+  decorators.css  # .recipe-card { ... }
+\`\`\`
+
+### Variable Naming Convention
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| \`--d-\` | Core Decantr tokens | \`--d-primary\`, \`--d-bg\` |
+| \`--d-gap-{n}\` | Spacing tokens | \`--d-gap-4\`, \`--d-gap-8\` |
+| \`--d-radius\` | Border radius | \`--d-radius\`, \`--d-radius-lg\` |`;
+function generateDecantrMdV31(guardMode, cssApproach) {
+  const template = loadTemplate("DECANTR.md.template");
+  return renderTemplate(template, {
+    GUARD_MODE: guardMode,
+    CSS_APPROACH: cssApproach
+  });
+}
+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.map(serializeLayoutItem).join(", ") || "none";
+  const scaffoldStructure = essence.structure.map((p) => {
+    const patterns = p.layout.length > 0 ? `
+  - Patterns: ${p.layout.map(serializeLayoutItem).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.map(serializeLayoutItem).join(", ") || "none"} |`).join("\n")}`;
+  const featuresList = essence.features.length > 0 ? essence.features.map((f) => `- ${f}`).join("\n") : "- No features specified";
+  const dnaEnforcement = essence.guard.enforce_style ? "error" : "off";
+  const blueprintEnforcement = essence.guard.enforce_recipe ? "warn" : "off";
+  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),
+    DNA_ENFORCEMENT: dnaEnforcement,
+    BLUEPRINT_ENFORCEMENT: blueprintEnforcement,
+    DENSITY: essence.density.level,
+    CONTENT_GAP: essence.density.content_gap,
+    LAST_UPDATED: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return renderTemplate(template, vars);
+}
+function generateEssenceSummaryV3(essence) {
+  const template = loadTemplate("essence-summary.md.template");
+  const blueprint = essence.blueprint;
+  const sections = blueprint.sections || [];
+  const flatPages = blueprint.pages || [];
+  let pagesTable;
+  if (sections.length > 0) {
+    const rows = sections.flatMap(
+      (s) => s.pages.map((p) => `| ${p.id} | ${s.shell} | ${p.layout.map(serializeLayoutItem).join(", ") || "none"} |`)
+    );
+    pagesTable = `| Page | Shell | Layout |
+|------|-------|--------|
+${rows.join("\n")}`;
+  } else {
+    const shell = blueprint.shell ?? "sidebar-main";
+    const rows = flatPages.map((p) => `| ${p.id} | ${shell} | ${p.layout.map(serializeLayoutItem).join(", ") || "none"} |`);
+    pagesTable = `| Page | Shell | Layout |
+|------|-------|--------|
+${rows.join("\n")}`;
+  }
+  const features = blueprint.features || [];
+  const featuresList = features.length > 0 ? features.map((f) => `- ${f}`).join("\n") : "- No features specified";
+  const vars = {
+    ARCHETYPE: essence.meta.archetype || "custom",
+    BLUEPRINT: "",
+    PERSONALITY: (essence.dna.personality || []).join(", "),
+    TARGET: essence.meta.target ?? "",
+    THEME_STYLE: essence.dna.theme.style,
+    THEME_MODE: essence.dna.theme.mode,
+    THEME_RECIPE: essence.dna.theme.recipe ?? "",
+    SHAPE: essence.dna.theme.shape ?? "",
+    PAGES_TABLE: pagesTable,
+    FEATURES_LIST: featuresList,
+    GUARD_MODE: essence.meta.guard.mode,
+    ENFORCE_STYLE: essence.meta.guard.dna_enforcement || "error",
+    ENFORCE_RECIPE: essence.meta.guard.blueprint_enforcement || "warn",
+    DNA_ENFORCEMENT: essence.meta.guard.dna_enforcement || "error",
+    BLUEPRINT_ENFORCEMENT: essence.meta.guard.blueprint_enforcement || "warn",
+    DENSITY: essence.dna.spacing?.density || "comfortable",
+    CONTENT_GAP: essence.dna.spacing?.content_gap || "_gap4",
+    LAST_UPDATED: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return renderTemplate(template, vars);
+}
+function updateGitignore(projectRoot) {
+  const gitignorePath = join(projectRoot, ".gitignore");
+  const cacheEntry = ".decantr/cache/";
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    if (!content.includes(cacheEntry)) {
+      appendFileSync(gitignorePath, `
+# Decantr cache
+${cacheEntry}
+`);
+      return true;
+    }
+    return false;
+  } else {
+    writeFileSync(gitignorePath, `# Decantr cache
+${cacheEntry}
+`);
+    return true;
+  }
+}
+async function scaffoldProject(projectRoot, options, detected, registry, archetypeData, registrySource = "cache", themeData, recipeData, topologyMarkdown, composedSections, routeMap, patternSpecs, blueprintData) {
+  const essenceV3 = buildEssenceV3(options, archetypeData, themeData, recipeData);
+  const essence = buildEssence(options, archetypeData);
+  const decantrDir = join(projectRoot, ".decantr");
+  const contextDir = join(decantrDir, "context");
+  const cacheDir = join(decantrDir, "cache");
+  mkdirSync(contextDir, { recursive: true });
+  mkdirSync(cacheDir, { recursive: true });
+  const essencePath = join(projectRoot, "decantr.essence.json");
+  writeFileSync(essencePath, JSON.stringify(essenceV3, null, 2) + "\n");
+  const projectJsonPath = join(decantrDir, "project.json");
+  writeFileSync(projectJsonPath, generateProjectJson(detected, options, registrySource));
+  const contextFiles = [];
+  const scaffoldPath = join(contextDir, "task-scaffold.md");
+  writeFileSync(scaffoldPath, generateTaskContext("task-scaffold.md.template", essence));
+  contextFiles.push(scaffoldPath);
+  const addPagePath = join(contextDir, "task-add-page.md");
+  writeFileSync(addPagePath, generateTaskContext("task-add-page.md.template", essence));
+  contextFiles.push(addPagePath);
+  const modifyPath = join(contextDir, "task-modify.md");
+  writeFileSync(modifyPath, generateTaskContext("task-modify.md.template", essence));
+  contextFiles.push(modifyPath);
+  const summaryPath = join(contextDir, "essence-summary.md");
+  writeFileSync(summaryPath, generateEssenceSummary(essence));
+  contextFiles.push(summaryPath);
+  if (composedSections) {
+    essenceV3.version = "3.1.0";
+    essenceV3.blueprint = {
+      sections: composedSections.sections,
+      features: composedSections.features,
+      routes: routeMap || {}
+    };
+    if (blueprintData?.personality?.length) {
+      essenceV3.dna.personality = blueprintData.personality;
+    }
+    if (blueprintData?.design_constraints) {
+      essenceV3.dna.constraints = blueprintData.design_constraints;
+    }
+    if (blueprintData?.seo_hints) {
+      essenceV3.meta.seo = blueprintData.seo_hints;
+    }
+    if (blueprintData?.navigation) {
+      essenceV3.meta.navigation = blueprintData.navigation;
+    }
+    writeFileSync(essencePath, JSON.stringify(essenceV3, null, 2) + "\n");
+  }
+  const refreshResult = await refreshDerivedFiles(projectRoot, essenceV3, registry);
+  contextFiles.push(...refreshResult.contextFiles);
+  const gitignoreUpdated = updateGitignore(projectRoot);
+  return {
+    essencePath,
+    decantrMdPath: refreshResult.decantrMdPath,
+    projectJsonPath,
+    contextFiles,
+    cssFiles: refreshResult.cssFiles,
+    gitignoreUpdated
+  };
+}
+function scaffoldMinimal(projectRoot) {
+  const decantrDir = join(projectRoot, ".decantr");
+  const customDir = join(decantrDir, "custom");
+  const contentTypes = ["patterns", "recipes", "themes", "blueprints", "archetypes", "shells"];
+  for (const type of contentTypes) {
+    mkdirSync(join(customDir, type), { recursive: true });
+  }
+  const essence = {
+    version: "3.0.0",
+    dna: {
+      theme: {
+        style: "default",
+        mode: "dark",
+        recipe: "default",
+        shape: "rounded"
+      },
+      spacing: {
+        base_unit: 4,
+        scale: "linear",
+        density: "comfortable",
+        content_gap: "_gap4"
+      },
+      typography: {
+        scale: "modular",
+        heading_weight: 600,
+        body_weight: 400
+      },
+      color: {
+        palette: "semantic",
+        accent_count: 1,
+        cvd_preference: "auto"
+      },
+      radius: {
+        philosophy: "rounded",
+        base: 8
+      },
+      elevation: {
+        system: "layered",
+        max_levels: 3
+      },
+      motion: {
+        preference: "subtle",
+        duration_scale: 1,
+        reduce_motion: true
+      },
+      accessibility: {
+        wcag_level: "AA",
+        focus_visible: true,
+        skip_nav: true
+      },
+      personality: ["clean", "modern"]
+    },
+    blueprint: {
+      shell: "sidebar-main",
+      pages: [
+        { id: "home", layout: ["hero"] }
+      ],
+      features: []
+    },
+    meta: {
+      archetype: "custom",
+      target: "react",
+      platform: {
+        type: "spa",
+        routing: "hash"
+      },
+      guard: {
+        mode: "guided",
+        dna_enforcement: "error",
+        blueprint_enforcement: "off"
+      }
+    }
+  };
+  const essencePath = join(projectRoot, "decantr.essence.json");
+  writeFileSync(essencePath, JSON.stringify(essence, null, 2) + "\n");
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const projectJson = {
+    detected: {
+      framework: "unknown",
+      version: null,
+      packageManager: "npm",
+      hasTypeScript: false,
+      hasTailwind: false,
+      existingRuleFiles: []
+    },
+    overrides: {
+      framework: null
+    },
+    sync: {
+      status: "needs-sync",
+      lastSync: now,
+      registrySource: "cache",
+      cachedContent: {
+        archetypes: [],
+        patterns: [],
+        themes: [],
+        recipes: []
+      }
+    },
+    initialized: {
+      at: now,
+      via: "cli",
+      version: CLI_VERSION,
+      flags: "--offline --minimal"
+    }
+  };
+  const projectJsonPath = join(decantrDir, "project.json");
+  writeFileSync(projectJsonPath, JSON.stringify(projectJson, null, 2));
+  const decantrMdPath = join(projectRoot, "DECANTR.md");
+  const decantrMdContent = `# DECANTR.md
+
+> This file was generated by \`decantr init\` in offline/minimal mode.
+> Run \`decantr upgrade\` when online to pull full registry content.
+
+## Two-Layer Model
+
+This project uses the v3 Essence format with two layers:
+
+### DNA (Immutable Design Axioms)
+DNA defines the foundational design rules that must never be violated. DNA violations are **errors**.
+
+- **Theme:** default (dark mode)
+- **Spacing:** comfortable density, _gap4
+- **Radius:** rounded (8px base)
+- **Accessibility:** WCAG AA
+- **Personality:** clean, modern
+
+### Blueprint (Structural Layout)
+Blueprint defines pages, shells, and patterns. Blueprint deviations are **warnings**.
+
+| Page | Shell | Layout |
+|------|-------|--------|
+| home | sidebar-main | hero |
+
+## Guard Mode: guided
+
+- **DNA enforcement:** error (violations block generation)
+- **Blueprint enforcement:** off (deviations are advisory)
+
+## MCP Tools
+
+When available, use these tools:
+- \`decantr_read_essence\` \u2014 Read the current essence
+- \`decantr_check_drift\` \u2014 Check for guard violations
+- \`decantr_accept_drift\` \u2014 Accept a detected drift as intentional
+- \`decantr_update_essence\` \u2014 Update the essence spec
+
+## Quick Start
+
+1. Edit \`decantr.essence.json\` to define your project structure.
+2. Run \`decantr sync\` when online to fetch registry content.
+3. Use \`decantr create <type> <name>\` to create custom content.
+4. Use \`decantr validate\` to check your essence file.
+
+## Commands
+
+- \`decantr init\` \u2014 Initialize a new Decantr project
+- \`decantr status\` \u2014 Project health and DNA/Blueprint overview
+- \`decantr sync\` \u2014 Sync registry content
+- \`decantr audit\` \u2014 Audit project for issues
+- \`decantr migrate\` \u2014 Migrate v2 essence to v3
+- \`decantr check\` \u2014 Detect drift issues
+- \`decantr sync-drift\` \u2014 Review and resolve drift entries
+- \`decantr validate\` \u2014 Validate essence file
+- \`decantr search\` \u2014 Search the registry
+- \`decantr suggest\` \u2014 Suggest patterns or alternatives
+- \`decantr get\` \u2014 Get full details of a registry item
+- \`decantr list\` \u2014 List items by type
+- \`decantr theme\` \u2014 Manage custom themes
+- \`decantr create\` \u2014 Create custom content items
+- \`decantr publish\` \u2014 Publish custom content to registry
+- \`decantr login\` \u2014 Authenticate with registry
+- \`decantr logout\` \u2014 Remove stored credentials
+- \`decantr upgrade\` \u2014 Check for content updates
+
+---
+
+*Generated by @decantr/cli v${CLI_VERSION}*
+`;
+  writeFileSync(decantrMdPath, decantrMdContent);
+  const gitignoreUpdated = updateGitignore(projectRoot);
+  return {
+    essencePath,
+    decantrMdPath,
+    projectJsonPath,
+    contextFiles: [],
+    cssFiles: [],
+    gitignoreUpdated
+  };
+}
+async function refreshDerivedFiles(projectRoot, essence, registry) {
+  const decantrDir = join(projectRoot, ".decantr");
+  const contextDir = join(decantrDir, "context");
+  mkdirSync(contextDir, { recursive: true });
+  const themeName = essence.dna.theme.style;
+  const recipeName = essence.dna.theme.recipe ?? themeName;
+  const mode = essence.dna.theme.mode;
+  const guardMode = essence.meta.guard.mode;
+  const guardConfig = {
+    mode: guardMode,
+    dna_enforcement: essence.meta.guard.dna_enforcement || "error",
+    blueprint_enforcement: essence.meta.guard.blueprint_enforcement || "warn"
+  };
+  const personality = essence.dna.personality || [];
+  let themeData;
+  let recipeData;
+  try {
+    const themeResult = await registry.fetchTheme(themeName);
+    if (themeResult?.data) {
+      const t = themeResult.data;
+      themeData = {
+        seed: t.seed,
+        palette: t.palette,
+        cvd_support: t.cvd_support,
+        tokens: t.tokens,
+        typography_hints: t.typography_hints,
+        motion_hints: t.motion_hints
+      };
+    }
+  } catch {
+  }
+  try {
+    const recipeResult = await registry.fetchRecipe(recipeName);
+    if (recipeResult?.data) {
+      const r = recipeResult.data;
+      recipeData = {
+        decorators: r.decorators,
+        spatial_hints: r.spatial_hints,
+        radius_hints: r.radius_hints
+      };
+    }
+  } catch {
+  }
+  const stylesDir = join(projectRoot, "src", "styles");
+  mkdirSync(stylesDir, { recursive: true });
+  const tokensPath = join(stylesDir, "tokens.css");
+  const hasRealThemeData = themeData?.seed?.primary || themeData?.palette?.background;
+  if (hasRealThemeData || !existsSync(tokensPath)) {
+    writeFileSync(tokensPath, generateTokensCSS(themeData, mode));
+  }
+  const decoratorsPath = join(stylesDir, "decorators.css");
+  const hasRealRecipeData = recipeData?.decorators && Object.keys(recipeData.decorators).length > 0;
+  if (hasRealRecipeData || !existsSync(decoratorsPath)) {
+    writeFileSync(decoratorsPath, generateDecoratorsCSS(recipeData, themeName));
+  }
+  const cssFiles = [tokensPath, decoratorsPath];
+  const decantrMdPath = join(projectRoot, "DECANTR.md");
+  writeFileSync(decantrMdPath, generateDecantrMdV31(guardMode, CSS_APPROACH_CONTENT));
+  const summaryPath = join(contextDir, "essence-summary.md");
+  writeFileSync(summaryPath, generateEssenceSummaryV3(essence));
+  const contextFiles = [summaryPath];
+  const blueprint = essence.blueprint;
+  const sections = blueprint.sections && blueprint.sections.length > 0 ? blueprint.sections : [];
+  if (sections.length > 0) {
+    const patternSpecs = {};
+    const seenPatterns = /* @__PURE__ */ new Set();
+    for (const section of sections) {
+      for (const page of section.pages) {
+        for (const item of page.layout) {
+          const names = extractPatternNames(item);
+          for (const name of names) {
+            if (!seenPatterns.has(name)) {
+              seenPatterns.add(name);
+              try {
+                const patResult = await registry.fetchPattern(name);
+                if (patResult?.data) {
+                  const raw = patResult.data;
+                  const inner = raw.data ?? raw;
+                  const defaultPreset = inner.default_preset || "standard";
+                  const preset = inner.presets?.[defaultPreset];
+                  patternSpecs[name] = {
+                    description: inner.description || "",
+                    components: inner.components || [],
+                    slots: preset?.layout?.slots || {}
+                  };
+                }
+              } catch {
+              }
+            }
+          }
+        }
+      }
+    }
+    const zoneInputs = sections.map((s) => ({
+      archetypeId: s.id,
+      role: s.role,
+      shell: s.shell,
+      features: s.features,
+      description: s.description
+    }));
+    const zones = deriveZones(zoneInputs);
+    const transitions = deriveTransitions(zones);
+    const hasPublic = zones.some((z) => z.role === "public");
+    const hasPrimary = zones.some((z) => z.role === "primary");
+    const topologyData = {
+      intent: sections.map((s) => s.id).join(" + "),
+      zones,
+      transitions,
+      entryPoints: {
+        anonymous: hasPublic ? "public zone" : "gateway",
+        authenticated: hasPrimary ? "primary zone" : "first section"
+      }
+    };
+    const topologyMarkdown = generateTopologySection(topologyData, personality);
+    const themeTokensCss = existsSync(tokensPath) ? readFileSync(tokensPath, "utf-8") : "";
+    const decoratorList = [];
+    if (recipeData?.decorators) {
+      for (const [name, desc] of Object.entries(recipeData.decorators)) {
+        decoratorList.push({ name, description: desc });
+      }
+    } else if (existsSync(decoratorsPath)) {
+      const decoratorsCss = readFileSync(decoratorsPath, "utf-8");
+      const classRegex = /\/\*\s*(.+?)\s*\*\/\s*\n\s*\.([\w-]+)\s*\{/g;
+      let match;
+      while ((match = classRegex.exec(decoratorsCss)) !== null) {
+        decoratorList.push({ name: match[2], description: match[1] });
+      }
+      if (decoratorList.length === 0) {
+        const simpleClassRegex = /^\.([\w-]+)\s*\{/gm;
+        while ((match = simpleClassRegex.exec(decoratorsCss)) !== null) {
+          decoratorList.push({ name: match[1], description: "" });
+        }
+      }
+    }
+    const shellInfoCache = {};
+    const seenShells = /* @__PURE__ */ new Set();
+    for (const section of sections) {
+      const shellId = section.shell;
+      if (!seenShells.has(shellId)) {
+        seenShells.add(shellId);
+        try {
+          const shellResult = await registry.fetchShell(shellId);
+          if (shellResult?.data) {
+            const raw = shellResult.data;
+            const inner = raw.data ?? raw;
+            shellInfoCache[shellId] = {
+              description: inner.description || "",
+              regions: inner.config?.regions || [],
+              layout: inner.layout || void 0
+            };
+          }
+        } catch {
+        }
+      }
+    }
+    for (const section of sections) {
+      const zoneLabel = section.role === "primary" || section.role === "auxiliary" ? "App" : section.role.charAt(0).toUpperCase() + section.role.slice(1);
+      const zoneContext = `This section is in the **${zoneLabel}** zone (${section.shell} shell).` + (topologyMarkdown ? "\n\n" + topologyMarkdown : "");
+      const sectionPatterns = {};
+      for (const page of section.pages) {
+        for (const item of page.layout) {
+          const names = extractPatternNames(item);
+          for (const name of names) {
+            if (patternSpecs[name]) {
+              sectionPatterns[name] = patternSpecs[name];
+            }
+          }
+        }
+      }
+      const contextContent = generateSectionContext({
+        section,
+        themeTokens: themeTokensCss,
+        decorators: decoratorList,
+        guardConfig,
+        personality,
+        themeName,
+        recipeName,
+        zoneContext,
+        patternSpecs: sectionPatterns,
+        constraints: essence.dna.constraints,
+        shellInfo: shellInfoCache[section.shell]
+      });
+      const sectionContextPath = join(contextDir, `section-${section.id}.md`);
+      writeFileSync(sectionContextPath, contextContent);
+      contextFiles.push(sectionContextPath);
+    }
+    const routes = blueprint.routes || {};
+    const scaffoldContent = generateScaffoldContext({
+      appName: essence.meta.archetype || "Application",
+      blueprintId: "",
+      themeName,
+      recipeName,
+      personality,
+      topologyMarkdown,
+      sections,
+      routes,
+      constraints: essence.dna.constraints,
+      seo: essence.meta.seo,
+      navigation: essence.meta.navigation
+    });
+    const scaffoldMdPath = join(contextDir, "scaffold.md");
+    writeFileSync(scaffoldMdPath, scaffoldContent);
+    contextFiles.push(scaffoldMdPath);
+  } else {
+    const pages = blueprint.pages || [{ id: "home", layout: ["hero"] }];
+    const shell = blueprint.shell ?? "sidebar-main";
+    const syntheticSection = {
+      id: essence.meta.archetype || "default",
+      role: "primary",
+      shell,
+      features: blueprint.features || [],
+      description: `${essence.meta.archetype || "Application"} section`,
+      pages
+    };
+    const patternSpecs = {};
+    const seenPatterns = /* @__PURE__ */ new Set();
+    for (const page of pages) {
+      for (const item of page.layout) {
+        const names = extractPatternNames(item);
+        for (const name of names) {
+          if (!seenPatterns.has(name)) {
+            seenPatterns.add(name);
+            try {
+              const patResult = await registry.fetchPattern(name);
+              if (patResult?.data) {
+                const raw = patResult.data;
+                const inner = raw.data ?? raw;
+                const defaultPreset = inner.default_preset || "standard";
+                const preset = inner.presets?.[defaultPreset];
+                patternSpecs[name] = {
+                  description: inner.description || "",
+                  components: inner.components || [],
+                  slots: preset?.layout?.slots || {}
+                };
+              }
+            } catch {
+            }
+          }
+        }
+      }
+    }
+    const themeTokensCss = existsSync(tokensPath) ? readFileSync(tokensPath, "utf-8") : "";
+    const decoratorList = [];
+    if (recipeData?.decorators) {
+      for (const [name, desc] of Object.entries(recipeData.decorators)) {
+        decoratorList.push({ name, description: desc });
+      }
+    } else if (existsSync(decoratorsPath)) {
+      const decoratorsCss = readFileSync(decoratorsPath, "utf-8");
+      const classRegex = /\/\*\s*(.+?)\s*\*\/\s*\n\s*\.([\w-]+)\s*\{/g;
+      let match;
+      while ((match = classRegex.exec(decoratorsCss)) !== null) {
+        decoratorList.push({ name: match[2], description: match[1] });
+      }
+      if (decoratorList.length === 0) {
+        const simpleClassRegex = /^\.([\w-]+)\s*\{/gm;
+        while ((match = simpleClassRegex.exec(decoratorsCss)) !== null) {
+          decoratorList.push({ name: match[1], description: "" });
+        }
+      }
+    }
+    let v30ShellInfo;
+    try {
+      const shellResult = await registry.fetchShell(shell);
+      if (shellResult?.data) {
+        const raw = shellResult.data;
+        const inner = raw.data ?? raw;
+        v30ShellInfo = {
+          description: inner.description || "",
+          regions: inner.config?.regions || [],
+          layout: inner.layout || void 0
+        };
+      }
+    } catch {
+    }
+    const contextContent = generateSectionContext({
+      section: syntheticSection,
+      themeTokens: themeTokensCss,
+      decorators: decoratorList,
+      guardConfig,
+      personality,
+      themeName,
+      recipeName,
+      zoneContext: `This is the primary section (${shell} shell).`,
+      patternSpecs,
+      constraints: essence.dna.constraints,
+      shellInfo: v30ShellInfo
+    });
+    const sectionContextPath = join(contextDir, `section-${syntheticSection.id}.md`);
+    writeFileSync(sectionContextPath, contextContent);
+    contextFiles.push(sectionContextPath);
+  }
+  return {
+    decantrMdPath,
+    contextFiles,
+    cssFiles
+  };
+}
+function generateSectionContext(input) {
+  const { section, themeTokens, decorators, guardConfig, personality, themeName, recipeName, zoneContext, patternSpecs, recipeHints, constraints, shellInfo } = input;
+  const lines = [];
+  lines.push(`# Section: ${section.id}`);
+  lines.push("");
+  lines.push(`**Role:** ${section.role} | **Shell:** ${section.shell} | **Archetype:** ${section.id}`);
+  lines.push(`**Description:** ${section.description}`);
+  if (shellInfo) {
+    lines.push(`**Shell structure:** ${shellInfo.description}`);
+    lines.push(`**Regions:** ${shellInfo.regions.join(", ")}`);
+  }
+  if (section.dna_overrides) {
+    const parts = [];
+    if (section.dna_overrides.density) parts.push(`density: ${section.dna_overrides.density}`);
+    if (section.dna_overrides.mode) parts.push(`mode: ${section.dna_overrides.mode}`);
+    if (parts.length > 0) {
+      lines.push(`**DNA Overrides:** ${parts.join(", ")}`);
+    }
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("## Guard Rules");
+  lines.push("");
+  lines.push(`| Rule | Scope | Severity | Description |`);
+  lines.push(`|------|-------|----------|-------------|`);
+  lines.push(`| Style guard | DNA | ${guardConfig.dna_enforcement} | Code must use the ${themeName} theme |`);
+  lines.push(`| Recipe guard | DNA | ${guardConfig.dna_enforcement} | Visual recipe must match ${recipeName} |`);
+  lines.push(`| Density guard | DNA | ${guardConfig.dna_enforcement} | Content gap must match essence density |`);
+  lines.push(`| Accessibility guard | DNA | ${guardConfig.dna_enforcement} | Must meet WCAG level from essence |`);
+  lines.push(`| Structure guard | Blueprint | ${guardConfig.blueprint_enforcement} | Pages must exist in essence structure |`);
+  lines.push(`| Layout guard | Blueprint | ${guardConfig.blueprint_enforcement} | Pattern order must match essence layout |`);
+  lines.push(`| Pattern existence | Blueprint | ${guardConfig.blueprint_enforcement} | All patterns must exist in registry |`);
+  lines.push("");
+  lines.push(`**Guard mode:** ${guardConfig.mode}`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push(`## Theme: ${themeName}`);
+  lines.push("");
+  lines.push("```css");
+  lines.push(themeTokens);
+  lines.push("```");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push(`## Decorators (${recipeName} recipe)`);
+  lines.push("");
+  if (decorators.length > 0) {
+    lines.push("| Decorator | Description |");
+    lines.push("|-----------|-------------|");
+    for (const dec of decorators) {
+      lines.push(`| ${dec.name} | ${dec.description} |`);
+    }
+  } else {
+    lines.push("No decorators defined.");
+  }
+  lines.push("");
+  if (recipeHints) {
+    if (recipeHints.preferred && recipeHints.preferred.length > 0) {
+      lines.push(`**Preferred:** ${recipeHints.preferred.join(", ")}`);
+    }
+    if (recipeHints.compositions) {
+      lines.push(`**Compositions:** ${recipeHints.compositions}`);
+    }
+    if (recipeHints.spatialHints) {
+      lines.push(`**Spatial hints:** ${recipeHints.spatialHints}`);
+    }
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push("");
+  if (zoneContext) {
+    lines.push("## Zone Context");
+    lines.push("");
+    lines.push(zoneContext);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+  if (section.features.length > 0) {
+    lines.push("## Features");
+    lines.push("");
+    lines.push(section.features.join(", "));
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+  if (personality.length > 0) {
+    lines.push("## Personality");
+    lines.push("");
+    lines.push(personality.join(", "));
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+  if (constraints && Object.keys(constraints).length > 0) {
+    lines.push("## Constraints");
+    lines.push("");
+    for (const [key, value] of Object.entries(constraints)) {
+      lines.push(`- **${key}:** ${typeof value === "object" && value !== null ? JSON.stringify(value) : value}`);
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+  lines.push("## Pages");
+  lines.push("");
+  for (const page of section.pages) {
+    const route = page.route || `/${section.id}/${page.id}`;
+    const layoutStr = page.layout.map(serializeLayoutItem).join(" \u2192 ");
+    lines.push(`### ${page.id} (${route})`);
+    lines.push("");
+    lines.push(`Layout: ${layoutStr}`);
+    lines.push("");
+    if (page.patterns && page.patterns.length > 0) {
+      lines.push("**Pattern mapping:**");
+      lines.push("| Alias | Pattern | Preset |");
+      lines.push("|-------|---------|--------|");
+      for (const ref of page.patterns) {
+        const alias = ref.as || ref.pattern;
+        const preset = ref.preset || "standard";
+        lines.push(`| ${alias} | ${ref.pattern} | ${preset} |`);
+      }
+      lines.push("");
+    }
+    const patternNames = page.layout.flatMap(extractPatternNames);
+    for (const patternName of patternNames) {
+      const spec = patternSpecs[patternName];
+      if (!spec) continue;
+      lines.push(`#### Pattern: ${patternName}`);
+      lines.push("");
+      lines.push(spec.description);
+      lines.push("");
+      lines.push(`**Components:** ${spec.components.join(", ")}`);
+      lines.push("");
+      lines.push("**Layout slots:**");
+      for (const [slot, desc] of Object.entries(spec.slots)) {
+        lines.push(`- \`${slot}\`: ${desc}`);
+      }
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function generateScaffoldContext(input) {
+  const { appName, blueprintId, themeName, recipeName, personality, topologyMarkdown, sections, routes, constraints, seo, navigation } = input;
+  const lines = [];
+  lines.push(`# Scaffold: ${appName}`);
+  lines.push("");
+  lines.push(`**Blueprint:** ${blueprintId}`);
+  lines.push(`**Theme:** ${themeName} | **Recipe:** ${recipeName}`);
+  lines.push(`**Personality:** ${personality.join(", ")}`);
+  lines.push("**Guard mode:** creative (no enforcement during initial scaffolding)");
+  lines.push("");
+  lines.push("## App Topology");
+  lines.push("");
+  lines.push(topologyMarkdown);
+  lines.push("");
+  lines.push("## Sections Overview");
+  lines.push("");
+  lines.push("| Section | Role | Shell | Pages | Features |");
+  lines.push("|---------|------|-------|-------|----------|");
+  for (const section of sections) {
+    const pageIds = section.pages.map((p) => p.id).join(", ");
+    const feats = section.features.join(", ") || "none";
+    lines.push(`| ${section.id} | ${section.role} | ${section.shell} | ${pageIds} | ${feats} |`);
+  }
+  lines.push("");
+  lines.push("## Route Map");
+  lines.push("");
+  lines.push("| Route | Section | Page |");
+  lines.push("|-------|---------|------|");
+  for (const [route, entry] of Object.entries(routes)) {
+    lines.push(`| ${route} | ${entry.section} | ${entry.page} |`);
+  }
+  lines.push("");
+  lines.push("## Section Contexts");
+  lines.push("");
+  lines.push("For detailed pattern specs per section, read:");
+  for (const section of sections) {
+    lines.push(`- .decantr/context/section-${section.id}.md`);
+  }
+  lines.push("");
+  const patternUsage = {};
+  for (const section of sections) {
+    for (const page of section.pages) {
+      const names = page.layout.flatMap(extractPatternNames);
+      for (const name of names) {
+        if (!patternUsage[name]) patternUsage[name] = [];
+        const pageLabel = sections.length > 1 ? `${section.id}/${page.id}` : page.id;
+        patternUsage[name].push(pageLabel);
+      }
+    }
+  }
+  const sharedPatterns = Object.entries(patternUsage).filter(([, pages]) => pages.length >= 2);
+  if (sharedPatterns.length > 0) {
+    lines.push("## Shared Components");
+    lines.push("");
+    lines.push("These patterns appear on multiple pages. Consider creating shared components:");
+    lines.push("");
+    lines.push("| Pattern | Used by |");
+    lines.push("|---------|---------|");
+    for (const [pattern, pages] of sharedPatterns) {
+      lines.push(`| ${pattern} | ${pages.join(", ")} |`);
+    }
+    lines.push("");
+  }
+  if (constraints && Object.keys(constraints).length > 0) {
+    lines.push("## Design Constraints");
+    lines.push("");
+    for (const [key, value] of Object.entries(constraints)) {
+      lines.push(`- **${key}:** ${typeof value === "object" && value !== null ? JSON.stringify(value) : value}`);
+    }
+    lines.push("");
+  }
+  if (seo && (seo.schema_org?.length || seo.meta_priorities?.length)) {
+    lines.push("## SEO Hints");
+    lines.push("");
+    if (seo.schema_org && seo.schema_org.length > 0) {
+      lines.push(`**Schema.org types:** ${seo.schema_org.join(", ")}`);
+    }
+    if (seo.meta_priorities && seo.meta_priorities.length > 0) {
+      lines.push(`**Meta priorities:** ${seo.meta_priorities.join(", ")}`);
+    }
+    lines.push("");
+  }
+  if (navigation && (navigation.hotkeys?.length || navigation.command_palette)) {
+    lines.push("## Navigation");
+    lines.push("");
+    if (navigation.command_palette) {
+      lines.push("- Command palette: enabled");
+    }
+    if (navigation.hotkeys && navigation.hotkeys.length > 0) {
+      lines.push(`- Hotkeys: ${navigation.hotkeys.length} configured`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/registry.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, readdirSync } from "fs";
+import { join as join2 } from "path";
+import { RegistryAPIClient } from "@decantr/registry";
+var DEFAULT_API_URL = "https://api.decantr.ai/v1";
+var ALL_CONTENT_TYPES = ["themes", "patterns", "recipes", "blueprints", "archetypes", "shells"];
+function loadFromCache(cacheDir, contentType, id, namespace) {
+  const nsDir = namespace ? join2(cacheDir, namespace) : cacheDir;
+  const cachePath = id ? join2(nsDir, contentType, `${id}.json`) : join2(nsDir, contentType, "index.json");
+  if (!existsSync2(cachePath)) return null;
+  try {
+    const data = JSON.parse(readFileSync2(cachePath, "utf-8"));
+    return { data, source: { type: "cache" } };
+  } catch {
+    return null;
+  }
+}
+function saveToCache(cacheDir, contentType, id, data, namespace = "@official") {
+  const dir = join2(cacheDir, namespace, contentType);
+  mkdirSync2(dir, { recursive: true });
+  const cachePath = id ? join2(dir, `${id}.json`) : join2(dir, "index.json");
+  writeFileSync2(cachePath, JSON.stringify(data, null, 2));
+}
+var RegistryClient = class {
+  cacheDir;
+  apiUrl;
+  offline;
+  projectRoot;
+  apiClient;
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.cacheDir = options.cacheDir || join2(this.projectRoot, ".decantr", "cache");
+    this.apiUrl = options.apiUrl || DEFAULT_API_URL;
+    this.offline = options.offline || false;
+    this.apiClient = new RegistryAPIClient({
+      baseUrl: this.apiUrl,
+      apiKey: options.apiKey
+    });
+  }
+  /**
+   * Load content from .decantr/custom/{contentType}/{id}.json
+   * Works for ALL content types, not just themes.
+   */
+  loadCustomContent(contentType, id) {
+    const customPath = join2(
+      this.projectRoot,
+      ".decantr",
+      "custom",
+      contentType,
+      `${id}.json`
+    );
+    if (!existsSync2(customPath)) return null;
+    try {
+      const data = JSON.parse(readFileSync2(customPath, "utf-8"));
+      return { data, source: { type: "custom", path: customPath } };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * List all custom content of a given type from .decantr/custom/{type}/
+   */
+  listCustomContent(contentType) {
+    const dir = join2(this.projectRoot, ".decantr", "custom", contentType);
+    if (!existsSync2(dir)) return [];
+    try {
+      return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => {
+        const data = JSON.parse(readFileSync2(join2(dir, f), "utf-8"));
+        return { id: data.id || f.replace(".json", ""), ...data };
+      });
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Unified fetch for a content list.
+   * Resolution: API -> Cache. Custom items are merged into the list.
+   */
+  async fetchContentList(contentType, namespace) {
+    let apiItems = [];
+    let source = { type: "cache" };
+    if (!this.offline) {
+      try {
+        const apiResult = await this.apiClient.listContent(contentType, { namespace });
+        apiItems = apiResult.items;
+        source = { type: "api", url: this.apiUrl };
+        saveToCache(this.cacheDir, contentType, null, apiResult, namespace || "@official");
+      } catch {
+      }
+    }
+    if (apiItems.length === 0) {
+      const cacheResult = loadFromCache(
+        this.cacheDir,
+        contentType,
+        void 0,
+        namespace
+      );
+      if (cacheResult) {
+        apiItems = cacheResult.data.items;
+        source = { type: "cache" };
+      }
+    }
+    const customItems = this.listCustomContent(contentType);
+    const allItems = [...customItems, ...apiItems];
+    return {
+      data: { items: allItems, total: allItems.length },
+      source
+    };
+  }
+  /**
+   * Unified fetch for a single content item.
+   * Resolution: Custom -> API -> Cache
+   */
+  async fetchContentItem(contentType, id, namespace = "@official") {
+    const customId = id.startsWith("custom:") ? id.slice(7) : id;
+    const customResult = this.loadCustomContent(contentType, customId);
+    if (customResult) return customResult;
+    if (id.startsWith("custom:")) return null;
+    if (!this.offline) {
+      try {
+        const data = await this.apiClient.getContent(contentType, namespace, id);
+        saveToCache(this.cacheDir, contentType, id, data, namespace);
+        return { data, source: { type: "api", url: this.apiUrl } };
+      } catch {
+      }
+    }
+    return loadFromCache(this.cacheDir, contentType, id, namespace);
+  }
+  // ── Convenience methods (delegate to unified fetch) ──
+  async fetchArchetypes() {
+    return this.fetchContentList("archetypes");
+  }
+  async fetchArchetype(id) {
+    return this.fetchContentItem("archetypes", id);
+  }
+  async fetchBlueprints() {
+    return this.fetchContentList("blueprints");
+  }
+  async fetchBlueprint(id) {
+    return this.fetchContentItem("blueprints", id);
+  }
+  async fetchThemes() {
+    return this.fetchContentList("themes");
+  }
+  async fetchTheme(id) {
+    return this.fetchContentItem("themes", id);
+  }
+  async fetchPatterns() {
+    return this.fetchContentList("patterns");
+  }
+  async fetchPattern(id) {
+    return this.fetchContentItem("patterns", id);
+  }
+  async fetchShells() {
+    return this.fetchContentList("shells");
+  }
+  async fetchShell(id) {
+    return this.fetchContentItem("shells", id);
+  }
+  async fetchRecipes() {
+    return this.fetchContentList("recipes");
+  }
+  async fetchRecipe(id) {
+    return this.fetchContentItem("recipes", id);
+  }
+  /**
+   * Check if API is available.
+   */
+  async checkApiAvailability() {
+    if (this.offline) return false;
+    return this.apiClient.checkHealth();
+  }
+};
+async function syncRegistry(cacheDir, apiUrl = DEFAULT_API_URL) {
+  const apiClient = new RegistryAPIClient({ baseUrl: apiUrl });
+  const synced = [];
+  const failed = [];
+  const healthy = await apiClient.checkHealth();
+  if (!healthy) {
+    return { synced: [], failed: ["API unavailable"] };
+  }
+  for (const type of ALL_CONTENT_TYPES) {
+    try {
+      const result = await apiClient.listContent(type, { namespace: "@official" });
+      saveToCache(cacheDir, type, null, result, "@official");
+      for (const item of result.items) {
+        const id = item.id || item.slug;
+        if (id) {
+          saveToCache(cacheDir, type, id, item, "@official");
+        }
+      }
+      synced.push(type);
+    } catch {
+      failed.push(type);
+    }
+  }
+  return { synced, failed };
+}
+
+export {
+  composeArchetypes,
+  composeSections,
+  deriveZones,
+  deriveTransitions,
+  generateTopologySection,
+  scaffoldProject,
+  scaffoldMinimal,
+  refreshDerivedFiles,
+  RegistryClient,
+  syncRegistry
+};