@decantr/cli 2.9.3 → 2.9.5

package/README.md

@@ -176,11 +176,11 @@ decantr verify --workspace --changed --since origin/main
 decantr export --to figma-tokens
 ```
 
-Use `--json` for machines and schema validation, `--markdown` for summaries, `--evidence` for the privacy-redacted Evidence Bundle, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. The prompt command prints instructions only; it does not modify source files. In monorepos, prompt commands preserve `--project <path>` so the finding resolves from the same app that produced it. `--browser` uses a project-local Playwright install and a supplied base URL to capture local route screenshots under `.decantr/evidence/screenshots/` and write `.decantr/evidence/visual-manifest.json`; missing Playwright becomes a visible setup finding/message, not a crash or silent skip. `--save-baseline` writes `.decantr/health-baseline.json`; `--since-baseline` writes `.decantr/health-baseline-diff.json` with changed files, route impact, finding deltas, screenshot hash drift, and contract drift. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `decantr ci --fail-on error` fails only when blocking errors exist; `decantr ci --fail-on warn` also fails on warnings.
+Use `--json` for machines and schema validation, `--markdown` for summaries, `--evidence` for the privacy-redacted Evidence Bundle, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. The prompt command prints instructions only; it does not modify source files. In monorepos, prompt commands preserve `--project <path>`, include app-prefixed read targets such as `apps/web/DECANTR.md`, and use root-safe runtime commands such as `pnpm --dir apps/web build` so the finding resolves from the same app that produced it. `--browser` uses a project-local Playwright install and a supplied base URL to capture local route screenshots under `.decantr/evidence/screenshots/` and write `.decantr/evidence/visual-manifest.json`; missing Playwright becomes a visible setup finding/message, not a crash or silent skip. `--save-baseline` writes `.decantr/health-baseline.json`; `--since-baseline` writes `.decantr/health-baseline-diff.json` with changed files, route impact, finding deltas, screenshot hash drift, and contract drift. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `decantr ci --fail-on error` fails only when blocking errors exist; `decantr ci --fail-on warn` also fails on warnings.
 
 `decantr ci init` installs `.github/workflows/decantr-ci.yml` for GitHub Actions. The generated workflow installs dependencies at the workspace root, writes JSON/markdown CI artifacts, gates with `decantr ci`, appends the markdown report to the GitHub step summary, and uploads both files as artifacts. Use `--force` to replace an existing workflow or `--fail-on warn` for stricter repositories. In monorepos, add `--project <path>` from the repository root; dependency install stays at the root while CI evaluates the app contract and uploads app-scoped artifacts. Use `--workspace` to generate an aggregate gate. Use `--provider generic` for Jenkins, Please, Buildkite, GitLab, Azure DevOps, or internal deployment tools. Generated CI uses the pinned local package-manager command and does not depend on `@latest`. Project Health remediation prompts are also monorepo-aware, so missing-pack fixes use `apps/web/decantr.essence.json` and CI recommendations include `--project apps/web`.
 
-`decantr workspace` is the monorepo reliability namespace. Before attach, `workspace list` shows app candidates. After attach, it also discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files. Workspace health runs projects with deterministic ordering, concurrency, per-project timeout, failure isolation, and aggregate JSON, and can limit a run to changed projects:
+`decantr workspace` is the monorepo reliability namespace. Before attach, `workspace list` shows app candidates. After attach, it also discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files, and it distinguishes "attach another app" from the empty-workspace first attach. Workspace health runs projects with deterministic ordering, concurrency, per-project timeout, failure isolation, and aggregate JSON, and can limit a run to changed projects:
 
 ```bash
 decantr workspace list
