@decantr/cli 2.6.0 → 2.7.0

package/README.md

@@ -17,9 +17,11 @@ Or run it without installing:
 npx @decantr/cli new my-app --blueprint=esports-hq
 ```
 
+Use `decantr setup` when you are unsure which path applies. It detects whether the repo is empty, already attached, or a Brownfield app and recommends the next command.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
-Use `decantr analyze` first when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, and only applies it when you explicitly accept or merge it.
-Use `decantr init` to attach Decantr contract/context files to an existing project or to create a contract-only workspace.
+Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, and only applies it when you explicitly accept or merge it.
+Use `decantr task` before asking an LLM to modify a route, and `decantr verify` after the edit. Use `decantr codify` when you want project-owned UI patterns such as local button/card/shell standards to appear in future task context.
+Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
 Current starter adapter availability:
 
@@ -35,6 +37,12 @@ Current starter adapter availability:
 Explicit workflow/adoption flags:
 
 ```bash
+decantr setup
+decantr adopt --base-url http://localhost:3000 --evidence --yes
+decantr task /feed "add saved recipe actions"
+decantr verify --brownfield
+decantr codify
+decantr codify --accept
 decantr init --workflow=greenfield --adoption=contract-only
 decantr analyze
 decantr init --existing --accept-proposal
@@ -57,11 +65,12 @@ Monorepos store both `workspaceRoot` and `appRoot`. In non-interactive workspace
 
 Assistant rule integration is preview-first: `--assistant-bridge=preview` writes `.decantr/context/assistant-bridge.md`, `decantr rules preview` prints the bridge, and `--assistant-bridge=apply` or `decantr rules apply` mutates supported rule files with idempotent marked blocks.
 
-Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. In 2.6 it also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr check --brownfield` uses the doctrine map to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, and unsafe defaults without treating current database migrations as stale docs.
+Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-precedence map across security/data, architecture, design-system, workflow/CI, feature/business, assistant-specific, stale, and unsafe-to-cite evidence. It also writes `.decantr/brownfield-intelligence.json`, `.decantr/theme-inventory.json`, and `.decantr/enrichment-backlog.md`. The proposal groups routes into observed semantic domains such as auth, RBAC, billing, reporting, facilities, settings, and public surfaces across Next App/Pages Router, React Router, Angular Router, SvelteKit, Vue Router, and Nuxt file routes. Existing styling systems such as Tailwind, Bootstrap, MUI, Chakra, plain CSS, and Decantr CSS are observed as evidence instead of replaced. Theme variants are observed in the theme inventory without changing Essence V4. `decantr verify --brownfield` uses the Brownfield guard layer to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, and unsafe defaults without treating current database migrations as stale docs.
 
 ## What It Does
 
 - scaffolds Decantr projects from blueprints, archetypes, or prompts
+- guides users through human workflow commands: setup, adopt, task, verify, and codify
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
@@ -75,10 +84,12 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 ## Common Commands
 
 ```bash
+decantr setup
 decantr new my-app --blueprint=esports-hq
-decantr analyze
-decantr init --existing --accept-proposal
-decantr check --brownfield
+decantr adopt --base-url http://localhost:3000 --evidence --yes
+decantr task /feed "add saved recipe actions"
+decantr verify --brownfield --local-patterns
+decantr codify
 decantr init --existing --blueprint=esports-hq
 decantr init --workflow=greenfield --adoption=contract-only
 decantr rules preview
@@ -86,12 +97,12 @@ decantr rules apply
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check
-decantr health --ci --fail-on error
+decantr verify --ci --fail-on error
 decantr studio --port 4319 --host 127.0.0.1
 decantr telemetry status
 decantr telemetry explain
 decantr telemetry link --enable --org <org-slug>
-decantr content-health --ci --fail-on error
+decantr content check --ci --fail-on error
 decantr registry summary --namespace @official --json
 decantr list blueprints --blueprint-set featured
 decantr list blueprints --blueprint-set certified
@@ -103,9 +114,16 @@ decantr showcase verification --json
 
 ## Project Health And Studio
 
-`decantr health` is the local project observability command. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
+`decantr verify` is the workflow command most users should run locally and in CI. It delegates to Project Health, can add Brownfield guard validation with `--brownfield`, requires an accepted local pattern pack with `--local-patterns`, supports workspace mode, and writes evidence to `.decantr/evidence/latest.json` by default when `--evidence` is used.
+
+`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
 
 ```bash
+decantr verify
+decantr verify --brownfield --local-patterns
+decantr verify --base-url http://localhost:3000 --evidence
+decantr verify --since-baseline
+decantr verify init-ci --project apps/registry
 decantr health
 decantr health --format json
 decantr health --markdown --output health.md
@@ -118,18 +136,18 @@ decantr health --save-baseline
 decantr health --since-baseline
 decantr health --design-tokens .decantr/design/figma-tokens.json
 decantr health --json --output decantr-health.json
-decantr health init-ci
-decantr health init-ci --fail-on warn --cli-version latest --force
-decantr health init-ci --project apps/registry
-decantr health init-ci --workspace
+decantr verify init-ci
+decantr verify init-ci --fail-on warn --cli-version latest --force
+decantr verify init-ci --project apps/registry
+decantr verify init-ci --workspace
 decantr workspace list
