@decantr/cli 2.9.0 → 2.9.2

package/README.md

@@ -19,8 +19,9 @@ npx @decantr/cli new my-app --blueprint=esports-hq
 
 Use `decantr setup` when you are unsure which path applies. It detects whether the repo is empty, already attached, or a Brownfield app and recommends the next command.
 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 adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, and only applies it when you explicitly accept or merge it.
+Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
 Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr codify --from-audit` when you want project-owned UI patterns and local rules such as button/card/shell/theme standards to appear in future task context and verification.
+In monorepos, app-scoped commands accept `--project <app-path>`. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
 Current starter adapter availability:
@@ -137,7 +138,7 @@ decantr showcase verification --json
 
 `decantr doctor` explains project/workspace state, adoption mode, generated artifacts, local law, visual evidence, design authority signals, CI wiring, and the next command to run. It is the command to reach for when an app is in a monorepo, has stale Decantr files, or someone is not sure what Decantr expects next.
 
-`decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`.
+`decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`; if the root manifest has not pinned Decantr yet, it prints the exact install command first.
 
 `decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
 
@@ -172,7 +173,7 @@ 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. `--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 setup finding, not a crash. `--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`.
+`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:
 

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-N7A3WUZ2.js";
-import "./chunk-V3XAQWKD.js";
-import "./chunk-T5INVSOP.js";
-import "./chunk-TMOCTDYY.js";
+import "./chunk-AXMGQ5IB.js";
+import "./chunk-RXF7ZYGK.js";
+import "./chunk-R57DMFLF.js";
+import "./chunk-DX2UDORT.js";
 import "./chunk-34TZXWIF.js";

package/dist/{chunk-N7A3WUZ2.js → chunk-AXMGQ5IB.js}

@@ -14,22 +14,22 @@ import {
   scaffoldProject,
   syncRegistry,
   writeExecutionPackBundleArtifacts
-} from "./chunk-V3XAQWKD.js";
+} from "./chunk-RXF7ZYGK.js";
 import {
   createWorkspaceHealthReport,
   formatWorkspaceHealthMarkdown,
   formatWorkspaceHealthText,
   listWorkspaceCandidates,
   listWorkspaceProjects,
-  resolveWorkspaceInfo,
   shouldFailWorkspaceHealth
-} from "./chunk-T5INVSOP.js";
+} from "./chunk-R57DMFLF.js";
 import {
   createProjectHealthReport,
   formatProjectHealthMarkdown,
   formatProjectHealthText,
+  resolveWorkspaceInfo,
   shouldFailHealth
-} from "./chunk-TMOCTDYY.js";
+} from "./chunk-DX2UDORT.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -3667,6 +3667,12 @@ function detectPackageManager(root) {
   if (existsSync14(join16(root, "bun.lock")) || existsSync14(join16(root, "bun.lockb"))) return "bun";
   return "unknown";
 }
