rekipedia 0.17.24 → 0.17.27

package/README.md

@@ -1,163 +1,202 @@
 # rekipedia
 
-**[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
+**Turn any repo into an AI-ready knowledge base — wiki, RAG, and MCP server included.**
 
-> Your AI tech lead — always available, always up to date.
+[![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/)
 
-rekipedia scans any repository into a portable SQLite knowledge store and gives every developer an LLM-powered tech lead they can ask anything.
+---
+
+## Why rekipedia?
 
-No hallucinations — every answer is grounded in your actual codebase.
+- **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.
 
 ---
 
-## Quick start
+## ⚡ Quickstart
 
 ```bash
-# No install required
-npx rekipedia init . && npx rekipedia scan .
-# or
-uvx rekipedia init . && uvx rekipedia scan .
+pip install rekipedia
+# or: npx rekipedia
 ```
 
+### Zero config — no API key needed
+
 ```bash
-# Permanent install
-pip install rekipedia          # core
-pip install "rekipedia[rag]"   # + semantic search (FAISS)
+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
+export REKIPEDIA_API_KEY=sk-...
+reki scan .
+reki ask "how does authentication work?"
 ```
 
 ---
 
-## Quick Start — No API Key Needed
+## Key Features
+
+### 🗂 `reki scan` — Instant knowledge store
 
-Run a full static analysis without any LLM API key:
+Parses your repo into a SQLite knowledge store with symbols, relationships, and auto-generated wiki pages.
 
 ```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 .            # full scan with LLM summaries
+reki scan . --no-llm   # zero config, no API key required
 ```
 
-> **Note:** `reki ask` (AI Q&A) requires an LLM API key. See [LLM Setup](#llm-setup) below.
+### 💬 `reki ask` — Q&A grounded in your code
 
----
+Answers questions with file:line citations. No hallucinations — every answer is backed by indexed source.
 
-## Core commands
+```bash
+reki ask "what is the entry point?"
+reki ask "which modules handle payments?" --brief
+```
 
-| Command | What it does |
-|---|---|
-| `reki init .` | Scaffold config |
-| `reki scan .` | Full analysis → wiki + knowledge store |
-| `reki update .` | Incremental refresh (changed files only) |
-| `reki update . --impact-only` | Impact-aware mode — only regenerates wiki pages for affected modules |
-| `reki serve .` | Local web UI — browse, search, ask AI |
-| `reki ask` | Interactive Q&A REPL (streamed) |
-| `reki embed .` | Build FAISS semantic index for hybrid RAG |
-| `reki export .` | Bundle wiki → `--format md\|zip\|json\|html` |
-| `reki diff` | Uncommitted-change impact analysis |
-| `reki domain .` | Map codebase to business layers (API/Service/Data/UI) |
-| `reki tour .` | Guided learning walkthrough by dependency depth |
-| `reki onboard .` | Static onboarding guide for new developers |
-| `reki review` | LLM PR review grounded in wiki context |
-| `reki refactor .` | Detect code smells → `REFACTOR.md` |
-| `reki refactor . --dry-run` | Preview refactor suggestions without writing files |
-| `reki refactor . --apply` | Auto-apply safe fixes (dead code markers, split suggestions) |
-| `reki refactor . --apply --dry-run` | Preview what `--apply` would do |
-| `reki watch .` | Auto-index on file change (OS watcher) |
-| `reki hook install` | Git post-commit auto-rebuild |
-| `reki mcp` | MCP stdio server for AI coding assistants |
+```
+Answer: The entry point is src/main.py:12 — `App.run()` bootstraps the server.
+Sources: src/main.py:12, src/server.py:34
+```
 
----
+### 🤖 `reki mcp` — MCP server for AI agents
+
+Plug rekipedia directly into Claude Code, Cursor, or any MCP-aware agent.
+
+```bash
+reki mcp
+```
 
-### `reki ask` — Brief mode
+Available tools: `ask`, `search_nodes`, `get_context`, `get_relationships`, `get_hub_nodes`, `get_impact`
+
+### 🔥 `reki hotspots` — Architectural hotspot detection
+
+Finds hub and bridge nodes — the files your whole codebase depends on.
 
 ```bash
-# Brief mode — ~150 tokens, summary + citations only
-reki ask "what does Scanner.scan() do?" --brief
+reki hotspots
+```
 
-# Or via env var (useful for piping)
-REKIPEDIA_BRIEF=1 reki ask "entry point?" | grep 'src/'
+```
+Hub nodes:   src/core/engine.py (42 dependents)
+Bridge nodes: src/adapters/db.py (connects 3 clusters)
 ```
 
----
+### 🔄 `reki update` — Incremental updates
 
-## LLM Setup
+Only regenerates wiki pages affected by your changes.
 
-rekipedia uses [litellm](https://github.com/BerriAI/litellm) and supports any provider:
+```bash
+reki update . --impact-only
+```
 
-| Provider | Example |
-|---|---|
-| 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 .` |
-| Local Ollama (default) | `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 .` |
+---
 
-After `reki init`, edit `.rekipedia/config.yml`:
+## MCP Integration
 
-```yaml
-llm:
-  model: ollama/llama4        # any litellm model string
-  api_key: ""                 # or REKIPEDIA_API_KEY env var
-  base_url: ""                # for local / self-hosted endpoints
-  temperature: 0.2
+rekipedia ships a full MCP stdio server. Connect it to any MCP-aware agent in seconds.
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "rekipedia": {
+      "command": "reki",
+      "args": ["mcp"],
+      "cwd": "."
+    }
+  }
+}
 ```
 
-Supported providers: Ollama, OpenAI, Anthropic, Gemini, any OpenAI-compatible endpoint.
+Claude Code and Cursor will automatically discover this config. The agent can then call:
 
-Environment variables:
-- `REKIPEDIA_MODEL` — litellm model string (default: `ollama/llama4`)
-- `REKIPEDIA_API_KEY` — API key for the chosen provider
-- `REKIPEDIA_BASE_URL` — custom base URL (for Azure, Ollama, proxies)
-- `REKIPEDIA_TIMEOUT` — LLM call timeout in seconds (default: 180)
+- `ask` — Q&A over the codebase
+- `search_nodes` — symbol/file search
+- `get_context` — file-level context
+- `get_relationships` — dependency graph queries
+- `get_hub_nodes` — architectural hotspots
+- `get_impact` — change impact analysis
 
 ---
 
-## Output layout
+## LLM Setup
 
+rekipedia works without an LLM (`--no-llm`). To enable richer summaries and Q&A:
+
+```bash
+export REKIPEDIA_API_KEY=sk-...          # OpenAI, Anthropic, or compatible
+export REKIPEDIA_MODEL=gpt-4o           # default: gpt-4o
 ```
-.rekipedia/
-├── config.yml          # settings (committed)
-├── store.db            # SQLite knowledge store (git-ignored)
-├── wiki/               # generated Markdown pages
-├── rag/                # FAISS index + chunks (git-ignored)
-├── diagrams/           # Mermaid diagrams
-└── exports/            # JSON exports + manifest
+
+Any OpenAI-compatible endpoint works:
+
+```bash
+export REKIPEDIA_API_KEY=ollama
+export REKIPEDIA_MODEL=ollama/llama3
 ```
 
 ---
 
-## Python API
+## Commands
+
+| Command | Description |
+|---|---|
+| `reki scan .` | Full scan — index symbols, generate wiki |
+| `reki scan . --no-llm` | Scan without LLM, zero config |
+| `reki ask "question"` | Ask anything about the codebase |
+| `reki ask "question" --brief` | Short answer mode |
+| `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 diff` | Show impact of uncommitted changes |
+| `reki hotspots` | Hub & bridge node detection |
+| `reki refactor . --dry-run` | Preview refactor suggestions |
+| `reki refactor . --apply` | Apply refactor suggestions |
+| `reki mcp` | Start MCP stdio server |
+| `reki review` | LLM-powered PR review |
+| `reki watch .` | Auto-index on file change |
+| `reki hook install` | Install git post-commit hook |
 
-```python
-import rekipedia
+---
 
-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}")
-```
+## Coming Soon
 
-Async variants: `rekipedia.scan_async()`, `rekipedia.ask_async()`
+- **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
 
 ---
 
-## Development
+## Contributing
+
+rekipedia is going MIT open source. Contributions welcome.
 
 ```bash
-make dev      # install deps
-make test     # run tests
-make lint     # lint
-make build    # wheel + npm tarball
+git clone https://github.com/unrealandychan/rekipedia.git
+pip install -e ".[dev]"
 ```
 
----
+Open an issue or PR — the bar is low and the maintainer is responsive.
 
-## License
+---
 
-Proprietary and Confidential — Copyright © 2026 Eddie Chan. All Rights Reserved.
+**Current version:** `0.17.25` · [PyPI](https://pypi.org/project/rekipedia/) · [MIT License](LICENSE)

package/README.zh-CN.md

@@ -2,436 +2,158 @@
 
 **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
 
-> 您的 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 中构建层级目录/文件树，支持结构化导航和未来基于推理的检索。
+> 你的 AI 技术负责人 —— 随时在线，始终最新。
 
-## 快速开始
+rekipedia 可扫描任意代码库，生成便携式 SQLite 知识库，为每位开发者提供一个由 LLM 驱动的技术负责人，随问随答。
 
-### 通过 npm / npx（无需安装）
+零幻觉 —— 每个回答都基于你的真实代码库。
 
-```bash
-npx rekipedia init .
-npx rekipedia scan .
-```
+---
 
-### 通过 uv / uvx（无需安装）
+## 快速开始
 
 ```bash
-uvx rekipedia init .
-uvx rekipedia scan .
+# 无需安装
+npx rekipedia init . && npx rekipedia scan .
+# 或
+uvx rekipedia init . && uvx rekipedia scan .
 ```
 
-### 永久安装
-
 ```bash
-# 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
+# 永久安装
+pip install rekipedia          # 核心
+pip install "rekipedia[rag]"   # + 语义搜索 (FAISS)
 ```
 
 ---
 
-## 快速开始——无需 API 密钥
+## 快速开始 —— 无需 API Key
 
-无需任何 LLM API 密钥即可执行完整静态分析：
+无需任何 LLM API Key，即可运行完整静态分析：
 
 ```bash
 pip install rekipedia
-reki scan . --no-llm   # ~5-10 秒，零 API 调用
-reki onboard .         # 架构总览
-reki tour .            # 依赖深度导览
-reki domain .          # 业务领域层次图
-reki diff .            # 变更影响分析
-reki export . --format md  # 导出完整 wiki 为 Markdown
+reki scan . --no-llm   # ~5-10s，零 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 Key。请参阅下方 [LLM 配置](#llm-配置)。
 
 ---
 
-## Python API
-
-在 Jupyter Notebook、CI 流水线或任意 Python 应用中以编程方式使用 rekipedia：
+## 核心命令
 
-```python
-import rekipedia
-
-# 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
-
-# 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}")
-
-# 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` |
+| `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 服务器 |
 
 ---
 
-## 命令
+### `reki ask` —— 简洁模式
 
-| 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 |
+```bash
+# 简洁模式 —— ~150 tokens，仅输出摘要 + 引用
+reki ask "what does Scanner.scan() do?" --brief
+
+# 或通过环境变量（便于管道传输）
+REKIPEDIA_BRIEF=1 reki ask "entry point?" | grep 'src/'
+```
 
 ---
 
 ## LLM 配置
 
-rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支持任何提供商：
+rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支持任意 LLM 提供商：
 
 | 提供商 | 示例 |
 |---|---|
-| 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 .` |
+| 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 .` |
 | 本地 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）
-
-运行 `rekipedia init` 后，编辑 `.rekipedia/config.yml`：
+执行 `reki init` 后，编辑 `.rekipedia/config.yml`：
 
 ```yaml
-version: 1
-ignore:
-  - .git
-  - node_modules
-  - __pycache__
-  - .rekipedia
-languages:
-  - python
-  - typescript
 llm:
-  model: ollama/llama4        # any litellm model string
-  api_key: ""                 # or set REKIPEDIA_API_KEY env var
-  base_url: ""                # for local / self-hosted endpoints
+  model: ollama/llama4
+  api_key: ""
+  base_url: ""
   temperature: 0.2
 ```
 
-### 支持的提供商（通过 [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_MODEL` —— litellm 模型字符串（默认：`ollama/llama4`）
+- `REKIPEDIA_API_KEY` —— 所选提供商的 API Key
+- `REKIPEDIA_BASE_URL` —— 自定义 Base URL
+- `REKIPEDIA_TIMEOUT` —— LLM 调用超时时间，单位秒（默认：180）
 
 ---
 
-## 输出
-
-`rekipedia scan` 将所有内容写入仓库内的 `.rekipedia/` 目录：
+## 输出目录结构
 
 ```
 .rekipedia/
-├── 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 驱动）。
-
-wiki 结构由 `PlannerAgent` 根据仓库实际内容动态设计：
-
-| 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 |
-
-### 扫描选项
-
-```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?"
+├── config.yml
+├── store.db
+├── wiki/
+├── rag/
+├── diagrams/
+└── exports/
 ```
 
-答案**完全**基于您的 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）。
-
-### 智能体规划器
+## Python API
 
-设置 `REKIPEDIA_AGENT_PLANNER=1` 以启用工具调用式 wiki 结构规划：
+```python
+import rekipedia
 
-```bash
-REKIPEDIA_AGENT_PLANNER=1 reki scan .
+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}")
 ```
 
-规划器通过工具调用逐步构建 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
-```
-
 ---
 
 ## 许可证
 
-专有且保密——版权所有 © 2026 Eddie Chan。保留所有权利。
-
-未经授权，严禁复制、分发或修改本软件。
-详情请参阅 [LICENSE](LICENSE)。
+MIT 许可证 — Copyright © 2026 Eddie Chan

package/README.zh-TW.md

@@ -2,436 +2,158 @@
 
 **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
 
-> 您的 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 中建立階層式目錄/檔案樹，支援結構化導航與未來基於推理的檢索。
+> 你的 AI 技術主管 — 隨時待命，永遠保持最新。
 
-## 快速開始
+rekipedia 可以將任何程式碼庫 scan 成可攜式的 SQLite 知識庫，讓每位開發者都擁有一位由 LLM 驅動的技術主管，可以隨時提問。
 
-### 透過 npm / npx（無需安裝）
+零幻覺 — 每個回答都以你實際的程式碼庫為依據。
 
-```bash
-npx rekipedia init .
-npx rekipedia scan .
-```
+---
 
-### 透過 uv / uvx（無需安裝）
+## 快速開始
 
 ```bash
-uvx rekipedia init .
-uvx rekipedia scan .
+# 無需安裝
+npx rekipedia init . && npx rekipedia scan .
+# 或
+uvx rekipedia init . && uvx rekipedia scan .
 ```
 
-### 永久安裝
-
 ```bash
-# 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
+# 永久安裝
+pip install rekipedia          # core
+pip install "rekipedia[rag]"   # + semantic search (FAISS)
 ```
 
 ---
 
-## 快速開始——無需 API 金鑰
+## 快速開始 — 無需 API 金鑰
 
-無需任何 LLM API 金鑰即可執行完整靜態分析：
+不需要任何 LLM API 金鑰，即可執行完整的靜態分析：
 
 ```bash
 pip install rekipedia
-reki scan . --no-llm   # ~5-10 秒，零 API 呼叫
-reki onboard .         # 架構總覽
-reki tour .            # 依賴深度導覽
-reki domain .          # 業務領域層次圖
-reki diff .            # 變更影響分析
-reki export . --format md  # 匯出完整 wiki 為 Markdown
+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 ask`（AI 問答）需要 LLM API 金鑰。請參閱下方 [LLM 設定](#llm-設定)。
+> **注意：** `reki ask`（AI 問答）需要 LLM API 金鑰。請參閱下方的 [LLM 設定](#llm-設定)。
 
 ---
 
-## Python API
-
-在 Jupyter 筆記本、CI 流水線或任何 Python 應用程式中以程式化方式使用 rekipedia：
+## 核心指令
 
-```python
-import rekipedia
-
-# 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
-
-# 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}")
-
-# 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` |
+| `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 伺服器 |
 
 ---
 
-## 指令
+### `reki ask` — 簡潔模式
 
-| 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 |
+```bash
+# Brief mode — ~150 tokens, summary + citations only
+reki ask "what does Scanner.scan() do?" --brief
+
+# Or via env var (useful for piping)
+REKIPEDIA_BRIEF=1 reki ask "entry point?" | grep 'src/'
+```
 
 ---
 
 ## LLM 設定
 
-rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支援任何提供者：
+rekipedia 使用 [litellm](https://github.com/BerriAI/litellm)，支援任何供應商：
 
-| 提供者 | 範例 |
+| 供應商 | 範例 |
 |---|---|
-| 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 .` |
+| 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 .` |
 | 本地 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 .` |
-
-環境變數：
-- `REKIPEDIA_MODEL` — litellm 模型字串（預設：`ollama/llama4`）
-- `REKIPEDIA_API_KEY` — 所選提供者的 API 金鑰
-- `REKIPEDIA_BASE_URL` — 自訂基礎 URL（用於 Azure、Ollama、代理）
-- `REKIPEDIA_TIMEOUT` — LLM 呼叫逾時秒數（預設：180）
+| Azure OpenAI | `REKIPEDIA_MODEL=azure/gpt-4o REKIPEDIA_BASE_URL=https://your-resource.openai.azure.com REKIPEDIA_API_KEY=*** reki scan .` |
 
-執行 `rekipedia init` 後，編輯 `.rekipedia/config.yml`：
+執行 `reki init` 後，編輯 `.rekipedia/config.yml`：
 
 ```yaml
-version: 1
-ignore:
-  - .git
-  - node_modules
-  - __pycache__
-  - .rekipedia
-languages:
-  - python
-  - typescript
 llm:
-  model: ollama/llama4        # any litellm model string
-  api_key: ""                 # or set REKIPEDIA_API_KEY env var
-  base_url: ""                # for local / self-hosted endpoints
+  model: ollama/llama4
+  api_key: ""
+  base_url: ""
   temperature: 0.2
 ```
 
-### 支援的提供者（透過 [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_MODEL` — litellm model string（預設：`ollama/llama4`）
+- `REKIPEDIA_API_KEY` — 所選供應商的 API 金鑰
+- `REKIPEDIA_BASE_URL` — 自訂 base URL
+- `REKIPEDIA_TIMEOUT` — LLM 呼叫逾時秒數（預設：180）
 
 ---
 
-## 輸出
-
-`rekipedia scan` 會將所有內容寫入您程式碼庫內的 `.rekipedia/`：
+## 輸出結構
 
 ```
 .rekipedia/
-├── 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 驅動）。
-
-Wiki 結構由 `PlannerAgent` 根據您程式碼庫的實際內容動態設計：
-
-| 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 |
-
-### 掃描選項
-
-```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
+├── config.yml
+├── store.db
+├── wiki/
+├── rag/
+├── diagrams/
+└── exports/
 ```
 
-### 增量更新
-
-初次掃描後，`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）。
-
-### 代理式規劃器
+## Python API
 
-設定 `REKIPEDIA_AGENT_PLANNER=1` 以啟用工具調用式 wiki 結構規劃：
+```python
+import rekipedia
 
-```bash
-REKIPEDIA_AGENT_PLANNER=1 reki scan .
+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}")
 ```
 
-規劃器使用工具調用增量建構 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
-```
-
 ---
 
 ## 授權條款
 
-專有且機密——版權所有 © 2026 Eddie Chan。保留所有權利。
-
-嚴禁未經授權複製、散布或修改本軟體。
-詳情請參閱 [LICENSE](LICENSE)。
+MIT License — Copyright © 2026 Eddie Chan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rekipedia",
-  "version": "0.17.24",
+  "version": "0.17.27",
   "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"