-decantr workspace health --changed --since origin/main
+decantr verify --workspace --changed --since origin/main
 decantr export --to figma-tokens
 ```
 
 Use `--json` for machines and schema validation, `--markdown` for CI summaries, `--evidence` for the privacy-redacted Evidence Bundle, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. The prompt command prints instructions only; it does not modify source files. `--browser` uses a project-local Playwright install and a supplied base URL to capture local route screenshots under `.decantr/evidence/screenshots/` and write `.decantr/evidence/visual-manifest.json`; missing Playwright becomes a setup finding, not a crash. `--save-baseline` writes `.decantr/health-baseline.json`; `--since-baseline` writes `.decantr/health-baseline-diff.json` with changed files, route impact, finding deltas, screenshot hash drift, and contract drift. `--design-tokens <path>` compares a Tokens Studio/Figma token JSON export against Decantr CSS token names. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
 
-`decantr health init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes JSON/markdown health artifacts, gates with `decantr health --ci --fail-on error --markdown --output decantr-health.md`, appends the markdown report to the GitHub step summary, and uploads both files as artifacts. Use `--force` to replace an existing workflow, `--fail-on warn` for stricter repositories, or `--cli-version <version|latest>` to pin the package used by CI. In monorepos, add `--project <path>` from the repository root; dependency install stays at the root while health runs inside the app contract and uploads artifacts from that project path. Use `--workspace` to generate an aggregate gate that runs `decantr workspace health` from the repository root and uploads `.decantr/workspace-health.json` plus `.decantr/workspace-health.md`.
+`decantr verify init-ci` installs `.github/workflows/decantr-health.yml` for GitHub Actions. The generated workflow installs project dependencies, writes JSON/markdown health artifacts, gates with the Project Health CI command, appends the markdown report to the GitHub step summary, and uploads both files as artifacts. Use `--force` to replace an existing workflow, `--fail-on warn` for stricter repositories, or `--cli-version <version|latest>` to pin the package used by CI. In monorepos, add `--project <path>` from the repository root; dependency install stays at the root while health runs inside the app contract and uploads artifacts from that project path. Use `--workspace` to generate an aggregate gate that runs `decantr workspace health` from the repository root and uploads `.decantr/workspace-health.json` plus `.decantr/workspace-health.md`.
 
 `decantr workspace` is the monorepo reliability namespace. It discovers Decantr projects from `.decantr/workspace.json` or by finding `decantr.essence.json` files, runs projects with deterministic ordering, concurrency, per-project timeout, failure isolation, and aggregate JSON, and can limit a run to changed projects:
 
@@ -137,7 +155,7 @@ Use `--json` for machines and schema validation, `--markdown` for CI summaries,
 decantr workspace list
 decantr workspace health
 decantr workspace health --json --output .decantr/workspace-health.json
-decantr workspace health --changed --since origin/main
+decantr verify --workspace --changed --since origin/main
 ```
 
 `decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
@@ -181,9 +199,11 @@ decantr telemetry link --enable --org <org-slug>
 
 ## Content Health
 