+function hasWorkspaceMarker(root) {
+  const pkg = readJson(join16(root, "package.json"));
+  return Boolean(
+    existsSync14(join16(root, "pnpm-workspace.yaml")) || existsSync14(join16(root, "turbo.json")) || existsSync14(join16(root, "nx.json")) || pkg?.workspaces
+  );
+}
 function installCommand(packageManager) {
   switch (packageManager) {
     case "pnpm":
@@ -3681,6 +3687,20 @@ function installCommand(packageManager) {
       return "npm install";
   }
 }
+function pinCliCommand(packageManager, root) {
+  switch (packageManager) {
+    case "pnpm":
+      return hasWorkspaceMarker(root) ? "pnpm add -D -w @decantr/cli" : "pnpm add -D @decantr/cli";
+    case "yarn":
+      return "yarn add -D @decantr/cli";
+    case "bun":
+      return "bun add -d @decantr/cli";
+    case "npm":
+      return "npm install -D @decantr/cli";
+    default:
+      return "npm install -D @decantr/cli";
+  }
+}
 function decantrCommand(packageManager) {
   switch (packageManager) {
     case "pnpm":
@@ -3837,7 +3857,7 @@ function writeCiInit(root, options) {
   const provider = options.provider ?? "github";
   if (!localCliPinned(outputRoot)) {
     console.log(
-      `${DIM3}No @decantr/cli dependency was found in the workspace root package.json. The generated command still uses the local package-manager binary path; pin @decantr/cli in devDependencies before relying on CI.${RESET3}`
+      `${DIM3}No @decantr/cli dependency was found in the workspace root package.json. Before relying on CI, pin it with: ${pinCliCommand(packageManager, outputRoot)}${RESET3}`
     );
   }
   if (provider === "generic") {
@@ -4194,6 +4214,7 @@ import { existsSync as existsSync16, readdirSync as readdirSync6, readFileSync a
 import { dirname as dirname3, join as join18, relative as relative4 } from "path";
 import { fileURLToPath } from "url";
 import { isV4 as isV44 } from "@decantr/essence-spec";
+import { collectMissingPackManifestFiles } from "@decantr/verifier";
 var BOLD3 = "\x1B[1m";
 var DIM4 = "\x1B[2m";
 var GREEN4 = "\x1B[32m";
@@ -4339,6 +4360,19 @@ function buildDoctorReport(root, args) {
   const ciFiles = findCiFiles(workspaceRoot);
   const workflowMode = projectJson?.initialized?.workflowMode ?? null;
   const adoptionMode = projectJson?.initialized?.adoptionMode ?? null;
+  const missingPackReferences = workspaceMode ? projects.flatMap(
+    (project) => collectMissingPackManifestFiles(join18(workspaceRoot, project.path)).map(
+      (missing) => `${project.path}/${missing.relativePath}`
+    )
+  ) : collectMissingPackManifestFiles(appRoot).map((missing) => missing.relativePath);
+  const workspaceProjectsMissingManifest = workspaceMode ? projects.map((project) => project.path).filter((projectPath2) => {
+    const projectContextDir = join18(workspaceRoot, projectPath2, ".decantr", "context");
+    return !existsSync16(join18(projectContextDir, "pack-manifest.json"));
+  }) : [];
+  const workspaceProjectsMissingReviewPack = workspaceMode ? projects.map((project) => project.path).filter((projectPath2) => {
+    const projectContextDir = join18(workspaceRoot, projectPath2, ".decantr", "context");
+    return !existsSync16(join18(projectContextDir, "review-pack.json"));
+  }) : [];
   const issues = [];
   if (!essenceVersion && !workspaceMode && !workspaceInfo.requiresProjectSelection) {
     issues.push({
@@ -4384,7 +4418,23 @@ function buildDoctorReport(root, args) {
       category: "generated-artifact",
       severity: "warn",
       message: "Generated context packs are missing or incomplete.",
-      nextCommand: projectPath ? `decantr refresh --project ${projectPath}` : "decantr refresh"
+      nextCommand: projectPath ? `decantr registry compile-packs ${projectPath}/decantr.essence.json --write-context` : "decantr registry compile-packs decantr.essence.json --write-context"
+    });
+  }
+  if (essenceVersion === "4.0.0" && missingPackReferences.length > 0) {
+    issues.push({
+      category: "generated-artifact",
+      severity: "warn",
+      message: `Generated pack manifest references ${missingPackReferences.length} missing file(s).`,
+      nextCommand: projectPath ? `decantr registry compile-packs ${projectPath}/decantr.essence.json --write-context` : "decantr registry compile-packs decantr.essence.json --write-context"
+    });
+  }
+  if (workspaceMode && (workspaceProjectsMissingManifest.length > 0 || workspaceProjectsMissingReviewPack.length > 0 || missingPackReferences.length > 0)) {
+    issues.push({
+      category: "generated-artifact",
+      severity: "warn",
+      message: "One or more attached workspace projects have missing or incomplete generated context packs.",
+      nextCommand: "decantr registry compile-packs <app-path>/decantr.essence.json --write-context"
     });
   }
   if (workflowMode === "brownfield-attach" && !existsSync16(localPatternsPath(appRoot))) {
@@ -4439,9 +4489,12 @@ function buildDoctorReport(root, args) {
       appCandidates: candidates
     },
     generatedArtifacts: {
-      contextDirPresent: existsSync16(contextDir),
-      packManifestPresent,
-      reviewPackPresent
+      contextDirPresent: workspaceMode ? projects.some(
+        (project) => existsSync16(join18(workspaceRoot, project.path, ".decantr", "context"))
+      ) : existsSync16(contextDir),
+      packManifestPresent: workspaceMode ? projects.length > 0 && workspaceProjectsMissingManifest.length === 0 : packManifestPresent,
+      reviewPackPresent: workspaceMode ? projects.length > 0 && workspaceProjectsMissingReviewPack.length === 0 : reviewPackPresent,
+      missingReferencedFiles: missingPackReferences.slice(0, 25)
     },
     localLaw: {
       patternsPresent: existsSync16(localPatternsPath(appRoot)),
@@ -4481,6 +4534,7 @@ function formatDoctorText(report) {
     `  Context directory: ${report.generatedArtifacts.contextDirPresent ? "present" : "missing"}`,
     `  Pack manifest: ${report.generatedArtifacts.packManifestPresent ? "present" : "missing"}`,
     `  Review pack: ${report.generatedArtifacts.reviewPackPresent ? "present" : "missing"}`,
+    `  Manifest references: ${report.generatedArtifacts.missingReferencedFiles.length === 0 ? "complete" : `${report.generatedArtifacts.missingReferencedFiles.length} missing`}`,
     `  Artifact guide: ${report.project.artifactReadmePresent ? "present" : "missing"}`,
     "",
     `${BOLD3}Local Law:${RESET4}`,
@@ -5829,6 +5883,7 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
 import { createHash } from "crypto";
 import { existsSync as existsSync23, readdirSync as readdirSync7, readFileSync as readFileSync17, statSync as statSync6 } from "fs";
 import { join as join25 } from "path";
+import { collectMissingPackManifestFiles as collectMissingPackManifestFiles2 } from "@decantr/verifier";
 import { isV4 as isV46 } from "@decantr/essence-spec";
 var GREEN9 = "\x1B[32m";
 var RED8 = "\x1B[31m";
@@ -5891,6 +5946,16 @@ function checkRefreshFreshness(projectRoot) {
   if (!existsSync23(join25(contextDir, "scaffold.md"))) {
     reasons.push(".decantr/context/scaffold.md is missing.");
   }
+  if (!existsSync23(join25(contextDir, "pack-manifest.json"))) {
+    reasons.push(".decantr/context/pack-manifest.json is missing.");
+  } else {
+    const missingPackFiles = collectMissingPackManifestFiles2(projectRoot);
+    if (missingPackFiles.length > 0) {
+      reasons.push(
+        `pack-manifest.json references missing files: ${missingPackFiles.slice(0, 5).map((missing) => missing.relativePath).join(", ")}${missingPackFiles.length > 5 ? "..." : ""}`
+      );
+    }
+  }
   const newestInput = newestInputMtime(projectRoot);
   const staleFiles = generated.filter((path) => fileMtimeMs(path) > 0 && fileMtimeMs(path) < newestInput).map((path) => path.replace(`${projectRoot}/`, ""));
   if (staleFiles.length > 0) {
@@ -7899,18 +7964,13 @@ async function printRegistryIntelligenceSummary(namespace, jsonOutput = false) {
   }
 }
 async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput = false, writeContext = false) {
-  const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join31(process.cwd(), "decantr.essence.json");
-  if (!existsSync29(resolvedPath)) {
-    throw new Error(`Essence file not found at ${resolvedPath}`);
-  }
-  const essence = JSON.parse(readFileSync22(resolvedPath, "utf-8"));
-  const bundle = await client.compileExecutionPacks(essence, namespace ? { namespace } : void 0);
+  const { resolvedPath, bundle, contextDir } = await compileHostedExecutionPackBundle(
+    essencePath,
+    namespace
+  );
   let writtenContextPaths = [];
   if (writeContext) {
-    const contextDir = join31(process.cwd(), ".decantr", "context");
-    mkdirSync16(contextDir, { recursive: true });
-    const written = writeExecutionPackBundleArtifacts(
+    const written = writeHostedExecutionPackContextArtifacts(
       contextDir,
       bundle
     );
@@ -7934,7 +7994,7 @@ async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput
   console.log(`  Sections: ${typedBundle.sections.length}`);
   console.log(`  Mutations: ${typedBundle.mutations.length}`);
   if (writeContext) {
-    console.log(`  Context bundle: ${join31(process.cwd(), ".decantr", "context")}`);
+    console.log(`  Context bundle: ${contextDir}`);
     console.log(`  Files written: ${writtenContextPaths.length}`);
   }
   console.log("");
@@ -7945,6 +8005,21 @@ async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput
     console.log(`  ${cyan3(route.path)} -> ${pageLabel} [${patterns}]`);
   }
 }
+async function compileHostedExecutionPackBundle(essencePath, namespace) {
+  const client = getPublicAPIClient();
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join31(process.cwd(), "decantr.essence.json");
+  if (!existsSync29(resolvedPath)) {
+    throw new Error(`Essence file not found at ${resolvedPath}`);
+  }
+  const essence = JSON.parse(readFileSync22(resolvedPath, "utf-8"));
+  const bundle = await client.compileExecutionPacks(essence, namespace ? { namespace } : void 0);
+  const contextDir = join31(dirname5(resolvedPath), ".decantr", "context");
+  return { resolvedPath, bundle, contextDir };
+}
+function writeHostedExecutionPackContextArtifacts(contextDir, bundle) {
+  mkdirSync16(contextDir, { recursive: true });
+  return writeExecutionPackBundleArtifacts(contextDir, bundle);
+}
 function resolvePagePackIdForRoute(essencePath, route) {
   if (!existsSync29(essencePath)) {
     throw new Error(`Essence file not found at ${essencePath}`);
@@ -7982,7 +8057,7 @@ async function printHostedSelectedExecutionPack(packType, id, essencePath, names
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join31(process.cwd(), ".decantr", "context");
+    const contextDir = join31(dirname5(resolvedPath), ".decantr", "context");
     mkdirSync16(contextDir, { recursive: true });
     writeFileSync19(
       join31(contextDir, "pack-manifest.json"),
@@ -8028,7 +8103,7 @@ async function printHostedExecutionPackManifest(essencePath, namespace, jsonOutp
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join31(process.cwd(), ".decantr", "context");
+    const contextDir = join31(dirname5(resolvedPath), ".decantr", "context");
     mkdirSync16(contextDir, { recursive: true });
     writeFileSync19(join31(contextDir, "pack-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
     writtenContextDir = contextDir;
@@ -9716,6 +9791,10 @@ function withoutWorkflowOnlyFlags(args) {
 function withProject(command, projectArg) {
   return projectArg ? `${command} --project ${projectArg}` : command;
 }
+function compilePacksCommandForProject(projectArg) {
+  const essencePath = projectArg ? `${projectArg}/decantr.essence.json` : "decantr.essence.json";
+  return `decantr registry compile-packs ${essencePath} --write-context`;
+}
 function firstWorkspaceCandidate(workspaceInfo) {
   return workspaceInfo.appCandidates[0] ?? "apps/web";
 }
@@ -9853,6 +9932,7 @@ async function cmdAdoptWorkflow(args) {
   const runBrowser = flagBoolean(flags, "browser") || Boolean(baseUrl);
   const evidence = flagBoolean(flags, "evidence") || runBrowser;
   const saveBaseline = flagBoolean(flags, "baseline", true) || flagBoolean(flags, "save-baseline");
+  const hydratePacks = flagBoolean(flags, "packs", true) && !flagBoolean(flags, "skip-packs") && !flagBoolean(flags, "offline") && process.env.DECANTR_OFFLINE !== "true";
   const initCi = flagBoolean(flags, "ci") || flagBoolean(flags, "init-ci");
   const assistantBridge = flagString(flags, "assistant-bridge");
   const hasEssence = existsSync29(join31(projectRoot, "decantr.essence.json"));
@@ -9861,6 +9941,9 @@ async function cmdAdoptWorkflow(args) {
     "analyze current app and write .decantr/brownfield intelligence",
     `init --existing ${proposalFlag} as contract-only Brownfield`
   ];
+  if (hydratePacks) {
+    steps.push("hydrate hosted execution packs into the app context");
+  }
   if (runVerify) {
     steps.push(
       runBrowser ? "verify with Project Health, browser evidence, visual manifest, and baseline" : "verify with Project Health and baseline"
@@ -9894,8 +9977,35 @@ async function cmdAdoptWorkflow(args) {
     telemetry: flagBoolean(flags, "telemetry")
   });
   if (process.exitCode && process.exitCode !== 0) return;
+  if (hydratePacks) {
+    try {
+      const { bundle, contextDir } = await compileHostedExecutionPackBundle(
+        join31(projectRoot, "decantr.essence.json")
+      );
+      const written = writeHostedExecutionPackContextArtifacts(
+        contextDir,
+        bundle
+      );
+      console.log(
+        success3(
+          `Hydrated Decantr execution packs (${written.paths.length} files) into ${contextDir}.`
+        )
+      );
+    } catch (e) {
+      console.log(
+        `${YELLOW10}Pack hydration skipped:${RESET16} ${e.message}`
+      );
+      console.log(
+        dim3(
+          `Run ${compilePacksCommandForProject(projectArg)} after adoption if you want hosted page/review packs.`
+        )
+      );
+    }
+  } else if (flagBoolean(flags, "offline") || process.env.DECANTR_OFFLINE === "true") {
+    console.log(dim3("Skipping hosted pack hydration in offline mode."));
+  }
   if (runVerify) {
-    const { cmdHealth } = await import("./health-Q7XF3I5Z.js");
+    const { cmdHealth } = await import("./health-LTDSTNOV.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -9936,7 +10046,7 @@ async function cmdVerifyWorkflow(args) {
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-H5QQJCCI.js");
+    const { cmdWorkspace } = await import("./workspace-53EIHUXB.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -9979,7 +10089,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-Q7XF3I5Z.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-LTDSTNOV.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -10045,6 +10155,7 @@ async function cmdTaskWorkflow(args) {
   const { flags, positional } = parseLooseArgs(args);
   const workspaceInfo = resolveWorkflowProject(flags, "task");
   if (!workspaceInfo) return;
+  const projectArg = flagString(flags, "project");
   const routeInput = positional[0];
   if (!routeInput) {
     console.error(
@@ -10113,7 +10224,7 @@ async function cmdTaskWorkflow(args) {
     localLaw,
     changedFiles: currentChangedFiles,
     changedRoutes,
-    verifyCommand: "decantr verify --brownfield --local-patterns"
+    verifyCommand: withProject("decantr verify --brownfield --local-patterns", projectArg)
   };
   if (flagBoolean(flags, "json")) {
     console.log(JSON.stringify(context, null, 2));
@@ -10154,7 +10265,7 @@ async function cmdTaskWorkflow(args) {
     console.log("");
     console.log(`${BOLD9}Project-owned local law:${RESET16}`);
     console.log(
-      `  ${YELLOW10}Not codified yet.${RESET16} Run ${cyan3("decantr codify --from-audit")} after adoption.`
+      `  ${YELLOW10}Not codified yet.${RESET16} Run ${cyan3(withProject("decantr codify --from-audit", projectArg))} after adoption.`
     );
   }
   if (context.changedFiles.length > 0) {
@@ -10268,7 +10379,7 @@ ${BOLD9}decantr${RESET16} \u2014 Design intelligence for AI-generated UI
 ${BOLD9}Usage:${RESET16}
   decantr setup [--project <path>]
   decantr new <name> [--blueprint=X] [--archetype=X] [--theme=X] [--workflow=greenfield] [--adoption=decantr-css] [--telemetry]
-  decantr adopt [--project <path>] [--base-url <url>] [--evidence] [--ci] [--yes]
+  decantr adopt [--project <path>] [--base-url <url>] [--evidence] [--ci] [--no-packs] [--yes]
   decantr task <route> ["task summary"] [--project <path>] [--since origin/main] [--json]
   decantr verify [--project <path>] [--brownfield] [--local-patterns] [health options]
   decantr ci [--project <path>] [--workspace] [--fail-on error|warn|none]
@@ -10628,11 +10739,11 @@ ${BOLD9}Examples:${RESET16}
 }
 function cmdAdoptHelp() {
   console.log(`
-${BOLD9}decantr adopt${RESET16} \u2014 Brownfield one-liner: analyze, attach, verify, and show the operating loop
+${BOLD9}decantr adopt${RESET16} \u2014 Brownfield one-liner: analyze, attach, hydrate packs, verify, and show the operating loop
 
 ${BOLD9}Usage:${RESET16}
-  decantr adopt [--project <path>] [--yes] [--dry-run]
-  decantr adopt [--project <path>] --base-url <url> [--evidence] [--ci] [--yes]
+  decantr adopt [--project <path>] [--yes] [--dry-run] [--no-packs]
+  decantr adopt [--project <path>] --base-url <url> [--evidence] [--ci] [--yes] [--no-packs]
 
 ${BOLD9}Options:${RESET16}
   --project           App path inside a workspace/monorepo
@@ -10643,6 +10754,7 @@ ${BOLD9}Options:${RESET16}
   --baseline          Save a health baseline (default)
   --no-baseline       Skip baseline save
   --no-verify         Skip the verification step
+  --no-packs          Skip hosted execution-pack hydration
   --ci, --init-ci     Install the Decantr CI gate after adoption
   --telemetry         Opt this project into privacy-filtered CLI product telemetry
   --merge-proposal    Merge the observed proposal into an existing essence
@@ -10921,7 +11033,7 @@ async function main() {
       break;
     }
     case "upgrade": {
-      const { cmdUpgrade } = await import("./upgrade-U2BTWJJJ.js");
+      const { cmdUpgrade } = await import("./upgrade-VON7Y3LG.js");
       const applyFlag = args.includes("--apply");
       await cmdUpgrade(process.cwd(), { apply: applyFlag });
       break;
@@ -10934,9 +11046,12 @@ async function main() {
         );
       }
       const { cmdHeal } = await import("./heal-2BDT7TR5.js");
+      const { flags } = parseLooseArgs(args);
+      const workspaceInfo = resolveWorkflowProject(flags, "check");
+      if (!workspaceInfo) break;
       const telemetryFlag = args.includes("--telemetry");
       const brownfieldFlag = args.includes("--brownfield");
-      await cmdHeal(process.cwd(), { telemetry: telemetryFlag, brownfield: brownfieldFlag });
+      await cmdHeal(workspaceInfo.appRoot, { telemetry: telemetryFlag, brownfield: brownfieldFlag });
       break;
     }
     case "health": {
@@ -10945,7 +11060,7 @@ async function main() {
           cmdHealthHelp();
           break;
         }
-        const { cmdHealth, parseHealthArgs } = await import("./health-Q7XF3I5Z.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-LTDSTNOV.js");
         await cmdHealth(process.cwd(), parseHealthArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -10973,7 +11088,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-B2Y4TKZ5.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-7E2LJS3A.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -10987,7 +11102,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-H5QQJCCI.js");
+        const { cmdWorkspace } = await import("./workspace-53EIHUXB.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error3(e.message));

package/dist/{chunk-TMOCTDYY.js → chunk-DX2UDORT.js}

@@ -8,15 +8,105 @@ import {
 // src/commands/health.ts
 import { execFileSync } from "child_process";
 import { createHash } from "crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { createRequire } from "module";
-import { dirname, isAbsolute, join, resolve } from "path";
+import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import {
   auditProject,
   createContractAssertions,
   createEvidenceBundle
 } from "@decantr/verifier";
+
+// src/workspace.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+function readPackageJson(dir) {
+  const path = join(dir, "package.json");
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function hasWorkspaceMarker(dir) {
+  if (existsSync(join(dir, "pnpm-workspace.yaml")) || existsSync(join(dir, "turbo.json")) || existsSync(join(dir, "nx.json"))) {
+    return true;
+  }
+  const pkg = readPackageJson(dir);
+  return Boolean(pkg?.workspaces);
+}
+function findWorkspaceRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (hasWorkspaceMarker(current)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+function looksLikeApp(dir, options = {}) {
+  const allowSourceDirs = options.allowSourceDirs ?? true;
+  const allowPackageDeps = options.allowPackageDeps ?? true;
+  const pkg = readPackageJson(dir);
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const hasFrontendDependency = Boolean(
+    deps.react || deps["react-dom"] || deps.next || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt
+  );
+  const hasServerOnlyDependency = Boolean(
+    deps.hono || deps.express || deps.fastify || deps.koa || deps["@hapi/hapi"]
+  );
+  if (existsSync(join(dir, "next.config.js")) || existsSync(join(dir, "next.config.ts")) || existsSync(join(dir, "next.config.mjs")) || existsSync(join(dir, "vite.config.ts")) || existsSync(join(dir, "vite.config.js")) || existsSync(join(dir, "angular.json")) || existsSync(join(dir, "svelte.config.js")) || existsSync(join(dir, "svelte.config.ts")) || existsSync(join(dir, "astro.config.mjs"))) {
+    return true;
+  }
+  if (allowSourceDirs && (existsSync(join(dir, "src")) || existsSync(join(dir, "app")) || existsSync(join(dir, "pages")))) {
+    if (hasFrontendDependency) return true;
+    if (hasServerOnlyDependency) return false;
+    return true;
+  }
+  if (!allowPackageDeps) return false;
+  return hasFrontendDependency;
+}
+function listWorkspaceApps(workspaceRoot) {
+  const candidates = [];
+  for (const base of ["apps", "packages"]) {
+    const baseDir = join(workspaceRoot, base);
+    if (!existsSync(baseDir)) continue;
+    for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const candidate = join(baseDir, entry.name);
+      if (looksLikeApp(candidate, {
+        allowSourceDirs: base === "apps",
+        allowPackageDeps: base === "apps"
+      })) {
+        candidates.push(`${base}/${entry.name}`);
+      }
+    }
+  }
+  return candidates.sort();
+}
+function listWorkspaceAppCandidates(workspaceRoot) {
+  return listWorkspaceApps(resolve(workspaceRoot));
+}
+function resolveWorkspaceInfo(cwd, projectArg) {
+  const absoluteCwd = resolve(cwd);
+  const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
+  const appRoot = projectArg ? resolve(absoluteCwd, projectArg) : absoluteCwd;
+  const appCandidates = listWorkspaceApps(workspaceRoot);
+  const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
+  const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 0;
+  return {
+    cwd: absoluteCwd,
+    workspaceRoot,
+    appRoot,
+    projectScope,
+    appCandidates,
+    requiresProjectSelection
+  };
+}
+
+// src/commands/health.ts
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
@@ -29,14 +119,14 @@ var DEFAULT_HEALTH_CI_WORKFLOW_PATH = ".github/workflows/decantr-health.yml";
 var DEFAULT_HEALTH_CI_REPORT_PATH = "decantr-health.md";
 var DEFAULT_HEALTH_CI_JSON_PATH = "decantr-health.json";
 var DEFAULT_HEALTH_CI_CLI_VERSION = "latest";
-var __dirname = dirname(fileURLToPath(import.meta.url));
+var __dirname = dirname2(fileURLToPath(import.meta.url));
 function readProjectMetadata(projectRoot) {
-  const projectJsonPath = join(projectRoot, ".decantr", "project.json");
-  if (!existsSync(projectJsonPath)) {
+  const projectJsonPath = join2(projectRoot, ".decantr", "project.json");
+  if (!existsSync2(projectJsonPath)) {
     return { workflowMode: null, adoptionMode: null, autoBrownfield: false };
   }
   try {
-    const data = JSON.parse(readFileSync(projectJsonPath, "utf-8"));
+    const data = JSON.parse(readFileSync2(projectJsonPath, "utf-8"));
     const workflowMode = typeof data.initialized?.workflowMode === "string" ? data.initialized.workflowMode : null;
     const adoptionMode = typeof data.initialized?.adoptionMode === "string" ? data.initialized.adoptionMode : null;
     return {
@@ -49,12 +139,12 @@ function readProjectMetadata(projectRoot) {
   }
 }
 function loadHealthTemplate(name) {
-  const fromDist = join(__dirname, "..", "src", "templates", name);
-  if (existsSync(fromDist)) return readFileSync(fromDist, "utf-8");
-  const fromSrc = join(__dirname, "..", "templates", name);
-  if (existsSync(fromSrc)) return readFileSync(fromSrc, "utf-8");
-  const fromCommandSrc = join(__dirname, "..", "..", "templates", name);
-  if (existsSync(fromCommandSrc)) return readFileSync(fromCommandSrc, "utf-8");
+  const fromDist = join2(__dirname, "..", "src", "templates", name);
+  if (existsSync2(fromDist)) return readFileSync2(fromDist, "utf-8");
+  const fromSrc = join2(__dirname, "..", "templates", name);
+  if (existsSync2(fromSrc)) return readFileSync2(fromSrc, "utf-8");
+  const fromCommandSrc = join2(__dirname, "..", "..", "templates", name);
+  if (existsSync2(fromCommandSrc)) return readFileSync2(fromCommandSrc, "utf-8");
   throw new Error(`Template not found: ${name}`);
 }
 function renderTemplate(template, vars) {
@@ -149,14 +239,14 @@ function writeProjectHealthCiWorkflow(projectRoot, options = {}) {
   const workflowRelativePath = validateWorkflowPath(
     options.workflowPath || DEFAULT_HEALTH_CI_WORKFLOW_PATH
   );
-  const workflowPath = join(projectRoot, workflowRelativePath);
-  const alreadyExists = existsSync(workflowPath);
+  const workflowPath = join2(projectRoot, workflowRelativePath);
+  const alreadyExists = existsSync2(workflowPath);
   if (alreadyExists && !options.force) {
     throw new Error(
       `${workflowRelativePath} already exists. Re-run with --force to replace it, or use --workflow-path <file>.`
     );
   }
-  mkdirSync(dirname(workflowPath), { recursive: true });
+  mkdirSync(dirname2(workflowPath), { recursive: true });
   writeFileSync(workflowPath, renderProjectHealthCiWorkflow(options), "utf-8");
   const projectPath = options.workspace ? void 0 : validateProjectPath(options.projectPath);
   const result = {
@@ -249,17 +339,17 @@ function slugify(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
 function hashFile(path) {
-  if (!existsSync(path)) return null;
+  if (!existsSync2(path)) return null;
   try {
-    return createHash("sha256").update(readFileSync(path)).digest("hex");
+    return createHash("sha256").update(readFileSync2(path)).digest("hex");
   } catch {
     return null;
   }
 }
 function readJsonFile(path) {
-  if (!existsSync(path)) return null;
+  if (!existsSync2(path)) return null;
   try {
-    return JSON.parse(readFileSync(path, "utf-8"));
+    return JSON.parse(readFileSync2(path, "utf-8"));
   } catch {
     return null;
   }
@@ -290,6 +380,80 @@ function commandsForFinding(source) {
       return ["decantr audit", "decantr health"];
   }
 }
+function commandContextForProject(projectRoot) {
+  const workspaceInfo = resolveWorkspaceInfo(projectRoot);
+  const relativeProjectPath = relative(workspaceInfo.workspaceRoot, projectRoot).replace(/\\/g, "/");
+  const projectPath = relativeProjectPath && !relativeProjectPath.startsWith("..") && !isAbsolute(relativeProjectPath) ? relativeProjectPath : null;
+  const projectFlag = projectPath ? ` --project ${projectPath}` : "";
+  const essencePath = projectPath ? `${projectPath}/decantr.essence.json` : "decantr.essence.json";
+  return {
+    projectPath,
+    compilePacksCommand: `decantr registry compile-packs ${essencePath} --write-context`,
+    verifyCommand: `decantr verify${projectFlag}`,
+    ciCommand: `decantr ci${projectFlag} --fail-on error`
+  };
+}
+function rewriteHealthCommand(command, context) {
+  let rewritten = command.replace(
+    /decantr registry compile-packs decantr\.essence\.json --write-context/g,
+    context.compilePacksCommand
+  );
+  if (!context.projectPath) return rewritten;
+  rewritten = rewritten.replace(
+    /^decantr init --existing\b/,
+    `decantr init --project ${context.projectPath} --existing`
+  );
+  rewritten = rewritten.replace(/^decantr analyze\b/, `decantr analyze --project ${context.projectPath}`);
+  rewritten = rewritten.replace(/^decantr check\b/, `decantr check --project ${context.projectPath}`);
+  rewritten = rewritten.replace(/^decantr audit\b/, context.verifyCommand);
+  rewritten = rewritten.replace(/^decantr health\b/, context.verifyCommand);
+  return rewritten;
+}
+function rewriteSuggestedFixForProject(suggestedFix, context) {
+  if (!suggestedFix) return suggestedFix;
+  return suggestedFix.replace(
+    /decantr registry compile-packs decantr\.essence\.json --write-context/g,
+    context.compilePacksCommand
+  );
+}
+function commandsForProjectFinding(finding, context) {
+  const isPackHydrationFinding = finding.source === "pack" || /pack-manifest|review-pack|compile-packs/i.test(
+    `${finding.id} ${finding.rule ?? ""} ${finding.suggestedFix ?? ""}`
+  );
+  if (isPackHydrationFinding) {
+    return [context.compilePacksCommand, context.verifyCommand];
+  }
+  return [
+    ...new Set(
+      finding.remediation.commands.map((command) => rewriteHealthCommand(command, context))
+    )
+  ];
+}
+function scopeHealthFindingsToProject(projectRoot, findings) {
+  const context = commandContextForProject(projectRoot);
+  return findings.map((finding) => {
+    const suggestedFix = rewriteSuggestedFixForProject(finding.suggestedFix, context);
+    const commands = commandsForProjectFinding(finding, context);
+    return {
+      ...finding,
+      suggestedFix,
+      remediation: {
+        summary: suggestedFix || finding.remediation.summary,
+        commands,
+        prompt: buildRemediationPrompt({
+          id: finding.id,
+          source: finding.source,
+          category: finding.category,
+          severity: finding.severity,
+          message: finding.message,
+          evidence: finding.evidence,
+          suggestedFix,
+          commands
+        })
+      }
+    };
+  });
+}
 function buildRemediationPrompt(input) {
   return [
     "You are fixing one Decantr Project Health finding in this local workspace.",
@@ -377,16 +541,16 @@ function isDuplicateFinding(existing, finding) {
 }
 function resolveOptionalPath(projectRoot, path) {
   if (!path) return void 0;
-  return isAbsolute(path) ? path : resolve(projectRoot, path);
+  return isAbsolute(path) ? path : resolve2(projectRoot, path);
 }
 function hasProjectPlaywright(projectRoot) {
   try {
-    const requireFromProject = createRequire(join(projectRoot, "package.json"));
+    const requireFromProject = createRequire(join2(projectRoot, "package.json"));
     requireFromProject.resolve("playwright");
     return true;
   } catch {
     try {
-      const requireFromProject = createRequire(join(projectRoot, "package.json"));
+      const requireFromProject = createRequire(join2(projectRoot, "package.json"));
       requireFromProject.resolve("@playwright/test");
       return true;
     } catch {
@@ -395,7 +559,7 @@ function hasProjectPlaywright(projectRoot) {
   }
 }
 function loadProjectPlaywright(projectRoot) {
-  const requireFromProject = createRequire(join(projectRoot, "package.json"));
+  const requireFromProject = createRequire(join2(projectRoot, "package.json"));
   for (const packageName of ["playwright", "@playwright/test"]) {
     try {
       const loaded = requireFromProject(packageName);
@@ -485,7 +649,7 @@ async function collectBrowserVerification(projectRoot, options, declaredRoutes)
   const screenshots = [];
   const browserFindings = [];
   const visualRoutes = [];
-  const screenshotDir = join(projectRoot, ".decantr", "evidence", "screenshots");
+  const screenshotDir = join2(projectRoot, ".decantr", "evidence", "screenshots");
   mkdirSync(screenshotDir, { recursive: true });
   let browser = null;
   try {
@@ -496,7 +660,7 @@ async function collectBrowserVerification(projectRoot, options, declaredRoutes)
       const relativePath = browserScreenshotRelativePath(route);
       try {
         await page.goto(url, { waitUntil: "networkidle", timeout: 15e3 });
-        const absoluteScreenshotPath = join(projectRoot, relativePath);
+        const absoluteScreenshotPath = join2(projectRoot, relativePath);
         await page.screenshot({ path: absoluteScreenshotPath, fullPage: true });
         screenshots.push(relativePath);
         visualRoutes.push({
@@ -531,8 +695,8 @@ async function collectBrowserVerification(projectRoot, options, declaredRoutes)
     baseUrl: options.browserBaseUrl,
     routes: visualRoutes
   };
-  const visualManifestPath = join(projectRoot, ".decantr", "evidence", "visual-manifest.json");
-  mkdirSync(dirname(visualManifestPath), { recursive: true });
+  const visualManifestPath = join2(projectRoot, ".decantr", "evidence", "visual-manifest.json");
+  mkdirSync(dirname2(visualManifestPath), { recursive: true });
   writeFileSync(visualManifestPath, JSON.stringify(visualManifest, null, 2) + "\n", "utf-8");
   if (browserFindings.length > 0) {
     const finding = createHealthFinding({
@@ -582,9 +746,9 @@ function flattenDesignTokenKeys(value, prefix = "") {
   return keys;
 }
 function parseDecantrCssTokenNames(projectRoot) {
-  const tokensPath = join(projectRoot, "src", "styles", "tokens.css");
-  if (!existsSync(tokensPath)) return [];
-  const css = readFileSync(tokensPath, "utf-8");
+  const tokensPath = join2(projectRoot, "src", "styles", "tokens.css");
+  if (!existsSync2(tokensPath)) return [];
+  const css = readFileSync2(tokensPath, "utf-8");
   const names = /* @__PURE__ */ new Set();
   for (const match of css.matchAll(/(--d-[\w-]+)\s*:/g)) {
     names.add(match[1]);
@@ -595,7 +759,7 @@ function collectDesignTokenEvidence(projectRoot, designTokensPath) {
   const resolved = resolveOptionalPath(projectRoot, designTokensPath);
   if (!resolved) return void 0;
   const sourceLabel = isAbsolute(designTokensPath ?? "") ? "<design-tokens>" : designTokensPath ?? "<design-tokens>";
-  if (!existsSync(resolved)) {
+  if (!existsSync2(resolved)) {
     return {
       source: sourceLabel,
       status: "error",
@@ -605,7 +769,7 @@ function collectDesignTokenEvidence(projectRoot, designTokensPath) {
     };
   }
   const decantrTokens = parseDecantrCssTokenNames(projectRoot);
-  const parsed = JSON.parse(readFileSync(resolved, "utf-8"));
+  const parsed = JSON.parse(readFileSync2(resolved, "utf-8"));
   const designKeys = flattenDesignTokenKeys(parsed);
   const missing = decantrTokens.filter((token) => {
     const bare = token.replace(/^--/, "");
@@ -648,19 +812,19 @@ function collectDesignTokenFinding(projectRoot, designTokensPath) {
   });
 }
 function baselinePath(projectRoot) {
-  return join(projectRoot, ".decantr", "health-baseline.json");
+  return join2(projectRoot, ".decantr", "health-baseline.json");
 }
 function baselineDiffPath(projectRoot) {
-  return join(projectRoot, ".decantr", "health-baseline-diff.json");
+  return join2(projectRoot, ".decantr", "health-baseline-diff.json");
 }
 function screenshotHashes(projectRoot) {
   const manifest = readJsonFile(
-    join(projectRoot, ".decantr", "evidence", "visual-manifest.json")
+    join2(projectRoot, ".decantr", "evidence", "visual-manifest.json")
   );
   if (manifest?.routes) {
     return manifest.routes.filter((route) => typeof route.screenshot === "string").map((route) => ({
       path: route.screenshot,
-      hash: route.screenshotHash ?? hashFile(join(projectRoot, route.screenshot))
+      hash: route.screenshotHash ?? hashFile(join2(projectRoot, route.screenshot))
     }));
   }
   return [];
@@ -688,7 +852,7 @@ function changedFilesSinceBaseline(projectRoot) {
 }
 function routeImpactsFromChangedFiles(report, changedFiles) {
   const analysis = readJsonFile(
-    join(report.projectRoot, ".decantr", "analysis.json")
+    join2(report.projectRoot, ".decantr", "analysis.json")
   );
   const routeEntries = analysis?.routes?.routes ?? [];
   const impacted = /* @__PURE__ */ new Set();
@@ -721,7 +885,7 @@ function createHealthBaseline(projectRoot, report) {
 }
 function saveHealthBaseline(projectRoot, report) {
   const path = baselinePath(projectRoot);
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(dirname2(path), { recursive: true });
   writeFileSync(
     path,
     JSON.stringify(createHealthBaseline(projectRoot, report), null, 2) + "\n",
@@ -760,7 +924,7 @@ function compareHealthBaseline(projectRoot, report) {
 }
 function saveHealthBaselineComparison(projectRoot, comparison) {
   const path = baselineDiffPath(projectRoot);
-  mkdirSync(dirname(path), { recursive: true });
+  mkdirSync(dirname2(path), { recursive: true });
   writeFileSync(path, JSON.stringify(comparison, null, 2) + "\n", "utf-8");
   return path;
 }
@@ -877,7 +1041,9 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
   if (browserVerification?.finding && !isDuplicateFinding(seen, browserVerification.finding)) {
     findings.push(browserVerification.finding);
   }
-  const finalCounts = countFindings(findings);
+  const scopedFindings = scopeHealthFindingsToProject(projectRoot, findings);
+  const finalCounts = countFindings(scopedFindings);
+  const commandContext = commandContextForProject(projectRoot);
   return {
     $schema: PROJECT_HEALTH_SCHEMA_URL,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -901,7 +1067,7 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
       runtimeChecked: audit.runtimeAudit.routeHintsChecked,
       runtimeMatched: audit.runtimeAudit.routeHintsMatched,
       runtimeCoverageOk: audit.summary.runtimeAuditChecked ? audit.runtimeAudit.routeHintsCoverageOk : null,
-      issues: routeIssuesFromFindings(findings)
+      issues: routeIssuesFromFindings(scopedFindings)
     },
     packs: {
       manifestPresent: Boolean(manifest),
@@ -913,10 +1079,10 @@ async function createProjectHealthReport(projectRoot = process.cwd(), options =
       generatedAt: typeof manifest?.generatedAt === "string" ? manifest.generatedAt : null
     },
     ci: {
-      recommendedCommand: "decantr ci --fail-on error",
+      recommendedCommand: commandContext.ciCommand,
       failOn: "error"
     },
-    findings
+    findings: scopedFindings
   };
 }
 function colorForStatus(status) {
@@ -1014,7 +1180,7 @@ async function createProjectEvidenceBundle(projectRoot, report, options = {}) {
     report,
     audit,
     assertions,
-    workspaceConfigPath: existsSync(join(projectRoot, ".decantr", "workspace.json")) ? join(projectRoot, ".decantr", "workspace.json") : null,
+    workspaceConfigPath: existsSync2(join2(projectRoot, ".decantr", "workspace.json")) ? join2(projectRoot, ".decantr", "workspace.json") : null,
     designTokensPath: resolveOptionalPath(projectRoot, options.designTokensPath) ?? null,
     browser: await browserEvidenceFromOptions(projectRoot, options, report.routes.declared),
     designTokens: collectDesignTokenEvidence(projectRoot, options.designTokensPath)
@@ -1090,8 +1256,8 @@ async function cmdHealth(projectRoot = process.cwd(), options = {}) {
 ` : format === "json" ? formatProjectHealthJson(report) : format === "markdown" ? formatProjectHealthMarkdown(report) : formatProjectHealthText(report);
   const payload = baselineComparison && !options.evidence && format === "text" ? `${basePayload}${formatBaselineComparisonText(baselineComparison)}` : basePayload;
   if (options.output) {
-    const outputPath = isAbsolute(options.output) ? options.output : join(projectRoot, options.output);
-    mkdirSync(dirname(outputPath), { recursive: true });
+    const outputPath = isAbsolute(options.output) ? options.output : join2(projectRoot, options.output);
+    mkdirSync(dirname2(outputPath), { recursive: true });
     writeFileSync(outputPath, payload, "utf-8");
     if (!options.ci) {
       console.log(
@@ -1236,6 +1402,8 @@ function parseHealthArgs(args) {
 }
 
 export {
+  listWorkspaceAppCandidates,
+  resolveWorkspaceInfo,
   renderProjectHealthCiWorkflow,
   writeProjectHealthCiWorkflow,
   collectDesignTokenEvidence,

package/dist/{chunk-T5INVSOP.js → chunk-R57DMFLF.js}

@@ -1,87 +1,12 @@
 import {
-  createProjectHealthReport
-} from "./chunk-TMOCTDYY.js";
+  createProjectHealthReport,
+  listWorkspaceAppCandidates
+} from "./chunk-DX2UDORT.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync2, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { dirname as dirname2, join as join2, relative, resolve as resolve2 } from "path";
-
-// src/workspace.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { dirname, join, resolve } from "path";
-function readPackageJson(dir) {
-  const path = join(dir, "package.json");
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-function hasWorkspaceMarker(dir) {
-  if (existsSync(join(dir, "pnpm-workspace.yaml")) || existsSync(join(dir, "turbo.json")) || existsSync(join(dir, "nx.json"))) {
-    return true;
-  }
-  const pkg = readPackageJson(dir);
-  return Boolean(pkg?.workspaces);
-}
-function findWorkspaceRoot(startDir) {
-  let current = resolve(startDir);
-  while (true) {
-    if (hasWorkspaceMarker(current)) return current;
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-function looksLikeApp(dir, options = {}) {
-  const allowSourceDirs = options.allowSourceDirs ?? true;
-  if (existsSync(join(dir, "next.config.js")) || existsSync(join(dir, "next.config.ts")) || existsSync(join(dir, "next.config.mjs")) || existsSync(join(dir, "vite.config.ts")) || existsSync(join(dir, "vite.config.js")) || existsSync(join(dir, "angular.json")) || existsSync(join(dir, "svelte.config.js")) || existsSync(join(dir, "svelte.config.ts")) || existsSync(join(dir, "astro.config.mjs")) || allowSourceDirs && (existsSync(join(dir, "src")) || existsSync(join(dir, "app")) || existsSync(join(dir, "pages")))) {
-    return true;
-  }
-  const pkg = readPackageJson(dir);
-  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
-  return Boolean(
-    deps.react || deps.next || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt
-  );
-}
-function listWorkspaceApps(workspaceRoot) {
-  const candidates = [];
-  for (const base of ["apps", "packages"]) {
-    const baseDir = join(workspaceRoot, base);
-    if (!existsSync(baseDir)) continue;
-    for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
-      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const candidate = join(baseDir, entry.name);
-      if (looksLikeApp(candidate, { allowSourceDirs: base === "apps" })) {
-        candidates.push(`${base}/${entry.name}`);
-      }
-    }
-  }
-  return candidates.sort();
-}
-function listWorkspaceAppCandidates(workspaceRoot) {
-  return listWorkspaceApps(resolve(workspaceRoot));
-}
-function resolveWorkspaceInfo(cwd, projectArg) {
-  const absoluteCwd = resolve(cwd);
-  const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
-  const appRoot = projectArg ? resolve(absoluteCwd, projectArg) : absoluteCwd;
-  const appCandidates = listWorkspaceApps(workspaceRoot);
-  const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
-  const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 0;
-  return {
-    cwd: absoluteCwd,
-    workspaceRoot,
-    appRoot,
-    projectScope,
-    appCandidates,
-    requiresProjectSelection
-  };
-}
-
-// src/commands/workspace.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var GREEN = "\x1B[32m";
@@ -100,12 +25,12 @@ var DEFAULT_IGNORES = /* @__PURE__ */ new Set([
   "playwright-report"
 ]);
 function workspaceConfigPath(root) {
-  return join2(root, ".decantr", "workspace.json");
+  return join(root, ".decantr", "workspace.json");
 }
 function readWorkspaceConfig(root) {
   const path = workspaceConfigPath(root);
-  if (!existsSync2(path)) return null;
-  return JSON.parse(readFileSync2(path, "utf-8"));
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8"));
 }
 function normalizeProjectPath(raw) {
   const normalized = raw.replace(/^\.\/+/, "").replace(/\/+$/, "");
@@ -124,21 +49,21 @@ function discoverProjectPaths(root, config) {
     if (depth > 6) return;
     const rel = relative(root, dir).replace(/\\/g, "/");
     if (rel && [...ignored].some((entry) => rel === entry || rel.startsWith(`${entry}/`))) return;
-    if (existsSync2(join2(dir, "decantr.essence.json"))) {
+    if (existsSync(join(dir, "decantr.essence.json"))) {
       results.add(rel || ".");
       return;
     }
-    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
       if (ignored.has(entry.name)) continue;
-      walk(join2(dir, entry.name), depth + 1);
+      walk(join(dir, entry.name), depth + 1);
     }
   }
   walk(root, 0);
   return [...results].sort();
 }
 function listWorkspaceProjects(root = process.cwd()) {
-  const workspaceRoot = resolve2(root);
+  const workspaceRoot = resolve(root);
   const config = readWorkspaceConfig(workspaceRoot);
   const byPath = /* @__PURE__ */ new Map();
   for (const project of config?.projects ?? []) {
@@ -146,7 +71,7 @@ function listWorkspaceProjects(root = process.cwd()) {
     byPath.set(path, {
       id: project.id ?? projectIdFromPath(path),
       path,
-      absolutePath: resolve2(workspaceRoot, path),
+      absolutePath: resolve(workspaceRoot, path),
       owner: project.owner ?? null,
       tags: project.tags ?? [],
       criticality: project.criticality ?? "normal",
@@ -159,7 +84,7 @@ function listWorkspaceProjects(root = process.cwd()) {
     byPath.set(path, {
       id: projectIdFromPath(path),
       path,
-      absolutePath: resolve2(workspaceRoot, path),
+      absolutePath: resolve(workspaceRoot, path),
       owner: null,
       tags: [],
       criticality: "normal",
@@ -226,7 +151,7 @@ async function mapLimited(items, concurrency, fn) {
   return results;
 }
 async function createWorkspaceHealthReport(root = process.cwd(), options = {}) {
-  const workspaceRoot = resolve2(root);
+  const workspaceRoot = resolve(root);
   const config = readWorkspaceConfig(workspaceRoot);
   const since = options.since ?? "origin/main";
   const changed = options.changedOnly ? changedPaths(workspaceRoot, since) : /* @__PURE__ */ new Set();
@@ -406,8 +331,8 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
   const payload = options.json ? `${JSON.stringify(report, null, 2)}
 ` : options.markdown ? formatWorkspaceHealthMarkdown(report) : formatWorkspaceHealthText(report);
   if (options.output) {
-    mkdirSync(dirname2(resolve2(workspaceRoot, options.output)), { recursive: true });
-    writeFileSync(resolve2(workspaceRoot, options.output), payload, "utf-8");
+    mkdirSync(dirname(resolve(workspaceRoot, options.output)), { recursive: true });
+    writeFileSync(resolve(workspaceRoot, options.output), payload, "utf-8");
     if (!options.ci)
       console.log(`${GREEN}Wrote Decantr workspace health:${RESET} ${options.output}`);
   } else {
@@ -419,7 +344,6 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
 }
 
 export {
-  resolveWorkspaceInfo,
   listWorkspaceProjects,
   listWorkspaceCandidates,
   createWorkspaceHealthReport,

package/dist/{chunk-V3XAQWKD.js → chunk-RXF7ZYGK.js}

@@ -4989,7 +4989,8 @@ async function refreshDerivedFiles(projectRoot, essence, registry, prefetchedThe
       themeData,
       themeMode: mode,
       voiceTone: storedVoice?.tone ? storedVoice.tone.split(".")[0] + "." : void 0,
-      spatialHints: sectionSpatialHints
+      spatialHints: sectionSpatialHints,
+      adoptionMode: effectiveAdoptionMode
     });
     const sectionContextPath = join2(contextDir, `section-${section.id}.md`);
     writeFileSync2(sectionContextPath, contextContent);
@@ -5345,7 +5346,8 @@ function generateSectionContext(input) {
     themeHints,
     constraints,
     shellInfo,
-    spatialHints
+    spatialHints,
+    adoptionMode
   } = input;
   const lines = [];
   lines.push(`# Section: ${section.id}`);
@@ -5429,9 +5431,15 @@ function generateSectionContext(input) {
   const decoratorDefs = input.themeData?.decorator_definitions;
   const totalDecoratorCount = decoratorDefs && Object.keys(decoratorDefs).length || decorators.length;
   if (totalDecoratorCount > 0) {
-    lines.push(
-      `**Theme decorators:** ${totalDecoratorCount} \`${themeName}-*\` classes \u2014 full Class/Intent/Apply-to table in \`section-${section.id}-pack.md\` (preferred) and DECANTR.md "Decorator Quick Reference". MUST apply.`
-    );
+    if (adoptionMode === "contract-only") {
+      lines.push(
+        `**Theme intent:** ${totalDecoratorCount} \`${themeName}-*\` decorator reference(s) exist, but this project is contract-only. Translate the intent into the app's current styling system instead of applying Decantr decorator classes directly.`
+      );
+    } else {
+      lines.push(
+        `**Theme decorators:** ${totalDecoratorCount} \`${themeName}-*\` classes \u2014 full Class/Intent/Apply-to table in \`section-${section.id}-pack.md\` (preferred) and DECANTR.md "Decorator Quick Reference". MUST apply.`
+      );
+    }
     lines.push("");
   }
   if (themeHints) {
@@ -5454,9 +5462,15 @@ function generateSectionContext(input) {
   }
   const themePrefix = themeName.split("-")[0] || themeName;
   lines.push("");
-  lines.push(
-    `Usage: \`className={css('_flex _col _gap4') + ' d-surface ${themePrefix}-glass'}\` \u2014 atoms via css(), treatments and theme decorators as plain class strings.`
-  );
+  if (adoptionMode === "contract-only") {
+    lines.push(
+      "Usage: implement this section through the app's existing styling authority (design-system components, Tailwind/Sass/theme tokens, CVA variants, or accepted local rules). Do not add `@decantr/css`, `css(...)`, `d-*` treatments, or Decantr token CSS unless adoption mode changes."
+    );
+  } else {
+    lines.push(
+      `Usage: \`className={css('_flex _col _gap4') + ' d-surface ${themePrefix}-glass'}\` \u2014 atoms via css(), treatments and theme decorators as plain class strings.`
+    );
+  }
   lines.push("");
   lines.push("---");
   lines.push("");

package/dist/{health-Q7XF3I5Z.js → health-LTDSTNOV.js}

@@ -10,7 +10,7 @@ import {
   renderProjectHealthCiWorkflow,
   shouldFailHealth,
   writeProjectHealthCiWorkflow
-} from "./chunk-TMOCTDYY.js";
+} from "./chunk-DX2UDORT.js";
 import "./chunk-34TZXWIF.js";
 export {
   cmdHealth,

package/dist/index.js

@@ -1,5 +1,5 @@
-import "./chunk-N7A3WUZ2.js";
-import "./chunk-V3XAQWKD.js";
-import "./chunk-T5INVSOP.js";
-import "./chunk-TMOCTDYY.js";
+import "./chunk-AXMGQ5IB.js";
+import "./chunk-RXF7ZYGK.js";
+import "./chunk-R57DMFLF.js";
+import "./chunk-DX2UDORT.js";
 import "./chunk-34TZXWIF.js";

package/dist/{studio-B2Y4TKZ5.js → studio-7E2LJS3A.js}

@@ -1,9 +1,9 @@
 import {
   createWorkspaceHealthReport
-} from "./chunk-T5INVSOP.js";
+} from "./chunk-R57DMFLF.js";
 import {
   createProjectHealthReport
-} from "./chunk-TMOCTDYY.js";
+} from "./chunk-DX2UDORT.js";
 import {
   sendStudioHealthRefreshedTelemetry,
   sendStudioStartedTelemetry

package/dist/{upgrade-U2BTWJJJ.js → upgrade-VON7Y3LG.js}

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

package/dist/{workspace-H5QQJCCI.js → workspace-53EIHUXB.js}

@@ -7,8 +7,8 @@ import {
   listWorkspaceProjects,
   parseWorkspaceArgs,
   shouldFailWorkspaceHealth
-} from "./chunk-T5INVSOP.js";
-import "./chunk-TMOCTDYY.js";
+} from "./chunk-R57DMFLF.js";
+import "./chunk-DX2UDORT.js";
 import "./chunk-34TZXWIF.js";
 export {
   cmdWorkspace,

package/package.json

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