@decantr/cli 3.4.0 → 3.4.2

package/README.md

@@ -22,7 +22,7 @@ Use `decantr setup` when you are unsure which path applies. It detects whether t
 Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files, detects framework/routes/styling/static-hosting/assistant-rule signals, previews typed Contract graph readiness in memory when a Decantr contract already exists, reports the contract capsule source-handle count and limit, prints a terminal report, and writes no `.decantr` files or report artifacts. Add `--json` when automation needs the `ScanReportV1` payload.
 Use `decantr new` for a greenfield workspace in a fresh directory. With a starter-kit blueprint or archetype it uses the runnable adapter and Decantr CSS; without certified vocabulary content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
-Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
+Use `decantr studio` after adoption when you want a local visual view of routes, findings, and attention areas. Use `decantr doctor` when the next step is unclear, `decantr task <route> "<intent>"` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. If runtime source and Decantr context disagree, report the drift instead of guessing; in Brownfield the existing source is observed truth, accepted local law/style bridge is project authority where present, Essence V4 is the structural contract, and hosted packs stay advisory until mapped into local law. Use `decantr graph` when you want the Decantr 3 typed Contract graph, typed graph diff summary, manifest, content-addressed snapshot history, and cache-friendly contract capsule written under `.decantr/graph`; the capsule includes a bounded SourceArtifact path index so agents can discover valid file-impact handles without reading the full snapshot, and `--capsule-source-limit <count>` can tune that index for large repos. Add `--route /feed --task "improve loading" --json` when you want the exact task-ranked route-scoped subgraph an agent should inspect before editing, `--node cmp:button --impact --json` when you need the graph-shaped blast radius for a component, token, rule, finding, or source artifact, or `--file src/app/page.tsx --impact --json` when the agent knows the source file it is about to change. Use `--snapshot-id <id>` to inspect a replayable history snapshot and `--compare-to <id> --include-diff-ops --json` to compare the selected/current graph against a prior snapshot. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, optional `behavior_obligations`, local rules, and token/class bridge mappings such as button/card/shell/theme standards to appear in future task context and verification. Once accepted, that local law is the first Hybrid lane: the app still owns source and styling, but Decantr treats accepted local patterns, behavior obligations, rules, and style bridge mappings as project authority.
 In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Hosted pack hydration also follows the essence path: `decantr registry compile-packs apps/web/decantr.essence.json --write-context` writes into `apps/web/.decantr/context`. In contract-only/offline Brownfield, deferred hosted packs are optional context unless a present manifest references missing files.
 Use `decantr init`, `decantr analyze`, `decantr check`, and `decantr health` as advanced primitives when you need direct control over one step.
 
@@ -46,6 +46,7 @@ decantr setup
 decantr scan
 decantr scan --project apps/web --json
 decantr adopt --yes
+decantr studio
 decantr doctor
 decantr ci --fail-on error
 decantr ci init

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-ZBGL7RID.js";
+import "./chunk-32WTNJQU.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-EL4KSW7E.js";
-import "./chunk-XUHPMETF.js";
-import "./chunk-XINHWP4T.js";
+import "./chunk-BDA6TWV3.js";
+import "./chunk-PQKTJGYL.js";
+import "./chunk-2GCVVEQC.js";

package/dist/{chunk-XINHWP4T.js → chunk-2GCVVEQC.js}

@@ -1187,7 +1187,7 @@ function routeLooksPublicFullBleed(path, file, code) {
   );
 }
 function routeLooksAppShell(file, code) {
-  return /\b(?:sidebar|side-nav|sidenav|app-frame|dashboard-shell|app-shell)\b|<\s*(?:Sidebar|AppShell|DashboardShell)\b/i.test(
+  return /\b(?:sidebar|side-nav|sidenav|app-frame|dashboard-shell|protected-shell)\b|<\s*(?:Sidebar|DashboardShell)\b/i.test(
     `${file} ${code}`
   );
 }

package/dist/{chunk-ZBGL7RID.js → chunk-32WTNJQU.js}

@@ -22,7 +22,7 @@ import {
   listWorkspaceCandidates,
   listWorkspaceProjects,
   shouldFailWorkspaceHealth
-} from "./chunk-EL4KSW7E.js";
+} from "./chunk-BDA6TWV3.js";
 import {
   acceptBrownfieldLocalLaw,
   acceptStyleBridge,
@@ -52,7 +52,7 @@ import {
   writeBrownfieldCodifyProposal,
   writeHostedPatternMappingProposal,
   writeStyleBridgeProposal
-} from "./chunk-XUHPMETF.js";
+} from "./chunk-PQKTJGYL.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -69,7 +69,7 @@ import {
   sendCliCommandTelemetry,
   sendNewProjectCompletedTelemetry,
   writeDoctrineMap