-`decantr content-health` is the local supply-chain observability command for registry content repositories such as `decantr-content`. It is separate from Project Health: Project Health checks an end-user app against its Decantr contract, while Content Health checks published content inputs before they flow into the hosted registry.
+`decantr content check` is the preferred content-author workflow for registry content repositories such as `decantr-content`. `decantr content-health` remains as a backward-compatible primitive. Content Health is separate from Project Health: Project Health checks an end-user app against its Decantr contract, while Content Health checks published content inputs before they flow into the hosted registry.
 
 ```bash
+decantr content check
+decantr content check --ci --fail-on error
 decantr content-health
 decantr content-health --json
 decantr content-health --markdown --output content-health.md
@@ -237,7 +257,7 @@ It covers:
 
 - greenfield blueprint bootstrap
 - greenfield contract-only
-- brownfield `analyze -> init --existing --accept-proposal -> check --brownfield`
+- brownfield `adopt -> task -> verify`, with `analyze -> init --existing --accept-proposal -> check --brownfield` still covered as primitives
 - brownfield doctrine maps and contract coverage checks
 - brownfield semantic route-domain sectioning
 - direct brownfield compatibility init
@@ -270,7 +290,7 @@ Recommended read order for AI-assisted scaffolding:
 
 Treat the compiled execution packs as the source of truth. Use the narrative docs as secondary explanation, start with the shell and route structure first, and run `decantr check` plus `decantr audit` after implementation.
 
-For a broader health pass, run `decantr health` after `refresh`, before opening a pull request, or inside CI. Install the default GitHub Actions gate with `decantr health init-ci`. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
+For a broader health pass, run `decantr verify` after `refresh`, before opening a pull request, or inside CI. Install the default GitHub Actions gate with `decantr verify init-ci`. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
 
 For cold-start harness or certification runs, use only the scaffolded workspace files as the contract. If local scaffold files disagree, stop and report the mismatch rather than relying on repo-global Decantr assumptions.
 

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-Q5OFRQY6.js";
+import "./chunk-ZYHR3BGT.js";
 import "./chunk-V3XAQWKD.js";
 import "./chunk-KT2ROK2D.js";

package/dist/{chunk-Q5OFRQY6.js → chunk-ZYHR3BGT.js}

@@ -8293,14 +8293,483 @@ ${BOLD7}Examples:${RESET14}
       process.exitCode = 1;
   }
 }
+function parseLooseArgs(args, startIndex = 1) {
+  const flags = {};
+  const positional = [];
+  for (let index = startIndex; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-y") {
+      flags.yes = true;
+      continue;
+    }
+    if (arg.startsWith("--no-")) {
+      flags[arg.slice(5)] = false;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const body = arg.slice(2);
+      const equalsIndex = body.indexOf("=");
+      if (equalsIndex !== -1) {
+        flags[body.slice(0, equalsIndex)] = body.slice(equalsIndex + 1);
+        continue;
+      }
+      if (args[index + 1] && !args[index + 1].startsWith("-")) {
+        flags[body] = args[++index];
+      } else {
+        flags[body] = true;
+      }
+      continue;
+    }
+    positional.push(arg);
+  }
+  return { flags, positional };
+}
+function flagString(flags, key) {
+  const value = flags[key];
+  return typeof value === "string" ? value : void 0;
+}
+function flagBoolean(flags, key, defaultValue = false) {
+  const value = flags[key];
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value !== "false";
+  return defaultValue;
+}
+function withoutWorkflowOnlyFlags(args) {
+  const stripped = [];
+  const flagsWithValues = /* @__PURE__ */ new Set(["--project"]);
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--brownfield" || arg === "--local-patterns" || arg === "--workspace" || arg === "--baseline") {
+      continue;
+    }
+    if (arg.startsWith("--project=")) {
+      continue;
+    }
+    if (flagsWithValues.has(arg)) {
+      index += 1;
+      continue;
+    }
+    stripped.push(arg);
+  }
+  return stripped;
+}
+function resolveWorkflowProject(flags) {
+  const projectArg = flagString(flags, "project");
+  const workspaceInfo = resolveWorkspaceInfo(process.cwd(), projectArg);
+  if (workspaceInfo.requiresProjectSelection) {
+    console.log(error3("This looks like a workspace root with multiple app candidates."));
+    console.log(dim3(`Use --project=<path>. Candidates: ${workspaceInfo.appCandidates.join(", ")}`));
+    process.exitCode = 1;
+    return null;
+  }
+  return workspaceInfo;
+}
+function printWorkflowPlan(title, steps) {
+  console.log(heading2(title));
+  console.log("  Decantr will run this workflow:");
+  for (const step of steps) {
+    console.log(`    ${cyan3(step)}`);
+  }
+  console.log("");
+}
+async function cmdSetupWorkflow(args) {
+  const { flags } = parseLooseArgs(args);
+  const workspaceInfo = resolveWorkflowProject(flags);
+  if (!workspaceInfo) return;
+  const detected = detectProject(workspaceInfo.appRoot);
+  const hasFootprint = detected.framework !== "unknown" || detected.packageManager !== "unknown" || detected.hasTypeScript || detected.hasTailwind || detected.existingRuleFiles.length > 0;
+  console.log(heading2("Decantr Setup"));
+  console.log(`  Project: ${workspaceInfo.appRoot}`);
+  console.log(`  Detected: ${formatDetection(detected)}`);
+  console.log("");
+  if (detected.existingEssence) {
+    console.log(`${BOLD7}Recommended path:${RESET14} maintain an attached Decantr project`);
+    console.log(`  ${cyan3('decantr task <route> "<change>"')}  Prepare LLM context before edits`);
+    console.log(`  ${cyan3("decantr verify")}                  Run local health and drift checks`);
+    console.log(`  ${cyan3("decantr codify")}                  Propose project-owned UI patterns`);
+    return;
+  }
+  if (hasFootprint) {
+    console.log(`${BOLD7}Recommended path:${RESET14} brownfield adoption`);
+    console.log(`  ${cyan3("decantr adopt --yes")}                       Analyze, attach, and verify`);
+    console.log(
+      `  ${cyan3("decantr adopt --base-url http://localhost:3000 --evidence --yes")}  Include visual evidence`
+    );
+    console.log(`  ${cyan3("decantr codify")}                            Propose local UI law`);
+    return;
+  }
+  console.log(`${BOLD7}Recommended path:${RESET14} greenfield start`);
+  console.log(`  ${cyan3("decantr new my-app --blueprint=<slug>")}`);
+  console.log(`  ${cyan3("decantr init --workflow=greenfield --adoption=contract-only")}`);
+}
+async function cmdAdoptWorkflow(args) {
+  const { flags } = parseLooseArgs(args);
+  const workspaceInfo = resolveWorkflowProject(flags);
+  if (!workspaceInfo) return;
+  const projectRoot = workspaceInfo.appRoot;
+  const dryRun = flagBoolean(flags, "dry-run");
+  const yes = flagBoolean(flags, "yes") || flagBoolean(flags, "y");
+  const baseUrl = flagString(flags, "base-url");
+  const runVerify = flagBoolean(flags, "verify", true);
+  const runBrowser = flagBoolean(flags, "browser") || Boolean(baseUrl);
+  const evidence = flagBoolean(flags, "evidence") || runBrowser;
+  const saveBaseline = flagBoolean(flags, "baseline", true) || flagBoolean(flags, "save-baseline");
+  const initCi = flagBoolean(flags, "ci") || flagBoolean(flags, "init-ci");
+  const assistantBridge = flagString(flags, "assistant-bridge");
+  const hasEssence = existsSync27(join28(projectRoot, "decantr.essence.json"));
+  const proposalFlag = flagBoolean(flags, "replace-essence") ? "--replace-essence" : flagBoolean(flags, "merge-proposal") || hasEssence ? "--merge-proposal" : "--accept-proposal";
+  const steps = [
+    "analyze current app and write .decantr/brownfield intelligence",
+    `init --existing ${proposalFlag} as contract-only Brownfield`
+  ];
+  if (runVerify) {
+    steps.push(
+      runBrowser ? "verify with Project Health, browser evidence, visual manifest, and baseline" : "verify with Project Health and baseline"
+    );
+  }
+  if (initCi) {
+    steps.push("install Project Health CI gate");
+  }
+  printWorkflowPlan("Decantr Adopt", steps);
+  if (dryRun) {
+    console.log(dim3("Dry run only. No files were written."));
+    return;
+  }
+  if (!yes) {
+    const ok = await confirm("Run this Brownfield adoption workflow?", false);
+    if (!ok) {
+      console.log(dim3("Cancelled."));
+      return;
+    }
+  }
+  await cmdAnalyze(projectRoot, workspaceInfo);
+  if (process.exitCode && process.exitCode !== 0) return;
+  await cmdInit({
+    existing: true,
+    yes: true,
+    project: flagString(flags, "project"),
+    "accept-proposal": proposalFlag === "--accept-proposal",
+    "merge-proposal": proposalFlag === "--merge-proposal",
+    "replace-essence": proposalFlag === "--replace-essence",
+    "assistant-bridge": assistantBridge,
+    telemetry: flagBoolean(flags, "telemetry")
+  });
+  if (process.exitCode && process.exitCode !== 0) return;
+  if (runVerify) {
+    const { cmdHealth } = await import("./health-ETZXWGTW.js");
+    await cmdHealth(projectRoot, {
+      browser: runBrowser,
+      browserBaseUrl: baseUrl,
+      evidence,
+      output: evidence ? ".decantr/evidence/latest.json" : void 0,
+      saveBaseline
+    });
+  }
+  if (initCi) {
+    const { cmdHealth } = await import("./health-ETZXWGTW.js");
+    const ciRoot = flagString(flags, "project") ? process.cwd() : projectRoot;
+    await cmdHealth(ciRoot, {
+      initCi: {
+        projectPath: flagString(flags, "project"),
+        failOn: "error"
+      }
+    });
+  }
+  console.log("");
+  console.log(`${BOLD7}Next useful commands:${RESET14}`);
+  console.log(`  ${cyan3('decantr task <route> "<change>"')}  Give your LLM route-specific context`);
+  console.log(`  ${cyan3("decantr codify")}                  Propose project-owned UI patterns`);
+  console.log(`  ${cyan3("decantr verify --since-baseline")} Compare future work against this baseline`);
+}
+async function cmdVerifyWorkflow(args) {
+  const { flags } = parseLooseArgs(args);
+  const workspaceMode = flagBoolean(flags, "workspace");
+  if (args[1] === "init-ci") {
+    const { cmdHealth: cmdHealth2, parseHealthArgs: parseHealthArgs2 } = await import("./health-ETZXWGTW.js");
+    await cmdHealth2(process.cwd(), parseHealthArgs2(["health", ...args.slice(1)]));
+    return;
+  }
+  if (workspaceMode) {
+    const { cmdWorkspace } = await import("./workspace-KSFWRZEX.js");
+    await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
+    return;
+  }
+  const workspaceInfo = resolveWorkflowProject(flags);
+  if (!workspaceInfo) return;
+  const brownfield = flagBoolean(flags, "brownfield");
+  const localPatterns = flagBoolean(flags, "local-patterns");
+  const evidence = flagBoolean(flags, "evidence");
+  const baseUrl = flagString(flags, "base-url");
+  const healthArgs = ["health", ...withoutWorkflowOnlyFlags(args)];
+  if (flagBoolean(flags, "baseline") && !healthArgs.includes("--save-baseline")) {
+    healthArgs.push("--save-baseline");
+  }
+  if (evidence && !flagString(flags, "output")) {
+    healthArgs.push("--output", ".decantr/evidence/latest.json");
+  }
+  if (baseUrl && !healthArgs.includes("--browser")) {
+    healthArgs.push("--browser");
+  }
+  const quietOutput = flagBoolean(flags, "json") || flagBoolean(flags, "ci") || Boolean(flagString(flags, "output"));
+  if (!quietOutput) {
+    console.log(heading2("Decantr Verify"));
+    console.log(
+      dim3(
+        brownfield ? "Running Brownfield guard validation before Project Health." : "Running Project Health as the canonical reliability gate."
+      )
+    );
+    console.log("");
+  }
+  let guardExitCode;
+  if (brownfield) {
+    const { cmdHeal, collectCheckIssues } = await import("./heal-ZYD6NVGE.js");
+    if (quietOutput) {
+      const result = collectCheckIssues(workspaceInfo.appRoot, { brownfield: true });
+      guardExitCode = result.issues.some((issue) => issue.type === "error") ? 1 : void 0;
+    } else {
+      await cmdHeal(workspaceInfo.appRoot, { brownfield: true });
+      guardExitCode = process.exitCode;
+      process.exitCode = void 0;
+    }
+  }
+  const { cmdHealth, parseHealthArgs } = await import("./health-ETZXWGTW.js");
+  await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
+  if (localPatterns) {
+    const localPatternsPath = join28(workspaceInfo.appRoot, ".decantr", "local-patterns.json");
+    if (!existsSync27(localPatternsPath)) {
+      console.log("");
+      console.log(
+        `${YELLOW9}Local pattern pack missing.${RESET14} Run ${cyan3("decantr codify --accept")} after reviewing the proposal.`
+      );
+      process.exitCode = process.exitCode || 1;
+    } else {
+      console.log("");
+      console.log(`${GREEN14}Local pattern pack found:${RESET14} ${localPatternsPath}`);
+    }
+  }
+  if (guardExitCode && guardExitCode !== 0 && (!process.exitCode || process.exitCode === 0)) {
+    process.exitCode = guardExitCode;
+  }
+}
+function readJsonIfPresent(path) {
+  if (!existsSync27(path)) return null;
+  try {
+    return JSON.parse(readFileSync20(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+async function cmdTaskWorkflow(args) {
+  const { flags, positional } = parseLooseArgs(args);
+  const workspaceInfo = resolveWorkflowProject(flags);
+  if (!workspaceInfo) return;
+  const routeInput = positional[0];
+  if (!routeInput) {
+    console.error(error3('Usage: decantr task <route> ["task summary"] [--project <path>] [--json]'));
+    process.exitCode = 1;
+    return;
+  }
+  const route = routeInput.startsWith("/") ? routeInput : `/${routeInput}`;
+  const taskSummary = positional.slice(1).join(" ").trim();
+  const essencePath = join28(workspaceInfo.appRoot, "decantr.essence.json");
+  const essence = readJsonIfPresent(essencePath);
+  if (!essence) {
+    console.error(error3("No decantr.essence.json found. Run `decantr adopt` or `decantr init` first."));
+    process.exitCode = 1;
+    return;
+  }
+  if (!isV47(essence)) {
+    console.error(error3("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(dim3(`Known routes: ${knownRoutes.join(", ") || "none"}`));
+    process.exitCode = 1;
+    return;
+  }
+  const section = essence.blueprint.sections.find((entry) => entry.id === target.section);
+  const page = section?.pages.find((entry) => entry.id === target.page);
+  const contextDir = join28(workspaceInfo.appRoot, ".decantr", "context");
+  const manifest = readJsonIfPresent(join28(contextDir, "pack-manifest.json"));
+  const pagePack = manifest?.pages?.find((entry) => entry.id === target.page);
+  const sectionPack = manifest?.sections?.find((entry) => entry.id === target.section);
+  const visualManifest = readJsonIfPresent(join28(workspaceInfo.appRoot, ".decantr", "evidence", "visual-manifest.json"));
+  const screenshot = visualManifest?.routes?.find((entry) => entry.route === route)?.screenshot;
+  const localPatternsPath = join28(workspaceInfo.appRoot, ".decantr", "local-patterns.json");
+  const context = {
+    route,
+    task: taskSummary || null,
+    section: target.section,
+    page: target.page,
+    shell: page?.shell ?? section?.shell ?? null,
+    patterns: page?.layout?.map(extractPatternName) ?? [],
+    read: [
+      pagePack ? join28(".decantr/context", pagePack.markdown) : null,
+      sectionPack ? join28(".decantr/context", sectionPack.markdown) : null,
+      manifest?.scaffold?.markdown ? join28(".decantr/context", manifest.scaffold.markdown) : null,
+      ".decantr/context/scaffold.md",
+      "DECANTR.md",
+      existsSync27(localPatternsPath) ? ".decantr/local-patterns.json" : null
+    ].filter(Boolean),
+    screenshot: screenshot ?? null
+  };
+  if (flagBoolean(flags, "json")) {
+    console.log(JSON.stringify(context, null, 2));
+    return;
+  }
+  console.log(heading2("Decantr Task Context"));
+  console.log(`  Route: ${cyan3(context.route)}`);
+  console.log(`  Section/page: ${context.section}/${context.page}`);
+  if (context.shell) console.log(`  Shell: ${context.shell}`);
+  if (context.patterns.length > 0) console.log(`  Patterns: ${context.patterns.join(", ")}`);
+  if (taskSummary) console.log(`  Task: ${taskSummary}`);
+  console.log("");
+  console.log(`${BOLD7}Read before editing:${RESET14}`);
+  for (const path of context.read) {
+    console.log(`  ${cyan3(path)}`);
+  }
+  if (context.screenshot) {
+    console.log("");
+    console.log(`${BOLD7}Visual evidence:${RESET14}`);
+    console.log(`  ${cyan3(context.screenshot)}`);
+  }
+  console.log("");
+  console.log(`${BOLD7}LLM instruction:${RESET14}`);
+  console.log(
+    "  Preserve the existing runtime and styling system. Use the route pack, section context, local patterns, and visual evidence above as the task contract before changing code."
+  );
+}
+async function cmdCodifyWorkflow(args) {
+  const { flags } = parseLooseArgs(args);
+  const workspaceInfo = resolveWorkflowProject(flags);
+  if (!workspaceInfo) return;
+  const decantrDir = join28(workspaceInfo.appRoot, ".decantr");
+  const proposalPathLocal = join28(decantrDir, "local-patterns.proposal.json");
+  const acceptedPath = join28(decantrDir, "local-patterns.json");
+  if (flagBoolean(flags, "accept")) {
+    if (!existsSync27(proposalPathLocal)) {
+      console.error(error3("No .decantr/local-patterns.proposal.json found. Run `decantr codify` first."));
+      process.exitCode = 1;
+      return;
+    }
+    writeFileSync16(acceptedPath, readFileSync20(proposalPathLocal, "utf-8"), "utf-8");
+    console.log(success3(`Accepted local pattern pack: ${acceptedPath}`));
+    console.log(dim3("Run `decantr verify --local-patterns` to require the pack during verification."));
+    return;
+  }
+  mkdirSync13(decantrDir, { recursive: true });
+  const detected = detectProject(workspaceInfo.appRoot);
+  const essence = readJsonIfPresent(join28(workspaceInfo.appRoot, "decantr.essence.json"));
+  const routes = essence && isV47(essence) ? Object.keys(essence.blueprint.routes ?? {}).sort() : [];
+  const proposal = {
+    version: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    status: "proposal",
+    source: "decantr codify",
+    project: {
+      framework: detected.framework,
+      packageManager: detected.packageManager,
+      hasTailwind: detected.hasTailwind,
+      ruleFiles: detected.existingRuleFiles,
+      routeCount: routes.length
+    },
+    purpose: "Project-owned Brownfield UI law. Review and edit before accepting; Decantr does not treat this as authoritative until copied to .decantr/local-patterns.json.",
+    patterns: [
+      {
+        id: "button",
+        role: "Actions and command triggers",
+        decide: "Define primary, secondary, tertiary, destructive, icon-only, and loading button variants from this app.",
+        evidenceToCollect: ["component wrapper path", "allowed classes/tokens", "forbidden raw <button> usage"]
+      },
+      {
+        id: "surface-card",
+        role: "Cards, panels, and content surfaces",
+        decide: "Define the canonical card background, border, radius, shadow, padding, and hover treatment.",
+        evidenceToCollect: ["shared card component", "token/class recipe", "allowed density variants"]
+      },
+      {
+        id: "page-shell",
+        role: "Route shell, nav, spacing, and scroll ownership",
+        decide: "Define which layout owns max width, gutters, sticky chrome, and scroll containers.",
+        evidenceToCollect: ["root layout path", "page template path", "responsive breakpoints"]
+      },
+      {
+        id: "form-control",
+        role: "Inputs, labels, validation, and form actions",
+        decide: "Define input height, label placement, error copy, disabled state, and focus treatment.",
+        evidenceToCollect: ["form field wrapper", "validation pattern", "accessibility expectations"]
+      }
+    ],
+    starterRules: [
+      "Prefer project-owned wrappers for repeated primitives once they exist.",
+      "Avoid raw hex/rgb values in component templates unless explicitly documented as dynamic data.",
+      "Avoid static inline styles for reusable visual treatment.",
+      "When adding a new route, map it to an existing local pattern before inventing a new visual variant."
+    ],
+    nextSteps: [
+      "Edit this proposal with real component paths and token/class recipes.",
+      "Run decantr codify --accept after review.",
+      "Use decantr task <route> before LLM edits so local patterns appear in the task context.",
+      "Wire mechanical enforcement through ESLint/Biome/project tests for rules Decantr cannot reliably infer."
+    ]
+  };
+  writeFileSync16(proposalPathLocal, JSON.stringify(proposal, null, 2) + "\n", "utf-8");
+  console.log(success3(`Wrote local pattern proposal: ${proposalPathLocal}`));
+  console.log(dim3("Review it, add real component paths/token recipes, then run `decantr codify --accept`."));
+}
+async function cmdContentWorkflow(args) {
+  const subcommand = args[1] ?? "check";
+  if (subcommand === "check" || subcommand === "health") {
+    const { cmdContentHealth, parseContentHealthArgs } = await import("./content-health-QQHBR6XG.js");
+    await cmdContentHealth(process.cwd(), parseContentHealthArgs(["content-health", ...args.slice(2)]));
+    return;
+  }
+  if (subcommand === "create") {
+    const type = args[2];
+    const name = args[3];
+    if (!type || !name) {
+      console.error(error3("Usage: decantr content create <type> <name>"));
+      process.exitCode = 1;
+      return;
+    }
+    cmdCreate(type, name);
+    return;
+  }
+  if (subcommand === "publish") {
+    const type = args[2];
+    const name = args[3];
+    if (!type || !name) {
+      console.error(error3("Usage: decantr content publish <type> <name>"));
+      process.exitCode = 1;
+      return;
+    }
+    await cmdPublish(type, name);
+    return;
+  }
+  console.error(error3("Usage: decantr content <check|create|publish>"));
+  process.exitCode = 1;
+}
 function cmdHelp() {
   console.log(`
 ${BOLD7}decantr${RESET14} \u2014 Design intelligence for AI-generated UI
 
 ${BOLD7}Usage:${RESET14}
