@decantr/cli 2.12.0 → 2.13.0

package/README.md

@@ -14,10 +14,12 @@ npm install -D @decantr/cli
 Or run it without installing:
 
 ```bash
+npx @decantr/cli scan
 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 right entry path.
+Use `decantr scan` when you want a zero-commit Brownfield preview. It reads local files, detects framework/routes/styling/static-hosting/assistant-rule signals, 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 blueprint/archetype it uses the runnable adapter and Decantr CSS; without registry content it creates a contract-only workspace unless you explicitly pass `--adoption=decantr-css`.
 Use `decantr adopt` when you already have an app and want Decantr governance without adopting a blueprint. Brownfield attach is proposal-driven: Decantr inventories the app, writes an observed essence proposal, hydrates hosted execution packs when online, and only applies the contract when you explicitly accept or merge it.
 Use `decantr doctor` when the next step is unclear, `decantr task` before asking an LLM to modify a route, `decantr verify` after the edit, and `decantr ci` in required automation. Use `decantr codify --from-audit --style-bridge` when you want project-owned UI patterns, 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, rules, and style bridge mappings as project authority.
@@ -41,11 +43,14 @@ Explicit workflow/adoption flags:
 
 ```bash
 decantr setup
+decantr scan
+decantr scan --project apps/web --json
 decantr adopt --yes
 decantr doctor
 decantr ci --fail-on error
 decantr ci init
 decantr codify --from-audit --style-bridge
+decantr codify --map-pattern hero
 decantr codify --accept
 decantr task /feed "add saved recipe actions"
 decantr verify --brownfield --local-patterns
@@ -76,16 +81,18 @@ pnpm exec decantr workspace list
 pnpm exec decantr adopt --project apps/web --yes
 pnpm exec decantr doctor --project apps/web
 pnpm exec decantr codify --from-audit --style-bridge --project apps/web
+pnpm exec decantr codify --map-pattern hero --project apps/web
 pnpm exec decantr ci init --project apps/web
 ```
 
 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. 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 codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with Hybrid authority guidance and source-derived button/card class hints; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`, mapping Decantr intent to project-owned tokens/classes without requiring `@decantr/css`. After review, `decantr codify --accept` promotes whichever proposals exist. `decantr doctor` reports whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or Hybrid composition. `decantr task` prints that authority block and warns before mixing runtimes or adding Decantr CSS to a non-Decantr-CSS app. `decantr suggest --from-code` surfaces accepted local patterns and style bridge mappings from the app root or selected `--project`, and `decantr ci` prints accepted local-rule findings plus style bridge status in text, markdown, and JSON reports. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
+`decantr scan` is different from the mutating Brownfield primitives: it is look-don't-touch reconnaissance for fit, route/style evidence, GitHub Pages hints, and next-command guidance. `decantr analyze` 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 codify --from-audit` proposes `.decantr/local-patterns.proposal.json` and `.decantr/rules.proposal.json` with Hybrid authority guidance, source-derived button/card/form/theme evidence, variant hints, and confidence tiers; `decantr codify --style-bridge` proposes `.decantr/style-bridge.proposal.json`, mapping Decantr intent to project-owned tokens/classes without requiring `@decantr/css`; `decantr codify --map-pattern <slug>` maps a hosted or bundled registry pattern into an advisory local-law proposal without changing source. After review, `decantr codify --accept` promotes whichever proposals exist. `decantr doctor` reports whether the app is contract-only, Hybrid local law, style bridge, Decantr CSS, or Hybrid composition. `decantr task` prints that authority block and warns before mixing runtimes or adding Decantr CSS to a non-Decantr-CSS app. `decantr suggest --from-code` surfaces accepted local patterns and style bridge mappings from the app root or selected `--project`, and `decantr ci` prints accepted local-rule findings plus style bridge status in text, markdown, and JSON reports. `decantr verify --brownfield --local-patterns` uses the Brownfield guard layer plus accepted local law to flag actionable missing doctrine coverage, unsafe context, missing assistant bridges, style drift, raw local-rule violations, and unsafe defaults without treating current database migrations as stale docs.
 
 ## What It Does
 
 - scaffolds Decantr projects from blueprints, archetypes, or prompts
+- previews existing apps with read-only Brownfield scan reports
 - guides users through human workflow commands: setup, adopt, doctor, task, verify, ci, and codify
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, Hybrid local law, Hybrid style bridge, Hybrid Decantr CSS, and hybrid composition
 - generates execution-pack context files for AI coding assistants
@@ -99,7 +106,7 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 
 ## Security And Permissions
 
