@grifhinz/logics-manager 2.3.3 → 2.5.0

package/clients/viewer/browser-host.js

@@ -1,6 +1,5 @@
 (() => {
   const stateKey = "logics.localViewer.state";
-  const autoRefreshIntervalMs = 60 * 1000;
   const meta = () => document.getElementById("viewer-meta");
   const documentPanel = () => document.getElementById("viewer-document");
   const documentTitle = () => document.getElementById("viewer-document-title");
@@ -10,6 +9,16 @@
   const updateCopy = () => document.getElementById("viewer-update-copy");
   const updateCommand = () => document.getElementById("viewer-update-command");
   const filterCount = () => document.getElementById("viewer-filter-count");
+  const repoPill = () => document.getElementById("viewer-repo-pill");
+  const autoRefreshControl = () => document.getElementById("viewer-auto-refresh");
+  const refreshIntervalControl = () => document.getElementById("viewer-refresh-interval");
+  const refreshMenuButton = () => document.getElementById("viewer-refresh-menu-button");
+  const refreshMenuPanel = () => document.getElementById("viewer-refresh-menu");
+  const activityClearControl = () => document.getElementById("activity-clear");
+  const activityStorageLimit = 80;
+  const minAutoRefreshIntervalSeconds = 5;
+  const maxAutoRefreshIntervalSeconds = 60;
+  const defaultAutoRefreshIntervalMs = 15 * 1000;
   const defaultFilterState = {
     focus: "active",
     type: "all",
@@ -19,12 +28,20 @@
   };
   let viewerFilterState = { ...defaultFilterState };
   let latestItems = [];
+  let latestRepoRoot = "";
+  let latestMetaText = "Read-only local viewer";
+  let autoRefreshIntervalMs = defaultAutoRefreshIntervalMs;
+  let nextAutoRefreshAt = 0;
+  let autoRefreshEnabled = true;
+  let autoRefreshTimeoutId = 0;
+  let autoRefreshIntervalTouched = false;
   let applyingLocalChrome = false;
   let autoRefreshStarted = false;
   let itemsLoadInFlight = false;
   let refreshAfterVisible = false;
   let mermaidInitialized = false;
   let focusApplied = false;
+  let latestGitBadgeCounts = { unpushedCommits: 0, uncommittedFiles: 0 };
 
   function readStoredState() {
     try {
@@ -62,6 +79,52 @@
     writeStoredState({ ...nextState, viewerFilterState: { ...viewerFilterState } });
   }
 
+  function updateStoredActivity(nextItems) {
+    const storedState = readStoredState();
+    const baseState = storedState && typeof storedState === "object" ? storedState : {};
+    const previousSnapshot = baseState.activitySnapshot && typeof baseState.activitySnapshot === "object"
+      ? baseState.activitySnapshot
+      : {};
+    const history = Array.isArray(baseState.activityHistory) ? [...baseState.activityHistory] : [];
+    const nextSnapshot = {};
+    const now = new Date().toISOString();
+    const decorated = nextItems.map((item) => {
+      const relPath = String(item.relPath || item.path || item.id || "");
+      const status = String(item?.indicators?.Status || "").trim();
+      if (relPath) {
+        nextSnapshot[relPath] = { status, updatedAt: item.updatedAt || "" };
+      }
+      const previous = relPath ? previousSnapshot[relPath] : null;
+      const previousStatus = String(previous?.status || "").trim();
+      const statusChanged = Boolean(previousStatus && status && previousStatus !== status);
+      if (relPath && (statusChanged || !previous)) {
+        history.unshift({ path: relPath, at: now, status, previousStatus, type: statusChanged ? "status-change" : "updated" });
+      }
+      return statusChanged ? { ...item, activityType: "status-change" } : item;
+    });
+    writeStoredState({
+      ...baseState,
+      viewerFilterState: { ...viewerFilterState },
+      activitySnapshot: nextSnapshot,
+      activityHistory: history.slice(0, activityStorageLimit)
+    });
+    return decorated;
+  }
+
+  function clearActivityHistory() {
+    const storedState = readStoredState();
+    const nextState = storedState && typeof storedState === "object" ? { ...storedState } : {};
+    delete nextState.activitySnapshot;
+    delete nextState.activityHistory;
+    writeStoredState(nextState);
+    latestItems = latestItems.map((item) => {
+      const clone = { ...item };
+      delete clone.activityType;
+      return clone;
+    });
+    setMeta("Local activity history cleared.");
+  }
+
   function markdownApi() {
     if (typeof window.createCdxLogicsMarkdownApi === "function") {
       return window.createCdxLogicsMarkdownApi();
@@ -90,9 +153,139 @@
   }
 
   function setMeta(text) {
+    latestMetaText = text;
+    renderMeta();
+  }
+
+  function renderMeta() {
     const node = meta();
     if (node) {
-      node.textContent = text;
+      const parts = [latestMetaText];
+      if (autoRefreshEnabled && nextAutoRefreshAt > 0) {
+        const seconds = Math.max(0, Math.ceil((nextAutoRefreshAt - Date.now()) / 1000));
+        parts.push(`next auto refresh in ${seconds}s`);
+      }
+      node.textContent = parts.join(" · ");
+    }
+  }
+
+  function normalizeAutoRefreshIntervalSeconds(value) {
+    const seconds = Math.round(Number(value));
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+      return defaultAutoRefreshIntervalMs / 1000;
+    }
+    return Math.min(maxAutoRefreshIntervalSeconds, Math.max(minAutoRefreshIntervalSeconds, seconds));
+  }
+
+  function updateRefreshIntervalControl() {
+    const control = refreshIntervalControl();
+    if (!(control instanceof HTMLSelectElement)) {
+      return;
+    }
+    const seconds = String(Math.round(autoRefreshIntervalMs / 1000));
+    if (![...control.options].some((option) => option.value === seconds)) {
+      const option = document.createElement("option");
+      option.value = seconds;
+      option.textContent = `${seconds} sec`;
+      control.appendChild(option);
+    }
+    control.value = seconds;
+  }
+
+  function setAutoRefreshIntervalSeconds(value, options = {}) {
+    autoRefreshIntervalMs = normalizeAutoRefreshIntervalSeconds(value) * 1000;
+    if (options.user) {
+      autoRefreshIntervalTouched = true;
+    }
+    updateRefreshIntervalControl();
+    scheduleNextAutoRefresh();
+  }
+
+  function scheduleNextAutoRefresh() {
+    if (autoRefreshTimeoutId) {
+      window.clearTimeout(autoRefreshTimeoutId);
+      autoRefreshTimeoutId = 0;
+    }
+    nextAutoRefreshAt = autoRefreshEnabled ? Date.now() + autoRefreshIntervalMs : 0;
+    if (autoRefreshEnabled) {
+      autoRefreshTimeoutId = window.setTimeout(autoRefreshItems, autoRefreshIntervalMs);
+    }
+    renderMeta();
+  }
+
+  function updateRepositoryIdentity(payload) {
+    latestRepoRoot = String(payload.root || latestRepoRoot || "");
+    const pill = repoPill();
+    if (!pill) {
+      return;
+    }
+    const repoName = String(payload.repoName || latestRepoRoot.split(/[\\/]/).filter(Boolean).pop() || "repository");
+    pill.textContent = repoName;
+    pill.title = latestRepoRoot || repoName;
+  }
+
+  function normalizeGitBadgeCounts(payload) {
+    const counts = payload && typeof payload === "object" ? payload.badgeCounts || {} : {};
+    return {
+      unpushedCommits: Math.max(0, Number(counts.unpushedCommits || payload?.ahead || 0)),
+      uncommittedFiles: Math.max(0, Number(counts.uncommittedFiles || 0))
+    };
+  }
+
+  function renderGitBadge(kind, count) {
+    const value = Number(count || 0);
+    if (value <= 0) {
+      return "";
+    }
+    const label = kind === "commits"
+      ? `${value} commits locaux non pushés`
+      : `${value} fichiers modifiés non commités`;
+    return `<span class="viewer-git-badge viewer-git-badge--${kind}" title="${escapeHtml(label)}" aria-label="${escapeHtml(label)}">${escapeHtml(value)}</span>`;
+  }
+
+  function gitBadgeHtml(scope) {
+    const commitsVisible = latestGitBadgeCounts.unpushedCommits > 0 && (
+      scope === "main" || scope === "history"
+    );
+    const filesVisible = latestGitBadgeCounts.uncommittedFiles > 0 && (
+      scope === "main" || scope === "changes"
+    );
+    const html = [
+      commitsVisible ? renderGitBadge("commits", latestGitBadgeCounts.unpushedCommits) : "",
+      filesVisible ? renderGitBadge("files", latestGitBadgeCounts.uncommittedFiles) : ""
+    ].filter(Boolean).join("");
+    return html ? `<span class="viewer-git-badges" data-viewer-git-badges="${escapeHtml(scope)}">${html}</span>` : "";
+  }
+
+  function updateMainGitBadges() {
+    const button = document.getElementById("viewer-git");
+    if (!(button instanceof HTMLElement)) {
+      return;
+    }
+    button.querySelector('[data-viewer-git-badges="main"]')?.remove();
+    const html = gitBadgeHtml("main");
+    if (html) {
+      button.insertAdjacentHTML("beforeend", html);
+    }
+  }
+
+  function setGitBadgeCountsFromPayload(payload, options = {}) {
+    latestGitBadgeCounts = normalizeGitBadgeCounts(payload);
+    if (options.updateMain !== false) {
+      updateMainGitBadges();
+    }
+  }
+
+  async function refreshGitBadgeCounters() {
+    try {
+      const response = await fetch("/api/git-status");
+      const data = await response.json();
+      if (response.ok && data.ok && data.payload?.state === "ok") {
+        setGitBadgeCountsFromPayload(data.payload);
+      }
+    } catch {
+      latestGitBadgeCounts = { unpushedCommits: 0, uncommittedFiles: 0 };
+      updateMainGitBadges();
     }
   }
 
@@ -333,16 +526,24 @@
   }
 
   function postToApp(payload, options = {}) {
-    latestItems = Array.isArray(payload.items) ? payload.items : [];
-    const nextPayload = options.silent ? payload : applyFocusRequest(payload);
+    latestItems = updateStoredActivity(Array.isArray(payload.items) ? payload.items : []);
+    if (!autoRefreshIntervalTouched) {
+      autoRefreshIntervalMs = normalizeAutoRefreshIntervalSeconds(payload.autoRefreshIntervalSeconds) * 1000;
+      updateRefreshIntervalControl();
+    }
+    updateRepositoryIdentity(payload);
+    const payloadWithActivity = { ...payload, items: latestItems };
+    const nextPayload = options.silent ? payloadWithActivity : applyFocusRequest(payloadWithActivity);
     window.dispatchEvent(new MessageEvent("message", { data: { type: "data", payload: nextPayload } }));
     const rootName = payload.root ? payload.root.split(/[\\/]/).filter(Boolean).pop() : "repository";
     if (!options.silent) {
       setMeta(`${rootName} · ${payload.items.length} docs · refreshed ${new Date().toLocaleTimeString()}`);
     }
+    scheduleNextAutoRefresh();
     renderUpdateNotice(payload.updateInfo);
     updateFilterSummary();
     applyLocalViewerChrome();
+    bindRefreshMenuControls();
   }
 
   function renderUpdateNotice(updateInfo) {
@@ -380,18 +581,47 @@
         throw new Error(data.error || "Unable to load viewer data.");
       }
       postToApp(data.payload, { silent: Boolean(options.silent) });
+      if (method !== "POST") {
+        await refreshGitBadgeCounters();
+      }
       return true;
     } finally {
       itemsLoadInFlight = false;
     }
   }
 
