@jagilber-org/index-server 1.28.9 → 1.28.19

package/CHANGELOG.md

@@ -6,6 +6,114 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 
 ## [Unreleased]
 
+## [1.28.19] - 2026-05-11
+
+### Added
+
+- ci: windows-smoke timeout bump
+
+## [1.28.18] - 2026-05-11
+
+### Added
+
+- fix(test): npmPackReadiness allowlist for setup-wizard-paths.mjs
+
+## [1.28.17] - 2026-05-10
+
+### Added
+
+- fix(ci): skip integrity-pre-push hook in CI to avoid 'files modified by hook' false-positive
+
+## [1.28.16] - 2026-05-10
+
+### Added
+
+- fix(ci): correct precommit.yml YAML indentation breaking workflow file
+
+## [1.28.15] - 2026-05-10
+
+### Added
+
+- fix: ship setup-wizard-paths.mjs in npm pack; fix governance-hash workflow checkout collision; remove unused buildZIndexEntry/RECORD_SCHEMA
+
+## [1.28.14] - 2026-05-10
+
+### Fixed
+
+- **SQLite restore leak: orphaned JSON files after backup restore**: `AdminPanel.restoreBackup`
+  now deletes per-instruction `.json` files from `instructionsDir` after a zero-error
+  SQLite ingest, preventing stale file accumulation and `ensureLoaded()` auto-migration
+  latch retriggering. Loader-generated metadata (`_manifest.json`, `_skipped.json`) is
+  preserved. JSON backend behavior is unchanged.
+- **SQLite embedding leak: `embeddings.json` written in sqlite mode**: `sqliteVecEnabled`
+  now auto-derives `true` when `INDEX_SERVER_STORAGE_BACKEND=sqlite` and the flag is
+  unset. Explicit `INDEX_SERVER_SQLITE_VEC_ENABLED=0` opts out. `ApiRoutes` wires
+  `SqliteEmbeddingStore` for sqlite backends with `logWarn` fallback to JSON if the
+  native extension fails to load.
+- **Embedding compute split-brain**: the dashboard compute endpoint now threads the
+  derived `SqliteEmbeddingStore` through to `getInstructionEmbeddings`, so reads and
+  writes use the same store in sqlite mode.
+- **Embeddings tab false error banner**: the "not configured" banner is now hidden when
+  the embedding state is `ready`, preventing a misleading error when the LLM is working.
+
+### Added
+
+- **`feedback_manage` MCP dispatcher**: adds a single feedback management tool
+  with `submit`, `list`, `get`, `update`, `delete`, and `stats` actions while
+  keeping `feedback_submit` as the standalone submit alias. Legacy standalone
+  feedback management tool names remain removed.
+- **PPID watchdog opt-out** (`INDEX_SERVER_DISABLE_PPID_WATCHDOG`): disables the
+  parent-process watchdog for dev sandbox launchers that spawn through a transient shell.
+- **Dashboard path reveal**: clickable paths in the build metadata panel open the
+  instructions, SQLite, or backups directory in the OS file manager (allowlist-gated).
+- **`/api/status/sqlite-reset`**: exposes sqlite backend flag, vec store status, and
+  embedding file presence for dashboard diagnostics.
+
+### Changed
+
+- **`dev-server.ps1`**: removed 4 env vars that duplicated compile-time defaults
+  (`SQLITE_WAL`, `SQLITE_MIGRATE_ON_START`, `DASHBOARD_HOST`, `SEMANTIC_DEVICE`);
+  added `INDEX_SERVER_DISABLE_PPID_WATCHDOG=1` for transient-shell spawning.
+
+### Added
+
+- **Canonical seed `002-content-model`**: a third bootstrap-tier seed derived
+  at module-load time from `schemas/instruction.schema.json`. Surfaces the
+  required-field set, the `contentType` decision matrix
+  (`agent|skill|instruction|prompt|workflow|knowledge|template|integration`), and a pointer to
+  the live `index_schema` MCP tool — so search-first agents that hit the index
+  before reading the schema get the same conceptual model the schema enforces.
+  Generated by a pure function (`buildContentModelSeed`) with `instruction.schema.json`
+  as the single source of truth; a drift trip-wire spec
+  (`src/tests/contentModelSeed.spec.ts`) asserts every required field and every
+  `contentType` enum member appears in the rendered body.
+- **Canonical seed `003-content-types`**: a schema-derived bootstrap seed that
+  lists the canonical eight-value `contentType` taxonomy.
+
+### Changed
+
+- **Instruction content taxonomy**: bumped instruction schema version to v6 and
+  adopted the canonical `agent|skill|instruction|prompt|workflow|knowledge|template|integration`
+  enum across schema, registry, validation, search, bootstrap seeds, generated
+  schemas, and docs. Removed write/load normalization for removed values; invalid
+  submitted or persisted values now follow existing validation rejection paths.
+
+## [1.28.13] - 2026-05-08
+
+### Fixed
+
+- **Release workflow: transient git-clone failures in `Publish-ToMirror.ps1`**: the public-mirror clone step now retries (3 attempts, exponential backoff: 5s, 10s) on transient Windows networking errors (`getaddrinfo() thread failed to start`, `Could not resolve host`, connection resets, RPC failures, 5xx responses, etc.) before giving up. The PR-branch push retries the same way. Previously a single transient DNS hiccup would abort `Invoke-ReleaseWorkflow.ps1 -CreatePR` mid-flight and force manual recovery.
+
+## [1.28.12] - 2026-05-07
+
+### Fixed
+
+- **Dashboard `/api/scripts/:name` 404**: client wrapper scripts (`index-server-client.ps1`, `index-server-client.sh`) are now packaged in the npm tarball and the route resolves them from the installed package directory instead of `process.cwd()`. Previously every install returned `Script file not found on disk`.
+
+### Added
+
+- **Embeddings panel — Clear Cache button + smarter Compute**: new `POST /api/embeddings/reset` endpoint clears the cached embeddings (works for both JSON and SQLite stores). The Compute button now pre-checks status and: warns when the model will download (~25MB), short-circuits when embeddings are already up to date with a confirm prompt, and surfaces an honest `cacheHit` / `computed` / `reused` summary instead of always reporting "Computed N embeddings". The old `Reset` button was renamed to `Reset View` to clarify that it only resets pan/zoom.
+
 ## [1.28.2] - 2026-05-06
 
 ### Added
