@decantr/cli 1.7.6 → 1.7.8

package/README.md

@@ -14,12 +14,22 @@ npm install -D @decantr/cli
 Or run it without installing:
 
 ```bash
-npx @decantr/cli init --blueprint=agent-marketplace --yes
+npx @decantr/cli new my-app --blueprint=agent-marketplace
 ```
 
+Use `decantr new` for a greenfield workspace in a fresh directory.
+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
+
 ## What It Does
 
 - scaffolds Decantr projects from blueprints, archetypes, or prompts
+- supports three workflow lanes: greenfield blueprint, 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
@@ -28,7 +38,10 @@ npx @decantr/cli init --blueprint=agent-marketplace --yes
 ## Common Commands
 
 ```bash
-decantr init --blueprint=agent-marketplace
+decantr new my-app --blueprint=agent-marketplace
+decantr analyze
+decantr init --existing --yes
+decantr init --existing --blueprint=agent-marketplace
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check
@@ -36,14 +49,49 @@ decantr registry summary --namespace @official --json
 decantr showcase verification --json
 ```
 
+## Greenfield Certification
+
+Use the built-in certification harness before releases when you want to prove that representative blueprints still scaffold into runnable starter projects:
+
+```bash
+pnpm --filter @decantr/cli certify:blueprints
+```
+
+By default it certifies `portfolio`, `producer-studio`, and `agent-marketplace` by:
+
+- running `decantr new` in fresh temp directories
+- seeding offline content from `DECANTR_CONTENT_DIR` or a sibling `decantr-content` checkout
+- verifying the starter runtime files and router mode match the generated essence
+- running `npm run build` in each scaffolded project
+
+Override the matrix or emit JSON when needed:
+
+```bash
+pnpm --filter @decantr/cli certify:blueprints -- --blueprints=portfolio,legal-research --json
+```
+
 Offline blueprint scaffolding expects a real local content source:
 
 ```bash
-DECANTR_CONTENT_DIR=/path/to/decantr-content decantr init --blueprint=agent-marketplace --offline --yes
+DECANTR_CONTENT_DIR=/path/to/decantr-content decantr new my-app --blueprint=agent-marketplace --offline
 ```
 
 If a requested offline blueprint, archetype, or theme cannot be resolved from local cache/custom content or `DECANTR_CONTENT_DIR`, the CLI now stops explicitly instead of silently falling back to the default scaffold.
 
+## Workflow Certification
+
+The broader workflow matrix now has its own certification entrypoint:
+
+```bash
+pnpm --filter @decantr/cli certify:workflows
+```
+
+It covers:
+
+- greenfield blueprint bootstrap
+- brownfield `analyze -> init --existing`
+- hybrid follow-up composition via Decantr mutation commands
+
 ## Generated Context
 
 Scaffolded projects include compiled execution packs under `.decantr/context/`, including:

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-KAEQTVAM.js";
-import "./chunk-H4H3IQJK.js";
+import "./chunk-ODJQZXHQ.js";
+import "./chunk-74G2RQDO.js";
 import "./chunk-KUDAVJOR.js";

package/dist/{chunk-H4H3IQJK.js → chunk-74G2RQDO.js}

@@ -6,8 +6,9 @@ import { computeSpatialTokens } from "@decantr/essence-spec";
 import { compileExecutionPackBundle } from "@decantr/core";
 
 // src/treatments.ts
-function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators, themeName) {
+function generateTreatmentCSS(spatialTokens, treatmentOverrides, themeDecorators, themeName, themeDecoratorDefinitions) {
   const lines = [];
+  const decoratorAnimationNames = /* @__PURE__ */ new Set();
   lines.push("/* Generated by @decantr/cli \u2014 Visual Treatment System */");
   lines.push("");
   lines.push("@layer treatments {");
@@ -195,9 +196,9 @@ ${themeBody}
     ["font-size", "0.75rem"],
     ["font-weight", "500"],
     ["padding", "0.125rem 0.5rem"],
-    ["margin-top", "calc(var(--d-annotation-mt) * var(--d-density-scale, 1))"],
     ["border-radius", "var(--d-radius-full)"],
-    ["background", "var(--d-surface)"],
+    ["background", "color-mix(in srgb, var(--d-surface-raised) 88%, transparent)"],
+    ["border", "1px solid color-mix(in srgb, var(--d-border) 72%, transparent)"],
     ["color", "var(--d-text-muted)"],
     ["white-space", "nowrap"]
   ]);
@@ -247,10 +248,47 @@ ${themeBody}
   lines.push("}");
   lines.push("");
   lines.push("} /* end @layer treatments */");
