@decantr/cli 1.7.1 → 1.7.5

package/dist/{chunk-X4RHL7WQ.js → chunk-H4H3IQJK.js}

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } fr
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { computeSpatialTokens } from "@decantr/essence-spec";
+import { compileExecutionPackBundle } from "@decantr/core";
 
 // src/treatments.ts
 function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators, themeName) {
@@ -49,7 +50,7 @@ ${themeBody}
     ["display", "inline-flex"],
     ["align-items", "center"],
     ["gap", "0.5em"],
-    ["padding", "var(--d-interactive-py) var(--d-interactive-px)"],
+    ["padding", "calc(var(--d-interactive-py) * var(--d-density-scale, 1)) var(--d-interactive-px)"],
     ["border", "1px solid var(--d-border)"],
     ["border-radius", "var(--d-radius)"],
     ["background", "transparent"],
@@ -98,7 +99,7 @@ ${themeBody}
     ["border", "1px solid var(--d-border)"],
     ["border-radius", "var(--d-radius)"],
     ["box-shadow", "var(--d-shadow)"],
-    ["padding", "var(--d-surface-p)"]
+    ["padding", "calc(var(--d-surface-p) * var(--d-density-scale, 1))"]
   ]);
   emitRule('.d-surface[data-elevation="raised"]', [
     ["background", "var(--d-surface-raised)"],
@@ -124,7 +125,7 @@ ${themeBody}
     ["font-size", "0.875rem"]
   ]);
   emitRule(".d-data-header", [
-    ["padding", "var(--d-data-py) var(--d-content-gap)"],
+    ["padding", "calc(var(--d-data-py) * var(--d-density-scale, 1)) var(--d-content-gap)"],
     ["font-weight", "500"],
     ["color", "var(--d-text-muted)"],
     ["border-bottom", "1px solid var(--d-border)"],
@@ -140,13 +141,13 @@ ${themeBody}
     ["background", "var(--d-surface)"]
   ]);
   emitRule(".d-data-cell", [
-    ["padding", "var(--d-data-py) var(--d-content-gap)"],
+    ["padding", "calc(var(--d-data-py) * var(--d-density-scale, 1)) var(--d-content-gap)"],
     ["vertical-align", "middle"]
   ]);
   emitRule(".d-control", [
     ["background", "var(--d-surface)"],
     ["color", "var(--d-text)"],
-    ["padding", "var(--d-control-py) 0.75rem"],
+    ["padding", "calc(var(--d-control-py) * var(--d-density-scale, 1)) 0.75rem"],
     ["border-radius", "var(--d-radius)"],
     ["border", "1px solid var(--d-border)"],
     ["width", "100%"],
@@ -170,16 +171,21 @@ ${themeBody}
     ["box-shadow", "0 0 0 3px color-mix(in srgb, var(--d-error) 15%, transparent)"]
   ]);
   emitRule(".d-section", [
-    ["padding", "var(--d-section-py) 0"]
+    ["--d-density-scale", "1"],
+    ["padding", "calc(var(--d-section-py) * var(--d-density-scale)) 0"]
   ]);
+  lines.push('.d-section[data-density="compact"] {');
+  lines.push("  --d-density-scale: 0.65;");
+  lines.push("}");
+  lines.push("");
+  lines.push('.d-section[data-density="spacious"] {');
+  lines.push("  --d-density-scale: 1.4;");
+  lines.push("}");
+  lines.push("");
   lines.push(".d-section + .d-section {");
   lines.push("  border-top: 1px solid transparent;");
   lines.push("  border-image: linear-gradient(to right, transparent, var(--d-border), transparent) 1;");
