@decantr/cli 3.5.4 → 3.6.0

package/README.md

@@ -23,7 +23,7 @@ Use `decantr scan` when you want a zero-commit Brownfield preview. It reads loca
 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 studio` after adoption when you want a local Control Room for routes, findings, evidence, authority, and next actions. 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, `decantr resolve` when source and contract disagree, 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. Route and impact ranking use deterministic weighted traversal plus local personalized PageRank and task boosts. 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.
+In monorepos, app-scoped commands accept `--project <app-path>`. `setup` shows attach guidance before adoption and the day-two loop after adoption. Candidate discovery ranks product UI apps ahead of docs, Storybook, API, MCP helper, workbench, and package surfaces; `decantr workspace list --json` includes rank, category, score, and reason metadata so automation can explain why `apps/web`, `apps/remix`, or `apps/dashboard` was suggested first. 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.
 
 App-scoped primitives now share the same `--project` posture as the primary workflow commands. From a workspace root, `health`, `status`, `upgrade`, `add`, `remove`, `theme`, `export`, `suggest`, `magic`, `rules`, and `telemetry` target the selected app instead of the root. Task/read paths, local-law summaries, and refresh change summaries are printed as openable workspace paths. Nonexistent project paths fail immediately, and Brownfield adoption refuses component packages unless you intentionally pass `--force-package`.
@@ -103,12 +103,14 @@ Assistant rule integration is preview-first: `--assistant-bridge=preview` writes
 - 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
+- ranks monorepo app candidates with explainable metadata so product UI apps come before docs, Storybook, API, helper packages, and workbench surfaces
 - generates execution-pack context files for AI coding assistants
 - generates typed Contract graph artifacts, replayable snapshot history, graph diffs, manifests, source-file impact context, style-bridge Token nodes, behavior-obligation LocalRule nodes, and `contract-capsule.json` for agent sessions
 - audits projects against Decantr contracts
 - produces local Project Health reports, Evidence Bundles, workspace health, and a localhost Studio dashboard for end-user drift triage
 - audits local vocabulary repositories with Content Health reports for schema, reference, and quality coverage
 - searches the registry and showcase benchmark corpus
+- runs real-world corpus harnesses with timing percentiles, slow-command budgets, root-smoke/app-scoped classification, and stable failure categories
 - filters blueprints through public portfolio sets: `All`, `Featured`, `Certified`, and opt-in `Labs`
 - syncs paginated hosted vocabulary content into a full slug-keyed local cache for offline guards and context generation
 - validates, refreshes, and maintains `decantr.essence.json`
@@ -184,7 +186,7 @@ decantr showcase verification --json
 
 `decantr ci` is the blessed non-mutating automation gate. It runs the Project Health surface with adoption-mode-aware local law checks and emits a schema-backed CI report. `decantr ci init` writes root GitHub workflows or portable generic snippets using the detected package manager and pinned local CLI command instead of `@latest`; if the root manifest has not pinned Decantr yet, it prints the exact install command first.
 
-`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, accepted behavior-obligation checks, typed Contract graph freshness, and execution-pack files into a v2 `ProjectHealthReport` with status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, evidence tier, authority resolution, loop readiness, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders raw controls such as `<button>` while the project already owns a reusable primitive. The behavior-obligation slice emits `A11Y010`, `A11Y011`, `INT010`, `INT011`, `INT012`, `INT013`, and `COMP020` for high-confidence dialog/form regressions such as missing accessible names, missing label associations, missing visible destructive consequence copy, missing cancel affordances, missing submitting guards, implicit form button types, or bypassed project-owned interaction primitives. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
+`decantr health` remains the advanced project observability primitive. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, component reuse drift, accepted style bridge drift, accepted behavior-obligation checks, typed Contract graph freshness, and execution-pack files into a v2 `ProjectHealthReport` with status, score, route summary, pack summary, findings, stable diagnostic codes, typed repair IDs, evidence tier, authority resolution, loop readiness, and AI-ready remediation prompts. The graph freshness slice emits `GRAPH001` / `regenerate-typed-graph` when an attached app has missing, stale, or non-derivable `.decantr/graph` artifacts. The component reuse slice emits `COMP001` / `import-existing-component` when production source locally redeclares a common primitive that already exists as an exported reusable component, and `COMP010` / `replace-raw-control-with-local-component` when production JSX renders generic raw controls such as `<button>` or text-like `<input>` while the project already owns a reusable primitive. Specialized inputs such as file, hidden, checkbox, radio, color, range, and Dropzone `getInputProps()` controls are not treated as generic `Input` drift. The behavior-obligation slice emits `A11Y010`, `A11Y011`, `INT010`, `INT011`, `INT012`, `INT013`, and `COMP020` for high-confidence dialog/form regressions such as missing accessible names, missing label associations, missing visible destructive consequence copy, missing cancel affordances, missing submitting guards, implicit form button types, or bypassed project-owned interaction primitives. The style bridge slice emits `TOKEN010` / `replace-arbitrary-style-with-bridge-token` when production JSX, common class helpers, hardcoded inline color styles, or hardcoded visual values in CSS/module stylesheets bypass `.decantr/style-bridge.json` after it has been accepted as project-owned style authority. The baseline slice emits `VISUAL010` / `review-visual-baseline-drift` when `--since-baseline` detects changed screenshot hashes. When `.decantr/graph/graph.snapshot.json` exists, each finding is anchored to the most specific graph node Decantr can resolve, and JSON, markdown, text output, repair prompts, and Evidence Bundles carry that anchor. `decantr graph` also writes content-addressed history snapshots under `.decantr/graph/snapshots/` so repeated graph runs can be replayed across an AI edit sequence. When `.decantr/analysis.json` exists, `decantr graph` links observed routes/pages to implementation source artifacts and links exported reusable component declarations to their source files. When browser evidence writes `.decantr/evidence/visual-manifest.json`, `decantr graph` ingests it as local route/page Evidence nodes without uploading screenshots. When `.decantr/evidence/latest.json` exists, `decantr graph` can also materialize saved findings, evidence strings, graph anchors, repair IDs, and referenced repair/read target files as typed graph nodes and edges. When `.decantr/health-baseline-diff.json` exists, baseline changed files become file-level temporal evidence in the graph.
 
 ```bash
 decantr verify

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./chunk-GPGBJFMF.js";
+import "./chunk-TGVBWTDK.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-UDBPH25I.js";
-import "./chunk-EWUWVQYM.js";
-import "./chunk-4WVKE2AQ.js";
+import "./chunk-56HUEUO3.js";
+import "./chunk-WAGVDMJV.js";
+import "./chunk-24JR4ZNG.js";

package/dist/{chunk-4WVKE2AQ.js → chunk-24JR4ZNG.js}

@@ -328,7 +328,7 @@ function scanAmbientContext(projectRoot) {
 
 // src/analyzers/routes.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
-import { join as join2, relative as relative2 } from "path";
+import { extname as extname2, join as join2, relative as relative2 } from "path";
 var SKIP_DIRS2 = /* @__PURE__ */ new Set(["node_modules", ".next", ".git", "api", "_app", "_document"]);
 function shouldSkipDir2(name) {
   return name.startsWith("_") || name.startsWith(".") || SKIP_DIRS2.has(name);
@@ -460,6 +460,16 @@ var ROUTE_VARIABLE_NAMES = "(?:path|pathname|route|currentPath|currentRoute|loca
 var ROUTE_ASSET_EXTENSION_RE = /\.(?:avif|bmp|css|gif|ico|jpeg|jpg|js|json|map|mp4|pdf|png|svg|webp|woff2?)$/i;
 var JSX_ROUTE_PATH_RE = /<(?:Route|[A-Z][\w.]*Route)\b[^>]*\bpath\s*=\s*(?:"([^"]+)"|'([^']+)'|{\s*"([^"]+)"\s*}|{\s*'([^']+)'\s*}|{\s*`([^`]+)`\s*})/g;
 var OBJECT_ROUTE_PATH_RE = /\bpath\s*:\s*(?:"([^"]+)"|'([^']+)'|`([^`]+)`)/g;
