@decantr/cli 1.4.0 → 1.5.2

package/dist/{chunk-ZQ5FTYKG.js → chunk-6RJSFLT4.js}

@@ -120,6 +120,12 @@ function composeSections(composeEntries, archetypeResults, overrides) {
       }
     }
   }
+  const primaryShell = sections.find((s) => s.role === "primary")?.shell || defaultShell;
+  for (const section of sections) {
+    if (section.shell === "inherit") {
+      section.shell = primaryShell;
+    }
+  }
   let features = [...new Set(allFeatures)];
   if (overrides?.features_add) {
     for (const f of overrides.features_add) {
@@ -292,11 +298,11 @@ function generateTokensCSS(themeData, mode) {
       "--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)",
+      // Shadows — dark mode needs higher opacity to be visible on dark backgrounds
+      "--d-shadow-sm": tokenMode === "light" ? "0 1px 2px rgba(0,0,0,0.05)" : "0 1px 2px rgba(0,0,0,0.2)",
+      "--d-shadow": tokenMode === "light" ? "0 1px 3px rgba(0,0,0,0.1)" : "0 1px 3px rgba(0,0,0,0.25)",
+      "--d-shadow-md": tokenMode === "light" ? "0 4px 6px rgba(0,0,0,0.1)" : "0 4px 6px rgba(0,0,0,0.3)",
+      "--d-shadow-lg": tokenMode === "light" ? "0 10px 15px rgba(0,0,0,0.1)" : "0 10px 15px rgba(0,0,0,0.4)",
       // Status colors
       "--d-success": themeData.tokens?.base?.success || "#22c55e",
       "--d-error": themeData.tokens?.base?.danger || "#ef4444",
@@ -313,7 +319,19 @@ ${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 paletteKeys = [
+      "--d-bg",
+      "--d-surface",
+      "--d-surface-raised",
+      "--d-border",
+      "--d-text",
+      "--d-text-muted",
+      "--d-primary-hover",
+      "--d-shadow-sm",
+      "--d-shadow",
+      "--d-shadow-md",
+      "--d-shadow-lg"
+    ];
     const lightLines = Object.entries(lightTokens).filter(([key]) => paletteKeys.includes(key)).map(([key, value]) => `    ${key}: ${value};`).join("\n");
     css += `
 @media (prefers-color-scheme: light) {
@@ -351,17 +369,132 @@ function generateDecoratorsCSS(recipeData, themeName) {
 `);
   return css.join("\n");
 }
+function generateGlobalCSS(personality) {
+  const personalityText = personality.join(" ").toLowerCase();
+  let fontBody = "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+  if (personalityText.includes("inter")) {
+    fontBody = `'Inter', ${fontBody}`;
+  } else if (personalityText.includes("geist")) {
+    fontBody = `'Geist', ${fontBody}`;
+  }
+  return `/* Generated by @decantr/cli \u2014 global reset + body styles */
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  color-scheme: dark;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
+body {
+  font-family: ${fontBody};
+  background: var(--d-bg);
+  color: var(--d-text);
+  line-height: 1.6;
+  min-height: 100dvh;
+}
+
+img, picture, video, canvas, svg {
+  display: block;
+  max-width: 100%;
+}
+
+input, button, textarea, select {
+  font: inherit;
+  color: inherit;
+}
+
+:focus-visible {
+  outline: 2px solid var(--d-primary);
+  outline-offset: 2px;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+`;
+}
+function generateDecoratorsContext(recipeData, recipeName) {
+  const lines = [];
+  lines.push(`# Recipe Decorators: ${recipeName}`);
+  lines.push("");
+  lines.push("## Available Classes");
+  lines.push("");
+  if (recipeData?.decorators && Object.keys(recipeData.decorators).length > 0) {
+    lines.push("| Decorator | Description |");
+    lines.push("|-----------|-------------|");
+    for (const [name, description] of Object.entries(recipeData.decorators)) {
+      lines.push(`| ${name} | ${description} |`);
+    }
+  } else {
+    lines.push("No decorators defined.");
+  }
+  lines.push("");
+  lines.push("## Usage");
+  lines.push("");
+  lines.push("Decorators are plain CSS class names from `src/styles/decorators.css`. Combine with atoms:");
+  lines.push("");
+  lines.push("```tsx");
+  lines.push("<div className={css('_flex _col _gap4') + ' " + recipeName + "-card'}>");
+  lines.push("  <pre className={css('_p3') + ' " + recipeName + "-code'}>{code}</pre>");
+  lines.push("</div>");
+  lines.push("```");
+  lines.push("");
+  lines.push("Atoms use `css()` function. Decorators are plain class strings. Combined via string concatenation.");
+  lines.push("");
+  return lines.join("\n");
+}
 function generateDecoratorRule(name, description) {
   const rules = [];
   const descLower = description.toLowerCase();
-  if (descLower.includes("surface background") || descLower.includes("surface elevation")) {
+  const nameLower = name.toLowerCase();
+  const isCard = descLower.includes("card") || descLower.includes("panel") || nameLower.includes("card") || nameLower.includes("panel");
+  const isInput = descLower.includes("input") || descLower.includes("field") || descLower.includes("textarea") || nameLower.includes("input") || nameLower.includes("textarea");
+  const isGlass = descLower.includes("glassmorphic") || descLower.includes("glass") || nameLower.includes("glass");
+  const isInteractive = isCard || isInput || isGlass;
+  const isNonInteractive = descLower.includes("divider") || descLower.includes("skeleton") || descLower.includes("keyframe") || descLower.includes("canvas") || nameLower.includes("divider") || nameLower.includes("skeleton") || nameLower.includes("canvas");
+  if (descLower.includes("monospace") || descLower.includes("mono font")) {
+    rules.push("font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace");
+  }
+  if (descLower.includes("surface-raised") || descLower.includes("surface raised")) {
+    rules.push("background: var(--d-surface-raised)");
+  } else 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")) {
+  if (isInput) {
+    if (!rules.some((r) => r.startsWith("background"))) {
+      rules.push("background: var(--d-surface)");
+    }
+    rules.push("color: var(--d-text)");
+    rules.push("padding: 0.5rem 0.75rem");
+    rules.push("border-radius: var(--d-radius)");
+    rules.push("width: 100%");
+    rules.push("outline: none");
+  }
+  const leftBorderMatch = descLower.match(/(\d+)px\s+left\s+border/);
+  if (leftBorderMatch) {
+    rules.push(`border-left: ${leftBorderMatch[1]}px solid var(--d-primary)`);
+  } else if (descLower.includes("left border")) {
+    rules.push("border-left: 3px solid var(--d-primary)");
+  } else 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)");
@@ -369,23 +502,40 @@ function generateDecoratorRule(name, description) {
   const radiusMatch = descLower.match(/(\d+)px radius/);
   if (radiusMatch) {
     rules.push(`border-radius: ${radiusMatch[1]}px`);
-  } else if (descLower.includes("radius") || descLower.includes("rounded")) {
+  } else if ((descLower.includes("radius") || descLower.includes("rounded")) && !isInput) {
     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 (isInteractive && !isNonInteractive) {
+    rules.push("transition: border-color 0.15s ease, box-shadow 0.15s ease, background 0.15s ease");
+  }
   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")) {
+  const blurMatch = descLower.match(/blur\((\d+)px\)/);
+  if (blurMatch) {
+    rules.push(`backdrop-filter: blur(${blurMatch[1]}px)`);
+    rules.push(`-webkit-backdrop-filter: blur(${blurMatch[1]}px)`);
+  } else if (isGlass) {
+    rules.push("backdrop-filter: blur(12px)");
+    rules.push("-webkit-backdrop-filter: blur(12px)");
+  } else if (descLower.includes("blur")) {
     rules.push("backdrop-filter: blur(8px)");
+    rules.push("-webkit-backdrop-filter: blur(8px)");
+  }
+  if (descLower.includes("semi-transparent") || descLower.includes("glassmorphic")) {
+    const bgIdx = rules.findIndex((r) => r.startsWith("background:"));
+    const rgbaBg = "background: rgba(31, 31, 35, 0.8)";
+    if (bgIdx !== -1) {
+      rules[bgIdx] = rgbaBg;
+    } else {
+      rules.push(rgbaBg);
+    }
   }
   if (descLower.includes("right-aligned")) {
     rules.push("margin-left: auto");
@@ -397,12 +547,45 @@ function generateDecoratorRule(name, description) {
     rules.push("border-radius: var(--d-radius-lg)");
     rules.push("max-width: 80%");
   }
+  if (descLower.includes("monospace") || descLower.includes("code")) {
+    if (!rules.some((r) => r.startsWith("padding"))) {
+      rules.push("padding: 0.75rem 1rem");
+    }
+    if (!rules.some((r) => r.startsWith("border-radius"))) {
+      rules.push("border-radius: var(--d-radius-sm)");
+    }
+    rules.push("overflow-x: auto");
+  }
   if (rules.length === 0) {
     return `/* .${name}: ${description} */`;
   }
-  return `.${name} {
+  let css = `.${name} {
   ${rules.join(";\n  ")};
 }`;
+  if (isInteractive && !isNonInteractive) {
+    const stateRules = [];
+    if (isCard || isGlass) {
+      stateRules.push(`.${name}:hover {
+  border-color: var(--d-primary-hover, var(--d-border));
+  box-shadow: var(--d-shadow-md);
+}`);
+    }
+    if (isInput) {
+      stateRules.push(`.${name}:focus {
+  border-color: var(--d-primary);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--d-primary) 25%, transparent);
+}`);
+      stateRules.push(`.${name}::placeholder {
+  color: var(--d-text-muted);
+}`);
+      stateRules.push(`.${name}:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}`);
+    }
+    css += "\n\n" + stateRules.join("\n\n");
+  }
+  return css;
 }
 function serializeLayoutItem(item) {
   if (typeof item === "string") {
@@ -833,6 +1016,32 @@ The \`css()\` function processes atom strings and injects CSS at runtime:
 | \`_trans\` | \`transition:all 0.15s ease\` |
 | \`_visible\`, \`_invisible\` | visibility |
 
+### Using Recipe Decorators
+
+Recipe decorators (from \`src/styles/decorators.css\`) are regular CSS class names, NOT atoms. They are applied directly as class names and combined with atoms using string concatenation:
+
+\`\`\`tsx
+// Atoms use css() function, decorators are plain class names
+<div className={css('_flex _col _gap4') + ' carbon-card'}>
+  <div className={css('_p4') + ' carbon-glass'}>
+    <pre className={css('_p3') + ' carbon-code'}>{code}</pre>
+  </div>
+</div>
+\`\`\`
+
+**Key difference:**
+- Atoms: \`css('_flex _col _gap4')\` \u2014 processed by @decantr/css runtime
+- Decorators: \`'carbon-card'\`, \`'carbon-glass'\` \u2014 plain CSS classes from decorators.css
+- Combined: \`css('_flex _col') + ' carbon-card'\`
+
+### Routing
+
+Check \`decantr.essence.json\` \u2192 \`meta.platform.routing\` for the routing strategy:
+- \`"hash"\` \u2192 use \`HashRouter\` (e.g., for static hosting, GitHub Pages)
+- \`"history"\` \u2192 use \`BrowserRouter\` (e.g., for server-rendered apps)
+
+Routes are defined in \`decantr.essence.json\` \u2192 \`blueprint.routes\` and listed in \`.decantr/context/scaffold.md\`.
+
 ### CSS Architecture
 
 The CSS is organized into two parts:
@@ -925,33 +1134,29 @@ function generateTaskContext(templateName, essence) {
   };
   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";
+function generateTaskContextV3(templateName, essence) {
+  const template = loadTemplate(templateName);
+  const pages = essence.blueprint.sections && essence.blueprint.sections.length > 0 ? essence.blueprint.sections.flatMap((s) => s.pages) : essence.blueprint.pages || [];
+  const defaultShell = essence.blueprint.sections?.[0]?.shell || essence.blueprint.shell || "sidebar-main";
+  const layout = pages[0]?.layout?.map(serializeLayoutItem).join(", ") || "none";
+  const scaffoldStructure = pages.map((p) => {
+    const patterns = p.layout.length > 0 ? `
+  - Patterns: ${p.layout.map(serializeLayoutItem).join(", ")}` : "";
+    return `- **${p.id}** (${defaultShell})${patterns}`;
+  }).join("\n");
+  const densityLevel = essence.dna.spacing?.density || "comfortable";
+  const contentGap = essence.dna.spacing?.content_gap || "_gap4";
   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()
+    TARGET: essence.meta.target || "react",
+    THEME_STYLE: essence.dna.theme.style,
+    THEME_MODE: essence.dna.theme.mode,
+    THEME_RECIPE: essence.dna.theme.recipe || essence.dna.theme.style,
+    DEFAULT_SHELL: defaultShell,
+    GUARD_MODE: essence.meta.guard.mode,
+    LAYOUT: layout,
+    DENSITY: densityLevel,
+    CONTENT_GAP: contentGap,
+    SCAFFOLD_STRUCTURE: scaffoldStructure
   };
   return renderTemplate(template, vars);
 }
@@ -1035,15 +1240,6 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
   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 = {
@@ -1052,7 +1248,7 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
       routes: routeMap || {}
     };
     if (blueprintData?.personality?.length) {
-      essenceV3.dna.personality = blueprintData.personality;
+      essenceV3.dna.personality = typeof blueprintData.personality === "string" ? [blueprintData.personality] : blueprintData.personality;
     }
     if (blueprintData?.design_constraints) {
       essenceV3.dna.constraints = blueprintData.design_constraints;
@@ -1065,7 +1261,7 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
     }
     writeFileSync(essencePath, JSON.stringify(essenceV3, null, 2) + "\n");
   }
-  const refreshResult = await refreshDerivedFiles(projectRoot, essenceV3, registry);
+  const refreshResult = await refreshDerivedFiles(projectRoot, essenceV3, registry, themeData, recipeData, { isInitialScaffold: true });
   contextFiles.push(...refreshResult.contextFiles);
   const gitignoreUpdated = updateGitignore(projectRoot);
   return {
@@ -1267,7 +1463,7 @@ When available, use these tools:
     gitignoreUpdated
   };
 }
-async function refreshDerivedFiles(projectRoot, essence, registry) {
+async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThemeData, prefetchedRecipeData, options) {
   const decantrDir = join(projectRoot, ".decantr");
   const contextDir = join(decantrDir, "context");
   mkdirSync(contextDir, { recursive: true });
@@ -1281,12 +1477,13 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
     blueprint_enforcement: essence.meta.guard.blueprint_enforcement || "warn"
   };
   const personality = essence.dna.personality || [];
-  let themeData;
-  let recipeData;
-  try {
+  let themeData = prefetchedThemeData;
+  let recipeData = prefetchedRecipeData;
+  if (!themeData) try {
     const themeResult = await registry.fetchTheme(themeName);
     if (themeResult?.data) {
-      const t = themeResult.data;
+      const raw = themeResult.data;
+      const t = raw.data ?? raw;
       themeData = {
         seed: t.seed,
         palette: t.palette,
@@ -1298,18 +1495,66 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
     }
   } catch {
   }
-  try {
+  if (!recipeData) try {
     const recipeResult = await registry.fetchRecipe(recipeName);
     if (recipeResult?.data) {
-      const r = recipeResult.data;
+      const raw = recipeResult.data;
+      const r = raw.data ?? raw;
       recipeData = {
         decorators: r.decorators,
         spatial_hints: r.spatial_hints,
         radius_hints: r.radius_hints
       };
+      if (!recipeData.decorators && raw.data) {
+        const inner = raw.data;
+        if (inner.decorators) {
+          recipeData.decorators = inner.decorators;
+          recipeData.spatial_hints = inner.spatial_hints;
+          recipeData.radius_hints = inner.radius_hints;
+        }
+      }
     }
   } catch {
   }
+  if (!recipeData?.decorators || Object.keys(recipeData.decorators).length === 0) {
+    try {
+      const apiUrl = registry.apiUrl || "https://api.decantr.ai/v1";
+      const resp = await fetch(`${apiUrl}/recipes/@official/${recipeName}`);
+      if (resp.ok) {
+        const apiData = await resp.json();
+        const inner = apiData.data ?? apiData;
+        if (inner.decorators && Object.keys(inner.decorators).length > 0) {
+          recipeData = {
+            decorators: inner.decorators,
+            spatial_hints: inner.spatial_hints,
+            radius_hints: inner.radius_hints
+          };
+        }
+      }
+    } catch {
+    }
+  }
+  if (!themeData?.seed?.primary) {
+    try {
+      const apiUrl = registry.apiUrl || "https://api.decantr.ai/v1";
+      const resp = await fetch(`${apiUrl}/themes/@official/${themeName}`);
+      if (resp.ok) {
+        const apiData = await resp.json();
+        const inner = apiData.data ?? apiData;
+        if (inner.seed) {
+          themeData = {
+            seed: inner.seed,
+            palette: inner.palette,
+            cvd_support: inner.cvd_support,
+            tokens: inner.tokens,
+            typography_hints: inner.typography_hints,
+            motion_hints: inner.motion_hints
+          };
+        }
+      }
+    } catch {
+    }
+  }
   const stylesDir = join(projectRoot, "src", "styles");
   mkdirSync(stylesDir, { recursive: true });
   const tokensPath = join(stylesDir, "tokens.css");
@@ -1322,15 +1567,39 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
   if (hasRealRecipeData || !existsSync(decoratorsPath)) {
     writeFileSync(decoratorsPath, generateDecoratorsCSS(recipeData, themeName));
   }
-  const cssFiles = [tokensPath, decoratorsPath];
+  const globalPath = join(stylesDir, "global.css");
+  if (!existsSync(globalPath)) {
+    writeFileSync(globalPath, generateGlobalCSS(personality));
+  }
+  const cssFiles = [tokensPath, decoratorsPath, globalPath];
+  const decoratorsMdPath = join(contextDir, "decorators.md");
+  writeFileSync(decoratorsMdPath, generateDecoratorsContext(recipeData, recipeName));
   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 hasSections = essence.blueprint.sections && essence.blueprint.sections.length > 0;
+  const contextFiles = [decoratorsMdPath];
+  if (!hasSections) {
+    const summaryPath = join(contextDir, "essence-summary.md");
+    writeFileSync(summaryPath, generateEssenceSummaryV3(essence));
+    contextFiles.push(summaryPath);
+  }
+  if (!options?.isInitialScaffold) {
+    const addPagePath = join(contextDir, "task-add-page.md");
+    writeFileSync(addPagePath, generateTaskContextV3("task-add-page.md.template", essence));
+    contextFiles.push(addPagePath);
+    const modifyPath = join(contextDir, "task-modify.md");
+    writeFileSync(modifyPath, generateTaskContextV3("task-modify.md.template", essence));
+    contextFiles.push(modifyPath);
+  }
   const blueprint = essence.blueprint;
   const sections = blueprint.sections && blueprint.sections.length > 0 ? blueprint.sections : [];
   if (sections.length > 0) {
+    const primarySectionShell = sections.find((s) => s.role === "primary")?.shell || "sidebar-main";
+    for (const section of sections) {
+      if (section.shell === "inherit") {
+        section.shell = primarySectionShell;
+      }
+    }
     const patternSpecs = {};
     const seenPatterns = /* @__PURE__ */ new Set();
     for (const section of sections) {
@@ -1347,13 +1616,36 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
                   const inner = raw.data ?? raw;
                   const defaultPreset = inner.default_preset || "standard";
                   const preset = inner.presets?.[defaultPreset];
-                  patternSpecs[name] = {
+                  let slots = preset?.layout?.slots || {};
+                  if (Object.keys(slots).length === 0) {
+                    const synthetic = generateSyntheticSlots(name, inner.description || "");
+                    if (Object.keys(synthetic).length > 0) {
+                      slots = synthetic;
+                    }
+                  }
+                  const spec = {
                     description: inner.description || "",
                     components: inner.components || [],
-                    slots: preset?.layout?.slots || {}
+                    slots
                   };
+                  if (!spec.components || spec.components.length === 0) {
+                    const syntheticComps = generateSyntheticComponents(name, spec.description);
+                    if (syntheticComps.length > 0) spec.components = syntheticComps;
+                  }
+                  patternSpecs[name] = spec;
+                } else {
+                  const synthetic = generateSyntheticSlots(name, "");
+                  const syntheticComps = generateSyntheticComponents(name, "");
+                  if (Object.keys(synthetic).length > 0 || syntheticComps.length > 0) {
+                    patternSpecs[name] = { description: "", components: syntheticComps, slots: synthetic };
+                  }
                 }
               } catch {
+                const synthetic = generateSyntheticSlots(name, "");
+                const syntheticComps = generateSyntheticComponents(name, "");
+                if (Object.keys(synthetic).length > 0 || syntheticComps.length > 0) {
+                  patternSpecs[name] = { description: "", components: syntheticComps, slots: synthetic };
+                }
               }
             }
           }
@@ -1423,8 +1715,17 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
       }
     }
     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 zoneLabel = section.role === "primary" || section.role === "auxiliary" ? "App" : section.role === "gateway" ? "Gateway" : "Public";
+      let zoneContext = `**Zone:** ${zoneLabel} (${section.role}) \u2014 ${section.shell} shell`;
+      if (section.role === "gateway") {
+        zoneContext += "\nAuth success \u2192 enters App zone. Sign out returns here.";
+      } else if (section.role === "primary") {
+        zoneContext += "\nAuthenticated users land here. Sign out \u2192 Gateway (/login).";
+      } else if (section.role === "public") {
+        zoneContext += "\nAnonymous visitors. CTAs lead to Gateway (/login, /register).";
+      } else if (section.role === "auxiliary") {
+        zoneContext += "\nSupporting section within App zone. Shares navigation with primary.";
+      }
       const sectionPatterns = {};
       for (const page of section.pages) {
         for (const item of page.layout) {
@@ -1496,13 +1797,36 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
                 const inner = raw.data ?? raw;
                 const defaultPreset = inner.default_preset || "standard";
                 const preset = inner.presets?.[defaultPreset];
-                patternSpecs[name] = {
+                let slots = preset?.layout?.slots || {};
+                if (Object.keys(slots).length === 0) {
+                  const synthetic = generateSyntheticSlots(name, inner.description || "");
+                  if (Object.keys(synthetic).length > 0) {
+                    slots = synthetic;
+                  }
+                }
+                const spec = {
                   description: inner.description || "",
                   components: inner.components || [],
-                  slots: preset?.layout?.slots || {}
+                  slots
                 };
+                if (!spec.components || spec.components.length === 0) {
+                  const syntheticComps = generateSyntheticComponents(name, spec.description);
+                  if (syntheticComps.length > 0) spec.components = syntheticComps;
+                }
+                patternSpecs[name] = spec;
+              } else {
+                const synthetic = generateSyntheticSlots(name, "");
+                const syntheticComps = generateSyntheticComponents(name, "");
+                if (Object.keys(synthetic).length > 0 || syntheticComps.length > 0) {
+                  patternSpecs[name] = { description: "", components: syntheticComps, slots: synthetic };
+                }
               }
             } catch {
+              const synthetic = generateSyntheticSlots(name, "");
+              const syntheticComps = generateSyntheticComponents(name, "");
+              if (Object.keys(synthetic).length > 0 || syntheticComps.length > 0) {
+                patternSpecs[name] = { description: "", components: syntheticComps, slots: synthetic };
+              }
             }
           }
         }
@@ -1565,8 +1889,95 @@ async function refreshDerivedFiles(projectRoot, essence, registry) {
     cssFiles
   };
 }
+function generateSyntheticSlots(patternId, description) {
+  const desc = description.toLowerCase();
+  const syntheticSlots = {};
+  if (patternId.includes("feature") || desc.includes("feature")) {
+    syntheticSlots["grid"] = "Grid of feature cards (icon + title + description)";
+    syntheticSlots["feature-card"] = "Individual feature with icon, heading, and description text";
+  }
+  if (patternId.includes("pricing") || desc.includes("pricing")) {
+    syntheticSlots["tiers"] = "Pricing tier cards (name, price, features list, CTA button)";
+    syntheticSlots["toggle"] = "Monthly/annual billing toggle (optional)";
+  }
+  if (patternId.includes("testimonial") || desc.includes("testimonial")) {
+    syntheticSlots["quotes"] = "Testimonial cards (quote text, author name, role, avatar)";
+  }
+  if (patternId.includes("cta") || desc.includes("call-to-action") || desc.includes("call to action")) {
+    syntheticSlots["headline"] = "CTA headline text";
+    syntheticSlots["description"] = "Supporting description text";
+    syntheticSlots["actions"] = "CTA button(s)";
+  }
+  if (patternId.includes("how-it-works") || desc.includes("how it works") || desc.includes("timeline") || desc.includes("steps")) {
+    syntheticSlots["steps"] = "Numbered steps (step number, title, description)";
+  }
+  if (patternId.includes("team") || desc.includes("team")) {
+    syntheticSlots["members"] = "Team member cards (avatar, name, role)";
+  }
+  if (patternId.includes("story") || desc.includes("story") || desc.includes("about")) {
+    syntheticSlots["content"] = "Story/about narrative text content";
+  }
+  if (patternId.includes("values") || desc.includes("values")) {
+    syntheticSlots["values"] = "Value cards (icon/emoji, title, description)";
+  }
+  if (patternId.includes("form") || desc.includes("form") || desc.includes("contact")) {
+    syntheticSlots["fields"] = "Form fields (name, email, message, etc.)";
+    syntheticSlots["submit"] = "Submit button";
+  }
+  if (patternId.includes("content") || desc.includes("legal") || desc.includes("privacy") || desc.includes("policy")) {
+    syntheticSlots["body"] = "Long-form text content with headings and paragraphs";
+    syntheticSlots["toc"] = "Table of contents sidebar (optional)";
+  }
+  if (patternId.includes("settings") || desc.includes("settings") || desc.includes("preferences")) {
+    syntheticSlots["sections"] = "Settings sections (label, description, input/toggle)";
+  }
+  if (patternId.includes("security") || desc.includes("security") || desc.includes("password")) {
+    syntheticSlots["sections"] = "Security sections (password change, MFA toggle, session list)";
+  }
+  if (patternId.includes("session") || desc.includes("session")) {
+    syntheticSlots["list"] = "Active sessions list (device, location, last active, revoke button)";
+  }
+  if (patternId.includes("message") || desc.includes("message") || desc.includes("chat")) {
+    syntheticSlots["messages"] = "Message bubbles (user/assistant, content, timestamp)";
+  }
+  if (patternId.includes("input") && desc.includes("chat")) {
+    syntheticSlots["textarea"] = "Auto-expanding message input";
+    syntheticSlots["actions"] = "Attach file button, send button";
+  }
+  if (patternId.includes("empty") || desc.includes("empty")) {
+    syntheticSlots["illustration"] = "Empty state illustration or icon";
+    syntheticSlots["message"] = "Welcome/empty state message";
+    syntheticSlots["suggestions"] = "Suggested actions or prompts";
+  }
+  if (patternId.includes("header") && desc.includes("chat")) {
+    syntheticSlots["title"] = "Conversation title or model name";
+    syntheticSlots["actions"] = "Header action buttons (new chat, settings)";
+  }
+  return syntheticSlots;
+}
+function generateSyntheticComponents(patternId, description) {
+  const desc = description.toLowerCase();
+  const syntheticComponents = [];
+  if (patternId.includes("hero")) syntheticComponents.push("Button", "Icon", "Image");
+  if (patternId.includes("feature")) syntheticComponents.push("Card", "Icon", "Text");
+  if (patternId.includes("pricing")) syntheticComponents.push("Card", "Button", "Badge");
+  if (patternId.includes("testimonial")) syntheticComponents.push("Card", "Avatar", "Text");
+  if (patternId.includes("cta")) syntheticComponents.push("Button", "Text");
+  if (patternId.includes("form") || patternId.includes("contact")) syntheticComponents.push("Input", "Textarea", "Button", "Label");
+  if (patternId.includes("team")) syntheticComponents.push("Card", "Avatar", "Text");
+  if (patternId.includes("settings") || patternId.includes("security")) syntheticComponents.push("Card", "Toggle", "Input", "Button");
+  if (patternId.includes("message") || patternId.includes("chat")) syntheticComponents.push("Avatar", "Text", "CodeBlock");
+  if (patternId.includes("input") && desc.includes("chat")) syntheticComponents.push("Textarea", "Button", "Icon");
+  if (patternId.includes("header") && desc.includes("chat")) syntheticComponents.push("Button", "Icon", "Text");
+  if (patternId.includes("content") || patternId.includes("legal")) syntheticComponents.push("Heading", "Text", "List");
+  if (patternId.includes("how-it-works") || patternId.includes("steps")) syntheticComponents.push("Card", "Icon", "Text", "Badge");
+  if (patternId.includes("values")) syntheticComponents.push("Card", "Icon", "Text");
+  if (patternId.includes("story") || patternId.includes("about")) syntheticComponents.push("Text", "Image");
+  if (patternId.includes("empty") || patternId.includes("new")) syntheticComponents.push("Icon", "Text", "Button");
+  return [...new Set(syntheticComponents)];
+}
 function generateSectionContext(input) {
-  const { section, themeTokens, decorators, guardConfig, personality, themeName, recipeName, zoneContext, patternSpecs, recipeHints, constraints, shellInfo } = input;
+  const { section, decorators, guardConfig, personality, themeName, recipeName, zoneContext, patternSpecs, recipeHints, constraints, shellInfo } = input;
   const lines = [];
   lines.push(`# Section: ${section.id}`);
   lines.push("");
@@ -1587,40 +1998,16 @@ function generateSectionContext(input) {
   lines.push("");
   lines.push("---");
   lines.push("");
-  lines.push("## Guard Rules");
+  lines.push(`**Guard:** ${guardConfig.mode} mode | DNA violations = ${guardConfig.dna_enforcement} | Blueprint violations = ${guardConfig.blueprint_enforcement}`);
   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(`**Theme tokens:** see \`src/styles/tokens.css\` \u2014 use \`var(--d-primary)\`, \`var(--d-bg)\`, etc.`);
   lines.push("");
   if (decorators.length > 0) {
-    lines.push("| Decorator | Description |");
-    lines.push("|-----------|-------------|");
-    for (const dec of decorators) {
-      lines.push(`| ${dec.name} | ${dec.description} |`);
-    }
+    const names = decorators.map((d) => `\`${d.name}\``).join(", ");
+    lines.push(`**Decorators:** ${names} (see \`src/styles/decorators.css\`)`);
+    lines.push("Usage: `className={css('_flex _col') + ' carbon-card'}` \u2014 atoms via css(), decorators as plain class strings.");
   } else {
-    lines.push("No decorators defined.");
+    lines.push("**Decorators:** none defined.");
   }
   lines.push("");
   if (recipeHints) {
@@ -1638,11 +2025,8 @@ function generateSectionContext(input) {
   lines.push("---");
   lines.push("");
   if (zoneContext) {
-    lines.push("## Zone Context");
-    lines.push("");
     lines.push(zoneContext);
-    lines.push("");
-    lines.push("---");
+    lines.push("For full app topology, see `.decantr/context/scaffold.md`");
     lines.push("");
   }
   if (section.features.length > 0) {
@@ -1654,11 +2038,7 @@ function generateSectionContext(input) {
     lines.push("");
   }
   if (personality.length > 0) {
-    lines.push("## Personality");
-    lines.push("");
-    lines.push(personality.join(", "));
-    lines.push("");
-    lines.push("---");
+    lines.push("**Personality:** See scaffold.md for personality and visual direction.");
     lines.push("");
   }
   if (constraints && Object.keys(constraints).length > 0) {
@@ -1671,6 +2051,34 @@ function generateSectionContext(input) {
     lines.push("---");
     lines.push("");
   }
+  const uniquePatterns = /* @__PURE__ */ new Map();
+  for (const page of section.pages) {
+    const patternNames = page.layout.flatMap(extractPatternNames);
+    for (const name of patternNames) {
+      if (patternSpecs[name] && !uniquePatterns.has(name)) {
+        uniquePatterns.set(name, patternSpecs[name]);
+      }
+    }
+  }
+  if (uniquePatterns.size > 0) {
+    lines.push("## Pattern Reference");
+    lines.push("");
+    for (const [patternName, spec] of uniquePatterns) {
+      lines.push(`### ${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("");
+    }
+    lines.push("---");
+    lines.push("");
+  }
   lines.push("## Pages");
   lines.push("");
   for (const page of section.pages) {
@@ -1691,22 +2099,6 @@ function generateSectionContext(input) {
       }
       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");
 }
@@ -1925,12 +2317,22 @@ var RegistryClient = class {
     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 {
+      for (let attempt = 0; attempt < 2; attempt++) {
+        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 (e) {
+          if (process.env.DECANTR_DEBUG) {
+            console.error(`  [debug] API fetch ${attempt === 0 ? "failed" : "retry failed"} for ${contentType}/${namespace}/${id}: ${e.message}`);
+          }
+          if (attempt === 0) {
+            await new Promise((r) => setTimeout(r, 500));
+          }
+        }
       }
+    } else if (process.env.DECANTR_DEBUG) {
+      console.error(`  [debug] Skipping API (offline mode) for ${contentType}/${namespace}/${id}`);
     }
     return loadFromCache(this.cacheDir, contentType, id, namespace);
   }
@@ -1992,9 +2394,12 @@ async function syncRegistry(cacheDir, apiUrl = DEFAULT_API_URL) {
       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");
+        const slug = item.slug;
+        const data = item.data;
+        const innerSlug = data?.id || data?.slug;
+        const cacheKey = slug || innerSlug || item.id;
+        if (cacheKey) {
+          saveToCache(cacheDir, type, cacheKey, item, "@official");
         }
       }
       synced.push(type);