@decantr/cli 1.7.24 → 1.7.25

package/README.md

@@ -17,19 +17,42 @@ Or run it without installing:
 npx @decantr/cli new my-app --blueprint=agent-marketplace
 ```
 
-Use `decantr new` for a greenfield workspace in a fresh directory.
+Use `decantr new` for a greenfield workspace in a fresh directory. With a blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr analyze` first when you already have an app and want Decantr governance without adopting a blueprint.
 Use `decantr init` to attach Decantr contract/context files to an existing project or to create a contract-only workspace.
 
 Current starter adapter availability:
 
 - `react-vite` is the runnable bootstrap adapter in this wave
-- other contract targets remain valid Decantr targets, but `decantr new` will keep them in contract-only mode until their adapters land
+- `next-app` is the runnable Next.js App Router adapter
+- other contract targets use the `generic-web` contract-only adapter until their runnable adapters land
+
+Explicit workflow/adoption flags:
+
+```bash
+decantr init --workflow=greenfield --adoption=contract-only
+decantr init --existing --adoption=contract-only
+decantr init --existing --adoption=style-bridge
+decantr init --existing --adoption=decantr-css
+decantr init --project=apps/web --yes
+decantr init --assistant-bridge=preview
+decantr rules apply
+```
+
+Adoption modes:
+
+- `contract-only` writes Decantr essence/context/governance files without Decantr CSS files or `@decantr/css` dependency guidance.
+- `style-bridge` writes bridge tokens/files that map Decantr intent onto an existing style system without requiring `@decantr/css`.
+- `decantr-css` writes the full Decantr CSS files and runtime guidance.
+
+Monorepos store both `workspaceRoot` and `appRoot`. In non-interactive workspace-root runs with multiple app candidates, pass `--project=<path>` so Decantr attaches to the intended app.
+
+Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, while `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks.
 
 ## What It Does
 
 - scaffolds Decantr projects from blueprints, archetypes, or prompts
-- supports three workflow lanes: greenfield blueprint, brownfield adoption, and hybrid composition
+- supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
 - searches the registry and showcase benchmark corpus
@@ -40,8 +63,10 @@ Current starter adapter availability:
 ```bash
 decantr new my-app --blueprint=agent-marketplace
 decantr analyze
-decantr init --existing --yes
+decantr init --existing --yes --adoption=contract-only
 decantr init --existing --blueprint=agent-marketplace
+decantr init --workflow=greenfield --adoption=contract-only
+decantr rules apply
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check
@@ -89,7 +114,14 @@ pnpm --filter @decantr/cli certify:workflows
 It covers:
 
 - greenfield blueprint bootstrap
+- greenfield contract-only
 - brownfield `analyze -> init --existing`
+- direct brownfield init
+- adoption modes (`contract-only`, `style-bridge`, `decantr-css`)
+- offline contract-only and offline blueprint flows
+- unsupported target contract-only fallback
+- monorepo `--project` handling
+- Next.js App Router adapter
 - hybrid follow-up composition via Decantr mutation commands
 
 ## Generated Context

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-7H3PAC5Y.js";
-import "./chunk-RH6IQ7YX.js";
+import "./chunk-7FXMRAC3.js";
+import "./chunk-3K6HWLD5.js";
 import "./chunk-QRQCPD3C.js";

package/dist/{chunk-RH6IQ7YX.js → chunk-3K6HWLD5.js}

