jxp 4.1.1 → 5.0.0

package/docs/mcp.md

@@ -0,0 +1,134 @@
+# MCP (Model Context Protocol)
+
+JXP can expose a **read-only** MCP server on the same HTTP port as the REST API. This lets AI clients (Cursor, LM Studio, RevEngine2 admin proxy) query your data with the same permissions as the REST API.
+
+## Enable
+
+```bash
+MCP_ENABLED=true
+```
+
+Optional settings (all prefixed `MCP_`):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MCP_PATH` | `/mcp` | HTTP endpoint |
+| `MCP_REQUIRE_API_KEY` | `true` | Reject unauthenticated MCP |
+| `MCP_MODEL_WHITELIST` | _(empty)_ | Expose default-hidden models (e.g. `user`) |
+| `MCP_MODEL_BLACKLIST` | _(empty)_ | Always hide models |
+| `MCP_DEFAULT_HIDDEN_MODELS` | builtin auth slugs | Override default-deny list |
+| `MCP_DEFAULT_LIMIT` | `20` | Default row limit |
+| `MCP_MAX_LIMIT` | `100` | Hard cap on `limit` |
+| `MCP_MAX_RESPONSE_SIZE` | `256kb` | JSON response cap |
+| `MCP_MAX_CSV_SIZE` | `512kb` | CSV export cap |
+| `MCP_TRUNCATE_STRINGS_AT` | `4000` | Truncate long string fields in JSON |
+| `MCP_DISABLE_AUTOPOPULATE` | `true` | Ignore expensive autopopulate |
+| `MCP_INSTRUCTIONS_APPEND` | _(empty)_ | Text appended to server instructions (initialize) |
+| `MCP_GUIDE_FILES` | _(empty)_ | Comma-separated markdown files merged into `jxp-guide` resource |
+
+## LLM guidance
+
+On connect, the MCP `initialize` response includes **server instructions** — a short workflow summary injected for the LLM.
+
+For the full guide, read the fixed MCP resource **`jxp-guide`** (`jxp://guide`, markdown). Content is merged in order:
+
+1. Built-in [`default.md`](https://github.com/WorkSpaceMan/jxp/blob/main/src/libs/mcp/guides/default.md)
+2. `JXPConfig.mcp.guideFiles` (app config)
+3. `MCP_GUIDE_FILES` (env)
+
+### App extension (`JXPConfig.mcp`)
+
+```typescript
+apiconfig.mcp = {
+  instructions: "Short app-specific note appended to server instructions.",
+  guideFiles: [path.join(__dirname, "../../mcp/guide.md")],
+};
+```
+
+Example: [revengine-api `mcp/guide.md`](https://github.com/WorkSpaceMan/revengine-api) adds domain context for `reader`, `segment`, etc.
+
+## Tools (fixed)
+
+1. **`jxp_list_models`** — models the caller can read via MCP
+2. **`jxp_describe_model`** — field types, links, populate hints
+3. **`jxp_find`** — list or get by `id`; supports `filter`, `search`, `populate`, `fields`, `sort`, `limit`, `page`
+4. **`jxp_count`** — count with optional `filter` / `search`
+5. **`jxp_export_csv`** — CSV text export (use `fields` + low `limit`)
+
+Tools never change when you add models — agents call `jxp_list_models` first.
+
+## Authentication
+
+Send the user's API key on every MCP HTTP request:
+
+```
+X-API-Key: <apikey>
+```
+
+Bearer tokens also work. MCP uses the same permission rules as `GET /api/:model`.
+
+## Docs playground
+
+When `MCP_ENABLED=true`, the built-in docs UI includes **`/docs/mcp`** — a chat-style assistant that calls the same five MCP tools (protected by the same login as **Browse API**). Use the API key field in the top bar or sign in; tool calls go through `POST /docs/mcp/call` with your permissions.
+
+Default-hidden models (unless whitelisted): built-in auth collections (`user`, `apikey`, `token`, etc.) and schemas with `internal: true`.
+
+## Cursor / LM Studio (stdio)
+
+Use the `jxp-mcp` bridge (proxies stdio → HTTP, including tools, resources, and instructions):
+
+```json
+{
+  "mcpServers": {
+    "jxp": {
+      "command": "npx",
+      "args": ["-y", "jxp-mcp"],
+      "env": {
+        "JXP_URL": "http://localhost:4001",
+        "JXP_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+For Cursor, direct HTTP MCP also works and receives instructions automatically:
+
+```json
+{
+  "mcpServers": {
+    "jxp": {
+      "url": "http://localhost:4001/mcp",
+      "headers": { "X-API-Key": "your-api-key" }
+    }
+  }
+}
+```
+
+## RevEngine2 / server proxy
+
+Backend connects to `{API_URL}/mcp` with the logged-in user's API key and proxies MCP between the admin UI and JXP. JXP's own docs UI also exposes `/docs/mcp` for local exploration.
+
+## Deploying `jxp-mcp`
+
+`jxp-mcp` is **not** a separate npm package. It ships as a **CLI binary on the `jxp` package** (since v5.0.0):
+
+```bash
+npm install jxp@5          # or depend on jxp in your app
+npx jxp-mcp                # stdio MCP → your HTTP /mcp endpoint
+```
+
+| Component | Where it runs | Role |
+|-----------|---------------|------|
+| **JXP HTTP API** | Your server (e.g. RevEngine Docker on port 4001) | Serves REST + `/mcp` when `MCP_ENABLED=true` |
+| **`jxp-mcp` bridge** | Developer's machine (Cursor, LM Studio) | stdio proxy; needs `JXP_URL` + `JXP_API_KEY` pointing at the HTTP server |
+
+**Production API containers** do not need to run `jxp-mcp`. Enable MCP on the API (`MCP_ENABLED=true`) and connect from the IDE via HTTP or stdio.
+
+**Publish order:** `npm publish` **jxp@5** first, then bump app dependencies (e.g. `revengine-api` `jxp: ^5.0.0`) and rebuild Docker images.
+
+## v1 limitations
+
+- Read-only (no mutations)
+- No `POST /query`, `/aggregate`, or `/call`
+- No per-model `mcp:` schema flag (env lists only)

package/docs/schemas.md

@@ -10,7 +10,9 @@ The schemas are based on Mongoose, so anything you can do with a [Mongoose schem
 
 ## Defining a schema
 
-Schemas are loaded from `MODEL_DIR` (default `./dist/models` on the sample server). Each file is named `<name>_model.js`. Each schema represents a collection in Mongo, with the Mongo collection name being the plural of the schema name. Eg. the data for `user_model.js` is stored in the `users` collection in Mongo.
+Schemas are loaded from `MODEL_DIR` (default `./dist/models` on the sample server). Each file is named `<name>_model.js`. JXP also ships **built-in** models (auth, `indexquerylog`, etc.) from the package when your app does not define them — see [Configuration — Built-in models](configuration.md#built-in-models). Set `internal: true` on schema options to hide a model from the docs API browser.
+
+Each schema represents a collection in Mongo, with the Mongo collection name being the plural of the schema name. Eg. the data for `user_model.js` is stored in the `users` collection in Mongo.
 
 A typical schema looks like `test_model.js` in your model directory:
 ```javascript

package/mkdocs.yml

@@ -13,7 +13,9 @@ nav:
   - Bulk Writes: bulk_writes.md
   - Queries: queries.md
   - Caching: caching.md
+  - Index diagnostics: index_diagnostics.md
   - Websocket: websocket.md
   - Special Features: special.md
+  - MCP: mcp.md
   - Changelog: changelog.md
 theme: readthedocs

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "jxp",
 	"description": "An opinionated RESTful API library based on Mongoose and Restify. Make an API by just writing Mongoose models.",
-	"version": "4.1.1",
+	"version": "5.0.0",
 	"private": false,
 	"main": "dist/libs/jxp.js",
 	"types": "dist/libs/jxp.d.ts",
@@ -39,21 +39,32 @@
 		},
 		"./types/jxp-config": {
 			"types": "./dist/types/jxp-config.d.ts"
+		},
+		"./libs/index_diagnostics": {
+			"types": "./dist/libs/index_diagnostics.d.ts",
+			"default": "./dist/libs/index_diagnostics.js"
+		},
+		"./libs/builtin_models": {
+			"types": "./dist/libs/builtin_models.d.ts",
+			"default": "./dist/libs/builtin_models.js"
 		}
 	},
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json && node -e \"require('fs').cpSync('src/libs/mcp/guides','dist/libs/mcp/guides',{recursive:true})\"",
 		"prepublishOnly": "npm run build",
 		"prepare": "node -e \"require('fs').existsSync('src')&&require('child_process').execSync('npm run build',{stdio:'inherit'})\"",
 		"start": "node dist/bin/server.js",
 		"dev": "nodemon --watch src --ext ts --exec 'npm run build && node dist/bin/server.js'",