+  decantr setup [--project <path>]
   decantr new <name> [--blueprint=X] [--archetype=X] [--theme=X] [--workflow=greenfield] [--adoption=decantr-css] [--telemetry]
-  decantr magic <prompt> [--dry-run]
+  decantr adopt [--project <path>] [--base-url <url>] [--evidence] [--ci] [--yes]
+  decantr task <route> ["task summary"] [--project <path>] [--json]
+  decantr verify [--project <path>] [--brownfield] [--local-patterns] [health options]
+  decantr codify [--accept] [--project <path>]
+  decantr studio [--port 4319] [--host 127.0.0.1] [--report decantr-health.json] [--workspace]
+
+${BOLD7}Advanced primitives:${RESET14}
   decantr init [options]
+  decantr analyze
+  decantr magic <prompt> [--dry-run]
   decantr status
   decantr sync
   decantr audit [file]
@@ -8324,8 +8793,8 @@ ${BOLD7}Usage:${RESET14}
   decantr health init-ci [--force] [--project <path>] [--workspace] [--fail-on <error|warn|none>] [--cli-version <version|latest>]
   decantr workspace list [--json]
   decantr workspace health [--json] [--changed --since origin/main]
+  decantr content check [--json] [--markdown] [--ci]
   decantr content-health [--json] [--markdown] [--ci]
