@decantr/cli 1.7.29 → 1.8.0

package/README.md

@@ -60,6 +60,7 @@ Brownfield analysis also writes `.decantr/doctrine-map.json`, a ranked source-pr
 - supports explicit workflow lanes: greenfield blueprint, greenfield contract-only, brownfield adoption, and hybrid composition
 - generates execution-pack context files for AI coding assistants
 - audits projects against Decantr contracts
+- produces local Project Health reports and a localhost Studio dashboard for end-user drift triage
 - searches the registry and showcase benchmark corpus
 - validates, refreshes, and maintains `decantr.essence.json`
 
@@ -77,10 +78,36 @@ decantr rules apply
 decantr magic "AI-native analytics workspace"
 decantr audit
 decantr check
+decantr health --ci --fail-on error
+decantr studio --port 4319 --host 127.0.0.1
 decantr registry summary --namespace @official --json
 decantr showcase verification --json
 ```
 
+## Project Health And Studio
+
+`decantr health` is the local project observability command. It composes the existing verifier audit, guard checks, brownfield route drift checks, runtime evidence, and execution-pack files into a `ProjectHealthReport` with a status, score, route summary, pack summary, findings, and AI-ready remediation prompts.
+
+```bash
+decantr health
+decantr health --format json
+decantr health --markdown --output health.md
+decantr health --ci --fail-on error
+decantr health --ci --fail-on warn
+decantr health --prompt <finding-id>
+```
+
+Use `--json` for machines and schema validation, `--markdown` for CI summaries, and `--prompt <finding-id>` when you want a scoped remediation prompt for an AI assistant. `--ci --fail-on error` fails only when blocking errors exist; `--ci --fail-on warn` also fails on warnings.
+
+`decantr studio` starts a local-only dashboard powered by the same report. It uses Node built-ins only and serves `GET /`, `GET /api/health`, and `POST /api/refresh`.
+
+```bash
+decantr studio
+decantr studio --port 4319 --host 127.0.0.1
+```
+
+Studio is for local triage, not Decantr admin telemetry. The tabs cover Overview, Routes, Drift, Findings, Remediation, CI, and Packs without uploading source code, prompts, file paths, or project data.
+
 ## Greenfield Certification
 
 Use the built-in certification harness before releases when you want to prove that representative blueprints still scaffold into runnable starter projects:
@@ -155,6 +182,8 @@ Recommended read order for AI-assisted scaffolding:
 
 Treat the compiled execution packs as the source of truth. Use the narrative docs as secondary explanation, start with the shell and route structure first, and run `decantr check` plus `decantr audit` after implementation.
 
+For a broader health pass, run `decantr health` after `refresh`, before opening a pull request, or inside CI. Findings include remediation commands and can be turned into focused AI prompts with `decantr health --prompt <finding-id>`.
+
 For cold-start harness or certification runs, use only the scaffolded workspace files as the contract. If local scaffold files disagree, stop and report the mismatch rather than relying on repo-global Decantr assumptions.
 
 ## Related Packages

package/dist/bin.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import "./chunk-US6RK5QT.js";
-import "./chunk-HULA6E2D.js";
+import "./chunk-Y45MCRGI.js";
+import "./chunk-USOO77A5.js";
 import "./chunk-DI2PLOJ6.js";

package/dist/chunk-DONMNPS7.js

@@ -0,0 +1,466 @@
+import {
+  collectCheckIssues
+} from "./chunk-RSDCWAHD.js";
+
+// src/commands/health.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  auditProject
+} from "@decantr/verifier";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+var RED = "\x1B[31m";
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+var YELLOW = "\x1B[33m";
+var PROJECT_HEALTH_SCHEMA_URL = "https://decantr.ai/schemas/project-health-report.v1.json";
+function readProjectMetadata(projectRoot) {
+  const projectJsonPath = join(projectRoot, ".decantr", "project.json");
+  if (!existsSync(projectJsonPath)) {
+    return { workflowMode: null, adoptionMode: null, autoBrownfield: false };
+  }
+  try {
+    const data = JSON.parse(readFileSync(projectJsonPath, "utf-8"));
+    const workflowMode = typeof data.initialized?.workflowMode === "string" ? data.initialized.workflowMode : null;
+    const adoptionMode = typeof data.initialized?.adoptionMode === "string" ? data.initialized.adoptionMode : null;
+    return {
+      workflowMode,
+      adoptionMode,
+      autoBrownfield: workflowMode === "brownfield-attach"
+    };
+  } catch {
+    return { workflowMode: null, adoptionMode: null, autoBrownfield: false };
+  }
+}
+function collectDeclaredRoutes(essence) {
+  if (!essence || typeof essence !== "object") return [];
+  const record = essence;
+  const blueprint = record.blueprint;
+  if (!blueprint || typeof blueprint !== "object") return [];
+  const bp = blueprint;
+  const routes = /* @__PURE__ */ new Set();
+  if (bp.routes && typeof bp.routes === "object" && !Array.isArray(bp.routes)) {
+    for (const route of Object.keys(bp.routes)) {
+      routes.add(route);
+    }
+  }
+  const flatPages = Array.isArray(bp.pages) ? bp.pages : [];
+  for (const page of flatPages) {
+    if (page && typeof page === "object") {
+      const route = page.route;
+      if (typeof route === "string") routes.add(route);
+    }
+  }
+  const sections = Array.isArray(bp.sections) ? bp.sections : [];
+  for (const section of sections) {
+    if (!section || typeof section !== "object") continue;
+    const pages = section.pages;
+    if (!Array.isArray(pages)) continue;
+    for (const page of pages) {
+      if (page && typeof page === "object") {
+        const route = page.route;
+        if (typeof route === "string") routes.add(route);
+      }
+    }
+  }
+  return [...routes].sort();
+}
+function severityFromCheckIssue(issue) {
+  return issue.type === "error" ? "error" : "warn";
+}
+function sourceFromAuditFinding(finding) {
+  const category = finding.category.toLowerCase();
+  const id = finding.id.toLowerCase();
+  const rule = finding.rule?.toLowerCase() ?? "";
+  if (category.includes("runtime") || category.includes("document") || category.includes("performance")) {
+    return "runtime";
+  }
+  if (category.includes("pack") || category.includes("review contract")) {
+    return "pack";
+  }
+  if (category.includes("interaction") || id.includes("interaction") || rule.includes("interaction")) {
+    return "interaction";
+  }
+  return "audit";
+}
+function sourceFromCheckIssue(issue) {
+  if (issue.rule.startsWith("brownfield-")) return "brownfield";
+  if (issue.rule.includes("interaction")) return "interaction";
+  return "check";
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+}
+function commandsForFinding(source) {
+  switch (source) {
+    case "brownfield":
+      return ["decantr analyze", "decantr init --existing --merge-proposal", "decantr health"];
+    case "pack":
+      return ["decantr refresh", "decantr registry get-pack review --write-context", "decantr health"];
+    case "runtime":
+      return ["npm run build", "decantr health"];
+    case "interaction":
+      return ["decantr check --strict", "decantr health"];
+    case "check":
+      return ["decantr check", "decantr health"];
+    default:
+      return ["decantr audit", "decantr health"];
+  }
+}
+function buildRemediationPrompt(input) {
+  return [
+    "You are fixing one Decantr Project Health finding in this local workspace.",
+    "",
+    "Read `DECANTR.md`, `decantr.essence.json`, and `.decantr/context/scaffold-pack.md` if they exist. For route or page work, read the matching page/section packs before editing.",
+    "",
+    `Finding: ${input.id}`,
+    `Source: ${input.source}`,
+    `Severity: ${input.severity}`,
+    `Category: ${input.category}`,
+    `Message: ${input.message}`,
+    input.evidence.length > 0 ? `Evidence:
+${input.evidence.map((entry) => `- ${entry}`).join("\n")}` : null,
+    input.suggestedFix ? `Suggested fix: ${input.suggestedFix}` : null,
+    "",
+    "Make the smallest coherent code or contract change that resolves this finding. Preserve the existing framework, routing, styling system, and Decantr workflow mode unless the finding explicitly requires a contract update.",
+    "",
+    `After the fix, run:
+${input.commands.map((command) => `- ${command}`).join("\n")}`
+  ].filter((line) => Boolean(line)).join("\n");
+}
+function createHealthFinding(input) {
+  const idBase = input.baseId || input.rule || `${input.category}-${input.message}`;
+  const id = `${input.source}-${slugify(idBase)}`;
+  const commands = commandsForFinding(input.source);
+  const remediation = {
+    summary: input.suggestedFix || `Resolve ${input.category.toLowerCase()} finding.`,
+    commands,
+    prompt: buildRemediationPrompt({
+      id,
+      source: input.source,
+      category: input.category,
+      severity: input.severity,
+      message: input.message,
+      evidence: input.evidence ?? [],
+      suggestedFix: input.suggestedFix,
+      commands
+    })
+  };
+  return {
+    id,
+    source: input.source,
+    category: input.category,
+    severity: input.severity,
+    message: input.message,
+    evidence: input.evidence ?? [],
+    target: input.target,
+    file: input.file,
+    rule: input.rule,
+    suggestedFix: input.suggestedFix,
+    remediation
+  };
+}
+function countFindings(findings) {
+  return {
+    errorCount: findings.filter((finding) => finding.severity === "error").length,
+    warnCount: findings.filter((finding) => finding.severity === "warn").length,
+    infoCount: findings.filter((finding) => finding.severity === "info").length
+  };
+}
+function statusFromCounts(counts) {
+  if (counts.errorCount > 0) return "error";
+  if (counts.warnCount > 0) return "warning";
+  return "healthy";
+}
+function scoreFromCounts(counts) {
+  return Math.max(0, Math.min(100, 100 - counts.errorCount * 15 - counts.warnCount * 5 - counts.infoCount));
+}
+function routeIssuesFromFindings(findings) {
+  const issues = findings.filter(
+    (finding) => finding.category.toLowerCase().includes("route") || finding.rule?.toLowerCase().includes("route") || finding.id.toLowerCase().includes("route")
+  ).map((finding) => finding.message);
+  return [...new Set(issues)];
+}
+function isDuplicateFinding(existing, finding) {
+  const key = `${finding.rule ?? finding.id}|${finding.message}`;
+  if (existing.has(key)) return true;
+  existing.add(key);
+  return false;
+}
+async function createProjectHealthReport(projectRoot = process.cwd()) {
+  const metadata = readProjectMetadata(projectRoot);
+  const audit = await auditProject(projectRoot);
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const finding of audit.findings) {
+    const healthFinding = createHealthFinding({
+      source: sourceFromAuditFinding(finding),
+      category: finding.category,
+      severity: finding.severity,
+      message: finding.message,
+      evidence: finding.evidence,
+      target: finding.target,
+      file: finding.file,
+      rule: finding.rule,
+      suggestedFix: finding.suggestedFix,
+      baseId: finding.id
+    });
+    if (!isDuplicateFinding(seen, healthFinding)) findings.push(healthFinding);
+  }
+  try {
+    const check = collectCheckIssues(projectRoot, { brownfield: metadata.autoBrownfield });
+    for (const issue of check.issues) {
+      const source = sourceFromCheckIssue(issue);
+      const healthFinding = createHealthFinding({
+        source,
+        category: source === "brownfield" ? "Brownfield Drift" : "Contract Check",
+        severity: severityFromCheckIssue(issue),
+        message: issue.message,
+        evidence: [`Rule: ${issue.rule}`],
+        rule: issue.rule,
+        suggestedFix: issue.suggestion,
+        baseId: issue.rule
+      });
+      if (!isDuplicateFinding(seen, healthFinding)) findings.push(healthFinding);
+    }
+  } catch (e) {
+    const healthFinding = createHealthFinding({
+      source: "check",
+      category: "Contract Check",
+      severity: "error",
+      message: `Decantr check could not complete: ${e.message}`,
+      evidence: ["The health command could not run the local check pass."],
+      rule: "check-failed",
+      suggestedFix: "Repair the local Decantr contract and rerun `decantr health`.",
+      baseId: "check-failed"
+    });
+    if (!isDuplicateFinding(seen, healthFinding)) findings.push(healthFinding);
+  }
+  if (!audit.valid && findings.every((finding) => finding.severity !== "error")) {
+    findings.push(
+      createHealthFinding({
+        source: "audit",
+        category: "Project Contract",
+        severity: "error",
+        message: "Project audit is not valid.",
+        evidence: ["The verifier returned valid=false."],
+        rule: "project-audit-invalid",
+        suggestedFix: "Resolve blocking audit findings and rerun `decantr health`."
+      })
+    );
+  }
+  const counts = countFindings(findings);
+  const declaredRoutes = collectDeclaredRoutes(audit.essence);
+  const manifest = audit.packManifest;
+  return {
+    $schema: PROJECT_HEALTH_SCHEMA_URL,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectRoot,
+    status: statusFromCounts(counts),
+    score: scoreFromCounts(counts),
+    summary: {
+      ...counts,
+      findingCount: findings.length,
+      workflowMode: metadata.workflowMode,
+      adoptionMode: metadata.adoptionMode,
+      essenceVersion: audit.summary.essenceVersion,
+      pageCount: audit.summary.pageCount,
+      runtimeAuditChecked: audit.summary.runtimeAuditChecked,
+      runtimePassed: audit.summary.runtimePassed,
+      packManifestPresent: audit.summary.packManifestPresent,
+      reviewPackPresent: audit.summary.reviewPackPresent
+    },
+    routes: {
+      declared: declaredRoutes,
+      runtimeChecked: audit.runtimeAudit.routeHintsChecked,
+      runtimeMatched: audit.runtimeAudit.routeHintsMatched,
+      runtimeCoverageOk: audit.summary.runtimeAuditChecked ? audit.runtimeAudit.routeHintsCoverageOk : null,
+      issues: routeIssuesFromFindings(findings)
+    },
+    packs: {
+      manifestPresent: Boolean(manifest),
+      reviewPackPresent: Boolean(manifest?.review ?? audit.reviewPack),
+      scaffoldPackPresent: Boolean(manifest?.scaffold),
+      sectionPackCount: manifest?.sections.length ?? 0,
+      pagePackCount: manifest?.pages.length ?? 0,
+      mutationPackCount: manifest?.mutations?.length ?? 0,
+      generatedAt: typeof manifest?.generatedAt === "string" ? manifest.generatedAt : null
+    },
+    ci: {
+      recommendedCommand: "decantr health --ci --fail-on error",
+      failOn: "error"
+    },
+    findings
+  };
+}
+function colorForStatus(status) {
+  if (status === "healthy") return GREEN;
+  if (status === "warning") return YELLOW;
+  return RED;
+}
+function formatProjectHealthText(report) {
+  const color = colorForStatus(report.status);
+  const lines = [
+    `${BOLD}Decantr Project Health${RESET}`,
+    "",
+    `${color}${report.status.toUpperCase()}${RESET}  score ${report.score}/100`,
+    `${DIM}${report.projectRoot}${RESET}`,
+    "",
+    `${BOLD}Summary:${RESET}`,
+    `  Findings: ${report.summary.errorCount} error(s), ${report.summary.warnCount} warn(s), ${report.summary.infoCount} info`,
+    `  Essence: ${report.summary.essenceVersion ?? "missing"} | pages ${report.summary.pageCount}`,
+    `  Workflow: ${report.summary.workflowMode ?? "unknown"} | adoption ${report.summary.adoptionMode ?? "unknown"}`,
+    `  Runtime audit: ${report.summary.runtimeAuditChecked ? report.summary.runtimePassed ? "passed" : "failed" : "not checked"}`,
+    `  Packs: manifest ${report.packs.manifestPresent ? "present" : "missing"} | review ${report.packs.reviewPackPresent ? "present" : "missing"} | pages ${report.packs.pagePackCount}`,
+    "",
+    `${BOLD}Findings:${RESET}`
+  ];
+  if (report.findings.length === 0) {
+    lines.push(`  ${GREEN}No findings. Project is healthy.${RESET}`);
+  } else {
+    for (const finding of report.findings) {
+      const findingColor = finding.severity === "error" ? RED : finding.severity === "warn" ? YELLOW : CYAN;
+      lines.push(
+        `  ${findingColor}[${finding.severity.toUpperCase()}]${RESET} ${finding.id}: ${finding.message}`
+      );
+      if (finding.evidence.length > 0) {
+        lines.push(`    ${DIM}${finding.evidence[0]}${RESET}`);
+      }
+      if (finding.suggestedFix) {
+        lines.push(`    ${DIM}Fix: ${finding.suggestedFix}${RESET}`);
+      }
+      lines.push(`    ${DIM}Prompt: decantr health --prompt ${finding.id}${RESET}`);
+    }
+  }
+  lines.push("");
+  lines.push(`${BOLD}CI:${RESET} ${report.ci.recommendedCommand}`);
+  return `${lines.join("\n")}
+`;
+}
+function formatProjectHealthMarkdown(report) {
+  const lines = [
+    "# Decantr Project Health",
+    "",
+    `- Status: **${report.status}**`,
+    `- Score: **${report.score}/100**`,
+    `- Project: \`${report.projectRoot}\``,
+    `- Findings: ${report.summary.errorCount} error(s), ${report.summary.warnCount} warn(s), ${report.summary.infoCount} info`,
+    `- Runtime audit: ${report.summary.runtimeAuditChecked ? report.summary.runtimePassed ? "passed" : "failed" : "not checked"}`,
+    `- Packs: manifest ${report.packs.manifestPresent ? "present" : "missing"}, review ${report.packs.reviewPackPresent ? "present" : "missing"}`,
+    "",
+    "## Findings",
+    ""
+  ];
+  if (report.findings.length === 0) {
+    lines.push("No findings. Project is healthy.");
+  } else {
+    for (const finding of report.findings) {
+      lines.push(`### ${finding.id}`);
+      lines.push("");
+      lines.push(`- Severity: ${finding.severity}`);
+      lines.push(`- Source: ${finding.source}`);
+      lines.push(`- Category: ${finding.category}`);
+      lines.push(`- Message: ${finding.message}`);
+      if (finding.suggestedFix) lines.push(`- Fix: ${finding.suggestedFix}`);
+      if (finding.evidence.length > 0) {
+        lines.push("- Evidence:");
+        for (const evidence of finding.evidence) lines.push(`  - ${evidence}`);
+      }
+      lines.push(`- Prompt: \`decantr health --prompt ${finding.id}\``);
+      lines.push("");
+    }
+  }
+  lines.push("## CI");
+  lines.push("");
+  lines.push(`\`${report.ci.recommendedCommand}\``);
+  return `${lines.join("\n")}
+`;
+}
+function formatProjectHealthJson(report) {
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+function resolveFormat(options) {
+  if (options.json) return "json";
+  if (options.markdown) return "markdown";
+  return options.format ?? "text";
+}
+function shouldFailHealth(report, failOn) {
+  if (failOn === "none") return false;
+  if (failOn === "warn") return report.summary.errorCount > 0 || report.summary.warnCount > 0;
+  return report.summary.errorCount > 0;
+}
+async function cmdHealth(projectRoot = process.cwd(), options = {}) {
+  const report = await createProjectHealthReport(projectRoot);
+  if (options.promptId) {
+    const finding = report.findings.find((entry) => entry.id === options.promptId);
+    if (!finding) {
+      console.error(`${RED}No health finding found for id: ${options.promptId}${RESET}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(finding.remediation.prompt);
+    return;
+  }
+  const format = resolveFormat(options);
+  const payload = format === "json" ? formatProjectHealthJson(report) : format === "markdown" ? formatProjectHealthMarkdown(report) : formatProjectHealthText(report);
+  if (options.output) {
+    writeFileSync(options.output, payload, "utf-8");
+    if (!options.ci) {
+      console.log(`${GREEN}Wrote Decantr health report:${RESET} ${options.output}`);
+    }
+  } else {
+    process.stdout.write(payload);
+  }
+  if (options.ci && shouldFailHealth(report, options.failOn ?? "error")) {
+    process.exitCode = 1;
+  }
+}
+function parseHealthArgs(args) {
+  const options = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--markdown") {
+      options.markdown = true;
+    } else if (arg === "--ci") {
+      options.ci = true;
+    } else if (arg === "--format" && args[index + 1]) {
+      options.format = args[++index];
+    } else if (arg.startsWith("--format=")) {
+      options.format = arg.split("=")[1];
+    } else if (arg === "--output" && args[index + 1]) {
+      options.output = args[++index];
+    } else if (arg.startsWith("--output=")) {
+      options.output = arg.split("=")[1];
+    } else if (arg === "--fail-on" && args[index + 1]) {
+      options.failOn = args[++index];
+    } else if (arg.startsWith("--fail-on=")) {
+      options.failOn = arg.split("=")[1];
+    } else if (arg === "--prompt" && args[index + 1]) {
+      options.promptId = args[++index];
+    } else if (arg.startsWith("--prompt=")) {
+      options.promptId = arg.split("=")[1];
+    }
+  }
+  if (options.format && !["text", "json", "markdown"].includes(options.format)) {
+    throw new Error("Invalid --format value. Use text, json, or markdown.");
+  }
+  if (options.failOn && !["error", "warn", "none"].includes(options.failOn)) {
+    throw new Error("Invalid --fail-on value. Use error, warn, or none.");
+  }
+  return options;
+}
+
+export {
+  createProjectHealthReport,
+  formatProjectHealthText,
+  formatProjectHealthMarkdown,
+  formatProjectHealthJson,
+  shouldFailHealth,
+  cmdHealth,
+  parseHealthArgs
+};

package/dist/{heal-YHLXO5QL.js → chunk-RSDCWAHD.js}

@@ -205,15 +205,22 @@ var YELLOW = "\x1B[33m";
 var CYAN = "\x1B[36m";
 var RESET = "\x1B[0m";
 var DIM = "\x1B[2m";
-async function cmdHeal(projectRoot = process.cwd(), options = {}) {
+function collectCheckIssues(projectRoot = process.cwd(), options = {}) {
   const essencePath = join2(projectRoot, "decantr.essence.json");
   if (!existsSync2(essencePath)) {
-    console.error("No decantr.essence.json found. Run `decantr init` first.");
-    process.exitCode = 1;
-    return;
+    return {
+      essence: null,
+      issues: [
+        {
+          type: "error",
+          rule: "essence-missing",
+          message: "No decantr.essence.json found. Run `decantr init` first."
+        }
+      ],
+      missingEssence: true
+    };
   }
   const essence = JSON.parse(readFileSync2(essencePath, "utf-8"));
-  console.log("Scanning for issues...\n");
   const issues = [];
   const validation = validateEssence(essence);
   if (!validation.valid) {
@@ -266,6 +273,18 @@ async function cmdHeal(projectRoot = process.cwd(), options = {}) {
       });
     }
   }
+  return { essence, issues, missingEssence: false };
+}
+async function cmdHeal(projectRoot = process.cwd(), options = {}) {
+  const result = collectCheckIssues(projectRoot, options);
+  console.log("Scanning for issues...\n");
+  if (result.missingEssence) {
+    console.error(result.issues[0]?.message ?? "No decantr.essence.json found.");
+    process.exitCode = 1;
+    return;
+  }
+  const issues = result.issues;
+  const essence = result.essence ?? {};
   if (issues.length === 0) {
     console.log(`${GREEN}No issues found. Project is healthy.${RESET}`);
     await maybeSendTelemetry(projectRoot, essence, issues, options);
@@ -302,6 +321,8 @@ ${CYAN}Telemetry enabled.${RESET} Anonymous guard metrics will be sent on future
     sendGuardMetrics(metrics);
   }
 }
+
 export {
+  collectCheckIssues,
   cmdHeal
 };

package/dist/{chunk-HULA6E2D.js → chunk-USOO77A5.js}

@@ -3756,7 +3756,16 @@ Start implementation from the shell layouts and shared route structure before fi
   }
   briefLines.push(`- **Guard mode:** ${params.guardMode}`);
   briefLines.push("");
-  const escDecCell = (s) => s.replace(/\|/g, "\\|");
+  const escDecCell = (s) => {
+    let escaped = "";
+    for (const char of s) {
+      if (char === "\\") escaped += "\\\\";
+      else if (char === "|") escaped += "\\|";
+      else if (char === "\n" || char === "\r") escaped += "<br>";
+      else escaped += char;
+    }
+    return escaped;
+  };
   if (params.decoratorDefinitions && Object.keys(params.decoratorDefinitions).length > 0) {
     briefLines.push("### Decorator Quick Reference");
     briefLines.push(

package/dist/{chunk-US6RK5QT.js → chunk-Y45MCRGI.js}

@@ -14,7 +14,7 @@ import {
   scaffoldProject,
   syncRegistry,
   writeExecutionPackBundleArtifacts
-} from "./chunk-HULA6E2D.js";
+} from "./chunk-USOO77A5.js";
 import {
   buildGuardRegistryContext,
   createDoctrineMap,
@@ -6480,6 +6480,8 @@ ${YELLOW9}You're offline. Scaffolding Decantr default.${RESET13}`);
   console.log("");
   console.log("  Commands:");
   console.log(`    ${cyan3("decantr status")}     Project health`);
+  console.log(`    ${cyan3("decantr health")}     Contract health report`);
+  console.log(`    ${cyan3("decantr studio")}     Local health dashboard`);
   console.log(`    ${cyan3("decantr search")}     Search registry`);
   console.log(`    ${cyan3("decantr get")}        Fetch content details`);
   console.log(`    ${cyan3("decantr validate")}   Check essence file`);
@@ -6961,6 +6963,8 @@ ${BOLD6}Commands:${RESET13}
   ${cyan3("magic")}       Greenfield-first intent flow; steers existing apps into analyze + init
   ${cyan3("init")}        Attach Decantr contract/context files to an existing project or empty workspace
   ${cyan3("status")}      Show project status, DNA axioms, and blueprint info
+  ${cyan3("health")}      Generate a local Project Health report [--json] [--markdown] [--ci]
+  ${cyan3("studio")}      Open a local Project Health dashboard backed by the same report
   ${cyan3("sync")}        Sync registry content from API
   ${cyan3("audit")}       Audit the project or critique a specific file against compiled packs
   ${cyan3("migrate")}     Migrate v2 essence to v3 format (with .v2.backup.json backup)
@@ -6997,6 +7001,9 @@ ${BOLD6}Examples:${RESET13}
   decantr rules preview
   decantr rules apply
   decantr status
+  decantr health
+  decantr health --ci --fail-on error
+  decantr studio
   decantr audit
   decantr audit src/pages/HomePage.tsx
   decantr migrate
@@ -7157,7 +7164,7 @@ async function main() {
       break;
     }
     case "upgrade": {
-      const { cmdUpgrade } = await import("./upgrade-EV23CKA3.js");
+      const { cmdUpgrade } = await import("./upgrade-4NRDVD5N.js");
       const applyFlag = args.includes("--apply");
       await cmdUpgrade(process.cwd(), { apply: applyFlag });
       break;
@@ -7169,12 +7176,32 @@ async function main() {
           `${YELLOW9}Note: \`decantr heal\` is deprecated. Use \`decantr check\` instead.${RESET13}`
         );
       }
-      const { cmdHeal } = await import("./heal-YHLXO5QL.js");
+      const { cmdHeal } = await import("./heal-5JHGCLDX.js");
       const telemetryFlag = args.includes("--telemetry");
       const brownfieldFlag = args.includes("--brownfield");
       await cmdHeal(process.cwd(), { telemetry: telemetryFlag, brownfield: brownfieldFlag });
       break;
     }
+    case "health": {
+      try {
+        const { cmdHealth, parseHealthArgs } = await import("./health-VSL4MROO.js");
+        await cmdHealth(process.cwd(), parseHealthArgs(args));
+      } catch (e) {
+        console.error(error3(e.message));
+        process.exitCode = 1;
+      }
+      break;
+    }
+    case "studio": {
+      try {
+        const { cmdStudio, parseStudioArgs } = await import("./studio-BCTWKXFH.js");
+        await cmdStudio(process.cwd(), parseStudioArgs(args));
+      } catch (e) {
+        console.error(error3(e.message));
+        process.exitCode = 1;
+      }
+      break;
+    }
     case "migrate": {
       await cmdMigrate(process.cwd());
       break;

package/dist/heal-5JHGCLDX.js

@@ -0,0 +1,9 @@
+import {
+  cmdHeal,
+  collectCheckIssues
+} from "./chunk-RSDCWAHD.js";
+import "./chunk-DI2PLOJ6.js";
+export {
+  cmdHeal,
+  collectCheckIssues
+};

package/dist/health-VSL4MROO.js

@@ -0,0 +1,20 @@
+import {
+  cmdHealth,
+  createProjectHealthReport,
+  formatProjectHealthJson,
+  formatProjectHealthMarkdown,
+  formatProjectHealthText,
+  parseHealthArgs,
+  shouldFailHealth
+} from "./chunk-DONMNPS7.js";
+import "./chunk-RSDCWAHD.js";
+import "./chunk-DI2PLOJ6.js";
+export {
+  cmdHealth,
+  createProjectHealthReport,
+  formatProjectHealthJson,
+  formatProjectHealthMarkdown,
+  formatProjectHealthText,
+  parseHealthArgs,
+  shouldFailHealth
+};

package/dist/index.js

@@ -1,3 +1,3 @@
-import "./chunk-US6RK5QT.js";
-import "./chunk-HULA6E2D.js";
+import "./chunk-Y45MCRGI.js";
+import "./chunk-USOO77A5.js";
 import "./chunk-DI2PLOJ6.js";

package/dist/studio-BCTWKXFH.js

@@ -0,0 +1,309 @@
+import {
+  createProjectHealthReport
+} from "./chunk-DONMNPS7.js";
+import "./chunk-RSDCWAHD.js";
+import "./chunk-DI2PLOJ6.js";
+
+// src/commands/studio.ts
+import { createServer } from "http";
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+var RESET = "\x1B[0m";
+function sendJson(res, status, value) {
+  const body = JSON.stringify(value, null, 2);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store"
+  });
+  res.end(body);
+}
+function sendHtml(res, body) {
+  res.writeHead(200, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store"
+  });
+  res.end(body);
+}
+function sendNotFound(res) {
+  sendJson(res, 404, { error: "not_found" });
+}
+function studioHtml() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Decantr Project Health</title>
+  <style>
+    :root {
+      color-scheme: dark;
+      --bg: #101014;
+      --panel: #181820;
+      --panel-2: #20202a;
+      --line: #343442;
+      --text: #f5f2eb;
+      --muted: #ada7bd;
+      --good: #5ee2a0;
+      --warn: #f2bd61;
+      --bad: #ff6f7d;
+      --accent: #8ed3ff;
+      --coral: #ff8b6a;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: radial-gradient(circle at 20% 0%, rgba(255,139,106,0.16), transparent 26rem), var(--bg);
+      color: var(--text);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      line-height: 1.4;
+    }
+    button, input { font: inherit; }
+    .shell { min-height: 100vh; display: grid; grid-template-rows: auto 1fr; }
+    header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 1rem;
+      padding: 1rem 1.25rem;
+      border-bottom: 1px solid var(--line);
+      background: rgba(16,16,20,0.84);
+      backdrop-filter: blur(18px);
+      position: sticky;
+      top: 0;
+      z-index: 2;
+    }
+    h1 { margin: 0; font-size: 1rem; letter-spacing: 0; }
+    .subtle { color: var(--muted); font-size: 0.875rem; }
+    .button {
+      border: 1px solid var(--line);
+      background: var(--panel-2);
+      color: var(--text);
+      border-radius: 8px;
+      padding: 0.55rem 0.8rem;
+      cursor: pointer;
+    }
+    .button:hover { border-color: var(--accent); }
+    main { display: grid; grid-template-columns: 15rem 1fr; min-height: 0; }
+    nav {
+      border-right: 1px solid var(--line);
+      padding: 1rem;
+      background: rgba(24,24,32,0.66);
+    }
+    .tab {
+      width: 100%;
+      text-align: left;
+      margin: 0 0 0.35rem;
+      border: 1px solid transparent;
+      border-radius: 8px;
+      padding: 0.65rem 0.7rem;
+      color: var(--muted);
+      background: transparent;
+      cursor: pointer;
+    }
+    .tab[aria-selected="true"] {
+      color: var(--text);
+      border-color: var(--line);
+      background: var(--panel-2);
+    }
+    .content { padding: 1rem; overflow: auto; }
+    .grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 0.75rem; }
+    .card {
+      border: 1px solid var(--line);
+      background: linear-gradient(180deg, var(--panel), rgba(24,24,32,0.74));
+      border-radius: 8px;
+      padding: 1rem;
+    }
+    .metric { font-size: 1.85rem; font-weight: 720; }
+    .label { color: var(--muted); font-size: 0.78rem; text-transform: uppercase; }
+    .status-healthy { color: var(--good); }
+    .status-warning { color: var(--warn); }
+    .status-error { color: var(--bad); }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { border-bottom: 1px solid var(--line); padding: 0.7rem; text-align: left; vertical-align: top; }
+    th { color: var(--muted); font-size: 0.78rem; text-transform: uppercase; }
+    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+    pre {
+      white-space: pre-wrap;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 1rem;
+      background: #0c0c10;
+      overflow: auto;
+    }
+    .pill { display: inline-flex; border: 1px solid var(--line); border-radius: 999px; padding: 0.2rem 0.55rem; }
+    .stack { display: grid; gap: 0.75rem; }
+    .hidden { display: none; }
+    @media (max-width: 760px) {
+      main { grid-template-columns: 1fr; }
+      nav { border-right: 0; border-bottom: 1px solid var(--line); display: grid; grid-template-columns: repeat(2, 1fr); gap: 0.35rem; }
+      .grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    }
+  </style>
+</head>
+<body>
+  <div class="shell">
+    <header>
+      <div>
+        <h1>Decantr Project Health</h1>
+        <div id="project" class="subtle">Loading local contract state...</div>
+      </div>
+      <button id="refresh" class="button" type="button">Refresh</button>
+    </header>
+    <main>
+      <nav aria-label="Project Health Views">
+        <button class="tab" type="button" data-tab="overview" aria-selected="true">Overview</button>
+        <button class="tab" type="button" data-tab="routes">Routes</button>
+        <button class="tab" type="button" data-tab="drift">Drift</button>
+        <button class="tab" type="button" data-tab="findings">Findings</button>
+        <button class="tab" type="button" data-tab="remediation">Remediation</button>
+        <button class="tab" type="button" data-tab="ci">CI</button>
+        <button class="tab" type="button" data-tab="packs">Packs</button>
+      </nav>
+      <section class="content">
+        <div id="overview" class="view stack"></div>
+        <div id="routes" class="view stack hidden"></div>
+        <div id="drift" class="view stack hidden"></div>
+        <div id="findings" class="view stack hidden"></div>
+        <div id="remediation" class="view stack hidden"></div>
+        <div id="ci" class="view stack hidden"></div>
+        <div id="packs" class="view stack hidden"></div>
+      </section>
+    </main>
+  </div>
+  <script>
+    let report = null;
+    const tabs = [...document.querySelectorAll('.tab')];
+    const views = [...document.querySelectorAll('.view')];
+    function esc(value) {
+      return String(value ?? '').replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]));
+    }
+    function metric(label, value, cls = '') {
+      return '<div class="card"><div class="label">' + esc(label) + '</div><div class="metric ' + cls + '">' + esc(value) + '</div></div>';
+    }
+    function table(headers, rows) {
+      return '<table><thead><tr>' + headers.map((h) => '<th>' + esc(h) + '</th>').join('') + '</tr></thead><tbody>' +
+        rows.map((row) => '<tr>' + row.map((cell) => '<td>' + cell + '</td>').join('') + '</tr>').join('') + '</tbody></table>';
+    }
+    function render() {
+      if (!report) return;
+      document.getElementById('project').textContent = report.projectRoot;
+      document.getElementById('overview').innerHTML =
+        '<div class="grid">' +
+        metric('Status', report.status, 'status-' + report.status) +
+        metric('Score', report.score + '/100') +
+        metric('Errors', report.summary.errorCount, 'status-error') +
+        metric('Warnings', report.summary.warnCount, 'status-warning') +
+        '</div><div class="card"><div class="label">Workflow</div><p>' + esc(report.summary.workflowMode || 'unknown') + ' / ' + esc(report.summary.adoptionMode || 'unknown') + '</p><p class="subtle">Generated ' + esc(report.generatedAt) + '</p></div>';
+      document.getElementById('routes').innerHTML =
+        '<div class="card"><div class="label">Route Coverage</div><p>Declared routes: ' + report.routes.declared.length + ' | runtime checked: ' + report.routes.runtimeChecked.length + ' | matched: ' + report.routes.runtimeMatched + '</p></div>' +
+        table(['Declared Route'], report.routes.declared.map((route) => ['<code>' + esc(route) + '</code>'])) +
+        (report.routes.issues.length ? '<div class="card"><div class="label">Route Issues</div><ul>' + report.routes.issues.map((issue) => '<li>' + esc(issue) + '</li>').join('') + '</ul></div>' : '');
+      const drift = report.findings.filter((finding) => finding.source === 'brownfield' || finding.id.includes('drift'));
+      document.getElementById('drift').innerHTML = drift.length
+        ? table(['Severity', 'Source', 'Message'], drift.map((finding) => [esc(finding.severity), esc(finding.source), esc(finding.message)]))
+        : '<div class="card">No drift findings.</div>';
+      document.getElementById('findings').innerHTML = report.findings.length
+        ? table(['Severity', 'Source', 'Finding', 'Prompt'], report.findings.map((finding) => [
+            '<span class="pill">' + esc(finding.severity) + '</span>',
+            esc(finding.source),
+            '<strong>' + esc(finding.id) + '</strong><br><span class="subtle">' + esc(finding.message) + '</span>',
+            '<code>decantr health --prompt ' + esc(finding.id) + '</code>'
+          ]))
+        : '<div class="card">No findings. Project is healthy.</div>';
+      document.getElementById('remediation').innerHTML = report.findings.length
+        ? report.findings.map((finding) => '<div class="card"><div class="label">' + esc(finding.id) + '</div><p>' + esc(finding.remediation.summary) + '</p><pre>' + esc(finding.remediation.prompt) + '</pre></div>').join('')
+        : '<div class="card">No remediation needed.</div>';
+      document.getElementById('ci').innerHTML = '<div class="card"><div class="label">Recommended CI Gate</div><pre>' + esc(report.ci.recommendedCommand) + '</pre></div>';
+      document.getElementById('packs').innerHTML =
+        '<div class="grid">' +
+        metric('Manifest', report.packs.manifestPresent ? 'present' : 'missing') +
+        metric('Review', report.packs.reviewPackPresent ? 'present' : 'missing') +
+        metric('Sections', report.packs.sectionPackCount) +
+        metric('Pages', report.packs.pagePackCount) +
+        '</div><div class="card"><div class="label">Generated</div><p>' + esc(report.packs.generatedAt || 'unknown') + '</p></div>';
+    }
+    async function load(refresh = false) {
+      const response = await fetch(refresh ? '/api/refresh' : '/api/health', { method: refresh ? 'POST' : 'GET' });
+      report = await response.json();
+      render();
+    }
+    tabs.forEach((tab) => tab.addEventListener('click', () => {
+      tabs.forEach((item) => item.setAttribute('aria-selected', String(item === tab)));
+      views.forEach((view) => view.classList.toggle('hidden', view.id !== tab.dataset.tab));
+    }));
+    document.getElementById('refresh').addEventListener('click', () => load(true));
+    load().catch((error) => {
+      document.getElementById('overview').innerHTML = '<div class="card status-error">Failed to load health report: ' + esc(error.message) + '</div>';
+    });
+  </script>
+</body>
+</html>`;
+}
+function createStudioRequestHandler(projectRoot) {
+  return async function handleStudioRequest(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    try {
+      if (req.method === "GET" && url.pathname === "/") {
+        sendHtml(res, studioHtml());
+        return;
+      }
+      if (req.method === "GET" && url.pathname === "/api/health") {
+        sendJson(res, 200, await createProjectHealthReport(projectRoot));
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/api/refresh") {
+        sendJson(res, 200, await createProjectHealthReport(projectRoot));
+        return;
+      }
+      sendNotFound(res);
+    } catch (e) {
+      sendJson(res, 500, { error: "health_report_failed", message: e.message });
+    }
+  };
+}
+async function startStudioServer(projectRoot = process.cwd(), options = {}) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 4319;
+  const server = createServer(createStudioRequestHandler(projectRoot));
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : port;
+  return { server, url: `http://${host}:${actualPort}` };
+}
+async function cmdStudio(projectRoot = process.cwd(), options = {}) {
+  const handle = await startStudioServer(projectRoot, options);
+  console.log(`${GREEN}Decantr Studio is running.${RESET}`);
+  console.log(`${CYAN}${handle.url}${RESET}`);
+  console.log("Press Ctrl+C to stop.");
+}
+function parseStudioArgs(args) {
+  const options = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--host" && args[index + 1]) {
+      options.host = args[++index];
+    } else if (arg.startsWith("--host=")) {
+      options.host = arg.split("=")[1];
+    } else if (arg === "--port" && args[index + 1]) {
+      options.port = Number.parseInt(args[++index], 10);
+    } else if (arg.startsWith("--port=")) {
+      options.port = Number.parseInt(arg.split("=")[1], 10);
+    }
+  }
+  if (options.port !== void 0 && (!Number.isInteger(options.port) || options.port < 0)) {
+    throw new Error("Invalid --port value.");
+  }
+  return options;
+}
+export {
+  cmdStudio,
+  createStudioRequestHandler,
+  parseStudioArgs,
+  startStudioServer
+};

