@decantr/cli 1.5.6 → 1.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decantr AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import "./chunk-G77ADKWE.js";
-import "./chunk-VKWRNLHR.js";
+import "./chunk-DESYSWLL.js";
+import "./chunk-PMBLHVBX.js";

package/dist/{chunk-G77ADKWE.js → chunk-DESYSWLL.js}

@@ -9,7 +9,7 @@ import {
   scaffoldMinimal,
   scaffoldProject,
   syncRegistry
-} from "./chunk-VKWRNLHR.js";
+} from "./chunk-PMBLHVBX.js";
 
 // src/index.ts
 import { readFileSync as readFileSync15, existsSync as existsSync23, readdirSync as readdirSync6 } from "fs";
@@ -2189,6 +2189,7 @@ ${YELLOW5}Next step:${RESET8} Ask your AI assistant to read ${BOLD3}.decantr/ana
 // src/commands/magic.ts
 import { join as join19 } from "path";
 import { existsSync as existsSync19 } from "fs";
+import * as fs from "fs/promises";
 var BOLD4 = "\x1B[1m";
 var DIM9 = "\x1B[2m";
 var RESET9 = "\x1B[0m";
@@ -2336,7 +2337,32 @@ function parseMagicPrompt(prompt) {
     archetype
   };
 }