+  function isGitStatusOpen() {
+    const panel = documentPanel();
+    const title = documentTitle();
+    return Boolean(panel && !panel.hidden && title && title.textContent === "Git status");
+  }
+
+  function isCdxStatusOpen() {
+    const panel = documentPanel();
+    const title = documentTitle();
+    return Boolean(panel && !panel.hidden && title && title.textContent === "CDX status");
+  }
+
+  async function refreshViewer(method = "POST", options = {}) {
+    await loadItems(method, options);
+    if (isGitStatusOpen()) {
+      await showGitStatus({ preserve: true, silent: Boolean(options.silent) });
+    } else if (isCdxStatusOpen()) {
+      await showCdxStatus({ silent: Boolean(options.silent) });
+    } else if (method === "POST") {
+      await refreshGitBadgeCounters();
+    }
+  }
+
   function autoRefreshItems() {
+    if (!autoRefreshEnabled) {
+      return;
+    }
     if (document.hidden) {
       refreshAfterVisible = true;
       return;
     }
-    loadItems("POST", { silent: true }).catch((error) => setMeta(error.message));
+    refreshViewer("POST", { silent: true }).catch((error) => setMeta(error.message));
   }
 
   function startAutoRefresh() {
@@ -399,7 +629,9 @@
       return;
     }
     autoRefreshStarted = true;
-    window.setInterval(autoRefreshItems, autoRefreshIntervalMs);
+    window.setInterval(() => {
+      renderMeta();
+    }, 1000);
     document.addEventListener("visibilitychange", () => {
       if (!document.hidden && refreshAfterVisible) {
         refreshAfterVisible = false;
@@ -408,13 +640,57 @@
     });
   }
 
+  function setAutoRefreshEnabled(enabled) {
+    autoRefreshEnabled = Boolean(enabled);
+    const control = autoRefreshControl();
+    if (control instanceof HTMLInputElement) {
+      control.checked = autoRefreshEnabled;
+    }
+    scheduleNextAutoRefresh();
+  }
+
+  function setRefreshMenuOpen(open) {
+    const panel = refreshMenuPanel();
+    const button = refreshMenuButton();
+    if (!panel) {
+      return;
+    }
+    panel.hidden = !open;
+    if (button instanceof HTMLElement) {
+      button.setAttribute("aria-expanded", open ? "true" : "false");
+    }
+  }
+
+  function bindRefreshMenuControls() {
+    const button = refreshMenuButton();
+    if (button) {
+      button.onclick = (event) => {
+        event.stopPropagation();
+        const panel = refreshMenuPanel();
+        setRefreshMenuOpen(Boolean(panel?.hidden));
+      };
+    }
+    const panel = refreshMenuPanel();
+    if (panel) {
+      panel.onclick = (event) => {
+        event.stopPropagation();
+      };
+    }
+  }
+
   function statusValue(item) {
     return String(item?.indicators?.Status || "").toLowerCase();
   }
 
   function isClosed(item) {
     const status = statusValue(item);
-    return status.includes("done") || status.includes("archived") || status.includes("obsolete");
+    return (
+      status.includes("done") ||
+      status.includes("archived") ||
+      status.includes("obsolete") ||
+      status.includes("superseded") ||
+      status.includes("settled")
+    );
   }
 
   function hasLinks(item) {
@@ -435,6 +711,52 @@
     return timestamp > 0 && timestamp < Date.now() - 30 * 24 * 60 * 60 * 1000 && !isClosed(item);
   }
 