-  decantr studio [--port 4319] [--host 127.0.0.1] [--report decantr-health.json] [--workspace]
   decantr telemetry status [--json]
   decantr telemetry explain [--json]
   decantr telemetry link [--enable] [--org <slug>]
@@ -8335,7 +8804,6 @@ ${BOLD7}Usage:${RESET14}
   decantr theme <subcommand>
   decantr create <type> <name>
   decantr publish <type> <name>
-  decantr analyze
   decantr login
   decantr logout
   decantr help
@@ -8363,14 +8831,22 @@ ${BOLD7}Init Options:${RESET14}
   --telemetry        Opt this project into privacy-filtered CLI product telemetry
 
 ${BOLD7}Commands:${RESET14}
+  ${cyan3("setup")}       Detect project state and recommend the right Decantr workflow
   ${cyan3("new")}         Create a new greenfield workspace and bootstrap the available starter adapter
+  ${cyan3("adopt")}       Brownfield one-liner: analyze, attach, verify, and show next steps
+  ${cyan3("task")}        Prepare route/task context for an AI coding assistant
+  ${cyan3("verify")}      One reliability gate over Project Health, Brownfield checks, baselines, and evidence
+  ${cyan3("codify")}      Propose or accept project-owned Brownfield UI patterns
+  ${cyan3("studio")}      Open a local Project Health dashboard backed by the same report
+  ${cyan3("content")}     Content-author namespace: check, create, publish
+
+${BOLD7}Advanced commands:${RESET14}
   ${cyan3("magic")}       Greenfield-first intent flow; steers existing apps into analyze + init
   ${cyan3("init")}        Attach Decantr contract/context files to an existing project or empty workspace
   ${cyan3("status")}      Show project status, DNA axioms, and blueprint info
   ${cyan3("health")}      Generate a local Project Health report [--json] [--markdown] [--ci]; use health init-ci to install a GitHub Actions gate
   ${cyan3("workspace")}   Discover and aggregate health across Decantr projects in a monorepo
   ${cyan3("content-health")} Generate a local registry content health report [--json] [--markdown] [--ci]
