rekipedia 0.17.29 → 0.20.0

package/LICENSE

@@ -1,13 +1,21 @@
-Copyright (c) 2026 Eddie Chan (unrealandychan). All Rights Reserved.
+MIT License
 
-PROPRIETARY AND CONFIDENTIAL
+Copyright (c) 2026 Eddie Chan (unrealandychan)
 
-This software and its source code are the exclusive property of Eddie Chan
-("Owner"). Unauthorized copying, distribution, modification, public display,
-or public performance of this software, via any medium, is strictly prohibited.
+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:
 
-No part of this software may be reproduced, distributed, or transmitted in any
-form or by any means, including photocopying, recording, or other electronic or
-mechanical methods, without the prior written permission of the Owner.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-For licensing inquiries, please contact the Owner directly.
+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

@@ -2,18 +2,19 @@
 
 **Turn any repo into an AI-ready knowledge base — wiki, RAG, and MCP server included.**
 
-[![PyPI version](https://img.shields.io/pypi/v/rekipedia)](https://pypi.org/project/rekipedia/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![PyPI version](https://img.shields.io/pypi/v/rekipedia.svg)](https://pypi.org/project/rekipedia/) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/) [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
 
 ---
 
 ## Why rekipedia?
 
-- **AI agents hallucinate on unfamiliar code.** rekipedia gives them grounded, citable context from the actual source.
-- **Onboarding is slow.** A generated wiki means new teammates (human or AI) ramp up in minutes, not days.
-- **RAG pipelines need structured input.** rekipedia produces a clean SQLite store, FAISS index, and wiki — ready to plug in.
-- **CI shouldn't break the knowledge base.** Works offline, commits alongside your code, zero cloud dependency.
+| Problem | rekipedia |
+|---|---|
+| "Where does the auth logic live?" | `reki ask "how does auth work?"` → `src/auth.py:42` |
+| Onboarding new devs takes days | `reki onboard .` generates a guided walkthrough in seconds |
+| AI agents hallucinate about your codebase | `reki mcp` gives agents a grounded knowledge base with citations |
+| Refactor anxiety | `reki hotspots` surfaces hub nodes and bridge nodes before you touch anything |
+| Wiki goes stale immediately | `reki watch .` auto-reindexes on every file save |
 
 ---
 
@@ -24,21 +25,6 @@ pip install rekipedia
 # or: npx rekipedia
 ```
 
-### Zero config — no API key needed
-
-```bash
-reki scan . --no-llm
-```
-
-```
-✔ Scanned 312 files  · 4,891 symbols indexed
-✔ Wiki generated     · .rekipedia/wiki/
-✔ Knowledge store    · .rekipedia/store.db
-Done in 4.2s
-```
-
-That's it. Your codebase is now a portable knowledge base.
-
 ### With LLM (richer wiki + Q&A)
 
 ```bash
@@ -133,6 +119,34 @@ Claude Code and Cursor will automatically discover this config. The agent can th
 - `get_relationships` — dependency graph queries
 - `get_hub_nodes` — architectural hotspots
 - `get_impact` — change impact analysis
+- `list_wiki_pages` — enumerate all wiki pages
+- `get_wiki_page` — read a specific wiki page by name
+---
+## AI CLI tool integration
+
+rekipedia integrates natively with the major AI coding assistants via MCP (Model Context Protocol). After scanning your codebase, run:
+
+```bash
+reki init --with-all-ai    # configure Copilot + Codex + Cursor in one step
+# or pick individually:
+reki init --with-copilot   # GitHub Copilot (VS Code) — writes .vscode/mcp.json
+reki init --with-codex     # Codex CLI — writes .codex/instructions.md + setup hint
+reki init --with-cursor    # Cursor — writes .cursor/mcp.json + rules
+```
+
+Once configured, each tool automatically gets access to these rekipedia MCP tools:
+
+| MCP Tool | What it does |
+|---|---|
+| `ask` | Natural-language Q&A grounded in the scanned wiki |
+| `search_nodes` | Fast symbol lookup by name |
+| `get_context` | Symbols and relationships for a file |
+| `get_relationships` | Callers and callees for a symbol |
+| `get_hub_nodes` | Architectural chokepoints |
+| `get_impact` | Blast-radius for a changed file |
+| `get_knowledge_gaps` | Untested high-call-count symbols |
+| `list_wiki_pages` | List all wiki pages |
+| `get_wiki_page` | Read a specific wiki page by name |
 
 ---
 
@@ -165,7 +179,12 @@ export REKIPEDIA_MODEL=ollama/llama3
 | `reki update . --impact-only` | Incremental update, affected pages only |
 | `reki serve .` | Local web UI at `http://127.0.0.1:7070` |
 | `reki embed .` | Build FAISS semantic index |
-| `reki export . --format md\|zip\|json\|html` | Export the wiki |
+| `reki publish . [--output-dir PATH]` | Publish wiki to a git-tracked directory for team sharing |
+| `reki export . --format bundle` | Export a content-addressed wiki bundle for team sync |
+| `reki merge <bundle-A> <bundle-B> [--base BASE]` | Three-way wiki merge — conflict-free team sync |
+| `reki pull [URL]` | Fetch and merge a remote wiki bundle (HTTPS/S3/GCS) |
+| `reki watch . --publish` | Auto-index + auto-publish wiki on every file save |
+| `reki export . --format md\|zip\|json\|html\|bundle` | Export the wiki |
 | `reki diff` | Show impact of uncommitted changes |
 | `reki hotspots` | Hub & bridge node detection |
 | `reki refactor . --dry-run` | Preview refactor suggestions |
@@ -174,14 +193,87 @@ export REKIPEDIA_MODEL=ollama/llama3
 | `reki review` | LLM-powered PR review |
 | `reki watch .` | Auto-index on file change |
 | `reki hook install` | Install git post-commit hook |
+| `reki init --with-all-ai` | Configure MCP for GitHub Copilot, Codex CLI, and Cursor in one step |
+
+---
+
+## FAQ
+
+### Q: Why is `store.db` gitignored? How do teammates use rekipedia?
+
+`store.db` is a binary SQLite file containing machine-specific absolute paths — committing it would cause path mismatches on other machines and create noisy binary diffs. Each developer runs `reki scan .` locally to build their own store. To share the human-readable output with your team, use `reki publish .`, which copies the generated wiki pages to `docs/wiki/` so they can be committed and browsed in your repo or docs site.
+
+---
+
+### Q: What is `store.db` for vs the FAISS index? Why do I need both?
+
+They serve distinct purposes and are not interchangeable. `store.db` is a structured SQLite graph: it stores symbols, relationships, file manifests, and scan run history — the kind of data you query with precise filters ("find all callers of function X"). The FAISS index (built by `reki embed .`) stores dense embedding vectors for every chunk of your codebase, enabling fuzzy semantic search ("find code that handles authentication"). `reki ask` uses both together: BM25 keyword search over SQLite and vector similarity search over FAISS, then merges the results.
+
+---
+
+### Q: Can I use Postgres, MySQL, or another database instead of SQLite?
+
+Not currently. SQLite is the only supported backend for the structured symbol/relationship store, and it is intentional — SQLite is zero-config, portable, and requires no running server, which keeps `reki scan` self-contained. The `reki export .` command produces JSON exports (`symbols.json`, `relationships.json`) you can load into any database. Postgres/MySQL support is not on the roadmap, but the JSON exports make integration with your own tooling straightforward.
+
+---
+
+### Q: Does rekipedia support Qdrant or Chroma instead of FAISS?
+
+Yes. FAISS is the default vector backend, but Qdrant and Chroma are both supported as optional backends. Qdrant and Chroma are useful when you want a persistent, server-hosted vector store shared across machines — unlike the local FAISS index, a running Qdrant or Chroma instance can be queried by your whole team without each person running `reki embed`. Install the relevant extras (`pip install rekipedia[qdrant]` or `rekipedia[chroma]`) and configure the backend in `.rekipedia/config.yml`.
+
+---
+
+### Q: Do I need an OpenAI API key?
+
+No. rekipedia can run entirely without an LLM using the `--no-llm` flag — `reki scan . --no-llm` performs static analysis only, producing the symbol graph and wiki structure without AI-generated summaries. When you do want richer summaries and Q&A, rekipedia supports OpenAI, Anthropic, Ollama (local), Azure OpenAI, and any OpenAI-compatible endpoint. For fully offline usage, point it at a local [Ollama](https://ollama.com) instance — no internet required.
+
+---
+
+### Q: How do I share the wiki with my team without everyone running `reki scan`?
+
+Use `reki publish .`. This command copies the generated `wiki/*.md` and `diagrams/*.md` files into `docs/wiki/` (not gitignored), which can be committed and browsed directly in GitHub, your docs site, or any Markdown viewer — no local scan required. The best setup is to automate publishing in CI so the wiki stays current whenever the main branch changes (see the GitHub Actions question below).
+
+---
+
+### Q: How do I keep the wiki up to date automatically?
+
+Run `reki init --with-ci` to scaffold a GitHub Actions workflow (`.github/workflows/rekipedia-wiki.yml`) that runs `reki scan`, then `reki publish` on every push to `main`. The workflow commits any changes to `docs/wiki/` back to the repo automatically. Set `REKIPEDIA_API_KEY` as a repository secret for LLM-enriched pages; omit it and the workflow falls back to `--no-llm` mode at zero cost.
+
+---
+
+### Q: How does team sync work for distributed teams?
+
+rekipedia's team sync is a multi-layer system for conflict-free wiki collaboration:
+
+1. **Bundle** — `reki export --format bundle` creates a deterministic, content-addressed snapshot with a stable `bundle_id` and per-page hash trailers.
+2. **Merge** — `reki merge bundle-A bundle-B --base bundle-base` performs a three-way merge: pages changed by only one developer are accepted automatically; only genuinely divergent pages produce conflict markers.
+3. **Git merge driver** — `reki init --with-merge-driver` registers a git merge driver so `git merge` and `git pull` automatically use rekipedia's merge logic — no `<<<<<<` conflicts in generated wiki files.
+4. **Live sync** — `reki watch . --publish` publishes the wiki after every incremental update, keeping `docs/wiki/` in sync as you code. Set `team.sync_dir` in `.rekipedia/config.yml` for the default target.
+5. **Remote pull** — `reki pull <url>` fetches a bundle from HTTPS, S3, or GCS and merges it locally. Combine with `reki init --with-ci --with-upload s3` to have CI upload a fresh bundle after every main-branch push.
+
+---
+
+### Q: How does `reki ask` actually work under the hood?
+
+`reki ask "question"` runs a hybrid retrieval pipeline. First, it executes a BM25 keyword search against the SQLite store to find exact and near-exact symbol/token matches. In parallel, it encodes your question into an embedding vector and queries the FAISS (or Qdrant/Chroma) index for semantically similar chunks. The two result sets are merged and re-ranked by relevance score, then the top chunks are passed as context to your configured LLM, which synthesises a final answer with file:line citations. With `--no-llm`, retrieval results are returned directly without synthesis.
+
+---
+
+### Q: How large does `store.db` / the FAISS index get on a large repo?
+
+For a typical mid-size repo (50k–200k lines of code), `store.db` is usually 10–80 MB. The FAISS index in `.rekipedia/rag/` scales with the number of embedded chunks — expect 50–500 MB for the same size range, which is why `rag/` is gitignored by default. On very large monorepos (1M+ LOC), the FAISS index can exceed 1 GB; in that case, switching to a server-backed Qdrant instance is recommended so the index lives outside your working directory.
+
+---
+
+### Q: Can rekipedia scan private or fully offline repos?
+
+Yes, fully. `reki scan` is pure static analysis — it never sends your source code anywhere. With `--no-llm`, the entire pipeline is offline and air-gap safe. When LLM features are enabled, only retrieved *chunks* (not your full source) are sent to the LLM provider as context; if you use Ollama, even that stays local. There are no telemetry calls, no license checks against a remote server, and no requirement for internet access beyond reaching your chosen LLM API endpoint.
 
 ---
 
 ## Coming Soon
 
 - **Hosted wiki** — share your knowledge base with a link, no self-hosting required
-- **Team sync** — collaborative wiki with conflict-free merge for distributed teams
-- **GitHub Action** — auto-update wiki on every push
 - **VS Code extension** — inline `reki ask` from your editor
 
 ---

package/README.zh-CN.md

@@ -2,158 +2,436 @@
 
 **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
 
-> 你的 AI 技术负责人 —— 随时在线，始终最新。
+> 您的 AI 技术负责人——随时在线，始终最新。
+
+rekipedia 可扫描任意代码仓库，将其转化为便携的 SQLite 知识库，让团队中的每位开发者都拥有一个由 LLM 驱动的技术负责人，可以随时询问：_"认证流程是如何运作的？"、"添加一个新 API 端点最快的方式是什么？"、"上周是什么导致了支付服务故障？"_
+
+零幻觉，零猜测——每个答案都基于您的真实代码库。
+
+### 核心功能
+- **关系置信度评分**：每个提取的关系均标记为 EXTRACTED/INFERRED/AMBIGUOUS，并附带置信度分数
+- **设计意图提取**：`# NOTE:`、`# HACK:`、`# WHY:` 注释被提取为知识节点
+- **God 节点**：度数最高的符号会在 index.md 中呈现，并在图形界面中高亮显示
+- **交互式依赖关系图**：`rekipedia serve` 现已包含 `/graph` 路由，提供基于 D3.js 的力导向可视化
+- **Git 钩子**：`rekipedia hook install` 可在每次提交时触发自动重建
+- **智能 wiki 编排**：`PlannerAgent` 根据您的仓库动态设计 wiki 结构
+- **页面重要性评分**：规划器为每个页面分配重要性分数（0–100），导航侧边栏按优先级排序
+- **DeepWiki 风格分节**：页面按逻辑分节分组（`getting-started`、`architecture`、`core-components` 等）
+- **Wiki 侧边栏分类**：`reki serve` 侧边栏按 `section` 字段分组，支持折叠标题
+- **实时搜索**：在侧边栏搜索框中输入内容，可即时按标题或分类筛选 wiki 页面
+- **重构分析**：`reki refactor` 检测代码异味（上帝类、循环依赖、死代码、高耦合），并提供 LLM 增强建议——输出 `REFACTOR.md` + `refactor_report.json`
+- **上下文切片**：每个页面仅接收其所需的数据（相比固定布局方式减少约 40–60% 的 token 用量）
+- **混合 RAG 问答**：FAISS 索引的代码块 + wiki 页面为 LLM 提供完整的代码库上下文以回答问题
+- **嵌入模型提供商选择**：`--embed-provider openai|ollama|azure|...`——支持任何兼容 litellm 的嵌入模型
+- **Wiki 导出**：打包为单个 Markdown 文件、ZIP 压缩包或结构化 JSON（`rekipedia export`）
+- **增量更新**：首次扫描后仅重新处理已变更的文件
+- **有据可查的问答**：答案引用真实的文件路径和行号——零幻觉
+- **代码库树形索引**——每次扫描在 SQLite 中构建层级目录/文件树，支持结构化导航和未来基于推理的检索。
 
-rekipedia 可扫描任意代码库，生成便携式 SQLite 知识库，为每位开发者提供一个由 LLM 驱动的技术负责人，随问随答。
+## 快速开始
 
-零幻觉 —— 每个回答都基于你的真实代码库。
+### 通过 npm / npx（无需安装）
 
----
+```bash
+npx rekipedia init .
+npx rekipedia scan .
+```
 
-## 快速开始
+### 通过 uv / uvx（无需安装）
 
 ```bash
-# 无需安装
-npx rekipedia init . && npx rekipedia scan .
-# 或
-uvx rekipedia init . && uvx rekipedia scan .
+uvx rekipedia init .
+uvx rekipedia scan .
 ```
 
+### 永久安装
+
 ```bash
-# 永久安装
-pip install rekipedia          # 核心
-pip install "rekipedia[rag]"   # + 语义搜索 (FAISS)
+# Core (scan + serve + ask)
+pip install rekipedia
+# or
+uv tool install rekipedia
+
+# With RAG support (semantic embed + search — needs faiss-cpu + numpy ~100MB)
+pip install "rekipedia[rag]"
+
+# Homebrew (Go single binary — no Python needed)
+brew tap unrealandychan/tap
+brew install rekipedia
 ```
 
 ---
 
-## 快速开始 —— 无需 API Key
+## 快速开始——无需 API 密钥
 
-无需任何 LLM API Key，即可运行完整静态分析：
+无需任何 LLM API 密钥即可执行完整静态分析：
 
 ```bash
 pip install rekipedia
-reki scan . --no-llm   # ~5-10s，零 API 调用
-reki onboard .         # 架构概览
-reki tour .            # 按依赖深度引导游览
-reki domain .          # 业务域分层图
-reki diff .            # 已变更文件的影响分析
-reki export . --format md  # 将完整 wiki 导出为 Markdown
+reki scan . --no-llm   # ~5-10 秒，零 API 调用
+reki onboard .         # 架构总览
+reki tour .            # 依赖深度导览
+reki domain .          # 业务领域层次图
+reki diff .            # 变更影响分析
+reki export . --format md  # 导出完整 wiki 为 Markdown
 ```
 
-> **注意：** `reki ask`（AI 问答）需要 LLM API Key。请参阅下方 [LLM 配置](#llm-配置)。
+> **注意：** `reki ask`（AI 问答）需要 LLM API 密钥。请参阅下方 [LLM 配置](#llm-配置)。
 
 ---
 
-## 核心命令
+## Python API
 
-| 命令 | 功能说明 |
-|---|---|
-| `reki init .` | 初始化配置 |
-| `reki scan .` | 完整分析 → wiki + 知识库 |
-| `reki update .` | 增量刷新（仅处理变更文件） |
-| `reki update . --impact-only` | 影响感知模式 —— 仅重新生成受影响模块的 wiki 页面 |
-| `reki serve .` | 本地 Web UI —— 浏览、搜索、问 AI |
-| `reki ask` | 交互式问答 REPL（流式输出） |
-| `reki embed .` | 构建 FAISS 语义索引（混合 RAG） |
-| `reki export .` | 打包 wiki → `--format md|zip|json|html` |
-| `reki diff` | 未提交变更的影响分析 |
-| `reki domain .` | 将代码库映射到业务层（API/Service/Data/UI） |
-| `reki tour .` | 按依赖深度引导学习游览 |
-| `reki onboard .` | 面向新开发者的静态入职指南 |
-| `reki review` | 基于 wiki 上下文的 LLM PR 审查 |
-| `reki refactor .` | 检测代码异味 → `REFACTOR.md` |
-| `reki refactor . --dry-run` | 预览重构建议，不写入文件 |
-| `reki refactor . --apply` | 自动应用安全修复（死代码标记、拆分建议） |
-| `reki refactor . --apply --dry-run` | 预览 `--apply` 将执行的操作 |
-| `reki watch .` | 文件变更时自动重建索引（OS 监听器） |
-| `reki hook install` | Git post-commit 自动重建 |
-| `reki mcp` | 面向 AI 编程助手的 MCP stdio 服务器 |
+在 Jupyter Notebook、CI 流水线或任意 Python 应用中以编程方式使用 rekipedia：
 
----
+```python
+import rekipedia
 
-### `reki ask` —— 简洁模式
+# Scan a local repo
+result = rekipedia.scan("/path/to/repo")
+print(result.page_count)   # number of wiki pages generated
+print(result.symbol_count) # number of code symbols extracted
+print(result.token_count)  # estimated token count of the wiki
 
-```bash
-# 简洁模式 —— ~150 tokens，仅输出摘要 + 引用
-reki ask "what does Scanner.scan() do?" --brief
+# Ask a question — grounded answer with file:line citations
+answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
+print(answer.text)
+for citation in answer.citations:
+    print(f"  {citation.file}:{citation.line}")
 
-# 或通过环境变量（便于管道传输）
-REKIPEDIA_BRIEF=1 reki ask "entry point?" | grep 'src/'
+# Async variants (Jupyter-friendly)
+result = await rekipedia.scan_async("/path/to/repo")
+answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
 ```
 
+**返回类型：**
+
+| Type | Key fields |
+|---|---|
+| `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
+| `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
+| `Citation` | `file`, `line`, `snippet` |
+
+---
+
+## 命令
+
+| Command | Description |
+|---|---|
+| `rekipedia init [REPO]` | Scaffold `.rekipedia/` with `config.yml` and update `.gitignore` |
+| `rekipedia scan [REPO]` | Full analysis — extracts symbols, synthesises wiki pages, exports JSON |
+| `rekipedia update [REPO]` | Incremental refresh — re-extracts only changed files, keeps the rest |
+| `rekipedia ask [QUESTION]` | Interactive Q&A REPL — streaming answers, Ctrl+C to quit |
+| `rekipedia serve [REPO]` | Start a local web UI to browse wiki pages and ask questions |
+| `rekipedia embed [REPO]` | Build (or rebuild) the FAISS semantic search index for hybrid RAG Q&A |
+| `rekipedia export [REPO]` | Bundle the wiki to a single file (`--format md\|zip\|json`) |
+| `rekipedia hook install/uninstall/status` | Manage git post-commit hook for auto wiki rebuild |
+| `rekipedia diff [A] [B]` | Compare two graph snapshots (defaults to last two) |
+| `rekipedia impact <file>` | Show blast-radius — all affected files, symbols, tests for a changed file |
+| `rekipedia search <query>` | Search symbols (`--all-repos` for cross-repo parallel search) |
+| `rekipedia export --format graphml\|cypher\|obsidian` | Export graph to GraphML / Neo4j Cypher / Obsidian wikilinks |
+| `rekipedia mcp` | Start JSON-RPC 2.0 MCP stdio server (6 tools for AI coding assistants) |
+| `rekipedia watch add\|start\|list\|remove` | Watch repos and auto-index on file change |
+| `rekipedia refactor [REPO]` | Detect code smells + generate `REFACTOR.md` and `refactor_report.json` (use `--no-llm` for static only) |
+| `rekipedia note add\|list\|remove\|edit\|import` | Manage persistent tech lead notes — injected into `reki ask` context automatically |
+
 ---
 
 ## LLM 配置
 
-rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支持任意 LLM 提供商：
+rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支持任何提供商：
 
 | 提供商 | 示例 |
 |---|---|
-| OpenAI | `OPENAI_API_KEY=*** reki scan .` |
-| Anthropic Claude | `REKIPEDIA_MODEL=claude-3-5-sonnet-20241022 REKIPEDIA_API_KEY=*** reki scan .` |
-| Google Gemini | `REKIPEDIA_MODEL=gemini/gemini-2.0-flash REKIPEDIA_API_KEY=*** reki scan .` |
-| OpenRouter | `REKIPEDIA_MODEL=openrouter/anthropic/claude-3.5-sonnet REKIPEDIA_API_KEY=*** reki scan .` |
+| OpenAI | `OPENAI_API_KEY=sk-... reki scan .` |
+| Anthropic Claude | `REKIPEDIA_MODEL=claude-3-5-sonnet-20241022 REKIPEDIA_API_KEY=sk-ant-... reki scan .` |
+| Google Gemini | `REKIPEDIA_MODEL=gemini/gemini-2.0-flash REKIPEDIA_API_KEY=AIza... reki scan .` |
+| OpenRouter | `REKIPEDIA_MODEL=openrouter/anthropic/claude-3.5-sonnet REKIPEDIA_API_KEY=sk-or-... reki scan .` |
 | 本地 Ollama（默认） | `REKIPEDIA_MODEL=ollama/llama4 reki scan .` |
-| Azure OpenAI | `REKIPEDIA_MODEL=azure/gpt-4o REKIPEDIA_BASE_URL=https://your-resource.openai.azure.com REKIPEDIA_API_KEY=*** reki scan .` |
+| Azure OpenAI | `REKIPEDIA_MODEL=azure/gpt-4o REKIPEDIA_BASE_URL=https://your-resource.openai.azure.com REKIPEDIA_API_KEY=... reki scan .` |
 
-执行 `reki init` 后，编辑 `.rekipedia/config.yml`：
+环境变量：
+- `REKIPEDIA_MODEL` — litellm 模型字符串（默认：`ollama/llama4`）
+- `REKIPEDIA_API_KEY` — 所选提供商的 API 密钥
+- `REKIPEDIA_BASE_URL` — 自定义基础 URL（用于 Azure、Ollama、代理）
+- `REKIPEDIA_TIMEOUT` — LLM 调用超时秒数（默认：180）
+
+运行 `rekipedia init` 后，编辑 `.rekipedia/config.yml`：
 
 ```yaml
+version: 1
+ignore:
+  - .git
+  - node_modules
+  - __pycache__
+  - .rekipedia
+languages:
+  - python
+  - typescript
 llm:
-  model: ollama/llama4
-  api_key: ""
-  base_url: ""
+  model: ollama/llama4        # any litellm model string
+  api_key: ""                 # or set REKIPEDIA_API_KEY env var
+  base_url: ""                # for local / self-hosted endpoints
   temperature: 0.2
 ```
 
-环境变量：
-- `REKIPEDIA_MODEL` —— litellm 模型字符串（默认：`ollama/llama4`）
-- `REKIPEDIA_API_KEY` —— 所选提供商的 API Key
-- `REKIPEDIA_BASE_URL` —— 自定义 Base URL
-- `REKIPEDIA_TIMEOUT` —— LLM 调用超时时间，单位秒（默认：180）
+### 支持的提供商（通过 [litellm](https://docs.litellm.ai)）
+
+| Provider | Example model string |
+|---|---|
+| Ollama (local, free) | `ollama/llama4` |
+| OpenAI | `gpt-5.5` |
+| Anthropic | `claude-opus-4-6` |
+| Google Gemini | `gemini/gemini-3.0-pro` |
+| Any OpenAI-compatible | set `base_url` in config |
+
+### 运行时覆盖（环境变量）
+
+```bash
+export REKIPEDIA_MODEL=gpt-5.5
+export REKIPEDIA_API_KEY=***
+export REKIPEDIA_BASE_URL=https://my-proxy/v1
+export REKIPEDIA_SHARD_TOKEN_BUDGET=***
+```
+
+| Variable | Description |
+|---|---|
+| `REKIPEDIA_MODEL` | LLM model name to use |
+| `REKIPEDIA_API_KEY` | API key for the LLM provider |
+| `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
+| `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
+| `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
+| `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
+| `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
 
 ---
 
-## 输出目录结构
+## 输出
+
+`rekipedia scan` 将所有内容写入仓库内的 `.rekipedia/` 目录：
 
 ```
 .rekipedia/
-├── config.yml
-├── store.db
-├── wiki/
-├── rag/
-├── diagrams/
-└── exports/
+├── config.yml              # your settings (committed)
+├── store.db                # SQLite knowledge store (git-ignored)
+├── scan_meta.json          # last scan metadata (model, timestamp, file count)
+├── wiki/                   # generated Markdown pages (3–15 pages, dynamically planned)
+│   ├── index.md
+│   ├── architecture-overview.md
+│   ├── repository-structure.md
+│   └── ... (pages vary by repo)
+├── rag/                    # RAG index (git-ignored)
+│   ├── index.faiss         # FAISS flat L2 index
+│   └── chunks.json         # source code chunks + metadata
+├── diagrams/               # Mermaid diagram files
+│   ├── module-graph.md
+│   └── class-hierarchy.md
+└── exports/                # JSON exports
+    ├── symbols.json
+    ├── relationships.json
+    └── manifest.json       # run summary + metadata + page importance scores
 ```
 
----
+根据仓库复杂度动态生成 3–15 个 wiki 页面（由 PlannerAgent 驱动）。
 
-## Python API
+wiki 结构由 `PlannerAgent` 根据仓库实际内容动态设计：
 
-```python
-import rekipedia
+| Section | Example pages | When generated |
+|---|---|---|
+| Getting Started | index, installation, quick-start | Always |
+| Architecture | architecture-overview, data-flow, repository-structure | ≥3 modules |
+| Core Components | One page per major module | ≥2 modules |
+| API Reference | cli-reference, python-api, rest-api | CLI/HTTP handlers found |
+| Development | testing, contributing, ci-cd | Test files found |
+| Ecosystem | integrations, deployment | ≥3 external deps |
 
-result = rekipedia.scan("/path/to/repo")
-answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
-print(answer.text)
-for c in answer.citations:
-    print(f"  {c.file}:{c.line}")
+### 扫描选项
+
+```bash
+# Use a specific LLM model
+rekipedia scan . --model gpt-5.5
+
+# Skip Docker (run extractors in-process)
+rekipedia scan . --no-docker
+
+# Write output to a custom directory
+rekipedia scan . --output-dir /tmp/wiki-output
+
+# Enable debug logging (litellm, HTTP, full tracebacks)
+rekipedia scan . --verbose
+
+# Auto-embed for RAG after scan
+rekipedia scan . --embed-model text-embedding-3-small --embed-provider openai
+```
+
+### RAG / 语义搜索
+
+`rekipedia ask` 使用**混合检索**——wiki 页面 + FAISS 索引的代码块——在完整代码库上下文中回答问题。
+
+```bash
+# Build or rebuild the FAISS index
+rekipedia embed .
+
+# Custom embedding model + provider
+rekipedia embed . --model text-embedding-3-small --provider openai
+rekipedia embed . --model nomic-embed-text --provider ollama
+
+# If your embed provider uses a DIFFERENT API key from your main LLM:
+rekipedia embed . --model text-embedding-3-small --provider openai
+# set embed_api_key in config.yml, or:
+export REKIPEDIA_EMBED_API_KEY=***
+
+# Or configure everything in .rekipedia/config.yml:
+# llm:
+#   model: ollama/llama4          # main LLM (local)
+#   embed_model: text-embedding-3-small
+#   embed_provider: openai
+#   embed_api_key: sk-xxx         # separate key for embed provider
+#   embed_base_url: ""            # optional: custom endpoint
+
+# Env var overrides (all optional):
+export REKIPEDIA_EMBED_MODEL=nomic-embed-text
+export REKIPEDIA_EMBED_PROVIDER=ollama
+export REKIPEDIA_EMBED_API_KEY=***
+export REKIPEDIA_EMBED_BASE_URL=https://my-proxy.example.com/v1
+```
+
+FAISS 索引保存至 `.rekipedia/rag/index.faiss`，分块后的源代码保存至 `.rekipedia/rag/chunks.json`。
+
+### 导出 wiki
+
+```bash
+# Single combined Markdown file (default)
+rekipedia export . --format md --output ./wiki-export.md
+
+# ZIP archive (one .md per page + manifest.json)
+rekipedia export . --format zip --output ./wiki.zip
+
+# Structured JSON (all pages + metadata)
+rekipedia export . --format json --output ./wiki.json
 ```
 
+### 增量更新
+
+首次扫描后，`rekipedia update` 仅重新处理 SHA-256 已发生变化的文件。未变更的符号和关系将从上次运行中延续——wiki 可在数秒内完成刷新。
+
+```bash
+rekipedia update .                    # auto-detect changed files
+rekipedia update . --no-docker        # skip Docker
+```
+
+若未找到之前的扫描记录，`update` 会自动回退至全量扫描。
+
+### 询问 wiki
+
+```bash
+# Start interactive Q&A session (streams answers, Ctrl+C to quit)
+rekipedia ask
+rekipedia ask --repo ./my-project
+rekipedia ask --model gpt-4o
+
+# Single-shot mode (backward compat)
+rekipedia ask -q "How does the auth flow work?"
+```
+
+答案**完全**基于您的 wiki 页面和符号索引——LLM 无法虚构扫描知识库中不存在的内容。答案以逐 token 流式方式输出，等待时显示进度指示器。
+
+对某个生成页面不满意？请参阅 **[docs/customizing.md](docs/customizing.md)**——您可以固定页面、覆盖提示词、更改写作风格，或添加扫描永不触碰的自定义页面。
+
+### 启动 wiki 服务
+
+```bash
+rekipedia serve .                     # opens browser at http://127.0.0.1:7070
+rekipedia serve . --port 8080         # custom port
+rekipedia serve . --no-browser        # don't auto-open browser
+```
+
+- 在深色主题的 Web 界面中浏览生成的 wiki 页面
+- 使用相同的有据可查问答功能提问（答案通过 Web 流式返回）
+- 问答历史记录存储于 SQLite
+
 ---
 
+## 前置要求
+
+- **Python ≥ 3.11**（或使用 `uv`，它自行管理 Python 环境）
+- **Docker**——可选；用于隔离提取。若 Docker 不可用，将自动回退至进程内运行模式（`--no-docker` 强制使用进程内模式）
+
+---
+
+## 与 AI 编程智能体配合使用
+
+rekipedia 附带一个 **Hermes agent skill**（`rekipedia-agent-skill.md`），可教会 AI 助手（Copilot、Claude Code、Codex）将 rekipedia 作为其代码库智能层：
+
+1. 将 `rekipedia-agent-skill.md` 复制到您的 Hermes skills 目录
+2. 任何已加载该 skill 的智能体都将在深入源文件之前自动扫描并查询 rekipedia
+3. 显著降低大型代码库的上下文窗口用量
+
+---
+
+## 智能体模式
+
+rekipedia 支持实验性智能体模式，其中 LLM 调用使用工具调用（ReAct）而非单次大上下文输入。
+
+### 智能体问答
+
+设置 `REKIPEDIA_AGENT_ASK=1` 以启用：
+
+```bash
+REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
+```
+
+LLM 按需发出工具调用以检索信息：
+- `search_code(query)` — 对源代码进行语义搜索
+- `get_symbol(name)` — 查找符号位置和签名
+- `get_page(slug)` — 按需获取 wiki 页面
+- `get_relationships(target)` — 获取符号/文件的依赖关系图
+- `finish(answer)` — 提供最终答案
+
+最大迭代次数可通过 `REKIPEDIA_ASK_MAX_ITER` 配置（默认值：5）。
+
+### 智能体规划器
+
+设置 `REKIPEDIA_AGENT_PLANNER=1` 以启用工具调用式 wiki 结构规划：
+
+```bash
+REKIPEDIA_AGENT_PLANNER=1 reki scan .
+```
+
+规划器通过工具调用逐步构建 wiki 结构，而非生成单个大型 JSON 响应。
+
 ## 开发
 
 ```bash
+# Install all deps
 make dev
+
+# Run tests
 make test
+
+# Lint
 make lint
+
+# Build wheel + npm tarball
 make build
 ```
 
+### 发布
+
+```bash
+PYPI_TOKEN=*** NPM_TOKEN=*** make release
+
+# Full release: build + tag + push + PyPI + npm
+make release-all PYPI_TOKEN=*** NPM_TOKEN=***
+# With version bump
+make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
+```
+
 ---
 
 ## 许可证
 
-MIT 许可证 — Copyright © 2026 Eddie Chan
+专有且保密——版权所有 © 2026 Eddie Chan。保留所有权利。
+
+未经授权，严禁复制、分发或修改本软件。
+详情请参阅 [LICENSE](LICENSE)。

package/README.zh-TW.md

@@ -2,158 +2,436 @@
 
 **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
 
-> 你的 AI 技術主管 — 隨時待命，永遠保持最新。
+> 您的 AI 技術領導——隨時待命，永遠最新。
+
+rekipedia 能掃描任何程式碼庫，將其轉化為可攜式的 SQLite 知識庫，並為團隊中每位開發者提供一位由 LLM 驅動的技術領導，讓他們隨時提問：_「驗證流程是如何運作的？」、「新增 API 端點最快的方法是什麼？」、「上週付款服務是什麼出了問題？」_
+
+不會產生幻覺，不靠猜測——每個答案都紮根於您實際的程式碼庫。
+
+### 主要功能
+- **關係可信度評分**：每個提取的關係都標記為 EXTRACTED/INFERRED/AMBIGUOUS，並附有可信度分數
+- **設計原理提取**：`# NOTE:`、`# HACK:`、`# WHY:` 注釋會被提取為知識節點
+- **核心節點（God nodes）**：連結度最高的符號會顯示於 index.md 並在圖表介面中高亮標示
+- **互動式依賴關係圖**：`rekipedia serve` 現在包含一個使用 D3.js 力導向視覺化的 `/graph` 路由
+- **Git hooks**：`rekipedia hook install` 會在每次提交時觸發自動重建
+- **代理式 wiki 協作**：`PlannerAgent` 根據您的程式碼庫動態設計 wiki 結構
+- **頁面重要性評分**：規劃器為每個頁面分配重要性分數（0–100）；導航側邊欄依優先級排序
+- **DeepWiki 式章節**：頁面分組至邏輯章節（`getting-started`、`architecture`、`core-components` 等）
+- **Wiki 側邊欄分類**：`reki serve` 側邊欄依 `section` 欄位將頁面分組，並支援可折疊標頭
+- **即時搜尋**：在側邊欄搜尋框中輸入，即可立即按標題或分類篩選 wiki 頁面
+- **重構分析**：`reki refactor` 偵測程式碼異味（神類、循環依賴、死碼、高耦合），並提供 LLM 增強的建議——輸出 `REFACTOR.md` + `refactor_report.json`
+- **上下文切片**：每個頁面只接收其所需的資料（相較固定佈局方式減少約 40–60% 的 token 用量）
+- **混合式 RAG 問答**：FAISS 索引的程式碼片段 + wiki 頁面，讓 LLM 在回答問題時擁有完整的程式碼庫上下文
+- **嵌入提供者選擇**：`--embed-provider openai|ollama|azure|...`——支援任何 litellm 相容的嵌入模型
+- **Wiki 匯出**：打包為單一 Markdown 檔案、ZIP 壓縮包或結構化 JSON（`rekipedia export`）
+- **增量更新**：初次掃描後僅重新處理已變更的檔案
+- **有依據的問答**：答案引用真實的檔案路徑和行號——不產生幻覺
+- **程式碼庫樹狀索引**——每次掃描都會在 SQLite 中建立階層式目錄/檔案樹，支援結構化導航與未來基於推理的檢索。
 
-rekipedia 可以將任何程式碼庫 scan 成可攜式的 SQLite 知識庫，讓每位開發者都擁有一位由 LLM 驅動的技術主管，可以隨時提問。
+## 快速開始
 
-零幻覺 — 每個回答都以你實際的程式碼庫為依據。
+### 透過 npm / npx（無需安裝）
 
----
+```bash
+npx rekipedia init .
+npx rekipedia scan .
+```
 
-## 快速開始
+### 透過 uv / uvx（無需安裝）
 
 ```bash
-# 無需安裝
-npx rekipedia init . && npx rekipedia scan .
-# 或
-uvx rekipedia init . && uvx rekipedia scan .
+uvx rekipedia init .
+uvx rekipedia scan .
 ```
 
+### 永久安裝
+
 ```bash
-# 永久安裝
-pip install rekipedia          # core
-pip install "rekipedia[rag]"   # + semantic search (FAISS)
+# Core (scan + serve + ask)
+pip install rekipedia
+# or
+uv tool install rekipedia
+
+# With RAG support (semantic embed + search — needs faiss-cpu + numpy ~100MB)
+pip install "rekipedia[rag]"
+
+# Homebrew (Go single binary — no Python needed)
+brew tap unrealandychan/tap
+brew install rekipedia
 ```
 
 ---
 
-## 快速開始 — 無需 API 金鑰
+## 快速開始——無需 API 金鑰
 
-不需要任何 LLM API 金鑰，即可執行完整的靜態分析：
+無需任何 LLM API 金鑰即可執行完整靜態分析：
 
 ```bash
 pip install rekipedia
-reki scan . --no-llm   # ~5-10s, zero API calls
-reki onboard .         # architecture overview
-reki tour .            # guided walkthrough by dependency depth
-reki domain .          # business domain layer map
-reki diff .            # impact analysis on changed files
-reki export . --format md  # export full wiki to markdown
+reki scan . --no-llm   # ~5-10 秒，零 API 呼叫
+reki onboard .         # 架構總覽
+reki tour .            # 依賴深度導覽
+reki domain .          # 業務領域層次圖
+reki diff .            # 變更影響分析
+reki export . --format md  # 匯出完整 wiki 為 Markdown
 ```
 
-> **注意：** `reki ask`（AI 問答）需要 LLM API 金鑰。請參閱下方的 [LLM 設定](#llm-設定)。
+> **注意：** `reki ask`（AI 問答）需要 LLM API 金鑰。請參閱下方 [LLM 設定](#llm-設定)。
 
 ---
 
-## 核心指令
+## Python API
 
-| 指令 | 功能說明 |
-|---|---|
-| `reki init .` | 建立初始設定檔 |
-| `reki scan .` | 完整分析 → wiki + 知識庫 |
-| `reki update .` | 增量更新（僅處理變更的檔案） |
-| `reki update . --impact-only` | 影響感知模式 — 僅重新產生受影響模組的 wiki 頁面 |
-| `reki serve .` | 本地端 Web UI — 瀏覽、搜尋、詢問 AI |
-| `reki ask` | 互動式問答 REPL（串流輸出） |
-| `reki embed .` | 建立 FAISS 語意索引以支援 hybrid RAG |
-| `reki export .` | 打包 wiki → `--format md|zip|json|html` |
-| `reki diff` | 未提交變更的影響分析 |
-| `reki domain .` | 將程式碼庫對應至業務層（API/Service/Data/UI） |
-| `reki tour .` | 依相依深度的引導式學習流程 |
-| `reki onboard .` | 給新開發者的靜態引導指南 |
-| `reki review` | 以 wiki 為基礎的 LLM PR 審查 |
-| `reki refactor .` | 偵測程式碼壞味道 → `REFACTOR.md` |
-| `reki refactor . --dry-run` | 預覽重構建議，不實際寫入檔案 |
-| `reki refactor . --apply` | 自動套用安全修正（死碼標記、拆分建議） |
-| `reki refactor . --apply --dry-run` | 預覽 `--apply` 將會執行的內容 |
-| `reki watch .` | 檔案變更時自動建立索引（OS watcher） |
-| `reki hook install` | Git post-commit 自動重建 |
-| `reki mcp` | 供 AI 程式碼助理使用的 MCP stdio 伺服器 |
+在 Jupyter 筆記本、CI 流水線或任何 Python 應用程式中以程式化方式使用 rekipedia：
 
----
+```python
+import rekipedia
 
-### `reki ask` — 簡潔模式
+# Scan a local repo
+result = rekipedia.scan("/path/to/repo")
+print(result.page_count)   # number of wiki pages generated
+print(result.symbol_count) # number of code symbols extracted
+print(result.token_count)  # estimated token count of the wiki
 
-```bash
-# Brief mode — ~150 tokens, summary + citations only
-reki ask "what does Scanner.scan() do?" --brief
+# Ask a question — grounded answer with file:line citations
+answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
+print(answer.text)
+for citation in answer.citations:
+    print(f"  {citation.file}:{citation.line}")
 
-# Or via env var (useful for piping)
-REKIPEDIA_BRIEF=1 reki ask "entry point?" | grep 'src/'
+# Async variants (Jupyter-friendly)
+result = await rekipedia.scan_async("/path/to/repo")
+answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
 ```
 
+**回傳型別：**
+
+| Type | Key fields |
+|---|---|
+| `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
+| `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
+| `Citation` | `file`, `line`, `snippet` |
+
+---
+
+## 指令
+
+| Command | Description |
+|---|---|
+| `rekipedia init [REPO]` | Scaffold `.rekipedia/` with `config.yml` and update `.gitignore` |
+| `rekipedia scan [REPO]` | Full analysis — extracts symbols, synthesises wiki pages, exports JSON |
+| `rekipedia update [REPO]` | Incremental refresh — re-extracts only changed files, keeps the rest |
+| `rekipedia ask [QUESTION]` | Interactive Q&A REPL — streaming answers, Ctrl+C to quit |
+| `rekipedia serve [REPO]` | Start a local web UI to browse wiki pages and ask questions |
+| `rekipedia embed [REPO]` | Build (or rebuild) the FAISS semantic search index for hybrid RAG Q&A |
+| `rekipedia export [REPO]` | Bundle the wiki to a single file (`--format md\|zip\|json`) |
+| `rekipedia hook install/uninstall/status` | Manage git post-commit hook for auto wiki rebuild |
+| `rekipedia diff [A] [B]` | Compare two graph snapshots (defaults to last two) |
+| `rekipedia impact <file>` | Show blast-radius — all affected files, symbols, tests for a changed file |
+| `rekipedia search <query>` | Search symbols (`--all-repos` for cross-repo parallel search) |
+| `rekipedia export --format graphml\|cypher\|obsidian` | Export graph to GraphML / Neo4j Cypher / Obsidian wikilinks |
+| `rekipedia mcp` | Start JSON-RPC 2.0 MCP stdio server (6 tools for AI coding assistants) |
+| `rekipedia watch add\|start\|list\|remove` | Watch repos and auto-index on file change |
+| `rekipedia refactor [REPO]` | Detect code smells + generate `REFACTOR.md` and `refactor_report.json` (use `--no-llm` for static only) |
+| `rekipedia note add\|list\|remove\|edit\|import` | Manage persistent tech lead notes — injected into `reki ask` context automatically |
+
 ---
 
 ## LLM 設定
 
-rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支援任何供應商：
+rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支援任何提供者：
 
-| 供應商 | 範例 |
+| 提供者 | 範例 |
 |---|---|
-| OpenAI | `OPENAI_API_KEY=*** reki scan .` |
-| Anthropic Claude | `REKIPEDIA_MODEL=claude-3-5-sonnet-20241022 REKIPEDIA_API_KEY=*** reki scan .` |
-| Google Gemini | `REKIPEDIA_MODEL=gemini/gemini-2.0-flash REKIPEDIA_API_KEY=*** reki scan .` |
-| OpenRouter | `REKIPEDIA_MODEL=openrouter/anthropic/claude-3.5-sonnet REKIPEDIA_API_KEY=*** reki scan .` |
+| OpenAI | `OPENAI_API_KEY=sk-... reki scan .` |
+| Anthropic Claude | `REKIPEDIA_MODEL=claude-3-5-sonnet-20241022 REKIPEDIA_API_KEY=sk-ant-... reki scan .` |
+| Google Gemini | `REKIPEDIA_MODEL=gemini/gemini-2.0-flash REKIPEDIA_API_KEY=AIza... reki scan .` |
+| OpenRouter | `REKIPEDIA_MODEL=openrouter/anthropic/claude-3.5-sonnet REKIPEDIA_API_KEY=sk-or-... reki scan .` |
 | 本地 Ollama（預設） | `REKIPEDIA_MODEL=ollama/llama4 reki scan .` |
-| Azure OpenAI | `REKIPEDIA_MODEL=azure/gpt-4o REKIPEDIA_BASE_URL=https://your-resource.openai.azure.com REKIPEDIA_API_KEY=*** reki scan .` |
+| Azure OpenAI | `REKIPEDIA_MODEL=azure/gpt-4o REKIPEDIA_BASE_URL=https://your-resource.openai.azure.com REKIPEDIA_API_KEY=... reki scan .` |
+
+環境變數：
+- `REKIPEDIA_MODEL` — litellm 模型字串（預設：`ollama/llama4`）
+- `REKIPEDIA_API_KEY` — 所選提供者的 API 金鑰
+- `REKIPEDIA_BASE_URL` — 自訂基礎 URL（用於 Azure、Ollama、代理）
+- `REKIPEDIA_TIMEOUT` — LLM 呼叫逾時秒數（預設：180）
 
-執行 `reki init` 後，編輯 `.rekipedia/config.yml`：
+執行 `rekipedia init` 後，編輯 `.rekipedia/config.yml`：
 
 ```yaml
+version: 1
+ignore:
+  - .git
+  - node_modules
+  - __pycache__
+  - .rekipedia
+languages:
+  - python
+  - typescript
 llm:
-  model: ollama/llama4
-  api_key: ""
-  base_url: ""
+  model: ollama/llama4        # any litellm model string
+  api_key: ""                 # or set REKIPEDIA_API_KEY env var
+  base_url: ""                # for local / self-hosted endpoints
   temperature: 0.2
 ```
 
-環境變數：
-- `REKIPEDIA_MODEL` — litellm model string（預設：`ollama/llama4`）
-- `REKIPEDIA_API_KEY` — 所選供應商的 API 金鑰
-- `REKIPEDIA_BASE_URL` — 自訂 base URL
-- `REKIPEDIA_TIMEOUT` — LLM 呼叫逾時秒數（預設：180）
+### 支援的提供者（透過 [litellm](https://docs.litellm.ai)）
+
+| Provider | Example model string |
+|---|---|
+| Ollama (local, free) | `ollama/llama4` |
+| OpenAI | `gpt-5.5` |
+| Anthropic | `claude-opus-4-6` |
+| Google Gemini | `gemini/gemini-3.0-pro` |
+| Any OpenAI-compatible | set `base_url` in config |
+
+### 執行時覆寫（環境變數）
+
+```bash
+export REKIPEDIA_MODEL=gpt-5.5
+export REKIPEDIA_API_KEY=***
+export REKIPEDIA_BASE_URL=https://my-proxy/v1
+export REKIPEDIA_SHARD_TOKEN_BUDGET=***
+```
+
+| Variable | Description |
+|---|---|
+| `REKIPEDIA_MODEL` | LLM model name to use |
+| `REKIPEDIA_API_KEY` | API key for the LLM provider |
+| `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
+| `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
+| `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
+| `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
+| `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
 
 ---
 
-## 輸出結構
+## 輸出
+
+`rekipedia scan` 會將所有內容寫入您程式碼庫內的 `.rekipedia/`：
 
 ```
 .rekipedia/
-├── config.yml
-├── store.db
-├── wiki/
-├── rag/
-├── diagrams/
-└── exports/
+├── config.yml              # your settings (committed)
+├── store.db                # SQLite knowledge store (git-ignored)
+├── scan_meta.json          # last scan metadata (model, timestamp, file count)
+├── wiki/                   # generated Markdown pages (3–15 pages, dynamically planned)
+│   ├── index.md
+│   ├── architecture-overview.md
+│   ├── repository-structure.md
+│   └── ... (pages vary by repo)
+├── rag/                    # RAG index (git-ignored)
+│   ├── index.faiss         # FAISS flat L2 index
+│   └── chunks.json         # source code chunks + metadata
+├── diagrams/               # Mermaid diagram files
+│   ├── module-graph.md
+│   └── class-hierarchy.md
+└── exports/                # JSON exports
+    ├── symbols.json
+    ├── relationships.json
+    └── manifest.json       # run summary + metadata + page importance scores
 ```
 
----
+根據程式碼庫複雜度動態生成 3–15 個 wiki 頁面（由 PlannerAgent 驅動）。
 
-## Python API
+Wiki 結構由 `PlannerAgent` 根據您程式碼庫的實際內容動態設計：
 
-```python
-import rekipedia
+| Section | Example pages | When generated |
+|---|---|---|
+| Getting Started | index, installation, quick-start | Always |
+| Architecture | architecture-overview, data-flow, repository-structure | ≥3 modules |
+| Core Components | One page per major module | ≥2 modules |
+| API Reference | cli-reference, python-api, rest-api | CLI/HTTP handlers found |
+| Development | testing, contributing, ci-cd | Test files found |
+| Ecosystem | integrations, deployment | ≥3 external deps |
 
-result = rekipedia.scan("/path/to/repo")
-answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
-print(answer.text)
-for c in answer.citations:
-    print(f"  {c.file}:{c.line}")
+### 掃描選項
+
+```bash
+# Use a specific LLM model
+rekipedia scan . --model gpt-5.5
+
+# Skip Docker (run extractors in-process)
+rekipedia scan . --no-docker
+
+# Write output to a custom directory
+rekipedia scan . --output-dir /tmp/wiki-output
+
+# Enable debug logging (litellm, HTTP, full tracebacks)
+rekipedia scan . --verbose
+
+# Auto-embed for RAG after scan
+rekipedia scan . --embed-model text-embedding-3-small --embed-provider openai
+```
+
+### RAG / 語義搜尋
+
+`rekipedia ask` 使用**混合式檢索**——wiki 頁面 + FAISS 索引的程式碼片段——以完整的程式碼庫上下文回答問題。
+
+```bash
+# Build or rebuild the FAISS index
+rekipedia embed .
+
+# Custom embedding model + provider
+rekipedia embed . --model text-embedding-3-small --provider openai
+rekipedia embed . --model nomic-embed-text --provider ollama
+
+# If your embed provider uses a DIFFERENT API key from your main LLM:
+rekipedia embed . --model text-embedding-3-small --provider openai
+# set embed_api_key in config.yml, or:
+export REKIPEDIA_EMBED_API_KEY=***
+
+# Or configure everything in .rekipedia/config.yml:
+# llm:
+#   model: ollama/llama4          # main LLM (local)
+#   embed_model: text-embedding-3-small
+#   embed_provider: openai
+#   embed_api_key: sk-xxx         # separate key for embed provider
+#   embed_base_url: ""            # optional: custom endpoint
+
+# Env var overrides (all optional):
+export REKIPEDIA_EMBED_MODEL=nomic-embed-text
+export REKIPEDIA_EMBED_PROVIDER=ollama
+export REKIPEDIA_EMBED_API_KEY=***
+export REKIPEDIA_EMBED_BASE_URL=https://my-proxy.example.com/v1
 ```
 
+FAISS 索引儲存於 `.rekipedia/rag/index.faiss`，分塊的原始碼儲存於 `.rekipedia/rag/chunks.json`。
+
+### 匯出 wiki
+
+```bash
+# Single combined Markdown file (default)
+rekipedia export . --format md --output ./wiki-export.md
+
+# ZIP archive (one .md per page + manifest.json)
+rekipedia export . --format zip --output ./wiki.zip
+
+# Structured JSON (all pages + metadata)
+rekipedia export . --format json --output ./wiki.json
+```
+
+### 增量更新
+
+初次掃描後，`rekipedia update` 只會重新處理 SHA-256 已變更的檔案。未變更的符號和關係會從上次執行中延續——wiki 可在幾秒內完成更新。
+
+```bash
+rekipedia update .                    # auto-detect changed files
+rekipedia update . --no-docker        # skip Docker
+```
+
+若找不到先前的掃描記錄，`update` 會自動回退至完整掃描。
+
+### 向 wiki 提問
+
+```bash
+# Start interactive Q&A session (streams answers, Ctrl+C to quit)
+rekipedia ask
+rekipedia ask --repo ./my-project
+rekipedia ask --model gpt-4o
+
+# Single-shot mode (backward compat)
+rekipedia ask -q "How does the auth flow work?"
+```
+
+答案**完全**以您的 wiki 頁面和符號索引為依據——LLM 無法捏造不存在於已掃描知識庫中的細節。答案以逐 token 串流方式輸出，等待時會顯示進度指示器。
+
+對某個生成頁面不滿意？請參閱 **[docs/customizing.md](docs/customizing.md)**——您可以釘選頁面、覆寫提示詞、更改寫作風格，或新增掃描時永遠不會觸及的自訂頁面。
+
+### 啟動 wiki 伺服器
+
+```bash
+rekipedia serve .                     # opens browser at http://127.0.0.1:7070
+rekipedia serve . --port 8080         # custom port
+rekipedia serve . --no-browser        # don't auto-open browser
+```
+
+- 在深色主題的網頁介面中瀏覽生成的 wiki 頁面
+- 使用相同的有依據問答功能提問（答案透過網頁串流）
+- 問答歷史記錄儲存於 SQLite
+
+---
+
+## 環境需求
+
+- **Python ≥ 3.11**（或使用 `uv`，它自行管理 Python 版本）
+- **Docker**——可選；用於隔離式提取。若 Docker 不可用，會自動回退至行程內執行模式（`--no-docker` 強制使用行程內模式）
+
 ---
 
+## 搭配 AI 程式碼代理使用 rekipedia
+
+rekipedia 附帶一個 **Hermes agent skill**（`rekipedia-agent-skill.md`），可教導 AI 助理（Copilot、Claude Code、Codex）將 rekipedia 作為其程式碼庫智慧層：
+
+1. 將 `rekipedia-agent-skill.md` 複製到您的 Hermes skills 目錄
+2. 任何已載入該技能的代理，都會在深入原始碼檔案前自動掃描並查詢 rekipedia
+3. 大幅減少大型程式碼庫的上下文視窗用量
+
+---
+
+## 代理模式
+
+rekipedia 支援實驗性的代理模式，其中 LLM 呼叫使用工具調用（ReAct）而非單次大型上下文傾倒。
+
+### 代理式提問
+
+設定 `REKIPEDIA_AGENT_ASK=1` 以啟用：
+
+```bash
+REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
+```
+
+LLM 會發出工具調用以按需取得資訊：
+- `search_code(query)` — 對原始碼進行語義搜尋
+- `get_symbol(name)` — 查詢符號的位置和簽名
+- `get_page(slug)` — 按需取得 wiki 頁面
+- `get_relationships(target)` — 取得符號/檔案的依賴關係圖
+- `finish(answer)` — 提供最終答案
+
+最大迭代次數可透過 `REKIPEDIA_ASK_MAX_ITER` 設定（預設值：5）。
+
+### 代理式規劃器
+
+設定 `REKIPEDIA_AGENT_PLANNER=1` 以啟用工具調用式 wiki 結構規劃：
+
+```bash
+REKIPEDIA_AGENT_PLANNER=1 reki scan .
+```
+
+規劃器使用工具調用增量建構 wiki 結構，而非生成單一大型 JSON 回應。
+
 ## 開發
 
 ```bash
+# Install all deps
 make dev
+
+# Run tests
 make test
+
+# Lint
 make lint
+
+# Build wheel + npm tarball
 make build
 ```
 
+### 發佈
+
+```bash
+PYPI_TOKEN=*** NPM_TOKEN=*** make release
+
+# Full release: build + tag + push + PyPI + npm
+make release-all PYPI_TOKEN=*** NPM_TOKEN=***
+# With version bump
+make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
+```
+
 ---
 
 ## 授權條款
 
-MIT License — Copyright © 2026 Eddie Chan
+專有且機密——版權所有 © 2026 Eddie Chan。保留所有權利。
+
+嚴禁未經授權複製、散布或修改本軟體。
+詳情請參閱 [LICENSE](LICENSE)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rekipedia",
-  "version": "0.17.29",
+  "version": "0.20.0",
   "description": "Agentic repo-to-wiki: scan any repository into a portable SQLite knowledge store with wiki pages, diagrams, and grounded Q&A.",
   "bin": {
     "rekipedia": "./bin/rekipedia.js"