+  function isRecent(item, days = 7) {
+    return updatedWithin(item, days);
+  }
+
+  function hasMissingOrAmbiguousStatus(item) {
+    const rawStatus = String(item?.indicators?.Status || "").trim();
+    if (!rawStatus) {
+      return true;
+    }
+    const normalized = rawStatus.toLowerCase();
+    return ![
+      "draft",
+      "ready",
+      "in progress",
+      "blocked",
+      "done",
+      "active",
+      "proposed",
+      "accepted",
+      "validated",
+      "rejected",
+      "superseded",
+      "settled",
+      "archived",
+      "obsolete"
+    ].includes(normalized);
+  }
+
+  function isSafeLogicsDocPath(value) {
+    const path = String(value || "").replace(/\\/g, "/").replace(/^\.?\//, "").trim();
+    if (!path || path.startsWith("/") || path.startsWith("~") || /^[A-Za-z]:/.test(path)) {
+      return false;
+    }
+    if (path.split("/").includes("..") || !path.endsWith(".md")) {
+      return false;
+    }
+    return [
+      "logics/request/",
+      "logics/backlog/",
+      "logics/tasks/",
+      "logics/product/",
+      "logics/architecture/",
+      "logics/specs/"
+    ].some((prefix) => path.startsWith(prefix));
+  }
+
   function matchesViewerFilter(item) {
     if (!item) {
       return false;
@@ -562,58 +884,233 @@
     count.textContent = `${visibleCount} of ${latestItems.length} docs shown${suffix}`;
   }
 
-  function buildCorpusInsights() {
-    const countsByStage = latestItems.reduce((acc, item) => {
-      acc[item.stage] = (acc[item.stage] || 0) + 1;
+  function countBy(items, selector) {
+    return items.reduce((acc, item) => {
+      const key = selector(item) || "unknown";
+      acc[key] = (acc[key] || 0) + 1;
       return acc;
     }, {});
-    const active = latestItems.filter((item) => !isClosed(item)).length;
-    const blocked = latestItems.filter((item) => statusValue(item).includes("blocked")).length;
-    const unlinked = latestItems.filter((item) => (item.references || []).length === 0 && (item.usedBy || []).length === 0).length;
-    const incompleteChains = latestItems.filter((item) => ["request", "backlog"].includes(item.stage) && !item.isPromoted && !isClosed(item)).length;
-    const cards = [
-      ["Docs", latestItems.length],
-      ["Active", active],
-      ["Blocked", blocked],
-      ["Unlinked", unlinked]
-    ].map(([label, value]) => `
+  }
+
+  function renderMetricCards(entries) {
+    return entries.map(([label, value]) => `
       <div class="viewer-insights__card">
         <div class="viewer-insights__label">${escapeHtml(label)}</div>
         <div class="viewer-insights__value">${escapeHtml(value)}</div>
       </div>
     `).join("");
+  }
+
+  function renderInsightRows(items, emptyText = "No signals") {
+    if (!items.length) {
+      return `<li class="viewer-insights__item">${escapeHtml(emptyText)}</li>`;
+    }
+    return items.map(([label, value]) => `
+      <li class="viewer-insights__item"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong></li>
+    `).join("");
+  }
+
+  function renderDocRows(items, emptyText = "None", limit = 6) {
+    if (!items.length) {
+      return `<li class="viewer-insights__row viewer-insights__row--empty">${escapeHtml(emptyText)}</li>`;
+    }
+    const rows = items.map((item, index) => {
+      const path = item.relPath || item.path || "";
+      const control = path && isSafeLogicsDocPath(path)
+        ? `<button class="viewer-insights__doc" type="button" data-viewer-doc-path="${escapeHtml(path)}">${escapeHtml(item.id || path)}</button>`
+        : `<span class="viewer-insights__doc">${escapeHtml(item.id || path || item.title)}</span>`;
+      return `
+        <li class="viewer-insights__row" ${index >= limit ? "hidden data-viewer-hidden-row" : ""}>
+          ${control}
+          <span>${escapeHtml(item.indicators?.Status || item.stage || "No status")}</span>
+        </li>
+      `;
+    });
+    const hiddenCount = Math.max(0, items.length - limit);
+    if (hiddenCount > 0) {
+      rows.push(`<li class="viewer-insights__row"><button class="viewer-insights__reveal" type="button" data-viewer-reveal>Show ${hiddenCount} more</button></li>`);
+    }
+    return rows.join("");
+  }
+
+  function renderPathRows(paths, emptyText = "None", limit = 6) {
+    if (!paths.length) {
+      return `<li class="viewer-insights__row viewer-insights__row--empty">${escapeHtml(emptyText)}</li>`;
+    }
+    const rows = paths.map((path, index) => {
+      const control = isSafeLogicsDocPath(path)
+        ? `<button class="viewer-insights__doc" type="button" data-viewer-doc-path="${escapeHtml(path)}">${escapeHtml(path)}</button>`
+        : `<span class="viewer-insights__doc">${escapeHtml(path)}</span>`;
+      return `<li class="viewer-insights__row" ${index >= limit ? "hidden data-viewer-hidden-row" : ""}>${control}</li>`;
+    });
+    const hiddenCount = Math.max(0, paths.length - limit);
+    if (hiddenCount > 0) {
+      rows.push(`<li class="viewer-insights__row"><button class="viewer-insights__reveal" type="button" data-viewer-reveal>Show ${hiddenCount} more</button></li>`);
+    }
+    return rows.join("");
+  }
+
+  function renderActionRows(actions) {
+    return actions.map((action) => {
+      if (action.filter) {
+        return `
+          <li class="viewer-insights__row">
+            <button class="viewer-insights__action" type="button" data-viewer-filter-group="${escapeHtml(action.filter.group)}" data-viewer-filter-value="${escapeHtml(action.filter.value)}">${escapeHtml(action.label)}</button>
+            <strong>${escapeHtml(action.value)}</strong>
+          </li>
+        `;
+      }
+      if (action.health) {
+        return `
+          <li class="viewer-insights__row">
+            <button class="viewer-insights__action" type="button" data-viewer-open-health>${escapeHtml(action.label)}</button>
+            <strong>${escapeHtml(action.value)}</strong>
+          </li>
+        `;
+      }
+      if (action.path && isSafeLogicsDocPath(action.path)) {
+        return `
+          <li class="viewer-insights__row">
+            <button class="viewer-insights__action" type="button" data-viewer-doc-path="${escapeHtml(action.path)}">${escapeHtml(action.label)}</button>
+            <strong>${escapeHtml(action.value)}</strong>
+          </li>
+        `;
+      }
+      return `<li class="viewer-insights__row"><span>${escapeHtml(action.label)}</span><strong>${escapeHtml(action.value)}</strong></li>`;
+    }).join("");
+  }
+
+  function itemLabel(item) {
+    return `${item.id || item.relPath || "doc"} - ${item.indicators?.Status || "No status"}`;
+  }
+
+  function buildCorpusInsights(lintData = null, auditData = null) {
+    const docs = latestItems;
+    const itemPaths = new Set(docs.map((item) => item.relPath).filter(Boolean));
+    const countsByStage = countBy(docs, (item) => item.stage);
+    const closed = docs.filter(isClosed);
+    const open = docs.filter((item) => !isClosed(item));
+    const blocked = docs.filter((item) => statusValue(item).includes("blocked"));
+    const missingStatus = docs.filter(hasMissingOrAmbiguousStatus);
+    const recentlyModified = docs.filter((item) => isRecent(item, 7));
+    const incompleteChains = docs.filter((item) => ["request", "backlog"].includes(item.stage) && !item.isPromoted && !isClosed(item));
+    const unlinked = docs.filter((item) => (item.references || []).length === 0 && (item.usedBy || []).length === 0);
+    const brokenRefs = [];
+    const relationshipCounts = {};
+    docs.forEach((item) => {
+      relationshipCounts[item.stage] = (relationshipCounts[item.stage] || 0) + (item.references || []).length + (item.usedBy || []).length;
+      (item.references || []).forEach((ref) => {
+        if (ref.path && !itemPaths.has(ref.path)) {
+          brokenRefs.push(`${item.id} -> ${ref.path}`);
+        }
+      });
+    });
+    const mostReferenced = [...docs]
+      .sort((left, right) => (right.usedBy || []).length - (left.usedBy || []).length)
+      .filter((item) => (item.usedBy || []).length > 0)
+      .slice(0, 8);
+    const recentRows = [...docs]
+      .sort((left, right) => (Date.parse(right.updatedAt || "") || 0) - (Date.parse(left.updatedAt || "") || 0))
+      .slice(0, 8);
+    const staleActive = open.filter(isStale).slice(0, 8);
+    const qualityFindings = lintData && auditData ? collectHealthFindings(lintData, auditData) : [];
+    const qualityBySource = countBy(qualityFindings, (finding) => finding.source || finding.code || "finding");
+    const qualityByDocType = countBy(qualityFindings, (finding) => {
+      const path = String(finding.path || "");
+      const matched = docs.find((item) => item.relPath === path);
+      return matched?.stage || (path ? "unknown document" : "repository");
+    });
+    const concentratedIssues = Object.entries(countBy(qualityFindings, (finding) => finding.path || "repository"))
+      .sort((left, right) => Number(right[1]) - Number(left[1]))
+      .slice(0, 8);
+    const actions = [];
+    if (blocked.length) {
+      actions.push({ label: "Review blocked workflow docs", value: blocked.length, filter: { group: "focus", value: "blocked" } });
+    }
+    if (incompleteChains.length) {
+      actions.push({ label: "Promote or close incomplete workflow chains", value: incompleteChains.length, filter: { group: "focus", value: "needs-promotion" } });
+    }
+    if (brokenRefs.length) {
+      actions.push({ label: "Repair broken references", value: brokenRefs.length, health: true });
+    }
+    if (qualityFindings.length) {
+      actions.push({ label: "Open validation health", value: qualityFindings.length, health: true });
+    }
+    if (missingStatus.length) {
+      actions.push({ label: "Normalize missing or ambiguous statuses", value: missingStatus.length, path: missingStatus[0]?.relPath || "" });
+    }
+    if (!actions.length) {
+      actions.push({ label: "No immediate operator action detected", value: "OK" });
+    }
+
     const stageRows = Object.entries(countsByStage)
       .sort((left, right) => String(left[0]).localeCompare(String(right[0])))
-      .map(([stage, count]) => `<li class="viewer-insights__item"><span>${escapeHtml(stage)}</span><strong>${escapeHtml(count)}</strong></li>`)
-      .join("");
-    const recentRows = [...latestItems]
-      .sort((left, right) => (Date.parse(right.updatedAt || "") || 0) - (Date.parse(left.updatedAt || "") || 0))
-      .slice(0, 8)
-      .map((item) => `<li class="viewer-insights__item"><span>${escapeHtml(item.id)}</span><strong>${escapeHtml(item.indicators?.Status || "No status")}</strong></li>`)
-      .join("");
+      .map(([stage, count]) => [stage, count]);
     return `
       <div class="viewer-insights">
-        <div class="viewer-insights__summary">${cards}</div>
-        <div class="viewer-insights__grid">
-          <div class="viewer-insights__card">
-            <div class="viewer-insights__label">Incomplete chains</div>
-            <div class="viewer-insights__value">${escapeHtml(incompleteChains)}</div>
-          </div>
-        </div>
+        <div class="viewer-insights__summary">${renderMetricCards([
+          ["Docs", docs.length],
+          ["Open", open.length],
+          ["Closed", closed.length],
+          ["Blocked", blocked.length],
+          ["Missing status", missingStatus.length],
+          ["Modified 7d", recentlyModified.length]
+        ])}</div>
+        <section class="viewer-insights__section">
+          <h2>Overview</h2>
+          <ul class="viewer-insights__list">${renderInsightRows(stageRows, "No docs loaded")}</ul>
+        </section>
+        <section class="viewer-insights__section">
+          <h2>Flow health</h2>
+          <ul class="viewer-insights__list">${renderInsightRows([
+            ["Incomplete workflow chains", incompleteChains.length],
+            ["Promotion gaps", incompleteChains.filter((item) => item.stage === "request" || item.stage === "backlog").length],
+            ["Orphan or unlinked docs", unlinked.length],
+            ["Broken reference risks", brokenRefs.length]
+          ])}</ul>
+          <ul class="viewer-insights__rows">${renderDocRows(incompleteChains, "No incomplete chains")}</ul>
+        </section>
         <section class="viewer-insights__section">
-          <h2>Corpus families</h2>
-          <ul class="viewer-insights__list">${stageRows || '<li class="viewer-insights__item">No docs loaded</li>'}</ul>
+          <h2>Activity</h2>
+          <ul class="viewer-insights__list">${renderInsightRows([
+            ["Latest changes", recentRows.map(itemLabel).join(", ") || "None"],
+            ["Stale active docs", staleActive.map(itemLabel).join(", ") || "None"],
+            ["Recently active docs", recentlyModified.slice(0, 8).map(itemLabel).join(", ") || "None"],
+            ["Activity classification", `recent ${recentlyModified.length}, stale ${open.filter(isStale).length}, quiet ${Math.max(0, open.length - recentlyModified.length)}`]
+          ])}</ul>
+          <ul class="viewer-insights__rows">${renderDocRows(recentRows, "No recent documents")}</ul>
         </section>
         <section class="viewer-insights__section">
-          <h2>Recent activity</h2>
-          <ul class="viewer-insights__list">${recentRows || '<li class="viewer-insights__item">No recent docs</li>'}</ul>
+          <h2>Traceability</h2>
+          <ul class="viewer-insights__list">${renderInsightRows([
+            ["Most referenced docs", mostReferenced.map((item) => `${item.id} (${(item.usedBy || []).length})`).join(", ") || "None"],
+            ["Unlinked docs", unlinked.slice(0, 8).map((item) => item.id).join(", ") || "None"],
+            ["Broken references", brokenRefs.slice(0, 8).join(", ") || "None"],
+            ["Relationships by type", Object.entries(relationshipCounts).map(([stage, count]) => `${stage} ${count}`).join(", ") || "None"]
+          ])}</ul>
+          <ul class="viewer-insights__rows">${renderDocRows(unlinked, "No unlinked documents")}${renderPathRows(brokenRefs, "No broken references")}</ul>
+        </section>
+        <section class="viewer-insights__section">
+          <h2>Quality signals</h2>
+          <ul class="viewer-insights__list">${renderInsightRows([
+            ["Lint/audit categories", Object.entries(qualityBySource).map(([key, count]) => `${key} ${count}`).join(", ") || "No findings loaded"],
+            ["Findings by document type", Object.entries(qualityByDocType).map(([key, count]) => `${key} ${count}`).join(", ") || "No findings loaded"],
+            ["Concentrated issues", concentratedIssues.map(([key, count]) => `${key} ${count}`).join(", ") || "None"]
+          ])}</ul>
+          <ul class="viewer-insights__rows">${renderPathRows(concentratedIssues.map(([key, count]) => `${key} (${count})`), "No concentrated issues")}</ul>
+        </section>
+        <section class="viewer-insights__section">
+          <h2>Operator actions</h2>
+          <ul class="viewer-insights__rows">${renderActionRows(actions)}</ul>
         </section>
       </div>
     `;
   }
 
-  function showCorpusInsights() {
-    setDocument("Corpus insights", buildCorpusInsights());
+  async function showCorpusInsights() {
+    const [lintResponse, auditResponse] = await Promise.all([fetch("/api/lint"), fetch("/api/audit")]);
+    const [lintData, auditData] = await Promise.all([lintResponse.json(), auditResponse.json()]);
+    setDocument("Corpus insights", buildCorpusInsights(lintData, auditData));
     setMeta("Corpus insights loaded.");
   }
 
@@ -711,9 +1208,9 @@
     const list = findings.length
       ? findings.slice(0, 50).map((finding) => {
           const path = finding.path || "";
-          const pathControl = path
+          const pathControl = path && isSafeLogicsDocPath(path)
             ? `<button class="viewer-health__path" type="button" data-viewer-doc-path="${escapeHtml(path)}">${escapeHtml(path)}</button>`
-            : '<span class="viewer-health__meta">Repository-level finding</span>';
+            : `<span class="viewer-health__meta">${escapeHtml(path ? `Repository-level or unsafe path: ${path}` : "Repository-level finding")}</span>`;
           const severity = finding.severity || finding.code || finding.source || "finding";
           return `
             <li class="viewer-health__issue">
@@ -744,6 +1241,710 @@
     setMeta("Health loaded.");
   }
 
+  function objectEntries(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? Object.entries(value) : [];
+  }
+
+  function asArray(value) {
+    if (Array.isArray(value)) {
+      return value;
+    }
+    if (value && typeof value === "object") {
+      return Object.entries(value).map(([key, entry]) => ({ name: key, ...(entry && typeof entry === "object" ? entry : { value: entry }) }));
+    }
+    return [];
+  }
+
+  function pickFirstObject(status, keys) {
+    for (const key of keys) {
+      if (status?.[key] && typeof status[key] === "object" && !Array.isArray(status[key])) {
+        return status[key];
+      }
+    }
+    return {};
+  }
+
+  function pickFirstArray(status, keys) {
+    for (const key of keys) {
+      const entries = asArray(status?.[key]);
+      if (entries.length) {
+        return entries;
+      }
+    }
+    return [];
+  }
+
+  function cdxRows(status) {
+    return asArray(status?.rows);
+  }
+
+  function cdxProviders(status) {
+    const explicitProviders = pickFirstArray(status, ["providers", "providerStatus", "provider_status"]);
+    if (explicitProviders.length) {
+      return explicitProviders;
+    }
+    const grouped = new Map();
+    cdxRows(status).forEach((row) => {
+      const provider = String(row.provider || "unknown");
+      const current = grouped.get(provider) || { name: provider, enabled: 0, active: 0, authenticated: 0, sessions: 0, lowest_available_pct: null };
+      current.sessions += 1;
+      if (row.enabled) {
+        current.enabled += 1;
+      }
+      if (row.active) {
+        current.active += 1;
+      }
+      if (String(row.auth_status || "").toLowerCase() === "authenticated") {
+        current.authenticated += 1;
+      }
+      if (typeof row.available_pct === "number") {
+        current.lowest_available_pct = current.lowest_available_pct === null
+          ? row.available_pct
+          : Math.min(current.lowest_available_pct, row.available_pct);
+      }
+      current.state = current.active > 0 ? "active" : current.enabled > 0 ? "enabled" : "disabled";
+      grouped.set(provider, current);
+    });
+    return Array.from(grouped.values());
+  }
+
+  function cdxSessions(status) {
+    const explicitSessions = pickFirstArray(status, ["sessions", "activeSessions", "active_sessions"]);
+    return sortCdxSessionsByRemaining(explicitSessions.length ? explicitSessions : cdxRows(status));
+  }
+
+  function cdxReadiness(status) {
+    const explicitReadiness = pickFirstObject(status, ["readiness", "quota", "quotas", "limits"]);
+    if (objectEntries(explicitReadiness).length) {
+      return explicitReadiness;
+    }
+    const rows = cdxRows(status);
+    if (!rows.length) {
+      return {};
+    }
+    const enabled = rows.filter((row) => row.enabled).length;
+    const active = rows.filter((row) => row.active).length;
+    const authenticated = rows.filter((row) => String(row.auth_status || "").toLowerCase() === "authenticated").length;
+    const availableValues = rows.map((row) => row.available_pct).filter((value) => typeof value === "number");
+    const lowestAvailable = availableValues.length ? Math.min(...availableValues) : null;
+    return {
+      enabled_sessions: enabled,
+      active_sessions: active,
+      authenticated_sessions: authenticated,
+      lowest_remaining: lowestAvailable === null ? "not reported" : `${lowestAvailable}%`
+    };
+  }
+
+  function renderCdxObjectRows(value, emptyText) {
+    const rows = objectEntries(value).slice(0, 12).map(([key, entry]) => `
+      <li class="viewer-cdx__row">
+        <span>${escapeHtml(cdxLabel(key))}</span>
+        <strong>${escapeHtml(typeof entry === "object" ? JSON.stringify(entry) : entry)}</strong>
+      </li>
+    `).join("");
+    return rows || `<li class="viewer-cdx__empty">${escapeHtml(emptyText)}</li>`;
+  }
+
+  function cdxLabel(value) {
+    return String(value || "")
+      .replace(/[_-]+/g, " ")
+      .replace(/\b\w/g, (letter) => letter.toUpperCase());
+  }
+
+  function cdxStateClass(value) {
+    const state = String(value || "").toLowerCase();
+    if (["ready", "ok", "active", "enabled", "authenticated"].some((entry) => state.includes(entry))) {
+      return "ok";
+    }
+    if (["starting", "pending", "warning", "low", "limited"].some((entry) => state.includes(entry))) {
+      return "warn";
+    }
+    if (["error", "failed", "disabled", "unavailable", "unauthenticated"].some((entry) => state.includes(entry))) {
+      return "bad";
+    }
+    return "neutral";
+  }
+
+  function cdxRemainingPct(item) {
+    const value = item?.remaining_pct ?? item?.remainingPct ?? item?.available_pct ?? item?.availablePct ?? item?.lowest_available_pct ?? item?.lowestAvailablePct;
+    const percent = Number(value);
+    return Number.isFinite(percent) ? Math.max(0, Math.min(100, Math.round(percent))) : null;
+  }
+
+  function cdxPct(value) {
+    const percent = Number(value);
+    return Number.isFinite(percent) ? `${Math.max(0, Math.min(100, Math.round(percent)))}%` : "-";
+  }
+
+  function cdxField(item, keys, fallback = "-") {
+    for (const key of keys) {
+      const value = item?.[key];
+      if (value !== undefined && value !== null && value !== "") {
+        return value;
+      }
+    }
+    return fallback;
+  }
+
+  function cdxRemainingClass(percent) {
+    if (percent === null) {
+      return "neutral";
+    }
+    if (percent <= 10) {
+      return "bad";
+    }
+    if (percent <= 30) {
+      return "warn";
+    }
+    return "ok";
+  }
+
+  function sortCdxSessionsByRemaining(entries) {
+    return [...entries].sort((left, right) => {
+      const leftRemaining = cdxRemainingPct(left);
+      const rightRemaining = cdxRemainingPct(right);
+      if (leftRemaining === null && rightRemaining === null) {
+        return 0;
+      }
+      if (leftRemaining === null) {
+        return 1;
+      }
+      if (rightRemaining === null) {
+        return -1;
+      }
+      return rightRemaining - leftRemaining;
+    });
+  }
+
+  function formatCdxValue(key, value) {
+    if (["reset_at", "resetAt", "resets_at", "resetsAt", "reset_5h_at", "reset5hAt", "reset_week_at", "resetWeekAt", "updated_at", "updatedAt"].includes(key)) {
+      return formatCdxResetAt(value);
+    }
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+
+  function parseCdxDate(value) {
+    const raw = String(value || "").trim();
+    if (!raw) {
+      return null;
+    }
+    const shortDate = raw.match(/^([A-Za-z]{3,})\s+(\d{1,2})\s+(\d{1,2}:\d{2})$/);
+    if (shortDate) {
+      const year = new Date().getFullYear();
+      const timestamp = Date.parse(`${shortDate[1]} ${shortDate[2]} ${year} ${shortDate[3]}`);
+      return Number.isFinite(timestamp) ? timestamp : null;
+    }
+    const timestamp = Date.parse(raw);
+    if (Number.isFinite(timestamp)) {
+      return timestamp;
+    }
+    return null;
+  }
+
+  function formatRelativeTime(timestamp) {
+    const diffMs = timestamp - Date.now();
+    const absMs = Math.abs(diffMs);
+    const minutes = Math.round(absMs / 60000);
+    if (minutes < 1) {
+      return diffMs >= 0 ? "now" : "just now";
+    }
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    const remainingMinutes = minutes % 60;
+    let body = "";
+    if (days > 0) {
+      body = `${days}d${remainingHours > 0 ? ` ${remainingHours}h` : ""}`;
+    } else if (hours > 0) {
+      body = `${hours}h${remainingMinutes > 0 ? ` ${remainingMinutes}m` : ""}`;
+    } else {
+      body = `${minutes}m`;
+    }
+    return diffMs >= 0 ? `in ${body}` : `${body} ago`;
+  }
+
+  function formatCdxResetAt(value) {
+    const raw = String(value || "").trim();
+    if (!raw) {
+      return "-";
+    }
+    const timestamp = parseCdxDate(raw);
+    return timestamp === null ? raw : formatRelativeTime(timestamp);
+  }
+
+  function formatCdxCredits(value) {
+    const text = String(value ?? "").trim();
+    if (!text || text === "-") {
+      return "-";
+    }
+    const number = Number(text);
+    return Number.isFinite(number) ? number.toFixed(2) : text;
+  }
+
+  function renderCdxBadge(value, fallback = "reported") {
+    const label = String(value || fallback || "reported");
+    return `<span class="viewer-cdx__badge viewer-cdx__badge--${cdxStateClass(label)}">${escapeHtml(cdxLabel(label))}</span>`;
+  }
+
+  function cdxDetailEntries(item, excludedKeys) {
+    return objectEntries(item)
+      .filter(([key, value]) => !excludedKeys.includes(key) && value !== undefined && value !== null && value !== "")
+      .slice(0, 6);
+  }
+
+  function renderCdxDetailPills(item, excludedKeys) {
+    const details = cdxDetailEntries(item, excludedKeys).map(([key, value]) => `
+      <span class="viewer-cdx__pill"><span>${escapeHtml(cdxLabel(key))}</span><strong>${escapeHtml(formatCdxValue(key, value))}</strong></span>
+    `).join("");
+    return details ? `<div class="viewer-cdx__pills">${details}</div>` : "";
+  }
+
+  function renderCdxRemainingPill(item) {
+    const percent = cdxRemainingPct(item);
+    if (percent === null) {
+      return "";
+    }
+    return `
+      <span class="viewer-cdx__remaining viewer-cdx__remaining--${cdxRemainingClass(percent)}" title="${escapeHtml(percent)}% usage remaining">
+        <span>Remaining</span>
+        <strong>${escapeHtml(percent)}%</strong>
+      </span>
+    `;
+  }
+
+  function cdxSessionBlock(item) {
+    const explicit = cdxField(item, ["block", "blocked", "blocking"], "");
+    if (explicit && explicit !== true) {
+      return explicit;
+    }
+    const fiveHour = Number(cdxField(item, ["remaining_5h_pct", "remaining5hPct"], NaN));
+    const week = Number(cdxField(item, ["remaining_week_pct", "remainingWeekPct"], NaN));
+    if (Number.isFinite(fiveHour) && fiveHour <= 0) {
+      return "5H";
+    }
+    if (Number.isFinite(week) && week <= 1) {
+      return "WEEK";
+    }
+    return explicit === true ? "YES" : "-";
+  }
+
+  function renderCdxSessionTable(sessions, emptyText) {
+    if (!sessions.length) {
+      return `<div class="viewer-cdx__empty">${escapeHtml(emptyText)}</div>`;
+    }
+    const rows = sessions.slice(0, 24).map((entry) => {
+      const item = entry && typeof entry === "object" ? entry : { value: entry };
+      const name = cdxField(item, ["session_name", "name", "id", "value"]);
+      const sessionName = `${name}${item.active ? "*" : ""}`;
+      const status = cdxField(item, ["status", "state"]);
+      const auth = String(cdxField(item, ["auth_status", "authStatus"], "-")).replace("authenticated", "logged");
+      const block = cdxSessionBlock(item);
+      return `
+        <tr>
+          <td class="viewer-cdx__session-name">${escapeHtml(sessionName)}</td>
+          <td>${escapeHtml(cdxField(item, ["provider"], "-"))}</td>
+          <td>${renderCdxBadge(status)}</td>
+          <td>${escapeHtml(auth)}</td>
+          <td>${renderCdxRemainingPill(item) || escapeHtml(cdxPct(cdxField(item, ["available_pct", "availablePct"], NaN)))}</td>
+          <td>${escapeHtml(cdxPct(cdxField(item, ["remaining_5h_pct", "remaining5hPct"], NaN)))}</td>
+          <td>${escapeHtml(cdxPct(cdxField(item, ["remaining_week_pct", "remainingWeekPct"], NaN)))}</td>
+          <td>${escapeHtml(block)}</td>
+          <td>${escapeHtml(formatCdxCredits(cdxField(item, ["credits", "cr"], "-")))}</td>
+          <td>${escapeHtml(formatCdxResetAt(cdxField(item, ["reset_5h_at", "reset5hAt", "reset_at", "resetAt"], "")))}</td>
+          <td>${escapeHtml(formatCdxResetAt(cdxField(item, ["reset_week_at", "resetWeekAt", "reset_at", "resetAt"], "")))}</td>
+          <td>${escapeHtml(formatCdxResetAt(cdxField(item, ["updated_at", "updatedAt"], "")))}</td>
+        </tr>
+      `;
+    }).join("");
+    return `
+      <div class="viewer-cdx__table-wrap">
+        <table class="viewer-cdx__table">
+          <thead>
+            <tr>
+              <th>SESSION</th>
+              <th>PROV.</th>
+              <th>STATUS</th>
+              <th>AUTH</th>
+              <th>OK</th>
+              <th>5H</th>
+              <th>WEEK</th>
+              <th>BLOCK</th>
+              <th>CR</th>
+              <th>RESET 5H</th>
+              <th>RESET WEEK</th>
+              <th>UPDATED</th>
+            </tr>
+          </thead>
+          <tbody>${rows}</tbody>
+        </table>
+      </div>
+    `;
+  }
+
+  function renderCdxEntityRows(entries, emptyText, options = {}) {
+    const titleKeys = options.titleKeys || ["name", "session_name", "id", "provider", "model", "value"];
+    const stateKeys = options.stateKeys || ["state", "status", "readiness", "available", "auth_status"];
+    const excludedKeys = [...titleKeys, ...stateKeys, "available_pct", "availablePct", "remaining_pct", "remainingPct", "lowest_available_pct", "lowestAvailablePct"];
+    const rows = entries.slice(0, 16).map((entry) => {
+      const item = entry && typeof entry === "object" ? entry : { value: entry };
+      const name = titleKeys.map((key) => item[key]).find(Boolean) || "entry";
+      const state = stateKeys.map((key) => item[key]).find((value) => value !== undefined && value !== null && value !== "") || "";
+      const subtitle = options.subtitleKeys
+        ? options.subtitleKeys.map((key) => item[key]).filter(Boolean).join(" · ")
+        : "";
+      return `
+        <li class="viewer-cdx__entity">
+          <div class="viewer-cdx__entity-main">
+            <div>
+              <strong>${escapeHtml(name)}</strong>
+              ${subtitle ? `<div class="viewer-cdx__meta">${escapeHtml(subtitle)}</div>` : ""}
+            </div>
+            <div class="viewer-cdx__entity-status">
+              ${renderCdxRemainingPill(item)}
+              ${renderCdxBadge(state)}
+            </div>
+          </div>
+          ${renderCdxDetailPills(item, excludedKeys)}
+        </li>
+      `;
+    }).join("");
+    return rows || `<li class="viewer-cdx__empty">${escapeHtml(emptyText)}</li>`;
+  }
+
+  function renderCdxStatus(payload) {
+    if (!payload || payload.state !== "ok") {
+      return `
+        <div class="viewer-cdx">
+          <div class="viewer-cdx__state">${escapeHtml(payload?.message || "CDX status is unavailable.")}</div>
+        </div>
+      `;
+    }
+    const status = payload.status || {};
+    const providers = cdxProviders(status);
+    const sessions = cdxSessions(status);
+    const readiness = cdxReadiness(status);
+    const commands = pickFirstArray(status, ["nextCommands", "next_commands", "safeCommands", "safe_commands", "commands"])
+      .map((entry) => typeof entry === "string" ? entry : (entry.command || entry.value || entry.name || ""))
+      .filter(Boolean);
+    if (!commands.length) {
+      commands.push("cdx status --json");
+    }
+    const runtimeState = status.state || status.status || status.availability || "ok";
+    const readinessCount = objectEntries(readiness).length;
+    const cards = [
+      ["Runtime", runtimeState],
+      ["Providers", providers.length],
+      ["Sessions", sessions.length],
+      ["Readiness", readinessCount ? `${readinessCount} signals` : "Not reported"]
+    ].map(([label, value]) => `
+      <div class="viewer-cdx__card">
+        <div class="viewer-cdx__label">${escapeHtml(label)}</div>
+        <div class="viewer-cdx__value">${label === "Runtime" ? renderCdxBadge(value) : escapeHtml(value)}</div>
+      </div>
+    `).join("");
+    const commandRows = commands.slice(0, 10).map((command, index) => `
+      <li>
+        <span>${escapeHtml(index + 1)}</span>
+        <code>${escapeHtml(command)}</code>
+      </li>
+    `).join("");
+    return `
+      <div class="viewer-cdx">
+        <div class="viewer-cdx__summary">${cards}</div>
+        <div class="viewer-cdx__workspace">
+          <div class="viewer-cdx__stack">
+            <section class="viewer-cdx__section">
+              <h2 class="viewer-cdx__heading">Sessions</h2>
+              ${renderCdxSessionTable(sessions, "No sessions reported.")}
+            </section>
+            <section class="viewer-cdx__section">
+              <h2 class="viewer-cdx__heading">Providers</h2>
+              <ul class="viewer-cdx__list">${renderCdxEntityRows(providers, "No provider status reported.", { subtitleKeys: ["model"] })}</ul>
+            </section>
+          </div>
+          <div class="viewer-cdx__stack">
+            <section class="viewer-cdx__section">
+              <h2 class="viewer-cdx__heading">Readiness and quota</h2>
+              <ul class="viewer-cdx__list">${renderCdxObjectRows(readiness, "No readiness or quota details reported.")}</ul>
+            </section>
+            <section class="viewer-cdx__section">
+              <h2 class="viewer-cdx__heading">Safe next commands</h2>
+              <ul class="viewer-cdx__commands">${commandRows || '<li class="viewer-cdx__empty">No suggested commands reported.</li>'}</ul>
+            </section>
+          </div>
+        </div>
+      </div>
+    `;
+  }
+
+  async function showCdxStatus(options = {}) {
+    if (!options.silent) {
+      setMeta("Checking CDX status...");
+    }
+    const response = await fetch("/api/cdx-status");
+    let data = {};
+    try {
+      data = await response.json();
+    } catch {
+      data = {};
+    }
+    if (response.status === 404) {
+      setDocument("CDX status", renderCdxStatus({
+        state: "unavailable",
+        message: "CDX status endpoint unavailable. Restart the local viewer so it loads the current logics-manager backend."
+      }));
+      setMeta("Restart the local viewer to enable CDX status.");
+      return;
+    }
+    if (!response.ok || !data.ok) {
+      throw new Error(data.error || "Unable to load CDX status.");
+    }
+    setDocument("CDX status", renderCdxStatus(data.payload));
+    setMeta(options.silent ? "CDX status refreshed." : "CDX status loaded.");
+  }
+
+  function renderGitStatus(payload) {
+    if (!payload || payload.state !== "ok") {
+      return `
+        <div class="viewer-git">
+          <div class="viewer-git__state">${escapeHtml(payload?.message || "Git status is unavailable.")}</div>
+        </div>
+      `;
+    }
+    const counts = payload.counts || {};
+    const stagedCount = Number(counts.staged || 0);
+    const modifiedCount = Number(counts.modified || 0);
+    const deletedCount = Number(counts.deleted || 0);
+    const renamedCount = Number(counts.renamed || 0);
+    const untrackedCount = Number(counts.untracked || 0);
+    const summary = [
+      ["Branch", payload.branch || "HEAD"],
+      ["Tracking", payload.tracking || "None"],
+      ["Ahead", payload.ahead || 0],
+      ["Behind", payload.behind || 0],
+      ["State", payload.clean ? "Clean" : "Dirty"],
+      ["Staged", stagedCount],
+      ["Worktree", modifiedCount + deletedCount + renamedCount],
+      ["Untracked", untrackedCount]
+    ];
+    const cards = renderMetricCards(summary);
+    const groupDefs = [
+      ["staged", "Staged", "staged"],
+      ["modified", "Modified", "worktree"],
+      ["deleted", "Deleted", "worktree"],
+      ["renamed", "Renamed", "worktree"],
+      ["untracked", "Untracked", "untracked"]
+    ];
+    const domainDefs = [
+      ["changes", "Changes", stagedCount + modifiedCount + deletedCount + renamedCount + untrackedCount],
+      ["staged", "Staged", stagedCount],
+      ["worktree", "Worktree", modifiedCount + deletedCount + renamedCount],
+      ["untracked", "Untracked", untrackedCount],
+      ["history", "History", Array.isArray(payload.recentCommits) ? payload.recentCommits.length : (payload.latestCommit ? 1 : 0)],
+      ["remote", "Remote", payload.tracking ? 1 : 0]
+    ];
+    const domains = domainDefs.map(([key, label, count], index) => `
+      <button class="viewer-git__domain${index === 0 ? " is-active" : ""}" type="button" data-viewer-git-domain="${escapeHtml(key)}" aria-pressed="${index === 0 ? "true" : "false"}">
+        <span class="viewer-git__domain-label">${escapeHtml(label)}${key === "changes" ? gitBadgeHtml("changes") : ""}${key === "history" ? gitBadgeHtml("history") : ""}</span><strong>${escapeHtml(count)}</strong>
+      </button>
+    `).join("");
+    const renderFileSections = (allowedKeys) => groupDefs.filter(([key]) => allowedKeys.includes(key)).map(([key, label]) => {
+      const entries = Array.isArray(payload.groups?.[key]) ? payload.groups[key] : [];
+      if (!entries.length) {
+        return "";
+      }
+      return `
+        <section class="viewer-git__section">
+          <h2>${escapeHtml(label)}</h2>
+          <ul class="viewer-git__files">${entries.map((entry) => `
+            <li>
+              <button class="viewer-git__file" type="button" data-viewer-git-file="${escapeHtml(entry.path)}" data-viewer-git-cached="${key === "staged" ? "1" : "0"}">
+                <span class="viewer-git__file-path">${escapeHtml(entry.from ? `${entry.from} -> ${entry.path}` : entry.path)}</span>
+                ${entry.logicsType ? `<span class="viewer-git__file-kind">${escapeHtml(entry.logicsType)}</span>` : ""}
+              </button>
+            </li>
+          `).join("")}</ul>
+        </section>
+      `;
+    }).join("");
+    const changesSections = renderFileSections(["staged", "modified", "deleted", "renamed", "untracked"]);
+    const stagedSections = renderFileSections(["staged"]);
+    const worktreeSections = renderFileSections(["modified", "deleted", "renamed"]);
+    const untrackedSections = renderFileSections(["untracked"]);
+    const clean = payload.clean ? '<p class="viewer-git__state">Working tree clean.</p>' : "";
+    const recentCommits = Array.isArray(payload.recentCommits) ? payload.recentCommits : [];
+    const historyRows = recentCommits.length
+      ? recentCommits.map((commit) => `
+        <li class="viewer-git__commit-row">
+          <div class="viewer-git__commit-main">
+            <code>${escapeHtml(commit.hash || "")}</code>
+            <strong>${escapeHtml(commit.subject || "Untitled commit")}</strong>
+          </div>
+          <div class="viewer-git__commit-meta">
+            <span>${escapeHtml([commit.author, commit.date].filter(Boolean).join(" · ") || "Unknown")}</span>
+            ${commit.refs ? `<span class="viewer-git__commit-refs">${escapeHtml(commit.refs)}</span>` : ""}
+          </div>
+        </li>
+      `).join("")
+      : `<li class="viewer-git__commit-row">${escapeHtml(payload.latestCommit || "No commit history available.")}</li>`;
+    const history = `
+      <section class="viewer-git__section">
+        <h2>History</h2>
+        <ul class="viewer-git__commits">${historyRows}</ul>
+      </section>
+    `;
+    const remote = `
+      <section class="viewer-git__section">
+        <h2>Remote</h2>
+        <p class="viewer-git__state">${escapeHtml(payload.tracking ? `Tracking ${payload.tracking}` : "No upstream branch detected.")}</p>
+        <p class="viewer-git__state">${escapeHtml(`Ahead ${payload.ahead || 0}, behind ${payload.behind || 0}`)}</p>
+      </section>
+    `;
+    return `
+      <div class="viewer-git">
+        <div class="viewer-git__summary">${cards}</div>
+        <div class="viewer-git__workspace">
+          <nav class="viewer-git__domains" aria-label="Git domains">${domains}</nav>
+          <div class="viewer-git__content" aria-label="Git domain content">
+            <section class="viewer-git__panel" data-viewer-git-panel="changes">
+              <header class="viewer-git__panel-header"><span>Changes</span><strong>${escapeHtml(stagedCount + modifiedCount + deletedCount + renamedCount + untrackedCount)} files</strong></header>
+              ${clean}
+              ${changesSections || '<p class="viewer-git__state">No file changes detected.</p>'}
+            </section>
+            <section class="viewer-git__panel" data-viewer-git-panel="staged" hidden>
+              <header class="viewer-git__panel-header"><span>Staged</span><strong>${escapeHtml(stagedCount)} files</strong></header>
+              ${stagedSections || '<p class="viewer-git__state">No staged files.</p>'}
+            </section>
+            <section class="viewer-git__panel" data-viewer-git-panel="worktree" hidden>
+              <header class="viewer-git__panel-header"><span>Worktree</span><strong>${escapeHtml(modifiedCount + deletedCount + renamedCount)} files</strong></header>
+              ${worktreeSections || '<p class="viewer-git__state">No modified, deleted, or renamed files.</p>'}
+            </section>
+            <section class="viewer-git__panel" data-viewer-git-panel="untracked" hidden>
+              <header class="viewer-git__panel-header"><span>Untracked</span><strong>${escapeHtml(untrackedCount)} files</strong></header>
+              ${untrackedSections || '<p class="viewer-git__state">No untracked files.</p>'}
+            </section>
+            <section class="viewer-git__panel" data-viewer-git-panel="history" hidden>
+              <header class="viewer-git__panel-header"><span>History</span><strong>${escapeHtml(recentCommits.length || (payload.latestCommit ? 1 : 0))} commits</strong></header>
+              ${history}
+            </section>
+            <section class="viewer-git__panel" data-viewer-git-panel="remote" hidden>
+              <header class="viewer-git__panel-header"><span>Remote</span><strong>${escapeHtml(payload.tracking || "none")}</strong></header>
+              ${remote}
+            </section>
+          </div>
+          <section class="viewer-git__detail" aria-label="Git diff">
+            <div class="viewer-git__detail-title">Diff preview</div>
+            <div class="viewer-git__diff" data-viewer-git-diff>Select a changed file to preview its diff.</div>
+          </section>
+        </div>
+      </div>
+    `;
+  }
+
+  function setActiveGitFile(button) {
+    document.querySelectorAll("[data-viewer-git-file]").forEach((node) => {
+      if (node instanceof HTMLElement) {
+        node.classList.toggle("is-active", node === button);
+      }
+    });
+  }
+
+  async function loadGitDiff(path, cached, button = null) {
+    const diffPanel = document.querySelector("[data-viewer-git-diff]");
+    if (!(diffPanel instanceof HTMLElement) || !path) {
+      return;
+    }
+    if (button instanceof HTMLElement) {
+      setActiveGitFile(button);
+    }
+    diffPanel.textContent = "Loading diff...";
+    const params = new URLSearchParams({ path });
+    if (cached) {
+      params.set("cached", "1");
+    }
+    const response = await fetch(`/api/git-diff?${params.toString()}`);
+    const data = await response.json();
+    const payload = data.payload || {};
+    if (!response.ok || !data.ok || payload.state !== "ok") {
+      diffPanel.textContent = payload.message || data.error || "Unable to load diff.";
+      return;
+    }
+    const content = payload.diff || payload.message || "No diff is available for this file.";
+    diffPanel.innerHTML = `<div class="viewer-git__diff-meta">${escapeHtml(payload.path || path)} · ${escapeHtml(payload.mode || "worktree")}${payload.truncated ? " · truncated" : ""}</div><pre><code>${escapeHtml(content)}</code></pre>`;
+  }
+
+  function applyGitDomain(domain) {
+    const selected = domain || "changes";
+    document.querySelectorAll(".viewer-git__domain[data-viewer-git-domain]").forEach((node) => {
+      if (node instanceof HTMLElement) {
+        const active = node.getAttribute("data-viewer-git-domain") === selected;
+        node.classList.toggle("is-active", active);
+        node.setAttribute("aria-pressed", active ? "true" : "false");
+      }
+    });
+    document.querySelectorAll("[data-viewer-git-panel]").forEach((node) => {
+      if (node instanceof HTMLElement) {
+        node.hidden = node.getAttribute("data-viewer-git-panel") !== selected;
+      }
+    });
+  }
+
+  function currentGitViewState() {
+    const activeDomain = document.querySelector(".viewer-git__domain.is-active[data-viewer-git-domain]");
+    const activeFile = document.querySelector(".viewer-git__file.is-active[data-viewer-git-file]");
+    return {
+      domain: activeDomain instanceof HTMLElement ? activeDomain.getAttribute("data-viewer-git-domain") || "changes" : "changes",
+      path: activeFile instanceof HTMLElement ? activeFile.getAttribute("data-viewer-git-file") || "" : "",
+      cached: activeFile instanceof HTMLElement && activeFile.getAttribute("data-viewer-git-cached") === "1",
+    };
+  }
+
+  function findGitFileButton(path, cached) {
+    return Array.from(document.querySelectorAll("[data-viewer-git-file]")).find((node) => (
+      node instanceof HTMLElement &&
+      node.getAttribute("data-viewer-git-file") === path &&
+      (node.getAttribute("data-viewer-git-cached") === "1") === Boolean(cached)
+    )) || null;
+  }
+
+  async function showGitStatus(options = {}) {
+    const previous = options.preserve ? currentGitViewState() : { domain: "changes", path: "", cached: false };
+    if (!options.silent) {
+      setMeta("Checking Git status...");
+    }
+    const response = await fetch("/api/git-status");
+    let data = {};
+    try {
+      data = await response.json();
+    } catch {
+      data = {};
+    }
+    if (response.status === 404) {
+      setDocument("Git status", renderGitStatus({
+        state: "unavailable",
+        message: "Git status endpoint unavailable. Restart the local viewer so it loads the current logics-manager backend."
+      }));
+      setMeta("Restart the local viewer to enable Git status.");
+      return;
+    }
+    if (!response.ok || !data.ok) {
+      throw new Error(data.error || "Unable to load Git status.");
+    }
+    setGitBadgeCountsFromPayload(data.payload, { updateMain: false });
+    updateMainGitBadges();
+    setDocument("Git status", renderGitStatus(data.payload));
+    applyGitDomain(previous.domain || "changes");
+    const restoredFile = previous.path ? findGitFileButton(previous.path, previous.cached) : null;
+    const firstFile = restoredFile || document.querySelector("[data-viewer-git-file]");
+    if (firstFile instanceof HTMLElement) {
+      await loadGitDiff(firstFile.getAttribute("data-viewer-git-file") || "", firstFile.getAttribute("data-viewer-git-cached") === "1", firstFile);
+    }
+    setMeta(options.silent ? "Git status refreshed." : "Git status loaded.");
+  }
+
   window.acquireVsCodeApi = function acquireVsCodeApi() {
     return {
       postMessage(message) {
@@ -755,7 +1956,7 @@
           return;
         }
         if (message.type === "refresh") {
-          loadItems("POST").catch((error) => setMeta(error.message));
+          refreshViewer("POST").catch((error) => setMeta(error.message));
           return;
         }
         if (message.type === "open" || message.type === "read") {
@@ -786,22 +1987,68 @@
     setControlValue("show-companion-docs", true, "change");
     setControlValue("hide-empty-columns", true, "change");
     applyLocalViewerChrome();
-    [document.getElementById("viewer-insights"), document.getElementById("header-logics-insights")].forEach((button) => {
+    [document.getElementById("viewer-insights")].forEach((button) => {
       button?.addEventListener("click", () => {
-        showCorpusInsights();
+        showCorpusInsights().catch((error) => setMeta(error.message));
+      });
+    });
+    const autoControl = autoRefreshControl();
+    if (autoControl instanceof HTMLInputElement) {
+      autoControl.addEventListener("change", () => {
+        setAutoRefreshEnabled(autoControl.checked);
+      });
+      setAutoRefreshEnabled(autoControl.checked);
+    }
+    const intervalControl = refreshIntervalControl();
+    if (intervalControl instanceof HTMLSelectElement) {
+      updateRefreshIntervalControl();
+      intervalControl.addEventListener("change", () => {
+        setAutoRefreshIntervalSeconds(intervalControl.value, { user: true });
       });
+    }
+    bindRefreshMenuControls();
+    document.addEventListener("click", (event) => {
+      const target = event.target;
+      const button = refreshMenuButton();
+      const panel = refreshMenuPanel();
+      try {
+        if (target && (
+          button?.contains(target) ||
+          panel?.contains(target)
+        )) {
+          return;
+        }
+      } catch {
+        // Ignore non-node event targets and close the menu below.
+      }
+      setRefreshMenuOpen(false);
+    });
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        setRefreshMenuOpen(false);
+      }
     });
     document.querySelectorAll('[data-action="refresh"]').forEach((element) => {
       if (!(element instanceof HTMLElement)) {
         return;
       }
       element.addEventListener("click", () => {
-        loadItems("POST").catch((error) => setMeta(error.message));
+        setRefreshMenuOpen(false);
+        refreshViewer("POST").catch((error) => setMeta(error.message));
       });
     });
     document.getElementById("viewer-health")?.addEventListener("click", () => {
       showHealth().catch((error) => setMeta(error.message));
     });
+    document.getElementById("viewer-git")?.addEventListener("click", () => {
+      showGitStatus().catch((error) => setMeta(error.message));
+    });
+    document.getElementById("viewer-cdx")?.addEventListener("click", () => {
+      showCdxStatus().catch((error) => setMeta(error.message));
+    });
+    activityClearControl()?.addEventListener("click", () => {
+      clearActivityHistory();
+    });
     document.querySelectorAll("[data-viewer-filter-group]").forEach((element) => {
       if (element instanceof HTMLSelectElement) {
         element.addEventListener("change", () => {
@@ -828,10 +2075,44 @@
     document.addEventListener("click", (event) => {
       window.setTimeout(() => applyLocalViewerChrome(), 0);
       const target = event.target instanceof Element ? event.target.closest("[data-viewer-doc-path]") : null;
-      if (!(target instanceof HTMLElement)) {
+      const healthTarget = event.target instanceof Element ? event.target.closest("[data-viewer-open-health]") : null;
+      const filterTarget = event.target instanceof Element ? event.target.closest("[data-viewer-filter-group][data-viewer-filter-value]") : null;
+      const revealTarget = event.target instanceof Element ? event.target.closest("[data-viewer-reveal]") : null;
+      const gitDomainTarget = event.target instanceof Element ? event.target.closest(".viewer-git__domain[data-viewer-git-domain]") : null;
+      const gitFileTarget = event.target instanceof Element ? event.target.closest("[data-viewer-git-file]") : null;
+      if (revealTarget instanceof HTMLElement) {
+        const list = revealTarget.closest("ul");
+        list?.querySelectorAll("[data-viewer-hidden-row]").forEach((row) => {
+          if (row instanceof HTMLElement) {
+            row.hidden = false;
+            row.removeAttribute("data-viewer-hidden-row");
+          }
+        });
+        revealTarget.closest("li")?.remove();
+        return;
+      }
+      if (gitDomainTarget instanceof HTMLElement) {
+        applyGitDomain(gitDomainTarget.getAttribute("data-viewer-git-domain") || "changes");
+        return;
+      }
+      if (gitFileTarget instanceof HTMLElement) {
+        loadGitDiff(
+          gitFileTarget.getAttribute("data-viewer-git-file") || "",
+          gitFileTarget.getAttribute("data-viewer-git-cached") === "1",
+          gitFileTarget
+        ).catch((error) => setMeta(error.message));
+        return;
+      }
+      if (healthTarget instanceof HTMLElement) {
+        showHealth().catch((error) => setMeta(error.message));
+        return;
+      }
+      if (filterTarget instanceof HTMLElement) {
+        applyViewerFilter(filterTarget.getAttribute("data-viewer-filter-group") || "", filterTarget.getAttribute("data-viewer-filter-value") || "");
+        setMeta("Insight filter applied. Clear filters restores the normal viewer view.");
         return;
       }
-      const path = target.getAttribute("data-viewer-doc-path");
+      const path = target instanceof HTMLElement ? target.getAttribute("data-viewer-doc-path") : "";
       if (path) {
         showDocumentByPath(path).catch((error) => setMeta(error.message));
       }