-		"test": "npm run build && mocha --require test/env.js test/bulkwrite_guard.test.js test/request_log.test.js test/test.js --timeout 1000 -b --exit",
-		"setup": "node dist/bin/setup.js"
+		"test": "npm run build && mocha --require test/env.js test/builtin_models.test.js test/bulkwrite_guard.test.js test/index_diagnostics.test.js test/mcp_guides.test.js test/mcp_visibility.test.js test/parse_byte_size.test.js test/query_limits.test.js test/request_log.test.js test/test.js --timeout 1000 -b --exit",
+		"setup": "node dist/bin/setup.js",
+		"indexes": "node dist/bin/index_audit.js"
 	},
 	"bin": {
 		"jxp": "dist/bin/setup.js",
 		"jxp-setup": "dist/bin/setup.js",
-		"jxp-add-admin": "dist/bin/init_db.js"
+		"jxp-add-admin": "dist/bin/init_db.js",
+		"jxp-indexes": "dist/bin/index_audit.js",
+		"jxp-mcp": "dist/bin/mcp-stdio-bridge.js"
 	},
 	"repository": {
 		"type": "git",
@@ -70,15 +81,20 @@
 		"url": "https://github.com/WorkSpaceMan/jxp/issues"
 	},
 	"dependencies": {
+		"@cfworker/json-schema": "^4.1.1",
+		"@json2csv/plainjs": "^7.0.6",
+		"@modelcontextprotocol/client": "^2.0.0-alpha.2",
+		"@modelcontextprotocol/node": "^2.0.0-alpha.2",
+		"@modelcontextprotocol/server": "^2.0.0-alpha.2",
 		"bcryptjs": "^3.0.2",
+		"bytes": "^3.1.2",
 		"commander": "^13.1.0",
 		"dotenv": "^16.5.0",
 		"glob": "11.1.0",
 		"js-yaml": "4.1.1",
-		"@json2csv/plainjs": "^7.0.6",
 		"jsonwebtoken": "^9.0.2",
-		"markdown-it": "^14.1.1",
 		"jxp-helper": "^1.4.3",
+		"markdown-it": "^14.1.1",
 		"moment": "^2.30.1",
 		"mongoose": "6.13.9",
 		"mongoose-friendly": "^0.1.4",
@@ -93,12 +109,13 @@
 		"restify-errors": "^8.0.2",
 		"traverse": "^0.6.11",
 		"underscore": "^1.13.8",
-		"ws": "^8.18.1"
+		"ws": "^8.18.1",
+		"zod": "^4.4.3"
 	},
 	"devDependencies": {
-		"@types/markdown-it": "^14.1.2",
 		"@types/bcryptjs": "^2.4.6",
 		"@types/jsonwebtoken": "^9.0.9",
+		"@types/markdown-it": "^14.1.2",
 		"@types/morgan": "^1.9.9",
 		"@types/node": "^22.15.21",
 		"@types/underscore": "^1.13.0",

package/templates/assets/diagnostics.js

@@ -0,0 +1,352 @@
+(function () {
+	"use strict";
+
+	const SYNC_CONFIRM = window.JXP_DIAG_SYNC_CONFIRM || "DROP_EXTRA_INDEXES";
+
+	const REASON_LABELS = {
+		collection_scan: "Collection scan",
+		inefficient_index: "Inefficient index",
+		collection_scan_below_threshold: "Collection scan (below threshold)",
+	};
+
+	function formatReason(reason) {
+		if (!reason) return "—";
+		return REASON_LABELS[reason] || reason.replace(/_/g, " ");
+	}
+
+	function formatScanStage(stage) {
+		if (!stage) return "—";
+		const hasCollScan = /\bCOLLSCAN\b/.test(stage);
+		const cls = hasCollScan ? "text-danger fw-semibold" : "text-body-secondary";
+		return `<code class="${cls}">${escapeHtml(stage)}</code>`;
+	}
+
+	function getApiKey() {
+		const input = document.getElementById("docs-api-key");
+		return input ? input.value.trim() : "";
+	}
+
+	function authHeaders() {
+		const headers = { Accept: "application/json" };
+		const key = getApiKey();
+		if (key) headers["X-API-Key"] = key;
+		return headers;
+	}
+
+	/** Same as api-console.js: docs login stores apikey in HttpOnly cookie; expose via /docs/session */
+	async function loadSessionApiKey() {
+		const access = document.documentElement.dataset.docsAccess;
+		if (access !== "protected") return;
+		try {
+			const res = await fetch("/docs/session", { credentials: "same-origin" });
+			if (!res.ok) return;
+			const data = await res.json();
+			if (!data.apikey) return;
+			const input = document.getElementById("docs-api-key");
+			if (input) input.value = data.apikey;
+		} catch {
+			/* ignore */
+		}
+	}
+
+	function loadStoredKey() {
+		if (localStorage.getItem("jxp_docs_remember_key") !== "1") return;
+		const key = localStorage.getItem("jxp_docs_api_key");
+		if (!key) return;
+		const input = document.getElementById("docs-api-key");
+		const remember = document.getElementById("docs-remember-key");
+		if (input) input.value = key;
+		if (remember) remember.checked = true;
+	}
+
+	async function ensureApiKey() {
+		if (getApiKey()) return;
+		await loadSessionApiKey();
+		if (getApiKey()) return;
+		loadStoredKey();
+	}
+
+	async function apiFetch(path, opts) {
+		const res = await fetch(path, {
+			...opts,
+			credentials: "same-origin",
+			headers: { ...authHeaders(), ...(opts && opts.headers) },
+		});
+		const text = await res.text();
+		let body;
+		try {
+			body = text ? JSON.parse(text) : null;
+		} catch {
+			body = text;
+		}
+		if (!res.ok) {
+			const msg =
+				(body && body.message) ||
+				(body && body.msg) ||
+				(typeof body === "string" ? body : res.statusText);
+			throw new Error(msg || `HTTP ${res.status}`);
+		}
+		return body;
+	}
+
+	function badgeClass(ok, kind) {
+		if (ok) return "text-bg-success";
+		if (kind === "missing") return "text-bg-warning";
+		return "text-bg-danger";
+	}
+
+	function renderIndexes(data) {
+		const table = document.getElementById("diag-indexes-table");
+		const tbody = table.querySelector("tbody");
+		const summary = document.getElementById("diag-indexes-summary");
+		const status = document.getElementById("diag-indexes-status");
+
+		if (!data || !data.collections) {
+			status.textContent = "No audit data.";
+			table.classList.add("d-none");
+			return;
+		}
+
+		const s = data.summary || {};
+		summary.innerHTML = `<span class="badge text-bg-secondary">${s.ok || 0}/${s.total || 0} OK</span>
+      ${s.withMissing ? `<span class="badge text-bg-warning ms-1">${s.withMissing} missing</span>` : ""}
+      ${s.withExtra ? `<span class="badge text-bg-danger ms-1">${s.withExtra} extra</span>` : ""}`;
+		status.textContent = `Generated ${data.generatedAt || ""}`;
+
+		tbody.innerHTML = "";
+		for (const row of data.collections) {
+			const tr = document.createElement("tr");
+			const missing =
+				row.missing && row.missing.length
+					? row.missing.map((k) => JSON.stringify(k)).join(", ")
+					: "—";
+			const extra = row.extra && row.extra.length ? row.extra.join(", ") : "—";
+			const statusLabel = row.error ? "error" : row.ok ? "ok" : "drift";
+			tr.innerHTML = `
+        <td><code>${escapeHtml(row.modelName)}</code></td>
+        <td class="text-muted small">${escapeHtml(row.collection)}</td>
+        <td><span class="badge ${badgeClass(row.ok && !row.error)}">${statusLabel}</span></td>
+        <td class="small">${escapeHtml(missing)}</td>
+        <td class="small">${escapeHtml(extra)}</td>`;
+			tbody.appendChild(tr);
+		}
+		table.classList.remove("d-none");
+	}
+
+	function renderMonitorHelp(monitorStatus) {
+		const help = document.getElementById("diag-query-monitor-help");
+		const controls = document.querySelector("#tab-queries .d-flex.flex-wrap.gap-2.mb-3");
+		if (!help) return;
+
+		if (!monitorStatus || monitorStatus.active) {
+			help.classList.add("d-none");
+			help.innerHTML = "";
+			if (controls) controls.classList.remove("opacity-50");
+			return;
+		}
+
+		if (controls) controls.classList.add("opacity-50");
+
+		const hints = (monitorStatus.env_hints || [])
+			.map(
+				(h) =>
+					`<li><code>${escapeHtml(h.name)}=${escapeHtml(h.value)}</code>${h.comment ? ` <span class="text-muted">— ${escapeHtml(h.comment)}</span>` : ""}</li>`
+			)
+			.join("");
+
+		const prodNote = monitorStatus.is_production
+			? '<p class="mb-2 small">In <strong>production</strong>, query monitoring is off unless <code>INDEX_DIAGNOSTICS_ENABLED=true</code>. Use a low sample rate to limit overhead.</p>'
+			: '<p class="mb-2 small">In development, monitoring is on by default. If you disabled it, set the variables below and restart the API.</p>';
+
+		const envDebug = monitorStatus.env
+			? `<p class="mb-2 small text-muted">Process env: <code>QUERY_INDEX_MONITOR=${escapeHtml(monitorStatus.env.QUERY_INDEX_MONITOR ?? "(unset)")}</code>, <code>INDEX_DIAGNOSTICS_ENABLED=${escapeHtml(monitorStatus.env.INDEX_DIAGNOSTICS_ENABLED ?? "(unset)")}</code>, <code>NODE_ENV=${escapeHtml(monitorStatus.env.NODE_ENV ?? "(unset)")}</code></p>`
+			: "";
+
+		const regNote = monitorStatus.registration_missing
+			? '<p class="mb-2 small"><strong>Your .env has monitoring enabled</strong>, but this server never called <code>registerQueryIndexMonitor()</code> before loading models. Restart the API after upgrading <code>jxp</code> (recent versions register automatically inside <code>JXP()</code>).</p>'
+			: "";
+
+		help.className = "alert alert-info mb-3";
+		help.innerHTML = `
+      <h2 class="h6 alert-heading mb-2">Query monitoring is disabled</h2>
+      <p class="mb-2 small">The API is not sampling read queries or running <code>explain('executionStats')</code>. Historical rows may still appear below if logging was on earlier.</p>
+      ${regNote}
+      ${envDebug}
+      ${prodNote}
+      <p class="mb-1 small fw-semibold">Enable via environment (.env)</p>
+      <ol class="small mb-2">
+        <li>Add to your <code>.env</code> (then restart the server):</li>
+      </ol>
+      <ul class="small mb-2">${hints}</ul>
+      <p class="mb-1 small fw-semibold">Or in code (<code>JXP(apiconfig)</code>)</p>
+      <pre class="small bg-body-secondary p-2 rounded mb-2"><code>index_diagnostics: {
+  enabled: true,
+  query_monitor: {
+    enabled: true,
+    sample_rate: ${monitorStatus.is_production ? "0.02" : "1.0"}
+  }
+}</code></pre>
+      <p class="mb-0 small text-muted">Monitoring is registered at startup in <code>server.ts</code> via <code>registerQueryIndexMonitor()</code> before models load — a restart is required after changing config. See <a href="/docs/md/index_diagnostics.md">Index diagnostics</a>.</p>`;
+	}
+
+	function renderQueries(data) {
+		const table = document.getElementById("diag-queries-table");
+		const tbody = table.querySelector("tbody");
+		const status = document.getElementById("diag-queries-status");
+		const configEl = document.getElementById("diag-monitor-config");
+		const monitorStatus = data?.monitor_status;
+
+		renderMonitorHelp(monitorStatus);
+
+		if (!data) {
+			status.textContent = "No query log data.";
+			table.classList.add("d-none");
+			return;
+		}
+
+		const cfg = data.config;
+		if (monitorStatus?.active && cfg) {
+			configEl.innerHTML = `Monitor active: <code>sample_rate=${cfg.sample_rate}</code>,
+        <code>min_docs=${cfg.min_docs_examined}</code>
+        ${data.persisted ? '<span class="badge text-bg-success ms-1">MongoDB</span>' : '<span class="badge text-bg-secondary ms-1">memory buffer</span>'}`;
+		} else {
+			configEl.innerHTML =
+				'<span class="badge text-bg-secondary">Query monitor off</span> <span class="text-muted">— enable using the steps above</span>';
+		}
+
+		const entries = data.entries || [];
+		const total = data.total != null ? data.total : entries.length;
+		if (monitorStatus?.active) {
+			status.textContent = `${entries.length} shown${data.persisted ? ` of ${total} stored` : " (in-memory)"}`;
+		} else if (entries.length) {
+			status.textContent = `${entries.length} historical entries (monitoring currently off)`;
+		} else {
+			status.textContent = "No entries yet — enable monitoring above, then run API read traffic.";
+		}
+
+		tbody.innerHTML = "";
+		for (const e of entries) {
+			const tr = document.createElement("tr");
+			const sev = e.severity === "alert" ? "danger" : "warning";
+			tr.innerHTML = `
+        <td class="small text-nowrap">${escapeHtml(e.at || "")}</td>
+        <td><code>${escapeHtml(e.model)}</code></td>
+        <td>${escapeHtml(e.op)}</td>
+        <td><span class="badge text-bg-${sev}">${escapeHtml(e.severity)}</span></td>
+        <td>${e.totalDocsExamined ?? "—"}</td>
+        <td>${e.nReturned ?? "—"}</td>
+        <td class="small">${formatScanStage(e.stage)}</td>
+        <td class="small">${escapeHtml(formatReason(e.reason))}</td>
+        <td class="small font-monospace">${escapeHtml(e.filterSummary || "")}</td>`;
+			tbody.appendChild(tr);
+		}
+		table.classList.toggle("d-none", entries.length === 0);
+	}
+
+	function escapeHtml(s) {
+		return String(s)
+			.replace(/&/g, "&amp;")
+			.replace(/</g, "&lt;")
+			.replace(/>/g, "&gt;")
+			.replace(/"/g, "&quot;");
+	}
+
+	async function loadIndexes(refresh) {
+		const status = document.getElementById("diag-indexes-status");
+		const unused = document.getElementById("diag-unused").checked;
+		status.textContent = "Loading…";
+		try {
+			const q = new URLSearchParams();
+			if (refresh) q.set("refresh", "1");
+			if (unused) q.set("unused", "1");
+			const data = await apiFetch(`/diagnostics/indexes?${q}`);
+			renderIndexes(data);
+		} catch (err) {
+			status.textContent = `Error: ${err.message}`;
+		}
+	}
+
+	async function loadQueries() {
+		const status = document.getElementById("diag-queries-status");
+		const severity = document.getElementById("diag-query-severity").value;
+		const model = document.getElementById("diag-query-model").value.trim();
+		status.textContent = "Loading…";
+		try {
+			const q = new URLSearchParams({ limit: "100" });
+			if (severity) q.set("severity", severity);
+			if (model) q.set("model", model);
+			const data = await apiFetch(`/diagnostics/queries?${q}`);
+			renderQueries(data);
+		} catch (err) {
+			status.textContent = `Error: ${err.message} (admin API key required)`;
+		}
+	}
+
+	async function syncIndexes() {
+		const confirmInput = document.getElementById("diag-sync-confirm");
+		const status = document.getElementById("diag-indexes-status");
+		if (confirmInput.value.trim() !== SYNC_CONFIRM) {
+			status.textContent = `Type ${SYNC_CONFIRM} to confirm sync.`;
+			return;
+		}
+		status.textContent = "Syncing…";
+		try {
+			await apiFetch("/diagnostics/indexes/sync", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ confirm: SYNC_CONFIRM }),
+			});
+			status.textContent = "Sync complete. Refreshing audit…";
+			confirmInput.value = "";
+			await loadIndexes(true);
+		} catch (err) {
+			status.textContent = `Sync failed: ${err.message}`;
+		}
+	}
+
+	function wireModelFilter() {
+		const input = document.getElementById("diag-query-model");
+		if (!input) return;
+		let debounceTimer;
+		input.addEventListener("change", loadQueries);
+		input.addEventListener("input", () => {
+			clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(loadQueries, 350);
+		});
+	}
+
+	function wireSyncConfirm() {
+		const input = document.getElementById("diag-sync-confirm");
+		const btn = document.getElementById("diag-sync-btn");
+		if (!input || !btn) return;
+		input.addEventListener("input", () => {
+			btn.disabled = input.value.trim() !== SYNC_CONFIRM;
+		});
+		btn.addEventListener("click", syncIndexes);
+	}
+
+	document.addEventListener("DOMContentLoaded", async () => {
+		document.getElementById("diag-refresh-indexes")?.addEventListener("click", () => loadIndexes(true));
+		document.getElementById("diag-refresh-queries")?.addEventListener("click", loadQueries);
+		document.getElementById("diag-query-severity")?.addEventListener("change", loadQueries);
+		wireModelFilter();
+		wireSyncConfirm();
+
+		const access = document.documentElement.dataset.docsAccess;
+		await loadSessionApiKey();
+		if (access !== "protected") loadStoredKey();
+		if (!getApiKey()) {
+			const status = document.getElementById("diag-indexes-status");
+			if (status) {
+				status.textContent =
+					"Set an admin API key in the top bar (or sign in again via /docs/login).";
+			}
+			return;
+		}
+		loadIndexes(false);
+
+		document.getElementById("tab-queries-btn")?.addEventListener("shown.bs.tab", () => {
+			if (getApiKey()) loadQueries();
+		});
+	});
+})();