@@ -189,6 +189,8 @@ decantr workspace health --json --output .decantr/workspace-health.json
 decantr verify --workspace --changed --since origin/main
 ```
 
+In observed Brownfield projects, common section shorthands are accepted for page additions when they resolve unambiguously. For example, `decantr add page app/settings --route /settings --project apps/web` resolves `app` to the single primary section, such as `observed-primary`, so docs and LLM prompts do not have to guess generated section IDs first.
+
 `decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
 
 ```bash

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-VMNUJOEH.js";
+import "./chunk-3KJ46XY7.js";
 import "./chunk-RXF7ZYGK.js";
-import "./chunk-ARR3EPS2.js";
-import "./chunk-XZFKK6V7.js";
-import "./chunk-34TZXWIF.js";
+import "./chunk-VCUFZB45.js";
+import "./chunk-FACL3NXU.js";
+import "./chunk-WONPNSSI.js";

package/dist/{chunk-VMNUJOEH.js → chunk-3KJ46XY7.js}

@@ -22,14 +22,14 @@ import {
   listWorkspaceCandidates,
   listWorkspaceProjects,
   shouldFailWorkspaceHealth
-} from "./chunk-ARR3EPS2.js";
+} from "./chunk-VCUFZB45.js";
 import {
   createProjectHealthReport,
   formatProjectHealthMarkdown,
   formatProjectHealthText,
   resolveWorkspaceInfo,
   shouldFailHealth
-} from "./chunk-XZFKK6V7.js";
+} from "./chunk-FACL3NXU.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -46,7 +46,7 @@ import {
   sendCliCommandTelemetry,
   sendNewProjectCompletedTelemetry,
   writeDoctrineMap
-} from "./chunk-34TZXWIF.js";
+} from "./chunk-WONPNSSI.js";
 
 // src/index.ts
 import { existsSync as existsSync29, mkdirSync as mkdirSync16, readdirSync as readdirSync9, readFileSync as readFileSync22, writeFileSync as writeFileSync19 } from "fs";
@@ -1743,6 +1743,7 @@ import { join as join6 } from "path";
 import { isV4 as isV42 } from "@decantr/essence-spec";
 var GREEN = "\x1B[32m";
 var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
 function readV4Essence(projectRoot) {
@@ -1786,6 +1787,36 @@ function normalizeRoute(route) {
   if (!trimmed || trimmed === "/") return "/";
   return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
+function resolveSectionForPage(sections, requestedSectionId) {
+  const exact = sections.find((section) => section.id === requestedSectionId);
+  if (exact) return { section: exact, resolvedFromAlias: false };
+  const lower = requestedSectionId.toLowerCase();
+  const roleByAlias = {
+    app: "primary",
+    main: "primary",
+    primary: "primary",
+    public: "public",
+    marketing: "public",
+    auth: "gateway",
+    gateway: "gateway",
+    auxiliary: "auxiliary"
+  };
+  const desiredRole = roleByAlias[lower];
+  if (!desiredRole) return null;
+  const roleMatches = sections.filter((section) => section.role === desiredRole);
+  if (roleMatches.length === 1) return { section: roleMatches[0], resolvedFromAlias: true };
+  if (roleMatches.length > 1) return null;
+  const observedMatch = sections.find((section) => section.id === `observed-${desiredRole}`);
+  return observedMatch ? { section: observedMatch, resolvedFromAlias: true } : null;
+}
+function printSectionNotFound(sectionId, sections, pageId) {
+  console.error(`${RED}Section "${sectionId}" not found.${RESET}`);
+  console.error(`${DIM}Available sections: ${sections.map((s) => s.id).join(", ")}${RESET}`);
+  if (pageId && sections.length > 0) {
+    const primary = sections.find((section) => section.role === "primary") ?? sections[0];
+    console.error(`${DIM}Try: decantr add page ${primary.id}/${pageId}${RESET}`);
+  }
+}
 async function cmdAddSection(archetypeId, args, projectRoot = process.cwd()) {
   if (!archetypeId) {
     console.error(`${RED}Usage: decantr add section <archetypeId>${RESET}`);
@@ -1849,15 +1880,18 @@ async function cmdAddPage(path, args, projectRoot = process.cwd()) {
   if (!loaded) return;
   const { essence, essencePath } = loaded;
   const sections = essence.blueprint.sections;
-  const section = sections.find((s) => s.id === sectionId);
-  if (!section) {
-    console.error(`${RED}Section "${sectionId}" not found.${RESET}`);
-    console.error(`${DIM}Available sections: ${sections.map((s) => s.id).join(", ")}${RESET}`);
+  const resolved = resolveSectionForPage(sections, sectionId);
+  if (!resolved) {
+    printSectionNotFound(sectionId, sections, pageId);
     process.exitCode = 1;
     return;
   }
+  const { section } = resolved;
+  const resolvedSectionId = section.id;
   if (section.pages.find((p) => p.id === pageId)) {
-    console.error(`${RED}Page "${pageId}" already exists in section "${sectionId}".${RESET}`);
+    console.error(
+      `${RED}Page "${pageId}" already exists in section "${resolvedSectionId}".${RESET}`
+    );
     process.exitCode = 1;
     return;
   }
@@ -1877,10 +1911,15 @@ async function cmdAddPage(path, args, projectRoot = process.cwd()) {
     route,
     layout: ["hero"]
   });
-  routes[route] = { section: sectionId, page: pageId };
+  routes[route] = { section: resolvedSectionId, page: pageId };
   writeEssence(essencePath, essence);
+  if (resolved.resolvedFromAlias) {
+    console.log(
+      `${YELLOW}Resolved section alias "${sectionId}" to "${resolvedSectionId}".${RESET}`
+    );
+  }
   console.log(
-    `${GREEN}Added page "${pageId}" to section "${sectionId}" at route "${route}".${RESET}`
+    `${GREEN}Added page "${pageId}" to section "${resolvedSectionId}" at route "${route}".${RESET}`
   );
   const registryClient = new RegistryClient({
     cacheDir: join6(projectRoot, ".decantr", "cache")
@@ -2958,7 +2997,7 @@ var DIM2 = "\x1B[2m";
 var RESET2 = "\x1B[0m";
 var GREEN2 = "\x1B[32m";
 var CYAN = "\x1B[36m";
-var YELLOW = "\x1B[33m";
+var YELLOW2 = "\x1B[33m";
 async function cmdAnalyze(projectRoot = process.cwd(), workspace) {
   const startedAt = Date.now();
   console.log(`
@@ -3126,7 +3165,7 @@ ${DIM2}Written to:${RESET2} ${outputPath}`);
   console.log(`${DIM2}Enrichment backlog:${RESET2} ${intelligenceArtifacts.backlogPath}`);
   console.log(
     `
