@decantr/cli 2.9.2 → 2.9.4

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

@@ -22,14 +22,14 @@ import {
   listWorkspaceCandidates,
   listWorkspaceProjects,
   shouldFailWorkspaceHealth
-} from "./chunk-R57DMFLF.js";
+} from "./chunk-VCUFZB45.js";
 import {
   createProjectHealthReport,
   formatProjectHealthMarkdown,
   formatProjectHealthText,
   resolveWorkspaceInfo,
   shouldFailHealth
-} from "./chunk-DX2UDORT.js";
+} from "./chunk-FACL3NXU.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -46,11 +46,11 @@ 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";
-import { basename as basename3, dirname as dirname5, isAbsolute, join as join31, resolve as resolve4 } from "path";
+import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute3, join as join31, relative as relative7, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { evaluateGuard, isV4 as isV49, validateEssence as validateEssence2 } from "@decantr/essence-spec";
 import {
@@ -1772,6 +1772,20 @@ function readV4Essence(projectRoot) {
 function writeEssence(essencePath, essence) {
   writeFileSync6(essencePath, JSON.stringify(essence, null, 2) + "\n");
 }
+function readFlagValue(args, name) {
+  const prefix = `--${name}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === `--${name}` && args[index + 1]) return args[index + 1];
+    if (arg.startsWith(prefix)) return arg.slice(prefix.length);
+  }
+  return void 0;
+}
+function normalizeRoute(route) {
+  const trimmed = route.trim();
+  if (!trimmed || trimmed === "/") return "/";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
 async function cmdAddSection(archetypeId, args, projectRoot = process.cwd()) {
   if (!archetypeId) {
     console.error(`${RED}Usage: decantr add section <archetypeId>${RESET}`);
@@ -1847,12 +1861,27 @@ async function cmdAddPage(path, args, projectRoot = process.cwd()) {
     process.exitCode = 1;
     return;
   }
+  const route = normalizeRoute(readFlagValue(args, "route") ?? pageId);
+  const routes = essence.blueprint.routes ??= {};
+  const existingRoute = routes[route];
+  if (existingRoute) {
+    console.error(
+      `${RED}Route "${route}" already maps to ${existingRoute.section}/${existingRoute.page}.${RESET}`
+    );
+    console.error(`${DIM}Pass a unique route with --route /some-path.${RESET}`);
+    process.exitCode = 1;
+    return;
+  }
   section.pages.push({
     id: pageId,
+    route,
     layout: ["hero"]
   });
+  routes[route] = { section: sectionId, page: pageId };
   writeEssence(essencePath, essence);
-  console.log(`${GREEN}Added page "${pageId}" to section "${sectionId}".${RESET}`);
+  console.log(
+    `${GREEN}Added page "${pageId}" to section "${sectionId}" at route "${route}".${RESET}`
+  );
   const registryClient = new RegistryClient({
     cacheDir: join6(projectRoot, ".decantr", "cache")
   });
@@ -1869,10 +1898,7 @@ async function cmdAddFeature(feature, args, projectRoot = process.cwd()) {
   if (!loaded) return;
   const { essence, essencePath } = loaded;
   let sectionId;
-  const sectionIdx = args.indexOf("--section");
-  if (sectionIdx !== -1 && args[sectionIdx + 1]) {
-    sectionId = args[sectionIdx + 1];
-  }
+  sectionId = readFlagValue(args, "section");
   if (sectionId) {
     const sections = essence.blueprint.sections;
     const section = sections.find((s) => s.id === sectionId);
@@ -1901,7 +1927,7 @@ async function cmdAddFeature(feature, args, projectRoot = process.cwd()) {
 
 // src/commands/analyze.ts
 import { existsSync as existsSync12, mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
-import { join as join14 } from "path";
+import { join as join14, relative as relative2 } from "path";
 
 // src/analyzers/components.ts
 import { existsSync as existsSync5, readdirSync, statSync as statSync2 } from "fs";
@@ -2957,6 +2983,10 @@ ${BOLD}Analyzing project...${RESET2}
   const doctrine = createDoctrineMap(ambient);
   const initSeed = createBrownfieldInitSeed(project, layout, styling);
   initSeed.projectScope = workspace?.projectScope ?? "single-app";
+  const projectLabel = workspace && workspace.appRoot !== workspace.workspaceRoot ? relative2(workspace.workspaceRoot, workspace.appRoot).replace(/\\/g, "/") : null;
+  const projectFlag = projectLabel ? ` --project ${projectLabel}` : "";
+  const reportDisplayPath = projectLabel ? `${projectLabel}/.decantr/brownfield-report.md` : ".decantr/brownfield-report.md";
+  const recommendedAttachCommand = `decantr init${projectFlag} --existing --accept-proposal`;
   const proposal = createBrownfieldProposal({
     project,
     routes,
@@ -2996,7 +3026,7 @@ ${BOLD}Analyzing project...${RESET2}
         adoptionMode: "contract-only",
         initSeedPath: ".decantr/init-seed.json",
         proposalPath: ".decantr/observed-essence.proposal.json",
-        recommendedCommand: "decantr init --existing --accept-proposal"
+        recommendedCommand: recommendedAttachCommand
       },
       hybrid: {
         ownerCommands: [
@@ -3096,7 +3126,7 @@ ${DIM2}Written to:${RESET2} ${outputPath}`);
   console.log(`${DIM2}Enrichment backlog:${RESET2} ${intelligenceArtifacts.backlogPath}`);
   console.log(
     `
-${YELLOW}Next step:${RESET2} Review ${BOLD}.decantr/brownfield-report.md${RESET2}, then run ${BOLD}decantr init --existing --accept-proposal${RESET2} to attach Decantr using the observed proposal.
+${YELLOW}Next step:${RESET2} Review ${BOLD}${reportDisplayPath}${RESET2}, then run ${BOLD}${recommendedAttachCommand}${RESET2} to attach Decantr using the observed proposal.
 `
   );
   await sendAnalyzeCompletedTelemetry({
@@ -3119,12 +3149,12 @@ ${YELLOW}Next step:${RESET2} Review ${BOLD}.decantr/brownfield-report.md${RESET2
 
 // src/commands/ci.ts
 import { existsSync as existsSync14, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "fs";
-import { dirname as dirname2, join as join16, relative as relative3, resolve } from "path";
+import { dirname as dirname2, join as join16, relative as relative4, resolve } from "path";
 
 // src/local-law.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync13, mkdirSync as mkdirSync8, readdirSync as readdirSync5, readFileSync as readFileSync11, statSync as statSync5, writeFileSync as writeFileSync9 } from "fs";
-import { basename as basename2, extname, join as join15, relative as relative2, sep } from "path";
+import { basename as basename2, extname, join as join15, relative as relative3, sep } from "path";
 import { isV4 as isV43 } from "@decantr/essence-spec";
 var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
   ".astro",
@@ -3565,7 +3595,7 @@ function listSourceFiles(projectRoot, maxFiles) {
       if (stat.isDirectory()) {
         visit(absolute);
       } else if (stat.isFile() && SOURCE_EXTENSIONS.has(extname(entry))) {
-        files.push({ absolute, relative: normalizePath(relative2(projectRoot, absolute)) });
+        files.push({ absolute, relative: normalizePath(relative3(projectRoot, absolute)) });
       }
     }
   };
@@ -3653,7 +3683,8 @@ function parseCiArgs(args) {
   return options;
 }
 function parseProvider(value) {
-  return value === "generic" ? "generic" : "github";
+  if (value === "github" || value === "generic") return value;
+  throw new Error("Invalid --provider value. Use github or generic.");
 }
 function detectPackageManager(root) {
   const pkg = readJson(join16(root, "package.json"));
@@ -3843,6 +3874,9 @@ jobs:
 }
 function writeCiInit(root, options) {
   const workspaceInfo = resolveWorkspaceInfo(root, options.project);
+  if (options.project && !existsSync14(workspaceInfo.appRoot)) {
+    throw new Error(`Project path does not exist: ${options.project}`);
+  }
   if (workspaceInfo.requiresProjectSelection && !options.workspace) {
     const candidate = workspaceInfo.appCandidates[0] ?? "apps/web";
     throw new Error(
@@ -3850,7 +3884,7 @@ function writeCiInit(root, options) {
     );
   }
   const outputRoot = workspaceInfo.workspaceRoot;
-  const projectPath = options.project ?? (options.workspace || workspaceInfo.appRoot === workspaceInfo.workspaceRoot ? void 0 : relative3(workspaceInfo.workspaceRoot, workspaceInfo.appRoot).replace(/\\/g, "/"));
+  const projectPath = options.project ?? (options.workspace || workspaceInfo.appRoot === workspaceInfo.workspaceRoot ? void 0 : relative4(workspaceInfo.workspaceRoot, workspaceInfo.appRoot).replace(/\\/g, "/"));
   const packageManager = detectPackageManager(outputRoot);
   const command = decantrCommand(packageManager);
   const failOn = options.failOn ?? "error";
@@ -3933,6 +3967,10 @@ async function runWorkspaceCi(root, options) {
 }
 async function runProjectCi(root, options) {
   const workspaceInfo = resolveWorkspaceInfo(root, options.project);
+  if (options.project && !existsSync14(workspaceInfo.appRoot)) {
+    console.error(`${RED2}Project path does not exist: ${options.project}${RESET3}`);
+    return 1;
+  }
   if (workspaceInfo.requiresProjectSelection) {
     const candidate = workspaceInfo.appCandidates[0] ?? "apps/web";
     console.error(`${RED2}Decantr CI needs an app path in this monorepo.${RESET3}`);
@@ -3983,16 +4021,16 @@ ${BOLD2}Examples:${RESET3}
 `);
 }
 async function cmdCi(args = ["ci"], root = process.cwd()) {
-  const options = parseCiArgs(args);
   try {
+    const options = parseCiArgs(args);
     if (options.init) {
       writeCiInit(root, options);
       return;
     }
     const exitCode = options.workspace ? await runWorkspaceCi(root, options) : await runProjectCi(root, options);
     if (exitCode !== 0) process.exitCode = exitCode;
-  } catch (error4) {
-    console.error(`${RED2}${error4.message}${RESET3}`);
+  } catch (error3) {
+    console.error(`${RED2}${error3.message}${RESET3}`);
     process.exitCode = 1;
   }
 }
@@ -4211,7 +4249,7 @@ function cmdCreate(type, name, projectRoot = process.cwd()) {
 
 // src/commands/doctor.ts
 import { existsSync as existsSync16, readdirSync as readdirSync6, readFileSync as readFileSync13 } from "fs";
-import { dirname as dirname3, join as join18, relative as relative4 } from "path";
+import { dirname as dirname3, join as join18, relative as relative5 } from "path";
 import { fileURLToPath } from "url";
 import { isV4 as isV44 } from "@decantr/essence-spec";
 import { collectMissingPackManifestFiles } from "@decantr/verifier";
@@ -4230,6 +4268,10 @@ function readJson2(path) {
     return null;
   }
 }
+function isContractOnlyProject(projectRoot) {
+  const projectJson = readJson2(join18(projectRoot, ".decantr", "project.json"));
+  return projectJson?.initialized?.adoptionMode === "contract-only";
+}
 function readCliPackageVersion() {
   const packagePath = join18(dirname3(fileURLToPath(import.meta.url)), "..", "..", "package.json");
   const srcPackagePath = join18(dirname3(fileURLToPath(import.meta.url)), "..", "package.json");
@@ -4255,8 +4297,28 @@ function localCliDependency(root) {
   const pkg = readPackageJson(root);
   return pkg?.devDependencies?.["@decantr/cli"] ?? pkg?.dependencies?.["@decantr/cli"] ?? null;
 }
+function hasWorkspaceMarker2(root) {
+  const pkg = readPackageJson(root);
+  return Boolean(
+    existsSync16(join18(root, "pnpm-workspace.yaml")) || existsSync16(join18(root, "turbo.json")) || existsSync16(join18(root, "nx.json")) || pkg?.workspaces
+  );
+}
+function pinCliCommand2(packageManager, root) {
+  switch (packageManager) {
+    case "pnpm":
+      return hasWorkspaceMarker2(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 rel(root, path) {
-  const value = relative4(root, path).replace(/\\/g, "/");
+  const value = relative5(root, path).replace(/\\/g, "/");
   return value || ".";
 }
 function hasAnyFile(dir, names) {
@@ -4335,14 +4397,20 @@ function statusFromIssues(issues, essenceVersion) {
   return "healthy";
 }
 function buildDoctorReport(root, args) {
-  const projectIdx = args.indexOf("--project");
-  const projectArg = projectIdx !== -1 && args[projectIdx + 1] ? args[projectIdx + 1] : void 0;
+  let projectArg;
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--project" && args[index + 1]) projectArg = args[++index];
+    else if (arg.startsWith("--project=")) projectArg = arg.slice("--project=".length);
+  }
   const workspaceMode = args.includes("--workspace");
   const workspaceInfo = resolveWorkspaceInfo(root, projectArg);
   const workspaceRoot = workspaceInfo.workspaceRoot;
   const appRoot = workspaceMode ? workspaceRoot : workspaceInfo.appRoot;
+  const projectMissing = Boolean(projectArg && !existsSync16(appRoot));
   const projectPath = appRoot === workspaceRoot ? null : rel(workspaceRoot, appRoot);
   const packageManager = detectPackageManager2(workspaceRoot);
+  const cliDependency = localCliDependency(workspaceRoot);
   const detected = detectProject(appRoot);
   const projectJson = readJson2(join18(appRoot, ".decantr", "project.json"));
   const essence = readJson2(join18(appRoot, "decantr.essence.json"));
@@ -4360,6 +4428,7 @@ function buildDoctorReport(root, args) {
   const ciFiles = findCiFiles(workspaceRoot);
   const workflowMode = projectJson?.initialized?.workflowMode ?? null;
   const adoptionMode = projectJson?.initialized?.adoptionMode ?? null;
+  const packHydrationOptional = adoptionMode === "contract-only";
   const missingPackReferences = workspaceMode ? projects.flatMap(
     (project) => collectMissingPackManifestFiles(join18(workspaceRoot, project.path)).map(
       (missing) => `${project.path}/${missing.relativePath}`
@@ -4367,14 +4436,21 @@ function buildDoctorReport(root, args) {
   ) : 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"));
+    return !isContractOnlyProject(join18(workspaceRoot, projectPath2)) && !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"));
+    return !isContractOnlyProject(join18(workspaceRoot, projectPath2)) && !existsSync16(join18(projectContextDir, "review-pack.json"));
   }) : [];
   const issues = [];
-  if (!essenceVersion && !workspaceMode && !workspaceInfo.requiresProjectSelection) {
+  if (projectMissing) {
+    issues.push({
+      category: "workspace",
+      severity: "error",
+      message: `Project path does not exist: ${projectArg}`,
+      nextCommand: "decantr workspace list"
+    });
+  } else if (!essenceVersion && !workspaceMode && !workspaceInfo.requiresProjectSelection) {
     issues.push({
       category: "setup",
       severity: "error",
@@ -4405,6 +4481,14 @@ function buildDoctorReport(root, args) {
       nextCommand: "decantr setup"
     });
   }
+  if ((essenceVersion === "4.0.0" || workspaceMode || projects.length > 0) && !cliDependency) {
+    issues.push({
+      category: "ci",
+      severity: "info",
+      message: "@decantr/cli is not pinned in the workspace root package.json.",
+      nextCommand: pinCliCommand2(packageManager, workspaceRoot)
+    });
+  }
   if (essenceVersion === "4.0.0" && !artifactReadmePresent) {
     issues.push({
       category: "generated-artifact",
@@ -4413,7 +4497,7 @@ function buildDoctorReport(root, args) {
       nextCommand: "decantr refresh"
     });
   }
-  if (essenceVersion === "4.0.0" && (!existsSync16(contextDir) || !packManifestPresent)) {
+  if (essenceVersion === "4.0.0" && !packHydrationOptional && (!existsSync16(contextDir) || !packManifestPresent)) {
     issues.push({
       category: "generated-artifact",
       severity: "warn",
@@ -4473,7 +4557,7 @@ function buildDoctorReport(root, args) {
     projectPath,
     packageManager,
     cli: {
-      localDependency: localCliDependency(workspaceRoot),
+      localDependency: cliDependency,
       runningVersion: readCliPackageVersion()
     },
     project: {
@@ -4584,18 +4668,34 @@ async function cmdDoctor(args = ["doctor"], root = process.cwd()) {
   const report = buildDoctorReport(root, args);
   if (args.includes("--json")) {
     console.log(JSON.stringify(report, null, 2));
+    if (report.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
     return;
   }
   process.stdout.write(formatDoctorText(report));
+  if (report.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
 }
 
 // src/commands/export.ts
 import { existsSync as existsSync17, mkdirSync as mkdirSync11, readFileSync as readFileSync14, writeFileSync as writeFileSync12 } from "fs";
-import { dirname as dirname4, join as join19 } from "path";
+import { dirname as dirname4, isAbsolute, join as join19 } from "path";
 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);
+}
 var SHADCN_MAP = {
   "--d-bg": "--background",
   "--d-text": "--foreground",
@@ -4744,9 +4844,7 @@ function generateFigmaTokens(tokens) {
   const out = {};
   for (const [key, value] of tokens) {
     const name = key.replace(/^--/, "").replace(/-/g, ".");
-    const type = /color|bg|surface|text|border|primary|secondary|accent|error|warning|success|info/.test(
-      key
-    ) ? "color" : /radius/.test(key) ? "borderRadius" : /shadow/.test(key) ? "shadow" : /gap|space|spacing/.test(key) ? "dimension" : "string";
+    const type = /color|bg|surface|text|border|primary|secondary|accent|error|warning|success|info/.test(key) ? "color" : /radius/.test(key) ? "borderRadius" : /shadow/.test(key) ? "shadow" : /gap|space|spacing/.test(key) ? "dimension" : "string";
     out[name] = {
       $type: type,
       $value: value,
@@ -4765,9 +4863,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;
   }
@@ -4780,7 +4878,11 @@ async function cmdExport(target, projectRoot, options = {}) {
   }
   switch (target) {
     case "shadcn": {
-      const cssOut = options.output ?? join19(projectRoot, "src", "styles", "shadcn-theme.css");
+      const cssOut = resolveOutputPath(
+        projectRoot,
+        options.output,
+        join19(projectRoot, "src", "styles", "shadcn-theme.css")
+      );
       const jsonOut = join19(projectRoot, "components.json");
       ensureDir(cssOut);
       writeFileSync12(cssOut, generateShadcnCSS(tokens), "utf-8");
@@ -4791,7 +4893,11 @@ async function cmdExport(target, projectRoot, options = {}) {
       break;
     }
     case "tailwind": {
-      const out = options.output ?? join19(projectRoot, "tailwind.decantr.config.ts");
+      const out = resolveOutputPath(
+        projectRoot,
+        options.output,
+        join19(projectRoot, "tailwind.decantr.config.ts")
+      );
       ensureDir(out);
       writeFileSync12(out, generateTailwindConfig(tokens), "utf-8");
       console.log(`${GREEN5}Exported Tailwind config:${RESET5}`);
@@ -4799,7 +4905,11 @@ async function cmdExport(target, projectRoot, options = {}) {
       break;
     }
     case "css-vars": {
-      const out = options.output ?? join19(projectRoot, "decantr-tokens.css");
+      const out = resolveOutputPath(
+        projectRoot,
+        options.output,
+        join19(projectRoot, "decantr-tokens.css")
+      );
       ensureDir(out);
       writeFileSync12(out, generateCSSVars(tokens), "utf-8");
       console.log(`${GREEN5}Exported CSS variables:${RESET5}`);
@@ -4807,7 +4917,11 @@ async function cmdExport(target, projectRoot, options = {}) {
       break;
     }
     case "figma-tokens": {
-      const out = options.output ?? join19(projectRoot, ".decantr", "design", "figma-tokens.json");
+      const out = resolveOutputPath(
+        projectRoot,
+        options.output,
+        join19(projectRoot, ".decantr", "design", "figma-tokens.json")
+      );
       ensureDir(out);
       writeFileSync12(out, generateFigmaTokens(tokens), "utf-8");
       console.log(`${GREEN5}Exported Figma/Tokens Studio tokens:${RESET5}`);
@@ -4830,7 +4944,6 @@ import { join as join20 } from "path";
 var BOLD4 = "\x1B[1m";
 var DIM6 = "\x1B[2m";
 var RESET6 = "\x1B[0m";
-var RED5 = "\x1B[31m";
 var GREEN6 = "\x1B[32m";
 var CYAN3 = "\x1B[36m";
 var YELLOW3 = "\x1B[33m";
@@ -4838,9 +4951,6 @@ var MAGENTA = "\x1B[35m";
 function success(text) {
   return `${GREEN6}${text}${RESET6}`;
 }
-function error(text) {
-  return `${RED5}${text}${RESET6}`;
-}
 function dim(text) {
   return `${DIM6}${text}${RESET6}`;
 }
@@ -5056,9 +5166,16 @@ async function cmdMagic(prompt, projectRoot, options) {
   console.log("");
   const essencePath = join20(projectRoot, "decantr.essence.json");
   if (existsSync18(essencePath)) {
-    console.log(error("  decantr.essence.json already exists in this directory."));
-    console.log(dim("  Remove it first or use a different directory."));
-    process.exitCode = 1;
+    const projectFlag = options.projectLabel ? ` --project ${options.projectLabel}` : "";
+    console.log(`${YELLOW3} Decantr is already attached to this project.${RESET6}`);
+    console.log(
+      dim(" decantr magic is greenfield-first; use task-time context for existing apps.")
+    );
+    console.log("");
+    console.log(`${BOLD4}Recommended next steps:${RESET6}`);
+    console.log(`  ${cyan(`decantr doctor${projectFlag}`)}`);
+    console.log(`  ${cyan(`decantr task <route> "${prompt}"${projectFlag}`)}`);
+    console.log(`  ${cyan(`decantr verify --brownfield --local-patterns${projectFlag}`)}`);
     return;
   }
   const detected = detectProject(projectRoot);
@@ -5073,8 +5190,9 @@ async function cmdMagic(prompt, projectRoot, options) {
       dim(" Running brownfield analysis instead so you can attach Decantr deliberately.\n")
     );
     await cmdAnalyze(projectRoot);
+    const projectFlag = options.projectLabel ? ` --project ${options.projectLabel}` : "";
     console.log(
-      `${BOLD4}Recommended next step:${RESET6} ${cyan("decantr init --existing --accept-proposal")}`
+      `${BOLD4}Recommended next step:${RESET6} ${cyan(`decantr init${projectFlag} --existing --accept-proposal`)}`
     );
     console.log("");
     return;
@@ -5400,7 +5518,7 @@ import {
   validateLegacyEssenceForMigration
 } from "@decantr/essence-spec";
 var GREEN7 = "\x1B[32m";
-var RED6 = "\x1B[31m";
+var RED5 = "\x1B[31m";
 var YELLOW4 = "\x1B[33m";
 var RESET7 = "\x1B[0m";
 var DIM7 = "\x1B[2m";
@@ -5468,13 +5586,13 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
   const inlineTarget = hasInlineTarget?.split("=")[1];
   const requestedTarget = inlineTarget ?? target;
   if (requestedTarget !== "v4") {
-    console.error(`${RED6}Usage: decantr migrate --to v4${RESET7}`);
+    console.error(`${RED5}Usage: decantr migrate --to v4${RESET7}`);
     process.exitCode = 1;
     return;
   }
   const essencePath = join21(projectRoot, "decantr.essence.json");
   if (!existsSync19(essencePath)) {
-    console.error(`${RED6}No decantr.essence.json found. Run \`decantr init\` first.${RESET7}`);
+    console.error(`${RED5}No decantr.essence.json found. Run \`decantr init\` first.${RESET7}`);
     process.exitCode = 1;
     return;
   }
@@ -5485,7 +5603,7 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
     return;
   }
   if (!result.success) {
-    console.error(`${RED6}Migration failed: ${result.error}${RESET7}`);
+    console.error(`${RED5}Migration failed: ${result.error}${RESET7}`);
     process.exitCode = 1;
     return;
   }
@@ -5565,7 +5683,7 @@ function seedOfflineRegistry(projectDir, workspaceRoot) {
 var BOLD5 = "\x1B[1m";
 var DIM8 = "\x1B[2m";
 var RESET8 = "\x1B[0m";
-var RED7 = "\x1B[31m";
+var RED6 = "\x1B[31m";
 var GREEN8 = "\x1B[32m";
 var CYAN4 = "\x1B[36m";
 var YELLOW5 = "\x1B[33m";
@@ -5577,8 +5695,8 @@ ${BOLD5}${text}${RESET8}
 function success2(text) {
   return `${GREEN8}${text}${RESET8}`;
 }
-function error2(text) {
-  return `${RED7}${text}${RESET8}`;
+function error(text) {
+  return `${RED6}${text}${RESET8}`;
 }
 function dim2(text) {
   return `${DIM8}${text}${RESET8}`;
@@ -5685,13 +5803,13 @@ async function cmdNewProject(projectName, options) {
   const shouldBootstrapRuntime = Boolean(bootstrapAdapter && inferredAdoption === "decantr-css");
   if (!/^[a-z0-9][a-z0-9._-]*$/i.test(projectName)) {
     console.error(
-      error2("Invalid project name. Use alphanumeric characters, hyphens, dots, or underscores.")
+      error("Invalid project name. Use alphanumeric characters, hyphens, dots, or underscores.")
     );
     process.exitCode = 1;
     return;
   }
   if (existsSync21(projectDir)) {
-    console.error(error2(`Directory "${projectName}" already exists.`));
+    console.error(error(`Directory "${projectName}" already exists.`));
     process.exitCode = 1;
     return;
   }
@@ -5699,7 +5817,7 @@ async function cmdNewProject(projectName, options) {
   try {
     initFlags = buildNewProjectInitArgs(options, inferredAdoption);
   } catch (err) {
-    console.error(error2(err.message));
+    console.error(error(err.message));
     process.exitCode = 1;
     return;
   }
@@ -5882,11 +6000,11 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
 // src/commands/refresh.ts
 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 { isAbsolute as isAbsolute2, join as join25, relative as relative6 } 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";
+var RED7 = "\x1B[31m";
 var DIM9 = "\x1B[2m";
 var RESET9 = "\x1B[0m";
 function hashFile(path) {
@@ -5937,18 +6055,29 @@ function newestInputMtime(projectRoot) {
     fileMtimeMs(join25(projectRoot, ".decantr", "project.json"))
   );
 }
+function isContractOnlyProject2(projectRoot) {
+  const projectJsonPath = join25(projectRoot, ".decantr", "project.json");
+  if (!existsSync23(projectJsonPath)) return false;
+  try {
+    const projectJson = JSON.parse(readFileSync17(projectJsonPath, "utf-8"));
+    return projectJson.initialized?.adoptionMode === "contract-only";
+  } catch {
+    return false;
+  }
+}
 function checkRefreshFreshness(projectRoot) {
   const contextDir = join25(projectRoot, ".decantr", "context");
   const generated = trackedGeneratedFiles(projectRoot);
   const reasons = [];
+  const packHydrationOptional = isContractOnlyProject2(projectRoot);
   if (!existsSync23(join25(projectRoot, "DECANTR.md"))) reasons.push("DECANTR.md is missing.");
   if (!existsSync23(contextDir)) reasons.push(".decantr/context is missing.");
   if (!existsSync23(join25(contextDir, "scaffold.md"))) {
     reasons.push(".decantr/context/scaffold.md is missing.");
   }
-  if (!existsSync23(join25(contextDir, "pack-manifest.json"))) {
+  if (!packHydrationOptional && !existsSync23(join25(contextDir, "pack-manifest.json"))) {
     reasons.push(".decantr/context/pack-manifest.json is missing.");
-  } else {
+  } else if (existsSync23(join25(contextDir, "pack-manifest.json"))) {
     const missingPackFiles = collectMissingPackManifestFiles2(projectRoot);
     if (missingPackFiles.length > 0) {
       reasons.push(
@@ -5999,10 +6128,19 @@ function summarizeChanges(projectRoot, before, after) {
     unchanged: unchanged.sort()
   };
 }
-function printRefreshSummary(summary) {
+function displayGeneratedPath(summary, file, displayRoot) {
+  if (!displayRoot) return file;
+  const absolutePath = join25(summary.projectRoot, file);
+  const relativePath = relative6(displayRoot, absolutePath).replace(/\\/g, "/");
+  if (relativePath && !relativePath.startsWith("..") && !isAbsolute2(relativePath)) {
+    return relativePath;
+  }
+  return absolutePath;
+}
+function printRefreshSummary(summary, displayRoot) {
   if (summary.check) {
     if (summary.stale) {
-      console.log(`${RED8}Generated Decantr context is stale.${RESET9}`);
+      console.log(`${RED7}Generated Decantr context is stale.${RESET9}`);
       for (const reason of summary.reasons) console.log(`  ${reason}`);
       console.log(`${DIM9}Run \`decantr refresh\` to regenerate derived files.${RESET9}`);
     } else {
@@ -6018,7 +6156,9 @@ function printRefreshSummary(summary) {
   for (const [label, files] of groups) {
     if (files.length === 0) continue;
     console.log(`${GREEN9}${label}:${RESET9}`);
-    for (const file of files) console.log(`  ${DIM9}${file}${RESET9}`);
+    for (const file of files) {
+      console.log(`  ${DIM9}${displayGeneratedPath(summary, file, displayRoot)}${RESET9}`);
+    }
   }
   if (groups.every(([, files]) => files.length === 0)) {
     console.log(`${GREEN9}Generated files were already current.${RESET9}`);
@@ -6027,7 +6167,7 @@ function printRefreshSummary(summary) {
 async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
   const essencePath = join25(projectRoot, "decantr.essence.json");
   if (!existsSync23(essencePath)) {
-    console.error(`${RED8}No decantr.essence.json found. Run \`decantr init\` first.${RESET9}`);
+    console.error(`${RED7}No decantr.essence.json found. Run \`decantr init\` first.${RESET9}`);
     process.exitCode = 1;
     return;
   }
@@ -6037,14 +6177,14 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
     const parsed = JSON.parse(raw);
     if (!isV46(parsed)) {
       console.error(
-        `${RED8}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET9}`
+        `${RED7}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET9}`
       );
       process.exitCode = 1;
       return;
     }
     essence = parsed;
   } catch (e) {
-    console.error(`${RED8}Could not read essence: ${e.message}${RESET9}`);
+    console.error(`${RED7}Could not read essence: ${e.message}${RESET9}`);
     process.exitCode = 1;
     return;
   }
@@ -6053,7 +6193,7 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
     if (options.json) {
       console.log(JSON.stringify(summary2, null, 2));
     } else {
-      printRefreshSummary(summary2);
+      printRefreshSummary(summary2, options.displayRoot);
     }
     if (summary2.stale) process.exitCode = 1;
     return;
@@ -6070,17 +6210,19 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
   if (options.json) {
     console.log(JSON.stringify({ ...summary, result }, null, 2));
   } else if (options.listChanges) {
-    printRefreshSummary(summary);
+    printRefreshSummary(summary, options.displayRoot);
   } else {
     console.log(`${GREEN9}Regenerated:${RESET9}`);
-    console.log(`  ${DIM9}DECANTR.md${RESET9}`);
+    console.log(
+      `  ${DIM9}${displayGeneratedPath(summary, "DECANTR.md", options.displayRoot)}${RESET9}`
+    );
     for (const css of result.cssFiles) {
       const rel2 = css.replace(projectRoot + "/", "");
-      console.log(`  ${DIM9}${rel2}${RESET9}`);
+      console.log(`  ${DIM9}${displayGeneratedPath(summary, rel2, options.displayRoot)}${RESET9}`);
     }
     for (const ctx of result.contextFiles) {
       const rel2 = ctx.replace(projectRoot + "/", "");
-      console.log(`  ${DIM9}${rel2}${RESET9}`);
+      console.log(`  ${DIM9}${displayGeneratedPath(summary, rel2, options.displayRoot)}${RESET9}`);
     }
   }
   console.log("");
@@ -6092,7 +6234,7 @@ import { mkdirSync as mkdirSync14, writeFileSync as writeFileSync14 } from "fs";
 import { join as join26 } from "path";
 import { API_CONTENT_TYPES, RegistryAPIClient as RegistryAPIClient2 } from "@decantr/registry";
 var GREEN10 = "\x1B[32m";
-var RED9 = "\x1B[31m";
+var RED8 = "\x1B[31m";
 var DIM10 = "\x1B[2m";
 var CYAN5 = "\x1B[36m";
 var YELLOW6 = "\x1B[33m";
@@ -6106,13 +6248,13 @@ async function cmdRegistryMirror(projectRoot, options = {}) {
   });
   const healthy = await apiClient.checkHealth();
   if (!healthy) {
-    console.error(`${RED9}Registry API is unavailable. Check your connection.${RESET10}`);
+    console.error(`${RED8}Registry API is unavailable. Check your connection.${RESET10}`);
     process.exitCode = 1;
     return;
   }
   const types = options.type ? [options.type] : ALL_CONTENT_TYPES;
   if (options.type && !ALL_CONTENT_TYPES.includes(options.type)) {
-    console.error(`${RED9}Unknown content type: ${options.type}${RESET10}`);
+    console.error(`${RED8}Unknown content type: ${options.type}${RESET10}`);
     console.error(`${DIM10}Valid types: ${ALL_CONTENT_TYPES.join(", ")}${RESET10}`);
     process.exitCode = 1;
     return;
@@ -6147,7 +6289,7 @@ Mirroring registry content to ${DIM10}.decantr/cache/${RESET10}
       console.log(`  ${GREEN10}\u2713${RESET10} ${type}: ${CYAN5}${itemCount}${RESET10} items`);
     } catch (e) {
       failed.push(type);
-      console.log(`  ${RED9}\u2717${RESET10} ${type}: ${e.message}`);
+      console.log(`  ${RED8}\u2717${RESET10} ${type}: ${e.message}`);
     }
   }
   const manifest = {
@@ -6176,13 +6318,13 @@ import { existsSync as existsSync25, readFileSync as readFileSync18, rmSync as r
 import { join as join27 } from "path";
 import { isV4 as isV47 } from "@decantr/essence-spec";
 var GREEN11 = "\x1B[32m";
-var RED10 = "\x1B[31m";
+var RED9 = "\x1B[31m";
 var DIM11 = "\x1B[2m";
 var RESET11 = "\x1B[0m";
 function readV4Essence2(projectRoot) {
   const essencePath = join27(projectRoot, "decantr.essence.json");
   if (!existsSync25(essencePath)) {
-    console.error(`${RED10}No decantr.essence.json found. Run \`decantr init\` first.${RESET11}`);
+    console.error(`${RED9}No decantr.essence.json found. Run \`decantr init\` first.${RESET11}`);
     process.exitCode = 1;
     return null;
   }
@@ -6190,13 +6332,13 @@ function readV4Essence2(projectRoot) {
   try {
     parsed = JSON.parse(readFileSync18(essencePath, "utf-8"));
   } catch (e) {
-    console.error(`${RED10}Could not read essence: ${e.message}${RESET11}`);
+    console.error(`${RED9}Could not read essence: ${e.message}${RESET11}`);
     process.exitCode = 1;
     return null;
   }
   if (!isV47(parsed)) {
     console.error(
-      `${RED10}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET11}`
+      `${RED9}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET11}`
     );
     process.exitCode = 1;
     return null;
@@ -6206,6 +6348,15 @@ function readV4Essence2(projectRoot) {
 function writeEssence2(essencePath, essence) {
   writeFileSync15(essencePath, JSON.stringify(essence, null, 2) + "\n");
 }
+function readFlagValue2(args, name) {
+  const prefix = `--${name}=`;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === `--${name}` && args[index + 1]) return args[index + 1];
+    if (arg.startsWith(prefix)) return arg.slice(prefix.length);
+  }
+  return void 0;
+}
 function recomputeGlobalFeatures(essence) {
   const all = /* @__PURE__ */ new Set();
   for (const section of essence.blueprint.sections || []) {
@@ -6228,7 +6379,7 @@ function removeRoutes(essence, sectionId, pageId) {
 }
 async function cmdRemoveSection(sectionId, args, projectRoot = process.cwd()) {
   if (!sectionId) {
-    console.error(`${RED10}Usage: decantr remove section <sectionId>${RESET11}`);
+    console.error(`${RED9}Usage: decantr remove section <sectionId>${RESET11}`);
     process.exitCode = 1;
     return;
   }
@@ -6238,7 +6389,7 @@ async function cmdRemoveSection(sectionId, args, projectRoot = process.cwd()) {
   const sections = essence.blueprint.sections;
   const idx = sections.findIndex((s) => s.id === sectionId);
   if (idx === -1) {
-    console.error(`${RED10}Section "${sectionId}" not found.${RESET11}`);
+    console.error(`${RED9}Section "${sectionId}" not found.${RESET11}`);
     console.error(`${DIM11}Available sections: ${sections.map((s) => s.id).join(", ")}${RESET11}`);
     process.exitCode = 1;
     return;
@@ -6260,7 +6411,7 @@ async function cmdRemoveSection(sectionId, args, projectRoot = process.cwd()) {
 }
 async function cmdRemovePage(path, args, projectRoot = process.cwd()) {
   if (!path || !path.includes("/")) {
-    console.error(`${RED10}Usage: decantr remove page <section>/<page>${RESET11}`);
+    console.error(`${RED9}Usage: decantr remove page <section>/<page>${RESET11}`);
     console.error(`${DIM11}Example: decantr remove page settings/notifications${RESET11}`);
     process.exitCode = 1;
     return;
@@ -6272,14 +6423,14 @@ async function cmdRemovePage(path, args, projectRoot = process.cwd()) {
   const sections = essence.blueprint.sections;
   const section = sections.find((s) => s.id === sectionId);
   if (!section) {
-    console.error(`${RED10}Section "${sectionId}" not found.${RESET11}`);
+    console.error(`${RED9}Section "${sectionId}" not found.${RESET11}`);
     console.error(`${DIM11}Available sections: ${sections.map((s) => s.id).join(", ")}${RESET11}`);
     process.exitCode = 1;
     return;
   }
   const pageIdx = section.pages.findIndex((p) => p.id === pageId);
   if (pageIdx === -1) {
-    console.error(`${RED10}Page "${pageId}" not found in section "${sectionId}".${RESET11}`);
+    console.error(`${RED9}Page "${pageId}" not found in section "${sectionId}".${RESET11}`);
     console.error(`${DIM11}Available pages: ${section.pages.map((p) => p.id).join(", ")}${RESET11}`);
     process.exitCode = 1;
     return;
@@ -6296,7 +6447,7 @@ async function cmdRemovePage(path, args, projectRoot = process.cwd()) {
 }
 async function cmdRemoveFeature(feature, args, projectRoot = process.cwd()) {
   if (!feature) {
-    console.error(`${RED10}Usage: decantr remove feature <feature> [--section <sectionId>]${RESET11}`);
+    console.error(`${RED9}Usage: decantr remove feature <feature> [--section <sectionId>]${RESET11}`);
     process.exitCode = 1;
     return;
   }
@@ -6304,15 +6455,12 @@ async function cmdRemoveFeature(feature, args, projectRoot = process.cwd()) {
   if (!loaded) return;
   const { essence, essencePath } = loaded;
   let sectionId;
-  const sectionIdx = args.indexOf("--section");
-  if (sectionIdx !== -1 && args[sectionIdx + 1]) {
-    sectionId = args[sectionIdx + 1];
-  }
+  sectionId = readFlagValue2(args, "section");
   if (sectionId) {
     const sections = essence.blueprint.sections;
     const section = sections.find((s) => s.id === sectionId);
     if (!section) {
-      console.error(`${RED10}Section "${sectionId}" not found.${RESET11}`);
+      console.error(`${RED9}Section "${sectionId}" not found.${RESET11}`);
       console.error(`${DIM11}Available sections: ${sections.map((s) => s.id).join(", ")}${RESET11}`);
       process.exitCode = 1;
       return;
@@ -6340,7 +6488,7 @@ async function cmdRemoveFeature(feature, args, projectRoot = process.cwd()) {
 import { existsSync as existsSync26, readFileSync as readFileSync19, writeFileSync as writeFileSync16 } from "fs";
 import { join as join28 } from "path";
 var GREEN12 = "\x1B[32m";
-var RED11 = "\x1B[31m";
+var RED10 = "\x1B[31m";
 var YELLOW7 = "\x1B[33m";
 var RESET12 = "\x1B[0m";
 var DIM12 = "\x1B[2m";
@@ -6359,12 +6507,12 @@ async function cmdSyncDrift(projectRoot = process.cwd()) {
   try {
     entries = JSON.parse(readFileSync19(driftLogPath, "utf-8"));
   } catch {
-    console.error(`${RED11}Could not parse drift-log.json${RESET12}`);
+    console.error(`${RED10}Could not parse drift-log.json${RESET12}`);
     process.exitCode = 1;
     return;
   }
   if (!Array.isArray(entries)) {
-    console.error(`${RED11}drift-log.json is not an array${RESET12}`);
+    console.error(`${RED10}drift-log.json is not an array${RESET12}`);
     process.exitCode = 1;
     return;
   }
@@ -6382,7 +6530,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" ? RED11 : YELLOW7;
+    const severityColor = entry.severity === "error" ? RED10 : YELLOW7;
     const icon = entry.severity === "error" ? "x" : "!";
     console.log(
       `  ${severityColor}${icon}${RESET12} ${BOLD6}#${i + 1}${RESET12} [${entry.rule}] ${entry.message}`
@@ -6665,7 +6813,7 @@ import { existsSync as existsSync27, readFileSync as readFileSync20, writeFileSy
 import { join as join29 } from "path";
 import { isV4 as isV48 } from "@decantr/essence-spec";
 var GREEN14 = "\x1B[32m";
-var RED12 = "\x1B[31m";
+var RED11 = "\x1B[31m";
 var YELLOW8 = "\x1B[33m";
 var DIM14 = "\x1B[2m";
 var RESET14 = "\x1B[0m";
@@ -6674,14 +6822,14 @@ var VALID_THEME_MODES = ["light", "dark", "auto"];
 async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
   if (!themeName) {
     console.error(
-      `${RED12}Usage: decantr theme switch <themeName> [--shape <s>] [--mode <m>]${RESET14}`
+      `${RED11}Usage: decantr theme switch <themeName> [--shape <s>] [--mode <m>]${RESET14}`
     );
     process.exitCode = 1;
     return;
   }
   const essencePath = join29(projectRoot, "decantr.essence.json");
   if (!existsSync27(essencePath)) {
-    console.error(`${RED12}No decantr.essence.json found. Run \`decantr init\` first.${RESET14}`);
+    console.error(`${RED11}No decantr.essence.json found. Run \`decantr init\` first.${RESET14}`);
     process.exitCode = 1;
     return;
   }
@@ -6689,13 +6837,13 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
   try {
     parsed = JSON.parse(readFileSync20(essencePath, "utf-8"));
   } catch (e) {
-    console.error(`${RED12}Could not read essence: ${e.message}${RESET14}`);
+    console.error(`${RED11}Could not read essence: ${e.message}${RESET14}`);
     process.exitCode = 1;
     return;
   }
   if (!isV48(parsed)) {
     console.error(
-      `${RED12}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET14}`
+      `${RED11}Active workflows require Essence v4.0.0. Run \`decantr migrate --to v4\` first.${RESET14}`
     );
     process.exitCode = 1;
     return;
@@ -6717,14 +6865,14 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
   }
   if (shape && !VALID_THEME_SHAPES.includes(shape)) {
     console.error(
-      `${RED12}Invalid shape "${shape}". Must be one of: ${VALID_THEME_SHAPES.join(", ")}.${RESET14}`
+      `${RED11}Invalid shape "${shape}". Must be one of: ${VALID_THEME_SHAPES.join(", ")}.${RESET14}`
     );
     process.exitCode = 1;
     return;
   }
   if (mode && !VALID_THEME_MODES.includes(mode)) {
     console.error(
-      `${RED12}Invalid mode "${mode}". Must be one of: ${VALID_THEME_MODES.join(", ")}.${RESET14}`
+      `${RED11}Invalid mode "${mode}". Must be one of: ${VALID_THEME_MODES.join(", ")}.${RESET14}`
     );
     process.exitCode = 1;
     return;
@@ -7228,7 +7376,7 @@ function importTheme(projectRoot, sourcePath) {
 var BOLD9 = "\x1B[1m";
 var DIM16 = "\x1B[2m";
 var RESET16 = "\x1B[0m";
-var RED13 = "\x1B[31m";
+var RED12 = "\x1B[31m";
 var GREEN16 = "\x1B[32m";
 var CYAN9 = "\x1B[36m";
 var YELLOW10 = "\x1B[33m";
@@ -7240,8 +7388,8 @@ ${BOLD9}${text}${RESET16}
 function success3(text) {
   return `${GREEN16}${text}${RESET16}`;
 }
-function error3(text) {
-  return `${RED13}${text}${RESET16}`;
+function error2(text) {
+  return `${RED12}${text}${RESET16}`;
 }
 function dim3(text) {
   return `${DIM16}${text}${RESET16}`;
@@ -7751,7 +7899,7 @@ function getPublicAPIClient() {
   });
 }
 function resolveUserPath(inputPath, cwd = process.cwd()) {
-  return isAbsolute(inputPath) ? inputPath : resolve4(cwd, inputPath);
+  return isAbsolute3(inputPath) ? inputPath : resolve4(cwd, inputPath);
 }
 function extractHostedAssetPaths(indexHtml) {
   const assetPaths = /* @__PURE__ */ new Set();
@@ -8345,22 +8493,22 @@ function patternCandidateFromRegistryItem(item, source) {
     { source, slug }
   );
 }
-function readSuggestCodeContext(route, file) {
+function readSuggestCodeContext(projectRoot, route, file) {
   const pieces = [];
   if (file) {
-    const resolved = isAbsolute(file) ? file : join31(process.cwd(), file);
+    const resolved = isAbsolute3(file) ? file : join31(projectRoot, file);
     if (existsSync29(resolved)) {
       pieces.push(readFileSync22(resolved, "utf-8"));
     }
   }
   if (route) {
-    const analysisPath = join31(process.cwd(), ".decantr", "analysis.json");
+    const analysisPath = join31(projectRoot, ".decantr", "analysis.json");
     if (existsSync29(analysisPath)) {
       try {
         const analysis = JSON.parse(readFileSync22(analysisPath, "utf-8"));
         const routeEntry = analysis.routes?.routes?.find((entry) => entry.path === route);
         if (routeEntry?.file) {
-          const resolved = join31(process.cwd(), routeEntry.file);
+          const resolved = join31(projectRoot, routeEntry.file);
           if (existsSync29(resolved)) {
             pieces.push(readFileSync22(resolved, "utf-8"));
           }
@@ -8371,6 +8519,28 @@ function readSuggestCodeContext(route, file) {
   }
   return pieces.join("\n\n").slice(0, 2e4);
 }
+function localPatternMatches(projectRoot, query) {
+  if (!projectRoot) return [];
+  const pack = readLocalPatternPack(projectRoot);
+  const patterns = Array.isArray(pack?.patterns) ? pack.patterns : [];
+  const queryTerms = query.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 1);
+  if (queryTerms.length === 0) return [];
+  return patterns.map((pattern) => {
+    const id = typeof pattern.id === "string" ? pattern.id : "local-pattern";
+    const label = typeof pattern.label === "string" ? pattern.label : null;
+    const role = typeof pattern.role === "string" ? pattern.role : null;
+    const haystack = [
+      id,
+      label,
+      role,
+      typeof pattern.decide === "string" ? pattern.decide : null,
+      ...Array.isArray(pattern.appliesTo) ? pattern.appliesTo : [],
+      ...Array.isArray(pattern.componentPaths) ? pattern.componentPaths : []
+    ].filter((entry) => typeof entry === "string").join(" ").toLowerCase();
+    const score = queryTerms.reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
+    return { id, label, role, score };
+  }).filter((match) => match.score > 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, 5);
+}
 async function loadPatternDiscoveryCandidates(registryClient) {
   const candidates = [];
   const seen = /* @__PURE__ */ new Set();
@@ -8419,9 +8589,9 @@ async function cmdSuggest(query, options = {}) {
     }
   }
   const registryClient = new RegistryClient({
-    cacheDir: join31(process.cwd(), ".decantr", "cache")
+    cacheDir: join31(options.projectRoot ?? process.cwd(), ".decantr", "cache")
   });
-  const code = options.fromCode || options.file ? readSuggestCodeContext(options.route, options.file) : "";
+  const code = options.fromCode || options.file ? readSuggestCodeContext(options.projectRoot ?? process.cwd(), options.route, options.file) : "";
   const candidates = await loadPatternDiscoveryCandidates(registryClient);
   const matches = rankPatternCandidates(
     {
@@ -8452,6 +8622,16 @@ async function cmdSuggest(query, options = {}) {
       `Pattern suggestions for "${query}"${contextBits.length > 0 ? ` (${contextBits.join(", ")})` : ""}`
     )
   );
+  const localMatches = localPatternMatches(options.projectRoot, query);
+  if (localMatches.length > 0) {
+    console.log(`${BOLD9}Project-owned local law:${RESET16}`);
+    for (const match of localMatches) {
+      const details = [match.label, match.role].filter(Boolean).join(" | ");
+      console.log(`  ${cyan3(match.id)}${details ? `  ${dim3(details)}` : ""}`);
+    }
+    console.log("");
+    console.log(`${BOLD9}Registry patterns:${RESET16}`);
+  }
   for (const match of matches.slice(0, 8)) {
     const candidate = match.candidate;
     const slug = candidate.slug || candidate.id;
@@ -8475,7 +8655,7 @@ async function cmdSuggest(query, options = {}) {
 }
 async function cmdGet(type, id) {
   if (!isGetContentType(type)) {
-    console.error(error3(`Invalid type "${type}". Must be one of: ${GET_CONTENT_TYPES.join(", ")}`));
+    console.error(error2(`Invalid type "${type}". Must be one of: ${GET_CONTENT_TYPES.join(", ")}`));
     process.exitCode = 1;
     return;
   }
@@ -8493,7 +8673,7 @@ async function cmdGet(type, id) {
     console.log(JSON.stringify(bundled.data, null, 2));
     return;
   }
-  console.error(error3(`${type} "${id}" not found.`));
+  console.error(error2(`${type} "${id}" not found.`));
   process.exitCode = 1;
   return;
 }
@@ -8503,7 +8683,7 @@ async function cmdValidate(path) {
   try {
     raw = readFileSync22(essencePath, "utf-8");
   } catch {
-    console.error(error3(`Could not read ${essencePath}`));
+    console.error(error2(`Could not read ${essencePath}`));
     process.exitCode = 1;
     return;
   }
@@ -8511,7 +8691,7 @@ async function cmdValidate(path) {
   try {
     essence = JSON.parse(raw);
   } catch (e) {
-    console.error(error3(`Invalid JSON: ${e.message}`));
+    console.error(error2(`Invalid JSON: ${e.message}`));
     process.exitCode = 1;
     return;
   }
@@ -8521,9 +8701,9 @@ async function cmdValidate(path) {
   if (result.valid) {
     console.log(success3(`Essence is valid (${detectedVersion}).`));
   } else {
-    console.error(error3("Validation failed:"));
+    console.error(error2("Validation failed:"));
     for (const err of result.errors) {
-      console.error(`  ${RED13}${err}${RESET16}`);
+      console.error(`  ${RED12}${err}${RESET16}`);
     }
     process.exitCode = 1;
     return;
@@ -8562,7 +8742,7 @@ async function cmdValidate(path) {
 async function cmdList(type, sort, recommended, intelligenceSource, blueprintSet) {
   if (!isApiContentType(type)) {
     console.error(
-      error3(`Invalid type "${type}". Must be one of: ${LIST_CONTENT_TYPES.join(", ")}`)
+      error2(`Invalid type "${type}". Must be one of: ${LIST_CONTENT_TYPES.join(", ")}`)
     );
     process.exitCode = 1;
     return;
@@ -8724,7 +8904,7 @@ async function applyAcceptedBrownfieldProposal(input) {
   const proposal = readBrownfieldProposal(input.projectRoot);
   if (!proposal) {
     console.log(
-      error3(`No observed brownfield proposal found at ${proposalPath(input.projectRoot)}.`)
+      error2(`No observed brownfield proposal found at ${proposalPath(input.projectRoot)}.`)
     );
     console.log(
       dim3(
@@ -8739,7 +8919,7 @@ async function applyAcceptedBrownfieldProposal(input) {
   let essence;
   let backupPath = null;
   if (input.mode === "accept" && hasEssence) {
-    console.log(error3("Refusing to accept proposal over an existing decantr.essence.json."));
+    console.log(error2("Refusing to accept proposal over an existing decantr.essence.json."));
     console.log(
       dim3(
         "Use `--merge-proposal` to preserve the existing contract or `--replace-essence` for an explicit destructive replacement."
@@ -8752,7 +8932,7 @@ async function applyAcceptedBrownfieldProposal(input) {
     const existing = JSON.parse(readFileSync22(essencePath, "utf-8"));
     if (!isV49(existing)) {
       console.log(
-        error3(
+        error2(
           "Existing essence is not v4. Run `decantr migrate --to v4` before merging a brownfield proposal."
         )
       );
@@ -8766,10 +8946,10 @@ async function applyAcceptedBrownfieldProposal(input) {
   const validation = validateEssence2(essence);
   if (!validation.valid) {
     console.log(
-      error3("Brownfield proposal produced an invalid Decantr essence. No files were changed.")
+      error2("Brownfield proposal produced an invalid Decantr essence. No files were changed.")
     );
     for (const validationError of validation.errors) {
-      console.log(`  ${RED13}${validationError}${RESET16}`);
+      console.log(`  ${RED12}${validationError}${RESET16}`);
     }
     process.exitCode = 1;
     return;
@@ -8815,13 +8995,24 @@ async function applyAcceptedBrownfieldProposal(input) {
   }
   const appliedRuleFiles = input.assistantBridge === "apply" ? applyAssistantBridge(input.projectRoot, input.detected) : [];
   console.log(success3("\nBrownfield proposal accepted.\n"));
+  const projectLabel = input.workspaceInfo.appRoot !== input.workspaceInfo.workspaceRoot ? relative7(input.workspaceInfo.workspaceRoot, input.workspaceInfo.appRoot).replace(/\\/g, "/") : void 0;
   console.log("  Files created/updated:");
-  console.log(`    ${cyan3("decantr.essence.json")}    Observed brownfield contract`);
-  console.log(`    ${cyan3("DECANTR.md")}              Reconciled assistant guidance`);
-  console.log(`    ${cyan3(".decantr/project.json")}  Brownfield attach metadata`);
-  console.log(`    ${cyan3(".decantr/context/")}      Generated contract context`);
+  console.log(
+    `    ${cyan3(displayProjectPath(input.workspaceInfo, "decantr.essence.json"))}    Observed brownfield contract`
+  );
+  console.log(
+    `    ${cyan3(displayProjectPath(input.workspaceInfo, "DECANTR.md"))}              Reconciled assistant guidance`
+  );
+  console.log(
+    `    ${cyan3(displayProjectPath(input.workspaceInfo, ".decantr/project.json"))}  Brownfield attach metadata`
+  );
+  console.log(
+    `    ${cyan3(displayProjectPath(input.workspaceInfo, ".decantr/context/"))}      Generated contract context`
+  );
   if (assistantBridgePath) {
-    console.log(`    ${cyan3(".decantr/context/assistant-bridge.md")} Assistant bridge preview`);
+    console.log(
+      `    ${cyan3(displayProjectPath(input.workspaceInfo, ".decantr/context/assistant-bridge.md"))} Assistant bridge preview`
+    );
   }
   if (appliedRuleFiles.length > 0) {
     console.log(`    ${dim3(`Rule bridge applied: ${appliedRuleFiles.join(", ")}`)}`);
@@ -8832,16 +9023,24 @@ async function applyAcceptedBrownfieldProposal(input) {
   console.log("");
   console.log("  Generated context:");
   for (const contextFile of refreshResult.contextFiles.slice(0, 8)) {
-    console.log(`    ${dim3(contextFile.replace(`${input.projectRoot}/`, ""))}`);
+    console.log(
+      `    ${dim3(displayProjectPath(input.workspaceInfo, contextFile.replace(`${input.projectRoot}/`, "")))}`
+    );
   }
   if (refreshResult.contextFiles.length > 8) {
     console.log(`    ${dim3(`(+${refreshResult.contextFiles.length - 8} more)`)}`);
   }
   console.log("");
   console.log("  Next steps:");
-  console.log(`    1. Run ${cyan3("decantr check --brownfield")} to verify contract coverage`);
-  console.log(`    2. Read ${cyan3(".decantr/brownfield-report.md")} for unresolved doctrine risks`);
-  console.log(`    3. Use ${cyan3("decantr rules preview")} before mutating assistant rule files`);
+  console.log(
+    `    1. Run ${cyan3(withProject("decantr check --brownfield", projectLabel))} to verify contract coverage`
+  );
+  console.log(
+    `    2. Read ${cyan3(displayProjectPath(input.workspaceInfo, ".decantr/brownfield-report.md"))} for unresolved doctrine risks`
+  );
+  console.log(
+    `    3. Use ${cyan3(withProject("decantr rules preview", projectLabel))} before mutating assistant rule files`
+  );
   console.log("");
 }
 async function cmdInit(args) {
@@ -8898,7 +9097,7 @@ async function cmdInit(args) {
   }
   if (policy.workflowMode === "brownfield-attach" && detected.existingEssence) {
     console.log(
-      error3("Refusing to overwrite existing decantr.essence.json in brownfield attach mode.")
+      error2("Refusing to overwrite existing decantr.essence.json in brownfield attach mode.")
     );
     console.log(
       dim3(
@@ -8909,7 +9108,7 @@ async function cmdInit(args) {
     return;
   }
   if (policy.workflowMode === "brownfield-attach" && readBrownfieldProposal(projectRoot)) {
-    console.log(error3("Observed brownfield proposal found, but it was not accepted."));
+    console.log(error2("Observed brownfield proposal found, but it was not accepted."));
     console.log(
       dim3(
         "Review `.decantr/brownfield-report.md`, then run `decantr init --existing --accept-proposal`."
@@ -8930,7 +9129,7 @@ async function cmdInit(args) {
       console.log(dim3(`  Seeded offline registry content from ${offlineSeed.strategy}.`));
     } else if (requestedBlueprint || requestedArchetype) {
       console.log(
-        error3("\nOffline blueprint/archetype scaffolding requires a local Decantr content source.")
+        error2("\nOffline blueprint/archetype scaffolding requires a local Decantr content source.")
       );
       console.log(
         dim3(
@@ -8998,7 +9197,7 @@ ${YELLOW10}You're offline. Scaffolding minimal Decantr project.${RESET16}`);
     }
     if (requestedBlueprint || requestedArchetype) {
       console.log(
-        error3(
+        error2(
           "\nThe requested blueprint/archetype could not be resolved from the hosted registry or local cache."
         )
       );
@@ -9187,7 +9386,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
       }
     } else {
       if (requestedBlueprint) {
-        console.log(error3(`  Error: Could not fetch blueprint "${options.blueprint}".`));
+        console.log(error2(`  Error: Could not fetch blueprint "${options.blueprint}".`));
         console.log(dim3("Resolve local registry content or retry against the hosted registry."));
         process.exitCode = 1;
         return;
@@ -9202,7 +9401,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
       archetypeData = mapRegistryArchetypeToArchetypeData(archetypeResult.data);
     } else {
       if (requestedArchetype) {
-        console.log(error3(`  Error: Could not fetch archetype "${options.archetype}".`));
+        console.log(error2(`  Error: Could not fetch archetype "${options.archetype}".`));
         console.log(dim3("Resolve local registry content or retry against the hosted registry."));
         process.exitCode = 1;
         return;
@@ -9219,7 +9418,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
       themeData = mapRegistryThemeToThemeData(themeResult.data);
     } else {
       if (requestedTheme) {
-        console.log(error3(`  Error: Could not fetch theme "${options.theme}".`));
+        console.log(error2(`  Error: Could not fetch theme "${options.theme}".`));
         console.log(dim3("Resolve local registry content or retry against the hosted registry."));
         process.exitCode = 1;
         return;
@@ -9329,7 +9528,7 @@ ${YELLOW10}You're offline. Scaffolding Decantr default.${RESET16}`);
   const essence = JSON.parse(essenceContent);
   const validation = validateEssence2(essence);
   if (!validation.valid) {
-    console.log(error3(`
+    console.log(error2(`
 Validation warnings: ${validation.errors.join(", ")}`));
   }
   console.log("");
@@ -9379,13 +9578,12 @@ Validation warnings: ${validation.errors.join(", ")}`));
     console.log(dim3('Run "decantr sync" when online to get the latest registry content.'));
   }
 }
-async function cmdStatus() {
-  const projectRoot = process.cwd();
+async function cmdStatus(projectRoot = process.cwd()) {
   const essencePath = join31(projectRoot, "decantr.essence.json");
   const projectJsonPath = join31(projectRoot, ".decantr", "project.json");
   console.log(heading2("Decantr Project Status"));
   if (!existsSync29(essencePath)) {
-    console.log(`${RED13}No decantr.essence.json found.${RESET16}`);
+    console.log(`${RED12}No decantr.essence.json found.${RESET16}`);
     console.log(dim3('Run "decantr init" to create one.'));
     return;
   }
@@ -9397,7 +9595,7 @@ async function cmdStatus() {
     if (validation.valid) {
       console.log(`  ${GREEN16}Valid${RESET16} (${essenceVersion})`);
     } else {
-      console.log(`  ${RED13}Invalid: ${validation.errors.join(", ")}${RESET16}`);
+      console.log(`  ${RED12}Invalid: ${validation.errors.join(", ")}${RESET16}`);
     }
     if (isV49(essence)) {
       const v4 = essence;
@@ -9434,7 +9632,7 @@ async function cmdStatus() {
       console.log(`  ${YELLOW10}Run \`decantr migrate --to v4\` to upgrade this project.${RESET16}`);
     }
   } catch (e) {
-    console.log(`  ${RED13}Error reading essence: ${e.message}${RESET16}`);
+    console.log(`  ${RED12}Error reading essence: ${e.message}${RESET16}`);
   }
   console.log("");
   console.log(`${BOLD9}Sync Status:${RESET16}`);
@@ -9480,7 +9678,7 @@ function printVerificationFindings(findings) {
     return;
   }
   for (const finding of findings) {
-    const color = finding.severity === "error" ? RED13 : finding.severity === "warn" ? YELLOW10 : CYAN9;
+    const color = finding.severity === "error" ? RED12 : finding.severity === "warn" ? YELLOW10 : CYAN9;
     console.log(
       `  ${color}[${finding.severity.toUpperCase()}]${RESET16} ${finding.category}: ${finding.message}`
     );
@@ -9496,7 +9694,7 @@ function printProjectAuditReport(report) {
   if (report.valid) {
     console.log(success3("Project contract is valid."));
   } else {
-    console.log(`${RED13}Project audit found blocking issues.${RESET16}`);
+    console.log(`${RED12}Project audit found blocking issues.${RESET16}`);
   }
   console.log("");
   console.log(`${BOLD9}Summary:${RESET16}`);
@@ -9585,13 +9783,12 @@ async function cmdAudit(filePath) {
       console.log(dim3("Project audit completed with advisory findings."));
     }
   } catch (e) {
-    console.log(`${RED13}Error: ${e.message}${RESET16}`);
+    console.log(`${RED12}Error: ${e.message}${RESET16}`);
     process.exitCode = 1;
   }
 }
-async function cmdTheme(args) {
+async function cmdTheme(args, projectRoot = process.cwd()) {
   const subcommand = args[0];
-  const projectRoot = process.cwd();
   if (!subcommand || subcommand === "help") {
     console.log(`
 ${BOLD9}decantr theme${RESET16} \u2014 Manage custom themes
@@ -9616,7 +9813,7 @@ ${BOLD9}Examples:${RESET16}
     case "create": {
       const name = args[1];
       if (!name) {
-        console.error(error3("Usage: decantr theme create <name>"));
+        console.error(error2("Usage: decantr theme create <name>"));
         process.exitCode = 1;
         return;
       }
@@ -9628,7 +9825,7 @@ ${BOLD9}Examples:${RESET16}
         console.log("");
         console.log(`Use in essence: ${cyan3(`"id": "custom:${name}"`)}`);
       } else {
-        console.error(error3(result.error || "Failed to create theme"));
+        console.error(error2(result.error || "Failed to create theme"));
         process.exitCode = 1;
       }
       break;
@@ -9649,13 +9846,13 @@ ${BOLD9}Examples:${RESET16}
     case "validate": {
       const name = args[1];
       if (!name) {
-        console.error(error3("Usage: decantr theme validate <name>"));
+        console.error(error2("Usage: decantr theme validate <name>"));
         process.exitCode = 1;
         return;
       }
       const themePath = join31(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
       if (!existsSync29(themePath)) {
-        console.error(error3(`Theme "${name}" not found at ${themePath}`));
+        console.error(error2(`Theme "${name}" not found at ${themePath}`));
         process.exitCode = 1;
         return;
       }
@@ -9665,14 +9862,14 @@ ${BOLD9}Examples:${RESET16}
         if (result.valid) {
           console.log(success3(`Custom theme "${name}" is valid`));
         } else {
-          console.error(error3("Validation failed:"));
+          console.error(error2("Validation failed:"));
           for (const err of result.errors) {
-            console.error(`  ${RED13}${err}${RESET16}`);
+            console.error(`  ${RED12}${err}${RESET16}`);
           }
           process.exitCode = 1;
         }
       } catch (e) {
-        console.error(error3(`Invalid JSON: ${e.message}`));
+        console.error(error2(`Invalid JSON: ${e.message}`));
         process.exitCode = 1;
       }
       break;
@@ -9680,7 +9877,7 @@ ${BOLD9}Examples:${RESET16}
     case "delete": {
       const name = args[1];
       if (!name) {
-        console.error(error3("Usage: decantr theme delete <name>"));
+        console.error(error2("Usage: decantr theme delete <name>"));
         process.exitCode = 1;
         return;
       }
@@ -9688,7 +9885,7 @@ ${BOLD9}Examples:${RESET16}
       if (result.success) {
         console.log(success3(`Deleted custom theme "${name}"`));
       } else {
-        console.error(error3(result.error || "Failed to delete theme"));
+        console.error(error2(result.error || "Failed to delete theme"));
         process.exitCode = 1;
       }
       break;
@@ -9696,7 +9893,7 @@ ${BOLD9}Examples:${RESET16}
     case "import": {
       const sourcePath = args[1];
       if (!sourcePath) {
-        console.error(error3("Usage: decantr theme import <path>"));
+        console.error(error2("Usage: decantr theme import <path>"));
         process.exitCode = 1;
         return;
       }
@@ -9705,9 +9902,9 @@ ${BOLD9}Examples:${RESET16}
         console.log(success3("Theme imported successfully"));
         console.log(dim3(`  Path: ${result.path}`));
       } else {
-        console.error(error3("Import failed:"));
+        console.error(error2("Import failed:"));
         for (const err of result.errors || []) {
-          console.error(`  ${RED13}${err}${RESET16}`);
+          console.error(`  ${RED12}${err}${RESET16}`);
         }
         process.exitCode = 1;
       }
@@ -9716,7 +9913,7 @@ ${BOLD9}Examples:${RESET16}
     case "switch": {
       const name = args[1];
       if (!name) {
-        console.error(error3("Usage: decantr theme switch <themeName> [--shape <s>] [--mode <m>]"));
+        console.error(error2("Usage: decantr theme switch <themeName> [--shape <s>] [--mode <m>]"));
         process.exitCode = 1;
         return;
       }
@@ -9724,7 +9921,7 @@ ${BOLD9}Examples:${RESET16}
       break;
     }
     default:
-      console.error(error3(`Unknown theme command: ${subcommand}`));
+      console.error(error2(`Unknown theme command: ${subcommand}`));
       process.exitCode = 1;
   }
 }
@@ -9791,6 +9988,44 @@ function withoutWorkflowOnlyFlags(args) {
 function withProject(command, projectArg) {
   return projectArg ? `${command} --project ${projectArg}` : command;
 }
+function displayProjectPath(workspaceInfo, projectPath) {
+  const absolutePath = join31(workspaceInfo.appRoot, projectPath);
+  const relativePath = relative7(workspaceInfo.cwd, absolutePath).replace(/\\/g, "/");
+  if (relativePath && !relativePath.startsWith("..") && !isAbsolute3(relativePath)) {
+    return relativePath;
+  }
+  return absolutePath;
+}
+function stripProjectArgs(args, startIndex = 1) {
+  const stripped = [args[0]];
+  for (let index = startIndex; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--project" && args[index + 1]) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--project=")) continue;
+    stripped.push(arg);
+  }
+  return stripped;
+}
+function normalizedProjectPath(value) {
+  if (!value) return null;
+  return value.replace(/\\/g, "/").replace(/\/+$/g, "");
+}
+function printProjectNotFound(projectArg, commandName) {
+  console.error(error2(`decantr ${commandName} could not find project path: ${projectArg}`));
+  console.error(dim3("Pass an existing app path, for example `--project apps/web`."));
+}
+function ensureAllowedFlags(flags, allowed, commandName) {
+  const allowedSet = new Set(allowed);
+  const unknown = Object.keys(flags).filter((flag) => !allowedSet.has(flag));
+  if (unknown.length === 0) return true;
+  console.error(error2(`Unsupported option for decantr ${commandName}: --${unknown[0]}`));
+  console.error(dim3("Run `decantr help` or the command-specific help to see supported options."));
+  process.exitCode = 1;
+  return false;
+}
 function compilePacksCommandForProject(projectArg) {
   const essencePath = projectArg ? `${projectArg}/decantr.essence.json` : "decantr.essence.json";
   return `decantr registry compile-packs ${essencePath} --write-context`;
@@ -9801,7 +10036,7 @@ function firstWorkspaceCandidate(workspaceInfo) {
 function printWorkspaceProjectSelection(workspaceInfo, commandName = "command") {
   const candidate = firstWorkspaceCandidate(workspaceInfo);
   const noun = commandName === "adopt" ? "Brownfield adoption" : `decantr ${commandName}`;
-  console.log(error3(`${noun} needs an app path.`));
+  console.log(error2(`${noun} needs an app path.`));
   console.log("");
   console.log(`${BOLD9}This looks like a monorepo.${RESET16}`);
   console.log("Install Decantr at the workspace root, then attach it to one app with --project.");
@@ -9821,10 +10056,47 @@ function printWorkspaceProjectSelection(workspaceInfo, commandName = "command")
 }
 function printMonorepoSetupGuidance(workspaceInfo) {
   const candidate = firstWorkspaceCandidate(workspaceInfo);
+  const attachedProjects = workspaceInfo.appCandidates.filter(
+    (appCandidate) => existsSync29(join31(workspaceInfo.workspaceRoot, appCandidate, "decantr.essence.json"))
+  );
+  const firstAttached = attachedProjects[0];
   console.log(heading2("Decantr Setup"));
   console.log(`${BOLD9}This looks like a monorepo.${RESET16}`);
   console.log(`  Workspace root: ${workspaceInfo.workspaceRoot}`);
   console.log("");
+  if (firstAttached) {
+    console.log("Decantr is already attached to at least one app.");
+    console.log("");
+    console.log("Attached projects:");
+    for (const project of attachedProjects) {
+      console.log(`  ${project}`);
+    }
+    console.log("");
+    console.log(`${BOLD9}Next:${RESET16}`);
+    console.log(
+      `  ${cyan3(`decantr doctor --project ${firstAttached}`)}                    Explain current state and next command`
+    );
+    console.log(
+      `  ${cyan3(`decantr task <route> "<change>" --project ${firstAttached}`)}   Prepare LLM context before edits`
+    );
+    console.log(
+      `  ${cyan3(`decantr verify --brownfield --local-patterns --project ${firstAttached}`)}  Check after edits`
+    );
+    console.log(
+      `  ${cyan3(`decantr ci init --project ${firstAttached}`)}                  Wire the app into CI`
+    );
+    const unattached = workspaceInfo.appCandidates.filter(
+      (appCandidate) => !attachedProjects.includes(appCandidate)
+    );
+    if (unattached.length > 0) {
+      console.log("");
+      console.log("Other app candidates:");
+      for (const appCandidate of unattached) {
+        console.log(`  ${appCandidate}`);
+      }
+    }
+    return;
+  }
   console.log(
     "Install Decantr at the workspace root, then attach it to the app you want Decantr to govern."
   );
@@ -9850,9 +10122,34 @@ function printMonorepoSetupGuidance(workspaceInfo) {
     `  ${cyan3(`decantr verify --project ${candidate} --base-url http://localhost:3000 --evidence`)}`
   );
 }
-function resolveWorkflowProject(flags, commandName = "command") {
+function resolveWorkflowProject(flags, commandName = "command", options = {}) {
   const projectArg = flagString(flags, "project");
   const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
+  if (projectArg && options.requireExisting !== false && !existsSync29(workspaceInfo.appRoot)) {
+    printProjectNotFound(projectArg, commandName);
+    process.exitCode = 1;
+    return null;
+  }
+  if (projectArg && options.requireAppCandidate && workspaceInfo.appCandidates.length > 0) {
+    const normalizedProject = normalizedProjectPath(projectArg);
+    const knownCandidate = normalizedProject ? workspaceInfo.appCandidates.includes(normalizedProject) : false;
+    const forcePackage = flagBoolean(flags, "force-package") || flagBoolean(flags, "allow-package") || flagBoolean(flags, "force");
+    if (!knownCandidate && !forcePackage && !options.allowPackageProject) {
+      console.error(
+        error2(`decantr ${commandName} is app-scoped, but "${projectArg}" is not an app candidate.`)
+      );
+      if (workspaceInfo.appCandidates.length > 0) {
+        console.error(dim3(`App candidates: ${workspaceInfo.appCandidates.join(", ")}`));
+      }
+      console.error(
+        dim3(
+          "Use --force-package only if you intentionally want Decantr attached to a non-app package."
+        )
+      );
+      process.exitCode = 1;
+      return null;
+    }
+  }
   if (workspaceInfo.requiresProjectSelection) {
     printWorkspaceProjectSelection(workspaceInfo, commandName);
     process.exitCode = 1;
@@ -9921,7 +10218,37 @@ async function cmdSetupWorkflow(args) {
 }
 async function cmdAdoptWorkflow(args) {
   const { flags } = parseLooseArgs(args);
-  const workspaceInfo = resolveWorkflowProject(flags, "adopt");
+  if (!ensureAllowedFlags(
+    flags,
+    [
+      "project",
+      "dry-run",
+      "yes",
+      "y",
+      "base-url",
+      "verify",
+      "browser",
+      "evidence",
+      "baseline",
+      "save-baseline",
+      "packs",
+      "skip-packs",
+      "offline",
+      "ci",
+      "init-ci",
+      "assistant-bridge",
+      "replace-essence",
+      "merge-proposal",
+      "telemetry",
+      "force-package",
+      "allow-package",
+      "force"
+    ],
+    "adopt"
+  )) {
+    return;
+  }
+  const workspaceInfo = resolveWorkflowProject(flags, "adopt", { requireAppCandidate: true });
   if (!workspaceInfo) return;
   const projectRoot = workspaceInfo.appRoot;
   const projectArg = flagString(flags, "project");
@@ -9992,9 +10319,7 @@ async function cmdAdoptWorkflow(args) {
         )
       );
     } catch (e) {
-      console.log(
-        `${YELLOW10}Pack hydration skipped:${RESET16} ${e.message}`
-      );
+      console.log(`${YELLOW10}Pack hydration skipped:${RESET16} ${e.message}`);
       console.log(
         dim3(
           `Run ${compilePacksCommandForProject(projectArg)} after adoption if you want hosted page/review packs.`
@@ -10005,7 +10330,7 @@ async function cmdAdoptWorkflow(args) {
     console.log(dim3("Skipping hosted pack hydration in offline mode."));
   }
   if (runVerify) {
-    const { cmdHealth } = await import("./health-LTDSTNOV.js");
+    const { cmdHealth } = await import("./health-R7AV5G4V.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -10040,13 +10365,43 @@ async function cmdAdoptWorkflow(args) {
 }
 async function cmdVerifyWorkflow(args) {
   const { flags } = parseLooseArgs(args);
+  const projectArg = flagString(flags, "project");
+  if (!ensureAllowedFlags(
+    flags,
+    [
+      "project",
+      "workspace",
+      "changed",
+      "since",
+      "json",
+      "markdown",
+      "format",
+      "output",
+      "ci",
+      "fail-on",
+      "prompt",
+      "brownfield",
+      "local-patterns",
+      "evidence",
+      "browser",
+      "require-browser",
+      "base-url",
+      "design-tokens",
+      "save-baseline",
+      "since-baseline",
+      "baseline"
+    ],
+    "verify"
+  )) {
+    return;
+  }
   const workspaceMode = flagBoolean(flags, "workspace");
   if (args[1] === "init-ci") {
     await cmdCi(["ci", "init", ...args.slice(2)], process.cwd());
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-53EIHUXB.js");
+    const { cmdWorkspace } = await import("./workspace-DRHTQ2NG.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -10079,7 +10434,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;
@@ -10089,7 +10444,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-LTDSTNOV.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-R7AV5G4V.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -10097,7 +10452,7 @@ async function cmdVerifyWorkflow(args) {
       if (!quietOutput) {
         console.log("");
         console.log(
-          `${YELLOW10}Local pattern pack missing.${RESET16} Run ${cyan3("decantr codify --from-audit")}, review the proposal, then run ${cyan3("decantr codify --accept")}.`
+          `${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))}.`
         );
       }
       process.exitCode = process.exitCode || 1;
@@ -10159,7 +10514,7 @@ async function cmdTaskWorkflow(args) {
   const routeInput = positional[0];
   if (!routeInput) {
     console.error(
-      error3(
+      error2(
         'Usage: decantr task <route> ["task summary"] [--project <path>] [--since origin/main] [--json]'
       )
     );
@@ -10172,20 +10527,20 @@ async function cmdTaskWorkflow(args) {
   const essence = readJsonIfPresent(essencePath);
   if (!essence) {
     console.error(
-      error3("No decantr.essence.json found. Run `decantr adopt` or `decantr init` first.")
+      error2("No decantr.essence.json found. Run `decantr adopt` or `decantr init` first.")
     );
     process.exitCode = 1;
     return;
   }
   if (!isV49(essence)) {
-    console.error(error3("Task context requires Essence v4. Run `decantr migrate --to v4` first."));
+    console.error(error2("Task context requires Essence v4. Run `decantr migrate --to v4` first."));
     process.exitCode = 1;
     return;
   }
   const target = essence.blueprint.routes?.[route];
   if (!target) {
     const knownRoutes = Object.keys(essence.blueprint.routes ?? {}).sort();
-    console.error(error3(`Route not found in Decantr contract: ${route}`));
+    console.error(error2(`Route not found in Decantr contract: ${route}`));
     console.error(dim3(`Known routes: ${knownRoutes.join(", ") || "none"}`));
     process.exitCode = 1;
     return;
@@ -10201,6 +10556,11 @@ async function cmdTaskWorkflow(args) {
   const localPatternPackPath = localPatternsPath(workspaceInfo.appRoot);
   const localRuleManifestPath = localRulesPath(workspaceInfo.appRoot);
   const localLaw = createLocalLawTaskSummary(workspaceInfo.appRoot);
+  const displayedLocalLaw = {
+    ...localLaw,
+    patternsPath: localLaw.patternsPath ? displayProjectPath(workspaceInfo, localLaw.patternsPath) : null,
+    rulesPath: localLaw.rulesPath ? displayProjectPath(workspaceInfo, localLaw.rulesPath) : null
+  };
   const changedSince = flagString(flags, "since");
   const currentChangedFiles = changedFiles(workspaceInfo.appRoot, changedSince);
   const changedRoutes = routeImpacts(workspaceInfo.appRoot, currentChangedFiles);
@@ -10212,16 +10572,16 @@ async function cmdTaskWorkflow(args) {
     shell: page?.shell ?? section?.shell ?? null,
     patterns: page?.layout?.map(extractPatternName) ?? [],
     read: [
-      pagePack ? join31(".decantr/context", pagePack.markdown) : null,
-      sectionPack ? join31(".decantr/context", sectionPack.markdown) : null,
-      manifest?.scaffold?.markdown ? join31(".decantr/context", manifest.scaffold.markdown) : null,
-      ".decantr/context/scaffold.md",
-      "DECANTR.md",
-      existsSync29(localPatternPackPath) ? ".decantr/local-patterns.json" : null,
-      existsSync29(localRuleManifestPath) ? ".decantr/rules.json" : null
+      pagePack ? displayProjectPath(workspaceInfo, join31(".decantr/context", pagePack.markdown)) : null,
+      sectionPack ? displayProjectPath(workspaceInfo, join31(".decantr/context", sectionPack.markdown)) : null,
+      manifest?.scaffold?.markdown ? displayProjectPath(workspaceInfo, join31(".decantr/context", manifest.scaffold.markdown)) : null,
+      displayProjectPath(workspaceInfo, ".decantr/context/scaffold.md"),
+      displayProjectPath(workspaceInfo, "DECANTR.md"),
+      existsSync29(localPatternPackPath) ? displayProjectPath(workspaceInfo, ".decantr/local-patterns.json") : null,
+      existsSync29(localRuleManifestPath) ? displayProjectPath(workspaceInfo, ".decantr/rules.json") : null
     ].filter(Boolean),
-    screenshot: screenshot ?? null,
-    localLaw,
+    screenshot: screenshot?.startsWith(".decantr/") ? displayProjectPath(workspaceInfo, screenshot) : screenshot ?? null,
+    localLaw: displayedLocalLaw,
     changedFiles: currentChangedFiles,
     changedRoutes,
     verifyCommand: withProject("decantr verify --brownfield --local-patterns", projectArg)
@@ -10290,12 +10650,20 @@ async function cmdTaskWorkflow(args) {
 }
 async function cmdCodifyWorkflow(args) {
   const { flags } = parseLooseArgs(args);
+  const projectArg = flagString(flags, "project");
+  if (!ensureAllowedFlags(
+    flags,
+    ["project", "from-audit", "discover-local-patterns", "codify-local-patterns", "accept"],
+    "codify"
+  )) {
+    return;
+  }
   const workspaceInfo = resolveWorkflowProject(flags, "codify");
   if (!workspaceInfo) return;
   if (flagBoolean(flags, "accept")) {
     if (!existsSync29(localPatternsProposalPath(workspaceInfo.appRoot)) && !existsSync29(localRulesProposalPath(workspaceInfo.appRoot))) {
       console.error(
-        error3(
+        error2(
           "No local law proposal found. Run `decantr codify --from-audit` or `decantr codify` first."
         )
       );
@@ -10309,7 +10677,11 @@ async function cmdCodifyWorkflow(args) {
     if (result2.rulesAcceptedPath) {
       console.log(success3(`Accepted local rule manifest: ${result2.rulesAcceptedPath}`));
     }
-    console.log(dim3("Run `decantr verify --brownfield --local-patterns` after project edits."));
+    console.log(
+      dim3(
+        `Run \`${withProject("decantr verify --brownfield --local-patterns", projectArg)}\` after project edits.`
+      )
+    );
     return;
   }
   const detected = detectProject(workspaceInfo.appRoot);
@@ -10333,7 +10705,7 @@ async function cmdCodifyWorkflow(args) {
   }
   console.log(
     dim3(
-      "Review both files, add real component paths/token recipes, then run `decantr codify --accept`."
+      `Review both files, add real component paths/token recipes, then run \`${withProject("decantr codify --accept", projectArg)}\`.`
     )
   );
 }
@@ -10348,10 +10720,12 @@ async function cmdContentWorkflow(args) {
     return;
   }
   if (subcommand === "create") {
+    const { flags } = parseLooseArgs(args);
+    if (!ensureAllowedFlags(flags, [], "content create")) return;
     const type = args[2];
     const name = args[3];
     if (!type || !name) {
-      console.error(error3("Usage: decantr content create <type> <name>"));
+      console.error(error2("Usage: decantr content create <type> <name>"));
       process.exitCode = 1;
       return;
     }
@@ -10359,17 +10733,19 @@ async function cmdContentWorkflow(args) {
     return;
   }
   if (subcommand === "publish") {
+    const { flags } = parseLooseArgs(args);
+    if (!ensureAllowedFlags(flags, [], "content publish")) return;
     const type = args[2];
     const name = args[3];
     if (!type || !name) {
-      console.error(error3("Usage: decantr content publish <type> <name>"));
+      console.error(error2("Usage: decantr content publish <type> <name>"));
       process.exitCode = 1;
       return;
     }
     await cmdPublish(type, name);
     return;
   }
-  console.error(error3("Usage: decantr content <check|create|publish>"));
+  console.error(error2("Usage: decantr content <check|create|publish>"));
   process.exitCode = 1;
 }
 function cmdHelp() {
@@ -10905,10 +11281,10 @@ async function main() {
           }
         }
       }
-      console.error(error3("Could not resolve @decantr/cli version from package.json."));
+      console.error(error2("Could not resolve @decantr/cli version from package.json."));
       process.exitCode = 1;
     } catch (e) {
-      console.error(error3(`Failed to read CLI version: ${e.message}`));
+      console.error(error2(`Failed to read CLI version: ${e.message}`));
       process.exitCode = 1;
     }
     return;
@@ -10953,7 +11329,7 @@ async function main() {
       const newName = args[1];
       if (!newName) {
         console.error(
-          error3("Usage: decantr new <project-name> [--blueprint=X] [--archetype=X] [--theme=X]")
+          error2("Usage: decantr new <project-name> [--blueprint=X] [--archetype=X] [--theme=X]")
         );
         process.exitCode = 1;
         break;
@@ -11025,7 +11401,10 @@ async function main() {
       break;
     }
     case "status": {
-      await cmdStatus();
+      const { flags } = parseLooseArgs(args);
+      const workspaceInfo = resolveWorkflowProject(flags, "status");
+      if (!workspaceInfo) break;
+      await cmdStatus(workspaceInfo.appRoot);
       break;
     }
     case "sync": {
@@ -11034,8 +11413,11 @@ async function main() {
     }
     case "upgrade": {
       const { cmdUpgrade } = await import("./upgrade-VON7Y3LG.js");
+      const { flags } = parseLooseArgs(args);
+      const workspaceInfo = resolveWorkflowProject(flags, "upgrade");
+      if (!workspaceInfo) break;
       const applyFlag = args.includes("--apply");
-      await cmdUpgrade(process.cwd(), { apply: applyFlag });
+      await cmdUpgrade(workspaceInfo.appRoot, { apply: applyFlag });
       break;
     }
     case "check":
@@ -11045,13 +11427,16 @@ async function main() {
           `${YELLOW10}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;
       const telemetryFlag = args.includes("--telemetry");
       const brownfieldFlag = args.includes("--brownfield");
-      await cmdHeal(workspaceInfo.appRoot, { telemetry: telemetryFlag, brownfield: brownfieldFlag });
+      await cmdHeal(workspaceInfo.appRoot, {
+        telemetry: telemetryFlag,
+        brownfield: brownfieldFlag
+      });
       break;
     }
     case "health": {
@@ -11060,10 +11445,17 @@ async function main() {
           cmdHealthHelp();
           break;
         }
-        const { cmdHealth, parseHealthArgs } = await import("./health-LTDSTNOV.js");
-        await cmdHealth(process.cwd(), parseHealthArgs(args));
+        if (args[1] === "init-ci") {
+          await cmdCi(["ci", "init", ...args.slice(2)], process.cwd());
+          break;
+        }
+        const { flags } = parseLooseArgs(args);
+        const workspaceInfo = resolveWorkflowProject(flags, "health");
+        if (!workspaceInfo) break;
+        const { cmdHealth, parseHealthArgs } = await import("./health-R7AV5G4V.js");
+        await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(stripProjectArgs(args)));
       } catch (e) {
-        console.error(error3(e.message));
+        console.error(error2(e.message));
         process.exitCode = 1;
       }
       break;
@@ -11077,7 +11469,7 @@ async function main() {
         const { cmdContentHealth, parseContentHealthArgs } = await import("./content-health-4KP2EGTI.js");
         await cmdContentHealth(process.cwd(), parseContentHealthArgs(args));
       } catch (e) {
-        console.error(error3(e.message));
+        console.error(error2(e.message));
         process.exitCode = 1;
       }
       break;
@@ -11088,10 +11480,10 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-7E2LJS3A.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-2734P63C.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
-        console.error(error3(e.message));
+        console.error(error2(e.message));
         process.exitCode = 1;
       }
       break;
@@ -11102,10 +11494,10 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-53EIHUXB.js");
+        const { cmdWorkspace } = await import("./workspace-DRHTQ2NG.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
-        console.error(error3(e.message));
+        console.error(error2(e.message));
         process.exitCode = 1;
       }
       break;
@@ -11128,7 +11520,7 @@ async function main() {
         if (result.success) {
           console.log(success3(clearFlag ? "Drift log cleared." : "Entries resolved."));
         } else {
-          console.error(error3(result.error || "Failed"));
+          console.error(error2(result.error || "Failed"));
           process.exitCode = 1;
         }
       } else {
@@ -11144,7 +11536,7 @@ async function main() {
       const query = args[1];
       if (!query) {
         console.error(
-          error3(
+          error2(
             "Usage: decantr search <query> [--type <type>] [--sort <recommended|recent|name>] [--source <authored|benchmark|hybrid>] [--blueprint-set <all|featured|certified|labs>]"
           )
         );
@@ -11162,7 +11554,7 @@ async function main() {
       const blueprintSet = rawBlueprintSet && isPublicBlueprintSet(rawBlueprintSet) ? rawBlueprintSet : void 0;
       if (rawBlueprintSet && !blueprintSet) {
         console.error(
-          error3(
+          error2(
             `Invalid blueprint set "${rawBlueprintSet}". Must be one of: all, featured, certified, labs.`
           )
         );
@@ -11171,7 +11563,7 @@ async function main() {
       }
       if (intelligenceSource && !isContentIntelligenceSource(intelligenceSource)) {
         console.error(
-          error3(
+          error2(
             `Invalid source "${intelligenceSource}". Must be one of: authored, benchmark, hybrid.`
           )
         );
@@ -11183,31 +11575,51 @@ async function main() {
       break;
     }
     case "suggest": {
-      const query = args[1];
+      const { flags, positional } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["type", "route", "file", "from-code", "project"], "suggest")) {
+        break;
+      }
+      const projectArg = flagString(flags, "project");
+      const route = flagString(flags, "route");
+      let file = flagString(flags, "file");
+      const normalizedProject = normalizedProjectPath(projectArg);
+      if (file && normalizedProject && normalizedProjectPath(file)?.startsWith(`${normalizedProject}/`)) {
+        file = normalizedProjectPath(file)?.slice(normalizedProject.length + 1);
+      }
+      const fromCode = flagBoolean(flags, "from-code");
+      let query = positional.join(" ").trim();
+      if (!query && (route || file || fromCode)) {
+        query = [
+          route ? `route ${route}` : null,
+          file ? `file ${basename3(file)}` : null,
+          fromCode ? "source code patterns" : null
+        ].filter((entry) => Boolean(entry)).join(" ");
+      }
       if (!query) {
         console.error(
-          error3(
-            "Usage: decantr suggest <query> [--type <type>] [--route <route>] [--file <path>] [--from-code]"
+          error2(
+            "Usage: decantr suggest <query> [--type <type>] [--route <route>] [--file <path>] [--from-code] [--project <path>]"
           )
         );
         process.exitCode = 1;
         return;
       }
-      const typeIdx = args.indexOf("--type");
-      const type = typeIdx !== -1 ? args[typeIdx + 1] : void 0;
-      const routeIdx = args.indexOf("--route");
-      const route = routeIdx !== -1 ? args[routeIdx + 1] : void 0;
-      const fileIdx = args.indexOf("--file");
-      const file = fileIdx !== -1 ? args[fileIdx + 1] : void 0;
-      const fromCode = args.includes("--from-code");
-      await cmdSuggest(query, { type, route, file, fromCode });
+      const workspaceInfo = projectArg ? resolveWorkflowProject(flags, "suggest") : null;
+      if (projectArg && !workspaceInfo) break;
+      await cmdSuggest(query, {
+        type: flagString(flags, "type"),
+        route,
+        file,
+        fromCode,
+        projectRoot: workspaceInfo?.appRoot
+      });
       break;
     }
     case "get": {
       const type = args[1];
       const id = args[2];
       if (!type || !id) {
-        console.error(error3("Usage: decantr get <type> <id>"));
+        console.error(error2("Usage: decantr get <type> <id>"));
         process.exitCode = 1;
         return;
       }
@@ -11218,7 +11630,7 @@ async function main() {
       const type = args[1];
       if (!type) {
         console.error(
-          error3(
+          error2(
             "Usage: decantr list <type> [--sort <recommended|recent|name>] [--source <authored|benchmark|hybrid>] [--blueprint-set <all|featured|certified|labs>]"
           )
         );
@@ -11234,7 +11646,7 @@ async function main() {
       const blueprintSet = rawBlueprintSet && isPublicBlueprintSet(rawBlueprintSet) ? rawBlueprintSet : void 0;
       if (rawBlueprintSet && !blueprintSet) {
         console.error(
-          error3(
+          error2(
             `Invalid blueprint set "${rawBlueprintSet}". Must be one of: all, featured, certified, labs.`
           )
         );
@@ -11243,7 +11655,7 @@ async function main() {
       }
       if (intelligenceSource && !isContentIntelligenceSource(intelligenceSource)) {
         console.error(
-          error3(
+          error2(
             `Invalid source "${intelligenceSource}". Must be one of: authored, benchmark, hybrid.`
           )
         );
@@ -11263,7 +11675,7 @@ async function main() {
         break;
       }
       if (requestedView && !["manifest", "shortlist", "verification"].includes(requestedView)) {
-        console.error(error3("Usage: decantr showcase [manifest|shortlist|verification] [--json]"));
+        console.error(error2("Usage: decantr showcase [manifest|shortlist|verification] [--json]"));
         process.exitCode = 1;
         break;
       }
@@ -11275,7 +11687,10 @@ async function main() {
       break;
     }
     case "theme": {
-      await cmdTheme(args.slice(1));
+      const { flags } = parseLooseArgs(args);
+      const workspaceInfo = flagString(flags, "project") ? resolveWorkflowProject(flags, "theme") : null;
+      if (flagString(flags, "project") && !workspaceInfo) break;
+      await cmdTheme(stripProjectArgs(args).slice(1), workspaceInfo?.appRoot ?? process.cwd());
       break;
     }
     case "login": {
@@ -11309,14 +11724,19 @@ async function main() {
       break;
     }
     case "telemetry": {
-      await cmdTelemetry(args.slice(1), process.cwd());
+      const { flags } = parseLooseArgs(args);
+      const workspaceInfo = flagString(flags, "project") ? resolveWorkflowProject(flags, "telemetry") : null;
+      if (flagString(flags, "project") && !workspaceInfo) break;
+      await cmdTelemetry(stripProjectArgs(args).slice(1), workspaceInfo?.appRoot ?? process.cwd());
       break;
     }
     case "create": {
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, [], "create")) break;
       const type = args[1];
       const name = args[2];
       if (!type || !name) {
-        console.error(error3("Usage: decantr create <type> <name>"));
+        console.error(error2("Usage: decantr create <type> <name>"));
         console.error(dim3("Types: pattern, theme, blueprint, archetype, shell"));
         process.exitCode = 1;
         break;
@@ -11325,10 +11745,12 @@ async function main() {
       break;
     }
     case "publish": {
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, [], "publish")) break;
       const type = args[1];
       const name = args[2];
       if (!type || !name) {
-        console.error(error3("Usage: decantr publish <type> <name>"));
+        console.error(error2("Usage: decantr publish <type> <name>"));
         console.error(dim3("Types: pattern, theme, blueprint, archetype, shell"));
         process.exitCode = 1;
         break;
@@ -11345,7 +11767,8 @@ async function main() {
         offline: refreshOffline,
         check: args.includes("--check"),
         listChanges: args.includes("--list-changes"),
-        json: args.includes("--json")
+        json: args.includes("--json"),
+        displayRoot: workspaceInfo.cwd
       });
       break;
     }
@@ -11380,7 +11803,7 @@ async function main() {
         let id = args[3] && !args[3].startsWith("--") ? args[3] : void 0;
         if (!packType || !["manifest", "scaffold", "review", "section", "page", "mutation"].includes(packType)) {
           console.error(
-            `${RED13}Usage: decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]${RESET16}`
+            `${RED12}Usage: decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]${RESET16}`
           );
           process.exitCode = 1;
           break;
@@ -11412,7 +11835,7 @@ async function main() {
         const sourcePath = args[2] && !args[2].startsWith("--") ? args[2] : void 0;
         if (!sourcePath) {
           console.error(
-            `${RED13}Usage: decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]${RESET16}`
+            `${RED12}Usage: decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]${RESET16}`
           );
           process.exitCode = 1;
           break;
@@ -11437,16 +11860,20 @@ async function main() {
         await printHostedProjectAudit(namespace, jsonOutput, essencePath, distPath, sourcesPath);
       } else {
         console.error(
-          `${RED13}Usage: decantr registry mirror [--type <type>] | decantr registry summary [--namespace <namespace>] [--json] | decantr registry compile-packs [path] [--namespace <namespace>] [--json] [--write-context] | decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context] | decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>] | decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]${RESET16}`
+          `${RED12}Usage: decantr registry mirror [--type <type>] | decantr registry summary [--namespace <namespace>] [--json] | decantr registry compile-packs [path] [--namespace <namespace>] [--json] [--write-context] | decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context] | decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>] | decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]${RESET16}`
         );
         process.exitCode = 1;
       }
       break;
     }
     case "add": {
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["project", "route", "section"], "add")) break;
+      const workspaceInfo = resolveWorkflowProject(flags, "add");
+      if (!workspaceInfo) break;
       const subcommand = args[1];
       if (!subcommand) {
-        console.error(error3("Usage: decantr add <section|page|feature> <target>"));
+        console.error(error2("Usage: decantr add <section|page|feature> <target>"));
         process.exitCode = 1;
         break;
       }
@@ -11454,45 +11881,49 @@ async function main() {
         case "section": {
           const id = args[2];
           if (!id) {
-            console.error(error3("Usage: decantr add section <archetypeId>"));
+            console.error(error2("Usage: decantr add section <archetypeId>"));
             process.exitCode = 1;
             break;
           }
-          await cmdAddSection(id, args, process.cwd());
+          await cmdAddSection(id, args, workspaceInfo.appRoot);
           break;
         }
         case "page": {
           const pagePath = args[2];
           if (!pagePath) {
-            console.error(error3("Usage: decantr add page <section>/<page>"));
+            console.error(error2("Usage: decantr add page <section>/<page>"));
             process.exitCode = 1;
             break;
           }
-          await cmdAddPage(pagePath, args, process.cwd());
+          await cmdAddPage(pagePath, args, workspaceInfo.appRoot);
           break;
         }
         case "feature": {
           const feature = args[2];
           if (!feature) {
-            console.error(error3("Usage: decantr add feature <feature> [--section <id>]"));
+            console.error(error2("Usage: decantr add feature <feature> [--section <id>]"));
             process.exitCode = 1;
             break;
           }
-          await cmdAddFeature(feature, args, process.cwd());
+          await cmdAddFeature(feature, args, workspaceInfo.appRoot);
           break;
         }
         default:
           console.error(
-            error3(`Unknown add subcommand: ${subcommand}. Use section, page, or feature.`)
+            error2(`Unknown add subcommand: ${subcommand}. Use section, page, or feature.`)
           );
           process.exitCode = 1;
       }
       break;
     }
     case "remove": {
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["project", "section"], "remove")) break;
+      const workspaceInfo = resolveWorkflowProject(flags, "remove");
+      if (!workspaceInfo) break;
       const subcommand = args[1];
       if (!subcommand) {
-        console.error(error3("Usage: decantr remove <section|page|feature> <target>"));
+        console.error(error2("Usage: decantr remove <section|page|feature> <target>"));
         process.exitCode = 1;
         break;
       }
@@ -11500,56 +11931,54 @@ async function main() {
         case "section": {
           const id = args[2];
           if (!id) {
-            console.error(error3("Usage: decantr remove section <sectionId>"));
+            console.error(error2("Usage: decantr remove section <sectionId>"));
             process.exitCode = 1;
             break;
           }
-          await cmdRemoveSection(id, args, process.cwd());
+          await cmdRemoveSection(id, args, workspaceInfo.appRoot);
           break;
         }
         case "page": {
           const pagePath = args[2];
           if (!pagePath) {
-            console.error(error3("Usage: decantr remove page <section>/<page>"));
+            console.error(error2("Usage: decantr remove page <section>/<page>"));
             process.exitCode = 1;
             break;
           }
-          await cmdRemovePage(pagePath, args, process.cwd());
+          await cmdRemovePage(pagePath, args, workspaceInfo.appRoot);
           break;
         }
         case "feature": {
           const feature = args[2];
           if (!feature) {
-            console.error(error3("Usage: decantr remove feature <feature> [--section <id>]"));
+            console.error(error2("Usage: decantr remove feature <feature> [--section <id>]"));
             process.exitCode = 1;
             break;
           }
-          await cmdRemoveFeature(feature, args, process.cwd());
+          await cmdRemoveFeature(feature, args, workspaceInfo.appRoot);
           break;
         }
         default:
           console.error(
-            error3(`Unknown remove subcommand: ${subcommand}. Use section, page, or feature.`)
+            error2(`Unknown remove subcommand: ${subcommand}. Use section, page, or feature.`)
           );
           process.exitCode = 1;
       }
       break;
     }
     case "analyze": {
-      let projectArg;
-      for (let i = 1; i < args.length; i++) {
-        if (args[i].startsWith("--project=")) {
-          projectArg = args[i].split("=")[1];
-        } else if (args[i] === "--project" && args[i + 1]) {
-          projectArg = args[++i];
-        }
-      }
-      const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
-      if (workspaceInfo.requiresProjectSelection) {
-        printWorkspaceProjectSelection(workspaceInfo, "analyze");
-        process.exitCode = 1;
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(
+        flags,
+        ["project", "force-package", "allow-package", "force"],
+        "analyze"
+      )) {
         break;
       }
+      const workspaceInfo = resolveWorkflowProject(flags, "analyze", {
+        requireAppCandidate: true
+      });
+      if (!workspaceInfo) break;
       await cmdAnalyze(workspaceInfo.appRoot, workspaceInfo);
       break;
     }
@@ -11560,24 +11989,14 @@ async function main() {
         break;
       }
       if (subcommand !== "apply" && subcommand !== "preview") {
-        console.error(error3("Usage: decantr rules <preview|apply> [--project=<path>]"));
-        process.exitCode = 1;
-        break;
-      }
-      let projectArg;
-      for (let i = 2; i < args.length; i++) {
-        if (args[i].startsWith("--project=")) {
-          projectArg = args[i].split("=")[1];
-        } else if (args[i] === "--project" && args[i + 1]) {
-          projectArg = args[++i];
-        }
-      }
-      const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
-      if (workspaceInfo.requiresProjectSelection) {
-        printWorkspaceProjectSelection(workspaceInfo, "rules");
+        console.error(error2("Usage: decantr rules <preview|apply> [--project=<path>]"));
         process.exitCode = 1;
         break;
       }
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["project"], "rules")) break;
+      const workspaceInfo = resolveWorkflowProject(flags, "rules");
+      if (!workspaceInfo) break;
       const detected = detectProject(workspaceInfo.appRoot);
       if (subcommand === "preview") {
         console.log(
@@ -11598,24 +12017,18 @@ async function main() {
       break;
     }
     case "magic": {
-      const magicFlags = {};
-      const promptParts = [];
-      for (let i = 1; i < args.length; i++) {
-        if (args[i] === "--dry-run") {
-          magicFlags.dryRun = true;
-        } else if (args[i] === "--offline") {
-          magicFlags.offline = true;
-        } else if (args[i].startsWith("--registry=")) {
-          magicFlags.registry = args[i].split("=")[1];
-        } else if (args[i].startsWith("--registry") && args[i + 1]) {
-          magicFlags.registry = args[++i];
-        } else {
-          promptParts.push(args[i]);
-        }
+      const { flags, positional } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["dry-run", "offline", "registry", "project"], "magic")) {
+        break;
       }
-      const magicPrompt = promptParts.join(" ").trim();
+      const workspaceInfo = flagString(flags, "project") ? resolveWorkflowProject(flags, "magic") : null;
+      if (flagString(flags, "project") && !workspaceInfo) break;
+      const projectArg = flagString(flags, "project");
+      const magicPrompt = positional.join(" ").trim();
       if (!magicPrompt) {
-        console.error(error3("Usage: decantr magic <prompt> [--dry-run] [--offline]"));
+        console.error(
+          error2("Usage: decantr magic <prompt> [--dry-run] [--offline] [--project <path>]")
+        );
         console.error("");
         console.error("  Example:");
         console.error(
@@ -11624,38 +12037,34 @@ async function main() {
         process.exitCode = 1;
         break;
       }
-      await cmdMagic(magicPrompt, process.cwd(), {
-        dryRun: magicFlags.dryRun,
-        offline: magicFlags.offline,
-        registry: magicFlags.registry
+      await cmdMagic(magicPrompt, workspaceInfo?.appRoot ?? process.cwd(), {
+        dryRun: flagBoolean(flags, "dry-run"),
+        offline: flagBoolean(flags, "offline"),
+        registry: flagString(flags, "registry"),
+        projectLabel: projectArg
       });
       break;
     }
     case "export": {
-      let exportTarget;
-      let exportOutput;
-      for (let i = 1; i < args.length; i++) {
-        if (args[i] === "--to" && args[i + 1]) {
-          exportTarget = args[++i];
-        } else if (args[i].startsWith("--to=")) {
-          exportTarget = args[i].split("=")[1];
-        } else if (args[i] === "--output" && args[i + 1]) {
-          exportOutput = args[++i];
-        } else if (args[i].startsWith("--output=")) {
-          exportOutput = args[i].split("=")[1];
-        }
-      }
+      const { flags } = parseLooseArgs(args);
+      if (!ensureAllowedFlags(flags, ["to", "output", "project"], "export")) break;
+      const workspaceInfo = flagString(flags, "project") ? resolveWorkflowProject(flags, "export") : null;
+      if (flagString(flags, "project") && !workspaceInfo) break;
+      const exportTarget = flagString(flags, "to");
+      const exportOutput = flagString(flags, "output");
       const validTargets = ["shadcn", "tailwind", "css-vars", "figma-tokens"];
       if (!exportTarget || !validTargets.includes(exportTarget)) {
-        console.error(error3(`Usage: decantr export --to <${validTargets.join("|")}>`));
+        console.error(error2(`Usage: decantr export --to <${validTargets.join("|")}>`));
         process.exitCode = 1;
         break;
       }
-      await cmdExport(exportTarget, process.cwd(), { output: exportOutput });
+      await cmdExport(exportTarget, workspaceInfo?.appRoot ?? process.cwd(), {
+        output: exportOutput
+      });
       break;
     }
     default:
-      console.error(error3(`Unknown command: ${command}`));
+      console.error(error2(`Unknown command: ${command}`));
       cmdHelp();
       process.exitCode = 1;
   }
@@ -11670,7 +12079,7 @@ main().then(async () => {
     success: !process.exitCode || process.exitCode === 0
   });
 }).catch(async (e) => {
-  console.error(error3(e.message));
+  console.error(error2(e.message));
   if (e.stack) console.error(e.stack);
   process.exitCode = 1;
   await sendCliCommandTelemetry({