From 08561c6621048f0f0d934586aafacdfad95cb171 Mon Sep 17 00:00:00 2001
From: Steven Salmons <stevencsalmons@gmail.com>
Date: Tue, 7 Jul 2026 14:08:27 -0400
Subject: [PATCH 1/4] feat(briefing): surface computed slices and complete
 flag-card wiring

- FLAG_UI: head.detached -> Open Source Control; analytics.unavailable ->
  Open Git Analytics (self-healing); four remaining ids documented as
  deliberately inert (no honest action exists)
- Activity: render topContributors as chip row (aggregator-capped, already
  in CSV, previously dropped)
- Pulse: hint now shows recorded / not recorded (10-min throttle) from
  p.appended

Presentation-only; no contract or host changes (ADR 011 additive rule).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../git/session-briefing-ui/index.html        |  1 +
 src/domains/git/session-briefing-ui/script.js | 42 ++++++++++++++++---
 .../git/session-briefing-ui/styles.css        | 25 +++++++++++
 3 files changed, 63 insertions(+), 5 deletions(-)

diff --git a/src/domains/git/session-briefing-ui/index.html b/src/domains/git/session-briefing-ui/index.html
index bb83ffe..352761e 100644
--- a/src/domains/git/session-briefing-ui/index.html
+++ b/src/domains/git/session-briefing-ui/index.html
@@ -40,6 +40,7 @@ <h3>Activity <span class="table-hint" id="activityPeriod"></span>
         <span class="report-link adornment" data-report="gitAnalytics" title="Open in Git Analytics">&#8599;</span>
       </h3>
       <div class="metrics" id="activityMetrics"></div>
+      <div id="contributorsBlock"></div>
       <div id="sparklineBlock"></div>
       <div id="churnFilterRow" class="filter-row" style="display:none">
         <input type="text" class="path-filter" data-target="churn" placeholder="filter path…" />
diff --git a/src/domains/git/session-briefing-ui/script.js b/src/domains/git/session-briefing-ui/script.js
index 78bb70a..022a83c 100644
--- a/src/domains/git/session-briefing-ui/script.js
+++ b/src/domains/git/session-briefing-ui/script.js
@@ -120,8 +120,15 @@
   // anchor and/or an action button. Keyed by id rather than matched against
   // message text, so rewording a message never breaks the wiring. Flags
   // without an entry here (or entries with neither `anchor` nor `action`)
-  // render as inert cards — acceptable, matching the prior regex-miss
-  // behavior.
+  // render as inert cards.
+  //
+  // Deliberately inert (no honest action exists — the condition is either
+  // environmental or self-describing):
+  //   runlog.unavailable / runlog.readFailed — run log is a peripheral; there
+  //     is no user command that creates or repairs it.
+  //   pulse.unavailable — pulse store missing/unreadable; same, no command.
+  //   pulse.notRecorded — throttle suppressed the write by design (ADR 019);
+  //     "record now" would defeat the min-interval.
   var HYGIENE_REPORT_UI = {
     anchor: "hygieneSection",
     action: { label: "Open Hygiene Analytics", message: { type: "openReport", payload: { id: "hygiene" } } },
@@ -132,11 +139,19 @@
       anchor: "uncommittedSection",
       action: { label: "Open Source Control", message: { type: "openScm" } },
     },
+    "head.detached": {
+      action: { label: "Open Source Control", message: { type: "openScm" } },
+    },
     "runs.failures": { anchor: "recentRunsSection" },
     "risk.hotspots": {
       anchor: "pendingRiskSection",
       action: { label: "Open Git Analytics", message: { type: "openReport", payload: { id: "gitAnalytics" } } },
     },
+    // Self-healing: opening Git Analytics computes the report, so the next
+    // briefing has the activity slice.
+    "analytics.unavailable": {
+      action: { label: "Open Git Analytics", message: { type: "openReport", payload: { id: "gitAnalytics" } } },
+    },
     "companions.missing": { anchor: "companionsSection" },
     "hygiene.deadFiles": HYGIENE_REPORT_UI,
     "hygiene.largeFiles": HYGIENE_REPORT_UI,
@@ -242,9 +257,13 @@
     section.style.display = "";
 
     var hint = document.getElementById("pulseHint");
-    hint.textContent = p.previousAt
-      ? "(since " + new Date(p.previousAt).toLocaleString() + ")"
-      : "(first snapshot — history starts now)";
+    var since = p.previousAt
+      ? "since " + new Date(p.previousAt).toLocaleString()
+      : "first snapshot — history starts now";
+    var recorded = p.appended
+      ? "recorded"
+      : "not recorded (within 10-min window)";
+    hint.textContent = "(" + since + " · " + recorded + ")";
 
     var cards = [];
     if (p.deltas) {
@@ -306,6 +325,19 @@
     }
     document.getElementById("activityMetrics").innerHTML = cards.join("");
 
+    // Top contributors — already aggregator-capped (SESSION_BRIEFING limit)
+    // and already in the CSV export; previously dropped by this renderer.
+    var contributors = w.topContributors || [];
+    document.getElementById("contributorsBlock").innerHTML = contributors.length
+      ? '<h3 class="sub">Top Contributors</h3>' +
+        '<div class="contributor-chips">' +
+        contributors.map(function (a) {
+          return '<span class="contributor-chip">' + esc(a.name) +
+            '<span class="contributor-count">' + (Number(a.commits) || 0) + '</span></span>';
+        }).join("") +
+        '</div>'
+      : "";
+
     var sb = document.getElementById("sparklineBlock");
     var spark = sparklineSvg(w.commitFrequency && w.commitFrequency.data);
     sb.innerHTML = spark
diff --git a/src/domains/git/session-briefing-ui/styles.css b/src/domains/git/session-briefing-ui/styles.css
index f58e101..db1b8d4 100644
--- a/src/domains/git/session-briefing-ui/styles.css
+++ b/src/domains/git/session-briefing-ui/styles.css
@@ -525,6 +525,31 @@ h3.sub {
   margin: 0 0 14px;
 }
 
+/* Top-contributor chips (Activity section) */
+
+.contributor-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+.contributor-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 10px;
+  border: 1px solid var(--vscode-input-border, #555);
+  border-radius: 12px;
+  font-size: 12px;
+}
+
+.contributor-count {
+  font-weight: 600;
+  font-size: 11px;
+  opacity: 0.6;
+}
+
 /* Pulse trend charts sit side-by-side where width allows, stack otherwise. */
 #pulseTrendBlock {
   display: flex;

From 1027e10e112bd945ca058822861daf2e1509d81d Mon Sep 17 00:00:00 2001
From: Steven Salmons <stevencsalmons@gmail.com>
Date: Tue, 7 Jul 2026 14:18:30 -0400
Subject: [PATCH 2/4] feat(export): markdown as a third export format with
 copy-to-clipboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- serializeReport gate widens to json|csv|md; abstract reportToMarkdown
  compile-enforced across all three webview providers
- gitReportToMd beside gitReportToCsv; hygiene + briefing builders inline in
  their providers, mirroring each CSV's section structure and caps
- mdEscape (pipes, backticks, newlines) + reportMdHeader in report-labels
- "MD" quick-save and "Copy MD" buttons on all three webview toolbars; copy
  routes through copyWithPolicy (security.clipboard.autoCopy) — no new
  clipboard surface
- Save-as QuickPick gains Markdown; md writes join .meridian/artifacts/
  (retention-governed, ADR 019); ADR 020 latest/ contract untouched
- Tests: builder escaping against real serializer output; export test
  extended for md quick-save, unknown-format reject, and both copy paths

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/domains/git/analytics-service.ts          |  69 +++++-
 src/domains/git/analytics-ui/index.html       |   2 +
 src/domains/git/analytics-ui/script.js        |   8 +
 .../git/session-briefing-ui/index.html        |   2 +
 src/domains/git/session-briefing-ui/script.js |   6 +
 src/domains/hygiene/analytics-ui/index.html   |   2 +
 src/domains/hygiene/analytics-ui/script.js    |   8 +
 src/infrastructure/webview-provider.ts        | 193 +++++++++++++++-
 src/report-labels.ts                          |  17 ++
 tests/reportMarkdown.test.ts                  | 206 ++++++++++++++++++
 tests/webviewProviderExport.test.ts           |  97 +++++++++
 11 files changed, 600 insertions(+), 10 deletions(-)
 create mode 100644 tests/reportMarkdown.test.ts

diff --git a/src/domains/git/analytics-service.ts b/src/domains/git/analytics-service.ts
index bad39e1..0fa0c14 100644
--- a/src/domains/git/analytics-service.ts
+++ b/src/domains/git/analytics-service.ts
@@ -16,7 +16,7 @@ import {
   TrendData,
 } from "./analytics-types";
 import { ANALYTICS_SETTINGS, CACHE_SETTINGS, CO_CHANGE, WORKSPACE_EXCLUDE_BASE } from "../../constants";
-import { REPORT_LABELS, reportCsvHeader } from "../../report-labels";
+import { REPORT_LABELS, reportCsvHeader, reportMdHeader, mdEscape } from "../../report-labels";
 import { normalizeRenamePath } from "./git-path";
 import { TtlCache } from "../../infrastructure/cache";
 import { pathMatchesAny } from "../../infrastructure/glob-match";
@@ -636,3 +636,70 @@ export function gitReportToCsv(report: GitAnalyticsReport): string {
 
   return lines.join("\n");
 }
