@decantr/cli 2.5.0 → 2.6.0

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

@@ -20,6 +20,8 @@ import {
   createDoctrineMap,
   getCliTelemetryIdentityStatus,
   isOptedIn,
+  loadBundledContentItem,
+  loadBundledContentList,
   optIn,
   scanAmbientContext,
   scanProjectInteractions,
@@ -29,11 +31,11 @@ import {
   sendCliCommandTelemetry,
   sendNewProjectCompletedTelemetry,
   writeDoctrineMap
-} from "./chunk-IEW2QFYI.js";
+} from "./chunk-KT2ROK2D.js";
 
 // src/index.ts
-import { existsSync as existsSync26, mkdirSync as mkdirSync12, readdirSync as readdirSync6, readFileSync as readFileSync19, writeFileSync as writeFileSync15 } from "fs";
-import { basename as basename2, dirname as dirname4, isAbsolute, join as join27, resolve as resolve4 } from "path";
+import { existsSync as existsSync27, mkdirSync as mkdirSync13, readdirSync as readdirSync7, readFileSync as readFileSync20, writeFileSync as writeFileSync16 } from "fs";
+import { basename as basename2, dirname as dirname4, isAbsolute, join as join28, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { evaluateGuard, isV4 as isV47, validateEssence as validateEssence2 } from "@decantr/essence-spec";
 import {
@@ -45,7 +47,9 @@ import {
   isContentType as isGetContentType,
   isPublicBlueprintSet,
   API_CONTENT_TYPES as LIST_CONTENT_TYPES,
-  RegistryAPIClient as RegistryAPIClient3
+  patternToDiscoveryCandidate,
+  RegistryAPIClient as RegistryAPIClient3,
+  rankPatternCandidates
 } from "@decantr/registry";
 import {
   auditProject,
@@ -1819,8 +1823,8 @@ async function cmdAddFeature(feature, args, projectRoot = process.cwd()) {
 }
 
 // src/commands/analyze.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, writeFileSync as writeFileSync6 } from "fs";
-import { join as join12 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7 } from "fs";
+import { join as join13 } from "path";
 
 // src/analyzers/components.ts
 import { existsSync as existsSync5, readdirSync, statSync as statSync2 } from "fs";
@@ -2346,9 +2350,262 @@ function scanLayout(projectRoot) {
   };
 }
 
+// src/brownfield-intelligence.ts
+import {
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync5,
+  readdirSync as readdirSync4,
+  readFileSync as readFileSync8,
+  statSync as statSync4,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { join as join10, relative } from "path";
+var CSS_SCAN_DIRS = ["src", "app", "styles", "assets"];
+var CSS_MAX_FILE_SIZE = 1024 * 1024;
+function collectCssFiles(projectRoot) {
+  const files = [];
+  const seen = /* @__PURE__ */ new Set();
+  const skip = /* @__PURE__ */ new Set(["node_modules", ".git", ".next", ".decantr", "dist", "build", "coverage"]);
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync4(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (skip.has(entry.name)) continue;
+      const full = join10(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith(".css")) continue;
+      try {
+        if (statSync4(full).size > CSS_MAX_FILE_SIZE) continue;
+      } catch {
+        continue;
+      }
+      if (!seen.has(full)) {
+        files.push(full);
+        seen.add(full);
+      }
+    }
+  };
+  for (const dir of CSS_SCAN_DIRS.map((segment) => join10(projectRoot, segment))) {
+    if (existsSync9(dir)) walk(dir);
+  }
+  return files.sort();
+}
+function selectorFromMatch(raw) {
+  return raw.replace(/\s+/g, " ").trim().slice(0, 120);
+}
+function createThemeInventory(projectRoot, styling) {
+  const files = collectCssFiles(projectRoot);
+  const variantMap = /* @__PURE__ */ new Map();
+  const notes = [];
+  const ensureVariant = (id, selector, evidence) => {
+    const existing = variantMap.get(id) ?? {
+      id,
+      selectors: [],
+      tokenCount: 0,
+      colorTokenCount: 0,
+      evidence: []
+    };
+    if (!existing.selectors.includes(selector)) existing.selectors.push(selector);
+    if (!existing.evidence.includes(evidence)) existing.evidence.push(evidence);
+    variantMap.set(id, existing);
+  };
+  for (const file of files) {
+    let content = "";
+    try {
+      content = readFileSync8(file, "utf-8");
+    } catch {
+      continue;
+    }
+    const rel = relative(projectRoot, file).replace(/\\/g, "/");
+    const selectorRegex = /((?:\.[\w-]*dark[\w-]*|\[data-theme=["'][^"']+["']\]|\[data-theme=[^\]]+\]|\[data-[\w-]*theme=["'][^"']+["']\]|html\.dark|:root|\.theme-[\w-]+)[^{]*)\{/g;
+    for (const match of content.matchAll(selectorRegex)) {
+      const selector = selectorFromMatch(match[1] ?? "");
+      if (!selector) continue;
+      let id = "base";
+      const dataTheme = selector.match(/data-(?:[\w-]*theme|theme)=["']?([^"'\]\s]+)/i);
+      const themeClass = selector.match(/\.theme-([a-z0-9-]+)/i);
+      if (/dark/i.test(selector)) id = "dark";
+      if (dataTheme?.[1]) id = dataTheme[1].toLowerCase();
+      if (themeClass?.[1]) id = themeClass[1].toLowerCase();
+      if (selector.includes(":root")) id = "base";
+      ensureVariant(id, selector, rel);
+    }
+    for (const [id, entry] of variantMap) {
+      const scopedSelectors = entry.selectors.filter((selector) => content.includes(selector));
+      if (scopedSelectors.length === 0) continue;
+      const scopedText = scopedSelectors.map((selector) => {
+        const idx = content.indexOf(selector);
+        return idx >= 0 ? content.slice(idx, Math.min(content.length, idx + 3e3)) : "";
+      }).join("\n");
+      const tokens = [...scopedText.matchAll(/--[\w-]+\s*:/g)].length;
+      const colors = [
+        ...scopedText.matchAll(
+          /--[\w-]*(?:color|bg|fg|surface|border|accent|primary|secondary)[\w-]*\s*:/gi
+        )
+      ].length;
+      variantMap.set(id, {
+        ...entry,
+        tokenCount: Math.max(entry.tokenCount, tokens),
+        colorTokenCount: Math.max(entry.colorTokenCount, colors)
+      });
+    }
+  }
+  if (variantMap.size === 0) {
+    ensureVariant("base", ":root or existing component styles", "detected styling inventory");
+    notes.push(
+      "No explicit theme selectors were found; Decantr will treat the current UI as the existing-app authority."
+    );
+  }
+  if (styling.darkMode && !variantMap.has("dark")) {
+    ensureVariant("dark", "dark mode signal", "styling analyzer");
+  }
+  const variants = [...variantMap.values()].sort((a, b) => a.id.localeCompare(b.id));
+  const modes = variants.map((variant) => variant.id);
+  if (variants.length > 2) {
+    notes.push(
+      "Multiple theme variants were observed. Essence V4 remains unchanged; variants are reported here for task-time context."
+    );
+  }
+  return {
+    version: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    localOnly: true,
+    stylingApproach: styling.approach,
+    darkModeDetected: styling.darkMode,
+    modes,
+    variants,
+    tokens: {
+      cssVariables: styling.cssVariables,
+      colors: styling.colors
+    },
+    notes
+  };
+}
+function readScreenshotEvidence(projectRoot) {
+  const dir = join10(projectRoot, ".decantr", "evidence", "screenshots");
+  if (!existsSync9(dir)) return [];
+  try {
+    return readdirSync4(dir).filter((file) => file.endsWith(".png") || file.endsWith(".jpg") || file.endsWith(".jpeg")).map((file) => `.decantr/evidence/screenshots/${file}`).sort();
+  } catch {
+    return [];
+  }
+}
+function backlogItems(input) {
+  const items = [
+    "Confirm the observed personality and visual target in `.decantr/observed-essence.proposal.json` before asking an AI agent to add net-new UI.",
+    "Enrich high-traffic routes with precise directives: states, interactions, shared components, responsive behavior, and accessibility expectations.",
+    "Run `decantr health --browser --base-url <url> --evidence` after the app is running to attach local screenshot evidence."
+  ];
+  if (input.routes.routes.length > 6) {
+    items.push(
+      "Group mature-app routes into stable zones so future tasks can load focused page or section context instead of the whole app."
+    );
+  }
+  if (input.components.componentCount > 10) {
+    items.push("Identify shared component surfaces and record where reuse beats duplication.");
+  }
+  if (input.themeInventory.variants.length > 1) {
+    items.push(
+      "Document which routes use each observed theme variant; do not promote variants into Essence until the contract boundary is reviewed."
+    );
+  }
+  if (input.features.detected.includes("chat") || input.features.detected.includes("file-upload")) {
+    items.push(
+      "Enrich AI/chat/upload flows with concrete interaction evidence so agents do not replace product behavior with generic patterns."
+    );
+  }
+  if (input.styling.approach !== "decantr-css") {
+    items.push(
+      `Keep Brownfield implementation in the existing ${input.styling.approach} styling system unless adoption mode changes.`
+    );
+  }
+  if (input.layout.shellPattern === "main-only" && input.routes.routes.length > 3) {
+    items.push(
+      "Review shell ownership; the analyzer did not find a clear nav/sidebar/footer structure for a multi-route app."
+    );
+  }
+  return items;
+}
+function renderBacklog(items) {
+  return [
+    "# Decantr Brownfield Enrichment Backlog",
+    "",
+    "Use this checklist to turn the first Brownfield attach pass into durable task-time context.",
+    "",
+    ...items.map((item) => `- [ ] ${item}`),
+    ""
+  ].join("\n");
+}
+function writeBrownfieldIntelligenceArtifacts(input) {
+  const decantrDir = join10(input.projectRoot, ".decantr");
+  mkdirSync5(decantrDir, { recursive: true });
+  const themeInventory = createThemeInventory(input.projectRoot, input.styling);
+  const screenshots = readScreenshotEvidence(input.projectRoot);
+  const backlog = backlogItems({ ...input, themeInventory });
+  const intelligence = {
+    version: 1,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    localOnly: true,
+    workflow: "brownfield-attach",
+    essenceVersion: "4.0.0",
+    project: {
+      framework: input.project.framework,
+      frameworkVersion: input.project.version ?? null,
+      packageManager: input.project.packageManager,
+      hasTypeScript: input.project.hasTypeScript,
+      hasTailwind: input.project.hasTailwind,
+      existingRuleFiles: input.project.existingRuleFiles
+    },
+    routeIntelligence: {
+      strategy: input.routes.strategy,
+      routeCount: input.routes.routes.length,
+      routes: input.routes.routes.map((route) => ({
+        path: route.path,
+        file: route.file,
+        hasLayout: route.hasLayout
+      }))
+    },
+    componentSurface: {
+      pageCount: input.components.pageCount,
+      componentCount: input.components.componentCount,
+      directories: input.components.directories
+    },
+    styling: {
+      approach: input.styling.approach,
+      configFile: input.styling.configFile ?? null,
+      darkMode: input.styling.darkMode,
+      cssVariableCount: input.styling.cssVariables.length,
+      themeInventoryPath: ".decantr/theme-inventory.json"
+    },
+    layout: input.layout,
+    features: input.features,
+    dependencies: input.dependencies,
+    evidence: {
+      screenshotsLocalOnly: true,
+      screenshots,
+      visualManifestPath: existsSync9(join10(decantrDir, "evidence", "visual-manifest.json")) ? ".decantr/evidence/visual-manifest.json" : null
+    },
+    recommendedNextSteps: backlog
+  };
+  const intelligencePath = join10(decantrDir, "brownfield-intelligence.json");
+  const themeInventoryPath = join10(decantrDir, "theme-inventory.json");
+  const backlogPath = join10(decantrDir, "enrichment-backlog.md");
+  writeFileSync6(intelligencePath, JSON.stringify(intelligence, null, 2) + "\n", "utf-8");
+  writeFileSync6(themeInventoryPath, JSON.stringify(themeInventory, null, 2) + "\n", "utf-8");
+  writeFileSync6(backlogPath, renderBacklog(backlog), "utf-8");
+  return { intelligencePath, themeInventoryPath, backlogPath };
+}
+
 // src/detect.ts
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
+import { join as join11 } from "path";
 var RULE_FILES = [
   "CLAUDE.md",
   ".claude/rules",
@@ -2370,52 +2627,52 @@ function detectProject(projectRoot = process.cwd()) {
     existingEssence: false,
     projectRoot
   };
-  result.existingEssence = existsSync9(join10(projectRoot, "decantr.essence.json"));
+  result.existingEssence = existsSync10(join11(projectRoot, "decantr.essence.json"));
   for (const ruleFile of RULE_FILES) {
-    if (existsSync9(join10(projectRoot, ruleFile))) {
+    if (existsSync10(join11(projectRoot, ruleFile))) {
       result.existingRuleFiles.push(ruleFile);
     }
   }
-  if (existsSync9(join10(projectRoot, "pnpm-lock.yaml"))) {
+  if (existsSync10(join11(projectRoot, "pnpm-lock.yaml"))) {
     result.packageManager = "pnpm";
-  } else if (existsSync9(join10(projectRoot, "yarn.lock"))) {
+  } else if (existsSync10(join11(projectRoot, "yarn.lock"))) {
     result.packageManager = "yarn";
-  } else if (existsSync9(join10(projectRoot, "bun.lockb"))) {
+  } else if (existsSync10(join11(projectRoot, "bun.lockb"))) {
     result.packageManager = "bun";
-  } else if (existsSync9(join10(projectRoot, "package-lock.json"))) {
+  } else if (existsSync10(join11(projectRoot, "package-lock.json"))) {
     result.packageManager = "npm";
   }
-  result.hasTypeScript = existsSync9(join10(projectRoot, "tsconfig.json"));
-  result.hasTailwind = existsSync9(join10(projectRoot, "tailwind.config.js")) || existsSync9(join10(projectRoot, "tailwind.config.ts")) || existsSync9(join10(projectRoot, "tailwind.config.mjs")) || existsSync9(join10(projectRoot, "tailwind.config.cjs"));
-  if (existsSync9(join10(projectRoot, "next.config.js")) || existsSync9(join10(projectRoot, "next.config.ts")) || existsSync9(join10(projectRoot, "next.config.mjs"))) {
+  result.hasTypeScript = existsSync10(join11(projectRoot, "tsconfig.json"));
+  result.hasTailwind = existsSync10(join11(projectRoot, "tailwind.config.js")) || existsSync10(join11(projectRoot, "tailwind.config.ts")) || existsSync10(join11(projectRoot, "tailwind.config.mjs")) || existsSync10(join11(projectRoot, "tailwind.config.cjs"));
+  if (existsSync10(join11(projectRoot, "next.config.js")) || existsSync10(join11(projectRoot, "next.config.ts")) || existsSync10(join11(projectRoot, "next.config.mjs"))) {
     result.framework = "nextjs";
     result.version = getPackageVersion(projectRoot, "next");
     return result;
   }
-  if (existsSync9(join10(projectRoot, "nuxt.config.js")) || existsSync9(join10(projectRoot, "nuxt.config.ts"))) {
+  if (existsSync10(join11(projectRoot, "nuxt.config.js")) || existsSync10(join11(projectRoot, "nuxt.config.ts"))) {
     result.framework = "nuxt";
     result.version = getPackageVersion(projectRoot, "nuxt");
     return result;
   }
-  if (existsSync9(join10(projectRoot, "astro.config.mjs")) || existsSync9(join10(projectRoot, "astro.config.ts"))) {
+  if (existsSync10(join11(projectRoot, "astro.config.mjs")) || existsSync10(join11(projectRoot, "astro.config.ts"))) {
     result.framework = "astro";
     result.version = getPackageVersion(projectRoot, "astro");
     return result;
   }
-  if (existsSync9(join10(projectRoot, "svelte.config.js")) || existsSync9(join10(projectRoot, "svelte.config.ts"))) {
+  if (existsSync10(join11(projectRoot, "svelte.config.js")) || existsSync10(join11(projectRoot, "svelte.config.ts"))) {
     result.framework = "svelte";
     result.version = getPackageVersion(projectRoot, "svelte");
     return result;
   }
-  if (existsSync9(join10(projectRoot, "angular.json"))) {
+  if (existsSync10(join11(projectRoot, "angular.json"))) {
     result.framework = "angular";
     result.version = getPackageVersion(projectRoot, "@angular/core");
     return result;
   }
-  const packageJsonPath = join10(projectRoot, "package.json");
-  if (existsSync9(packageJsonPath)) {
+  const packageJsonPath = join11(projectRoot, "package.json");
+  if (existsSync10(packageJsonPath)) {
     try {
-      const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf-8"));
+      const packageJson = JSON.parse(readFileSync9(packageJsonPath, "utf-8"));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
       if (deps.next) {
         result.framework = "nextjs";
@@ -2445,18 +2702,18 @@ function detectProject(projectRoot = process.cwd()) {
     } catch {
     }
   }
-  if (result.framework === "unknown" && !existsSync9(packageJsonPath)) {
-    if (existsSync9(join10(projectRoot, "index.html"))) {
+  if (result.framework === "unknown" && !existsSync10(packageJsonPath)) {
+    if (existsSync10(join11(projectRoot, "index.html"))) {
       result.framework = "html";
     }
   }
   return result;
 }
 function getPackageVersion(projectRoot, packageName) {
-  const packageJsonPath = join10(projectRoot, "package.json");
-  if (!existsSync9(packageJsonPath)) return void 0;
+  const packageJsonPath = join11(projectRoot, "package.json");
+  if (!existsSync10(packageJsonPath)) return void 0;
   try {
-    const packageJson = JSON.parse(readFileSync8(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(readFileSync9(packageJsonPath, "utf-8"));
     const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
     const version = deps[packageName];
     return version?.replace(/^\^|~/, "");
@@ -2489,8 +2746,8 @@ function formatDetection(detected) {
 }
 
 // src/workflow-model.ts
-import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
+import { join as join12 } from "path";
 function inferSuggestedShell(layout) {
   if (layout.hasSidebar) return "sidebar-main";
   if (layout.hasTopNav) return "top-nav-main";
@@ -2577,12 +2834,12 @@ function createBrownfieldInitSeed(detected, layout, styling) {
   };
 }
 function readBrownfieldInitSeed(projectRoot) {
-  const seedPath = join11(projectRoot, ".decantr", "init-seed.json");
-  if (!existsSync10(seedPath)) {
+  const seedPath = join12(projectRoot, ".decantr", "init-seed.json");
+  if (!existsSync11(seedPath)) {
     return null;
   }
   try {
-    const parsed = JSON.parse(readFileSync9(seedPath, "utf-8"));
+    const parsed = JSON.parse(readFileSync10(seedPath, "utf-8"));
     if (parsed.workflow !== "brownfield-adoption") {
       return null;
     }
@@ -2693,21 +2950,31 @@ ${BOLD}Analyzing project...${RESET2}
       ]
     }
   };
-  const decantrDir = join12(projectRoot, ".decantr");
-  if (!existsSync11(decantrDir)) {
-    mkdirSync5(decantrDir, { recursive: true });
-  }
-  const outputPath = join12(decantrDir, "analysis.json");
-  const initSeedPath = join12(decantrDir, "init-seed.json");
-  const ambientPath = join12(decantrDir, "ambient-context.json");
-  const doctrinePath = join12(decantrDir, "doctrine-map.json");
-  const reportPath = join12(decantrDir, "brownfield-report.md");
-  writeFileSync6(outputPath, JSON.stringify(analysis, null, 2) + "\n", "utf-8");
-  writeFileSync6(initSeedPath, JSON.stringify(initSeed, null, 2) + "\n", "utf-8");
-  writeFileSync6(ambientPath, JSON.stringify(ambient, null, 2) + "\n", "utf-8");
+  const decantrDir = join13(projectRoot, ".decantr");
+  if (!existsSync12(decantrDir)) {
+    mkdirSync6(decantrDir, { recursive: true });
+  }
+  const outputPath = join13(decantrDir, "analysis.json");
+  const initSeedPath = join13(decantrDir, "init-seed.json");
+  const ambientPath = join13(decantrDir, "ambient-context.json");
+  const doctrinePath = join13(decantrDir, "doctrine-map.json");
+  const reportPath = join13(decantrDir, "brownfield-report.md");
+  writeFileSync7(outputPath, JSON.stringify(analysis, null, 2) + "\n", "utf-8");
+  writeFileSync7(initSeedPath, JSON.stringify(initSeed, null, 2) + "\n", "utf-8");
+  writeFileSync7(ambientPath, JSON.stringify(ambient, null, 2) + "\n", "utf-8");
   writeDoctrineMap(projectRoot, doctrine);
   writeBrownfieldProposal(projectRoot, proposal);
-  writeFileSync6(reportPath, generateBrownfieldReport(proposal, ambient, doctrine), "utf-8");
+  writeFileSync7(reportPath, generateBrownfieldReport(proposal, ambient, doctrine), "utf-8");
+  const intelligenceArtifacts = writeBrownfieldIntelligenceArtifacts({
+    projectRoot,
+    project,
+    routes,
+    components,
+    styling,
+    layout,
+    features,
+    dependencies
+  });
   console.log(`
 ${GREEN2}Analysis complete.${RESET2}
 `);
@@ -2743,8 +3010,13 @@ ${DIM2}Written to:${RESET2} ${outputPath}`);
   console.log(`${DIM2}Init seed:${RESET2} ${initSeedPath}`);
   console.log(`${DIM2}Ambient context:${RESET2} ${ambientPath}`);
   console.log(`${DIM2}Doctrine map:${RESET2} ${doctrinePath}`);
-  console.log(`${DIM2}Observed proposal:${RESET2} ${join12(decantrDir, "observed-essence.proposal.json")}`);
+  console.log(
+    `${DIM2}Observed proposal:${RESET2} ${join13(decantrDir, "observed-essence.proposal.json")}`
+  );
   console.log(`${DIM2}Brownfield report:${RESET2} ${reportPath}`);
+  console.log(`${DIM2}Brownfield intelligence:${RESET2} ${intelligenceArtifacts.intelligencePath}`);
+  console.log(`${DIM2}Theme inventory:${RESET2} ${intelligenceArtifacts.themeInventoryPath}`);
+  console.log(`${DIM2}Enrichment backlog:${RESET2} ${intelligenceArtifacts.backlogPath}`);
   console.log(
     `
 ${YELLOW}Next step:${RESET2} Review ${BOLD}.decantr/brownfield-report.md${RESET2}, then run ${BOLD}decantr init --existing --accept-proposal${RESET2} to attach Decantr using the observed proposal.
@@ -2769,8 +3041,8 @@ ${YELLOW}Next step:${RESET2} Review ${BOLD}.decantr/brownfield-report.md${RESET2
 }
 
 // src/commands/create.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7 } from "fs";
-import { join as join13 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
+import { join as join14 } from "path";
 import {
   CONTENT_TYPE_TO_API_CONTENT_TYPE,
   CONTENT_TYPES
@@ -2966,23 +3238,23 @@ function cmdCreate(type, name, projectRoot = process.cwd()) {
   }
   const contentType = type;
   const plural = PLURAL[contentType];
-  const customDir = join13(projectRoot, ".decantr", "custom", plural);
-  const filePath = join13(customDir, `${name}.json`);
-  if (existsSync12(filePath)) {
+  const customDir = join14(projectRoot, ".decantr", "custom", plural);
+  const filePath = join14(customDir, `${name}.json`);
+  if (existsSync13(filePath)) {
     console.error(`${type} "${name}" already exists at ${filePath}`);
     process.exitCode = 1;
     return;
   }
-  mkdirSync6(customDir, { recursive: true });
+  mkdirSync7(customDir, { recursive: true });
   const skeleton = getSkeleton(contentType, name, humanizeId(name));
-  writeFileSync7(filePath, JSON.stringify(skeleton, null, 2));
+  writeFileSync8(filePath, JSON.stringify(skeleton, null, 2));
   console.log(`Created ${type} "${name}" at ${filePath}`);
   console.log(`Edit it, then publish with: decantr publish ${type} ${name}`);
 }
 
 // src/commands/export.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync8 } from "fs";
-import { dirname as dirname2, join as join14 } from "path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync9 } from "fs";
+import { dirname as dirname2, join as join15 } from "path";
 var GREEN3 = "\x1B[32m";
 var RED2 = "\x1B[31m";
 var DIM3 = "\x1B[2m";
@@ -3148,21 +3420,21 @@ function generateFigmaTokens(tokens) {
 `;
 }
 async function cmdExport(target, projectRoot, options = {}) {
-  const essencePath = join14(projectRoot, "decantr.essence.json");
-  const tokensPath = join14(projectRoot, "src", "styles", "tokens.css");
-  if (!existsSync13(essencePath)) {
+  const essencePath = join15(projectRoot, "decantr.essence.json");
+  const tokensPath = join15(projectRoot, "src", "styles", "tokens.css");
+  if (!existsSync14(essencePath)) {
     console.error(`${RED2}No decantr.essence.json found. Run \`decantr init\` first.${RESET3}`);
     process.exitCode = 1;
     return;
   }
-  if (!existsSync13(tokensPath)) {
+  if (!existsSync14(tokensPath)) {
     console.error(
       `${RED2}No src/styles/tokens.css found. Run \`decantr refresh\` to generate tokens.${RESET3}`
     );
     process.exitCode = 1;
     return;
   }
-  const tokensCSS = readFileSync10(tokensPath, "utf-8");
+  const tokensCSS = readFileSync11(tokensPath, "utf-8");
   const tokens = parseTokensCSS(tokensCSS);
   if (tokens.size === 0) {
     console.error(`${RED2}No --d-* tokens found in tokens.css.${RESET3}`);
@@ -3171,36 +3443,36 @@ async function cmdExport(target, projectRoot, options = {}) {
   }
   switch (target) {
     case "shadcn": {
-      const cssOut = options.output ?? join14(projectRoot, "src", "styles", "shadcn-theme.css");
-      const jsonOut = join14(projectRoot, "components.json");
+      const cssOut = options.output ?? join15(projectRoot, "src", "styles", "shadcn-theme.css");
+      const jsonOut = join15(projectRoot, "components.json");
       ensureDir(cssOut);
-      writeFileSync8(cssOut, generateShadcnCSS(tokens), "utf-8");
-      writeFileSync8(jsonOut, generateShadcnComponentsJSON(), "utf-8");
+      writeFileSync9(cssOut, generateShadcnCSS(tokens), "utf-8");
+      writeFileSync9(jsonOut, generateShadcnComponentsJSON(), "utf-8");
       console.log(`${GREEN3}Exported shadcn theme:${RESET3}`);
       console.log(`  ${DIM3}CSS:${RESET3}  ${cssOut}`);
       console.log(`  ${DIM3}JSON:${RESET3} ${jsonOut}`);
       break;
     }
     case "tailwind": {
-      const out = options.output ?? join14(projectRoot, "tailwind.decantr.config.ts");
+      const out = options.output ?? join15(projectRoot, "tailwind.decantr.config.ts");
       ensureDir(out);
-      writeFileSync8(out, generateTailwindConfig(tokens), "utf-8");
+      writeFileSync9(out, generateTailwindConfig(tokens), "utf-8");
       console.log(`${GREEN3}Exported Tailwind config:${RESET3}`);
       console.log(`  ${DIM3}File:${RESET3} ${out}`);
       break;
     }
     case "css-vars": {
-      const out = options.output ?? join14(projectRoot, "decantr-tokens.css");
+      const out = options.output ?? join15(projectRoot, "decantr-tokens.css");
       ensureDir(out);
-      writeFileSync8(out, generateCSSVars(tokens), "utf-8");
+      writeFileSync9(out, generateCSSVars(tokens), "utf-8");
       console.log(`${GREEN3}Exported CSS variables:${RESET3}`);
       console.log(`  ${DIM3}File:${RESET3} ${out}`);
       break;
     }
     case "figma-tokens": {
-      const out = options.output ?? join14(projectRoot, ".decantr", "design", "figma-tokens.json");
+      const out = options.output ?? join15(projectRoot, ".decantr", "design", "figma-tokens.json");
       ensureDir(out);
-      writeFileSync8(out, generateFigmaTokens(tokens), "utf-8");
+      writeFileSync9(out, generateFigmaTokens(tokens), "utf-8");
       console.log(`${GREEN3}Exported Figma/Tokens Studio tokens:${RESET3}`);
       console.log(`  ${DIM3}File:${RESET3} ${out}`);
       break;
@@ -3209,15 +3481,15 @@ async function cmdExport(target, projectRoot, options = {}) {
 }
 function ensureDir(filePath) {
   const dir = dirname2(filePath);
-  if (!existsSync13(dir)) {
-    mkdirSync7(dir, { recursive: true });
+  if (!existsSync14(dir)) {
+    mkdirSync8(dir, { recursive: true });
   }
 }
 
 // src/commands/magic.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 import * as fs from "fs/promises";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 var BOLD2 = "\x1B[1m";
 var DIM4 = "\x1B[2m";
 var RESET4 = "\x1B[0m";
@@ -3445,8 +3717,8 @@ async function cmdMagic(prompt, projectRoot, options) {
     console.log(`   Archetype:    ${intent.archetype}`);
   }
   console.log("");
-  const essencePath = join15(projectRoot, "decantr.essence.json");
-  if (existsSync14(essencePath)) {
+  const essencePath = join16(projectRoot, "decantr.essence.json");
+  if (existsSync15(essencePath)) {
     console.log(error("  decantr.essence.json already exists in this directory."));
     console.log(dim("  Remove it first or use a different directory."));
     process.exitCode = 1;
@@ -3471,7 +3743,7 @@ async function cmdMagic(prompt, projectRoot, options) {
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join15(projectRoot, ".decantr", "cache"),
+    cacheDir: join16(projectRoot, ".decantr", "cache"),
     apiUrl: options.registry,
     offline: options.offline
   });
@@ -3742,14 +4014,14 @@ async function cmdMagic(prompt, projectRoot, options) {
   if (result.gitignoreUpdated) {
     console.log(`   ${dim(".gitignore updated")}`);
   }
-  const contextDir = join15(projectRoot, ".decantr", "context");
+  const contextDir = join16(projectRoot, ".decantr", "context");
   let sectionCount = 0;
   try {
     const files = await fs.readdir(contextDir);
     sectionCount = files.filter((f) => f.startsWith("section-")).length;
   } catch {
   }
-  const treatmentsPath = join15(projectRoot, "src", "styles", "treatments.css");
+  const treatmentsPath = join16(projectRoot, "src", "styles", "treatments.css");
   let hasLayers = false;
   try {
     const css = await fs.readFile(treatmentsPath, "utf-8");
@@ -3782,8 +4054,8 @@ ${GREEN4}${BOLD2}Quality summary:${RESET4}`);
 }
 
 // src/commands/migrate.ts
-import { copyFileSync, existsSync as existsSync15, readFileSync as readFileSync11, writeFileSync as writeFileSync9 } from "fs";
-import { join as join16 } from "path";
+import { copyFileSync, existsSync as existsSync16, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "fs";
+import { join as join17 } from "path";
 import {
   isV4 as isV43,
   migrateToV4,
@@ -3796,12 +4068,12 @@ var YELLOW3 = "\x1B[33m";
 var RESET5 = "\x1B[0m";
 var DIM5 = "\x1B[2m";
 function migrateEssenceFile(essencePath) {
-  if (!existsSync15(essencePath)) {
+  if (!existsSync16(essencePath)) {
     return { success: false, error: `File not found: ${essencePath}` };
   }
   let raw;
   try {
-    raw = readFileSync11(essencePath, "utf-8");
+    raw = readFileSync12(essencePath, "utf-8");
   } catch (e) {
     return { success: false, error: `Could not read ${essencePath}: ${e.message}` };
   }
@@ -3842,7 +4114,7 @@ function migrateEssenceFile(essencePath) {
     };
   }
   try {
-    writeFileSync9(essencePath, JSON.stringify(v4, null, 2) + "\n");
+    writeFileSync10(essencePath, JSON.stringify(v4, null, 2) + "\n");
   } catch (e) {
     return {
       success: false,
@@ -3863,8 +4135,8 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
     process.exitCode = 1;
     return;
   }
-  const essencePath = join16(projectRoot, "decantr.essence.json");
-  if (!existsSync15(essencePath)) {
+  const essencePath = join17(projectRoot, "decantr.essence.json");
+  if (!existsSync16(essencePath)) {
     console.error(`${RED4}No decantr.essence.json found. Run \`decantr init\` first.${RESET5}`);
     process.exitCode = 1;
     return;
@@ -3886,7 +4158,7 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
   }
   if (result.essence) {
     const registryClient = new RegistryClient({
-      cacheDir: join16(projectRoot, ".decantr", "cache")
+      cacheDir: join17(projectRoot, ".decantr", "cache")
     });
     await refreshDerivedFiles(projectRoot, result.essence, registryClient);
     console.log(`${GREEN5}Derived context and execution packs refreshed.${RESET5}`);
@@ -3897,50 +4169,50 @@ async function cmdMigrate(projectRoot = process.cwd(), args = []) {
 
 // src/commands/new-project.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync17, mkdirSync as mkdirSync9 } from "fs";
-import { join as join18, resolve as resolve2 } from "path";
+import { existsSync as existsSync18, mkdirSync as mkdirSync10 } from "fs";
+import { join as join19, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/offline-content.ts
-import { cpSync, existsSync as existsSync16, mkdirSync as mkdirSync8 } from "fs";
-import { join as join17, resolve } from "path";
+import { cpSync, existsSync as existsSync17, mkdirSync as mkdirSync9 } from "fs";
+import { join as join18, resolve } from "path";
 var CONTENT_TYPES2 = ["archetypes", "blueprints", "patterns", "themes", "shells"];
 function copyIfExists(source, target) {
-  if (!existsSync16(source)) return false;
+  if (!existsSync17(source)) return false;
   if (resolve(source) === resolve(target)) return true;
   cpSync(source, target, { recursive: true });
   return true;
 }
 function hydrateContentRoot(projectDir, contentRoot) {
-  if (!existsSync16(contentRoot)) return false;
-  const customRoot = join17(projectDir, ".decantr", "custom");
-  const cacheRoot = join17(projectDir, ".decantr", "cache", "@official");
-  mkdirSync8(customRoot, { recursive: true });
-  mkdirSync8(cacheRoot, { recursive: true });
+  if (!existsSync17(contentRoot)) return false;
+  const customRoot = join18(projectDir, ".decantr", "custom");
+  const cacheRoot = join18(projectDir, ".decantr", "cache", "@official");
+  mkdirSync9(customRoot, { recursive: true });
+  mkdirSync9(cacheRoot, { recursive: true });
   let copiedAny = false;
   for (const type of CONTENT_TYPES2) {
-    const sourceDir = join17(contentRoot, type);
-    if (!existsSync16(sourceDir)) continue;
-    cpSync(sourceDir, join17(customRoot, type), { recursive: true });
-    cpSync(sourceDir, join17(cacheRoot, type), { recursive: true });
+    const sourceDir = join18(contentRoot, type);
+    if (!existsSync17(sourceDir)) continue;
+    cpSync(sourceDir, join18(customRoot, type), { recursive: true });
+    cpSync(sourceDir, join18(cacheRoot, type), { recursive: true });
     copiedAny = true;
   }
   return copiedAny;
 }
 function seedOfflineRegistry(projectDir, workspaceRoot) {
-  const projectDecantrRoot = join17(projectDir, ".decantr");
-  mkdirSync8(projectDecantrRoot, { recursive: true });
+  const projectDecantrRoot = join18(projectDir, ".decantr");
+  mkdirSync9(projectDecantrRoot, { recursive: true });
   const configuredContentRoot = process.env.DECANTR_CONTENT_DIR ? resolve(process.env.DECANTR_CONTENT_DIR) : null;
   if (configuredContentRoot && hydrateContentRoot(projectDir, configuredContentRoot)) {
     return { seeded: true, strategy: "configured-content-root" };
   }
   const copiedCache = copyIfExists(
-    join17(workspaceRoot, ".decantr", "cache"),
-    join17(projectDecantrRoot, "cache")
+    join18(workspaceRoot, ".decantr", "cache"),
+    join18(projectDecantrRoot, "cache")
   );
   const copiedCustom = copyIfExists(
-    join17(workspaceRoot, ".decantr", "custom"),
-    join17(projectDecantrRoot, "custom")
+    join18(workspaceRoot, ".decantr", "custom"),
+    join18(projectDecantrRoot, "custom")
   );
   if (copiedCache || copiedCustom) {
     return { seeded: true, strategy: "workspace-cache" };
@@ -4053,7 +4325,7 @@ function runArgvCommand(command, args, cwd) {
 }
 function resolveInitCommand(initFlags) {
   const bundledCliEntrypoint = fileURLToPath(new URL("./bin.js", import.meta.url));
-  const cliEntrypoint = existsSync17(bundledCliEntrypoint) ? bundledCliEntrypoint : process.argv[1] && existsSync17(process.argv[1]) ? process.argv[1] : null;
+  const cliEntrypoint = existsSync18(bundledCliEntrypoint) ? bundledCliEntrypoint : process.argv[1] && existsSync18(process.argv[1]) ? process.argv[1] : null;
   if (cliEntrypoint) {
     return {
       command: process.execPath,
@@ -4081,7 +4353,7 @@ async function cmdNewProject(projectName, options) {
     process.exitCode = 1;
     return;
   }
-  if (existsSync17(projectDir)) {
+  if (existsSync18(projectDir)) {
     console.error(error2(`Directory "${projectName}" already exists.`));
     process.exitCode = 1;
     return;
@@ -4095,7 +4367,7 @@ async function cmdNewProject(projectName, options) {
     return;
   }
   console.log(heading(`Creating ${projectName}...`));
-  mkdirSync9(projectDir, { recursive: true });
+  mkdirSync10(projectDir, { recursive: true });
   console.log(dim2(`  Created ${projectName}/`));
   const title = projectName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
   if (shouldBootstrapRuntime && bootstrapAdapter) {
@@ -4194,21 +4466,21 @@ ${YELLOW4}Decantr init encountered issues. Run \`decantr init\` manually inside
   }
 }
 function detectPackageManager() {
-  if (existsSync17(join18(process.cwd(), "pnpm-lock.yaml")) || existsSync17(join18(process.cwd(), "pnpm-workspace.yaml"))) {
+  if (existsSync18(join19(process.cwd(), "pnpm-lock.yaml")) || existsSync18(join19(process.cwd(), "pnpm-workspace.yaml"))) {
     return "pnpm";
   }
-  if (existsSync17(join18(process.cwd(), "yarn.lock"))) {
+  if (existsSync18(join19(process.cwd(), "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync17(join18(process.cwd(), "bun.lockb")) || existsSync17(join18(process.cwd(), "bun.lock"))) {
+  if (existsSync18(join19(process.cwd(), "bun.lockb")) || existsSync18(join19(process.cwd(), "bun.lock"))) {
     return "bun";
   }
   return "npm";
 }
 
 // src/commands/publish.ts
-import { existsSync as existsSync18, readFileSync as readFileSync12 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync13 } from "fs";
+import { join as join20 } from "path";
 import {
   API_CONTENT_TYPE_TO_CONTENT_TYPE,
   CONTENT_TYPE_TO_API_CONTENT_TYPE as CONTENT_TYPE_TO_API_CONTENT_TYPE2,
@@ -4224,8 +4496,8 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
   }
   const singularType = API_CONTENT_TYPE_TO_CONTENT_TYPE[type] || type;
   const pluralType = CONTENT_TYPE_TO_API_CONTENT_TYPE2[type] || CONTENT_TYPE_TO_API_CONTENT_TYPE2[singularType] || `${type}s`;
-  const customPath = join19(projectRoot, ".decantr", "custom", pluralType, `${name}.json`);
-  if (!existsSync18(customPath)) {
+  const customPath = join20(projectRoot, ".decantr", "custom", pluralType, `${name}.json`);
+  if (!existsSync19(customPath)) {
     console.error(`Custom ${singularType} "${name}" not found at ${customPath}`);
     console.error(`Create one first: decantr create ${singularType} ${name}`);
     process.exitCode = 1;
@@ -4233,7 +4505,7 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
   }
   let data;
   try {
-    data = JSON.parse(readFileSync12(customPath, "utf-8"));
+    data = JSON.parse(readFileSync13(customPath, "utf-8"));
   } catch {
     console.error(`Failed to parse ${customPath}`);
     process.exitCode = 1;
@@ -4271,23 +4543,23 @@ async function cmdPublish(type, name, projectRoot = process.cwd()) {
 }
 
 // src/commands/refresh.ts
-import { existsSync as existsSync19, readFileSync as readFileSync13 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync14 } from "fs";
+import { join as join21 } from "path";
 import { isV4 as isV44 } from "@decantr/essence-spec";
 var GREEN7 = "\x1B[32m";
 var RED6 = "\x1B[31m";
 var DIM7 = "\x1B[2m";
 var RESET7 = "\x1B[0m";
 async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
-  const essencePath = join20(projectRoot, "decantr.essence.json");
-  if (!existsSync19(essencePath)) {
+  const essencePath = join21(projectRoot, "decantr.essence.json");
+  if (!existsSync20(essencePath)) {
     console.error(`${RED6}No decantr.essence.json found. Run \`decantr init\` first.${RESET7}`);
     process.exitCode = 1;
     return;
   }
   let essence;
   try {
-    const raw = readFileSync13(essencePath, "utf-8");
+    const raw = readFileSync14(essencePath, "utf-8");
     const parsed = JSON.parse(raw);
     if (!isV44(parsed)) {
       console.error(
@@ -4303,7 +4575,7 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join20(projectRoot, ".decantr", "cache"),
+    cacheDir: join21(projectRoot, ".decantr", "cache"),
     offline: options.offline
   });
   console.log("Regenerating derived files...\n");
@@ -4323,8 +4595,8 @@ async function cmdRefresh(projectRoot = process.cwd(), options = {}) {
 }
 
 // src/commands/registry-mirror.ts
-import { mkdirSync as mkdirSync10, writeFileSync as writeFileSync10 } from "fs";
-import { join as join21 } from "path";
+import { mkdirSync as mkdirSync11, writeFileSync as writeFileSync11 } from "fs";
+import { join as join22 } from "path";
 import { API_CONTENT_TYPES, RegistryAPIClient as RegistryAPIClient2 } from "@decantr/registry";
 var GREEN8 = "\x1B[32m";
 var RED7 = "\x1B[31m";
@@ -4352,7 +4624,7 @@ async function cmdRegistryMirror(projectRoot, options = {}) {
     process.exitCode = 1;
     return;
   }
-  const cacheDir = join21(projectRoot, ".decantr", "cache");
+  const cacheDir = join22(projectRoot, ".decantr", "cache");
   const counts = {};
   const failed = [];
   console.log(`
@@ -4362,19 +4634,19 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
     try {
       const result = await apiClient.listContent(type, { namespace: "@official" });
       const items = result.items;
-      const typeDir = join21(cacheDir, "@official", type);
-      mkdirSync10(typeDir, { recursive: true });
-      writeFileSync10(join21(typeDir, "index.json"), JSON.stringify(result, null, 2));
+      const typeDir = join22(cacheDir, "@official", type);
+      mkdirSync11(typeDir, { recursive: true });
+      writeFileSync11(join22(typeDir, "index.json"), JSON.stringify(result, null, 2));
       let itemCount = 0;
       for (const item of items) {
         const slug = item.slug || item.id;
         if (!slug) continue;
         try {
           const fullItem = await apiClient.getContent(type, "@official", slug);
-          writeFileSync10(join21(typeDir, `${slug}.json`), JSON.stringify(fullItem, null, 2));
+          writeFileSync11(join22(typeDir, `${slug}.json`), JSON.stringify(fullItem, null, 2));
           itemCount++;
         } catch {
-          writeFileSync10(join21(typeDir, `${slug}.json`), JSON.stringify(item, null, 2));
+          writeFileSync11(join22(typeDir, `${slug}.json`), JSON.stringify(item, null, 2));
           itemCount++;
         }
       }
@@ -4389,8 +4661,8 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
     mirrored_at: (/* @__PURE__ */ new Date()).toISOString(),
     counts
   };
-  mkdirSync10(join21(cacheDir), { recursive: true });
-  writeFileSync10(join21(cacheDir, "mirror-manifest.json"), JSON.stringify(manifest, null, 2));
+  mkdirSync11(join22(cacheDir), { recursive: true });
+  writeFileSync11(join22(cacheDir, "mirror-manifest.json"), JSON.stringify(manifest, null, 2));
   const totalItems = Object.values(counts).reduce((a, b) => a + b, 0);
   console.log("");
   if (failed.length > 0) {
@@ -4407,23 +4679,23 @@ Mirroring registry content to ${DIM8}.decantr/cache/${RESET8}
 }
 
 // src/commands/remove.ts
-import { existsSync as existsSync21, readFileSync as readFileSync14, rmSync as rmSync2, writeFileSync as writeFileSync11 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync15, rmSync as rmSync2, writeFileSync as writeFileSync12 } from "fs";
+import { join as join23 } from "path";
 import { isV4 as isV45 } from "@decantr/essence-spec";
 var GREEN9 = "\x1B[32m";
 var RED8 = "\x1B[31m";
 var DIM9 = "\x1B[2m";
 var RESET9 = "\x1B[0m";
 function readV4Essence2(projectRoot) {
-  const essencePath = join22(projectRoot, "decantr.essence.json");
-  if (!existsSync21(essencePath)) {
+  const essencePath = join23(projectRoot, "decantr.essence.json");
+  if (!existsSync22(essencePath)) {
     console.error(`${RED8}No decantr.essence.json found. Run \`decantr init\` first.${RESET9}`);
     process.exitCode = 1;
     return null;
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync14(essencePath, "utf-8"));
+    parsed = JSON.parse(readFileSync15(essencePath, "utf-8"));
   } catch (e) {
     console.error(`${RED8}Could not read essence: ${e.message}${RESET9}`);
     process.exitCode = 1;
@@ -4439,7 +4711,7 @@ function readV4Essence2(projectRoot) {
   return { essence: parsed, essencePath };
 }
 function writeEssence2(essencePath, essence) {
-  writeFileSync11(essencePath, JSON.stringify(essence, null, 2) + "\n");
+  writeFileSync12(essencePath, JSON.stringify(essence, null, 2) + "\n");
 }
 function recomputeGlobalFeatures(essence) {
   const all = /* @__PURE__ */ new Set();
@@ -4481,14 +4753,14 @@ async function cmdRemoveSection(sectionId, args, projectRoot = process.cwd()) {
   sections.splice(idx, 1);
   recomputeGlobalFeatures(essence);
   removeRoutes(essence, sectionId);
-  const contextFile = join22(projectRoot, ".decantr", "context", `${sectionId}.md`);
-  if (existsSync21(contextFile)) {
+  const contextFile = join23(projectRoot, ".decantr", "context", `${sectionId}.md`);
+  if (existsSync22(contextFile)) {
     rmSync2(contextFile);
   }
   writeEssence2(essencePath, essence);
   console.log(`${GREEN9}Removed section "${sectionId}".${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
@@ -4524,7 +4796,7 @@ async function cmdRemovePage(path, args, projectRoot = process.cwd()) {
   writeEssence2(essencePath, essence);
   console.log(`${GREEN9}Removed page "${pageId}" from section "${sectionId}".${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
@@ -4565,15 +4837,15 @@ async function cmdRemoveFeature(feature, args, projectRoot = process.cwd()) {
   const target = sectionId ? `section "${sectionId}" and global` : "global";
   console.log(`${GREEN9}Removed feature "${feature}" from ${target} features.${RESET9}`);
   const registryClient = new RegistryClient({
-    cacheDir: join22(projectRoot, ".decantr", "cache")
+    cacheDir: join23(projectRoot, ".decantr", "cache")
   });
   await refreshDerivedFiles(projectRoot, essence, registryClient);
   console.log(`${GREEN9}Derived files refreshed.${RESET9}`);
 }
 
 // src/commands/sync-drift.ts
-import { existsSync as existsSync22, readFileSync as readFileSync15, writeFileSync as writeFileSync12 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync23, readFileSync as readFileSync16, writeFileSync as writeFileSync13 } from "fs";
+import { join as join24 } from "path";
 var GREEN10 = "\x1B[32m";
 var RED9 = "\x1B[31m";
 var YELLOW6 = "\x1B[33m";
@@ -4582,8 +4854,8 @@ var DIM10 = "\x1B[2m";
 var BOLD4 = "\x1B[1m";
 var CYAN5 = "\x1B[36m";
 async function cmdSyncDrift(projectRoot = process.cwd()) {
-  const driftLogPath = join23(projectRoot, ".decantr", "drift-log.json");
-  if (!existsSync22(driftLogPath)) {
+  const driftLogPath = join24(projectRoot, ".decantr", "drift-log.json");
+  if (!existsSync23(driftLogPath)) {
     console.log(`${GREEN10}No drift log found \u2014 no drift recorded.${RESET10}`);
     console.log(
       `${DIM10}Drift is logged when guard violations are detected during development.${RESET10}`
@@ -4592,7 +4864,7 @@ async function cmdSyncDrift(projectRoot = process.cwd()) {
   }
   let entries;
   try {
-    entries = JSON.parse(readFileSync15(driftLogPath, "utf-8"));
+    entries = JSON.parse(readFileSync16(driftLogPath, "utf-8"));
   } catch {
     console.error(`${RED9}Could not parse drift-log.json${RESET10}`);
     process.exitCode = 1;
@@ -4638,13 +4910,13 @@ ${BOLD4}Unresolved Drift Entries (${unresolved.length})${RESET10}
   console.log("");
 }
 function resolveDriftEntries(projectRoot, options) {
-  const driftLogPath = join23(projectRoot, ".decantr", "drift-log.json");
-  if (!existsSync22(driftLogPath)) {
+  const driftLogPath = join24(projectRoot, ".decantr", "drift-log.json");
+  if (!existsSync23(driftLogPath)) {
     return { success: true };
   }
   if (options.clear) {
     try {
-      writeFileSync12(driftLogPath, "[]");
+      writeFileSync13(driftLogPath, "[]");
       return { success: true };
     } catch (e) {
       return { success: false, error: `Could not clear drift log: ${e.message}` };
@@ -4652,7 +4924,7 @@ function resolveDriftEntries(projectRoot, options) {
   }
   let entries;
   try {
-    entries = JSON.parse(readFileSync15(driftLogPath, "utf-8"));
+    entries = JSON.parse(readFileSync16(driftLogPath, "utf-8"));
   } catch {
     return { success: false, error: "Could not parse drift-log.json" };
   }
@@ -4671,7 +4943,7 @@ function resolveDriftEntries(projectRoot, options) {
     }
   }
   try {
-    writeFileSync12(driftLogPath, JSON.stringify(entries, null, 2));
+    writeFileSync13(driftLogPath, JSON.stringify(entries, null, 2));
     return { success: true };
   } catch (e) {
     return { success: false, error: `Could not write drift log: ${e.message}` };
@@ -4896,8 +5168,8 @@ function trimTrailingSlashes(value) {
 }
 
 // src/commands/theme-switch.ts
-import { existsSync as existsSync23, readFileSync as readFileSync16, writeFileSync as writeFileSync13 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync24, readFileSync as readFileSync17, writeFileSync as writeFileSync14 } from "fs";
+import { join as join25 } from "path";
 import { isV4 as isV46 } from "@decantr/essence-spec";
 var GREEN12 = "\x1B[32m";
 var RED10 = "\x1B[31m";
@@ -4914,15 +5186,15 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     process.exitCode = 1;
     return;
   }
-  const essencePath = join24(projectRoot, "decantr.essence.json");
-  if (!existsSync23(essencePath)) {
+  const essencePath = join25(projectRoot, "decantr.essence.json");
+  if (!existsSync24(essencePath)) {
     console.error(`${RED10}No decantr.essence.json found. Run \`decantr init\` first.${RESET12}`);
     process.exitCode = 1;
     return;
   }
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync16(essencePath, "utf-8"));
+    parsed = JSON.parse(readFileSync17(essencePath, "utf-8"));
   } catch (e) {
     console.error(`${RED10}Could not read essence: ${e.message}${RESET12}`);
     process.exitCode = 1;
@@ -4973,7 +5245,7 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     essence.dna.theme.mode = mode;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join24(projectRoot, ".decantr", "cache")
+    cacheDir: join25(projectRoot, ".decantr", "cache")
   });
   try {
     const themeResult = await registryClient.fetchTheme(themeName);
@@ -4988,7 +5260,7 @@ async function cmdThemeSwitch(themeName, args, projectRoot = process.cwd()) {
     }
   } catch {
   }
-  writeFileSync13(essencePath, JSON.stringify(essence, null, 2) + "\n");
+  writeFileSync14(essencePath, JSON.stringify(essence, null, 2) + "\n");
   console.log(`${GREEN12}Switched theme: ${oldThemeId} \u2192 ${themeName}${RESET12}`);
   if (shape) console.log(`  ${DIM12}Shape: ${shape}${RESET12}`);
   if (mode) console.log(`  ${DIM12}Mode: ${mode}${RESET12}`);
@@ -5296,8 +5568,8 @@ async function runSimplifiedInit(blueprints) {
 }
 
 // src/theme-commands.ts
-import { existsSync as existsSync24, mkdirSync as mkdirSync11, readdirSync as readdirSync4, readFileSync as readFileSync17, rmSync as rmSync3, writeFileSync as writeFileSync14 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync25, mkdirSync as mkdirSync12, readdirSync as readdirSync5, readFileSync as readFileSync18, rmSync as rmSync3, writeFileSync as writeFileSync15 } from "fs";
+import { join as join26 } from "path";
 var REQUIRED_FIELDS = [
   "$schema",
   "id",
@@ -5357,20 +5629,20 @@ function validateCustomTheme(theme) {
   };
 }
 function createTheme(projectRoot, id, name) {
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  const themePath = join25(customThemesDir, `${id}.json`);
-  const howToPath = join25(customThemesDir, "how-to-theme.md");
-  mkdirSync11(customThemesDir, { recursive: true });
-  if (existsSync24(themePath)) {
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  const themePath = join26(customThemesDir, `${id}.json`);
+  const howToPath = join26(customThemesDir, "how-to-theme.md");
+  mkdirSync12(customThemesDir, { recursive: true });
+  if (existsSync25(themePath)) {
     return {
       success: false,
       error: `Theme "${id}" already exists at ${themePath}`
     };
   }
   const skeleton = getThemeSkeleton(id, name);
-  writeFileSync14(themePath, JSON.stringify(skeleton, null, 2));
-  if (!existsSync24(howToPath)) {
-    writeFileSync14(howToPath, getHowToThemeDoc());
+  writeFileSync15(themePath, JSON.stringify(skeleton, null, 2));
+  if (!existsSync25(howToPath)) {
+    writeFileSync15(howToPath, getHowToThemeDoc());
   }
   return {
     success: true,
@@ -5378,17 +5650,17 @@ function createTheme(projectRoot, id, name) {
   };
 }
 function listCustomThemes(projectRoot) {
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  if (!existsSync24(customThemesDir)) {
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  if (!existsSync25(customThemesDir)) {
     return [];
   }
   const themes = [];
   try {
-    const files = readdirSync4(customThemesDir).filter((f) => f.endsWith(".json"));
+    const files = readdirSync5(customThemesDir).filter((f) => f.endsWith(".json"));
     for (const file of files) {
-      const filePath = join25(customThemesDir, file);
+      const filePath = join26(customThemesDir, file);
       try {
-        const data = JSON.parse(readFileSync17(filePath, "utf-8"));
+        const data = JSON.parse(readFileSync18(filePath, "utf-8"));
         themes.push({
           id: data.id || file.replace(".json", ""),
           name: data.name || data.id,
@@ -5403,8 +5675,8 @@ function listCustomThemes(projectRoot) {
   return themes;
 }
 function deleteTheme(projectRoot, id) {
-  const themePath = join25(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
-  if (!existsSync24(themePath)) {
+  const themePath = join26(projectRoot, ".decantr", "custom", "themes", `${id}.json`);
+  if (!existsSync25(themePath)) {
     return {
       success: false,
       error: `Theme "${id}" not found at ${themePath}`
@@ -5421,7 +5693,7 @@ function deleteTheme(projectRoot, id) {
   }
 }
 function importTheme(projectRoot, sourcePath) {
-  if (!existsSync24(sourcePath)) {
+  if (!existsSync25(sourcePath)) {
     return {
       success: false,
       errors: [`Source file not found: ${sourcePath}`]
@@ -5429,7 +5701,7 @@ function importTheme(projectRoot, sourcePath) {
   }
   let theme;
   try {
-    theme = JSON.parse(readFileSync17(sourcePath, "utf-8"));
+    theme = JSON.parse(readFileSync18(sourcePath, "utf-8"));
   } catch (e) {
     return {
       success: false,
@@ -5445,14 +5717,14 @@ function importTheme(projectRoot, sourcePath) {
   }
   theme.source = "custom";
   const id = theme.id;
-  const customThemesDir = join25(projectRoot, ".decantr", "custom", "themes");
-  const destPath = join25(customThemesDir, `${id}.json`);
-  mkdirSync11(customThemesDir, { recursive: true });
-  const howToPath = join25(customThemesDir, "how-to-theme.md");
-  if (!existsSync24(howToPath)) {
-    writeFileSync14(howToPath, getHowToThemeDoc());
-  }
-  writeFileSync14(destPath, JSON.stringify(theme, null, 2));
+  const customThemesDir = join26(projectRoot, ".decantr", "custom", "themes");
+  const destPath = join26(customThemesDir, `${id}.json`);
+  mkdirSync12(customThemesDir, { recursive: true });
+  const howToPath = join26(customThemesDir, "how-to-theme.md");
+  if (!existsSync25(howToPath)) {
+    writeFileSync15(howToPath, getHowToThemeDoc());
+  }
+  writeFileSync15(destPath, JSON.stringify(theme, null, 2));
   return {
     success: true,
     path: destPath
@@ -5460,19 +5732,19 @@ function importTheme(projectRoot, sourcePath) {
 }
 
 // src/workspace.ts
-import { existsSync as existsSync25, readdirSync as readdirSync5, readFileSync as readFileSync18 } from "fs";
-import { dirname as dirname3, join as join26, resolve as resolve3 } from "path";
+import { existsSync as existsSync26, readdirSync as readdirSync6, readFileSync as readFileSync19 } from "fs";
+import { dirname as dirname3, join as join27, resolve as resolve3 } from "path";
 function readPackageJson(dir) {
-  const path = join26(dir, "package.json");
-  if (!existsSync25(path)) return null;
+  const path = join27(dir, "package.json");
+  if (!existsSync26(path)) return null;
   try {
-    return JSON.parse(readFileSync18(path, "utf-8"));
+    return JSON.parse(readFileSync19(path, "utf-8"));
   } catch {
     return null;
   }
 }
 function hasWorkspaceMarker(dir) {
-  if (existsSync25(join26(dir, "pnpm-workspace.yaml")) || existsSync25(join26(dir, "turbo.json")) || existsSync25(join26(dir, "nx.json"))) {
+  if (existsSync26(join27(dir, "pnpm-workspace.yaml")) || existsSync26(join27(dir, "turbo.json")) || existsSync26(join27(dir, "nx.json"))) {
     return true;
   }
   const pkg = readPackageJson(dir);
@@ -5488,7 +5760,7 @@ function findWorkspaceRoot(startDir) {
   }
 }
 function looksLikeApp(dir) {
-  if (existsSync25(join26(dir, "next.config.js")) || existsSync25(join26(dir, "next.config.ts")) || existsSync25(join26(dir, "next.config.mjs")) || existsSync25(join26(dir, "vite.config.ts")) || existsSync25(join26(dir, "vite.config.js")) || existsSync25(join26(dir, "angular.json")) || existsSync25(join26(dir, "svelte.config.js")) || existsSync25(join26(dir, "svelte.config.ts")) || existsSync25(join26(dir, "astro.config.mjs")) || existsSync25(join26(dir, "src")) || existsSync25(join26(dir, "app")) || existsSync25(join26(dir, "pages"))) {
+  if (existsSync26(join27(dir, "next.config.js")) || existsSync26(join27(dir, "next.config.ts")) || existsSync26(join27(dir, "next.config.mjs")) || existsSync26(join27(dir, "vite.config.ts")) || existsSync26(join27(dir, "vite.config.js")) || existsSync26(join27(dir, "angular.json")) || existsSync26(join27(dir, "svelte.config.js")) || existsSync26(join27(dir, "svelte.config.ts")) || existsSync26(join27(dir, "astro.config.mjs")) || existsSync26(join27(dir, "src")) || existsSync26(join27(dir, "app")) || existsSync26(join27(dir, "pages"))) {
     return true;
   }
   const pkg = readPackageJson(dir);
@@ -5500,11 +5772,11 @@ function looksLikeApp(dir) {
 function listWorkspaceApps(workspaceRoot) {
   const candidates = [];
   for (const base of ["apps", "packages"]) {
-    const baseDir = join26(workspaceRoot, base);
-    if (!existsSync25(baseDir)) continue;
-    for (const entry of readdirSync5(baseDir, { withFileTypes: true })) {
+    const baseDir = join27(workspaceRoot, base);
+    if (!existsSync26(baseDir)) continue;
+    for (const entry of readdirSync6(baseDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-      const candidate = join26(baseDir, entry.name);
+      const candidate = join27(baseDir, entry.name);
       if (looksLikeApp(candidate)) {
         candidates.push(`${base}/${entry.name}`);
       }
@@ -6069,18 +6341,18 @@ function extractHostedAssetPaths(indexHtml) {
   return [...assetPaths];
 }
 function readHostedDistSnapshot(distPath) {
-  const resolvedDistPath = distPath ? resolveUserPath(distPath) : join27(process.cwd(), "dist");
-  const indexPath = join27(resolvedDistPath, "index.html");
-  if (!existsSync26(indexPath)) {
+  const resolvedDistPath = distPath ? resolveUserPath(distPath) : join28(process.cwd(), "dist");
+  const indexPath = join28(resolvedDistPath, "index.html");
+  if (!existsSync27(indexPath)) {
     return void 0;
   }
-  const indexHtml = readFileSync19(indexPath, "utf-8");
+  const indexHtml = readFileSync20(indexPath, "utf-8");
   const assetPaths = extractHostedAssetPaths(indexHtml);
   const assets = {};
   for (const assetPath of assetPaths) {
-    const assetFilePath = join27(resolvedDistPath, assetPath.replace(/^[/\\]+/, ""));
-    if (existsSync26(assetFilePath)) {
-      assets[assetPath] = readFileSync19(assetFilePath, "utf-8");
+    const assetFilePath = join28(resolvedDistPath, assetPath.replace(/^[/\\]+/, ""));
+    if (existsSync27(assetFilePath)) {
+      assets[assetPath] = readFileSync20(assetFilePath, "utf-8");
     }
   }
   return {
@@ -6095,7 +6367,7 @@ function isHostedSourceSnapshotFile(path) {
 function readHostedSourceSnapshot(sourcePath) {
   if (!sourcePath) return void 0;
   const resolvedSourcePath = resolveUserPath(sourcePath);
-  if (!existsSync26(resolvedSourcePath)) {
+  if (!existsSync27(resolvedSourcePath)) {
     return void 0;
   }
   const files = {};
@@ -6109,17 +6381,17 @@ function readHostedSourceSnapshot(sourcePath) {
   ]);
   const rootPrefix = basename2(resolvedSourcePath);
   const walk = (absoluteDir, relativeDir) => {
-    for (const entry of readdirSync6(absoluteDir, { withFileTypes: true })) {
+    for (const entry of readdirSync7(absoluteDir, { withFileTypes: true })) {
       if (ignoredDirNames.has(entry.name)) continue;
-      const absolutePath = join27(absoluteDir, entry.name);
-      const relativePath = join27(relativeDir, entry.name).replace(/\\/g, "/");
+      const absolutePath = join28(absoluteDir, entry.name);
+      const relativePath = join28(relativeDir, entry.name).replace(/\\/g, "/");
       if (entry.isDirectory()) {
         walk(absolutePath, relativePath);
         continue;
       }
       if (!entry.isFile()) continue;
       if (!isHostedSourceSnapshotFile(relativePath)) continue;
-      files[relativePath] = readFileSync19(absolutePath, "utf-8");
+      files[relativePath] = readFileSync20(absolutePath, "utf-8");
     }
   };
   walk(resolvedSourcePath, rootPrefix);
@@ -6270,16 +6542,16 @@ async function printRegistryIntelligenceSummary(namespace, jsonOutput = false) {
 }
 async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join27(process.cwd(), "decantr.essence.json");
-  if (!existsSync26(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
-  const essence = JSON.parse(readFileSync19(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const bundle = await client.compileExecutionPacks(essence, namespace ? { namespace } : void 0);
   let writtenContextPaths = [];
   if (writeContext) {
-    const contextDir = join27(process.cwd(), ".decantr", "context");
-    mkdirSync12(contextDir, { recursive: true });
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync13(contextDir, { recursive: true });
     const written = writeExecutionPackBundleArtifacts(
       contextDir,
       bundle
@@ -6304,7 +6576,7 @@ async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput
   console.log(`  Sections: ${typedBundle.sections.length}`);
   console.log(`  Mutations: ${typedBundle.mutations.length}`);
   if (writeContext) {
-    console.log(`  Context bundle: ${join27(process.cwd(), ".decantr", "context")}`);
+    console.log(`  Context bundle: ${join28(process.cwd(), ".decantr", "context")}`);
     console.log(`  Files written: ${writtenContextPaths.length}`);
   }
   console.log("");
@@ -6315,16 +6587,33 @@ async function printHostedExecutionPackBundle(essencePath, namespace, jsonOutput
     console.log(`  ${cyan3(route.path)} -> ${pageLabel} [${patterns}]`);
   }
 }
+function resolvePagePackIdForRoute(essencePath, route) {
+  if (!existsSync27(essencePath)) {
+    throw new Error(`Essence file not found at ${essencePath}`);
+  }
+  const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
+  if (!isV47(essence)) {
+    throw new Error("Route-based pack resolution requires Essence v4.0.0.");
+  }
+  const target = essence.blueprint.routes?.[route];
+  if (!target) {
+    const known = Object.keys(essence.blueprint.routes ?? {}).sort();
+    throw new Error(
+      `Route "${route}" was not found in blueprint.routes. Known routes: ${known.join(", ") || "none"}.`
+    );
+  }
+  return target.page;
+}
 async function printHostedSelectedExecutionPack(packType, id, essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join27(process.cwd(), "decantr.essence.json");
-  if (!existsSync26(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
   if ((packType === "section" || packType === "page" || packType === "mutation") && !id) {
     throw new Error(`Pack type "${packType}" requires an id.`);
   }
-  const essence = JSON.parse(readFileSync19(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const selected = await client.selectExecutionPack(
     {
       essence,
@@ -6335,17 +6624,17 @@ async function printHostedSelectedExecutionPack(packType, id, essencePath, names
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join27(process.cwd(), ".decantr", "context");
-    mkdirSync12(contextDir, { recursive: true });
-    writeFileSync15(
-      join27(contextDir, "pack-manifest.json"),
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync13(contextDir, { recursive: true });
+    writeFileSync16(
+      join28(contextDir, "pack-manifest.json"),
       JSON.stringify(selected.manifest, null, 2) + "\n"
     );
     const manifestEntry = selected.selector.packType === "scaffold" ? selected.manifest.scaffold : selected.selector.packType === "review" ? selected.manifest.review : selected.selector.packType === "section" ? selected.manifest.sections.find((entry) => entry.id === selected.selector.id) : selected.selector.packType === "page" ? selected.manifest.pages.find((entry) => entry.id === selected.selector.id) : selected.manifest.mutations.find((entry) => entry.id === selected.selector.id);
     const markdownFile = manifestEntry?.markdown ?? `${selected.selector.packType}${selected.selector.id ? `-${selected.selector.id}` : ""}-pack.md`;
     const jsonFile = manifestEntry?.json ?? `${selected.selector.packType}${selected.selector.id ? `-${selected.selector.id}` : ""}-pack.json`;
-    writeFileSync15(join27(contextDir, markdownFile), selected.pack.renderedMarkdown);
-    writeFileSync15(join27(contextDir, jsonFile), JSON.stringify(selected.pack, null, 2) + "\n");
+    writeFileSync16(join28(contextDir, markdownFile), selected.pack.renderedMarkdown);
+    writeFileSync16(join28(contextDir, jsonFile), JSON.stringify(selected.pack, null, 2) + "\n");
     writtenContextDir = contextDir;
   }
   if (jsonOutput) {
@@ -6370,20 +6659,20 @@ async function printHostedSelectedExecutionPack(packType, id, essencePath, names
 }
 async function printHostedExecutionPackManifest(essencePath, namespace, jsonOutput = false, writeContext = false) {
   const client = getPublicAPIClient();
-  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join27(process.cwd(), "decantr.essence.json");
-  if (!existsSync26(resolvedPath)) {
+  const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedPath)) {
     throw new Error(`Essence file not found at ${resolvedPath}`);
   }
-  const essence = JSON.parse(readFileSync19(resolvedPath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedPath, "utf-8"));
   const manifest = await client.getExecutionPackManifest(
     essence,
     namespace ? { namespace } : void 0
   );
   let writtenContextDir = null;
   if (writeContext) {
-    const contextDir = join27(process.cwd(), ".decantr", "context");
-    mkdirSync12(contextDir, { recursive: true });
-    writeFileSync15(join27(contextDir, "pack-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    const contextDir = join28(process.cwd(), ".decantr", "context");
+    mkdirSync13(contextDir, { recursive: true });
+    writeFileSync16(join28(contextDir, "pack-manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
     writtenContextDir = contextDir;
   }
   if (jsonOutput) {
@@ -6404,14 +6693,14 @@ async function printHostedExecutionPackManifest(essencePath, namespace, jsonOutp
   }
 }
 async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@official") {
-  const contextDir = join27(projectRoot, ".decantr", "context");
-  const reviewPackPath = join27(contextDir, "review-pack.json");
-  const manifestPath = join27(contextDir, "pack-manifest.json");
-  if (existsSync26(reviewPackPath) && existsSync26(manifestPath)) {
+  const contextDir = join28(projectRoot, ".decantr", "context");
+  const reviewPackPath = join28(contextDir, "review-pack.json");
+  const manifestPath = join28(contextDir, "pack-manifest.json");
+  if (existsSync27(reviewPackPath) && existsSync27(manifestPath)) {
     return { attempted: false, hydrated: false };
   }
-  const essencePath = join27(projectRoot, "decantr.essence.json");
-  if (!existsSync26(essencePath)) {
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  if (!existsSync27(essencePath)) {
     return { attempted: false, hydrated: false };
   }
   const reviewHydration = await hydrateHostedReviewPackIfMissing(projectRoot, namespace);
@@ -6420,9 +6709,9 @@ async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@o
   }
   try {
     const client = getPublicAPIClient();
-    const essence = JSON.parse(readFileSync19(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const bundle = await client.compileExecutionPacks(essence, { namespace });
-    mkdirSync12(contextDir, { recursive: true });
+    mkdirSync13(contextDir, { recursive: true });
     writeExecutionPackBundleArtifacts(contextDir, bundle);
     return { attempted: true, hydrated: true, scope: "bundle" };
   } catch {
@@ -6430,19 +6719,19 @@ async function hydrateHostedExecutionPacksIfMissing(projectRoot, namespace = "@o
   }
 }
 async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@official") {
-  const contextDir = join27(projectRoot, ".decantr", "context");
-  const reviewPackPath = join27(contextDir, "review-pack.json");
-  const manifestPath = join27(contextDir, "pack-manifest.json");
-  if (existsSync26(reviewPackPath) && existsSync26(manifestPath)) {
+  const contextDir = join28(projectRoot, ".decantr", "context");
+  const reviewPackPath = join28(contextDir, "review-pack.json");
+  const manifestPath = join28(contextDir, "pack-manifest.json");
+  if (existsSync27(reviewPackPath) && existsSync27(manifestPath)) {
     return { attempted: false, hydrated: false };
   }
-  const essencePath = join27(projectRoot, "decantr.essence.json");
-  if (!existsSync26(essencePath)) {
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  if (!existsSync27(essencePath)) {
     return { attempted: false, hydrated: false };
   }
   try {
     const client = getPublicAPIClient();
-    const essence = JSON.parse(readFileSync19(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const selected = await client.selectExecutionPack(
       {
         essence,
@@ -6450,14 +6739,14 @@ async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@offic
       },
       { namespace }
     );
-    mkdirSync12(contextDir, { recursive: true });
-    writeFileSync15(join27(contextDir, "review-pack.md"), selected.pack.renderedMarkdown);
-    writeFileSync15(
-      join27(contextDir, "review-pack.json"),
+    mkdirSync13(contextDir, { recursive: true });
+    writeFileSync16(join28(contextDir, "review-pack.md"), selected.pack.renderedMarkdown);
+    writeFileSync16(
+      join28(contextDir, "review-pack.json"),
       JSON.stringify(selected.pack, null, 2) + "\n"
     );
-    if (!existsSync26(manifestPath)) {
-      writeFileSync15(manifestPath, JSON.stringify(selected.manifest, null, 2) + "\n");
+    if (!existsSync27(manifestPath)) {
+      writeFileSync16(manifestPath, JSON.stringify(selected.manifest, null, 2) + "\n");
     }
     return { attempted: true, hydrated: true, scope: "review" };
   } catch {
@@ -6467,17 +6756,17 @@ async function hydrateHostedReviewPackIfMissing(projectRoot, namespace = "@offic
 async function printHostedFileCritique(sourcePath, namespace, jsonOutput = false, essencePath, treatmentsPath) {
   const client = getPublicAPIClient();
   const resolvedSourcePath = resolveUserPath(sourcePath);
-  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join27(process.cwd(), "decantr.essence.json");
-  const resolvedTreatmentsPath = treatmentsPath ? resolveUserPath(treatmentsPath) : join27(process.cwd(), "src", "styles", "treatments.css");
-  if (!existsSync26(resolvedSourcePath)) {
+  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  const resolvedTreatmentsPath = treatmentsPath ? resolveUserPath(treatmentsPath) : join28(process.cwd(), "src", "styles", "treatments.css");
+  if (!existsSync27(resolvedSourcePath)) {
     throw new Error(`Source file not found at ${resolvedSourcePath}`);
   }
-  if (!existsSync26(resolvedEssencePath)) {
+  if (!existsSync27(resolvedEssencePath)) {
     throw new Error(`Essence file not found at ${resolvedEssencePath}`);
   }
-  const code = readFileSync19(resolvedSourcePath, "utf-8");
-  const essence = JSON.parse(readFileSync19(resolvedEssencePath, "utf-8"));
-  const treatmentsCss = existsSync26(resolvedTreatmentsPath) ? readFileSync19(resolvedTreatmentsPath, "utf-8") : void 0;
+  const code = readFileSync20(resolvedSourcePath, "utf-8");
+  const essence = JSON.parse(readFileSync20(resolvedEssencePath, "utf-8"));
+  const treatmentsCss = existsSync27(resolvedTreatmentsPath) ? readFileSync20(resolvedTreatmentsPath, "utf-8") : void 0;
   const report = await client.critiqueFile(
     {
       essence,
@@ -6501,11 +6790,11 @@ async function printHostedFileCritique(sourcePath, namespace, jsonOutput = false
 }
 async function printHostedProjectAudit(namespace, jsonOutput = false, essencePath, distPath, sourcesPath) {
   const client = getPublicAPIClient();
-  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join27(process.cwd(), "decantr.essence.json");
-  if (!existsSync26(resolvedEssencePath)) {
+  const resolvedEssencePath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+  if (!existsSync27(resolvedEssencePath)) {
     throw new Error(`Essence file not found at ${resolvedEssencePath}`);
   }
-  const essence = JSON.parse(readFileSync19(resolvedEssencePath, "utf-8"));
+  const essence = JSON.parse(readFileSync20(resolvedEssencePath, "utf-8"));
   const dist = readHostedDistSnapshot(distPath);
   const sources = readHostedSourceSnapshot(sourcesPath);
   const report = await client.auditProject(
@@ -6523,7 +6812,7 @@ async function printHostedProjectAudit(namespace, jsonOutput = false, essencePat
   console.log(heading2("Hosted Project Audit"));
   console.log(`  Essence: ${resolvedEssencePath}`);
   console.log(
-    `  Dist snapshot: ${dist ? distPath ? resolveUserPath(distPath) : join27(process.cwd(), "dist") : "none"}`
+    `  Dist snapshot: ${dist ? distPath ? resolveUserPath(distPath) : join28(process.cwd(), "dist") : "none"}`
   );
   console.log(
     `  Source snapshot: ${sources && sourcesPath ? resolveUserPath(sourcesPath) : "none"}`
@@ -6542,6 +6831,11 @@ function formatBlueprintPortfolioSummary(value) {
   const alternative = portfolio.recommended_alternative ? `; recommended alternative: ${portfolio.recommended_alternative}` : "";
   return `Blueprint set: ${labels.join(" + ")}${alternative}`;
 }
+function formatRegistryListIdentifier(item) {
+  if (!item || typeof item !== "object") return String(item ?? "");
+  const record = item;
+  return typeof record.slug === "string" && record.slug || typeof record.id === "string" && record.id || typeof record.name === "string" && record.name || "";
+}
 function printBlueprintPortfolioNotice(blueprint) {
   const portfolio = getBlueprintPortfolioMetadata(blueprint);
   if (!portfolio) return;
@@ -6600,42 +6894,151 @@ async function cmdSearch(query, type, sort, recommended, intelligenceSource, blu
     console.log(dim3(`Search failed. API may be unavailable.`));
   }
 }
-async function cmdSuggest(query, type) {
-  const apiClient = getAPIClient();
-  const searchType = type || "pattern";
-  try {
-    const response = await apiClient.search({ q: query, type: searchType });
-    const results = response.results;
-    if (results.length === 0) {
-      console.log(dim3(`No suggestions for "${query}"`));
-      console.log("");
-      console.log("Try:");
-      console.log(`  ${cyan3("decantr list patterns")} - see all patterns`);
-      console.log(`  ${cyan3("decantr search <broader-term>")} - broaden your search`);
-      return;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function patternCandidateFromRegistryItem(item, source) {
+  const record = item;
+  const data = isRecord(record.data) ? record.data : record;
+  const slug = typeof record.slug === "string" && record.slug || typeof data.slug === "string" && data.slug || typeof data.id === "string" && data.id || typeof record.id === "string" && record.id || "pattern";
+  return patternToDiscoveryCandidate(
+    {
+      ...data,
+      id: typeof data.id === "string" ? data.id : slug,
+      slug,
+      name: typeof data.name === "string" ? data.name : typeof record.name === "string" ? record.name : slug,
+      description: typeof data.description === "string" ? data.description : typeof record.description === "string" ? record.description : void 0
+    },
+    { source, slug }
+  );
+}
+function readSuggestCodeContext(route, file) {
+  const pieces = [];
+  if (file) {
+    const resolved = isAbsolute(file) ? file : join28(process.cwd(), file);
+    if (existsSync27(resolved)) {
+      pieces.push(readFileSync20(resolved, "utf-8"));
     }
-    console.log(heading2(`Suggestions for "${query}"`));
-    const queryLower = query.toLowerCase();
-    const exact = results.filter((r) => r.slug.toLowerCase().includes(queryLower));
-    const related = results.filter((r) => !r.slug.toLowerCase().includes(queryLower));
-    if (exact.length > 0) {
-      console.log(`${BOLD7}Direct matches:${RESET14}`);
-      for (const r of exact.slice(0, 3)) {
-        console.log(`  ${cyan3(r.slug)} - ${r.description || ""}`);
+  }
+  if (route) {
+    const analysisPath = join28(process.cwd(), ".decantr", "analysis.json");
+    if (existsSync27(analysisPath)) {
+      try {
+        const analysis = JSON.parse(readFileSync20(analysisPath, "utf-8"));
+        const routeEntry = analysis.routes?.routes?.find((entry) => entry.path === route);
+        if (routeEntry?.file) {
+          const resolved = join28(process.cwd(), routeEntry.file);
+          if (existsSync27(resolved)) {
+            pieces.push(readFileSync20(resolved, "utf-8"));
+          }
+        }
+      } catch {
       }
-      console.log("");
     }
-    if (related.length > 0) {
-      console.log(`${BOLD7}Related:${RESET14}`);
-      for (const r of related.slice(0, 5)) {
-        console.log(`  ${cyan3(r.slug)} - ${r.description || ""}`);
-      }
-      console.log("");
+  }
+  return pieces.join("\n\n").slice(0, 2e4);
+}
+async function loadPatternDiscoveryCandidates(registryClient) {
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (candidate) => {
+    const key = candidate.slug || candidate.id;
+    if (seen.has(key)) return;
+    seen.add(key);
+    candidates.push(candidate);
+  };
+  const bundledPatterns = loadBundledContentList("patterns");
+  for (const entry of bundledPatterns) {
+    add(patternToDiscoveryCandidate(entry.data, { source: "bundled", slug: entry.id }));
+  }
+  try {
+    const result = await registryClient.fetchContentList("patterns");
+    for (const item of result.data.items) {
+      const source = result.source.type === "api" ? "hosted" : result.source.type;
+      add(patternCandidateFromRegistryItem(item, source));
     }
-    console.log(dim3(`Use "decantr get pattern <id>" for full details`));
   } catch {
-    console.log(dim3(`Suggestion search failed. API may be unavailable.`));
   }
+  for (const item of registryClient.listCustomContent("patterns")) {
+    add(patternCandidateFromRegistryItem(item, "custom"));
+  }
+  return candidates;
+}
+async function cmdSuggest(query, options = {}) {
+  const searchType = options.type || "pattern";
+  if (searchType !== "pattern" && searchType !== "patterns") {
+    const apiClient = getAPIClient();
+    try {
+      const response = await apiClient.search({ q: query, type: searchType });
+      const results = response.results;
+      if (results.length === 0) {
+        console.log(dim3(`No suggestions for "${query}"`));
+        return;
+      }
+      console.log(heading2(`Suggestions for "${query}"`));
+      for (const r of results.slice(0, 8)) {
+        console.log(`  ${cyan3(r.slug)} - ${r.description || r.name || ""}`);
+      }
+      return;
+    } catch {
+      console.log(dim3(`Suggestion search failed. API may be unavailable.`));
+      return;
+    }
+  }
+  const registryClient = new RegistryClient({
+    cacheDir: join28(process.cwd(), ".decantr", "cache")
+  });
+  const code = options.fromCode || options.file ? readSuggestCodeContext(options.route, options.file) : "";
+  const candidates = await loadPatternDiscoveryCandidates(registryClient);
+  const matches = rankPatternCandidates(
+    {
+      query,
+      route: options.route,
+      code,
+      limit: 10
+    },
+    candidates
+  );
+  if (matches.length === 0) {
+    console.log(dim3(`No pattern suggestions for "${query}"`));
+    console.log("");
+    console.log("Try:");
+    console.log(`  ${cyan3("decantr list patterns")} - browse slug, name, domain, and source`);
+    console.log(
+      `  ${cyan3('decantr suggest "<broader description>" --from-code --route <route>')} - rank from observed code`
+    );
+    return;
+  }
+  const contextBits = [
+    options.route ? `route ${options.route}` : null,
+    options.file ? `file ${options.file}` : null,
+    code ? "code context" : null
+  ].filter((entry) => Boolean(entry));
+  console.log(
+    heading2(
+      `Pattern suggestions for "${query}"${contextBits.length > 0 ? ` (${contextBits.join(", ")})` : ""}`
+    )
+  );
+  for (const match of matches.slice(0, 8)) {
+    const candidate = match.candidate;
+    const slug = candidate.slug || candidate.id;
+    const details = [
+      candidate.name && candidate.name !== slug ? candidate.name : null,
+      candidate.domain || candidate.category || null,
+      candidate.source || null
+    ].filter(Boolean);
+    console.log(
+      `  ${cyan3(slug)}  score ${match.score}${details.length > 0 ? `  ${dim3(details.join(" | "))}` : ""}`
+    );
+    if (candidate.description) {
+      console.log(`    ${dim3(candidate.description)}`);
+    }
+    if (match.reasons.length > 0) {
+      console.log(`    ${dim3(`why: ${match.reasons.slice(0, 2).join("; ")}`)}`);
+    }
+  }
+  console.log("");
+  console.log(dim3('Use "decantr get pattern <slug>" for full details.'));
 }
 async function cmdGet(type, id) {
   if (!isGetContentType(type)) {
@@ -6645,26 +7048,16 @@ async function cmdGet(type, id) {
   }
   const apiType = CONTENT_TYPE_TO_API_CONTENT_TYPE3[type];
   const registryClient = new RegistryClient({
-    cacheDir: join27(process.cwd(), ".decantr", "cache")
+    cacheDir: join28(process.cwd(), ".decantr", "cache")
   });
   const result = await registryClient.fetchContentItem(apiType, id);
   if (result) {
     console.log(JSON.stringify(result.data, null, 2));
     return;
   }
-  const currentDir = dirname4(fileURLToPath2(import.meta.url));
-  const bundledCandidates = [
-    join27(currentDir, "bundled", apiType, `${id}.json`),
-    // Running from src/
-    join27(currentDir, "..", "src", "bundled", apiType, `${id}.json`),
-    // Running from dist/
-    join27(currentDir, "..", "bundled", apiType, `${id}.json`)
-    // Alternative dist layout
-  ];
-  const bundledPath = bundledCandidates.find((p) => existsSync26(p)) || null;
-  if (bundledPath) {
-    const data = JSON.parse(readFileSync19(bundledPath, "utf-8"));
-    console.log(JSON.stringify(data, null, 2));
+  const bundled = loadBundledContentItem(apiType, id);
+  if (bundled) {
+    console.log(JSON.stringify(bundled.data, null, 2));
     return;
   }
   console.error(error3(`${type} "${id}" not found.`));
@@ -6672,10 +7065,10 @@ async function cmdGet(type, id) {
   return;
 }
 async function cmdValidate(path) {
-  const essencePath = path || join27(process.cwd(), "decantr.essence.json");
+  const essencePath = path || join28(process.cwd(), "decantr.essence.json");
   let raw;
   try {
-    raw = readFileSync19(essencePath, "utf-8");
+    raw = readFileSync20(essencePath, "utf-8");
   } catch {
     console.error(error3(`Could not read ${essencePath}`));
     process.exitCode = 1;
@@ -6742,7 +7135,7 @@ async function cmdList(type, sort, recommended, intelligenceSource, blueprintSet
     return;
   }
   const registryClient = new RegistryClient({
-    cacheDir: join27(process.cwd(), ".decantr", "cache")
+    cacheDir: join28(process.cwd(), ".decantr", "cache")
   });
   const result = await registryClient.fetchContentList(
     type,
@@ -6752,7 +7145,13 @@ async function cmdList(type, sort, recommended, intelligenceSource, blueprintSet
     intelligenceSource,
     blueprintSet
   );
-  const items = result.data.items;
+  const bundledPatternItems = type === "patterns" ? loadBundledContentList("patterns").map((entry) => ({
+    ...entry.data,
+    id: entry.data.id || entry.id,
+    slug: entry.data.slug || entry.id,
+    source: "bundled"
+  })) : [];
+  const items = type === "patterns" ? [...bundledPatternItems, ...result.data.items] : result.data.items;
   if (items.length === 0) {
     console.log(dim3(`No ${type} found.`));
     return;
@@ -6779,7 +7178,21 @@ async function cmdList(type, sort, recommended, intelligenceSource, blueprintSet
   } else {
     console.log(heading2(`${items.length} ${type} found`));
     for (const item of items) {
-      console.log(`  ${cyan3(item.id)}  ${dim3(item.description || item.name || "")}`);
+      if (type === "patterns") {
+        const pattern = item;
+        const slug = pattern.slug || pattern.id;
+        const domain = pattern.domain || pattern.category || pattern.tags?.[0] || "general";
+        const source = pattern.source || (result.source.type === "api" ? "hosted" : result.source.type);
+        const label = [pattern.name && pattern.name !== slug ? pattern.name : null, domain, source].filter(Boolean).join(" | ");
+        console.log(`  ${cyan3(slug)}  ${dim3(label)}`);
+        if (pattern.description) {
+          console.log(`    ${dim3(pattern.description)}`);
+        }
+      } else {
+        console.log(
+          `  ${cyan3(formatRegistryListIdentifier(item))}  ${dim3(item.description || item.name || "")}`
+        );
+      }
       const intelligenceSummary = formatIntelligenceSummary(
         item.intelligence
       );
@@ -6805,10 +7218,10 @@ ${CYAN8}Telemetry enabled.${RESET14} Decantr will send privacy-filtered CLI prod
 }
 function readCliPackageVersion() {
   const here = dirname4(fileURLToPath2(import.meta.url));
-  const candidates = [join27(here, "..", "package.json"), join27(here, "..", "..", "package.json")];
+  const candidates = [join28(here, "..", "package.json"), join28(here, "..", "..", "package.json")];
   for (const candidate of candidates) {
     try {
-      const pkg = JSON.parse(readFileSync19(candidate, "utf-8"));
+      const pkg = JSON.parse(readFileSync20(candidate, "utf-8"));
       if (pkg.version) return pkg.version;
     } catch {
     }
@@ -6819,19 +7232,19 @@ function timestampForFile() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
 function backupExistingEssence(projectRoot, label) {
-  const essencePath = join27(projectRoot, "decantr.essence.json");
-  if (!existsSync26(essencePath)) return null;
-  const backupPath = join27(
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  if (!existsSync27(essencePath)) return null;
+  const backupPath = join28(
     projectRoot,
     `decantr.essence.${label}.${timestampForFile()}.backup.json`
   );
-  writeFileSync15(backupPath, readFileSync19(essencePath, "utf-8"), "utf-8");
+  writeFileSync16(backupPath, readFileSync20(essencePath, "utf-8"), "utf-8");
   return backupPath;
 }
 function writeBrownfieldProjectJson(input) {
-  const decantrDir = join27(input.projectRoot, ".decantr");
-  mkdirSync12(join27(decantrDir, "context"), { recursive: true });
-  mkdirSync12(join27(decantrDir, "cache"), { recursive: true });
+  const decantrDir = join28(input.projectRoot, ".decantr");
+  mkdirSync13(join28(decantrDir, "context"), { recursive: true });
+  mkdirSync13(join28(decantrDir, "cache"), { recursive: true });
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const projectJson = {
     detected: {
@@ -6872,7 +7285,7 @@ function writeBrownfieldProjectJson(input) {
       }
     }
   };
-  writeFileSync15(join27(decantrDir, "project.json"), JSON.stringify(projectJson, null, 2) + "\n");
+  writeFileSync16(join28(decantrDir, "project.json"), JSON.stringify(projectJson, null, 2) + "\n");
 }
 async function applyAcceptedBrownfieldProposal(input) {
   const proposal = readBrownfieldProposal(input.projectRoot);
@@ -6888,8 +7301,8 @@ async function applyAcceptedBrownfieldProposal(input) {
     process.exitCode = 1;
     return;
   }
-  const essencePath = join27(input.projectRoot, "decantr.essence.json");
-  const hasEssence = existsSync26(essencePath);
+  const essencePath = join28(input.projectRoot, "decantr.essence.json");
+  const hasEssence = existsSync27(essencePath);
   let essence;
   let backupPath = null;
   if (input.mode === "accept" && hasEssence) {
@@ -6903,7 +7316,7 @@ async function applyAcceptedBrownfieldProposal(input) {
     return;
   }
   if (input.mode === "merge" && hasEssence) {
-    const existing = JSON.parse(readFileSync19(essencePath, "utf-8"));
+    const existing = JSON.parse(readFileSync20(essencePath, "utf-8"));
     if (!isV47(existing)) {
       console.log(
         error3(
@@ -6940,9 +7353,9 @@ async function applyAcceptedBrownfieldProposal(input) {
     assistantBridge: input.assistantBridge,
     mode: input.mode
   });
-  writeFileSync15(essencePath, JSON.stringify(essence, null, 2) + "\n", "utf-8");
+  writeFileSync16(essencePath, JSON.stringify(essence, null, 2) + "\n", "utf-8");
   const registryClient = new RegistryClient({
-    cacheDir: join27(input.projectRoot, ".decantr", "cache"),
+    cacheDir: join28(input.projectRoot, ".decantr", "cache"),
     offline: true,
     projectRoot: input.projectRoot
   });
@@ -7096,7 +7509,7 @@ async function cmdInit(args) {
     }
   }
   const registryClient = new RegistryClient({
-    cacheDir: join27(projectRoot, ".decantr", "cache"),
+    cacheDir: join28(projectRoot, ".decantr", "cache"),
     apiUrl: args.registry,
     offline: args.offline,
     projectRoot
@@ -7426,7 +7839,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET14}`);
   if (appliedRuleFiles.length > 0) {
     console.log(`    ${dim3(`Rule bridge applied: ${appliedRuleFiles.join(", ")}`)}`);
   }
-  if (!existsSync26(join27(projectRoot, "package.json"))) {
+  if (!existsSync27(join28(projectRoot, "package.json"))) {
     console.log("");
     console.log(
       dim3(`  Note: ${cyan3("decantr init")} created Decantr contract/context files only.`)
@@ -7437,7 +7850,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET14}`);
       )
     );
   }
-  const hasCompiledPacks = existsSync26(join27(projectRoot, ".decantr", "context", "scaffold-pack.md"));
+  const hasCompiledPacks = existsSync27(join28(projectRoot, ".decantr", "context", "scaffold-pack.md"));
   console.log("");
   console.log("  Next steps:");
   if (hasCompiledPacks) {
@@ -7477,7 +7890,7 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET14}`);
   console.log(`    ${cyan3("decantr upgrade")}    Update to latest patterns`);
   console.log(`    ${cyan3("decantr check")}      Detect drift issues`);
   console.log(`    ${cyan3("decantr migrate --to v4")} Migrate older essence files to v4`);
-  const essenceContent = readFileSync19(result.essencePath, "utf-8");
+  const essenceContent = readFileSync20(result.essencePath, "utf-8");
   const essence = JSON.parse(essenceContent);
   const validation = validateEssence2(essence);
   if (!validation.valid) {
@@ -7533,16 +7946,16 @@ Validation warnings: ${validation.errors.join(", ")}`));
 }
 async function cmdStatus() {
   const projectRoot = process.cwd();
-  const essencePath = join27(projectRoot, "decantr.essence.json");
-  const projectJsonPath = join27(projectRoot, ".decantr", "project.json");
+  const essencePath = join28(projectRoot, "decantr.essence.json");
+  const projectJsonPath = join28(projectRoot, ".decantr", "project.json");
   console.log(heading2("Decantr Project Status"));
-  if (!existsSync26(essencePath)) {
+  if (!existsSync27(essencePath)) {
     console.log(`${RED11}No decantr.essence.json found.${RESET14}`);
     console.log(dim3('Run "decantr init" to create one.'));
     return;
   }
   try {
-    const essence = JSON.parse(readFileSync19(essencePath, "utf-8"));
+    const essence = JSON.parse(readFileSync20(essencePath, "utf-8"));
     const validation = validateEssence2(essence);
     const essenceVersion = isV47(essence) ? "v4" : "legacy";
     console.log(`${BOLD7}Essence:${RESET14}`);
@@ -7590,9 +8003,9 @@ async function cmdStatus() {
   }
   console.log("");
   console.log(`${BOLD7}Sync Status:${RESET14}`);
-  if (existsSync26(projectJsonPath)) {
+  if (existsSync27(projectJsonPath)) {
     try {
-      const projectJson = JSON.parse(readFileSync19(projectJsonPath, "utf-8"));
+      const projectJson = JSON.parse(readFileSync20(projectJsonPath, "utf-8"));
       const syncStatus = projectJson.sync?.status || "unknown";
       const lastSync = projectJson.sync?.lastSync || "never";
       const source = projectJson.sync?.registrySource || "unknown";
@@ -7610,7 +8023,7 @@ async function cmdStatus() {
 }
 async function cmdSync() {
   const projectRoot = process.cwd();
-  const cacheDir = join27(projectRoot, ".decantr", "cache");
+  const cacheDir = join28(projectRoot, ".decantr", "cache");
   console.log(heading2("Syncing registry content..."));
   const result = await syncRegistry(cacheDir);
   if (result.synced.length > 0) {
@@ -7805,14 +8218,14 @@ ${BOLD7}Examples:${RESET14}
         process.exitCode = 1;
         return;
       }
-      const themePath = join27(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
-      if (!existsSync26(themePath)) {
+      const themePath = join28(projectRoot, ".decantr", "custom", "themes", `${name}.json`);
+      if (!existsSync27(themePath)) {
         console.error(error3(`Theme "${name}" not found at ${themePath}`));
         process.exitCode = 1;
         return;
       }
       try {
-        const theme = JSON.parse(readFileSync19(themePath, "utf-8"));
+        const theme = JSON.parse(readFileSync20(themePath, "utf-8"));
         const result = validateCustomTheme(theme);
         if (result.valid) {
           console.log(success3(`Custom theme "${name}" is valid`));
@@ -7896,7 +8309,7 @@ ${BOLD7}Usage:${RESET14}
   decantr check --brownfield
   decantr sync-drift
   decantr search <query> [--type <type>] [--sort <recommended|recent|name>] [--recommended] [--source <authored|benchmark|hybrid>]
-  decantr suggest <query> [--type <type>]
+  decantr suggest <query> [--type <type>] [--route <route>] [--file <path>] [--from-code]
   decantr get <type> <id>
   decantr list <type> [--sort <recommended|recent|name>] [--recommended] [--source <authored|benchmark|hybrid>]
   decantr showcase [manifest|shortlist|verification] [--json]
@@ -7906,7 +8319,8 @@ ${BOLD7}Usage:${RESET14}
   decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]
   decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]
   decantr health [--format text|json|markdown] [--ci] [--fail-on error|warn|none]
-  decantr health --evidence [--browser] [--design-tokens <path>]
+  decantr health --evidence [--browser] [--base-url <url>] [--design-tokens <path>]
+  decantr health --save-baseline | --since-baseline
   decantr health init-ci [--force] [--project <path>] [--workspace] [--fail-on <error|warn|none>] [--cli-version <version|latest>]
   decantr workspace list [--json]
   decantr workspace health [--json] [--changed --since origin/main]
@@ -8013,7 +8427,7 @@ ${BOLD7}Examples:${RESET14}
   decantr check --brownfield
   decantr sync-drift
   decantr search dashboard
-  decantr suggest leaderboard
+  decantr suggest "recipe feed with infinite scroll" --route /feed --from-code
   decantr list patterns
   decantr showcase shortlist
   decantr showcase verification --json
@@ -8030,7 +8444,7 @@ ${BOLD7}Examples:${RESET14}
 ${BOLD7}Workflow Model:${RESET14}
   ${cyan3("Greenfield blueprint")}   decantr new my-app --blueprint=X --workflow=greenfield --adoption=decantr-css
   ${cyan3("Greenfield contract")}    decantr init --workflow=greenfield --adoption=contract-only
-  ${cyan3("Brownfield adoption")}    decantr analyze -> decantr init --existing --accept-proposal -> decantr check --brownfield
+  ${cyan3("Brownfield adoption")}    decantr analyze -> decantr init --existing --accept-proposal -> decantr health --browser --evidence
   ${cyan3("Hybrid composition")}     decantr add/remove, decantr theme switch, decantr registry, decantr upgrade
 
 ${BOLD7}Bootstrap adapters:${RESET14}
@@ -8070,6 +8484,9 @@ ${BOLD7}Usage:${RESET14}
   decantr health --ci [--fail-on error|warn|none]
   decantr health --prompt <finding-id>
   decantr health --evidence [--browser] [--design-tokens <path>]
+  decantr health --browser --base-url <url> --evidence
+  decantr health --save-baseline
+  decantr health --since-baseline
   decantr health init-ci [--force] [--project <path>] [--workspace] [--fail-on error|warn|none] [--cli-version <version|latest>]
 
 ${BOLD7}Options:${RESET14}
@@ -8082,6 +8499,9 @@ ${BOLD7}Options:${RESET14}
   --prompt      Print an AI-ready remediation prompt for a finding
   --evidence    Emit a local Evidence Bundle JSON artifact
   --browser     Include optional rendered-browser setup/evidence checks
+  --base-url    Base URL for rendered route checks when --browser is enabled
+  --save-baseline Save the current health state for later comparison
+  --since-baseline Compare this run to .decantr/health-baseline.json
   --design-tokens Compare against a Figma/Tokens Studio JSON export
 
 ${BOLD7}Examples:${RESET14}
@@ -8165,6 +8585,61 @@ ${BOLD7}Examples:${RESET14}
   decantr studio --workspace
 `);
 }
+function cmdRegistryHelp() {
+  console.log(`
+${BOLD7}decantr registry${RESET14} \u2014 Read hosted execution packs and registry intelligence
+
+${BOLD7}Usage:${RESET14}
+  decantr registry summary [--namespace <namespace>] [--json]
+  decantr registry compile-packs [path] [--namespace <namespace>] [--json] [--write-context]
+  decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]
+  decantr registry get-pack page --route <route> [--namespace <namespace>] [--json] [--essence <path>]
+  decantr registry critique-file <file> [--namespace <namespace>] [--json] [--essence <path>] [--treatments <path>]
+  decantr registry audit-project [--namespace <namespace>] [--json] [--essence <path>] [--dist <path>] [--sources <dir>]
+`);
+}
+function cmdThemeHelp() {
+  console.log(`
+${BOLD7}decantr theme${RESET14} \u2014 Manage custom themes
+
+${BOLD7}Usage:${RESET14}
+  decantr theme create <name>
+  decantr theme create <name> --guided
+  decantr theme list
+  decantr theme validate <name>
+  decantr theme delete <name>
+  decantr theme import <path>
+`);
+}
+function printCommandHelp(command, args) {
+  if (!isCommandHelpRequest(args)) return false;
+  switch (command) {
+    case "health":
+      cmdHealthHelp();
+      return true;
+    case "content-health":
+      cmdContentHealthHelp();
+      return true;
+    case "studio":
+      cmdStudioHelp();
+      return true;
+    case "workspace":
+      cmdWorkspaceHelp();
+      return true;
+    case "rules":
+      cmdRulesHelp();
+      return true;
+    case "registry":
+      cmdRegistryHelp();
+      return true;
+    case "theme":
+      cmdThemeHelp();
+      return true;
+    default:
+      cmdHelp();
+      return true;
+  }
+}
 async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -8175,10 +8650,10 @@ async function main() {
   if (command === "--version" || command === "-v" || command === "version") {
     try {
       const here = dirname4(fileURLToPath2(import.meta.url));
-      const candidates = [join27(here, "..", "package.json"), join27(here, "..", "..", "package.json")];
+      const candidates = [join28(here, "..", "package.json"), join28(here, "..", "..", "package.json")];
       for (const candidate of candidates) {
-        if (existsSync26(candidate)) {
-          const pkg = JSON.parse(readFileSync19(candidate, "utf-8"));
+        if (existsSync27(candidate)) {
+          const pkg = JSON.parse(readFileSync20(candidate, "utf-8"));
           if (pkg.version) {
             console.log(pkg.version);
             return;
@@ -8193,6 +8668,9 @@ async function main() {
     }
     return;
   }
+  if (printCommandHelp(command, args)) {
+    return;
+  }
   switch (command) {
     case "new": {
       const newName = args[1];
@@ -8290,7 +8768,7 @@ async function main() {
           `${YELLOW9}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET14}`
         );
       }
-      const { cmdHeal } = await import("./heal-M6PRCIIF.js");
+      const { cmdHeal } = await import("./heal-ZYD6NVGE.js");
       const telemetryFlag = args.includes("--telemetry");
       const brownfieldFlag = args.includes("--brownfield");
       await cmdHeal(process.cwd(), { telemetry: telemetryFlag, brownfield: brownfieldFlag });
@@ -8302,7 +8780,7 @@ async function main() {
           cmdHealthHelp();
           break;
         }
-        const { cmdHealth, parseHealthArgs } = await import("./health-ZXOPGNBZ.js");
+        const { cmdHealth, parseHealthArgs } = await import("./health-ETZXWGTW.js");
         await cmdHealth(process.cwd(), parseHealthArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -8330,7 +8808,7 @@ async function main() {
           cmdStudioHelp();
           break;
         }
-        const { cmdStudio, parseStudioArgs } = await import("./studio-LHQXHBE7.js");
+        const { cmdStudio, parseStudioArgs } = await import("./studio-MKLBUC3A.js");
         await cmdStudio(process.cwd(), parseStudioArgs(args));
       } catch (e) {
         console.error(error3(e.message));
@@ -8344,7 +8822,7 @@ async function main() {
           cmdWorkspaceHelp();
           break;
         }
-        const { cmdWorkspace } = await import("./workspace-MOLAGT2B.js");
+        const { cmdWorkspace } = await import("./workspace-KSFWRZEX.js");
         await cmdWorkspace(process.cwd(), args);
       } catch (e) {
         console.error(error3(e.message));
@@ -8427,13 +8905,22 @@ async function main() {
     case "suggest": {
       const query = args[1];
       if (!query) {
-        console.error(error3("Usage: decantr suggest <query> [--type <type>]"));
+        console.error(
+          error3(
+            "Usage: decantr suggest <query> [--type <type>] [--route <route>] [--file <path>] [--from-code]"
+          )
+        );
         process.exitCode = 1;
         return;
       }
       const typeIdx = args.indexOf("--type");
       const type = typeIdx !== -1 ? args[typeIdx + 1] : void 0;
-      await cmdSuggest(query, type);
+      const routeIdx = args.indexOf("--route");
+      const route = routeIdx !== -1 ? args[routeIdx + 1] : void 0;
+      const fileIdx = args.indexOf("--file");
+      const file = fileIdx !== -1 ? args[fileIdx + 1] : void 0;
+      const fromCode = args.includes("--from-code");
+      await cmdSuggest(query, { type, route, file, fromCode });
       break;
     }
     case "get": {
@@ -8600,7 +9087,9 @@ async function main() {
         const essenceIdx = args.indexOf("--essence");
         const essencePath = essenceIdx !== -1 ? args[essenceIdx + 1] : void 0;
         const packType = args[2] && !args[2].startsWith("--") ? args[2] : void 0;
-        const id = args[3] && !args[3].startsWith("--") ? args[3] : void 0;
+        const routeIdx = args.indexOf("--route");
+        const route = routeIdx !== -1 ? args[routeIdx + 1] : void 0;
+        let id = args[3] && !args[3].startsWith("--") ? args[3] : void 0;
         if (!packType || !["manifest", "scaffold", "review", "section", "page", "mutation"].includes(packType)) {
           console.error(
             `${RED11}Usage: decantr registry get-pack <manifest|scaffold|review|section|page|mutation> [id] [--namespace <namespace>] [--json] [--essence <path>] [--write-context]${RESET14}`
@@ -8612,6 +9101,10 @@ async function main() {
           await printHostedExecutionPackManifest(essencePath, namespace, jsonOutput, writeContext);
           break;
         }
+        if (packType === "page" && route && !id) {
+          const resolvedPath = essencePath ? resolveUserPath(essencePath) : join28(process.cwd(), "decantr.essence.json");
+          id = resolvePagePackIdForRoute(resolvedPath, route);
+        }
         await printHostedSelectedExecutionPack(
           packType,
           id,