@@ -40,6 +40,9 @@ var RegistryClient = class {
   getApiUrl() {
     return this.apiUrl;
   }
+  isOffline() {
+    return this.offline;
+  }
   /**
    * Load content from .decantr/custom/{contentType}/{id}.json
    * Works for ALL content types, not just themes.
@@ -587,6 +590,16 @@ ${themeBody}
     ["font-variant-numeric", "tabular-nums"],
     ["transition", "background 0.15s ease, border-color 0.15s ease, color 0.15s ease"]
   ]);
+  emitRule('.d-step-chip[data-shape="pill"]', [
+    ["width", "auto"],
+    ["min-width", "2rem"],
+    ["height", "auto"],
+    ["min-height", "2rem"],
+    ["padding", "0.375rem 0.875rem"],
+    ["border-radius", "9999px"],
+    ["gap", "0.375rem"],
+    ["font-variant-numeric", "normal"]
+  ]);
   emitRule('.d-step-chip[data-step-state="active"]', [
     ["background", "var(--d-primary)"],
     ["border-color", "var(--d-primary)"],
@@ -1319,6 +1332,8 @@ ${themeBody}
   emitRule('.d-modal-panel[data-size="sm"]', [["max-width", "24rem"]]);
   emitRule('.d-modal-panel[data-size="lg"]', [["max-width", "48rem"]]);
   emitRule(".d-palette", [
+    ["position", "relative"],
+    ["z-index", "1"],
     ["width", "100%"],
     ["max-width", "40rem"],
     ["margin-inline", "auto"],
@@ -1331,34 +1346,73 @@ ${themeBody}
     ["overflow", "hidden"],
     ["max-height", "60vh"]
   ]);
+  emitRule(".d-palette-search", [
+    ["display", "flex"],
+    ["align-items", "center"],
+    ["gap", "0.75rem"],
+    ["padding", "0.85rem 1rem"],
+    ["border-bottom", "1px solid var(--d-border)"],
+    ["background", "color-mix(in srgb, var(--d-surface) 82%, transparent)"],
+    ["color", "var(--d-text-muted)"],
+    ["transition", "background var(--d-motion-fast, 150ms) ease, box-shadow var(--d-motion-fast, 150ms) ease, color var(--d-motion-fast, 150ms) ease"]
+  ]);
+  emitRule(".d-palette-search:focus-within", [
+    ["background", "var(--d-surface)"],
+    ["color", "var(--d-text)"],
+    ["box-shadow", "inset 0 -2px 0 var(--d-primary)"]
+  ]);
   emitRule(".d-palette-input", [
-    ["padding", "1rem 1.25rem"],
+    ["flex", "1"],
+    ["min-width", "0"],
+    ["padding", "0.6rem 0"],
     ["border", "0"],
-    ["border-bottom", "1px solid var(--d-border)"],
     ["background", "transparent"],
     ["color", "var(--d-text)"],
-    ["font-size", "1rem"],
+    ["font-size", "1.05rem"],
+    ["line-height", "1.4"],
     ["outline", "0"],
     ["width", "100%"]
   ]);
+  emitRule(".d-palette-input:focus-visible", [
+    ["outline", "0"],
+    ["box-shadow", "none"]
+  ]);
+  emitRule(".d-palette-input::placeholder", [["color", "var(--d-text-muted)"]]);
   emitRule(".d-palette-list", [
     ["flex", "1"],
     ["overflow-y", "auto"],
-    ["padding", "0.5rem"]
+    ["padding", "0.5rem"],
+    ["display", "grid"],
+    ["gap", "0.25rem"]
   ]);
   emitRule(".d-palette-row", [
     ["display", "flex"],
     ["align-items", "center"],
     ["gap", "0.75rem"],
-    ["padding", "0.5rem 0.75rem"],
-    ["border-radius", "var(--d-radius-sm)"],
+    ["width", "100%"],
+    ["min-height", "3rem"],
+    ["padding", "0.7rem 0.75rem"],
+    ["border", "0"],
+    ["border-radius", "var(--d-radius)"],
+    ["background", "transparent"],
     ["cursor", "pointer"],
     ["color", "var(--d-text)"],
-    ["font-size", "0.875rem"],
-    ["transition", "background 0.1s ease"]
+    ["font", "inherit"],
+    ["font-size", "0.92rem"],
+    ["text-align", "left"],
+    ["box-shadow", "inset 0 0 0 1px transparent"],
+    ["transition", "background 0.12s ease, box-shadow 0.12s ease, color 0.12s ease"]
   ]);
   emitRule('.d-palette-row:hover, .d-palette-row[data-active="true"]', [
-    ["background", "color-mix(in srgb, var(--d-primary) 10%, transparent)"]
+    ["background", "color-mix(in srgb, var(--d-primary) 10%, transparent)"],
+    ["box-shadow", "inset 0 0 0 1px color-mix(in srgb, var(--d-primary) 24%, transparent)"]
+  ]);
+  emitRule(".d-palette-row svg", [
+    ["flex", "0 0 auto"],
+    ["color", "var(--d-text-muted)"]
+  ]);
+  emitRule('.d-palette-row:hover svg, .d-palette-row[data-active="true"] svg', [
+    ["color", "var(--d-primary)"]
   ]);
   emitRule(".d-palette-section", [
     ["padding", "0.5rem 0.75rem 0.25rem"],
@@ -2308,7 +2362,17 @@ function generateTopologySection(data, personality) {
   lines.push("");
   return lines.join("\n");
 }
-var CLI_VERSION = "1.0.0";
+function readCliVersion() {
+  for (const candidate of [join2(__dirname, "..", "package.json"), join2(__dirname, "..", "..", "package.json")]) {
+    try {
+      const pkg = JSON.parse(readFileSync2(candidate, "utf-8"));
+      if (pkg.version) return pkg.version;
+    } catch {
+    }
+  }
+  return "0.0.0";
+}
+var CLI_VERSION = readCliVersion();
 function mapRegistryThemeToThemeData(theme) {
   return {
     seed: theme.seed,
@@ -2342,7 +2406,16 @@ function generateTokensCSS(themeData, mode, spatialTokens, options) {
   --d-surface-raised: #27272a;
   --d-border: #3f3f46;
   --d-text: #fafafa;
-  --d-text-muted: #a1a1aa;${spatialLines2}
+  --d-text-muted: #a1a1aa;
+  --d-fg: var(--d-text);
+  --d-foreground: var(--d-text);
+  --d-fg-muted: var(--d-text-muted);
+  --d-background: var(--d-bg);
+  --d-muted: var(--d-surface-raised);
+  --d-bg-surface: var(--d-surface);
+  --d-bg-muted: var(--d-surface-raised);
+  --d-border-subtle: var(--d-border);
+  --d-border-muted: var(--d-border);${spatialLines2}
 }
 }
 `;
@@ -2378,6 +2451,18 @@ function generateTokensCSS(themeData, mode, spatialTokens, options) {
       "--d-border": palette.border?.[tokenMode] || pickFb("border"),
       "--d-text": palette.text?.[tokenMode] || pickFb("text"),
       "--d-text-muted": palette["text-muted"]?.[tokenMode] || pickFb("text-muted"),
+      // Compatibility aliases for older registry decorator and pattern copy.
+      // Keep these as var() aliases so theme toggles automatically follow the
+      // active canonical token values without needing duplicate mode blocks.
+      "--d-fg": "var(--d-text)",
+      "--d-foreground": "var(--d-text)",
+      "--d-fg-muted": "var(--d-text-muted)",
+      "--d-background": "var(--d-bg)",
+      "--d-muted": "var(--d-surface-raised)",
+      "--d-bg-surface": "var(--d-surface)",
+      "--d-bg-muted": "var(--d-surface-raised)",
+      "--d-border-subtle": "var(--d-border)",
+      "--d-border-muted": "var(--d-border)",
       "--d-primary-hover": palette["primary-hover"]?.[tokenMode] || seed.primary || "#6366f1",
       // Spacing scale
       "--d-gap-1": "0.25rem",
@@ -2412,6 +2497,8 @@ function generateTokensCSS(themeData, mode, spatialTokens, options) {
       "--d-error": themeData.tokens?.base?.danger || "#ef4444",
       "--d-warning": themeData.tokens?.base?.warning || "#f59e0b",
       "--d-info": "#3b82f6",
+      "--d-danger": "var(--d-error)",
+      "--d-destructive": "var(--d-error)",
       // Motion scale (v2.1 Tier B1). Canonical durations + easings.
       // d-enter-fade, d-pulse, d-glow-hover, etc. all read these.
       // Themes can override via theme.motion.* and this picks them up
@@ -3070,6 +3157,7 @@ Do NOT branch component code on the current mode via JS to re-style elements \u2
 | **Modal backdrop** | \`d-modal-backdrop\` | Scrim with backdrop-blur. Place as a sibling inside \`d-modal\` with \`onClick\` to close. |
 | **Modal panel** | \`d-modal-panel\` | The actual dialog content. \`data-size="sm\\|lg"\` adjusts max-width (default 32rem). |
 | **Command palette** | \`d-palette\` | Specialized modal-panel variant for command palettes \u2014 40rem wide, 60vh max-height. |
+| **Palette search row** | \`d-palette-search\` | Icon + search input row at the top of a palette. Use this wrapper so focus styling belongs to the palette, not the raw input. |
 | **Palette input** | \`d-palette-input\` | Search input at top of palette. |
 | **Palette list** | \`d-palette-list\` | Scrollable command list. |
 | **Palette row** | \`d-palette-row\` | Individual command row. \`data-active="true"\` for keyboard-highlighted row. |
@@ -3083,7 +3171,10 @@ Composition pattern for a command palette (REQUIRED \u2014 palette MUST be wrapp
   <div className="d-modal" data-align="top">
     <div className="d-modal-backdrop" onClick={close} />
     <div className="d-palette">
-      <input className="d-palette-input" placeholder="Type a command..." />
+      <div className="d-palette-search">
+        <Search />
+        <input className="d-palette-input" placeholder="Type a command..." />
+      </div>
       <ul className="d-palette-list">
         <li className="d-palette-section">Navigation</li>
         <li className="d-palette-row" data-active={i === selectedIndex}>
@@ -3565,19 +3656,48 @@ Dark themes emit stronger alpha values automatically.
 | \`shimmer-skeleton\` | \`d-shimmer\` on skeleton placeholders during loading |
 | \`zoom-pinch\` | Touch handlers (\`touchstart\`/\`touchmove\`) tracking pinch distance, OR \`gestureend\` on Safari; same scale transform as \`zoom-scroll\` |
 | \`ripple-click\` | \`d-ripple\` on the interactive surface |`;
+var CONTRACT_ONLY_CSS_APPROACH = `## Styling Adoption
+
+This project uses Decantr as a **contract and governance layer only**.
+
+Do not install \`@decantr/css\`, rewrite the styling system, or add generated Decantr CSS files unless the task explicitly changes the adoption mode. Preserve the existing framework styling conventions and map them into the Decantr context before changing implementation files.
+
+Use \`.decantr/context/scaffold-pack.md\` and the matching section/page packs to understand visual intent, shell structure, and route contracts. Implement those contracts through the project's current CSS, component library, tokens, or design-system primitives.`;
+var STYLE_BRIDGE_CSS_APPROACH = `## Styling Adoption
+
+This project uses Decantr in **style-bridge** mode.
+
+Decantr may generate lightweight bridge files such as \`src/styles/tokens.css\` and \`src/styles/decantr-bridge.css\`, but \`@decantr/css\` is not required. Treat these files as a mapping layer between Decantr context and the app's existing styling system.
+
+Preserve the current CSS framework/component library. Use Decantr tokens and bridge classes only where they clarify design intent without replacing the app's established styling conventions.`;
+function getCssApproachContent(adoptionMode) {
+  if (adoptionMode === "contract-only") return CONTRACT_ONLY_CSS_APPROACH;
+  if (adoptionMode === "style-bridge") return STYLE_BRIDGE_CSS_APPROACH;
+  return CSS_APPROACH_CONTENT;
+}
 function generateDecantrMdV31(params) {
   const template = loadTemplate("DECANTR.md.template");
   const body = renderTemplate(template, {
     GUARD_MODE: params.guardMode,
     CSS_APPROACH: params.cssApproach,
-    WORKFLOW_MODE: params.workflowMode === "brownfield-attach" ? "brownfield attach" : "greenfield scaffold",
-    WORKFLOW_GUIDANCE: params.workflowMode === "brownfield-attach" ? `This project is using Decantr in **brownfield attach** mode.
+    WORKFLOW_MODE: params.workflowMode === "brownfield-attach" ? "brownfield attach" : params.workflowMode === "greenfield-contract-only" ? "greenfield contract-only" : params.workflowMode === "hybrid-compose" ? "hybrid composition" : "greenfield scaffold",
+    WORKFLOW_GUIDANCE: params.workflowMode === "brownfield-attach" ? params.analysisArtifacts ? `This project is using Decantr in **brownfield attach** mode with **${params.adoptionMode || "contract-only"}** adoption.
 
 Read \`.decantr/analysis.json\` first for the detected framework, routes, styling, layout, and dependency facts.
 Then read \`.decantr/init-seed.json\` for the recommended attach defaults.
 Then read \`.decantr/context/scaffold-pack.md\` and \`.decantr/context/scaffold.md\` to understand the Decantr contract you are layering onto the existing app.
 
-Preserve the current framework, package manager, router, and working runtime structure unless the contract gives you a reviewed reason to change them. Map existing routes and components onto the declared Decantr sections/pages before creating new files. Registry content is optional in this workflow unless the task explicitly asks for it.` : `This project is using Decantr in **greenfield scaffold** mode.
+Preserve the current framework, package manager, router, and working runtime structure unless the contract gives you a reviewed reason to change them. Map existing routes and components onto the declared Decantr sections/pages before creating new files. Registry content is optional in this workflow unless the task explicitly asks for it.` : `This project is using Decantr in **brownfield attach** mode with **${params.adoptionMode || "contract-only"}** adoption.
+
+No \`.decantr/analysis.json\` or \`.decantr/init-seed.json\` was present when this context was generated. Inventory the current framework, routes, styling, layout, package manager, and rule files before changing runtime code. Then read \`.decantr/context/scaffold-pack.md\` and \`.decantr/context/scaffold.md\` to understand the Decantr contract you are layering onto the existing app.
+
+Preserve the current framework, package manager, router, and working runtime structure unless the contract gives you a reviewed reason to change them. Registry content is optional in this workflow unless the task explicitly asks for it.` : params.workflowMode === "greenfield-contract-only" ? `This project is using Decantr in **greenfield contract-only** mode with **${params.adoptionMode || "contract-only"}** adoption.
+
+Treat the compiled execution-pack files as the primary source of truth for the app contract, but do not assume Decantr owns the runtime or styling system. Use narrative docs only as secondary explanation when the compiled packs are not enough.
+Use only files present in this workspace as the source of truth. If local scaffold files disagree, stop and report the mismatch instead of relying on external Decantr assumptions or prior examples.
+
+Read \`.decantr/context/scaffold-pack.md\` first for the compact compiled shell, theme, feature, and route contract.
+Then read \`.decantr/context/scaffold.md\` for the fuller app overview, topology, route map, and voice guidance.` : `This project is using Decantr in **greenfield scaffold** mode with **${params.adoptionMode || "decantr-css"}** adoption.
 
 Treat the compiled execution-pack files as the primary source of truth.
 Use narrative docs only as secondary explanation when the compiled packs are not enough.
@@ -3594,8 +3714,9 @@ Start implementation from the shell layouts and shared route structure before fi
   const themeDesc = `${params.themeName || "default"} (${params.themeMode || "dark"} mode${params.themeShape ? `, ${params.themeShape} shape` : ""})`;
   briefLines.push(`- **Theme:** ${themeDesc}`);
   briefLines.push(
-    `- **Workflow:** ${params.workflowMode === "brownfield-attach" ? "brownfield attach" : "greenfield scaffold"}`
+    `- **Workflow:** ${params.workflowMode || "greenfield-scaffold"}`
   );
+  briefLines.push(`- **Adoption mode:** ${params.adoptionMode || "decantr-css"}`);
   if (params.personality && params.personality.length > 0) {
     briefLines.push(`- **Personality:** ${params.personality.join(". ")}`);
   }
@@ -3683,7 +3804,9 @@ function generateProjectJson(detected, options, registrySource) {
       packageManager: detected.packageManager,
       hasTypeScript: detected.hasTypeScript,
       hasTailwind: detected.hasTailwind,
-      existingRuleFiles: detected.existingRuleFiles
+      existingRuleFiles: detected.existingRuleFiles,
+      workspaceRoot: options.workspaceRoot || detected.projectRoot,
+      appRoot: options.appRoot || detected.projectRoot
     },
     overrides: {
       framework: options.target !== detected.framework ? options.target : null
@@ -3703,7 +3826,13 @@ function generateProjectJson(detected, options, registrySource) {
       via: "cli",
       version: CLI_VERSION,
       flags: buildFlagsString(options),
-      workflowMode: options.workflowMode || "greenfield-scaffold"
+      workflowMode: options.workflowMode || "greenfield-scaffold",
+      adoptionMode: options.adoptionMode || "decantr-css",
+      contentSource: options.contentSource || "none",
+      assistantBridge: options.assistantBridge || "none",
+      projectScope: options.projectScope || "single-app",
+      adapterId: options.adapterId || null,
+      analysisArtifacts: Boolean(options.analysisArtifacts)
     }
   };
   if (options.blueprint) {
@@ -3717,6 +3846,12 @@ function buildFlagsString(options) {
   if (options.theme) flags.push(`--theme=${options.theme}`);
   if (options.mode) flags.push(`--mode=${options.mode}`);
   if (options.guard) flags.push(`--guard=${options.guard}`);
+  if (options.workflowMode) flags.push(`--workflow=${options.workflowMode}`);
+  if (options.adoptionMode) flags.push(`--adoption=${options.adoptionMode}`);
+  if (options.assistantBridge) flags.push(`--assistant-bridge=${options.assistantBridge}`);
+  if (options.appRoot && options.workspaceRoot && options.appRoot !== options.workspaceRoot) {
+    flags.push(`--project=${options.appRoot}`);
+  }
   return flags.join(" ");
 }
 function generateTaskContextV3(templateName, essence) {
@@ -3775,7 +3910,8 @@ function generateScaffoldTaskContext(essence, scaffoldPack, manifest) {
   const features = scaffoldPack.data.features.length > 0 ? scaffoldPack.data.features.join(", ") : "none";
   const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
     const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
-    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+    const pageLabel = route.sectionId ? `${route.sectionId}/${route.pageId}` : route.pageId;
+    return `- \`${route.path}\` -> \`${pageLabel}\` [${patternSummary}]`;
   }).join("\n") : "- No routes declared";
   const successChecks = scaffoldPack.successChecks.map((check) => `- [${check.severity}] ${check.label}`).join("\n");
   const tokenStrategy = scaffoldPack.tokenBudget.strategy.map((item) => `- ${item}`).join("\n");
@@ -3831,7 +3967,8 @@ function generateAddPageTaskContext(essence, scaffoldPack, manifest) {
   }
   const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
     const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
-    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+    const pageLabel = route.sectionId ? `${route.sectionId}/${route.pageId}` : route.pageId;
+    return `- \`${route.path}\` -> \`${pageLabel}\` [${patternSummary}]`;
   }).join("\n") : "- No routes declared";
   const sectionRefs = manifest?.sections.map(
     (section) => `Section \`${section.id}\` -> \`.decantr/context/${section.markdown}\``
@@ -3887,7 +4024,8 @@ function generateModifyTaskContext(essence, scaffoldPack, manifest) {
   }
   const routePlan = scaffoldPack.data.routes.length > 0 ? scaffoldPack.data.routes.map((route) => {
     const patternSummary = route.patternIds.length > 0 ? route.patternIds.join(", ") : "none";
-    return `- \`${route.path}\` -> \`${route.pageId}\` [${patternSummary}]`;
+    const pageLabel = route.sectionId ? `${route.sectionId}/${route.pageId}` : route.pageId;
+    return `- \`${route.path}\` -> \`${pageLabel}\` [${patternSummary}]`;
   }).join("\n") : "- No routes declared";
   const pageRefs = manifest?.pages.map((page) => `Page \`${page.id}\` -> \`.decantr/context/${page.markdown}\``) ?? [];
   const successChecks = scaffoldPack.successChecks.map((check) => `- [${check.severity}] ${check.label}`).join("\n");
@@ -4033,7 +4171,10 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
   }
   const refreshResult = await refreshDerivedFiles(projectRoot, essenceV3, registry, themeData, {
     isInitialScaffold: true,
-    patternSpecs
+    patternSpecs,
+    workflowMode: options.workflowMode,
+    adoptionMode: options.adoptionMode,
+    analysisArtifacts: options.analysisArtifacts
   });
   contextFiles.push(...refreshResult.contextFiles);
   const gitignoreUpdated = updateGitignore(projectRoot);
@@ -4046,7 +4187,7 @@ async function scaffoldProject(projectRoot, options, detected, registry, archety
     gitignoreUpdated
   };
 }
-function scaffoldMinimal(projectRoot) {
+function scaffoldMinimal(projectRoot, options = {}) {
   const decantrDir = join2(projectRoot, ".decantr");
   const customDir = join2(decantrDir, "custom");
   const contentTypes = API_CONTENT_TYPES2;
@@ -4143,7 +4284,12 @@ function scaffoldMinimal(projectRoot) {
       via: "cli",
       version: CLI_VERSION,
       flags: "--offline --minimal",
-      workflowMode: "greenfield-scaffold"
+      workflowMode: options.workflowMode || "greenfield-contract-only",
+      adoptionMode: options.adoptionMode || "contract-only",
+      contentSource: options.contentSource || "none",
+      assistantBridge: options.assistantBridge || "none",
+      projectScope: "single-app",
+      analysisArtifacts: false
     }
   };
   const projectJsonPath = join2(decantrDir, "project.json");
@@ -4257,9 +4403,11 @@ function writeExecutionPackBundleArtifacts(contextDir, bundle) {
     );
     outputPaths.push(sectionPackPath);
   }
-  for (const pagePack of bundle.pages) {
+  for (const [index, pagePack] of bundle.pages.entries()) {
+    const manifestPage = bundle.manifest.pages[index];
+    const pageBaseName = manifestPage?.markdown?.endsWith(".md") ? manifestPage.markdown.slice(0, -".md".length) : `page-${pagePack.data.pageId}-pack`;
     const pagePackPath = writeExecutionPackArtifacts(
-      join2(contextDir, `page-${pagePack.data.pageId}-pack`),
+      join2(contextDir, pageBaseName),
       pagePack
     );
     outputPaths.push(pagePackPath);
@@ -4369,6 +4517,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   let storedBlueprintId;
   let storedVoice;
   let storedWorkflowMode;
+  let storedAdoptionMode;
+  let storedAnalysisArtifacts = false;
   const projectJsonFilePath = join2(decantrDir, "project.json");
   let projectJsonData = {};
   if (existsSync2(projectJsonFilePath)) {
@@ -4378,9 +4528,16 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       if (projectJsonData.voice) storedVoice = projectJsonData.voice;
       if (projectJsonData.initialized?.workflowMode)
         storedWorkflowMode = projectJsonData.initialized.workflowMode;
+      if (projectJsonData.initialized?.adoptionMode)
+        storedAdoptionMode = projectJsonData.initialized.adoptionMode;
+      if (projectJsonData.initialized?.analysisArtifacts)
+        storedAnalysisArtifacts = projectJsonData.initialized.analysisArtifacts;
     } catch {
     }
   }
+  const effectiveWorkflowMode = options?.workflowMode || storedWorkflowMode || "greenfield-scaffold";
+  const effectiveAdoptionMode = options?.adoptionMode || storedAdoptionMode || "decantr-css";
+  const effectiveAnalysisArtifacts = options?.analysisArtifacts ?? storedAnalysisArtifacts ?? false;
   if (!storedVoice && storedBlueprintId) {
     try {
       const bpResult = await registry.fetchBlueprint(storedBlueprintId);
@@ -4404,7 +4561,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   };
   const personality = essence.dna.personality || [];
   let themeData = prefetchedThemeData;
-  if (!themeData)
+  const shouldResolveThemeData = effectiveAdoptionMode !== "contract-only" || Boolean(themeData);
+  if (!themeData && shouldResolveThemeData)
     try {
       const themeResult = await registry.fetchTheme(themeName);
       if (themeResult?.data) {
@@ -4412,7 +4570,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       }
     } catch {
     }
-  if (!themeData?.seed?.primary) {
+  const registryIsOffline = typeof registry.isOffline === "function" ? registry.isOffline() : false;
+  if (shouldResolveThemeData && !themeData?.seed?.primary && !registryIsOffline) {
     try {
       const apiUrl = registry.getApiUrl();
       const resp = await fetch(`${apiUrl}/themes/@official/${themeName}`);
@@ -4442,7 +4601,10 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     }
   }
   const stylesDir = join2(projectRoot, "src", "styles");
-  mkdirSync2(stylesDir, { recursive: true });
+  const shouldWriteCss = effectiveAdoptionMode !== "contract-only";
+  if (shouldWriteCss) {
+    mkdirSync2(stylesDir, { recursive: true });
+  }
   const densityLevel = essence.dna?.spacing?.density || "comfortable";
   const spatialTokens = computeSpatialTokens(
     densityLevel,
@@ -4453,8 +4615,9 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     } : void 0
   );
   const tokensPath = join2(stylesDir, "tokens.css");
+  const bridgePath = join2(stylesDir, "decantr-bridge.css");
   const hasRealThemeData = themeData?.seed?.primary || themeData?.palette?.background;
-  if (hasRealThemeData || !existsSync2(tokensPath)) {
+  if (shouldWriteCss && (hasRealThemeData || !existsSync2(tokensPath))) {
     if (themeData?.palette && mode && mode !== "auto") {
       const paletteEntries = Object.values(themeData.palette);
       const modeDefined = paletteEntries.some(
@@ -4489,27 +4652,36 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     }
     const features = essence.blueprint?.features ?? [];
     const hasThemeToggle = features.includes("theme-toggle") || features.includes("theme_toggle");
+    writeFileSync2(tokensPath, generateTokensCSS(themeData, mode, spatialTokens, { hasThemeToggle }));
+  }
+  const treatmentsPath = join2(stylesDir, "treatments.css");
+  if (effectiveAdoptionMode === "decantr-css") {
+    let treatmentCSS = generateTreatmentCSS(
+      spatialTokens,
+      themeData?.treatments,
+      themeData?.decorators,
+      themeName,
+      themeData?.decorator_definitions
+    );
+    const personalityCSS = generatePersonalityCSS(personality || [], themeData || {});
+    treatmentCSS += personalityCSS;
+    writeFileSync2(treatmentsPath, treatmentCSS);
+  } else if (effectiveAdoptionMode === "style-bridge") {
     writeFileSync2(
-      tokensPath,
-      generateTokensCSS(themeData, mode, spatialTokens, { hasThemeToggle })
+      bridgePath,
+      `/* Decantr style bridge: map these CSS variables into the existing design system. */
+:root {
+  --decantr-bridge-theme: ${themeName};
+  --decantr-bridge-density: ${densityLevel};
+}
+`
     );
   }
-  const treatmentsPath = join2(stylesDir, "treatments.css");
-  let treatmentCSS = generateTreatmentCSS(
-    spatialTokens,
-    themeData?.treatments,
-    themeData?.decorators,
-    themeName,
-    themeData?.decorator_definitions
-  );
-  const personalityCSS = generatePersonalityCSS(personality || [], themeData || {});
-  treatmentCSS += personalityCSS;
-  writeFileSync2(treatmentsPath, treatmentCSS);
   const globalPath = join2(stylesDir, "global.css");
-  if (!existsSync2(globalPath)) {
+  if (shouldWriteCss && !existsSync2(globalPath)) {
     writeFileSync2(globalPath, generateGlobalCSS(personality, essence));
   }
-  const cssFiles = [tokensPath, treatmentsPath, globalPath];
+  const cssFiles = effectiveAdoptionMode === "contract-only" ? [] : effectiveAdoptionMode === "style-bridge" ? [tokensPath, bridgePath, globalPath] : [tokensPath, treatmentsPath, globalPath];
   const earlyDecoratorList = [];
   if (themeData?.decorators) {
     for (const [name, desc] of Object.entries(themeData.decorators)) {
@@ -4538,8 +4710,10 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     decantrMdPath,
     generateDecantrMdV31({
       guardMode,
-      cssApproach: CSS_APPROACH_CONTENT,
-      workflowMode: storedWorkflowMode,
+      cssApproach: getCssApproachContent(effectiveAdoptionMode),
+      workflowMode: effectiveWorkflowMode,
+      adoptionMode: effectiveAdoptionMode,
+      analysisArtifacts: effectiveAnalysisArtifacts,
       blueprintId: storedBlueprintId || getLegacyBlueprintId(essence.meta) || void 0,
       themeName,
       themeMode: mode,