-  ${cyan3("studio")}      Open a local Project Health dashboard backed by the same report
   ${cyan3("sync")}        Sync registry content from API
   ${cyan3("audit")}       Audit the project or critique a specific file against compiled packs
   ${cyan3("migrate")}     Migrate older essence files to v4 format (with .pre-v4.backup.json backup)
@@ -8396,7 +8872,15 @@ ${BOLD7}Commands:${RESET14}
   ${cyan3("help")}        Show this help
 
 ${BOLD7}Examples:${RESET14}
+  decantr setup
   decantr new my-app --blueprint=carbon-ai-portal
+  decantr adopt --base-url http://localhost:3000 --evidence --yes
+  decantr task /feed "add saved recipe actions"
+  decantr verify --brownfield --local-patterns
+  decantr verify --since-baseline
+  decantr codify
+  decantr codify --accept
+  decantr content check --ci --fail-on error
   decantr magic "AI chatbot with dark cyber theme \u2014 bold and futuristic"
   decantr init
   decantr analyze
@@ -8409,13 +8893,13 @@ ${BOLD7}Examples:${RESET14}
   decantr rules apply
   decantr status
   decantr health
-  decantr health init-ci
-  decantr health init-ci --project apps/web
-  decantr health --ci --fail-on error
+  decantr verify init-ci
+  decantr verify init-ci --project apps/web
+  decantr verify --ci --fail-on error
   decantr health --evidence --output .decantr/evidence/latest.json
   decantr workspace list