-The CLI is intentionally a local project inspector and artifact writer. It reads selected project/workspace files, package manifests, routing/style/config files, `.decantr` artifacts, and Decantr cache/config files. It writes `decantr.essence.json`, `DECANTR.md`, `.decantr/*`, generated context packs, optional CI workflows/snippets, optional style/export files, and auth/telemetry config only when explicitly requested.
+The CLI is intentionally a local project inspector and artifact writer. It reads selected project/workspace files, package manifests, routing/style/config files, `.decantr` artifacts, and Decantr cache/config files. It writes `decantr.essence.json`, `DECANTR.md`, `.decantr/*`, generated context packs, optional CI workflows/snippets, optional style/export files, and auth/telemetry config only when explicitly requested. `decantr scan` is the exception by design: it reads and prints only, and does not create `.decantr`, save reports, upload source, run package scripts, or install dependencies.
 
 Telemetry is disabled by default. Hosted registry, hosted pack hydration, hosted critique/audit, and browser evidence are explicit command paths; screenshots and Evidence Bundles stay local unless a hosted workflow is invoked. Release audits prove the installed package with `npm pack --dry-run --json`. See [security permissions](https://decantr.ai/reference/security-permissions.md).
 
@@ -107,12 +114,16 @@ Telemetry is disabled by default. Hosted registry, hosted pack hydration, hosted
 
 ```bash
 decantr setup
+decantr scan
+decantr scan --project apps/web
+decantr scan --json
 decantr new my-app --blueprint=esports-hq
 decantr adopt --yes
 decantr adopt --project apps/web --yes
 decantr doctor
 decantr doctor --project apps/web
 decantr codify --from-audit --style-bridge
+decantr codify --map-pattern hero --project apps/web
 decantr codify --accept
 decantr task /feed "add saved recipe actions"
 decantr verify --brownfield --local-patterns

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-SWPAAAO4.js";
-import "./chunk-IQZCIMQJ.js";
-import "./chunk-F6SWDGKO.js";
-import "./chunk-PHRVC575.js";
-import "./chunk-CAKQWTZS.js";
+import "./chunk-5MZH6XXQ.js";
+import "./chunk-SIDKK73N.js";
+import "./chunk-YBSBAJ3E.js";
+import "./chunk-3A2DLR47.js";
+import "./chunk-MNZKOZW7.js";

package/dist/{chunk-PHRVC575.js → chunk-3A2DLR47.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-CAKQWTZS.js";
+} from "./chunk-MNZKOZW7.js";
 
 // src/commands/health.ts
 import { execFileSync } from "child_process";
@@ -91,8 +91,10 @@ function listWorkspaceAppCandidates(workspaceRoot) {
 }
 function resolveWorkspaceInfo(cwd, projectArg) {
   const absoluteCwd = resolve(cwd);
-  const workspaceRoot = findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
-  const appRoot = projectArg ? resolve(isAbsolute(projectArg) ? "/" : workspaceRoot, projectArg) : absoluteCwd;
+  const appRoot = projectArg ? resolve(
+    isAbsolute(projectArg) ? projectArg : join(findWorkspaceRoot(absoluteCwd) ?? absoluteCwd, projectArg)
+  ) : absoluteCwd;
+  const workspaceRoot = projectArg && isAbsolute(projectArg) ? findWorkspaceRoot(appRoot) ?? appRoot : findWorkspaceRoot(absoluteCwd) ?? absoluteCwd;
   const appCandidates = listWorkspaceApps(workspaceRoot);
   const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
   const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 0;

package/dist/{chunk-SWPAAAO4.js → chunk-5MZH6XXQ.js}

@@ -14,7 +14,7 @@ import {
   scaffoldProject,
   syncRegistry,
   writeExecutionPackBundleArtifacts
-} from "./chunk-IQZCIMQJ.js";
+} from "./chunk-SIDKK73N.js";
 import {
   createWorkspaceHealthReport,
   formatWorkspaceHealthMarkdown,
@@ -22,14 +22,14 @@ import {
   listWorkspaceCandidates,
   listWorkspaceProjects,
   shouldFailWorkspaceHealth
-} from "./chunk-F6SWDGKO.js";
+} from "./chunk-YBSBAJ3E.js";
 import {
   createProjectHealthReport,
   formatProjectHealthMarkdown,
   formatProjectHealthText,
   resolveWorkspaceInfo,
   shouldFailHealth
-} from "./chunk-PHRVC575.js";
+} from "./chunk-3A2DLR47.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -46,7 +46,7 @@ import {
   sendCliCommandTelemetry,
   sendNewProjectCompletedTelemetry,
   writeDoctrineMap
-} from "./chunk-CAKQWTZS.js";
+} from "./chunk-MNZKOZW7.js";
 
 // src/index.ts
 import { existsSync as existsSync30, mkdirSync as mkdirSync17, readdirSync as readdirSync9, readFileSync as readFileSync23, writeFileSync as writeFileSync20 } from "fs";
@@ -68,7 +68,8 @@ import {
 } from "@decantr/registry";
 import {
   auditProject,
-  critiqueFile as critiqueProjectFile
+  critiqueFile as critiqueProjectFile,
+  scanProject as scanProjectReadOnly
 } from "@decantr/verifier";
 
 // src/artifacts.ts
@@ -3327,6 +3328,22 @@ function createBrownfieldCodifyProposal(input) {
         componentPaths: evidence.buttonComponents,
         decide: "Define primary, secondary, tertiary, destructive, icon-only, disabled, and loading button variants from this app.",
         classHints: evidence.buttonClassHints,
+        variants: evidence.buttonVariants,
+        sourceEvidence: evidence.buttonSourceEvidence,
+        confidence: confidenceForEvidence({
+          componentCount: evidence.buttonComponents.length,
+          classHintCount: evidence.buttonClassHints.length,
+          variantCount: evidence.buttonVariants.length,
+          sourceEvidenceCount: evidence.buttonSourceEvidence.length
+        }),
+        enforcement: {
+          level: "warn",
+          status: "proposal",
+          notes: [
+            "Treat as advisory until the team confirms variant names and wrapper paths.",
+            "Raise related rules to error only after raw button usage can be fixed without churn."
+          ]
+        },
         evidence: evidence.buttonComponents.length ? evidence.buttonComponents : evidence.buttonClassHints.length ? evidence.buttonClassHints : [
           "No obvious Button wrapper found yet. Add the project-owned wrapper path before strict enforcement."
         ],
@@ -3340,6 +3357,22 @@ function createBrownfieldCodifyProposal(input) {
         componentPaths: evidence.cardComponents,
         decide: "Define the canonical card background, border, radius, shadow, padding, density, and hover treatment.",
         classHints: evidence.cardClassHints,
+        variants: evidence.cardVariants,
+        sourceEvidence: evidence.cardSourceEvidence,
+        confidence: confidenceForEvidence({
+          componentCount: evidence.cardComponents.length,
+          classHintCount: evidence.cardClassHints.length,
+          variantCount: evidence.cardVariants.length,
+          sourceEvidenceCount: evidence.cardSourceEvidence.length
+        }),
+        enforcement: {
+          level: "warn",
+          status: "proposal",
+          notes: [
+            "Use this family to converge repeated surface recipes before enforcing card rules.",
+            "Document route-specific card exceptions before asking CI to block them."
+          ]
+        },
         evidence: evidence.cardComponents.length ? evidence.cardComponents : [
           "No obvious Card wrapper found yet. Add the project-owned wrapper path or class recipe."
         ],
@@ -3352,6 +3385,24 @@ function createBrownfieldCodifyProposal(input) {
         appliesTo: ["routes", "layouts", "navigation shells", "scroll containers"],
         componentPaths: evidence.shellComponents,
         decide: "Define which layout owns max width, gutters, sticky chrome, responsive breakpoints, and scroll containers.",
+        sourceEvidence: collectSourceEvidence(input.projectRoot, sourceFiles, [
+          "layout",
+          "shell",
+          "nav",
+          "sidebar",
+          "container"
+        ]),
+        confidence: confidenceForEvidence({
+          componentCount: evidence.shellComponents.length,
+          sourceEvidenceCount: evidence.shellComponents.length
+        }),
+        enforcement: {
+          level: "advisory",
+          status: "proposal",
+          notes: [
+            "Layout ownership is usually reviewed by humans first because route shells can legitimately differ."
+          ]
+        },
         evidence: evidence.shellComponents.length ? evidence.shellComponents : ["Add root layout, shell, or app frame files that establish route chrome and spacing."],
         forbiddenAlternatives: [
           "Each page inventing independent max-width, padding, or sticky nav rules."
@@ -3364,6 +3415,20 @@ function createBrownfieldCodifyProposal(input) {
         appliesTo: ["inputs", "selects", "textareas", "validation messages", "form actions"],
         componentPaths: evidence.formComponents,
         decide: "Define input height, label placement, error copy, disabled state, required state, and focus treatment.",
+        variants: evidence.formVariants,
+        sourceEvidence: evidence.formSourceEvidence,
+        confidence: confidenceForEvidence({
+          componentCount: evidence.formComponents.length,
+          variantCount: evidence.formVariants.length,
+          sourceEvidenceCount: evidence.formSourceEvidence.length
+        }),
+        enforcement: {
+          level: "warn",
+          status: "proposal",
+          notes: [
+            "Start by mapping field wrappers, labels, error states, and disabled states from source."
+          ]
+        },
         evidence: evidence.formComponents.length ? evidence.formComponents : ["Add form field wrapper paths and validation examples."],
         forbiddenAlternatives: [
           "Unlabeled one-off inputs or validation states that do not match the app standard."
@@ -3376,6 +3441,20 @@ function createBrownfieldCodifyProposal(input) {
         appliesTo: ["theme toggles", "mode-specific classes", "brand variants", "tenant variants"],
         componentPaths: evidence.themeComponents,
         decide: "Document which theme variants exist, where they are toggled, and which tokens/classes are legal per variant.",
+        variants: evidence.themeVariants,
+        sourceEvidence: evidence.themeSourceEvidence,
+        confidence: confidenceForEvidence({
+          componentCount: evidence.themeComponents.length,
+          variantCount: evidence.themeVariants.length,
+          sourceEvidenceCount: evidence.themeSourceEvidence.length
+        }),
+        enforcement: {
+          level: "advisory",
+          status: "proposal",
+          notes: [
+            "Theme variant law should preserve the existing theme provider/tokens before adding any new mode."
+          ]
+        },
         evidence: evidence.themeComponents.length ? evidence.themeComponents : ["If the app has dark/light or brand variants, add the toggles/providers here."],
         forbiddenAlternatives: [
           "Component-local theme forks that bypass shared theme providers or tokens."
@@ -3467,6 +3546,107 @@ function writeBrownfieldCodifyProposal(projectRoot, proposal) {
 `, "utf-8");
   return { patternPath, rulesPath };
 }