-${YELLOW}Next step:${RESET2} Review ${BOLD}${reportDisplayPath}${RESET2}, then run ${BOLD}${recommendedAttachCommand}${RESET2} to attach Decantr using the observed proposal.
+${YELLOW2}Next step:${RESET2} Review ${BOLD}${reportDisplayPath}${RESET2}, then run ${BOLD}${recommendedAttachCommand}${RESET2} to attach Decantr using the observed proposal.
 `
   );
   await sendAnalyzeCompletedTelemetry({
@@ -4257,7 +4296,7 @@ var BOLD3 = "\x1B[1m";
 var DIM4 = "\x1B[2m";
 var GREEN4 = "\x1B[32m";
 var RED3 = "\x1B[31m";
-var YELLOW2 = "\x1B[33m";
+var YELLOW3 = "\x1B[33m";
 var CYAN2 = "\x1B[36m";
 var RESET4 = "\x1B[0m";
 function readJson2(path) {
@@ -4596,7 +4635,7 @@ function buildDoctorReport(root, args) {
 function colorForStatus(status) {
   if (status === "healthy") return GREEN4;
   if (status === "needs-setup" || status === "needs-migration") return RED3;
-  return YELLOW2;
+  return YELLOW3;
 }
 function formatDoctorText(report) {
   const lines = [
@@ -4640,7 +4679,7 @@ function formatDoctorText(report) {
     lines.push(`  ${GREEN4}No doctor findings.${RESET4}`);
   } else {
     for (const issue of report.issues) {
-      const color = issue.severity === "error" ? RED3 : issue.severity === "warn" ? YELLOW2 : CYAN2;
+      const color = issue.severity === "error" ? RED3 : issue.severity === "warn" ? YELLOW3 : CYAN2;
       lines.push(
         `  ${color}[${issue.severity.toUpperCase()}]${RESET4} ${issue.category}: ${issue.message}`
       );
@@ -4682,6 +4721,16 @@ var GREEN5 = "\x1B[32m";
 var RED4 = "\x1B[31m";
 var DIM5 = "\x1B[2m";
 var RESET5 = "\x1B[0m";
+function readAdoptionMode(projectRoot) {
+  const projectJsonPath = join19(projectRoot, ".decantr", "project.json");
+  if (!existsSync17(projectJsonPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync14(projectJsonPath, "utf-8"));
+    return typeof parsed.initialized?.adoptionMode === "string" ? parsed.initialized.adoptionMode : null;
+  } catch {
+    return null;
+  }
+}
 function resolveOutputPath(projectRoot, output, fallback) {
   if (!output) return fallback;
   return isAbsolute(output) ? output : join19(projectRoot, output);
@@ -4853,9 +4902,9 @@ async function cmdExport(target, projectRoot, options = {}) {
     return;
   }
   if (!existsSync17(tokensPath)) {
-    console.error(
-      `${RED4}No src/styles/tokens.css found. Run \`decantr refresh\` to generate tokens.${RESET5}`
-    );
+    const adoptionMode = readAdoptionMode(projectRoot);
+    const message = adoptionMode === "contract-only" ? `No src/styles/tokens.css found. This export reads Decantr CSS tokens, but this project is contract-only Brownfield and may intentionally use its own Tailwind/Sass token system. Export from the app's token source or adopt a style bridge before using \`decantr export --to ${target}\`.` : "No src/styles/tokens.css found. Run `decantr refresh` to generate tokens.";
+    console.error(`${RED4}${message}${RESET5}`);
     process.exitCode = 1;
     return;
   }
@@ -4936,7 +4985,7 @@ var DIM6 = "\x1B[2m";
 var RESET6 = "\x1B[0m";
 var GREEN6 = "\x1B[32m";
 var CYAN3 = "\x1B[36m";
