rbxstudio-mcp 2.3.1 → 2.4.0

package/dist/docs/embeddings/embedder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Thin wrapper around @huggingface/transformers' feature-extraction
+ * pipeline.
+ *
+ * Why a wrapper instead of using `pipeline()` directly at call sites?
+ *   1. The pipeline is HEAVY to load (~25MB model download + ~200ms
+ *      ORT init). We want exactly one instance per process, created
+ *      lazily on first use.
+ *   2. The library is pure ESM and import-heavy; isolating it here
+ *      means the rest of the codebase doesn't pay the cost on startup
+ *      and tests that don't need embeddings don't load it.
+ *   3. We want a stable surface (encode(string[]) → Float32Array[])
+ *      regardless of which Transformers.js version we're on.
+ *
+ * Model: sentence-transformers/all-MiniLM-L6-v2 (via the Xenova ONNX
+ * port). 384-dim normalized sentence embeddings, ~25MB on disk,
+ * ~5–10ms per encode on a modern CPU. Trained on 1B+ sentence pairs
+ * with contrastive loss → great general-purpose retrieval quality at
+ * tiny model size.
+ */
+export declare const EMBED_DIM = 384;
+export declare const EMBED_MODEL = "Xenova/all-MiniLM-L6-v2";
+export declare function __setEmbedderForTests(fn: ((texts: string[]) => Promise<Float32Array[]>) | null): void;
+/**
+ * Encode an array of strings into normalized 384-dim Float32 vectors.
+ *
+ * Normalization is done by the model (pooling: 'mean', normalize: true)
+ * so cosine similarity == plain dot product, which is hot-path-cheap.
+ *
+ * Batched internally — pass big arrays (50–200 items per call is fine)
+ * to amortize tensor allocation overhead.
+ */
+export declare function encode(texts: string[]): Promise<Float32Array[]>;
+/** Convenience: encode a single string. */
+export declare function encodeOne(text: string): Promise<Float32Array>;
+/**
+ * Dot product of two normalized vectors == cosine similarity. Tight
+ * loop, no allocations, called millions of times during query.
+ */
+export declare function dot(a: Float32Array, b: Float32Array): number;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/docs/embeddings/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../../../src/docs/embeddings/embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,WAAW,4BAA4B,CAAC;AAerD,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,GAAG,IAAI,GACxD,IAAI,CAKN;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA6BrE;AAED,2CAA2C;AAC3C,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAGnE;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAK5D"}

package/dist/docs/embeddings/embedder.js