-  lines.push("  margin-top: var(--d-gap-2);");
-  lines.push("}");
-  lines.push("");
-  lines.push('.d-section[data-density="compact"] {');
-  lines.push("  padding: calc(var(--d-section-py) * 0.5) 0;");
+  lines.push("  margin-top: calc(var(--d-section-gap) * var(--d-density-scale, 1));");
   lines.push("}");
   lines.push("");
   emitRule(".d-annotation", [
@@ -189,6 +195,7 @@ ${themeBody}
     ["font-size", "0.75rem"],
     ["font-weight", "500"],
     ["padding", "0.125rem 0.5rem"],
+    ["margin-top", "calc(var(--d-annotation-mt) * var(--d-density-scale, 1))"],
     ["border-radius", "var(--d-radius-full)"],
     ["background", "var(--d-surface)"],
     ["color", "var(--d-text-muted)"],
@@ -216,7 +223,13 @@ ${themeBody}
     ["text-transform", "uppercase"],
     ["letter-spacing", "0.08em"],
     ["color", "var(--d-text-muted)"],
-    ["font-family", "var(--d-font-mono, ui-monospace, monospace)"]
+    ["font-family", "var(--d-font-mono, ui-monospace, monospace)"],
+    ["display", "block"],
+    ["margin-bottom", "calc(var(--d-label-mb) * var(--d-density-scale, 1))"]
+  ]);
+  emitRule(".d-label[data-anchor]", [
+    ["padding-left", "var(--d-label-px)"],
+    ["border-left", "2px solid var(--d-accent)"]
   ]);
   if (themeOverrideRules.length > 0) {
     lines.push("/* \u2500\u2500 Theme-scoped Treatment Overrides \u2500\u2500 */");
@@ -275,7 +288,62 @@ function generatePersonalityCSS(personality, themeData) {
 }
 
 // src/scaffold.ts
+import { API_CONTENT_TYPES } from "@decantr/registry";
 var __dirname = dirname(fileURLToPath(import.meta.url));
+function getPlatformMeta(target) {
+  const normalized = (target || "react").toLowerCase();
+  const routing = normalized === "nextjs" ? "pathname" : "hash";
+  return {
+    type: "spa",
+    routing
+  };
+}
+function getLegacyBlueprintId(meta) {
+  return meta.blueprint;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getStringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function toPatternReferenceObject(ref) {
+  return typeof ref === "string" ? { pattern: ref } : ref;
+}
+function collectPatternIdsFromValue(value, ids) {
+  if (typeof value === "string") {
+    ids.add(value);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  if ("pattern" in value && typeof value.pattern === "string") {
+    ids.add(value.pattern);
+  }
+  if ("cols" in value && Array.isArray(value.cols)) {
+    for (const col of value.cols) collectPatternIdsFromValue(col, ids);
+  }
+}
+function collectPatternIdsFromItems(items) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const item of items) collectPatternIdsFromValue(item, ids);
+  return [...ids];
+}
+function mapRegistryArchetypeToArchetypeData(archetype) {
+  return {
+    id: archetype.id,
+    name: archetype.name,
+    role: archetype.role,
+    description: archetype.description,
+    pages: archetype.pages?.map((page) => ({
+      id: page.id,
+      shell: page.shell,
+      default_layout: page.default_layout?.length ? page.default_layout : ["hero"],
+      patterns: page.patterns?.map(toPatternReferenceObject)
+    })),
+    features: archetype.features,
+    seo_hints: archetype.seo_hints
+  };
+}
 function composeArchetypes(composeEntries, archetypeResults) {
   if (composeEntries.length === 0) {
     return {
@@ -298,7 +366,7 @@ function composeArchetypes(composeEntries, archetypeResults) {
       for (const page of data.pages) {
         allPages.push({
           id: page.id,
-          layout: page.default_layout?.length ? page.default_layout : ["hero"],
+          layout: (page.default_layout?.length ? page.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, page.patterns)),
           ...page.shell !== defaultShell ? { shell_override: page.shell } : {}
         });
       }
@@ -307,7 +375,7 @@ function composeArchetypes(composeEntries, archetypeResults) {
       for (const page of data.pages) {
         allPages.push({
           id: `${prefix}-${page.id}`,
-          layout: page.default_layout?.length ? page.default_layout : ["hero"],
+          layout: (page.default_layout?.length ? page.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, page.patterns)),
           ...page.shell !== defaultShell ? { shell_override: page.shell } : {}
         });
       }
@@ -359,7 +427,7 @@ function composeSections(composeEntries, archetypeResults, overrides) {
       const overriddenPage = overrides?.pages?.[page.id];
       pages.push({
         id: page.id,
-        layout: page.default_layout?.length ? page.default_layout : ["hero"],
+        layout: (page.default_layout?.length ? page.default_layout : ["hero"]).map((item) => resolvePatternAlias(item, page.patterns)),
         ...overriddenPage
       });
     }
@@ -521,6 +589,24 @@ function generateTopologySection(data, personality) {
   return lines.join("\n");
 }
 var CLI_VERSION = "1.0.0";
+function mapRegistryThemeToThemeData(theme) {
+  return {
+    seed: theme.seed,
+    palette: theme.palette,
+    tokens: theme.tokens,
+    cvd_support: theme.cvd_support,
+    typography: theme.typography,
+    motion: theme.motion,
+    decorators: theme.decorators,
+    treatments: theme.treatments,
+    spatial: theme.spatial,
+    radius: theme.radius,
+    shell: theme.shell,
+    effects: theme.effects,
+    compositions: theme.compositions,
+    pattern_preferences: theme.pattern_preferences
+  };
+}
 function generateTokensCSS(themeData, mode, spatialTokens) {
   if (!themeData) {
     const spatialLines2 = spatialTokens ? "\n" + Object.entries(spatialTokens).map(([k, v]) => `  ${k}: ${v};`).join("\n") : "";
@@ -671,6 +757,26 @@ body {
   min-height: 100dvh;
 }
 
+.skip-link {
+  position: absolute;
+  top: 0.75rem;
+  left: 0.75rem;
+  z-index: 100;
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--d-radius);
+  background: var(--d-surface-raised);
+  color: var(--d-text);
+  text-decoration: none;
+  border: 1px solid var(--d-border);
+  transform: translateY(-150%);
+  transition: transform 0.15s ease;
+}
+
+.skip-link:focus,
+.skip-link:focus-visible {
+  transform: translateY(0);
+}
+
 img, picture, video, canvas, svg {
   display: block;
   max-width: 100%;
@@ -698,6 +804,15 @@ input, button, textarea, select {
   border-width: 0;
 }
 
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
 }
 `;
 }
@@ -861,10 +976,7 @@ function buildEssenceV3(options, archetypeData, themeHints) {
   const meta = {
     archetype: options.archetype || "custom",
     target: options.target,
-    platform: {
-      type: "spa",
-      routing: "hash"
-    },
+    platform: getPlatformMeta(options.target),
     guard: guardModeMap[options.guard] || guardModeMap.guided
   };
   return {
@@ -894,6 +1006,14 @@ import './styles/treatments.css';            // Treatments + theme decorators
 import './styles/global.css';                // Resets
 \`\`\`
 
+### Runtime Rules
+
+- Use the real \`@decantr/css\` runtime for atoms. If \`package.json\` does not already depend on \`@decantr/css\`, add it before building.
+- Do **not** create local atom-runtime substitutes such as \`src/lib/css.js\`, \`src/lib/css.ts\`, or hand-written \`src/styles/atoms.css\` files unless the task explicitly asks for a fallback runtime.
+- Keep atoms in \`css(...)\`, treatments as semantic classes, and theme decorators as additive classes. Do not blur those roles together.
+- Use \`d-control\` as the default semantic treatment for inputs, selects, and textareas. Theme decorators such as \`carbon-input\` are additive and should only layer on when the section or theme contract explicitly calls for them.
+- Use loading decorators such as \`carbon-skeleton\` as optional enhancement on top of a structurally correct loading state \u2014 they do not replace the need for a real loading/skeleton branch.
+
 ### Visual Treatments
 
 Six base treatment classes provide semantic styling. Combine with atoms for layout:
@@ -1032,16 +1152,26 @@ css('hover:_opacity80')
 | Atom | CSS |
 |------|-----|
 | \`_bgprimary\` | \`background:var(--d-primary)\` |
+| \`_bgaccent\` | \`background:var(--d-accent)\` |
+| \`_bgsecondary\` | \`background:var(--d-secondary)\` |
 | \`_bgsurface\` | \`background:var(--d-surface)\` |
 | \`_bgsurface0\`-\`_bgsurface2\` | surface elevation layers |
 | \`_bgmuted\` | \`background:var(--d-muted)\` |
 | \`_bgbg\` | \`background:var(--d-bg)\` |
+| \`_bgtransparent\` | \`background:transparent\` |
 | \`_bgsuccess\`, \`_bgerror\`, \`_bgwarning\`, \`_bginfo\` | status backgrounds |
 | \`_fgprimary\` | \`color:var(--d-primary)\` |
+| \`_fgaccent\` | \`color:var(--d-accent)\` |
+| \`_fgsecondary\` | \`color:var(--d-secondary)\` |
 | \`_fgtext\` | \`color:var(--d-text)\` |
 | \`_fgmuted\` | \`color:var(--d-text-muted)\` |
+| \`_fgwhite\`, \`_fgblack\`, \`_fginherit\` | absolute/inherited text colors |
 | \`_fgsuccess\`, \`_fgerror\`, \`_fgwarning\`, \`_fginfo\` | status text |
+| \`_bcprimary\` | \`border-color:var(--d-primary)\` |
+| \`_bcaccent\` | \`border-color:var(--d-accent)\` |
 | \`_bcborder\` | \`border-color:var(--d-border)\` |
+| \`_bcmuted\` | \`border-color:var(--d-muted)\` |
+| \`_bctransparent\` | \`border-color:transparent\` |
 
 #### Overflow & Whitespace
 | Atom | CSS |
@@ -1138,16 +1268,54 @@ If the essence defines hotkeys or command_palette, implement as keyboard event l
 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)
+- \`"pathname"\` \u2192 use pathname-based routing (e.g., Next.js App Router or React apps using \`BrowserRouter\`)
 
 Routes are defined in \`decantr.essence.json\` \u2192 \`blueprint.routes\` and listed in \`.decantr/context/scaffold.md\`.
 
+### SEO Expectations by Platform
+
+- For hash-routed SPA scaffolds, focus SEO work on the root document: document title, description, Open Graph/Twitter meta, and any root-level JSON-LD that the contract calls for.
+- Do **not** invent SSR-only per-route metadata systems for a clearly hash-routed scaffold.
+- For history/SSR-style projects, per-route metadata can be richer, but it still needs to follow the declared route contract instead of introducing off-contract marketing pages.
+
 ### Layout Rules
 
 1. **Never nest d-surface inside d-surface.** Inner sections use plain containers with padding atoms.
 2. **Shell regions are frames, not surfaces.** Sidebar and header use var(--d-surface) or var(--d-bg) directly. Apply d-surface only to content cards within the body region.
 3. **One scroll container per region.** Body has overflow-y-auto. Sidebar nav has its own overflow-y-auto. Never nest additional scrollable wrappers.
 4. **d-section spacing is self-contained.** Each d-section owns its padding. The d-section + d-section rule adds a separator. Do NOT add extra margin between adjacent sections.
-5. **Responsive nav rules.** Hamburger menus appear ONLY below the shell collapse breakpoint. Full nav shows above it.`;
+5. **Responsive nav rules.** Hamburger menus appear ONLY below the shell collapse breakpoint. Full nav shows above it.
+
+### Accessibility Defaults
+
+- If \`dna.accessibility.skip_nav = true\`, add a visible-on-focus skip link such as \`<a href="#main-content" className="skip-link">Skip to content</a>\`.
+- Pair that skip link with a real main landmark target such as \`<main id="main-content">\`.
+- Keep keyboard focus visible with \`:focus-visible\` treatments on custom interactive surfaces, not just browser defaults.
+- Implement shell-level accessibility and routing behaviors as reusable structure or shared helpers, not one-off inline patches. Compact header sizing, responsive sidebar collapse, and skip-nav targets should be consistent across the shell, not re-solved page by page.
+
+### Motion Philosophy
+
+Every interaction should feel responsive and polished. Apply motion by default, not as an afterthought:
+
+- **Page transitions:** Apply entrance-fade (or the personality entrance animation) to the main content area on route change
+- **Stagger children:** Lists, grids, and card groups should stagger-animate on mount (50-100ms delay per item)
+- **Data visualization:** Charts, gauges, progress bars, and counters should animate to their values on mount \u2014 never render static
+- **Micro-interactions:** All interactive elements (buttons, toggles, cards, nav items) need hover/press transitions. Use the motion tokens (--d-duration-hover, --d-easing) for consistency.
+- **Scroll reveals:** Sections below the fold should fade-in on scroll intersection (IntersectionObserver, once)
+- **Reduced motion:** Wrap all animations in \`prefers-reduced-motion\` media query \u2014 skip animation, keep state changes instant
+
+Never leave this to implication when \`dna.motion.reduce_motion = true\`. The scaffold should include a reviewed reduced-motion path in project CSS, even when the app initially runs on mock data.
+
+### Interactivity Philosophy
+
+Build for wow factor. When a pattern describes a canvas, graph, map, or spatial visualization, implement it as a **fully interactive surface**, not a static illustration:
+
+- **Drag and drop:** Nodes, cards, and items on spatial canvases should be draggable. Use pointer events with proper grab/grabbing cursors.
+- **Pan and zoom:** Canvases and large visualizations should support pan (click-drag on background) and zoom (scroll wheel or pinch). Show zoom level indicator.
+- **Connections:** When nodes exist in a graph/topology view, they should have visible connection lines. Implement click-to-select + click-target for connecting nodes.
+- **Live state:** Data-driven visualizations should update in real-time with simulated data. Status changes should animate (color transitions, pulse effects).
+- **Direct manipulation:** Prefer drag-to-reorder over dropdown menus. Prefer inline editing over modal forms. Prefer resize handles over fixed layouts.
+- **Hover reveals:** Show contextual information (tooltips, expanded cards, action menus) on hover \u2014 don't require clicks to discover functionality.`;
 function generateDecantrMdV31(params) {
   const template = loadTemplate("DECANTR.md.template");
   const body = renderTemplate(template, {
@@ -1191,6 +1359,29 @@ function generateDecantrMdV31(params) {
     }
     briefLines.push("");
   }
+  briefLines.push("## Development Workflow");
+  briefLines.push("");
+  briefLines.push("The essence file (`decantr.essence.json`) is the source of truth for your project's structure. Context files in `.decantr/context/` are derived from it. When you need to add, remove, or modify pages, sections, or features:");
+  briefLines.push("");
+  briefLines.push("**1. Update the essence** (use CLI commands for consistency):");
+  briefLines.push("- `decantr add page {section}/{page} --route /{path}`");
+  briefLines.push("- `decantr add section {archetype}`");
+  briefLines.push("- `decantr add feature {name}` (or `--section {id}` for scoped)");
+  briefLines.push("- `decantr remove page {section}/{page}`");
+  briefLines.push("- `decantr remove section {id}`");
+  briefLines.push("- `decantr remove feature {name}`");
+  briefLines.push("- `decantr theme switch {name}`");
+  briefLines.push("");
+  briefLines.push("**2. Regenerate context:** `decantr refresh`");
+  briefLines.push("");
+  briefLines.push("**3. Read the updated context files**, then build.");
+  briefLines.push("");
+  briefLines.push("**Rules:**");
+  briefLines.push("- Never create page components for routes that don't exist in the essence");
+  briefLines.push("- Never delete pages without removing them from the essence");
+  briefLines.push("- Always refresh after mutations \u2014 stale context files lead to drift");
+  briefLines.push("- If you edit the essence directly, run `decantr refresh` before building");
+  briefLines.push("");
   briefLines.push("---");
   briefLines.push("");
   return briefLines.join("\n") + body;
@@ -1261,9 +1452,8 @@ function generateTaskContextV3(templateName, essence) {
   const contentGap = essence.dna.spacing?.content_gap || "_gap4";
   const vars = {
     TARGET: essence.meta.target || "react",
-    THEME_STYLE: essence.dna.theme.id || essence.dna.theme.style || "",
+    THEME_ID: essence.dna.theme.id || "",
     THEME_MODE: essence.dna.theme.mode,
-    THEME_RECIPE: essence.dna.theme.id || essence.dna.theme.style || "",
     DEFAULT_SHELL: defaultShell,
     GUARD_MODE: essence.meta.guard.mode,
     LAYOUT: layout,
@@ -1273,6 +1463,186 @@ function generateTaskContextV3(templateName, essence) {
   };
   return renderTemplate(template, vars);
 }
+function renderPackReferenceList(title, entries, fallback, summaryPath = ".decantr/context/pack-manifest.json") {
+  if (entries.length === 0) {
+    return `### ${title}
+
+- ${fallback}`;
+  }
+  if (entries.length <= 6) {
+    return `### ${title}
+
+${entries.map((entry) => `- ${entry}`).join("\n")}`;
+  }
+  return `### ${title}
+
+- ${entries.length} compiled references available. Use \`${summaryPath}\` to resolve the exact files for this scope.`;
+}
+function generateScaffoldTaskContext(essence, scaffoldPack, manifest) {
+  if (!scaffoldPack) {
+    return generateTaskContextV3("task-scaffold.md.template", essence);
+  }
+  const themeShape = scaffoldPack.data.theme.shape || "default";
+  const features = scaffoldPack.data.features.length > 0 ? scaffoldPack.data.features.join(", ") : "none";
+  const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
+    const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+  }).join("\n") : "- No routes declared";
+  const successChecks = scaffoldPack.successChecks.map((check) => `- [${check.severity}] ${check.label}`).join("\n");
+  const tokenStrategy = scaffoldPack.tokenBudget.strategy.map((item) => `- ${item}`).join("\n");
+  const sectionRefs = manifest?.sections.map(
+    (section) => `Section \`${section.id}\` -> \`.decantr/context/${section.markdown}\``
+  ) ?? [];
+  const pageRefs = manifest?.pages.map(
+    (page) => `Page \`${page.id}\` -> \`.decantr/context/${page.markdown}\``
+  ) ?? [];
+  return `# Task Context: Scaffolding
+
+**Enforcement Tier: Creative** \u2014 Guard rules are advisory during initial scaffolding.
+
+## Primary Compiled Contract
+
+- Start with \`.decantr/context/scaffold-pack.md\` for the compact route, shell, and theme contract.
+- Use \`.decantr/context/scaffold.md\` only as secondary detail when the compiled pack is not enough.
+- Read the route-local page packs before building each page so layout and wiring stay aligned with the compiled plan.
+
+## Generate This Application
+
+- Target: \`${scaffoldPack.target.adapter}\` (${scaffoldPack.target.framework || "unknown framework"})
+- Shell: \`${scaffoldPack.data.shell}\`
+- Theme: \`${scaffoldPack.data.theme.id}\` (${scaffoldPack.data.theme.mode}, ${themeShape})
+- Routing: \`${scaffoldPack.data.routing}\`
+- Features: ${features}
+
+## Route Plan
+
+${routePlan}
+
+${renderPackReferenceList("Section Packs", sectionRefs, "No section packs were generated for this scaffold.")}
+
+${renderPackReferenceList("Page Packs", pageRefs, "No page packs were generated for this scaffold.")}
+
+## Success Checks
+
+${successChecks}
+
+## Token Budget
+
+- Target: ${scaffoldPack.tokenBudget.target} tokens
+- Max: ${scaffoldPack.tokenBudget.max} tokens
+${tokenStrategy}
+
+Post-scaffold enforcement mode: **${essence.meta.guard.mode.toUpperCase()}**.
+
+---
+
+*Task context generated from Decantr execution packs*`;
+}
+function generateAddPageTaskContext(essence, scaffoldPack, manifest) {
+  if (!scaffoldPack) {
+    return generateTaskContextV3("task-add-page.md.template", essence);
+  }
+  const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
+    const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+  }).join("\n") : "- No routes declared";
+  const sectionRefs = manifest?.sections.map(
+    (section) => `Section \`${section.id}\` -> \`.decantr/context/${section.markdown}\``
+  ) ?? [];
+  const pageRefs = manifest?.pages.map(
+    (page) => `Page \`${page.id}\` -> \`.decantr/context/${page.markdown}\``
+  ) ?? [];
+  return `# Task Context: Adding Pages
+
+**Enforcement Tier: Guided**
+
+## Primary Compiled Contract
+
+- Start with \`.decantr/context/mutation-add-page-pack.md\` for the add-page workflow contract.
+- Use \`.decantr/context/scaffold-pack.md\` for the current route, shell, and theme contract.
+- Use \`.decantr/context/pack-manifest.json\` to choose the target section before you add a route.
+- After updating the essence, run \`npx @decantr/cli refresh\` so the new section/page packs exist before code generation.
+
+## Current Scaffold Contract
+
+- Target: \`${scaffoldPack.target.adapter}\` (${scaffoldPack.target.framework || "unknown framework"})
+- Shell: \`${scaffoldPack.data.shell}\`
+- Theme: \`${scaffoldPack.data.theme.id}\` (${scaffoldPack.data.theme.mode})
+- Existing routes: ${scaffoldPack.data.routes.length}
+
+## Existing Routes
+
+${routePlan}
+
+${renderPackReferenceList("Section Packs", sectionRefs, "No section packs were generated for this scaffold.")}
+
+${renderPackReferenceList("Page Packs", pageRefs, "No page packs were generated for this scaffold.")}
+
+## Required Workflow
+
+1. Add the new page to the essence before generating any code.
+2. Keep the new page inside a declared section and shell contract.
+3. Refresh derived files so Decantr recompiles the section and page packs.
+4. Read the relevant section pack and the new page pack before implementation.
+
+## Guided Checks
+
+- [error] Theme identity remains \`${scaffoldPack.data.theme.id}\` until the essence changes.
+- [error] The new page exists in the essence before code generation begins.
+- [error] New layouts only use registry-backed patterns.
+- [warn] New routes should fit the current shell and section topology instead of creating off-contract filler pages.
+
+---
+
+*Task context generated from Decantr execution packs*`;
+}
+function generateModifyTaskContext(essence, scaffoldPack, manifest) {
+  if (!scaffoldPack) {
+    return generateTaskContextV3("task-modify.md.template", essence);
+  }
+  const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
+    const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
+    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+  }).join("\n") : "- No routes declared";
+  const pageRefs = manifest?.pages.map(
+    (page) => `Page \`${page.id}\` -> \`.decantr/context/${page.markdown}\``
+  ) ?? [];
+  const successChecks = scaffoldPack.successChecks.map((check) => `- [${check.severity}] ${check.label}`).join("\n");
+  return `# Task Context: Modifying Code
+
+**Enforcement Tier: Strict**
+
+## Primary Compiled Contract
+
+- Start with \`.decantr/context/mutation-modify-pack.md\` for the strict modification workflow contract.
+- Start with \`decantr_get_page_context\` or the matching \`.decantr/context/page-*-pack.md\` file for the route you are editing.
+- Use \`decantr_get_section_context\` when you need the richer section contract behind that route.
+- If a change would alter route identity, shell identity, theme identity, or pattern contract, update the essence first and then refresh the packs.
+
+## Current Route Topology
+
+${routePlan}
+
+${renderPackReferenceList("Page Packs", pageRefs, "No page packs were generated for this scaffold.")}
+
+## Strict Workflow
+
+1. Identify the target page and read its compiled page pack first.
+2. Compare the planned edit against the compiled route, shell, and pattern contract.
+3. If the edit changes that contract, stop and update the essence before writing code.
+4. Run \`npx @decantr/cli validate\` and \`npx @decantr/cli check\` after the modification.
+
+## Strict Checks
+
+${successChecks}
+- [error] The page you modify must already exist in the compiled topology.
+- [error] Pattern order and shell usage should stay aligned with the page pack unless the essence changes first.
+- [warn] Use section context only as supporting detail; the page pack is the primary contract for route-local work.
+
+---
+
+*Task context generated from Decantr execution packs*`;
+}
 function generateEssenceSummaryV3(essence) {
   const template = loadTemplate("essence-summary.md.template");
   const blueprint = essence.blueprint;
@@ -1300,9 +1670,8 @@ ${rows.join("\n")}`;
     BLUEPRINT: "",
     PERSONALITY: (essence.dna.personality || []).join(", "),
     TARGET: essence.meta.target ?? "",
-    THEME_STYLE: essence.dna.theme.id ?? essence.dna.theme.style ?? "",
+    THEME_ID: essence.dna.theme.id ?? "",
     THEME_MODE: essence.dna.theme.mode,
-    THEME_RECIPE: essence.dna.theme.id ?? essence.dna.theme.style ?? "",
     SHAPE: essence.dna.theme.shape ?? "",
     PAGES_TABLE: pagesTable,
     FEATURES_LIST: featuresList,
@@ -1354,9 +1723,6 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
   }
   writeFileSync(projectJsonPath, JSON.stringify(projectJsonObj, null, 2));
   const contextFiles = [];
-  const scaffoldPath = join(contextDir, "task-scaffold.md");
-  writeFileSync(scaffoldPath, generateTaskContextV3("task-scaffold.md.template", essenceV3));
-  contextFiles.push(scaffoldPath);
   if (composedSections) {
     essenceV3.version = "3.1.0";
     essenceV3.blueprint = {
@@ -1393,7 +1759,7 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
 function scaffoldMinimal(projectRoot) {
   const decantrDir = join(projectRoot, ".decantr");
   const customDir = join(decantrDir, "custom");
-  const contentTypes = ["patterns", "themes", "blueprints", "archetypes", "shells"];
+  const contentTypes = API_CONTENT_TYPES;
   for (const type of contentTypes) {
     mkdirSync(join(customDir, type), { recursive: true });
   }
@@ -1451,10 +1817,7 @@ function scaffoldMinimal(projectRoot) {
     meta: {
       archetype: "custom",
       target: "react",
-      platform: {
-        type: "spa",
-        routing: "hash"
-      },
+      platform: getPlatformMeta("react"),
       guard: {
         mode: "guided",
         dna_enforcement: "error",
@@ -1578,6 +1941,76 @@ When available, use these tools:
     gitignoreUpdated
   };
 }
+function writeExecutionPackArtifacts(basePathWithoutExtension, pack) {
+  const markdownPath = `${basePathWithoutExtension}.md`;
+  const jsonPath = `${basePathWithoutExtension}.json`;
+  writeFileSync(markdownPath, pack.renderedMarkdown);
+  writeFileSync(jsonPath, JSON.stringify(pack, null, 2) + "\n");
+  return markdownPath;
+}
+function writeExecutionPackBundleArtifacts(contextDir, bundle) {
+  mkdirSync(contextDir, { recursive: true });
+  const outputPaths = [];
+  const scaffoldPackPath = writeExecutionPackArtifacts(join(contextDir, "scaffold-pack"), bundle.scaffold);
+  outputPaths.push(scaffoldPackPath);
+  const reviewPackPath = writeExecutionPackArtifacts(join(contextDir, "review-pack"), bundle.review);
+  outputPaths.push(reviewPackPath);
+  for (const sectionPack of bundle.sections) {
+    const sectionPackPath = writeExecutionPackArtifacts(
+      join(contextDir, `section-${sectionPack.data.sectionId}-pack`),
+      sectionPack
+    );
+    outputPaths.push(sectionPackPath);
+  }
+  for (const pagePack of bundle.pages) {
+    const pagePackPath = writeExecutionPackArtifacts(
+      join(contextDir, `page-${pagePack.data.pageId}-pack`),
+      pagePack
+    );
+    outputPaths.push(pagePackPath);
+  }
+  for (const mutationPack of bundle.mutations) {
+    const mutationPackPath = writeExecutionPackArtifacts(
+      join(contextDir, `mutation-${mutationPack.data.mutationType}-pack`),
+      mutationPack
+    );
+    outputPaths.push(mutationPackPath);
+  }
+  const manifestPath = join(contextDir, "pack-manifest.json");
+  writeFileSync(manifestPath, JSON.stringify(bundle.manifest, null, 2) + "\n");
+  outputPaths.push(manifestPath);
+  return {
+    paths: outputPaths,
+    scaffoldPackPath,
+    reviewPackPath,
+    manifestPath
+  };
+}
+async function generatePackContexts(projectRoot, contextDir, essence) {
+  const emptyResult = {
+    paths: [],
+    scaffoldPack: null,
+    manifest: null
+  };
+  const cacheRoot = join(projectRoot, ".decantr", "cache", "@official");
+  if (!existsSync(cacheRoot)) return emptyResult;
+  const customRoot = join(projectRoot, ".decantr", "custom");
+  const overridePaths = existsSync(customRoot) ? [customRoot] : void 0;
+  try {
+    const bundle = await compileExecutionPackBundle(essence, {
+      contentRoot: cacheRoot,
+      overridePaths
+    });
+    const writtenArtifacts = writeExecutionPackBundleArtifacts(contextDir, bundle);
+    return {
+      paths: writtenArtifacts.paths,
+      scaffoldPack: bundle.scaffold,
+      manifest: bundle.manifest
+    };
+  } catch {
+    return emptyResult;
+  }
+}
 async function resolvePatternSpec(name, registry, prefetched, includeExtendedFields = true) {
   if (prefetched && (prefetched.layout_hints || prefetched.visual_brief || !includeExtendedFields)) {
     if (!prefetched.components || prefetched.components.length === 0) {
@@ -1593,32 +2026,7 @@ async function resolvePatternSpec(name, registry, prefetched, includeExtendedFie
   try {
     const patResult = await registry.fetchPattern(name);
     if (patResult?.data) {
-      const inner = patResult.data;
-      const defaultPreset = inner.default_preset || "standard";
-      const preset = inner.presets?.[defaultPreset];
-      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 || prefetched?.description || "",
-        components: inner.components || prefetched?.components || [],
-        slots,
-        layout_hints: inner.layout_hints,
-        ...includeExtendedFields ? {
-          visual_brief: inner.visual_brief,
-          composition: inner.composition,
-          motion: inner.motion,
-          responsive: inner.responsive,
-          accessibility: inner.accessibility
-        } : {}
-      };
-      if (!spec.components || spec.components.length === 0) {
-        const syntheticComps2 = generateSyntheticComponents(name, spec.description);
-        if (syntheticComps2.length > 0) spec.components = syntheticComps2;
-      }
-      return spec;
+      return mapRegistryPatternToPatternSpecSummary(patResult.data, prefetched, includeExtendedFields);
     }
   } catch {
   }
@@ -1660,17 +2068,16 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     try {
       const bpResult = await registry.fetchBlueprint(storedBlueprintId);
       if (bpResult?.data) {
-        const bpData = bpResult.data;
-        if (bpData.voice) {
-          storedVoice = bpData.voice;
-          projectJsonData.voice = bpData.voice;
+        if (bpResult.data.voice) {
+          storedVoice = bpResult.data.voice;
+          projectJsonData.voice = bpResult.data.voice;
           writeFileSync(projectJsonFilePath, JSON.stringify(projectJsonData, null, 2));
         }
       }
     } catch {
     }
   }
-  const themeName = essence.dna.theme.id || essence.dna.theme.style || "default";
+  const themeName = essence.dna.theme.id || "default";
   const mode = essence.dna.theme.mode;
   const guardMode = essence.meta.guard.mode;
   const guardConfig = {
@@ -1683,29 +2090,13 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   if (!themeData) 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: t.typography,
-        motion: t.motion,
-        decorators: t.decorators,
-        treatments: t.treatments,
-        spatial: t.spatial,
-        radius: t.radius,
-        shell: t.shell,
-        effects: t.effects,
-        compositions: t.compositions,
-        pattern_preferences: t.pattern_preferences
-      };
+      themeData = mapRegistryThemeToThemeData(themeResult.data);
     }
   } catch {
   }
   if (!themeData?.seed?.primary) {
     try {
-      const apiUrl = registry.apiUrl || "https://api.decantr.ai/v1";
+      const apiUrl = registry.getApiUrl();
       const resp = await fetch(`${apiUrl}/themes/@official/${themeName}`);
       if (resp.ok) {
         const apiData = await resp.json();
@@ -1787,7 +2178,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   writeFileSync(decantrMdPath, generateDecantrMdV31({
     guardMode,
     cssApproach: CSS_APPROACH_CONTENT,
-    blueprintId: storedBlueprintId || essence.meta.blueprint || void 0,
+    blueprintId: storedBlueprintId || getLegacyBlueprintId(essence.meta) || void 0,
     themeName,
     themeMode: mode,
     themeShape: essence.dna.theme.shape || void 0,
@@ -1804,15 +2195,25 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     writeFileSync(summaryPath, generateEssenceSummaryV3(essence));
     contextFiles.push(summaryPath);
   }
+  const packContexts = await generatePackContexts(projectRoot, contextDir, essence);
+  const scaffoldTaskPath = join(contextDir, "task-scaffold.md");
+  writeFileSync(
+    scaffoldTaskPath,
+    generateScaffoldTaskContext(essence, packContexts.scaffoldPack, packContexts.manifest)
+  );
+  contextFiles.push(scaffoldTaskPath);
   if (!options?.isInitialScaffold) {
-    const scaffoldTaskPath = join(contextDir, "task-scaffold.md");
-    writeFileSync(scaffoldTaskPath, generateTaskContextV3("task-scaffold.md.template", essence));
-    contextFiles.push(scaffoldTaskPath);
     const addPagePath = join(contextDir, "task-add-page.md");
-    writeFileSync(addPagePath, generateTaskContextV3("task-add-page.md.template", essence));
+    writeFileSync(
+      addPagePath,
+      generateAddPageTaskContext(essence, packContexts.scaffoldPack, packContexts.manifest)
+    );
     contextFiles.push(addPagePath);
     const modifyPath = join(contextDir, "task-modify.md");
-    writeFileSync(modifyPath, generateTaskContextV3("task-modify.md.template", essence));
+    writeFileSync(
+      modifyPath,
+      generateModifyTaskContext(essence, packContexts.scaffoldPack, packContexts.manifest)
+    );
     contextFiles.push(modifyPath);
   }
   const blueprint = essence.blueprint;
@@ -1878,16 +2279,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
         try {
           const shellResult = await registry.fetchShell(shellId);
           if (shellResult?.data) {
-            const inner = shellResult.data;
-            shellInfoCache[shellId] = {
-              description: inner.description || "",
-              regions: inner.config?.regions || [],
-              layout: inner.layout || void 0,
-              guidance: inner.guidance || void 0,
-              atoms: inner.atoms || void 0,
-              config: inner.config || void 0,
-              internal_layout: inner.internal_layout || void 0
-            };
+            shellInfoCache[shellId] = mapRegistryShellToShellInfo(shellResult.data);
           }
         } catch {
         }
@@ -1916,6 +2308,12 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
           }
         }
       }
+      const sectionSpatialHints = themeData?.spatial ? {
+        section_padding: themeData.spatial.section_padding ?? void 0,
+        density_bias: typeof themeData.spatial.density_bias === "number" ? themeData.spatial.density_bias : void 0,
+        content_gap_shift: themeData.spatial.content_gap_shift,
+        label_content_gap: themeData.spatial.label_content_gap ?? void 0
+      } : void 0;
       const contextContent = generateSectionContext({
         section,
         themeTokens: themeTokensCss,
@@ -1934,7 +2332,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
         shellInfo: shellInfoCache[section.shell],
         themeData,
         themeMode: mode,
-        voiceTone: storedVoice?.tone ? storedVoice.tone.split(".")[0] + "." : void 0
+        voiceTone: storedVoice?.tone ? storedVoice.tone.split(".")[0] + "." : void 0,
+        spatialHints: sectionSpatialHints
       });
       const sectionContextPath = join(contextDir, `section-${section.id}.md`);
       writeFileSync(sectionContextPath, contextContent);
@@ -1943,7 +2342,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     const routes = blueprint.routes || {};
     const scaffoldContent = generateScaffoldContext({
       appName: essence.meta.archetype || "Application",
-      blueprintId: storedBlueprintId || essence.meta.blueprint || "",
+      blueprintId: storedBlueprintId || getLegacyBlueprintId(essence.meta) || "",
       themeName,
       personality,
       topologyMarkdown,
@@ -1994,19 +2393,16 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     try {
       const shellResult = await registry.fetchShell(shell);
       if (shellResult?.data) {
-        const inner = shellResult.data;
-        v30ShellInfo = {
-          description: inner.description || "",
-          regions: inner.config?.regions || [],
-          layout: inner.layout || void 0,
-          guidance: inner.guidance || void 0,
-          atoms: inner.atoms || void 0,
-          config: inner.config || void 0,
-          internal_layout: inner.internal_layout || void 0
-        };
+        v30ShellInfo = mapRegistryShellToShellInfo(shellResult.data);
       }
     } catch {
     }
+    const v30SpatialHints = themeData?.spatial ? {
+      section_padding: themeData.spatial.section_padding ?? void 0,
+      density_bias: typeof themeData.spatial.density_bias === "number" ? themeData.spatial.density_bias : void 0,
+      content_gap_shift: themeData.spatial.content_gap_shift,
+      label_content_gap: themeData.spatial.label_content_gap ?? void 0
+    } : void 0;
     const contextContent = generateSectionContext({
       section: syntheticSection,
       themeTokens: themeTokensCss,
@@ -2025,12 +2421,16 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       shellInfo: v30ShellInfo,
       themeData,
       themeMode: mode,
-      voiceTone: storedVoice?.tone ? storedVoice.tone.split(".")[0] + "." : void 0
+      voiceTone: storedVoice?.tone ? storedVoice.tone.split(".")[0] + "." : void 0,
+      spatialHints: v30SpatialHints
     });
     const sectionContextPath = join(contextDir, `section-${syntheticSection.id}.md`);
     writeFileSync(sectionContextPath, contextContent);
     contextFiles.push(sectionContextPath);
   }
+  if (packContexts.paths.length > 0) {
+    contextFiles.push(...packContexts.paths);
+  }
   return {
     decantrMdPath,
     contextFiles,
@@ -2124,6 +2524,50 @@ function generateSyntheticComponents(patternId, description) {
   if (patternId.includes("empty") || patternId.includes("new")) syntheticComponents.push("Icon", "Text", "Button");
   return [...new Set(syntheticComponents)];
 }
+function mapRegistryPatternToPatternSpecSummary(pattern, prefetched, includeExtendedFields = true) {
+  const defaultPreset = pattern.default_preset || "standard";
+  const preset = pattern.presets?.[defaultPreset];
+  let slots = preset?.layout?.slots || pattern.default_layout?.slots || prefetched?.slots || {};
+  if (Object.keys(slots).length === 0) {
+    const synthetic = generateSyntheticSlots(pattern.id, pattern.description || prefetched?.description || "");
+    if (Object.keys(synthetic).length > 0) slots = synthetic;
+  }
+  const spec = {
+    description: pattern.description || prefetched?.description || "",
+    components: pattern.components || prefetched?.components || [],
+    slots,
+    layout_hints: pattern.layout_hints,
+    ...includeExtendedFields ? {
+      visual_brief: pattern.visual_brief,
+      composition: pattern.composition,
+      motion: pattern.motion,
+      responsive: pattern.responsive,
+      accessibility: pattern.accessibility ? {
+        role: pattern.accessibility.role,
+        keyboard: pattern.accessibility.keyboard,
+        announcements: pattern.accessibility.announcements,
+        focus_management: pattern.accessibility.focus_management
+      } : void 0
+    } : {}
+  };
+  if (!spec.components || spec.components.length === 0) {
+    const syntheticComps = generateSyntheticComponents(pattern.id, spec.description);
+    if (syntheticComps.length > 0) spec.components = syntheticComps;
+  }
+  return spec;
+}
+function mapRegistryShellToShellInfo(shell) {
+  const config = isRecord(shell.config) ? shell.config : void 0;
+  return {
+    description: shell.description || "",
+    regions: getStringArray(config?.regions),
+    layout: shell.layout || void 0,
+    guidance: shell.guidance,
+    atoms: shell.atoms,
+    config,
+    internal_layout: isRecord(shell.internal_layout) ? shell.internal_layout : void 0
+  };
+}
 function generateShellImplementation(shellId, shellInfo) {
   const lines = [];
   lines.push(`## Shell Implementation (${shellId})`);
@@ -2132,9 +2576,9 @@ function generateShellImplementation(shellId, shellInfo) {
     for (const [region, props] of Object.entries(shellInfo.internal_layout)) {
       lines.push(`### ${region}`);
       lines.push("");
-      if (typeof props === "object" && props !== null) {
+      if (isRecord(props)) {
         for (const [key, value] of Object.entries(props)) {
-          if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+          if (isRecord(value)) {
             lines.push(`- **${key}:**`);
             for (const [subKey, subValue] of Object.entries(value)) {
               lines.push(`  - ${subKey}: ${subValue}`);
@@ -2236,10 +2680,10 @@ function generateQuickStart(input) {
   lines.push("");
   return lines;
 }
-function generateSpacingGuide(density) {
+function generateSpacingGuide(density, spatialHints) {
   const lines = [];
   const level = density === "compact" || density === "spacious" ? density : "comfortable";
-  const tokens = computeSpatialTokens(level);
+  const tokens = computeSpatialTokens(level, spatialHints);
   lines.push("## Spacing Guide");
   lines.push("");
   lines.push("| Context | Token | Value | Usage |");
@@ -2251,11 +2695,15 @@ function generateSpacingGuide(density) {
   lines.push(`| Interactive H | \`--d-interactive-px\` | \`${tokens["--d-interactive-px"]}\` | Horizontal padding on buttons |`);
   lines.push(`| Control | \`--d-control-py\` | \`${tokens["--d-control-py"]}\` | Vertical padding on inputs |`);
   lines.push(`| Data row | \`--d-data-py\` | \`${tokens["--d-data-py"]}\` | Vertical padding on table rows |`);
+  lines.push(`| Label gap | \`--d-label-mb\` | \`${tokens["--d-label-mb"]}\` | Gap below d-label section headers |`);
+  lines.push(`| Label indent | \`--d-label-px\` | \`${tokens["--d-label-px"]}\` | Anchor indent for d-label[data-anchor] |`);
+  lines.push(`| Section gap | \`--d-section-gap\` | \`${tokens["--d-section-gap"]}\` | Gap between adjacent d-sections |`);
+  lines.push(`| Annotation gap | \`--d-annotation-mt\` | \`${tokens["--d-annotation-mt"]}\` | Top margin on d-annotation |`);
   lines.push("");
   return lines;
 }
 function generateSectionContext(input) {
-  const { section, decorators, guardConfig, personality, themeName, zoneContext, patternSpecs, themeHints, constraints, shellInfo } = input;
+  const { section, decorators, guardConfig, personality, themeName, zoneContext, patternSpecs, themeHints, constraints, shellInfo, spatialHints } = input;
   const lines = [];
   lines.push(`# Section: ${section.id}`);
   lines.push("");
@@ -2275,16 +2723,36 @@ function generateSectionContext(input) {
     lines.push(...generateShellImplementation(section.shell, shellInfo));
   }
   if (shellInfo?.guidance && Object.keys(shellInfo.guidance).length > 0) {
+    const labelTreatment = shellInfo.guidance.section_label_treatment;
+    const sectionDensity = shellInfo.guidance.section_density;
+    if (labelTreatment) {
+      lines.push("## Section Label Treatment");
+      lines.push("");
+      lines.push(`Apply \`${labelTreatment}\` to section headers in this shell.`);
+      lines.push("- Uppercase monospace label typography (d-label base treatment)");
+      if (labelTreatment.includes("[data-anchor]")) {
+        lines.push("- Left accent border anchor (data-anchor variant)");
+      }
+      lines.push("- Density-responsive bottom gap via `--d-label-mb` x `--d-density-scale`");
+      if (sectionDensity) {
+        const scaleMap = { compact: "0.65", comfortable: "1", spacious: "1.4" };
+        lines.push("");
+        lines.push(`Section density: ${sectionDensity} (--d-density-scale: ${scaleMap[sectionDensity] || "1"})`);
+      }
+      lines.push("");
+    }
+    const structuredKeys = /* @__PURE__ */ new Set(["section_label_treatment", "section_density"]);
     lines.push(`## Shell Notes (${section.shell})`);
     lines.push("");
     for (const [key, value] of Object.entries(shellInfo.guidance)) {
+      if (structuredKeys.has(key)) continue;
       const label = key.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
       lines.push(`- **${label}:** ${value}`);
     }
     lines.push("");
   }
   const density = section.dna_overrides?.density || "comfortable";
-  lines.push(...generateSpacingGuide(density));
+  lines.push(...generateSpacingGuide(density, spatialHints));
   lines.push("---");
   lines.push("");
   lines.push(`**Guard:** ${guardConfig.mode} mode | DNA violations = ${guardConfig.dna_enforcement} | Blueprint violations = ${guardConfig.blueprint_enforcement}`);
@@ -2370,7 +2838,7 @@ function generateSectionContext(input) {
   }
   if (themeHints) {
     if (themeHints.preferred && themeHints.preferred.length > 0) {
-      const sectionPatterns = new Set(section.pages.flatMap((p) => p.layout.map((l) => typeof l === "string" ? l : l.pattern)));
+      const sectionPatterns = new Set(section.pages.flatMap((p) => p.layout.flatMap(extractPatternNames)));
       const relevant = themeHints.preferred.filter((p) => sectionPatterns.has(p));
       if (relevant.length > 0) {
         lines.push(`**Preferred:** ${relevant.join(", ")}`);
@@ -2445,6 +2913,9 @@ function generateSectionContext(input) {
   if (uniquePatterns.size > 0) {
     lines.push("## Pattern Reference");
     lines.push("");
+    lines.push("Scaffold-tier rule: implement the core visual structure, states, and required slots first.");
+    lines.push("Treat advanced capabilities such as drag/drop, force-layout, minimaps, or simulated live streaming as optional unless the slot guidance or section contract makes them explicitly required.");
+    lines.push("");
     for (const [patternName, spec] of uniquePatterns) {
       lines.push(`### ${patternName}`);
       lines.push("");
@@ -2557,6 +3028,15 @@ function generateScaffoldContext(input) {
     if (input.voice.metrics_format) lines.push(`**Metrics format:** ${input.voice.metrics_format}`);
     lines.push("");
   }
+  lines.push("## Development Mode");
+  lines.push("");
+  lines.push("For local development and showcases, wire all zone transitions with mock data:");
+  lines.push("");
+  lines.push("- **Auth bypass:** Auth pages should accept any input and redirect to the primary section's default route");
+  lines.push("- **Route guards:** Check a simple localStorage flag (e.g., `decantr_authenticated`). Login sets it \u2192 redirect to app zone entry. Logout clears it \u2192 redirect to public/gateway zone.");
+  lines.push("- **Mock data on every page:** All pages should render with simulated data on first load \u2014 never show empty states during development");
+  lines.push("- **Zone transitions:** CTA links on marketing pages should route to the gateway (login/register). Successful auth should route to the primary section default page.");
+  lines.push("");
   lines.push(topologyMarkdown);
   lines.push("");
   lines.push("## Sections Overview");
@@ -2644,9 +3124,9 @@ function generateScaffoldContext(input) {
 // 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";
+import { RegistryAPIClient, API_CONTENT_TYPES as API_CONTENT_TYPES2 } from "@decantr/registry";
 var DEFAULT_API_URL = "https://api.decantr.ai/v1";
-var ALL_CONTENT_TYPES = ["themes", "patterns", "blueprints", "archetypes", "shells"];
+var ALL_CONTENT_TYPES = API_CONTENT_TYPES2;
 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");
@@ -2673,13 +3153,16 @@ var RegistryClient = class {
   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.apiUrl = options.apiUrl || process.env.DECANTR_API_URL || DEFAULT_API_URL;
     this.offline = options.offline || false;
     this.apiClient = new RegistryAPIClient({
       baseUrl: this.apiUrl,
-      apiKey: options.apiKey
+      apiKey: options.apiKey || process.env.DECANTR_API_KEY || void 0
     });
   }
+  getApiUrl() {
+    return this.apiUrl;
+  }
   /**
    * Load content from .decantr/custom/{contentType}/{id}.json
    * Works for ALL content types, not just themes.
@@ -2719,12 +3202,17 @@ var RegistryClient = class {
    * Unified fetch for a content list.
    * Resolution: API -> Cache. Custom items are merged into the list.
    */
-  async fetchContentList(contentType, namespace) {
+  async fetchContentList(contentType, namespace, sort, recommended, intelligenceSource) {
     let apiItems = [];
     let source = { type: "cache" };
     if (!this.offline) {
       try {
-        const apiResult = await this.apiClient.listContent(contentType, { namespace });
+        const apiResult = await this.apiClient.listContent(contentType, {
+          namespace,
+          sort,
+          recommended,
+          intelligenceSource
+        });
         apiItems = apiResult.items;
         source = { type: "api", url: this.apiUrl };
         saveToCache(this.cacheDir, contentType, null, apiResult, namespace || "@official");
@@ -2848,14 +3336,19 @@ async function syncRegistry(cacheDir, apiUrl = DEFAULT_API_URL) {
 }
 
 export {
+  collectPatternIdsFromItems,
+  mapRegistryArchetypeToArchetypeData,
   composeArchetypes,
   composeSections,
   deriveZones,
   deriveTransitions,
   generateTopologySection,
+  mapRegistryThemeToThemeData,
   scaffoldProject,
   scaffoldMinimal,
+  writeExecutionPackBundleArtifacts,
   refreshDerivedFiles,
+  mapRegistryPatternToPatternSpecSummary,
   RegistryClient,
   syncRegistry
 };