docs: add kb_add tool to README and site documentation

README.md

@@ -51,12 +51,14 @@ wikiloop-kb/
 
 ## How Agents Use WikiLoop
 
-Agents interact with WikiLoop through two MCP tools:
+Agents interact with WikiLoop through three MCP tools:
 
 **`kb_search(query, limit?)`** — Search with a keyword or phrase. Returns up to 5 source-notes and 3 concept/comparison/decision pages per call. Each result includes a `related` field listing linked documents for navigation. Use multiple searches with different keywords to cover a topic from multiple angles.
 
 **`kb_page(ids, full?)`** — Fetch full content of one or more pages by ID (from `kb_search` results). Pass up to 5 IDs to scan several documents at once, or `full=true` with a single ID to get the complete untruncated text.
 
+**`kb_add(filename, content, source_url?)`** — Add a text document to the knowledge base. Writes content to `raw/<filename>` and triggers incremental indexing. Distillation runs asynchronously in the background. Use the `converted/` prefix for agent-extracted PDF/Word/Excel/EPUB content.
+
 The recommended agent workflow:
 
 ```text
@@ -232,7 +234,7 @@ All commands accept a global `--kb <path>` flag (defaults to `$WIKILOOP_KB`, the
 
 WikiLoop exposes KB tools via the MCP protocol.
 
-**Available tools:** `kb_search`, `kb_page`
+**Available tools:** `kb_search`, `kb_page`, `kb_add`
 
 Admin operations (`status`, `reindex`, `lint`) are available via the Web UI or CLI (`wikiloop status`, `wikiloop index`, `wikiloop lint`).
 

docs/site/guide/mcp-server.md

@@ -58,5 +58,6 @@ The KB directory is created automatically on first launch. No manual `init` need
 |---|---|
 | `kb_search` | FTS keyword search, returns ranked results with related links |
 | `kb_page` | Fetch full page content by ID |
+| `kb_add` | Add a text document to the KB; triggers incremental indexing and async distillation |
 
 Admin operations (`status`, `reindex`, `lint`) are available via the Web UI or CLI.

docs/site/reference/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP Tools Reference
 
-WikiLoop exposes two MCP tools for agents.
+WikiLoop exposes three MCP tools for agents.
 
 ## kb_search
 
@@ -30,6 +30,31 @@ Search the knowledge base with a keyword or phrase.
 }
 ```
 
+## kb_add
+
+Add a text document to the knowledge base.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filename` | string | yes | Path relative to `raw/`. Use any subdirectory structure (e.g. `references/article.md`, `converted/report.md`). Use `converted/` prefix for agent-extracted PDF/Word/Excel/EPUB content. |
+| `content` | string | yes | File content (Markdown or plain text) |
+| `source_url` | string | no | Original source URL, written as a comment at the top of the file |
+| `overwrite` | boolean | no | Overwrite if file already exists (default false) |
+
+Writes content to `raw/<filename>` and triggers incremental indexing. Distillation runs asynchronously in the background.
+
+**Example:**
+
+```json
+{
+  "filename": "references/my-article.md",
+  "content": "# My Article\n\nContent here...",
+  "source_url": "https://example.com/article"
+}
+```
+
 ## kb_page
 
 Fetch full content of one or more pages by ID.

docs/site/zh-CN/guide/mcp-server.md

@@ -58,5 +58,6 @@ wikiloop serve
 |---|---|
 | `kb_search` | FTS 关键词搜索，返回带 related 链接的排序结果 |
 | `kb_page` | 通过 ID 获取完整页面内容 |
+| `kb_add` | 向知识库添加文本文档，触发增量索引和异步提炼 |
 
 管理操作（`status`、`reindex`、`lint`）可通过 Web UI 或 CLI 执行。

docs/site/zh-CN/reference/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP 工具参考
 
-WikiLoop 为 Agent 暴露两个 MCP 工具。
+WikiLoop 为 Agent 暴露三个 MCP 工具。
 
 ## kb_search
 
@@ -21,6 +21,21 @@ WikiLoop 为 Agent 暴露两个 MCP 工具。
 - `kind`、`layer` — 页面分类
 - `related` — 关联文档，用于图谱导航
 
+## kb_add
+
+向知识库添加文本文档。
+
+**参数：**
+
+| 参数 | 类型 | 必填 | 描述 |
+|---|---|---|---|
+| `filename` | string | 是 | 相对于 `raw/` 的路径，支持任意子目录结构（如 `references/article.md`、`converted/report.md`）。Agent 提取的 PDF/Word/Excel/EPUB 内容使用 `converted/` 前缀。 |
+| `content` | string | 是 | 文件内容（Markdown 或纯文本） |
+| `source_url` | string | 否 | 原始来源 URL，写入文件顶部注释 |
+| `overwrite` | boolean | 否 | 文件已存在时是否覆盖（默认 false） |
+
+将内容写入 `raw/<filename>` 并触发增量索引。提炼在后台异步运行。
+
 ## kb_page
 
 通过 ID 获取一个或多个页面的完整内容。