-function resolveTheme(hints) {
+async function resolveTheme(intent, registryClient) {
+  const hints = intent.themeHints;
+  if (registryClient) {
+    try {
+      const themes = await registryClient.fetchThemes();
+      if (themes && themes.length > 0) {
+        const scored = themes.map((t) => {
+          let score = 0;
+          const personality = (t.personality || "").toLowerCase();
+          const tags = (t.tags || []).map((tag) => tag.toLowerCase());
+          for (const hint of intent.themeHints) {
+            if (personality.includes(hint)) score += 3;
+            if (tags.some((tag) => tag.includes(hint))) score += 2;
+          }
+          if (intent.themeHints.includes("dark") && t.modes?.includes("dark")) score += 1;
+          if (intent.themeHints.includes("light") && t.modes?.includes("light")) score += 1;
+          return { id: t.id || t.slug, score, modes: t.modes };
+        }).sort((a, b) => b.score - a.score);
+        if (scored[0] && scored[0].score > 0) {
+          const mode2 = intent.themeHints.includes("light") ? "light" : intent.themeHints.includes("dark") ? "dark" : scored[0].modes?.includes("dark") ? "dark" : "light";
+          return { style: scored[0].id, mode: mode2 };
+        }
+      }
+    } catch {
+    }
+  }
   let mode = "dark";
   if (hints.includes("light")) mode = "light";
   if (hints.includes("neon") || hints.includes("glass")) return { style: "obsidianite", mode };
@@ -2358,6 +2384,18 @@ function buildPersonality(intent) {
   if (intent.themeHints.includes("playful")) return ["friendly", "energetic"];
   return ["professional"];
 }
+function buildRichPersonality(intent, blueprintData, themeData) {
+  const parts = [];
+  if (blueprintData?.personality && typeof blueprintData.personality === "string")
+    parts.push(blueprintData.personality);
+  if (intent.personalityHints.length > 0 && !parts.some((p) => intent.personalityHints.every((h) => p.toLowerCase().includes(h))))
+    parts.push(`Visual character: ${intent.personalityHints.join(", ")}.`);
+  if (themeData?.personality && !parts.some((p) => p.toLowerCase().includes(themeData.personality.toLowerCase())))
+    parts.push(`Theme influence: ${themeData.personality}.`);
+  if (parts.length === 0)
+    parts.push(`Modern, production-ready ${intent.description}. Clean typography, intentional spacing, polished interactions.`);
+  return parts.join(" ");
+}
 async function cmdMagic(prompt, projectRoot, options) {
   console.log("");
   console.log(`${MAGENTA}${BOLD4} Decantr Magic${RESET9}`);
@@ -2435,7 +2473,7 @@ async function cmdMagic(prompt, projectRoot, options) {
   } else {
     console.log(dim("  Offline mode \u2014 using defaults."));
   }
-  const themeResolved = resolveTheme(intent.themeHints);
+  const themeResolved = await resolveTheme(intent, apiAvailable ? registryClient : void 0);
   const personality = buildPersonality(intent);
   const initOptions = {
     blueprint: matchedBlueprint,
@@ -2463,17 +2501,28 @@ async function cmdMagic(prompt, projectRoot, options) {
       initOptions.personality = [...merged];
     }
   }
+  if (intent.constraints.includes("accessible")) {
+    initOptions.accessibility = { wcag_level: "AA" };
+  }
+  if (intent.constraints.includes("mobile-first")) {
+    initOptions.density = "comfortable";
+  }
+  if (intent.constraints.includes("real-time")) {
+    initOptions.features = [...initOptions.features || [], "websockets", "live-updates"];
+  }
   if (options.dryRun) {
+    const personalityStr = initOptions.personality.join(". ");
     console.log("");
-    console.log(`${YELLOW6}${BOLD4} Dry run \u2014 no files written${RESET9}`);
-    console.log("");
-    console.log(`   Blueprint:    ${matchedBlueprint || dim("(none \u2014 archetype-based)")}`);
-    console.log(`   Theme:        ${initOptions.theme} (${initOptions.mode})`);
-    console.log(`   Personality:  ${initOptions.personality.join(", ")}`);
-    console.log(`   Archetype:    ${initOptions.archetype}`);
-    console.log(`   Guard:        ${initOptions.guard}`);
-    console.log(`   Density:      ${initOptions.density}`);
-    console.log("");
+    console.log(`${BOLD4}decantr magic preview${RESET9}`);
+    console.log("\u2500".repeat(60));
+    console.log(`  Blueprint:    ${matchedBlueprint || "none (archetype-direct)"}`);
+    console.log(`  Theme:        ${initOptions.theme} (${initOptions.mode}${initOptions.shape ? ", " + initOptions.shape : ""})`);
+    console.log(`  Archetype:    ${initOptions.archetype || "auto-detected"}`);
+    console.log(`  Personality:  ${personalityStr.slice(0, 80)}${personalityStr.length > 80 ? "..." : ""}`);
+    console.log(`  WCAG:         ${initOptions.accessibility?.wcag_level || "AA"} | Density: ${initOptions.density} | Guard: ${initOptions.guard}`);
+    if (intent.constraints.length > 0)
+      console.log(`  Constraints:  ${intent.constraints.join(", ")}`);
+    console.log("\u2500".repeat(60));
     return;
   }
   console.log("");
@@ -2625,6 +2674,10 @@ async function cmdMagic(prompt, projectRoot, options) {
       };
     }
   }
+  const richPersonality = buildRichPersonality(intent, blueprintData, themeData);
+  if (richPersonality) {
+    initOptions.personality = [richPersonality];
+  }
   console.log(`${BOLD4} Scaffolding...${RESET9}`);
   const result = await scaffoldProject(
     projectRoot,
@@ -2664,6 +2717,25 @@ async function cmdMagic(prompt, projectRoot, options) {
   if (result.gitignoreUpdated) {
     console.log(`   ${dim(".gitignore updated")}`);
   }
+  const contextDir = join19(projectRoot, ".decantr", "context");
+  let sectionCount = 0;
+  try {
+    const files = await fs.readdir(contextDir);
+    sectionCount = files.filter((f) => f.startsWith("section-")).length;
+  } catch {
+  }
+  const treatmentsPath = join19(projectRoot, "src", "styles", "treatments.css");
+  let hasLayers = false;
+  try {
+    const css = await fs.readFile(treatmentsPath, "utf-8");
+    hasLayers = css.includes("@layer");
+  } catch {
+  }
+  console.log(`
+${GREEN9}${BOLD4}Quality summary:${RESET9}`);
+  console.log(`  Context files:   ${sectionCount} sections + scaffold.md + DECANTR.md`);
+  console.log(`  CSS:             tokens.css + treatments.css + global.css`);
+  console.log(`  @layer cascade:  ${hasLayers ? GREEN9 + "yes" + RESET9 : YELLOW6 + "missing" + RESET9}`);
   console.log("");
   console.log(`${BOLD4} Ready!${RESET9} Next steps:`);
   console.log(`   1. Read ${cyan("DECANTR.md")} to understand the design system`);
@@ -3576,12 +3648,22 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   const blueprints = blueprintsResult.data.items;
   const themes = themesResult.data.items;
   let options;
+  const userExplicit = {
+    theme: Boolean(args.theme),
+    mode: Boolean(args.mode),
+    shape: Boolean(args.shape),
+    personality: Boolean(args.personality)
+  };
   if (args.yes || selectedBlueprint !== "default") {
     const flags = parseFlags(args, detected);
     flags.blueprint = selectedBlueprint !== "default" ? selectedBlueprint : flags.blueprint;
     options = mergeWithDefaults(flags, detected);
   } else {
     options = await runInteractivePrompts(detected, archetypes, blueprints, themes);
+    userExplicit.theme = true;
+    userExplicit.mode = true;
+    userExplicit.shape = true;
+    userExplicit.personality = true;
   }
   let topologyMarkdown = "";
   let archetypeData;
@@ -3592,20 +3674,19 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   if (options.blueprint) {
     const blueprintResult = await registryClient.fetchBlueprint(options.blueprint);
     if (blueprintResult) {
-      const rawBlueprint = blueprintResult.data;
-      const blueprint = rawBlueprint.data ?? rawBlueprint;
+      const blueprint = blueprintResult.data;
       if (blueprint.theme) {
-        if ((blueprint.theme.id || blueprint.theme.style) && options.theme === "luminarum") {
+        if (!userExplicit.theme && (blueprint.theme.id || blueprint.theme.style)) {
           options.theme = blueprint.theme.id || blueprint.theme.style;
         }
-        if (blueprint.theme.mode && options.mode === "dark") {
+        if (!userExplicit.mode && blueprint.theme.mode) {
           options.mode = blueprint.theme.mode;
         }
-        if (blueprint.theme.shape && options.shape === "rounded") {
+        if (!userExplicit.shape && blueprint.theme.shape) {
           options.shape = blueprint.theme.shape;
         }
       }
-      if (blueprint.personality && (!options.personality || options.personality.length === 0 || options.personality.length === 1 && options.personality[0] === "professional")) {
+      if (!userExplicit.personality && blueprint.personality) {
         options.personality = typeof blueprint.personality === "string" ? [blueprint.personality] : blueprint.personality;
       }
       if (blueprint.compose && blueprint.compose.length > 0) {
@@ -3614,9 +3695,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
         for (const entry of entries) {
           const id = typeof entry === "string" ? entry : entry.archetype;
           const r = await registryClient.fetchArchetype(id);
-          const raw = r?.data;
-          const inner = raw?.data ?? raw;
-          results.push([id, inner]);
+          results.push([id, r?.data ?? null]);
         }
         const archetypeMap = new Map(results.map(([id, data]) => [id, data || null]));
         const composed = composeArchetypes(entries, archetypeMap);
@@ -3664,8 +3743,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
             try {
               const result2 = await registryClient.fetchPattern(pid);
               if (result2) {
-                const raw = result2.data;
-                const inner = raw.data ?? raw;
+                const inner = result2.data;
                 const defaultPreset = inner.default_preset || "standard";
                 const preset = inner.presets?.[defaultPreset];
                 patternSpecs[pid] = {
@@ -3717,8 +3795,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   } else if (options.archetype) {
     const archetypeResult = await registryClient.fetchArchetype(options.archetype);
     if (archetypeResult) {
-      const rawArch = archetypeResult.data;
-      archetypeData = rawArch.data ?? rawArch;
+      archetypeData = archetypeResult.data;
     } else {
       console.log(`${YELLOW9}  Warning: Could not fetch archetype "${options.archetype}". Using defaults.${RESET13}`);
     }
@@ -3727,8 +3804,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   if (options.theme) {
     const themeResult = await registryClient.fetchTheme(options.theme);
     if (themeResult) {
-      const rawTheme = themeResult.data;
-      const theme = rawTheme.data ?? rawTheme;
+      const theme = themeResult.data;
       themeData = {
         seed: theme.seed,
         palette: theme.palette,
@@ -4256,7 +4332,7 @@ async function main() {
       break;
     }
     case "upgrade": {
-      const { cmdUpgrade } = await import("./upgrade-6MKC6EDQ.js");
+      const { cmdUpgrade } = await import("./upgrade-2OG7UKTR.js");
       const applyFlag = args.includes("--apply");
       await cmdUpgrade(process.cwd(), { apply: applyFlag });
       break;

package/dist/{chunk-VKWRNLHR.js → chunk-PMBLHVBX.js}

@@ -9,6 +9,8 @@ function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators
   const lines = [];
   lines.push("/* Generated by @decantr/cli \u2014 Visual Treatment System */");
   lines.push("");
+  lines.push("@layer treatments {");
+  lines.push("");
   lines.push("/* \u2500\u2500 Layer 1: Base Treatments \u2500\u2500 */");
   lines.push("");
   function emitRule(selector, props) {
@@ -202,16 +204,6 @@ function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators
     ["color", "var(--d-text-muted)"],
     ["font-family", "var(--d-font-mono, ui-monospace, monospace)"]
   ]);
-  if (themeDecorators && Object.keys(themeDecorators).length > 0) {
-    const label = themeName ? ` (${themeName})` : "";
-    lines.push(`/* \u2500\u2500 Layer 3: Theme Decorators${label} \u2500\u2500 */`);
-    lines.push("");
-    for (const [name, description] of Object.entries(themeDecorators)) {
-      const rule = generateDecoratorRule(name, description);
-      lines.push(rule);
-      lines.push("");
-    }
-  }
   lines.push("/* \u2500\u2500 Keyframes \u2500\u2500 */");
   lines.push("");
   lines.push("@keyframes decantr-fade-in {");
@@ -223,6 +215,22 @@ function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators
   lines.push("  0%, 100% { opacity: 1; }");
   lines.push("  50% { opacity: 0.5; }");
   lines.push("}");
+  lines.push("");
+  lines.push("} /* end @layer treatments */");
+  if (themeDecorators && Object.keys(themeDecorators).length > 0) {
+    const label = themeName ? ` (${themeName})` : "";
+    lines.push("");
+    lines.push("@layer decorators {");
+    lines.push("");
+    lines.push(`/* \u2500\u2500 Layer 3: Theme Decorators${label} \u2500\u2500 */`);
+    lines.push("");
+    for (const [name, description] of Object.entries(themeDecorators)) {
+      const rule = generateDecoratorRule(name, description);
+      lines.push(rule);
+      lines.push("");
+    }
+    lines.push("} /* end @layer decorators */");
+  }
   return lines.join("\n");
 }
 function generatePersonalityCSS(personality, themeData) {
@@ -252,7 +260,7 @@ function generatePersonalityCSS(personality, themeData) {
     rules.push(`@keyframes decantr-entrance { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }`);
   }
   if (rules.length === 0) return "";
-  return "\n/* \u2500\u2500 Personality-Derived Utilities \u2500\u2500 */\n\n" + rules.join("\n\n") + "\n";
+  return "\n@layer utilities {\n\n/* \u2500\u2500 Personality-Derived Utilities \u2500\u2500 */\n\n" + rules.join("\n\n") + "\n\n} /* end @layer utilities */\n";
 }
 
 // src/scaffold.ts
@@ -509,6 +517,7 @@ function generateTokensCSS(themeData, mode, spatialTokens) {
   if (!themeData) {
     const spatialLines2 = spatialTokens ? "\n" + Object.entries(spatialTokens).map(([k, v]) => `  ${k}: ${v};`).join("\n") : "";
     return `/* No theme data available */
+@layer tokens {
 :root {
   --d-primary: #6366f1;
   --d-secondary: #a1a1aa;
@@ -520,6 +529,7 @@ function generateTokensCSS(themeData, mode, spatialTokens) {
   --d-text: #fafafa;
   --d-text-muted: #a1a1aa;${spatialLines2}
 }
+}
 `;
   }
   const seed = themeData.seed || {};
@@ -584,6 +594,7 @@ function generateTokensCSS(themeData, mode, spatialTokens) {
   const lines = Object.entries(tokens).map(([key, value]) => `  ${key}: ${value};`).join("\n");
   const spatialLines = spatialTokens ? "\n" + Object.entries(spatialTokens).map(([k, v]) => `  ${k}: ${v};`).join("\n") : "";
   let css = `/* Generated by @decantr/cli */
+@layer tokens {
 :root {
 ${lines}${spatialLines}
 }
@@ -612,9 +623,11 @@ ${lightLines}
 }
 `;
   }
+  css += `}
+`;
   return css;
 }
-function generateGlobalCSS(personality) {
+function generateGlobalCSS(personality, essence) {
   const personalityText = personality.join(" ").toLowerCase();
   let fontBody = "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
   if (personalityText.includes("inter")) {
@@ -622,7 +635,12 @@ function generateGlobalCSS(personality) {
   } else if (personalityText.includes("geist")) {
     fontBody = `'Geist', ${fontBody}`;
   }
+  const mode = essence?.dna?.theme?.mode || "dark";
+  const colorScheme = mode === "auto" ? "light dark" : mode;
   return `/* Generated by @decantr/cli \u2014 global reset + body styles */
+@layer reset, tokens, treatments, decorators, utilities, app;
+
+@layer reset {
 
 *, *::before, *::after {
   box-sizing: border-box;
@@ -631,7 +649,7 @@ function generateGlobalCSS(personality) {
 }
 
 html {
-  color-scheme: dark;
+  color-scheme: ${colorScheme};
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   text-rendering: optimizeLegibility;
@@ -671,6 +689,8 @@ input, button, textarea, select {
   white-space: nowrap;
   border-width: 0;
 }
+
+}
 `;
 }
 function generateDecoratorRule(name, description) {
@@ -1291,12 +1311,44 @@ Check \`decantr.essence.json\` \u2192 \`meta.platform.routing\` for the routing
 - \`"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\`.`;
-function generateDecantrMdV31(guardMode, cssApproach) {
+function generateDecantrMdV31(params) {
   const template = loadTemplate("DECANTR.md.template");
-  return renderTemplate(template, {
-    GUARD_MODE: guardMode,
-    CSS_APPROACH: cssApproach
+  const body = renderTemplate(template, {
+    GUARD_MODE: params.guardMode,
+    CSS_APPROACH: params.cssApproach
   });
+  const briefLines = [];
+  briefLines.push("## Project Brief");
+  briefLines.push("");
+  briefLines.push(`- **Blueprint:** ${params.blueprintId || "custom"}`);
+  const themeParts = [params.themeName || "default"];
+  if (params.themeMode) themeParts.push(`${params.themeMode} mode`);
+  if (params.themeShape) themeParts.push(params.themeShape);
+  briefLines.push(`- **Theme:** ${themeParts.join(" (").replace(/ \($/, "") + (themeParts.length > 1 ? ")" : "")}`);
+  if (params.personality && params.personality.length > 0) {
+    briefLines.push(`- **Personality:** ${params.personality.join(". ")}`);
+  }
+  if (params.sections && params.sections.length > 0) {
+    const sectionList = params.sections.map((s) => `${s.id} [${s.role}]`).join(", ");
+    briefLines.push(`- **Sections:** ${params.sections.length} (${sectionList})`);
+  }
+  if (params.features && params.features.length > 0) {
+    briefLines.push(`- **Features:** ${params.features.join(", ")}`);
+  }
+  briefLines.push(`- **Guard mode:** ${params.guardMode}`);
+  briefLines.push("");
+  if (params.decorators && params.decorators.length > 0) {
+    briefLines.push("### Decorator Quick Reference");
+    briefLines.push("| Class | Purpose |");
+    briefLines.push("|-------|---------|");
+    for (const d of params.decorators) {
+      briefLines.push(`| \`.${d.name}\` | ${d.description} |`);
+    }
+    briefLines.push("");
+  }
+  briefLines.push("---");
+  briefLines.push("");
+  return briefLines.join("\n") + body;
 }
 function generateProjectJson(detected, options, registrySource) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1706,8 +1758,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   if (!themeData) try {
     const themeResult = await registry.fetchTheme(themeName);
     if (themeResult?.data) {
-      const raw = themeResult.data;
-      const t = raw.data ?? raw;
+      const t = themeResult.data;
       themeData = {
         seed: t.seed,
         palette: t.palette,
@@ -1758,7 +1809,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   }
   const stylesDir = join(projectRoot, "src", "styles");
   mkdirSync(stylesDir, { recursive: true });
-  const densityLevel = options.density || "comfortable";
+  const densityLevel = essence.dna?.spacing?.density || "comfortable";
   const spatialTokens = computeSpatialTokens(densityLevel, themeData?.spatial ? {
     section_padding: themeData.spatial.section_padding ?? void 0,
     density_bias: typeof themeData.spatial.density_bias === "number" ? themeData.spatial.density_bias : void 0,
@@ -1781,11 +1832,45 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   writeFileSync(treatmentsPath, treatmentCSS);
   const globalPath = join(stylesDir, "global.css");
   if (!existsSync(globalPath)) {
-    writeFileSync(globalPath, generateGlobalCSS(personality));
+    writeFileSync(globalPath, generateGlobalCSS(personality, essence));
   }
   const cssFiles = [tokensPath, treatmentsPath, globalPath];
+  const earlyDecoratorList = [];
+  if (themeData?.decorators) {
+    for (const [name, desc] of Object.entries(themeData.decorators)) {
+      earlyDecoratorList.push({ name, description: desc });
+    }
+  }
+  const allFeatures = [];
+  const sectionSummaries = [];
+  if (essence.blueprint.sections && essence.blueprint.sections.length > 0) {
+    for (const s of essence.blueprint.sections) {
+      sectionSummaries.push({ id: s.id, role: s.role });
+      if (s.features) {
+        for (const f of s.features) {
+          if (!allFeatures.includes(f)) allFeatures.push(f);
+        }
+      }
+    }
+  }
+  if (essence.blueprint.features) {
+    for (const f of essence.blueprint.features) {
+      if (!allFeatures.includes(f)) allFeatures.push(f);
+    }
+  }
   const decantrMdPath = join(projectRoot, "DECANTR.md");
-  writeFileSync(decantrMdPath, generateDecantrMdV31(guardMode, CSS_APPROACH_CONTENT));
+  writeFileSync(decantrMdPath, generateDecantrMdV31({
+    guardMode,
+    cssApproach: CSS_APPROACH_CONTENT,
+    blueprintId: essence.meta.blueprint || void 0,
+    themeName,
+    themeMode: mode,
+    themeShape: essence.dna.theme.shape || void 0,
+    personality,
+    sections: sectionSummaries.length > 0 ? sectionSummaries : void 0,
+    features: allFeatures.length > 0 ? allFeatures : void 0,
+    decorators: earlyDecoratorList.length > 0 ? earlyDecoratorList : void 0
+  }));
   const hasSections = essence.blueprint.sections && essence.blueprint.sections.length > 0;
   const contextFiles = [];
   if (!hasSections) {
@@ -1822,8 +1907,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
               try {
                 const patResult = await registry.fetchPattern(name);
                 if (patResult?.data) {
-                  const raw = patResult.data;
-                  const inner = raw.data ?? raw;
+                  const inner = patResult.data;
                   const defaultPreset = inner.default_preset || "standard";
                   const preset = inner.presets?.[defaultPreset];
                   let slots = preset?.layout?.slots || {};
@@ -1837,7 +1921,12 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
                     description: inner.description || "",
                     components: inner.components || [],
                     slots,
-                    layout_hints: inner.layout_hints
+                    layout_hints: inner.layout_hints,
+                    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 syntheticComps = generateSyntheticComponents(name, spec.description);
@@ -1890,19 +1979,6 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       for (const [name, desc] of Object.entries(themeData.decorators)) {
         decoratorList.push({ name, description: desc });
       }
-    } else if (existsSync(decoratorsPath)) {
-      const decoratorsCss = readFileSync(decoratorsPath, "utf-8");
-      const classRegex = /\/\*\s*(.+?)\s*\*\/\s*\n\s*\.([\w-]+)\s*\{/g;
-      let match;
-      while ((match = classRegex.exec(decoratorsCss)) !== null) {
-        decoratorList.push({ name: match[2], description: match[1] });
-      }
-      if (decoratorList.length === 0) {
-        const simpleClassRegex = /^\.([\w-]+)\s*\{/gm;
-        while ((match = simpleClassRegex.exec(decoratorsCss)) !== null) {
-          decoratorList.push({ name: match[1], description: "" });
-        }
-      }
     }
     const shellInfoCache = {};
     const seenShells = /* @__PURE__ */ new Set();
@@ -1913,8 +1989,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
         try {
           const shellResult = await registry.fetchShell(shellId);
           if (shellResult?.data) {
-            const raw = shellResult.data;
-            const inner = raw.data ?? raw;
+            const inner = shellResult.data;
             shellInfoCache[shellId] = {
               description: inner.description || "",
               regions: inner.config?.regions || [],
@@ -1958,8 +2033,15 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
         themeName,
         zoneContext,
         patternSpecs: sectionPatterns,
+        themeHints: themeData ? {
+          preferred: themeData.pattern_preferences?.prefer,
+          compositions: themeData.compositions ? Object.entries(themeData.compositions).map(([k, v]) => `**${k}:** ${v.description || v}`).join("\n") : void 0,
+          spatialHints: themeData.spatial ? `Density bias: ${themeData.spatial.density_bias || "none"}. Section padding: ${themeData.spatial.section_padding || "default"}. Card wrapping: ${themeData.spatial.card_wrapping || "default"}.` : void 0
+        } : void 0,
         constraints: essence.dna.constraints,
-        shellInfo: shellInfoCache[section.shell]
+        shellInfo: shellInfoCache[section.shell],
+        themeData,
+        themeMode: mode
       });
       const sectionContextPath = join(contextDir, `section-${section.id}.md`);
       writeFileSync(sectionContextPath, contextContent);
@@ -2003,8 +2085,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
             try {
               const patResult = await registry.fetchPattern(name);
               if (patResult?.data) {
-                const raw = patResult.data;
-                const inner = raw.data ?? raw;
+                const inner = patResult.data;
                 const defaultPreset = inner.default_preset || "standard";
                 const preset = inner.presets?.[defaultPreset];
                 let slots = preset?.layout?.slots || {};
@@ -2049,26 +2130,12 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       for (const [name, desc] of Object.entries(themeData.decorators)) {
         decoratorList.push({ name, description: desc });
       }
-    } else if (existsSync(decoratorsPath)) {
-      const decoratorsCss = readFileSync(decoratorsPath, "utf-8");
-      const classRegex = /\/\*\s*(.+?)\s*\*\/\s*\n\s*\.([\w-]+)\s*\{/g;
-      let match;
-      while ((match = classRegex.exec(decoratorsCss)) !== null) {
-        decoratorList.push({ name: match[2], description: match[1] });
-      }
-      if (decoratorList.length === 0) {
-        const simpleClassRegex = /^\.([\w-]+)\s*\{/gm;
-        while ((match = simpleClassRegex.exec(decoratorsCss)) !== null) {
-          decoratorList.push({ name: match[1], description: "" });
-        }
-      }
     }
     let v30ShellInfo;
     try {
       const shellResult = await registry.fetchShell(shell);
       if (shellResult?.data) {
-        const raw = shellResult.data;
-        const inner = raw.data ?? raw;
+        const inner = shellResult.data;
         v30ShellInfo = {
           description: inner.description || "",
           regions: inner.config?.regions || [],
@@ -2087,8 +2154,15 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       themeName,
       zoneContext: `This is the primary section (${shell} shell).`,
       patternSpecs,
+      themeHints: themeData ? {
+        preferred: themeData.pattern_preferences?.prefer,
+        compositions: themeData.compositions ? Object.entries(themeData.compositions).map(([k, v]) => `**${k}:** ${v.description || v}`).join("\n") : void 0,
+        spatialHints: themeData.spatial ? `Density bias: ${themeData.spatial.density_bias || "none"}. Section padding: ${themeData.spatial.section_padding || "default"}. Card wrapping: ${themeData.spatial.card_wrapping || "default"}.` : void 0
+      } : void 0,
       constraints: essence.dna.constraints,
-      shellInfo: v30ShellInfo
+      shellInfo: v30ShellInfo,
+      themeData,
+      themeMode: mode
     });
     const sectionContextPath = join(contextDir, `section-${syntheticSection.id}.md`);
     writeFileSync(sectionContextPath, contextContent);
@@ -2220,14 +2294,47 @@ function generateSectionContext(input) {
   lines.push("");
   lines.push(`**Guard:** ${guardConfig.mode} mode | DNA violations = ${guardConfig.dna_enforcement} | Blueprint violations = ${guardConfig.blueprint_enforcement}`);
   lines.push("");
-  lines.push(`**Theme tokens:** see \`src/styles/tokens.css\` \u2014 use \`var(--d-primary)\`, \`var(--d-bg)\`, etc.`);
+  lines.push("**Key palette tokens:**");
+  lines.push("");
+  lines.push("| Token | Value | Role |");
+  lines.push("|-------|-------|------|");
+  const semanticRoles = {
+    background: "Page canvas / base layer",
+    surface: "Cards, panels, containers",
+    "surface-raised": "Elevated containers, modals, popovers",
+    border: "Dividers, card borders, separators",
+    text: "Body text, headings, primary content",
+    "text-muted": "Secondary text, placeholders, labels",
+    primary: "Brand color, key interactive, selected states",
+    "primary-hover": "Hover state for primary elements"
+  };
+  if (input.themeData?.palette) {
+    const modeKey = input.themeMode || "dark";
+    for (const [name, values] of Object.entries(input.themeData.palette)) {
+      const val = values[modeKey] || values.dark || values.light || Object.values(values)[0];
+      lines.push(`| \`--d-${name}\` | \`${val}\` | ${semanticRoles[name] || ""} |`);
+    }
+  }
+  if (input.themeData?.seed?.accent) {
+    lines.push(`| \`--d-accent\` | \`${input.themeData.seed.accent}\` | CTAs, links, active states, glow effects |`);
+  }
+  lines.push("");
+  lines.push("Full token set: `src/styles/tokens.css`");
   lines.push("");
   lines.push("**Visual Treatments:** All 6 base treatments available (see DECANTR.md for usage).");
   if (decorators.length > 0) {
-    const names = decorators.map((d) => d.name).join(", ");
-    lines.push(`**Theme decorators:** ${names}`);
+    lines.push("**Theme decorators:**");
+    lines.push("");
+    lines.push("| Class | Usage |");
+    lines.push("|-------|-------|");
+    for (const d of decorators) {
+      lines.push(`| \`.${d.name}\` | ${d.description} |`);
+    }
+    lines.push("");
+  } else {
+    lines.push("**Theme decorators:** None defined for this theme.");
+    lines.push("");
   }
-  lines.push("");
   if (themeHints) {
     if (themeHints.preferred && themeHints.preferred.length > 0) {
       lines.push(`**Preferred:** ${themeHints.preferred.join(", ")}`);
@@ -2260,8 +2367,24 @@ function generateSectionContext(input) {
     lines.push("");
   }
   if (personality.length > 0) {
-    lines.push("**Personality:** See scaffold.md for personality and visual direction.");
+    const personalityText = personality.join(". ");
+    lines.push("## Visual Direction");
+    lines.push("");
+    lines.push(`**Personality:** ${personalityText}`);
     lines.push("");
+    const pLower = personalityText.toLowerCase();
+    const utils = [];
+    if (pLower.includes("neon") || pLower.includes("glow"))
+      utils.push("`neon-glow`, `neon-glow-hover`, `neon-text-glow`, `neon-border-glow` \u2014 Apply to elements needing accent emphasis");
+    if (pLower.includes("mono") || pLower.includes("monospace"))
+      utils.push("`mono-data` \u2014 Monospace + tabular-nums for metrics, IDs, timestamps");
+    if (pLower.includes("pulse") || pLower.includes("ring") || pLower.includes("status"))
+      utils.push('`status-ring` with `data-status="active|idle|error|processing"` \u2014 Color-coded status with pulse animation');
+    if (utils.length > 0) {
+      lines.push("**Personality utilities available in treatments.css:**");
+      for (const u of utils) lines.push(`- ${u}`);
+      lines.push("");
+    }
   }
   if (constraints && Object.keys(constraints).length > 0) {
     lines.push("## Constraints");
@@ -2290,8 +2413,21 @@ function generateSectionContext(input) {
       lines.push("");
       lines.push(spec.description);
       lines.push("");
+      if (spec.visual_brief) {
+        lines.push(`**Visual brief:** ${spec.visual_brief}`);
+        lines.push("");
+      }
       lines.push(`**Components:** ${spec.components.join(", ")}`);
       lines.push("");
+      if (spec.composition && Object.keys(spec.composition).length > 0) {
+        lines.push("**Composition:**");
+        lines.push("```");
+        for (const [name, expr] of Object.entries(spec.composition)) {
+          lines.push(`${name} = ${expr}`);
+        }
+        lines.push("```");
+        lines.push("");
+      }
       lines.push("**Layout slots:**");
       for (const [slot, desc] of Object.entries(spec.slots)) {
         lines.push(`- \`${slot}\`: ${desc}`);
@@ -2302,6 +2438,38 @@ function generateSectionContext(input) {
           lines.push(`  - ${key}: ${value}`);
         }
       }
+      if (spec.motion) {
+        const entries = [];
+        const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+        if (isObj(spec.motion.micro)) for (const [k, v] of Object.entries(spec.motion.micro)) entries.push([k, v]);
+        else if (typeof spec.motion.micro === "string") entries.push(["micro", spec.motion.micro]);
+        if (isObj(spec.motion.transitions)) for (const [k, v] of Object.entries(spec.motion.transitions)) entries.push([k, v]);
+        else if (typeof spec.motion.transitions === "string") entries.push(["transitions", spec.motion.transitions]);
+        if (isObj(spec.motion.ambient)) for (const [k, v] of Object.entries(spec.motion.ambient)) entries.push([k, v]);
+        else if (typeof spec.motion.ambient === "string") entries.push(["ambient", spec.motion.ambient]);
+        if (entries.length > 0) {
+          lines.push("**Motion:**");
+          lines.push("| Interaction | Animation |");
+          lines.push("|-------------|-----------|");
+          for (const [k, v] of entries) lines.push(`| ${k} | ${v} |`);
+          lines.push("");
+        }
+      }
+      if (spec.responsive) {
+        lines.push("**Responsive:**");
+        if (spec.responsive.mobile) lines.push(`- **Mobile (<640px):** ${spec.responsive.mobile}`);
+        if (spec.responsive.tablet) lines.push(`- **Tablet (640-1024px):** ${spec.responsive.tablet}`);
+        if (spec.responsive.desktop) lines.push(`- **Desktop (>1024px):** ${spec.responsive.desktop}`);
+        lines.push("");
+      }
+      if (spec.accessibility) {
+        lines.push("**Accessibility:**");
+        if (spec.accessibility.role) lines.push(`- Role: \`${spec.accessibility.role}\``);
+        if (Array.isArray(spec.accessibility.keyboard) && spec.accessibility.keyboard.length) lines.push(`- Keyboard: ${spec.accessibility.keyboard.join("; ")}`);
+        if (Array.isArray(spec.accessibility.announcements) && spec.accessibility.announcements.length) lines.push(`- Announcements: ${spec.accessibility.announcements.join("; ")}`);
+        if (spec.accessibility.focus_management) lines.push(`- Focus: ${spec.accessibility.focus_management}`);
+        lines.push("");
+      }
       lines.push("");
     }
     lines.push("---");
@@ -2340,6 +2508,18 @@ function generateScaffoldContext(input) {
   lines.push(`**Personality:** ${personality.join(", ")}`);
   lines.push("**Guard mode:** creative (no enforcement during initial scaffolding)");
   lines.push("");
+  if (input.voice) {
+    lines.push("## Voice & Copy");
+    lines.push("");
+    if (input.voice.tone) lines.push(`**Tone:** ${input.voice.tone}`);
+    if (input.voice.cta_verbs?.length) lines.push(`**CTA verbs:** ${input.voice.cta_verbs.join(", ")}`);
+    if (input.voice.avoid?.length) lines.push(`**Avoid:** ${input.voice.avoid.join(", ")}`);
+    if (input.voice.empty_states) lines.push(`**Empty states:** ${input.voice.empty_states}`);
+    if (input.voice.errors) lines.push(`**Errors:** ${input.voice.errors}`);
+    if (input.voice.loading) lines.push(`**Loading states:** ${input.voice.loading}`);
+    if (input.voice.metrics_format) lines.push(`**Metrics format:** ${input.voice.metrics_format}`);
+    lines.push("");
+  }
   lines.push("## App Topology");
   lines.push("");
   lines.push(topologyMarkdown);

package/dist/index.js

@@ -1,2 +1,2 @@
-import "./chunk-G77ADKWE.js";
-import "./chunk-VKWRNLHR.js";
+import "./chunk-DESYSWLL.js";
+import "./chunk-PMBLHVBX.js";

package/dist/{upgrade-6MKC6EDQ.js → upgrade-2OG7UKTR.js}

@@ -1,7 +1,7 @@
 import {
   RegistryClient,
   refreshDerivedFiles
-} from "./chunk-VKWRNLHR.js";
+} from "./chunk-PMBLHVBX.js";
 
 // src/commands/upgrade.ts
 import { readFileSync, writeFileSync, existsSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "1.5.6",
+  "version": "1.6.1",
   "description": "Decantr CLI — search the registry, validate essence files, and access design intelligence from the terminal",
   "license": "MIT",
   "repository": {
@@ -22,13 +22,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@decantr/essence-spec": "1.0.0-beta.11",
+    "@decantr/registry": "1.0.0-beta.11"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest"
-  },
-  "dependencies": {
-    "@decantr/essence-spec": "workspace:*",
-    "@decantr/registry": "workspace:*"
   }
-}
+}