package/dist/{upgrade-EV23CKA3.js → upgrade-4NRDVD5N.js}

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@decantr/cli",
-  "version": "1.7.29",
-  "description": "Decantr CLI — scaffold, audit, and maintain Decantr projects from the terminal",
+  "version": "1.8.0",
+  "description": "Decantr CLI - scaffold, audit, inspect Project Health, and maintain Decantr projects from the terminal",
   "author": "Decantr AI",
   "license": "MIT",
   "bugs": {
@@ -30,11 +30,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@decantr/telemetry": "0.1.2",
     "@decantr/core": "1.0.6",
     "@decantr/essence-spec": "1.0.7",
-    "@decantr/verifier": "1.0.6",
-    "@decantr/registry": "1.0.4"
+    "@decantr/verifier": "1.1.0",
+    "@decantr/registry": "1.0.4",
+    "@decantr/telemetry": "0.1.2"
   },
   "scripts": {
     "build": "tsup",

package/src/templates/DECANTR.md.template

@@ -115,12 +115,15 @@ Read `.decantr/context/page-{name}-pack.md` for the most local compiled route co
 ### Validation
 
 Run `decantr check` to detect drift violations while editing and `decantr audit` to audit the whole project contract after implementation.
+Run `decantr health` for the broader Project Health view before handoff, pull requests, or CI. Use `decantr health --prompt <finding-id>` to generate a scoped remediation prompt for a specific issue, and `decantr studio` to inspect local drift, routes, findings, remediation, CI, and pack state in a localhost dashboard.
 Declared command palettes and hotkeys must be implemented, not merely acknowledged.
 
 ### Quick Commands
 
 ```bash
-decantr status          # Project health
+decantr status          # Project status overview
+decantr health          # Local contract health report
+decantr studio          # Local health dashboard
 decantr check           # Detect drift violations
 decantr get pattern X   # Fetch a pattern spec from registry
 decantr get theme X     # Fetch theme details and decorators