+var STATIC_HTML_ENTRY_FILES = [
+  "index.html",
+  "docs/index.html",
+  "src/index.html",
+  "public/index.html",
+  "dist/index.html"
+];
+var STATIC_HTML_ROUTE_DIRS = ["demos", "examples"];
+var MAX_STATIC_HTML_ROUTES = 80;
+var MAX_STATIC_HTML_CANDIDATES = 1e3;
 function collectRouteCandidateFiles(dir, files, depth = 0) {
   if (depth > 5) return;
   let entries;
@@ -568,6 +578,65 @@ function collectRouteLiterals(pattern, content, routes) {
   }
   return count;
 }
+function htmlRouteFromFile(file) {
+  let withoutExt = file.slice(0, -extname2(file).length).replace(/\\/g, "/");
+  if (withoutExt.endsWith("/index")) withoutExt = withoutExt.slice(0, -"/index".length);
+  if (withoutExt === "index" || withoutExt === "docs" || withoutExt === "src" || withoutExt === "public" || withoutExt === "dist") {
+    return "/";
+  }
+  return `/${withoutExt.split("/").filter(Boolean).join("/")}` || "/";
+}
+function collectStaticHtmlFiles(dir, projectRoot, files, depth = 0) {
+  if (depth > 5 || files.length >= MAX_STATIC_HTML_CANDIDATES) return;
+  let entries;
+  try {
+    entries = readdirSync2(dir).sort();
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (files.length >= MAX_STATIC_HTML_CANDIDATES) return;
+    if (entry.startsWith(".") || entry === "node_modules") continue;
+    const fullPath = join2(dir, entry);
+    try {
+      const stat = statSync2(fullPath);
+      if (stat.isDirectory()) {
+        collectStaticHtmlFiles(fullPath, projectRoot, files, depth + 1);
+      } else if (stat.isFile() && /\.(?:html|htm)$/i.test(entry)) {
+        files.push(relative2(projectRoot, fullPath).replace(/\\/g, "/"));
+      }
+    } catch {
+    }
+  }
+}
+function staticHtmlFilePriority(file) {
+  const base = file.split("/").pop()?.toLowerCase();
+  if (base === "index.html" || base === "index.htm") return 0;
+  if (base === "default.html" || base === "default.htm") return 1;
+  return 2;
+}
+function scanStaticHtmlRoutes(projectRoot) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const file of STATIC_HTML_ENTRY_FILES) {
+    if (!existsSync2(join2(projectRoot, file))) continue;
+    routes.set("/", { path: "/", file, hasLayout: false });
+    break;
+  }
+  for (const dir of STATIC_HTML_ROUTE_DIRS) {
+    const fullDir = join2(projectRoot, dir);
+    if (!existsSync2(fullDir)) continue;
+    const files = [];
+    collectStaticHtmlFiles(fullDir, projectRoot, files);
+    for (const file of files.sort(
+      (a, b) => staticHtmlFilePriority(a) - staticHtmlFilePriority(b) || a.localeCompare(b)
+    )) {
+      const routePath = htmlRouteFromFile(file);
+      if (routes.has(routePath)) continue;
+      routes.set(routePath, { path: routePath, file, hasLayout: false });
+    }
+  }
+  return [...routes.values()].slice(0, MAX_STATIC_HTML_ROUTES);
+}
 function detectPathnameBranchRoutes(content) {
   const routes = /* @__PURE__ */ new Set();
   const comparison = new RegExp(
@@ -739,6 +808,10 @@ function scanRoutes(projectRoot) {
   if (reactRouterRoutes.length > 0) {
     return { strategy: "react-router", routes: reactRouterRoutes };
   }
+  const staticHtmlRoutes = scanStaticHtmlRoutes(projectRoot);
+  if (staticHtmlRoutes.length > 0) {
+    return { strategy: "static-html", routes: staticHtmlRoutes };
+  }
   return { strategy: "none", routes: [] };
 }
 
@@ -1534,7 +1607,7 @@ function buildGuardRegistryContext(projectRoot = process.cwd()) {
 
 // src/lib/scan-interactions.ts
 import { existsSync as existsSync8, readdirSync as readdirSync6, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
-import { extname as extname2, join as join8, relative as relative4 } from "path";
+import { extname as extname3, join as join8, relative as relative4 } from "path";
 import { verifyInteractionsInSource } from "@decantr/verifier";
 var SCAN_EXTENSIONS = /* @__PURE__ */ new Set([".tsx", ".jsx", ".ts", ".js", ".html", ".mdx"]);
 var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
@@ -1586,7 +1659,7 @@ function walkSourceTree(rootDir) {
       const relativePath = relative4(rootDir, fullPath) || entry;
       if (s.isDirectory()) {
         walk2(fullPath);
-      } else if (s.isFile() && SCAN_EXTENSIONS.has(extname2(entry))) {
+      } else if (s.isFile() && SCAN_EXTENSIONS.has(extname3(entry))) {
         if (s.size > MAX_FILE_SIZE) continue;
         if (isNonUiInteractionSource(relativePath)) continue;
         try {

package/dist/{chunk-UDBPH25I.js → chunk-56HUEUO3.js}

@@ -1,7 +1,7 @@
 import {
   createProjectHealthReport,
-  listWorkspaceAppCandidates
-} from "./chunk-EWUWVQYM.js";
+  listWorkspaceAppCandidateDetails
+} from "./chunk-WAGVDMJV.js";
 
 // src/commands/workspace.ts
 import { execFileSync } from "child_process";
@@ -97,10 +97,14 @@ function listWorkspaceProjects(root = process.cwd()) {
 }
 function listWorkspaceCandidates(root = process.cwd(), projects = listWorkspaceProjects(root)) {
   const attached = new Set(projects.map((project) => project.path));
-  return listWorkspaceAppCandidates(root).map((path) => ({
-    path,
-    attached: attached.has(path),
-    suggestedAdoptCommand: `decantr adopt --project ${path} --yes`
+  return listWorkspaceAppCandidateDetails(root).map((candidate, index) => ({
+    path: candidate.path,
+    attached: attached.has(candidate.path),
+    suggestedAdoptCommand: `decantr adopt --project ${candidate.path} --yes`,
+    rank: index + 1,
+    score: candidate.score,
+    category: candidate.category,
+    reason: candidate.reason
   }));
 }
 function changedPaths(root, since) {
@@ -342,7 +346,9 @@ async function cmdWorkspace(workspaceRoot = process.cwd(), args = ["workspace"])
       console.log("App candidates:");
       for (const candidate of candidates) {
         const status = candidate.attached ? `${GREEN}attached${RESET}` : `${YELLOW}unattached${RESET}`;
-        console.log(`  ${candidate.path} ${DIM}${status}${RESET}`);
+        console.log(
+          `  #${candidate.rank} ${candidate.path} ${DIM}${status} \xB7 ${candidate.category} \xB7 score ${candidate.score}${RESET}`
+        );
       }
     }
     if (unattachedCandidates.length > 0) {

package/dist/{chunk-GPGBJFMF.js → chunk-TGVBWTDK.js}

@@ -22,7 +22,7 @@ import {
   listWorkspaceCandidates,
   listWorkspaceProjects,
   shouldFailWorkspaceHealth
-} from "./chunk-UDBPH25I.js";
+} from "./chunk-56HUEUO3.js";
 import {
   acceptBrownfieldLocalLaw,
   acceptStyleBridge,
@@ -52,7 +52,7 @@ import {
   writeBrownfieldCodifyProposal,
   writeHostedPatternMappingProposal,
   writeStyleBridgeProposal
-} from "./chunk-EWUWVQYM.js";
+} from "./chunk-WAGVDMJV.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -69,7 +69,7 @@ import {
   sendCliCommandTelemetry,
   sendNewProjectCompletedTelemetry,
   writeDoctrineMap
-} from "./chunk-4WVKE2AQ.js";
+} from "./chunk-24JR4ZNG.js";
 
 // src/index.ts
 import { existsSync as existsSync29, mkdirSync as mkdirSync16, readdirSync as readdirSync8, readFileSync as readFileSync22, writeFileSync as writeFileSync19 } from "fs";
@@ -2940,6 +2940,21 @@ var RULE_FILES = [
   ".github/copilot-instructions.md",
   ".windsurfrules"
 ];
+var STATIC_HTML_ENTRY_FILES = [
+  "index.html",
+  "docs/index.html",
+  "src/index.html",
+  "public/index.html",
+  "dist/index.html"
+];
+var STATIC_HTML_ROUTE_DIRS = ["demos", "examples"];
+function hasAnyFile(projectRoot, relPaths) {
+  return relPaths.some((relPath) => existsSync10(join12(projectRoot, relPath)));
+}
+function hasStaticHtmlSurface(projectRoot) {
+  if (hasAnyFile(projectRoot, STATIC_HTML_ENTRY_FILES)) return true;
+  return STATIC_HTML_ROUTE_DIRS.some((dir) => existsSync10(join12(projectRoot, dir, "index.html")));
+}
 function readPackageJson(dir) {
   const path = join12(dir, "package.json");
   if (!existsSync10(path)) return null;
@@ -3045,8 +3060,8 @@ function detectProject(projectRoot = process.cwd()) {
     } catch {
     }
   }
-  if (result.framework === "unknown" && !existsSync10(packageJsonPath)) {
-    if (existsSync10(join12(projectRoot, "index.html"))) {
+  if (result.framework === "unknown") {
+    if (hasStaticHtmlSurface(projectRoot)) {
       result.framework = "html";
     }
   }
@@ -4251,7 +4266,7 @@ function rel(root, path) {
   const value = relative4(root, path).replace(/\\/g, "/");
   return value || ".";
 }
-function hasAnyFile(dir, names) {
+function hasAnyFile2(dir, names) {
   for (const name of names) {
     const path = join17(dir, name);
     if (existsSync15(path)) return name;
@@ -4280,7 +4295,7 @@ function detectDesignAuthority(workspaceRoot, appRoot) {
   }
   for (const root of [appRoot, workspaceRoot]) {
     const label = root === appRoot ? "app" : "workspace";
-    const tailwind = hasAnyFile(root, [
+    const tailwind = hasAnyFile2(root, [
       "tailwind.config.js",
       "tailwind.config.ts",
       "tailwind.config.mjs",
@@ -11078,7 +11093,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-WO2BQYIC.js");
+    const { cmdHealth } = await import("./health-KUPBUU3B.js");
     await cmdHealth(projectRoot, {
       browser: runBrowser,
       browserBaseUrl: baseUrl,
@@ -11152,7 +11167,7 @@ async function cmdVerifyWorkflow(args) {
     return;
   }
   if (workspaceMode) {
-    const { cmdWorkspace } = await import("./workspace-G6PN53XI.js");
+    const { cmdWorkspace } = await import("./workspace-QAZ3F4VT.js");
     await cmdWorkspace(process.cwd(), ["workspace", "health", ...withoutWorkflowOnlyFlags(args)]);
     return;
   }
@@ -11185,7 +11200,7 @@ async function cmdVerifyWorkflow(args) {
   }
   let guardExitCode;
   if (brownfield) {
-    const { cmdHeal, collectCheckIssues } = await import("./heal-4BQCO4ST.js");
+    const { cmdHeal, collectCheckIssues } = await import("./heal-2FK63EQE.js");
     if (quietOutput) {
       const result = collectCheckIssues(workspaceInfo.appRoot, { brownfield: true });
       guardExitCode = result.issues.some((issue) => issue.type === "error") ? 1 : void 0;
@@ -11195,7 +11210,7 @@ async function cmdVerifyWorkflow(args) {
       process.exitCode = void 0;
     }
   }
-  const { cmdHealth, parseHealthArgs } = await import("./health-WO2BQYIC.js");
+  const { cmdHealth, parseHealthArgs } = await import("./health-KUPBUU3B.js");
   await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(healthArgs));
   if (localPatterns) {
     const validation = validateLocalLaw(workspaceInfo.appRoot);
@@ -12832,7 +12847,7 @@ async function main() {
           `${YELLOW13}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET17}`
         );
       }
-      const { cmdHeal } = await import("./heal-4BQCO4ST.js");
+      const { cmdHeal } = await import("./heal-2FK63EQE.js");
       const { flags } = parseLooseArgs(args);
       const workspaceInfo = resolveWorkflowProject(flags, "check");
       if (!workspaceInfo) break;
@@ -12857,7 +12872,7 @@ async function main() {
         const { flags } = parseLooseArgs(args);
         const workspaceInfo = resolveWorkflowProject(flags, "health");
         if (!workspaceInfo) break;
-        const { cmdHealth, parseHealthArgs } = await import("./health-WO2BQYIC.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-KUPBUU3B.js");
         await cmdHealth(workspaceInfo.appRoot, parseHealthArgs(stripProjectArgs(args)));
       } catch (e) {
         console.error(error2(e.message));
@@ -12885,7 +12900,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-TXFV3PDM.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-J6Z3AUAR.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error2(e.message));
@@ -12899,7 +12914,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-G6PN53XI.js");
+        const { cmdWorkspace } = await import("./workspace-QAZ3F4VT.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error2(e.message));

package/dist/{chunk-EWUWVQYM.js → chunk-WAGVDMJV.js}

@@ -3,7 +3,7 @@ import {
   sendProjectHealthCiFailedTelemetry,
   sendProjectHealthPromptTelemetry,
   sendProjectHealthReportTelemetry
-} from "./chunk-4WVKE2AQ.js";
+} from "./chunk-24JR4ZNG.js";
 
 // src/commands/health.ts
 import { execFileSync as execFileSync2 } from "child_process";
@@ -60,7 +60,7 @@ function looksLikeApp(dir, options = {}) {
   const pkg = readPackageJson(dir);
   const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
   const hasFrontendDependency = Boolean(
-    deps.react || deps["react-dom"] || deps.next || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt
+    deps.react || deps["react-dom"] || deps.next || deps["@remix-run/react"] || deps["@remix-run/dev"] || deps.vue || deps.svelte || deps["@angular/core"] || deps.astro || deps.nuxt || deps["solid-js"]
   );
   const hasServerOnlyDependency = Boolean(
     deps.hono || deps.express || deps.fastify || deps.koa || deps["@hapi/hapi"]
@@ -76,7 +76,86 @@ function looksLikeApp(dir, options = {}) {
   if (!allowPackageDeps) return false;
   return hasFrontendDependency;
 }
-function listWorkspaceApps(workspaceRoot) {
+function hasConfig(dir) {
+  return existsSync(join(dir, "next.config.js")) || existsSync(join(dir, "next.config.ts")) || existsSync(join(dir, "next.config.mjs")) || existsSync(join(dir, "vite.config.ts")) || existsSync(join(dir, "vite.config.js")) || existsSync(join(dir, "angular.json")) || existsSync(join(dir, "svelte.config.js")) || existsSync(join(dir, "svelte.config.ts")) || existsSync(join(dir, "astro.config.mjs")) || existsSync(join(dir, "remix.config.js")) || existsSync(join(dir, "remix.config.mjs")) || existsSync(join(dir, "remix.config.ts"));
+}
+function hasUiSource(dir) {
+  return existsSync(join(dir, "src")) || existsSync(join(dir, "app")) || existsSync(join(dir, "pages"));
+}
+function rankWorkspaceAppCandidate(workspaceRoot, base, name) {
+  const path = `${base}/${name}`;
+  const dir = join(workspaceRoot, path);
+  const pkg = readPackageJson(dir);
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const lowerPath = path.toLowerCase();
+  const reasons = [];
+  let score = base === "apps" ? 25 : -20;
+  if (base === "apps") reasons.push("under apps/");
+  if (base === "packages") reasons.push("under packages/");
+  const frontendDeps = [
+    "react",
+    "react-dom",
+    "next",
+    "@remix-run/react",
+    "@remix-run/dev",
+    "vue",
+    "svelte",
+    "@angular/core",
+    "astro",
+    "nuxt",
+    "solid-js"
+  ].filter((dep) => deps[dep]);
+  if (frontendDeps.length > 0) {
+    score += 30;
+    reasons.push(`frontend deps: ${frontendDeps.slice(0, 3).join(", ")}`);
+  }
+  if (hasConfig(dir)) {
+    score += 20;
+    reasons.push("frontend config");
+  }
+  if (hasUiSource(dir)) {
+    score += 10;
+    reasons.push("UI source tree");
+  }
+  if (/\b(web|app|dashboard|remix|client|frontend|site|portal)\b/u.test(lowerPath)) {
+    score += 25;
+    reasons.push("product-app name");
+  }
+  if (/\b(marketing|admin|console)\b/u.test(lowerPath)) {
+    score += 10;
+    reasons.push("taskable app surface");
+  }
+  const negativeSignals = [
+    [/\b(docs?|documentation)\b/u, 40, "docs surface"],
+    [/\bstorybook\b/u, 45, "Storybook surface"],
+    [/\b(api|server|backend|worker|queue)\b/u, 35, "server/API surface"],
+    [/\bmcp\b/u, 40, "MCP/helper surface"],
+    [/\b(workbench|playground|sandbox|example|demo)\b/u, 30, "workbench/demo surface"],
+    [
+      /\b(design-system|components?|ui|tokens?|theme|config|eslint|tsconfig)\b/u,
+      30,
+      "library/config surface"
+    ]
+  ];
+  for (const [pattern, penalty, reason] of negativeSignals) {
+    if (!pattern.test(lowerPath)) continue;
+    score -= penalty;
+    reasons.push(reason);
+  }
+  const serverDeps = ["hono", "express", "fastify", "koa", "@hapi/hapi"].filter((dep) => deps[dep]);
+  if (serverDeps.length > 0 && frontendDeps.length === 0) {
+    score -= 35;
+    reasons.push(`server-only deps: ${serverDeps.slice(0, 2).join(", ")}`);
+  }
+  const category = score >= 65 ? "product-ui" : score >= 30 ? "supporting-ui" : "low-confidence-ui";
+  return {
+    path,
+    score,
+    category,
+    reason: reasons.join("; ") || "filesystem candidate"
+  };
+}
+function listWorkspaceAppDetails(workspaceRoot) {
   const candidates = [];
   for (const base of ["apps", "packages"]) {
     const baseDir = join(workspaceRoot, base);
@@ -88,14 +167,21 @@ function listWorkspaceApps(workspaceRoot) {
         allowSourceDirs: base === "apps",
         allowPackageDeps: base === "apps"
       })) {
-        candidates.push(`${base}/${entry.name}`);
+        const ranked = rankWorkspaceAppCandidate(
+          workspaceRoot,
+          base,
+          entry.name
+        );
+        if (ranked.score <= 0) continue;
+        if (base === "packages" && ranked.category !== "product-ui") continue;
+        candidates.push(ranked);
       }
     }
   }
-  return candidates.sort();
+  return candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
 }
-function listWorkspaceAppCandidates(workspaceRoot) {
-  return listWorkspaceApps(resolve(workspaceRoot));
+function listWorkspaceAppCandidateDetails(workspaceRoot) {
+  return listWorkspaceAppDetails(resolve(workspaceRoot));
 }
 function resolveWorkspaceInfo(cwd, projectArg) {
   const absoluteCwd = resolve(cwd);
@@ -103,7 +189,8 @@ function resolveWorkspaceInfo(cwd, projectArg) {
     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 appCandidateDetails = listWorkspaceAppDetails(workspaceRoot);
+  const appCandidates = appCandidateDetails.map((candidate) => candidate.path);
   const projectScope = workspaceRoot !== appRoot || appCandidates.length > 0 ? "workspace-app" : "single-app";
   const requiresProjectSelection = !projectArg && workspaceRoot === absoluteCwd && appCandidates.length > 0;
   return {
@@ -112,6 +199,7 @@ function resolveWorkspaceInfo(cwd, projectArg) {
     appRoot,
     projectScope,
     appCandidates,
+    appCandidateDetails,
     requiresProjectSelection
   };
 }
@@ -5438,7 +5526,7 @@ export {
   acceptStyleBridge,
   createStyleBridgeTaskSummary,
   styleBridgeMatches,
-  listWorkspaceAppCandidates,
+  listWorkspaceAppCandidateDetails,
   resolveWorkspaceInfo,
   buildGraphArtifacts,
   cmdGraphHelp,

package/dist/{heal-4BQCO4ST.js → heal-2FK63EQE.js}

@@ -1,7 +1,7 @@
 import {
   cmdHeal,
   collectCheckIssues
-} from "./chunk-4WVKE2AQ.js";
+} from "./chunk-24JR4ZNG.js";
 export {
   cmdHeal,
   collectCheckIssues

package/dist/{health-WO2BQYIC.js → health-KUPBUU3B.js}

@@ -13,8 +13,8 @@ import {
   renderProjectHealthCiWorkflow,
   shouldFailHealth,
   writeProjectHealthCiWorkflow
-} from "./chunk-EWUWVQYM.js";
-import "./chunk-4WVKE2AQ.js";
+} from "./chunk-WAGVDMJV.js";
+import "./chunk-24JR4ZNG.js";
 export {
   cmdHealth,
   collectDesignTokenEvidence,

package/dist/index.js

@@ -1,5 +1,5 @@
-import "./chunk-GPGBJFMF.js";
+import "./chunk-TGVBWTDK.js";
 import "./chunk-SIDKK73N.js";
-import "./chunk-UDBPH25I.js";
-import "./chunk-EWUWVQYM.js";
-import "./chunk-4WVKE2AQ.js";
+import "./chunk-56HUEUO3.js";
+import "./chunk-WAGVDMJV.js";
+import "./chunk-24JR4ZNG.js";

package/dist/{studio-TXFV3PDM.js → studio-J6Z3AUAR.js}

@@ -1,13 +1,13 @@
 import {
   createWorkspaceHealthReport
-} from "./chunk-UDBPH25I.js";
+} from "./chunk-56HUEUO3.js";
 import {
   createProjectHealthReport
-} from "./chunk-EWUWVQYM.js";
+} from "./chunk-WAGVDMJV.js";
 import {
   sendStudioHealthRefreshedTelemetry,
   sendStudioStartedTelemetry
-} from "./chunk-4WVKE2AQ.js";
+} from "./chunk-24JR4ZNG.js";
 
 // src/commands/studio.ts
 import { existsSync, readFileSync } from "fs";

package/dist/{workspace-G6PN53XI.js → workspace-QAZ3F4VT.js}

@@ -7,9 +7,9 @@ import {
   listWorkspaceProjects,
   parseWorkspaceArgs,
   shouldFailWorkspaceHealth
-} from "./chunk-UDBPH25I.js";
-import "./chunk-EWUWVQYM.js";
-import "./chunk-4WVKE2AQ.js";
+} from "./chunk-56HUEUO3.js";
+import "./chunk-WAGVDMJV.js";
+import "./chunk-24JR4ZNG.js";
 export {
   cmdWorkspace,
   createWorkspaceHealthReport,

package/package.json

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