-var YELLOW3 = "\x1B[33m";
+var YELLOW4 = "\x1B[33m";
 var MAGENTA = "\x1B[35m";
 function success(text) {
   return `${GREEN6}${text}${RESET6}`;
@@ -5157,7 +5206,7 @@ async function cmdMagic(prompt, projectRoot, options) {
   const essencePath = join20(projectRoot, "decantr.essence.json");
   if (existsSync18(essencePath)) {
     const projectFlag = options.projectLabel ? ` --project ${options.projectLabel}` : "";
-    console.log(`${YELLOW3} Decantr is already attached to this project.${RESET6}`);
+    console.log(`${YELLOW4} Decantr is already attached to this project.${RESET6}`);
     console.log(
       dim(" decantr magic is greenfield-first; use task-time context for existing apps.")
     );
@@ -5170,7 +5219,7 @@ async function cmdMagic(prompt, projectRoot, options) {
   }
   const detected = detectProject(projectRoot);
   if (hasExistingProjectFootprint(detected)) {
-    console.log(`${YELLOW3} Existing project detected.${RESET6}`);
+    console.log(`${YELLOW4} Existing project detected.${RESET6}`);
     console.log(
       dim(
         " decantr magic stays greenfield-first and will not silently bootstrap over an existing app."
@@ -5480,7 +5529,7 @@ ${GREEN6}${BOLD4}Quality summary:${RESET6}`);
   );
   console.log(`  CSS:             tokens.css + treatments.css + global.css`);
   console.log(
-    `  @layer cascade:  ${hasLayers ? GREEN6 + "yes" + RESET6 : YELLOW3 + "missing" + RESET6}`
+    `  @layer cascade:  ${hasLayers ? GREEN6 + "yes" + RESET6 : YELLOW4 + "missing" + RESET6}`
   );
   console.log("");
   console.log(`${BOLD4} Ready!${RESET6} Next steps:`);
@@ -5509,7 +5558,7 @@ import {
 } from "@decantr/essence-spec";
 var GREEN7 = "\x1B[32m";
 var RED5 = "\x1B[31m";
-var YELLOW4 = "\x1B[33m";
+var YELLOW5 = "\x1B[33m";
 var RESET7 = "\x1B[0m";
 var DIM7 = "\x1B[2m";
 function migrateEssenceFile(essencePath) {
@@ -5609,7 +5658,7 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
     console.log(`${GREEN7}Derived context and execution packs refreshed.${RESET7}`);
   }
   console.log("");
-  console.log(`${YELLOW4}Review the migrated file and run \`decantr check\` to verify.${RESET7}`);
+  console.log(`${YELLOW5}Review the migrated file and run \`decantr check\` to verify.${RESET7}`);
 }
 
 // src/commands/new-project.ts
@@ -5676,7 +5725,7 @@ var RESET8 = "\x1B[0m";
 var RED6 = "\x1B[31m";
 var GREEN8 = "\x1B[32m";
 var CYAN4 = "\x1B[36m";
-var YELLOW5 = "\x1B[33m";
+var YELLOW6 = "\x1B[33m";
 function heading(text) {
   return `
 ${BOLD5}${text}${RESET8}
@@ -5826,7 +5875,7 @@ async function cmdNewProject(projectName, options) {
     );
   } else {
     console.log(
-      `${YELLOW5}  No greenfield bootstrap adapter is available yet for target "${bootstrapTarget.target}" (${bootstrapTarget.packAdapter}).${RESET8}`
+      `${YELLOW6}  No greenfield bootstrap adapter is available yet for target "${bootstrapTarget.target}" (${bootstrapTarget.packAdapter}).${RESET8}`
     );
     console.log(
       dim2(
@@ -5842,7 +5891,7 @@ async function cmdNewProject(projectName, options) {
     } catch {
       console.log(
         `
-${YELLOW5}Dependency install failed. Run \`${packageManager} install\` manually.${RESET8}`
+${YELLOW6}Dependency install failed. Run \`${packageManager} install\` manually.${RESET8}`
       );
     }
   }
@@ -5854,7 +5903,7 @@ ${YELLOW5}Dependency install failed. Run \`${packageManager} install\` manually.
     console.log(dim2(`  Seeded offline registry content from ${seeded.strategy}.`));
   } else if (requiresOfflineContent) {
     console.log(
-      `${YELLOW5}  Offline blueprint/archetype resolution requires local registry content.${RESET8}`
+      `${YELLOW6}  Offline blueprint/archetype resolution requires local registry content.${RESET8}`
     );
     console.log(
       dim2(
@@ -5884,7 +5933,7 @@ ${YELLOW5}Dependency install failed. Run \`${packageManager} install\` manually.
   } catch {
     console.log(
       `
-${YELLOW5}Decantr init encountered issues. Run \`decantr init\` manually inside ${projectName}/.${RESET8}`
+${YELLOW6}Decantr init encountered issues. Run \`decantr init\` manually inside ${projectName}/.${RESET8}`
     );
   }
   console.log(success2(`
@@ -6227,7 +6276,7 @@ var GREEN10 = "\x1B[32m";
 var RED8 = "\x1B[31m";
 var DIM10 = "\x1B[2m";
 var CYAN5 = "\x1B[36m";
-var YELLOW6 = "\x1B[33m";
+var YELLOW7 = "\x1B[33m";
 var RESET10 = "\x1B[0m";
 var ALL_CONTENT_TYPES = [...API_CONTENT_TYPES];
 async function cmdRegistryMirror(projectRoot, options = {}) {
@@ -6291,7 +6340,7 @@ Mirroring registry content to ${DIM10}.decantr/cache/${RESET10}
   const totalItems = Object.values(counts).reduce((a, b) => a + b, 0);
   console.log("");
   if (failed.length > 0) {
-    console.log(`${YELLOW6}Mirrored ${totalItems} items (${failed.length} type(s) failed)${RESET10}`);
+    console.log(`${YELLOW7}Mirrored ${totalItems} items (${failed.length} type(s) failed)${RESET10}`);
   } else {
     console.log(
       `${GREEN10}Mirrored ${totalItems} items across ${Object.keys(counts).length} types${RESET10}`
@@ -6479,7 +6528,7 @@ import { existsSync as existsSync26, readFileSync as readFileSync19, writeFileSy
 import { join as join28 } from "path";
 var GREEN12 = "\x1B[32m";
 var RED10 = "\x1B[31m";
-var YELLOW7 = "\x1B[33m";
+var YELLOW8 = "\x1B[33m";
 var RESET12 = "\x1B[0m";
 var DIM12 = "\x1B[2m";
 var BOLD6 = "\x1B[1m";
@@ -6520,7 +6569,7 @@ ${BOLD6}Unresolved Drift Entries (${unresolved.length})${RESET12}
 `);
   for (let i = 0; i < unresolved.length; i++) {
     const entry = unresolved[i];
-    const severityColor = entry.severity === "error" ? RED10 : YELLOW7;
+    const severityColor = entry.severity === "error" ? RED10 : YELLOW8;
     const icon = entry.severity === "error" ? "x" : "!";
     console.log(
       `  ${severityColor}${icon}${RESET12} ${BOLD6}#${i + 1}${RESET12} [${entry.rule}] ${entry.message}`
@@ -6804,7 +6853,7 @@ import { join as join29 } from "path";
 import { isV4 as isV48 } from "@decantr/essence-spec";
 var GREEN14 = "\x1B[32m";
 var RED11 = "\x1B[31m";
-var YELLOW8 = "\x1B[33m";
+var YELLOW9 = "\x1B[33m";
 var DIM14 = "\x1B[2m";
 var RESET14 = "\x1B[0m";
 var VALID_THEME_SHAPES = ["sharp", "rounded", "pill"];
@@ -6899,7 +6948,7 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
   console.log(
     `${GREEN14}Derived files refreshed (tokens.css, treatments.css, all contexts).${RESET14}`
   );
-  console.log(`${YELLOW8}Guard will flag code using old tokens. Run \`decantr check\`.${RESET14}`);
+  console.log(`${YELLOW9}Guard will flag code using old tokens. Run \`decantr check\`.${RESET14}`);
 }
 
 // src/prompts.ts
@@ -6908,7 +6957,7 @@ var BOLD8 = "\x1B[1m";
 var DIM15 = "\x1B[2m";
 var RESET15 = "\x1B[0m";
 var GREEN15 = "\x1B[32m";
-var YELLOW9 = "\x1B[33m";
+var YELLOW10 = "\x1B[33m";
 var CYAN8 = "\x1B[36m";
 function ask(question, defaultValue) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -6948,7 +6997,7 @@ async function confirm(question, defaultYes = true) {
 }
 function warn(message) {
   console.log(`
-${YELLOW9}  Warning: ${message}${RESET15}`);
+${YELLOW10}  Warning: ${message}${RESET15}`);
 }
 function showDetection(detected) {
   console.log(`
@@ -6967,7 +7016,7 @@ ${CYAN8}Detected project configuration:${RESET15}`);
     console.log(`  Tailwind CSS: ${GREEN15}yes${RESET15}`);
   }
   if (detected.existingEssence) {
-    console.log(`  Existing essence: ${YELLOW9}yes${RESET15}`);
+    console.log(`  Existing essence: ${YELLOW10}yes${RESET15}`);
   }
 }
 async function runInteractivePrompts(detected, archetypes, blueprints, themes, workflowSeed) {
@@ -7369,7 +7418,7 @@ var RESET16 = "\x1B[0m";
 var RED12 = "\x1B[31m";
 var GREEN16 = "\x1B[32m";
 var CYAN9 = "\x1B[36m";
-var YELLOW10 = "\x1B[33m";
+var YELLOW11 = "\x1B[33m";
 function heading2(text) {
   return `
 ${BOLD9}${text}${RESET16}
@@ -8412,7 +8461,7 @@ function printBlueprintPortfolioNotice(blueprint) {
   if (!portfolio) return;
   if (portfolio.visibility === "hidden" || portfolio.maturity === "fold-candidate") {
     console.log(
-      `${YELLOW10}  Warning:${RESET16} blueprint "${blueprint.id}" is folded out of public browsing.`
+      `${YELLOW11}  Warning:${RESET16} blueprint "${blueprint.id}" is folded out of public browsing.`
     );
     if (portfolio.recommended_alternative) {
       console.log(
@@ -8425,7 +8474,7 @@ function printBlueprintPortfolioNotice(blueprint) {
   }
   if (portfolio.visibility === "labs") {
     console.log(
-      `${YELLOW10}  Note:${RESET16} blueprint "${blueprint.id}" is a Labs blueprint; direct scaffolding is supported, but it is not a default recommendation yet.`
+      `${YELLOW11}  Note:${RESET16} blueprint "${blueprint.id}" is a Labs blueprint; direct scaffolding is supported, but it is not a default recommendation yet.`
     );
   }
 }
@@ -8714,7 +8763,7 @@ async function cmdValidate(path) {
       console.log(heading2("Guard violations:"));
       for (const v of violations) {
         const vr = v;
-        console.log(`  ${YELLOW10}[${vr.rule}]${RESET16} ${vr.message}`);
+        console.log(`  ${YELLOW11}[${vr.rule}]${RESET16} ${vr.message}`);
         if (vr.suggestion) {
           console.log(`    ${DIM16}Suggestion: ${vr.suggestion}${RESET16}`);
         }
@@ -9048,7 +9097,7 @@ async function cmdInit(args) {
     console.log(dim3("  Found .decantr/init-seed.json brownfield guidance."));
   }
   if (detected.existingEssence && !args.existing) {
-    console.log(`${YELLOW10}Warning: decantr.essence.json already exists.${RESET16}`);
+    console.log(`${YELLOW11}Warning: decantr.essence.json already exists.${RESET16}`);
     const overwrite = await confirm("Overwrite existing configuration?", false);
     if (!overwrite) {
       console.log(dim3("Cancelled."));
@@ -9151,7 +9200,7 @@ async function cmdInit(args) {
   } else if (shouldUseRegistry && !apiAvailable) {
     if (!args.blueprint) {
       console.log(`
-${YELLOW10}You're offline. Scaffolding minimal Decantr project.${RESET16}`);
+${YELLOW11}You're offline. Scaffolding minimal Decantr project.${RESET16}`);
       console.log(
         dim3("Run `decantr sync` or `decantr upgrade` when online to pull full registry content.\n")
       );
@@ -9200,7 +9249,7 @@ ${YELLOW10}You're offline. Scaffolding minimal Decantr project.${RESET16}`);
       return;
     }
     console.log(`
-${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
+${YELLOW11}You're offline. Scaffolding Decantr default.${RESET16}`);
     console.log(dim3("Run `decantr upgrade` when online, or visit decantr.ai/registry\n"));
     selectedBlueprint = "default";
   } else if (shouldUseRegistry) {
@@ -9382,7 +9431,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
         return;
       }
       console.log(
-        `${YELLOW10}  Warning: Could not fetch blueprint "${options.blueprint}". Using defaults.${RESET16}`
+        `${YELLOW11}  Warning: Could not fetch blueprint "${options.blueprint}". Using defaults.${RESET16}`
       );
     }
   } else if (shouldUseRegistry && options.archetype) {
@@ -9397,7 +9446,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
         return;
       }
       console.log(
-        `${YELLOW10}  Warning: Could not fetch archetype "${options.archetype}". Using defaults.${RESET16}`
+        `${YELLOW11}  Warning: Could not fetch archetype "${options.archetype}". Using defaults.${RESET16}`
       );
     }
   }
@@ -9414,7 +9463,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
         return;
       }
       console.log(
-        `${YELLOW10}  Warning: Could not fetch theme "${options.theme}". Using defaults.${RESET16}`
+        `${YELLOW11}  Warning: Could not fetch theme "${options.theme}". Using defaults.${RESET16}`
       );
     }
   }
@@ -9619,7 +9668,7 @@ async function cmdStatus(projectRoot = process.cwd()) {
         `    Guard: ${v4.meta.guard.mode} (DNA: ${v4.meta.guard.dna_enforcement}, Blueprint: ${v4.meta.guard.blueprint_enforcement})`
       );
     } else {
-      console.log(`  ${YELLOW10}Run \`decantr migrate --to v4\` to upgrade this project.${RESET16}`);
+      console.log(`  ${YELLOW11}Run \`decantr migrate --to v4\` to upgrade this project.${RESET16}`);
     }
   } catch (e) {
     console.log(`  ${RED12}Error reading essence: ${e.message}${RESET16}`);
@@ -9632,15 +9681,15 @@ async function cmdStatus(projectRoot = process.cwd()) {
       const syncStatus = projectJson.sync?.status || "unknown";
       const lastSync = projectJson.sync?.lastSync || "never";
       const source = projectJson.sync?.registrySource || "unknown";
-      const statusColor = syncStatus === "synced" ? GREEN16 : YELLOW10;
+      const statusColor = syncStatus === "synced" ? GREEN16 : YELLOW11;
       console.log(`  Status: ${statusColor}${syncStatus}${RESET16}`);
       console.log(`  Last sync: ${dim3(lastSync)}`);
       console.log(`  Source: ${dim3(source)}`);
     } catch {
-      console.log(`  ${YELLOW10}Could not read project.json${RESET16}`);
+      console.log(`  ${YELLOW11}Could not read project.json${RESET16}`);
     }
   } else {
-    console.log(`  ${YELLOW10}No .decantr/project.json found${RESET16}`);
+    console.log(`  ${YELLOW11}No .decantr/project.json found${RESET16}`);
     console.log(dim3('  Run "decantr init" to create project files.'));
   }
 }
