@jagilber-org/index-server 1.26.11 → 1.27.2

package/CHANGELOG.md

@@ -6,7 +6,59 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 
 ## [Unreleased]
 
-## [1.26.11] - 2026-04-30
+## [1.27.2] - 2026-05-01
+
+### Fixed
+
+- **Release workflow** (`.github/workflows/release.yml`): trim `description` in `package.json` and `server.json` from 146 to 98 chars to satisfy the MCP Registry validator (`expected length <= 100` on `body.description`). The MCP Registry publish step had been failing on every release since v1.26.3 with HTTP 422.
+- **Release workflow** (`scripts/Invoke-ReleaseWorkflow.ps1`): add a fail-fast parity guard that aborts before tagging when `package.json.version` does not match the `-Tag` argument (sans `v` prefix). The v1.27.1 release shipped a tag whose `package.json` still said `1.27.0`, which caused the `Check npmjs version status` step to skip publish (it found `1.27.0` already on npmjs and set `already_published=true`). This guard prevents the same class of mismatch from reaching the public mirror again.
+
+### Added
+
+- **Release workflow** (`.github/workflows/release.yml`): publish to the GitHub Packages npm registry (`https://npm.pkg.github.com`) in addition to npmjs, so `https://github.com/jagilber-org/index-server/pkgs/npm/index-server` populates on each release. Auth uses the workflow-scoped `GITHUB_TOKEN` (no extra secret needed).
+
+### Notes
+
+- v1.27.1 was tagged on the public mirror but is **incomplete**: the npmjs publish step was skipped (stale version in tag), the GitHub Packages registry was never wired (now fixed), and the MCP Registry rejected the description (now fixed). v1.27.2 is the corrected release. v1.27.1 will not be retroactively republished.
+
+## [1.27.1] - 2026-05-01
+
+### Changed
+
+- **Security**: pin `mermaid` and `@mermaid-js/layout-elk` transitive `uuid` to `^14.0.0` via npm overrides to clear GHSA-w5hq-g745-h8pq. Server-side bundle has no mermaid imports; dashboard remains lazy-loaded.
+- **Build**: pin `@types/express-serve-static-core` to `5.0.7` to keep dashboard route handler signatures stable after lockfile regen pulled `5.1.1` (which changed `req.params` typing).
+
+### Fixed
+
+- **Deploy** (`scripts/deploy-local.ps1`): runtime `package.json` written to the deploy target now preserves the `overrides` block from the source manifest. Without it, `npm ci --omit=dev` failed with `EUSAGE Missing: uuid@11.1.1 from lock file` because the override-resolved lockfile didn't match the unstripped manifest.
+- **CodeQL pre-push gate** (`scripts/run-codeql-pre-push.ps1`): now sources `scripts/Load-RepoEnv.ps1` and honors absolute paths from `.env` (`CODEQL_DB_PATH`, `CODEQL_LOG_DIR`, `CODEQL_OUTPUT_PATH`, `CODEQL_LANGUAGE`, `CODEQL_THREADS`, `CODEQL_RAM`). Reuses pre-built databases instead of always rebuilding in-repo.
+- **Publish workflow** (`scripts/Publish-ToMirror.ps1`): after opening a publish PR via `-CreatePR`, now prints a copy-pasteable next-steps block (`gh api …/git/refs` + `gh release create --generate-notes`) so the operator can tag the merge commit and kick off the GitHub release in one shot. The `-WaitForMerge` success path also surfaces the `gh release create` command.
+
+## [1.27.0] - 2026-04-30
+
+### Changed (BREAKING)
+
+- **Rate limiting is now opt-in** and consolidated behind a single environment variable, `INDEX_SERVER_RATE_LIMIT` (#270).
+  - `INDEX_SERVER_RATE_LIMIT=0` (default, or unset) — rate limiting is **disabled**.
+  - `INDEX_SERVER_RATE_LIMIT=N` (positive integer) — enforces **N requests per minute** with a fixed 60-second window.
+  - Bulk import/export/backup/restore routes (`/api/admin/maintenance/normalize`, `/api/admin/maintenance/backup`, `/api/admin/maintenance/backups`, `/api/admin/maintenance/restore`, `/api/charts/export`, `/api/sqlite/backup`, `/api/sqlite/restore`, `/api/sqlite/export`) are **unconditionally exempt**, so dashboard bulk operations no longer trigger 429 responses.
+  - The 429 response body shape simplifies to `{ error, message, retryAfterSeconds, timestamp }`. The previous `tier` field (global vs. mutation) has been removed; there is now a single tier.
+
+### Removed (BREAKING)
+
+The following environment variables have been **removed with no back-compat aliases**. Replace them with `INDEX_SERVER_RATE_LIMIT`:
+
+| Removed variable | Replacement |
+|------------------|-------------|
+| `INDEX_SERVER_DISABLE_RATE_LIMIT` | unset / `INDEX_SERVER_RATE_LIMIT=0` (default) |
+| `INDEX_SERVER_DISABLE_USAGE_RATE_LIMIT` | unset / `INDEX_SERVER_RATE_LIMIT=0` (default) |
+| `INDEX_SERVER_RATE_LIMIT_MAX` | `INDEX_SERVER_RATE_LIMIT=<N>` |
+| `INDEX_SERVER_RATE_LIMIT_WINDOW_MS` | _removed; window is fixed at 60 seconds_ |
+| `INDEX_SERVER_RATE_LIMIT_MUTATION_MAX` | _removed; single tier only_ |
+
+Also removed: `DashboardHttpConfig.rateLimitEnabled / rateLimitWindowMs / rateLimitMax / rateLimitMutationMax` (replaced by `rateLimitPerMinute: number`); `ApiRoutesOptions.rateLimit` (replaced by `rateLimitPerMinute?: number`); `AdminConfig.serverSettings.rateLimit` reduced to `{ perMinute: number }`.
+
+
 
 ### Fixed
 

package/dist/config/dashboardConfig.d.ts

@@ -15,10 +15,17 @@ interface DashboardHttpConfig {
     verboseLogging: boolean;
     mutationEnabled: boolean;
     adminApiKey?: string;
-    rateLimitEnabled: boolean;
-    rateLimitWindowMs: number;
-    rateLimitMax: number;
-    rateLimitMutationMax: number;
+    /**
+     * Dashboard HTTP API rate limit, in requests per minute.
+     *
+     * - `0` (default) disables rate limiting entirely (HTTP API + usage tracking).
+     * - Any positive integer N enforces N requests/min globally with a fixed
+     *   60-second window. Bulk import/export/backup/restore routes are
+     *   unconditionally exempt regardless of this value.
+     *
+     * Configured via the `INDEX_SERVER_RATE_LIMIT` environment variable.
+     */
+    rateLimitPerMinute: number;
     tls: DashboardTlsConfig;
 }
 interface DashboardAdminConfig {

package/dist/config/dashboardConfig.js

@@ -36,10 +36,7 @@ function parseDashboardConfig(mutationEnabled, instructionsBaseDir) {
             verboseLogging: (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_VERBOSE_LOGGING'),
             mutationEnabled,
             adminApiKey: process.env.INDEX_SERVER_ADMIN_API_KEY || undefined,
-            rateLimitEnabled: !(0, envUtils_1.getBooleanEnv)('INDEX_SERVER_DISABLE_RATE_LIMIT'),
-            rateLimitWindowMs: Math.max(1, (0, configUtils_1.numberFromEnv)('INDEX_SERVER_RATE_LIMIT_WINDOW_MS', 60_000)),
-            rateLimitMax: Math.max(0, (0, configUtils_1.numberFromEnv)('INDEX_SERVER_RATE_LIMIT_MAX', 100)),
-            rateLimitMutationMax: Math.max(0, (0, configUtils_1.numberFromEnv)('INDEX_SERVER_RATE_LIMIT_MUTATION_MAX', 20)),
+            rateLimitPerMinute: Math.max(0, (0, configUtils_1.numberFromEnv)('INDEX_SERVER_RATE_LIMIT', 0)),
             tls: {
                 enabled: (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_DASHBOARD_TLS'),
                 certPath: process.env.INDEX_SERVER_DASHBOARD_TLS_CERT || undefined,

package/dist/dashboard/client/admin.html

@@ -1,29 +1,30 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta name="dashboard-build-version" content="1.26.11-9badd8dd">
+    <meta name="dashboard-build-version" content="1.27.2-d7f5ec0e">
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>Index Server Admin</title>
-    <link rel="stylesheet" href="css/admin.css?v=1.26.11-9badd8dd">
-    <script defer src="js/admin.utils.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.auth.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.overview.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.sessions.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.monitor.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.graph.js?v=1.26.11-9badd8dd"></script>
+    <link rel="stylesheet" href="css/admin.css?v=1.27.2-d7f5ec0e">
+    <script defer src="js/admin.utils.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.auth.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.overview.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.sessions.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.monitor.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.events.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.graph.js?v=1.27.2-d7f5ec0e"></script>
     <script defer src="js/marked.umd.js"></script>
-    <script defer src="js/admin.instructions.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.logs.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.maintenance.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.config.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.performance.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.instances.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.embeddings.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.messaging.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.sqlite.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.boot.js?v=1.26.11-9badd8dd"></script>
-    <script defer src="js/admin.feedback.js?v=1.26.11-9badd8dd"></script>
+    <script defer src="js/admin.instructions.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.logs.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.maintenance.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.config.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.performance.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.instances.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.embeddings.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.messaging.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.sqlite.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.boot.js?v=1.27.2-d7f5ec0e"></script>
+    <script defer src="js/admin.feedback.js?v=1.27.2-d7f5ec0e"></script>
 </head>
 <body>
     <div class="admin-container admin-root">
@@ -48,7 +49,7 @@
                 <button class="nav-btn" data-section="config" onclick="window.showSection && window.showSection('config')">Configuration</button>
                 <button id="nav-sessions" class="nav-btn" data-section="sessions" onclick="window.showSection && window.showSection('sessions')">Sessions</button>
                 <button class="nav-btn" data-section="maintenance" onclick="window.showSection && window.showSection('maintenance')">Maintenance</button>
-                <button class="nav-btn" data-section="monitoring" onclick="window.showSection && window.showSection('monitoring')">Monitoring</button>
+                <button class="nav-btn" data-section="monitoring" onclick="window.showSection && window.showSection('monitoring')">Monitoring<span id="nav-events-bubble" class="nav-bubble" hidden></span></button>
                 <button class="nav-btn" data-section="instructions" onclick="window.showSection && window.showSection('instructions')">Instructions</button>
                 <button class="nav-btn" data-section="graph" onclick="window.showSection && window.showSection('graph')">Graph</button>
                 <button class="nav-btn" data-section="embeddings" onclick="window.showSection && window.showSection('embeddings')">Embeddings</button>
@@ -328,6 +329,34 @@
         <!-- Monitoring Section -->
         <div id="monitoring-section" class="admin-section hidden">
             <div class="admin-card">
+                <div class="card-header">
+                    <div class="card-icon">⚠️</div>
+                    <div class="card-title">Recent Events <span id="events-counts-summary" class="muted small"></span></div>
+                    <div class="card-actions">
+                        <input id="events-search" class="form-input form-input-sm events-search" type="search" placeholder="Search msg/detail…" />
+                        <select id="events-level-filter" class="form-input form-input-sm">
+                            <option value="">All severities</option>
+                            <option value="WARN">WARN only</option>
+                            <option value="ERROR">ERROR only</option>
+                        </select>
+                        <select id="events-page-size" class="form-input form-input-sm" title="Page size">
+                            <option value="25">25 / page</option>
+                            <option value="50" selected>50 / page</option>
+                            <option value="100">100 / page</option>
+                            <option value="200">200 / page</option>
+                        </select>
+                        <button id="events-refresh-btn" class="action-btn-sm" onclick="window.loadEvents && window.loadEvents()">Refresh</button>
+                        <button id="events-clear-btn" class="action-btn-sm" onclick="window.clearEvents && window.clearEvents()">Mark All Read</button>
+                    </div>
+                </div>
+                <div id="events-panel" class="loading">Loading events…</div>
+                <div id="events-pager" class="events-pager hidden">
+                    <button id="events-prev" class="action-btn-sm" type="button">‹ Newer</button>
+                    <span id="events-page-info" class="muted small"></span>
+                    <button id="events-next" class="action-btn-sm" type="button">Older ›</button>
+                </div>
+            </div>
+            <div class="admin-card mt-xxl">
                 <div class="card-header">
                     <div class="card-icon"><svg viewBox="0 0 24 24" fill="none" stroke="#3b82f6" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="4 14 10 14 12 10 16 20 18 14 22 14"/><circle cx="6" cy="6" r="2"/></svg></div>
                     <div class="card-title">Real-time Monitoring <a class="doc-link" href="/api/docs/monitoring" target="_blank" title="Panel documentation">?</a></div>
@@ -404,6 +433,7 @@
 
         <!-- Embeddings Visualization Section -->
         <div id="embeddings-section" class="admin-section hidden">
+            <div id="emb-status-banner" class="emb-status-banner hidden" role="status" aria-live="polite"></div>
             <div class="admin-card" style="padding:0;overflow:hidden">
                 <div class="emb-layout">
                     <!-- Sidebar -->
@@ -879,10 +909,10 @@
             }
         }
 
-        // Graph logic was extracted to js/admin.graph.js?v=1.26.11-9badd8dd
+        // Graph logic was extracted to js/admin.graph.js?v=1.27.2-d7f5ec0e
         // Functions available globally: reloadGraphMermaid, initGraphScopeDefaults, copyMermaidSource, toggleGraphEdit, applyGraphEdit, cancelGraphEdit, refreshDrillCategories, loadDrillInstructions, clearSelections
 
-        <!-- overview functions moved to js/admin.overview.js?v=1.26.11-9badd8dd -->
+        <!-- overview functions moved to js/admin.overview.js?v=1.27.2-d7f5ec0e -->
 
         // Lightweight overview-level maintenance display (optional)
         // Intentionally minimal to avoid blocking overview rendering.
@@ -1067,7 +1097,7 @@
         }
 
         // --- Backup / Restore ---
-        // Extracted to js/admin.maintenance.js?v=1.26.11-9badd8dd
+        // Extracted to js/admin.maintenance.js?v=1.27.2-d7f5ec0e
 
         async function performBackup() {
             try {
@@ -1133,7 +1163,7 @@
         }
 
                 async function loadConfiguration() {
-                    // Primary implementation in js/admin.config.js?v=1.26.11-9badd8dd (loaded via defer).
+                    // Primary implementation in js/admin.config.js?v=1.27.2-d7f5ec0e (loaded via defer).
                     // This inline fallback only fires if the external script failed to load.
                     if (window.__configExternalLoaded) return;
                     try {
@@ -1193,10 +1223,10 @@
                         return false;
                 }
 
-        // Monitoring functions moved to js/admin.monitor.js?v=1.26.11-9badd8dd
+        // Monitoring functions moved to js/admin.monitor.js?v=1.27.2-d7f5ec0e
 
         // ===== Log Viewer =====
-        // Extracted to js/admin.logs.js?v=1.26.11-9badd8dd
+        // Extracted to js/admin.logs.js?v=1.27.2-d7f5ec0e
 
         // ===== Instruction Management =====
         let instructionEditing = null;
@@ -1693,7 +1723,7 @@
             setInterval(fetchResourceTrends, 10000);
         })();
 
-        // Instruction management logic extracted to js/admin.instructions.js?v=1.26.11-9badd8dd
+        // Instruction management logic extracted to js/admin.instructions.js?v=1.27.2-d7f5ec0e
         // Functions exposed globally: loadInstructions, renderInstructionList, editInstruction, saveInstruction, deleteInstruction, etc.
 
         function startAutoRefresh() {

package/dist/dashboard/client/css/admin.css

@@ -1159,6 +1159,36 @@ a.mermaid-link { color: var(--admin-accent); }
     font-size: 12px;
     color: var(--admin-text-dim);
 }
+.emb-status-banner {
+    margin: 0 0 12px 0;
+    padding: 12px 16px;
+    border-radius: 6px;
+    border-left: 4px solid var(--admin-text-dim);
+    background: rgba(255,255,255,0.04);
+    font-size: 13px;
+    line-height: 1.45;
+    color: var(--admin-text);
+}
+.emb-status-banner.hidden { display: none; }
+.emb-status-banner .title {
+    font-weight: 600;
+    margin-bottom: 4px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.emb-status-banner .meta {
+    color: var(--admin-text-dim);
+    font-size: 12px;
+    margin-top: 6px;
+    font-family: var(--mcp-font-mono);
+    word-break: break-all;
+}
+.emb-status-banner.state-ready { border-left-color: var(--admin-success); }
+.emb-status-banner.state-will-download { border-left-color: var(--admin-accent); }
+.emb-status-banner.state-no-embeddings { border-left-color: var(--admin-warn); }
+.emb-status-banner.state-missing,
+.emb-status-banner.state-disabled { border-left-color: var(--admin-danger); }
 .emb-stat {
     margin-bottom: 4px;
     font-size: 13px;
@@ -1736,3 +1766,27 @@ a.mermaid-link { color: var(--admin-accent); }
 #backup-warning-banner {
     animation: rl-fade-in 0.3s ease-out;
 }
+
+
+/* Events panel + nav bubble (added for issue #282 events buffer) */
+.nav-bubble { display:inline-block; min-width:18px; padding:0 6px; margin-left:6px; border-radius:9px; background:var(--admin-warn); color:var(--admin-white); font-size:11px; line-height:18px; text-align:center; vertical-align:middle; }
+.nav-bubble.has-error { background:var(--admin-danger-dark); }
+.events-table { width:100%; border-collapse:collapse; }
+.events-table th, .events-table td { padding:6px 8px; text-align:left; border-bottom:1px solid var(--admin-border); font-size:13px; vertical-align:top; }
+.events-table th { color:var(--admin-text-dim); font-weight:500; }
+.event-badge { display:inline-block; padding:1px 6px; border-radius:3px; font-size:11px; font-weight:600; }
+.event-badge.level-warn { background:var(--admin-warn-dark); color:var(--admin-drill-gold); }
+.event-badge.level-error { background:var(--admin-danger-darker); color:var(--admin-red-bright); }
+.event-row.level-error { background:rgba(220,38,38,0.06); }
+.event-row.level-warn { background:rgba(245,158,11,0.04); }
+.event-detail { font-family:var(--mcp-font-mono); font-size:11px; white-space:pre-wrap; margin-top:3px; }
+.event-ts { white-space:nowrap; color:var(--admin-text-dim); font-family:var(--mcp-font-mono); font-size:12px; }
+.event-row .event-msg { cursor: pointer; }
+.event-row .event-detail { display: none; max-height: 240px; overflow: auto; }
+.event-row.expanded .event-detail { display: block; }
+.event-row .toggle-caret { display:inline-block; width:14px; color:var(--admin-text-dim); transition: transform 0.15s; }
+.event-row.expanded .toggle-caret { transform: rotate(90deg); }
+.events-pager { display:flex; align-items:center; gap:12px; padding:8px 4px; }
+.events-pager.hidden { display:none; }
+.events-search { min-width: 180px; }
+.events-table tr.event-row mark { background: var(--admin-drill-gold); color: var(--admin-text); padding: 0 1px; border-radius: 2px; }

package/dist/dashboard/client/js/admin.config.js

@@ -90,10 +90,8 @@
                 + '<div class="form-group"><label class="form-label">Enable Mutation</label>'
                 + '<select class="form-input" id="cfg-mutation"><option value="1"' + (cfg.serverSettings.enableMutation ? ' selected' : '') + '>Enabled</option>'
                 + '<option value="0"' + (!cfg.serverSettings.enableMutation ? ' selected' : '') + '>Disabled</option></select></div>'
-                + '<div class="form-group"><label class="form-label">Rate Limit Window (ms)</label>'
-                + '<input class="form-input" type="number" id="cfg-windowMs" value="' + cfg.serverSettings.rateLimit.windowMs + '" /></div>'
-                + '<div class="form-group"><label class="form-label">Rate Limit Max Requests</label>'
-                + '<input class="form-input" type="number" id="cfg-maxRequests" value="' + cfg.serverSettings.rateLimit.maxRequests + '" /></div>'
+                + '<div class="form-group"><label class="form-label">Rate Limit (req/min, 0 = off)</label>'
+                + '<input class="form-input" type="number" min="0" id="cfg-rateLimitPerMinute" value="' + (cfg.serverSettings.rateLimit && cfg.serverSettings.rateLimit.perMinute != null ? cfg.serverSettings.rateLimit.perMinute : 0) + '" /></div>'
                 + '</div>'
                 + '<div class="cfg-save-row"><button class="action-btn" type="submit">💾 Save Config</button></div>'
                 + '</form>'
@@ -173,8 +171,7 @@
                 enableVerboseLogging: document.getElementById('cfg-verbose').value === '1',
                 enableMutation: document.getElementById('cfg-mutation').value === '1',
                 rateLimit: {
-                    windowMs: parseInt(document.getElementById('cfg-windowMs').value),
-                    maxRequests: parseInt(document.getElementById('cfg-maxRequests').value)
+                    perMinute: parseInt(document.getElementById('cfg-rateLimitPerMinute').value) || 0
                 }
             },
             featureFlags: featureFlags

package/dist/dashboard/client/js/admin.embeddings.js

@@ -378,8 +378,61 @@
   var origShowSection = window.showSection;
   window.showSection = function (name) {
     if (origShowSection) origShowSection(name);
-    if (name === 'embeddings' && !embData) {
-      setTimeout(init, 50);
+    if (name === 'embeddings') {
+      window.loadEmbeddingsStatus();
+      if (!embData) setTimeout(init, 50);
+    }
+  };
+
+  function escapeHtml(s) {
+    if (s == null) return '';
+    return String(s)
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+  }
+
+  function renderStatusBanner(status) {
+    var banner = document.getElementById('emb-status-banner');
+    if (!banner) return;
+    banner.className = 'emb-status-banner';
+    if (!status || status.success === false) {
+      banner.classList.add('hidden');
+      return;
+    }
+    var state = status.state || 'unknown';
+    var titleText = '', icon = '';
+    if (state === 'disabled') { icon = '🚫'; titleText = 'Semantic embeddings are disabled'; }
+    else if (state === 'missing') { icon = '⛔'; titleText = 'Model not available — compute will fail'; }
+    else if (state === 'will-download') { icon = '⬇️'; titleText = 'Model will download on first compute'; }
+    else if (state === 'no-embeddings') { icon = '⚠️'; titleText = 'No embeddings computed yet'; }
+    else if (state === 'ready') { icon = '✅'; titleText = 'Embeddings ready'; }
+    else { icon = 'ℹ️'; titleText = 'Embeddings status'; }
+    banner.classList.add('state-' + state);
+    var parts = [];
+    parts.push('<div class="title">' + icon + ' <span>' + escapeHtml(titleText) + '</span></div>');
+    if (status.message) parts.push('<div>' + escapeHtml(status.message) + '</div>');
+    var meta = [];
+    if (status.model) meta.push('model=' + status.model);
+    if (status.device) meta.push('device=' + status.device);
+    if (typeof status.localOnly === 'boolean') meta.push('localOnly=' + status.localOnly);
+    if (typeof status.modelCached === 'boolean') meta.push('modelCached=' + status.modelCached);
+    if (typeof status.embeddingsCount === 'number') meta.push('embeddings=' + status.embeddingsCount);
+    if (status.cacheDir) meta.push('cacheDir=' + status.cacheDir);
+    if (status.embeddingPath) meta.push('embeddingPath=' + status.embeddingPath);
+    if (meta.length) parts.push('<div class="meta">' + escapeHtml(meta.join(' · ')) + '</div>');
+    banner.innerHTML = parts.join('');
+    banner.classList.remove('hidden');
+  }
+
+  window.loadEmbeddingsStatus = async function loadEmbeddingsStatus() {
+    try {
+      var res = await adminAuth.adminFetch('/api/embeddings/status');
+      if (!res.ok) { renderStatusBanner(null); return; }
+      var data = await res.json();
+      renderStatusBanner(data);
+    } catch (_err) {
+      void _err;
+      renderStatusBanner(null);
     }
   };
 
@@ -391,12 +444,18 @@
       var res = await adminAuth.adminFetch('/api/embeddings/compute', { method: 'POST', headers: { 'Content-Type': 'application/json' } });
       if (!res.ok) {
         var err = await res.json().catch(function () { return {}; });
-        if (statusEl) statusEl.textContent = 'Error: ' + (err.error || res.statusText) + (err.hint ? ' — ' + err.hint : '');
+        var detail = err.error || res.statusText;
+        if (err.hint) detail += ' — ' + err.hint;
+        else if (err.message) detail += ' — ' + err.message;
+        if (statusEl) statusEl.textContent = 'Error: ' + detail;
+        // Refresh banner so user sees the actionable state machine.
+        window.loadEmbeddingsStatus();
         return;
       }
       var result = await res.json();
       if (statusEl) statusEl.textContent = 'Computed ' + result.count + ' embeddings (' + result.model + ', ' + result.elapsedMs + 'ms). Loading visualization…';
-      // Auto-load the projection after compute
+      // Auto-load the projection + refresh banner
+      window.loadEmbeddingsStatus();
       await window.loadEmbeddings();
     } catch (e) {
       if (statusEl) statusEl.textContent = 'Compute failed: ' + e.message;