-} from "./chunk-XINHWP4T.js";
+} from "./chunk-2GCVVEQC.js";
 
 // src/index.ts
 import { existsSync as existsSync28, mkdirSync as mkdirSync15, readdirSync as readdirSync8, readFileSync as readFileSync21, writeFileSync as writeFileSync18 } from "fs";
@@ -188,11 +188,14 @@ function buildAssistantBridgeContent(input) {
   lines.push("## Suggested Rule Block");
   lines.push("");
   lines.push(START);
+  lines.push(
+    'Before editing any route, run `decantr task <route> "<intent>"` and use the printed authority block, read targets, local law, evidence, and verify command as the working contract.'
+  );
   lines.push(
     "Before implementing Decantr-scoped work, read `decantr.essence.json`, `.decantr/brownfield-report.md`, `.decantr/doctrine-map.json`, `.decantr/ambient-context.json`, and the compiled packs in `.decantr/context/`."
   );
   lines.push(
-    "Treat Decantr as the reconciled contract layer and the original project docs/rules as cited evidence; if they conflict, stop and report the conflict instead of guessing."
+    "Treat Decantr as the reconciled contract layer and the original project docs/rules as cited evidence; if runtime source and Decantr context conflict, stop and report the drift instead of guessing which side wins."
   );
   lines.push(
     "For brownfield adoption, preserve existing framework, routing, styling, package manager, data boundaries, and build conventions unless the Decantr contract explicitly records a reviewed change."
@@ -215,8 +218,9 @@ function writeAssistantBridgePreview(input) {
 function bridgeBlock() {
   return [
     START,
+    'Before editing any route, run `decantr task <route> "<intent>"` and use the printed authority block, read targets, local law, evidence, and verify command as the working contract.',
     "Before implementing Decantr-scoped work, read `decantr.essence.json`, `.decantr/brownfield-report.md`, `.decantr/doctrine-map.json`, `.decantr/ambient-context.json`, and `.decantr/context/scaffold-pack.md` first.",
-    "Treat Decantr as the reconciled contract layer and the original project docs/rules as cited evidence; if they conflict, stop and report the conflict instead of guessing.",
+    "Treat Decantr as the reconciled contract layer and the original project docs/rules as cited evidence; if runtime source and Decantr context conflict, stop and report the drift instead of guessing which side wins.",
     "For brownfield adoption, preserve existing framework, routing, styling, package manager, data boundaries, and build conventions unless the Decantr contract explicitly records a reviewed change.",
     "Do not install `@decantr/css` or rewrite styling unless the project adoption mode says `decantr-css` or the task explicitly asks for it.",
     END,
@@ -3585,7 +3589,7 @@ function formatLocalLawText(summary, health) {
     lines.push(`  ${DIM3}[WARN] ${warning}${RESET3}`);
   }
   for (const finding of summary.findings.slice(0, 8)) {
-    const label = finding.severity.toUpperCase();
+    const label = finding.severity === "error" ? "Local law error" : finding.severity === "warn" ? "Local law warning" : "Local law info";
     lines.push(
       `  [${label}] ${finding.ruleId} ${finding.file}:${finding.line}:${finding.column} ${finding.message}`
     );
@@ -10448,6 +10452,18 @@ function printWorkflowPlan(title, steps) {
   }
   console.log("");
 }
+function studioCommandForProject(projectArg) {
+  return projectArg ? `cd ${projectArg} && decantr studio` : "decantr studio";
+}
+function formatWhichCommandFirst(projectArg) {
+  return [
+    `${BOLD9}Which command first?${RESET16}`,
+    `  ${cyan3(withProject("decantr scan", projectArg))}          Existing app, read-only preview`,
+    `  ${cyan3(withProject("decantr adopt --yes", projectArg))}   Existing app, attach Decantr`,
+    `  ${cyan3("decantr new my-app --blueprint=<slug>")}  New runnable app`,
+    `  ${cyan3(withProject("decantr init --existing", projectArg))}  Advanced attach primitive`
+  ].join("\n");
+}
 function scanSeverityColor(finding) {
   if (finding.severity === "success") return success3("ok");
   if (finding.severity === "error") return error2("error");
@@ -10583,7 +10599,7 @@ function printScanGraphPreview(preview) {
   }
   console.log("");
 }
-function printScanReport(report) {
+function printScanReport(report, projectArg) {
   console.log(heading2("Decantr Scan"));
   console.log(dim3("Read-only Brownfield reconnaissance. No files were written."));
   console.log("");
@@ -10655,6 +10671,19 @@ function printScanReport(report) {
   }
   console.log("");
   console.log(dim3(report.privacy.notes[0] ?? "Scan completed without writing files."));
+  console.log(
+    dim3(
+      "This scan was read-only: no Decantr files, dependencies, scripts, uploads, or reports were created."
+    )
+  );
+  if (report.applicability.status !== "not_applicable") {
+    console.log(
+      `When ready to attach Decantr, run ${cyan3(withProject("decantr adopt --yes", projectArg))}.`
+    );
+    console.log(
+      `After adoption, inspect what Decantr found with ${cyan3(studioCommandForProject(projectArg))}.`
+    );
+  }
 }
 async function cmdScanWorkflow(args) {
   const { flags } = parseLooseArgs(args);
@@ -10673,7 +10702,7 @@ async function cmdScanWorkflow(args) {
     console.log(JSON.stringify(reportWithGraph, null, 2));
     return;
   }
-  printScanReport(reportWithGraph);
+  printScanReport(reportWithGraph, projectArg);
 }
 async function cmdSetupWorkflow(args) {
   const { flags } = parseLooseArgs(args);
@@ -10859,7 +10888,7 @@ async function cmdAdoptWorkflow(args) {
   await cmdGraph(projectRoot, { displayRoot: process.cwd() });
   if (process.exitCode && process.exitCode !== 0) return;
   if (runVerify) {
-    const { cmdHealth } = await import("./health-H2256NIM.js");
+    const { cmdHealth } = await import("./health-U7O6PCLZ.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -10888,6 +10917,9 @@ async function cmdAdoptWorkflow(args) {
   console.log(
     `  ${cyan3(withProject("decantr verify --brownfield --local-patterns", projectArg))}  Check contract, health, and local law after edits`
   );
+  console.log(
+    `  ${cyan3(studioCommandForProject(projectArg))}                      Inspect routes, findings, and attention areas visually`
+  );
   console.log(
     `  ${cyan3(withProject("decantr verify --since-baseline", projectArg))}      Compare future work against this baseline`
   );
@@ -10930,7 +10962,7 @@ async function cmdVerifyWorkflow(args) {
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-SR6ZGG2E.js");
+    const { cmdWorkspace } = await import("./workspace-NE232D4K.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -10963,7 +10995,7 @@ async function cmdVerifyWorkflow(args) {
   }
   let guardExitCode;
   if (brownfield) {
-    const { cmdHeal, collectCheckIssues } = await import("./heal-ZY4BX5HU.js");
+    const { cmdHeal, collectCheckIssues } = await import("./heal-OKZ5QZN7.js");
     if (quietOutput) {
       const result = collectCheckIssues(workspaceInfo.appRoot, { brownfield: true });
       guardExitCode = result.issues.some((issue) => issue.type === "error") ? 1 : void 0;
@@ -10973,7 +11005,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-H2256NIM.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-U7O6PCLZ.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -11708,6 +11740,8 @@ ${BOLD9}Usage:${RESET16}
   decantr codify [--from-audit] [--style-bridge] [--map-pattern <slug>] [--accept] [--project <path>]
   decantr studio [--port 4319] [--host 127.0.0.1] [--report decantr-health.json] [--workspace]
 
+${formatWhichCommandFirst()}
+
 ${BOLD9}Advanced primitives:${RESET16}
   decantr init [options]
   decantr analyze
@@ -11935,6 +11969,8 @@ ${BOLD9}Behavior:${RESET16}
   and prints a terminal report. It does not write .decantr files, install dependencies,
   build the app, execute scripts, upload source, or open pull requests.
 
+${formatWhichCommandFirst()}
+
 ${BOLD9}Examples:${RESET16}
   decantr scan
   decantr scan --project apps/web
@@ -12093,6 +12129,8 @@ ${BOLD9}decantr setup${RESET16} \u2014 Detect the project state and recommend th
 ${BOLD9}Usage:${RESET16}
   decantr setup [--project <path>]
 
+${formatWhichCommandFirst()}
+
 ${BOLD9}Examples:${RESET16}
   decantr setup
   decantr setup --project apps/web
@@ -12476,7 +12514,7 @@ async function main() {
           `${YELLOW12}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET16}`
         );
       }
-      const { cmdHeal } = await import("./heal-ZY4BX5HU.js");
+      const { cmdHeal } = await import("./heal-OKZ5QZN7.js");
       const { flags } = parseLooseArgs(args);
       const workspaceInfo = resolveWorkflowProject(flags, "check");
       if (!workspaceInfo) break;
@@ -12501,7 +12539,7 @@ async function main() {
         const { flags } = parseLooseArgs(args);
         const workspaceInfo = resolveWorkflowProject(flags, "health");
         if (!workspaceInfo) break;
-        const { cmdHealth, parseHealthArgs } = await import("./health-H2256NIM.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-U7O6PCLZ.js");
         await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(stripProjectArgs(args)));
       } catch (e) {
         console.error(error2(e.message));
@@ -12529,7 +12567,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-UKSCSRX7.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-X565XJKV.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error2(e.message));
@@ -12543,7 +12581,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-SR6ZGG2E.js");
+        const { cmdWorkspace } = await import("./workspace-NE232D4K.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error2(e.message));

package/dist/{chunk-EL4KSW7E.js → chunk-BDA6TWV3.js}

@@ -1,7 +1,7 @@
 import {
   createProjectHealthReport,
   listWorkspaceAppCandidates
-} from "./chunk-XUHPMETF.js";
+} from "./chunk-PQKTJGYL.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";

package/dist/{chunk-XUHPMETF.js → chunk-PQKTJGYL.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-XINHWP4T.js";
+} from "./chunk-2GCVVEQC.js";
 
 // src/commands/health.ts
 import { execFileSync as execFileSync2 } from "child_process";
@@ -4907,6 +4907,36 @@ function colorForStatus(status) {
   if (status === "warning") return YELLOW;
   return RED2;
 }
+var DNA_RULES = /* @__PURE__ */ new Set(["style", "density", "accessibility", "theme-mode", "theme"]);
+var BLUEPRINT_RULES = /* @__PURE__ */ new Set([
+  "structure",
+  "layout",
+  "pattern-exists",
+  "page-route-required",
+  "page-pack-count-mismatch"
+]);
+function formatHumanFindingLabel(finding) {
+  const severity = finding.severity;
+  const rule = finding.rule?.toLowerCase() ?? "";
+  const category = finding.category.toLowerCase();
+  const source = finding.source;
+  if (source === "brownfield" || rule.startsWith("brownfield-")) {
+    return "Brownfield drift";
+  }
+  if (source === "style-bridge") {
+    return `Style bridge ${severity}`;
+  }
+  if (source === "interaction") {
+    return `Interaction ${severity}`;
+  }
+  if (DNA_RULES.has(rule) || category.includes("dna")) {
+    return `DNA ${severity}`;
+  }
+  if (BLUEPRINT_RULES.has(rule) || category.includes("blueprint")) {
+    return `Blueprint ${severity === "error" ? "error" : "warning"}`;
+  }
+  return severity.toUpperCase();
+}
 function formatProjectHealthText(report) {
   const color = colorForStatus(report.status);
   const commandContext = commandContextForProject(report.projectRoot);
@@ -4932,7 +4962,7 @@ function formatProjectHealthText(report) {
     for (const finding of report.findings) {
       const findingColor = finding.severity === "error" ? RED2 : finding.severity === "warn" ? YELLOW : CYAN;
       lines.push(
-        `  ${findingColor}[${finding.severity.toUpperCase()}]${RESET2} ${finding.id}: ${finding.message}`
+        `  ${findingColor}[${formatHumanFindingLabel(finding)}]${RESET2} ${finding.id}: ${finding.message}`
       );
       if (finding.evidence.length > 0) {
         lines.push(`    ${DIM2}${finding.evidence[0]}${RESET2}`);

package/dist/{heal-ZY4BX5HU.js → heal-OKZ5QZN7.js}

@@ -1,7 +1,7 @@
 import {
   cmdHeal,
   collectCheckIssues
-} from "./chunk-XINHWP4T.js";
+} from "./chunk-2GCVVEQC.js";
 export {
   cmdHeal,
   collectCheckIssues

package/dist/{health-H2256NIM.js → health-U7O6PCLZ.js}

@@ -13,8 +13,8 @@ import {
   renderProjectHealthCiWorkflow,
   shouldFailHealth,
   writeProjectHealthCiWorkflow
-} from "./chunk-XUHPMETF.js";
-import "./chunk-XINHWP4T.js";
+} from "./chunk-PQKTJGYL.js";
+import "./chunk-2GCVVEQC.js";
 export {
   cmdHealth,
   collectDesignTokenEvidence,

package/dist/index.js

@@ -1,5 +1,5 @@
-import "./chunk-ZBGL7RID.js";
+import "./chunk-32WTNJQU.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-EL4KSW7E.js";
-import "./chunk-XUHPMETF.js";
-import "./chunk-XINHWP4T.js";
+import "./chunk-BDA6TWV3.js";
+import "./chunk-PQKTJGYL.js";
+import "./chunk-2GCVVEQC.js";

package/dist/{studio-UKSCSRX7.js → studio-X565XJKV.js}

@@ -1,13 +1,13 @@
 import {
   createWorkspaceHealthReport
-} from "./chunk-EL4KSW7E.js";
+} from "./chunk-BDA6TWV3.js";
 import {
   createProjectHealthReport
-} from "./chunk-XUHPMETF.js";
+} from "./chunk-PQKTJGYL.js";
 import {
   sendStudioHealthRefreshedTelemetry,
   sendStudioStartedTelemetry
-} from "./chunk-XINHWP4T.js";
+} from "./chunk-2GCVVEQC.js";
 
 // src/commands/studio.ts
 import { readFileSync } from "fs";

package/dist/{workspace-SR6ZGG2E.js → workspace-NE232D4K.js}

@@ -7,9 +7,9 @@ import {
   listWorkspaceProjects,
   parseWorkspaceArgs,
   shouldFailWorkspaceHealth
-} from "./chunk-EL4KSW7E.js";
-import "./chunk-XUHPMETF.js";
-import "./chunk-XINHWP4T.js";
+} from "./chunk-BDA6TWV3.js";
+import "./chunk-PQKTJGYL.js";
+import "./chunk-2GCVVEQC.js";
 export {
   cmdWorkspace,
   createWorkspaceHealthReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decantr/cli",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Decantr CLI - adopt, verify, graph, and govern frontend codebases touched by AI agents",
   "keywords": [
     "decantr",
@@ -50,10 +50,10 @@
   "dependencies": {
     "ajv": "^8.20.0",
     "@decantr/core": "3.4.0",
-    "@decantr/telemetry": "3.4.0",
+    "@decantr/essence-spec": "3.4.0",
     "@decantr/registry": "3.4.0",
-    "@decantr/verifier": "3.4.0",
-    "@decantr/essence-spec": "3.4.0"
+    "@decantr/telemetry": "3.4.0",
+    "@decantr/verifier": "3.4.1"
   },
   "scripts": {
     "build": "tsup",

package/src/templates/DECANTR.md.template

@@ -2,6 +2,8 @@
 
 This project uses **Decantr** for AI Frontend Governance. Read this file before generating or editing UI code.
 
+**Before editing any route, run `decantr task <route> "<intent>"`.** Use that task context as the working contract for the edit. If you are an AI assistant, do not start route-level source changes until task context has been loaded or the user explicitly tells you to proceed without it.
+
 ---
 
 ## What is Decantr?
@@ -16,13 +18,13 @@ Decantr is a Contract / Context / Evidence layer that sits between you (the AI c
 
 ### DNA (Design Axioms)
 
-DNA defines the foundational design rules. **DNA violations are errors** -- they must never happen without updating the essence first.
+DNA defines the foundational design rules. **DNA violations are blocking contract errors** -- they must never happen without updating the essence first.
 
 DNA axioms include: Theme (id, mode, shape), Spacing (density, content gap), Typography (scale, weights), Color (palette, accent count), Radius (philosophy, base), Elevation (system, levels), Motion (preference, reduce-motion), Accessibility (WCAG level, focus-visible), and Personality traits.
 
 ### Blueprint (Structural Layout)
 
-Blueprint defines sections, pages, routes, features, and pattern layouts. **Blueprint deviations are warnings** -- they should be corrected but do not block generation.
+Blueprint defines sections, pages, routes, features, and pattern layouts. **Blueprint deviations are usually advisory structural warnings** -- they should be corrected or reviewed, but they do not normally block generation unless the active workflow makes them strict.
 
 Blueprint includes: Sections (grouped by archetype with role, shell, and scoped features), Page definitions with layouts and pattern references, Routes (URL mapping), and Features (resolved from archetype union + blueprint overrides).
 
@@ -82,6 +84,15 @@ When a user request would violate guard rules:
 
 `decantr.essence.json` is the structural spec. Tools and guards read this.
 
+Authority order for this project:
+
+1. In Brownfield and Hybrid workflows, the existing production source is the observed implementation truth.
+2. Accepted `.decantr/local-patterns.json`, `.decantr/rules.json`, and `.decantr/style-bridge.json` are project-owned local law where present.
+3. `decantr.essence.json` is the structural contract for routes, sections, DNA, guard mode, and intended product shape.
+4. Hosted registry patterns and execution packs are guidance unless the project maps them into accepted local law.
+
+When runtime source and Decantr context disagree, report the drift and run `decantr doctor` or `decantr verify --brownfield --local-patterns`; do not guess which side wins.
+
 ### Initial scaffolding
 
 This project is using Decantr in **{{WORKFLOW_MODE}}** mode.
@@ -95,6 +106,8 @@ Then read `.decantr/context/section-{name}.md` for the fuller context. Prefer th
 
 ### Working on a route
 
+Run `decantr task <route> "<intent>"` before editing. Read the files it lists first and preserve the authority block it prints.
+
 Read `.decantr/context/page-{name}-pack.md` for the most local compiled route contract before editing a specific page. Route-local packs should win over broader narrative docs when there is any mismatch.
 
 ### Editing rules
@@ -114,21 +127,20 @@ Read `.decantr/context/page-{name}-pack.md` for the most local compiled route co
 
 ### Validation
 
-Run `decantr check` to detect drift violations while editing and `decantr audit` to audit the whole project contract after implementation.
-Run `decantr health` for the broader Project Health view before handoff, pull requests, or CI. Use `decantr health init-ci` to install the default GitHub Actions health gate, `decantr health --prompt <finding-id>` to generate a scoped remediation prompt for a specific issue, and `decantr studio` to inspect local drift, routes, findings, remediation, CI, and pack state in a localhost dashboard.
+Run `decantr verify` for the broader Project Health view before handoff, pull requests, or CI. Use `decantr ci init` to install the default GitHub Actions gate, `decantr health --prompt <finding-id>` to generate a scoped remediation prompt for a specific issue, and `decantr studio` to inspect local drift, routes, findings, remediation, CI, and pack state in a localhost dashboard.
 Declared command palettes and hotkeys must be implemented, not merely acknowledged.
 
 ### Quick Commands
 
 ```bash
-decantr status          # Project status overview
-decantr health          # Local contract health report
-decantr health init-ci  # Install GitHub Actions health gate
-decantr studio          # Local health dashboard
-decantr check           # Detect drift violations
-decantr get pattern X   # Fetch a pattern spec from registry
-decantr get theme X     # Fetch theme details and decorators
-decantr search <query>  # Search the registry
+decantr setup                         # Detect project state and next workflow step
+decantr scan                          # Read-only Brownfield preview; writes no files
+decantr adopt --yes                   # Attach Decantr to an existing app
+decantr doctor                        # Explain current state, authority, and next steps
+decantr task <route> "<intent>"       # Load route/task context before AI edits
+decantr verify --brownfield           # Run local Project Health and drift checks
+decantr ci init                       # Install the pinned CI gate
+decantr studio                        # Open the local health dashboard
 ```
 
 ---