@@ -0,0 +1,113 @@
+/**
+ * Thin wrapper around @huggingface/transformers' feature-extraction
+ * pipeline.
+ *
+ * Why a wrapper instead of using `pipeline()` directly at call sites?
+ *   1. The pipeline is HEAVY to load (~25MB model download + ~200ms
+ *      ORT init). We want exactly one instance per process, created
+ *      lazily on first use.
+ *   2. The library is pure ESM and import-heavy; isolating it here
+ *      means the rest of the codebase doesn't pay the cost on startup
+ *      and tests that don't need embeddings don't load it.
+ *   3. We want a stable surface (encode(string[]) → Float32Array[])
+ *      regardless of which Transformers.js version we're on.
+ *
+ * Model: sentence-transformers/all-MiniLM-L6-v2 (via the Xenova ONNX
+ * port). 384-dim normalized sentence embeddings, ~25MB on disk,
+ * ~5–10ms per encode on a modern CPU. Trained on 1B+ sentence pairs
+ * with contrastive loss → great general-purpose retrieval quality at
+ * tiny model size.
+ */
+export const EMBED_DIM = 384;
+export const EMBED_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/**
+ * Cached pipeline promise. We store the promise (not the resolved
+ * value) so concurrent first-callers all wait on the same
+ * initialization instead of each kicking off their own.
+ */
+let pipelinePromise = null;
+/**
+ * For the test/dev path where we want to inject a stub instead of
+ * downloading 25MB of weights into a temp dir.
+ */
+let overrideEmbed = null;
+export function __setEmbedderForTests(fn) {
+    overrideEmbed = fn;
+    // Also clear any lazily-loaded real pipeline so a test that runs
+    // after a real load doesn't accidentally use the stub afterward.
+    pipelinePromise = null;
+}
+async function loadPipeline() {
+    if (pipelinePromise)
+        return pipelinePromise;
+    pipelinePromise = (async () => {
+        // Dynamic import keeps the heavy ESM out of the module-load graph
+        // until someone actually needs an embedding. The whole transformers
+        // package weighs ~30MB of JS — not something we want loaded just
+        // because a user called `search_roblox_docs` with one keyword.
+        const t = await import('@huggingface/transformers');
+        // `pipeline('feature-extraction', ...)` returns a callable that
+        // takes a string or string[] and returns a Tensor.
+        return await t.pipeline('feature-extraction', EMBED_MODEL, {
+            // fp32 is the safest dtype on Node — q4f16 hit ORT graph-fusion
+            // bugs (see HF issue #1567). Size on disk is ~90MB for fp32 vs
+            // ~25MB for q8; for a one-time download we accept that cost in
+            // exchange for not having to debug runtime errors later.
+            dtype: 'fp32',
+        });
+    })();
+    return pipelinePromise;
+}
+/**
+ * Encode an array of strings into normalized 384-dim Float32 vectors.
+ *
+ * Normalization is done by the model (pooling: 'mean', normalize: true)
+ * so cosine similarity == plain dot product, which is hot-path-cheap.
+ *
+ * Batched internally — pass big arrays (50–200 items per call is fine)
+ * to amortize tensor allocation overhead.
+ */
+export async function encode(texts) {
+    if (texts.length === 0)
+        return [];
+    if (overrideEmbed)
+        return await overrideEmbed(texts);
+    const pipe = await loadPipeline();
+    const output = await pipe(texts, { pooling: 'mean', normalize: true });
+    // Transformers.js returns a single Tensor of shape [N, EMBED_DIM]
+    // even for single-input calls. `.tolist()` would give a nested
+    // array; for perf we slice the flat backing buffer ourselves.
+    const data = output.data instanceof Float32Array
+        ? output.data
+        : Float32Array.from(output.data);
+    const dim = output.dims?.[1] ?? EMBED_DIM;
+    if (dim !== EMBED_DIM) {
+        // Defensive: if HF ever updates the model and dim changes, we'd
+        // index incompatible vectors and silently return garbage. Loud
+        // failure is better.
+        throw new Error(`Embedding dim mismatch: model returned ${dim}, expected ${EMBED_DIM}. ` +
+            `Bump EMBED_DIM and rebuild the docs index.`);
+    }
+    const out = new Array(texts.length);
+    for (let i = 0; i < texts.length; i++) {
+        out[i] = data.subarray(i * dim, (i + 1) * dim).slice(); // copy
+    }
+    return out;
+}
+/** Convenience: encode a single string. */
+export async function encodeOne(text) {
+    const [vec] = await encode([text]);
+    return vec;
+}
+/**
+ * Dot product of two normalized vectors == cosine similarity. Tight
+ * loop, no allocations, called millions of times during query.
+ */
+export function dot(a, b) {
+    const n = a.length;
+    let s = 0;
+    for (let i = 0; i < n; i++)
+        s += a[i] * b[i];
+    return s;
+}
+//# sourceMappingURL=embedder.js.map

package/dist/docs/embeddings/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../../../src/docs/embeddings/embedder.ts"],"names":[],"mappings":"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"}

package/dist/docs/embeddings/index.d.ts