+  const decoratorRules = [];
+  if (themeDecoratorDefinitions) {
+    for (const [className, definition] of Object.entries(themeDecoratorDefinitions)) {
+      const props = definition?.suggested_properties ?? {};
+      const entries = Object.entries(props);
+      if (entries.length === 0) continue;
+      decoratorRules.push(`.${className} {`);
+      for (const [prop, value] of entries) {
+        decoratorRules.push(`  ${prop}: ${value};`);
+        if (prop === "animation") {
+          const animationName = value.split(/\s+/)[0]?.trim();
+          if (animationName) decoratorAnimationNames.add(animationName);
+        }
+      }
+      decoratorRules.push("}");
+      decoratorRules.push("");
+    }
+  }
+  const decoratorKeyframes = [];
+  if (decoratorAnimationNames.has("carbon-fade-slide")) {
+    decoratorKeyframes.push("@keyframes carbon-fade-slide {");
+    decoratorKeyframes.push("  from { opacity: 0; transform: translateY(12px); }");
+    decoratorKeyframes.push("  to { opacity: 1; transform: translateY(0); }");
+    decoratorKeyframes.push("}");
+    decoratorKeyframes.push("");
+  }
+  if (decoratorAnimationNames.has("pulse")) {
+    decoratorKeyframes.push("@keyframes pulse {");
+    decoratorKeyframes.push("  0%, 100% { opacity: 1; }");
+    decoratorKeyframes.push("  50% { opacity: 0.5; }");
+    decoratorKeyframes.push("}");
+    decoratorKeyframes.push("");
+  }
+  const decoratorComments = themeDecorators ? Object.entries(themeDecorators).map(([name, description]) => `  /* .${name}: ${description} */`).join("\n") : "  /* No theme decorators available. */";
+  const decoratorBody = decoratorRules.length > 0 ? `${decoratorRules.join("\n")}${decoratorKeyframes.length > 0 ? `
+${decoratorKeyframes.join("\n")}` : ""}${decoratorComments ? `
+${decoratorComments}` : ""}` : `${decoratorComments}
+  /* Canonical decorator CSS should be derived from theme decorator definitions when available. */`;
   const decoratorBlock = `
 @layer decorators {
-  /* Decorator CSS is AI-generated from structured definitions in section context files. */
-  /* See .decantr/context/section-*.md for intent, suggested properties, and usage guidance. */
+${decoratorBody}
 }
 `;
   lines.push(decoratorBlock);
