becki-mcp 1.1.0

package/dist/index.js

@@ -0,0 +1,3412 @@
+#!/usr/bin/env node
+/**
+ * Becki MCP Server
+ *
+ * Exposes NeuraVault to Claude Code and Cursor via the Model Context Protocol.
+ * Transport: stdio (standard for Claude Code integration)
+ *
+ * Tool: becki_context
+ *   Input:  { query: string }
+ *   Output: { context: string }
+ *
+ * Add to ~/.claude/claude_desktop_config.json:
+ * {
+ *   "mcpServers": {
+ *     "becki": {
+ *       "command": "node",
+ *       "args": ["/Users/bdsantos/becki/tools/becki-mcp/dist/index.js"]
+ *     }
+ *   }
+ * }
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, appendFileSync, statSync, watch as fsWatch, } from "fs";
+import { join } from "path";
+import { homedir, platform } from "os";
+import { randomUUID, createHash } from "crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createServer as createHttpServer } from "node:http";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+//
+// Only public values live here. No Voyage key, no Anthropic key, no Supabase
+// service-role key. All server-side secrets stay on Supabase.
+//
+// - Embeddings (both query and write) are proxied through the
+//   voyage-embed edge function. The function owns the Voyage key and
+//   enforces per-install quotas.
+// - Vault reads use the anon key with RLS handling scoping.
+// - Vault writes flow through the running Becki.app's IPC listener
+//   (localhost:9876) so the authenticated Swift client does the actual
+//   DB insert. The MCP binary therefore never handles user credentials.
+//
+// The SUPABASE_ANON_KEY below is intentionally embedded in a shipped
+// binary — it's a public-by-design credential (every Supabase project
+// has a public anon key). Every row it can touch is RLS-gated, so it
+// carries no data-access risk. Abuse protection is quota-based, handled
+// server-side by the edge function.
+const SUPABASE_URL = "https://mbutedmgtkmoigfbrthr.supabase.co";
+const SUPABASE_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im1idXRlZG1ndGttb2lnZmJydGhyIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzY4Mjk1NTYsImV4cCI6MjA5MjQwNTU1Nn0.FHMSjKrwSgglGa6__ykxuPjxCrjmj8gKqwpEbJoVvgk";
+const BECKI_IPC_URL = "http://localhost:9876";
+// ---------------------------------------------------------------------------
+// Install identity
+// ---------------------------------------------------------------------------
+//
+// The edge function's anon-query branch buckets Voyage spend by install_id
+// so one abusive process can't drain the global anon quota. The id is a
+// random UUID generated on first run and persisted next to the MCP
+// registry. Users never see it.
+// ── Cross-platform Becki home directory ─────────────────────────────────────
+//
+// becki-mcp ships in two shapes:
+//   - Bundled inside Becki.app (Studio tier on macOS) — reads/writes the
+//     legacy `~/Library/Application Support/Becki/` path so the Swift app
+//     and the MCP daemon share state.
+//   - Standalone npm/Homebrew install (Core tier, cross-platform) — uses
+//     `~/.becki/` everywhere.
+//
+// Resolution order:
+//   1. `BECKI_HOME` env var (explicit override, useful for tests & non-default installs)
+//   2. On macOS with the legacy Application Support dir already present
+//      (i.e. Becki.app is installed), keep using it for backward compatibility
+//   3. Otherwise `~/.becki/` (cross-platform default)
+function resolveBeckiHome() {
+    const envOverride = process.env.BECKI_HOME;
+    if (envOverride && envOverride.length > 0)
+        return envOverride;
+    if (platform() === "darwin") {
+        const legacy = join(homedir(), "Library", "Application Support", "Becki");
+        if (existsSync(legacy))
+            return legacy;
+    }
+    return join(homedir(), ".becki");
+}
+const APP_SUPPORT_DIR = resolveBeckiHome();
+const INSTALL_ID_PATH = join(APP_SUPPORT_DIR, "mcp-install-id");
+function getInstallId() {
+    try {
+        if (existsSync(INSTALL_ID_PATH)) {
+            const existing = readFileSync(INSTALL_ID_PATH, "utf8").trim();
+            if (existing)
+                return existing;
+        }
+    }
+    catch {
+        // fall through and regenerate
+    }
+    const fresh = randomUUID();
+    try {
+        mkdirSync(APP_SUPPORT_DIR, { recursive: true });
+        writeFileSync(INSTALL_ID_PATH, fresh + "\n", "utf8");
+    }
+    catch {
+        // best-effort — if we can't persist, rotating every cold start is
+        // acceptable degradation (quota just resets more often).
+    }
+    return fresh;
+}
+const INSTALL_ID = getInstallId();
+// ---------------------------------------------------------------------------
+// MCP ingest token (v0.7.0)
+// ---------------------------------------------------------------------------
+//
+// Becki.app issues a per-install scoped token that authorizes ONLY POST to
+// /functions/v1/ingest-vault-row. Stored in a 0600 file at:
+//
+//   ~/Library/Application Support/Becki/mcp-ingest-token
+//
+// We read this on startup + watch for changes. When present, becki_ingest
+// POSTs directly to the edge function — meaning the embed lands in
+// vault_embeddings even when Becki.app is closed/crashed/quit.
+//
+// When ABSENT (e.g. user hasn't upgraded Becki.app yet), we fall back to the
+// existing IPC + file-watch path. Backward compatible.
+//
+// Security: file mode is checked on every read. If perms aren't 0600 we
+// refuse to use the token (defends against accidental permission downgrades
+// or hostile processes touching the file).
+const MCP_INGEST_TOKEN_PATH = join(APP_SUPPORT_DIR, "mcp-ingest-token");
+const MCP_USER_ID_PATH = join(APP_SUPPORT_DIR, "mcp-user-id");
+let cachedIngestToken = null;
+let cachedUserId = null;
+let ingestTokenWatcher = null;
+const requestContext = new AsyncLocalStorage();
+function currentUserId() {
+    return requestContext.getStore()?.userId ?? cachedUserId;
+}
+/**
+ * Scopes for the active request. HTTP requests carry the OAuth token's
+ * granted scopes. stdio gets full access — the local user owns their own
+ * machine and vault; there is no scope to withhold.
+ */
+function currentScopes() {
+    return requestContext.getStore()?.scopes ?? ["read", "write"];
+}
+// True when this process is the remote-MCP HTTP service (Railway), false for
+// the Mac-app-bundled stdio server. Gates the ingest path: HTTP ingests via
+// the ingest_vault_row RPC scoped to the OAuth user; stdio uses the local
+// install-token + file + IPC fallback chain.
+const IS_HTTP_TRANSPORT = process.env.BECKI_MCP_TRANSPORT === "http";
+function readIngestToken() {
+    return readProtectedFile(MCP_INGEST_TOKEN_PATH, "mcp-ingest-token");
+}
+function readUserId() {
+    // user_id is required by match_vault_v4 (post-migration 027 — closes the
+    // cross-user vault read by requiring an explicit user scope). Becki.app
+    // writes this file alongside mcp-ingest-token after registration.
+    const v = readProtectedFile(MCP_USER_ID_PATH, "mcp-user-id");
+    if (!v)
+        return null;
+    // UUID format check — defensive: a malformed user_id would be rejected by
+    // the RPC anyway, but we'd rather not POST garbage.
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v) ? v : null;
+}
+function readProtectedFile(path, label) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const stat = statSync(path);
+        // 0o777 mask isolates the permission bits. Anything other than 0o600
+        // means somebody touched the file — refuse to trust it.
+        if ((stat.mode & 0o777) !== 0o600) {
+            console.error(`${label}: refusing to read — file mode is ${(stat.mode & 0o777).toString(8)}, expected 600. ` +
+                `Run \`chmod 600 ${path}\` if this was unintentional.`);
+            return null;
+        }
+        const raw = readFileSync(path, "utf8").trim();
+        return raw || null;
+    }
+    catch (err) {
+        console.error(`${label}: read failed`, err);
+        return null;
+    }
+}
+function startIngestTokenWatcher() {
+    cachedIngestToken = readIngestToken();
+    cachedUserId = readUserId();
+    if (ingestTokenWatcher)
+        return;
+    // Watch the parent dir, not the file itself — fsWatch on a single file is
+    // unreliable on macOS when the file is replaced via atomic move (which is
+    // exactly what Becki.app does to write the token). Watching the dir picks
+    // up the rename event reliably.
+    try {
+        if (!existsSync(APP_SUPPORT_DIR)) {
+            mkdirSync(APP_SUPPORT_DIR, { recursive: true });
+        }
+        ingestTokenWatcher = fsWatch(APP_SUPPORT_DIR, (_event, filename) => {
+            if (filename === "mcp-ingest-token") {
+                const next = readIngestToken();
+                if (next !== cachedIngestToken) {
+                    cachedIngestToken = next;
+                    console.error(`mcp-ingest-token: ${next ? "loaded" : "cleared"}`);
+                }
+            }
+            else if (filename === "mcp-user-id") {
+                const next = readUserId();
+                if (next !== cachedUserId) {
+                    cachedUserId = next;
+                    console.error(`mcp-user-id: ${next ? "loaded" : "cleared"}`);
+                }
+            }
+        });
+    }
+    catch (err) {
+        console.error("mcp-ingest-token: watcher setup failed", err);
+    }
+}
+startIngestTokenWatcher();
+/**
+ * Canonical project-slug form on write — mirrors the SQL becki.norm_project_slug
+ * (migration 046): case-folded, '_' and '-' treated as equivalent, trimmed.
+ * Applied to project_name before ingest so new rows stop fragmenting
+ * (BECKI / becki / Becki, forecast_performance vs forecast-performance).
+ */
+function normProjectSlug(raw) {
+    if (!raw)
+        return undefined;
+    const norm = raw.trim().toLowerCase().replace(/_/g, "-");
+    return norm || undefined;
+}
+/**
+ * POST to ingest-vault-row using the install token. Returns ok:true on 2xx,
+ * ok:false otherwise. Caller falls back to the IPC + file-watch path on
+ * failure or when no token is loaded.
+ */
+async function cloudIngest(type, content, project, title) {
+    const token = cachedIngestToken;
+    if (!token)
+        return { ok: false, error: "no_token" };
+    const sourceId = title ? `${todayStr()}-${toSlug(title)}` : undefined;
+    const metadata = {};
+    const projectSlug = normProjectSlug(project);
+    if (projectSlug)
+        metadata.project_name = projectSlug;
+    try {
+        const resp = await fetch(`${SUPABASE_URL}/functions/v1/ingest-vault-row`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${token}`,
+                "User-Agent": `becki-mcp/${INSTALL_ID.slice(0, 8)}`,
+            },
+            body: JSON.stringify({
+                content,
+                source_type: type,
+                source_id: sourceId,
+                metadata,
+            }),
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            return { ok: false, status: resp.status, error: body.slice(0, 300) };
+        }
+        const json = await resp.json();
+        return {
+            ok: true,
+            status: resp.status,
+            vault_id: json.vault_id,
+            source_id: json.source_id,
+        };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// Decision Reasoning Graph forward-capture (HTTP-transport path). Fire the
+// extractor for a freshly-written decision so its structured "why" lands in
+// becki.decision_reasoning. Fire-and-forget: becki-mcp is a long-lived Node
+// server (unlike an edge isolate), so the request completes after the ingest
+// response returns. extract-decision-reasoning is idempotent + does its own
+// service-role auth (verify_jwt=false). Never throws into the caller.
+function fireDecisionReasoning(vaultId, userId, content, secret) {
+    fetch(`${SUPABASE_URL}/functions/v1/extract-decision-reasoning`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${secret}` },
+        body: JSON.stringify({ text: content, decision_id: vaultId, user_id: userId }),
+    }).catch((err) => console.error("[decision-reasoning] fire failed (non-fatal):", err instanceof Error ? err.message : err));
+}
+// ---------------------------------------------------------------------------
+// HTTP-transport ingest (v0.10.0 — remote MCP web ingest)
+// ---------------------------------------------------------------------------
+// The stdio cloudIngest() above POSTs to the ingest-vault-row edge function
+// authed by a local install-token file — which doesn't exist on Railway.
+// The HTTP transport instead: embed the content via voyage-embed, then call
+// the ingest_vault_row RPC (migration 044) with the service key, scoped to
+// the OAuth-resolved user (currentUserId()). No local file, no install token,
+// no Becki.app IPC.
+async function httpIngest(type, content, project, title) {
+    const secret = process.env.SUPABASE_SECRET_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!secret)
+        return { ok: false, error: "SUPABASE_SECRET_KEY not configured" };
+    const userId = currentUserId();
+    if (!userId)
+        return { ok: false, error: "no user_id in request context" };
+    let embedding;
+    try {
+        // Service-role auth: voyage-embed forbids document embeds on the anon
+        // path. The secret key routes through voyage-embed's "service" branch,
+        // and X-Becki-User-Id (set inside generateEmbedding) attributes spend.
+        embedding = await generateEmbedding(content, "document", { secretKey: secret, userId });
+    }
+    catch (err) {
+        return { ok: false, error: `embed failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    // source_id matches cloudIngest's scheme so a row ingested via remote MCP
+    // dedups against the same decision ingested any other way.
+    const sourceId = title ? `${todayStr()}-${toSlug(title)}` : null;
+    const metadata = {};
+    const projectSlug = normProjectSlug(project);
+    if (projectSlug)
+        metadata.project_name = projectSlug;
+    // Origin tag — marks this row as web-ingested (remote MCP, not the Mac).
+    // The macOS app's cloud->local pull-sync (#150) queries on this to know
+    // which rows need a local ~/Documents/Becki/*.md file written.
+    metadata.origin = "remote-mcp";
+    try {
+        const resp = await fetch(`${SUPABASE_URL}/rest/v1/rpc/ingest_vault_row`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                apikey: secret,
+                Authorization: `Bearer ${secret}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({
+                pp_user_id: userId,
+                pp_source_type: type,
+                pp_source_id: sourceId,
+                pp_content: content,
+                pp_embedding: embedding,
+                pp_metadata: metadata,
+            }),
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            return { ok: false, error: `${resp.status} ${body.slice(0, 200)}` };
+        }
+        // The RPC returns the row uuid as a bare JSON scalar.
+        const raw = await resp.json();
+        const vaultId = typeof raw === "string" ? raw : String(raw);
+        if (type === "decision" && vaultId) {
+            fireDecisionReasoning(vaultId, userId, content, secret);
+        }
+        return { ok: true, vault_id: vaultId };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// ---------------------------------------------------------------------------
+// Embedding proxy — all Voyage calls go through the edge function so the
+// key never touches the client.
+// ---------------------------------------------------------------------------
+async function generateEmbedding(text, inputType = "query", serviceAuth) {
+    // voyage-embed's anon path is query-only — it returns 403
+    // anon_writes_forbidden for input_type "document" (no anonymous writes).
+    // The remote-MCP HTTP transport ingests documents, so it must authenticate
+    // as service-role: voyage-embed's "service" branch allows document embeds
+    // and attributes the Voyage spend to the OAuth-resolved user via the
+    // X-Becki-User-Id header. The stdio transport keeps the anon+install-id
+    // path (query embeds only ever go through anon, document embeds there go
+    // through Becki.app's authenticated IPC, not this function).
+    const headers = { "Content-Type": "application/json" };
+    if (serviceAuth) {
+        headers.apikey = serviceAuth.secretKey;
+        headers.Authorization = `Bearer ${serviceAuth.secretKey}`;
+        headers["X-Becki-User-Id"] = serviceAuth.userId;
+    }
+    else {
+        headers.apikey = SUPABASE_ANON_KEY;
+        headers.Authorization = `Bearer ${SUPABASE_ANON_KEY}`;
+        headers["X-Becki-Install-Id"] = INSTALL_ID;
+    }
+    const res = await fetch(`${SUPABASE_URL}/functions/v1/voyage-embed`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ texts: [text], input_type: inputType }),
+    });
+    if (res.status === 429) {
+        throw new Error("NeuraVault is rate-limited right now — the daily query quota is exhausted. Try again in an hour.");
+    }
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`voyage-embed ${res.status}: ${body.slice(0, 300)}`);
+    }
+    const json = (await res.json());
+    if (!Array.isArray(json.vectors) || !Array.isArray(json.vectors[0])) {
+        throw new Error("voyage-embed returned no vector");
+    }
+    return json.vectors[0];
+}
+// Retrieval tuning — v0.4 retrieval hardening (task #32).
+//
+// MATCH_COUNT: was 5, bumped to 12. Pre-v0.4 the MCP returned the top
+//   5 chunks and the downstream LLM had to work from that. Empirically
+//   that was too tight — the 2026-04-24 cross-tool test showed a fresh
+//   dead_end node getting ranked 6th and silently dropped, producing a
+//   confident hallucination in Codex. 12 gives the LLM enough surface
+//   to spot the right node when it exists without overwhelming context.
+//
+// MATCH_THRESHOLD: was 0.3, lowered to 0.2. Same trade — rather lean in
+//   more loose-related candidates and let the LLM filter, than cut a
+//   near-miss that would have been the correct answer.
+//
+// CONFIDENCE_THRESHOLD: new. If the top hit's similarity is below this
+//   value, queryVault / queryCodeContext prepend a "⚠ No high-confidence
+//   match" warning to the returned context so the downstream LLM knows
+//   not to confabulate. 0.55 chosen empirically — a genuinely relevant
+//   chunk for a focused question usually scores 0.6-0.8; below 0.55 we
+//   are almost always looking at noise that will produce hallucinations
+//   if fed to an LLM without a warning.
+const MATCH_COUNT = 12;
+const MATCH_THRESHOLD = 0.2;
+const CONFIDENCE_THRESHOLD = 0.55;
+function classifyIntent(query) {
+    const q = query.toLowerCase();
+    // Decision-recall triggers — the dominant failure mode pre-v0.4 (knowledge
+    // chunks buried under code). Hits all the question shapes a user typically
+    // uses to ask Becki "what's in our memory about X."
+    const decisionPatterns = [
+        /what (did|do|have) we decide/, /what(?:'s| is) (our|the) decision/,
+        /what(?:'s| is) the plan/, /what did we agree/, /how did we resolve/,
+        /any decisions? (about|on)/, /any dead.ends?/, /what (did|have) we tried/,
+        /open loops?/, /commitments?/, /what(?:'s| is) outstanding/,
+        /what changed/, /what(?:'s| is) (the|our) latest/, /recent (decisions?|changes?)/,
+        // v0.6.0: action verbs that imply decision-recall intent. Real users ask
+        // "what did we ship to fix X" expecting the decision/dead_end about X — not
+        // a code chunk. Eval surfaced this gap on 2026-05-01.
+        /what (did|have) we (ship|build|release|fix|implement|add|launch|deploy)/,
+        /how did we (ship|build|release|fix|implement|add|solve|handle)/,
+        /why (did|do) we (ship|build|release|fix|implement|choose|use)/,
+    ];
+    if (decisionPatterns.some((re) => re.test(q)))
+        return "decision_recall";
+    // Code-locator triggers — query is about implementation details, file
+    // structure, or specific functions. Knowledge boost would pollute these.
+    const codePatterns = [
+        /where (is|are) /, /show me (how|the )/, /find the /, /which file/,
+        /implementation of /, /how (is|does) .* implemented/, /the function /,
+        /the class /, /the handler /, /import .* from/,
+    ];
+    if (codePatterns.some((re) => re.test(q)))
+        return "code_locator";
+    return "general";
+}
+function paramsForIntent(intent, codeOnly) {
+    if (codeOnly)
+        return { knowledgeBoost: 1.0, filterSourceTypes: ["code"] };
+    switch (intent) {
+        case "decision_recall":
+            // Strong knowledge bias. Don't filter out code entirely — the LLM still
+            // benefits from seeing relevant file context, just not as the dominant
+            // signal. Threshold + boost combination pushes weak code chunks below
+            // the cutoff naturally.
+            return { knowledgeBoost: 1.5, filterSourceTypes: null };
+        case "code_locator":
+            // Pure raw similarity. Code wins when code is what's relevant.
+            return { knowledgeBoost: 1.0, filterSourceTypes: null };
+        case "general":
+            // Mild bias toward knowledge for ambiguous queries — keeps decisions
+            // visible without burying code that's relevant.
+            return { knowledgeBoost: 1.2, filterSourceTypes: null };
+    }
+}
+// RRF normalization ceiling — a chunk that hits rank 1 in BOTH vector AND BM25
+// gets RRF = 1/(60+1) + 1/(60+1) ≈ 0.0328. Dividing raw RRF by this ceiling
+// brings the score back into [0, 1] cosine-equivalent space so CONFIDENCE_THRESHOLD
+// (0.55) stays meaningful and the downstream LLM warning fires on the same band
+// of "weakly related" results it always did. Mirrors the Swift Terminal calibration.
+const RRF_CEILING = 0.0328;
+// v0.6.0 temporal layer half-life defaults per intent. Code-locator queries
+// disable temporal weighting entirely — old code is still correct code, freshness
+// is irrelevant. Decision-recall and general queries use 30d half-life so a
+// chunk loses ~17% relevance after 8 days, ~50% after 30 days, ~88% after 90 days
+// (subject to the 0.1 floor in match_vault_v4).
+const HALF_LIFE_DAYS_BY_INTENT = {
+    decision_recall: 30,
+    general: 30,
+    code_locator: 0, // disable
+};
+// v0.6.0: relax websearch_to_tsquery's phrase-query behavior on slug-shaped
+// inputs. websearch_to_tsquery turns `foo-bar-baz` into a phrase query
+// (`'foo-bar-baz' <-> 'foo' <-> 'bar' <-> 'baz'`) which fails to match content
+// that has the slug appearing with extra trailing tokens (e.g. `foo-bar-baz-shipped`).
+// Replacing internal hyphens with spaces in pure slug tokens lets websearch build
+// an AND query over individual lexemes — same recall, less brittle.
+//
+// Heuristic: only rewrite if the query is a single whitespace-free token with
+// 2+ hyphens. Multi-word natural-language queries are untouched so quoted
+// phrases ("becki_context" handler) keep their websearch semantics.
+function relaxSlugQuery(query) {
+    const trimmed = query.trim();
+    if (/\s/.test(trimmed))
+        return query; // multi-word — leave alone
+    if ((trimmed.match(/-/g) ?? []).length < 2)
+        return query; // not slug-shaped
+    return trimmed.replace(/-/g, " ");
+}
+// v1.x retrieval-quality (#168): obligation IDIOMS carry content words that
+// collide lexically with unrelated projects — "what's on my plate?" (an
+// obligation question) BM25-matches weightlifting "plate" chunks from a gym
+// project. The deterministic commitments ledger already answers the obligation;
+// the pun only pollutes the supporting chunk list. When an unambiguous
+// obligation idiom is present in the ORIGINAL query, drop its pun token from the
+// LEXICAL query only — the embedding still uses the raw query (semantic recall
+// untouched) and the chunk set is never neutered, so this is symmetric with the
+// in-app surface and never makes either poorer. Mirrors
+// BECKI-macOS NeuraVaultQuery.stripObligationPun.
+const OBLIGATION_IDIOMS = [
+    { marker: "on my plate", puns: ["plate", "plates"], embed: "among my open commitments and obligations" },
+    { marker: "on your plate", puns: ["plate", "plates"], embed: "among your open commitments and obligations" },
+    { marker: "off my plate", puns: ["plate", "plates"], embed: "from my open commitments and obligations" },
+    { marker: "off your plate", puns: ["plate", "plates"], embed: "from your open commitments and obligations" },
+];
+// BM25 side: drop the idiom's pun token from the LEXICAL query.
+function stripObligationPun(lexical, original) {
+    const lo = original.toLowerCase();
+    let out = lexical;
+    for (const idiom of OBLIGATION_IDIOMS) {
+        if (!lo.includes(idiom.marker))
+            continue;
+        for (const pun of idiom.puns) {
+            out = out.replace(new RegExp(`\\b${pun}\\b`, "gi"), " ");
+        }
+    }
+    return out.replace(/\s+/g, " ").trim();
+}
+// Embedding side (#168 step 2): the BM25 strip kills the lexical pun, but the
+// VECTOR search still pulls "plate" content because the raw idiom embeds near
+// food/weightlifting. Replace the idiom phrase with obligation vocabulary for
+// the EMBEDDING INPUT ONLY so the vector search anchors on commitments, not the
+// literal noun. The raw query is unchanged for BM25/display, and nothing is
+// suppressed — symmetric with the in-app surface. Mirrors
+// BECKI-macOS NeuraVaultQuery.canonicalizeObligationIdiom.
+function canonicalizeObligationIdiom(query) {
+    let out = query;
+    for (const idiom of OBLIGATION_IDIOMS) {
+        const rx = new RegExp(idiom.marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
+        out = out.replace(rx, idiom.embed);
+    }
+    return out;
+}
+/**
+ * Calls match_vault_v4 (migration 023) — v0.6.0 temporal-aware hybrid retrieval.
+ * Builds on v3 (vector + BM25 + RRF + resolution-aware) by adding a recency
+ * half-life decay. Code-locator queries disable temporal weighting; everything
+ * else gets a 30d half-life so fresh decisions outrank ancient ones at equal
+ * semantic relevance.
+ *
+ * Knowledge_boost + project_anchor + resolution multipliers all apply pre-recency
+ * so relevance still dominates — recency is a tiebreaker (with a 0.1 floor so
+ * highly-relevant ancient chunks still surface).
+ *
+ * Returned similarity is the boosted RRF score post-recency; we normalize against
+ * RRF_CEILING to bring it back into [0,1] for confidence-threshold comparison.
+ */
+/**
+ * v0.7.7 temporal pre-pass. Detect "today / yesterday / this week / last week /
+ * this month / last month / last N days / since YYYY-MM-DD" and resolve to
+ * absolute (since, until) ISO 8601 bounds for pp_since / pp_until on the v4
+ * RPC call. Half-open interval [since, until). Returns nulls for both when
+ * no temporal phrase matched.
+ *
+ * Mirrors the Swift NeuraVaultQuery.resolveTemporalFilters logic so the in-
+ * app Becki Terminal and the MCP-served vault search agree on temporal
+ * scoping. Tweak both together if either evolves.
+ */
+function resolveTemporalFilters(query, now = new Date()) {
+    const q = query.toLowerCase();
+    // Helper: produce an ISO date at start-of-day UTC for a given Date.
+    const startOfDayUTC = (d) => {
+        const out = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+        return out;
+    };
+    const startOfToday = startOfDayUTC(now);
+    const startOfTomorrow = new Date(startOfToday);
+    startOfTomorrow.setUTCDate(startOfTomorrow.getUTCDate() + 1);
+    if (q.includes("today")) {
+        return {
+            since: startOfToday.toISOString(),
+            until: startOfTomorrow.toISOString(),
+            matchedPhrase: "today",
+        };
+    }
+    if (q.includes("yesterday")) {
+        const startOfYesterday = new Date(startOfToday);
+        startOfYesterday.setUTCDate(startOfYesterday.getUTCDate() - 1);
+        return {
+            since: startOfYesterday.toISOString(),
+            until: startOfToday.toISOString(),
+            matchedPhrase: "yesterday",
+        };
+    }
+    // "this week" — Monday 00:00 UTC of current week (ISO week).
+    if (q.includes("this week")) {
+        const day = now.getUTCDay(); // 0 = Sun, 1 = Mon, ...
+        const offsetToMonday = ((day + 6) % 7); // Sun → 6, Mon → 0, Tue → 1, ...
+        const monday = new Date(startOfToday);
+        monday.setUTCDate(monday.getUTCDate() - offsetToMonday);
+        const nextMonday = new Date(monday);
+        nextMonday.setUTCDate(nextMonday.getUTCDate() + 7);
+        return {
+            since: monday.toISOString(),
+            until: nextMonday.toISOString(),
+            matchedPhrase: "this week",
+        };
+    }
+    if (q.includes("last week")) {
+        const day = now.getUTCDay();
+        const offsetToMonday = ((day + 6) % 7);
+        const thisMonday = new Date(startOfToday);
+        thisMonday.setUTCDate(thisMonday.getUTCDate() - offsetToMonday);
+        const lastMonday = new Date(thisMonday);
+        lastMonday.setUTCDate(lastMonday.getUTCDate() - 7);
+        return {
+            since: lastMonday.toISOString(),
+            until: thisMonday.toISOString(),
+            matchedPhrase: "last week",
+        };
+    }
+    if (q.includes("this month")) {
+        const firstOfMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+        const firstOfNext = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+        return {
+            since: firstOfMonth.toISOString(),
+            until: firstOfNext.toISOString(),
+            matchedPhrase: "this month",
+        };
+    }
+    if (q.includes("last month")) {
+        const firstOfMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+        const firstOfLast = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 1, 1));
+        return {
+            since: firstOfLast.toISOString(),
+            until: firstOfMonth.toISOString(),
+            matchedPhrase: "last month",
+        };
+    }
+    // "in the last N days" / "last N days" / "past N days" / "in the past N days"
+    const lastNDaysMatch = q.match(/(?:in the last|last|past|in the past)\s+(\d{1,3})\s+days?/);
+    if (lastNDaysMatch) {
+        const n = parseInt(lastNDaysMatch[1], 10);
+        if (n > 0 && n < 366) {
+            const since = new Date(startOfTomorrow);
+            since.setUTCDate(since.getUTCDate() - n);
+            return {
+                since: since.toISOString(),
+                until: null,
+                matchedPhrase: `last ${n} days`,
+            };
+        }
+    }
+    // "since YYYY-MM-DD" or "since YYYY-MM"
+    const sinceDateMatch = q.match(/since\s+(\d{4}-\d{2}-\d{2}|\d{4}-\d{2})/);
+    if (sinceDateMatch) {
+        const raw = sinceDateMatch[1];
+        const iso = raw.length === 7 ? `${raw}-01T00:00:00Z` : `${raw}T00:00:00Z`;
+        const parsed = new Date(iso);
+        if (!isNaN(parsed.getTime())) {
+            return {
+                since: parsed.toISOString(),
+                until: null,
+                matchedPhrase: `since ${raw}`,
+            };
+        }
+    }
+    return { since: null, until: null, matchedPhrase: null };
+}
+const REWRITE_ENDPOINT = `${SUPABASE_URL}/functions/v1/claude-proxy/rewrite`;
+// Hard cap so a slow Anthropic call can't stall the MCP. Below this we just
+// fall through to the regex layer — degraded retrieval beats a 12-second
+// stall in Claude Desktop / Cursor.
+const REWRITE_TIMEOUT_MS = 4500;
+/**
+ * Calls claude-proxy /rewrite. Returns the rewrite on success, null on any
+ * failure (timeout, network, 4xx/5xx, invalid JSON, missing install token).
+ * Never throws — all callers expect a maybe-rewrite they can fall through.
+ */
+async function rewriteQueryViaProxy(query) {
+    const token = cachedIngestToken;
+    if (!token)
+        return null; // no install token = MCP not registered yet
+    // tz from the OS — Intl.DateTimeFormat().resolvedOptions().timeZone returns
+    // an IANA name like "America/Chicago" on every modern Node. Fall back to
+    // "UTC" if for some reason it doesn't resolve (containers without zoneinfo).
+    let tz;
+    try {
+        tz = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        tz = "UTC";
+    }
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REWRITE_TIMEOUT_MS);
+    try {
+        const res = await fetch(REWRITE_ENDPOINT, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query, tz }),
+            signal: ctrl.signal,
+        });
+        if (!res.ok) {
+            // 422 is expected when Haiku misbehaves — drop to debug-level logging
+            // so the MCP doesn't spam stderr on transient model issues.
+            if (res.status === 422) {
+                console.error(`rewrite: 422 from claude-proxy, falling back to regex`);
+            }
+            else {
+                console.error(`rewrite: ${res.status} from claude-proxy`);
+            }
+            return null;
+        }
+        const body = (await res.json());
+        if (!body?.rewrite)
+            return null;
+        if (body.cache_hit) {
+            console.error(`rewrite: cache hit`);
+        }
+        return body.rewrite;
+    }
+    catch (err) {
+        if (err?.name === "AbortError") {
+            console.error(`rewrite: timeout after ${REWRITE_TIMEOUT_MS}ms — using regex fallback`);
+        }
+        else {
+            console.error(`rewrite: failed (non-fatal) — ${String(err).slice(0, 200)}`);
+        }
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Convert Haiku's local-date interval (YYYY-MM-DD strings in the user's
+ * timezone) into UTC ISO timestamps suitable for match_vault_v4's pp_since
+ * / pp_until parameters.
+ *
+ * Half-open semantics: until is the day AFTER the user's intended last day.
+ * Haiku is told this in the system prompt, so we only convert here. If
+ * Haiku slips and emits an inclusive range, the worst case is a one-day-
+ * wide miss at the edge — acceptable.
+ *
+ * Implementation note: `new Date("YYYY-MM-DDTHH:MM:SS")` (no Z, no offset)
+ * is interpreted in the runtime's LOCAL timezone, which is exactly what we
+ * want here — Haiku's "2026-05-05" is meant to be midnight in the user's
+ * local zone, and Node is running in that same zone (we read it via Intl
+ * one paragraph up). `.toISOString()` then returns the UTC equivalent.
+ */
+function rewriteTemporalToUTC(rewrite) {
+    const sinceUtc = localDateToUtcStartOfDay(rewrite.since);
+    const untilUtc = localDateToUtcStartOfDay(rewrite.until);
+    if (!sinceUtc && !untilUtc) {
+        return { since: null, until: null, matchedPhrase: null };
+    }
+    return {
+        since: sinceUtc,
+        until: untilUtc,
+        matchedPhrase: `haiku:${rewrite.since ?? "*"}..${rewrite.until ?? "*"}`,
+    };
+}
+function localDateToUtcStartOfDay(yyyymmdd) {
+    if (!yyyymmdd)
+        return null;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(yyyymmdd))
+        return null;
+    const d = new Date(`${yyyymmdd}T00:00:00`);
+    if (isNaN(d.getTime()))
+        return null;
+    return d.toISOString();
+}
+async function matchChunks(embedding, limit = MATCH_COUNT, codeOnly = false, query) {
+    // v0.7.8: Haiku semantic-rewrite pre-pass. Try to get structured retrieval
+    // params from claude-proxy /rewrite first; fall through to the regex layers
+    // below on any failure (network, 422, invalid JSON, etc.). Rewrite tells us:
+    //   - intent (decision_recall | code_locator | general)
+    //   - since/until in user's LOCAL date space — converted to UTC ISO here
+    //   - expanded_query — fed to BM25 instead of the raw query for better recall
+    //
+    // codeOnly is an explicit caller override that beats the rewrite's intent
+    // (intel_analyst handles its own routing). The rewrite still informs
+    // since/until and expanded_query in that case.
+    const rewrite = query && !codeOnly ? await rewriteQueryViaProxy(query) : null;
+    const intent = codeOnly
+        ? "code_locator"
+        : (rewrite?.intent ?? (query ? classifyIntent(query) : "general"));
+    const { knowledgeBoost, filterSourceTypes } = paramsForIntent(intent, codeOnly);
+    // codeOnly forces zero half-life regardless of intent — explicit caller
+    // override beats heuristic intent. Otherwise pick from the per-intent table.
+    const halfLifeDays = codeOnly ? 0 : HALF_LIFE_DAYS_BY_INTENT[intent];
+    // Temporal: prefer Haiku's local-date interval (converted to UTC ISO) when
+    // available; otherwise fall back to the v0.7.7 regex pre-pass. The rewrite
+    // path handles a wider range of phrasings ("two Fridays ago", "since the
+    // restructure last quarter" — Haiku's call) AND uses the user's actual
+    // local timezone for "today / yesterday / this week" math, which the regex
+    // path computes in UTC and gets wrong near midnight.
+    const temporal = rewrite
+        ? rewriteTemporalToUTC(rewrite)
+        : query
+            ? resolveTemporalFilters(query)
+            : { since: null, until: null, matchedPhrase: null };
+    if (temporal.matchedPhrase) {
+        console.error(`becki-mcp: temporal filter matched '${temporal.matchedPhrase}' → ` +
+            `since=${temporal.since} until=${temporal.until}`);
+    }
+    // pp_user_id is REQUIRED post-migration 027 — match_vault_v4's COALESCE
+    // (pp_user_id, auth.uid()) returns NULL for anon callers without it,
+    // which yields zero rows. We read user_id from the file Becki.app writes
+    // alongside the install token. If we don't have it, the call would be a
+    // wasted round-trip — short-circuit with a clear error so the host (Claude
+    // Desktop, Cursor) knows to prompt the user to launch + sign in to Becki.
+    const userId = currentUserId();
+    if (!userId) {
+        throw new Error("becki: no user_id available — open Becki.app and sign in once to register this device. " +
+            "(Vault search requires per-user scoping after the v0.7 security fix.)");
+    }
+    // v1.x: use match_vault_v5 (resolution-aware) when available. v5 is a
+    // strict superset of v4 — same params + new optional pp_resolution_filter,
+    // new returned consolidation_level column. The "resolution_intent" Haiku
+    // returned drives this:
+    //   - "atomic"  → user wants specific items (recall query)
+    //   - "project" → user wants synthesis (high-level / "what's X about" query)
+    //   - "auto" or undefined → no filter; v5 mixes synthesis + atomic with
+    //     the small synthesis boost letting them edge out at similar scores.
+    const resolutionFilter = rewrite?.resolution_intent === "atomic"
+        ? "atomic"
+        : rewrite?.resolution_intent === "project"
+            ? "project"
+            : null;
+    const url = `${SUPABASE_URL}/rest/v1/rpc/match_vault_v5`;
+    // BM25 input: prefer Haiku's expanded_query (fills in pronouns + ambiguous
+    // references), fall through to the raw query otherwise. relaxSlugQuery
+    // still applies — it handles the slug-shaped-input phrase-query bug, which
+    // is orthogonal to semantic expansion.
+    const queryTextForBm25 = stripObligationPun(relaxSlugQuery(rewrite?.expanded_query ?? query ?? ""), query ?? "");
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            apikey: SUPABASE_ANON_KEY,
+            Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+            "Content-Profile": "becki",
+        },
+        body: JSON.stringify({
+            pp_query_embedding: embedding,
+            pp_query_text: queryTextForBm25,
+            pp_match_threshold: MATCH_THRESHOLD,
+            pp_match_count: limit,
+            pp_filter_source_types: filterSourceTypes,
+            // v0.7.8: Haiku may identify a project slug; pass it through. Swift
+            // app does its own AppState-aware project inference and would set
+            // this from there. Either path is exclusive at the call site.
+            pp_filter_project_id: rewrite?.project ?? null,
+            pp_knowledge_boost: knowledgeBoost,
+            pp_candidate_pool: 60,
+            pp_include_resolved: false,
+            pp_recency_half_life_days: halfLifeDays,
+            pp_since: temporal.since,
+            pp_until: temporal.until,
+            pp_recency_floor: 0.1,
+            pp_user_id: userId,
+            pp_resolution_filter: resolutionFilter,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Supabase RPC error ${res.status}: ${body}`);
+    }
+    const raw = (await res.json());
+    const chunks = raw.map((c) => ({ ...c, similarity: Math.min(1.0, c.similarity / RRF_CEILING) }));
+    // v0.7.5: synapse-firing viz broadcast. Fire-and-forget — failures
+    // here NEVER fail the query. The viz subscribes to the same channel
+    // and animates the matching nodes. Tagged source: 'mcp' so the viz
+    // tints with the lime accent (vs indigo for app-side queries).
+    void broadcastQueryEvent({
+        queryText: query ?? '',
+        chunks,
+        source: 'mcp',
+        tool: 'becki_context',
+    });
+    return chunks;
+}
+/**
+ * v0.7.5 — synapse-firing viz broadcast.
+ *
+ * Sends an ephemeral Realtime broadcast to channel "vault-queries:{user_id}"
+ * announcing which chunks the latest query touched. The NeuraVault viz
+ * subscribes + animates the matching nodes (lime tint for MCP-triggered,
+ * indigo for app-triggered).
+ *
+ * Uses Supabase Realtime's HTTP broadcast endpoint — no websocket required
+ * on the becki-mcp side, so we don't pull supabase-js as a dep just for
+ * this. The endpoint accepts apikey + JSON body; auth is the anon key
+ * (per-user scoping happens via the channel name including user_id).
+ *
+ * Best-effort: never throws to caller. The query itself already returned
+ * by the time this runs.
+ */
+async function broadcastQueryEvent(args) {
+    const userId = currentUserId();
+    if (!userId)
+        return;
+    try {
+        const payload = {
+            query_text: args.queryText.slice(0, 200),
+            source: args.source,
+            tool: args.tool,
+            chunks: args.chunks.map((c) => ({
+                source_type: c.source_type,
+                source_id: c.source_id,
+                similarity: c.similarity,
+            })),
+            ts: new Date().toISOString(),
+        };
+        const url = `${SUPABASE_URL}/realtime/v1/api/broadcast`;
+        await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'apikey': SUPABASE_ANON_KEY,
+                'Authorization': `Bearer ${SUPABASE_ANON_KEY}`,
+            },
+            body: JSON.stringify({
+                messages: [{
+                        topic: `vault-queries:${userId}`,
+                        event: 'query',
+                        payload,
+                        private: false,
+                    }],
+            }),
+        });
+        // Don't read the response. The endpoint returns 202 for queued sends;
+        // we don't care about deliverability — viz is best-effort UX, not a
+        // transactional signal.
+    }
+    catch (err) {
+        // Swallow — never propagate.
+        console.error('broadcastQueryEvent failed (non-fatal):', err);
+    }
+}
+/**
+ * If the strongest chunk in a retrieval batch is still weak, prepend a
+ * warning the downstream LLM can respect. This is the single most
+ * important retrieval-hardening knob — without it, an LLM given a
+ * low-similarity chunk will pad the gap with training-data hallucination
+ * and produce a confident wrong answer. With it, a well-behaved agent
+ * degrades to "I don't know — this may not be in the vault."
+ *
+ * Returns empty string when confidence is fine; otherwise a multi-line
+ * warning block terminated by a separator line.
+ */
+/**
+ * Pull a leading YYYY-MM-DD out of a source_id when present.
+ * Becki's ingest writes source_ids like
+ * "2026-04-25-positioning-shift-vs-littlebird" for decisions/dead_ends/etc.
+ * Returns "" if no leading date is found.
+ */
+function dateFromSourceId(source_id) {
+    if (!source_id)
+        return "";
+    const m = source_id.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m ? m[1] : "";
+}
+/**
+ * One-line confidence bar. Replaces the multi-paragraph warning when
+ * top similarity ≥ threshold; below threshold we still want the loud
+ * warning so the LLM doesn't confabulate.
+ */
+function renderConfidenceLine(top) {
+    const filled = Math.max(0, Math.min(12, Math.round(top * 12)));
+    const bar = "█".repeat(filled) + "░".repeat(12 - filled);
+    const label = top >= 0.7 ? "high" : top >= CONFIDENCE_THRESHOLD ? "medium" : "low";
+    return `Confidence: ${bar} ${top.toFixed(2)} (${label})`;
+}
+/**
+ * Quote a chunk body with a left bar (│ ) on every line. Reads as
+ * a clean blockquote in monospace renderers (Claude Code terminal,
+ * Cursor MCP panel, etc.).
+ */
+function quoteBody(content) {
+    return content
+        .split("\n")
+        .map((l) => (l.length === 0 ? "│" : `│ ${l}`))
+        .join("\n");
+}
+function retrievalConfidenceWarning(chunks) {
+    if (chunks.length === 0)
+        return "";
+    const top = chunks[0]?.similarity ?? 0;
+    if (top >= CONFIDENCE_THRESHOLD)
+        return "";
+    const pct = Math.round(top * 100);
+    return [
+        "⚠ No high-confidence match in Becki's vault.",
+        `Best similarity: ${pct}% (threshold for confidence: ${Math.round(CONFIDENCE_THRESHOLD * 100)}%).`,
+        "Treat the chunks below as weak leads, not ground truth.",
+        "If answering the user's question requires definitive facts you do not",
+        "see stated explicitly in the chunks below, prefer \"I don't know — this",
+        "may not be in Becki's vault\" over confabulating from your training data.",
+        "───────────────────────────────────────────────────────────────",
+        "",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Core query — text → embedding → pgvector → formatted context
+// ---------------------------------------------------------------------------
+/**
+ * Render a single chunk's header line. Code chunks get file:lines:symbol
+ * if metadata is present; other chunks just show source_type.
+ */
+function renderChunkHeader(chunk, idx) {
+    const pct = Math.round(chunk.similarity * 100);
+    const md = chunk.metadata;
+    // Code chunks keep the file:line:symbol format — that's the
+    // identifier developers actually want for "where is X".
+    if (chunk.source_type === "code" && md && md.file) {
+        const range = md.line_start != null && md.line_end != null
+            ? `:${md.line_start}-${md.line_end}`
+            : "";
+        const sym = md.symbol ? ` · ${md.symbol}` : "";
+        const proj = md.project_name ? ` [${md.project_name}]` : "";
+        // v0.7.5: rank prefix on every header (not just non-code) so the
+        // synthesis-ordering instruction has a stable reference. "[1]" =
+        // most-recent-best-match, [N] = lowest. Code chunks rank too because
+        // newer commits should usually beat older ones for the same file.
+        return `[${idx}] code${proj} ${md.file}${range}${sym} (${pct}% match)`;
+    }
+    // v1.x: synthesis rows get a distinctive header. Detection is via
+    // metadata.synthesis_kind — the consolidate-vault edge function writes
+    // this when generating project/cluster/career-level summaries.
+    // Synthesis rows are returned alongside atomic rows by match_vault_v4;
+    // they bubble up naturally because they're embedded the same way.
+    // The distinctive header tells the consuming LLM: "this is the high-
+    // level synthesis answer, not a raw item — lead with this when the
+    // query is high-level/synthesis-shaped."
+    if (md?.synthesis_kind) {
+        const kindLabel = md.synthesis_kind === "project_level"
+            ? "PROJECT SYNTHESIS"
+            : md.synthesis_kind === "cluster_level"
+                ? "CLUSTER SYNTHESIS"
+                : md.synthesis_kind === "career_level"
+                    ? "CAREER SYNTHESIS"
+                    : "SYNTHESIS";
+        const sourceCount = md.synthesis_atomic_count
+            ? ` · derived from ${md.synthesis_atomic_count} atomic items`
+            : "";
+        const projTag = md.project_name ? ` [${md.project_name}]` : "";
+        const idLine = chunk.id ? `\n  row_id: ${chunk.id}` : "";
+        // Star prefix instead of diamond — synthesis rows are visually distinct
+        // so a downstream LLM scanning the result block immediately spots them.
+        return `★ ${kindLabel}${projTag}${sourceCount}    (${pct}% match)${idLine}`;
+    }
+    // Knowledge chunks (decision / dead_end / commitment / open_loop /
+    // note) get a labeled diamond header. Date is parsed from source_id
+    // when present — Becki's ingest writes "YYYY-MM-DD-slug" filenames.
+    const date = dateFromSourceId(chunk.source_id);
+    const label = SOURCE_LABELS[chunk.source_type] ?? chunk.source_type.toUpperCase();
+    const dateSuffix = date ? ` · ${date}` : "";
+    // v0.7.5: surface row UUID so agents can call becki_resolve. Two-line
+    // format: human-readable header + machine-extractable id line that's
+    // easy to grep ("row_id: <uuid>" prefix is stable + unique).
+    const idLine = chunk.id ? `\n  row_id: ${chunk.id}` : "";
+    return `◆ ${label}${dateSuffix}    (${pct}% match)${idLine}`;
+}
+const SOURCE_LABELS = {
+    decision: "DECISION",
+    dead_end: "DEAD END",
+    commitment: "COMMITMENT",
+    open_loop: "OPEN LOOP",
+    note: "NOTE",
+    meeting: "MEETING",
+    commit: "COMMIT",
+};
+async function queryVault(query, codeOnly = false) {
+    // Cap query length to avoid wasting embedding tokens
+    const queryText = query.slice(0, 4000);
+    // #168 step 2: anchor the embedding on obligation vocabulary when an idiom
+    // fires, so the vector search stops pulling cross-project "plate" content.
+    // queryText itself stays raw (BM25 + display).
+    const embedding = await generateEmbedding(canonicalizeObligationIdiom(queryText), "query");
+    // Pass `query` so matchChunks can route via the heuristic intent classifier
+    // (decision_recall vs code_locator vs general) and apply the right
+    // knowledge_boost on the v0.4 match_vault_v2 RPC.
+    const chunks = await matchChunks(embedding, MATCH_COUNT, codeOnly, queryText);
+    // v1.x: dead-end pattern recognition (Path B — at-query-time). Runs in
+    // PARALLEL with the main retrieval, never blocks it. Code-only queries
+    // skip this lane (code_locator intent has no use for dead-end warnings).
+    // See: decisions/2026-05-10-dead-end-pattern-recognition-path-b-at-query-time-not-contin.md
+    const deadEndWarningsPromise = codeOnly
+        ? Promise.resolve([])
+        : surfaceDeadEnds(queryText, embedding).catch((err) => {
+            // Best-effort — never propagate. Dead-end surface is OPTIONAL context.
+            console.error("[dead-end] surface failed (non-fatal):", err instanceof Error ? err.message : err);
+            return [];
+        });
+    // v1.x Lane 3 (Path C): project-synthesis surfacing. Direct SQL lookup
+    // (NOT embedding similarity) for the project's consolidated narrative
+    // when Haiku /rewrite identifies a project_name slug. Synthesis is a
+    // project ATTRIBUTE, not a haystack item — it surfaces deterministically
+    // when project intent is detected, regardless of query phrasing.
+    // The /rewrite call here hits the same 24h per-user cache that matchChunks
+    // hit moments ago — second call is free. Skip for code-only queries
+    // (intent is finding code, not project gestalt).
+    const projectSynthesisPromise = codeOnly
+        ? Promise.resolve(null)
+        : surfaceProjectSynthesis(queryText).catch((err) => {
+            console.error("[lane3] synthesis surface failed (non-fatal):", err instanceof Error ? err.message : err);
+            return null;
+        });
+    // v1.x Lane 4: career-level synthesis surfacing. Same Path C mechanism
+    // at user scope (no project filter). Fires when Haiku classifies
+    // resolution_intent='career' — meta-questions about working patterns
+    // ("how do I tend to handle X" / "what's my pattern with Y").
+    // Skip for code-only queries.
+    const careerSynthesisPromise = codeOnly
+        ? Promise.resolve(null)
+        : surfaceCareerSynthesis(queryText).catch((err) => {
+            console.error("[lane4] synthesis surface failed (non-fatal):", err instanceof Error ? err.message : err);
+            return null;
+        });
+    // Rung 2.5 Lane 5: deterministic commitments ledger. Fires only on a local
+    // obligation/status heuristic (no LLM). Parallel, never blocks retrieval.
+    const commitmentLedgerPromise = codeOnly
+        ? Promise.resolve(null)
+        : surfaceCommitmentLedger(queryText).catch((err) => {
+            console.error("[lane5] ledger surface failed (non-fatal):", err instanceof Error ? err.message : err);
+            return null;
+        });
+    // Lane 6: decision reasoning graph. Fires only on a local "why did we decide"
+    // intent heuristic (no LLM). Parallel, never blocks retrieval.
+    const decisionReasoningPromise = codeOnly
+        ? Promise.resolve(null)
+        : surfaceDecisionReasoning(queryText).catch((err) => {
+            console.error("[lane6] decision-reasoning surface failed (non-fatal):", err instanceof Error ? err.message : err);
+            return null;
+        });
+    if (chunks.length === 0) {
+        // Even with zero main-retrieval chunks, surface dead-ends OR project
+        // synthesis OR career synthesis if any were found — all useful context
+        // on their own. Wait for parallel calls.
+        const [earlyWarnings, earlyProjectSynth, earlyCareerSynth, earlyLedger, earlyDecisionReasoning] = await Promise.all([
+            deadEndWarningsPromise,
+            projectSynthesisPromise,
+            careerSynthesisPromise,
+            commitmentLedgerPromise,
+            decisionReasoningPromise,
+        ]);
+        const scope = codeOnly ? "code" : "vault";
+        if (earlyWarnings.length === 0 && !earlyProjectSynth && !earlyCareerSynth && !earlyLedger && !earlyDecisionReasoning) {
+            return `NeuraVault: no relevant ${scope} context found for this query. The vault may be empty or no chunks matched the similarity threshold. Do not confabulate from training data — tell the user you don't have this in Becki's memory.`;
+        }
+        const lines = [];
+        lines.push(`NeuraVault: no atomic ${scope} matches — surfacing synthesis + warnings:`);
+        lines.push("");
+        if (earlyLedger)
+            lines.push(...renderCommitmentLedgerSection(earlyLedger));
+        if (earlyDecisionReasoning)
+            lines.push(...renderDecisionReasoningSection(earlyDecisionReasoning));
+        if (earlyCareerSynth)
+            lines.push(...renderCareerSynthesisSection(earlyCareerSynth));
+        if (earlyProjectSynth)
+            lines.push(...renderProjectSynthesisSection(earlyProjectSynth));
+        if (earlyWarnings.length > 0)
+            lines.push(...renderDeadEndSection(earlyWarnings));
+        return lines.join("\n").trim();
+    }
+    const label = codeOnly ? "code context" : "context";
+    const top = chunks[0]?.similarity ?? 0;
+    const confidenceWarning = retrievalConfidenceWarning(chunks);
+    const lines = [];
+    lines.push("Querying NeuraVault…");
+    lines.push("");
+    if (confidenceWarning) {
+        lines.push(confidenceWarning);
+        lines.push("");
+    }
+    lines.push(`Relevant ${label} from NeuraVault (${chunks.length} chunk${chunks.length === 1 ? "" : "s"}):`, "");
+    // v0.7.5: synthesis-ordering instruction. The chunks are returned in
+    // recency-weighted retrieval rank order (match_vault_v4's combined
+    // similarity × recency-half-life-decay × type-anchor score). Chunk [1]
+    // is the BEST-MATCHING-AND-MOST-RECENT relevant chunk for this query.
+    // Without this hint, downstream LLMs sometimes synthesize the narrative
+    // from whichever chunk is most verbose — even if it's older + describes
+    // a superseded approach. The "we recently switched to per-process Process
+    // Tap" failure (Bryan, 2026-05-04: AI summarized v0.5.7 architecture
+    // when the user asked about a v0.7.4 change) was exactly this shape.
+    lines.push("When synthesizing an answer, LEAD with chunk [1] — it is the most", "recent + best-matching chunk. Only reference older chunks (lower in", "this list) to provide background or to show evolution; do NOT let an", "older chunk's verbosity dominate the narrative if a more recent chunk", "describes the current state. If the user asked about \"recent\",", "\"latest\", or \"current\", base the answer on chunk [1] specifically.", "");
+    for (let i = 0; i < chunks.length; i++) {
+        const chunk = chunks[i];
+        lines.push(renderChunkHeader(chunk, i + 1));
+        lines.push(quoteBody(chunk.content));
+        lines.push("");
+    }
+    // One-line confidence summary at the bottom — easy to spot, easy to
+    // visually parse. Distinct from the loud paragraph warning, which
+    // only fires below CONFIDENCE_THRESHOLD.
+    lines.push(renderConfidenceLine(top));
+    // v1.x: dead-end warnings, if any. Rendered AFTER the main retrieval
+    // so the model has full context first; placement at the END means
+    // warnings are read last and stay top-of-mind during synthesis.
+    const [deadEndWarnings, projectSynthesis, careerSynthesis, commitmentLedger, decisionReasoning] = await Promise.all([
+        deadEndWarningsPromise,
+        projectSynthesisPromise,
+        careerSynthesisPromise,
+        commitmentLedgerPromise,
+        decisionReasoningPromise,
+    ]);
+    // v1.x Lanes 3 + 4 + Rung 2.5 Lane 5: lead blocks inserted at the VERY TOP
+    // of the response (before atomic chunks) so the consuming LLM reads them
+    // first as framing. Atomic chunks become supporting detail underneath.
+    // unshift order is reverse of display order — whatever is unshifted LAST
+    // ends up on top. Display order top→bottom: ledger (the exhaustive fact for
+    // obligation queries) → career → project → atomic chunks.
+    if (careerSynthesis) {
+        lines.unshift(...renderCareerSynthesisSection(careerSynthesis), "");
+    }
+    if (projectSynthesis) {
+        lines.unshift(...renderProjectSynthesisSection(projectSynthesis), "");
+    }
+    if (commitmentLedger) {
+        lines.unshift(...renderCommitmentLedgerSection(commitmentLedger), "");
+    }
+    // Decision reasoning unshifted last → sits on top for "why did we decide" queries.
+    if (decisionReasoning) {
+        lines.unshift(...renderDecisionReasoningSection(decisionReasoning), "");
+    }
+    if (deadEndWarnings.length > 0) {
+        lines.push("");
+        lines.push(...renderDeadEndSection(deadEndWarnings));
+    }
+    return lines.join("\n").trim();
+}
+async function surfaceProjectSynthesis(query) {
+    const userId = currentUserId();
+    if (!userId)
+        return null;
+    // Reuse the Haiku rewrite — second call hits the 24h per-user cache, so
+    // the latency cost is sub-50ms vs the original ~1500ms first call.
+    const rewrite = await rewriteQueryViaProxy(query);
+    if (!rewrite || !rewrite.project)
+        return null;
+    // Direct RPC lookup — no embedding similarity. The migration 039 RPC
+    // get_project_synthesis takes p_user_id (install-token scoped) and
+    // p_project_name (the slug Haiku returned).
+    const url = `${SUPABASE_URL}/rest/v1/rpc/get_project_synthesis`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                apikey: SUPABASE_ANON_KEY,
+                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({
+                p_user_id: userId,
+                p_project_name: rewrite.project,
+            }),
+        });
+    }
+    catch (err) {
+        console.error("[lane3] get_project_synthesis fetch failed:", err instanceof Error ? err.message : err);
+        return null;
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[lane3] get_project_synthesis ${res.status}: ${body.slice(0, 200)}`);
+        return null;
+    }
+    const rows = (await res.json());
+    return rows.length > 0 ? rows[0] : null;
+}
+function renderProjectSynthesisSection(row) {
+    const md = row.metadata ?? {};
+    const projectName = md.project_name ?? "(unnamed project)";
+    const sourceCount = row.source_count ?? 0;
+    const generatedAt = row.consolidated_at?.slice(0, 10) ?? "";
+    const ageNote = generatedAt ? ` · synthesized ${generatedAt}` : "";
+    const lines = [];
+    lines.push(`★ PROJECT SYNTHESIS [${projectName}] · derived from ${sourceCount} atomic items${ageNote}`);
+    lines.push(`  row_id: ${row.id}`);
+    lines.push("");
+    lines.push("This is the curated project-level summary. Lead with this for any high-");
+    lines.push("level question about the project. Atomic items below are supporting detail.");
+    lines.push("");
+    lines.push(row.content);
+    return lines;
+}
+async function surfaceCareerSynthesis(query) {
+    const userId = currentUserId();
+    if (!userId)
+        return null;
+    // Reuse the cached Haiku rewrite — second call hits 24h per-user cache.
+    const rewrite = await rewriteQueryViaProxy(query);
+    if (!rewrite || rewrite.resolution_intent !== "career")
+        return null;
+    // Direct RPC lookup — no embedding similarity. The migration 040 RPC
+    // get_career_synthesis takes p_user_id (install-token scoped) only.
+    const url = `${SUPABASE_URL}/rest/v1/rpc/get_career_synthesis`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                apikey: SUPABASE_ANON_KEY,
+                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({ p_user_id: userId }),
+        });
+    }
+    catch (err) {
+        console.error("[lane4] get_career_synthesis fetch failed:", err instanceof Error ? err.message : err);
+        return null;
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[lane4] get_career_synthesis ${res.status}: ${body.slice(0, 200)}`);
+        return null;
+    }
+    const rows = (await res.json());
+    return rows.length > 0 ? rows[0] : null;
+}
+function renderCareerSynthesisSection(row) {
+    const md = row.metadata ?? {};
+    const projectCount = md.synthesis_project_count ?? 0;
+    const atomicCount = md.synthesis_recent_atomic_count ?? 0;
+    const generatedAt = row.consolidated_at?.slice(0, 10) ?? "";
+    const ageNote = generatedAt ? ` · synthesized ${generatedAt}` : "";
+    const lines = [];
+    lines.push(`🌐 CAREER PATTERNS · derived from ${projectCount} project syntheses + ${atomicCount} recent atomic items${ageNote}`);
+    lines.push(`  row_id: ${row.id}`);
+    lines.push("");
+    lines.push("This is the cross-project view of how the user works — preferences,");
+    lines.push("recurring dead-end patterns, vocabulary, current themes. Lead with this");
+    lines.push("for meta-questions about working style. Project + atomic context below.");
+    lines.push("");
+    lines.push(row.content);
+    return lines;
+}
+// Deterministic intent gate. Matches obligation/status phrasing only, so we
+// don't inject the ledger on unrelated queries. A false negative just means
+// normal retrieval still runs; a false positive only adds a little context.
+const LEDGER_INTENT_RE = /\b(owe|owed|owes|waiting on|waiting for|on my plate|outstanding|action items?|follow[\s-]?ups?|commitments?|open (?:asks?|items?|loops?|commitments?)|what (?:do|did) i (?:owe|need to do|promise|commit)|what(?:'?s| am i| are my)?\s+(?:waiting on|on my plate|due|open|outstanding|owed)|who owes me|my (?:tasks?|to-?dos?)|to-?do list|did i (?:promise|commit|agree))\b/i;
+function ledgerIntent(query) {
+    return LEDGER_INTENT_RE.test(query);
+}
+const LEDGER_RENDER_PER_BUCKET = 12;
+async function surfaceCommitmentLedger(query) {
+    const userId = currentUserId();
+    if (!userId)
+        return null;
+    if (!ledgerIntent(query))
+        return null;
+    const url = `${SUPABASE_URL}/rest/v1/rpc/commitment_ledger_v1`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                apikey: SUPABASE_ANON_KEY,
+                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({ pp_user_id: userId }),
+        });
+    }
+    catch (err) {
+        console.error("[lane5] commitment_ledger_v1 fetch failed:", err instanceof Error ? err.message : err);
+        return null;
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[lane5] commitment_ledger_v1 ${res.status}: ${body.slice(0, 200)}`);
+        return null;
+    }
+    const ledger = (await res.json());
+    const total = (ledger?.my_commitments?.length ?? 0) +
+        (ledger?.asks_of_me?.length ?? 0) +
+        (ledger?.waiting_on?.length ?? 0) +
+        (ledger?.dependencies?.length ?? 0);
+    return total > 0 ? ledger : null;
+}
+function renderLedgerItem(it) {
+    const who = it.counterparty ? ` → ${it.counterparty}` : "";
+    const deadline = it.deadline
+        ? ` · due ${it.deadline}${it.deadline_confidence && it.deadline_confidence !== "explicit" ? ` (${it.deadline_confidence})` : ""}`
+        : "";
+    const proj = it.project ? ` · ${it.project}` : "";
+    const age = Number.isFinite(it.age_days) ? ` · ${it.age_days}d old` : "";
+    return `  • ${it.text}${who}${deadline}${proj}${age}`;
+}
+function renderLedgerBucket(title, items, total) {
+    if (total === 0)
+        return [];
+    const shown = items.slice(0, LEDGER_RENDER_PER_BUCKET);
+    const lines = [`${title} (${total}):`];
+    for (const it of shown)
+        lines.push(renderLedgerItem(it));
+    const remaining = total - shown.length;
+    if (remaining > 0)
+        lines.push(`  …and ${remaining} more`);
+    lines.push("");
+    return lines;
+}
+function renderCommitmentLedgerSection(ledger) {
+    const c = ledger.counts ?? {};
+    const grand = (c.my_commitments ?? 0) + (c.asks_of_me ?? 0) + (c.waiting_on ?? 0) + (c.dependencies ?? 0);
+    const lines = [];
+    lines.push(`📋 ON YOUR PLATE · ${grand} open item${grand === 1 ? "" : "s"} (deterministic ledger — the COMPLETE set, not retrieval)`);
+    lines.push("");
+    lines.push("This is a relational walk over the user's tracked commitments, not a");
+    lines.push("similarity search. It is exhaustive for the buckets shown — when answering");
+    lines.push("\"what do I owe / what's owed to me / what am I waiting on\", trust these");
+    lines.push("counts as complete and do NOT supplement from the atomic chunks below.");
+    lines.push("");
+    lines.push(...renderLedgerBucket("YOU OWE / PROMISED", ledger.my_commitments, c.my_commitments ?? 0));
+    lines.push(...renderLedgerBucket("ASKED OF YOU (you owe a reply)", ledger.asks_of_me, c.asks_of_me ?? 0));
+    lines.push(...renderLedgerBucket("WAITING ON OTHERS", ledger.waiting_on, c.waiting_on ?? 0));
+    lines.push(...renderLedgerBucket("DEPENDENCIES", ledger.dependencies, c.dependencies ?? 0));
+    return lines;
+}
+const DECISION_INTENT_RE = /\b(why (?:did|do|'d|would|are|is|was|were)?\s*(?:we|i|you|they)\s+(?:decide|decided|chose|choose|pick|picked|go with|went with|reject|rule out|ruled out|avoid)|why not\b|why (?:we|i) (?:chose|decided|picked|went with|rejected|avoided)|rationale (?:for|behind)|reasoning behind|what (?:did|do) (?:we|i|you) (?:rule out|reject|decide against|consider)|what (?:were|are) (?:the|our|my) (?:options|alternatives|trade-?offs?)|alternatives? (?:we |i )?considered|decided against|ruled out|trade-?offs?\b)/i;
+function decisionIntent(query) {
+    return DECISION_INTENT_RE.test(query);
+}
+const DECISION_REASONING_LIMIT = 4;
+async function surfaceDecisionReasoning(query) {
+    const userId = currentUserId();
+    if (!userId)
+        return null;
+    if (!decisionIntent(query))
+        return null;
+    const url = `${SUPABASE_URL}/rest/v1/rpc/decision_reasoning_v1`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                apikey: SUPABASE_ANON_KEY,
+                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({ pp_user_id: userId, pp_query: query, pp_match_count: DECISION_REASONING_LIMIT }),
+        });
+    }
+    catch (err) {
+        console.error("[lane6] decision_reasoning_v1 fetch failed:", err instanceof Error ? err.message : err);
+        return null;
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[lane6] decision_reasoning_v1 ${res.status}: ${body.slice(0, 200)}`);
+        return null;
+    }
+    const rows = (await res.json());
+    return Array.isArray(rows) && rows.length > 0 ? rows : null;
+}
+function renderDecisionReasoningSection(rows) {
+    const lines = [];
+    lines.push(`🧭 DECISION REASONING · ${rows.length} matching decision${rows.length === 1 ? "" : "s"} (structured "why", not similarity retrieval)`);
+    lines.push("");
+    lines.push("The chosen path, the alternatives considered, and WHY each was rejected.");
+    lines.push("When the user asks \"why did we decide X / what did we rule out\", lead with");
+    lines.push("this — it is the structured record, not a fuzzy chunk match.");
+    lines.push("");
+    for (const r of rows) {
+        lines.push(`▸ ${r.title || r.chosen || "(decision)"}`);
+        if (r.chosen)
+            lines.push(`   chose: ${r.chosen}`);
+        if (r.rationale)
+            lines.push(`   why: ${r.rationale}`);
+        const opts = Array.isArray(r.options) ? r.options : [];
+        for (const o of opts.filter((o) => o.verdict === "rejected")) {
+            lines.push(`   ✗ rejected — ${o.label ?? "option"}: ${o.why ?? ""}`.trimEnd());
+        }
+        for (const o of opts.filter((o) => o.verdict === "considered")) {
+            lines.push(`   ◦ considered — ${o.label ?? "option"}: ${o.why ?? ""}`.trimEnd());
+        }
+        if (r.tradeoffs)
+            lines.push(`   tradeoff: ${r.tradeoffs}`);
+        lines.push("");
+    }
+    return lines;
+}
+const DEAD_END_CANDIDATE_LIMIT = 3;
+/** Top-level: returns warnings ready to render. Empty array on any failure. */
+async function surfaceDeadEnds(queryText, embedding) {
+    const userId = currentUserId();
+    if (!userId)
+        return [];
+    const candidates = await matchDeadEndCandidates(embedding, queryText, userId);
+    if (candidates.length === 0)
+        return [];
+    const evaluations = await evaluateDeadEndRelevance(queryText, candidates);
+    if (evaluations.length === 0)
+        return [];
+    const warnings = [];
+    for (const evaluation of evaluations) {
+        if (evaluation.decision === "suppress")
+            continue;
+        const candidate = candidates.find((c) => c.id === evaluation.id);
+        if (!candidate)
+            continue;
+        warnings.push({
+            id: candidate.id,
+            decision: evaluation.decision,
+            headline: evaluation.headline,
+            reason: evaluation.reason,
+            content: candidate.content,
+            agePhrase: formatAgePhrase(candidate.age_days),
+            resolved: candidate.resolved_at !== null || candidate.superseded_by !== null,
+        });
+    }
+    return warnings;
+}
+async function matchDeadEndCandidates(embedding, queryText, userId) {
+    const url = `${SUPABASE_URL}/rest/v1/rpc/match_dead_ends_v1`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                apikey: SUPABASE_ANON_KEY,
+                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({
+                pp_query_embedding: embedding,
+                pp_query_text: stripObligationPun(relaxSlugQuery(queryText), queryText),
+                pp_match_count: DEAD_END_CANDIDATE_LIMIT,
+                pp_user_id: userId,
+            }),
+        });
+    }
+    catch (err) {
+        console.error("[dead-end] match_dead_ends_v1 fetch failed:", err instanceof Error ? err.message : err);
+        return [];
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        console.error(`[dead-end] match_dead_ends_v1 RPC ${res.status}: ${body.slice(0, 200)}`);
+        return [];
+    }
+    try {
+        return (await res.json());
+    }
+    catch (err) {
+        console.error("[dead-end] match_dead_ends_v1 parse failed:", err instanceof Error ? err.message : err);
+        return [];
+    }
+}
+async function evaluateDeadEndRelevance(query, candidates) {
+    const token = cachedIngestToken;
+    if (!token)
+        return []; // no install token = MCP not registered yet
+    const endpoint = `${SUPABASE_URL}/functions/v1/claude-proxy/dead-end-evaluate`;
+    const body = {
+        query,
+        candidates: candidates.map((c) => ({
+            id: c.id,
+            content: c.content,
+            age_days: c.age_days,
+            resolved: c.resolved_at !== null || c.superseded_by !== null,
+        })),
+    };
+    // Hard-cap via AbortController — Haiku evaluation typically <2s; cap at
+    // 6s so a slow call can't stall the query response perceptibly. Same
+    // pattern as rewriteQueryViaProxy above so the AbortError telemetry is
+    // consistent.
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 6000);
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+            signal: ctrl.signal,
+        });
+    }
+    catch (err) {
+        if (err?.name === "AbortError") {
+            console.error("[dead-end] evaluator: timeout after 6000ms");
+        }
+        else {
+            console.error("[dead-end] evaluator fetch failed:", err instanceof Error ? err.message : err);
+        }
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!res.ok) {
+        if (res.status !== 422) {
+            const body = await res.text().catch(() => "");
+            console.error(`[dead-end] evaluator ${res.status}: ${body.slice(0, 200)}`);
+        }
+        return [];
+    }
+    try {
+        const envelope = (await res.json());
+        return Array.isArray(envelope.evaluations) ? envelope.evaluations : [];
+    }
+    catch (err) {
+        console.error("[dead-end] evaluator parse failed:", err instanceof Error ? err.message : err);
+        return [];
+    }
+}
+function formatAgePhrase(days) {
+    if (days <= 0)
+        return "today";
+    if (days === 1)
+        return "yesterday";
+    if (days < 14)
+        return `${days} days ago`;
+    if (days < 60)
+        return `about ${Math.round(days / 7)} weeks ago`;
+    if (days < 365)
+        return `about ${Math.round(days / 30)} months ago`;
+    const years = days / 365;
+    if (years < 1.5)
+        return "about a year ago";
+    return `over ${Math.floor(years)} years ago`;
+}
+/**
+ * Rendered as a distinct callout block in the becki_context output. The
+ * caller (Claude / Cursor / Zed via MCP) reads this as a heads-up section
+ * separate from the main retrieval results, so it stays top-of-mind during
+ * synthesis instead of being lost in the chunk list.
+ */
+function renderDeadEndSection(warnings) {
+    const lines = [];
+    const warns = warnings.filter((w) => w.decision === "warn");
+    const notes = warnings.filter((w) => w.decision === "footnote");
+    lines.push("⚠ PAST FAILURES RELEVANT TO THIS QUERY");
+    lines.push("(Becki's pattern recognition surfaces these to prevent repeating mistakes.)");
+    lines.push("");
+    for (const w of warns) {
+        const tag = w.resolved ? "(resolved)" : "(active warning)";
+        lines.push(`  ⚠ ${w.headline} — ${w.agePhrase} ${tag}`);
+        lines.push(`     why surfaced: ${w.reason}`);
+        lines.push(`     full: ${truncateForCallout(w.content, 280)}`);
+        lines.push("");
+    }
+    if (notes.length > 0) {
+        lines.push("  Soft mentions (you might also want to check):");
+        for (const w of notes) {
+            lines.push(`    · ${w.headline} — ${w.agePhrase}: ${w.reason}`);
+        }
+    }
+    return lines;
+}
+function truncateForCallout(text, max) {
+    const trimmed = text.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return trimmed.slice(0, max - 1).trimEnd() + "…";
+}
+async function listVaultRows(projectId, sinceISO, untilISO, types, limit) {
+    // p_user_id is REQUIRED post-migration 028 — same fix pattern as
+    // match_vault_v4 (migration 027). Anon callers without it get zero rows.
+    // p_until added in migration 029 for v0.7.5 time-window queries — pass
+    // null when the caller didn't supply an upper bound.
+    const userId = currentUserId();
+    if (!userId) {
+        throw new Error("becki: no user_id available — open Becki.app and sign in once to register this device. " +
+            "(Vault listing requires per-user scoping after the v0.7 security fix.)");
+    }
+    const url = `${SUPABASE_URL}/rest/v1/rpc/list_vault_rows`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            apikey: SUPABASE_ANON_KEY,
+            Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+            "Content-Profile": "becki",
+        },
+        body: JSON.stringify({
+            p_project_id: projectId ?? null,
+            p_since: sinceISO ?? null,
+            p_until: untilISO ?? null,
+            p_types: types && types.length > 0 ? types : null,
+            p_limit: limit,
+            p_user_id: userId,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`list_vault_rows RPC error ${res.status}: ${body.slice(0, 300)}`);
+    }
+    return (await res.json());
+}
+async function resolveVaultRow(rowId, supersededBy, note) {
+    // v0.7.5: pp_user_id is REQUIRED post-migration 031 — same fix-shape as
+    // match_vault_v4 (027) and list_vault_rows (028). The install-token call
+    // path authenticates with the anon key (auth.uid() returns NULL); without
+    // an explicit user_id the SECURITY DEFINER function falls through to the
+    // NULL-return branch and the resolve silently no-ops, indistinguishable
+    // from "row not found." This was the bug Bryan hit on 2026-05-05.
+    const userId = currentUserId();
+    if (!userId) {
+        throw new Error("becki: no user_id available — open Becki.app and sign in once to register this device. " +
+            "(Vault resolution requires per-user scoping after the v0.7.5 security fix.)");
+    }
+    // Two RPCs to choose between: supersede_vault_row when a newer row
+    // takes the older one's place; resolve_vault_row for plain "done."
+    const isSupersession = !!supersededBy;
+    const rpcName = isSupersession ? "supersede_vault_row" : "resolve_vault_row";
+    const body = isSupersession
+        ? {
+            pp_old_row_id: rowId,
+            pp_new_row_id: supersededBy,
+            pp_resolved_by: "agent",
+            pp_note: note ?? null,
+            pp_user_id: userId,
+        }
+        : {
+            pp_row_id: rowId,
+            pp_resolved_by: "agent",
+            pp_note: note ?? null,
+            pp_user_id: userId,
+        };
+    const url = `${SUPABASE_URL}/rest/v1/rpc/${rpcName}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+            apikey: SUPABASE_ANON_KEY,
+            Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
+            "Content-Profile": "becki",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const errBody = await res.text();
+        throw new Error(`${rpcName} error ${res.status}: ${errBody.slice(0, 300)}`);
+    }
+    const rows = (await res.json());
+    if (!rows || rows.length === 0) {
+        throw new Error(`Row ${rowId} not found, not owned by the calling user, or RLS denied the update.`);
+    }
+    return {
+        status: isSupersession ? "superseded" : "resolved",
+        row_id: rows[0].id,
+        superseded_by: supersededBy,
+        note: note ?? undefined,
+    };
+}
+function formatListResults(rows, projectId, sinceISO, untilISO, types) {
+    if (rows.length === 0) {
+        const scope = [];
+        if (projectId)
+            scope.push(`project=${projectId}`);
+        if (sinceISO)
+            scope.push(`since=${sinceISO}`);
+        if (untilISO)
+            scope.push(`until=${untilISO}`);
+        if (types && types.length > 0)
+            scope.push(`types=${types.join(",")}`);
+        const scopeStr = scope.length > 0 ? ` (${scope.join(", ")})` : "";
+        return `No vault rows found${scopeStr}. This is a definitive answer — the vault has nothing matching. Do not invent history.`;
+    }
+    const header = [`NeuraVault listing — ${rows.length} row${rows.length === 1 ? "" : "s"}`];
+    if (projectId)
+        header.push(`  project: ${projectId}`);
+    if (sinceISO)
+        header.push(`  since:   ${sinceISO}`);
+    if (untilISO)
+        header.push(`  until:   ${untilISO}`);
+    if (types && types.length > 0)
+        header.push(`  types:   ${types.join(", ")}`);
+    header.push("");
+    const lines = [...header];
+    for (let i = 0; i < rows.length; i++) {
+        const r = rows[i];
+        const date = r.created_at.slice(0, 10);
+        const md = r.metadata;
+        const projLabel = md?.project_name ? ` [${md.project_name}]` : "";
+        lines.push(`[${i + 1}] ${date} · ${r.source_type}${projLabel}`);
+        lines.push(r.content);
+        lines.push("");
+    }
+    return lines.join("\n").trim();
+}
+async function lookupSymbols(query, projectId, limit = 20, timeoutMs = 1500) {
+    const params = new URLSearchParams({ q: query, limit: String(limit) });
+    if (projectId)
+        params.set("project", projectId);
+    const url = `${BECKI_IPC_URL}/symbols?${params.toString()}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok)
+            return [];
+        const body = (await res.json());
+        return Array.isArray(body) ? body : [];
+    }
+    catch {
+        // Becki app not running / IPC port not listening — degrade silently.
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Answer a code query: try exact-symbol match via IPC first, then fall back
+ * to code-scoped semantic search. Callers see one combined, formatted answer.
+ */
+async function queryCodeContext(query, projectId) {
+    // 1. Symbol-table exact / fuzzy match — fast, authoritative for
+    //    "where is validateToken" type queries. Symbol hits are
+    //    high-confidence by construction (exact/fuzzy name match from a
+    //    GRDB-indexed table), so when we get any, the confidence-warning
+    //    logic doesn't apply to them.
+    const symbols = await lookupSymbols(query, projectId, 10);
+    const lines = [];
+    if (symbols.length > 0) {
+        lines.push(`Symbol index hits (${symbols.length}):`, ...symbols.map((s) => `  ${s.filePath}:${s.lineStart}-${s.lineEnd} — ${s.symbolName} (${s.symbolKind})`), "");
+    }
+    // 2. Semantic search, code-only. queryVault already handles the
+    //    confidence warning + no-results wording, so just inline its
+    //    return value.
+    try {
+        const semantic = await queryVault(query, true);
+        lines.push(semantic);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (symbols.length === 0) {
+            return `Code search failed: ${message}`;
+        }
+        lines.push(`(Semantic search unavailable: ${message})`);
+    }
+    return lines.join("\n").trim();
+}
+// ---------------------------------------------------------------------------
+// launch_neuravault — tell the Becki.app to open the WKWebView window.
+// The visualization itself is served from https://www.becki.io/viz, so
+// there's nothing to boot locally. If Becki.app isn't running we can't
+// open the window on the user's behalf — return a clear message.
+// ---------------------------------------------------------------------------
+async function isUp(url, timeoutMs = 1000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        await fetch(url, { signal: controller.signal });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function notifyBeckiApp() {
+    if (!(await isUp(`${BECKI_IPC_URL}/status`, 500))) {
+        return { ok: false, detail: "Becki app IPC listener not running on :9876" };
+    }
+    try {
+        const res = await fetch(`${BECKI_IPC_URL}/open-neuravault`, {
+            method: "POST",
+        });
+        if (!res.ok)
+            return { ok: false, detail: `IPC POST ${res.status}` };
+        return { ok: true, detail: "window opened in Becki" };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+const VAULT_ROOT = join(homedir(), "Documents", "Becki");
+function todayStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+function toSlug(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60);
+}
+function ensureDir(p) {
+    mkdirSync(p, { recursive: true });
+}
+/** A clean one-line headline for an open-loop / commitment checklist entry
+ *  in `_meta/open-loops.md`. Prefers the caller-supplied title (de-slugified
+ *  when it looks like a kebab-case slug); falls back to the first sentence of
+ *  the content. Dumping the whole content as the checklist line made the file
+ *  unreadable — Becki Shell surfaced paragraph fragments as thread names. */
+function openLoopHeadline(title, content) {
+    const trunc = (s, n) => s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s;
+    const t = (title || "").trim();
+    if (t) {
+        // "becki-mcp-use-claude" → "becki mcp use claude" — slugs read badly as
+        // a checklist headline; spaces are kinder.
+        const text = /^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(t) ? t.replace(/-/g, " ") : t;
+        return trunc(text.charAt(0).toUpperCase() + text.slice(1), 96);
+    }
+    const firstLine = content.trim().split("\n").find((l) => l.trim()) ?? "";
+    const sentence = firstLine.split(/(?<=[.!?])\s/)[0] || firstLine;
+    return trunc(sentence.trim(), 96);
+}
+function writeVaultFile(type, content, project, title) {
+    const date = todayStr();
+    const slug = title ? toSlug(title) : toSlug(content.slice(0, 40));
+    const now = new Date().toLocaleTimeString("en-US", { hour12: false, hour: "2-digit", minute: "2-digit" });
+    // Path-traversal guard: the `project` argument is user-controlled and
+    // gets join()'d into the vault path. Slug it first so "../../etc"
+    // becomes "etc" and can never escape the vault root.
+    const projectSlug = project ? toSlug(project) : undefined;
+    if (type === "decision") {
+        const dir = join(VAULT_ROOT, "decisions");
+        ensureDir(dir);
+        const fileName = `${date}-${slug}.md`;
+        const path = join(dir, fileName);
+        const heading = title || slug;
+        const body = [
+            `# Decision: ${heading}`,
+            `**Date:** ${date}`,
+            `**Status:** Locked`,
+            `**Source:** Claude.ai / Claude Code (MCP)`,
+            "",
+            "## What was decided",
+            content,
+        ].join("\n");
+        writeFileSync(path, body, "utf8");
+        if (projectSlug) {
+            const projFile = join(VAULT_ROOT, "projects", projectSlug, "becki.md");
+            if (existsSync(projFile)) {
+                appendFileSync(projFile, `\n\n## Recent Decisions\n- ${date}: ${heading}\n`, "utf8");
+            }
+        }
+        return path;
+    }
+    if (type === "commitment" || type === "open_loop") {
+        const dir = join(VAULT_ROOT, "_meta");
+        ensureDir(dir);
+        const path = join(dir, "open-loops.md");
+        // The checklist line is a clean title — matching the meeting-extracted
+        // loops already in this file. The full content is kept as an indented
+        // detail block so the local file stays a complete record; retrieval
+        // uses the embedded cloud row regardless.
+        const headline = openLoopHeadline(title, content);
+        const tag = type === "commitment" ? "commitment" : "open loop";
+        const projTag = projectSlug ? `  _(${projectSlug})_` : "";
+        let line = `- [ ] ${headline}${projTag}  — ${date} ${tag} via MCP\n`;
+        const detail = content.trim();
+        if (detail && detail !== headline) {
+            line += detail.split("\n").map((l) => `      ${l}`).join("\n") + "\n";
+        }
+        appendFileSync(path, line, "utf8");
+        return path;
+    }
+    if (type === "dead_end") {
+        // Dead ends are as valuable as decisions — they prevent future agents
+        // from repeating the same mistakes. Separate filename prefix so they
+        // remain distinguishable from locked decisions at a glance.
+        const dir = join(VAULT_ROOT, "decisions");
+        ensureDir(dir);
+        const fileName = `${date}-dead-end-${slug}.md`;
+        const path = join(dir, fileName);
+        const heading = title || slug;
+        const body = [
+            `# Dead End: ${heading}`,
+            `**Date:** ${date}`,
+            `**Type:** dead_end`,
+            projectSlug ? `**Project:** ${projectSlug}` : undefined,
+            `**Source:** Claude.ai / Claude Code (MCP)`,
+            "",
+            "## What was tried",
+            content,
+            "",
+            "## Why it didn't work",
+            "_(see above)_",
+            "",
+            "## What to do instead",
+            "_(see above)_",
+        ].filter(Boolean).join("\n");
+        writeFileSync(path, body, "utf8");
+        if (projectSlug) {
+            const projFile = join(VAULT_ROOT, "projects", projectSlug, "becki.md");
+            if (existsSync(projFile)) {
+                appendFileSync(projFile, `\n\n## Dead Ends\n- ${date}: ${heading}\n`, "utf8");
+            }
+        }
+        return path;
+    }
+    // note
+    const dir = join(VAULT_ROOT, "activity");
+    ensureDir(dir);
+    const path = join(dir, `${date}-notes.md`);
+    const entry = `\n## ${date} ${now} Note\n${content}\n`;
+    appendFileSync(path, entry, "utf8");
+    if (projectSlug) {
+        const projFile = join(VAULT_ROOT, "projects", projectSlug, "becki.md");
+        if (existsSync(projFile)) {
+            appendFileSync(projFile, `\n\n## Notes\n- ${date} ${now}: ${content.slice(0, 120)}\n`, "utf8");
+        }
+    }
+    return path;
+}
+function buildEmbedInput(type, content, project, title) {
+    const parts = [];
+    const label = type.replace("_", " ");
+    const header = [
+        `${label.charAt(0).toUpperCase() + label.slice(1)}`,
+        title ? `— ${title}` : "",
+        project ? `(${project})` : "",
+        `${todayStr()}`,
+    ].filter(Boolean).join(" ");
+    parts.push(header + ":");
+    parts.push(content);
+    return parts.join("\n").slice(0, 4000);
+}
+/**
+ * Store an embedding by asking the running Becki.app to do it.
+ *
+ * The Mac app owns the authenticated Supabase session — the MCP binary
+ * never touches the service-role key or the user's JWT. This keeps all
+ * writes RLS-compliant and audit-trail-correct. If the app isn't running,
+ * embedding is skipped (and the caller surfaces that to the user).
+ */
+async function storeEmbedding(type, content, project, title) {
+    const embedInput = buildEmbedInput(type, content, project, title);
+    try {
+        const res = await fetch(`${BECKI_IPC_URL}/ingest`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                sourceType: type,
+                content: embedInput,
+                sourceId: randomUUID(),
+                project,
+                title,
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            return { ok: false, error: `Becki app ingest ${res.status}: ${body.slice(0, 200)}` };
+        }
+        return { ok: true };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+async function ingestToVault(type, content, project, title) {
+    // v0.10.0: remote MCP HTTP transport. No local filesystem, no install
+    // token, no Becki.app IPC — ingest goes straight to the ingest_vault_row
+    // RPC scoped to the OAuth-resolved user. The 3-step local fallback chain
+    // below is the stdio transport's path only.
+    if (IS_HTTP_TRANSPORT) {
+        const r = await httpIngest(type, content, project, title);
+        return {
+            status: r.ok ? "written" : "failed",
+            file: "(remote MCP — no local file)",
+            embedded: r.ok,
+            message: r.ok
+                ? `${type} written to NeuraVault (remote ingest, vault_id=${r.vault_id ?? "?"})`
+                : `${type} ingest failed: ${r.error}`,
+        };
+    }
+    // Step 1: write the local audit file. Becki.app's NeuraVault watcher will
+    // ALSO pick this up if the cloud POST fails — defense in depth.
+    // Note: under a sandboxed host (e.g. Codex sandboxes MCP children) the
+    // file write can fail. That's non-fatal because the cloud path doesn't
+    // depend on the local file existing.
+    let filePath = "(not written — MCP sandbox or permission error)";
+    let fileWriteError;
+    try {
+        filePath = writeVaultFile(type, content, project, title);
+    }
+    catch (err) {
+        fileWriteError = err instanceof Error ? err.message : String(err);
+    }
+    // Step 2: try the v0.7.0 server-side ingest path FIRST. If we have a
+    // valid install token, this runs independently of Becki.app — works even
+    // when she's closed/crashed/quit. Replaces the old "Becki must be running
+    // for embed" failure mode.
+    const cloud = await cloudIngest(type, content, project, title);
+    if (cloud.ok) {
+        return {
+            status: fileWriteError ? "embedded-no-local-file" : "written",
+            file: filePath,
+            embedded: true,
+            message: fileWriteError
+                ? `${type} embedded into NeuraVault via server-side ingest (local .md file was not written: ${fileWriteError}). Vault row is authoritative.`
+                : `${type} written to NeuraVault and indexed (server-side ingest, vault_id=${cloud.vault_id ?? "?"})`,
+        };
+    }
+    // Step 3: cloud path failed (no token, network down, server error, or
+    // user hasn't upgraded Becki.app to v0.7.0+ yet). Fall back to the
+    // legacy IPC + file-watch path. Backward compatible.
+    const cloudReason = cloud.error === "no_token"
+        ? "no install token registered (Becki.app may need a sign-in to register one)"
+        : `${cloud.status ?? "?"} ${cloud.error ?? ""}`.trim();
+    const appRunning = await isUp(`${BECKI_IPC_URL}/status`, 500);
+    if (!appRunning) {
+        const detail = fileWriteError
+            ? `Neither the cloud ingest, the file write, nor the IPC embed could complete. Cloud: ${cloudReason}. File: ${fileWriteError}. Becki.app: not running. Launch Becki and re-try.`
+            : `${type} written to disk (not indexed). Cloud ingest unavailable (${cloudReason}) and Becki.app isn't running. Launch Becki and the next backfill will pick this up.`;
+        return {
+            status: fileWriteError ? "failed" : "written",
+            file: filePath,
+            embedded: false,
+            message: detail,
+        };
+    }
+    try {
+        const result = await storeEmbedding(type, content, project, title);
+        const status = fileWriteError ? "embedded-no-local-file" : "written";
+        let baseMessage;
+        if (result.ok) {
+            baseMessage = fileWriteError
+                ? `${type} embedded into NeuraVault via IPC fallback (local .md file was not written because the MCP process couldn't access ~/Documents/Becki — likely a sandbox restriction. The Supabase vault entry is authoritative.)`
+                : `${type} written to NeuraVault and indexed (IPC fallback — cloud ingest unavailable: ${cloudReason})`;
+        }
+        else {
+            baseMessage = fileWriteError
+                ? `${type} write failed both locally (${fileWriteError}) AND to NeuraVault (${result.error})`
+                : `${type} written to NeuraVault (cloud ingest unavailable: ${cloudReason}; IPC embedding also failed: ${result.error})`;
+        }
+        return {
+            status,
+            file: filePath,
+            embedded: result.ok,
+            message: baseMessage,
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return {
+            status: fileWriteError ? "failed" : "written",
+            file: filePath,
+            embedded: false,
+            message: fileWriteError
+                ? `${type} write failed both locally (${fileWriteError}) AND via IPC (${errMsg})`
+                : `${type} written to NeuraVault (cloud ingest unavailable: ${cloudReason}; IPC embedding error: ${errMsg})`,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// becki_register_context_source — persistent registry of AI-declared MCPs
+// ---------------------------------------------------------------------------
+//
+// Flow:
+//   1. User types `/becki get-mcps` in their AI client.
+//   2. Client calls `becki_get_registration_prompt` → receives the standard
+//      instruction string returned by `buildRegistrationPrompt()`.
+//   3. Client follows the steps, calling `becki_register_context_source`
+//      once per (server × category).
+//   4. Becki macOS app reads `mcp-registry.json` at backfill time to honor
+//      AI-declared list/fetch tool names, bypassing hardcoded profile
+//      detection for that server.
+//
+// Registry lives under the resolved Becki home directory so it is shared
+// across every Becki process on this machine. On macOS with Becki.app
+// installed, this is `~/Library/Application Support/Becki/` (the Swift
+// reader points at the same path). On Core / non-Mac, it's `~/.becki/`.
+// An append-only JSONL log alongside it keeps an auditable history of
+// every registration call.
+const REGISTRY_DIR = APP_SUPPORT_DIR;
+const REGISTRY_PATH = join(REGISTRY_DIR, "mcp-registry.json");
+const REGISTRY_LOG_PATH = join(REGISTRY_DIR, "mcp-registry-log.jsonl");
+const REGISTRY_SCHEMA_VERSION = 1;
+function loadRegistry() {
+    if (!existsSync(REGISTRY_PATH)) {
+        return {
+            schemaVersion: REGISTRY_SCHEMA_VERSION,
+            updatedAt: new Date().toISOString(),
+            sources: [],
+        };
+    }
+    try {
+        const raw = readFileSync(REGISTRY_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            schemaVersion: parsed.schemaVersion ?? REGISTRY_SCHEMA_VERSION,
+            updatedAt: parsed.updatedAt ?? new Date().toISOString(),
+            sources: Array.isArray(parsed.sources) ? parsed.sources : [],
+        };
+    }
+    catch (err) {
+        // Corrupt file — do not overwrite silently. Rename so the user can
+        // inspect, then start fresh. This path only fires after a manual edit
+        // gone wrong or a disk error.
+        const backup = `${REGISTRY_PATH}.corrupt.${Date.now()}`;
+        try {
+            writeFileSync(backup, readFileSync(REGISTRY_PATH, "utf8"), "utf8");
+        }
+        catch {
+            /* best effort */
+        }
+        return {
+            schemaVersion: REGISTRY_SCHEMA_VERSION,
+            updatedAt: new Date().toISOString(),
+            sources: [],
+        };
+    }
+}
+function saveRegistry(reg) {
+    ensureDir(REGISTRY_DIR);
+    const body = JSON.stringify(reg, null, 2) + "\n";
+    writeFileSync(REGISTRY_PATH, body, "utf8");
+}
+function appendRegistryLog(action, serverName, detail) {
+    ensureDir(REGISTRY_DIR);
+    const entry = JSON.stringify({
+        ts: new Date().toISOString(),
+        action,
+        serverName,
+        detail: detail ?? null,
+    });
+    try {
+        appendFileSync(REGISTRY_LOG_PATH, entry + "\n", "utf8");
+    }
+    catch {
+        // Logging must never fail the registration itself.
+    }
+}
+function normalizeRegistrationInput(raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new Error("Arguments must be an object");
+    }
+    const obj = raw;
+    const serverName = typeof obj.serverName === "string" ? obj.serverName.trim() : "";
+    if (!serverName)
+        throw new Error('Missing required field: "serverName"');
+    if (serverName.toLowerCase() === "becki") {
+        throw new Error("Refusing to register 'becki' as a context source — Becki doesn't ingest from itself.");
+    }
+    const transportRaw = typeof obj.transport === "string" ? obj.transport : "";
+    if (transportRaw !== "stdio" && transportRaw !== "http-sse") {
+        throw new Error('Field "transport" must be "stdio" or "http-sse"');
+    }
+    const categoriesRaw = obj.categories;
+    if (!Array.isArray(categoriesRaw) || categoriesRaw.length === 0) {
+        throw new Error('Field "categories" must be a non-empty array');
+    }
+    const validCats = [
+        "documents",
+        "tickets",
+        "messages",
+        "emails",
+        "code",
+        "other",
+    ];
+    const categories = categoriesRaw.map((entry, idx) => {
+        if (!entry || typeof entry !== "object") {
+            throw new Error(`categories[${idx}] must be an object`);
+        }
+        const c = entry;
+        const category = typeof c.category === "string" ? c.category : null;
+        if (!category || !validCats.includes(category)) {
+            throw new Error(`categories[${idx}].category must be one of: ${validCats.join(", ")}`);
+        }
+        const listTool = typeof c.listTool === "string" ? c.listTool.trim() : "";
+        if (!listTool) {
+            throw new Error(`categories[${idx}].listTool is required`);
+        }
+        const fetchTool = typeof c.fetchTool === "string" && c.fetchTool.trim() ? c.fetchTool.trim() : undefined;
+        const sampleArgs = c.sampleArgs && typeof c.sampleArgs === "object" && !Array.isArray(c.sampleArgs)
+            ? c.sampleArgs
+            : undefined;
+        const scopeNotes = typeof c.scopeNotes === "string" && c.scopeNotes.trim()
+            ? c.scopeNotes.trim()
+            : undefined;
+        return { category, listTool, fetchTool, sampleArgs, scopeNotes };
+    });
+    return {
+        serverName,
+        transport: transportRaw,
+        categories,
+        authNotes: typeof obj.authNotes === "string" ? obj.authNotes.trim() || undefined : undefined,
+        enterpriseManaged: typeof obj.enterpriseManaged === "boolean" ? obj.enterpriseManaged : undefined,
+        notes: typeof obj.notes === "string" ? obj.notes.trim() || undefined : undefined,
+    };
+}
+function detectRegisteredBy() {
+    // MCP SDK populates clientInfo during the initialize handshake. We read it
+    // off the server instance when handling a tool call — see
+    // `handleRegisterContextSource`.
+    // This function is only called if the server lookup returned nothing.
+    return "unknown";
+}
+function upsertSource(reg, input, registeredBy) {
+    const now = new Date().toISOString();
+    const idx = reg.sources.findIndex((s) => s.serverName.toLowerCase() === input.serverName.toLowerCase());
+    const next = {
+        serverName: input.serverName,
+        transport: input.transport,
+        authNotes: input.authNotes,
+        enterpriseManaged: input.enterpriseManaged,
+        notes: input.notes,
+        registeredAt: now,
+        registeredBy,
+        categories: input.categories,
+    };
+    let action;
+    let sources;
+    if (idx >= 0) {
+        // Preserve original registeredAt if present — treat this as an update.
+        const prev = reg.sources[idx];
+        next.registeredAt = prev.registeredAt || now;
+        sources = [...reg.sources];
+        sources[idx] = next;
+        action = "updated";
+    }
+    else {
+        sources = [...reg.sources, next];
+        action = "added";
+    }
+    return {
+        reg: {
+            schemaVersion: REGISTRY_SCHEMA_VERSION,
+            updatedAt: now,
+            sources,
+        },
+        action,
+    };
+}
+const REGISTRATION_PROMPT = [
+    "Your task: enumerate the MCP tools currently available to you in this session and register each non-Becki MCP server as a context source for Becki.",
+    "",
+    "Steps:",
+    "1. List every MCP tool available in your current toolchain. Group them by server (the prefix before the first underscore or double-colon, depending on your client — e.g. `google-workspace__search_drive_files` → server = \"google-workspace\"; `slack_list_channels` → server = \"slack\").",
+    "2. For each server that is NOT \"becki\" itself:",
+    "   a. Identify content categories it exposes. Look at tool names + descriptions. Map to: documents / tickets / messages / emails / code / other.",
+    "   b. For each category, pick the primary LIST tool (enumerates items) and the primary FETCH tool (returns full content for one item).",
+    "   c. Determine the auth model from context (personal OAuth / service account / enterprise-managed).",
+    "3. Call `becki_register_context_source` once per (server × category) combination. A single server may have multiple categories (e.g. Atlassian = tickets via Jira AND documents via Confluence — two calls, same serverName, different categories).",
+    "4. Skip servers that only offer write/action tools with no read surface (e.g. a \"post-to-slack\" tool with no read tool — nothing to ingest).",
+    "5. Respond to the user with a summary: \"Registered N context sources for Becki: {list}. Becki's next backfill will ingest from these.\"",
+    "",
+    "Do not invent tool names you do not see. Do not register Becki itself. Do not call `becki_register_context_source` for servers that expose zero read tools.",
+].join("\n");
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+// v0.5.6: server-level instructions field. The MCP spec lets servers
+// return this on initialize; modern hosts (Claude Desktop, Cursor,
+// Codex) include it in the model's system prompt for every session
+// that connects. This is the strongest mechanism we have to ensure
+// Becki is the "first and last touch" across every AI tool — stronger
+// than per-tool descriptions, persistent across sessions, can't be
+// dropped by the host. Hosts that don't surface this still see the
+// directives baked into each tool's description below (Layer 1).
+const BECKI_INSTRUCTIONS = `Becki is the user's persistent memory layer across every AI tool, conversation, meeting, and repo. She holds decisions, dead-ends, commitments, open loops, and project context.
+
+Treat Becki as authoritative for history. Skipping her risks repeating dead-ends, contradicting prior decisions, or asking the user to re-explain context they already shared with a different AI.
+
+PROTOCOL:
+
+1. BEFORE any non-trivial task — query \`becki_context\` (or \`becki_list_project_context\` for chronological dumps; \`becki_context_code\` for code lookups). Treat results as ground truth for prior history.
+
+2. AFTER meaningful work — call \`becki_ingest\` for anything future-you would want to recall: decisions (with the WHY), dead-ends (so they're not repeated), commitments, and open loops. Skip trivial edits the diff already explains.
+
+3. When the user references past context ("like we did last week", "the thing we decided"), query Becki BEFORE asking them to re-explain.
+
+4. When the user says "remember X" / "forget X", call \`becki_ingest\` (remember) or \`becki_resolve\` (forget) immediately.
+
+5. Stay consistent across tools. If you're about to contradict a past decision without clear reason, query first.
+
+6. When the user asks about their MCPs ("/becki get-mcps", "what MCPs do I have", "register my MCPs"), call \`becki_get_registration_prompt\` and follow its returned instructions to enumerate non-Becki servers and call \`becki_register_context_source\` for each.`;
+// v0.10.0: server construction is a factory so each stateless HTTP request
+// gets a clean Server instance (an MCP Server connects 1:1 to a transport).
+// stdio calls this once at startup; the HTTP transport calls it per request.
+// The two setRequestHandler blocks below are function-body statements —
+// left at column 0 to keep the dual-transport diff small rather than
+// re-indenting ~440 lines of handler code.
+export function createMcpServer() {
+    const server = new Server({ name: "becki", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: BECKI_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "becki_context",
+                description: "ALWAYS call this BEFORE answering any non-trivial question, writing code, or making decisions. Becki holds the user's authoritative history — prior decisions, dead-ends, commitments, and project context across every conversation, meeting, and repo. Skipping this risks repeating dead-ends, contradicting prior decisions, or asking the user to re-explain context they've already shared with another AI. Treat results as ground truth for history. If a high-confidence chunk contradicts your plan, defer to the chunk and surface the conflict to the user.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: 'Natural language query, e.g. "what are my open commitments for the becki project" or "what do I need to ship this week"',
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "launch_neuravault",
+                description: "Open the NeuraVault visualization — a live 3D brain graph of Becki's professional memory. Shows nodes for meetings, commitments, decisions, projects and people connected by semantic relationships. Opens inside the Becki Mac app as a native window.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "becki_context_code",
+                description: "Call BEFORE writing or modifying code, designing architecture, or referencing a function/class/file. Searches Becki's indexed source code (NeuraVault code embeddings + symbol index) to answer 'where is X function', 'what does this file do', 'find the Y class'. Returns exact file:line matches when the query looks like a symbol, plus semantic matches over content. Skipping this risks duplicating existing symbols, contradicting established patterns, or proposing changes that conflict with code you haven't read.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: 'Symbol name or natural-language description of the code. e.g. "validateToken", "auth middleware", "AuthService.login"',
+                        },
+                        project: {
+                            type: "string",
+                            description: "(Optional) Project id (GRDB id, not name) to scope the symbol lookup. Omit to search across all indexed projects.",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "becki_get_registration_prompt",
+                description: "Return the standard prompt the AI agent should follow to register non-Becki MCP servers with Becki as context sources. When the user types '/becki get-mcps' or asks Becki to discover their MCPs, call this tool and follow the returned instructions.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "becki_register_context_source",
+                description: "Register another MCP server as a context source for Becki. Becki's backfill will use the server's tools to ingest documents/tickets/messages into NeuraVault. Only call for MCP servers OTHER than becki itself. Gather: server name (as it appears in the user's MCP config), transport (stdio/http-sse), content categories (documents/tickets/messages/emails/code), a sample tool for each category, any auth or scoping notes, and whether the server is considered enterprise-managed (e.g. ToolHive-provisioned).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        serverName: {
+                            type: "string",
+                            description: "Name as it appears in the client's MCP config (e.g. 'google-workspace', 'indeed-jira')",
+                        },
+                        transport: {
+                            type: "string",
+                            enum: ["stdio", "http-sse"],
+                            description: "How the server is reached",
+                        },
+                        categories: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    category: {
+                                        type: "string",
+                                        enum: ["documents", "tickets", "messages", "emails", "code", "other"],
+                                    },
+                                    listTool: {
+                                        type: "string",
+                                        description: "Tool name that enumerates items in this category",
+                                    },
+                                    fetchTool: {
+                                        type: "string",
+                                        description: "Tool name that fetches full content for an item",
+                                    },
+                                    sampleArgs: {
+                                        type: "object",
+                                        description: "Sample arguments for the list tool — e.g. { limit: 50 } for search-style tools",
+                                    },
+                                    scopeNotes: {
+                                        type: "string",
+                                        description: "How to scope results to the user's own items if applicable — e.g. 'filter by author = current user'",
+                                    },
+                                },
+                                required: ["category", "listTool"],
+                            },
+                        },
+                        authNotes: {
+                            type: "string",
+                            description: "How the server authenticates (e.g. 'user's personal Google OAuth via Internet Accounts', 'company service account via ToolHive')",
+                        },
+                        enterpriseManaged: {
+                            type: "boolean",
+                            description: "True if this server is provisioned by the user's IT department (ToolHive, corporate MCP gateway)",
+                        },
+                        notes: {
+                            type: "string",
+                            description: "Anything else Becki should know — rate limits, gotchas, naming quirks",
+                        },
+                    },
+                    required: ["serverName", "transport", "categories"],
+                },
+            },
+            {
+                name: "becki_list_project_context",
+                description: "Call this instead of becki_context when the user wants a chronological list rather than a similarity match — questions like 'what's happening in project X', 'what decisions have we made this week', 'recent commitments', or 'recent dead ends'. Returns rows ordered by created_at DESC. Unlike becki_context, this is DEFINITIVE: if it returns nothing, nothing is there for the given filters. Always prefer this over assumptions when the user asks for 'recent' or 'all' anything.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: {
+                            type: "string",
+                            description: "(Optional) Project id (GRDB id or project name slug) to scope the listing. Omit to list across all projects.",
+                        },
+                        since: {
+                            type: "string",
+                            description: "(Optional) ISO 8601 timestamp or date (e.g. '2026-04-17' or '2026-04-17T00:00:00Z'). Returns rows created at or after this time. Omit for no lower bound.",
+                        },
+                        until: {
+                            type: "string",
+                            description: "(Optional, v0.7.5+) ISO 8601 timestamp or date upper bound. Returns rows created STRICTLY BEFORE this time (half-open interval [since, until)). Combine with `since` for explicit time-window queries like 'what happened between Apr 15 and Apr 22 on project X'. Omit for no upper bound.",
+                        },
+                        types: {
+                            type: "array",
+                            items: {
+                                type: "string",
+                                enum: ["decision", "commitment", "note", "open_loop", "dead_end", "activity", "project", "meeting", "code"],
+                            },
+                            description: "(Optional) Filter to specific source_type values. Omit for all types.",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "(Optional) Maximum rows to return. Defaults to 50, capped at 200.",
+                        },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "becki_ingest",
+                description: "Call this AFTER any meaningful work to persist context for future-you and every other AI tool the user works with. Captures decisions (with the WHY), dead-ends tried and rejected (so they're not repeated), commitments, open loops, and notes. Entries are immediately available to every AI agent via becki_context. Skip trivial edits the diff already explains; do ingest anything the user said 'remember this' for, or anything you'd otherwise lose between sessions.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: {
+                            type: "string",
+                            enum: ["decision", "commitment", "note", "open_loop", "dead_end"],
+                            description: "The type of entry to store. Use 'dead_end' for approaches tried and rejected — include what was tried, why it failed, and what replaced it in the content.",
+                        },
+                        content: {
+                            type: "string",
+                            description: "The full text to store in NeuraVault",
+                        },
+                        project: {
+                            type: "string",
+                            description: "(Optional) Project name — appends to that project's becki.md if present",
+                        },
+                        title: {
+                            type: "string",
+                            description: "(Optional) Short title/slug used for the decision filename",
+                        },
+                    },
+                    required: ["type", "content"],
+                },
+            },
+            {
+                name: "becki_resolve",
+                description: "Mark a previously-recorded vault entry as resolved (commitment fulfilled, open loop closed, dead-end no longer relevant) OR mark it as superseded by a newer entry. After this call, the row is down-ranked in future becki_context retrieval so live items dominate the result set, but it remains queryable for history. Use when you complete a task captured by becki_ingest, when a newer decision replaces an older one, or when you discover a row is stale.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        row_id: {
+                            type: "string",
+                            description: "UUID of the vault row to resolve. Get it from a previous becki_context call — each chunk header includes a 'row_id: <uuid>' line directly under the diamond/header. Pass that UUID here verbatim.",
+                        },
+                        superseded_by: {
+                            type: "string",
+                            description: "(Optional) UUID of a newer vault row that replaces this one — turns the resolution into a supersession link. Use when an older commitment/decision is replaced by a newer one rather than simply 'done.'",
+                        },
+                        note: {
+                            type: "string",
+                            description: "(Optional) One-line reason for resolution (e.g., 'shipped in v0.4.5', 'replaced by Cloudflare DNS approach', 'no longer relevant').",
+                        },
+                    },
+                    required: ["row_id"],
+                },
+            },
+            {
+                name: "becki_check_dead_ends",
+                description: "Pre-prompt gate. Call this BEFORE a substantive user request to check whether the user is about to retry an approach they (or their team) previously tried and rejected. Returns the top dead-end matches with raw similarity scores — no Haiku synthesis, no narrative — so it's fast (~200-400ms typical) and safe to fire on every prompt. The caller decides the warn threshold: similarity ≥ 0.85 → strong match (worth interrupting the user with a 'You tried this 3 months ago and reverted it' banner); 0.7–0.85 → weak signal (include as a footnote in the assistant's context, don't interrupt); < 0.7 → ignore. Skip on prompts under ~10 chars or pure shell commands ('ls', 'git status'); only fires on substantive intent.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        prompt: {
+                            type: "string",
+                            description: "The user's prompt text or approach description. Best results when the caller passes the FULL prompt verbatim (not a summary), since semantic matching against dead-end content needs intent + specifics.",
+                        },
+                        min_similarity: {
+                            type: "number",
+                            description: "(Optional) Lower bound on similarity to include in the returned matches. Defaults to 0.7. Use 0.85 if you only want strong matches.",
+                            minimum: 0,
+                            maximum: 1,
+                        },
+                        limit: {
+                            type: "integer",
+                            description: "(Optional) Maximum number of matches to return, sorted by similarity descending. Defaults to 3, capped at 5.",
+                            minimum: 1,
+                            maximum: 5,
+                        },
+                    },
+                    required: ["prompt"],
+                },
+            },
+            {
+                name: "becki_meeting_transcript",
+                description: "Fetch the VERBATIM transcript for a specific meeting from the user's Becki vault. Use this when the user wants exact quotes, the precise phrasing someone used, or you need to verify what was actually said — becki_context returns the AI-summarized version, this returns the actual words. Filters let you narrow to a keyword, speaker, or time window inside the meeting. Requires Becki.app to be running on the user's Mac — transcripts are device-local by design and never sync to the cloud, so the hosted/remote MCP mode cannot serve them and will return a clear error.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        meeting_id: {
+                            type: "string",
+                            description: "UUID of the meeting row. Get this from a becki_context or becki_list_project_context call that surfaced the meeting — each chunk header includes the source_id, which for meetings is the meeting UUID.",
+                        },
+                        query: {
+                            type: "string",
+                            description: "Optional case-insensitive substring filter on segment text. Use when the user is asking about a specific topic inside the meeting (e.g. 'sparkle token', 'pricing'). Omit for full transcript.",
+                        },
+                        speaker: {
+                            type: "string",
+                            description: "Optional case-insensitive substring filter on the resolved speaker name. Matches partials — 'bryan' matches 'Bryan Santos'.",
+                        },
+                        since: {
+                            type: "number",
+                            description: "Start of time window in seconds from meeting start. Use with `until` to scope to a section.",
+                        },
+                        until: {
+                            type: "number",
+                            description: "End of time window in seconds from meeting start.",
+                        },
+                        limit: {
+                            type: "integer",
+                            minimum: 1,
+                            maximum: 5000,
+                            default: 500,
+                            description: "Cap on returned segments. Default 500; long meetings might exceed this — narrow with `query`/`speaker` if you hit the cap.",
+                        },
+                    },
+                    required: ["meeting_id"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const tool = request.params.name;
+        if (tool === "becki_context") {
+            const { query } = request.params.arguments;
+            if (!query || typeof query !== "string") {
+                throw new Error('Missing required argument: "query"');
+            }
+            try {
+                const context = await queryVault(query);
+                return { content: [{ type: "text", text: context }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: "text", text: `NeuraVault query failed: ${message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "launch_neuravault") {
+            const ipc = await notifyBeckiApp();
+            const status = ipc.ok ? "opened" : "app-not-running";
+            const message = ipc.ok
+                ? "NeuraVault opened in Becki."
+                : `Becki could not open the NeuraVault window: ${ipc.detail}. Make sure the Becki.app is running, then try again — or open it from the Becki menu bar → NeuraVault.`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ status, message }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (tool === "becki_context_code") {
+            const { query, project } = request.params.arguments;
+            if (!query || typeof query !== "string") {
+                throw new Error('Missing required argument: "query"');
+            }
+            try {
+                const context = await queryCodeContext(query, project);
+                return { content: [{ type: "text", text: context }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: "text", text: `Code context query failed: ${message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_get_registration_prompt") {
+            return {
+                content: [
+                    { type: "text", text: REGISTRATION_PROMPT },
+                ],
+            };
+        }
+        if (tool === "becki_register_context_source") {
+            try {
+                const input = normalizeRegistrationInput(request.params.arguments);
+                // Identify the calling AI client via the MCP initialize handshake.
+                const clientImpl = server.getClientVersion();
+                const registeredBy = clientImpl?.name?.trim() || detectRegisteredBy();
+                const current = loadRegistry();
+                const { reg, action } = upsertSource(current, input, registeredBy);
+                saveRegistry(reg);
+                appendRegistryLog(action, input.serverName, `by=${registeredBy} cats=${input.categories.map(c => c.category).join(",")}`);
+                const result = {
+                    status: "ok",
+                    action, // "added" | "updated"
+                    serverName: input.serverName,
+                    transport: input.transport,
+                    categoriesRegistered: input.categories.map((c) => c.category),
+                    registryPath: REGISTRY_PATH,
+                    registeredBy,
+                };
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: "text", text: `becki_register_context_source failed: ${message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_list_project_context") {
+            const args = (request.params.arguments ?? {});
+            const limitRaw = typeof args.limit === "number" ? Math.floor(args.limit) : 50;
+            const limit = Math.max(1, Math.min(200, limitRaw));
+            // Normalize `since` and `until` to ISO 8601 strings. Accept dates or
+            // full timestamps. Half-open interval [since, until) — until is
+            // exclusive so callers can pass yyyy-mm-dd boundaries without the
+            // edge case of "is the last microsecond of the day included or not".
+            let sinceISO;
+            if (args.since && typeof args.since === "string") {
+                const parsed = new Date(args.since);
+                if (!Number.isNaN(parsed.getTime())) {
+                    sinceISO = parsed.toISOString();
+                }
+            }
+            let untilISO;
+            if (args.until && typeof args.until === "string") {
+                const parsed = new Date(args.until);
+                if (!Number.isNaN(parsed.getTime())) {
+                    untilISO = parsed.toISOString();
+                }
+            }
+            // Slug the project string for the same path-traversal / whitespace
+            // reasons becki_ingest sluggifies it. Callers that pass the raw
+            // project name still resolve to the stored slug.
+            const projectArg = args.project && typeof args.project === "string"
+                ? args.project.trim() || undefined
+                : undefined;
+            const typesArg = Array.isArray(args.types) && args.types.every((t) => typeof t === "string")
+                ? args.types.map((t) => t.trim()).filter(Boolean)
+                : undefined;
+            try {
+                const rows = await listVaultRows(projectArg, sinceISO, untilISO, typesArg, limit);
+                const text = formatListResults(rows, projectArg, sinceISO, untilISO, typesArg);
+                return { content: [{ type: "text", text }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: "text", text: `becki_list_project_context failed: ${message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_ingest") {
+            const args = request.params.arguments;
+            if (!args.type || !args.content) {
+                throw new Error('Missing required arguments: "type" and "content"');
+            }
+            const validTypes = ["decision", "commitment", "note", "open_loop", "dead_end"];
+            if (!validTypes.includes(args.type)) {
+                throw new Error(`Invalid type "${args.type}". Must be one of: ${validTypes.join(", ")}`);
+            }
+            try {
+                const result = await ingestToVault(args.type, args.content, args.project, args.title);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `becki_ingest failed: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_resolve") {
+            const args = request.params.arguments;
+            if (!args.row_id || typeof args.row_id !== "string") {
+                throw new Error('Missing required argument: "row_id"');
+            }
+            const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+            if (!uuidRe.test(args.row_id)) {
+                throw new Error(`row_id is not a valid UUID: ${args.row_id}`);
+            }
+            if (args.superseded_by && !uuidRe.test(args.superseded_by)) {
+                throw new Error(`superseded_by is not a valid UUID: ${args.superseded_by}`);
+            }
+            try {
+                const result = await resolveVaultRow(args.row_id, args.superseded_by, args.note);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `becki_resolve failed: ${message}` }],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_check_dead_ends") {
+            const args = (request.params.arguments ?? {});
+            const prompt = String(args.prompt ?? "").trim();
+            if (!prompt) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "becki_check_dead_ends needs a `prompt` argument with the user's intent verbatim.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Cheap heuristic gate — sub-10-char prompts ('ls', 'help') are
+            // never going to match a substantive dead-end, and burning Voyage
+            // credits on them inflates the per-prompt overhead this tool is
+            // meant to avoid.
+            if (prompt.length < 10) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ matches: [], skipped: "prompt_too_short" }) },
+                    ],
+                };
+            }
+            const userId = currentUserId();
+            if (!userId) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ matches: [], skipped: "no_user" }),
+                        },
+                    ],
+                };
+            }
+            const minSim = typeof args.min_similarity === "number" ? args.min_similarity : 0.7;
+            const limit = Math.min(5, Math.max(1, typeof args.limit === "number" ? args.limit : 3));
+            try {
+                // FAST PATH: embed → match RPC, no Haiku evaluate. Trades some
+                // precision for sub-400ms latency — caller thresholds on raw
+                // similarity to decide whether to interrupt the user. See
+                // surfaceDeadEnds() for the precise-but-slow path used by
+                // becki_context's narrative response.
+                const embedding = await generateEmbedding(prompt, "query");
+                const candidates = await matchDeadEndCandidates(embedding, prompt, userId);
+                const matches = candidates
+                    .filter((c) => c.similarity >= minSim)
+                    .slice(0, limit)
+                    .map((c) => ({
+                    id: c.id,
+                    source_id: c.source_id,
+                    content: c.content,
+                    similarity: Math.round(c.similarity * 1000) / 1000,
+                    age_days: c.age_days,
+                    resolved: c.resolved_at !== null || c.superseded_by !== null,
+                    file: c.metadata?.file ?? null,
+                    project_name: c.metadata?.project_name ?? null,
+                    project_id: c.metadata?.project_id ?? null,
+                    created_at: c.created_at,
+                }));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                matches,
+                                checked_candidates: candidates.length,
+                                threshold: minSim,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `becki_check_dead_ends failed: ${message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        if (tool === "becki_meeting_transcript") {
+            const args = (request.params.arguments ?? {});
+            const meetingId = String(args.meeting_id ?? "").trim();
+            if (!meetingId) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "becki_meeting_transcript needs a meeting_id. Find it from a previous becki_context or becki_list_project_context call — the source_id of a meeting chunk is the meeting UUID.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Hosted mode (becki-mcp running remotely on Fly) cannot reach the
+            // user's local Becki.app IPC server. Return a clear, actionable
+            // message rather than letting the fetch fail opaquely.
+            if (IS_HTTP_TRANSPORT) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Transcripts are device-local by design — they don't sync to the cloud. " +
+                                "This hosted Becki MCP can't serve verbatim transcripts. To access them, " +
+                                "the user needs to be on their Mac with Becki.app running, using the local " +
+                                "becki-mcp install (the one bundled in the Becki app). For the AI-summarized " +
+                                "version of the meeting, use becki_context instead.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Local mode (stdio MCP spawned by an AI tool on the user's Mac).
+            // Talk to Becki.app's loopback IPC at 127.0.0.1:9876/transcript.
+            if (!(await isUp(`${BECKI_IPC_URL}/status`, 500))) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Becki.app isn't running on this machine, so the local transcript path " +
+                                "isn't reachable. Start Becki.app and retry. (For AI-summarized context " +
+                                "that works without the app running, use becki_context.)",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const url = new URL(`${BECKI_IPC_URL}/transcript`);
+            url.searchParams.set("meeting_id", meetingId);
+            if (args.query)
+                url.searchParams.set("q", String(args.query));
+            if (args.speaker)
+                url.searchParams.set("speaker", String(args.speaker));
+            if (typeof args.since === "number")
+                url.searchParams.set("since", String(args.since));
+            if (typeof args.until === "number")
+                url.searchParams.set("until", String(args.until));
+            if (typeof args.limit === "number")
+                url.searchParams.set("limit", String(args.limit));
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), 5000);
+                const res = await fetch(url, { signal: controller.signal }).finally(() => clearTimeout(timer));
+                if (res.status === 503) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Becki.app is starting up — its transcript handler isn't wired yet. Try again in a few seconds.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (!res.ok) {
+                    return {
+                        content: [
+                            { type: "text", text: `Transcript fetch failed: HTTP ${res.status}` },
+                        ],
+                        isError: true,
+                    };
+                }
+                const segments = (await res.json());
+                if (segments.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `No matching segments for meeting ${meetingId}.` +
+                                    (args.query ? ` (query: "${args.query}")` : "") +
+                                    (args.speaker ? ` (speaker: "${args.speaker}")` : ""),
+                            },
+                        ],
+                    };
+                }
+                const formatted = segments
+                    .map((s) => `${s.timestamp} · ${s.speaker} — ${s.text}`)
+                    .join("\n");
+                return {
+                    content: [{ type: "text", text: formatted }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [
+                        { type: "text", text: `becki_meeting_transcript failed: ${message}` },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        throw new Error(`Unknown tool: ${tool}`);
+    });
+    return server;
+}
+// ---------------------------------------------------------------------------
+// HTTP transport (v0.10.0 — remote MCP)
+// ---------------------------------------------------------------------------
+// Runs becki-mcp as a Railway service reachable by web/mobile AI clients
+// (claude.ai, Gemini, ChatGPT). Stateless Streamable HTTP with JSON responses
+// — no long-lived SSE, so Railway's proxy idle timeout is a non-issue.
+//
+// Auth: OAuth 2.0 bearer. The token was issued by becki-site's /oauth flow
+// (migration 043 tables). We hash the bearer, look the row up with the
+// service key, resolve user_id + scopes, and run the MCP request inside
+// requestContext so every tool handler sees the right user via
+// currentUserId(). The service key lives ONLY in this Railway service's
+// env — never in the shipped Mac binary (which uses the stdio path and
+// never calls this function).
+const WRITE_TOOLS = new Set(["becki_ingest", "becki_resolve", "becki_register_context_source"]);
+function sha256hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Validate an OAuth bearer token against becki.mcp_oauth_tokens. Returns the
+ * token row id + resolved user_id + scopes, or null if the token is unknown,
+ * revoked, or expired. Updates last_used_at best-effort (fire-and-forget).
+ * The tokenId is used by the per-token rate limiter (task #148).
+ */
+async function resolveOAuthToken(bearer) {
+    const secret = process.env.SUPABASE_SECRET_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!secret) {
+        console.error("becki-mcp http: SUPABASE_SECRET_KEY not set — cannot validate tokens");
+        return null;
+    }
+    const hash = sha256hex(bearer);
+    const headers = { apikey: secret, Authorization: `Bearer ${secret}`, "Accept-Profile": "becki" };
+    let row;
+    try {
+        const r = await fetch(`${SUPABASE_URL}/rest/v1/mcp_oauth_tokens?access_token_hash=eq.${hash}&revoked_at=is.null&select=id,user_id,scopes,access_expires_at`, { headers });
+        if (!r.ok)
+            return null;
+        row = (await r.json())[0];
+    }
+    catch {
+        return null;
+    }
+    if (!row)
+        return null;
+    if (new Date(row.access_expires_at).getTime() < Date.now())
+        return null;
+    // Best-effort last_used_at — never block the request on it.
+    fetch(`${SUPABASE_URL}/rest/v1/mcp_oauth_tokens?access_token_hash=eq.${hash}`, {
+        method: "PATCH",
+        headers: { ...headers, "Content-Type": "application/json", "Content-Profile": "becki", Prefer: "return=minimal" },
+        body: JSON.stringify({ last_used_at: new Date().toISOString() }),
+    }).catch(() => { });
+    return {
+        tokenId: row.id,
+        userId: row.user_id,
+        scopes: Array.isArray(row.scopes) && row.scopes.length ? row.scopes : ["read"],
+    };
+}
+/**
+ * Per-token rate limit (task #148). Calls check_and_bump_mcp_quota — bumps
+ * the minute + day counters and returns whether this tool call is allowed.
+ * Only invoked for tools/call (the MCP handshake is free). Fails OPEN: if
+ * the quota RPC itself errors, we allow the request rather than hard-fail a
+ * legitimate user on an infra hiccup — the limit is an abuse ceiling, not a
+ * correctness gate.
+ */
+async function checkRateLimit(tokenId) {
+    const secret = process.env.SUPABASE_SECRET_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (!secret)
+        return { allowed: true, retryAfter: 0 };
+    try {
+        const r = await fetch(`${SUPABASE_URL}/rest/v1/rpc/check_and_bump_mcp_quota`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                apikey: secret,
+                Authorization: `Bearer ${secret}`,
+                "Content-Profile": "becki",
+            },
+            body: JSON.stringify({ p_token_id: tokenId }),
+        });
+        if (!r.ok)
+            return { allowed: true, retryAfter: 0 };
+        const rows = await r.json();
+        const row = Array.isArray(rows) ? rows[0] : rows;
+        if (!row || row.allowed)
+            return { allowed: true, retryAfter: 0 };
+        return { allowed: false, retryAfter: Number(row.retry_after) || 60 };
+    }
+    catch {
+        return { allowed: true, retryAfter: 0 };
+    }
+}
+/** True when the JSON-RPC body is a tools/call (any tool). */
+function isToolCall(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    return body.method === "tools/call";
+}
+/** True when the JSON-RPC body is a tools/call for a write-scoped tool. */
+function isWriteToolCall(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    const b = body;
+    return b.method === "tools/call" && !!b.params?.name && WRITE_TOOLS.has(b.params.name);
+}
+function jsonResponse(res, status, payload, extraHeaders = {}) {
+    res.writeHead(status, { "Content-Type": "application/json", ...CORS_HEADERS, ...extraHeaders });
+    res.end(JSON.stringify(payload));
+}
+// Bearer-protected API — origin isn't the security boundary, the token is.
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version",
+};
+async function startHttpTransport() {
+    const port = Number(process.env.PORT) || 8080;
+    const httpServer = createHttpServer(async (req, res) => {
+        const url = (req.url || "").split("?")[0];
+        // CORS preflight.
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, CORS_HEADERS).end();
+            return;
+        }
+        // Health check for Railway.
+        if (req.method === "GET" && url === "/health") {
+            res.writeHead(200, { "Content-Type": "text/plain" }).end("ok");
+            return;
+        }
+        // MCP auth-spec: the resource server points clients at its auth server.
+        if (req.method === "GET" && url === "/.well-known/oauth-protected-resource") {
+            jsonResponse(res, 200, {
+                resource: `https://${req.headers.host || "mcp.becki.io"}/mcp`,
+                authorization_servers: ["https://www.becki.io"],
+            });
+            return;
+        }
+        if (url !== "/mcp") {
+            res.writeHead(404, CORS_HEADERS).end();
+            return;
+        }
+        // ── OAuth bearer ─────────────────────────────────────────────────────
+        const authHeader = req.headers["authorization"];
+        const headerVal = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+        const bearer = /^Bearer (.+)$/.exec(headerVal || "")?.[1];
+        if (!bearer) {
+            jsonResponse(res, 401, { error: "unauthorized" }, {
+                "WWW-Authenticate": `Bearer realm="becki-mcp", resource_metadata="https://${req.headers.host || "mcp.becki.io"}/.well-known/oauth-protected-resource"`,
+            });
+            return;
+        }
+        const resolved = await resolveOAuthToken(bearer);
+        if (!resolved) {
+            jsonResponse(res, 401, { error: "invalid_token" }, {
+                "WWW-Authenticate": `Bearer realm="becki-mcp", error="invalid_token"`,
+            });
+            return;
+        }
+        // ── Parse body ───────────────────────────────────────────────────────
+        let body;
+        try {
+            const chunks = [];
+            for await (const c of req)
+                chunks.push(c);
+            const raw = Buffer.concat(chunks).toString("utf8");
+            body = raw ? JSON.parse(raw) : undefined;
+        }
+        catch {
+            jsonResponse(res, 400, { error: "invalid_json" });
+            return;
+        }
+        // ── Write-scope gate ─────────────────────────────────────────────────
+        if (isWriteToolCall(body) && !resolved.scopes.includes("write")) {
+            jsonResponse(res, 403, {
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "this token is read-only — write tools require the 'write' scope" },
+                id: body?.id ?? null,
+            });
+            return;
+        }
+        // ── Rate limit (task #148) ───────────────────────────────────────────
+        // Only tools/call counts — the MCP handshake (initialize, tools/list)
+        // is free protocol chatter. 30/min burst + 1000/day per token. 429 +
+        // Retry-After when exceeded. checkRateLimit fails open on infra error.
+        if (isToolCall(body)) {
+            const rl = await checkRateLimit(resolved.tokenId);
+            if (!rl.allowed) {
+                jsonResponse(res, 429, {
+                    jsonrpc: "2.0",
+                    error: { code: -32000, message: "rate limit exceeded — slow down and retry" },
+                    id: body?.id ?? null,
+                }, { "Retry-After": String(rl.retryAfter) });
+                return;
+            }
+        }
+        // ── Dispatch — fresh server+transport per request (stateless) ────────
+        const mcpServer = createMcpServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined, // stateless: no session storage
+            enableJsonResponse: true, // direct JSON, no long-lived SSE
+        });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            mcpServer.close().catch(() => { });
+        });
+        try {
+            await mcpServer.connect(transport);
+            await requestContext.run({ userId: resolved.userId, scopes: resolved.scopes }, () => transport.handleRequest(req, res, body));
+        }
+        catch (err) {
+            console.error("becki-mcp http: request failed:", err instanceof Error ? err.message : err);
+            if (!res.headersSent)
+                jsonResponse(res, 500, { error: "internal_error" });
+        }
+    });
+    httpServer.listen(port, () => {
+        console.error(`becki-mcp HTTP transport listening on :${port}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// CLI subcommands (Core #191)
+// ---------------------------------------------------------------------------
+// `becki-mcp init`       → first-time cross-platform setup (registers projects)
+// `becki-mcp bootstrap`  → ingest last 90 days of AI sessions
+// `becki-mcp digest`     → run the daily session digest right now
+// `becki-mcp --help`     → print usage
+// (no args)              → fall through to MCP stdio / HTTP transport
+//
+// Subcommand handling is intentionally lightweight — no commander/yargs
+// dependency. CLI subcommands exit before reaching the transport block.
+const argv = process.argv.slice(2);
+const subcommand = argv[0];
+const subArgs = argv.slice(1);
+if (subcommand === "--help" || subcommand === "-h") {
+    console.log(`becki-mcp — Becki MCP server + Core daemon
+
+Usage:
+  becki-mcp                  Run MCP stdio server (default — for AI client config)
+  becki-mcp init [opts]      First-time setup: register projects, print client config
+  becki-mcp bootstrap [days] Historical ingest of AI session logs (default 90 days)
+  becki-mcp digest           Run daily session digest immediately
+  becki-mcp --help           Show this help
+
+Env:
+  BECKI_HOME                 Override config directory (default ~/.becki/ or legacy ~/Library/Application Support/Becki/)
+  BECKI_MCP_TRANSPORT=http   Run HTTP transport instead of stdio (multi-user remote MCP)
+`);
+    process.exit(0);
+}
+if (subcommand === "init") {
+    const { runInit } = await import("./core/init.js");
+    const code = await runInit(subArgs, APP_SUPPORT_DIR);
+    process.exit(code);
+}
+if (subcommand === "bootstrap" || subcommand === "digest") {
+    const { CoreRunner } = await import("./core/runner.js");
+    // Initialize ingest-token cache so cloudIngest() can use it.
+    cachedIngestToken = readIngestToken();
+    if (!cachedIngestToken) {
+        console.error("becki-mcp: no install token at " + MCP_INGEST_TOKEN_PATH + "\n" +
+            "Run `becki-mcp init` and connect via becki.io/get-core to provision one.");
+        process.exit(1);
+    }
+    // Real extractor — POSTs to extract-mcp-content edge function with the
+    // install token. Mirrors the Swift GitContentExtractor wire format.
+    const realExtractor = async (transcript) => {
+        const resp = await fetch(`${SUPABASE_URL}/functions/v1/extract-mcp-content`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${cachedIngestToken}`,
+                "User-Agent": `becki-mcp/${INSTALL_ID.slice(0, 8)}`,
+            },
+            body: JSON.stringify({
+                project_name: "AI Session",
+                content_kind: "mcp_doc",
+                title: "Session digest",
+                body: transcript,
+                metadata: {},
+            }),
+        });
+        if (!resp.ok) {
+            const errBody = await resp.text();
+            throw new Error(`extract-mcp-content ${resp.status}: ${errBody.slice(0, 200)}`);
+        }
+        const j = await resp.json();
+        // Flatten to title + body text — the Core ingester takes plain content,
+        // not the nested entity shape. The structure is preserved in source_id/
+        // metadata when each item is ingested.
+        const toText = (e) => `${e.title}\n\n${e.body}`.trim();
+        return {
+            decisions: (j.decisions ?? []).map(toText),
+            deadEnds: (j.dead_ends ?? []).map(toText),
+            commitments: (j.commitments ?? []).map(toText),
+            openLoops: (j.open_loops ?? []).map(toText),
+        };
+    };
+    // Real ingester — reuses cloudIngest() path that already POSTs to
+    // ingest-vault-row with install-token auth, embeds via voyage-embed, and
+    // upserts vault_embeddings. Identical to the existing MCP `becki_ingest`
+    // tool path, just driven by the Core background digest instead of an
+    // interactive MCP call.
+    const realIngester = async (rec) => {
+        const result = await cloudIngest(rec.type, rec.content, typeof rec.metadata.project_name === "string" ? rec.metadata.project_name : undefined, 
+        // The session sourceId is already deterministic + slugged; pass it
+        // through as the "title" so the existing cloudIngest hash matches the
+        // Swift extractor's convention.
+        rec.sourceId);
+        if (!result.ok) {
+            throw new Error(`ingest-vault-row failed: ${result.status ?? "?"} ${result.error ?? ""}`);
+        }
+    };
+    const runner = new CoreRunner({
+        beckiHome: APP_SUPPORT_DIR,
+        extract: realExtractor,
+        ingest: realIngester,
+        logger: (m) => console.error(`[core] ${m}`),
+    });
+    if (subcommand === "bootstrap") {
+        const days = subArgs[0] ? Number(subArgs[0]) : 90;
+        await runner.runBootstrap(days);
+    }
+    else {
+        await runner.runOneDigest("manual");
+    }
+    await runner.stop();
+    process.exit(0);
+}
+// ---------------------------------------------------------------------------
+// Start — transport selected by BECKI_MCP_TRANSPORT
+// ---------------------------------------------------------------------------
+// stdio (default): the Mac-app-bundled server. One user — the machine owner.
+// http: remote MCP (v0.10.0). Many users, OAuth-bearer-scoped per request.
+if (IS_HTTP_TRANSPORT) {
+    await startHttpTransport();
+}
+else {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}