-  decantr workspace health --changed --since origin/main
-  decantr content-health --ci --fail-on error
+  decantr verify --workspace --changed --since origin/main
+  decantr content check --ci --fail-on error
   decantr studio
   decantr studio --report decantr-health.json
   decantr telemetry status
@@ -8444,7 +8928,9 @@ ${BOLD7}Examples:${RESET14}
 ${BOLD7}Workflow Model:${RESET14}
   ${cyan3("Greenfield blueprint")}   decantr new my-app --blueprint=X --workflow=greenfield --adoption=decantr-css
   ${cyan3("Greenfield contract")}    decantr init --workflow=greenfield --adoption=contract-only
-  ${cyan3("Brownfield adoption")}    decantr analyze -> decantr init --existing --accept-proposal -> decantr health --browser --evidence
+  ${cyan3("Brownfield adoption")}    decantr adopt --base-url <url> --evidence --yes
+  ${cyan3("Daily LLM work")}          decantr task <route> "<change>" -> decantr verify
+  ${cyan3("Project-owned law")}       decantr codify -> edit proposal -> decantr codify --accept
   ${cyan3("Hybrid composition")}     decantr add/remove, decantr theme switch, decantr registry, decantr upgrade
 
 ${BOLD7}Bootstrap adapters:${RESET14}
