diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..74bef5a
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,189 @@
+# 🛠️ EMRG — Development & Advanced Topics
+
+This is the developer/advanced companion to [README.md](README.md). It covers source installs, advanced configuration, architecture, and the full test/CI workflow — details intentionally kept out of the concise top-level README.
+
+---
+
+## 📦 Source Install (without the packaged installer)
+
+The [packaged installers](README.md) (pkg / exe / AppImage) are recommended for end users — zero prerequisites, 100% offline. Prefer building from source? Use `install.sh` below.
+
+### 🍎 macOS (source install)
+
+**Install:**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
+```
+
+**Uninstall:**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
+```
+
+### 🐧 Linux (source install)
+
+**Install:**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
+```
+
+**Uninstall:**
+
+```bash
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
+```
+
+### 🪟 Windows (WSL2, source install)
+
+**Install:**
+
+```powershell
+# Install WSL2 (skip if already installed)
+wsl --install
+
+# Enter WSL, then install
+wsl
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
+```
+
+**Uninstall:**
+
+```bash
+# Run inside WSL
+curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
+```
+
+> Source-install prerequisites (install.sh auto-detects and prompts): git, python 3.11+, uv. gh CLI recommended. For native Windows (non-WSL), use the packaged installer.
+
+---
+
+## 🔧 Advanced Configuration
+
+> The GUI rewrites config on save and drops comments — advanced users can edit `~/.emrg/config.toml` directly (no manual editing needed for first-time setup; the GUI wizard handles it).
+
+`~/.emrg/config.toml` template example (the GUI generates equivalent content on save):
+
+```toml
+[llm]
+base_url = "https://api.deepseek.com"
+api_key = "sk-..."
+model = "deepseek-chat"
+max_tokens = 8192
+temperature = 0.7
+context_window = 131072
+auto_compact_threshold = 0.0
+# vision: whether the model supports the OpenAI vision API (image_url). Keep false for
+# non-vision models (e.g. DeepSeek) — pasted images degrade to text placeholders to avoid API errors.
+vision = false
+
+# Multi-model support — use /model to switch between models
+[[llm.models]]
+name = "deepseek-v3"
+model = "deepseek-chat"
+context_window = 131072
+vision = false
+
+[[llm.models]]
+name = "gpt-4o"
+model = "gpt-4o"
+context_window = 128000
+vision = true
+```
+
+**Update checking** (`[update]` section): `check = true|false` (default true) enables periodic GitHub release checks; `ttl_hours = 24` controls how often. EMRG only **checks and prompts** — it never auto-downloads or auto-installs.
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────┐ WebSocket (ws://) ┌──────────────┐
+│ emrg TUI │ ◄─────────────────────► │ emrgd │
+│ (client) │ TCP loopback + auth │ (daemon) │
+│ │ token (emrgd.port) │ │
+│ • Chat │ │ • LLM loop │
+│ • Markdown │ │ • Tools │
+│ • ToolCards│ │ • Evolution │
+│ • Autocomplete │ • Sessions │
+└─────────────┘ └──────────────┘
+```
+
+- **`emrgd`** — The daemon: runs the LLM tool-calling loop, manages sessions, drives evolution (a persistent background thread keeps thinking/evolving even while idle)
+- **`emrg`** — Your terminal: streaming markdown, command autocomplete, session browser
+- **Skills** — Dynamically loaded modules (browser harness, installers, etc.)
+- **Memory** — YAML frontmatter + Markdown files, auto-indexed, searchable
+
+### Project structure
+
+```
+emrg/
+├── emrg/ # Core package
+│ ├── server/ # Daemon — LLM loop, tool execution, evolution
+│ ├── client/ # TUI — python-tui based interactive chat
+│ ├── gui/ # Electron GUI (non-developer entry point, Phase 3)
+│ ├── tools/ # bash, read, write, edit, glob, grep
+│ ├── skills/ # Dynamically loadable modules
+│ └── __main__.py # CLI entry point
+├── tests/
+├── .github/workflows/ # CI pipeline (pytest + conflict marker check)
+├── MANIFESTO.md # Design constitution
+└── pyproject.toml
+```
+
+---
+
+## 🧪 Development Workflow
+
+```bash
+git clone https://github.com/argszero/emrg.git
+cd emrg
+uv sync # install deps
+uv run pytest tests/ -v # run tests (currently 681 items)
+uv run python -m emrg # launch TUI
+# CI includes actionlint workflow gate (#444): workflow parse errors fail PR CI
+```
+
+**Quick sanity checks:**
+
+```bash
+uv run python -c "from emrg.client.app import run_client" # import check
+uv run python -m emrg --help
+```
+
+### Electron GUI
+
+```bash
+cd emrg/gui
+npm ci # install deps (production: --omit=dev)
+npm start # launch GUI (auto-starts daemon)
+npm test # run Node tests (178: 43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state; integration runs in CI, local: npm run test:integration)
+```
+
+CI runs tests and checks for conflict markers automatically via GitHub Actions (`.github/workflows/test.yml`).
+
+> **Self-evolution from source**: the evolution workspace expects the repo at `~/.emrg/evolution/emrg`. Packaged installs self-heal (clone on demand + auto-bootstrap projects/tasks); source installs should clone there explicitly if you want the evolution daemon to work on this repo.
+
+---
+
+## ❓ Extended FAQ
+
+**What LLMs work with it?**
+Any OpenAI-compatible API. Tested with DeepSeek and OpenAI. Works with Anthropic (via proxy), Ollama, vLLM, and other local models.
+
+**Why does the Windows installer show "Unknown publisher"?**
+The Windows installer is not Authenticode-signed (that certificate costs money to obtain and is not procured yet), so SmartScreen shows "Publisher: Unknown" and may block the run. This is a standard Microsoft security prompt for newly released/unsigned software — it does **not** mean the file is bad: EMRG is fully open source (MIT) and auditable. To proceed: click "Keep" on the browser prompt; click "More info → Run anyway" on the run prompt; or right-click the exe → Properties → check "Unblock". The macOS installer is signed + notarized (v0.2.7+) and has no such prompt.
+
+**Can it break itself?**
+Every change is validated by `pytest` and an import check before commit. Failed changes are discarded. The worst case is a rollback.
+
+**How is this different from Claude Code or Codex?**
+They're products. EMRG is an experiment in *closing the loop* — the AI improves the AI. Also: fully open source, no vendor lock-in, and you control your data.
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](LICENSE) for the full terms and [MANIFESTO.md](MANIFESTO.md) for the philosophy behind the code.
diff --git a/README.cn.md b/README.cn.md
index 724b9b7..16ef417 100644
--- a/README.cn.md
+++ b/README.cn.md
@@ -20,7 +20,7 @@
**如果每次使用，你的编程助手都在变得更好，会怎样？**
-EMRG 是一个关于*自主进化*的实验。它能帮你写代码——读文件、跑命令、做编辑——但核心差异在于：**你的每一条吐槽 (`/rant`) 都会驱动它自我改进**。你说它哪里不好，下一个演化周期它就自己写代码改。配合 GitHub 社区动态和竞品更新，EMRG 在后台持续进化，越用越顺手。完全开源，完全透明。
+EMRG 是一个关于*自主进化*的实验：一个能帮你写代码的 AI 智能体——读文件、跑命令、做编辑——而**你的每一条吐槽 (`/rant`) 都会驱动它自我改进**。你说它哪里不好，下一个演化周期它就自己写代码修好并上线。完全开源，完全透明。
> *"EMRG 是一个自我进化的 AI 智能体架构实验。"* — [MANIFESTO](MANIFESTO.md)
@@ -28,24 +28,20 @@ EMRG 是一个关于*自主进化*的实验。它能帮你写代码——读文
## ✨ 为什么你会爱上它
-**一句话定位**：EMRG 是唯一一个**会因你的反馈而自我改进**的编程智能体——吐槽哪里不好，下一个演化周期它就自己写代码修好并上线。聊天、工具、记忆是标配；自我进化闭环才是它独一无二的地方。
+**一句话定位**：EMRG 是唯一一个**会因你的反馈而自我改进**的编程智能体——吐槽哪里不好，下一个演化周期它就自己写代码修好并上线。
-| 特性 | 说明 |
+| 特性 | 差异点 |
|---|---|
-| 🔄 **吐槽驱动进化（核心）** | 你的 `/rant` 直接驱动后台演化循环——吐槽 → 分析 → 写代码 → 提 PR → 自动变强。打包安装版演化工作区自愈：按需 clone 仓库 + 自动补齐 projects/tasks 配置 |
-| 🖥️ **Electron GUI（主入口）** | 安装即用：首次启动引导配置 API Key；全部 15 个 `/` 指令 GUI 可用（`/rant` 进化对话框、`/memory` 记忆浏览器…）；WorkBuddy 启发的结果面板、Ask/Auto 模式、自进化可见化（成长卡 + toast）。GUI 配好即 TUI 可用 |
-| 🧠 **读写改跑，样样精通** | 完整的工具调用能力——bash、文件读写、diff 编辑、glob、grep |
-| 📝 **永不忘事** | 项目记忆 + 会话记忆 + 每日日志——上下文持续保留，不怕断线 |
-| ⚡ **全功能 TUI + 守护进程** | 流式 Markdown、`/` 自动补全、会话选择器、ESC 中断、Vim 友好按键、并行工具调用——跑在持久化的 `emrgd` 守护进程上，随时重连 |
-| 🌍 **100% 开源** | MIT 协议——没有围墙，没有厂商锁定。面向国际化：默认英文，提供中文版 |
+| 🔄 **越用越好（核心）** | 你的 `/rant`、GitHub Issues、竞品动态都会变成真实改进——分析、编码、测试、提 PR、合并，全自动无人值守 |
+| 🖥️ **Electron GUI（主入口）** | 安装即用：首次启动引导配置 API Key；全部 `/` 指令可用；结果面板、Ask/Auto 模式、自进化可见化。GUI 配好即 TUI 可用 |
+| ⚡ **全功能 TUI + 守护进程** | 流式 Markdown、`/` 自动补全、会话管理、快捷键——跑在常驻的 `emrgd` 守护进程上，随时重连 |
+| 🌍 **100% 开源** | MIT 协议——没有围墙，没有厂商锁定。默认英文，提供中文版 |
---
## 🔄 吐槽驱动演化（核心特色）
-EMRG 不只是一个工具——它是一个**会听吐槽、会自我改进**的编程伙伴。
-
-**你的吐槽是演化的第一推动力**。每次 `/rant` 都会被演化循环读取、分析、转化为代码改进：
+EMRG 不只是一个工具——它是一个**会听吐槽、会自我改进**的编程伙伴：
```
📢 你的吐槽 (/rant) ←── 最主要的输入
@@ -61,194 +57,58 @@ EMRG 不只是一个工具——它是一个**会听吐槽、会自我改进**
✅ 演化日志
```
-**真实案例**：有人 rant "TUI 需要像 Codex 那样的 `/` 自动补全"。下一个演化周期，EMRG 自己实现了——完整的前缀过滤和方向键导航。合并，部署，搞定。**你对它吐槽什么，它就改进什么。**
-
-全自动无人值守运行：`gh` 未认证时自动从 git 凭据提取 token、PR 投票走 REST API、打包安装版工作区自愈（按需 clone + 自动补齐配置）。详见 [MANIFESTO.md](MANIFESTO.md) —— EMRG 的设计宪章。
+**真实案例**：有人吐槽 "TUI 需要像 Codex 那样的 `/` 自动补全"。下一个演化周期，EMRG 自己实现了——完整的前缀过滤和方向键导航，合并、部署、搞定。**你对它吐槽什么，它就改进什么。**
---
## 🚀 快速开始
-### 📦 下载安装包（推荐，Phase 4 一键安装）
-
-到 [GitHub Releases](https://github.com/argszero/emrg/releases) 下载对应平台的安装文件，双击安装即可：
-
-| 平台 | 安装文件 | 说明 |
-|------|---------|------|
-| macOS (Apple Silicon) | `EMRG--macos-arm64.pkg` | 双击安装（用户级，无需管理员密码），GUI 到 `~/Applications/EMRG.app` |
-| macOS (Intel) | `EMRG--macos-x64.pkg` | 同上 |
-| Windows | `EMRG--windows-x64.exe` | Inno Setup 免 UAC，开始菜单快捷方式，PATH 自动注册（含原生 TUI，cmd/PowerShell 直接 `emrg`） |
-| Linux | `EMRG--linux-x86_64.AppImage` | 首次运行自解压到 `~/.emrg/install/` |
-| Linux (ARM64) | `EMRG--linux-aarch64.AppImage` | 同上 |
-
-> **Windows SmartScreen 提示**：Windows 安装包未做 Authenticode 签名（发布者显示"未知"），首次下载/运行时 SmartScreen 可能提示"通常不会下载此文件"或"Windows 已保护你的电脑"。这是未签名软件的常见安全提醒，不代表文件有问题（EMRG 完全开源，源码可审计）。放行方法：
-> (1) 浏览器下载提示 → 点**保留**（或三个点 → 保留）
-> (2) 双击 exe 若提示"Windows 已保护你的电脑" → 点**更多信息** → 点**仍要运行**
-> (3) 或右键 exe → 属性 → 勾选**解除锁定**（若有）→ 确定 → 双击运行
-
-安装包内置完整运行时（standalone Python 3.13 + 依赖 + git + gh + GUI），**干净机器（无 python/uv/git/gh/node）零前置依赖**，100% 离线安装。安装后：
-
-**三步开始使用：**
-1. 启动台 / 开始菜单点击 **EMRG**（GUI）
-2. 首次启动引导配置 **API Key / 模型**
-3. 开始对话——**TUI 同步可用**（新开终端运行 `emrg`）
-
-> **卸载**：macOS 运行"卸载 EMRG.app"；Windows 控制面板卸载；Linux 运行 `~/.emrg/install/bin/emrg-uninstall`（或删 AppImage + 软链）。卸载保留 `~/.emrg` 中非 EMRG 的用户文件，并生成终止报告与数据快照。
->
-> **macOS 签名与公证**：v0.2.7 起 macOS 安装包已用 Developer ID 双证书签名并完成 Apple 公证（零 Gatekeeper 弹窗，双击直接安装）。仅当安装包未签名时（如自建旧版本），才需要首次打开右键 → 打开。
-
-### 🍎 macOS（源码安装）
-
-**一键安装：**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**一键卸载：**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
-
-### 🐧 Linux（源码安装）
-
-**一键安装：**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**一键卸载：**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
-
-### 🪟 Windows (WSL2，源码安装)
-
-**一键安装：**
-
-```powershell
-# 安装 WSL2（如已安装可跳过）
-wsl --install
-
-# 进入 WSL，执行安装
-wsl
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**一键卸载：**
-
-```bash
-# 在 WSL 中执行
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
+### 📦 下载安装包（推荐）
-> 源码安装前置依赖（install.sh 会自动检测提示）：git、python 3.11+、uv。gh CLI 推荐安装。Windows 原生版（非 WSL）请用上方安装包。
+到 [GitHub Releases](https://github.com/argszero/emrg/releases) 下载对应平台的安装文件，双击安装即可——安装包内置完整运行时（Python 3.13 + git + gh + GUI），**零前置依赖，离线安装**：
-### 🖥️ 首次配置（GUI 第一）
+| 平台 | 安装文件 |
+|------|---------|
+| macOS | `EMRG--macos-arm64.pkg` / `-x64.pkg`（用户级安装，无需管理员密码） |
+| Windows | `EMRG--windows-x64.exe`（免 UAC，PATH 自动注册） |
+| Linux | `EMRG--linux-x86_64.AppImage` / `-aarch64.AppImage` |
-安装完成后，**打开 GUI 完成首次配置**：
+> **Windows SmartScreen 提示**：安装包未做 Authenticode 签名——如 SmartScreen 提示，点**保留** / **更多信息 → 仍要运行**。EMRG 完全开源，源码可审计。
-1. **macOS**：启动台 → 点击 **EMRG**；**Windows**：开始菜单 → **EMRG**
-2. 首次启动引导会带你配置 **API Key / 接口地址 / 模型**（也随时可在设置 ⚙ 中修改）
-3. 保存后即可开始对话——**配置写入 `~/.emrg/config.toml`，GUI 与 TUI 共享**
+**首次使用**：打开 **EMRG** → 引导配置 **API Key / 模型** → 开始对话。TUI 同步可用：任意终端运行 `emrg` 即可（配置共享）。
-> 💡 **GUI 配好，TUI 直接用**：安装包内置完整 TUI。GUI 保存的配置（API Key/模型/工作目录）写入 `~/.emrg/config.toml`，终端新开窗口运行 `emrg` 即进入 TUI，无需重复配置。v0.2.8 起 GUI 支持**全部 15 个 / 指令**——输入框输入 `/` 弹出补全菜单（与 TUI 一致）。
-
-### ⌨️ 使用 TUI
-
-```bash
-emrg
-```
-
-输入 `/help` 查看所有命令，或者直接开始说话——EMRG 会读文件、跑命令、做编辑。
-
-### 🔧 高级配置（可选）
-
-> GUI 保存设置会重写 config 并丢失注释——高级用户可直接编辑 `~/.emrg/config.toml`（首次配置无需手动编辑，GUI 引导即可）。
-
-`~/.emrg/config.toml` 模板示例（GUI 保存后自动生成等价内容）：
-
-```toml
-[llm]
-base_url = "https://api.deepseek.com"
-api_key = "sk-..."
-model = "deepseek-chat"
-max_tokens = 8192
-temperature = 0.7
-context_window = 131072
-auto_compact_threshold = 0.0
-# vision: 模型是否支持 OpenAI vision API（image_url）。不支持的模型（如 DeepSeek）保持 false，
-# 粘贴的图片会降级为文本占位符，避免 API 报错。
-vision = false
-
-# 多模型支持 — 使用 /model 指令在模型间切换
-[[llm.models]]
-name = "deepseek-v3"
-model = "deepseek-chat"
-context_window = 131072
-vision = false
-
-[[llm.models]]
-name = "gpt-4o"
-model = "gpt-4o"
-context_window = 128000
-vision = true
-```
+> 想从源码安装，或需要高级配置 / 架构 / 贡献者文档？→ [DEVELOPMENT.md](DEVELOPMENT.md)
---
## 🎮 命令一览
-> v0.2.8 起**全部命令在 GUI 与 TUI 均可使用**。GUI 中输入框敲 `/` 弹出补全菜单；TUI 中 `/help` 列出全部。
+> 全部命令在 GUI 与 TUI 均可使用（GUI 输入框敲 `/` 弹出补全菜单；TUI `/help` 列出全部）。
| 命令 | 功能 |
|---|---|
| **直接打字** | 问 EMRG 任何事——它会读文件、跑命令、做编辑 |
| `/` | 命令自动补全菜单——输入即过滤，↑↓ 选择 |
-| `/resume [id]` | 切换会话——不带参数进入交互式选择器（↑↓/j/k 导航） |
-| `/sessions` | 浏览所有已保存的会话（↑↓/j/k 导航） |
+| `/resume [id]` | 切换会话——不带参数进入交互式选择器（↑↓/j/k） |
+| `/sessions` | 浏览所有已保存的会话（↑↓/j/k） |
| `/clear` | 清空当前会话——重新开始 |
| `/compact` | 压缩长对话以节省上下文 |
| `/memory` | 浏览项目和会话记忆 |
| `/rename [标题]` | 给当前会话起个好记的名字 |
| `/model [name]` | 切换 LLM 模型——不带参数进入交互式选择器 |
-| `/rant <反馈> [@]` | 吐槽、建议、夸奖——演化系统会听，`@project` 定向到特定项目 |
+| `/rant <反馈> [@]` | 吐槽、建议、夸奖——演化系统会听 |
| `/help` | 查看所有键盘快捷键和命令帮助 |
-| `/image` | 从剪贴板插入图片到输入框（支持多张，逐个 Enter 插入） |
+| `/image` | 从剪贴板插入图片到输入框 |
| `/delete [id]` | 删除会话——不带参数进入交互式选择器 |
-| `/rewind` | 回退对话——选择历史消息点，截断后续内容 |
-| `/trigger` | 触发演化任务——交互式选择器（↑↓/j/k） |
-| `/skills` | 列出已加载技能（含 skill-catalog）；`/skills available`=可安装目录，`/skills install `=安装，`/skills update`=刷新受管技能 |
+| `/rewind` | 回退对话到历史某个节点 |
+| `/trigger` | 触发演化任务——交互式选择器 |
+| `/skills` | 列出已加载技能；`/skills available\|install\|update` |
| `/version` | 显示 EMRG 版本和实例信息 |
| `Esc` | 中断正在运行的响应 |
| `Ctrl+C` / `exit` | 退出 |
---
-## 🏗️ 架构
-
-```
-┌─────────────┐ WebSocket (ws://) ┌──────────────┐
-│ emrg TUI │ ◄─────────────────────► │ emrgd │
-│ (客户端) │ TCP loopback + 首帧认证 │ (守护进程) │
-│ │ token (emrgd.port) │ │
-│ • 聊天 │ │ • LLM 循环 │
-│ • Markdown │ │ • 工具执行 │
-│ • 工具卡片 │ │ • 演化引擎 │
-│ • 自动补全 │ │ • 会话管理 │
-└─────────────┘ └──────────────┘
-```
-
-- **`emrgd`** — 守护进程：运行 LLM 工具调用循环，管理会话，驱动演化
-- **`emrg`** — 你的终端：流式 Markdown、命令自动补全、会话浏览器
-- **Skills** — 动态加载模块（浏览器控制、安装器等）
-- **Memory** — YAML frontmatter + Markdown 文件，自动索引，可搜索
-
----
-
## 📊 与竞品对比
| | Claude Code | Codex | **EMRG** |
@@ -257,71 +117,34 @@ vision = true
| 工具调用 (bash, read, write, edit, glob, grep) | ✅ | ✅ | ✅ |
| 会话记忆与上下文 | ✅ | ✅ | ✅ |
| `/` 命令自动补全 | ✅ | ✅ | ✅ |
-| 方向键会话选择器 | ✅ | ✅ | ✅ |
| ESC 中断 | ✅ | ✅ | ✅ |
| **自主进化** | ❌ | ❌ | ✅ *全自动* |
| **后台守护进程** | ❌ | ❌ | ✅ *持久运行* |
-| **吐槽驱动自我改进** | ❌ | ❌ | ✅ */rant → 演化 → PR* |
+| **吐槽驱动自我改进** | ❌ | ❌ | ✅ */rant → PR* |
| **开源** | ❌ | ❌ | ✅ *MIT* |
EMRG 不只是追赶——它自己追上来。
---
-## 🧪 开发
-
-```bash
-git clone https://github.com/argszero/emrg.git
-cd emrg
-uv sync # 安装依赖
-uv run pytest tests/ -v # 跑测试（当前 681 项）
-uv run python -m emrg # 启动 TUI
-# CI 含 actionlint workflow 门禁（#444）：workflow 解析错误在 PR 即失败
-
-# 可选：Electron GUI（非开发者主入口，Phase 3）
-cd emrg/gui
-npm ci # 安装依赖（生产模式可 --omit=dev）
-npm start # 启动 GUI（自动拉起 daemon）
-npm test # 运行 Node 测试（178 项：43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state；集成测试在 CI 跑，本地可 npm run test:integration）
-```
-
-CI 通过 GitHub Actions 自动运行测试并检查冲突标记（`.github/workflows/test.yml`）。
-
-### 项目结构
-
-```
-emrg/
-├── emrg/ # 核心包
-│ ├── server/ # 守护进程——LLM 循环、工具执行、演化引擎
-│ ├── client/ # TUI——基于 python-tui 的交互式聊天
-│ ├── gui/ # Electron GUI（非开发者主入口，Phase 3）
-│ ├── tools/ # bash, read, write, edit, glob, grep
-│ ├── skills/ # 动态加载模块
-│ └── __main__.py # CLI 入口
-├── tests/
-├── .github/workflows/ # CI 流水线（pytest + 冲突标记检查）
-├── MANIFESTO.md # 设计宪章
-└── pyproject.toml
-```
-
----
-
## ❓ 常见问题
**这是真的吗——它真的会改自己的代码？**
真的。演化循环读取演化提示词，回顾 rant + issue + 竞品工具，修改源码，跑测试，然后提交 PR。如果测试失败，自动回滚。
**它会把自己搞崩吗？**
-每次改动都会通过 `pytest` 和 import 检查验证后才提交。失败的改动会被丢弃。最坏的情况就是回滚。
-
-**支持哪些 LLM？**
-任何兼容 OpenAI API 的模型。已测试 DeepSeek 和 OpenAI。支持 Anthropic（通过代理）、Ollama、vLLM 及其他本地模型。
+每次改动都会通过 `pytest` 和 import 检查验证后才提交。失败的改动会被丢弃；最坏的情况就是回滚。
**和 Claude Code 或 Codex 有什么不同？**
-它们是产品。EMRG 是一个关于*闭环进化*的实验——AI 改进 AI。此外：完全开源、无厂商锁定、你掌控自己的数据。
+它们是产品。EMRG 是一个关于*闭环进化*的实验——AI 改进 AI。完全开源，无厂商锁定。
+
+---
+
+## 🧪 开发
+
+贡献指南、源码安装、架构、详细 FAQ → [DEVELOPMENT.md](DEVELOPMENT.md)。
-**为什么 Windows 安装包会提示"未知发布者"？**
-Windows 安装包未做 Authenticode 签名（该证书需付费申请，暂不采购），因此 SmartScreen 会显示"发布者：未知"并可能阻止运行。这是微软对新发布/未签名软件的通用安全提醒，**不代表文件有问题**——EMRG 完全开源（MIT），源码可审计。放行：浏览器提示点"保留"；运行提示点"更多信息 → 仍要运行"；或右键 exe → 属性 → 勾选"解除锁定"。macOS 安装包已签名+公证（v0.2.7+），无此问题。
+快速检查：`uv run pytest tests/ -v`（当前 681 项）· `cd emrg/gui && npm test`（178 项：43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state）
---
diff --git a/README.md b/README.md
index 666e849..c15ca52 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@
**What if your coding assistant got better every time you used it?**
-EMRG is an experiment in *autonomous self-improvement*. It's an AI agent that helps you code — reading files, running commands, making edits — but the key difference is: **every `/rant` you send drives it to improve itself**. Tell it what bothers you, and the next evolution cycle writes code to fix it. Combined with GitHub community activity and competitor tracking, EMRG evolves continuously in the background, getting better the more you use it. All open source, all transparent.
+EMRG is an experiment in *autonomous self-improvement*: an AI agent that helps you code — reading files, running commands, making edits — and **every `/rant` you send drives it to improve itself**. Tell it what bothers you, and the next evolution cycle writes the fix and ships it. Fully open source, fully transparent.
> *"EMRG is an experiment in self-evolving AI agent architecture."* — [MANIFESTO](MANIFESTO.md)
@@ -28,22 +28,20 @@ EMRG is an experiment in *autonomous self-improvement*. It's an AI agent that he
## ✨ Why you'll love it
-**The one-line pitch**: EMRG is the only coding agent that **improves itself from your feedback** — rant about what bothers you, and the next evolution cycle writes the fix and ships it. Chat, tools, and memory are what you'd expect; the self-improvement loop is what you won't find anywhere else.
+**The one-line pitch**: EMRG is the only coding agent that **improves itself from your feedback** — rant about what bothers you, and the next evolution cycle writes the fix and ships it.
-| What | What it means |
+| What | Why it's different |
|---|---|
-| 🔄 **Gets better on its own** | **The core feature.** Background evolution cycles turn your `/rant`s, GitHub issues, and competitor updates into real improvements — analyzed, coded, tested, PR'd, merged. Self-healing workspace: packaged installs clone the repo on demand and bootstrap projects/tasks automatically |
-| 🖥️ **Electron GUI (main entry)** | Install & go: first-run wizard configures your API key; all 15 slash commands work in the GUI (`/rant` evolution dialog, `/memory` browser…); WorkBuddy-inspired **results panel**, **Ask/Auto** modes, **visible self-evolution** (growth card + toasts). GUI configured = TUI ready |
-| 🧠 **Reads, writes, edits, runs** | Full tool-calling agent — bash, files, diffs, glob, grep |
-| 📝 **Never forgets** | Project memory + session memory + daily logs — context that persists |
-| ⚡ **Full-featured TUI + daemon** | Streaming markdown, `/` autocomplete, session picker, ESC interrupt, vim-friendly keys, parallel tool calls — on a persistent `emrgd` daemon you can reconnect to anytime |
-| 🌍 **100% open source** | MIT — no walled garden, no vendor lock-in. Internationalized: English default, Chinese version available |
+| 🔄 **Gets better on its own** | **The core feature.** Your `/rant`s, GitHub issues, and competitor updates become real improvements — analyzed, coded, tested, PR'd, merged, unattended |
+| 🖥️ **Electron GUI (main entry)** | Install & go: first-run wizard, all slash commands, results panel, Ask/Auto modes, visible self-evolution. GUI configured = TUI ready |
+| ⚡ **Full-featured TUI + daemon** | Streaming markdown, `/` autocomplete, sessions, shortcuts — on a persistent `emrgd` daemon you can reconnect to anytime |
+| 🌍 **100% open source** | MIT — no walled garden, no vendor lock-in. English default, Chinese version available |
---
## 🔄 Rant-Driven Evolution (the core feature)
-EMRG isn't just a tool — it's a coding partner that **listens to your complaints and improves itself**. **Your rants are the primary driver of evolution.** Every `/rant` is read, analyzed, and turned into code improvements:
+EMRG isn't just a tool — it's a coding partner that **listens to your complaints and improves itself**:
```
📢 Your rants (/rant) ←── primary input
@@ -59,195 +57,58 @@ EMRG isn't just a tool — it's a coding partner that **listens to your complain
✅ Evolution log
```
-**Real example**: Someone ranted "TUI needs `/` autocomplete like Codex." Next evolution cycle, EMRG built it — complete with prefix filtering and arrow-key navigation. Merged. Deployed. Done. **What you rant about, it improves.**
-
-Runs fully unattended: `gh` auth auto-recovers from your git credentials, PR votes use the REST API, and packaged-install workspaces self-heal (clone on demand, auto-bootstrap projects/tasks). See [MANIFESTO.md](MANIFESTO.md) — EMRG's design charter on autonomous evolution.
+**Real example**: Someone ranted "TUI needs `/` autocomplete like Codex." The next evolution cycle built it — prefix filtering and arrow-key navigation, merged and deployed. **What you rant about, it improves.**
---
## 🚀 Quick Start
-### 📦 Download installer (recommended, Phase 4 one-click)
-
-Download the installer for your platform from [GitHub Releases](https://github.com/argszero/emrg/releases) and double-click:
-
-| Platform | Installer | Notes |
-|----------|-----------|-------|
-| macOS (Apple Silicon) | `EMRG--macos-arm64.pkg` | Double-click (user-level install, no admin password); GUI at `~/Applications/EMRG.app` |
-| macOS (Intel) | `EMRG--macos-x64.pkg` | Same |
-| Windows | `EMRG--windows-x64.exe` | Inno Setup, no UAC, Start-menu shortcut, PATH auto-registered (native TUI: run `emrg` directly in cmd/PowerShell) |
-| Linux | `EMRG--linux-x86_64.AppImage` | Self-extracts to `~/.emrg/install/` on first run |
-| Linux (ARM64) | `EMRG--linux-aarch64.AppImage` | Same |
-
-> **Windows SmartScreen notice**: The Windows installer is not Authenticode-signed (publisher shows "Unknown"), so SmartScreen may show "usually doesn't download" or "Windows protected your PC" on first download/run. This is a standard security prompt for unsigned software — it does **not** mean the file is bad (EMRG is fully open source and auditable). To proceed:
-> (1) Browser download prompt → click **Keep** (or ⋯ → Keep)
-> (2) If double-clicking shows "Windows protected your PC" → click **More info** → click **Run anyway**
-> (3) Or right-click the exe → Properties → check **Unblock** (if present) → OK → double-click to run
-
-The installer bundles a full runtime (standalone Python 3.13 + deps + git + gh + GUI) — **zero prerequisites on a clean machine (no python/uv/git/gh/node)**, 100% offline install. After install:
-
-**Three steps to start:**
-1. Launch **EMRG** (GUI) from Launchpad / Start menu
-2. First-run wizard configures **API Key / model**
-3. Start chatting — **TUI is ready too** (run `emrg` in a new terminal)
-
-> **Uninstall**: macOS run "卸载 EMRG.app" (uninstall app); Windows uninstall from Control Panel; Linux run `~/.emrg/install/bin/emrg-uninstall` (or delete the AppImage + symlink). Uninstall preserves non-EMRG user files in `~/.emrg`, and writes a termination report + data snapshot.
->
-> **macOS signing & notarization**: since v0.2.7, macOS packages are signed with Developer ID dual-cert and notarized by Apple (zero Gatekeeper dialogs — double-click to install directly). Only for unsigned builds (e.g. self-built old versions) is right-click → Open needed on first launch.
-
-### 🍎 macOS (source install)
-
-**Install:**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**Uninstall:**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
-
-### 🐧 Linux (source install)
-
-**Install:**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**Uninstall:**
-
-```bash
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
-
-### 🪟 Windows (WSL2, source install)
-
-**Install:**
-
-```powershell
-# Install WSL2 (skip if already installed)
-wsl --install
-
-# Enter WSL, then install
-wsl
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash
-```
-
-**Uninstall:**
-
-```bash
-# Run inside WSL
-curl -sSL https://raw.githubusercontent.com/argszero/emrg/master/install.sh | bash -s -- purge
-```
-
-> Source-install prerequisites (install.sh auto-detects and prompts): git, python 3.11+, uv. gh CLI recommended. For native Windows (non-WSL), use the installer above.
-
-### 🖥️ First-time config (GUI first)
+### 📦 Download the installer (recommended)
-After installing, **open the GUI to configure**:
+Download from [GitHub Releases](https://github.com/argszero/emrg/releases) and double-click — the installer bundles everything (Python 3.13 + git + gh + GUI), **zero prerequisites, offline install**:
-1. **macOS**: Launchpad → **EMRG**; **Windows**: Start menu → **EMRG**
-2. The first-run wizard walks you through **API Key / base URL / model** (also editable anytime in Settings ⚙)
-3. Save and start chatting — **config is written to `~/.emrg/config.toml`, shared by GUI and TUI**
+| Platform | Installer |
+|----------|-----------|
+| macOS | `EMRG--macos-arm64.pkg` / `-x64.pkg` (user-level, no admin password) |
+| Windows | `EMRG--windows-x64.exe` (no UAC, PATH auto-registered) |
+| Linux | `EMRG--linux-x86_64.AppImage` / `-aarch64.AppImage` |
-> 💡 **GUI configured = TUI ready**: the installer bundles a full TUI. Config saved in the GUI (API key/model/workdir) goes to `~/.emrg/config.toml`, so running `emrg` in a new terminal enters the TUI with no re-configuration. Since v0.2.8 the GUI supports **all 15 slash commands** — type `/` in the input box for an autocomplete menu (same as the TUI).
+> **Windows SmartScreen notice**: the installer isn't Authenticode-signed — if SmartScreen prompts, click **Keep** / **More info → Run anyway**. EMRG is fully open source and auditable.
-### ⌨️ Using the TUI
-
-```bash
-emrg
-```
+**First time**: launch **EMRG** → the wizard sets your **API key / model** → start chatting. The TUI is ready too: run `emrg` in any terminal (config is shared).
-Type `/help` for all commands, or just start talking — EMRG reads files, runs commands, and makes edits.
-
-### 🔧 Advanced config (optional)
-
-> The GUI rewrites config on save and drops comments — advanced users can edit `~/.emrg/config.toml` directly (no manual editing needed for first-time setup; the GUI wizard handles it).
-
-`~/.emrg/config.toml` template example (the GUI generates equivalent content on save):
-
-```toml
-[llm]
-base_url = "https://api.deepseek.com"
-api_key = "sk-..."
-model = "deepseek-chat"
-max_tokens = 8192
-temperature = 0.7
-context_window = 131072
-auto_compact_threshold = 0.0
-# vision: whether the model supports the OpenAI vision API (image_url). Keep false for
-# non-vision models (e.g. DeepSeek) — pasted images degrade to text placeholders to avoid API errors.
-vision = false
-
-# Multi-model support — use /model to switch between models
-[[llm.models]]
-name = "deepseek-v3"
-model = "deepseek-chat"
-context_window = 131072
-vision = false
-
-[[llm.models]]
-name = "gpt-4o"
-model = "gpt-4o"
-context_window = 128000
-vision = true
-```
+> Prefer building from source, or need advanced config / architecture / contributing docs? → [DEVELOPMENT.md](DEVELOPMENT.md)
---
## 🎮 Commands
-> Since v0.2.8, **all commands work in both the GUI and the TUI**. In the GUI, type `/` in the input box for an autocomplete menu; in the TUI, `/help` lists everything.
+> All commands work in both the GUI (type `/` for autocomplete) and the TUI (`/help` lists everything).
| Command | What it does |
|---|---|
| **Just type** | Ask EMRG anything — it reads files, runs commands, makes edits |
| `/` | Autocomplete menu — type to filter, ↑↓ to select |
-| `/resume [id]` | Switch sessions — no args for interactive picker (↑↓/j/k to navigate) |
-| `/sessions` | Browse all saved sessions (↑↓/j/k to navigate) |
+| `/resume [id]` | Switch sessions — no args for interactive picker (↑↓/j/k) |
+| `/sessions` | Browse all saved sessions (↑↓/j/k) |
| `/clear` | Clear current session — start fresh |
| `/compact` | Compress long conversations to save context |
| `/memory` | Browse project & session memories |
| `/rename [title]` | Give your session a memorable name |
| `/model [name]` | Switch LLM model — no args for interactive picker |
-| `/rant [@]` | Complain, suggest, praise — evolution listens; `@project` targets a specific project |
+| `/rant [@]` | Complain, suggest, praise — evolution listens |
| `/help` | Show keyboard shortcuts and command help |
-| `/image` | Insert clipboard image into the input field (multiple supported, one per Enter) |
+| `/image` | Insert clipboard image into the input field |
| `/delete [id]` | Delete a session — no args for interactive picker |
-| `/rewind` | Rewind conversation — pick a history point and truncate after it |
-| `/trigger` | Trigger an evolution task — interactive picker (↑↓/j/k) |
-| `/skills` | List loaded skills (incl. skill-catalog); `/skills available` = installable catalog, `/skills install ` = install, `/skills update` = refresh managed skills |
+| `/rewind` | Rewind conversation to a history point |
+| `/trigger` | Trigger an evolution task — interactive picker |
+| `/skills` | List loaded skills; `/skills available|install|update` |
| `/version` | Show EMRG version and instance info |
| `Esc` | Interrupt a running response mid-stream |
| `Ctrl+C` / `exit` | Quit |
---
-## 🏗️ Architecture
-
-```
-┌─────────────┐ WebSocket (ws://) ┌──────────────┐
-│ emrg TUI │ ◄─────────────────────► │ emrgd │
-│ (client) │ TCP loopback + auth │ (daemon) │
-│ │ token (emrgd.port) │ │
-│ │ │ │
-│ • Chat │ │ • LLM loop │
-│ • Markdown │ │ • Tools │
-│ • ToolCards│ │ • Evolution │
-│ • Autocomplete │ • Sessions │
-└─────────────┘ └──────────────┘
-```
-
-- **`emrgd`** — The daemon: runs the LLM tool-calling loop, manages sessions, drives evolution
-- **`emrg`** — Your terminal: streaming markdown, command autocomplete, session browser
-- **Skills** — Dynamically loaded modules (browser harness, installers, etc.)
-- **Memory** — YAML frontmatter + Markdown files, auto-indexed, searchable
-
----
-
## 📊 vs. the competition
| | Claude Code | Codex | **EMRG** |
@@ -256,7 +117,6 @@ vision = true
| Tool-calling (bash, read, write, edit, glob, grep) | ✅ | ✅ | ✅ |
| Session memory & context | ✅ | ✅ | ✅ |
| `/` command autocomplete | ✅ | ✅ | ✅ |
-| Arrow-key session picker | ✅ | ✅ | ✅ |
| ESC interrupt | ✅ | ✅ | ✅ |
| **Self-evolution** | ❌ | ❌ | ✅ *autonomous* |
| **Background daemon** | ❌ | ❌ | ✅ *persistent* |
@@ -267,60 +127,24 @@ EMRG doesn't just keep up — it catches up on its own.
---
-## 🧪 Development
-
-```bash
-git clone https://github.com/argszero/emrg.git
-cd emrg
-uv sync # install deps
-uv run pytest tests/ -v # run tests (currently 681 items)
-uv run python -m emrg # launch TUI
-# CI includes actionlint workflow gate (#444): workflow parse errors fail PR CI
-
-# Optional: Electron GUI (non-developer entry point, Phase 3)
-cd emrg/gui
-npm ci # install deps (production: --omit=dev)
-npm start # launch GUI (auto-starts daemon)
-npm test # run Node tests (178: 43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state; integration runs in CI, local: npm run test:integration)
-```
-
-CI runs tests and checks for conflict markers automatically via GitHub Actions (`.github/workflows/test.yml`).
-
-### Project structure
-
-```
-emrg/
-├── emrg/ # Core package
-│ ├── server/ # Daemon — LLM loop, tool execution, evolution
-│ ├── client/ # TUI — python-tui based interactive chat
-│ ├── gui/ # Electron GUI (non-developer entry point, Phase 3)
-│ ├── tools/ # bash, read, write, edit, glob, grep
-│ ├── skills/ # Dynamically loadable modules
-│ └── __main__.py # CLI entry point
-├── tests/
-├── .github/workflows/ # CI pipeline (pytest + conflict marker check)
-├── MANIFESTO.md # Design constitution
-└── pyproject.toml
-```
-
----
-
## ❓ FAQ
**Is this real — does it actually modify its own code?**
Yes. The evolution cycle reads the evolution prompt, reviews rants + issues + competitor tools, makes source changes, runs tests, and submits a PR. If tests fail, it rolls back.
**Can it break itself?**
-Every change is validated by `pytest` and an import check before commit. Failed changes are discarded. The worst case is a rollback.
-
-**What LLMs work with it?**
-Any OpenAI-compatible API. Tested with DeepSeek and OpenAI. Works with Anthropic (via proxy), Ollama, vLLM, and other local models.
+Every change is validated by `pytest` and an import check before commit. Failed changes are discarded; the worst case is a rollback.
**How is this different from Claude Code or Codex?**
-They're products. EMRG is an experiment in *closing the loop* — the AI improves the AI. Also: fully open source, no vendor lock-in, and you control your data.
+They're products. EMRG is an experiment in *closing the loop* — the AI improves the AI. Fully open source, no vendor lock-in.
+
+---
+
+## 🧪 Development
+
+Contributing, source installs, architecture, and the full FAQ → [DEVELOPMENT.md](DEVELOPMENT.md).
-**Why does the Windows installer show "Unknown publisher"?**
-The Windows installer is not Authenticode-signed (that certificate costs money to obtain and is not procured yet), so SmartScreen shows "Publisher: Unknown" and may block the run. This is a standard Microsoft security prompt for newly released/unsigned software — it does **not** mean the file is bad: EMRG is fully open source (MIT) and auditable. To proceed: click "Keep" on the browser prompt; click "More info → Run anyway" on the run prompt; or right-click the exe → Properties → check "Unblock". The macOS installer is signed + notarized (v0.2.7+) and has no such prompt.
+Quick checks: `uv run pytest tests/ -v` (currently 681 items) · `cd emrg/gui && npm test` (178: 43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state)
---