tailwindcss-docs-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitaly Gorodetsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# tailwindcss-docs-mcp
+
+[![npm version](https://img.shields.io/npm/v/tailwindcss-docs-mcp)](https://www.npmjs.com/package/tailwindcss-docs-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Local semantic search for Tailwind CSS documentation via [Model Context Protocol](https://modelcontextprotocol.io).
+
+LLMs hallucinate Tailwind classes. This MCP server downloads the docs once, embeds them locally with ONNX, and gives your AI instant semantic search — no API keys, no external services, no per-query costs.
+
+## Installation
+
+```json
+{
+  "mcpServers": {
+    "tailwindcss-docs-mcp": {
+      "command": "npx",
+      "args": ["-y", "tailwindcss-docs-mcp"]
+    }
+  }
+}
+```
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add tailwindcss-docs-mcp -- npx -y tailwindcss-docs-mcp
+```
+
+</details>
+
+<details>
+<summary>Cursor / Windsurf</summary>
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tailwindcss-docs-mcp": {
+      "command": "npx",
+      "args": ["-y", "tailwindcss-docs-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+### First run
+
+On first boot the embedding model (~27 MB) downloads in the background. The server is usable immediately — tools that need embeddings will return a status message until the model is ready. Use `check_status` to verify.
+
+Then ask your assistant: _"Fetch the Tailwind CSS docs"_ — this downloads and indexes the documentation. You only need to do this once.
+
+### Example prompts
+
+- _"How do I center a div with Tailwind?"_
+- _"Show me the grid layout utilities"_
+- _"What's the dark mode configuration in v4?"_
+- _"Search for responsive padding classes"_
+
+## Tools
+
+### `fetch_docs`
+
+Download and index Tailwind CSS documentation. Run once, re-run with `force: true` to refresh.
+
+| Parameter | Type      | Default | Description                        |
+| --------- | --------- | ------- | ---------------------------------- |
+| `version` | `string`  | `"v4"`  | `"v3"` or `"v4"`                   |
+| `force`   | `boolean` | `false` | Re-download even if already cached |
+
+### `search_docs`
+
+Semantic + keyword hybrid search. Returns relevant snippets with code examples and deep links.
+
+| Parameter | Type     | Default | Description                   |
+| --------- | -------- | ------- | ----------------------------- |
+| `query`   | `string` | —       | Natural language search query |
+| `version` | `string` | `"v4"`  | `"v3"` or `"v4"`              |
+| `limit`   | `number` | `5`     | Results to return (1–20)      |
+
+### `list_utilities`
+
+Browse all utility categories (Layout, Spacing, Typography, etc.).
+
+| Parameter  | Type     | Default | Description             |
+| ---------- | -------- | ------- | ----------------------- |
+| `category` | `string` | —       | Filter by category name |
+| `version`  | `string` | `"v4"`  | `"v3"` or `"v4"`        |
+
+### `check_status`
+
+Check index state — doc counts, embedding model status, last indexed time.
+
+| Parameter | Type     | Default | Description                             |
+| --------- | -------- | ------- | --------------------------------------- |
+| `version` | `string` | —       | Check specific version, or omit for all |
+
+## How It Works
+
+```
+GitHub → Fetch MDX → Parse → Chunk by heading → Embed (ONNX) → SQLite
+                                                                  ↓
+                                          search_docs → Hybrid Search
+                                                        Semantic + FTS5
+                                                        Rank Fusion
+```
+
+- **Hybrid search** — cosine similarity on embeddings + FTS5 keyword match, fused via reciprocal rank fusion. Semantic handles _"how to center a div"_, keywords handle exact classes like `grid-cols-3`.
+- **Incremental re-indexing** — SHA-256 content hashing per chunk. Unchanged content skips re-embedding.
+- **In-process embeddings** — `snowflake-arctic-embed-xs` (22M params, 384 dims) runs locally via ONNX. No external calls.
+- **Auto model management** — the embedding model (~27 MB) downloads on first boot and caches locally. Server starts immediately; model loads in background.
+
+## Configuration
+
+| Variable                            | Default                   | Description                           |
+| ----------------------------------- | ------------------------- | ------------------------------------- |
+| `TAILWIND_DOCS_MCP_DEFAULT_VERSION` | `v4`                      | Set to `v3` for Tailwind 3.x projects |
+| `TAILWIND_DOCS_MCP_PATH`            | `~/.tailwindcss-docs-mcp` | Data directory                        |
+
+<details>
+<summary>Using with Tailwind CSS v3</summary>
+
+```json
+{
+  "mcpServers": {
+    "tailwindcss-docs-mcp": {
+      "command": "npx",
+      "args": ["-y", "tailwindcss-docs-mcp"],
+      "env": {
+        "TAILWIND_DOCS_MCP_DEFAULT_VERSION": "v3"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Development
+
+```bash
+git clone https://github.com/vitalis/tailwindcss-docs-mcp.git
+cd tailwindcss-docs-mcp
+bun install
+bun run test                   # Vitest
+bun run build                  # TypeScript
+bunx biome check src/ test/    # Lint
+```
+
+## Acknowledgments
+
+Inspired by [HexDocs MCP](https://github.com/bradleygolden/hexdocs-mcp), which does the same for Elixir/Hex documentation.
+
+## License
+
+[MIT](LICENSE)

package/dist/auto-index.d.ts

@@ -0,0 +1,21 @@
+import type { Embedder } from "./pipeline/embedder.js";
+import type { Database } from "./storage/database.js";
+import type { Config } from "./utils/config.js";
+/**
+ * Callbacks for auto-index lifecycle events.
+ */
+export interface AutoIndexCallbacks {
+    onStart: () => void;
+    onComplete: () => void;
+    onError: (error: unknown) => void;
+}
+/**
+ * Auto-index the default Tailwind CSS version if not already indexed.
+ *
+ * Checks the database for an existing index. If found, calls onComplete
+ * immediately. Otherwise, triggers handleFetchDocs in the background.
+ *
+ * Reuses handleFetchDocs which has its own mutex for concurrent-call safety.
+ */
+export declare function maybeAutoIndex(config: Config, db: Database, embedder: Embedder, callbacks: AutoIndexCallbacks): Promise<void>;
+//# sourceMappingURL=auto-index.d.ts.map

package/dist/auto-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-index.d.ts","sourceRoot":"","sources":["../src/auto-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,kBAAkB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/auto-index.js

@@ -0,0 +1,27 @@
+import { handleFetchDocs } from "./tools/fetch-docs.js";
+/**
+ * Auto-index the default Tailwind CSS version if not already indexed.
+ *
+ * Checks the database for an existing index. If found, calls onComplete
+ * immediately. Otherwise, triggers handleFetchDocs in the background.
+ *
+ * Reuses handleFetchDocs which has its own mutex for concurrent-call safety.
+ */
+export async function maybeAutoIndex(config, db, embedder, callbacks) {
+    const version = config.defaultVersion;
+    // Skip if already indexed
+    const status = db.getIndexStatus(version);
+    if (status.length > 0) {
+        callbacks.onComplete();
+        return;
+    }
+    callbacks.onStart();
+    try {
+        await handleFetchDocs({ version }, config, db, embedder);
+        callbacks.onComplete();
+    }
+    catch (error) {
+        callbacks.onError(error);
+    }
+}
+//# sourceMappingURL=auto-index.js.map

package/dist/auto-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-index.js","sourceRoot":"","sources":["../src/auto-index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAYxD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,EAAY,EACZ,QAAkB,EAClB,SAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;IAEtC,0BAA0B;IAC1B,MAAM,MAAM,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,SAAS,CAAC,UAAU,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,SAAS,CAAC,OAAO,EAAE,CAAC;IAEpB,IAAI,CAAC;QACH,MAAM,eAAe,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACzD,SAAS,CAAC,UAAU,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * tailwindcss-docs-mcp — MCP server entry point.
+ *
+ * Local semantic search for Tailwind CSS documentation
+ * via Model Context Protocol (MCP).
+ *
+ * Boot workflow:
+ * 1. Start MCP server immediately (database only, no embedder)
+ * 2. Try to load embedding model from cache (no network, fast)
+ *    - Success: server is fully operational, check for updates in background
+ *    - Failure: download model in background, server tools fail until ready
+ * 3. Background update/download completes — embedder is hot-swapped immediately
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG"}

package/dist/index.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * tailwindcss-docs-mcp — MCP server entry point.
+ *
+ * Local semantic search for Tailwind CSS documentation
+ * via Model Context Protocol (MCP).
+ *
+ * Boot workflow:
+ * 1. Start MCP server immediately (database only, no embedder)
+ * 2. Try to load embedding model from cache (no network, fast)
+ *    - Success: server is fully operational, check for updates in background
+ *    - Failure: download model in background, server tools fail until ready
+ * 3. Background update/download completes — embedder is hot-swapped immediately
+ */
+import { mkdirSync } from "node:fs";
+import { createEmbedder, loadCachedEmbedder } from "./pipeline/embedder.js";
+import { createServer } from "./server.js";
+import { createDatabase } from "./storage/database.js";
+import { loadConfig } from "./utils/config.js";
+async function main() {
+    const config = loadConfig();
+    // Ensure data directory exists
+    mkdirSync(config.dataDir, { recursive: true });
+    // Initialize database
+    const db = await createDatabase(config);
+    // Ensure database is closed on process exit (WAL checkpoint, release locks)
+    process.on("exit", () => {
+        db.close();
+    });
+    // Start MCP server immediately (embedder loads in background)
+    const server = await createServer({ config, db, embedder: null });
+    // Phase 1: Try local cache (fast, no network)
+    const cached = await loadCachedEmbedder(config);
+    if (cached) {
+        // Model loaded from cache — server is fully operational
+        server.setEmbedder(cached);
+        console.error("[tailwindcss-docs-mcp] Embedding model loaded from cache.");
+        // Phase 2: Check for model updates in background, hot-swap if updated
+        createEmbedder(config)
+            .then((updated) => {
+            server.setEmbedder(updated);
+            console.error("[tailwindcss-docs-mcp] Model update check complete.");
+        })
+            .catch((error) => {
+            console.error("[tailwindcss-docs-mcp] Model update check failed:", error);
+        });
+    }
+    else {
+        // Model not cached — download in background
+        server.setEmbedderStatus("downloading");
+        console.error("[tailwindcss-docs-mcp] Embedding model not cached. Downloading in background...");
+        createEmbedder(config)
+            .then((embedder) => {
+            server.setEmbedder(embedder);
+            console.error("[tailwindcss-docs-mcp] Embedding model downloaded and ready.");
+        })
+            .catch((error) => {
+            server.setEmbedderStatus("failed");
+            console.error("[tailwindcss-docs-mcp] Failed to download embedding model:", error);
+        });
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAE5B,+BAA+B;IAC/B,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/C,sBAAsB;IACtB,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;IAExC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,8DAA8D;IAC9D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAElE,8CAA8C;IAC9C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAEhD,IAAI,MAAM,EAAE,CAAC;QACX,wDAAwD;QACxD,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAE3E,sEAAsE;QACtE,cAAc,CAAC,MAAM,CAAC;aACnB,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YAChB,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACvE,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,OAAO,CAAC,KAAK,CAAC,mDAAmD,EAAE,KAAK,CAAC,CAAC;QAC5E,CAAC,CAAC,CAAC;IACP,CAAC;SAAM,CAAC;QACN,4CAA4C;QAC5C,MAAM,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;QACxC,OAAO,CAAC,KAAK,CACX,iFAAiF,CAClF,CAAC;QACF,cAAc,CAAC,MAAM,CAAC;aACnB,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;YACjB,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,CAAC,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAChF,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,4DAA4D,EAAE,KAAK,CAAC,CAAC;QACrF,CAAC,CAAC,CAAC;IACP,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/pipeline/chunker.d.ts

@@ -0,0 +1,61 @@
+import type { CleanDocument } from "./parser.js";
+/**
+ * A chunk of documentation content with metadata for embedding and retrieval.
+ */
+export interface Chunk {
+    /** SHA-256 hash of content for deduplication and incremental re-indexing */
+    id: string;
+    /** Parent document slug (e.g., "padding") */
+    docSlug: string;
+    /** Heading breadcrumb (e.g., "## Basic usage > ### Padding a single side") */
+    heading: string;
+    /** Chunk text content (clean markdown) */
+    content: string;
+    /** Deep link URL (e.g., "https://tailwindcss.com/docs/padding#basic-usage") */
+    url: string;
+    /** Tailwind CSS version */
+    version: string;
+    /** Approximate token count for context window awareness */
+    tokenCount: number;
+}
+/**
+ * Options for the chunking process.
+ */
+export interface ChunkOptions {
+    /** Maximum tokens per chunk (default: 500) */
+    maxTokens?: number;
+}
+/**
+ * Split a clean document into semantically meaningful chunks.
+ *
+ * Chunking rules:
+ * 1. Split on `##` headings — each `##` section becomes one or more chunks
+ * 2. Max chunk size: ~500 tokens (configurable)
+ * 3. Code blocks stay intact — never split a code block across chunks
+ * 4. Heading breadcrumb: include heading hierarchy in each chunk
+ * 5. Overlap: include parent `##` heading text in sub-chunks
+ */
+export declare function chunkDocument(doc: CleanDocument, options?: ChunkOptions): Chunk[];
+/**
+ * Generate a SHA-256 content hash for a chunk.
+ *
+ * Used for incremental re-indexing: unchanged content produces
+ * the same hash, so we can skip re-embedding.
+ */
+export declare function contentHash(content: string): string;
+/**
+ * Estimate the token count for a string.
+ *
+ * Uses a simple heuristic: ~4 characters per token for English text.
+ * This is intentionally approximate — exact tokenization is model-dependent
+ * and not worth the overhead for chunk size estimation.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Convert a heading string into a URL-safe anchor fragment.
+ *
+ * "## Basic usage" -> "basic-usage"
+ * "### Adding horizontal padding" -> "adding-horizontal-padding"
+ */
+export declare function headingToAnchor(heading: string): string;
+//# sourceMappingURL=chunker.d.ts.map

package/dist/pipeline/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/pipeline/chunker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,KAAK,EAAE,CAcjF;AA2ID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQvD"}

package/dist/pipeline/chunker.js

@@ -0,0 +1,162 @@
+import { createHash } from "node:crypto";
+/** Default maximum tokens per chunk */
+const DEFAULT_MAX_TOKENS = 500;
+/**
+ * Split a clean document into semantically meaningful chunks.
+ *
+ * Chunking rules:
+ * 1. Split on `##` headings — each `##` section becomes one or more chunks
+ * 2. Max chunk size: ~500 tokens (configurable)
+ * 3. Code blocks stay intact — never split a code block across chunks
+ * 4. Heading breadcrumb: include heading hierarchy in each chunk
+ * 5. Overlap: include parent `##` heading text in sub-chunks
+ */
+export function chunkDocument(doc, options) {
+    const maxTokens = options?.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const content = doc.content.trim();
+    if (!content)
+        return [];
+    const sections = splitOnHeadingLevel(content, 2);
+    const chunks = [];
+    for (const section of sections) {
+        chunkSection(doc, section, maxTokens, chunks);
+    }
+    return chunks;
+}
+/** Process a single ## section, splitting further if needed. */
+function chunkSection(doc, section, maxTokens, out) {
+    const h2Heading = extractHeading(section, 2);
+    if (estimateTokens(section) <= maxTokens) {
+        out.push(buildChunk(doc, h2Heading || "", section.trim(), h2Heading || ""));
+        return;
+    }
+    const sectionBody = h2Heading ? section.slice(section.indexOf("\n") + 1).trim() : section;
+    const subsections = splitOnHeadingLevel(sectionBody, 3);
+    for (const sub of subsections) {
+        chunkSubsection(doc, sub, h2Heading, maxTokens, out);
+    }
+}
+/** Process a single ### subsection within a ## section. */
+function chunkSubsection(doc, sub, h2Heading, maxTokens, out) {
+    const h3Heading = extractHeading(sub, 3);
+    const breadcrumb = [h2Heading, h3Heading].filter(Boolean).join(" > ");
+    const chunkContent = h2Heading ? `${h2Heading}\n\n${sub.trim()}` : sub.trim();
+    if (estimateTokens(chunkContent) <= maxTokens) {
+        out.push(buildChunk(doc, breadcrumb, chunkContent, breadcrumb));
+        return;
+    }
+    const parts = splitByParagraphs(sub, maxTokens);
+    for (const part of parts) {
+        const partContent = h2Heading ? `${h2Heading}\n\n${part.trim()}` : part.trim();
+        out.push(buildChunk(doc, breadcrumb, partContent, breadcrumb));
+    }
+}
+function buildChunk(doc, breadcrumb, content, headingForAnchor) {
+    const lastHeading = headingForAnchor.split(" > ").pop() || "";
+    const anchor = headingToAnchor(lastHeading);
+    const url = anchor ? `${doc.url}#${anchor}` : doc.url;
+    return {
+        id: contentHash(content),
+        docSlug: doc.slug,
+        heading: breadcrumb,
+        content,
+        url,
+        version: doc.version,
+        tokenCount: estimateTokens(content),
+    };
+}
+function splitOnHeadingLevel(content, level) {
+    const prefix = "#".repeat(level);
+    const regex = new RegExp(`(?=^${prefix} )`, "gm");
+    return content.split(regex).filter((s) => s.trim());
+}
+/** Check if adding a piece to the accumulator would exceed the token limit. */
+function wouldExceedLimit(current, addition, maxTokens) {
+    return estimateTokens(`${current}\n\n${addition}`) > maxTokens;
+}
+/** Append a piece to the accumulator, or start fresh. */
+function appendOrStart(current, piece) {
+    return current ? `${current}\n\n${piece}` : piece;
+}
+/** Split content into paragraph-sized parts, never breaking code blocks. */
+function splitByParagraphs(content, maxTokens) {
+    const segments = content.split(/(```[\s\S]*?```)/);
+    const parts = [];
+    let current = "";
+    for (const segment of segments) {
+        if (segment.startsWith("```")) {
+            current = processCodeBlock(segment, current, maxTokens, parts);
+        }
+        else {
+            current = processTextBlock(segment, current, maxTokens, parts);
+        }
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+function processCodeBlock(block, current, maxTokens, parts) {
+    if (!wouldExceedLimit(current, block, maxTokens)) {
+        return appendOrStart(current, block);
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return block;
+}
+function processTextBlock(block, current, maxTokens, parts) {
+    const paragraphs = block.split(/\n\n+/);
+    let acc = current;
+    for (const para of paragraphs) {
+        if (!para.trim())
+            continue;
+        if (!wouldExceedLimit(acc, para, maxTokens)) {
+            acc = appendOrStart(acc, para);
+        }
+        else {
+            if (acc.trim())
+                parts.push(acc.trim());
+            acc = para;
+        }
+    }
+    return acc;
+}
+function extractHeading(text, level) {
+    const prefix = "#".repeat(level);
+    const firstLine = text.split("\n")[0].trim();
+    return firstLine.startsWith(`${prefix} `) ? firstLine : null;
+}
+/**
+ * Generate a SHA-256 content hash for a chunk.
+ *
+ * Used for incremental re-indexing: unchanged content produces
+ * the same hash, so we can skip re-embedding.
+ */
+export function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Estimate the token count for a string.
+ *
+ * Uses a simple heuristic: ~4 characters per token for English text.
+ * This is intentionally approximate — exact tokenization is model-dependent
+ * and not worth the overhead for chunk size estimation.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Convert a heading string into a URL-safe anchor fragment.
+ *
+ * "## Basic usage" -> "basic-usage"
+ * "### Adding horizontal padding" -> "adding-horizontal-padding"
+ */
+export function headingToAnchor(heading) {
+    return heading
+        .replace(/^#+\s*/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+//# sourceMappingURL=chunker.js.map

package/dist/pipeline/chunker.js.map

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

package/dist/pipeline/embedder.d.ts

@@ -0,0 +1,57 @@
+import type { Config } from "../utils/config.js";
+/**
+ * Options for embedding operations.
+ */
+export interface EmbedOptions {
+    /** Whether to prepend the query prefix (for search queries, not documents) */
+    isQuery: boolean;
+}
+/**
+ * The embedder instance, initialized with the ONNX model.
+ */
+export interface Embedder {
+    /** Embed a single text string */
+    embed(text: string, options?: EmbedOptions): Promise<Float32Array>;
+    /** Embed multiple texts in a batch */
+    embedBatch(texts: string[], options?: EmbedOptions): Promise<Float32Array[]>;
+    /** Check if the model is loaded */
+    isReady(): boolean;
+}
+/**
+ * Build the embedding input string for a chunk.
+ *
+ * Prepends metadata to improve retrieval quality:
+ * - Library context ("Tailwind CSS: {docTitle}")
+ * - Section context (heading breadcrumb)
+ * - Actual content
+ */
+export declare function buildEmbeddingInput(docTitle: string, heading: string, content: string): string;
+/**
+ * Normalize a vector to unit length (L2 normalization).
+ */
+export declare function normalize(vector: Float32Array): Float32Array;
+/**
+ * Try to load the embedder from local cache only (no network).
+ * Returns null if the model is not cached or cache is corrupted.
+ *
+ * CONCURRENCY: This function and `createEmbedder` both mutate the shared
+ * `env` singleton from @huggingface/transformers. They must NOT be called
+ * concurrently — always await one before starting the other.
+ */
+export declare function loadCachedEmbedder(config: Config): Promise<Embedder | null>;
+/**
+ * Create an embedder, downloading the model if needed.
+ *
+ * The model (snowflake-arctic-embed-xs) is downloaded on first use and cached locally.
+ * Subsequent calls load from cache (~27 MB model file).
+ *
+ * For search queries, the model requires prepending a specific prefix:
+ * "Represent this sentence for searching relevant passages: "
+ * This is handled automatically when `isQuery: true` is passed to embed().
+ *
+ * CONCURRENCY: This function and `loadCachedEmbedder` both mutate the shared
+ * `env` singleton from @huggingface/transformers. They must NOT be called
+ * concurrently — always await one before starting the other.
+ */
+export declare function createEmbedder(config: Config): Promise<Embedder>;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/pipeline/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../../src/pipeline/embedder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,iCAAiC;IACjC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnE,sCAAsC;IACtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC7E,mCAAmC;IACnC,OAAO,IAAI,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAa5D;AAgDD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAgBjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAQtE"}