@@ -29,7 +137,7 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 - **Publish scripts**: restored root-level entrypoints for `New-CleanRoomCopy.ps1`, `Publish-ToMirror.ps1`, and `publish-direct-to-remote.cjs` after the scripts reorganization so documented/template paths continue to work without introducing alternate release workflow names.
 - **Public publish/security gates**: clean-room publish now keeps ambient exact env-value leak detection active, GitHub Action scanner uploads fail visibly instead of being hidden, ggshield quota exhaustion fails closed, and internal release branch/tag verification compares exact local/remote SHAs.
 - **Tool classification docs**: clarified that registry `stable` vs `mutation` is a visibility/gating contract, so `feedback_submit` remains stable/core while still persisting feedback and audit entries.
-- **Instruction content type migration**: bumped instruction schema version to v5 and added a compatibility path mapping legacy `contentType: "chat-session"` records and writes to `workflow`, preserving workflow/runbook semantics instead of falling back to `instruction`.
+- **Instruction content type migration**: bumped instruction schema version to v5 and mapped the former conversation-oriented content type to `workflow`, preserving workflow/runbook semantics instead of falling back to `instruction`.
 
 ### Fixed
 

package/CONTRIBUTING.md

@@ -28,6 +28,10 @@ Use feature branches. Submit PRs to `main`.
 
 Fill out the PR template completely before requesting review.
 
+### Agent PR Preflight
+
+Agents MUST complete the mandatory pre-PR checklist in [`.instructions/local/agent-pr-preflight.md`](.instructions/local/agent-pr-preflight.md) before opening a pull request, handing a branch to a coordinator, or reporting a change as PR-ready. The checklist covers `npm test`, `npm run typecheck`, `npm run lint`, `pre-commit run --all-files`, `git diff --check`, and staged-diff review for unintended changes.
+
 ### Mandatory AI-Generated Code/Test Review
 
 If any code or tests in the PR were generated or materially edited by an AI agent, reviewers MUST confirm all of the following before merge:
@@ -117,6 +121,15 @@ Critical or actively-exploited vulnerabilities may be merged with **zero pre-mer
 
 If the post-merge audit reveals problems, a follow-up fix must be prioritized immediately. Abuse of this policy to bypass review for non-critical changes will be treated as a process violation.
 
+## Shared Instructions
+
+This project maintains shared instruction files in `.instructions/shared/` that define reusable patterns for security hooks, git workflow, observability, agent attestation, and more. Review these when contributing changes to the areas they cover:
+
+- **Security**: `repository-security-hooks.md`, `adopter-hook-patterns.md`, `public-mirror-guard.md`
+- **Workflow**: `git-workflow.md`, `template-adoption-workflow.md`, `mirrored-release-workflow.md`
+- **Analysis**: `language-ecosystem-patterns.md`, `codeql-configuration-patterns.md`, `iac-patterns.md`
+- **Operations**: `observability-logging.md`, `agent-attestation.md`, `index-server-bootstrap.md`
+
 ## Code Style
 
 Respect existing formatting. Run any lint scripts if present.

package/README.md

@@ -29,27 +29,23 @@ winget install nodejs
 
 ## Quick Start Options
 
-### Option A: Global install via `npm` (recommended)
+### Option A: MCP-native via `npx` (recommended)
 
-Install once and run from anywhere. Choose this when you want a stable `index-server` command on your `PATH` with no per-invocation download.
+Run the latest published package without cloning the repo. Choose this when you want the fastest local start and already have Node.js installed.
 
-```bash
-npm install -g @jagilber-org/index-server
-```
-
-Then launch the setup wizard to generate the right MCP client config for VS Code, Copilot CLI, or Claude Desktop:
+Start with the setup wizard so it can generate the right MCP client config for VS Code, Copilot CLI, or Claude Desktop:
 
 ```bash
-index-server --setup
+npx -y @jagilber-org/index-server@latest --setup
 ```
 
 To launch the server directly without the wizard:
 
 ```bash
-index-server --dashboard
+npx -y @jagilber-org/index-server@latest --dashboard
 ```
 
