diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..22159f6
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,224 @@
+# 架构说明
+
+本文档解释当前代码中真实存在的 `cc-slim` 架构。
+
+## 当前已实现
+
+### 1. 入口层
+
+`src/cc_slim/main.py` 提供单一 Typer 命令入口，支持：
+
+- 单次 prompt 执行
+- REPL 模式
+- 显式 `--workspace`
+- history 列表与 session resume
+- `--auto-approve` 启动模式
+
+REPL 本身刻意保持很小。slash command 会在普通 agent loop 之前先被拦截。
+
+当前代码里也明确区分两个 root：
+
+- program root
+  - `cc-slim` 自己读取 `.cc-slim.toml` 的位置
+- workspace root
+  - 真正被工具、session、memory、权限与边界逻辑操作的项目目录
+
+### 2. 命令层
+
+`src/cc_slim/commands.py` 是一个很薄的 slash command 路由层。
+
+它负责处理：
+
+- session 命令
+- memory 命令
+- mode 命令
+- permission 命令
+
+它本身不负责模型推理逻辑，而是把动作委托给 store 或当前 `Agent`。
+
+### 3. 核心 Agent Loop
+
+`src/cc_slim/engine.py` 包含最小 harness 闭环：
+
+1. 把用户消息追加到内存 history
+2. 调模型
+3. 流式输出文本 chunk
+4. 如果模型请求工具，先做权限检查
+5. 执行工具
+6. 回填工具结果
+7. 循环，直到得到最终回答或达到最大轮数
+
+当前对外有两个主要入口：
+
+- `stream_reply()`
+  - 给 REPL 使用
+- `reply()`
+  - 兼容包装层，把流式文本拼成完整字符串
+
+### 4. Prompt 组装
+
+system prompt 的层次是刻意分开的：
+
+1. 内置 `system.md`
+2. runtime summary
+3. workspace `AGENTS.md`
+4. workspace `SKILLS/*.md`
+5. `Memory`
+
+每一层只负责自己的职责，不混用。
+
+### 5. 工具层
+
+`src/cc_slim/tools.py` 提供一个刻意收窄的工具面：
+
+- `Read`
+- `Glob`
+- `Grep`
+- `Write`
+- `Edit`
+- `Bash`
+
+设计重点是：工具都是简单的 string-in / string-out primitive。
+
+重要边界：
+
+- 文件类工具通过 `_safe_path()` 保持在 workspace 内
+- `Edit` 与 `Write` 都是整文件覆盖，不支持局部 patch
+- `Grep` 是普通文本搜索，不是 regex 引擎
+- `Bash` 可用，但受 mode、permission 与 workspace boundary 控制
+
+### 6. Session 层
+
+`src/cc_slim/session.py` 保存原始对话历史。
+
+Session 的职责是：
+
+- 保存可恢复的消息历史
+- 支持 `--history` 与 `--resume`
+- 保存标题、时间戳等元信息
+
+Session 刻意保持为“原始历史”，而不是长期知识。
+
+### 7. Memory 层
+
+`src/cc_slim/memory.py` 以 Markdown 形式保存结构化长期知识。
+
+当前 sections：
+
+- `User Memory`
+- `Project Memory`
+- `Constraints`
+- `Consolidated Facts`
+- `Scratch Notes`
+
+Memory 不是 transcript。它是一个能跨 session 持续带入 prompt 的长期知识层。
+
+### 8. Dream 层
+
+Dream v1 当前以手动命令形式存在：
+
+- `/dream`
+
+它只使用当前已加载的 session，调用模型提炼长期有价值的信息，把结果写回结构化 Memory，并刷新内存中的 system prompt。
+
+这很关键，因为 Dream 不是 summary。summary 压缩对话内容，而 Dream 要保留的是未来仍值得记住的知识。
+
+### 9. Mode、Permission、Boundary
+
+当前工具执行受三层控制：
+
+- mode
+- permission approval
+- workspace boundary
+
+优先级关系很重要：
+
+1. 先做硬阻止
+2. 再进入审批
+3. 最后才执行工具
+
+当前硬阻止包括：
+
+- `plan` 模式下阻止 `Write`、`Edit`、`Bash`
+- 明显指向 workspace 外路径的 `Bash`
+
+只有通过硬阻止检查后，才会进入普通 y/n 审批流程。
+
+## 为什么 Memory 不是 Session
+
+这是整个项目最重要的设计点之一。
+
+Session：
+
+- 原始对话和工具轨迹
+- 可恢复
+- 天然带噪声
+- 适合做连续性上下文
+
+Memory：
+
+- 结构化长期知识
+- 不是“发生过”就保留，而是“值得以后继续记住”才保留
+- 规模足够小，可以持续注入 prompt
+
+如果把 Session 和 Memory 混成一个概念，整个 harness 会同时失去清晰性和可控性。
+
+## 为什么 Dream 不是 Summary
+
+Summary 回答的问题是：
+
+- 这次对话发生了什么？
+
+Dream 回答的问题是：
+
+- 这次对话里有哪些内容以后仍值得记住？
+
+所以当前 Dream v1：
+
+- 不做 multi-session 汇总
+- 不改写 `AGENTS.md`
+- 只更新结构化 memory sections
+- 保留 `Scratch Notes`
+
+它是一个很小的 consolidation pass，而不是 transcript reducer。
+
+## 为什么 AGENTS.md 不再承担系统人设
+
+`system.md` 负责内置 harness 行为。
+
+workspace `AGENTS.md` 负责项目 / 工作区规则。
+
+这样可以把这几类东西拆开：
+
+- 程序内置身份和行为
+- 当前项目规则
+- 长期用户 / 项目知识
+
+如果不拆开，prompt assembly 会越来越难理解，也更难继续演化。
+
+## 当前明确未做的内容
+
+当前架构没有实现：
+
+- sandbox
+- sub-agent orchestration
+- 向量记忆检索
+- 自动 dream 或定时 consolidation
+- multi-session dream
+- 复杂权限策略
+- patch 级编辑工具
+- skill execution isolation
+
+这些都是刻意保留在范围之外的内容。
+
+## 未来可选增强
+
+如果项目以后继续扩展，合理的可选方向包括：
+
+- 更稳健的 `Bash` 风险检测，而不是完整 shell 解析
+- memory section 质量约束
+- 针对选定 session 的 dream
+- 更明确的配置来源 / 生效状态展示
+- 更细一点的 streaming 边界测试
+
+这些是可选增强，不是当前已经实现的能力。
diff --git a/README.md b/README.md
index e69de29..eef4510 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,302 @@
+# cc-slim
+
+`cc-slim` is a deliberately small coding harness in the style of Claude Code / Codex.
+
+It focuses on the core local loop only:
+
+- REPL / CLI entry
+- model-driven agentic loop
+- streamed text output
+- small tool surface
+- session persistence
+- structured project memory
+- manual `/dream` consolidation
+- mode / permission / workspace control
+
+The project is intentionally not a full platform. It is built to be readable, easy to explain in an interview, and small enough to reason about end to end.
+
+## What It Actually Implements
+
+- Agentic loop with model -> tool call -> tool execution -> tool result -> final answer
+- Streaming REPL output with tool call / tool result status lines
+- Built-in tools:
+  - `Read`
+  - `Glob`
+  - `Grep`
+  - `Write`
+  - `Edit`
+  - `Bash`
+- Slash command router for session, memory, mode, and permissions
+- Session persistence with history / resume
+- Structured Memory v2 stored as Markdown
+- Manual Dream v1 to consolidate the current session into Memory
+- Permission gate for `Write`, `Edit`, and `Bash`
+- `build` / `plan` mode
+- workspace boundary as the default operating scope
+- explicit `--workspace` support
+
+## What It Does Not Implement
+
+- sandboxing
+- sub-agents or coordinator routing
+- vector database or Mem0 backend
+- automatic background dream / consolidation
+- multi-session dream
+- complex skill execution framework
+- fine-grained path allowlists / denylists
+
+Those are intentional omissions, not missing TODOs.
+
+## Installation
+
+```bash
+uv sync
+```
+
+Set credentials through environment variables or `.cc-slim.toml` in the `cc-slim` program directory.
+
+`--workspace` only changes the target project. It does not change where `cc-slim` reads its own config.
+
+## Quick Start
+
+Run inside the target project directory:
+
+```bash
+uv run cc-slim
+```
+
+Run from elsewhere but target a workspace explicitly:
+
+```bash
+uv run cc-slim --workspace E:\04test
+```
+
+Single-shot prompt:
+
+```bash
+uv run cc-slim "what does this repo do?"
+```
+
+List history for the current workspace:
+
+```bash
+uv run cc-slim --history
+```
+
+Resume a prior session:
+
+```bash
+uv run cc-slim --resume 1
+```
+
+Skip confirmation for high-risk tools:
+
+```bash
+uv run cc-slim --auto-approve
+```
+
+## REPL Commands
+
+Session:
+
+- `/history`
+- `/resume <id-or-index>`
+- `/new`
+- `/clear` as an alias for `/new`
+
+Memory:
+
+- `/memory`
+- `/remember <text>`
+- `/dream`
+
+Mode:
+
+- `/mode`
+- `/mode build`
+- `/mode plan`
+- `/build`
+- `/plan`
+
+Permissions:
+
+- `/permissions`
+- `/permissions auto-on`
+- `/permissions auto-off`
+
+## Runtime Model
+
+There are two roots in the current code:
+
+- program root
+  - the `cc-slim` repository itself
+  - used for reading `.cc-slim.toml`
+- workspace root
+  - the project being operated on
+  - used for `AGENTS.md`, `SKILLS`, `Session`, `Memory`, permissions, and boundary checks
+
+The system prompt is assembled in this order:
+
+1. `src/cc_slim/system.md`
+2. runtime summary
+3. workspace `AGENTS.md`
+4. workspace `SKILLS/*.md`
+5. structured `Memory`
+
+This keeps responsibilities separate:
+
+- `system.md`
+  - built-in harness behavior
+- workspace `AGENTS.md`
+  - workspace / project rules
+- `Memory`
+  - long-lived project knowledge and user preferences
+- `Session`
+  - raw conversation history
+- `Dream`
+  - manual consolidation from the current session into Memory
+
+## Mermaid Architecture
+
+```mermaid
+flowchart TD
+    U[User] --> CLI[CLI / REPL in main.py]
+    CLI --> CMD[Slash command router in commands.py]
+    CLI --> LOOP[Agent loop in engine.py]
+
+    CMD --> SESS[SessionStore]
+    CMD --> MEM[MemoryStore]
+    CMD --> MODE[ModeState]
+    CMD --> PERM[PermissionChecker]
+    CMD --> DREAM[/dream -> Agent.dream/]
+
+    SYS[system.md] --> PROMPT[Prompt Assembly]
+    RT[Runtime Summary] --> PROMPT
+    AG[workspace AGENTS.md] --> PROMPT
+    SK[workspace SKILLS/*.md] --> PROMPT
+    MEM --> PROMPT
+
+    PROMPT --> LOOP
+    SESS --> LOOP
+
+    LOOP --> TOOLS[Read / Glob / Grep / Write / Edit / Bash]
+    PERM --> TOOLS
+    MODE --> PERM
+    BOUNDARY[Workspace Boundary] --> PERM
+
+    LOOP --> STREAM[Streaming text + tool events]
+    STREAM --> CLI
+
+    DREAM --> MEM
+    SESS --> CMD
+```
+
+## Tools
+
+Current tool boundaries are intentionally narrow:
+
+- `Read`
+  - reads a text file inside the workspace
+- `Glob`
+  - matches paths inside the workspace
+- `Grep`
+  - plain-text contains search inside the workspace
+  - not regex-based
+  - returns up to 20 matches
+- `Write`
+  - create or overwrite a full file
+- `Edit`
+  - overwrite an existing file with full new content
+- `Bash`
+  - runs a shell command with the workspace as `cwd`
+
+There is no partial-edit patch tool, no AST manipulation, and no shell sandbox.
+
+## Modes, Permissions, and Boundary Control
+
+`build` mode is the normal execution mode.
+
+`plan` mode is read-only in practice:
+
+- allowed by default:
+  - `Read`
+  - `Glob`
+  - `Grep`
+- hard-blocked:
+  - `Write`
+  - `Edit`
+  - `Bash`
+
+Permission behavior:
+
+- `Read`, `Glob`, `Grep` are auto-allowed
+- `Write`, `Edit`, `Bash` require confirmation unless `--auto-approve` or `/permissions auto-on` is enabled
+- hard boundaries are checked before approval:
+  - `plan` mode restrictions
+  - obvious workspace-external `Bash` targets
+
+## Session, Memory, Dream
+
+Session storage:
+
+- stored under `~/.config/cc-slim/sessions/<workspace>/`
+- message history in `.jsonl`
+- metadata in `.meta.json`
+
+Memory storage:
+
+- stored under `~/.config/cc-slim/memory/<workspace>/MEMORY.md`
+- structured sections:
+  - `User Memory`
+  - `Project Memory`
+  - `Constraints`
+  - `Consolidated Facts`
+  - `Scratch Notes`
+
+`/remember`:
+
+- appends raw notes into `Scratch Notes`
+
+`/dream`:
+
+- uses only the currently loaded session
+- asks the model to extract durable information
+- updates structured Memory sections
+- keeps `Scratch Notes` intact
+
+This is consolidation, not chat summary.
+
+## Why This Project Is Intentionally Small
+
+This repository is meant to demonstrate the core harness mechanics without hiding them behind infrastructure.
+
+It intentionally does not include:
+
+- sandbox
+  - because the project is about control flow and boundary handling, not process isolation
+- sub-agent / coordinator orchestration
+  - because a single readable loop is easier to explain and verify
+- vector DB / Mem0 backend
+  - because Memory here is file-based and explicit by design
+- automatic background dream
+  - because manual consolidation makes the memory boundary easier to reason about
+- complex skill runtime
+  - because workspace `SKILLS/*.md` is enough to show prompt layering without building a plugin platform
+
+The result is smaller than production systems, but much easier to inspect, demo, and discuss.
+
+## Testing
+
+Run the current test suite:
+
+```bash
+uv run pytest -q
+```
+
+Current tests cover:
+
+- config resolution
+- tool primitives
+- structured memory behavior
+- dream updates
+- prompt assembly order
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..bd8f3d0
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,311 @@
+# cc-slim
+
+`cc-slim` 是一个刻意保持极简的 coding harness，风格接近 Claude Code / Codex。
+
+它只聚焦本地 coding agent 的最小核心闭环：
+
+- CLI / REPL 入口
+- 模型驱动的 agentic loop
+- 流式文本输出
+- 小而清晰的工具面
+- session 持久化
+- 结构化长期记忆
+- 手动 `/dream` consolidation
+- mode / permission / workspace 控制面
+
+这个项目不是一个“大而全的平台”。它的目标是：
+
+- 可读
+- 可讲解
+- 适合写进简历
+- 足够小，能从头到尾讲清楚
+
+## 当前真实已实现的能力
+
+- 模型 -> 工具调用 -> 工具执行 -> 结果回填 -> 最终回答 的 agentic loop
+- 带工具状态提示的 streaming REPL
+- 内置工具：
+  - `Read`
+  - `Glob`
+  - `Grep`
+  - `Write`
+  - `Edit`
+  - `Bash`
+- 用于 session / memory / mode / permission 的 slash command 路由
+- session 持久化、history、resume
+- 基于 Markdown 的结构化 Memory v2
+- 手动 `/dream`，把当前 session 提炼进 Memory
+- `Write` / `Edit` / `Bash` 的 permission gate
+- `build` / `plan` 两种模式
+- 以 workspace 为默认边界
+- 显式 `--workspace` 支持
+
+## 当前明确没有实现的内容
+
+- sandbox
+- sub-agent / coordinator
+- 向量数据库或 Mem0 backend
+- 自动后台 dream / consolidation
+- multi-session dream
+- 复杂技能执行框架
+- 细粒度路径白名单 / 黑名单
+
+这些是刻意不做的取舍，不是“以后补完才算完整”。
+
+## 安装
+
+```bash
+uv sync
+```
+
+凭证可以通过环境变量提供，也可以通过 `cc-slim` 程序目录下的 `.cc-slim.toml` 提供。
+
+## 快速开始
+
+在目标项目目录中直接运行：
+
+```bash
+uv run cc-slim
+```
+
+从其他目录运行，但显式指定工作区：
+
+```bash
+uv run cc-slim --workspace E:\04test
+```
+
+单次提问：
+
+```bash
+uv run cc-slim "what does this repo do?"
+```
+
+查看当前 workspace 的历史 session：
+
+```bash
+uv run cc-slim --history
+```
+
+恢复历史 session：
+
+```bash
+uv run cc-slim --resume 1
+```
+
+跳过高风险工具确认：
+
+```bash
+uv run cc-slim --auto-approve
+```
+
+`--workspace` 只影响操作目标项目，不影响 `cc-slim` 自身配置的读取位置。
+
+## REPL 命令
+
+会话命令：
+
+- `/history`
+- `/resume <id-or-index>`
+- `/new`
+- `/clear`，作为 `/new` 的别名
+
+Memory 命令：
+
+- `/memory`
+- `/remember <text>`
+- `/dream`
+
+模式命令：
+
+- `/mode`
+- `/mode build`
+- `/mode plan`
+- `/build`
+- `/plan`
+
+权限命令：
+
+- `/permissions`
+- `/permissions auto-on`
+- `/permissions auto-off`
+
+## 运行时模型
+
+当前代码里实际上区分了两个 root：
+
+- program root
+  - `cc-slim` 自己的程序仓库
+  - 用于读取 `.cc-slim.toml`
+- workspace root
+  - 当前实际要操作的项目目录
+  - 用于 `AGENTS.md`、`SKILLS`、`Session`、`Memory`、权限与边界控制
+
+system prompt 的组装顺序是：
+
+1. `src/cc_slim/system.md`
+2. runtime summary
+3. workspace `AGENTS.md`
+4. workspace `SKILLS/*.md`
+5. 结构化 `Memory`
+
+这几层职责分别是：
+
+- `system.md`
+  - 程序内置的基础行为
+- workspace `AGENTS.md`
+  - 当前项目 / 工作区规则
+- `Memory`
+  - 长期项目知识与用户偏好
+- `Session`
+  - 原始对话历史
+- `Dream`
+  - 把当前 session 手动整理进 Memory
+
+## Mermaid 架构图
+
+```mermaid
+flowchart TD
+    U[User] --> CLI[CLI / REPL in main.py]
+    CLI --> CMD[Slash command router in commands.py]
+    CLI --> LOOP[Agent loop in engine.py]
+
+    CMD --> SESS[SessionStore]
+    CMD --> MEM[MemoryStore]
+    CMD --> MODE[ModeState]
+    CMD --> PERM[PermissionChecker]
+    CMD --> DREAM[/dream -> Agent.dream/]
+
+    SYS[system.md] --> PROMPT[Prompt Assembly]
+    RT[Runtime Summary] --> PROMPT
+    AG[workspace AGENTS.md] --> PROMPT
+    SK[workspace SKILLS/*.md] --> PROMPT
+    MEM --> PROMPT
+
+    PROMPT --> LOOP
+    SESS --> LOOP
+
+    LOOP --> TOOLS[Read / Glob / Grep / Write / Edit / Bash]
+    PERM --> TOOLS
+    MODE --> PERM
+    BOUNDARY[Workspace Boundary] --> PERM
+
+    LOOP --> STREAM[Streaming text + tool events]
+    STREAM --> CLI
+
+    DREAM --> MEM
+    SESS --> CMD
+```
+
+## 工具层
+
+当前工具边界是刻意收窄的：
+
+- `Read`
+  - 读取 workspace 内文本文件
+- `Glob`
+  - 在 workspace 内按路径模式查找文件
+- `Grep`
+  - 在 workspace 内做普通文本包含搜索
+  - 不是正则搜索
+  - 最多返回 20 条结果
+- `Write`
+  - 创建或覆盖完整文件
+- `Edit`
+  - 用完整新内容覆盖已有文件
+- `Bash`
+  - 以 workspace 为 `cwd` 执行 shell 命令
+
+当前没有：
+
+- patch 级局部编辑工具
+- AST 编辑
+- shell sandbox
+
+## 模式、权限与边界控制
+
+`build` 是正常执行模式。
+
+`plan` 在当前实现中是只读模式：
+
+- 默认允许：
+  - `Read`
+  - `Glob`
+  - `Grep`
+- 硬性阻止：
+  - `Write`
+  - `Edit`
+  - `Bash`
+
+权限行为：
+
+- `Read`、`Glob`、`Grep` 自动允许
+- `Write`、`Edit`、`Bash` 需要确认，除非使用 `--auto-approve` 或 `/permissions auto-on`
+- 硬边界优先于审批：
+  - `plan` 模式限制
+  - 明显指向 workspace 外路径的 `Bash`
+
+## Session、Memory、Dream
+
+Session：
+
+- 存在 `~/.config/cc-slim/sessions/<workspace>/`
+- 消息历史为 `.jsonl`
+- 元信息为 `.meta.json`
+
+Memory：
+
+- 存在 `~/.config/cc-slim/memory/<workspace>/MEMORY.md`
+- 当前结构化 sections 为：
+  - `User Memory`
+  - `Project Memory`
+  - `Constraints`
+  - `Consolidated Facts`
+  - `Scratch Notes`
+
+`/remember`：
+
+- 把原始笔记追加到 `Scratch Notes`
+
+`/dream`：
+
+- 只使用当前已加载的 session
+- 调模型提炼长期有效信息
+- 回写结构化 Memory sections
+- 保留 `Scratch Notes`
+
+它是 consolidation，不是聊天 summary。
+
+## Why this project is intentionally small
+
+这个仓库的目标是展示 harness 的核心机制，而不是用更多基础设施把问题“藏起来”。
+
+因此它刻意没有做：
+
+- sandbox
+  - 因为当前重点是控制流、权限和边界，而不是进程隔离
+- sub-agent / coordinator
+  - 因为单 agent 闭环更容易讲清楚，也更容易验证
+- vector DB / Mem0 backend
+  - 因为当前 Memory 刻意保持文件化、可读、可控
+- 自动后台 dream
+  - 因为手动 consolidation 更容易清楚地区分 Session 与 Memory
+- 复杂技能系统
+  - 因为 `SKILLS/*.md` 已足够展示 prompt layering，而不需要引入插件平台
+
+结果是它比生产系统小很多，但也更容易读、演示和讲解。
+
+## 测试
+
+运行测试：
+
+```bash
+uv run pytest -q
+```
+
+当前测试覆盖：
+
+- 配置解析
+- 工具原语
+- 结构化 memory 行为
+- dream 更新行为
+- prompt 分层顺序