@@ -0,0 +1,102 @@
+import { type Chunk } from './chunker.js';
+export interface IndexMeta {
+    schemaVersion: number;
+    /** Docs SHA this index was built against. Used to detect staleness. */
+    sha: string;
+    /** Embedding model identifier; mismatched models are incompatible vectors. */
+    model: string;
+    /** Vector dimension (defensive — matches embedder.EMBED_DIM at build time). */
+    dim: number;
+    /** Number of chunks indexed. */
+    chunkCount: number;
+    /** ISO timestamp of the build. */
+    builtAt: string;
+    /** ms spent building (informational). */
+    buildDurationMs: number;
+}
+export interface DocsIndex {
+    meta: IndexMeta;
+    chunks: Chunk[];
+    /** Packed N*dim vectors. */
+    vectors: Float32Array;
+}
+export interface QueryHit {
+    chunk: Chunk;
+    /** Raw cosine score in [-1, 1] (in practice [0, 1] for these vectors). */
+    score: number;
+}
+export declare function indexDir(cacheDir: string): string;
+export interface BuildOptions {
+    /** Override the embedding model identifier recorded in meta. */
+    model?: string;
+    /**
+     * Chunks per embed call. Larger = fewer round-trips, but each call
+     * holds the batch in memory. 64 is a comfortable middle.
+     */
+    batchSize?: number;
+    /** Optional progress callback for long builds. */
+    onProgress?: (done: number, total: number) => void;
+}
+/**
+ * Build (or rebuild) the vector index for the docs tree in `cacheDir`.
+ * Writes atomically: builds into a tmp dir then renames into place
+ * so a partial/aborted build never leaves the index half-written.
+ */
+export declare function buildIndex(cacheDir: string, docsSha: string, options?: BuildOptions): Promise<IndexMeta>;
+/**
+ * Try to load the on-disk index. Returns null if absent, corrupt, or
+ * mismatched against `expectedSha` / model / dim. Callers should treat
+ * null as "needs rebuild".
+ */
+export declare function loadIndex(cacheDir: string, expectedSha?: string, expectedModel?: string): Promise<DocsIndex | null>;
+export interface QueryOptions {
+    /** Number of results to return. Default 10. */
+    topK?: number;
+    /**
+     * MMR diversity weight in [0, 1]. 0 = pure relevance, 1 = pure
+     * diversity. Default 0.3 — small bias toward diversity so we don't
+     * return five near-identical chunks from the same page.
+     */
+    diversity?: number;
+    /**
+     * Restrict to chunks whose `path` starts with this prefix.
+     * Mirrors `SearchOptions.scope` from the keyword search.
+     */
+    scope?: string;
+    /**
+     * Restrict to chunks of these kinds. Default: all kinds.
+     * Useful for "search only API reference" (yaml-member / yaml-preamble).
+     */
+    kinds?: Chunk['kind'][];
+    /**
+     * Initial candidate pool size before MMR rerank. Should be >= topK.
+     * Default 4× topK, capped at 200. Bigger = better diversity options
+     * but more cosine math at query time.
+     */
+    poolSize?: number;
+}
+/**
+ * Run a semantic query against the index. Returns top-K hits ranked
+ * by cosine similarity and diversified with MMR.
+ *
+ * MMR (Maximal Marginal Relevance) algorithm:
+ *   1. Pick the highest-cosine candidate as the first result.
+ *   2. For each subsequent slot, score remaining candidates as
+ *        λ * cosine_to_query - (1 - λ) * max_cosine_to_already_picked
+ *      and pick the highest.
+ *   3. Repeat until we have K results.
+ *
+ * This guarantees that a query like "Motor6D" doesn't return six
+ * near-duplicate snippets from the same Motor6D.yaml file — we get
+ * the top member, then the next-best chunk that's *also* different
+ * from what we've already shown.
+ */
+export declare function query(index: DocsIndex, queryText: string, options?: QueryOptions): Promise<QueryHit[]>;
+/**
+ * Has an index been built for this cache dir? Cheap stat — doesn't
+ * touch the vector file.
+ */
+export declare function indexExists(cacheDir: string): Promise<boolean>;
+/** Wipe the index directory. */
+export declare function clearIndex(cacheDir: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/embeddings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/docs/embeddings/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAgCpD,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,4BAA4B;IAC5B,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjD;AAgBD,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,SAAS,CAAC,CAqDpB;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA6C3B;AAID,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,KAAK,CACzB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAyErB;AAQD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOpE;AAED,gCAAgC;AAChC,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE"}

package/dist/docs/embeddings/index.js

@@ -0,0 +1,250 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { chunkAll } from './chunker.js';
+import { dot, encode, encodeOne, EMBED_DIM } from './embedder.js';
+/**
+ * Vector index for the Roblox creator-docs mirror.
+ *
+ * On-disk layout (sits next to the cached docs tree):
+ *
+ *   <cacheDir>/
+ *     content/                    ← (existing) extracted docs
+ *     index/
+ *       meta.json                 ← schema version, chunk count, sha
+ *       chunks.json               ← Chunk[] metadata (path, lines, …)
+ *       vectors.bin               ← Float32Array, N*EMBED_DIM packed
+ *
+ * Why a separate `index/` dir instead of jamming it into `meta.json`?
+ *   1. We keep it adjacent to the data it indexes — the docs cache
+ *      already knows how to wipe itself; we just nuke `index/` alongside.
+ *   2. `vectors.bin` is a flat Float32 dump (~4.6MB at 3k chunks) —
+ *      loading it with `fs.readFile` + `new Float32Array(buf.buffer)`
+ *      is sub-10ms vs. parsing the same data out of JSON.
+ *
+ * Why flat cosine instead of HNSW / IVF?
+ *   At ~19k chunks × 384 dims (measured on the real docs tree),
+ *   brute-force takes ~5-15ms in JS — still well within "interactive"
+ *   for a tool call. HNSW would add a dependency and complexity for
+ *   savings that don't move the user-visible needle. If the index
+ *   grows past ~100k chunks we should reconsider.
+ */
+const INDEX_SCHEMA_VERSION = 2;
+export function indexDir(cacheDir) {
+    return path.join(cacheDir, 'index');
+}
+function indexMetaPath(cacheDir) {
+    return path.join(indexDir(cacheDir), 'meta.json');
+}
+function indexChunksPath(cacheDir) {
+    return path.join(indexDir(cacheDir), 'chunks.json');
+}
+function indexVectorsPath(cacheDir) {
+    return path.join(indexDir(cacheDir), 'vectors.bin');
+}
+/**
+ * Build (or rebuild) the vector index for the docs tree in `cacheDir`.
+ * Writes atomically: builds into a tmp dir then renames into place
+ * so a partial/aborted build never leaves the index half-written.
+ */
+export async function buildIndex(cacheDir, docsSha, options = {}) {
+    const t0 = Date.now();
+    const model = options.model ?? 'Xenova/all-MiniLM-L6-v2';
+    const batchSize = Math.max(1, Math.min(options.batchSize ?? 64, 256));
+    const chunks = await chunkAll(cacheDir);
+    if (chunks.length === 0) {
+        throw new Error(`No chunks produced from ${cacheDir}/content — is the docs cache empty?`);
+    }
+    // Embed in batches. The packed Float32Array is allocated up-front
+    // so each batch writes directly into its slice — no per-batch
+    // concat / copy.
+    const vectors = new Float32Array(chunks.length * EMBED_DIM);
+    for (let i = 0; i < chunks.length; i += batchSize) {
+        const batch = chunks.slice(i, i + batchSize);
+        const vecs = await encode(batch.map((c) => c.text));
+        for (let j = 0; j < vecs.length; j++) {
+            vectors.set(vecs[j], (i + j) * EMBED_DIM);
+        }
+        options.onProgress?.(Math.min(i + batchSize, chunks.length), chunks.length);
+    }
+    // Write atomically via tmp dir → rename.
+    const dir = indexDir(cacheDir);
+    const tmp = `${dir}.tmp-${process.pid}-${Date.now()}`;
+    await fs.mkdir(tmp, { recursive: true });
+    const meta = {
+        schemaVersion: INDEX_SCHEMA_VERSION,
+        sha: docsSha,
+        model,
+        dim: EMBED_DIM,
+        chunkCount: chunks.length,
+        builtAt: new Date().toISOString(),
+        buildDurationMs: Date.now() - t0,
+    };
+    await fs.writeFile(path.join(tmp, 'meta.json'), JSON.stringify(meta, null, 2), 'utf8');
+    await fs.writeFile(path.join(tmp, 'chunks.json'), JSON.stringify(chunks), 'utf8');
+    await fs.writeFile(path.join(tmp, 'vectors.bin'), Buffer.from(vectors.buffer, vectors.byteOffset, vectors.byteLength));
+    // Wipe old, rename new. Two-step because some platforms (Windows)
+    // don't allow renaming over an existing directory.
+    await fs.rm(dir, { recursive: true, force: true });
+    await fs.rename(tmp, dir);
+    return meta;
+}
+// ---------- Load / check ----------
+/**
+ * Try to load the on-disk index. Returns null if absent, corrupt, or
+ * mismatched against `expectedSha` / model / dim. Callers should treat
+ * null as "needs rebuild".
+ */
+export async function loadIndex(cacheDir, expectedSha, expectedModel) {
+    let metaRaw;
+    let chunksRaw;
+    let vecBuf;
+    try {
+        [metaRaw, chunksRaw, vecBuf] = await Promise.all([
+            fs.readFile(indexMetaPath(cacheDir), 'utf8'),
+            fs.readFile(indexChunksPath(cacheDir), 'utf8'),
+            fs.readFile(indexVectorsPath(cacheDir)),
+        ]);
+    }
+    catch {
+        return null;
+    }
+    let meta;
+    try {
+        meta = JSON.parse(metaRaw);
+    }
+    catch {
+        return null;
+    }
+    if (meta.schemaVersion !== INDEX_SCHEMA_VERSION)
+        return null;
+    if (expectedSha && meta.sha && meta.sha !== expectedSha)
+        return null;
+    if (expectedModel && meta.model !== expectedModel)
+        return null;
+    if (meta.dim !== EMBED_DIM)
+        return null;
+    let chunks;
+    try {
+        chunks = JSON.parse(chunksRaw);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(chunks) || chunks.length !== meta.chunkCount)
+        return null;
+    // Wrap the underlying buffer as a Float32Array — zero-copy.
+    // `vecBuf.buffer` may be larger than vecBuf if Node pooled it, so
+    // honor byteOffset/byteLength.
+    const expectedBytes = meta.chunkCount * meta.dim * 4;
+    if (vecBuf.byteLength !== expectedBytes)
+        return null;
+    const vectors = new Float32Array(vecBuf.buffer, vecBuf.byteOffset, meta.chunkCount * meta.dim);
+    return { meta, chunks, vectors };
+}
+/**
+ * Run a semantic query against the index. Returns top-K hits ranked
+ * by cosine similarity and diversified with MMR.
+ *
+ * MMR (Maximal Marginal Relevance) algorithm:
+ *   1. Pick the highest-cosine candidate as the first result.
+ *   2. For each subsequent slot, score remaining candidates as
+ *        λ * cosine_to_query - (1 - λ) * max_cosine_to_already_picked
+ *      and pick the highest.
+ *   3. Repeat until we have K results.
+ *
+ * This guarantees that a query like "Motor6D" doesn't return six
+ * near-duplicate snippets from the same Motor6D.yaml file — we get
+ * the top member, then the next-best chunk that's *also* different
+ * from what we've already shown.
+ */
+export async function query(index, queryText, options = {}) {
+    if (!queryText || index.chunks.length === 0)
+        return [];
+    const topK = Math.max(1, Math.min(options.topK ?? 10, 100));
+    const diversity = clamp(options.diversity ?? 0.3, 0, 1);
+    const poolSize = Math.max(topK, Math.min(options.poolSize ?? topK * 4, Math.min(200, index.chunks.length)));
+    const qvec = await encodeOne(queryText);
+    // Score every chunk that passes the scope / kind filter.
+    // For 3k chunks this is ~1.1M float multiplies = sub-millisecond.
+    const dim = index.meta.dim;
+    const scope = options.scope;
+    const kinds = options.kinds ? new Set(options.kinds) : null;
+    const scored = [];
+    for (let i = 0; i < index.chunks.length; i++) {
+        const c = index.chunks[i];
+        if (scope && !c.path.startsWith(scope))
+            continue;
+        if (kinds && !kinds.has(c.kind))
+            continue;
+        const vec = index.vectors.subarray(i * dim, (i + 1) * dim);
+        scored.push({ idx: i, score: dot(qvec, vec) });
+    }
+    if (scored.length === 0)
+        return [];
+    // Partial sort: take top poolSize candidates. For our sizes a full
+    // sort is fast enough; if perf ever matters use a heap.
+    scored.sort((a, b) => b.score - a.score);
+    const pool = scored.slice(0, poolSize);
+    // MMR. λ in textbook MMR == "relevance weight" — we use
+    // λ = 1 - diversity so that diversity=0 → λ=1 → pure relevance,
+    // diversity=1 → λ=0 → pure diversity.
+    const lambda = 1 - diversity;
+    const picked = []; // positions inside `pool`
+    const used = new Uint8Array(pool.length);
+    // Always pick the highest-score candidate first.
+    picked.push(0);
+    used[0] = 1;
+    while (picked.length < topK && picked.length < pool.length) {
+        let bestI = -1;
+        let bestScore = -Infinity;
+        for (let i = 0; i < pool.length; i++) {
+            if (used[i])
+                continue;
+            const cand = pool[i];
+            const candVec = index.vectors.subarray(cand.idx * dim, (cand.idx + 1) * dim);
+            // Max similarity to anything already picked.
+            let maxSim = -Infinity;
+            for (const pi of picked) {
+                const pickedVec = index.vectors.subarray(pool[pi].idx * dim, (pool[pi].idx + 1) * dim);
+                const sim = dot(candVec, pickedVec);
+                if (sim > maxSim)
+                    maxSim = sim;
+            }
+            const mmrScore = lambda * cand.score - (1 - lambda) * maxSim;
+            if (mmrScore > bestScore) {
+                bestScore = mmrScore;
+                bestI = i;
+            }
+        }
+        if (bestI < 0)
+            break;
+        picked.push(bestI);
+        used[bestI] = 1;
+    }
+    return picked.map((p) => ({
+        chunk: index.chunks[pool[p].idx],
+        score: pool[p].score,
+    }));
+}
+function clamp(n, lo, hi) {
+    return Math.min(hi, Math.max(lo, n));
+}
+// ---------- Convenience ----------
+/**
+ * Has an index been built for this cache dir? Cheap stat — doesn't
+ * touch the vector file.
+ */
+export async function indexExists(cacheDir) {
+    try {
+        const stat = await fs.stat(indexMetaPath(cacheDir));
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Wipe the index directory. */
+export async function clearIndex(cacheDir) {
+    await fs.rm(indexDir(cacheDir), { recursive: true, force: true });
+}
+//# sourceMappingURL=index.js.map

package/dist/docs/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/docs/embeddings/index.ts"],"names":[],"mappings":"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"}

package/dist/docs/embeddings/manager.d.ts

@@ -0,0 +1,68 @@
+import { type DocsIndex, type IndexMeta } from './index.js';
+/**
+ * Process-wide manager for the semantic docs index.
+ *
+ * Responsibilities:
+ *   1. Lazy-load the index on first semantic query so plain keyword
+ *      searches don't pay the cost.
+ *   2. Cache the loaded index in memory (packed Float32 vectors are
+ *      ~29MB for the measured ~19k chunks).
+ *   3. Coalesce concurrent first-callers onto the same load/build
+ *      promise so we don't run two builds in parallel.
+ *   4. Rebuild on docs-SHA mismatch (the fetcher handed us a new
+ *      docs cache → invalidate stale vectors).
+ *
+ * NOT this module's job:
+ *   - Deciding *when* to rebuild based on TTL — that's the fetcher.
+ *   - Knowing about the keyword search — `search.ts` calls this lazily
+ *     and falls back to keyword-only if the load/build fails.
+ */
+interface CachedEntry {
+    cacheDir: string;
+    sha: string;
+    index: DocsIndex;
+}
+/**
+ * Test seam: lets unit tests inject a precanned index and skip the
+ * load/build path entirely. The keyword + hybrid rerank machinery
+ * uses `getOrBuild` directly, so injecting here is enough to
+ * deterministically exercise reranking.
+ */
+export declare function __setIndexForTests(entry: CachedEntry | null): void;
+export interface GetOrBuildOptions {
+    /** If true, suppress build-on-miss and only attempt a load. */
+    loadOnly?: boolean;
+    /** Build progress hook (passed through to buildIndex). */
+    onProgress?: (done: number, total: number) => void;
+}
+/**
+ * Return a usable in-memory index for `cacheDir`@`docsSha`, building
+ * it if necessary. Returns null when the index can't be obtained — the
+ * caller should fall back to keyword-only mode in that case.
+ *
+ * Decision tree:
+ *   1. We already have a hot index for this (cacheDir, sha) → return it.
+ *   2. Otherwise try to loadIndex() from disk — if it matches the sha,
+ *      cache + return it.
+ *   3. Otherwise, if loadOnly: return null.
+ *   4. Otherwise build a fresh index. Heavy: ~25MB model download +
+ *      embedding ~19k chunks. Measured at ~8 minutes on a single CPU
+ *      box; faster on multi-core / GPU. Subsequent process restarts
+ *      load from disk in <100ms.
+ *
+ * Errors during build are swallowed (returned as null) because we
+ * don't want a semantic-index failure to break the keyword search.
+ */
+export declare function getOrBuild(cacheDir: string, docsSha: string, options?: GetOrBuildOptions): Promise<DocsIndex | null>;
+/**
+ * Drop the in-memory cache. Used when the docs cache itself is
+ * re-fetched and we know the on-disk vectors are now stale. The
+ * fetcher (or its caller) is expected to nuke the index directory
+ * separately if it wants the on-disk vectors gone too — typically
+ * `buildIndex` will overwrite atomically on the next call anyway.
+ */
+export declare function invalidate(): void;
+/** Diagnostic: is anything cached right now? */
+export declare function currentMeta(): IndexMeta | null;
+export {};
+//# sourceMappingURL=manager.d.ts.map

package/dist/docs/embeddings/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../src/docs/embeddings/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAGnF;;;;;;;;;;;;;;;;;GAiBG;AAEH,UAAU,WAAW;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;CAClB;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAGlE;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAoD3B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,gDAAgD;AAChD,wBAAgB,WAAW,IAAI,SAAS,GAAG,IAAI,CAE9C"}