@decantr/cli 1.7.24 → 1.7.26

package/dist/{chunk-7H3PAC5Y.js → chunk-RAAUNHXD.js}

@@ -14,15 +14,15 @@ import {
   scaffoldProject,
   syncRegistry,
   writeExecutionPackBundleArtifacts
-} from "./chunk-RH6IQ7YX.js";
+} from "./chunk-3K6HWLD5.js";
 import {
   buildGuardRegistryContext,
   scanProjectInteractions
 } from "./chunk-QRQCPD3C.js";
 
 // src/index.ts
-import { existsSync as existsSync25, mkdirSync as mkdirSync10, readdirSync as readdirSync6, readFileSync as readFileSync18, writeFileSync as writeFileSync13 } from "fs";
-import { basename as basename2, dirname as dirname2, isAbsolute, join as join26, resolve as resolve3 } from "path";
+import { existsSync as existsSync27, mkdirSync as mkdirSync11, readdirSync as readdirSync7, readFileSync as readFileSync20, writeFileSync as writeFileSync14 } from "fs";
+import { basename as basename2, dirname as dirname4, isAbsolute, join as join28, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { evaluateGuard, isV3 as isV36, validateEssence as validateEssence2 } from "@decantr/essence-spec";
 import {
@@ -40,29 +40,63 @@ import {
 } from "@decantr/verifier";
 
 // src/auth.ts
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var CONFIG_DIR = join(homedir(), ".config", "decantr");
-var AUTH_FILE = join(CONFIG_DIR, "auth.json");
+var CONFIG_DIR_MODE = 448;
+var AUTH_FILE_MODE = 384;
+function getConfigDir() {
+  return process.env.DECANTR_CONFIG_DIR || join(homedir(), ".config", "decantr");
+}
+function getAuthFile() {
+  return join(getConfigDir(), "auth.json");
+}
+function chmodIfNeeded(path, mode) {
+  try {
+    if ((statSync(path).mode & 511) !== mode) {
+      chmodSync(path, mode);
+    }
+  } catch {
+  }
+}
+function ensureConfigDir() {
+  const configDir = getConfigDir();
+  mkdirSync(configDir, { recursive: true, mode: CONFIG_DIR_MODE });
+  chmodIfNeeded(configDir, CONFIG_DIR_MODE);
+}
 function getCredentials() {
-  if (!existsSync(AUTH_FILE)) return null;
+  const authFile = getAuthFile();
+  if (!existsSync(authFile)) return null;
   try {
-    return JSON.parse(readFileSync(AUTH_FILE, "utf-8"));
+    chmodIfNeeded(authFile, AUTH_FILE_MODE);
+    return JSON.parse(readFileSync(authFile, "utf-8"));
   } catch {
     return null;
   }
 }
 function saveCredentials(creds) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(AUTH_FILE, JSON.stringify(creds, null, 2));
+  ensureConfigDir();
+  const authFile = getAuthFile();
+  writeFileSync(authFile, JSON.stringify(creds, null, 2), { mode: AUTH_FILE_MODE });
+  chmodIfNeeded(authFile, AUTH_FILE_MODE);
 }
 function clearCredentials() {
-  if (existsSync(AUTH_FILE)) {
-    rmSync(AUTH_FILE);
+  const authFile = getAuthFile();
+  if (existsSync(authFile)) {
+    rmSync(authFile);
   }
 }
 function getApiKeyOrToken() {
+  const envKey = process.env.DECANTR_API_KEY?.trim();
+  if (envKey) return envKey;
   const creds = getCredentials();
   if (!creds) return null;
   return creds.api_key || creds.access_token || null;
@@ -229,13 +263,120 @@ async function cmdAddFeature(feature, args, projectRoot = process.cwd()) {
   console.log(`${GREEN}Derived files refreshed.${RESET}`);
 }
 
+// src/assistant-bridge.ts
+import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname, join as join3 } from "path";
+var START = "<!-- decantr:assistant-bridge:start -->";
+var END = "<!-- decantr:assistant-bridge:end -->";
+function buildAssistantBridgeContent(input) {
+  const lines = [];
+  lines.push("# Decantr Assistant Bridge");
+  lines.push("");
+  lines.push(
+    "Use this bridge when an AI assistant works in a repository that already has local rules."
+  );
+  lines.push("");
+  lines.push(`- Workflow mode: ${input.workflowMode}`);
+  lines.push(`- Detected framework: ${input.detected.framework}`);
+  lines.push(`- Package manager: ${input.detected.packageManager}`);
+  lines.push(
+    `- Existing rule files: ${input.detected.existingRuleFiles.length > 0 ? input.detected.existingRuleFiles.join(", ") : "none detected"}`
+  );
+  lines.push(`- Bridge mode: ${input.assistantBridge}`);
+  lines.push("");
+  lines.push("## Suggested Rule Block");
+  lines.push("");
+  lines.push(START);
+  lines.push(
+    "Before implementing Decantr-scoped work, read `DECANTR.md`, `decantr.essence.json`, and the compiled packs in `.decantr/context/`."
+  );
+  lines.push(
+    "For brownfield adoption, preserve existing framework, routing, styling, package manager, and build conventions unless the Decantr contract explicitly requires a reviewed change."
+  );
+  lines.push(
+    "Use `.decantr/context/scaffold-pack.md` as the primary compact contract, then read matching section/page packs for the surface being changed."
+  );
+  lines.push(
+    "Do not install `@decantr/css` or rewrite styling unless the project adoption mode says `decantr-css` or the task explicitly asks for it."
+  );
+  lines.push(END);
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
+function writeAssistantBridgePreview(input) {
+  const contextDir = join3(input.projectRoot, ".decantr", "context");
+  mkdirSync2(contextDir, { recursive: true });
+  const bridgePath = join3(contextDir, "assistant-bridge.md");
+  writeFileSync3(bridgePath, buildAssistantBridgeContent(input));
+  return bridgePath;
+}
+function bridgeBlock() {
+  return [
+    START,
+    "Before implementing Decantr-scoped work, read `DECANTR.md`, `decantr.essence.json`, and `.decantr/context/scaffold-pack.md` first.",
+    "For brownfield adoption, preserve existing framework, routing, styling, package manager, and build conventions unless the Decantr contract explicitly requires a reviewed change.",
+    "Do not install `@decantr/css` or rewrite styling unless the project adoption mode says `decantr-css` or the task explicitly asks for it.",
+    END,
+    ""
+  ].join("\n");
+}
+function upsertMarkdownBlock(path) {
+  const block = bridgeBlock();
+  if (!existsSync3(path)) {
+    mkdirSync2(dirname(path), { recursive: true });
+    writeFileSync3(path, `# Project Rules
+
+${block}`);
+    return true;
+  }
+  const content = readFileSync3(path, "utf-8");
+  if (content.includes(START) && content.includes(END)) return false;
+  appendFileSync(path, `
+
+${block}`);
+  return true;
+}
+function writeCursorRule(projectRoot) {
+  const path = join3(projectRoot, ".cursor", "rules", "decantr.mdc");
+  const content = `---
+description: Decantr project contract and brownfield adoption bridge
+alwaysApply: true
+---
+
+${bridgeBlock()}`;
+  if (existsSync3(path) && readFileSync3(path, "utf-8") === content) return false;
+  mkdirSync2(dirname(path), { recursive: true });
+  writeFileSync3(path, content);
+  return true;
+}
+function applyAssistantBridge(projectRoot, detected) {
+  const updated = [];
+  const markdownTargets = ["CLAUDE.md", "AGENTS.md", "GEMINI.md", "copilot-instructions.md"];
+  for (const target of markdownTargets) {
+    if (detected.existingRuleFiles.includes(target) && upsertMarkdownBlock(join3(projectRoot, target))) {
+      updated.push(target);
+    }
+  }
+  if (detected.existingRuleFiles.includes(".cursorrules")) {
+    if (upsertMarkdownBlock(join3(projectRoot, ".cursorrules"))) updated.push(".cursorrules");
+  }
+  if (detected.existingRuleFiles.includes(".cursor/rules")) {
+    if (writeCursorRule(projectRoot)) updated.push(".cursor/rules/decantr.mdc");
+  }
+  if (updated.length === 0 && detected.existingRuleFiles.length === 0) {
+    if (writeCursorRule(projectRoot)) updated.push(".cursor/rules/decantr.mdc");
+  }
+  return updated;
+}
+
 // src/commands/analyze.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { join as join12 } from "path";
 
 // src/analyzers/components.ts
-import { existsSync as existsSync3, readdirSync, statSync } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync4, readdirSync, statSync as statSync2 } from "fs";
+import { join as join4 } from "path";
 var PAGE_EXTENSIONS = /* @__PURE__ */ new Set([".tsx", ".ts", ".jsx", ".js"]);
 var ROOT_COMPONENT_CANDIDATES = [
   "src/App.tsx",
@@ -257,9 +398,9 @@ function countFilesRecursive(dir, extensions) {
   }
   for (const entry of entries) {
     if (entry.startsWith(".") || entry === "node_modules") continue;
-    const fullPath = join3(dir, entry);
+    const fullPath = join4(dir, entry);
     try {
-      const stat = statSync(fullPath);
+      const stat = statSync2(fullPath);
       if (stat.isDirectory()) {
         count += countFilesRecursive(fullPath, extensions);
       } else if (stat.isFile()) {
@@ -283,9 +424,9 @@ function countPageFiles(dir) {
   }
   for (const entry of entries) {
     if (entry.startsWith(".") || entry === "node_modules") continue;
-    const fullPath = join3(dir, entry);
+    const fullPath = join4(dir, entry);
     try {
-      const stat = statSync(fullPath);
+      const stat = statSync2(fullPath);
       if (stat.isDirectory()) {
         count += countPageFiles(fullPath);
       } else if (stat.isFile()) {
@@ -301,27 +442,27 @@ function countPageFiles(dir) {
 function scanComponents(projectRoot) {
   let pageCount = 0;
   const componentDirs = [];
-  const appDirs = [join3(projectRoot, "src", "app"), join3(projectRoot, "app")];
+  const appDirs = [join4(projectRoot, "src", "app"), join4(projectRoot, "app")];
   for (const dir of appDirs) {
-    if (existsSync3(dir)) {
+    if (existsSync4(dir)) {
       pageCount += countPageFiles(dir);
     }
   }
-  const pagesDirs = [join3(projectRoot, "src", "pages"), join3(projectRoot, "pages")];
+  const pagesDirs = [join4(projectRoot, "src", "pages"), join4(projectRoot, "pages")];
   for (const dir of pagesDirs) {
-    if (existsSync3(dir)) {
+    if (existsSync4(dir)) {
       pageCount += countFilesRecursive(dir, PAGE_EXTENSIONS);
     }
   }
   let componentCount = 0;
   const componentPaths = [
-    join3(projectRoot, "src", "components"),
-    join3(projectRoot, "components"),
-    join3(projectRoot, "src", "ui"),
-    join3(projectRoot, "ui")
+    join4(projectRoot, "src", "components"),
+    join4(projectRoot, "components"),
+    join4(projectRoot, "src", "ui"),
+    join4(projectRoot, "ui")
   ];
   for (const dir of componentPaths) {
-    if (existsSync3(dir)) {
+    if (existsSync4(dir)) {
       const count = countFilesRecursive(dir, PAGE_EXTENSIONS);
       if (count > 0) {
         componentCount += count;
@@ -331,7 +472,7 @@ function scanComponents(projectRoot) {
     }
   }
   const hasRootAppComponent = ROOT_COMPONENT_CANDIDATES.some(
-    (relativePath) => existsSync3(join3(projectRoot, relativePath))
+    (relativePath) => existsSync4(join4(projectRoot, relativePath))
   );
   if (pageCount === 0 && hasRootAppComponent) {
     pageCount = 1;
@@ -350,8 +491,8 @@ function scanComponents(projectRoot) {
 }
 
 // src/analyzers/dependencies.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join5 } from "path";
 var CATEGORIES = {
   ui: [
     "react",
@@ -501,11 +642,11 @@ function scanDependencies(projectRoot) {
     styling: [],
     other: []
   };
-  const pkgPath = join4(projectRoot, "package.json");
-  if (!existsSync4(pkgPath)) return result;
+  const pkgPath = join5(projectRoot, "package.json");
+  if (!existsSync5(pkgPath)) return result;
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
   } catch {
     return result;
   }
@@ -525,8 +666,8 @@ function scanDependencies(projectRoot) {
 }
 
 // src/analyzers/features.ts
-import { existsSync as existsSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
+import { join as join6 } from "path";
 var FEATURE_PATTERNS = {
   auth: [
     "login",
@@ -579,11 +720,11 @@ function collectPaths(dir, baseDir, depth = 0) {
   for (const entry of entries) {
     if (entry.startsWith(".") || entry.startsWith("_") || entry === "node_modules" || entry === "api")
       continue;
-    const fullPath = join5(dir, entry);
+    const fullPath = join6(dir, entry);
     const relPath = fullPath.slice(baseDir.length + 1);
     paths.push(relPath);
     try {
-      if (statSync2(fullPath).isDirectory()) {
+      if (statSync3(fullPath).isDirectory()) {
         paths.push(...collectPaths(fullPath, baseDir, depth + 1));
       }
     } catch {
@@ -595,16 +736,16 @@ function scanFeatures(projectRoot) {
   const detected = [];
   const evidence = {};
   const scanDirs = [
-    join5(projectRoot, "src", "app"),
-    join5(projectRoot, "app"),
-    join5(projectRoot, "src", "pages"),
-    join5(projectRoot, "pages"),
-    join5(projectRoot, "src", "components"),
-    join5(projectRoot, "components")
+    join6(projectRoot, "src", "app"),
+    join6(projectRoot, "app"),
+    join6(projectRoot, "src", "pages"),
+    join6(projectRoot, "pages"),
+    join6(projectRoot, "src", "components"),
+    join6(projectRoot, "components")
   ];
   const allPaths = [];
   for (const dir of scanDirs) {
-    if (existsSync5(dir)) {
+    if (existsSync6(dir)) {
       allPaths.push(...collectPaths(dir, projectRoot));
     }
   }
@@ -628,8 +769,8 @@ function scanFeatures(projectRoot) {
 }
 
 // src/analyzers/layout.ts
-import { existsSync as existsSync6, readdirSync as readdirSync3, readFileSync as readFileSync4 } from "fs";
-import { join as join6 } from "path";
+import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync5 } from "fs";
+import { join as join7 } from "path";
 var SIDEBAR_PATTERNS = ["sidebar", "side-bar", "sidenav", "side-nav", "drawer", "aside"];
 var NAV_PATTERNS = ["nav", "navbar", "header", "top-bar", "topbar", "app-bar", "appbar"];
 var FOOTER_PATTERNS = ["footer", "bottom-bar", "bottombar"];
@@ -640,12 +781,12 @@ function containsPattern(text, patterns) {
 function checkComponentDirs(projectRoot) {
   const result = { sidebar: false, nav: false, footer: false };
   const componentDirs = [
-    join6(projectRoot, "src", "components"),
-    join6(projectRoot, "components"),
-    join6(projectRoot, "src", "ui")
+    join7(projectRoot, "src", "components"),
+    join7(projectRoot, "components"),
+    join7(projectRoot, "src", "ui")
   ];
   for (const dir of componentDirs) {
-    if (!existsSync6(dir)) continue;
+    if (!existsSync7(dir)) continue;
     let entries;
     try {
       entries = readdirSync3(dir);
@@ -664,16 +805,16 @@ function checkComponentDirs(projectRoot) {
 function checkLayoutFiles(projectRoot) {
   const result = { sidebar: false, nav: false, footer: false };
   const layoutPaths = [
-    join6(projectRoot, "src", "app", "layout.tsx"),
-    join6(projectRoot, "src", "app", "layout.jsx"),
-    join6(projectRoot, "app", "layout.tsx"),
-    join6(projectRoot, "app", "layout.jsx")
+    join7(projectRoot, "src", "app", "layout.tsx"),
+    join7(projectRoot, "src", "app", "layout.jsx"),
+    join7(projectRoot, "app", "layout.tsx"),
+    join7(projectRoot, "app", "layout.jsx")
   ];
   for (const layoutPath of layoutPaths) {
-    if (!existsSync6(layoutPath)) continue;
+    if (!existsSync7(layoutPath)) continue;
     let content;
     try {
-      content = readFileSync4(layoutPath, "utf-8");
+      content = readFileSync5(layoutPath, "utf-8");
     } catch {
       continue;
     }
@@ -684,16 +825,16 @@ function checkLayoutFiles(projectRoot) {
   const subLayoutDirs = ["dashboard", "admin", "app"];
   for (const sub of subLayoutDirs) {
     const paths = [
-      join6(projectRoot, "src", "app", sub, "layout.tsx"),
-      join6(projectRoot, "src", "app", sub, "layout.jsx"),
-      join6(projectRoot, "app", sub, "layout.tsx"),
-      join6(projectRoot, "app", sub, "layout.jsx")
+      join7(projectRoot, "src", "app", sub, "layout.tsx"),
+      join7(projectRoot, "src", "app", sub, "layout.jsx"),
+      join7(projectRoot, "app", sub, "layout.tsx"),
+      join7(projectRoot, "app", sub, "layout.jsx")
     ];
     for (const layoutPath of paths) {
-      if (!existsSync6(layoutPath)) continue;
+      if (!existsSync7(layoutPath)) continue;
       let content;
       try {
-        content = readFileSync4(layoutPath, "utf-8");
+        content = readFileSync5(layoutPath, "utf-8");
       } catch {
         continue;
       }
@@ -715,10 +856,10 @@ function inferShellPattern(hasSidebar, hasTopNav, hasFooter) {
   return "main-only";
 }
 function inferShellPatternFromDecantrContract(projectRoot) {
-  const essencePath = join6(projectRoot, "decantr.essence.json");
-  if (!existsSync6(essencePath)) return null;
+  const essencePath = join7(projectRoot, "decantr.essence.json");
+  if (!existsSync7(essencePath)) return null;
   try {
-    const essence = JSON.parse(readFileSync4(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync5(essencePath, "utf-8"));
     const sectionShells = essence.blueprint?.sections?.map((section) => section.shell).filter((shell) => typeof shell === "string" && shell.length > 0) ?? [];
     if (sectionShells.length === 0 && essence.blueprint?.shell) {
       return `${essence.blueprint.shell} (contract)`;
@@ -754,8 +895,8 @@ function scanLayout(projectRoot) {
 }
 
 // src/analyzers/routes.ts
-import { existsSync as existsSync7, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync as statSync3 } from "fs";
-import { join as join7, relative } from "path";
+import { existsSync as existsSync8, readdirSync as readdirSync4, readFileSync as readFileSync6, statSync as statSync4 } from "fs";
+import { join as join8, relative } from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".next", ".git", "api", "_app", "_document"]);
 function shouldSkipDir(name) {
   return name.startsWith("_") || name.startsWith(".") || SKIP_DIRS.has(name);
@@ -795,15 +936,15 @@ function walkAppDir(dir, baseDir, segments) {
     const pageFile = entries.find((e) => e.startsWith("page."));
     routes.push({
       path: routePath || "/",
-      file: relative(baseDir, join7(dir, pageFile)),
+      file: relative(baseDir, join8(dir, pageFile)),
       hasLayout
     });
   }
   for (const entry of entries) {
     if (shouldSkipDir(entry)) continue;
-    const fullPath = join7(dir, entry);
+    const fullPath = join8(dir, entry);
     try {
-      if (!statSync3(fullPath).isDirectory()) continue;
+      if (!statSync4(fullPath).isDirectory()) continue;
     } catch {
       continue;
     }
@@ -823,9 +964,9 @@ function walkPagesDir(dir, baseDir, segments) {
   }
   for (const entry of entries) {
     if (shouldSkipDir(entry)) continue;
-    const fullPath = join7(dir, entry);
+    const fullPath = join8(dir, entry);
     try {
-      const stat = statSync3(fullPath);
+      const stat = statSync4(fullPath);
       if (stat.isDirectory()) {
         const routeSegment = segmentToRoute(entry);
         const nextSegments = routeSegment === null ? [...segments] : [...segments, routeSegment];
@@ -859,9 +1000,9 @@ function collectRouteCandidateFiles(dir, files, depth = 0) {
   }
   for (const entry of entries) {
     if (entry.startsWith(".") || entry === "node_modules") continue;
-    const fullPath = join7(dir, entry);
+    const fullPath = join8(dir, entry);
     try {
-      const stat = statSync3(fullPath);
+      const stat = statSync4(fullPath);
       if (stat.isDirectory()) {
         collectRouteCandidateFiles(fullPath, files, depth + 1);
       } else if (stat.isFile()) {
@@ -875,16 +1016,16 @@ function collectRouteCandidateFiles(dir, files, depth = 0) {
   }
 }
 function scanReactRouter(projectRoot) {
-  const candidateDirs = [join7(projectRoot, "src"), projectRoot];
+  const candidateDirs = [join8(projectRoot, "src"), projectRoot];
   const candidateFiles = [];
   for (const dir of candidateDirs) {
-    if (existsSync7(dir)) collectRouteCandidateFiles(dir, candidateFiles);
+    if (existsSync8(dir)) collectRouteCandidateFiles(dir, candidateFiles);
   }
   const routeMap = /* @__PURE__ */ new Map();
   for (const absolutePath of candidateFiles) {
     let content;
     try {
-      content = readFileSync5(absolutePath, "utf-8");
+      content = readFileSync6(absolutePath, "utf-8");
     } catch {
       continue;
     }
@@ -914,18 +1055,18 @@ function scanReactRouter(projectRoot) {
   return [...routeMap.values()];
 }
 function scanRoutes(projectRoot) {
-  const appDirs = [join7(projectRoot, "src", "app"), join7(projectRoot, "app")];
+  const appDirs = [join8(projectRoot, "src", "app"), join8(projectRoot, "app")];
   for (const appDir of appDirs) {
-    if (existsSync7(appDir)) {
+    if (existsSync8(appDir)) {
       const routes = walkAppDir(appDir, projectRoot, []);
       if (routes.length > 0) {
         return { strategy: "app-router", routes };
       }
     }
   }
-  const pagesDirs = [join7(projectRoot, "src", "pages"), join7(projectRoot, "pages")];
+  const pagesDirs = [join8(projectRoot, "src", "pages"), join8(projectRoot, "pages")];
   for (const pagesDir of pagesDirs) {
-    if (existsSync7(pagesDir)) {
+    if (existsSync8(pagesDir)) {
       const routes = walkPagesDir(pagesDir, projectRoot, []);
       if (routes.length > 0) {
         return { strategy: "pages-router", routes };
@@ -940,8 +1081,8 @@ function scanRoutes(projectRoot) {
 }
 
 // src/analyzers/styling.ts
-import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
+import { join as join9 } from "path";
 var TAILWIND_CONFIGS = [
   "tailwind.config.js",
   "tailwind.config.ts",
@@ -1003,10 +1144,10 @@ function detectDarkMode(projectRoot, cssContents) {
     "app/layout.jsx"
   ];
   for (const rel of layoutPaths) {
-    const fullPath = join8(projectRoot, rel);
-    if (existsSync8(fullPath)) {
+    const fullPath = join9(projectRoot, rel);
+    if (existsSync9(fullPath)) {
       try {
-        const layoutContent = readFileSync6(fullPath, "utf-8");
+        const layoutContent = readFileSync7(fullPath, "utf-8");
         if (layoutContent.includes('className="dark"') || layoutContent.includes("className='dark'") || layoutContent.includes('class="dark"')) {
           return true;
         }
@@ -1014,10 +1155,10 @@ function detectDarkMode(projectRoot, cssContents) {
       }
     }
   }
-  const pkgPath = join8(projectRoot, "package.json");
-  if (existsSync8(pkgPath)) {
+  const pkgPath = join9(projectRoot, "package.json");
+  if (existsSync9(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync7(pkgPath, "utf-8"));
       const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
       if (allDeps["next-themes"] || allDeps["theme-toggle"] || allDeps["use-dark-mode"]) {
         return true;
@@ -1025,10 +1166,10 @@ function detectDarkMode(projectRoot, cssContents) {
     } catch {
     }
   }
-  const essencePath = join8(projectRoot, "decantr.essence.json");
-  if (existsSync8(essencePath)) {
+  const essencePath = join9(projectRoot, "decantr.essence.json");
+  if (existsSync9(essencePath)) {
     try {
-      const essence = JSON.parse(readFileSync6(essencePath, "utf-8"));
+      const essence = JSON.parse(readFileSync7(essencePath, "utf-8"));
       const mode = essence.dna?.theme?.mode;
       if (mode === "dark" || mode === "auto") {
         return true;
@@ -1042,17 +1183,17 @@ function scanStyling(projectRoot) {
   let approach = "unknown";
   let configFile;
   for (const cfg of TAILWIND_CONFIGS) {
-    if (existsSync8(join8(projectRoot, cfg))) {
+    if (existsSync9(join9(projectRoot, cfg))) {
       approach = "tailwind";
       configFile = cfg;
       break;
     }
   }
   if (approach === "unknown") {
-    const pkgPath = join8(projectRoot, "package.json");
-    if (existsSync8(pkgPath)) {
+    const pkgPath = join9(projectRoot, "package.json");
+    if (existsSync9(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync6(pkgPath, "utf-8"));
+        const pkg = JSON.parse(readFileSync7(pkgPath, "utf-8"));
         const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
         if (allDeps["@decantr/css"]) {
           approach = "decantr-css";
@@ -1065,27 +1206,27 @@ function scanStyling(projectRoot) {
       }
     }
   }
-  const decantrStyleFiles = DECANTR_STYLE_PATHS.filter((rel) => existsSync8(join8(projectRoot, rel)));
+  const decantrStyleFiles = DECANTR_STYLE_PATHS.filter((rel) => existsSync9(join9(projectRoot, rel)));
   if (decantrStyleFiles.length >= 2) {
     approach = "decantr-css";
     configFile = decantrStyleFiles.join(" + ");
   }
   const cssContents = [];
   for (const rel of GLOBALS_CSS_PATHS) {
-    const fullPath = join8(projectRoot, rel);
-    if (existsSync8(fullPath)) {
+    const fullPath = join9(projectRoot, rel);
+    if (existsSync9(fullPath)) {
       try {
-        cssContents.push(readFileSync6(fullPath, "utf-8"));
+        cssContents.push(readFileSync7(fullPath, "utf-8"));
       } catch {
       }
     }
   }
   for (const rel of DECANTR_STYLE_PATHS) {
     if (GLOBALS_CSS_PATHS.includes(rel)) continue;
-    const fullPath = join8(projectRoot, rel);
-    if (existsSync8(fullPath)) {
+    const fullPath = join9(projectRoot, rel);
+    if (existsSync9(fullPath)) {
       try {
-        cssContents.push(readFileSync6(fullPath, "utf-8"));
+        cssContents.push(readFileSync7(fullPath, "utf-8"));
       } catch {
       }
     }
@@ -1101,7 +1242,7 @@ function scanStyling(projectRoot) {
   const darkMode = detectDarkMode(projectRoot, cssContents);
   if (approach === "unknown" && cssContents.length > 0) {
     approach = "css";
-    configFile = GLOBALS_CSS_PATHS.find((rel) => existsSync8(join8(projectRoot, rel)));
+    configFile = GLOBALS_CSS_PATHS.find((rel) => existsSync9(join9(projectRoot, rel)));
   }
   return {
     approach,
@@ -1113,8 +1254,8 @@ function scanStyling(projectRoot) {
 }
 
 // src/detect.ts
-import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync8 } from "fs";
+import { join as join10 } from "path";
 var RULE_FILES = [
   "CLAUDE.md",
   ".cursorrules",
@@ -1133,52 +1274,52 @@ function detectProject(projectRoot = process.cwd()) {
     existingEssence: false,
     projectRoot
   };
-  result.existingEssence = existsSync9(join9(projectRoot, "decantr.essence.json"));
+  result.existingEssence = existsSync10(join10(projectRoot, "decantr.essence.json"));
   for (const ruleFile of RULE_FILES) {
-    if (existsSync9(join9(projectRoot, ruleFile))) {
+    if (existsSync10(join10(projectRoot, ruleFile))) {
       result.existingRuleFiles.push(ruleFile);
     }
   }
-  if (existsSync9(join9(projectRoot, "pnpm-lock.yaml"))) {
+  if (existsSync10(join10(projectRoot, "pnpm-lock.yaml"))) {
     result.packageManager = "pnpm";
-  } else if (existsSync9(join9(projectRoot, "yarn.lock"))) {
+  } else if (existsSync10(join10(projectRoot, "yarn.lock"))) {
     result.packageManager = "yarn";
-  } else if (existsSync9(join9(projectRoot, "bun.lockb"))) {
+  } else if (existsSync10(join10(projectRoot, "bun.lockb"))) {
     result.packageManager = "bun";
-  } else if (existsSync9(join9(projectRoot, "package-lock.json"))) {
+  } else if (existsSync10(join10(projectRoot, "package-lock.json"))) {
     result.packageManager = "npm";
   }
-  result.hasTypeScript = existsSync9(join9(projectRoot, "tsconfig.json"));
-  result.hasTailwind = existsSync9(join9(projectRoot, "tailwind.config.js")) || existsSync9(join9(projectRoot, "tailwind.config.ts")) || existsSync9(join9(projectRoot, "tailwind.config.mjs")) || existsSync9(join9(projectRoot, "tailwind.config.cjs"));
-  if (existsSync9(join9(projectRoot, "next.config.js")) || existsSync9(join9(projectRoot, "next.config.ts")) || existsSync9(join9(projectRoot, "next.config.mjs"))) {
+  result.hasTypeScript = existsSync10(join10(projectRoot, "tsconfig.json"));
+  result.hasTailwind = existsSync10(join10(projectRoot, "tailwind.config.js")) || existsSync10(join10(projectRoot, "tailwind.config.ts")) || existsSync10(join10(projectRoot, "tailwind.config.mjs")) || existsSync10(join10(projectRoot, "tailwind.config.cjs"));
+  if (existsSync10(join10(projectRoot, "next.config.js")) || existsSync10(join10(projectRoot, "next.config.ts")) || existsSync10(join10(projectRoot, "next.config.mjs"))) {
     result.framework = "nextjs";
     result.version = getPackageVersion(projectRoot, "next");
     return result;
   }
-  if (existsSync9(join9(projectRoot, "nuxt.config.js")) || existsSync9(join9(projectRoot, "nuxt.config.ts"))) {
+  if (existsSync10(join10(projectRoot, "nuxt.config.js")) || existsSync10(join10(projectRoot, "nuxt.config.ts"))) {
     result.framework = "nuxt";
     result.version = getPackageVersion(projectRoot, "nuxt");
     return result;
   }
-  if (existsSync9(join9(projectRoot, "astro.config.mjs")) || existsSync9(join9(projectRoot, "astro.config.ts"))) {
+  if (existsSync10(join10(projectRoot, "astro.config.mjs")) || existsSync10(join10(projectRoot, "astro.config.ts"))) {
     result.framework = "astro";
     result.version = getPackageVersion(projectRoot, "astro");
     return result;
   }
-  if (existsSync9(join9(projectRoot, "svelte.config.js")) || existsSync9(join9(projectRoot, "svelte.config.ts"))) {
+  if (existsSync10(join10(projectRoot, "svelte.config.js")) || existsSync10(join10(projectRoot, "svelte.config.ts"))) {
     result.framework = "svelte";
     result.version = getPackageVersion(projectRoot, "svelte");
     return result;
   }
-  if (existsSync9(join9(projectRoot, "angular.json"))) {
+  if (existsSync10(join10(projectRoot, "angular.json"))) {
     result.framework = "angular";
     result.version = getPackageVersion(projectRoot, "@angular/core");
     return result;
   }
-  const packageJsonPath = join9(projectRoot, "package.json");
-  if (existsSync9(packageJsonPath)) {
+  const packageJsonPath = join10(projectRoot, "package.json");
+  if (existsSync10(packageJsonPath)) {
     try {
-      const packageJson = JSON.parse(readFileSync7(packageJsonPath, "utf-8"));
+      const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf-8"));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
       if (deps.next) {
         result.framework = "nextjs";
@@ -1205,18 +1346,18 @@ function detectProject(projectRoot = process.cwd()) {
     } catch {
     }
   }
-  if (result.framework === "unknown" && !existsSync9(packageJsonPath)) {
-    if (existsSync9(join9(projectRoot, "index.html"))) {
+  if (result.framework === "unknown" && !existsSync10(packageJsonPath)) {
+    if (existsSync10(join10(projectRoot, "index.html"))) {
       result.framework = "html";
     }
   }
   return result;
 }
 function getPackageVersion(projectRoot, packageName) {
-  const packageJsonPath = join9(projectRoot, "package.json");
-  if (!existsSync9(packageJsonPath)) return void 0;
+  const packageJsonPath = join10(projectRoot, "package.json");
+  if (!existsSync10(packageJsonPath)) return void 0;
   try {
-    const packageJson = JSON.parse(readFileSync7(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf-8"));
     const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
     const version = deps[packageName];
     return version?.replace(/^\^|~/, "");
@@ -1249,8 +1390,8 @@ function formatDetection(detected) {
 }
 
 // src/workflow-model.ts
-import { existsSync as existsSync10, readFileSync as readFileSync8 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync9 } from "fs";
+import { join as join11 } from "path";
 function inferSuggestedShell(layout) {
   if (layout.hasSidebar) return "sidebar-main";
   if (layout.hasTopNav) return "top-nav-main";
@@ -1259,6 +1400,58 @@ function inferSuggestedShell(layout) {
 function hasExistingProjectFootprint(detected) {
   return detected.framework !== "unknown" || detected.packageManager !== "unknown" || detected.hasTypeScript || detected.hasTailwind || detected.existingRuleFiles.length > 0;
 }
+function normalizeWorkflowFlag(value) {
+  if (value === "greenfield" || value === "brownfield" || value === "hybrid") return value;
+  return void 0;
+}
+function normalizeAdoptionMode(value) {
+  if (value === "contract-only" || value === "style-bridge" || value === "decantr-css") {
+    return value;
+  }
+  return void 0;
+}
+function normalizeAssistantBridge(value) {
+  if (value === "none" || value === "preview" || value === "apply") return value;
+  return void 0;
+}
+function resolveWorkflowPolicy(input) {
+  const requestedWorkflow = normalizeWorkflowFlag(input.requestedWorkflow);
+  const requestedAdoption = normalizeAdoptionMode(input.requestedAdoption);
+  const requestedAssistantBridge = normalizeAssistantBridge(input.requestedAssistantBridge);
+  const hasRegistryContent = Boolean(
+    input.requestedBlueprint || input.requestedArchetype || input.requestedTheme
+  );
+  const hasAnalysisArtifacts = Boolean(input.workflowSeed);
+  const existingFootprint = hasExistingProjectFootprint(input.detected);
+  let workflowMode;
+  if (requestedWorkflow === "hybrid") {
+    workflowMode = "hybrid-compose";
+  } else if (requestedWorkflow === "brownfield" || input.explicitExisting || input.workflowSeed) {
+    workflowMode = "brownfield-attach";
+  } else if (requestedWorkflow === "greenfield") {
+    workflowMode = hasRegistryContent ? "greenfield-scaffold" : "greenfield-contract-only";
+  } else if (input.command === "new") {
+    workflowMode = hasRegistryContent ? "greenfield-scaffold" : "greenfield-contract-only";
+  } else if (existingFootprint && hasRegistryContent) {
+    workflowMode = "hybrid-compose";
+  } else if (existingFootprint && !hasRegistryContent) {
+    workflowMode = "brownfield-attach";
+  } else {
+    workflowMode = hasRegistryContent ? "greenfield-scaffold" : "greenfield-contract-only";
+  }
+  const adoptionMode = requestedAdoption ?? input.workflowSeed?.adoptionMode ?? (workflowMode === "brownfield-attach" ? "contract-only" : workflowMode === "hybrid-compose" ? "contract-only" : workflowMode === "greenfield-contract-only" ? "contract-only" : "decantr-css");
+  const contentSource = hasRegistryContent ? input.offline ? "cache" : "official" : "none";
+  const assistantBridge = requestedAssistantBridge ?? input.workflowSeed?.assistantBridge ?? (workflowMode === "brownfield-attach" && input.detected.existingRuleFiles.length > 0 ? "preview" : "none");
+  return {
+    workflowMode,
+    adoptionMode,
+    contentSource,
+    assistantBridge,
+    projectScope: input.projectScope ?? "single-app",
+    hasAnalysisArtifacts,
+    registryRequired: hasRegistryContent
+  };
+}
 function createBrownfieldInitSeed(detected, layout, styling) {
   return {
     version: 1,
@@ -1266,6 +1459,10 @@ function createBrownfieldInitSeed(detected, layout, styling) {
     contractOnly: true,
     registryOptional: true,
     workflowMode: "brownfield-attach",
+    adoptionMode: "contract-only",
+    contentSource: "none",
+    assistantBridge: detected.existingRuleFiles.length > 0 ? "preview" : "none",
+    projectScope: "single-app",
     target: detected.framework !== "unknown" ? detected.framework : "react",
     shell: inferSuggestedShell(layout),
     guard: "guided",
@@ -1281,12 +1478,12 @@ function createBrownfieldInitSeed(detected, layout, styling) {
   };
 }
 function readBrownfieldInitSeed(projectRoot) {
-  const seedPath = join10(projectRoot, ".decantr", "init-seed.json");
-  if (!existsSync10(seedPath)) {
+  const seedPath = join11(projectRoot, ".decantr", "init-seed.json");
+  if (!existsSync11(seedPath)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(readFileSync8(seedPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync9(seedPath, "utf-8"));
     if (parsed.workflow !== "brownfield-adoption") {
       return null;
     }
@@ -1303,7 +1500,7 @@ var RESET2 = "\x1B[0m";
 var GREEN2 = "\x1B[32m";
 var CYAN = "\x1B[36m";
 var YELLOW = "\x1B[33m";
-function cmdAnalyze(projectRoot = process.cwd()) {
+function cmdAnalyze(projectRoot = process.cwd(), workspace) {
   console.log(`
 ${BOLD}Analyzing project...${RESET2}
 `);
@@ -1322,6 +1519,7 @@ ${BOLD}Analyzing project...${RESET2}
   console.log(`${DIM2}Scanning dependencies...${RESET2}`);
   const dependencies = scanDependencies(projectRoot);
   const initSeed = createBrownfieldInitSeed(project, layout, styling);
+  initSeed.projectScope = workspace?.projectScope ?? "single-app";
   const analysis = {
     version: 1,
     analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1330,7 +1528,11 @@ ${BOLD}Analyzing project...${RESET2}
       frameworkVersion: project.version ?? null,
       packageManager: project.packageManager,
       hasTypeScript: project.hasTypeScript,
-      hasTailwind: project.hasTailwind
+      hasTailwind: project.hasTailwind,
+      existingRuleFiles: project.existingRuleFiles,
+      workspaceRoot: workspace?.workspaceRoot ?? projectRoot,
+      appRoot: workspace?.appRoot ?? projectRoot,
+      projectScope: workspace?.projectScope ?? "single-app"
     },
     routes,
     components,
@@ -1344,8 +1546,9 @@ ${BOLD}Analyzing project...${RESET2}
       attach: {
         entrypoint: "decantr analyze",
         contractOnly: true,
+        adoptionMode: "contract-only",
         initSeedPath: ".decantr/init-seed.json",
-        recommendedCommand: "decantr init --existing --yes"
+        recommendedCommand: "decantr init --existing --yes --adoption=contract-only"
       },
       hybrid: {
         ownerCommands: [
@@ -1356,16 +1559,31 @@ ${BOLD}Analyzing project...${RESET2}
           "decantr upgrade"
         ]
       }
+    },
+    retrofitPlan: {
+      recommendedWorkflowMode: "brownfield-attach",
+      recommendedAdoptionMode: "contract-only",
+      assistantBridge: project.existingRuleFiles.length > 0 ? "preview existing rule files before applying" : "none detected",
+      routeAnchors: routes.routes.map((route) => route.path),
+      stylingAnchors: [styling.configFile].filter(Boolean),
+      ruleFiles: project.existingRuleFiles,
+      preserve: [
+        "framework",
+        "package manager",
+        "router",
+        "build tooling",
+        "existing styling system"
+      ]
     }
   };
-  const decantrDir = join11(projectRoot, ".decantr");
-  if (!existsSync11(decantrDir)) {
-    mkdirSync2(decantrDir, { recursive: true });
-  }
-  const outputPath = join11(decantrDir, "analysis.json");
-  const initSeedPath = join11(decantrDir, "init-seed.json");
-  writeFileSync3(outputPath, JSON.stringify(analysis, null, 2) + "\n", "utf-8");
-  writeFileSync3(initSeedPath, JSON.stringify(initSeed, null, 2) + "\n", "utf-8");
+  const decantrDir = join12(projectRoot, ".decantr");
+  if (!existsSync12(decantrDir)) {
+    mkdirSync3(decantrDir, { recursive: true });
+  }
+  const outputPath = join12(decantrDir, "analysis.json");
+  const initSeedPath = join12(decantrDir, "init-seed.json");
+  writeFileSync4(outputPath, JSON.stringify(analysis, null, 2) + "\n", "utf-8");
+  writeFileSync4(initSeedPath, JSON.stringify(initSeed, null, 2) + "\n", "utf-8");
   console.log(`
 ${GREEN2}Analysis complete.${RESET2}
 `);
@@ -1399,14 +1617,14 @@ ${DIM2}Written to:${RESET2} ${outputPath}`);
   console.log(`${DIM2}Init seed:${RESET2} ${initSeedPath}`);
   console.log(
     `
-${YELLOW}Next step:${RESET2} Run ${BOLD}decantr init --existing --yes${RESET2} to attach Decantr using the generated brownfield seed.
+${YELLOW}Next step:${RESET2} Run ${BOLD}decantr init --existing --yes --adoption=contract-only${RESET2} to attach Decantr using the generated brownfield seed.
 `
   );
 }
 
 // src/commands/create.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
+import { join as join13 } from "path";
 import {
   CONTENT_TYPE_TO_API_CONTENT_TYPE,
   CONTENT_TYPES
@@ -1602,23 +1820,23 @@ function cmdCreate(type, name, projectRoot = process.cwd()) {
   }
   const contentType = type;
   const plural = PLURAL[contentType];
-  const customDir = join12(projectRoot, ".decantr", "custom", plural);
-  const filePath = join12(customDir, `${name}.json`);
-  if (existsSync12(filePath)) {
+  const customDir = join13(projectRoot, ".decantr", "custom", plural);
+  const filePath = join13(customDir, `${name}.json`);
+  if (existsSync13(filePath)) {
     console.error(`${type} "${name}" already exists at ${filePath}`);
     process.exitCode = 1;
     return;
   }
-  mkdirSync3(customDir, { recursive: true });
+  mkdirSync4(customDir, { recursive: true });
   const skeleton = getSkeleton(contentType, name, humanizeId(name));
-  writeFileSync4(filePath, JSON.stringify(skeleton, null, 2));
+  writeFileSync5(filePath, JSON.stringify(skeleton, null, 2));
   console.log(`Created ${type} "${name}" at ${filePath}`);
   console.log(`Edit it, then publish with: decantr publish ${type} ${name}`);
 }
 
 // src/commands/export.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "fs";
-import { dirname, join as join13 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
+import { dirname as dirname2, join as join14 } from "path";
 var GREEN3 = "\x1B[32m";
 var RED2 = "\x1B[31m";
 var DIM3 = "\x1B[2m";
@@ -1768,21 +1986,21 @@ function generateCSSVars(tokens) {
   return lines.join("\n");
 }
 async function cmdExport(target, projectRoot, options = {}) {
-  const essencePath = join13(projectRoot, "decantr.essence.json");
-  const tokensPath = join13(projectRoot, "src", "styles", "tokens.css");
-  if (!existsSync13(essencePath)) {
+  const essencePath = join14(projectRoot, "decantr.essence.json");
+  const tokensPath = join14(projectRoot, "src", "styles", "tokens.css");
+  if (!existsSync14(essencePath)) {
     console.error(`${RED2}No decantr.essence.json found. Run \`decantr init\` first.${RESET3}`);
     process.exitCode = 1;
     return;
   }
-  if (!existsSync13(tokensPath)) {
+  if (!existsSync14(tokensPath)) {
     console.error(
       `${RED2}No src/styles/tokens.css found. Run \`decantr refresh\` to generate tokens.${RESET3}`
     );
     process.exitCode = 1;
     return;
   }
-  const tokensCSS = readFileSync9(tokensPath, "utf-8");
+  const tokensCSS = readFileSync10(tokensPath, "utf-8");
   const tokens = parseTokensCSS(tokensCSS);
   if (tokens.size === 0) {
     console.error(`${RED2}No --d-* tokens found in tokens.css.${RESET3}`);
@@ -1791,28 +2009,28 @@ async function cmdExport(target, projectRoot, options = {}) {
   }
   switch (target) {
     case "shadcn": {
-      const cssOut = options.output ?? join13(projectRoot, "src", "styles", "shadcn-theme.css");
-      const jsonOut = join13(projectRoot, "components.json");
+      const cssOut = options.output ?? join14(projectRoot, "src", "styles", "shadcn-theme.css");
+      const jsonOut = join14(projectRoot, "components.json");
       ensureDir(cssOut);
-      writeFileSync5(cssOut, generateShadcnCSS(tokens), "utf-8");
-      writeFileSync5(jsonOut, generateShadcnComponentsJSON(), "utf-8");
+      writeFileSync6(cssOut, generateShadcnCSS(tokens), "utf-8");
+      writeFileSync6(jsonOut, generateShadcnComponentsJSON(), "utf-8");
       console.log(`${GREEN3}Exported shadcn theme:${RESET3}`);
       console.log(`  ${DIM3}CSS:${RESET3}  ${cssOut}`);
       console.log(`  ${DIM3}JSON:${RESET3} ${jsonOut}`);
       break;
     }
     case "tailwind": {
-      const out = options.output ?? join13(projectRoot, "tailwind.decantr.config.ts");
+      const out = options.output ?? join14(projectRoot, "tailwind.decantr.config.ts");
       ensureDir(out);
-      writeFileSync5(out, generateTailwindConfig(tokens), "utf-8");
+      writeFileSync6(out, generateTailwindConfig(tokens), "utf-8");
       console.log(`${GREEN3}Exported Tailwind config:${RESET3}`);
       console.log(`  ${DIM3}File:${RESET3} ${out}`);
       break;
     }
     case "css-vars": {
-      const out = options.output ?? join13(projectRoot, "decantr-tokens.css");
+      const out = options.output ?? join14(projectRoot, "decantr-tokens.css");
       ensureDir(out);
-      writeFileSync5(out, generateCSSVars(tokens), "utf-8");
+      writeFileSync6(out, generateCSSVars(tokens), "utf-8");
       console.log(`${GREEN3}Exported CSS variables:${RESET3}`);
       console.log(`  ${DIM3}File:${RESET3} ${out}`);
       break;
@@ -1820,16 +2038,16 @@ async function cmdExport(target, projectRoot, options = {}) {
   }
 }
 function ensureDir(filePath) {
-  const dir = dirname(filePath);
-  if (!existsSync13(dir)) {
-    mkdirSync4(dir, { recursive: true });
+  const dir = dirname2(filePath);
+  if (!existsSync14(dir)) {
+    mkdirSync5(dir, { recursive: true });
   }
 }
 
 // src/commands/magic.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import * as fs from "fs/promises";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 var BOLD2 = "\x1B[1m";
 var DIM4 = "\x1B[2m";
 var RESET4 = "\x1B[0m";
@@ -1979,7 +2197,8 @@ async function resolveTheme(intent, registryClient) {
   const hints = intent.themeHints;
   if (registryClient) {
     try {
-      const themes = await registryClient.fetchThemes();
+      const themesResult = await registryClient.fetchThemes();
+      const themes = Array.isArray(themesResult) ? themesResult : Array.isArray(themesResult?.data?.items) ? themesResult.data.items : [];
       if (themes && themes.length > 0) {
         const scored = themes.map((t) => {
           let score = 0;
@@ -1994,7 +2213,7 @@ async function resolveTheme(intent, registryClient) {
           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";
+          const mode2 = intent.themeHints.includes("light") ? "light" : intent.themeHints.includes("dark") ? "dark" : scored[0].modes?.includes("light") ? "light" : scored[0].modes?.includes("dark") ? "dark" : "light";
           return { id: scored[0].id, mode: mode2 };
         }
       }
@@ -2056,8 +2275,8 @@ async function cmdMagic(prompt, projectRoot, options) {
     console.log(`   Archetype:    ${intent.archetype}`);
   }
   console.log("");
-  const essencePath = join14(projectRoot, "decantr.essence.json");
-  if (existsSync14(essencePath)) {
+  const essencePath = join15(projectRoot, "decantr.essence.json");
+  if (existsSync15(essencePath)) {
     console.log(error("  decantr.essence.json already exists in this directory."));
     console.log(dim("  Remove it first or use a different directory."));
     process.exitCode = 1;
@@ -2080,7 +2299,7 @@ async function cmdMagic(prompt, projectRoot, options) {
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join14(projectRoot, ".decantr", "cache"),
+    cacheDir: join15(projectRoot, ".decantr", "cache"),
     apiUrl: options.registry,
     offline: options.offline
   });
@@ -2351,14 +2570,14 @@ async function cmdMagic(prompt, projectRoot, options) {
   if (result.gitignoreUpdated) {
     console.log(`   ${dim(".gitignore updated")}`);
   }
-  const contextDir = join14(projectRoot, ".decantr", "context");
+  const contextDir = join15(projectRoot, ".decantr", "context");
   let sectionCount = 0;
   try {
     const files = await fs.readdir(contextDir);
     sectionCount = files.filter((f) => f.startsWith("section-")).length;
   } catch {
   }
-  const treatmentsPath = join14(projectRoot, "src", "styles", "treatments.css");
+  const treatmentsPath = join15(projectRoot, "src", "styles", "treatments.css");
   let hasLayers = false;
   try {
     const css = await fs.readFile(treatmentsPath, "utf-8");
@@ -2376,27 +2595,23 @@ ${GREEN4}${BOLD2}Quality summary:${RESET4}`);
   );
   console.log("");
   console.log(`${BOLD2} Ready!${RESET4} Next steps:`);
-  console.log(`   1. Read ${cyan("DECANTR.md")} for guard rules, CSS approach, and workflow`);
-  console.log(
-    `   2. Read ${cyan(".decantr/context/scaffold-pack.md")} first as the primary compiled contract`
-  );
   console.log(
-    `   3. Read ${cyan(".decantr/context/scaffold.md")} second for broader topology and voice guidance`
+    `   1. Read ${cyan(".decantr/context/scaffold-pack.md")} first as the primary compiled contract`
   );
   console.log(
-    `   4. Read the matching ${cyan(".decantr/context/section-*-pack.md")} and ${cyan(".decantr/context/section-*.md")} files before section work`
+    `   2. Read the matching ${cyan(".decantr/context/section-*-pack.md")} and ${cyan(".decantr/context/page-*-pack.md")} files before section or route work`
   );
   console.log(
-    `   5. Read the matching ${cyan(".decantr/context/page-*-pack.md")} file before route work`
+    `   3. Use ${cyan("DECANTR.md")} as a lookup reference for guard rules, CSS atoms, treatments, decorators, and workflow`
   );
-  console.log(`   6. Build the shell and route structure first, then implement each page`);
-  console.log(`   7. Run ${cyan("decantr check")} and ${cyan("decantr audit")} before you ship`);
+  console.log(`   4. Build the shell and route structure first, then implement each page`);
+  console.log(`   5. Run ${cyan("decantr check")} and ${cyan("decantr audit")} before you ship`);
   console.log("");
 }
 
 // src/commands/migrate.ts
-import { copyFileSync, existsSync as existsSync15, readFileSync as readFileSync10, writeFileSync as writeFileSync6 } from "fs";
-import { join as join15 } from "path";
+import { copyFileSync, existsSync as existsSync16, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
+import { join as join16 } from "path";
 import { isV3 as isV32, migrateV2ToV3, validateEssence } from "@decantr/essence-spec";
 var GREEN5 = "\x1B[32m";
 var RED4 = "\x1B[31m";
@@ -2404,12 +2619,12 @@ var YELLOW3 = "\x1B[33m";
 var RESET5 = "\x1B[0m";
 var DIM5 = "\x1B[2m";
 function migrateEssenceFile(essencePath) {
-  if (!existsSync15(essencePath)) {
+  if (!existsSync16(essencePath)) {
     return { success: false, error: `File not found: ${essencePath}` };
   }
   let raw;
   try {
-    raw = readFileSync10(essencePath, "utf-8");
+    raw = readFileSync11(essencePath, "utf-8");
   } catch (e) {
     return { success: false, error: `Could not read ${essencePath}: ${e.message}` };
   }
@@ -2450,7 +2665,7 @@ function migrateEssenceFile(essencePath) {
     };
   }
   try {
-    writeFileSync6(essencePath, JSON.stringify(v3, null, 2) + "\n");
+    writeFileSync7(essencePath, JSON.stringify(v3, null, 2) + "\n");
   } catch (e) {
     return {
       success: false,
@@ -2461,8 +2676,8 @@ function migrateEssenceFile(essencePath) {
   return { success: true, backupPath };
 }
 async function cmdMigrate(projectRoot = process.cwd()) {
-  const essencePath = join15(projectRoot, "decantr.essence.json");
-  if (!existsSync15(essencePath)) {
+  const essencePath = join16(projectRoot, "decantr.essence.json");
+  if (!existsSync16(essencePath)) {
     console.error(`${RED4}No decantr.essence.json found. Run \`decantr init\` first.${RESET5}`);
     process.exitCode = 1;
     return;
@@ -2487,20 +2702,38 @@ async function cmdMigrate(projectRoot = process.cwd()) {
 }
 
 // src/commands/new-project.ts
-import { execSync } from "child_process";
-import { existsSync as existsSync17, mkdirSync as mkdirSync7 } from "fs";
-import { join as join18, resolve as resolve2 } from "path";
+import { spawnSync } from "child_process";
+import { existsSync as existsSync18, mkdirSync as mkdirSync8 } from "fs";
+import { join as join19, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/bootstrap.ts
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync7 } from "fs";
-import { basename, join as join16 } from "path";
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync12, writeFileSync as writeFileSync8 } from "fs";
+import { basename, join as join17 } from "path";
 import { resolvePackAdapter } from "@decantr/core";
 var reactViteBootstrapAdapter = {
   id: "react-vite",
   label: "React + Vite starter",
+  target: "react",
+  packAdapter: "react-vite",
+  capabilities: {
+    bootstrap: true,
+    attach: true,
+    styling: true,
+    verify: true
+  },
+  attach: {
+    routeRoots: ["src/App.tsx", "src/routes", "src/pages"],
+    layoutFiles: ["src/App.tsx", "src/main.tsx"],
+    componentRoots: ["src/components", "src/pages", "src/routes"]
+  },
+  verify: {
+    devCommand: "npm run dev",
+    buildCommand: "npm run build",
+    distDir: "dist"
+  },
   writeProjectFiles(projectDir, title, routingMode) {
-    const srcDir = join16(projectDir, "src");
+    const srcDir = join17(projectDir, "src");
     const routerImport = routingMode === "hash" ? "HashRouter" : "BrowserRouter";
     const packageJson = {
       name: basename(projectDir) || "decantr-app",
@@ -2532,7 +2765,7 @@ var reactViteBootstrapAdapter = {
         vite: "^6.0.0"
       }
     };
-    writeFileSync7(join16(projectDir, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
+    writeFileSync8(join17(projectDir, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
     const viteConfig = `import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 
@@ -2540,7 +2773,7 @@ export default defineConfig({
   plugins: [react()],
 });
 `;
-    writeFileSync7(join16(projectDir, "vite.config.ts"), viteConfig);
+    writeFileSync8(join17(projectDir, "vite.config.ts"), viteConfig);
     const tsconfig = {
       compilerOptions: {
         target: "ES2020",
@@ -2562,7 +2795,7 @@ export default defineConfig({
       },
       include: ["src"]
     };
-    writeFileSync7(join16(projectDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
+    writeFileSync8(join17(projectDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2) + "\n");
     const tsconfigApp = {
       compilerOptions: {
         tsBuildInfoFile: "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
@@ -2585,8 +2818,8 @@ export default defineConfig({
       },
       include: ["src"]
     };
-    writeFileSync7(
-      join16(projectDir, "tsconfig.app.json"),
+    writeFileSync8(
+      join17(projectDir, "tsconfig.app.json"),
       JSON.stringify(tsconfigApp, null, 2) + "\n"
     );
     const indexHtml = `<!doctype html>
@@ -2602,8 +2835,8 @@ export default defineConfig({
   </body>
 </html>
 `;
-    writeFileSync7(join16(projectDir, "index.html"), indexHtml);
-    mkdirSync5(srcDir, { recursive: true });
+    writeFileSync8(join17(projectDir, "index.html"), indexHtml);
+    mkdirSync6(srcDir, { recursive: true });
     const mainTsx = `import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { ${routerImport} } from 'react-router-dom';
@@ -2620,7 +2853,7 @@ createRoot(document.getElementById('root')!).render(
   </StrictMode>,
 );
 `;
-    writeFileSync7(join16(srcDir, "main.tsx"), mainTsx);
+    writeFileSync8(join17(srcDir, "main.tsx"), mainTsx);
     const appTsx = `import { css } from '@decantr/css';
 import { Routes, Route } from 'react-router-dom';
 
@@ -2634,7 +2867,7 @@ function WelcomePage() {
             <p className="d-label" data-anchor>Decantr starter</p>
             <h1 className={css('_heading2')}>${title}</h1>
             <p className={css('_textsm _fgmuted _mw[32rem]')}>
-              Scaffolded with Decantr. Read DECANTR.md and the compiled packs in .decantr/context before building routes.
+              Scaffolded with Decantr. Read .decantr/context/scaffold-pack.md first, then use DECANTR.md as a lookup reference.
             </p>
             <div className={css('_flex _gap3 _wrap _jcc')}>
               <span className="d-annotation" data-status="info">Runtime: @decantr/css</span>
@@ -2655,34 +2888,184 @@ export function App() {
   );
 }
 `;
-    writeFileSync7(join16(srcDir, "App.tsx"), appTsx);
-    writeFileSync7(join16(srcDir, "vite-env.d.ts"), '/// <reference types="vite/client" />\n');
-    mkdirSync5(join16(srcDir, "styles"), { recursive: true });
+    writeFileSync8(join17(srcDir, "App.tsx"), appTsx);
+    writeFileSync8(join17(srcDir, "vite-env.d.ts"), '/// <reference types="vite/client" />\n');
+    mkdirSync6(join17(srcDir, "styles"), { recursive: true });
   }
 };
-var BOOTSTRAP_ADAPTERS = {
-  "react-vite": reactViteBootstrapAdapter
+var nextAppAdapter = {
+  id: "next-app",
+  label: "Next.js App Router starter",
+  target: "nextjs",
+  packAdapter: "nextjs",
+  capabilities: {
+    bootstrap: true,
+    attach: true,
+    styling: true,
+    verify: true
+  },
+  attach: {
+    routeRoots: ["app", "pages"],
+    layoutFiles: ["app/layout.tsx", "pages/_app.tsx"],
+    componentRoots: ["components", "src/components", "app"]
+  },
+  verify: {
+    devCommand: "npm run dev",
+    buildCommand: "npm run build",
+    distDir: ".next"
+  },
+  writeProjectFiles(projectDir, title) {
+    const appDir = join17(projectDir, "app");
+    const stylesDir = join17(projectDir, "src", "styles");
+    const packageJson = {
+      name: basename(projectDir) || "decantr-next-app",
+      private: true,
+      version: "0.0.0",
+      type: "module",
+      scripts: {
+        dev: "next dev",
+        build: "next build",
+        start: "next start"
+      },
+      dependencies: {
+        "@decantr/css": "^1.0.4",
+        "lucide-react": "^0.468.0",
+        next: "^16.0.0",
+        react: "^19.0.0",
+        "react-dom": "^19.0.0"
+      },
+      devDependencies: {
+        "@types/node": "^20.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        typescript: "^5.7.0"
+      }
+    };
+    writeFileSync8(join17(projectDir, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
+    writeFileSync8(join17(projectDir, "next.config.ts"), 'import type { NextConfig } from "next";\n\nconst nextConfig: NextConfig = {};\n\nexport default nextConfig;\n');
+    writeFileSync8(join17(projectDir, "next-env.d.ts"), '/// <reference types="next" />\n/// <reference types="next/image-types/global" />\n\n// This file is generated by Next.js.\n');
+    writeFileSync8(
+      join17(projectDir, "tsconfig.json"),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            target: "ES2017",
+            lib: ["dom", "dom.iterable", "esnext"],
+            allowJs: true,
+            skipLibCheck: true,
+            strict: true,
+            noEmit: true,
+            esModuleInterop: true,
+            module: "esnext",
+            moduleResolution: "bundler",
+            resolveJsonModule: true,
+            isolatedModules: true,
+            jsx: "preserve",
+            incremental: true,
+            plugins: [{ name: "next" }]
+          },
+          include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+          exclude: ["node_modules"]
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    mkdirSync6(appDir, { recursive: true });
+    mkdirSync6(stylesDir, { recursive: true });
+    writeFileSync8(
+      join17(appDir, "layout.tsx"),
+      `import type { Metadata } from 'next';
+import '../src/styles/global.css';
+import '../src/styles/tokens.css';
+import '../src/styles/treatments.css';
+
+export const metadata: Metadata = {
+  title: '${title}',
+  description: 'Scaffolded with Decantr',
+};
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+`
+    );
+    writeFileSync8(
+      join17(appDir, "page.tsx"),
+      `import { css } from '@decantr/css';
+
+export default function HomePage() {
+  return (
+    <main id="main-content" className={css('_minh[100vh] _flex _col _aic _jcc _p6 _gap4')}>
+      <section className={css('_wfull _mw[42rem]') + ' d-section'} data-density="comfortable">
+        <div className={css('_flex _col _aic _gap4 _textc') + ' d-surface'} data-elevation="raised">
+          <p className="d-label" data-anchor>Decantr starter</p>
+          <h1 className={css('_heading2')}>${title}</h1>
+          <p className={css('_textsm _fgmuted _mw[32rem]')}>Scaffolded with Decantr. Read .decantr/context/scaffold-pack.md first, then use DECANTR.md as a lookup reference.</p>
+          <span className="d-annotation" data-status="info">Runtime: Next.js App Router</span>
+        </div>
+      </section>
+    </main>
+  );
+}
+`
+    );
+  }
+};
+var genericWebAdapter = {
+  id: "generic-web",
+  label: "Generic web contract adapter",
+  target: "generic",
+  packAdapter: "generic-web",
+  capabilities: {
+    bootstrap: false,
+    attach: true,
+    styling: true,
+    verify: true
+  },
+  attach: {
+    routeRoots: ["src", "app", "pages"],
+    layoutFiles: ["index.html", "src/main.ts", "src/main.tsx"],
+    componentRoots: ["src/components", "components"]
+  },
+  verify: {
+    devCommand: "npm run dev",
+    buildCommand: "npm run build",
+    distDir: "dist"
+  }
+};
+var DECANTR_ADAPTERS = {
+  "react-vite": reactViteBootstrapAdapter,
+  "next-app": nextAppAdapter,
+  "generic-web": genericWebAdapter
 };
 function resolveBootstrapTarget(target) {
   const normalizedTarget = (target || "react").toLowerCase();
-  const platformType = "spa";
+  const platformType = normalizedTarget === "nextjs" ? "ssr" : "spa";
   const packAdapter = resolvePackAdapter(normalizedTarget, platformType);
+  const adapterId = normalizedTarget === "nextjs" ? "next-app" : DECANTR_ADAPTERS[packAdapter] ? packAdapter : "generic-web";
   return {
     target: normalizedTarget,
     platformType,
     packAdapter,
-    bootstrapAdapterId: BOOTSTRAP_ADAPTERS[packAdapter]?.id ?? null
+    adapterId,
+    bootstrapAdapterId: DECANTR_ADAPTERS[adapterId]?.capabilities.bootstrap && DECANTR_ADAPTERS[adapterId]?.writeProjectFiles ? adapterId : null
   };
 }
 function getBootstrapAdapter(resolution) {
   if (!resolution.bootstrapAdapterId) {
     return null;
   }
-  return BOOTSTRAP_ADAPTERS[resolution.bootstrapAdapterId] ?? null;
+  const adapter = DECANTR_ADAPTERS[resolution.bootstrapAdapterId];
+  return adapter?.writeProjectFiles ? adapter : null;
 }
 function detectRoutingMode(projectDir) {
   try {
-    const essence = JSON.parse(readFileSync11(join16(projectDir, "decantr.essence.json"), "utf-8"));
+    const essence = JSON.parse(readFileSync12(join17(projectDir, "decantr.essence.json"), "utf-8"));
     const routing = essence.meta?.platform?.routing;
     if (routing === "history" || routing === "pathname") {
       return routing;
@@ -2694,45 +3077,45 @@ function detectRoutingMode(projectDir) {
 }
 
 // src/offline-content.ts
-import { cpSync, existsSync as existsSync16, mkdirSync as mkdirSync6 } from "fs";
-import { join as join17, resolve } from "path";
+import { cpSync, existsSync as existsSync17, mkdirSync as mkdirSync7 } from "fs";
+import { join as join18, resolve } from "path";
 var CONTENT_TYPES2 = ["archetypes", "blueprints", "patterns", "themes", "shells"];
 function copyIfExists(source, target) {
-  if (!existsSync16(source)) return false;
+  if (!existsSync17(source)) return false;
   if (resolve(source) === resolve(target)) return true;
   cpSync(source, target, { recursive: true });
   return true;
 }
 function hydrateContentRoot(projectDir, contentRoot) {
-  if (!existsSync16(contentRoot)) return false;
-  const customRoot = join17(projectDir, ".decantr", "custom");
-  const cacheRoot = join17(projectDir, ".decantr", "cache", "@official");
-  mkdirSync6(customRoot, { recursive: true });
-  mkdirSync6(cacheRoot, { recursive: true });
+  if (!existsSync17(contentRoot)) return false;
+  const customRoot = join18(projectDir, ".decantr", "custom");
+  const cacheRoot = join18(projectDir, ".decantr", "cache", "@official");
+  mkdirSync7(customRoot, { recursive: true });
+  mkdirSync7(cacheRoot, { recursive: true });
   let copiedAny = false;
   for (const type of CONTENT_TYPES2) {
-    const sourceDir = join17(contentRoot, type);
-    if (!existsSync16(sourceDir)) continue;
-    cpSync(sourceDir, join17(customRoot, type), { recursive: true });
-    cpSync(sourceDir, join17(cacheRoot, type), { recursive: true });
+    const sourceDir = join18(contentRoot, type);
+    if (!existsSync17(sourceDir)) continue;
+    cpSync(sourceDir, join18(customRoot, type), { recursive: true });
+    cpSync(sourceDir, join18(cacheRoot, type), { recursive: true });
     copiedAny = true;
   }
   return copiedAny;
 }
 function seedOfflineRegistry(projectDir, workspaceRoot) {
-  const projectDecantrRoot = join17(projectDir, ".decantr");
-  mkdirSync6(projectDecantrRoot, { recursive: true });
+  const projectDecantrRoot = join18(projectDir, ".decantr");
+  mkdirSync7(projectDecantrRoot, { recursive: true });
   const configuredContentRoot = process.env.DECANTR_CONTENT_DIR ? resolve(process.env.DECANTR_CONTENT_DIR) : null;
   if (configuredContentRoot && hydrateContentRoot(projectDir, configuredContentRoot)) {
     return { seeded: true, strategy: "configured-content-root" };
   }
   const copiedCache = copyIfExists(
-    join17(workspaceRoot, ".decantr", "cache"),
-    join17(projectDecantrRoot, "cache")
+    join18(workspaceRoot, ".decantr", "cache"),
+    join18(projectDecantrRoot, "cache")
   );
   const copiedCustom = copyIfExists(
-    join17(workspaceRoot, ".decantr", "custom"),
-    join17(projectDecantrRoot, "custom")
+    join18(workspaceRoot, ".decantr", "custom"),
+    join18(projectDecantrRoot, "custom")
   );
   if (copiedCache || copiedCustom) {
     return { seeded: true, strategy: "workspace-cache" };
@@ -2769,12 +3152,80 @@ function dim2(text) {
 function cyan2(text) {
   return `${CYAN3}${text}${RESET6}`;
 }
+function validatePassThroughFlagValue(flag, value) {
+  if (value.length === 0) {
+    throw new Error(`--${flag} cannot be empty.`);
+  }
+  if (value.length > 512) {
+    throw new Error(`--${flag} is too long.`);
+  }
+  if (/[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error(`--${flag} contains unsupported control characters.`);
+  }
+  return value;
+}
+function pushPassThroughFlag(flags, flag, value) {
+  if (value == null) return;
+  flags.push(`--${flag}=${validatePassThroughFlagValue(flag, value)}`);
+}
+function buildNewProjectInitArgs(options, inferredAdoption) {
+  const initFlags = [
+    "--yes",
+    "--workflow=greenfield",
+    `--adoption=${validatePassThroughFlagValue("mode", inferredAdoption)}`
+  ];
+  pushPassThroughFlag(initFlags, "blueprint", options.blueprint);
+  pushPassThroughFlag(initFlags, "archetype", options.archetype);
+  pushPassThroughFlag(initFlags, "theme", options.theme);
+  pushPassThroughFlag(initFlags, "mode", options.mode);
+  pushPassThroughFlag(initFlags, "shape", options.shape);
+  pushPassThroughFlag(initFlags, "target", options.target);
+  if (options.offline) initFlags.push("--offline");
+  pushPassThroughFlag(initFlags, "registry", options.registry);
+  pushPassThroughFlag(initFlags, "assistant-bridge", options.assistantBridge);
+  return initFlags;
+}
+function commandForPlatform(command) {
+  if (process.platform !== "win32") {
+    return command;
+  }
+  return /^(?:npm|pnpm|yarn|bun|npx)$/.test(command) ? `${command}.cmd` : command;
+}
+function runArgvCommand(command, args, cwd) {
+  const result = spawnSync(commandForPlatform(command), args, {
+    cwd,
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+  }
+}
+function resolveInitCommand(initFlags) {
+  const bundledCliEntrypoint = fileURLToPath(new URL("./bin.js", import.meta.url));
+  const cliEntrypoint = existsSync18(bundledCliEntrypoint) ? bundledCliEntrypoint : process.argv[1] && existsSync18(process.argv[1]) ? process.argv[1] : null;
+  if (cliEntrypoint) {
+    return {
+      command: process.execPath,
+      args: [cliEntrypoint, "init", ...initFlags]
+    };
+  }
+  return {
+    command: "npx",
+    args: ["decantr", "init", ...initFlags]
+  };
+}
 async function cmdNewProject(projectName, options) {
   const workspaceRoot = process.cwd();
   const projectDir = resolve2(workspaceRoot, projectName);
   const bootstrapTarget = resolveBootstrapTarget(options.target);
   const bootstrapAdapter = getBootstrapAdapter(bootstrapTarget);
-  const hasRunnableBootstrap = Boolean(bootstrapAdapter);
+  const registryBackedScaffold = Boolean(options.blueprint || options.archetype);
+  const inferredAdoption = options.adoption || (registryBackedScaffold ? "decantr-css" : "contract-only");
+  const shouldBootstrapRuntime = Boolean(bootstrapAdapter && inferredAdoption === "decantr-css");
   if (!/^[a-z0-9][a-z0-9._-]*$/i.test(projectName)) {
     console.error(
       error2("Invalid project name. Use alphanumeric characters, hyphens, dots, or underscores.")
@@ -2782,18 +3233,32 @@ async function cmdNewProject(projectName, options) {
     process.exitCode = 1;
     return;
   }
-  if (existsSync17(projectDir)) {
+  if (existsSync18(projectDir)) {
     console.error(error2(`Directory "${projectName}" already exists.`));
     process.exitCode = 1;
     return;
   }
+  let initFlags;
+  try {
+    initFlags = buildNewProjectInitArgs(options, inferredAdoption);
+  } catch (err) {
+    console.error(error2(err.message));
+    process.exitCode = 1;
+    return;
+  }
   console.log(heading(`Creating ${projectName}...`));
-  mkdirSync7(projectDir, { recursive: true });
+  mkdirSync8(projectDir, { recursive: true });
   console.log(dim2(`  Created ${projectName}/`));
   const title = projectName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-  if (bootstrapAdapter) {
+  if (shouldBootstrapRuntime && bootstrapAdapter) {
     bootstrapAdapter.writeProjectFiles(projectDir, title, "hash");
     console.log(dim2(`  Bootstrapped ${bootstrapAdapter.label}`));
+  } else if (bootstrapAdapter) {
+    console.log(
+      dim2(
+        `  Skipping runtime bootstrap for adoption=${inferredAdoption}; creating a Decantr contract-only workspace.`
+      )
+    );
   } else {
     console.log(
       `${YELLOW4}  No greenfield bootstrap adapter is available yet for target "${bootstrapTarget.target}" (${bootstrapTarget.packAdapter}).${RESET6}`
@@ -2805,10 +3270,10 @@ async function cmdNewProject(projectName, options) {
     );
   }
   const packageManager = detectPackageManager();
-  if (hasRunnableBootstrap) {
+  if (shouldBootstrapRuntime) {
     console.log(heading("Installing dependencies..."));
     try {
-      execSync(`${packageManager} install`, { cwd: projectDir, stdio: "inherit" });
+      runArgvCommand(packageManager, ["install"], projectDir);
     } catch {
       console.log(
         `
@@ -2845,21 +3310,10 @@ ${YELLOW4}Dependency install failed. Run \`${packageManager} install\` manually.
     return;
   }
   console.log(heading("Initializing Decantr..."));
-  const initFlags = ["--yes", "--existing"];
-  if (options.blueprint) initFlags.push(`--blueprint=${options.blueprint}`);
-  if (options.archetype) initFlags.push(`--archetype=${options.archetype}`);
-  if (options.theme) initFlags.push(`--theme=${options.theme}`);
-  if (options.mode) initFlags.push(`--mode=${options.mode}`);
-  if (options.shape) initFlags.push(`--shape=${options.shape}`);
-  if (options.target) initFlags.push(`--target=${options.target}`);
-  if (options.offline) initFlags.push("--offline");
-  if (options.registry) initFlags.push(`--registry=${options.registry}`);
   try {
-    const bundledCliEntrypoint = fileURLToPath(new URL("./bin.js", import.meta.url));
-    const cliEntrypoint = existsSync17(bundledCliEntrypoint) ? bundledCliEntrypoint : process.argv[1] && existsSync17(process.argv[1]) ? process.argv[1] : null;
-    const cliPath = cliEntrypoint ? `"${process.execPath}" "${cliEntrypoint}"` : "npx decantr";
-    execSync(`${cliPath} init ${initFlags.join(" ")}`, { cwd: projectDir, stdio: "inherit" });
-    if (bootstrapAdapter) {
+    const initCommand = resolveInitCommand(initFlags);
+    runArgvCommand(initCommand.command, initCommand.args, projectDir);
+    if (shouldBootstrapRuntime && bootstrapAdapter) {
       bootstrapAdapter.writeProjectFiles(projectDir, title, detectRoutingMode(projectDir));
     }
   } catch {
@@ -2872,33 +3326,33 @@ ${YELLOW4}Decantr init encountered issues. Run \`decantr init\` manually inside
 \u2713 Project "${projectName}" created!
 `));
   console.log(`  ${cyan2("cd " + projectName)}`);
-  if (bootstrapAdapter) {
+  if (shouldBootstrapRuntime) {
     console.log(`  ${cyan2(packageManager + " run dev")}`);
   } else {
     console.log(
       dim2(
-        `  Contract-only mode for target ${bootstrapTarget.target}. Bring your own runtime, or rerun ${cyan2(`decantr new ${projectName} --target=react`)} for the current starter adapter.`
+        `  Contract-only mode for target ${bootstrapTarget.target}. Bring your own runtime, or rerun with ${cyan2("--adoption=decantr-css")} for a runnable Decantr CSS starter adapter.`
       )
     );
   }
   console.log("");
 }
 function detectPackageManager() {
-  if (existsSync17(join18(process.cwd(), "pnpm-lock.yaml")) || existsSync17(join18(process.cwd(), "pnpm-workspace.yaml"))) {
+  if (existsSync18(join19(process.cwd(), "pnpm-lock.yaml")) || existsSync18(join19(process.cwd(), "pnpm-workspace.yaml"))) {
     return "pnpm";
   }
-  if (existsSync17(join18(process.cwd(), "yarn.lock"))) {
+  if (existsSync18(join19(process.cwd(), "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync17(join18(process.cwd(), "bun.lockb")) || existsSync17(join18(process.cwd(), "bun.lock"))) {
+  if (existsSync18(join19(process.cwd(), "bun.lockb")) || existsSync18(join19(process.cwd(), "bun.lock"))) {
     return "bun";
   }
   return "npm";
 }
 
 // src/commands/publish.ts
-import { existsSync as existsSync18, readFileSync as readFileSync12 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync13 } from "fs";
+import { join as join20 } from "path";
 import {
   API_CONTENT_TYPE_TO_CONTENT_TYPE,
   CONTENT_TYPE_TO_API_CONTENT_TYPE as CONTENT_TYPE_TO_API_CONTENT_TYPE2,
@@ -2914,8 +3368,8 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
   }
   const singularType = API_CONTENT_TYPE_TO_CONTENT_TYPE[type] || type;
   const pluralType = CONTENT_TYPE_TO_API_CONTENT_TYPE2[type] || CONTENT_TYPE_TO_API_CONTENT_TYPE2[singularType] || `${type}s`;
-  const customPath = join19(projectRoot, ".decantr", "custom", pluralType, `${name}.json`);
-  if (!existsSync18(customPath)) {
+  const customPath = join20(projectRoot, ".decantr", "custom", pluralType, `${name}.json`);
+  if (!existsSync19(customPath)) {
     console.error(`Custom ${singularType} "${name}" not found at ${customPath}`);
     console.error(`Create one first: decantr create ${singularType} ${name}`);
     process.exitCode = 1;
@@ -2923,7 +3377,7 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
   }
   let data;
   try {
-    data = JSON.parse(readFileSync12(customPath, "utf-8"));
+    data = JSON.parse(readFileSync13(customPath, "utf-8"));
   } catch {
     console.error(`Failed to parse ${customPath}`);
     process.exitCode = 1;
@@ -2961,23 +3415,23 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
 }
 
 // src/commands/refresh.ts
-import { existsSync as existsSync19, readFileSync as readFileSync13 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync14 } from "fs";
+import { join as join21 } from "path";
 import { isV3 as isV33 } from "@decantr/essence-spec";
 var GREEN7 = "\x1B[32m";
 var RED6 = "\x1B[31m";
 var DIM7 = "\x1B[2m";
 var RESET7 = "\x1B[0m";
 async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
-  const essencePath = join20(projectRoot, "decantr.essence.json");
-  if (!existsSync19(essencePath)) {
+  const essencePath = join21(projectRoot, "decantr.essence.json");
+  if (!existsSync20(essencePath)) {
     console.error(`${RED6}No decantr.essence.json found. Run \`decantr init\` first.${RESET7}`);
     process.exitCode = 1;
     return;
   }
   let essence;
   try {
-    const raw = readFileSync13(essencePath, "utf-8");
+    const raw = readFileSync14(essencePath, "utf-8");
     const parsed = JSON.parse(raw);
     if (!isV33(parsed)) {
       console.error(`${RED6}Essence is not v3. Run \`decantr migrate\` first.${RESET7}`);
@@ -2991,7 +3445,7 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join20(projectRoot, ".decantr", "cache"),
+    cacheDir: join21(projectRoot, ".decantr", "cache"),
     offline: options.offline
   });
   console.log("Regenerating derived files...\n");
@@ -3011,8 +3465,8 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
 }
 
 // src/commands/registry-mirror.ts
-import { mkdirSync as mkdirSync8, writeFileSync as writeFileSync8 } from "fs";
-import { join as join21 } from "path";
+import { mkdirSync as mkdirSync9, writeFileSync as writeFileSync9 } from "fs";
+import { join as join22 } from "path";
 import { API_CONTENT_TYPES, RegistryAPIClient as RegistryAPIClient2 } from "@decantr/registry";
 var GREEN8 = "\x1B[32m";
 var RED7 = "\x1B[31m";
@@ -3040,7 +3494,7 @@ async function cmdRegistryMirror(projectRoot, options = {}) {
     process.exitCode = 1;
     return;
   }
-  const cacheDir = join21(projectRoot, ".decantr", "cache");
+  const cacheDir = join22(projectRoot, ".decantr", "cache");
   const counts = {};
   const failed = [];
   console.log(`
@@ -3050,19 +3504,19 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
     try {
       const result = await apiClient.listContent(type, { namespace: "@official" });
       const items = result.items;
-      const typeDir = join21(cacheDir, "@official", type);
-      mkdirSync8(typeDir, { recursive: true });
-      writeFileSync8(join21(typeDir, "index.json"), JSON.stringify(result, null, 2));
+      const typeDir = join22(cacheDir, "@official", type);
+      mkdirSync9(typeDir, { recursive: true });
+      writeFileSync9(join22(typeDir, "index.json"), JSON.stringify(result, null, 2));
       let itemCount = 0;
       for (const item of items) {
         const slug = item.slug || item.id;
         if (!slug) continue;
         try {
           const fullItem = await apiClient.getContent(type, "@official", slug);
-          writeFileSync8(join21(typeDir, `${slug}.json`), JSON.stringify(fullItem, null, 2));
+          writeFileSync9(join22(typeDir, `${slug}.json`), JSON.stringify(fullItem, null, 2));
           itemCount++;
         } catch {
-          writeFileSync8(join21(typeDir, `${slug}.json`), JSON.stringify(item, null, 2));
+          writeFileSync9(join22(typeDir, `${slug}.json`), JSON.stringify(item, null, 2));
           itemCount++;
         }
       }
@@ -3077,8 +3531,8 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
     mirrored_at: (/* @__PURE__ */ new Date()).toISOString(),
     counts
   };
-  mkdirSync8(join21(cacheDir), { recursive: true });
-  writeFileSync8(join21(cacheDir, "mirror-manifest.json"), JSON.stringify(manifest, null, 2));
+  mkdirSync9(join22(cacheDir), { recursive: true });
+  writeFileSync9(join22(cacheDir, "mirror-manifest.json"), JSON.stringify(manifest, null, 2));
   const totalItems = Object.values(counts).reduce((a, b) => a + b, 0);
   console.log("");
   if (failed.length > 0) {
@@ -3095,23 +3549,23 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
 }
 
 // src/commands/remove.ts
-import { existsSync as existsSync21, readFileSync as readFileSync14, rmSync as rmSync2, writeFileSync as writeFileSync9 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync15, rmSync as rmSync2, writeFileSync as writeFileSync10 } from "fs";
+import { join as join23 } from "path";
 import { isV3 as isV34, migrateV30ToV31 as migrateV30ToV312 } from "@decantr/essence-spec";
 var GREEN9 = "\x1B[32m";
 var RED8 = "\x1B[31m";
 var DIM9 = "\x1B[2m";
 var RESET9 = "\x1B[0m";
 function readAndMigrate2(projectRoot) {
-  const essencePath = join22(projectRoot, "decantr.essence.json");
-  if (!existsSync21(essencePath)) {
+  const essencePath = join23(projectRoot, "decantr.essence.json");
+  if (!existsSync22(essencePath)) {
     console.error(`${RED8}No decantr.essence.json found. Run \`decantr init\` first.${RESET9}`);
     process.exitCode = 1;
     return null;
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync14(essencePath, "utf-8"));
+    parsed = JSON.parse(readFileSync15(essencePath, "utf-8"));
   } catch (e) {
     console.error(`${RED8}Could not read essence: ${e.message}${RESET9}`);
     process.exitCode = 1;
@@ -3126,7 +3580,7 @@ function readAndMigrate2(projectRoot) {
   return { essence, essencePath };
 }
 function writeEssence2(essencePath, essence) {
-  writeFileSync9(essencePath, JSON.stringify(essence, null, 2) + "\n");
+  writeFileSync10(essencePath, JSON.stringify(essence, null, 2) + "\n");
 }
 function recomputeGlobalFeatures(essence) {
   const all = /* @__PURE__ */ new Set();
@@ -3168,14 +3622,14 @@ async function cmdRemoveSection(sectionId, args, projectRoot = process.cwd()) {
   sections.splice(idx, 1);
   recomputeGlobalFeatures(essence);
   removeRoutes(essence, sectionId);
-  const contextFile = join22(projectRoot, ".decantr", "context", `${sectionId}.md`);
-  if (existsSync21(contextFile)) {
+  const contextFile = join23(projectRoot, ".decantr", "context", `${sectionId}.md`);
+  if (existsSync22(contextFile)) {
     rmSync2(contextFile);
   }
   writeEssence2(essencePath, essence);
   console.log(`${GREEN9}Removed section "${sectionId}".${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
@@ -3211,7 +3665,7 @@ async function cmdRemovePage(path, args, projectRoot = process.cwd()) {
   writeEssence2(essencePath, essence);
   console.log(`${GREEN9}Removed page "${pageId}" from section "${sectionId}".${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
@@ -3252,15 +3706,15 @@ async function cmdRemoveFeature(feature, args, projectRoot = process.cwd()) {
   const target = sectionId ? `section "${sectionId}" and global` : "global";
   console.log(`${GREEN9}Removed feature "${feature}" from ${target} features.${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
 }
 
 // src/commands/sync-drift.ts
-import { existsSync as existsSync22, readFileSync as readFileSync15, writeFileSync as writeFileSync10 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync23, readFileSync as readFileSync16, writeFileSync as writeFileSync11 } from "fs";
+import { join as join24 } from "path";
 var GREEN10 = "\x1B[32m";
 var RED9 = "\x1B[31m";
 var YELLOW6 = "\x1B[33m";
@@ -3269,8 +3723,8 @@ var DIM10 = "\x1B[2m";
 var BOLD4 = "\x1B[1m";
 var CYAN5 = "\x1B[36m";
 async function cmdSyncDrift(projectRoot = process.cwd()) {
-  const driftLogPath = join23(projectRoot, ".decantr", "drift-log.json");
-  if (!existsSync22(driftLogPath)) {
+  const driftLogPath = join24(projectRoot, ".decantr", "drift-log.json");
+  if (!existsSync23(driftLogPath)) {
     console.log(`${GREEN10}No drift log found \u2014 no drift recorded.${RESET10}`);
     console.log(
       `${DIM10}Drift is logged when guard violations are detected during development.${RESET10}`
@@ -3279,7 +3733,7 @@ async function cmdSyncDrift(projectRoot = process.cwd()) {
   }
   let entries;
   try {
-    entries = JSON.parse(readFileSync15(driftLogPath, "utf-8"));
+    entries = JSON.parse(readFileSync16(driftLogPath, "utf-8"));
   } catch {
     console.error(`${RED9}Could not parse drift-log.json${RESET10}`);
     process.exitCode = 1;
@@ -3325,13 +3779,13 @@ ${BOLD4}Unresolved Drift Entries (${unresolved.length})${RESET10}
   console.log("");
 }
 function resolveDriftEntries(projectRoot, options) {
-  const driftLogPath = join23(projectRoot, ".decantr", "drift-log.json");
-  if (!existsSync22(driftLogPath)) {
+  const driftLogPath = join24(projectRoot, ".decantr", "drift-log.json");
+  if (!existsSync23(driftLogPath)) {
     return { success: true };
   }
   if (options.clear) {
     try {
-      writeFileSync10(driftLogPath, "[]");
+      writeFileSync11(driftLogPath, "[]");
       return { success: true };
     } catch (e) {
       return { success: false, error: `Could not clear drift log: ${e.message}` };
@@ -3339,7 +3793,7 @@ function resolveDriftEntries(projectRoot, options) {
   }
   let entries;
   try {
-    entries = JSON.parse(readFileSync15(driftLogPath, "utf-8"));
+    entries = JSON.parse(readFileSync16(driftLogPath, "utf-8"));
   } catch {
     return { success: false, error: "Could not parse drift-log.json" };
   }
@@ -3358,7 +3812,7 @@ function resolveDriftEntries(projectRoot, options) {
     }
   }
   try {
-    writeFileSync10(driftLogPath, JSON.stringify(entries, null, 2));
+    writeFileSync11(driftLogPath, JSON.stringify(entries, null, 2));
     return { success: true };
   } catch (e) {
     return { success: false, error: `Could not write drift log: ${e.message}` };
@@ -3366,8 +3820,8 @@ function resolveDriftEntries(projectRoot, options) {
 }
 
 // src/commands/theme-switch.ts
-import { existsSync as existsSync23, readFileSync as readFileSync16, writeFileSync as writeFileSync11 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync24, readFileSync as readFileSync17, writeFileSync as writeFileSync12 } from "fs";
+import { join as join25 } from "path";
 import { isV3 as isV35, migrateV30ToV31 as migrateV30ToV313 } from "@decantr/essence-spec";
 var GREEN11 = "\x1B[32m";
 var RED10 = "\x1B[31m";
@@ -3384,15 +3838,15 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     process.exitCode = 1;
     return;
   }
-  const essencePath = join24(projectRoot, "decantr.essence.json");
-  if (!existsSync23(essencePath)) {
+  const essencePath = join25(projectRoot, "decantr.essence.json");
+  if (!existsSync24(essencePath)) {
     console.error(`${RED10}No decantr.essence.json found. Run \`decantr init\` first.${RESET11}`);
     process.exitCode = 1;
     return;
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync16(essencePath, "utf-8"));
+    parsed = JSON.parse(readFileSync17(essencePath, "utf-8"));
   } catch (e) {
     console.error(`${RED10}Could not read essence: ${e.message}${RESET11}`);
     process.exitCode = 1;
@@ -3441,7 +3895,7 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     essence.dna.theme.mode = mode;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join24(projectRoot, ".decantr", "cache")
+    cacheDir: join25(projectRoot, ".decantr", "cache")
   });
   try {
     const themeResult = await registryClient.fetchTheme(themeName);
@@ -3456,7 +3910,7 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     }
   } catch {
   }
-  writeFileSync11(essencePath, JSON.stringify(essence, null, 2) + "\n");
+  writeFileSync12(essencePath, JSON.stringify(essence, null, 2) + "\n");
   console.log(`${GREEN11}Switched theme: ${oldThemeId} \u2192 ${themeName}${RESET11}`);
   if (shape) console.log(`  ${DIM11}Shape: ${shape}${RESET11}`);
   if (mode) console.log(`  ${DIM11}Mode: ${mode}${RESET11}`);
@@ -3478,10 +3932,10 @@ var CYAN6 = "\x1B[36m";
 function ask(question, defaultValue) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const prompt = defaultValue ? `${question} ${DIM12}(${defaultValue})${RESET12}: ` : `${question}: `;
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     rl.question(prompt, (answer) => {
       rl.close();
-      resolve4(answer.trim() || defaultValue || "");
+      resolve5(answer.trim() || defaultValue || "");
     });
   });
 }
@@ -3663,7 +4117,11 @@ async function runInteractivePrompts(detected, archetypes, blueprints, themes, w
     personality: ["professional"],
     features: [],
     existing: workflowSeed?.existing || detected.existingEssence,
-    workflowMode: workflowSeed?.workflowMode
+    workflowMode: workflowSeed?.workflowMode,
+    adoptionMode: workflowSeed?.adoptionMode,
+    contentSource: workflowSeed?.contentSource,
+    assistantBridge: workflowSeed?.assistantBridge,
+    projectScope: workflowSeed?.projectScope
   };
 }
 function parseFlags(args, detected) {
@@ -3685,6 +4143,12 @@ function parseFlags(args, detected) {
   if (typeof args.features === "string")
     options.features = args.features.split(",").map((s) => s.trim());
   if (args.existing === true) options.existing = true;
+  if (args.adoption === "contract-only" || args.adoption === "style-bridge" || args.adoption === "decantr-css") {
+    options.adoptionMode = args.adoption;
+  }
+  if (args["assistant-bridge"] === "none" || args["assistant-bridge"] === "preview" || args["assistant-bridge"] === "apply") {
+    options.assistantBridge = args["assistant-bridge"];
+  }
   return options;
 }
 function mergeWithDefaults(flags, detected, workflowSeed) {
@@ -3701,12 +4165,16 @@ function mergeWithDefaults(flags, detected, workflowSeed) {
     personality: flags.personality || ["professional"],
     features: flags.features || [],
     existing: flags.existing || workflowSeed?.existing || detected.existingEssence,
-    workflowMode: flags.workflowMode || workflowSeed?.workflowMode
+    workflowMode: flags.workflowMode || workflowSeed?.workflowMode,
+    adoptionMode: flags.adoptionMode || workflowSeed?.adoptionMode,
+    contentSource: flags.contentSource || workflowSeed?.contentSource,
+    assistantBridge: flags.assistantBridge || workflowSeed?.assistantBridge,
+    projectScope: flags.projectScope || workflowSeed?.projectScope
   };
 }
 async function runSimplifiedInit(blueprints) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const question = (q) => new Promise((resolve4) => rl.question(q, resolve4));
+  const question = (q) => new Promise((resolve5) => rl.question(q, resolve5));
   console.log("\n? What blueprint would you like to scaffold?\n");
   console.log("  1. Decantr default (recommended)");
   console.log("  2. Search registry...\n");
@@ -3738,8 +4206,8 @@ async function runSimplifiedInit(blueprints) {
 }
 
 // src/theme-commands.ts
-import { existsSync as existsSync24, mkdirSync as mkdirSync9, readdirSync as readdirSync5, readFileSync as readFileSync17, rmSync as rmSync3, writeFileSync as writeFileSync12 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync25, mkdirSync as mkdirSync10, readdirSync as readdirSync5, readFileSync as readFileSync18, rmSync as rmSync3, writeFileSync as writeFileSync13 } from "fs";
+import { join as join26 } from "path";
 var REQUIRED_FIELDS = [
   "$schema",
   "id",
@@ -3799,20 +4267,20 @@ function validateCustomTheme(theme) {
   };
 }
 function createTheme(projectRoot, id, name) {
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  const themePath = join25(customThemesDir, `${id}.json`);
-  const howToPath = join25(customThemesDir, "how-to-theme.md");
-  mkdirSync9(customThemesDir, { recursive: true });
-  if (existsSync24(themePath)) {
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  const themePath = join26(customThemesDir, `${id}.json`);
+  const howToPath = join26(customThemesDir, "how-to-theme.md");
+  mkdirSync10(customThemesDir, { recursive: true });
+  if (existsSync25(themePath)) {
     return {
       success: false,
       error: `Theme "${id}" already exists at ${themePath}`
     };
   }
   const skeleton = getThemeSkeleton(id, name);
-  writeFileSync12(themePath, JSON.stringify(skeleton, null, 2));
-  if (!existsSync24(howToPath)) {
-    writeFileSync12(howToPath, getHowToThemeDoc());
+  writeFileSync13(themePath, JSON.stringify(skeleton, null, 2));
+  if (!existsSync25(howToPath)) {
+    writeFileSync13(howToPath, getHowToThemeDoc());
   }
   return {
     success: true,
@@ -3820,17 +4288,17 @@ function createTheme(projectRoot, id, name) {
   };
 }
 function listCustomThemes(projectRoot) {
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  if (!existsSync24(customThemesDir)) {
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  if (!existsSync25(customThemesDir)) {
     return [];
   }
   const themes = [];
   try {
     const files = readdirSync5(customThemesDir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
-      const filePath = join25(customThemesDir, file);
+      const filePath = join26(customThemesDir, file);
       try {
-        const data = JSON.parse(readFileSync17(filePath, "utf-8"));
+        const data = JSON.parse(readFileSync18(filePath, "utf-8"));
         themes.push({
           id: data.id || file.replace(".json", ""),
           name: data.name || data.id,
@@ -3845,8 +4313,8 @@ function listCustomThemes(projectRoot) {
   return themes;
 }
 function deleteTheme(projectRoot, id) {
-  const themePath = join25(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
-  if (!existsSync24(themePath)) {
+  const themePath = join26(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
+  if (!existsSync25(themePath)) {
     return {
       success: false,
       error: `Theme "${id}" not found at ${themePath}`
@@ -3863,7 +4331,7 @@ function deleteTheme(projectRoot, id) {
   }
 }
 function importTheme(projectRoot, sourcePath) {
-  if (!existsSync24(sourcePath)) {
+  if (!existsSync25(sourcePath)) {
     return {
       success: false,
       errors: [`Source file not found: ${sourcePath}`]
@@ -3871,7 +4339,7 @@ function importTheme(projectRoot, sourcePath) {
   }
   let theme;
   try {
-    theme = JSON.parse(readFileSync17(sourcePath, "utf-8"));
+    theme = JSON.parse(readFileSync18(sourcePath, "utf-8"));
   } catch (e) {
     return {
       success: false,
@@ -3887,20 +4355,90 @@ function importTheme(projectRoot, sourcePath) {
   }
   theme.source = "custom";
   const id = theme.id;
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  const destPath = join25(customThemesDir, `${id}.json`);
-  mkdirSync9(customThemesDir, { recursive: true });
-  const howToPath = join25(customThemesDir, "how-to-theme.md");
-  if (!existsSync24(howToPath)) {
-    writeFileSync12(howToPath, getHowToThemeDoc());
-  }
-  writeFileSync12(destPath, JSON.stringify(theme, null, 2));
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  const destPath = join26(customThemesDir, `${id}.json`);
+  mkdirSync10(customThemesDir, { recursive: true });
+  const howToPath = join26(customThemesDir, "how-to-theme.md");
+  if (!existsSync25(howToPath)) {
+    writeFileSync13(howToPath, getHowToThemeDoc());
+  }
+  writeFileSync13(destPath, JSON.stringify(theme, null, 2));
   return {
     success: true,
     path: destPath
   };
 }
 
+// src/workspace.ts
+import { existsSync as existsSync26, readdirSync as readdirSync6, readFileSync as readFileSync19 } from "fs";
+import { dirname as dirname3, join as join27, resolve as resolve3 } from "path";
+function readPackageJson(dir) {
+  const path = join27(dir, "package.json");
+  if (!existsSync26(path)) return null;
+  try {
+    return JSON.parse(readFileSync19(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function hasWorkspaceMarker(dir) {
+  if (existsSync26(join27(dir, "pnpm-workspace.yaml")) || existsSync26(join27(dir, "turbo.json")) || existsSync26(join27(dir, "nx.json"))) {
+    return true;
+  }
+  const pkg = readPackageJson(dir);
+  return Boolean(pkg?.workspaces);
+}
+function findWorkspaceRoot(startDir) {
+  let current = resolve3(startDir);
+  while (true) {
+    if (hasWorkspaceMarker(current)) return current;
+    const parent = dirname3(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function looksLikeApp(dir) {
+  if (existsSync26(join27(dir, "next.config.js")) || existsSync26(join27(dir, "next.config.ts")) || existsSync26(join27(dir, "next.config.mjs")) || existsSync26(join27(dir, "vite.config.ts")) || existsSync26(join27(dir, "vite.config.js")) || existsSync26(join27(dir, "angular.json")) || existsSync26(join27(dir, "svelte.config.js")) || existsSync26(join27(dir, "svelte.config.ts")) || existsSync26(join27(dir, "astro.config.mjs")) || existsSync26(join27(dir, "src")) || existsSync26(join27(dir, "app")) || existsSync26(join27(dir, "pages"))) {
+    return true;
+  }
+  const pkg = readPackageJson(dir);
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  return Boolean(
+    deps.react || deps.next || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt
+  );
+}
+function listWorkspaceApps(workspaceRoot) {
+  const candidates = [];
+  for (const base of ["apps", "packages"]) {
+    const baseDir = join27(workspaceRoot, base);
+    if (!existsSync26(baseDir)) continue;
+    for (const entry of readdirSync6(baseDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const candidate = join27(baseDir, entry.name);
+      if (looksLikeApp(candidate)) {
+        candidates.push(`${base}/${entry.name}`);
+      }
+    }
+  }
+  return candidates.sort();
+}
+function resolveWorkspaceInfo(cwd, projectArg) {
+  const absoluteCwd = resolve3(cwd);
+  const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
+  const appRoot = projectArg ? resolve3(absoluteCwd, projectArg) : absoluteCwd;
+  const appCandidates = listWorkspaceApps(workspaceRoot);
+  const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
+  const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 1;
+  return {
+    cwd: absoluteCwd,
+    workspaceRoot,
+    appRoot,
+    projectScope,
+    appCandidates,
+    requiresProjectSelection
+  };
+}
+
 // src/index.ts
 var BOLD6 = "\x1B[1m";
 var DIM13 = "\x1B[2m";
@@ -3997,8 +4535,19 @@ function extractPatternName(item) {
 }
 function generateGreenfieldPrompt(ctx) {
   const lines = [];
+  const usesDecantrCss = ctx.adoptionMode === "decantr-css" || !ctx.adoptionMode;
   lines.push("Build this greenfield application using the Decantr design system.");
   lines.push("");
+  if (ctx.blueprint) lines.push(`Blueprint: ${ctx.blueprint}`);
+  if (ctx.archetype) lines.push(`Primary archetype: ${ctx.archetype}`);
+  if (ctx.theme) lines.push(`Theme: ${ctx.theme}${ctx.mode ? ` (${ctx.mode})` : ""}`);
+  if (ctx.target) lines.push(`Target: ${ctx.target}`);
+  if (ctx.pages.length > 0) {
+    lines.push(
+      `Routes/pages: ${ctx.pages.map((page) => `${page.sectionId ? `${page.sectionId}/` : ""}${page.id}:${page.shell}`).join(", ")}`
+    );
+  }
+  lines.push("");
   lines.push(
     "This workspace is a new Decantr scaffold. Use the contract to create or extend the runtime deliberately, not to reverse-engineer a hidden starter."
   );
@@ -4013,210 +4562,201 @@ function generateGreenfieldPrompt(ctx) {
   lines.push("");
   lines.push("Read in this order:");
   lines.push(
-    '1. DECANTR.md for the design spec, "Atoms in 5 minutes" walkthrough, treatment catalog, motion/typography/elevation tables, and the Interaction Requirements canonical-implementation table.'
+    "1. .decantr/context/scaffold-pack.md \u2014 the canonical compiled contract. Contains route plan, shell layouts, navigation, Required Theme Decorators, and project-wide execution rules."
   );
   lines.push(
-    '2. .decantr/context/scaffold-pack.md \u2014 the canonical compiled contract. Contains the route plan, shell layouts, navigation, AND the project-wide "Required Theme Decorators" table (class | intent | apply-to). This table is the authoritative decorator contract; section packs reference it.'
+    "2. Before section work, read the matching .decantr/context/section-*-pack.md first, then .decantr/context/section-*.md only for extra slot/layout detail."
   );
   lines.push(
-    "3. .decantr/context/scaffold.md for the broader app overview, topology, route map, and voice guidance."
+    "3. Before route work, read the matching .decantr/context/page-*-pack.md file. Its pattern layout and interaction checklists are contract."
   );
   lines.push(
-    '4. Before working on any section, read its matching .decantr/context/section-*-pack.md (compact contract \u2014 pay close attention to the "Section Directives" block; those are non-negotiable execution rules) and then .decantr/context/section-*.md (long-form context with shell internal_layout + slot guidance).'
+    "4. .decantr/context/scaffold.md for broader topology, route map, and voice guidance after the compact packs are understood."
   );
   lines.push(
-    '5. Before working on any route/page, read its matching .decantr/context/page-*-pack.md file. The "Interactions (MUST implement each)" checklist per pattern is contract \u2014 see the next section.'
+    "5. DECANTR.md as a lookup reference for atoms, treatments, decorators, interaction implementations, and guard rules. Do not let narrative docs override compiled packs."
   );
   lines.push("");
   lines.push("\u2550\u2550\u2550 INTERACTIONS ARE CONTRACT, NOT GUIDANCE \u2550\u2550\u2550");
   lines.push("");
   lines.push(
-    'Each page pack lists an "Interactions (MUST implement each)" checkbox list per pattern. Treat each checkbox as a contract item, NOT a suggestion. The DECANTR.md "Interaction Requirements" table maps each canonical interaction to its required implementation:'
-  );
-  lines.push(
-    "- drag-nodes \u2192 onPointerDown/Move handlers with 4px threshold + cursor: grab/grabbing"
+    'Each page pack lists "Interactions (MUST implement each)" per pattern. Implement the actual behavior, not visible text saying it exists. Use DECANTR.md only to look up the canonical implementation shape when needed.'
   );
-  lines.push("- status-pulse \u2192 d-pulse class on the indicator element");
   lines.push(
-    "- animate-on-mount \u2192 d-enter-fade / d-enter-slide-up / d-enter-scale on the pattern root"
-  );
-  lines.push(
-    '- stagger-children \u2192 d-stagger-children parent + style={{ "--d-stagger-index": i }} on each child'
-  );
-  lines.push(
-    "- pan-background \u2192 pointer handlers on canvas BACKGROUND only (not nodes); translate viewport transform"
-  );
-  lines.push("- zoom-scroll \u2192 onWheel adjusting a scale transform, clamped [0.25, 4]");
-  lines.push("- keyboard-navigation \u2192 onKeyDown arrow handlers + tabIndex={0}");
-  lines.push("- focus-trap \u2192 Tab cycle inside dialog; restore focus on close");
-  lines.push("- hover-tooltip \u2192 data-tooltip + onMouseEnter handler showing popover");
-  lines.push(
-    "- real-time-updates \u2192 setInterval (2-8s) updating mock state with d-pulse on changed elements"
-  );
-  lines.push("- scroll-reveal \u2192 IntersectionObserver (once: true) triggering d-enter-fade");
-  lines.push("- inline-edit \u2192 controlled <input> on click; commit on blur or Enter");
-  lines.push(
-    "- lift-hover / scale-hover / glow-hover \u2192 matching d-*-hover treatment classes"
+    "Examples: pointer handlers for dragging/panning, onWheel for zoom, onKeyDown + tabIndex for keyboard navigation, IntersectionObserver for scroll reveal, state updates for real-time indicators, and d-* motion classes where the contract calls for animation."
   );
   lines.push("");
   lines.push(
-    "`decantr check --strict` FAILS the build when a declared interaction has no matching implementation. The full canonical-implementation table is in DECANTR.md."
+    "`decantr check --strict` fails when a declared interaction has no matching implementation."
   );
   lines.push("");
-  lines.push("\u2550\u2550\u2550 ATOMS-FIRST FOR LAYOUT \u2014 DO NOT INLINE-STYLE \u2550\u2550\u2550");
+  lines.push("\u2550\u2550\u2550 STYLING ADOPTION \u2550\u2550\u2550");
   lines.push("");
-  lines.push(
-    'Decantr ships @decantr/css as a runtime atom system (already in package.json). Use atoms via `css(...)` for ALL layout, spacing, sizing, flex/grid, position, and typography sizing \u2014 wherever you would otherwise reach for `style={{ display: "flex", gap: "1rem", padding: "1rem", ... }}`.'
-  );
-  lines.push("");
-  lines.push("Mandatory translation (NOT optional). USE THESE EXACT ATOM NAMES:");
-  lines.push(
-    '  \u274C style={{ display: "flex", gap: "1rem" }}                   \u2192  \u2705 className={css("_flex _gap4")}'
-  );
-  lines.push(
-    '  \u274C style={{ flexDirection: "column", alignItems: "center" }}  \u2192  \u2705 className={css("_col _aic")}'
-  );
-  lines.push(
-    '  \u274C style={{ justifyContent: "space-between" }}                \u2192  \u2705 className={css("_jcsb")}'
-  );
-  lines.push(
-    '  \u274C style={{ padding: "1rem 1.5rem" }}                         \u2192  \u2705 className={css("_py4 _px6")}'
-  );
-  lines.push(
-    '  \u274C style={{ gridTemplateColumns: "repeat(3, 1fr)" }}           \u2192  \u2705 className={css("_grid _gc3")}'
-  );
-  lines.push(
-    '  \u274C style={{ position: "sticky", top: 0 }}                     \u2192  \u2705 className={css("_sticky _top0")}'
-  );
-  lines.push(
-    '  \u274C style={{ width: "100%", maxWidth: "40rem" }}               \u2192  \u2705 className={css("_wfull _maxw[40rem]")}'
-  );
-  lines.push(
-    '  \u274C style={{ marginInline: "auto" }}                            \u2192  \u2705 className={css("_mxauto")}'
-  );
-  lines.push(
-    '  \u274C style={{ fontSize: "1.5rem" }}                              \u2192  \u2705 className={css("_text2xl")}'
-  );
-  lines.push("");
-  lines.push(
-    'Atom naming convention: compact prefix-spelling \u2014 `_aic` (align-items:center) not `_items-center`, `_jcsb` (justify-content:space-between) not `_justify-between`, `_wfull` not `_w-full`, `_top0` not `_t0`. The runtime accepts hyphenated Tailwind-style aliases as fallback BUT compact prefix is canonical, shorter, and what every existing scaffold uses. Do not invent your own atom shapes \u2014 if you need an arbitrary value (e.g. `maxWidth: "72rem"`), use the brackets form `_maxw[72rem]`.'
-  );
-  lines.push("");
-  lines.push(
-    'Combine atoms with treatment / decorator strings: `className={css("_flex _col _gap4") + " d-card clean-card"}`.'
-  );
+  if (ctx.adoptionMode === "contract-only") {
+    lines.push(
+      "This project is contract-only. Use Decantr packs for design intent and governance, but implement through the app runtime and styling system already present or explicitly chosen for this project."
+    );
+    lines.push(
+      "Do not install @decantr/css or add Decantr style files unless the adoption mode changes."
+    );
+  } else if (ctx.adoptionMode === "style-bridge") {
+    lines.push(
+      "This project uses Decantr style-bridge mode. Use generated bridge tokens as a mapping layer onto the selected styling system; @decantr/css is not required."
+    );
+  } else {
+    lines.push(
+      "Use @decantr/css atoms via `css(...)` for layout, spacing, sizing, flex/grid, position, and typography sizing. Static visual values should not live in inline style props."
+    );
+  }
+  if (usesDecantrCss) {
+    lines.push("");
+    lines.push("Use these canonical compact atom shapes:");
+    lines.push(
+      "- Layout: _flex, _col, _aic, _jcc, _jcsb, _grid, _gc3, _gc[2fr_1fr], _gap4, _wrap"
+    );
+    lines.push(
+      "- Spacing/sizing: _p4, _py4, _px6, _wfull, _maxw[40rem], _mxauto, _h[20rem]"
+    );
+    lines.push(
+      "- Position/type: _rel, _abs, _sticky, _top0, _text2xl, _textlg, _fgmuted"
+    );
+    lines.push("- Responsive: _sm:gc2, _lg:gc3, _mdmax:p4, _lg:gc[1.05fr_1fr]");
+    lines.push("");
+    lines.push(
+      "Use compact atom names: `_aic` not `_items-center`, `_jcsb` not `_justify-between`, `_wfull` not `_w-full`, `_top0` not `_t0`. For arbitrary values, use brackets such as `_maxw[72rem]`."
+    );
+    lines.push("");
+    lines.push(
+      'Combine atoms with treatment / decorator strings: `className={css("_flex _col _gap4") + " d-card clean-card"}`.'
+    );
+  } else {
+    lines.push("");
+    lines.push(
+      "When packs mention atoms, treatments, decorators, or shell class names, treat them as Decantr vocabulary and map the intent into the selected runtime. Keep the literal class names only if this project has a compatible implementation."
+    );
+  }
   lines.push("");
   lines.push("Inline `style={{...}}` is ONLY acceptable for:");
   lines.push(
-    '  1. CSS custom-property writes the contract REQUIRES (`style={{ "--d-stagger-index": i }}`, `style={{ "--lum-card-color": accent }}`, etc.)'
+    "  1. CSS custom-property writes the contract requires (`--d-stagger-index`, theme color vars, etc.)"
   );
   lines.push(
-    "  2. Truly dynamic geometry no atom can express (computed pan/zoom transforms, draggable-node positions calculated from data, real-time gradient hue interpolation)."
+    "  2. Truly dynamic geometry no atom can express (computed transforms, drag positions, live chart geometry)."
   );
   lines.push("");
-  lines.push(
-    'If you find yourself writing >5 inline styles in a component for static visual values, STOP and migrate to atoms. The full atom reference is in DECANTR.md ("Atoms in 5 minutes" + "Atom Reference"). `decantr check` flags inline-style attributes as a contract violation.'
-  );
+  if (usesDecantrCss) {
+    lines.push(
+      "If a component accumulates static inline visual styles, migrate them to atoms, treatments, decorators, or CSS vars. `decantr check` flags inline-style drift."
+    );
+  } else {
+    lines.push(
+      "If a component accumulates static inline visual styles, migrate them into the project styling system or mapped Decantr bridge variables. `decantr check` flags inline-style drift."
+    );
+  }
   lines.push("");
   lines.push("\u2550\u2550\u2550 TREATMENT SURFACE \u2014 USE WHAT EXISTS \u2550\u2550\u2550");
   lines.push("");
-  lines.push(
-    "60+ treatment classes ship in src/styles/treatments.css. Reach for these BEFORE inventing equivalent CSS. Families:"
-  );
-  lines.push(
-    "- Core surfaces: d-interactive (data-variant + data-size), d-surface, d-data + d-data-row/cell/header, d-control, d-section, d-annotation, d-label"
-  );
-  lines.push(
-    '- Common UI: d-link, d-icon-btn (data-size + data-variant), d-nav-link, d-step-chip (data-step-state="pending|active|done"), d-divider-{top,bottom,left,right}'
-  );
-  lines.push(
-    "- Utility primitives (1.7.21): d-tooltip (data-position), d-empty-state, d-breadcrumb + d-breadcrumb-item (data-current) + d-breadcrumb-separator, d-avatar (data-size), d-icon-well (data-size), d-toggle (data-on), d-toc + d-toc-item (data-current), d-popover"
-  );
-  lines.push(
-    '- Spatial / graph: d-agent-node, d-port (data-side, data-active); d-cta-banner; d-interactive[data-variant="dark"]'
-  );
-  lines.push(
-    '- Shells (14 layouts shipped): d-shell + data-layout="sidebar-main | centered | top-nav-footer | sidebar-aside | top-nav-main | minimal-header | full-bleed | recipefork-top-nav | canvas-overlay | chat-portal | copilot-overlay | terminal-split | three-column-browser | workspace-aside". Child regions: d-shell-sidebar, d-shell-main, d-shell-aside, d-shell-header, d-shell-body, d-shell-footer, d-shell-centered-card, d-shell-list (three-column-browser), d-shell-copilot (copilot-overlay), d-shell-status-bar + d-shell-hotkey-bar (terminal-split), d-shell-overlay (canvas-overlay, with data-corner). d-shell-mobile-trigger + d-shell-mobile-backdrop close the mobile drawer loop.'
-  );
-  lines.push(
-    '- Modal / palette: d-modal (data-align="top"), d-modal-backdrop, d-modal-panel (data-size="sm|lg"), d-palette + d-palette-input/list/row/section, d-kbd, d-hotkey-indicator'
-  );
-  lines.push("- Composite card: d-card, d-card-header, d-card-body, d-card-footer");
-  lines.push(
-    "- Motion: d-enter-fade, d-enter-slide-up, d-enter-scale, d-stagger-children, d-pulse, d-pulse-ring, d-shimmer, d-float, d-glow-hover, d-scale-hover, d-lift-hover, d-ripple"
-  );
-  lines.push(
-    "- Typography: d-display, d-headline, d-title, d-subtitle, d-prose, d-body, d-caption, d-eyebrow, d-numeric, d-mono-text"
-  );
-  lines.push('- Elevation: d-elevate[data-level="0..5"]');
-  lines.push(
-    "- Data-viz: d-timeline-rail + d-timeline-dot[data-state], d-sparkline + d-sparkline-path/area, d-intent-radar + d-intent-radar-ring/axis, d-waveform, d-qr-placeholder, d-conic-ring (--d-conic-value 0..1), d-heatmap-cell"
-  );
+  if (usesDecantrCss) {
+    lines.push(
+      "60+ treatment classes ship in src/styles/treatments.css. Reach for these before inventing CSS:"
+    );
+    lines.push(
+      "- Shells: d-shell + data-layout, d-shell-sidebar/main/aside/header/body/footer, d-shell-mobile-trigger/backdrop"
+    );
+    lines.push(
+      "- Core UI: d-interactive, d-icon-btn, d-nav-link, d-step-chip, d-control, d-card, d-data, d-label, d-annotation"
+    );
+    lines.push(
+      "- Overlays: d-modal, d-modal-backdrop, d-modal-panel, d-palette, d-tooltip, d-popover"
+    );
+    lines.push(
+      "- Motion/type/data-viz: d-enter-*, d-stagger-children, d-pulse, d-lift-hover, d-display/headline/title, d-sparkline, d-conic-ring, d-heatmap-cell"
+    );
+  } else {
+    lines.push(
+      "The treatment names in the packs describe reusable UI roles. Map shells, cards, controls, overlays, motion, typography, and data-viz roles into the project styling system instead of inventing unrelated component language."
+    );
+  }
   lines.push("");
   lines.push(
-    "Token scales are tunable via CSS vars: --d-motion-{instant,fast,base,slow,slower}, --d-text-{xs..6xl}, --d-elevation-{1..5}, --d-tracking-*, --d-leading-*, --d-weight-*. Themes override per-blueprint."
+    "Consult DECANTR.md only when you need the full table or exact data-* attributes."
   );
   lines.push("");
   lines.push("\u2550\u2550\u2550 THEME DECORATOR CONTRACT \u2014 APPLY OR THE THEME DOES NOT LAND \u2550\u2550\u2550");
   lines.push("");
   lines.push(
-    'Each theme ships 5-15 namespaced decorator classes (`clean-card`, `lum-glass`, `carbon-canvas`, `paper-card`, etc.). The full Class | Intent | Apply-to contract for the active theme is in scaffold-pack.md under "Required Theme Decorators". Apply them as additive classes alongside d-* treatments \u2014 that is what makes the theme look like the theme rather than "themed colors only."'
+    'Each theme ships namespaced decorator classes (`clean-card`, `lum-glass`, `carbon-canvas`, `paper-card`, etc.). Apply the scaffold-pack.md "Required Theme Decorators" as additive classes alongside d-* treatments so the theme lands as more than token colors.'
   );
   lines.push(
-    'Section packs ship a one-line pointer to the scaffold-pack table; the canonical contract is in scaffold-pack.md (also mirrored in DECANTR.md "Decorator Quick Reference" with intent + apply-to + key CSS).'
+    "Section packs may point back to the scaffold-pack table; scaffold-pack.md is authoritative."
   );
   lines.push("");
   lines.push("\u2550\u2550\u2550 HARD RULES (NON-NEGOTIABLE) \u2550\u2550\u2550");
   lines.push("");
+  if (usesDecantrCss) {
+    lines.push(
+      '- Auth pages use `d-shell[data-layout="centered"]` with `d-shell-centered-card` around the form.'
+    );
+    lines.push(
+      '- Command palette uses `d-modal[data-align="top"]` + `d-modal-backdrop` + `d-palette`; rows include Lucide icon, label, and d-kbd hotkey.'
+    );
+  } else {
+    lines.push("- Auth pages use a centered shell with a focused centered-card form surface.");
+    lines.push(
+      "- Command palette uses an accessible modal/palette structure; rows include Lucide icon, label, and keyboard hint where the product contract calls for it."
+    );
+  }
   lines.push(
-    '- Auth pages MUST wrap content in `<div className="d-shell" data-layout="centered"><div className="d-shell-centered-card">{form}</div></div>`. Skipping d-shell-centered-card produces a full-viewport-width card.'
+    "- Use lucide-react for ALL iconography (already in package.json). Pick semantic icons (Bot, Activity, Database, Search) over generic ones. Do NOT inline SVGs for icons that have Lucide equivalents."
   );
   lines.push(
-    '- Command palette MUST wrap `<div className="d-palette">` inside `<div className="d-modal" data-align="top"><div className="d-modal-backdrop" onClick={close} />{palette}</div>`. Without the modal+backdrop wrap, the palette renders as a full-width strip pinned to viewport top. Group commands via d-palette-section eyebrow rows (honor blueprint\'s commands[].section). Each row anatomy: [Lucide icon | label | d-kbd hotkey].'
+    "- Section Directives in section packs are execution rules for layout proportions, treatment stacks, copy conventions, and pattern fitness."
   );
   lines.push(
-    "- Use lucide-react for ALL iconography (already in package.json). Pick semantic icons (Bot, Activity, Database, Search) over generic ones. Do NOT inline SVGs for icons that have Lucide equivalents."
+    "- Filter chip rows / tab strips use `d-step-chip[data-step-state]`, not bare `d-interactive` buttons."
   );
   lines.push(
-    "- Section Directives (when present in section-*-pack.md) are non-negotiable execution rules. They define layout proportions, treatment stacks (e.g., card-grid uses d-card + d-elevate[1] + d-lift-hover + theme card decorator + d-stagger-children), copy conventions, and pattern-fitness rules per section. Honor them exactly \u2014 they encode product-quality decisions the registry author made for this archetype."
+    "- Do not render Decantr guard prose, implementation notes, keyboard shortcut hints, or treatment/debug labels as product UI unless a route/shell contract explicitly declares that text as user-facing."
   );
   lines.push(
-    "- Filter chip rows / tab strips MUST use d-step-chip with data-step-state, NOT bare d-interactive. d-step-chip ships proper active-fill, hover-tint, and chip-row sizing. Bare buttons make filter rows look like generic SaaS form controls."
+    "- Prevent layout collisions: hero content, CTA banners, cards, footers, and sticky chrome must not overlap or clip at desktop or mobile widths."
   );
   lines.push("");
   lines.push("\u2550\u2550\u2550 IMPLEMENTATION RULES \u2550\u2550\u2550");
   lines.push(
-    "- Do not invent routes, sections, shells, themes, or features that are not present in the compiled packs."
-  );
-  lines.push(
-    "- Prefer scaffold-pack, section-pack, and page-pack guidance over broader narrative docs when they differ."
+    "- Do not invent routes, sections, shells, themes, or features beyond the compiled packs."
   );
+  lines.push("- Prefer scaffold-pack, section-pack, and page-pack guidance over narrative docs.");
   lines.push(
     "- Start with the shell layouts and route structure first, then build section pages route by route."
   );
+  if (ctx.adoptionMode === "decantr-css") {
+    lines.push("- Import src/styles/global.css, src/styles/tokens.css, and src/styles/treatments.css.");
+  } else if (ctx.adoptionMode === "style-bridge") {
+    lines.push("- Import src/styles/tokens.css and src/styles/decantr-bridge.css where appropriate.");
+  } else {
+    lines.push("- Keep styling imports aligned with the selected runtime; Decantr does not own CSS here.");
+  }
   lines.push(
-    "- Import src/styles/global.css, src/styles/tokens.css, and src/styles/treatments.css."
-  );
-  lines.push(
-    "- Use the existing Decantr tokens, treatments, and decorators instead of inventing a new visual system."
+    usesDecantrCss ? "- Use the existing Decantr tokens, treatments, and decorators instead of inventing a new visual system." : "- Map Decantr tokens, treatments, and decorators into the selected runtime instead of inventing an unrelated visual system."
   );
   lines.push(
-    "- If package.json, app entry files, or router/runtime files are absent, create them explicitly for the declared target instead of assuming a hidden starter already exists in the workspace."
+    "- If package.json, app entry files, or router/runtime files are absent, create them for the declared target."
   );
   lines.push(
-    "- Do not use inline visual style values or component-scoped <style> tags as the primary styling path. Colors, spacing, borders, shadows, gradients, and transitions should come from atoms, treatments, decorators, or CSS variables. Inline styles are only acceptable for truly dynamic geometry (computed positions, CSS custom properties like --d-stagger-index, dynamic gradient hues) that cannot be expressed through the contract."
+    usesDecantrCss ? "- Colors, spacing, borders, shadows, gradients, and transitions should come from atoms, treatments, decorators, or CSS variables." : "- Colors, spacing, borders, shadows, gradients, and transitions should come from the project styling system or mapped Decantr variables."
   );
   lines.push(
-    "- Let shells own spacing, centering, and scroll containers. Pages should not duplicate shell responsibilities with extra full-height wrappers, max-width wrappers, or page-local padding unless the route contract explicitly requires it."
+    "- Let shells own spacing, centering, and scroll containers unless the route contract says otherwise."
   );
   lines.push(
-    "- If command_palette or hotkeys are declared in the generated context, implement them as real features. Do not merely acknowledge them in copy or comments."
+    "- If command_palette or hotkeys are declared, implement them as real features rather than visible copy."
   );
   lines.push(
     "- Treat declared hotkeys as interaction bindings by default, not visible navigation label text, unless the shell or route contract explicitly calls for shown shortcut hints."
   );
   lines.push(
-    "- If a required decorator class is referenced in the contract but missing from generated CSS, report the contract gap instead of inventing a parallel visual system."
+    "- If a required decorator class is missing from generated CSS, report the contract gap instead of inventing a parallel system."
   );
   lines.push(
     "- Do not modify generated context files unless the task is explicitly to regenerate or refresh Decantr context."
@@ -4226,7 +4766,7 @@ function generateGreenfieldPrompt(ctx) {
   lines.push("- Build the shell and shared layout first.");
   lines.push("- Then implement each section's pages using the matching section and page packs.");
   lines.push(
-    "- After implementation, run `decantr check` (primary gate \u2014 8 guard rules including the experiential interactions guard). It fails strict-mode builds when declared interactions[] are not implemented; the suggestions point at the canonical implementation. Run `decantr audit` (supplementary \u2014 surfaces inline-style counts, security hygiene findings, accessibility / auth-flow advisories) for deeper diagnostics."
+    "- After implementation, run `decantr check` (primary gate) and `decantr audit` (supplementary diagnostics)."
   );
   lines.push("- Fix all violations until `decantr check` exits 0.");
   lines.push(
@@ -4236,14 +4776,32 @@ function generateGreenfieldPrompt(ctx) {
 }
 function generateBrownfieldPrompt(ctx) {
   const lines = [];
-  lines.push("Attach Decantr to this existing application without rebuilding it from scratch.");
+  lines.push(
+    ctx.workflow === "hybrid-compose" ? "Compose the requested Decantr registry contract into this existing application without rebuilding it from scratch." : "Attach Decantr to this existing application without rebuilding it from scratch."
+  );
+  lines.push("");
+  if (ctx.blueprint) lines.push(`Blueprint: ${ctx.blueprint}`);
+  if (ctx.archetype) lines.push(`Primary archetype: ${ctx.archetype}`);
+  if (ctx.theme) lines.push(`Theme: ${ctx.theme}${ctx.mode ? ` (${ctx.mode})` : ""}`);
+  if (ctx.target) lines.push(`Target: ${ctx.target}`);
+  if (ctx.pages.length > 0) {
+    lines.push(
+      `Routes/pages: ${ctx.pages.map((page) => `${page.sectionId ? `${page.sectionId}/` : ""}${page.id}:${page.shell}`).join(", ")}`
+    );
+  }
   lines.push("");
   lines.push(
     "Preserve the current framework, package manager, router, build tooling, and working runtime structure unless the generated Decantr contract gives you a reviewed reason to change them."
   );
   lines.push("");
-  lines.push("Treat .decantr/analysis.json as the factual inventory of the current app.");
-  lines.push("Treat .decantr/init-seed.json as the recommended Decantr attach defaults.");
+  if (ctx.analysisArtifacts) {
+    lines.push("Treat .decantr/analysis.json as the factual inventory of the current app.");
+    lines.push("Treat .decantr/init-seed.json as the recommended Decantr attach defaults.");
+  } else {
+    lines.push(
+      "No Decantr analysis seed is present. Start by inventorying the app before changing runtime files."
+    );
+  }
   lines.push(
     "Treat the compiled execution-pack files as the Decantr contract you are layering onto the app."
   );
@@ -4252,20 +4810,34 @@ function generateBrownfieldPrompt(ctx) {
   );
   lines.push("");
   lines.push("Read in this order:");
-  lines.push(
-    "1. .decantr/analysis.json for the detected framework, routes, styling, layout, and dependencies."
-  );
-  lines.push("2. .decantr/init-seed.json for the intended attach defaults and workflow lane.");
-  lines.push("3. DECANTR.md for guard rules, CSS expectations, and Decantr operating rules.");
-  lines.push(
-    "4. .decantr/context/scaffold-pack.md for the compact compiled shell, theme, feature, and route contract."
-  );
-  lines.push(
-    "5. .decantr/context/scaffold.md for broader topology, route map, and voice guidance."
-  );
-  lines.push(
-    "6. The matching section and page pack files only when you are working on those specific surfaces."
-  );
+  if (ctx.analysisArtifacts) {
+    lines.push(
+      "1. .decantr/analysis.json for the detected framework, routes, styling, layout, and dependencies."
+    );
+    lines.push("2. .decantr/init-seed.json for the intended attach defaults and workflow lane.");
+    lines.push("3. DECANTR.md for guard rules, CSS expectations, and Decantr operating rules.");
+    lines.push(
+      "4. .decantr/context/scaffold-pack.md for the compact compiled shell, theme, feature, and route contract."
+    );
+    lines.push(
+      "5. .decantr/context/scaffold.md for broader topology, route map, and voice guidance."
+    );
+    lines.push(
+      "6. The matching section and page pack files only when you are working on those specific surfaces."
+    );
+  } else {
+    lines.push("1. Inventory existing framework, routes, styling, layout, rule files, and dependencies.");
+    lines.push("2. DECANTR.md for guard rules, adoption mode, and Decantr operating rules.");
+    lines.push(
+      "3. .decantr/context/scaffold-pack.md for the compact compiled shell, theme, feature, and route contract."
+    );
+    lines.push(
+      "4. .decantr/context/scaffold.md for broader topology, route map, and voice guidance."
+    );
+    lines.push(
+      "5. The matching section and page pack files only when you are working on those specific surfaces."
+    );
+  }
   lines.push("");
   lines.push("Implementation rules:");
   lines.push(
@@ -4277,21 +4849,33 @@ function generateBrownfieldPrompt(ctx) {
   lines.push(
     "- If package.json, router files, or style files already exist, extend them deliberately instead of replacing them with a different starter shape."
   );
+  if (ctx.adoptionMode === "decantr-css") {
+    lines.push(
+      "- If Decantr style files are absent, add src/styles/global.css, src/styles/tokens.css, and src/styles/treatments.css in a way that fits the current app structure."
+    );
+    lines.push(
+      "- Use the existing Decantr tokens, treatments, and decorators instead of inventing a parallel visual system."
+    );
+  } else if (ctx.adoptionMode === "style-bridge") {
+    lines.push(
+      "- Use Decantr bridge files as a mapping layer onto the existing styling system; do not install @decantr/css unless explicitly requested."
+    );
+  } else {
+    lines.push(
+      "- Keep the existing styling system. Do not add Decantr CSS files or @decantr/css unless the adoption mode changes."
+    );
+  }
   lines.push(
-    "- If Decantr style files are absent, add src/styles/global.css, src/styles/tokens.css, and src/styles/treatments.css in a way that fits the current app structure."
-  );
-  lines.push(
-    "- Use the existing Decantr tokens, treatments, and decorators instead of inventing a parallel visual system."
-  );
-  lines.push(
-    "- Registry content is optional in this workflow unless the task explicitly asks for blueprint/theme/pattern enrichment."
+    ctx.workflow === "hybrid-compose" ? "- Registry content is part of this task. Layer it onto the current app through existing route/component anchors before creating new runtime structure." : "- Registry content is optional in this workflow unless the task explicitly asks for blueprint/theme/pattern enrichment."
   );
   lines.push(
     "- Do not invent routes, sections, shells, themes, or features that are not present in the compiled packs."
   );
-  lines.push(
-    "- Do not use inline visual style values or component-scoped <style> tags as the primary styling path. Colors, spacing, borders, shadows, gradients, and transitions should come from atoms, treatments, decorators, or CSS variables."
-  );
+  if (ctx.adoptionMode === "decantr-css") {
+    lines.push(
+      "- Do not use inline visual style values or component-scoped <style> tags as the primary styling path. Colors, spacing, borders, shadows, gradients, and transitions should come from atoms, treatments, decorators, or CSS variables."
+    );
+  }
   lines.push(
     "- Let shells own spacing, centering, and scroll containers. Preserve app structure, but remove duplicated shell responsibilities when the contract makes them explicit."
   );
@@ -4322,7 +4906,7 @@ function generateBrownfieldPrompt(ctx) {
   return lines.join("\n");
 }
 function generateCuratedPrompt(ctx) {
-  return ctx.workflow === "brownfield-attach" ? generateBrownfieldPrompt(ctx) : generateGreenfieldPrompt(ctx);
+  return ctx.workflow === "brownfield-attach" || ctx.workflow === "hybrid-compose" ? generateBrownfieldPrompt(ctx) : generateGreenfieldPrompt(ctx);
 }
 function getAPIClient() {
   return new RegistryAPIClient3({
@@ -4336,7 +4920,7 @@ function getPublicAPIClient() {
   });
 }
 function resolveUserPath(inputPath, cwd = process.cwd()) {
-  return isAbsolute(inputPath) ? inputPath : resolve3(cwd, inputPath);
+  return isAbsolute(inputPath) ? inputPath : resolve4(cwd, inputPath);
 }
 function extractHostedAssetPaths(indexHtml) {
   const assetPaths = /* @__PURE__ */ new Set();
@@ -4349,18 +4933,18 @@ function extractHostedAssetPaths(indexHtml) {
   return [...assetPaths];
 }
 function readHostedDistSnapshot(distPath) {
-  const resolvedDistPath = distPath ? resolveUserPath(distPath) : join26(process.cwd(), "dist");
-  const indexPath = join26(resolvedDistPath, "index.html");
-  if (!existsSync25(indexPath)) {
+  const resolvedDistPath = distPath ? resolveUserPath(distPath) : join28(process.cwd(), "dist");
+  const indexPath = join28(resolvedDistPath, "index.html");
+  if (!existsSync27(indexPath)) {
     return void 0;
   }
-  const indexHtml = readFileSync18(indexPath, "utf-8");
+  const indexHtml = readFileSync20(indexPath, "utf-8");
   const assetPaths = extractHostedAssetPaths(indexHtml);
   const assets = {};
   for (const assetPath of assetPaths) {
-    const assetFilePath = join26(resolvedDistPath, assetPath.replace(/^[/\\]+/, ""));
-    if (existsSync25(assetFilePath)) {
-      assets[assetPath] = readFileSync18(assetFilePath, "utf-8");
+    const assetFilePath = join28(resolvedDistPath, assetPath.replace(/^[/\\]+/, ""));
+    if (existsSync27(assetFilePath)) {
+      assets[assetPath] = readFileSync20(assetFilePath, "utf-8");
     }
   }
   return {
@@ -4375,7 +4959,7 @@ function isHostedSourceSnapshotFile(path) {
 function readHostedSourceSnapshot(sourcePath) {
   if (!sourcePath) return void 0;
   const resolvedSourcePath = resolveUserPath(sourcePath);
-  if (!existsSync25(resolvedSourcePath)) {
+  if (!existsSync27(resolvedSourcePath)) {
     return void 0;
   }
   const files = {};
@@ -4389,17 +4973,17 @@ function readHostedSourceSnapshot(sourcePath) {
   ]);
   const rootPrefix = basename2(resolvedSourcePath);
   const walk = (absoluteDir, relativeDir) => {
-    for (const entry of readdirSync6(absoluteDir, { withFileTypes: true })) {
+    for (const entry of readdirSync7(absoluteDir, { withFileTypes: true })) {
       if (ignoredDirNames.has(entry.name)) continue;
-      const absolutePath = join26(absoluteDir, entry.name);
-      const relativePath = join26(relativeDir, entry.name).replace(/\\/g, "/");
+      const absolutePath = join28(absoluteDir, entry.name);
+      const relativePath = join28(relativeDir, entry.name).replace(/\\/g, "/");
       if (entry.isDirectory()) {
         walk(absolutePath, relativePath);
         continue;
       }
       if (!entry.isFile()) continue;
       if (!isHostedSourceSnapshotFile(relativePath)) continue;
-      files[relativePath] = readFileSync18(absolutePath, "utf-8");
+      files[relativePath] = readFileSync20(absolutePath, "utf-8");
     }
   };
   walk(resolvedSourcePath, rootPrefix);
@@ -4550,16 +5134,16 @@ async function printRegistryIntelligenceSummary(namespace, jsonOutput = false) {
 }
 async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join26(process.cwd(), "decantr.essence.json");
-  if (!existsSync25(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
-  const essence = JSON.parse(readFileSync18(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const bundle = await client.compileExecutionPacks(essence, namespace ? { namespace } : void 0);
   let writtenContextPaths = [];
   if (writeContext) {
-    const contextDir = join26(process.cwd(), ".decantr", "context");
-    mkdirSync10(contextDir, { recursive: true });
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync11(contextDir, { recursive: true });
     const written = writeExecutionPackBundleArtifacts(
       contextDir,
       bundle
@@ -4584,26 +5168,27 @@ async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput
   console.log(`  Sections: ${typedBundle.sections.length}`);
   console.log(`  Mutations: ${typedBundle.mutations.length}`);
   if (writeContext) {
-    console.log(`  Context bundle: ${join26(process.cwd(), ".decantr", "context")}`);
+    console.log(`  Context bundle: ${join28(process.cwd(), ".decantr", "context")}`);
     console.log(`  Files written: ${writtenContextPaths.length}`);
   }
   console.log("");
   console.log(`${BOLD6}Route Plan:${RESET13}`);
   for (const route of typedBundle.scaffold.data.routes) {
     const patterns = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
-    console.log(`  ${cyan3(route.path)} -> ${route.pageId} [${patterns}]`);
+    const pageLabel = route.sectionId ? `${route.sectionId}/${route.pageId}` : route.pageId;
+    console.log(`  ${cyan3(route.path)} -> ${pageLabel} [${patterns}]`);
   }
 }
 async function printHostedSelectedExecutionPack(packType, id, essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join26(process.cwd(), "decantr.essence.json");
-  if (!existsSync25(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
   if ((packType === "section" || packType === "page" || packType === "mutation") && !id) {
     throw new Error(`Pack type "${packType}" requires an id.`);
   }
-  const essence = JSON.parse(readFileSync18(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const selected = await client.selectExecutionPack(
     {
       essence,
@@ -4614,17 +5199,17 @@ async function printHostedSelectedExecutionPack(packType, id, essencePath, names
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join26(process.cwd(), ".decantr", "context");
-    mkdirSync10(contextDir, { recursive: true });
-    writeFileSync13(
-      join26(contextDir, "pack-manifest.json"),
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync11(contextDir, { recursive: true });
+    writeFileSync14(
+      join28(contextDir, "pack-manifest.json"),
       JSON.stringify(selected.manifest, null, 2) + "\n"
     );
     const manifestEntry = selected.selector.packType === "scaffold" ? selected.manifest.scaffold : selected.selector.packType === "review" ? selected.manifest.review : selected.selector.packType === "section" ? selected.manifest.sections.find((entry) => entry.id === selected.selector.id) : selected.selector.packType === "page" ? selected.manifest.pages.find((entry) => entry.id === selected.selector.id) : selected.manifest.mutations.find((entry) => entry.id === selected.selector.id);
     const markdownFile = manifestEntry?.markdown ?? `${selected.selector.packType}${selected.selector.id ? `-${selected.selector.id}` : ""}-pack.md`;
     const jsonFile = manifestEntry?.json ?? `${selected.selector.packType}${selected.selector.id ? `-${selected.selector.id}` : ""}-pack.json`;
-    writeFileSync13(join26(contextDir, markdownFile), selected.pack.renderedMarkdown);
-    writeFileSync13(join26(contextDir, jsonFile), JSON.stringify(selected.pack, null, 2) + "\n");
+    writeFileSync14(join28(contextDir, markdownFile), selected.pack.renderedMarkdown);
+    writeFileSync14(join28(contextDir, jsonFile), JSON.stringify(selected.pack, null, 2) + "\n");
     writtenContextDir = contextDir;
   }
   if (jsonOutput) {
@@ -4649,20 +5234,20 @@ async function printHostedSelectedExecutionPack(packType, id, essencePath, names
 }
 async function printHostedExecutionPackManifest(essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join26(process.cwd(), "decantr.essence.json");
-  if (!existsSync25(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
-  const essence = JSON.parse(readFileSync18(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const manifest = await client.getExecutionPackManifest(
     essence,
     namespace ? { namespace } : void 0
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join26(process.cwd(), ".decantr", "context");
-    mkdirSync10(contextDir, { recursive: true });
-    writeFileSync13(join26(contextDir, "pack-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync11(contextDir, { recursive: true });
+    writeFileSync14(join28(contextDir, "pack-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
     writtenContextDir = contextDir;
   }
   if (jsonOutput) {
@@ -4683,14 +5268,14 @@ async function printHostedExecutionPackManifest(essencePath, namespace, jsonOutp
   }
 }
 async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@official") {
-  const contextDir = join26(projectRoot, ".decantr", "context");
-  const reviewPackPath = join26(contextDir, "review-pack.json");
-  const manifestPath = join26(contextDir, "pack-manifest.json");
-  if (existsSync25(reviewPackPath) && existsSync25(manifestPath)) {
+  const contextDir = join28(projectRoot, ".decantr", "context");
+  const reviewPackPath = join28(contextDir, "review-pack.json");
+  const manifestPath = join28(contextDir, "pack-manifest.json");
+  if (existsSync27(reviewPackPath) && existsSync27(manifestPath)) {
     return { attempted: false, hydrated: false };
   }
-  const essencePath = join26(projectRoot, "decantr.essence.json");
-  if (!existsSync25(essencePath)) {
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  if (!existsSync27(essencePath)) {
     return { attempted: false, hydrated: false };
   }
   const reviewHydration = await hydrateHostedReviewPackIfMissing(projectRoot, namespace);
@@ -4699,9 +5284,9 @@ async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@o
   }
   try {
     const client = getPublicAPIClient();
-    const essence = JSON.parse(readFileSync18(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const bundle = await client.compileExecutionPacks(essence, { namespace });
-    mkdirSync10(contextDir, { recursive: true });
+    mkdirSync11(contextDir, { recursive: true });
     writeExecutionPackBundleArtifacts(contextDir, bundle);
     return { attempted: true, hydrated: true, scope: "bundle" };
   } catch {
@@ -4709,19 +5294,19 @@ async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@o
   }
 }
 async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@official") {
-  const contextDir = join26(projectRoot, ".decantr", "context");
-  const reviewPackPath = join26(contextDir, "review-pack.json");
-  const manifestPath = join26(contextDir, "pack-manifest.json");
-  if (existsSync25(reviewPackPath) && existsSync25(manifestPath)) {
+  const contextDir = join28(projectRoot, ".decantr", "context");
+  const reviewPackPath = join28(contextDir, "review-pack.json");
+  const manifestPath = join28(contextDir, "pack-manifest.json");
+  if (existsSync27(reviewPackPath) && existsSync27(manifestPath)) {
     return { attempted: false, hydrated: false };
   }
-  const essencePath = join26(projectRoot, "decantr.essence.json");
-  if (!existsSync25(essencePath)) {
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  if (!existsSync27(essencePath)) {
     return { attempted: false, hydrated: false };
   }
   try {
     const client = getPublicAPIClient();
-    const essence = JSON.parse(readFileSync18(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const selected = await client.selectExecutionPack(
       {
         essence,
@@ -4729,14 +5314,14 @@ async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@offic
       },
       { namespace }
     );
-    mkdirSync10(contextDir, { recursive: true });
-    writeFileSync13(join26(contextDir, "review-pack.md"), selected.pack.renderedMarkdown);
-    writeFileSync13(
-      join26(contextDir, "review-pack.json"),
+    mkdirSync11(contextDir, { recursive: true });
+    writeFileSync14(join28(contextDir, "review-pack.md"), selected.pack.renderedMarkdown);
+    writeFileSync14(
+      join28(contextDir, "review-pack.json"),
       JSON.stringify(selected.pack, null, 2) + "\n"
     );
-    if (!existsSync25(manifestPath)) {
-      writeFileSync13(manifestPath, JSON.stringify(selected.manifest, null, 2) + "\n");
+    if (!existsSync27(manifestPath)) {
+      writeFileSync14(manifestPath, JSON.stringify(selected.manifest, null, 2) + "\n");
     }
     return { attempted: true, hydrated: true, scope: "review" };
   } catch {
@@ -4746,17 +5331,17 @@ async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@offic
 async function printHostedFileCritique(sourcePath, namespace, jsonOutput = false, essencePath, treatmentsPath) {
   const client = getPublicAPIClient();
   const resolvedSourcePath = resolveUserPath(sourcePath);
-  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join26(process.cwd(), "decantr.essence.json");
-  const resolvedTreatmentsPath = treatmentsPath ? resolveUserPath(treatmentsPath) : join26(process.cwd(), "src", "styles", "treatments.css");
-  if (!existsSync25(resolvedSourcePath)) {
+  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  const resolvedTreatmentsPath = treatmentsPath ? resolveUserPath(treatmentsPath) : join28(process.cwd(), "src", "styles", "treatments.css");
+  if (!existsSync27(resolvedSourcePath)) {
     throw new Error(`Source file not found at ${resolvedSourcePath}`);
   }
-  if (!existsSync25(resolvedEssencePath)) {
+  if (!existsSync27(resolvedEssencePath)) {
     throw new Error(`Essence file not found at ${resolvedEssencePath}`);
   }
-  const code = readFileSync18(resolvedSourcePath, "utf-8");
-  const essence = JSON.parse(readFileSync18(resolvedEssencePath, "utf-8"));
-  const treatmentsCss = existsSync25(resolvedTreatmentsPath) ? readFileSync18(resolvedTreatmentsPath, "utf-8") : void 0;
+  const code = readFileSync20(resolvedSourcePath, "utf-8");
+  const essence = JSON.parse(readFileSync20(resolvedEssencePath, "utf-8"));
+  const treatmentsCss = existsSync27(resolvedTreatmentsPath) ? readFileSync20(resolvedTreatmentsPath, "utf-8") : void 0;
   const report = await client.critiqueFile(
     {
       essence,
@@ -4780,11 +5365,11 @@ async function printHostedFileCritique(sourcePath, namespace, jsonOutput = false
 }
 async function printHostedProjectAudit(namespace, jsonOutput = false, essencePath, distPath, sourcesPath) {
   const client = getPublicAPIClient();
-  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join26(process.cwd(), "decantr.essence.json");
-  if (!existsSync25(resolvedEssencePath)) {
+  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedEssencePath)) {
     throw new Error(`Essence file not found at ${resolvedEssencePath}`);
   }
-  const essence = JSON.parse(readFileSync18(resolvedEssencePath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedEssencePath, "utf-8"));
   const dist = readHostedDistSnapshot(distPath);
   const sources = readHostedSourceSnapshot(sourcesPath);
   const report = await client.auditProject(
@@ -4802,7 +5387,7 @@ async function printHostedProjectAudit(namespace, jsonOutput = false, essencePat
   console.log(heading2("Hosted Project Audit"));
   console.log(`  Essence: ${resolvedEssencePath}`);
   console.log(
-    `  Dist snapshot: ${dist ? distPath ? resolveUserPath(distPath) : join26(process.cwd(), "dist") : "none"}`
+    `  Dist snapshot: ${dist ? distPath ? resolveUserPath(distPath) : join28(process.cwd(), "dist") : "none"}`
   );
   console.log(
     `  Source snapshot: ${sources && sourcesPath ? resolveUserPath(sourcesPath) : "none"}`
@@ -4883,25 +5468,25 @@ async function cmdGet(type, id) {
   }
   const apiType = CONTENT_TYPE_TO_API_CONTENT_TYPE3[type];
   const registryClient = new RegistryClient({
-    cacheDir: join26(process.cwd(), ".decantr", "cache")
+    cacheDir: join28(process.cwd(), ".decantr", "cache")
   });
   const result = await registryClient.fetchContentItem(apiType, id);
   if (result) {
     console.log(JSON.stringify(result.data, null, 2));
     return;
   }
-  const currentDir = dirname2(fileURLToPath2(import.meta.url));
+  const currentDir = dirname4(fileURLToPath2(import.meta.url));
   const bundledCandidates = [
-    join26(currentDir, "bundled", apiType, `${id}.json`),
+    join28(currentDir, "bundled", apiType, `${id}.json`),
     // Running from src/
-    join26(currentDir, "..", "src", "bundled", apiType, `${id}.json`),
+    join28(currentDir, "..", "src", "bundled", apiType, `${id}.json`),
     // Running from dist/
-    join26(currentDir, "..", "bundled", apiType, `${id}.json`)
+    join28(currentDir, "..", "bundled", apiType, `${id}.json`)
     // Alternative dist layout
   ];
-  const bundledPath = bundledCandidates.find((p) => existsSync25(p)) || null;
+  const bundledPath = bundledCandidates.find((p) => existsSync27(p)) || null;
   if (bundledPath) {
-    const data = JSON.parse(readFileSync18(bundledPath, "utf-8"));
+    const data = JSON.parse(readFileSync20(bundledPath, "utf-8"));
     console.log(JSON.stringify(data, null, 2));
     return;
   }
@@ -4910,10 +5495,10 @@ async function cmdGet(type, id) {
   return;
 }
 async function cmdValidate(path) {
-  const essencePath = path || join26(process.cwd(), "decantr.essence.json");
+  const essencePath = path || join28(process.cwd(), "decantr.essence.json");
   let raw;
   try {
-    raw = readFileSync18(essencePath, "utf-8");
+    raw = readFileSync20(essencePath, "utf-8");
   } catch {
     console.error(error3(`Could not read ${essencePath}`));
     process.exitCode = 1;
@@ -4982,7 +5567,7 @@ async function cmdList(type, sort, recommended, intelligenceSource) {
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join26(process.cwd(), ".decantr", "cache")
+    cacheDir: join28(process.cwd(), ".decantr", "cache")
   });
   const result = await registryClient.fetchContentList(
     type,
@@ -5029,11 +5614,17 @@ async function cmdList(type, sort, recommended, intelligenceSource) {
   }
 }
 async function cmdInit(args) {
-  const projectRoot = process.cwd();
+  const workspaceInfo = resolveWorkspaceInfo(process.cwd(), args.project);
+  if (args.yes && workspaceInfo.requiresProjectSelection) {
+    console.log(error3("This looks like a workspace root with multiple app candidates."));
+    console.log(dim3(`Use --project=<path>. Candidates: ${workspaceInfo.appCandidates.join(", ")}`));
+    process.exitCode = 1;
+    return;
+  }
+  const projectRoot = workspaceInfo.appRoot;
   console.log(heading2("Decantr Project Setup"));
   const detected = detectProject(projectRoot);
   const workflowSeed = readBrownfieldInitSeed(projectRoot);
-  const brownfieldAttach = Boolean(workflowSeed) || hasExistingProjectFootprint(detected);
   if (workflowSeed) {
     console.log(dim3("  Found .decantr/init-seed.json brownfield guidance."));
   }
@@ -5048,11 +5639,27 @@ async function cmdInit(args) {
   const requestedBlueprint = Boolean(args.blueprint);
   const requestedArchetype = Boolean(args.archetype);
   const requestedTheme = Boolean(args.theme);
+  const policy = resolveWorkflowPolicy({
+    command: "init",
+    detected,
+    workflowSeed,
+    requestedWorkflow: args.workflow,
+    requestedAdoption: args.adoption,
+    requestedAssistantBridge: args["assistant-bridge"],
+    requestedBlueprint,
+    requestedArchetype,
+    requestedTheme,
+    explicitExisting: args.existing,
+    offline: args.offline,
+    projectScope: workspaceInfo.projectScope
+  });
+  const preferContractOnly = policy.contentSource === "none" && (policy.workflowMode === "brownfield-attach" || policy.workflowMode === "greenfield-contract-only");
+  const shouldUseRegistry = !preferContractOnly || policy.registryRequired;
   let offlineSeed = {
     seeded: false,
     strategy: null
   };
-  if (args.offline) {
+  if (args.offline && shouldUseRegistry) {
     offlineSeed = seedOfflineRegistry(projectRoot, projectRoot);
     if (offlineSeed.seeded) {
       console.log(dim3(`  Seeded offline registry content from ${offlineSeed.strategy}.`));
@@ -5070,11 +5677,12 @@ async function cmdInit(args) {
     }
   }
   const registryClient = new RegistryClient({
-    cacheDir: join26(projectRoot, ".decantr", "cache"),
+    cacheDir: join28(projectRoot, ".decantr", "cache"),
     apiUrl: args.registry,
-    offline: args.offline
+    offline: args.offline,
+    projectRoot
   });
-  const apiAvailable = await registryClient.checkApiAvailability();
+  const apiAvailable = shouldUseRegistry ? await registryClient.checkApiAvailability() : false;
   if (!apiAvailable && !args.offline && (requestedBlueprint || requestedArchetype)) {
     const fallbackSeed = seedOfflineRegistry(projectRoot, projectRoot);
     if (fallbackSeed.seeded) {
@@ -5084,18 +5692,21 @@ async function cmdInit(args) {
   }
   let selectedBlueprint = "default";
   let registrySource = "cache";
-  const preferContractOnly = brownfieldAttach && !requestedBlueprint && !requestedArchetype;
-  const workflowMode = workflowSeed || brownfieldAttach && !requestedBlueprint && !requestedArchetype ? "brownfield-attach" : "greenfield-scaffold";
   if (args.yes) {
     selectedBlueprint = args.blueprint || "default";
-  } else if (!apiAvailable) {
+  } else if (shouldUseRegistry && !apiAvailable) {
     if (!args.blueprint) {
       console.log(`
 ${YELLOW9}You're offline. Scaffolding minimal Decantr project.${RESET13}`);
       console.log(
         dim3("Run `decantr sync` or `decantr upgrade` when online to pull full registry content.\n")
       );
-      const result2 = scaffoldMinimal(projectRoot);
+      const result2 = scaffoldMinimal(projectRoot, {
+        workflowMode: policy.workflowMode,
+        adoptionMode: policy.adoptionMode,
+        contentSource: policy.contentSource,
+        assistantBridge: policy.assistantBridge
+      });
       console.log(success3("\nProject scaffolded (minimal/offline)!\n"));
       console.log("  Files created:");
       console.log(`    ${cyan3("decantr.essence.json")}    Design specification`);
@@ -5111,7 +5722,7 @@ ${YELLOW9}You're offline. Scaffolding minimal Decantr project.${RESET13}`);
         `    2. Run ${cyan3("decantr refresh")} after syncing to generate scaffold, section, and page packs`
       );
       console.log(
-        `    3. Read ${cyan3("DECANTR.md")} and the generated ${cyan3(".decantr/context/*")} files before implementation`
+        `    3. Read ${cyan3(".decantr/context/scaffold-pack.md")} first, then use ${cyan3("DECANTR.md")} as a lookup reference`
       );
       console.log(
         `    4. Use ${cyan3("decantr create <type> <name>")} to create custom content if needed`
@@ -5136,22 +5747,22 @@ ${YELLOW9}You're offline. Scaffolding minimal Decantr project.${RESET13}`);
 ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
     console.log(dim3("Run `decantr upgrade` when online, or visit decantr.ai/registry\n"));
     selectedBlueprint = "default";
-  } else if (!preferContractOnly) {
+  } else if (shouldUseRegistry) {
     console.log(dim3("Fetching registry content..."));
     const blueprintsResult2 = await registryClient.fetchBlueprints();
     registrySource = blueprintsResult2.source.type === "api" ? "api" : "cache";
     const { selectedBlueprint: selected } = await runSimplifiedInit(blueprintsResult2.data.items);
     selectedBlueprint = selected || "default";
   }
-  const archetypesResult = await registryClient.fetchArchetypes();
-  const blueprintsResult = await registryClient.fetchBlueprints();
-  const themesResult = await registryClient.fetchThemes();
-  if (archetypesResult.source.type === "api") {
+  const archetypesResult = shouldUseRegistry ? await registryClient.fetchArchetypes() : null;
+  const blueprintsResult = shouldUseRegistry ? await registryClient.fetchBlueprints() : null;
+  const themesResult = shouldUseRegistry ? await registryClient.fetchThemes() : null;
+  if (archetypesResult?.source.type === "api") {
     registrySource = "api";
   }
-  const archetypes = archetypesResult.data.items;
-  const blueprints = blueprintsResult.data.items;
-  const themes = themesResult.data.items;
+  const archetypes = archetypesResult?.data.items ?? [];
+  const blueprints = blueprintsResult?.data.items ?? [];
+  const themes = themesResult?.data.items ?? [];
   let options;
   const userExplicit = {
     theme: Boolean(args.theme),
@@ -5159,7 +5770,10 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
     shape: Boolean(args.shape),
     personality: Boolean(args.personality)
   };
-  if (args.yes || selectedBlueprint !== "default") {
+  if (preferContractOnly) {
+    const flags = parseFlags(args, detected);
+    options = mergeWithDefaults(flags, detected, workflowSeed ?? void 0);
+  } else if (args.yes || selectedBlueprint !== "default") {
     const flags = parseFlags(args, detected);
     flags.blueprint = selectedBlueprint !== "default" ? selectedBlueprint : flags.blueprint;
     options = mergeWithDefaults(flags, detected, workflowSeed ?? void 0);
@@ -5176,14 +5790,22 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
     userExplicit.shape = true;
     userExplicit.personality = true;
   }
-  options.workflowMode = workflowMode;
+  options.workflowMode = policy.workflowMode;
+  options.adoptionMode = policy.adoptionMode;
+  options.contentSource = policy.contentSource;
+  options.assistantBridge = policy.assistantBridge;
+  options.projectScope = policy.projectScope;
+  options.workspaceRoot = workspaceInfo.workspaceRoot;
+  options.appRoot = workspaceInfo.appRoot;
+  options.analysisArtifacts = policy.hasAnalysisArtifacts;
+  options.adapterId = resolveBootstrapTarget(options.target).adapterId;
   let topologyMarkdown = "";
   let archetypeData;
   let composedSections;
   let routeMap;
   let patternSpecs;
   let blueprintData;
-  if (options.blueprint) {
+  if (shouldUseRegistry && options.blueprint) {
     const blueprintResult = await registryClient.fetchBlueprint(options.blueprint);
     if (blueprintResult) {
       const blueprint = blueprintResult.data;
@@ -5306,7 +5928,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
         `${YELLOW9}  Warning: Could not fetch blueprint "${options.blueprint}". Using defaults.${RESET13}`
       );
     }
-  } else if (options.archetype) {
+  } else if (shouldUseRegistry && options.archetype) {
     const archetypeResult = await registryClient.fetchArchetype(options.archetype);
     if (archetypeResult) {
       archetypeData = mapRegistryArchetypeToArchetypeData(archetypeResult.data);
@@ -5323,7 +5945,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
     }
   }
   let themeData;
-  if (options.theme) {
+  if (shouldUseRegistry && options.theme) {
     const themeResult = await registryClient.fetchTheme(options.theme);
     if (themeResult) {
       themeData = mapRegistryThemeToThemeData(themeResult.data);
@@ -5355,6 +5977,19 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
     patternSpecs,
     blueprintData
   );
+  let assistantBridgePath = null;
+  let appliedRuleFiles = [];
+  if (policy.assistantBridge === "preview" || policy.assistantBridge === "apply") {
+    assistantBridgePath = writeAssistantBridgePreview({
+      projectRoot,
+      detected,
+      workflowMode: policy.workflowMode,
+      assistantBridge: policy.assistantBridge
+    });
+  }
+  if (policy.assistantBridge === "apply") {
+    appliedRuleFiles = applyAssistantBridge(projectRoot, detected);
+  }
   console.log(success3("\nProject scaffolded!\n"));
   console.log("  Files created:");
   console.log(`    ${cyan3("decantr.essence.json")}    Design specification`);
@@ -5363,7 +5998,13 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   if (result.gitignoreUpdated) {
     console.log(`    ${dim3(".gitignore updated")}`);
   }
-  if (!existsSync25(join26(projectRoot, "package.json"))) {
+  if (assistantBridgePath) {
+    console.log(`    ${cyan3(".decantr/context/assistant-bridge.md")} Assistant bridge preview`);
+  }
+  if (appliedRuleFiles.length > 0) {
+    console.log(`    ${dim3(`Rule bridge applied: ${appliedRuleFiles.join(", ")}`)}`);
+  }
+  if (!existsSync27(join28(projectRoot, "package.json"))) {
     console.log("");
     console.log(
       dim3(`  Note: ${cyan3("decantr init")} created Decantr contract/context files only.`)
@@ -5376,14 +6017,15 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   }
   console.log("");
   console.log("  Next steps:");
-  console.log("    1. Read DECANTR.md for methodology, CSS approach, and guard rules");
+  console.log("    1. Read .decantr/context/scaffold-pack.md first as the primary compiled contract");
   console.log(
-    "    2. Read .decantr/context/scaffold-pack.md first, then .decantr/context/scaffold.md"
+    "    2. Read .decantr/context/scaffold.md for broader topology, route map, and voice guidance"
   );
   console.log("    3. Read the matching section and page packs before implementing each route");
-  console.log("    4. Build the shell and route structure first, then implement the pages");
-  console.log("    5. Run decantr check and decantr audit after implementation");
-  console.log("    6. Explore more at decantr.ai/registry");
+  console.log("    4. Use DECANTR.md as a lookup reference for atoms, treatments, and guard rules");
+  console.log("    5. Build the shell and route structure first, then implement the pages");
+  console.log("    6. Run decantr check and decantr audit after implementation");
+  console.log("    7. Explore more at decantr.ai/registry");
   console.log("");
   console.log("  Commands:");
   console.log(`    ${cyan3("decantr status")}     Project health`);
@@ -5393,7 +6035,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   console.log(`    ${cyan3("decantr upgrade")}    Update to latest patterns`);
   console.log(`    ${cyan3("decantr check")}      Detect drift issues`);
   console.log(`    ${cyan3("decantr migrate")}    Migrate v2 essence to v3`);
-  const essenceContent = readFileSync18(result.essencePath, "utf-8");
+  const essenceContent = readFileSync20(result.essencePath, "utf-8");
   const essence = JSON.parse(essenceContent);
   if (essence.version !== "3.1.0") {
     const validation = validateEssence2(essence);
@@ -5406,11 +6048,12 @@ Validation warnings: ${validation.errors.join(", ")}`));
   let promptPages;
   if (isV36(essence)) {
     const allPages = essence.blueprint.sections ? essence.blueprint.sections.flatMap(
-      (s) => s.pages.map((p) => ({ ...p, _shell: s.shell }))
+      (s) => s.pages.map((p) => ({ ...p, _sectionId: s.id, _shell: s.shell }))
     ) : essence.blueprint.pages || [];
     promptPages = allPages.map(
       (p) => ({
         id: p.id,
+        sectionId: p._sectionId,
         shell: p.shell_override ?? p._shell ?? essence.blueprint.shell,
         layout: (p.layout || []).map(
           (item) => typeof item === "string" ? item : extractPatternName(item)
@@ -5421,7 +6064,9 @@ Validation warnings: ${validation.errors.join(", ")}`));
     promptPages = essence.structure || [{ id: "home", shell: options.shell, layout: ["hero"] }];
   }
   const promptCtx = {
-    workflow: options.workflowMode === "brownfield-attach" ? "brownfield-attach" : "greenfield-scaffold",
+    workflow: options.workflowMode || "greenfield-scaffold",
+    adoptionMode: options.adoptionMode,
+    analysisArtifacts: options.analysisArtifacts,
     archetype: options.archetype || "custom",
     blueprint: options.blueprint,
     theme: options.theme,
@@ -5447,16 +6092,16 @@ Validation warnings: ${validation.errors.join(", ")}`));
 }
 async function cmdStatus() {
   const projectRoot = process.cwd();
-  const essencePath = join26(projectRoot, "decantr.essence.json");
-  const projectJsonPath = join26(projectRoot, ".decantr", "project.json");
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  const projectJsonPath = join28(projectRoot, ".decantr", "project.json");
   console.log(heading2("Decantr Project Status"));
-  if (!existsSync25(essencePath)) {
+  if (!existsSync27(essencePath)) {
     console.log(`${RED11}No decantr.essence.json found.${RESET13}`);
     console.log(dim3('Run "decantr init" to create one.'));
     return;
   }
   try {
-    const essence = JSON.parse(readFileSync18(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const validation = validateEssence2(essence);
     const essenceVersion = isV36(essence) ? "v3" : "v2";
     console.log(`${BOLD6}Essence:${RESET13}`);
@@ -5513,9 +6158,9 @@ async function cmdStatus() {
   }
   console.log("");
   console.log(`${BOLD6}Sync Status:${RESET13}`);
-  if (existsSync25(projectJsonPath)) {
+  if (existsSync27(projectJsonPath)) {
     try {
-      const projectJson = JSON.parse(readFileSync18(projectJsonPath, "utf-8"));
+      const projectJson = JSON.parse(readFileSync20(projectJsonPath, "utf-8"));
       const syncStatus = projectJson.sync?.status || "unknown";
       const lastSync = projectJson.sync?.lastSync || "never";
       const source = projectJson.sync?.registrySource || "unknown";
@@ -5533,7 +6178,7 @@ async function cmdStatus() {
 }
 async function cmdSync() {
   const projectRoot = process.cwd();
-  const cacheDir = join26(projectRoot, ".decantr", "cache");
+  const cacheDir = join28(projectRoot, ".decantr", "cache");
   console.log(heading2("Syncing registry content..."));
   const result = await syncRegistry(cacheDir);
   if (result.synced.length > 0) {
@@ -5728,14 +6373,14 @@ ${BOLD6}Examples:${RESET13}
         process.exitCode = 1;
         return;
       }
-      const themePath = join26(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
-      if (!existsSync25(themePath)) {
+      const themePath = join28(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
+      if (!existsSync27(themePath)) {
         console.error(error3(`Theme "${name}" not found at ${themePath}`));
         process.exitCode = 1;
         return;
       }
       try {
-        const theme = JSON.parse(readFileSync18(themePath, "utf-8"));
+        const theme = JSON.parse(readFileSync20(themePath, "utf-8"));
         const result = validateCustomTheme(theme);
         if (result.valid) {
           console.log(success3(`Custom theme "${name}" is valid`));
@@ -5808,7 +6453,7 @@ function cmdHelp() {
 ${BOLD6}decantr${RESET13} \u2014 Design intelligence for AI-generated UI
 
 ${BOLD6}Usage:${RESET13}
-  decantr new <name> [--blueprint=X] [--archetype=X] [--theme=X]
+  decantr new <name> [--blueprint=X] [--archetype=X] [--theme=X] [--workflow=greenfield] [--adoption=decantr-css]
   decantr magic <prompt> [--dry-run]
   decantr init [options]
   decantr status
@@ -5827,6 +6472,7 @@ ${BOLD6}Usage:${RESET13}
   decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]
   decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]
   decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]
+  decantr rules apply [--project=<path>]
   decantr validate [path]
   decantr theme <subcommand>
   decantr create <type> <name>
@@ -5845,6 +6491,10 @@ ${BOLD6}Init Options:${RESET13}
   --guard            Guard mode: creative | guided | strict
   --density          Spacing: compact | comfortable | spacious
   --shell            Default shell layout
+  --workflow         Workflow: greenfield | brownfield | hybrid
+  --adoption         Adoption: contract-only | style-bridge | decantr-css
+  --assistant-bridge Assistant rules: none | preview | apply
+  --project          App path inside a workspace/monorepo
   --existing         Initialize in existing project
   --offline          Force offline mode
   --yes, -y          Accept defaults, skip confirmations
@@ -5874,6 +6524,7 @@ ${BOLD6}Commands:${RESET13}
   ${cyan3("analyze")}     Brownfield entrypoint: scan an existing project and emit attach guidance
   ${cyan3("export")}      Export design tokens to framework format (shadcn, tailwind, css-vars)
   ${cyan3("registry")}    Registry management and intelligence summary
+  ${cyan3("rules")}       Preview/apply Decantr assistant bridge blocks to repo rule files
   ${cyan3("upgrade")}     Check for content updates from registry
   ${cyan3("help")}        Show this help
 
@@ -5881,7 +6532,11 @@ ${BOLD6}Examples:${RESET13}
   decantr new my-app --blueprint=carbon-ai-portal
   decantr magic "AI chatbot with dark cyber theme \u2014 bold and futuristic"
   decantr init
-  decantr init --existing --blueprint=saas-dashboard --theme=luminarum --yes
+  decantr init --existing --adoption=contract-only --yes
+  decantr init --existing --adoption=style-bridge --assistant-bridge=preview
+  decantr init --workflow=greenfield --adoption=contract-only
+  decantr init --project=apps/web --yes
+  decantr rules apply
   decantr status
   decantr audit
   decantr audit src/pages/HomePage.tsx
@@ -5904,13 +6559,14 @@ ${BOLD6}Examples:${RESET13}
   decantr create pattern my-card
 
 ${BOLD6}Workflow Model:${RESET13}
-  ${cyan3("Greenfield blueprint")}   decantr new / decantr magic
-  ${cyan3("Brownfield adoption")}    decantr analyze -> decantr init --existing
+  ${cyan3("Greenfield blueprint")}   decantr new my-app --blueprint=X --workflow=greenfield --adoption=decantr-css
+  ${cyan3("Greenfield contract")}    decantr init --workflow=greenfield --adoption=contract-only
+  ${cyan3("Brownfield adoption")}    decantr analyze -> decantr init --existing --adoption=contract-only
   ${cyan3("Hybrid composition")}     decantr add/remove, decantr theme switch, decantr registry, decantr upgrade
 
 ${BOLD6}Bootstrap adapters:${RESET13}
-  Current runnable starter adapter: ${cyan3("react-vite")}
-  Other contract targets stay framework-agnostic, but currently initialize in contract-only mode until their starter adapters land.
+  Runnable starter adapters: ${cyan3("react-vite")}, ${cyan3("next-app")}
+  Unsupported targets resolve through ${cyan3("generic-web")} contract-only mode until their starter adapters land.
 `);
 }
 async function main() {
@@ -5922,14 +6578,14 @@ async function main() {
   }
   if (command === "--version" || command === "-v" || command === "version") {
     try {
-      const here = dirname2(fileURLToPath2(import.meta.url));
+      const here = dirname4(fileURLToPath2(import.meta.url));
       const candidates = [
-        join26(here, "..", "package.json"),
-        join26(here, "..", "..", "package.json")
+        join28(here, "..", "package.json"),
+        join28(here, "..", "..", "package.json")
       ];
       for (const candidate of candidates) {
-        if (existsSync25(candidate)) {
-          const pkg = JSON.parse(readFileSync18(candidate, "utf-8"));
+        if (existsSync27(candidate)) {
+          const pkg = JSON.parse(readFileSync20(candidate, "utf-8"));
           if (pkg.version) {
             console.log(pkg.version);
             return;
@@ -5976,7 +6632,10 @@ async function main() {
         shape: newOpts.shape,
         target: newOpts.target,
         offline: newOpts.offline === true,
-        registry: newOpts.registry
+        registry: newOpts.registry,
+        workflow: newOpts.workflow,
+        adoption: newOpts.adoption,
+        assistantBridge: newOpts["assistant-bridge"]
       });
       break;
     }
@@ -6015,7 +6674,7 @@ async function main() {
       break;
     }
     case "upgrade": {
-      const { cmdUpgrade } = await import("./upgrade-7LHT3S7E.js");
+      const { cmdUpgrade } = await import("./upgrade-KG42WK5C.js");
       const applyFlag = args.includes("--apply");
       await cmdUpgrade(process.cwd(), { apply: applyFlag });
       break;
@@ -6407,7 +7066,47 @@ async function main() {
       break;
     }
     case "analyze": {
-      cmdAnalyze(process.cwd());
+      let projectArg;
+      for (let i = 1; i < args.length; i++) {
+        if (args[i].startsWith("--project=")) {
+          projectArg = args[i].split("=")[1];
+        } else if (args[i] === "--project" && args[i + 1]) {
+          projectArg = args[++i];
+        }
+      }
+      const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
+      if (workspaceInfo.requiresProjectSelection) {
+        console.log(error3("This looks like a workspace root with multiple app candidates."));
+        console.log(dim3(`Use --project=<path>. Candidates: ${workspaceInfo.appCandidates.join(", ")}`));
+        process.exitCode = 1;
+        break;
+      }
+      cmdAnalyze(workspaceInfo.appRoot, workspaceInfo);
+      break;
+    }
+    case "rules": {
+      const subcommand = args[1];
+      if (subcommand !== "apply") {
+        console.error(error3("Usage: decantr rules apply [--project=<path>]"));
+        process.exitCode = 1;
+        break;
+      }
+      let projectArg;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i].startsWith("--project=")) {
+          projectArg = args[i].split("=")[1];
+        } else if (args[i] === "--project" && args[i + 1]) {
+          projectArg = args[++i];
+        }
+      }
+      const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
+      const detected = detectProject(workspaceInfo.appRoot);
+      const updated = applyAssistantBridge(workspaceInfo.appRoot, detected);
+      if (updated.length === 0) {
+        console.log(dim3("Assistant bridge rule files are already up to date."));
+      } else {
+        console.log(success3(`Applied Decantr assistant bridge to ${updated.join(", ")}.`));
+      }
       break;
     }
     case "magic": {