+
+/**
+ * Convert a git analytics report to Markdown. Mirrors gitReportToCsv's
+ * section structure (same caps) so the two exports can never diverge in
+ * coverage, only in framing.
+ */
+export function gitReportToMd(report: GitAnalyticsReport): string {
+  const lines: string[] = [];
+
+  lines.push(reportMdHeader(REPORT_LABELS.gitAnalytics));
+  lines.push("");
+  lines.push(`- **Period:** ${report.period}`);
+  lines.push(`- **Generated:** ${report.generatedAt.toISOString()}`);
+  lines.push("");
+
+  const sum = report.summary;
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| Metric | Value |");
+  lines.push("| --- | --- |");
+  lines.push(`| Total Commits | ${sum.totalCommits} |`);
+  lines.push(`| Total Authors | ${sum.totalAuthors} |`);
+  lines.push(`| Total Files Modified | ${sum.totalFilesModified} |`);
+  lines.push(`| Lines Added | ${sum.totalLinesAdded} |`);
+  lines.push(`| Lines Deleted | ${sum.totalLinesDeleted} |`);
+  lines.push(`| Commit Frequency (per week) | ${sum.commitFrequency.toFixed(2)} |`);
+  lines.push(`| Avg Commit Size | ${sum.averageCommitSize.toFixed(2)} |`);
+  lines.push(`| Churn Rate | ${sum.churnRate.toFixed(2)} |`);
+  lines.push("");
+
+  lines.push("## Files");
+  lines.push("");
+  lines.push("| Path | Commits | Insertions | Deletions | Volatility | Risk | Authors | Last Modified |");
+  lines.push("| --- | --- | --- | --- | --- | --- | --- | --- |");
+  for (const file of report.files.slice(0, ANALYTICS_SETTINGS.CSV_MAX_FILES)) {
+    lines.push(
+      `| ${mdEscape(file.path)} | ${file.commitCount} | ${file.insertions} | ${file.deletions} | ${file.volatility.toFixed(2)} | ${file.risk} | ${mdEscape(file.authors.join("; "))} | ${file.lastModified.toISOString()} |`
+    );
+  }
+  lines.push("");
+
+  lines.push("## Authors");
+  lines.push("");
+  lines.push("| Name | Commits | Insertions | Deletions | Files Changed | Last Active |");
+  lines.push("| --- | --- | --- | --- | --- | --- |");
+  for (const author of report.authors) {
+    lines.push(
+      `| ${mdEscape(author.name)} | ${author.commits} | ${author.insertions} | ${author.deletions} | ${author.filesChanged} | ${author.lastActive.toISOString()} |`
+    );
+  }
+
+  const coChange = report.coChange ?? [];
+  if (coChange.length > 0) {
+    lines.push("");
+    lines.push("## Change Companions");
+    lines.push("");
+    lines.push("| File A | File B | Co-Changes | Co-change % |");
+    lines.push("| --- | --- | --- | --- |");
+    for (const pair of coChange.slice(0, CO_CHANGE.CSV_MAX_PAIRS)) {
+      lines.push(
+        `| ${mdEscape(pair.a)} | ${mdEscape(pair.b)} | ${pair.count} | ${(pair.coChangeRate * 100).toFixed(0)} |`
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
diff --git a/src/domains/git/analytics-ui/index.html b/src/domains/git/analytics-ui/index.html
index 8d306b1..93bfaae 100644
--- a/src/domains/git/analytics-ui/index.html
+++ b/src/domains/git/analytics-ui/index.html
@@ -16,6 +16,8 @@ <h1>Git Analytics</h1>
       <div class="header-actions">
         <button id="exportCsv" class="btn-secondary" title="Quick-save CSV to .meridian/artifacts/">↓ CSV</button>
         <button id="exportJson" class="btn-secondary" title="Quick-save JSON to .meridian/artifacts/">↓ JSON</button>
+        <button id="exportMd" class="btn-secondary" title="Quick-save Markdown to .meridian/artifacts/">↓ MD</button>
+        <button id="copyMd" class="btn-secondary" title="Copy Markdown to clipboard">Copy MD</button>
         <button id="exportAs" class="btn-secondary" title="Choose format and location…">Save as…</button>
         <button id="refreshBtn">↺ Refresh</button>
       </div>
diff --git a/src/domains/git/analytics-ui/script.js b/src/domains/git/analytics-ui/script.js
index 9080c00..8c7e5f4 100644
--- a/src/domains/git/analytics-ui/script.js
+++ b/src/domains/git/analytics-ui/script.js
@@ -467,6 +467,14 @@ document.getElementById("exportCsv")?.addEventListener("click", () => {
   vscode?.postMessage({ type: "export", format: "csv" });
 });
 
+document.getElementById("exportMd")?.addEventListener("click", () => {
+  vscode?.postMessage({ type: "export", format: "md" });
+});
+
+document.getElementById("copyMd")?.addEventListener("click", () => {
+  vscode?.postMessage({ type: "copyMarkdown" });
+});
+
 document.getElementById("exportAs")?.addEventListener("click", () => {
   vscode?.postMessage({ type: "exportAs" });
 });
diff --git a/src/domains/git/session-briefing-ui/index.html b/src/domains/git/session-briefing-ui/index.html
index 352761e..3ae1d7b 100644
--- a/src/domains/git/session-briefing-ui/index.html
+++ b/src/domains/git/session-briefing-ui/index.html
@@ -15,6 +15,8 @@ <h1>Session Briefing</h1>
       <div class="header-actions">
         <button id="exportCsv" class="btn-secondary" title="Quick-save CSV to .meridian/artifacts/">&#8595; CSV</button>
         <button id="exportJson" class="btn-secondary" title="Quick-save JSON to .meridian/artifacts/">&#8595; JSON</button>
+        <button id="exportMd" class="btn-secondary" title="Quick-save Markdown to .meridian/artifacts/">&#8595; MD</button>
+        <button id="copyMd" class="btn-secondary" title="Copy Markdown to clipboard">Copy MD</button>
         <button id="exportAs" class="btn-secondary" title="Choose format and location&#8230;">Save as&#8230;</button>
         <button id="refreshBtn">&#8634; Refresh</button>
       </div>
diff --git a/src/domains/git/session-briefing-ui/script.js b/src/domains/git/session-briefing-ui/script.js
index 022a83c..0cae097 100644
--- a/src/domains/git/session-briefing-ui/script.js
+++ b/src/domains/git/session-briefing-ui/script.js
@@ -32,6 +32,12 @@
   document.getElementById("exportJson").addEventListener("click", function () {
     vscode.postMessage({ type: "export", format: "json" });
   });
+  document.getElementById("exportMd").addEventListener("click", function () {
+    vscode.postMessage({ type: "export", format: "md" });
+  });
+  document.getElementById("copyMd").addEventListener("click", function () {
+    vscode.postMessage({ type: "copyMarkdown" });
+  });
   document.getElementById("exportAs").addEventListener("click", function () {
     vscode.postMessage({ type: "exportAs" });
   });
diff --git a/src/domains/hygiene/analytics-ui/index.html b/src/domains/hygiene/analytics-ui/index.html
index 88455dc..0364604 100644
--- a/src/domains/hygiene/analytics-ui/index.html
+++ b/src/domains/hygiene/analytics-ui/index.html
@@ -17,6 +17,8 @@ <h1>Hygiene Analytics</h1>
       <div class="header-actions">
         <button id="exportCsvBtn" class="btn-secondary" title="Quick-save CSV to .meridian/artifacts/">↓ CSV</button>
         <button id="exportJsonBtn" class="btn-secondary" title="Quick-save JSON to .meridian/artifacts/">↓ JSON</button>
+        <button id="exportMdBtn" class="btn-secondary" title="Quick-save Markdown to .meridian/artifacts/">↓ MD</button>
+        <button id="copyMdBtn" class="btn-secondary" title="Copy Markdown to clipboard">Copy MD</button>
         <button id="exportAsBtn" class="btn-secondary" title="Choose format and location…">Save as…</button>
         <button id="refreshBtn">Refresh</button>
       </div>
diff --git a/src/domains/hygiene/analytics-ui/script.js b/src/domains/hygiene/analytics-ui/script.js
index dc0797f..f5f3905 100644
--- a/src/domains/hygiene/analytics-ui/script.js
+++ b/src/domains/hygiene/analytics-ui/script.js
@@ -408,6 +408,14 @@ document.getElementById("exportCsvBtn")?.addEventListener("click", () => {
   vscode?.postMessage({ type: "export", format: "csv" });
 });
 
+document.getElementById("exportMdBtn")?.addEventListener("click", () => {
+  vscode?.postMessage({ type: "export", format: "md" });
+});
+
+document.getElementById("copyMdBtn")?.addEventListener("click", () => {
+  vscode?.postMessage({ type: "copyMarkdown" });
+});
+
 document.getElementById("exportAsBtn")?.addEventListener("click", () => {
   vscode?.postMessage({ type: "exportAs" });
 });
diff --git a/src/infrastructure/webview-provider.ts b/src/infrastructure/webview-provider.ts
index 2c43ffe..223f82b 100644
--- a/src/infrastructure/webview-provider.ts
+++ b/src/infrastructure/webview-provider.ts
@@ -4,12 +4,13 @@ import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { GitAnalyticsReport, AnalyticsOptions } from "../domains/git/analytics-types";
-import { gitReportToCsv } from "../domains/git/analytics-service";
+import { gitReportToCsv, gitReportToMd } from "../domains/git/analytics-service";
 import { HygieneAnalyticsReport } from "../domains/hygiene/analytics-types";
 import { SessionBriefingReport } from "../domains/git/types";
 import { resolveWorkspacePath } from "../security/path-guard";
 import { appendIgnorePattern } from "../security/ignore-store";
-import { REPORT_LABELS, reportCsvHeader } from "../report-labels";
+import { copyWithPolicy } from "../security/operation-policy";
+import { REPORT_LABELS, reportCsvHeader, reportMdHeader, mdEscape } from "../report-labels";
 import { MERIDIAN_DIR, MERIDIAN_ARTIFACTS_DIR } from "../constants";
 import type { ReportOpenArg } from "../ui/tree-providers/reports-tree-provider";
 import type { Logger } from "../types";
@@ -55,6 +56,7 @@ export abstract class BaseWebviewProvider<TReport> {
   protected abstract getUiDirSegments(): string[];
   protected abstract getExportFilenamePrefix(): string;
   protected abstract reportToCsv(report: TReport): string;
+  protected abstract reportToMarkdown(report: TReport): string;
   protected abstract onMessage(msg: { type: string; [key: string]: unknown }): Promise<void>;
   /** Snapshot kind for the ADR 020 `.meridian/latest/` write on every updateReport(). */
   protected abstract getLatestSnapshotKind(): LatestSnapshotKind;
@@ -93,6 +95,10 @@ export abstract class BaseWebviewProvider<TReport> {
       await this.handleSaveAs();
       return;
     }
+    if (msg.type === "copyMarkdown") {
+      await this.handleCopyMarkdown();
+      return;
+    }
     if (msg.type === "ignorePath") {
       await this.handleIgnorePath(msg.payload as { path?: string; kind?: string } | undefined);
       return;
@@ -209,10 +215,23 @@ export abstract class BaseWebviewProvider<TReport> {
 
   /** Serialize the current report in the requested format, or null if absent/invalid. */
   private serializeReport(format: string): string | null {
-    if (!this.lastReport || (format !== "json" && format !== "csv")) return null;
-    return format === "json"
-      ? this.reportToJson(this.lastReport)
-      : this.reportToCsv(this.lastReport);
+    if (!this.lastReport || (format !== "json" && format !== "csv" && format !== "md")) {
+      return null;
+    }
+    if (format === "json") return this.reportToJson(this.lastReport);
+    if (format === "md") return this.reportToMarkdown(this.lastReport);
+    return this.reportToCsv(this.lastReport);
+  }
+
+  /**
+   * Copy the markdown rendering of the current report to the clipboard,
+   * routed through the security.clipboard.autoCopy policy (same gate as the
+   * impact-analysis summary copy — no new clipboard surface).
+   */
+  protected async handleCopyMarkdown(): Promise<void> {
+    const content = this.serializeReport("md");
+    if (content === null) return;
+    await copyWithPolicy(content, `${this.getViewTitle()} markdown`);
   }
 
   /** Timestamped, Windows-safe filename for this report (millisecond precision). */
@@ -301,11 +320,11 @@ export abstract class BaseWebviewProvider<TReport> {
    * .meridian/artifacts/). The escape hatch for saving anywhere.
    */
   protected async handleSaveAs(): Promise<void> {
-    const picked = await vscode.window.showQuickPick(["JSON", "CSV"], {
+    const picked = await vscode.window.showQuickPick(["JSON", "CSV", "Markdown"], {
       placeHolder: "Export format",
     });
     if (!picked) return;
-    const format = picked.toLowerCase();
+    const format = picked === "Markdown" ? "md" : picked.toLowerCase();
 
     const content = this.serializeReport(format);
     if (content === null) return;
@@ -320,7 +339,9 @@ export abstract class BaseWebviewProvider<TReport> {
 
     const filters: Record<string, string[]> = format === "json"
       ? { "JSON Files": ["json"] }
-      : { "CSV Files": ["csv"] };
+      : format === "md"
+        ? { "Markdown Files": ["md"] }
+        : { "CSV Files": ["csv"] };
 
     const uri = await vscode.window.showSaveDialog({ defaultUri, filters });
     if (!uri) return;
@@ -423,6 +444,10 @@ export class AnalyticsWebviewProvider extends BaseWebviewProvider<GitAnalyticsRe
     return gitReportToCsv(report);
   }
 
+  protected reportToMarkdown(report: GitAnalyticsReport): string {
+    return gitReportToMd(report);
+  }
+
   protected async onMessage(msg: { type: string; payload?: unknown }): Promise<void> {
     if (msg.type === "filter") {
       try {
@@ -524,6 +549,31 @@ export class HygieneAnalyticsWebviewProvider extends BaseWebviewProvider<Hygiene
     return lines.join("\n");
   }
 
+  protected reportToMarkdown(report: HygieneAnalyticsReport): string {
+    const lines: string[] = [];
+
+    lines.push(reportMdHeader(REPORT_LABELS.hygieneAnalytics));
+    lines.push("");
+    lines.push(`- **Generated:** ${report.generatedAt instanceof Date ? report.generatedAt.toISOString() : String(report.generatedAt)}`);
+    lines.push(`- **Workspace:** ${mdEscape(report.workspaceRoot)}`);
+    lines.push(`- **Total Files:** ${report.summary.totalFiles}`);
+    lines.push(`- **Prune Candidates:** ${report.summary.pruneCount}`);
+    lines.push(`- **Estimated Savings:** ${(report.summary.pruneEstimateSizeBytes / 1024).toFixed(1)} KB`);
+    lines.push("");
+
+    lines.push("## Files");
+    lines.push("");
+    lines.push("| Path | Size (bytes) | Lines | Age (days) | Category | Prune Candidate |");
+    lines.push("| --- | --- | --- | --- | --- | --- |");
+    for (const f of report.files) {
+      lines.push(
+        `| ${mdEscape(f.path)} | ${f.sizeBytes} | ${f.lineCount} | ${f.ageDays} | ${f.category} | ${f.isPruneCandidate} |`
+      );
+    }
+
+    return lines.join("\n");
+  }
+
   protected async onMessage(msg: { type: string; [key: string]: unknown }): Promise<void> {
     if (msg.type === "refresh") {
       try {
@@ -702,6 +752,131 @@ export class SessionBriefingWebviewProvider extends BaseWebviewProvider<SessionB
     return lines.join("\n");
   }
 
+  protected reportToMarkdown(report: SessionBriefingReport): string {
+    const lines: string[] = [];
+
+    lines.push(reportMdHeader(REPORT_LABELS.sessionBriefing));
+    lines.push("");
+    lines.push(`- **Generated:** ${report.generatedAt}`);
+    lines.push(`- **Branch:** ${mdEscape(report.branch)}`);
+    lines.push(`- **Dirty:** ${report.isDirty}`);
+    lines.push(`- **Staged:** ${report.staged}`);
+    lines.push(`- **Unstaged:** ${report.unstaged}`);
+    lines.push(`- **Untracked:** ${report.untracked}`);
+    lines.push("");
+
+    lines.push("## Recent Commits");
+    lines.push("");
+    lines.push("| Hash | Author | Message | Insertions | Deletions |");
+    lines.push("| --- | --- | --- | --- | --- |");
+    for (const c of report.recentCommits) {
+      lines.push(
+        `| ${c.shortHash} | ${mdEscape(c.author)} | ${mdEscape(c.message)} | ${c.insertions} | ${c.deletions} |`
+      );
+    }
+    lines.push("");
+
+    lines.push("## Uncommitted Files");
+    lines.push("");
+    lines.push("| Path | Status |");
+    lines.push("| --- | --- |");
+    for (const f of report.uncommittedFiles) {
+      lines.push(`| ${mdEscape(f.path)} | ${f.status} |`);
+    }
+
+    const w = report.activityWindow;
+    if (w) {
+      lines.push("");
+      lines.push("## Activity");
+      lines.push("");
+      lines.push(`- **Period:** ${w.period}`);
+      lines.push(`- **Commits In Window:** ${w.commitsInWindow}`);
+      lines.push(`- **Files Touched:** ${w.filesTouched}`);
+      if (w.trends) {
+        lines.push(`- **Commit Trend:** ${w.trends.commitDirection}`);
+        lines.push(`- **Commit Confidence:** ${w.trends.commitConfidence}`);
+        lines.push(`- **Volatility Trend:** ${w.trends.volatilityDirection}`);
+      }
+      lines.push("");
+      lines.push("### Top Contributors");
+      lines.push("");
+      lines.push("| Name | Commits |");
+      lines.push("| --- | --- |");
+      for (const a of w.topContributors) {
+        lines.push(`| ${mdEscape(a.name)} | ${a.commits} |`);
+      }
+      if (w.topChurnFiles && w.topChurnFiles.length > 0) {
+        lines.push("");
+        lines.push("### Top Churn Files");
+        lines.push("");
+        lines.push("| Path | Volatility | Risk |");
+        lines.push("| --- | --- | --- |");
+        for (const f of w.topChurnFiles) {
+          lines.push(`| ${mdEscape(f.path)} | ${f.volatility} | ${f.risk} |`);
+        }
+      }
+    }
+
+    const h = report.hygieneSnapshot;
+    if (h) {
+      lines.push("");
+      lines.push("## Hygiene");
+      lines.push("");
+      lines.push(`- **Scanned At:** ${h.scannedAt}`);
+      lines.push(`- **Dead Files:** ${h.deadFileCount}`);
+      lines.push(`- **Large Files:** ${h.largeFileCount}`);
+      lines.push(`- **Log Files:** ${h.logFileCount}`);
+      lines.push(`- **Dead Code Items:** ${h.deadCodeItemCount}`);
+      if (h.deadCodeSample && h.deadCodeSample.length > 0) {
+        lines.push("");
+        lines.push("### Dead Code Sample");
+        lines.push("");
+        lines.push("| File | Line | Message |");
+        lines.push("| --- | --- | --- |");
+        for (const d of h.deadCodeSample) {
+          lines.push(`| ${mdEscape(d.filePath)} | ${d.line} | ${mdEscape(d.message)} |`);
+        }
+      }
+    }
+
+    const pr = report.pendingChangeRisk;
+    if (pr && pr.files.length > 0) {
+      lines.push("");
+      lines.push("## Pending-Change Risk");
+      lines.push("");
+      lines.push(`- **Total Changed:** ${pr.totalChanged}`);
+      lines.push(`- **High-Risk:** ${pr.hotspotCount}`);
+      lines.push(`- **Capped:** ${pr.capped}`);
+      lines.push("");
+      lines.push("| Path | Status | Churn | Volatility | Risk |");
+      lines.push("| --- | --- | --- | --- | --- |");
+      for (const f of pr.files) {
+        lines.push(
+          `| ${mdEscape(f.path)} | ${f.status} | ${f.churn ?? ""} | ${f.volatility ?? ""} | ${f.risk} |`
+        );
+      }
+    }
+
+    const pc2 = report.pendingChangeCompanions;
+    if (pc2 && pc2.files.length > 0) {
+      lines.push("");
+      lines.push("## Pending-Change Companions");
+      lines.push("");
+      lines.push(`- **Suggested:** ${pc2.count}`);
+      lines.push(`- **Capped:** ${pc2.capped}`);
+      lines.push("");
+      lines.push("| Path | Co-Changes | Co-change % | Ships With |");
+      lines.push("| --- | --- | --- | --- |");
+      for (const f of pc2.files) {
+        lines.push(
+          `| ${mdEscape(f.path)} | ${f.count} | ${(f.coChangeRate * 100).toFixed(0)} | ${mdEscape(f.becauseOf.join("; "))} |`
+        );
+      }
+    }
+
+    return lines.join("\n");
+  }
+
   protected async onMessage(msg: { type: string; [key: string]: unknown }): Promise<void> {
     if (msg.type === "refresh") {
       try {
diff --git a/src/report-labels.ts b/src/report-labels.ts
index 7977a72..3dcd984 100644
--- a/src/report-labels.ts
+++ b/src/report-labels.ts
@@ -10,3 +10,20 @@ export type ReportLabelKey = keyof typeof REPORT_LABELS;
 export function reportCsvHeader(label: string): string {
   return `${label} Report`;
 }
+
+export function reportMdHeader(label: string): string {
+  return `# ${label} Report`;
+}
+
+/**
+ * Escape a value for a markdown table cell: pipes and backticks are escaped,
+ * newlines collapsed to spaces so a multi-line commit message can never break
+ * the row structure.
+ */
+export function mdEscape(value: string): string {
+  return value
+    .replace(/\r?\n/g, " ")
+    .replace(/\\/g, "\\\\")
+    .replace(/\|/g, "\\|")
+    .replace(/`/g, "\\`");
+}
diff --git a/tests/reportMarkdown.test.ts b/tests/reportMarkdown.test.ts
new file mode 100644
index 0000000..8cb69c4
--- /dev/null
+++ b/tests/reportMarkdown.test.ts
@@ -0,0 +1,206 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("vscode", () => ({
+  commands: { executeCommand: vi.fn() },
+  window: {
+    showErrorMessage: vi.fn(),
+    showInformationMessage: vi.fn(),
+    showSaveDialog: vi.fn(),
+    createWebviewPanel: vi.fn(),
+  },
+  workspace: { fs: { writeFile: vi.fn() } },
+  Uri: { file: (fsPath: string) => ({ fsPath }) },
+  ViewColumn: { One: 1 },
+}));
+
+import { mdEscape, reportMdHeader, REPORT_LABELS } from "../src/report-labels";
+import { gitReportToMd } from "../src/domains/git/analytics-service";
+import {
+  HygieneAnalyticsWebviewProvider,
+  SessionBriefingWebviewProvider,
+} from "../src/infrastructure/webview-provider";
+import type { GitAnalyticsReport } from "../src/domains/git/analytics-types";
+import type { HygieneAnalyticsReport } from "../src/domains/hygiene/analytics-types";
+import type { SessionBriefingReport } from "../src/domains/git/types";
+
+const WHEN = new Date("2026-07-07T12:00:00.000Z");
+
+function makeGitReport(): GitAnalyticsReport {
+  return {
+    period: "3mo",
+    generatedAt: WHEN,
+    summary: {
+      totalCommits: 2,
+      totalAuthors: 1,
+      totalFilesModified: 2,
+      totalLinesAdded: 10,
+      totalLinesDeleted: 4,
+      commitFrequency: 0.5,
+      averageCommitSize: 7,
+      churnRate: 1.25,
+    },
+    commits: [],
+    files: [
+      {
+        path: "src/pipe|and`tick.ts",
+        commitCount: 2,
+        insertions: 8,
+        deletions: 3,
+        volatility: 5.5,
+        authors: ["Ada | Lovelace"],
+        lastModified: WHEN,
+        risk: "high",
+      },
+    ],
+    authors: [
+      {
+        name: "Ada | Lovelace",
+        commits: 2,
+        insertions: 10,
+        deletions: 4,
+        filesChanged: 2,
+        lastActive: WHEN,
+      },
+    ],
+    trends: {
+      commitTrend: { slope: 0, direction: "stable", confidence: 0.5 },
+      volatilityTrend: { slope: 0, direction: "stable" },
+    },
+    commitFrequency: { labels: ["Week 1"], data: [2] },
+    churnFiles: [],
+    topAuthors: [],
+    coChange: [{ a: "a.ts", b: "b|c.ts", count: 3, coChangeRate: 0.75 }],
+  };
+}
+
+function makeBriefingReport(): SessionBriefingReport {
+  return {
+    generatedAt: "2026-07-07T12:00:00.000Z",
+    branch: "develop",
+    isDirty: true,
+    staged: 1,
+    unstaged: 1,
+    untracked: 0,
+    recentCommits: [
+      {
+        shortHash: "abc1234",
+        author: "Ada",
+        message: "fix: handle `weird|pipe`\nwith a second line",
+        insertions: 3,
+        deletions: 1,
+      },
+    ],
+    uncommittedFiles: [{ path: "src/a|b.ts", status: "M" }],
+    flags: [],
+    flagItems: [],
+    activityWindow: {
+      period: "3mo",
+      commitsInWindow: 2,
+      filesTouched: 3,
+      topContributors: [{ name: "Ada | Lovelace", commits: 2 }],
+    },
+    summary: "Quiet session.",
+  };
+}
+
+describe("markdown export helpers", () => {
+  it("reportMdHeader mirrors reportCsvHeader as an H1", () => {
+    expect(reportMdHeader(REPORT_LABELS.gitAnalytics)).toBe("# Git Analytics Report");
+  });
+
+  it("mdEscape escapes pipes and backticks and collapses newlines", () => {
+    expect(mdEscape("a|b")).toBe("a\\|b");
+    expect(mdEscape("run `cmd`")).toBe("run \\`cmd\\`");
+    expect(mdEscape("line one\nline two\r\nline three")).toBe("line one line two line three");
+    expect(mdEscape("back\\slash")).toBe("back\\\\slash");
+  });
+});
+
+describe("gitReportToMd", () => {
+  it("mirrors the CSV section structure with escaped table cells", () => {
+    const md = gitReportToMd(makeGitReport());
+
+    expect(md.startsWith("# Git Analytics Report")).toBe(true);
+    expect(md).toContain("## Summary");
+    expect(md).toContain("## Files");
+    expect(md).toContain("## Authors");
+    expect(md).toContain("## Change Companions");
+
+    // Real values off the report, escaped for table cells.
+    expect(md).toContain("| src/pipe\\|and\\`tick.ts | 2 | 8 | 3 | 5.50 | high |");
+    expect(md).toContain("| Ada \\| Lovelace | 2 | 10 | 4 | 2 |");
+    expect(md).toContain("| a.ts | b\\|c.ts | 3 | 75 |");
+    expect(md).toContain("- **Period:** 3mo");
+    expect(md).toContain(`- **Generated:** ${WHEN.toISOString()}`);
+  });
+
+  it("omits the Change Companions section when there are no pairs", () => {
+    const report = { ...makeGitReport(), coChange: [] };
+    expect(gitReportToMd(report)).not.toContain("Change Companions");
+  });
+});
+
+describe("SessionBriefingWebviewProvider.reportToMarkdown", () => {
+  it("renders commits and contributors with escaping, no row-breaking newlines", () => {
+    const provider = new SessionBriefingWebviewProvider(
+      { fsPath: "/ext" } as never,
+      "/ws",
+      async () => ({} as never)
+    );
+    const md: string = (provider as never as {
+      reportToMarkdown(r: SessionBriefingReport): string;
+    }).reportToMarkdown(makeBriefingReport());
+
+    expect(md.startsWith("# Session Briefing Report")).toBe(true);
+    expect(md).toContain("## Recent Commits");
+    expect(md).toContain("## Uncommitted Files");
+    expect(md).toContain("### Top Contributors");
+
+    // Multi-line commit message stays a single table row.
+    const commitRow = md.split("\n").find((l) => l.includes("abc1234"));
+    expect(commitRow).toBe(
+      "| abc1234 | Ada | fix: handle \\`weird\\|pipe\\` with a second line | 3 | 1 |"
+    );
+    expect(md).toContain("| src/a\\|b.ts | M |");
+    expect(md).toContain("| Ada \\| Lovelace | 2 |");
+    // Optional slices absent from the payload stay absent from the export.
+    expect(md).not.toContain("## Hygiene");
+    expect(md).not.toContain("## Pending-Change Risk");
+  });
+});
+
+describe("HygieneAnalyticsWebviewProvider.reportToMarkdown", () => {
+  it("renders summary bullets and the files table with escaping", () => {
+    const provider = new HygieneAnalyticsWebviewProvider(
+      { fsPath: "/ext" } as never,
+      async () => ({} as never)
+    );
+    // Only the fields the markdown builder consumes — same idiom as the CSV
+    // export tests; the serializer output itself is real.
+    const report = {
+      generatedAt: WHEN,
+      workspaceRoot: "/ws",
+      summary: { totalFiles: 3, pruneCount: 1, pruneEstimateSizeBytes: 2048 },
+      files: [
+        {
+          path: "logs/build|old`.log",
+          sizeBytes: 2048,
+          lineCount: 10,
+          ageDays: 40,
+          category: "log",
+          isPruneCandidate: true,
+        },
+      ],
+    } as unknown as HygieneAnalyticsReport;
+
+    const md: string = (provider as never as {
+      reportToMarkdown(r: HygieneAnalyticsReport): string;
+    }).reportToMarkdown(report);
+
+    expect(md.startsWith("# Hygiene Analytics Report")).toBe(true);
+    expect(md).toContain(`- **Generated:** ${WHEN.toISOString()}`);
+    expect(md).toContain("- **Total Files:** 3");
+    expect(md).toContain("- **Estimated Savings:** 2.0 KB");
+    expect(md).toContain("| logs/build\\|old\\`.log | 2048 | 10 | 40 | log | true |");
+  });
+});
diff --git a/tests/webviewProviderExport.test.ts b/tests/webviewProviderExport.test.ts
index b4d9a8e..e073737 100644
--- a/tests/webviewProviderExport.test.ts
+++ b/tests/webviewProviderExport.test.ts
@@ -9,6 +9,7 @@ const {
   showErrorMessageMock,
   showQuickPickMock,
   showSaveDialogMock,
+  clipboardWriteTextMock,
   workspaceState,
 } = vi.hoisted(() => ({
   writeFileMock: vi.fn(async () => {}),
@@ -16,6 +17,7 @@ const {
   showErrorMessageMock: vi.fn(() => Promise.resolve(undefined)),
   showQuickPickMock: vi.fn(),
   showSaveDialogMock: vi.fn(),
+  clipboardWriteTextMock: vi.fn(async () => {}),
   workspaceState: { root: undefined as string | undefined },
 }));
 
@@ -36,6 +38,9 @@ vi.mock("vscode", () => ({
     },
     fs: { writeFile: writeFileMock },
   },
+  env: {
+    clipboard: { writeText: clipboardWriteTextMock },
+  },
   Uri: {
     file: (fsPath: string) => ({ fsPath }),
   },
@@ -45,6 +50,8 @@ vi.mock("vscode", () => ({
 import * as vscode from "vscode";
 import { AnalyticsWebviewProvider } from "../src/infrastructure/webview-provider";
 import { flushLatestSnapshotWrites } from "../src/infrastructure/latest-snapshot";
+import { gitReportToMd } from "../src/domains/git/analytics-service";
+import type { GitAnalyticsReport } from "../src/domains/git/analytics-types";
 import { LATEST_SNAPSHOT_FILES, MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../src/constants";
 
 function makeProvider(root: string): AnalyticsWebviewProvider {
@@ -58,6 +65,38 @@ function makeProvider(root: string): AnalyticsWebviewProvider {
   return provider;
 }
 
+/** Minimal fully-typed report so the markdown paths serialize real values. */
+function makeGitReport(): GitAnalyticsReport {
+  const when = new Date("2026-07-07T12:00:00.000Z");
+  return {
+    period: "3mo",
+    generatedAt: when,
+    summary: {
+      totalCommits: 1,
+      totalAuthors: 1,
+      totalFilesModified: 1,
+      totalLinesAdded: 2,
+      totalLinesDeleted: 1,
+      commitFrequency: 0.25,
+      averageCommitSize: 3,
+      churnRate: 1,
+    },
+    commits: [],
+    files: [],
+    authors: [
+      { name: "Ada", commits: 1, insertions: 2, deletions: 1, filesChanged: 1, lastActive: when },
+    ],
+    trends: {
+      commitTrend: { slope: 0, direction: "stable", confidence: 0.5 },
+      volatilityTrend: { slope: 0, direction: "stable" },
+    },
+    commitFrequency: { labels: ["Week 1"], data: [1] },
+    churnFiles: [],
+    topAuthors: [],
+    coChange: [],
+  };
+}
+
 describe("WebviewProvider report export", () => {
   beforeEach(() => {
     writeFileMock.mockReset().mockResolvedValue(undefined);
@@ -65,6 +104,7 @@ describe("WebviewProvider report export", () => {
     showErrorMessageMock.mockReset().mockReturnValue(Promise.resolve(undefined));
     showQuickPickMock.mockReset();
     showSaveDialogMock.mockReset();
+    clipboardWriteTextMock.mockReset().mockResolvedValue(undefined);
     workspaceState.root = undefined;
   });
 
@@ -119,6 +159,63 @@ describe("WebviewProvider report export", () => {
     expect(fs.readFileSync(path.join(artifactsDir, ".gitignore"), "utf-8")).toBe("# custom\n");
   });
 
+  it("quick-save md writes the real markdown serialization", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-export-md-"));
+    workspaceState.root = root;
+    const provider = makeProvider(root);
+    const report = makeGitReport();
+    (provider as any).lastReport = report;
+
+    await (provider as any).handleQuickSave("md");
+
+    expect(writeFileMock).toHaveBeenCalledTimes(1);
+    const [target, buf] = writeFileMock.mock.calls[0] as unknown as [
+      { fsPath: string },
+      Buffer,
+    ];
+    expect(target.fsPath).toMatch(/meridian-git-analytics-.*\.md$/);
+    expect(buf.toString("utf-8")).toBe(gitReportToMd(report));
+  });
+
+  it("quick-save rejects an unknown format and writes nothing", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-export-bad-"));
+    workspaceState.root = root;
+    const provider = makeProvider(root);
+
+    await (provider as any).handleQuickSave("html");
+
+    expect(writeFileMock).not.toHaveBeenCalled();
+  });
+
+  it("copyMarkdown routes the markdown through the clipboard policy", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-copy-md-"));
+    workspaceState.root = root;
+    const provider = makeProvider(root);
+    const report = makeGitReport();
+    (provider as any).lastReport = report;
+
+    // autoCopy defaults to false → copyWithPolicy prompts; accepting copies.
+    showInformationMessageMock.mockReturnValue(Promise.resolve("Copy to Clipboard") as never);
+
+    await (provider as any).handleMessage({ type: "copyMarkdown" });
+
+    expect(showInformationMessageMock).toHaveBeenCalledWith(
+      "Git Analytics markdown is ready.",
+      "Copy to Clipboard"
+    );
+    expect(clipboardWriteTextMock).toHaveBeenCalledWith(gitReportToMd(report));
+  });
+
+  it("copyMarkdown with no report does nothing", async () => {
+    const provider = makeProvider("/tmp/none");
+    (provider as any).lastReport = null;
+
+    await (provider as any).handleMessage({ type: "copyMarkdown" });
+
+    expect(clipboardWriteTextMock).not.toHaveBeenCalled();
+    expect(showInformationMessageMock).not.toHaveBeenCalled();
+  });
+
   it("save-as cancelled (dialog returns nothing) leaves no artifacts dir behind", async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-export-"));
     workspaceState.root = root;

From 6b294246aa6f490ac03999cfddebe7679e0ea586 Mon Sep 17 00:00:00 2001
From: Steven Salmons <stevencsalmons@gmail.com>
Date: Tue, 7 Jul 2026 14:27:55 -0400
Subject: [PATCH 3/4] feat(reports): snapshot freshness in the Reports tree +
 reveal command

- latest-snapshot.ts: onLatestSnapshotWrite(cb) hook, notified inside the
  queue post-rename with the written kind; listener errors swallowed; module
  stays vscode-free
- ReportsTreeProvider: onDidChangeTreeData + refresh(); async getChildren
  stats the three latest/ snapshot mtimes (hygiene row -> hygieneAnalytics)
  into coarse relative-age descriptions via pure formatRelativeAge; no
  workspace -> no descriptions
- tree-setup: snapshot-write hook drives reportsTree.refresh() (disposable);
  new meridian.latest.reveal command (reveal latest/ in Explorer, or info
  message when no snapshots exist)
- package.json: command contributed to commands, commandPalette
  (workspace-open when), and the Reports view title; manifest whitelist
  updated
- Docs: ADR 020 internal mtime-only consumer note; FEATURES.md Reports-view
  and export-toolbar (MD/Copy MD, from previous commit) touch-ups

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/FEATURES.md                              |   4 +-
 docs/adr/020-latest-snapshot-contract.md      |   4 +
 package.json                                  |  17 +-
 src/infrastructure/latest-snapshot.ts         |  26 +++
 src/presentation/tree-setup.ts                |  25 ++-
 .../tree-providers/reports-tree-provider.ts   |  60 ++++++-
 tests/manifest.test.ts                        |   3 +-
 tests/reportsTreeFreshness.test.ts            | 162 ++++++++++++++++++
 8 files changed, 290 insertions(+), 11 deletions(-)
 create mode 100644 tests/reportsTreeFreshness.test.ts

diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index 6c4f338..7ec429b 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -22,7 +22,7 @@ Create a commit with a provided message. Validates the message, with comprehensi
 ### **git.showAnalytics**
 Open a full-screen dashboard displaying Git analytics: churn (commits per file), volatility (recent change frequency), authorship (commits per author), commit trends (over time), and top contributors. Includes a **Risk Hotspots** scatter — each file plotted by change frequency (x) against volatility (y), bubble size by total lines changed, colored by risk tier — so refactor candidates surface in the top-right at a glance. A **Change Companions** table surfaces files that change together in the same commit (co-change count + co-change rate), revealing hidden coupling — candidates to refactor together or split apart. Real-time chart rendering with drill-down.
 
-**Export (all report dashboards).** Each report webview (Git Analytics, Hygiene Analytics, Session Briefing) offers two save paths: **↓ CSV / ↓ JSON** quick-save the report dialog-free to `.meridian/artifacts/` with a timestamped filename (per [ADR 014](./adr/014-dotdir-doctrine.md); the dir self-ignores so artifacts never enter git), and **Save as…** opens a dialog (format + location) for saving anywhere. Every report render (initial open, refresh, or filter) also refreshes that report's `.meridian/latest/` agent-readable snapshot ([ADR 020](./adr/020-latest-snapshot-contract.md)).
+**Export (all report dashboards).** Each report webview (Git Analytics, Hygiene Analytics, Session Briefing) offers two save paths: **↓ CSV / ↓ JSON / ↓ MD** quick-save the report dialog-free to `.meridian/artifacts/` with a timestamped filename (per [ADR 014](./adr/014-dotdir-doctrine.md); the dir self-ignores so artifacts never enter git), and **Save as…** opens a dialog (format + location) for saving anywhere. **Copy MD** copies the markdown rendering to the clipboard through the `security.clipboard.autoCopy` policy. Every report render (initial open, refresh, or filter) also refreshes that report's `.meridian/latest/` agent-readable snapshot ([ADR 020](./adr/020-latest-snapshot-contract.md)).
 
 ### **git.sessionBriefing**
 Generate a session-orientation summary. Aggregates git working-tree status, recent commits, run-log activity (`recentRuns`), git analytics (`activityWindow` — including momentum trends and a commit-frequency sparkline showing the shape behind the trend arrow), hygiene scan state (`hygieneSnapshot`), and a pending-change risk preview (`pendingChangeRisk` — each uncommitted file joined against the computed analytics risk model: churn, volatility, and risk tier, with files absent from the analytics window marked `new` (no history) or `cold` (changed but quiet — low, not unknown); a flag is raised when several high-risk files are in flight), and a pending-change companion preview (`pendingChangeCompanions` — files that historically ship in the same commit as your current edits but are not in the dirty set yet, i.e. possibly-forgotten siblings such as tests/types/docs; a flag is raised when several are likely missing), and a longitudinal pulse slice (`pulse` — movement since your previous briefing plus trend lines over the stored history in `.meridian/pulse/`; snapshots are captured automatically per briefing, throttled to one per 10 minutes, capped and local-only per [ADR 019](./adr/019-pulse-and-retention.md)) into a deterministic `SessionBriefing` record, then layers optional AI prose on top. Optional slices degrade gracefully when data is unavailable; the prose layer degrades to the raw aggregate when no language model is available. Raised flags are surfaced as actionable cards in the briefing panel, each with a jump-to-section link and one-click actions. Useful for standup notes, context switching, pre-commit risk triage, or morning orientation.
@@ -64,7 +64,7 @@ Meridian polices its own storage ([ADR 019](./adr/019-pulse-and-retention.md)).
 ## Sidebar Views & UI
 
 ### **Panel Reports View** (`meridian.reports.view`)
-First view in the Meridian activity-bar container — the anchored, first-class entry point for the three webview reports, in order: **Session Briefing**, **Git Analytics**, **Hygiene Analytics**. Report rows carry no glyphs by design. Single-click (or the hover **View** action, `$(open-preview)`) reveals a live panel without recomputing, or runs the report once if no panel is open. The hover **Refresh** action (`$(refresh)`) always recomputes. The former in-tree "View Git Report" / "View Hygiene Report" nodes and the Git/Hygiene view-title report icons were removed — report entry now lives exclusively here.
+First view in the Meridian activity-bar container — the anchored, first-class entry point for the three webview reports, in order: **Session Briefing**, **Git Analytics**, **Hygiene Analytics**. Report rows carry no glyphs by design. Single-click (or the hover **View** action, `$(open-preview)`) reveals a live panel without recomputing, or runs the report once if no panel is open. The hover **Refresh** action (`$(refresh)`) always recomputes. Each row shows a coarse freshness description ("just now", "5m ago", …) read from its `.meridian/latest/` snapshot mtime, redrawn on every snapshot write; the view-title **Reveal Latest Snapshots** action (`Meridian: Reveal Latest Snapshots`, also in the palette) reveals `latest/` in the Explorer ([ADR 020](./adr/020-latest-snapshot-contract.md)). The former in-tree "View Git Report" / "View Hygiene Report" nodes and the Git/Hygiene view-title report icons were removed — report entry now lives exclusively here.
 
 ### **Git View** (`meridian.git.view`)
 Browse current branch, dirty state, change groups (staged/unstaged/untracked, expandable to files), and recent commits. The Git Analytics report is reached via the Panel Reports view.
diff --git a/docs/adr/020-latest-snapshot-contract.md b/docs/adr/020-latest-snapshot-contract.md
index 6af016d..c52069c 100644
--- a/docs/adr/020-latest-snapshot-contract.md
+++ b/docs/adr/020-latest-snapshot-contract.md
@@ -171,6 +171,10 @@ new subsystem.
 - **Layering invariant.** `src/infrastructure/latest-snapshot.ts` has no
   `vscode` import and no dependency on `src/domains/*`; `BaseWebviewProvider`
   is the only caller. Consistent with `retention.ts` / `jsonl-tail.ts`.
+- **Internal consumer.** The Reports tree is a sanctioned internal consumer
+  of `latest/` — but mtime-only: it stats the three files for its coarse
+  "updated Nm ago" row descriptions (redrawn via `onLatestSnapshotWrite`)
+  and never parses the JSON, so it cannot couple to the envelope shape.
 
 ## Cross-references
 
diff --git a/package.json b/package.json
index 6d8d0a4..d207033 100644
--- a/package.json
+++ b/package.json
@@ -172,6 +172,12 @@
           "dark": "media/glyph-dark.svg"
         },
         "category": "Meridian"
+      },
+      {
+        "command": "meridian.latest.reveal",
+        "title": "Reveal Latest Snapshots",
+        "icon": "$(folder-opened)",
+        "category": "Meridian"
       }
     ],
     "configuration": {
@@ -403,6 +409,10 @@
         {
           "command": "meridian.hygiene.impactAnalysis",
           "when": "workspaceFolderCount > 0"
+        },
+        {
+          "command": "meridian.latest.reveal",
+          "when": "workspaceFolderCount > 0"
         }
       ],
       "view/title": [
@@ -417,10 +427,15 @@
           "group": "navigation@1"
         },
         {
-          "command": "meridian.openSettings",
+          "command": "meridian.latest.reveal",
           "when": "view == meridian.reports.view",
           "group": "navigation@1"
         },
+        {
+          "command": "meridian.openSettings",
+          "when": "view == meridian.reports.view",
+          "group": "navigation@2"
+        },
         {
           "command": "meridian.openSettings",
           "when": "view == meridian.git.view",
diff --git a/src/infrastructure/latest-snapshot.ts b/src/infrastructure/latest-snapshot.ts
index 45ae5df..2102a7b 100644
--- a/src/infrastructure/latest-snapshot.ts
+++ b/src/infrastructure/latest-snapshot.ts
@@ -117,6 +117,23 @@ async function writeFileIfMissing(filePath: string, content: string, logger: Log
  */
 let writeQueue: Promise<void> = Promise.resolve();
 
+export type LatestSnapshotWriteListener = (kind: LatestSnapshotKind) => void;
+
+const writeListeners = new Set<LatestSnapshotWriteListener>();
+
+/**
+ * Subscribe to successful snapshot writes (invoked inside the queue, after
+ * the rename lands). Returns an unsubscribe function. Listener errors are
+ * swallowed — a bad subscriber can never stall the queue or fail a write.
+ * Module stays `vscode`-free; callers adapt the unsubscribe to a Disposable.
+ */
+export function onLatestSnapshotWrite(listener: LatestSnapshotWriteListener): () => void {
+  writeListeners.add(listener);
+  return () => {
+    writeListeners.delete(listener);
+  };
+}
+
 /**
  * Write `report` to `.meridian/latest/<kind>.v1.json`, atomically (unique
  * tmp + rename) so a concurrent reader never observes torn JSON.
@@ -162,6 +179,15 @@ export function writeLatestSnapshot(
         // Best-effort cleanup only — nothing further to do on double failure.
       });
       logger.warn(`Latest-snapshot write failed for ${kind}: ${String(e)}`, "writeLatestSnapshot");
+      return;
+    }
+
+    for (const listener of writeListeners) {
+      try {
+        listener(kind);
+      } catch {
+        // Listener errors never fail the write or stall the queue.
+      }
     }
   };
 
diff --git a/src/presentation/tree-setup.ts b/src/presentation/tree-setup.ts
index 5b5c689..bb98c58 100644
--- a/src/presentation/tree-setup.ts
+++ b/src/presentation/tree-setup.ts
@@ -3,7 +3,11 @@
  */
 
 import * as vscode from "vscode";
+import * as fs from "fs";
+import * as path from "path";
 import { Command, CommandContext, GitProvider, Logger, Result } from "../types";
+import { MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../constants";
+import { onLatestSnapshotWrite } from "../infrastructure/latest-snapshot";
 import { GitTreeProvider } from "../ui/tree-providers/git-tree-provider";
 import { HygieneTreeProvider } from "../ui/tree-providers/hygiene-tree-provider";
 import {
@@ -43,12 +47,18 @@ export function setupTreeProviders(
 ): TreeProviders {
   const gitTree     = new GitTreeProvider(gitProvider, logger, workspaceRoot);
   const hygieneTree = new HygieneTreeProvider(dispatch, cmdCtx, logger);
-  const reportsTree = new ReportsTreeProvider();
+  // Real workspace folder only (not the cwd fallback in workspaceRoot):
+  // without one there are no snapshots, so rows render without freshness.
+  const workspaceFolder = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+  const reportsTree = new ReportsTreeProvider(workspaceFolder);
 
   context.subscriptions.push(
     vscode.window.registerTreeDataProvider("meridian.reports.view", reportsTree),
     vscode.window.registerTreeDataProvider("meridian.git.view",     gitTree),
     vscode.window.registerTreeDataProvider("meridian.hygiene.view", hygieneTree),
+    // Freshness: redraw the Reports rows whenever a latest snapshot lands, so
+    // "updated Nm ago" descriptions track renders without any live timer.
+    { dispose: onLatestSnapshotWrite(() => reportsTree.refresh()) },
   );
 
   // reportId → underlying VS Code command + its webview panel provider.
@@ -73,6 +83,19 @@ export function setupTreeProviders(
       if (!item) return;
       void vscode.commands.executeCommand(reportMap[item.reportId].cmd);
     }),
+    // Surface the on-disk ADR 020 snapshots to humans. Reveal-if-present;
+    // otherwise explain how they come into being.
+    vscode.commands.registerCommand("meridian.latest.reveal", () => {
+      const root = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
+      const latestDir = root ? path.join(root, MERIDIAN_DIR, MERIDIAN_LATEST_DIR) : null;
+      if (latestDir && fs.existsSync(latestDir)) {
+        void vscode.commands.executeCommand("revealInExplorer", vscode.Uri.file(latestDir));
+      } else {
+        void vscode.window.showInformationMessage(
+          "No snapshots yet — open any Meridian report to generate them."
+        );
+      }
+    }),
     // Branded "Meridian Settings" title action — host-portable replacement for
     // VS Code's implicit view→extension settings cog, which Cursor doesn't honor
     // (its click falls through to Cursor's top-level settings). Contributed to
diff --git a/src/ui/tree-providers/reports-tree-provider.ts b/src/ui/tree-providers/reports-tree-provider.ts
index f8ab1f4..962191e 100644
--- a/src/ui/tree-providers/reports-tree-provider.ts
+++ b/src/ui/tree-providers/reports-tree-provider.ts
@@ -1,6 +1,9 @@
 /**
  * Reports Tree Provider — first-class, anchored entry points for the webview
- * reports. Static three-row tree (no scanning, no fetching).
+ * reports. Static three-row tree (no scanning, no fetching) plus a coarse
+ * freshness description per row, read off the `.meridian/latest/` snapshot
+ * mtimes (ADR 020). The tree is an internal, mtime-only consumer of that
+ * contract — it never parses the snapshot JSON.
  *
  * Standard: every webview-report row carries one identical icon
  * (ThemeIcon "graph") so the reports read as a single visual class wherever
@@ -9,7 +12,10 @@
  */
 
 import * as vscode from "vscode";
+import { promises as fsp } from "node:fs";
+import * as path from "node:path";
 import { REPORT_LABELS } from "../../report-labels";
+import { LATEST_SNAPSHOT_FILES, MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../../constants";
 
 export type ReportId = "sessionBriefing" | "gitAnalytics" | "hygiene";
 
@@ -29,6 +35,27 @@ const REPORTS: ReadonlyArray<{ id: ReportId; label: string }> = [
   { id: "hygiene", label: REPORT_LABELS.hygieneAnalytics },
 ];
 
+/** ReportId → latest-snapshot filename. The tree's `hygiene` row reads the `hygieneAnalytics` snapshot. */
+const REPORT_SNAPSHOT_FILE: Record<ReportId, string> = {
+  sessionBriefing: LATEST_SNAPSHOT_FILES.sessionBriefing,
+  gitAnalytics: LATEST_SNAPSHOT_FILES.gitAnalytics,
+  hygiene: LATEST_SNAPSHOT_FILES.hygieneAnalytics,
+};
+
+/**
+ * Coarse relative age for a tree-row description. Deliberately minute-grained
+ * (no seconds, no live timer): recomputed only on tree redraw and on
+ * snapshot-write refresh.
+ */
+export function formatRelativeAge(ageMs: number): string {
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
 export class ReportTreeItem extends vscode.TreeItem {
   constructor(public readonly reportId: ReportId, label: string) {
     super(label, vscode.TreeItemCollapsibleState.None);
@@ -45,15 +72,36 @@ export class ReportTreeItem extends vscode.TreeItem {
 }
 
 export class ReportsTreeProvider implements vscode.TreeDataProvider<ReportTreeItem> {
-  private readonly items: ReportTreeItem[] = REPORTS.map(
-    (r) => new ReportTreeItem(r.id, r.label)
-  );
+  private readonly changeEmitter = new vscode.EventEmitter<void>();
+  readonly onDidChangeTreeData = this.changeEmitter.event;
+
+  /** No workspace root → rows render without freshness descriptions. */
+  constructor(private readonly workspaceRoot?: string) {}
+
+  refresh(): void {
+    this.changeEmitter.fire();
+  }
 
   getTreeItem(element: ReportTreeItem): vscode.TreeItem {
     return element;
   }
 
-  getChildren(element?: ReportTreeItem): ReportTreeItem[] {
-    return element ? [] : this.items;
+  async getChildren(element?: ReportTreeItem): Promise<ReportTreeItem[]> {
+    if (element) return [];
+    const items = REPORTS.map((r) => new ReportTreeItem(r.id, r.label));
+    if (!this.workspaceRoot) return items;
+
+    const latestDir = path.join(this.workspaceRoot, MERIDIAN_DIR, MERIDIAN_LATEST_DIR);
+    await Promise.all(
+      items.map(async (item) => {
+        try {
+          const stat = await fsp.stat(path.join(latestDir, REPORT_SNAPSHOT_FILE[item.reportId]));
+          item.description = formatRelativeAge(Date.now() - stat.mtimeMs);
+        } catch {
+          // No snapshot yet for this report — leave the description absent.
+        }
+      })
+    );
+    return items;
   }
 }
diff --git a/tests/manifest.test.ts b/tests/manifest.test.ts
index f29ee36..a7ac942 100644
--- a/tests/manifest.test.ts
+++ b/tests/manifest.test.ts
@@ -22,12 +22,13 @@ import { SETTING_DEFAULTS } from "../src/infrastructure/settings";
 
 // ── Whitelists ────────────────────────────────────────────────────────────────
 
-/** Registered in specialized-commands.ts (ADR 005). Not in COMMAND_MAP. */
+/** Dedicated registrations outside COMMAND_MAP (ADR 005): custom UI/param sourcing. */
 const SPECIALIZED_COMMANDS = new Set([
   "meridian.hygiene.deleteFile",
   "meridian.hygiene.ignoreFile",
   "meridian.hygiene.impactAnalysis", // ADR 005: active-file fallback + InputBox prompt
   "meridian.hygiene.pruneStorage",   // ADR 019: status preview + confirmation modal
+  "meridian.latest.reveal",          // tree-setup.ts: reveal-or-explain .meridian/latest/ (ADR 020)
 ]);
 
 /** View lifecycle commands. No routing, no palette exposure. */
diff --git a/tests/reportsTreeFreshness.test.ts b/tests/reportsTreeFreshness.test.ts
new file mode 100644
index 0000000..42abe87
--- /dev/null
+++ b/tests/reportsTreeFreshness.test.ts
@@ -0,0 +1,162 @@
+/**
+ * Reports-tree freshness — coarse relative-age descriptions read off the
+ * `.meridian/latest/` snapshot mtimes (mtime-only ADR 020 consumer), plus the
+ * onLatestSnapshotWrite hook that drives the redraw.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+vi.mock("vscode", () => ({
+  TreeItem: class {
+    description?: string;
+    constructor(public label: string, public collapsibleState?: number) {}
+  },
+  TreeItemCollapsibleState: { None: 0, Collapsed: 1, Expanded: 2 },
+  ThemeIcon: class { constructor(public id: string) {} },
+  EventEmitter: class {
+    private listeners: Array<(arg: unknown) => void> = [];
+    event = (cb: (arg: unknown) => void) => { this.listeners.push(cb); return { dispose: () => {} }; };
+    fire = (arg?: unknown) => { for (const l of this.listeners) l(arg); };
+  },
+  Uri: { file: (p: string) => ({ fsPath: p }) },
+}));
+
+import {
+  ReportsTreeProvider,
+  formatRelativeAge,
+} from "../src/ui/tree-providers/reports-tree-provider";
+import {
+  writeLatestSnapshot,
+  onLatestSnapshotWrite,
+  LatestSnapshotKind,
+} from "../src/infrastructure/latest-snapshot";
+import { LATEST_SNAPSHOT_FILES, MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../src/constants";
+import { MockLogger } from "./fixtures";
+
+describe("formatRelativeAge", () => {
+  it("buckets ages coarsely: just now / minutes / hours / days", () => {
+    expect(formatRelativeAge(0)).toBe("just now");
+    expect(formatRelativeAge(59_000)).toBe("just now");
+    expect(formatRelativeAge(60_000)).toBe("1m ago");
+    expect(formatRelativeAge(5 * 60_000)).toBe("5m ago");
+    expect(formatRelativeAge(59 * 60_000)).toBe("59m ago");
+    expect(formatRelativeAge(60 * 60_000)).toBe("1h ago");
+    expect(formatRelativeAge(23 * 3_600_000)).toBe("23h ago");
+    expect(formatRelativeAge(24 * 3_600_000)).toBe("1d ago");
+    expect(formatRelativeAge(3 * 24 * 3_600_000)).toBe("3d ago");
+  });
+});
+
+describe("ReportsTreeProvider freshness descriptions", () => {
+  let root: string;
+  let latestDir: string;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-reports-tree-"));
+    latestDir = path.join(root, MERIDIAN_DIR, MERIDIAN_LATEST_DIR);
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("renders three rows without descriptions when no workspace root is given", async () => {
+    const provider = new ReportsTreeProvider(undefined);
+    const items = await provider.getChildren();
+    expect(items).toHaveLength(3);
+    for (const item of items) expect(item.description).toBeUndefined();
+  });
+
+  it("renders without descriptions when no snapshots exist yet", async () => {
+    const provider = new ReportsTreeProvider(root);
+    const items = await provider.getChildren();
+    expect(items).toHaveLength(3);
+    for (const item of items) expect(item.description).toBeUndefined();
+  });
+
+  it("describes each row from its real snapshot mtime (hygiene → hygieneAnalytics)", async () => {
+    const logger = new MockLogger();
+    await writeLatestSnapshot(root, "sessionBriefing", {}, logger);
+    await writeLatestSnapshot(root, "hygieneAnalytics", {}, logger);
+    // Age the hygiene snapshot by 5 minutes; leave the briefing fresh.
+    const hygieneFile = path.join(latestDir, LATEST_SNAPSHOT_FILES.hygieneAnalytics);
+    const fiveMinAgo = new Date(Date.now() - 5 * 60_000);
+    fs.utimesSync(hygieneFile, fiveMinAgo, fiveMinAgo);
+
+    const provider = new ReportsTreeProvider(root);
+    const items = await provider.getChildren();
+    const byId = new Map(items.map((i) => [i.reportId, i]));
+
+    expect(byId.get("sessionBriefing")!.description).toBe("just now");
+    expect(byId.get("hygiene")!.description).toBe("5m ago");
+    // gitAnalytics snapshot was never written — description stays absent.
+    expect(byId.get("gitAnalytics")!.description).toBeUndefined();
+  });
+
+  it("refresh() fires onDidChangeTreeData", () => {
+    const provider = new ReportsTreeProvider(root);
+    const seen: unknown[] = [];
+    provider.onDidChangeTreeData((e: unknown) => seen.push(e));
+    provider.refresh();
+    expect(seen).toHaveLength(1);
+  });
+});
+
+describe("onLatestSnapshotWrite", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-latest-hook-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("notifies subscribers with the written kind after a successful write", async () => {
+    const kinds: LatestSnapshotKind[] = [];
+    const unsubscribe = onLatestSnapshotWrite((kind) => kinds.push(kind));
+    try {
+      await writeLatestSnapshot(root, "gitAnalytics", {}, new MockLogger());
+      expect(kinds).toEqual(["gitAnalytics"]);
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  it("does not notify on a failed write, and unsubscribe stops notifications", async () => {
+    const logger = new MockLogger();
+    const kinds: LatestSnapshotKind[] = [];
+    const unsubscribe = onLatestSnapshotWrite((kind) => kinds.push(kind));
+
+    // A file squatting as the "root" makes the write fail (ENOTDIR).
+    const blockerFile = path.join(root, "not-a-dir");
+    fs.writeFileSync(blockerFile, "x");
+    await writeLatestSnapshot(blockerFile, "gitAnalytics", {}, logger);
+    expect(kinds).toEqual([]);
+
+    unsubscribe();
+    await writeLatestSnapshot(root, "gitAnalytics", {}, logger);
+    expect(kinds).toEqual([]);
+  });
+
+  it("a throwing listener is swallowed and later listeners still run", async () => {
+    const kinds: LatestSnapshotKind[] = [];
+    const unsubBad = onLatestSnapshotWrite(() => {
+      throw new Error("bad listener");
+    });
+    const unsubGood = onLatestSnapshotWrite((kind) => kinds.push(kind));
+    try {
+      await expect(
+        writeLatestSnapshot(root, "sessionBriefing", {}, new MockLogger())
+      ).resolves.toBeUndefined();
+      expect(kinds).toEqual(["sessionBriefing"]);
+    } finally {
+      unsubBad();
+      unsubGood();
+    }
+  });
+});

From f64cf8bf09992c79cc6badfabbeefb937b1c18d6 Mon Sep 17 00:00:00 2001
From: Steven Salmons <stevencsalmons@gmail.com>
Date: Tue, 7 Jul 2026 14:44:30 -0400
Subject: [PATCH 4/4] refactor: post-review cleanups from simplify pass

Export latestDirPath/latestSnapshotPath so tree and reveal command share
the writer's path encoding; type Reports-tree map as ReportId->kind.
Centralize export-format facts in one EXPORT_FORMATS registry.
Restore manifest-test whitelist semantics via presentation-utility bucket.
Dedupe git-report test fixture into tests/fixtures; single-pass mdEscape.
---
 src/infrastructure/latest-snapshot.ts         | 10 +++-
 src/infrastructure/webview-provider.ts        | 55 +++++++++++++------
 src/presentation/tree-setup.ts                |  6 +-
 src/report-labels.ts                          |  7 +--
 .../tree-providers/reports-tree-provider.ts   | 17 +++---
 tests/fixtures.ts                             | 43 +++++++++++++++
 tests/manifest.test.ts                        | 20 ++++++-
 tests/reportMarkdown.test.ts                  | 26 ++-------
 tests/webviewProviderExport.test.ts           | 37 +------------
 9 files changed, 126 insertions(+), 95 deletions(-)

diff --git a/src/infrastructure/latest-snapshot.ts b/src/infrastructure/latest-snapshot.ts
index 2102a7b..fbc9d27 100644
--- a/src/infrastructure/latest-snapshot.ts
+++ b/src/infrastructure/latest-snapshot.ts
@@ -91,10 +91,16 @@ export function serializeReportJson(value: unknown): string {
   }, 2);
 }
 
-function latestDirPath(workspaceRoot: string): string {
+/** Canonical `.meridian/latest/` location — the one place the on-disk layout is encoded. */
+export function latestDirPath(workspaceRoot: string): string {
   return path.join(workspaceRoot, MERIDIAN_DIR, MERIDIAN_LATEST_DIR);
 }
 
+/** Canonical absolute path of one kind's snapshot file (writer and readers share it). */
+export function latestSnapshotPath(workspaceRoot: string, kind: LatestSnapshotKind): string {
+  return path.join(latestDirPath(workspaceRoot), LATEST_SNAPSHOT_FILES[kind]);
+}
+
 /**
  * Atomic create-if-missing (`wx` flag): a pre-existing file — including a
  * user-edited one — is never clobbered, without an exists/write TOCTOU gap.
@@ -148,7 +154,7 @@ export function writeLatestSnapshot(
 ): Promise<void> {
   const run = async (): Promise<void> => {
     const latestDir = latestDirPath(workspaceRoot);
-    const target = path.join(latestDir, LATEST_SNAPSHOT_FILES[kind]);
+    const target = latestSnapshotPath(workspaceRoot, kind);
     // pid-scoped tmp name: in-process interleaving is prevented by the queue;
     // this guards against a second extension host on the same workspace.
     const tmpTarget = `${target}.${process.pid}.tmp`;
diff --git a/src/infrastructure/webview-provider.ts b/src/infrastructure/webview-provider.ts
index 223f82b..7d66582 100644
--- a/src/infrastructure/webview-provider.ts
+++ b/src/infrastructure/webview-provider.ts
@@ -41,6 +41,29 @@ export interface IgnoreHooks {
   readonly invalidateCaches: () => void;
 }
 
+/**
+ * Single home for per-format export facts. Adding a format = one entry here
+ * plus a serializer branch in `serializeReport` (which switches exhaustively
+ * on ExportFormat); the QuickPick labels, label→format lookup, and save-dialog
+ * filters all derive from this table.
+ */
+interface ExportFormatSpec {
+  label: string;
+  filters: Record<string, string[]>;
+}
+
+const EXPORT_FORMATS: Record<"json" | "csv" | "md", ExportFormatSpec> = {
+  json: { label: "JSON", filters: { "JSON Files": ["json"] } },
+  csv: { label: "CSV", filters: { "CSV Files": ["csv"] } },
+  md: { label: "Markdown", filters: { "Markdown Files": ["md"] } },
+};
+
+type ExportFormat = keyof typeof EXPORT_FORMATS;
+
+function isExportFormat(format: string): format is ExportFormat {
+  return format in EXPORT_FORMATS;
+}
+
 // ============================================================================
 // Base Class
 // ============================================================================
@@ -215,12 +238,12 @@ export abstract class BaseWebviewProvider<TReport> {
 
   /** Serialize the current report in the requested format, or null if absent/invalid. */
   private serializeReport(format: string): string | null {
-    if (!this.lastReport || (format !== "json" && format !== "csv" && format !== "md")) {
-      return null;
+    if (!this.lastReport || !isExportFormat(format)) return null;
+    switch (format) {
+      case "json": return this.reportToJson(this.lastReport);
+      case "csv": return this.reportToCsv(this.lastReport);
+      case "md": return this.reportToMarkdown(this.lastReport);
     }
-    if (format === "json") return this.reportToJson(this.lastReport);
-    if (format === "md") return this.reportToMarkdown(this.lastReport);
-    return this.reportToCsv(this.lastReport);
   }
 
   /**
@@ -320,11 +343,14 @@ export abstract class BaseWebviewProvider<TReport> {
    * .meridian/artifacts/). The escape hatch for saving anywhere.
    */
   protected async handleSaveAs(): Promise<void> {
-    const picked = await vscode.window.showQuickPick(["JSON", "CSV", "Markdown"], {
-      placeHolder: "Export format",
-    });
+    const formats = Object.keys(EXPORT_FORMATS) as ExportFormat[];
+    const picked = await vscode.window.showQuickPick(
+      formats.map((f) => EXPORT_FORMATS[f].label),
+      { placeHolder: "Export format" }
+    );
     if (!picked) return;
-    const format = picked === "Markdown" ? "md" : picked.toLowerCase();
+    const format = formats.find((f) => EXPORT_FORMATS[f].label === picked);
+    if (!format) return;
 
     const content = this.serializeReport(format);
     if (content === null) return;
@@ -337,13 +363,10 @@ export abstract class BaseWebviewProvider<TReport> {
       ? vscode.Uri.file(path.join(artifactsDir, defaultName))
       : vscode.Uri.file(defaultName);
 
-    const filters: Record<string, string[]> = format === "json"
-      ? { "JSON Files": ["json"] }
-      : format === "md"
-        ? { "Markdown Files": ["md"] }
-        : { "CSV Files": ["csv"] };
-
-    const uri = await vscode.window.showSaveDialog({ defaultUri, filters });
+    const uri = await vscode.window.showSaveDialog({
+      defaultUri,
+      filters: EXPORT_FORMATS[format].filters,
+    });
     if (!uri) return;
 
     try {
diff --git a/src/presentation/tree-setup.ts b/src/presentation/tree-setup.ts
index bb98c58..d954b54 100644
--- a/src/presentation/tree-setup.ts
+++ b/src/presentation/tree-setup.ts
@@ -4,10 +4,8 @@
 
 import * as vscode from "vscode";
 import * as fs from "fs";
-import * as path from "path";
 import { Command, CommandContext, GitProvider, Logger, Result } from "../types";
-import { MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../constants";
-import { onLatestSnapshotWrite } from "../infrastructure/latest-snapshot";
+import { latestDirPath, onLatestSnapshotWrite } from "../infrastructure/latest-snapshot";
 import { GitTreeProvider } from "../ui/tree-providers/git-tree-provider";
 import { HygieneTreeProvider } from "../ui/tree-providers/hygiene-tree-provider";
 import {
@@ -87,7 +85,7 @@ export function setupTreeProviders(
     // otherwise explain how they come into being.
     vscode.commands.registerCommand("meridian.latest.reveal", () => {
       const root = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
-      const latestDir = root ? path.join(root, MERIDIAN_DIR, MERIDIAN_LATEST_DIR) : null;
+      const latestDir = root ? latestDirPath(root) : null;
       if (latestDir && fs.existsSync(latestDir)) {
         void vscode.commands.executeCommand("revealInExplorer", vscode.Uri.file(latestDir));
       } else {
diff --git a/src/report-labels.ts b/src/report-labels.ts
index 3dcd984..8a83bc0 100644
--- a/src/report-labels.ts
+++ b/src/report-labels.ts
@@ -21,9 +21,6 @@ export function reportMdHeader(label: string): string {
  * the row structure.
  */
 export function mdEscape(value: string): string {
-  return value
-    .replace(/\r?\n/g, " ")
-    .replace(/\\/g, "\\\\")
-    .replace(/\|/g, "\\|")
-    .replace(/`/g, "\\`");
+  // Single pass: it runs per table cell inside the export serializer loops.
+  return value.replace(/\r?\n|[\\|`]/g, (m) => (m === "\r\n" || m === "\n" ? " " : `\\${m}`));
 }
diff --git a/src/ui/tree-providers/reports-tree-provider.ts b/src/ui/tree-providers/reports-tree-provider.ts
index 962191e..1f4a877 100644
--- a/src/ui/tree-providers/reports-tree-provider.ts
+++ b/src/ui/tree-providers/reports-tree-provider.ts
@@ -13,9 +13,8 @@
 
 import * as vscode from "vscode";
 import { promises as fsp } from "node:fs";
-import * as path from "node:path";
 import { REPORT_LABELS } from "../../report-labels";
-import { LATEST_SNAPSHOT_FILES, MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../../constants";
+import { latestSnapshotPath, LatestSnapshotKind } from "../../infrastructure/latest-snapshot";
 
 export type ReportId = "sessionBriefing" | "gitAnalytics" | "hygiene";
 
@@ -35,11 +34,11 @@ const REPORTS: ReadonlyArray<{ id: ReportId; label: string }> = [
   { id: "hygiene", label: REPORT_LABELS.hygieneAnalytics },
 ];
 
-/** ReportId → latest-snapshot filename. The tree's `hygiene` row reads the `hygieneAnalytics` snapshot. */
-const REPORT_SNAPSHOT_FILE: Record<ReportId, string> = {
-  sessionBriefing: LATEST_SNAPSHOT_FILES.sessionBriefing,
-  gitAnalytics: LATEST_SNAPSHOT_FILES.gitAnalytics,
-  hygiene: LATEST_SNAPSHOT_FILES.hygieneAnalytics,
+/** ReportId → snapshot kind. Only the tree's `hygiene` row is renamed (`hygieneAnalytics`). */
+const REPORT_SNAPSHOT_KIND: Record<ReportId, LatestSnapshotKind> = {
+  sessionBriefing: "sessionBriefing",
+  gitAnalytics: "gitAnalytics",
+  hygiene: "hygieneAnalytics",
 };
 
 /**
@@ -91,11 +90,11 @@ export class ReportsTreeProvider implements vscode.TreeDataProvider<ReportTreeIt
     const items = REPORTS.map((r) => new ReportTreeItem(r.id, r.label));
     if (!this.workspaceRoot) return items;
 
-    const latestDir = path.join(this.workspaceRoot, MERIDIAN_DIR, MERIDIAN_LATEST_DIR);
+    const root = this.workspaceRoot;
     await Promise.all(
       items.map(async (item) => {
         try {
-          const stat = await fsp.stat(path.join(latestDir, REPORT_SNAPSHOT_FILE[item.reportId]));
+          const stat = await fsp.stat(latestSnapshotPath(root, REPORT_SNAPSHOT_KIND[item.reportId]));
           item.description = formatRelativeAge(Date.now() - stat.mtimeMs);
         } catch {
           // No snapshot yet for this report — leave the description absent.
diff --git a/tests/fixtures.ts b/tests/fixtures.ts
index 725a494..f2bde64 100644
--- a/tests/fixtures.ts
+++ b/tests/fixtures.ts
@@ -20,6 +20,7 @@ import {
   AppError,
 } from '../src/types';
 import type { RunLog } from '../src/infrastructure/run-log';
+import type { GitAnalyticsReport } from '../src/domains/git/analytics-types';
 
 // ============================================================================
 // Mock Logger
@@ -249,6 +250,48 @@ export class MockWorkspaceProvider implements WorkspaceProvider {
   }
 }
 
+// ============================================================================
+// Git Analytics Report Fixture
+// ============================================================================
+
+/**
+ * Minimal fully-typed GitAnalyticsReport. Tests override the fields they
+ * exercise (e.g. escape-bait paths for the markdown serializer).
+ */
+export function makeGitAnalyticsReport(
+  overrides?: Partial<GitAnalyticsReport>
+): GitAnalyticsReport {
+  const when = new Date('2026-07-07T12:00:00.000Z');
+  return {
+    period: '3mo',
+    generatedAt: when,
+    summary: {
+      totalCommits: 1,
+      totalAuthors: 1,
+      totalFilesModified: 1,
+      totalLinesAdded: 2,
+      totalLinesDeleted: 1,
+      commitFrequency: 0.25,
+      averageCommitSize: 3,
+      churnRate: 1,
+    },
+    commits: [],
+    files: [],
+    authors: [
+      { name: 'Ada', commits: 1, insertions: 2, deletions: 1, filesChanged: 1, lastActive: when },
+    ],
+    trends: {
+      commitTrend: { slope: 0, direction: 'stable', confidence: 0.5 },
+      volatilityTrend: { slope: 0, direction: 'stable' },
+    },
+    commitFrequency: { labels: ['Week 1'], data: [1] },
+    churnFiles: [],
+    topAuthors: [],
+    coChange: [],
+    ...overrides,
+  };
+}
+
 // ============================================================================
 // Test Data — Sample Changes, Commits, etc.
 // ============================================================================
diff --git a/tests/manifest.test.ts b/tests/manifest.test.ts
index a7ac942..7128808 100644
--- a/tests/manifest.test.ts
+++ b/tests/manifest.test.ts
@@ -8,6 +8,7 @@
  * Whitelisted command classes (not in COMMAND_MAP, but valid in the manifest):
  *   SPECIALIZED_COMMANDS — dedicated registrations per ADR 005 (custom UI/param sourcing)
  *   INFRASTRUCTURE_COMMANDS — view lifecycle commands (refresh, statusBar); no routing
+ *   PRESENTATION_UTILITY_COMMANDS — palette-visible utilities registered in tree-setup.ts
  */
 
 import { describe, it, expect, vi } from "vitest";
@@ -22,13 +23,21 @@ import { SETTING_DEFAULTS } from "../src/infrastructure/settings";
 
 // ── Whitelists ────────────────────────────────────────────────────────────────
 
-/** Dedicated registrations outside COMMAND_MAP (ADR 005): custom UI/param sourcing. */
+/** Registered in specialized-commands.ts (ADR 005). Not in COMMAND_MAP. */
 const SPECIALIZED_COMMANDS = new Set([
   "meridian.hygiene.deleteFile",
   "meridian.hygiene.ignoreFile",
   "meridian.hygiene.impactAnalysis", // ADR 005: active-file fallback + InputBox prompt
   "meridian.hygiene.pruneStorage",   // ADR 019: status preview + confirmation modal
-  "meridian.latest.reveal",          // tree-setup.ts: reveal-or-explain .meridian/latest/ (ADR 020)
+]);
+
+/**
+ * Palette-visible utility commands registered in tree-setup.ts. Distinct from
+ * INFRASTRUCTURE_COMMANDS (which are enforced out of the palette) and from
+ * SPECIALIZED_COMMANDS (whose home is specialized-commands.ts).
+ */
+const PRESENTATION_UTILITY_COMMANDS = new Set([
+  "meridian.latest.reveal", // reveal-or-explain .meridian/latest/ (ADR 020)
 ]);
 
 /** View lifecycle commands. No routing, no palette exposure. */
@@ -102,7 +111,12 @@ describe("Manifest — VS Code commands surface", () => {
   it("every contributes.commands entry is accounted for (COMMAND_MAP or whitelist)", () => {
     const orphans: string[] = [];
     for (const { command } of manifestCommands) {
-      if (!commandMapIds.has(command) && !SPECIALIZED_COMMANDS.has(command) && !INFRASTRUCTURE_COMMANDS.has(command)) {
+      if (
+        !commandMapIds.has(command) &&
+        !SPECIALIZED_COMMANDS.has(command) &&
+        !INFRASTRUCTURE_COMMANDS.has(command) &&
+        !PRESENTATION_UTILITY_COMMANDS.has(command)
+      ) {
         orphans.push(command);
       }
     }
diff --git a/tests/reportMarkdown.test.ts b/tests/reportMarkdown.test.ts
index 8cb69c4..4f40fac 100644
--- a/tests/reportMarkdown.test.ts
+++ b/tests/reportMarkdown.test.ts
@@ -22,24 +22,13 @@ import {
 import type { GitAnalyticsReport } from "../src/domains/git/analytics-types";
 import type { HygieneAnalyticsReport } from "../src/domains/hygiene/analytics-types";
 import type { SessionBriefingReport } from "../src/domains/git/types";
+import { makeGitAnalyticsReport } from "./fixtures";
 
 const WHEN = new Date("2026-07-07T12:00:00.000Z");
 
+/** Shared fixture, seeded with pipe/backtick escape-bait values. */
 function makeGitReport(): GitAnalyticsReport {
-  return {
-    period: "3mo",
-    generatedAt: WHEN,
-    summary: {
-      totalCommits: 2,
-      totalAuthors: 1,
-      totalFilesModified: 2,
-      totalLinesAdded: 10,
-      totalLinesDeleted: 4,
-      commitFrequency: 0.5,
-      averageCommitSize: 7,
-      churnRate: 1.25,
-    },
-    commits: [],
+  return makeGitAnalyticsReport({
     files: [
       {
         path: "src/pipe|and`tick.ts",
@@ -62,15 +51,8 @@ function makeGitReport(): GitAnalyticsReport {
         lastActive: WHEN,
       },
     ],
-    trends: {
-      commitTrend: { slope: 0, direction: "stable", confidence: 0.5 },
-      volatilityTrend: { slope: 0, direction: "stable" },
-    },
-    commitFrequency: { labels: ["Week 1"], data: [2] },
-    churnFiles: [],
-    topAuthors: [],
     coChange: [{ a: "a.ts", b: "b|c.ts", count: 3, coChangeRate: 0.75 }],
-  };
+  });
 }
 
 function makeBriefingReport(): SessionBriefingReport {
diff --git a/tests/webviewProviderExport.test.ts b/tests/webviewProviderExport.test.ts
index e073737..3eda799 100644
--- a/tests/webviewProviderExport.test.ts
+++ b/tests/webviewProviderExport.test.ts
@@ -51,7 +51,7 @@ import * as vscode from "vscode";
 import { AnalyticsWebviewProvider } from "../src/infrastructure/webview-provider";
 import { flushLatestSnapshotWrites } from "../src/infrastructure/latest-snapshot";
 import { gitReportToMd } from "../src/domains/git/analytics-service";
-import type { GitAnalyticsReport } from "../src/domains/git/analytics-types";
+import { makeGitAnalyticsReport } from "./fixtures";
 import { LATEST_SNAPSHOT_FILES, MERIDIAN_DIR, MERIDIAN_LATEST_DIR } from "../src/constants";
 
 function makeProvider(root: string): AnalyticsWebviewProvider {
@@ -65,37 +65,6 @@ function makeProvider(root: string): AnalyticsWebviewProvider {
   return provider;
 }
 
-/** Minimal fully-typed report so the markdown paths serialize real values. */
-function makeGitReport(): GitAnalyticsReport {
-  const when = new Date("2026-07-07T12:00:00.000Z");
-  return {
-    period: "3mo",
-    generatedAt: when,
-    summary: {
-      totalCommits: 1,
-      totalAuthors: 1,
-      totalFilesModified: 1,
-      totalLinesAdded: 2,
-      totalLinesDeleted: 1,
-      commitFrequency: 0.25,
-      averageCommitSize: 3,
-      churnRate: 1,
-    },
-    commits: [],
-    files: [],
-    authors: [
-      { name: "Ada", commits: 1, insertions: 2, deletions: 1, filesChanged: 1, lastActive: when },
-    ],
-    trends: {
-      commitTrend: { slope: 0, direction: "stable", confidence: 0.5 },
-      volatilityTrend: { slope: 0, direction: "stable" },
-    },
-    commitFrequency: { labels: ["Week 1"], data: [1] },
-    churnFiles: [],
-    topAuthors: [],
-    coChange: [],
-  };
-}
 
 describe("WebviewProvider report export", () => {
   beforeEach(() => {
@@ -163,7 +132,7 @@ describe("WebviewProvider report export", () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-export-md-"));
     workspaceState.root = root;
     const provider = makeProvider(root);
-    const report = makeGitReport();
+    const report = makeGitAnalyticsReport();
     (provider as any).lastReport = report;
 
     await (provider as any).handleQuickSave("md");
@@ -191,7 +160,7 @@ describe("WebviewProvider report export", () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), "meridian-copy-md-"));
     workspaceState.root = root;
     const provider = makeProvider(root);
-    const report = makeGitReport();
+    const report = makeGitAnalyticsReport();
     (provider as any).lastReport = report;
 
     // autoCopy defaults to false → copyWithPolicy prompts; accepting copies.