soup-chop 1.0.0

package/README.md

@@ -0,0 +1,901 @@
+<p align="center">
+  <h1 align="center">soupChop</h1>
+  <p align="center">
+    <strong>The Just-In-Time Documentation Proxy for the Model Context Protocol.</strong>
+  </p>
+  <p align="center">
+    Give your AI agent instant, version-accurate access to any NPM package's documentation — no custom servers, no hallucinated APIs.
+  </p>
+  <p align="center">
+    Start from a soup of markdown, then chop and mince it into small, evidence-backed bites an agent can actually use.
+  </p>
+</p>
+
+---
+
+<p align="center">
+  <a href="#why-soup-chop">Why?</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#available-tools">Tools</a> •
+  <a href="#how-it-works">How It Works</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#for-library-authors">For Library Authors</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#faq">FAQ</a>
+</p>
+
+---
+
+## The Problem
+
+You're using an AI coding assistant. You ask it to help you with `mutts@2.0.0`.
+It confidently writes code using the `v1` API — because that's what was in its
+training data. You correct it. It apologizes. It does it again.
+
+**soupChop fixes this.**
+
+It gives your AI agent a live, on-demand window into the *actual* documentation
+for the *exact* version of the library you're working with. No pre-training
+required. No stale knowledge. No hallucinated function signatures.
+
+---
+
+## Why soupChop?
+
+| Without soupChop | With soupChop |
+| :--- | :--- |
+| AI guesses API from training data | AI reads the real docs for your exact version |
+| You paste READMEs into chat manually | Docs are fetched and structured automatically |
+| Full READMEs flood the context window | Only the relevant section is delivered |
+| Every library needs its own MCP server | One server handles every NPM package |
+
+---
+
+## Quick Start
+
+### Option 1 — Run directly with `npx`
+
+```bash
+npx soup-chop serve
+```
+
+That's it. The MCP server starts on `stdio` and is ready for your AI client to connect.
+
+### Option 2 — Install globally
+
+```bash
+npm install -g soup-chop
+soup-chop serve
+```
+
+### Option 3 — Inspect the supported clients
+
+```bash
+npx soup-chop clients
+```
+
+This prints the currently documented client list and highlights which clients support
+automatic file-based configuration on your current platform.
+
+### Option 4 — Auto-configure a supported client
+
+```bash
+npx soup-chop configure windsurf
+npx soup-chop configure cursor
+npx soup-chop configure cursor --project
+npx soup-chop configure vscode-copilot
+npx soup-chop configure firebase-studio
+npx soup-chop configure cursor --project --dry-run
+npx soup-chop configure cursor --print
+npx soup-chop configure cursor --project --local-build --dry-run
+```
+
+Use `--project` or `--global` when a client supports more than one writable scope. Without a flag, `soup-chop` uses that client's default writable scope.
+
+On Linux today, the exact auto-config targets exposed by `soup-chop help` depend on the current platform and writable config paths.
+On macOS and Windows, Claude Desktop is also documented and may become auto-configurable when its stable config path is available on that platform.
+
+For a non-mutating preview, use:
+
+```bash
+npx soup-chop configure cursor --project --dry-run
+npx soup-chop configure vscode-copilot --dry-run
+```
+
+ To print only the config snippet for copy-paste workflows, use:
+
+ ```bash
+ npx soup-chop configure cursor --print
+ npx soup-chop configure vscode-copilot --print
+ ```
+
+ To generate config for an unpublished local build instead of `npx soup-chop serve`, use:
+
+ ```bash
+ npx soup-chop configure cursor --project --local-build --dry-run
+ npx soup-chop configure cursor --local-build
+ ```
+
+ This emits `node /abs/path/to/dist/index.js serve` using the current working directory as the local build root.
+
+ If you're unsure what the current build supports on your machine, run:
+
+```bash
+npx soup-chop help
+npx soup-chop clients --json
+```
+
+ The help output includes the exact auto-config client IDs available on the current platform. `clients --json` emits the same client matrix as structured JSON for setup scripts and tooling.
+
+### Option 5 — Manual configuration matrix
+
+The ecosystem is moving quickly, so `soupChop` documents both implemented auto-config targets and UI/manual targets that are officially supported by their clients.
+
+| Client | Status | Scope | Verified config path / flow | Notes |
+| :----- | :----- | :---- | :-------------------------- | :---- |
+| Claude Desktop | Auto-config on macOS and Windows | Global | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`<br>Windows: `%APPDATA%\Claude\claude_desktop_config.json` | Official MCP docs expose this file via Claude > Settings > Developer > Edit Config; Linux remains documented-only in CLI output |
+| Claude Code | Documented | Project / user | `claude mcp add soup-chop npx -- soup-chop serve` | Official docs favor CLI / plugin flows rather than direct file editing |
+| Cursor | Auto-config | Global / project | Global: `~/.cursor/mcp.json`<br>Project: `.cursor/mcp.json` | Use `npx soup-chop configure cursor` for the global file or `npx soup-chop configure cursor --project` for the project file |
+| Windsurf | Auto-config | Global | `~/.codeium/windsurf/mcp_config.json` | Official docs also expose MCP management from the MCP Marketplace / Settings UI |
+| Antigravity | Documented | UI-managed | Agent pane → `MCP Servers` / `MCP Store` / `View raw config` | Official docs describe the flow but do not publish a stable file path |
+| Cline | Documented | UI-managed | MCP Servers icon → Configure MCP Servers → `cline_mcp_settings.json` | Official docs expose the config file through the UI |
+| VS Code Copilot | Auto-config | Project / user | Project: `.vscode/mcp.json`<br>User: VS Code user settings under `mcp.servers` | `soup-chop` writes the project file today; the user-settings path remains manual. Uses `servers` rather than `mcpServers` |
+| Gemini CLI | Documented | Project / user | Project: `.gemini/settings.json`<br>User: `~/.gemini/settings.json` | Same JSON shape as other `mcpServers` clients |
+| Gemini Code Assist | Documented | Project / user | Project: `.gemini/settings.json`<br>User: `~/.gemini/settings.json` | Shares Gemini CLI config format |
+| Firebase Studio | Auto-config | Project | `.idx/mcp.json` | `soup-chop` writes the project-local MCP config directly |
+
+### Option 6 — Manual snippets by client
+
+ The `configure` command accepts a few convenience aliases, for example `claude`, `copilot`, and `firebase`, and it supports explicit `--project` / `--global` scope selection when a client exposes more than one writable file target. Use `--dry-run` to preview the resolved file and merged JSON, `--print` to emit just the minimal snippet, or `--local-build` to point the config at the local built `dist/index.js` entrypoint.
+
+ When `configure` cannot write a client automatically, it now reports the documented target and points you back to `soup-chop clients` for the full matrix instead of failing with a generic message.
+
+#### Claude Desktop / Cursor / Windsurf / Gemini / Firebase Studio
+
+```json
+{
+  "mcpServers": {
+    "soup-chop": {
+      "command": "npx",
+      "args": ["soup-chop", "serve"]
+    }
+  }
+}
+```
+
+#### VS Code Copilot project config
+
+```json
+{
+  "servers": {
+    "soup-chop": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["soup-chop", "serve"]
+    }
+  }
+}
+```
+
+#### Claude Code manual registration
+
+```bash
+claude mcp add soup-chop npx -- soup-chop serve
+```
+
+#### Antigravity manual registration
+
+Open the Agent pane, then go to `MCP Servers` or `MCP Store`, add a custom stdio server, and point it to:
+
+```bash
+npx soup-chop serve
+```
+
+If Antigravity exposes raw JSON editing in your current build, use the same `mcpServers` JSON shown above.
+
+---
+
+## Available Tools
+
+The server is primarily tool-oriented, but it also exposes a small capability
+resource at `soup-chop://capabilities` so MCP clients that inspect resources
+have a useful entry point.
+
+### `get_toc`
+
+> **Discover what's in the documentation.**
+
+Returns a structured table of contents for a package's markdown docs.
+
+Without `origin`, it returns a package-wide multi-document TOC that includes
+synthetic file-root entries such as `README.md`, `CHANGELOG.md`, or
+`docs/faq.md`.
+
+With `origin`, it returns the TOC for a single markdown document.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                            |
+| :-------- | :------- | :------- | :------------------------------------- |
+| `package` | `string` | Yes      | NPM package name (e.g., `"express"`)   |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"4.18.2"`, `"latest"`) |
+| `origin`  | `string` | No       | Markdown source path from `search_docs` such as `"docs/faq.md"` or `"CHANGELOG.md"` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_toc",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8"
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "axios",
+  "version": "1.6.7",
+  "entries": [
+    {
+      "depth": 0,
+      "title": "README.md",
+      "path": "README.md",
+      "startLine": 1,
+      "endLine": 1648,
+      "origin": "README.md",
+      "topicId": "README.md"
+    },
+    {
+      "depth": 2,
+      "title": "Request Config",
+      "path": "Request Config",
+      "startLine": 386,
+      "endLine": 634,
+      "origin": "README.md",
+      "topicId": "README.md#Request Config"
+    },
+    {
+      "depth": 0,
+      "title": "CHANGELOG.md",
+      "path": "CHANGELOG.md",
+      "startLine": 1,
+      "endLine": 205,
+      "origin": "CHANGELOG.md",
+      "topicId": "CHANGELOG.md"
+    }
+  ]
+}
+```
+
+When you already know the document you want, pass `origin` to get just that
+document's headings.
+
+### `get_topic`
+
+> **Read a specific section.**
+
+Fetches the raw Markdown content for a specific section or whole markdown
+document.
+
+You can identify the target either with `topic_id`, or with `path` plus an
+optional `origin`.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                              |
+| :-------- | :------- | :------- | :------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                         |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag   |
+| `path`    | `string` | No       | Section path from `get_toc` (e.g., `"Zod/Installation"`) |
+| `origin`  | `string` | No       | Markdown source path from `search_docs` such as `"docs/faq.md"` or `"CHANGELOG.md"` |
+| `topic_id`| `string` | No       | Stable topic identifier from `search_docs` or aggregated `get_toc` |
+
+**Example call using `topic_id`:**
+
+```json
+{
+  "name": "get_topic",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "topic_id": "README.md#Coercion for primitives"
+  }
+}
+```
+
+### `search_docs`
+
+> **Search package docs when you do not know the exact section yet.**
+
+Searches `README.md`, package-local markdown under `doc/` and `docs/`, and a
+small allowlist of top-level markdown docs such as `API.md`, `FAQ.md`,
+`MIGRATING.md`, `UPGRADING.md`, `CHANGELOG.md`, and `CONTRIBUTING.md`.
+
+Results are ranked lexically and return the source origin, section path, line
+ranges, a stable `topicId`, and a short preview so the caller can follow up
+with `get_toc` or `get_topic`.
+
+**Current language support:** search is currently optimized for **English**
+tokenization and ranking.
+
+**TODO:** add better Chinese / broader CJK tokenization and ranking support.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                             |
+| :-------- | :------- | :------- | :---------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                        |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag                 |
+| `query`   | `string` | Yes      | Keyword query or natural-language question                              |
+| `limit`   | `number` | No       | Maximum number of ranked results to return, from `1` to `20`, default `5` |
+
+**Example call:**
+
+```json
+{
+  "name": "search_docs",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "query": "coercion schema parsing",
+    "limit": 3
+  }
+}
+```
+
+**Example follow-up flow:**
+
+1. Call `search_docs` to find likely sections.
+2. If needed, call `get_toc` with the returned `origin` to inspect that doc's structure.
+3. Call `get_topic` with the returned `topicId`, or with the returned `path` and `origin`, to fetch the exact section.
+
+### `get_traps`
+
+> **Surface warnings, caveats, and operational gotchas.**
+
+Returns compact, evidence-backed trap findings extracted deterministically from
+the same markdown corpus used by `search_docs`.
+
+Each finding includes:
+
+- `package`
+- `version`
+- `kind`
+- `severity`
+- `confidence`
+- `title`
+- `summary`
+- `evidence`
+
+Each evidence item includes the source document, section path, exact line
+range, snippet, and detector names so the caller can pivot back into
+`get_topic` without losing traceability.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                              |
+| :-------- | :------- | :------- | :----------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                         |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag                  |
+| `limit`   | `number` | No       | Maximum number of ranked trap findings to return, from `1` to `50`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_traps",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "limit": 2
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "zod",
+  "version": "3.23.8",
+  "kind": "traps",
+  "findings": [
+    {
+      "package": "zod",
+      "version": "3.23.8",
+      "kind": "traps",
+      "severity": "warning",
+      "confidence": "high",
+      "title": "Important caveat noted in documentation",
+      "summary": "> IMPORTANT: The value returned by .parse is a deep clone of the variable you passed in.",
+      "evidence": [
+        {
+          "sourceId": "readme__md",
+          "sourceKind": "readme",
+          "sourceTitle": "README.md",
+          "origin": "README.md",
+          "path": "Schema methods/.parse",
+          "startLine": 1930,
+          "endLine": 1930,
+          "snippet": "> IMPORTANT: The value returned by .parse is a deep clone of the variable you passed in.",
+          "detectors": ["trap.important"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `get_deprecations`
+
+> **Surface deprecated APIs, legacy guidance, and replacements.**
+
+Returns compact, evidence-backed deprecation findings extracted deterministically
+from the same markdown corpus used by `search_docs`.
+
+Deprecation findings are surfaced at `warning` severity because they usually
+indicate migration work, compatibility edge-cases, or removal risk rather than
+neutral reference material.
+
+Use it when you want focused migration and replacement guidance instead of the
+broader caveat-oriented `get_traps` view.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                    |
+| :-------- | :------- | :------- | :----------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                               |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag                        |
+| `limit`   | `number` | No       | Maximum number of ranked deprecation findings to return, from `1` to `50`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_deprecations",
+  "arguments": {
+    "package": "zod",
+    "version": "3.23.8",
+    "limit": 2
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "demo",
+  "version": "1.0.0",
+  "kind": "deprecations",
+  "findings": [
+    {
+      "package": "demo",
+      "version": "1.0.0",
+      "kind": "deprecations",
+      "severity": "warning",
+      "confidence": "high",
+      "title": "Deprecation or replacement guidance",
+      "summary": "This API is deprecated; use createClient instead.",
+      "evidence": [
+        {
+          "sourceId": "migration",
+          "sourceKind": "package_doc",
+          "sourceTitle": "migration.md",
+          "origin": "docs/migration.md",
+          "path": "Migration",
+          "startLine": 8,
+          "endLine": 8,
+          "snippet": "This API is deprecated; use createClient instead.",
+          "detectors": ["deprecation.deprecated", "deprecation.use_instead"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `get_constraints`
+
+> **Surface prerequisites, ordering requirements, and unsupported scenarios.**
+
+Returns compact, evidence-backed constraint findings extracted deterministically
+from the same markdown corpus used by `search_docs`.
+
+Use it when you want integration requirements and support boundaries rather than
+general caveats.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                  |
+| :-------- | :------- | :------- | :--------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                             |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag                      |
+| `limit`   | `number` | No       | Maximum number of ranked constraint findings to return, from `1` to `50`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_constraints",
+  "arguments": {
+    "package": "demo",
+    "version": "1.0.0",
+    "limit": 2
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "demo",
+  "version": "1.0.0",
+  "kind": "constraints",
+  "findings": [
+    {
+      "package": "demo",
+      "version": "1.0.0",
+      "kind": "constraints",
+      "severity": "warning",
+      "confidence": "high",
+      "title": "Operational constraint",
+      "summary": "This only works after setup and requires a token.",
+      "evidence": [
+        {
+          "sourceId": "guide",
+          "sourceKind": "package_doc",
+          "sourceTitle": "guide.md",
+          "origin": "docs/guide.md",
+          "path": "Setup",
+          "startLine": 4,
+          "endLine": 4,
+          "snippet": "This only works after setup and requires a token.",
+          "detectors": ["constraint.after_setup", "constraint.only_works", "constraint.requires"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `get_performance_notes`
+
+> **Surface complexity notes, expensive operations, and hot paths.**
+
+Returns compact, evidence-backed performance findings extracted deterministically
+from the same markdown corpus used by `search_docs`.
+
+Use it when you want cost and scaling signals rather than functional or
+operational caveats.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                    |
+| :-------- | :------- | :------- | :----------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                               |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag                        |
+| `limit`   | `number` | No       | Maximum number of ranked performance findings to return, from `1` to `50`, default `10` |
+
+**Example call:**
+
+```json
+{
+  "name": "get_performance_notes",
+  "arguments": {
+    "package": "demo",
+    "version": "1.0.0",
+    "limit": 2
+  }
+}
+```
+
+**Example response:**
+
+```json
+{
+  "package": "demo",
+  "version": "1.0.0",
+  "kind": "performance",
+  "findings": [
+    {
+      "package": "demo",
+      "version": "1.0.0",
+      "kind": "performance",
+      "severity": "warning",
+      "confidence": "high",
+      "title": "Performance-sensitive behavior",
+      "summary": "This operation is expensive on the hot path.",
+      "evidence": [
+        {
+          "sourceId": "perf",
+          "sourceKind": "package_doc",
+          "sourceTitle": "performance.md",
+          "origin": "docs/performance.md",
+          "path": "Performance",
+          "startLine": 12,
+          "endLine": 12,
+          "snippet": "This operation is expensive on the hot path.",
+          "detectors": ["performance.expensive", "performance.hot_path"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `soup-chop://capabilities`
+
+> **Quick MCP entry point for resource-oriented clients.**
+
+If your client starts by listing resources, `soup-chop://capabilities` explains
+the server surface and points you toward the recommended tool-first flow.
+
+Use it to discover:
+
+- the main tools
+- the recommended `search_docs` -> `get_toc` / `get_topic` flow
+- the current English-first search behavior
+
+### `get_api_ref`
+
+> **Index the published API surface.**
+
+Returns a compact index of exported identifiers from published `.d.ts` files.
+Each entry is grouped by identifier name and lists its associated runtime and
+compile-time kinds.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                            |
+| :-------- | :------- | :------- | :------------------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                                       |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.23.8"`, `"latest"`) |
+
+### `get_declaration`
+
+> **Read the exact declaration body.**
+
+Returns the explicit TypeScript declaration text for an exported identifier.
+Use `get_api_ref` to discover names first, then fetch the full declaration body
+only when needed.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                            |
+| :-------- | :------- | :------- | :------------------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                                       |
+| `version` | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.23.8"`, `"latest"`) |
+| `name`    | `string` | Yes      | Exported identifier name (e.g., `"ZodType"`)                                         |
+
+### `compare_versions`
+
+> **See what changed between versions.**
+
+Diffs the documentation structure between two versions of a package, showing
+added, removed, and moved sections.
+
+**Parameters:**
+
+| Name      | Type     | Required | Description                                                                            |
+| :-------- | :------- | :------- | :------------------------------------------------------------------------------------- |
+| `package` | `string` | Yes      | NPM package name                                                                       |
+| `v_old`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.22.0"`, `"latest"`) |
+| `v_new`   | `string` | Yes      | NPM version string: exact version or published dist-tag (e.g., `"3.23.8"`, `"latest"`) |
+
+---
+
+## How It Works
+
+```
+You ask about express@4.18.2
+        │
+        ▼
+┌─────────────────┐
+│   Your AI Agent  │   "What middleware options are available?"
+│   (Claude, etc.) │
+└────────┬─────────┘
+         │  calls get_toc("express", "4.18.2")
+         ▼
+┌─────────────────┐
+│   soupChop    │   MCP Server (runs locally on stdio)
+└────────┬─────────┘
+         │
+    ┌────┴─────────────────────────┐
+    │  Is it cached on disk?       │
+    │                              │
+    │  YES → read from             │
+    │  ~/.cache/soup-chop/       │
+    │  express/4.18.2/README.md    │
+    │                              │
+    │  NO → fetch from             │
+    │  unpkg.com/express@4.18.2/   │
+    │  README.md                   │
+    │  then cache it.              │
+    └────┬─────────────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Remark AST     │   Parses Markdown into a heading tree
+│   Parser         │   with line ranges for each section
+└────────┬─────────┘
+         │
+         ▼
+    Structured TOC returned to the AI
+    (only metadata — not the full README)
+```
+
+**Key design decisions:**
+
+- **Version-scoped caching** — Each `package@version` pair is cached independently.
+  Since published NPM versions are immutable, the cache never goes stale.
+- **No API keys required** — Everything runs locally. No LLM calls, no embeddings
+  API, no external services beyond UNPKG (a public CDN).
+- **Surgical delivery** — The AI gets a *table of contents*, not the full README.
+  It can then request only the section it needs, keeping context windows lean.
+
+---
+
+## Configuration
+
+### Cache Location
+
+soupChop uses [`env-paths`](https://github.com/sindresorhus/env-paths) to store
+cached documentation in the standard OS-specific cache directory:
+
+| OS      | Path                                      |
+| :------ | :---------------------------------------- |
+| Linux   | `~/.cache/soup-chop/`                    |
+| macOS   | `~/Library/Caches/soup-chop/`            |
+| Windows | `%LOCALAPPDATA%\soup-chop\Cache\`        |
+
+Cache is organized as:
+
+```
+~/.cache/soup-chop/
+├── express/
+│   └── 4.18.2/
+│       └── README.md
+├── zod/
+│   └── 3.23.8/
+│       └── README.md
+└── ...
+```
+
+To clear the cache, simply delete the directory.
+
+---
+
+## For Library Authors
+
+`soupChop` is designed to work with ordinary package docs. You do not need a special integration, custom metadata, or an MCP-specific format.
+
+That said, some documentation patterns make retrieval much more reliable for both humans and AI agents:
+
+### Best Practices for Library Authors
+
+#### Use Clear, Specific Headings
+
+Prefer headings like `Authentication`, `Error Handling`, `Transactions`, or `React Integration` over vague titles like `Advanced` or `More`. Section-based retrieval works best when the heading already says what problem the section solves.
+
+#### Keep Sections Focused
+
+One section should usually answer one question well. Very large umbrella sections are harder to retrieve precisely than several smaller, well-named sections.
+
+#### Document Important Concepts in Prose, Not Only in Examples
+
+Short narrative explanations help retrieval and ranking much more than code alone. Keep examples, but explain what they demonstrate and when to use them.
+
+#### Use Stable Terminology Consistently
+
+If the product uses terms like `schema`, `resolver`, `adapter`, or `provider`, prefer one canonical term and reuse it throughout the docs. Synonym drift makes both human search and automated retrieval weaker.
+
+#### Publish Package-Local Markdown When It Matters
+
+`README.md` is a strong default, but additional docs such as `docs/*.md`, `API.md`, `FAQ.md`, or `MIGRATING.md` make specialized topics easier to isolate. Migration guides, upgrade notes, and troubleshooting docs are especially valuable.
+
+#### Separate Version-Sensitive Material Clearly
+
+If behavior changed in `v2`, say so explicitly in the relevant section. Dedicated upgrade or breaking-change sections are easier to retrieve than scattered notes.
+
+#### Include Exact Names and Signatures Where Possible
+
+Mention real option names, config keys, CLI flags, and exported identifiers. Precise tokens help users, search, and AI agents converge on the right section faster.
+
+#### Prefer Descriptive Links and Filenames
+
+`docs/authentication.md` and `docs/error-handling.md` are more useful than opaque file names. Good filenames also make multi-document corpora easier to navigate.
+
+A good rule of thumb is simple: write docs so that a person can jump straight to the answer from the table of contents alone. If that works well for a human, it usually works well for `soupChop` too.
+
+---
+
+## Examples
+
+### Example 1 — Exploring a new library
+
+> **You:** "I want to use `zod` for form validation. What does it offer?"
+>
+> **AI** *(calls `get_toc("zod", "3.23.8")`)*: "Here's what Zod's documentation
+> covers: Introduction, Installation, Basic Usage, Primitives, Coercion, Literals,
+> Strings, Numbers, ..."
+>
+> **You:** "Tell me about coercion."
+>
+> **AI** *(calls `get_topic("zod", "3.23.8", "Zod/Coercion")`)*: "Zod provides
+> coercion methods that automatically transform input data..."
+
+### Example 2 — Debugging a version mismatch
+
+> **You:** "This code worked in express 4 but breaks in express 5."
+>
+> **AI** *(calls `compare_versions("express", "4.18.2", "5.0.0")`)*: "Several
+> sections have changed between these versions. The 'Middleware' section was
+> reorganized and 'Error Handling' has new subsections..."
+
+### Example 3 — Getting accurate type information
+
+> **You:** "What's the actual type signature for `z.object`?"
+>
+> **AI** *(calls `get_api_ref("zod", "3.23.8")`)*: "I found `object` in the
+> published API index. It is exported as a function."
+>
+> **AI** *(calls `get_declaration("zod", "3.23.8", "object")`)*: "Here is the
+> explicit declaration from the published type definitions..."
+
+---
+
+## Requirements
+
+- **Node.js** 20 or later
+- An MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, etc.)
+
+---
+
+## FAQ
+
+### Why not just paste the README into the chat?
+
+Three reasons:
+
+1. **Context window waste.** A typical README is 5,000–50,000 tokens. soupChop
+   delivers only the section the AI needs — often under 500 tokens.
+2. **Version accuracy.** You'd have to find and paste the README for the exact
+   version you're using. soupChop does this automatically.
+3. **Automation.** The AI can explore documentation *on its own*, without you
+   acting as a copy-paste intermediary.
+
+### Why UNPKG instead of the npm registry API?
+
+UNPKG serves individual files from published packages via a simple URL scheme
+(`unpkg.com/pkg@version/file`). The npm registry API returns package metadata
+but not file contents directly. UNPKG gives us exactly what we need with a
+single HTTP request.
+
+### Does this work with private packages?
+
+Not yet. The current version only supports packages published to the public npm
+registry via UNPKG. Private registry support is on the roadmap.
+
+### What if the package has no README?
+
+soupChop returns a clear error message indicating that no README was found for
+the requested package and version. The AI can then inform you and suggest
+alternative documentation sources.
+
+### Is my data sent anywhere?
+
+**No.** soupChop runs entirely on your machine. The only external request is to
+`unpkg.com` to fetch package files — the same CDN used by millions of
+developers daily. No telemetry, no analytics, no API keys.
+
+---
+
+## License
+
+[MIT](LICENSE)