@@ -598,6 +636,7 @@ function mapRegistryThemeToThemeData(theme) {
     typography: theme.typography,
     motion: theme.motion,
     decorators: theme.decorators,
+    decorator_definitions: theme.decorator_definitions,
     treatments: theme.treatments,
     spatial: theme.spatial,
     radius: theme.radius,
@@ -777,11 +816,15 @@ body {
   transform: translateY(0);
 }
 
-img, picture, video, canvas, svg {
+img, picture, video, canvas {
   display: block;
   max-width: 100%;
 }
 
+svg {
+  max-width: 100%;
+}
+
 input, button, textarea, select {
   font: inherit;
   color: inherit;
@@ -1009,10 +1052,14 @@ import './styles/global.css';                // Resets
 ### Runtime Rules
 
 - Use the real \`@decantr/css\` runtime for atoms. If \`package.json\` does not already depend on \`@decantr/css\`, add it before building.
+- 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.
 - Do **not** create local atom-runtime substitutes such as \`src/lib/css.js\`, \`src/lib/css.ts\`, or hand-written \`src/styles/atoms.css\` files unless the task explicitly asks for a fallback runtime.
 - Keep atoms in \`css(...)\`, treatments as semantic classes, and theme decorators as additive classes. Do not blur those roles together.
+- 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 that cannot be expressed through the contract.
 - Use \`d-control\` as the default semantic treatment for inputs, selects, and textareas. Theme decorators such as \`carbon-input\` are additive and should only layer on when the section or theme contract explicitly calls for them.
 - Use loading decorators such as \`carbon-skeleton\` as optional enhancement on top of a structurally correct loading state \u2014 they do not replace the need for a real loading/skeleton branch.
+- 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.
+- If a required decorator class is referenced in the generated contract but missing from generated CSS, report that contract gap instead of inventing a parallel visual system.
 
 ### Visual Treatments
 
@@ -1044,12 +1091,19 @@ Atoms + treatment + theme decorator:
 
 \`\`\`tsx
 // Responsive prefix \u2014 applies at breakpoint and above:
-css('_col sm:_row')
+css('_col _sm:row')
 
 // Pseudo prefix:
-css('hover:_opacity80')
+css('_bgprimary _h:bgprimary/80')
 \`\`\`
 
+### Prefix and Arbitrary Value Syntax
+
+- Responsive prefixes are part of the atom token itself: \`_sm:gc2\`, \`_md:flex\`, \`_lg:row\`.
+- Pseudo prefixes are also token-prefixed: \`_h:bgprimary/80\`, \`_f:borderprimary\`, \`_fv:shadowmd\`.
+- Arbitrary values use square brackets when the standard scale is not enough: \`_w[512px]\`, \`_h[100vh]\`, \`_p[clamp(1rem,3vw,2rem)]\`, \`_z[40]\`.
+- When you see bracket atoms in shell or page contracts, treat them as first-class Decantr syntax, not as an error or a cue to fall back to inline styles.
+
 ### Atom Reference
 
 #### Display
@@ -1226,7 +1280,7 @@ css('hover:_opacity80')
 | \`_trans\` | \`transition:all 0.15s ease\` |
 | \`_visible\`, \`_invisible\` | visibility |
 
-Responsive prefixes: \`_sm:\`, \`_md:\`, \`_lg:\` (e.g. \`_md:gc2\`, \`_lg:gc4\`, \`_sm:flex\`).
+Responsive prefixes: \`_sm:\`, \`_md:\`, \`_lg:\`, \`_xl:\` (e.g. \`_sm:gc2\`, \`_md:flex\`, \`_lg:row\`).
 
 ### Section Labels
 
@@ -1245,6 +1299,7 @@ If the theme provides motion tokens, apply the \`entrance-fade\` class to page c
 ### Navigation Shortcuts
 
 If the essence defines hotkeys or command_palette, implement as keyboard event listeners (useEffect + keydown) \u2014 not as visible UI text.
+Missing declared navigation features are contract drift, not optional polish.
 
 ### Design Tokens
 
@@ -1320,7 +1375,23 @@ function generateDecantrMdV31(params) {
   const template = loadTemplate("DECANTR.md.template");
   const body = renderTemplate(template, {
     GUARD_MODE: params.guardMode,
-    CSS_APPROACH: params.cssApproach
+    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.
+
+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.
+
+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.
+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.
+Start implementation from the shell layouts and shared route structure before filling in section pages.`
   });
   const briefLines = [];
   briefLines.push("## Project Brief");
@@ -1328,6 +1399,7 @@ function generateDecantrMdV31(params) {
   briefLines.push(`- **Blueprint:** ${params.blueprintId || "custom"}`);
   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"}`);
   if (params.personality && params.personality.length > 0) {
     briefLines.push(`- **Personality:** ${params.personality.join(". ")}`);
   }
@@ -1414,7 +1486,8 @@ function generateProjectJson(detected, options, registrySource) {
       at: now,
       via: "cli",
       version: CLI_VERSION,
-      flags: buildFlagsString(options)
+      flags: buildFlagsString(options),
+      workflowMode: options.workflowMode || "greenfield-scaffold"
     }
   };
   if (options.blueprint) {
@@ -1854,7 +1927,8 @@ function scaffoldMinimal(projectRoot) {
       at: now,
       via: "cli",
       version: CLI_VERSION,
-      flags: "--offline --minimal"
+      flags: "--offline --minimal",
+      workflowMode: "greenfield-scaffold"
     }
   };
   const projectJsonPath = join(decantrDir, "project.json");
@@ -2054,6 +2128,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   mkdirSync(contextDir, { recursive: true });
   let storedBlueprintId;
   let storedVoice;
+  let storedWorkflowMode;
   const projectJsonFilePath = join(decantrDir, "project.json");
   let projectJsonData = {};
   if (existsSync(projectJsonFilePath)) {
@@ -2061,6 +2136,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       projectJsonData = JSON.parse(readFileSync(projectJsonFilePath, "utf-8"));
       if (projectJsonData.blueprintId) storedBlueprintId = projectJsonData.blueprintId;
       if (projectJsonData.voice) storedVoice = projectJsonData.voice;
+      if (projectJsonData.initialized?.workflowMode) storedWorkflowMode = projectJsonData.initialized.workflowMode;
     } catch {
     }
   }
@@ -2141,7 +2217,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
     spatialTokens,
     themeData?.treatments,
     themeData?.decorators,
-    themeName
+    themeName,
+    themeData?.decorator_definitions
   );
   const personalityCSS = generatePersonalityCSS(personality || [], themeData || {});
   treatmentCSS += personalityCSS;
@@ -2178,6 +2255,7 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
   writeFileSync(decantrMdPath, generateDecantrMdV31({
     guardMode,
     cssApproach: CSS_APPROACH_CONTENT,
+    workflowMode: storedWorkflowMode,
     blueprintId: storedBlueprintId || getLegacyBlueprintId(essence.meta) || void 0,
     themeName,
     themeMode: mode,
@@ -3112,9 +3190,18 @@ function generateScaffoldContext(input) {
     lines.push("");
     if (navigation.command_palette) {
       lines.push("- Command palette: enabled");
+      lines.push("- Requirement: implement a real keyboard-triggered command palette, not just placeholder UI text.");
     }
     if (navigation.hotkeys && navigation.hotkeys.length > 0) {
       lines.push(`- Hotkeys: ${navigation.hotkeys.length} configured`);
+      for (const hotkey of navigation.hotkeys) {
+        if (typeof hotkey === "object" && hotkey !== null && typeof hotkey.key === "string") {
+          const target = [hotkey.label, hotkey.route || hotkey.action].filter(Boolean).join(" \u2014 ");
+          lines.push(`  - \`${hotkey.key}\`${target ? `: ${target}` : ""}`);
+        }
+      }
+      lines.push("- Requirement: implement these bindings as real keyboard shortcuts, not as decorative text.");
+      lines.push("- Presentation rule: do not append hotkey text to persistent nav labels, breadcrumbs, or page titles unless the shell or route contract explicitly requests visible shortcut hints.");
     }
     lines.push("");
   }