-> **No-install alternative:** `npx -y @jagilber-org/index-server@latest --setup` works too (resolves from npmjs.org). Use it for a one-shot try; prefer `-g` for routine use. The GitHub Packages mirror requires authentication, so `npx` against `npm.pkg.github.com` needs a per-scope `.npmrc` plus a `GITHUB_TOKEN` with `read:packages`.
+> **Prefer a stable `index-server` command on `PATH`?** Install globally instead: `npm install -g @jagilber-org/index-server`, then run `index-server --setup` / `index-server --dashboard`. The GitHub Packages mirror requires authentication, so `npx` against `npm.pkg.github.com` needs a per-scope `.npmrc` plus a `GITHUB_TOKEN` with `read:packages`.
 
 > **Upgrading or hitting "unsupported INDEX_SERVER key" / "Cannot find module" errors after install?** See [Upgrading and Uninstalling](docs/quickstart.md#upgrading-and-uninstalling) for the clean-uninstall steps that clear stale non-global installs.
 
@@ -59,7 +55,7 @@ Generate a self-signed TLS cert+key in one command:
 
 ```bash
 # Generate at ~/.index-server/certs/, then start with HTTPS automatically
-index-server --init-cert --start --dashboard
+npx -y @jagilber-org/index-server@latest --init-cert --start --dashboard
 ```
 
 `--init-cert` alone exits after generation. `--init-cert --start` continues
@@ -73,7 +69,7 @@ reference, security notes, and troubleshooting.
 
 ### Option B: VS Code MCP configuration
 
-Use VS Code's built-in MCP support with `.vscode/mcp.json` or your global `mcp.json`. You can add the server entry manually or run `index-server --setup` (after `npm install -g @jagilber-org/index-server`) to generate the config for you.
+Use VS Code's built-in MCP support with `.vscode/mcp.json` or your global `mcp.json`. You can add the server entry manually or run `npx -y @jagilber-org/index-server@latest --setup` to generate the config for you.
 
 ### Option C: Docker
 
@@ -183,7 +179,7 @@ See [MCP Configuration Guide](docs/mcp_configuration.md) for advanced patterns,
 ### Verify
 
 - Server appears in your MCP client's server list
-- Run `tools/list` to see 40+ available tools
+- Run `tools/list` to see 50+ available tools
 - Run `prompts/list` to discover setup/config/verification prompts
 - Run `resources/list` to discover quickstart and configuration guides
 - Dashboard (if enabled) at `http://localhost:8787`
@@ -260,7 +256,7 @@ See [dashboard.md](docs/dashboard.md) for full details. REST client scripts (`sc
 ## Key Features
 
 - **MCP protocol compliance** — Full JSON-RPC 2.0 over stdio with schema validation
-- **40+ tools** for search, CRUD, governance, analytics, messaging, and feedback
+- **50+ tools** for search, CRUD, governance, analytics, messaging, and feedback
 - **Semantic search** — Optional embedding-based similarity search (HuggingFace models)
 - **Bootstrap security** — Mutations gated until human confirmation on fresh installs
 - **Cross-repo knowledge promotion** — Validate locally, then promote proven patterns to the shared catalog

package/dist/config/featureConfig.js

@@ -120,7 +120,10 @@ function parseStorageConfig() {
         sqlitePath: (0, configUtils_1.toAbsolute)(process.env.INDEX_SERVER_SQLITE_PATH, path_1.default.join(configUtils_1.CWD, dirConstants_1.DIR.DATA_SQLITE)),
         sqliteWal: (0, envUtils_1.parseBooleanEnv)(process.env.INDEX_SERVER_SQLITE_WAL, true),
         sqliteMigrateOnStart: (0, envUtils_1.parseBooleanEnv)(process.env.INDEX_SERVER_SQLITE_MIGRATE_ON_START, true),
-        sqliteVecEnabled: (0, envUtils_1.parseBooleanEnv)(process.env.INDEX_SERVER_SQLITE_VEC_ENABLED, false),
+        sqliteVecEnabled: (0, envUtils_1.parseBooleanEnv)(process.env.INDEX_SERVER_SQLITE_VEC_ENABLED, 
+        // Default to enabled when the storage backend is already sqlite;
+        // factory.ts falls back to JSON automatically if the native extension fails.
+        backend === 'sqlite'),
         sqliteVecPath: process.env.INDEX_SERVER_SQLITE_VEC_PATH || '',
     };
 }

package/dist/dashboard/client/admin.html

@@ -1,30 +1,30 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta name="dashboard-build-version" content="1.28.9-0009101e">
+    <meta name="dashboard-build-version" content="1.28.19-52109005">
     <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.28.9-0009101e">
-    <script defer src="js/admin.utils.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.auth.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.overview.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.sessions.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.monitor.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.events.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.graph.js?v=1.28.9-0009101e"></script>
+    <link rel="stylesheet" href="css/admin.css?v=1.28.19-52109005">
+    <script defer src="js/admin.utils.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.auth.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.overview.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.sessions.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.monitor.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.events.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.graph.js?v=1.28.19-52109005"></script>
     <script defer src="js/marked.umd.js"></script>
-    <script defer src="js/admin.instructions.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.logs.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.maintenance.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.config.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.performance.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.instances.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.embeddings.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.messaging.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.sqlite.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.boot.js?v=1.28.9-0009101e"></script>
-    <script defer src="js/admin.feedback.js?v=1.28.9-0009101e"></script>
+    <script defer src="js/admin.instructions.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.logs.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.maintenance.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.config.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.performance.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.instances.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.embeddings.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.messaging.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.sqlite.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.boot.js?v=1.28.19-52109005"></script>
+    <script defer src="js/admin.feedback.js?v=1.28.19-52109005"></script>
 </head>
 <body>
     <div class="admin-container admin-root">
@@ -443,7 +443,8 @@
                             <div class="emb-controls">
                                 <button class="emb-btn" data-emb-action="compute">Compute</button>
                                 <button class="emb-btn" data-emb-action="load">Load</button>
-                                <button class="emb-btn" data-emb-action="reset">Reset</button>
+                                <button class="emb-btn" data-emb-action="reset" title="Reset pan/zoom view">Reset View</button>
+                                <button class="emb-btn" data-emb-action="clear" title="Clear cached embeddings (forces recompute on next Compute)">Clear Cache</button>
                                 <button class="emb-btn" id="emb-norm-btn" data-emb-action="norm">Norm</button>
                             </div>
                             <span id="emb-status" class="emb-status-text"></span>
@@ -909,10 +910,10 @@
             }
         }
 
-        // Graph logic was extracted to js/admin.graph.js?v=1.28.9-0009101e
+        // Graph logic was extracted to js/admin.graph.js?v=1.28.19-52109005
         // Functions available globally: reloadGraphMermaid, initGraphScopeDefaults, copyMermaidSource, toggleGraphEdit, applyGraphEdit, cancelGraphEdit, refreshDrillCategories, loadDrillInstructions, clearSelections
 
-        <!-- overview functions moved to js/admin.overview.js?v=1.28.9-0009101e -->
+        <!-- overview functions moved to js/admin.overview.js?v=1.28.19-52109005 -->
 
         // Lightweight overview-level maintenance display (optional)
         // Intentionally minimal to avoid blocking overview rendering.
@@ -1097,7 +1098,7 @@
         }
 
         // --- Backup / Restore ---
-        // Extracted to js/admin.maintenance.js?v=1.28.9-0009101e
+        // Extracted to js/admin.maintenance.js?v=1.28.19-52109005
 
         async function performBackup() {
             try {
@@ -1163,7 +1164,7 @@
         }
 
                 async function loadConfiguration() {
-                    // Primary implementation in js/admin.config.js?v=1.28.9-0009101e (loaded via defer).
+                    // Primary implementation in js/admin.config.js?v=1.28.19-52109005 (loaded via defer).
                     // This inline fallback only fires if the external script failed to load.
                     if (window.__configExternalLoaded) return;
                     try {
@@ -1223,10 +1224,10 @@
                         return false;
                 }
 
-        // Monitoring functions moved to js/admin.monitor.js?v=1.28.9-0009101e
+        // Monitoring functions moved to js/admin.monitor.js?v=1.28.19-52109005
 
         // ===== Log Viewer =====
-        // Extracted to js/admin.logs.js?v=1.28.9-0009101e
+        // Extracted to js/admin.logs.js?v=1.28.19-52109005
 
         // ===== Instruction Management =====
         let instructionEditing = null;
@@ -1651,7 +1652,7 @@
                 categories: ['general'],
                 primaryCategory: 'general',
                 reviewIntervalDays: 180,
-                schemaVersion: '5',
+                schemaVersion: '6',
                 description: 'Describe purpose and scope.',
                 createdAt: now,
                 updatedAt: now
@@ -1723,7 +1724,7 @@
             setInterval(fetchResourceTrends, 10000);
         })();
 
-        // Instruction management logic extracted to js/admin.instructions.js?v=1.28.9-0009101e
+        // Instruction management logic extracted to js/admin.instructions.js?v=1.28.19-52109005
         // Functions exposed globally: loadInstructions, renderInstructionList, editInstruction, saveInstruction, deleteInstruction, etc.
 
         function startAutoRefresh() {
@@ -1761,6 +1762,45 @@
                         el.appendChild(buildBadge);
                     }
                     el.append(` • Built ${bt}`);
+                    if(j.paths){
+                        const p = j.paths;
+                        const addPath = (label, value, key) => {
+                            if(!value) return;
+                            const wrap = document.createElement('span');
+                            wrap.className = 'build-path';
+                            wrap.style.marginLeft = '0.75em';
+                            wrap.append(`${label}: `);
+                            const code = document.createElement('code');
+                            code.textContent = String(value);
+                            code.title = `Click to open ${value}`;
+                            code.style.cursor = 'pointer';
+                            code.style.textDecoration = 'underline dotted';
+                            code.addEventListener('click', async (ev) => {
+                                ev.preventDefault();
+                                code.style.opacity = '0.5';
+                                try {
+                                    const r = await fetch('/api/system/reveal-path', {
+                                        method: 'POST',
+                                        headers: { 'Content-Type': 'application/json' },
+                                        body: JSON.stringify({ key })
+                                    });
+                                    if (!r.ok) {
+                                        const j2 = await r.json().catch(() => ({}));
+                                        showError(`Open folder failed: ${j2.error || r.statusText}`);
+                                    }
+                                } catch (e) {
+                                    showError(`Open folder failed: ${e && e.message ? e.message : e}`);
+                                } finally {
+                                    code.style.opacity = '1';
+                                }
+                            });
+                            wrap.appendChild(code);
+                            el.appendChild(wrap);
+                        };
+                        addPath('Instructions', p.instructionsDir, 'instructions');
+                        if(p.storageBackend === 'sqlite') addPath('SQLite', p.sqlitePath, 'sqlite');
+                        addPath('Backups', p.backupsDir, 'backups');
+                    }
                 }
             } catch { const el = document.getElementById('buildMeta'); if(el) el.textContent='Build metadata unavailable'; }
         })();

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

@@ -400,12 +400,19 @@
       return;
     }
     var state = status.state || 'unknown';
+    // Suppress the informational banner once the model is cached and embeddings
+    // are ready — at that point there is nothing actionable to communicate, and
+    // the meta line (model/device/embeddings count) is already visible in the
+    // STATISTICS panel below.
+    if (state === 'ready') {
+      banner.classList.add('hidden');
+      return;
+    }
     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 = [];
@@ -436,10 +443,76 @@
     }
   };
 
+  window.clearEmbeddingsCache = async function clearEmbeddingsCache() {
+    var statusEl = document.getElementById('emb-status');
+    var ok = window.confirm(
+      'Clear cached embeddings?\n\nNext Compute will rebuild them and download the embedding model if not already cached.'
+    );
+    if (!ok) return;
+    try {
+      if (statusEl) statusEl.textContent = 'Clearing embeddings cache…';
+      var res = await adminAuth.adminFetch('/api/embeddings/reset', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ clearModel: false }),
+      });
+      var data = await res.json().catch(function () { return {}; });
+      if (!res.ok) {
+        if (statusEl) statusEl.textContent = 'Clear failed: ' + (data.error || res.statusText);
+        return;
+      }
+      if (statusEl) statusEl.textContent = 'Cleared (embeddingsCleared=' + !!data.embeddingsCleared + '). Click Compute to rebuild.';
+      window.loadEmbeddingsStatus();
+    } catch (e) {
+      if (statusEl) statusEl.textContent = 'Clear failed: ' + e.message;
+    }
+  };
+
   window.computeEmbeddings = async function computeEmbeddings() {
     if (!canvas) init();
     var statusEl = document.getElementById('emb-status');
-    if (statusEl) statusEl.textContent = 'Computing embeddings (model download on first run)…';
+
+    // Pre-flight: fetch status so we can give the user actionable info.
+    var pre = null;
+    try {
+      var sres = await adminAuth.adminFetch('/api/embeddings/status');
+      if (sres.ok) pre = await sres.json();
+    } catch (_e) { void _e; }
+
+    if (pre && pre.success) {
+      if (pre.state === 'disabled') {
+        if (statusEl) statusEl.textContent = 'Embeddings are disabled. Set INDEX_SERVER_SEMANTIC_ENABLED=1 and restart.';
+        return;
+      }
+      if (pre.state === 'missing') {
+        if (statusEl) statusEl.textContent = 'Model is not cached and remote downloads are disabled (localOnly=true). Set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=0 and restart, or pre-stage the model.';
+        return;
+      }
+      if (pre.state === 'ready') {
+        var ok = window.confirm(
+          'Embeddings are already up to date (' + (pre.embeddingsCount || 0) + ' cached, model=' + (pre.model || '?') + ').\n\nCompute will be a no-op unless the index has changed.\n\nProceed anyway?'
+        );
+        if (!ok) {
+          if (statusEl) statusEl.textContent = 'Cancelled. Use "Clear Cache" to force a full rebuild.';
+          return;
+        }
+      }
+      if (pre.state === 'will-download') {
+        var ok2 = window.confirm(
+          'Model "' + (pre.model || '?') + '" is not cached. Compute will download ~25MB to:\n\n' + (pre.cacheDir || '?') + '\n\nProceed?'
+        );
+        if (!ok2) {
+          if (statusEl) statusEl.textContent = 'Cancelled.';
+          return;
+        }
+        if (statusEl) statusEl.textContent = 'Downloading model + computing embeddings (this may take 30-60s)…';
+      } else if (statusEl) {
+        statusEl.textContent = 'Computing embeddings…';
+      }
+    } else if (statusEl) {
+      statusEl.textContent = 'Computing embeddings (model download on first run)…';
+    }
+
     try {
       var res = await adminAuth.adminFetch('/api/embeddings/compute', { method: 'POST', headers: { 'Content-Type': 'application/json' } });
       if (!res.ok) {
@@ -448,13 +521,31 @@
         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 + refresh banner
+      if (statusEl) {
+        if (result.cacheHit) {
+          statusEl.textContent = 'Cache hit: ' + result.count + ' embeddings already current (no work done, ' + result.elapsedMs + 'ms). Use "Clear Cache" to force a rebuild.';
+        } else {
+          var summary = 'Computed ' + (result.computed != null ? result.computed : result.count) + ' new'
+            + (result.reused != null && result.reused > 0 ? ' (' + result.reused + ' reused)' : '')
+            + ' · model=' + result.model + ' · ' + result.elapsedMs + 'ms. Loading visualization…';
+          statusEl.textContent = summary;
+        }
+      }
+      // Follow-up: if the model was just downloaded (pre-state was will-download)
+      // and downloads are still allowed, suggest enabling local-only mode to
+      // prevent further network access. The flag requires a restart to take
+      // effect, so we just surface the recommendation.
+      if (pre && pre.state === 'will-download' && pre.localOnly === false && !result.cacheHit) {
+        setTimeout(function () {
+          window.alert(
+            'Model is now cached locally.\n\nRecommended: set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=1 and restart the server to disable further remote model downloads (offline mode).'
+          );
+        }, 50);
+      }
       window.loadEmbeddingsStatus();
       await window.loadEmbeddings();
     } catch (e) {
@@ -472,6 +563,7 @@
       if (action === 'compute') window.computeEmbeddings();
       else if (action === 'load') window.loadEmbeddings();
       else if (action === 'reset') window.resetEmbeddingsView();
+      else if (action === 'clear') window.clearEmbeddingsCache();
       else if (action === 'norm') window.toggleNormColor();
     });
   }

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

@@ -448,7 +448,7 @@
 
   function formatInstructionJson(){ const ta = document.getElementById('instruction-content'); if(!ta) return; try{ const parsed = JSON.parse(ta.value); ta.value = JSON.stringify(parsed, null, 2); updateInstructionEditorDiagnostics(); } catch { globals.showError && globals.showError('Cannot format: invalid JSON'); } }
 
-  function applyInstructionTemplate(){ const ta = document.getElementById('instruction-content'); if(!ta) return; if(ta.value.trim() && !confirm('Replace current content with template?')) return; const now = new Date().toISOString(); const template = { id:'sample-instruction', title:'Sample Instruction', body:'Detailed instruction content here.\nAdd multi-line guidance and steps.', contentType:'instruction', priority:50, audience:'all', requirement:'optional', categories:['general'], primaryCategory:'general', schemaVersion:'5', status:'draft', owner:'you@example.com', version:'1.0.0', reviewIntervalDays:180, semanticSummary:'Brief summary of what this instruction covers.', createdAt: now, updatedAt: now }; ta.value = JSON.stringify(template, null, 2); updateInstructionEditorDiagnostics(); }
+  function applyInstructionTemplate(){ const ta = document.getElementById('instruction-content'); if(!ta) return; if(ta.value.trim() && !confirm('Replace current content with template?')) return; const now = new Date().toISOString(); const template = { id:'sample-instruction', title:'Sample Instruction', body:'Detailed instruction content here.\nAdd multi-line guidance and steps.', contentType:'instruction', priority:50, audience:'all', requirement:'optional', categories:['general'], primaryCategory:'general', schemaVersion:'6', status:'draft', owner:'you@example.com', version:'1.0.0', reviewIntervalDays:180, semanticSummary:'Brief summary of what this instruction covers.', createdAt: now, updatedAt: now }; ta.value = JSON.stringify(template, null, 2); updateInstructionEditorDiagnostics(); }
 
   async function deleteInstruction(name) {
     if (!confirm('Delete instruction ' + name + '?')) return;

package/dist/dashboard/server/AdminPanel.js

@@ -308,6 +308,44 @@ class AdminPanel {
                         ?? path_1.default.join(process.cwd(), 'data', 'index.db');
                     const mr = (0, migrationEngine_1.migrateJsonToSqlite)(instructionsDir, dbPath);
                     sqliteIngest = { migrated: mr.migrated, errors: mr.errors.length };
+                    // RCA 2026-05-08: in sqlite mode the .db is the source of truth, so
+                    // the per-instruction JSON files extracted from the zip are dead
+                    // weight after a clean ingest. Leaving them on disk caused the
+                    // ensureLoaded() auto-migration latch to detect jsonFiles >
+                    // result.entries forever and bloated `instructions/` to 700+ files.
+                    // Only clean up when ingest had zero errors — preserve files for
+                    // operator triage when something failed.
+                    if (mr.errors.length === 0) {
+                        let cleaned = 0;
+                        try {
+                            for (const f of fs_1.default.readdirSync(instructionsDir)) {
+                                // Keep loader-generated metadata (_manifest.json, _skipped.json)
+                                // and anything not a .json file.
+                                if (!f.toLowerCase().endsWith('.json'))
+                                    continue;
+                                if (f.startsWith('_'))
+                                    continue;
+                                try {
+                                    fs_1.default.unlinkSync(path_1.default.join(instructionsDir, f));
+                                    cleaned++;
+                                }
+                                catch (unlinkErr) {
+                                    (0, logger_1.logWarn)('[admin] post-restore sqlite cleanup unlink failed', {
+                                        backupId: safeId, file: f,
+                                        error: unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr),
+                                    });
+                                }
+                            }
+                            sqliteIngest.cleanedJson = cleaned;
+                            (0, logger_1.logInfo)('[admin] post-restore sqlite cleanup', { backupId: safeId, cleanedJson: cleaned });
+                        }
+                        catch (cleanupErr) {
+                            (0, logger_1.logWarn)('[admin] post-restore sqlite cleanup scan failed', {
+                                backupId: safeId,
+                                error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr),
+                            });
+                        }
+                    }
                     (0, logger_1.logInfo)('[admin] post-restore sqlite re-ingest', { backupId: safeId, ...sqliteIngest });
                 }
                 catch (err) {

package/dist/dashboard/server/ApiRoutes.js

@@ -49,6 +49,7 @@ const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
 const index_js_1 = require("./routes/index.js");
 const ensureLoadedMiddleware_js_1 = require("./middleware/ensureLoadedMiddleware.js");
 const logger_js_1 = require("../../services/logger.js");
+const factory_js_1 = require("../../services/storage/factory.js");
 /**
  * Path prefixes whose endpoints are *unconditionally* exempt from the dashboard
  * HTTP rate limiter. These are bulk-shaped, operator-driven operations
@@ -200,7 +201,19 @@ function createApiRoutes(options = {}) {
     router.use((0, index_js_1.createSyntheticRoutes)(metricsCollector));
     router.use((0, index_js_1.createInstancesRoutes)());
     router.use((0, index_js_1.createToolsRoutes)());
-    router.use((0, index_js_1.createEmbeddingsRoutes)());
+    let embeddingStore;
+    {
+        const storageConfig = (0, runtimeConfig_js_1.getRuntimeConfig)().storage;
+        if ((storageConfig?.backend ?? 'json') === 'sqlite' && storageConfig?.sqliteVecEnabled !== false) {
+            try {
+                embeddingStore = (0, factory_js_1.createEmbeddingStore)('sqlite');
+            }
+            catch (err) {
+                (0, logger_js_1.logWarn)(`[api] sqlite-vec embedding store unavailable, using JSON fallback: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    router.use((0, index_js_1.createEmbeddingsRoutes)(undefined, embeddingStore));
     router.use((0, index_js_1.createUsageRoutes)());
     router.use((0, index_js_1.createScriptsRoutes)());
     router.use((0, index_js_1.createMessagingRoutes)());