@@ -9653,12 +9702,12 @@ async function cmdSync() {
     console.log(success3("Sync completed successfully."));
     console.log(`  Synced: ${result.synced.join(", ")}`);
     if (result.failed.length > 0) {
-      console.log(`  ${YELLOW10}Failed: ${result.failed.join(", ")}${RESET16}`);
+      console.log(`  ${YELLOW11}Failed: ${result.failed.join(", ")}${RESET16}`);
     }
   } else {
-    console.log(`${YELLOW10}Could not sync: API unavailable${RESET16}`);
+    console.log(`${YELLOW11}Could not sync: API unavailable${RESET16}`);
     if (result.failed.length > 0) {
-      console.log(`  ${YELLOW10}Failed: ${result.failed.join(", ")}${RESET16}`);
+      console.log(`  ${YELLOW11}Failed: ${result.failed.join(", ")}${RESET16}`);
     }
   }
 }
@@ -9668,7 +9717,7 @@ function printVerificationFindings(findings) {
     return;
   }
   for (const finding of findings) {
-    const color = finding.severity === "error" ? RED12 : finding.severity === "warn" ? YELLOW10 : CYAN9;
+    const color = finding.severity === "error" ? RED12 : finding.severity === "warn" ? YELLOW11 : CYAN9;
     console.log(
       `  ${color}[${finding.severity.toUpperCase()}]${RESET16} ${finding.category}: ${finding.message}`
     );
@@ -10309,7 +10358,7 @@ async function cmdAdoptWorkflow(args) {
         )
       );
     } catch (e) {
-      console.log(`${YELLOW10}Pack hydration skipped:${RESET16} ${e.message}`);
+      console.log(`${YELLOW11}Pack hydration skipped:${RESET16} ${e.message}`);
       console.log(
         dim3(
           `Run ${compilePacksCommandForProject(projectArg)} after adoption if you want hosted page/review packs.`
@@ -10320,7 +10369,7 @@ async function cmdAdoptWorkflow(args) {
     console.log(dim3("Skipping hosted pack hydration in offline mode."));
   }
   if (runVerify) {
-    const { cmdHealth } = await import("./health-MB63O56B.js");
+    const { cmdHealth } = await import("./health-R7AV5G4V.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -10391,7 +10440,7 @@ async function cmdVerifyWorkflow(args) {
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-OGFYJA4N.js");
+    const { cmdWorkspace } = await import("./workspace-DRHTQ2NG.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -10424,7 +10473,7 @@ async function cmdVerifyWorkflow(args) {
   }
   let guardExitCode;
   if (brownfield) {
-    const { cmdHeal, collectCheckIssues } = await import("./heal-2BDT7TR5.js");
+    const { cmdHeal, collectCheckIssues } = await import("./heal-ZQHEHBUJ.js");
     if (quietOutput) {
       const result = collectCheckIssues(workspaceInfo.appRoot, { brownfield: true });
       guardExitCode = result.issues.some((issue) => issue.type === "error") ? 1 : void 0;
@@ -10434,7 +10483,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-MB63O56B.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-R7AV5G4V.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -10442,7 +10491,7 @@ async function cmdVerifyWorkflow(args) {
       if (!quietOutput) {
         console.log("");
         console.log(
-          `${YELLOW10}Local pattern pack missing.${RESET16} Run ${cyan3(withProject("decantr codify --from-audit", projectArg))}, review the proposal, then run ${cyan3(withProject("decantr codify --accept", projectArg))}.`
+          `${YELLOW11}Local pattern pack missing.${RESET16} Run ${cyan3(withProject("decantr codify --from-audit", projectArg))}, review the proposal, then run ${cyan3(withProject("decantr codify --accept", projectArg))}.`
         );
       }
       process.exitCode = process.exitCode || 1;
@@ -10458,11 +10507,11 @@ async function cmdVerifyWorkflow(args) {
           console.log(`${GREEN16}Local rule manifest found:${RESET16} ${validation.rulesPath}`);
         } else {
           console.log(
-            `${YELLOW10}Local rule manifest missing.${RESET16} Run ${cyan3("decantr codify --from-audit")} to propose .decantr/rules.json.`
+            `${YELLOW11}Local rule manifest missing.${RESET16} Run ${cyan3("decantr codify --from-audit")} to propose .decantr/rules.json.`
           );
         }
         for (const warning of validation.warnings.slice(0, 8)) {
-          console.log(`${YELLOW10}warn${RESET16} ${warning}`);
+          console.log(`${YELLOW11}warn${RESET16} ${warning}`);
         }
         if (validation.findings.length > 0) {
           console.log("");
@@ -10615,7 +10664,7 @@ async function cmdTaskWorkflow(args) {
     console.log("");
     console.log(`${BOLD9}Project-owned local law:${RESET16}`);
     console.log(
-      `  ${YELLOW10}Not codified yet.${RESET16} Run ${cyan3(withProject("decantr codify --from-audit", projectArg))} after adoption.`
+      `  ${YELLOW11}Not codified yet.${RESET16} Run ${cyan3(withProject("decantr codify --from-audit", projectArg))} after adoption.`
     );
   }
   if (context.changedFiles.length > 0) {
@@ -11414,10 +11463,10 @@ async function main() {
     case "heal": {
       if (command === "heal") {
         console.log(
-          `${YELLOW10}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET16}`
+          `${YELLOW11}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET16}`
         );
       }
-      const { cmdHeal } = await import("./heal-2BDT7TR5.js");
+      const { cmdHeal } = await import("./heal-ZQHEHBUJ.js");
       const { flags } = parseLooseArgs(args);
       const workspaceInfo = resolveWorkflowProject(flags, "check");
       if (!workspaceInfo) break;
@@ -11442,7 +11491,7 @@ async function main() {
         const { flags } = parseLooseArgs(args);
         const workspaceInfo = resolveWorkflowProject(flags, "health");
         if (!workspaceInfo) break;
-        const { cmdHealth, parseHealthArgs } = await import("./health-MB63O56B.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-R7AV5G4V.js");
         await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(stripProjectArgs(args)));
       } catch (e) {
         console.error(error2(e.message));
@@ -11470,7 +11519,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-6QGXJBVH.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-2734P63C.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error2(e.message));
@@ -11484,7 +11533,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-OGFYJA4N.js");
+        const { cmdWorkspace } = await import("./workspace-DRHTQ2NG.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error2(e.message));

package/dist/{chunk-XZFKK6V7.js → chunk-FACL3NXU.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-34TZXWIF.js";
+} from "./chunk-WONPNSSI.js";
 
 // src/commands/health.ts
 import { execFileSync } from "child_process";
@@ -383,6 +383,47 @@ function commandsForFinding(source) {
       return ["decantr audit", "decantr health"];
   }
 }
+function detectPackageManager(root) {
+  const pkg = readJsonFile(join2(root, "package.json"));
+  const declared = pkg?.packageManager?.split("@")[0];
+  if (declared === "pnpm" || declared === "npm" || declared === "yarn" || declared === "bun") {
+    return declared;
+  }
+  if (existsSync2(join2(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync2(join2(root, "package-lock.json"))) return "npm";
+  if (existsSync2(join2(root, "yarn.lock"))) return "yarn";
+  if (existsSync2(join2(root, "bun.lock")) || existsSync2(join2(root, "bun.lockb"))) return "bun";
+  return "unknown";
+}
+function buildCommandForProject(workspaceRoot, projectPath) {
+  const packageManager = detectPackageManager(workspaceRoot);
+  if (projectPath) {
+    switch (packageManager) {
+      case "pnpm":
+        return `pnpm --dir ${projectPath} build`;
+      case "yarn":
+        return `yarn --cwd ${projectPath} build`;
+      case "bun":
+        return `bun --cwd ${projectPath} run build`;
+      case "npm":
+        return `npm --prefix ${projectPath} run build`;
+      default:
+        return `cd ${projectPath} && npm run build`;
+    }
+  }
+  switch (packageManager) {
+    case "pnpm":
+      return "pnpm build";
+    case "yarn":
+      return "yarn build";
+    case "bun":
+      return "bun run build";
+    case "npm":
+      return "npm run build";
+    default:
+      return "npm run build";
+  }
+}
 function commandContextForProject(projectRoot) {
   const workspaceInfo = resolveWorkspaceInfo(projectRoot);
   const relativeProjectPath = relative(workspaceInfo.workspaceRoot, projectRoot).replace(
@@ -394,6 +435,7 @@ function commandContextForProject(projectRoot) {
   const essencePath = projectPath ? `${projectPath}/decantr.essence.json` : "decantr.essence.json";
   return {
     projectPath,
+    buildCommand: buildCommandForProject(workspaceInfo.workspaceRoot, projectPath),
     compilePacksCommand: `decantr registry compile-packs ${essencePath} --write-context`,
     verifyCommand: `decantr verify${projectFlag}`,
     ciCommand: `decantr ci${projectFlag} --fail-on error`,
@@ -401,6 +443,7 @@ function commandContextForProject(projectRoot) {
   };
 }
 function rewriteHealthCommand(command, context) {
+  if (command === "npm run build") return context.buildCommand;
   let rewritten = command.replace(
     /decantr registry compile-packs decantr\.essence\.json --write-context/g,
     context.compilePacksCommand
@@ -461,17 +504,25 @@ function scopeHealthFindingsToProject(projectRoot, findings) {
           message: finding.message,
           evidence: finding.evidence,
           suggestedFix,
-          commands
+          commands,
+          projectPath: context.projectPath
         })
       }
     };
   });
 }
 function buildRemediationPrompt(input) {
+  const prefix = input.projectPath ? `${input.projectPath}/` : "";
+  const readTargets = [
+    `${prefix}DECANTR.md`,
+    `${prefix}decantr.essence.json`,
+    `${prefix}.decantr/context/scaffold-pack.md`,
+    `${prefix}.decantr/context/scaffold.md`
+  ];
   return [
     "You are fixing one Decantr Project Health finding in this local workspace.",
     "",
-    "Read `DECANTR.md`, `decantr.essence.json`, and `.decantr/context/scaffold-pack.md` if they exist. For route or page work, read the matching page/section packs before editing.",
+    `Read project-scoped Decantr files if they exist: ${readTargets.map((target) => `\`${target}\``).join(", ")}. For route or page work, read the matching page/section packs before editing.`,
     "",
     `Finding: ${input.id}`,
     `Source: ${input.source}`,

package/dist/{chunk-ARR3EPS2.js → chunk-VCUFZB45.js}

@@ -1,7 +1,7 @@
 import {
   createProjectHealthReport,
   listWorkspaceAppCandidates
-} from "./chunk-XZFKK6V7.js";
+} from "./chunk-FACL3NXU.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";
@@ -322,7 +322,7 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
     }
     if (unattachedCandidates.length > 0) {
       console.log("");
-      console.log("Start by attaching one app:");
+      console.log(projects.length > 0 ? "Attach another app:" : "Start by attaching one app:");
       console.log(`  ${unattachedCandidates[0].suggestedAdoptCommand}`);
     }
     return;

package/dist/{chunk-34TZXWIF.js → chunk-WONPNSSI.js}

@@ -1323,6 +1323,22 @@ var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
   ".cache"
 ]);
 var MAX_FILE_SIZE = 1024 * 1024;
+function isNonUiInteractionSource(relativePath) {
+  const normalized2 = relativePath.replace(/\\/g, "/");
+  if (/\.d\.ts$/i.test(normalized2)) return true;
+  if (/(?:^|\/)(?:__tests__|__mocks__|tests?|specs?|fixtures?|mocks?|stories?)(?:\/|$)/i.test(
+    normalized2
+  )) {
+    return true;
+  }
+  if (/\.(?:test|spec|stories?|story|fixture|mock)\.(?:[cm]?[jt]sx?|mdx|html)$/i.test(normalized2)) {
+    return true;
+  }
+  if (/^(?:src\/)?app\/api\//i.test(normalized2)) return true;
+  if (/^(?:src\/)?pages\/api\//i.test(normalized2)) return true;
+  if (/(?:^|\/)route\.[cm]?[jt]s$/i.test(normalized2)) return true;
+  return false;
+}
 function walkSourceTree(rootDir) {
   const sources = /* @__PURE__ */ new Map();
   function walk2(dir) {
@@ -1341,12 +1357,14 @@ function walkSourceTree(rootDir) {
       } catch {
         continue;
       }
+      const relativePath = relative3(rootDir, fullPath) || entry;
       if (s.isDirectory()) {
         walk2(fullPath);
       } else if (s.isFile() && SCAN_EXTENSIONS.has(extname2(entry))) {
         if (s.size > MAX_FILE_SIZE) continue;
+        if (isNonUiInteractionSource(relativePath)) continue;
         try {
-          sources.set(relative3(rootDir, fullPath) || entry, readFileSync8(fullPath, "utf8"));
+          sources.set(relativePath, readFileSync8(fullPath, "utf8"));
         } catch {
         }
       }

package/dist/{heal-2BDT7TR5.js → heal-ZQHEHBUJ.js}

@@ -1,7 +1,7 @@
 import {
   cmdHeal,
   collectCheckIssues
-} from "./chunk-34TZXWIF.js";
+} from "./chunk-WONPNSSI.js";
 export {
   cmdHeal,
   collectCheckIssues

package/dist/{health-MB63O56B.js → health-R7AV5G4V.js}

@@ -10,8 +10,8 @@ import {
   renderProjectHealthCiWorkflow,
   shouldFailHealth,
   writeProjectHealthCiWorkflow
-} from "./chunk-XZFKK6V7.js";
-import "./chunk-34TZXWIF.js";
+} from "./chunk-FACL3NXU.js";
+import "./chunk-WONPNSSI.js";
 export {
   cmdHealth,
   collectDesignTokenEvidence,

package/dist/index.js

@@ -1,5 +1,5 @@
-import "./chunk-VMNUJOEH.js";
+import "./chunk-3KJ46XY7.js";
 import "./chunk-RXF7ZYGK.js";
-import "./chunk-ARR3EPS2.js";
-import "./chunk-XZFKK6V7.js";
-import "./chunk-34TZXWIF.js";
+import "./chunk-VCUFZB45.js";
+import "./chunk-FACL3NXU.js";
+import "./chunk-WONPNSSI.js";

package/dist/{studio-6QGXJBVH.js → studio-2734P63C.js}

@@ -1,13 +1,13 @@
 import {
   createWorkspaceHealthReport
-} from "./chunk-ARR3EPS2.js";
+} from "./chunk-VCUFZB45.js";
 import {
   createProjectHealthReport
-} from "./chunk-XZFKK6V7.js";
+} from "./chunk-FACL3NXU.js";
 import {
   sendStudioHealthRefreshedTelemetry,
   sendStudioStartedTelemetry
-} from "./chunk-34TZXWIF.js";
+} from "./chunk-WONPNSSI.js";
 
 // src/commands/studio.ts
 import { readFileSync } from "fs";

package/dist/{workspace-OGFYJA4N.js → workspace-DRHTQ2NG.js}

@@ -7,9 +7,9 @@ import {
   listWorkspaceProjects,
   parseWorkspaceArgs,
   shouldFailWorkspaceHealth
-} from "./chunk-ARR3EPS2.js";
-import "./chunk-XZFKK6V7.js";
-import "./chunk-34TZXWIF.js";
+} from "./chunk-VCUFZB45.js";
+import "./chunk-FACL3NXU.js";
+import "./chunk-WONPNSSI.js";
 export {
   cmdWorkspace,
   createWorkspaceHealthReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "2.9.3",
+  "version": "2.9.5",
   "description": "Decantr CLI - scaffold, audit, inspect Project Health, and maintain Decantr projects from the terminal",
   "keywords": [
     "decantr",
@@ -48,11 +48,11 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@decantr/essence-spec": "2.0.1",
+    "@decantr/core": "2.1.0",
     "@decantr/registry": "2.2.0",
-    "@decantr/verifier": "2.3.3",
     "@decantr/telemetry": "2.2.1",
-    "@decantr/core": "2.1.0"
+    "@decantr/essence-spec": "2.0.1",
+    "@decantr/verifier": "2.3.3"
   },
   "scripts": {
     "build": "tsup",