+function writeHostedPatternMappingProposal(input) {
+  const decantrDir = join15(input.projectRoot, ".decantr");
+  mkdirSync8(decantrDir, { recursive: true });
+  const existing = readJsonFile(localPatternsProposalPath(input.projectRoot)) ?? readJsonFile(localPatternsPath(input.projectRoot));
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const patternPack = {
+    version: 2,
+    generatedAt,
+    status: "proposal",
+    source: "decantr codify --map-pattern",
+    purpose: existing?.purpose ?? "Project-owned Brownfield/Hybrid UI law. Review and edit before accepting; Decantr treats this as authoritative only after it is copied to .decantr/local-patterns.json.",
+    hybrid: existing?.hybrid ?? {
+      intent: "This local pattern pack maps Decantr concepts onto project-owned components, tokens, classes, and rules without replacing the app runtime.",
+      authorityPrecedence: [
+        "existing production source",
+        "accepted local patterns and rules",
+        "Decantr Essence V4 contract",
+        "hosted registry patterns and execution packs as optional guidance"
+      ],
+      hostedPatternMapping: "Hosted registry patterns are advisory until mapped to project-owned component paths, token recipes, class recipes, and explicit exceptions."
+    },
+    patterns: Array.isArray(existing?.patterns) ? [...existing.patterns] : [],
+    starterRules: Array.isArray(existing?.starterRules) ? existing.starterRules : [],
+    nextSteps: Array.isArray(existing?.nextSteps) ? existing.nextSteps : [
+      "Review this proposal with the team.",
+      "Add project-owned component paths, token hints, class recipes, and exceptions.",
+      "Run decantr codify --accept after review.",
+      "Use decantr task <route> before LLM edits so local law appears in task context."
+    ]
+  };
+  const slug = input.hostedPattern.slug.trim();
+  const existingIds = new Set(
+    (patternPack.patterns ?? []).map((pattern) => typeof pattern.id === "string" ? pattern.id : "").filter(Boolean)
+  );
+  const localPatternId = existingIds.has(slug) ? `${slug}-registry-map` : slug;
+  const mappedPattern = {
+    id: localPatternId,
+    label: input.hostedPattern.name ? `${input.hostedPattern.name} registry mapping` : `${slug} registry mapping`,
+    role: "Hosted registry guidance mapped into project-owned Hybrid law",
+    appliesTo: [
+      ...input.hostedPattern.components ?? [],
+      ...input.hostedPattern.interactions ?? [],
+      ...input.hostedPattern.tags ?? []
+    ].slice(0, 24),
+    componentPaths: [],
+    tokenHints: [],
+    classHints: [],
+    decide: `Map hosted pattern "${slug}" into this app's existing components, tokens, classes, and exceptions before treating it as enforceable.`,
+    hostedPatternRefs: [input.hostedPattern],
+    confidence: {
+      tier: "low",
+      score: 0.25,
+      rationale: [
+        "A hosted registry pattern was selected intentionally.",
+        "No project-owned component path or token recipe has been mapped yet."
+      ]
+    },
+    enforcement: {
+      level: "advisory",
+      status: "needs-mapping",
+      notes: [
+        "This proposal does not change source files.",
+        "Do not enforce this hosted pattern until project-owned implementation details are filled in.",
+        "Use accepted local rules, ESLint, Biome, Storybook, or visual regression for deterministic blocking checks."
+      ]
+    },
+    evidence: [
+      `Hosted pattern ${input.hostedPattern.source}/${slug}${input.hostedPattern.description ? `: ${input.hostedPattern.description}` : ""}`,
+      input.hostedPattern.visualBrief ? `Visual brief: ${input.hostedPattern.visualBrief}` : "Visual brief not provided by the hosted pattern."
+    ],
+    evidenceToCollect: [
+      "Project-owned component path(s) that implement this pattern.",
+      "Allowed token/class recipe(s) for this app.",
+      "Variant names and states that are legal in this project.",
+      "Explicit exceptions where this hosted pattern should not apply."
+    ],
+    forbiddenAlternatives: [
+      "Replacing existing app components solely because a hosted pattern exists.",
+      "Treating hosted registry guidance as enforceable without accepted local law."
+    ]
+  };
+  const index = (patternPack.patterns ?? []).findIndex((pattern) => pattern.id === localPatternId);
+  const replacedExisting = index >= 0;
+  if (replacedExisting) {
+    patternPack.patterns[index] = mappedPattern;
+  } else {
+    patternPack.patterns = [...patternPack.patterns ?? [], mappedPattern];
+  }
+  patternPack.nextSteps = [
+    .../* @__PURE__ */ new Set([
+      ...patternPack.nextSteps ?? [],
+      "Fill the hosted mapping with project-owned component paths, token/class recipes, variants, and exceptions.",
+      "Run decantr codify --accept only after the mapping reflects the existing app.",
+      "Use decantr verify --brownfield --local-patterns after edits to keep mapped local law visible."
+    ])
+  ];
+  const patternPath = localPatternsProposalPath(input.projectRoot);
+  writeFileSync9(patternPath, `${JSON.stringify(patternPack, null, 2)}
+`, "utf-8");
+  return { patternPath, localPatternId, replacedExisting };
+}
 function acceptBrownfieldLocalLaw(projectRoot) {
   const patternProposal = readJsonFile(localPatternsProposalPath(projectRoot));
   const ruleProposal = readJsonFile(localRulesProposalPath(projectRoot));
@@ -3509,11 +3689,17 @@ function validateLocalLaw(projectRoot) {
       const paths = Array.isArray(pattern.componentPaths) ? pattern.componentPaths : [];
       const evidence = Array.isArray(pattern.evidence) ? pattern.evidence : [];
       const todoEvidence = Array.isArray(pattern.evidenceToCollect) ? pattern.evidenceToCollect : [];
+      const hostedRefs = Array.isArray(pattern.hostedPatternRefs) ? pattern.hostedPatternRefs : [];
       if (id && paths.length === 0 && evidence.length === 0 && todoEvidence.length > 0) {
         warnings.push(
           `Local pattern ${id} still reads like a TODO; add concrete component paths or evidence.`
         );
       }
+      if (id && hostedRefs.length > 0 && paths.length === 0) {
+        warnings.push(
+          `Local pattern ${id} maps hosted registry guidance but has no project-owned component path yet.`
+        );
+      }
     }
   }
   if (ruleManifest && !Array.isArray(ruleManifest.rules)) {
@@ -3535,7 +3721,10 @@ function createLocalLawTaskSummary(projectRoot) {
   const patterns = (patternPack?.patterns ?? []).map((pattern) => ({
     id: typeof pattern.id === "string" ? pattern.id : "unknown",
     role: typeof pattern.role === "string" ? pattern.role : null,
-    componentPaths: Array.isArray(pattern.componentPaths) ? pattern.componentPaths.filter((entry) => typeof entry === "string") : []
+    componentPaths: Array.isArray(pattern.componentPaths) ? pattern.componentPaths.filter((entry) => typeof entry === "string") : [],
+    confidenceTier: typeof pattern.confidence === "object" && pattern.confidence !== null && typeof pattern.confidence.tier === "string" ? pattern.confidence.tier : null,
+    enforcementLevel: typeof pattern.enforcement === "object" && pattern.enforcement !== null && typeof pattern.enforcement.level === "string" ? pattern.enforcement.level : null,
+    hostedPatternRefs: Array.isArray(pattern.hostedPatternRefs) ? pattern.hostedPatternRefs.map((ref) => typeof ref?.slug === "string" ? ref.slug : null).filter((slug) => Boolean(slug)) : []
   }));
   const rules = (ruleManifest?.rules ?? []).map((rule) => ({
     id: rule.id,
@@ -3653,6 +3842,50 @@ function summarizeSourceEvidence(projectRoot, files) {
     formComponents: byName(["input", "field", "form", "select", "textarea"]),
     shellComponents,
     themeComponents,
+    buttonVariants: detectVariants(projectRoot, files, {
+      family: "button",
+      terms: ["primary", "secondary", "tertiary", "ghost", "link", "destructive", "icon"]
+    }),
+    cardVariants: detectVariants(projectRoot, files, {
+      family: "surface",
+      terms: ["card", "panel", "surface", "tile", "elevated", "interactive", "glass"]
+    }),
+    formVariants: detectVariants(projectRoot, files, {
+      family: "form",
+      terms: ["error", "invalid", "disabled", "required", "success", "helper"]
+    }),
+    themeVariants: detectVariants(projectRoot, files, {
+      family: "theme",
+      terms: ["dark", "light", "brand", "tenant", "theme", "mode", "density"]
+    }),
+    buttonSourceEvidence: collectSourceEvidence(projectRoot, files, [
+      "button",
+      "primary",
+      "secondary",
+      "tertiary",
+      "destructive"
+    ]),
+    cardSourceEvidence: collectSourceEvidence(projectRoot, files, [
+      "card",
+      "panel",
+      "surface",
+      "rounded",
+      "shadow"
+    ]),
+    formSourceEvidence: collectSourceEvidence(projectRoot, files, [
+      "input",
+      "label",
+      "error",
+      "field",
+      "select"
+    ]),
+    themeSourceEvidence: collectSourceEvidence(projectRoot, files, [
+      "theme",
+      "dark",
+      "light",
+      "brand",
+      "tenant"
+    ]),
     buttonClassHints: collectClassHints(projectRoot, files, [
       "button",
       "btn",
@@ -3666,6 +3899,70 @@ function summarizeSourceEvidence(projectRoot, files) {
     cardClassHints: collectClassHints(projectRoot, files, ["card", "panel", "surface", "tile"])
   };
 }
+function detectVariants(projectRoot, files, input) {
+  const variants = /* @__PURE__ */ new Map();
+  const termPattern = new RegExp(
+    `\\b(${input.terms.map(escapeRegExp).join("|")})(?:[-_:][a-z0-9-]+)?\\b`,
+    "gi"
+  );
+  for (const file of files) {
+    if (!UI_TEMPLATE_EXTENSIONS.has(extname(file.absolute))) continue;
+    const content = readFileSync11(join15(projectRoot, file.relative), "utf-8");
+    for (const match of content.matchAll(termPattern)) {
+      const raw = (match[0] ?? "").toLowerCase();
+      const id = raw.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+      if (!id || id.length < 3) continue;
+      const position = lineColumnAt(content, match.index ?? 0);
+      const line = lineAt(content, position.line).trim().slice(0, 160);
+      const entry = variants.get(id) ?? { evidence: /* @__PURE__ */ new Set(), count: 0 };
+      entry.count += 1;
+      entry.evidence.add(`${file.relative}:${position.line} ${line}`);
+      variants.set(id, entry);
+    }
+  }
+  return [...variants.entries()].sort((a, b) => b[1].count - a[1].count || a[0].localeCompare(b[0])).slice(0, 8).map(([id, value]) => ({
+    id,
+    label: `${input.family} ${id}`,
+    evidence: [...value.evidence].slice(0, 4),
+    confidence: value.count >= 4 ? "high" : value.count >= 2 ? "medium" : "low"
+  }));
+}
+function collectSourceEvidence(projectRoot, files, terms) {
+  const results = [];
+  const termPattern = new RegExp(terms.map(escapeRegExp).join("|"), "i");
+  for (const file of files) {
+    if (!UI_TEMPLATE_EXTENSIONS.has(extname(file.absolute))) continue;
+    const content = readFileSync11(join15(projectRoot, file.relative), "utf-8");
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      if (!termPattern.test(line)) continue;
+      const signals = terms.filter((term) => line.toLowerCase().includes(term.toLowerCase()));
+      results.push({
+        file: file.relative,
+        line: index + 1,
+        excerpt: line.trim().slice(0, 180),
+        signals: signals.slice(0, 6)
+      });
+      if (results.length >= 16) return results;
+      break;
+    }
+  }
+  return results;
+}
+function confidenceForEvidence(input) {
+  const score = Math.min(
+    1,
+    input.componentCount * 0.28 + (input.classHintCount ?? 0) * 0.08 + (input.variantCount ?? 0) * 0.08 + (input.sourceEvidenceCount ?? 0) * 0.05
+  );
+  const tier = score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low";
+  const rationale = [
+    input.componentCount > 0 ? `${input.componentCount} likely component path(s) detected` : "no likely component wrapper detected yet",
+    (input.classHintCount ?? 0) > 0 ? `${input.classHintCount} class recipe hint(s) detected` : "no strong class recipe hints detected yet",
+    (input.variantCount ?? 0) > 0 ? `${input.variantCount} possible variant signal(s) detected` : "variant names still need team confirmation"
+  ];
+  return { tier, score: Number(score.toFixed(2)), rationale };
+}
 function collectClassHints(projectRoot, files, terms) {
   const hints = /* @__PURE__ */ new Map();
   const wantsButton = terms.some(
@@ -3760,6 +4057,9 @@ function lineColumnAt(contents, index) {
     column: lines[lines.length - 1].length + 1
   };
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function lineAt(contents, line) {
   return contents.split(/\r?\n/)[line - 1] ?? "";
 }
@@ -4225,6 +4525,9 @@ function formatLocalLawText(summary, health) {
   lines.push(
     `  Patterns: ${summary.patternsPresent ? "present" : "missing"} | Rules: ${summary.rulesPresent ? "present" : "missing"}`
   );
+  lines.push(
+    summary.rulesPresent ? "  Enforcement: Decantr scans accepted .decantr/rules.json; this command's --fail-on setting controls whether findings block." : "  Enforcement: advisory only until .decantr/rules.json is accepted."
+  );
   lines.push(`  Findings: ${summary.errorCount} error(s), ${summary.warnCount} warning(s)`);
   for (const warning of summary.warnings.slice(0, 5)) {
     lines.push(`  ${DIM3}[WARN] ${warning}${RESET3}`);
@@ -4252,6 +4555,9 @@ function formatStyleBridgeText(summary) {
   lines.push(
     `  Present: ${summary.present ? "yes" : "no"} | Mappings: ${summary.mappingCount} | Styling: ${summary.stylingApproach ?? "unknown"}`
   );
+  lines.push(
+    "  Enforcement: advisory style-intent mapping; pair with accepted local rules, lint, tests, or visual regression when it should block."
+  );
   if (summary.themeModes.length > 0) {
     lines.push(`  Theme modes: ${summary.themeModes.join(", ")}`);
   }
@@ -4276,6 +4582,9 @@ function formatLocalLawMarkdown(summary, health) {
   lines.push(
     `Patterns: **${summary.patternsPresent ? "present" : "missing"}** \xB7 Rules: **${summary.rulesPresent ? "present" : "missing"}**`
   );
+  lines.push(
+    summary.rulesPresent ? "Enforcement: Decantr scans accepted `.decantr/rules.json`; CI blocking depends on `--fail-on`." : "Enforcement: advisory only until `.decantr/rules.json` is accepted."
+  );
   lines.push("");
   lines.push(`Findings: **${summary.errorCount} error(s), ${summary.warnCount} warning(s)**`);
   if (summary.warnings.length > 0) {
@@ -4303,6 +4612,10 @@ function formatStyleBridgeMarkdown(summary) {
   lines.push(
     `Present: **${summary.present ? "yes" : "no"}** \xB7 Mappings: **${summary.mappingCount}** \xB7 Styling: **${summary.stylingApproach ?? "unknown"}**`
   );
+  lines.push("");
+  lines.push(
+    "Enforcement: advisory style-intent mapping; pair with accepted local rules, lint, tests, or visual regression when it should block."
+  );
   if (summary.themeModes.length > 0) {
     lines.push("", `Theme modes: ${summary.themeModes.map((mode) => `\`${mode}\``).join(", ")}`);
   }
@@ -9270,6 +9583,25 @@ function patternCandidateFromRegistryItem(item, source) {
     { source, slug }
   );
 }
+function hostedPatternRefFromCandidate(candidate) {
+  const slug = candidate.slug || candidate.id;
+  return {
+    slug,
+    source: candidate.source ?? "registry",
+    name: candidate.name,
+    description: candidate.description,
+    tags: candidate.tags,
+    components: candidate.components,
+    interactions: candidate.interactions,
+    visualBrief: candidate.visual_brief
+  };
+}
+function findPatternCandidateBySlug(candidates, slug) {
+  const normalized = slug.toLowerCase();
+  return candidates.find(
+    (candidate) => candidate.slug?.toLowerCase() === normalized || candidate.id.toLowerCase() === normalized || candidate.name?.toLowerCase() === normalized
+  ) ?? null;
+}
 function readSuggestCodeContext(projectRoot, route, file) {
   const pieces = [];
   if (file) {
@@ -10936,7 +11268,12 @@ function resolveWorkflowProject(flags, commandName = "command", options = {}) {
   }
   if (projectArg && options.requireAppCandidate && workspaceInfo.appCandidates.length > 0) {
     const normalizedProject = normalizedProjectPath(projectArg);
-    const knownCandidate = normalizedProject ? workspaceInfo.appCandidates.includes(normalizedProject) : false;
+    const normalizedWorkspaceProject = normalizedProjectPath(
+      relative7(workspaceInfo.workspaceRoot, workspaceInfo.appRoot)
+    );
+    const knownCandidate = normalizedProject ? workspaceInfo.appCandidates.includes(normalizedProject) || Boolean(
+      normalizedWorkspaceProject && workspaceInfo.appCandidates.includes(normalizedWorkspaceProject)
+    ) : false;
     const forcePackage = flagBoolean(flags, "force-package") || flagBoolean(flags, "allow-package") || flagBoolean(flags, "force");
     if (!knownCandidate && !forcePackage && !options.allowPackageProject) {
       console.error(
@@ -10969,6 +11306,101 @@ function printWorkflowPlan(title, steps) {
   }
   console.log("");
 }
+function scanSeverityColor(finding) {
+  if (finding.severity === "success") return success3("ok");
+  if (finding.severity === "error") return error2("error");
+  if (finding.severity === "warn") return `${YELLOW12}warn${RESET16}`;
+  return cyan3("info");
+}
+function formatScanApplicability(status) {
+  if (status === "strong_fit") return success3("strong fit");
+  if (status === "partial_fit") return `${YELLOW12}partial fit${RESET16}`;
+  if (status === "not_applicable") return dim3("not applicable");
+  return dim3("unknown");
+}
+function printScanReport(report) {
+  console.log(heading2("Decantr Scan"));
+  console.log(dim3("Read-only Brownfield reconnaissance. No files were written."));
+  console.log("");
+  console.log(`${BOLD9}Verdict${RESET16}`);
+  console.log(`  ${formatScanApplicability(report.applicability.status)}  ${report.applicability.label}`);
+  console.log(
+    `  Confidence: ${cyan3(`${report.confidence.score}/100`)} (${report.confidence.level})`
+  );
+  for (const reason of report.applicability.reasons.slice(0, 3)) {
+    console.log(`  ${dim3("-")} ${reason}`);
+  }
+  console.log("");
+  console.log(`${BOLD9}Project${RESET16}`);
+  console.log(`  Framework:      ${cyan3(report.project.framework)}${report.project.frameworkVersion ? ` ${report.project.frameworkVersion}` : ""}`);
+  console.log(`  Package manager:${" "} ${report.project.packageManager}`);
+  console.log(`  Language:       ${report.project.primaryLanguage}`);
+  console.log(`  TypeScript:     ${report.project.hasTypeScript ? "yes" : "no"}`);
+  console.log(`  Decantr:        ${report.project.hasDecantr ? "present" : "not attached"}`);
+  console.log("");
+  console.log(`${BOLD9}Routes And Styling${RESET16}`);
+  console.log(`  Routes:         ${report.routes.count} (${report.routes.strategy})`);
+  for (const route of report.routes.items.slice(0, 8)) {
+    console.log(`    ${cyan3(route.path.padEnd(18))} ${dim3(route.file)}`);
+  }
+  if (report.routes.items.length > 8) {
+    console.log(`    ${dim3(`...${report.routes.items.length - 8} more route(s)`)}`);
+  }
+  console.log(`  Components:     ${report.components.componentCount}`);
+  console.log(
+    `  Styling:        ${report.styling.approach}${report.styling.configFile ? ` (${report.styling.configFile})` : ""}`
+  );
+  console.log(`  CSS variables:  ${report.styling.cssVariableCount}`);
+  console.log(`  Dark mode:      ${report.styling.darkMode ? "yes" : "no"}`);
+  console.log("");
+  if (report.staticHosting.githubPagesLikely || report.pagesProbe) {
+    console.log(`${BOLD9}Published Surface${RESET16}`);
+    console.log(`  GitHub Pages:   ${report.staticHosting.githubPagesLikely ? "likely" : "not detected"}`);
+    if (report.source.publishedSiteUrl) {
+      console.log(`  Site URL:       ${report.source.publishedSiteUrl}`);
+    }
+    if (report.pagesProbe?.checked) {
+      console.log(
+        `  HTTP probe:     ${report.pagesProbe.reachable ? success3("reachable") : `${YELLOW12}unreachable${RESET16}`} ${report.pagesProbe.status ?? ""}`
+      );
+      if (report.pagesProbe.title) console.log(`  Title:          ${report.pagesProbe.title}`);
+    }
+    for (const item of report.staticHosting.evidence.slice(0, 4)) {
+      console.log(`  ${dim3("-")} ${item}`);
+    }
+    console.log("");
+  }
+  console.log(`${BOLD9}Findings${RESET16}`);
+  for (const finding of report.findings.slice(0, 8)) {
+    console.log(`  [${scanSeverityColor(finding)}] ${finding.title}`);
+    console.log(`      ${finding.message}`);
+    if (finding.recommendation) console.log(`      ${dim3(finding.recommendation)}`);
+  }
+  console.log("");
+  console.log(`${BOLD9}Next Commands${RESET16}`);
+  for (const command of report.recommendedCommands) {
+    console.log(`  ${cyan3(command)}`);
+  }
+  console.log("");
+  console.log(dim3(report.privacy.notes[0] ?? "Scan completed without writing files."));
+}
+async function cmdScanWorkflow(args) {
+  const { flags } = parseLooseArgs(args);
+  if (!ensureAllowedFlags(flags, ["project", "json"], "scan")) return;
+  const workspaceInfo = resolveWorkflowProject(flags, "scan");
+  if (!workspaceInfo) return;
+  const jsonOutput = flagBoolean(flags, "json");
+  const projectArg = flagString(flags, "project");
+  const inputValue = projectArg ?? ".";
+  const report = await scanProjectReadOnly(workspaceInfo.appRoot, {
+    input: { kind: "local", value: inputValue }
+  });
+  if (jsonOutput) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  printScanReport(report);
+}
 async function cmdSetupWorkflow(args) {
   const { flags } = parseLooseArgs(args);
   const projectArg = flagString(flags, "project");
@@ -11148,7 +11580,7 @@ async function cmdAdoptWorkflow(args) {
     console.log(dim3("Skipping hosted pack hydration in offline mode."));
   }
   if (runVerify) {
-    const { cmdHealth } = await import("./health-DBCUR6VQ.js");
+    const { cmdHealth } = await import("./health-B4W7UJBZ.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -11219,7 +11651,7 @@ async function cmdVerifyWorkflow(args) {
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-BCA5RCHN.js");
+    const { cmdWorkspace } = await import("./workspace-7RU77ZZW.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -11252,7 +11684,7 @@ async function cmdVerifyWorkflow(args) {
   }
   let guardExitCode;
   if (brownfield) {
-    const { cmdHeal, collectCheckIssues } = await import("./heal-WMSAX4LU.js");
+    const { cmdHeal, collectCheckIssues } = await import("./heal-IRIDB7IZ.js");
     if (quietOutput) {
       const result = collectCheckIssues(workspaceInfo.appRoot, { brownfield: true });
       guardExitCode = result.issues.some((issue) => issue.type === "error") ? 1 : void 0;
@@ -11262,7 +11694,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-DBCUR6VQ.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-B4W7UJBZ.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -11284,6 +11716,9 @@ async function cmdVerifyWorkflow(args) {
         console.log(`${GREEN16}Local pattern pack found:${RESET16} ${validation.patternsPath}`);
         if (validation.ruleManifestPresent) {
           console.log(`${GREEN16}Local rule manifest found:${RESET16} ${validation.rulesPath}`);
+          console.log(
+            `${DIM16}Enforcement: accepted .decantr/rules.json is the Decantr-scanned layer; --fail-on controls whether findings block.${RESET16}`
+          );
         } else {
           console.log(
             `${YELLOW12}Local rule manifest missing.${RESET16} Run ${cyan3("decantr codify --from-audit")} to propose .decantr/rules.json.`
@@ -11319,6 +11754,9 @@ async function cmdVerifyWorkflow(args) {
     console.log(
       `${DIM16}${styleBridge.mappingCount} mapping(s), ${styleBridge.stylingApproach ?? "unknown"} styling${styleBridge.themeModes.length > 0 ? `, themes: ${styleBridge.themeModes.join(", ")}` : ""}${RESET16}`
     );
+    console.log(
+      `${DIM16}Enforcement: advisory style-intent mapping; pair with accepted local rules, lint, tests, or visual regression when it should block.${RESET16}`
+    );
   }
   if (guardExitCode && guardExitCode !== 0 && (!process.exitCode || process.exitCode === 0)) {
     process.exitCode = guardExitCode;
@@ -11548,10 +11986,17 @@ async function cmdTaskWorkflow(args) {
     }
     if (context.localLaw.rulesPath) {
       console.log(`  Rules: ${cyan3(context.localLaw.rulesPath)} (${context.localLaw.ruleCount})`);
+      console.log("  Enforcement: accepted local rules are the Decantr-scanned layer.");
     }
     for (const pattern of context.localLaw.patterns.slice(0, 4)) {
       const pathHint = pattern.componentPaths.length > 0 ? ` \u2014 ${pattern.componentPaths.slice(0, 2).join(", ")}` : "";
-      console.log(`  ${pattern.id}: ${pattern.role ?? "local pattern"}${pathHint}`);
+      const authorityHint = [
+        pattern.role ?? "local pattern",
+        pattern.confidenceTier ? `confidence ${pattern.confidenceTier}` : null,
+        pattern.enforcementLevel ? `${pattern.enforcementLevel}` : null,
+        pattern.hostedPatternRefs.length > 0 ? `maps ${pattern.hostedPatternRefs.slice(0, 2).join(", ")}` : null
+      ].filter(Boolean).join(" | ");
+      console.log(`  ${pattern.id}: ${authorityHint}${pathHint}`);
     }
   } else {
     console.log("");
@@ -11566,6 +12011,9 @@ async function cmdTaskWorkflow(args) {
     console.log(
       `  Bridge: ${cyan3(context.styleBridge.path)} (${context.styleBridge.mappingCount} mappings, ${context.styleBridge.stylingApproach ?? "unknown"} styling)`
     );
+    console.log(
+      "  Enforcement: advisory mapping layer; accepted local rules or project lint/tests do the blocking."
+    );
     if (context.styleBridge.themeModes.length > 0) {
       console.log(`  Theme modes: ${context.styleBridge.themeModes.join(", ")}`);
     }
@@ -11605,6 +12053,8 @@ async function cmdCodifyWorkflow(args) {
       "discover-local-patterns",
       "codify-local-patterns",
       "style-bridge",
+      "map-pattern",
+      "hosted-pattern",
       "accept"
     ],
     "codify"
@@ -11652,6 +12102,48 @@ async function cmdCodifyWorkflow(args) {
   );
   const fromAudit = flagBoolean(flags, "from-audit") || flagBoolean(flags, "discover-local-patterns") || flagBoolean(flags, "codify-local-patterns");
   const wantsStyleBridge = flagBoolean(flags, "style-bridge");
+  const mapPatternSlug = flagString(flags, "map-pattern") ?? flagString(flags, "hosted-pattern");
+  if (mapPatternSlug) {
+    const registryClient = new RegistryClient({
+      cacheDir: join32(workspaceInfo.appRoot, ".decantr", "cache")
+    });
+    const candidates = await loadPatternDiscoveryCandidates(registryClient);
+    const candidate = findPatternCandidateBySlug(candidates, mapPatternSlug);
+    if (!candidate) {
+      const suggestions = rankPatternCandidates({ query: mapPatternSlug, limit: 5 }, candidates);
+      console.error(error2(`Could not find pattern "${mapPatternSlug}" to map into local law.`));
+      if (suggestions.length > 0) {
+        console.error(dim3("Closest registry patterns:"));
+        for (const suggestion of suggestions) {
+          const slug2 = suggestion.candidate.slug || suggestion.candidate.id;
+          console.error(dim3(`  ${slug2} - ${suggestion.candidate.name ?? slug2}`));
+        }
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const result = writeHostedPatternMappingProposal({
+      projectRoot: workspaceInfo.appRoot,
+      hostedPattern: hostedPatternRefFromCandidate(candidate)
+    });
+    const slug = candidate.slug || candidate.id;
+    console.log(
+      success3(
+        `${result.replacedExisting ? "Updated" : "Wrote"} hosted pattern mapping proposal: ${result.patternPath}`
+      )
+    );
+    console.log(
+      dim3(
+        `Mapped registry pattern "${slug}" into local pattern "${result.localPatternId}" as advisory Hybrid law. No source files were changed.`
+      )
+    );
+    console.log(
+      dim3(
+        `Fill in project-owned component paths, token/class recipes, variants, and exceptions, then run \`${withProject("decantr codify --accept", projectArg)}\`.`
+      )
+    );
+    return;
+  }
   const wantsLocalLaw = !wantsStyleBridge || fromAudit;
   let localResult = null;
   if (wantsLocalLaw) {
@@ -11741,13 +12233,14 @@ ${BOLD9}decantr${RESET16} \u2014 Design intelligence for AI-generated UI
 
 ${BOLD9}Usage:${RESET16}
   decantr setup [--project <path>]
+  decantr scan [--project <path>] [--json]
   decantr new <name> [--blueprint=X] [--archetype=X] [--theme=X] [--workflow=greenfield] [--adoption=decantr-css] [--telemetry]
   decantr adopt [--project <path>] [--base-url <url>] [--evidence] [--ci] [--no-packs] [--yes]
   decantr task <route> ["task summary"] [--project <path>] [--since origin/main] [--json]
   decantr verify [--project <path>] [--brownfield] [--local-patterns] [health options]
   decantr ci [--project <path>] [--workspace] [--fail-on error|warn|none]
   decantr doctor [--project <path>] [--workspace] [--json]
-  decantr codify [--from-audit] [--style-bridge] [--accept] [--project <path>]
+  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]
 
 ${BOLD9}Advanced primitives:${RESET16}
@@ -11817,6 +12310,7 @@ ${BOLD9}Init Options:${RESET16}
 
 ${BOLD9}Commands:${RESET16}
   ${cyan3("setup")}       Detect project state and recommend the right Decantr workflow
+  ${cyan3("scan")}        Read-only Brownfield reconnaissance; no files written
   ${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, local law, evidence, and changed-file impact for an AI coding assistant
@@ -11860,6 +12354,8 @@ ${BOLD9}Advanced commands:${RESET16}
 
 ${BOLD9}Examples:${RESET16}
   decantr setup
+  decantr scan
+  decantr scan --json
   decantr new my-app --blueprint=carbon-ai-portal
   decantr adopt --yes
   decantr adopt --project apps/web --yes
@@ -11871,6 +12367,7 @@ ${BOLD9}Examples:${RESET16}
   decantr ci --project apps/web
   decantr ci init --project apps/web
   decantr codify --from-audit
+  decantr codify --map-pattern hero --project apps/web
   decantr codify --accept
   decantr content check --ci --fail-on error
   decantr magic "AI chatbot with dark cyber theme \u2014 bold and futuristic"
@@ -11918,6 +12415,7 @@ ${BOLD9}Workflow Model:${RESET16}
   ${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 adopt --yes
+  ${cyan3("Brownfield preview")}     decantr scan -> decantr adopt --yes
   ${cyan3("Brownfield monorepo")}    decantr adopt --project apps/web --yes
   ${cyan3("Daily LLM work")}          decantr task <route> "<change>" -> decantr verify --brownfield --local-patterns
   ${cyan3("Project-owned law")}       decantr codify --from-audit -> edit proposal -> decantr codify --accept
@@ -11946,6 +12444,28 @@ ${BOLD9}Examples:${RESET16}
   decantr rules apply --project=apps/web
 `);
 }
+function cmdScanHelp() {
+  console.log(`
+${BOLD9}decantr scan${RESET16} \u2014 Read-only Brownfield reconnaissance
+
+${BOLD9}Usage:${RESET16}
+  decantr scan [--project <path>] [--json]
+
+${BOLD9}Options:${RESET16}
+  --project   App path inside a workspace/monorepo
+  --json      Emit the ScanReportV1 JSON to stdout
+
+${BOLD9}Behavior:${RESET16}
+  Reads local project files, detects frontend framework/routes/styling/static-hosting signals,
+  and prints a terminal report. It does not write .decantr files, install dependencies,
+  build the app, execute scripts, upload source, or open pull requests.
+
+${BOLD9}Examples:${RESET16}
+  decantr scan
+  decantr scan --project apps/web
+  decantr scan --json
+`);
+}
 function isCommandHelpRequest(args) {
   return args[1] === "help" || args.slice(1).some((arg) => arg === "--help" || arg === "-h");
 }
@@ -12171,6 +12691,7 @@ ${BOLD9}decantr codify${RESET16} \u2014 Propose or accept project-owned Brownfie
 
 ${BOLD9}Usage:${RESET16}
   decantr codify [--from-audit] [--style-bridge] [--project <path>]
+  decantr codify --map-pattern <registry-pattern-slug> [--project <path>]
   decantr codify --accept [--project <path>]
 
 ${BOLD9}Examples:${RESET16}
@@ -12178,6 +12699,7 @@ ${BOLD9}Examples:${RESET16}
   decantr codify --from-audit
   decantr codify --style-bridge
   decantr codify --from-audit --style-bridge
+  decantr codify --map-pattern hero --project apps/web
   decantr codify --accept
   decantr verify --brownfield --local-patterns
 `);
@@ -12203,6 +12725,9 @@ function printCommandHelp(command, args) {
     case "setup":
       cmdSetupHelp();
       return true;
+    case "scan":
+      cmdScanHelp();
+      return true;
     case "adopt":
       cmdAdoptHelp();
       return true;
@@ -12286,6 +12811,10 @@ async function main() {
       await cmdSetupWorkflow(args);
       break;
     }
+    case "scan": {
+      await cmdScanWorkflow(args);
+      break;
+    }
     case "adopt": {
       await cmdAdoptWorkflow(args);
       break;
@@ -12401,7 +12930,7 @@ async function main() {
       break;
     }
     case "upgrade": {
-      const { cmdUpgrade } = await import("./upgrade-7ZYWR2GH.js");
+      const { cmdUpgrade } = await import("./upgrade-WBFE6EN7.js");
       const { flags } = parseLooseArgs(args);
       const workspaceInfo = resolveWorkflowProject(flags, "upgrade");
       if (!workspaceInfo) break;
@@ -12416,7 +12945,7 @@ async function main() {
           `${YELLOW12}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET16}`
         );
       }
-      const { cmdHeal } = await import("./heal-WMSAX4LU.js");
+      const { cmdHeal } = await import("./heal-IRIDB7IZ.js");
       const { flags } = parseLooseArgs(args);
       const workspaceInfo = resolveWorkflowProject(flags, "check");
       if (!workspaceInfo) break;
@@ -12441,7 +12970,7 @@ async function main() {
         const { flags } = parseLooseArgs(args);
         const workspaceInfo = resolveWorkflowProject(flags, "health");
         if (!workspaceInfo) break;
-        const { cmdHealth, parseHealthArgs } = await import("./health-DBCUR6VQ.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-B4W7UJBZ.js");
         await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(stripProjectArgs(args)));
       } catch (e) {
         console.error(error2(e.message));
@@ -12469,7 +12998,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-L6JJQYCS.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-JOEECLI6.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error2(e.message));
@@ -12483,7 +13012,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-BCA5RCHN.js");
+        const { cmdWorkspace } = await import("./workspace-7RU77ZZW.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error2(e.message));

package/dist/{chunk-CAKQWTZS.js → chunk-MNZKOZW7.js}

@@ -1083,6 +1083,14 @@ function routeLabel(routes) {
   if (routes.length <= 6) return routes.join(", ");
   return `${routes.slice(0, 6).join(", ")} (+${routes.length - 6} more)`;
 }
+function routePathname(route) {
+  const queryIndex = route.indexOf("?");
+  if (queryIndex === -1) return route;
+  return route.slice(0, queryIndex) || "/";
+}
+function declaredRouteObserved(route, observedRoutes) {
+  return observedRoutes.has(route) || route.includes("?") && observedRoutes.has(routePathname(route));
+}
 function hasDoctrineEffect(essence, key) {
   const effects = essence.dna.constraints?.effects;
   return Boolean(effects && effects[key]);
@@ -1126,7 +1134,9 @@ function scanBrownfieldIssues(projectRoot, essence) {
   const declaredRoutes = essenceRoutes(essence);
   const observedRoutes = new Set(routes.routes.map((route) => route.path));
   const missingFromEssence = [...observedRoutes].filter((route) => !declaredRoutes.has(route));
-  const missingFromSource = [...declaredRoutes].filter((route) => !observedRoutes.has(route));
+  const missingFromSource = [...declaredRoutes].filter(
+    (route) => !declaredRouteObserved(route, observedRoutes)
+  );
   if (routes.routes.length > 0 && declaredRoutes.size === 0) {
     issues.push({
       type: "error",

package/dist/{chunk-IQZCIMQJ.js → chunk-SIDKK73N.js}

@@ -3780,14 +3780,36 @@ This project uses Decantr as a **contract and governance layer only**.
 
 Do not install \`@decantr/css\`, rewrite the styling system, or add generated Decantr CSS files unless the task explicitly changes the adoption mode. Preserve the existing framework styling conventions and map them into the Decantr context before changing implementation files.
 
-Use \`.decantr/context/scaffold-pack.md\` and the matching section/page packs to understand visual intent, shell structure, and route contracts. Implement those contracts through the project's current CSS, component library, tokens, or design-system primitives.`;
+Use \`.decantr/context/scaffold-pack.md\` and the matching section/page packs to understand visual intent, shell structure, and route contracts. Implement those contracts through the project's current CSS, component library, tokens, or design-system primitives.
+
+### Interaction Requirements
+
+Every pattern declares its required interactions in its page-pack \`Interactions\` checklist. A declared interaction must be implemented in source through the project's existing component library, CSS, or event-handler patterns.
+
+| Declared interaction | Canonical implementation shape |
+|----------------------|--------------------------------|
+| \`animate-on-mount\` | Entrance animation class or component transition on the pattern root |
+| \`stagger-children\` | Parent stagger class or animation delay driven by child index |
+| \`keyboard-navigation\` | Arrow-key/Enter/Space handlers with visible focus state |
+| \`ripple-click\` | \`d-ripple\` or an equivalent click feedback class on the interactive surface |`;
 var STYLE_BRIDGE_CSS_APPROACH = `## Styling Adoption
 
 This project uses Decantr in **style-bridge** mode.
 
 Decantr may generate lightweight bridge files such as \`src/styles/tokens.css\` and \`src/styles/decantr-bridge.css\`, but \`@decantr/css\` is not required. Treat these files as a mapping layer between Decantr context and the app's existing styling system.
 
-Preserve the current CSS framework/component library. Use Decantr tokens and bridge classes only where they clarify design intent without replacing the app's established styling conventions.`;
+Preserve the current CSS framework/component library. Use Decantr tokens and bridge classes only where they clarify design intent without replacing the app's established styling conventions.
+
+### Interaction Requirements
+
+Every pattern declares its required interactions in its page-pack \`Interactions\` checklist. A declared interaction must be implemented in source through the project's existing component library, CSS, or event-handler patterns.
+
+| Declared interaction | Canonical implementation shape |
+|----------------------|--------------------------------|
+| \`animate-on-mount\` | Entrance animation class or component transition on the pattern root |
+| \`stagger-children\` | Parent stagger class or animation delay driven by child index |
+| \`keyboard-navigation\` | Arrow-key/Enter/Space handlers with visible focus state |
+| \`ripple-click\` | \`d-ripple\` or an equivalent click feedback class on the interactive surface |`;
 function getCssApproachContent(adoptionMode) {
   if (adoptionMode === "contract-only") return CONTRACT_ONLY_CSS_APPROACH;
   if (adoptionMode === "style-bridge") return STYLE_BRIDGE_CSS_APPROACH;

package/dist/{chunk-F6SWDGKO.js → chunk-YBSBAJ3E.js}

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

package/dist/{heal-WMSAX4LU.js → heal-IRIDB7IZ.js}

@@ -1,7 +1,7 @@
 import {
   cmdHeal,
   collectCheckIssues
-} from "./chunk-CAKQWTZS.js";
+} from "./chunk-MNZKOZW7.js";
 export {
   cmdHeal,
   collectCheckIssues

package/dist/{health-DBCUR6VQ.js → health-B4W7UJBZ.js}

@@ -10,8 +10,8 @@ import {
   renderProjectHealthCiWorkflow,
   shouldFailHealth,
   writeProjectHealthCiWorkflow
-} from "./chunk-PHRVC575.js";
-import "./chunk-CAKQWTZS.js";
+} from "./chunk-3A2DLR47.js";
+import "./chunk-MNZKOZW7.js";
 export {
   cmdHealth,
   collectDesignTokenEvidence,

package/dist/index.js

@@ -1,5 +1,5 @@
-import "./chunk-SWPAAAO4.js";
-import "./chunk-IQZCIMQJ.js";
-import "./chunk-F6SWDGKO.js";
-import "./chunk-PHRVC575.js";
-import "./chunk-CAKQWTZS.js";
+import "./chunk-5MZH6XXQ.js";
+import "./chunk-SIDKK73N.js";
+import "./chunk-YBSBAJ3E.js";
+import "./chunk-3A2DLR47.js";
+import "./chunk-MNZKOZW7.js";

package/dist/{studio-L6JJQYCS.js → studio-JOEECLI6.js}

@@ -1,13 +1,13 @@
 import {
   createWorkspaceHealthReport
-} from "./chunk-F6SWDGKO.js";
+} from "./chunk-YBSBAJ3E.js";
 import {
   createProjectHealthReport
-} from "./chunk-PHRVC575.js";
+} from "./chunk-3A2DLR47.js";
 import {
   sendStudioHealthRefreshedTelemetry,
   sendStudioStartedTelemetry
-} from "./chunk-CAKQWTZS.js";
+} from "./chunk-MNZKOZW7.js";
 
 // src/commands/studio.ts
 import { readFileSync } from "fs";

package/dist/{upgrade-7ZYWR2GH.js → upgrade-WBFE6EN7.js}

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

package/dist/{workspace-BCA5RCHN.js → workspace-7RU77ZZW.js}

@@ -7,9 +7,9 @@ import {
   listWorkspaceProjects,
   parseWorkspaceArgs,
   shouldFailWorkspaceHealth
-} from "./chunk-F6SWDGKO.js";
-import "./chunk-PHRVC575.js";
-import "./chunk-CAKQWTZS.js";
+} from "./chunk-YBSBAJ3E.js";
+import "./chunk-3A2DLR47.js";
+import "./chunk-MNZKOZW7.js";
 export {
   cmdWorkspace,
   createWorkspaceHealthReport,

package/package.json

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