@@ -8611,9 +9097,127 @@ ${BOLD7}Usage:${RESET14}
   decantr theme import <path>
 `);
 }
+function cmdSetupHelp() {
+  console.log(`
+${BOLD7}decantr setup${RESET14} \u2014 Detect the project state and recommend the right Decantr path
+
+${BOLD7}Usage:${RESET14}
+  decantr setup [--project <path>]
+
+${BOLD7}Examples:${RESET14}
+  decantr setup
+  decantr setup --project apps/web
+`);
+}
+function cmdAdoptHelp() {
+  console.log(`
+${BOLD7}decantr adopt${RESET14} \u2014 Brownfield one-liner: analyze, attach, verify, and show the next step
+
+${BOLD7}Usage:${RESET14}
+  decantr adopt [--project <path>] [--yes] [--dry-run]
+  decantr adopt --base-url <url> [--evidence] [--ci] [--yes]
+
+${BOLD7}Options:${RESET14}
+  --project           App path inside a workspace/monorepo
+  --yes, -y           Run without confirmation
+  --dry-run           Show the workflow without writing files
+  --base-url          Include browser evidence against this dev server URL
+  --evidence          Write .decantr/evidence/latest.json
+  --baseline          Save a health baseline (default)
+  --no-baseline       Skip baseline save
+  --no-verify         Skip the verification step
+  --ci, --init-ci     Install the Project Health CI gate after adoption
+  --telemetry         Opt this project into privacy-filtered CLI product telemetry
+  --merge-proposal    Merge the observed proposal into an existing essence
+  --replace-essence   Replace an existing essence with backup
+
+${BOLD7}Examples:${RESET14}
+  decantr adopt --yes
+  decantr adopt --base-url http://localhost:3000 --evidence --yes
+  decantr adopt --project apps/web --ci --yes
+`);
+}
+function cmdVerifyHelp() {
+  console.log(`
+${BOLD7}decantr verify${RESET14} \u2014 One reliability command for local work, CI, and LLM agent loops
+
+${BOLD7}Usage:${RESET14}
+  decantr verify [--project <path>] [--brownfield] [--local-patterns]
+  decantr verify --base-url <url> --evidence
+  decantr verify --since-baseline
+  decantr verify --workspace [--changed --since origin/main]
+  decantr verify init-ci [health init-ci options]
+
+${BOLD7}Examples:${RESET14}
+  decantr verify
+  decantr verify --brownfield --local-patterns
+  decantr verify --base-url http://localhost:3000 --evidence
+  decantr verify --workspace --changed --since origin/main
+  decantr verify init-ci --project apps/web
+`);
+}
+function cmdTaskHelp() {
+  console.log(`
+${BOLD7}decantr task${RESET14} \u2014 Prepare compact route/task context for an AI coding assistant
+
+${BOLD7}Usage:${RESET14}
+  decantr task <route> ["task summary"] [--project <path>] [--json]
+
+${BOLD7}Examples:${RESET14}
+  decantr task /feed "add saved recipe actions"
+  decantr task /profile --json
+`);
+}
+function cmdCodifyHelp() {
+  console.log(`
+${BOLD7}decantr codify${RESET14} \u2014 Propose or accept project-owned Brownfield UI patterns
+
+${BOLD7}Usage:${RESET14}
+  decantr codify [--project <path>]
+  decantr codify --accept [--project <path>]
+
+${BOLD7}Examples:${RESET14}
+  decantr codify
+  decantr codify --accept
+  decantr verify --local-patterns
+`);
+}
+function cmdContentHelp() {
+  console.log(`
+${BOLD7}decantr content${RESET14} \u2014 Content-author namespace for registry content repositories
+
+${BOLD7}Usage:${RESET14}
+  decantr content check [content-health options]
+  decantr content create <type> <name>
+  decantr content publish <type> <name>
+
+${BOLD7}Examples:${RESET14}
+  decantr content check --ci --fail-on error
+  decantr content create pattern my-card
+  decantr content publish pattern my-card
+`);
+}
 function printCommandHelp(command, args) {
   if (!isCommandHelpRequest(args)) return false;
   switch (command) {
+    case "setup":
+      cmdSetupHelp();
+      return true;
+    case "adopt":
+      cmdAdoptHelp();
+      return true;
+    case "verify":
+      cmdVerifyHelp();
+      return true;
+    case "task":
+      cmdTaskHelp();
+      return true;
+    case "codify":
+      cmdCodifyHelp();
+      return true;
+    case "content":
+      cmdContentHelp();
+      return true;
     case "health":
       cmdHealthHelp();
       return true;
@@ -8672,6 +9276,30 @@ async function main() {
     return;
   }
   switch (command) {
+    case "setup": {
+      await cmdSetupWorkflow(args);
+      break;
+    }
+    case "adopt": {
+      await cmdAdoptWorkflow(args);
+      break;
+    }
+    case "task": {
+      await cmdTaskWorkflow(args);
+      break;
+    }
+    case "verify": {
+      await cmdVerifyWorkflow(args);
+      break;
+    }
+    case "codify": {
+      await cmdCodifyWorkflow(args);
+      break;
+    }
+    case "content": {
+      await cmdContentWorkflow(args);
+      break;
+    }
     case "new": {
       const newName = args[1];
       if (!newName) {

package/dist/index.js

@@ -1,3 +1,3 @@
-import "./chunk-Q5OFRQY6.js";
+import "./chunk-ZYHR3BGT.js";
 import "./chunk-V3XAQWKD.js";
 import "./chunk-KT2ROK2D.js";

package/package.json

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