diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e61210e
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,146 @@
+# Contributing to Yada
+
+Thanks for helping improve Yada. This guide covers local setup, validation, and
+the Git workflow expected for pull requests.
+
+Before changing behavior, read the [architecture](docs/dev/architecture.md).
+For failures and trace inspection, use the
+[debugging guide](docs/dev/debugging.md). User-facing commands belong in the
+[CLI reference](docs/cli-reference.md).
+
+## Development setup
+
+Fork `GenTang/Yada` on GitHub, then clone your fork and add the canonical
+repository as `upstream`:
+
+```bash
+git clone https://github.com/YOUR-USERNAME/Yada.git
+cd Yada
+git remote add upstream https://github.com/GenTang/Yada.git
+git remote -v
+
+uv sync --locked --dev
+```
+
+Create a feature branch from the latest `upstream/main`:
+
+```bash
+git fetch upstream
+git switch -c feature/short-description upstream/main
+```
+
+Keep unrelated changes in separate branches and pull requests. Do not commit
+generated workspaces, evaluation results, traces, virtual environments, caches,
+API keys, or other secrets.
+
+## Make and validate a change
+
+Run focused tests while developing, then run the full local CI suite before
+opening or updating a pull request:
+
+```bash
+uv run --frozen ruff check .
+uv run --frozen ruff format --check .
+uv run --frozen pytest tests/ -v
+```
+
+To apply Ruff formatting locally:
+
+```bash
+uv run --frozen ruff format .
+```
+
+CI runs lint, formatting, and tests on Python 3.11 and 3.12. If a behavior change
+cannot be covered by a deterministic offline test, explain why in the pull
+request and provide the smallest reproducible trace or benchmark case available.
+
+Documentation changes should keep `README.md` and `README-cn.md` structurally
+aligned. Never put a real API key or an unreviewed debug trace in an issue or PR.
+
+## Keep your branch current with rebase
+
+Yada uses a rebase workflow. Update your feature branch from `upstream/main`
+without creating merge commits:
+
+```bash
+git fetch upstream
+git rebase upstream/main
+```
+
+Do not use `git merge upstream/main` on a feature branch. A linear history keeps
+review and later bisection focused on the actual change.
+
+### Resolve rebase conflicts
+
+When Git stops on a conflict:
+
+```bash
+git status
+# Edit each conflicted file and remove conflict markers.
+git add path/to/resolved-file
+git rebase --continue
+```
+
+Repeat until the rebase finishes. To abandon the entire attempt and restore the
+branch to its pre-rebase state:
+
+```bash
+git rebase --abort
+```
+
+Use `git rebase --skip` only when the stopped commit is genuinely redundant; it
+drops that commit from the rewritten branch.
+
+## Clean up commits before the PR
+
+Use interactive rebase to reorder, reword, fix up, or squash noisy development
+commits into a small set of logical changes:
+
+```bash
+git fetch upstream
+git rebase -i upstream/main
+```
+
+Do not squash unrelated behavior, tests, and documentation merely to reach one
+commit. The goal is reviewable history, not a specific commit count.
+
+Then run the full validation suite again and push the branch:
+
+```bash
+git push -u origin feature/short-description
+```
+
+Open a pull request against `GenTang/Yada:main` and complete the repository's PR
+template with:
+
+- what changed and why;
+- the exact validation commands and results;
+- benchmark, token, latency, or trace impact, or `N/A` when not applicable.
+
+## Update a PR after review
+
+Make the requested changes, commit them, and rebase again before updating the
+remote branch:
+
+```bash
+git fetch upstream
+git rebase upstream/main
+uv run --frozen ruff check .
+uv run --frozen ruff format --check .
+uv run --frozen pytest tests/ -v
+git push --force-with-lease origin feature/short-description
+```
+
+Rebase rewrites commit IDs, so a normal push will be rejected. Use
+`--force-with-lease`, never plain `--force`: the lease refuses to overwrite
+remote work you have not seen.
+
+If another contributor also writes to your branch, coordinate before rebasing
+or force-pushing it.
+
+## Review scope
+
+A pull request is ready for review when it is focused, tested, documented, and
+rebased onto the current `upstream/main`. Maintainers may ask for additional
+benchmark evidence when a change affects prompts, tools, context, verification,
+or model-call behavior.
diff --git a/README-cn.md b/README-cn.md
new file mode 100644
index 0000000..72f2c70
--- /dev/null
+++ b/README-cn.md
@@ -0,0 +1,61 @@
+# Yada
+
+**Yet Another DeepSeek Agent** 是一个为 DeepSeek V4 构建的小型、可审计
+Coding Agent Harness。给它一个任务和一个 Git 仓库，Yada 会检查代码、应用经过
+校验的 Patch、运行验证，并记录完整执行轨迹。
+
+[English README](README.md)
+
+> 只想使用 Yada？直接阅读下面的**快速开始**。想贡献代码？请从
+> [CONTRIBUTING.md](CONTRIBUTING.md) 和[开发者文档](docs/dev/architecture.md)
+> 开始。
+
+Yada 目前处于 Alpha 阶段。仓库已经测试本地 Agent 闭环，但尚未宣称任何对比
+评测结果。
+
+## 运行条件
+
+- Python 3.11+
+- Git
+- [uv](https://docs.astral.sh/uv/)（推荐）
+- DeepSeek API Key
+
+## 快速开始
+
+```bash
+git clone https://github.com/GenTang/Yada.git
+cd Yada
+uv sync --locked --dev
+
+export DEEPSEEK_API_KEY="sk-..."
+
+uv run yada "修复 parser 的边界问题，并运行相关测试" \
+  --workspace /path/to/repository
+```
+
+Yada 默认会在运行仓库命令前请求确认。只有在可信、一次性的隔离环境中才应使用
+`--yes`：
+
+```bash
+uv run yada --task-file issue.md --workspace /workspace --yes
+```
+
+## 运行时会发生什么
+
+Yada 会打印每轮 DeepSeek 调用和工具执行，最后报告任务是否通过验证门槛。默认
+Trace 保存在目标仓库的 `.yada/runs/` 目录下。
+
+仓库测试可以执行任意代码。Yada 提供 Guardrail，但不是完整的操作系统沙箱；
+处理陌生项目时请使用一次性 VM 或容器。
+
+## 更多文档
+
+- [配置](docs/configuration.md)：其他安装方式、API Key、模型参数、命令策略和
+  Trace Level。
+- [CLI 参考](docs/cli-reference.md)：`yada`、`yada eval` 和 `yada-trace`。
+- [贡献指南](CONTRIBUTING.md)：开发环境、验证命令和基于 Rebase 的 PR 流程。
+- [架构](docs/dev/architecture.md)：Agent 循环、工具、Patch 事务、评测边界与
+  安全不变量。
+- [调试](docs/dev/debugging.md)：测试、Trace 检查与可复现 Issue。
+
+Yada 使用 [MIT License](LICENSE)。
diff --git a/README.md b/README.md
index f1cfc3a..8f5802e 100644
--- a/README.md
+++ b/README.md
@@ -1,271 +1,64 @@
 # Yada
 
-**Yet Another DeepSeek Agent** — a small, auditable coding-agent harness built
-specifically for DeepSeek V4.
+**Yet Another DeepSeek Agent** is a small, auditable coding-agent harness built
+for DeepSeek V4. Give it a task and a Git repository; Yada inspects the code,
+applies a checked patch, runs verification, and records a trace of the run.
 
-[中文说明](README.zh-CN.md)
+[中文说明](README-cn.md)
 
-Yada is deliberately narrow: one agent loop, separate planning and execution
-boundaries, one append-only conversation, five tools, version-checked patches,
-and a verification gate. The runtime has no third-party Python dependencies.
-Development checks use Ruff and pytest.
+> Just want to use Yada? Follow **Quick start** below. Want to contribute?
+> Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
+> [developer docs](docs/dev/architecture.md).
 
-> Alpha status: the offline agent loop is tested, but no comparative benchmark
-> result is claimed yet.
+Yada is currently alpha software. The local agent loop is tested, but the
+project does not claim a comparative benchmark result yet.
 
-## Generic evaluation
+## Requirements
 
-Yada includes a benchmark-neutral evaluation layer. `EvalRunner` composes any
-`BenchmarkAdapter` with any `AgentAdapter`; the initial adapters cover local
-JSON manifests, SWE-bench, native Yada, and arbitrary external commands.
-
-The repository includes one portable SWE-bench Verified development case. Its
-first run fetches the exact pytest commit and creates a locked Python 3.9 task
-environment; later runs reuse those caches while keeping each agent workspace
-fresh:
-
-```bash
-uv run yada eval \
-  --case benchmarks/swebench_verified/pytest-10051 \
-  --agent yada \
-  --yes
-```
-
-This produces a real local verdict from one FAIL_TO_PASS and 15 PASS_TO_PASS
-tests, but it is not an official Docker score. The checkout lives under
-`.yada/cache/evals/`; the task recipe and its own `uv.lock` are committed.
-
-For SWE-bench, Yada produces the patch and official `predictions.jsonl` while
-delegating the verdict to the Docker-based `swebench.harness.run_evaluation`.
-See [docs/evaluation.md](docs/evaluation.md) for manifests, external-agent
-templates, Docker prerequisites, and fair-comparison constraints.
-
-## Why this exists
-
-General-purpose harnesses can run DeepSeek, but they are not necessarily shaped
-around DeepSeek's tool-use and context behavior. Yada is a compact research
-vehicle for testing model-native harness ideas with reproducible trajectories
-and ablations.
-
-The current hypotheses are:
-
-1. A tiny, stable tool schema reduces tool-call failures.
-2. SHA-bound unified diffs prevent stale and ambiguous edits.
-3. Structured, bounded command observations improve recovery after test failures.
-4. An append-only conversation preserves DeepSeek prefix-cache opportunities.
+- Python 3.11+
+- Git
+- [uv](https://docs.astral.sh/uv/) (recommended)
+- A DeepSeek API key
 
 ## Quick start
 
-Requirements: Python 3.11+, Git, and a DeepSeek API key.
-
-The recommended workflow uses [uv](https://docs.astral.sh/uv/):
-
 ```bash
+git clone https://github.com/GenTang/Yada.git
 cd Yada
 uv sync --locked --dev
-export DEEPSEEK_API_KEY="sk-..."
-
-uv run yada "Fix the failing parser edge case and run the relevant tests" \
-  --workspace /path/to/repository
-```
-
-The package also works with standard library tooling and pip:
 
-```bash
-cd Yada
-python3 -m venv .venv
-.venv/bin/python -m pip install -e .
 export DEEPSEEK_API_KEY="sk-..."
 
-yada "Fix the failing parser edge case and run the relevant tests" \
+uv run yada "Fix the failing parser edge case and run the relevant tests" \
   --workspace /path/to/repository
 ```
 
-Yada asks before every repository command by default. For autonomous execution
-inside a disposable sandbox:
-
-```bash
-yada "Fix the issue described in issue.md" \
-  --workspace /workspace \
-  --yes
-```
-
-You can also pass a task file:
-
-```bash
-yada --task-file issue.md --workspace .
-```
-
-The default model is `deepseek-v4-pro`, thinking is enabled, and reasoning
-effort is `max`. These can be changed with `--model`, `--no-thinking`, and
-`--reasoning-effort`.
-
-## Docker
-
-The container limits filesystem exposure to the mounted repository. It is not a
-network sandbox.
+Yada asks before running repository commands. Use `--yes` only inside a trusted,
+disposable environment:
 
 ```bash
-docker build -t yada .
-docker run --rm -it \
-  -e DEEPSEEK_API_KEY \
-  -v "/path/to/repository:/workspace" \
-  yada "Fix the failing test" --workspace /workspace --yes
+uv run yada --task-file issue.md --workspace /workspace --yes
 ```
 
-## The loop
-
-```text
-stable prompt + tool schema
-          ↓
-DeepSeek tool call
-          ↓
-validate → approve → execute
-          ↓
-bounded structured observation
-          ↓
-append and repeat
-          ↓
-finish only after post-patch verification
-```
-
-Tools:
-
-- `search_code`: ripgrep-backed repository search, with a Python fallback.
-- `read_file`: bounded numbered reads plus SHA-256.
-- `apply_patch`: Git-style unified diffs checked against every file hash.
-- `run_command`: argv-only command execution with an allowlist and approval gate.
-- `finish`: rejected until a test or build succeeds after the latest patch.
-
-DeepSeek thinking-mode `reasoning_content` is retained in memory and passed back
-after tool calls, as required by the API. The default `--trace-level summary`
-records compact context metrics. `--trace-level debug` additionally records the
-complete sanitized provider payload and reasoning text for every model turn.
-Summary traces replace reasoning with its length and hash. Both levels redact
-common API keys, authorization values, tokens, passwords, and secrets. Debug
-traces contain sensitive model context and must be handled accordingly.
-
-Capture a replayable debug trace during an evaluation:
-
-```bash
-uv run yada eval \
-  --case benchmarks/swebench_verified/pytest-10051 \
-  --agent yada \
-  --yes \
-  --trace-level debug
-```
-
-Inspect a completed or interrupted run without manually scanning JSONL:
-
-```bash
-uv run yada-trace \
-  .yada/runs/fix-parser-edge-case__2026-08-02_20-26.jsonl
-uv run yada-trace \
-  eval-results/pytest-dev__pytest-10051__2026-08-02_20-26.artifacts/yada-trace.jsonl \
-  --step 8
-uv run yada-trace eval-results/<task>__<system-local-time>.artifacts/yada-trace.jsonl \
-  --verbose
-uv run yada-trace TRACE.jsonl --events
-```
-
-The default report groups each model request, response, planning decision, and
-ordered tool executions into one agent step. Every summary includes physical
-JSONL line references so the source evidence is immediately reachable with tools
-such as `sed`. `--step` and `--verbose` expand sanitized model messages, tool
-arguments, patches, stdout, and stderr inside grouped steps; `--events` retains a
-line-prefixed flat timeline. The source JSONL remains the durable,
-streaming-friendly record. Debug traces can contain source code and test output
-even after secret redaction, so handle them as sensitive artifacts. See
-[docs/tracing.md](docs/tracing.md) for the event reference, field-presence
-semantics, lifecycle, and `jq` recipes.
-
-Default trace and evaluation paths use the system-local time at minute
-precision. If a name already exists, Yada appends `(1)`, `(2)`, and so on before
-the file or artifacts suffix, keeping the result JSON and artifacts directory on
-the same number.
-
-## Safety model
-
-Yada provides guardrails, not a complete OS sandbox:
-
-- File tools reject workspace escapes, symlink escapes, `.git`, and `.yada`.
-- Patches reject binary, rename, copy, mode, and symlink changes.
-- Commands use argv arrays rather than a shell string.
-- Shell `-c` and mutating Git subcommands are rejected.
-- Secret-looking environment variables, including the DeepSeek key, are removed
-  from child command environments.
-- Command execution asks for confirmation unless `--yes` is used.
-
-Repository tests are arbitrary code. Run unfamiliar repositories in a disposable
-VM or a stronger sandbox. The included Dockerfile reduces filesystem exposure,
-but repository code can still access the container network.
-
-## Development checks
-
-The test suite includes a fully offline fake-model run through read → patch →
-test → finish, plus stale hash, path escape, secret environment, and verification
-gate tests. Ruff provides the repository's lint and formatting gates.
-
-```bash
-uv sync --locked --dev
-uv run --frozen ruff check .
-uv run --frozen ruff format --check .
-uv run --frozen pytest tests/ -v
-```
-
-CI runs the same checks on Python 3.11 and 3.12. Without uv, install the runtime
-project with `python3 -m pip install -e .`, install `pytest` and `ruff` separately,
-then run the equivalent commands. These tools remain development dependencies and
-do not increase Yada's runtime dependency footprint.
-
-## Project layout
-
-Yada uses a `src/` layout and keeps orchestration separate from execution:
-
-```text
-src/yada/
-├── agents/        # thin loop, side-effect-free planner, and tool executor
-├── models/        # model protocol and DeepSeek API adapter
-├── environments/  # workspace boundary and command approval
-├── tools/         # one module per tool plus the small dispatcher
-├── traces/        # JSONL writer plus a human-readable diagnostic report
-├── evals/         # generic runner plus benchmark and agent adapters
-├── run/           # CLI entry point
-└── utils/         # bounded-output helpers
-benchmarks/        # portable recipes; generated checkouts stay in .yada/cache
-tests/
-├── agents/
-├── evals/
-├── models/
-├── tools/
-├── traces/
-└── utils/
-```
-
-`Planner` owns conversation policy and validates the next action without I/O.
-`Executor` owns argument parsing, workspace side effects, and correlated tool
-events. `Agent` only coordinates the two. This is a deliberately small seam—not
-a second model call—but it prevents the main loop from accumulating every future
-planning and execution policy.
-
-The package boundaries follow the useful parts of mini-SWE-agent's structure,
-while Yada retains its own multi-tool protocol, SHA-bound patches, command
-policy, and verification gate.
+## What happens next
 
-## Design lineage
+Yada prints each DeepSeek turn and tool execution, then reports whether the task
+passed its verification gate. Traces are written under the target repository's
+`.yada/runs/` directory by default.
 
-Yada learns from the simplicity of
-[mini-SWE-agent](https://github.com/SWE-agent/mini-swe-agent), the reproducible
-trajectory discipline of [SWE-agent](https://github.com/SWE-agent/SWE-agent),
-and DeepSeek's official [thinking-mode](https://api-docs.deepseek.com/guides/thinking_mode)
-and [tool-call](https://api-docs.deepseek.com/guides/tool_calls) contracts. The
-implementation is original and intentionally smaller than those systems.
+Repository tests can execute arbitrary code. Yada provides guardrails, not a
+complete OS sandbox; use a disposable VM or container for unfamiliar projects.
 
-See [docs/architecture.md](docs/architecture.md) for the detailed contracts and
-planned ablations, and [docs/tracing.md](docs/tracing.md) for the trace schema.
+## Learn more
 
-## Current non-goals
+- [Configuration](docs/configuration.md): installation alternatives, API key,
+  model settings, command policy, and trace levels.
+- [CLI reference](docs/cli-reference.md): `yada`, `yada eval`, and `yada-trace`.
+- [Contributing](CONTRIBUTING.md): development setup, validation, and the rebase
+  pull-request workflow.
+- [Architecture](docs/dev/architecture.md): agent loop, tools, patch transaction,
+  evaluation boundaries, and safety invariants.
+- [Debugging](docs/dev/debugging.md): tests, trace inspection, and reproducible
+  issue reports.
 
-No TUI, IDE plugin, MCP, skills, subagents, web search, long-term memory, model
-routing, automatic commits, or benchmark leaderboard. Those features should be
-earned by evaluation evidence.
+Yada is licensed under the [MIT License](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
deleted file mode 100644
index bbbea0c..0000000
--- a/README.zh-CN.md
+++ /dev/null
@@ -1,203 +0,0 @@
-# Yada
-
-**Yet Another DeepSeek Agent**：一个专为 DeepSeek V4 构建的小型、可审计
-Coding Agent Harness。
-
-[English README](README.md)
-
-Yada 有意保持克制：单 Agent 循环、独立的规划/执行边界、追加式会话、5个工具、
-带版本校验的 Patch，以及“修改后必须通过测试才能完成”的验证门槛。运行时没有
-第三方 Python 依赖；开发验证使用 Ruff 和 pytest。
-
-> 当前为 Alpha：离线 Agent 闭环已通过测试，但尚未宣称任何对比评测结果。
-
-## 通用评测
-
-Yada 内置了 Benchmark-neutral 的评测层。`EvalRunner` 将任意
-`BenchmarkAdapter` 与任意 `AgentAdapter` 组合起来；当前提供本地 JSON Manifest、
-SWE-bench、原生 Yada 和外部命令四个适配器。
-
-仓库内置了一个可移植的 SWE-bench Verified 开发用例。首次运行会拉取 pytest 的
-精确 commit，并创建锁定的 Python 3.9 任务环境；后续运行复用缓存，但每个 Agent
-仍获得全新的工作区：
-
-```bash
-uv run yada eval \
-  --case benchmarks/swebench_verified/pytest-10051 \
-  --agent yada \
-  --yes
-```
-
-该命令会运行 1 个 FAIL_TO_PASS 和 15 个 PASS_TO_PASS 测试，产生真实的本地
-resolved/unresolved 判定，但不等同于官方 Docker 成绩。源码缓存在
-`.yada/cache/evals/`，仓库只提交任务配方和任务自己的 `uv.lock`。
-
-运行 SWE-bench 时，Yada 只生成 Patch 和官方 `predictions.jsonl`，评分仍委托给
-`swebench.harness.run_evaluation` 的 Docker Harness。使用 `--grade-mode none` 可以
-只检查任务准备和预测文件，不会产生虚假的 resolved 结果。Manifest Schema、外部
-Agent 命令模板和公平比较约束见 [docs/evaluation.md](docs/evaluation.md)。
-
-## 快速开始
-
-需要 Python 3.11+、Git 和 DeepSeek API Key。
-
-推荐使用 `uv`：
-
-```bash
-cd Yada
-uv sync --locked --dev
-export DEEPSEEK_API_KEY="sk-..."
-
-uv run yada "修复 parser 的边界问题，并运行相关测试" \
-  --workspace /path/to/repository
-```
-
-也可以继续使用标准 venv 与 pip：
-
-```bash
-cd Yada
-python3 -m venv .venv
-.venv/bin/python -m pip install -e .
-export DEEPSEEK_API_KEY="sk-..."
-
-yada "修复 parser 的边界问题，并运行相关测试" \
-  --workspace /path/to/repository
-```
-
-Yada 默认会在运行仓库命令前请求确认。在一次性沙箱中可以启用自动执行：
-
-```bash
-yada --task-file issue.md --workspace /workspace --yes
-```
-
-默认使用 `deepseek-v4-pro`、开启思考模式，并把推理强度设为 `max`。
-
-## 最小闭环
-
-```text
-稳定 Prompt + Tool Schema
-          ↓
-DeepSeek 工具调用
-          ↓
-校验 → 审批 → 执行
-          ↓
-结构化、限长的 Observation
-          ↓
-追加会话并继续
-          ↓
-最新 Patch 通过验证后才允许 finish
-```
-
-工具只有5个：
-
-- `search_code`：优先使用 ripgrep，缺失时使用 Python 回退。
-- `read_file`：分段读取带行号内容，并返回 SHA-256。
-- `apply_patch`：使用 Git Unified Diff，并检查全部目标文件 Hash。
-- `run_command`：无 Shell 的 argv 执行、命令白名单和用户审批。
-- `finish`：最新修改后没有成功测试或构建时直接拒绝。
-
-DeepSeek 思考模式要求工具轮次继续回传 `reasoning_content`。Yada 会在内存中
-保留并正确回传。默认的 `--trace-level summary` 只记录紧凑的上下文指标；
-`--trace-level debug` 还会保存每轮模型请求的完整脱敏 provider payload。
-JSONL 默认只保留 reasoning 的长度和 Hash，并脱敏常见 API key、
-Authorization、token、password 和 secret。只有显式使用
-`--trace-reasoning` 才会落盘完整推理。
-
-在评测中生成可还原的 debug trace：
-
-```bash
-uv run yada eval \
-  --case benchmarks/swebench_verified/pytest-10051 \
-  --agent yada \
-  --yes \
-  --trace-level debug
-```
-
-无需手工翻阅 JSONL，可以直接生成关联后的诊断时间线：
-
-```bash
-uv run yada-trace .yada/runs/20260801T120000.000000Z.jsonl
-uv run yada-trace eval-results/<run>.artifacts/yada-trace.jsonl --step 8
-uv run yada-trace eval-results/<run>.artifacts/yada-trace.jsonl --verbose
-uv run yada-trace TRACE.jsonl --events
-```
-
-默认报告会按 Agent step 归组模型请求、响应、规划决定和有序工具执行，并为
-step、模型调用、工具执行和协议事件显示真实 JSONL 行号。`--step` 和
-`--verbose` 会在分组内展开脱敏后的模型消息、工具参数、Patch、stdout 和
-stderr；`--events` 可切回带物理行号的平铺时间线。Debug trace 脱敏后仍可能
-包含源码和测试输出，应当作敏感 artifact 处理。
-
-默认 trace 和评测路径使用精确到分钟的系统本地时间，不包含秒和小数秒。
-若名称已存在，Yada 会在文件或 `.artifacts` 后缀前依次添加 `(1)`、`(2)`；
-同一次评测的结果 JSON 与 artifacts 目录始终使用相同编号。
-
-## 安全边界
-
-Yada 提供 Guardrail，但不是完整的操作系统沙箱：
-
-- 文件工具拒绝工作区逃逸、符号链接逃逸、`.git` 和 `.yada`。
-- Patch 拒绝二进制、重命名、复制、权限模式和符号链接变更。
-- 命令使用 argv 数组，拒绝 Shell `-c` 和修改性 Git 子命令。
-- 子进程环境会移除 API Key、Token、Secret 等变量。
-- 默认每条命令都需要确认；`--yes` 仅应在隔离环境使用。
-
-仓库测试本身就是任意代码。陌生仓库应放在一次性 VM 或更强的沙箱中运行。
-Dockerfile 能限制文件系统暴露，但不会阻断容器网络。
-
-## 开发验证
-
-测试套件包含一个完全离线的 Fake Model 端到端流程，以及过期 Hash、路径
-逃逸、密钥环境变量和验证门槛测试；Ruff 负责 Lint 和格式检查：
-
-```bash
-uv sync --locked --dev
-uv run --frozen ruff check .
-uv run --frozen ruff format --check .
-uv run --frozen pytest tests/ -v
-```
-
-CI 会在 Python 3.11 和 3.12 上运行同样的检查。没有 uv 时，可使用
-`python3 -m pip install -e .` 安装运行时项目，再单独安装 `pytest` 和 `ruff`
-并执行对应命令。它们只是开发依赖，不会增加 Yada 的运行时依赖。
-
-## 项目结构
-
-Yada 采用 `src/` 布局，并把 Agent 编排与具体执行分离：
-
-```text
-src/yada/
-├── agents/        # 薄编排循环、无副作用 Planner 与工具 Executor
-├── models/        # 模型协议与 DeepSeek API 适配器
-├── environments/  # 工作区边界与命令审批
-├── tools/         # 每个工具一个模块，以及小型分发器
-├── traces/        # JSONL 轨迹记录与人类可读诊断报告
-├── evals/         # 通用 Runner、Benchmark 与 Agent 适配器
-├── run/           # CLI 入口
-└── utils/         # 输出截断等通用逻辑
-benchmarks/        # 可移植任务配方；运行时 checkout 放在 .yada/cache
-tests/
-├── agents/
-├── evals/
-├── models/
-├── tools/
-└── traces/
-```
-
-`Planner` 只负责会话策略和下一步动作校验，不做 I/O；`Executor` 负责参数解析、
-工作区副作用和带关联 ID 的工具事件；`Agent` 只负责编排二者。它目前不是一次
-额外的模型调用，但已经为未来的独立规划模型留下替换点，避免主循环演变成上帝类。
-
-边界设计参考了 mini-SWE-agent 的有效结构，但 Yada 保留自己的多工具协议、
-基于 SHA 的 Patch、命令策略和验证门槛。
-
-## 借鉴与差异
-
-Yada 借鉴了 [mini-SWE-agent](https://github.com/SWE-agent/mini-swe-agent)
-的极简循环、[SWE-agent](https://github.com/SWE-agent/SWE-agent) 的可复现轨迹，
-并直接遵循 DeepSeek 官方的[思考模式](https://api-docs.deepseek.com/guides/thinking_mode)
-和[工具调用](https://api-docs.deepseek.com/guides/tool_calls)契约。代码为独立实现，
-目标是成为一个便于实验和消融的 DeepSeek-native Harness。
-
-当前不做 TUI、IDE、MCP、Skills、多 Agent、联网、长期记忆、模型路由或自动
-提交。详细设计见 [docs/architecture.md](docs/architecture.md)。
diff --git a/docs/architecture.md b/docs/architecture.md
deleted file mode 100644
index ee215a6..0000000
--- a/docs/architecture.md
+++ /dev/null
@@ -1,129 +0,0 @@
-# Yada architecture
-
-Yada is a single-loop coding harness, not an orchestration framework. Its
-directory boundaries make the minimal loop easier to test without turning it
-into a framework of abstractions.
-
-## Package map
-
-```text
-run/cli.py
-    ├── agents/default.py
-        ├── agents/planning.py
-        ├── agents/executor.py
-        │   └── tools/runner.py
-        │       ├── environments/workspace.py
-        │       ├── environments/approval.py
-        │       ├── tools/search.py
-        │       ├── tools/read.py
-        │       ├── tools/patch.py
-        │       ├── tools/command.py
-        │       └── tools/finish.py
-        ├── models/base.py ← models/deepseek.py
-        └── traces/jsonl.py ← traces/report.py
-    └── evals/cli.py
-        └── evals/runner.py
-            ├── evals/benchmarks/{local,swebench}.py
-            ├── evals/benchmarks/local_{source,environment}.py
-            └── evals/agents/{yada,command}.py
-benchmarks/
-    └── swebench_verified/pytest-10051/  # recipe only; no checkout or venv
-```
-
-- `agents/default.py`: coordinates state and the step limit; it owns no tool policy.
-- `agents/planning.py`: side-effect-free conversation and batch protocol policy.
-- `agents/executor.py`: parses, executes, and traces tool calls and their results.
-- `models`: defines the completion boundary and implements DeepSeek transport.
-- `environments`: owns access to the local workspace and command approval.
-- `tools`: contains stateless handlers; `runner.py` composes shared tool state.
-- `traces`: records correlated append-only events and renders diagnostic timelines.
-- `evals`: composes benchmark preparation/grading with interchangeable agents.
-- `benchmarks`: stores reproducible task recipes, canonical public inputs,
-  locked task environments, and external graders.
-- `run`: parses user configuration and assembles the runtime.
-- `utils`: holds small mechanics shared by otherwise independent modules.
-
-Dependencies point inward through these contracts. A tool handler does not know
-about the model or agent, and the DeepSeek adapter does not know about tools.
-
-## Invariants
-
-1. The system prompt and tool schema stay stable for the whole run.
-2. Messages are append-only; assistant `reasoning_content` is retained in memory.
-3. File mutation is possible only through a checked unified diff.
-4. Every existing patch target must have been read at the exact current SHA-256.
-5. Every patch invalidates prior verification.
-6. `finish` succeeds only if a `test` or `build` command passed at the latest revision.
-7. All trace events are append-only JSONL records with a run ID and sequence.
-
-## Planner/executor seam
-
-The current `Planner` is a deterministic policy layer, not a second LLM call. It
-builds the stable prompt prefix, recovers from text-only responses, and rejects
-unsafe multi-call `finish` batches. It has no access to the workspace. The
-`Executor` owns argument decoding, `ToolRunner` side effects, durations, and
-tool-call correlation IDs.
-
-This split prevents `default.py` from becoming the home of every future policy.
-An experiment can replace `Planner` with an explicit plan-producing model or
-state machine without changing tool safety, and can replace `Executor` for a
-remote sandbox without changing conversation policy.
-
-## Patch transaction
-
-`read_file` returns a content hash. `apply_patch` parses every `diff --git`
-header and requires an exact set of `{path, sha256}` declarations. The patch is
-rejected if a file changed after it was read, if a path leaves the workspace, or
-if Git cannot apply it cleanly. A new file uses the sentinel `NEW`.
-
-This contract is intentionally stricter than a generic text-replace tool and
-smaller than maintaining session-local snippet objects.
-
-## Command observations
-
-Commands use an argv array and capture stdout, stderr, exit code, duration, and
-timeout separately. Long output keeps a larger prefix plus a suffix containing
-the final error frames. Successful `inspect` commands do not satisfy the
-verification gate; only `test` and `build` do.
-
-## Trace diagnostics
-
-JSONL is the crash-safe source of truth, but it is not the debugging interface.
-Schema v2 has two capture levels. `summary` records context size and event timing;
-`debug` also stores the sanitized provider payload built by the same client method
-used for the HTTP request. Responses, planner decisions, tool calls, and tool
-results remain correlated by step, request ID, and tool-call ID. `run_start`
-records Yada version/commit, workspace base commit, case ID when available, and
-the model configuration.
-
-`yada-trace PATH` renders one source-located section per agent step. `--step N`
-expands one complete request → response → tools step, while `--verbose` expands
-every grouped step and `--events` provides the line-prefixed flat timeline.
-Reasoning is length/hash-redacted in summary traces and automatically retained in
-debug traces. Common secret keys and bearer/API-key-like text are redacted in
-both modes. A debug trace can still contain reasoning, source code, and test
-output and must be handled as a sensitive artifact.
-The complete event and field reference lives in [tracing.md](tracing.md).
-
-The MVP stores a full sanitized request snapshot per turn. This deliberately
-favors deterministic inspection over delta complexity; content-addressed prompts
-or message deltas can replace it later if measured trace size justifies the added
-reader and compatibility cost.
-
-## Security boundary
-
-Path checks and command policy reduce accidental damage, but `python`, test
-runners, build tools, and repository scripts execute arbitrary code. A real
-benchmark deployment should run each task in a disposable container and run the
-hidden grader in a separate container after the agent exits.
-
-## Evaluation-driven next steps
-
-Do not add a feature until a frozen baseline exposes a failure class. Candidate
-ablations are:
-
-1. SHA-bound patch vs ordinary unified diff.
-2. Bounded structured output vs raw terminal output.
-3. Append-only stable prefix vs context rebuilding.
-4. Free exploration vs mandatory plan.
-5. One DeepSeek model vs a cheaper exploration model followed by a stronger repair model.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
new file mode 100644
index 0000000..cd6f6c1
--- /dev/null
+++ b/docs/cli-reference.md
@@ -0,0 +1,233 @@
+# CLI reference
+
+Yada installs two entry points:
+
+- `yada`: run the coding agent or an evaluation;
+- `yada-trace`: inspect a JSONL execution trace.
+
+Examples below use `uv run`. After editable pip installation, omit `uv run`.
+Run `uv run yada --help`, `uv run yada eval --help`, or
+`uv run yada-trace --help` for the parser-generated reference.
+
+## `yada`
+
+```text
+yada TASK [OPTIONS]
+yada --task-file FILE [OPTIONS]
+```
+
+Provide exactly one task source. The workspace defaults to the current directory.
+
+```bash
+uv run yada "Fix the parser boundary case and run its tests" \
+  --workspace /path/to/repository
+
+uv run yada --task-file issue.md --workspace /path/to/repository
+```
+
+### Options
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `TASK` | Natural-language coding task. | — |
+| `--task-file PATH` | Read the task from a UTF-8 file. | — |
+| `--workspace PATH` | Target Git workspace. | Current directory |
+| `--model NAME` | DeepSeek model name. | `DEEPSEEK_MODEL` or `deepseek-v4-pro` |
+| `--base-url URL` | DeepSeek-compatible API base URL. | `DEEPSEEK_BASE_URL` or `https://api.deepseek.com` |
+| `--reasoning-effort high\|max` | Thinking effort. | `max` |
+| `--thinking` / `--no-thinking` | Enable or disable thinking. | Enabled |
+| `--max-steps N` | Maximum model turns. | `30` |
+| `--max-output-tokens N` | Maximum tokens requested per completion. | `16384` |
+| `--api-timeout SECONDS` | Timeout for one model request. | `300` |
+| `--command-timeout SECONDS` | Default repository-command timeout. | `120` |
+| `--command-policy ask\|allow\|deny` | Repository-command approval policy. | `ask` |
+| `--yes` | Alias for command policy `allow`. | Off |
+| `--trace PATH` | Exact JSONL trace path. | `.yada/runs/<task>__<time>.jsonl` |
+| `--trace-level summary\|debug` | Trace capture detail. | `summary` |
+| `--version` | Print the Yada version. | — |
+
+Exit status is `0` after verified completion, `2` when the step limit or another
+unfinished outcome is reached, `3` for a DeepSeek API error, and `130` after
+keyboard interruption. Argument errors also use the standard argparse status `2`.
+
+## `yada eval`
+
+`yada eval` runs an agent behind a benchmark-neutral adapter and persists a
+schema-versioned result even for ordinary adapter failures.
+
+### Checked-in development case
+
+```bash
+uv run yada eval \
+  --case benchmarks/swebench_verified/pytest-10051 \
+  --agent yada \
+  --yes
+```
+
+The first run fetches the pinned pytest commit and builds the case's locked
+Python environment. Later runs reuse caches but create a fresh agent workspace.
+This local grader is a development feedback loop, not an official SWE-bench
+Docker score.
+
+### Common options
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `--benchmark local\|swebench` | Benchmark adapter. | Inferred from `--case`, otherwise required |
+| `--case PATH` | Portable local case directory or `case.json`. | — |
+| `--instance ID` | Benchmark instance ID. | Manifest ID for local cases |
+| `--agent yada\|command` | Agent adapter. | `yada` |
+| `--output PATH` | Result JSON path. | `eval-results/<task>__<time>.json` |
+| `--artifact-dir PATH` | Workspace, logs, patch, trace, and grader artifacts. | Sibling `<result>.artifacts` |
+| `--run-id ID` | Stable correlation ID. | Generated |
+| `--max-steps N` | Model-turn budget. | `30` |
+| `--wall-time SECONDS` | Comparable wall-time budget. | `1800` |
+| `--max-output-tokens N` | Per-completion token limit. | `16384` |
+
+The native agent also accepts the model, thinking, timeout, command-policy, and
+trace-level options documented for `yada`. A deployment-level supervisor should
+enforce a hard wall-time limit for an in-process native agent.
+
+Evaluation exits with `0` for `resolved`, `1` for `unresolved`, and `2` for
+errors or non-verdict outcomes such as skipped grading.
+
+### Local manifest
+
+Use `--benchmark local --manifest FILE` for a private or machine-local task.
+A minimal version 1 manifest is:
+
+```json
+{
+  "schema_version": 1,
+  "instance_id": "example__repo-1",
+  "task_file": "task.md",
+  "workspace": "candidate",
+  "workspace_mode": "copy",
+  "base_commit": "0123456789abcdef",
+  "grader": {
+    "argv": ["python", "grader.py", "{workspace}"],
+    "timeout_seconds": 1800
+  }
+}
+```
+
+Paths are relative to the manifest. `workspace_mode=copy` preserves the source
+fixture and gives each run a fresh copy. An in-place workspace is also supported
+for explicitly local experiments. The grader runs after the agent exits:
+
+- exit `0`: resolved;
+- exit `1`: unresolved;
+- any other exit: grading error.
+
+Grader argv entries may use `{workspace}`, `{patch}`, `{run_dir}`, and `{run_id}`.
+
+A portable case can replace `workspace` with a pinned Git source and define a
+locked uv environment:
+
+```json
+{
+  "schema_version": 1,
+  "instance_id": "owner__repo-1",
+  "instance_file": "instance.json",
+  "workspace": {
+    "type": "git",
+    "url": "https://github.com/owner/repo.git",
+    "cache_key": "verified/owner__repo-1"
+  },
+  "base_commit": "0123456789abcdef",
+  "environment": {
+    "type": "uv",
+    "project": ".",
+    "install_workspace": "editable",
+    "pythonpath": ["src"]
+  },
+  "grader": {
+    "argv": [".venv/bin/python", "grader.py", "{workspace}"]
+  }
+}
+```
+
+Portable Git checkouts are cached under `--cache-dir` (default
+`.yada/cache/evals`) but never used directly as the mutable agent workspace.
+`install_workspace` accepts `editable` and `legacy-editable`.
+
+### External command agent
+
+The command adapter runs a non-interactive argv without a shell:
+
+```bash
+uv run yada eval \
+  --benchmark local \
+  --manifest /path/to/task.local.json \
+  --agent command \
+  --agent-name another-agent \
+  --agent-command \
+    'another-agent run --task-file {task_file} --workspace {workspace}' \
+  --output results/another-agent.json
+```
+
+The template supports `{task}`, `{task_file}`, `{workspace}`, `{output_patch}`,
+and `{run_dir}`. If the command does not write `{output_patch}`, Yada collects
+the complete Git diff, including untracked files.
+
+### SWE-bench
+
+The SWE-bench adapter loads public instance metadata from `--instance-file`, or
+from Hugging Face when the optional `datasets` package is installed. It discards
+gold patches, test patches, and hidden test IDs at the public task boundary.
+
+Install the official SWE-bench package and Docker separately, then run:
+
+```bash
+uv run yada eval \
+  --benchmark swebench \
+  --instance pytest-dev__pytest-10051 \
+  --instance-file benchmarks/swebench_verified/pytest-10051/instance.json \
+  --workspace /path/to/clean/pytest-base-repo \
+  --agent yada \
+  --yes \
+  --swebench-python /path/to/swebench-env/bin/python \
+  --output results/yada-pytest-10051.json
+```
+
+`--workspace` is optional; without it, Yada fetches the exact base commit. It
+prepares the candidate workspace but does not replace official Docker grading.
+Use `--grade-mode none` to test preparation and prediction generation without
+Docker; the result is `skipped`, never `resolved`.
+
+Other SWE-bench options are `--dataset-name`, `--split`, `--cache-level`,
+`--clean`, `--namespace`, and `--grade-timeout`. Use the same task, base commit,
+model budget, network policy, and official grader when comparing agents.
+
+## `yada-trace`
+
+```text
+yada-trace TRACE.jsonl [--step N | --verbose | --events]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--step N` | Expand one complete request → response → tools step. |
+| `--verbose` | Expand payloads inside every grouped step. |
+| `--events` | Show the flat event timeline with physical JSONL line numbers. |
+
+The default view groups records by agent step and shows physical JSONL line
+references for the model request/response and each tool call/result pair:
+
+```bash
+uv run yada-trace TRACE.jsonl
+uv run yada-trace TRACE.jsonl --step 8
+uv run yada-trace TRACE.jsonl --events
+```
+
+`yada-trace` returns `0` after rendering and `2` for an unreadable or invalid
+trace. See the [debugging guide](dev/debugging.md) for event semantics, trace
+levels, `jq` recipes, and reproduction workflows.
+
+## Output naming
+
+Default direct-run and evaluation names contain a sanitized task name and the
+system-local time at minute precision. If a name exists, Yada appends `(1)`,
+`(2)`, and so on. An evaluation result JSON and its `.artifacts` directory always
+share the same collision number. Explicit `--trace`, `--output`, and
+`--artifact-dir` paths are never renamed.
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..7b7186c
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,143 @@
+# Configuration
+
+This guide covers installation choices, DeepSeek credentials, model settings,
+execution policy, and trace capture. See the [CLI reference](cli-reference.md)
+for every command-line option.
+
+## Requirements
+
+Yada requires Python 3.11+ and Git. The recommended setup uses
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/GenTang/Yada.git
+cd Yada
+uv sync --locked --dev
+```
+
+The runtime itself has no third-party Python dependencies. To use a standard
+virtual environment instead:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+After editable installation, use `.venv/bin/yada`; after `uv sync`, use
+`uv run yada`.
+
+## DeepSeek credentials
+
+`DEEPSEEK_API_KEY` is required when the native Yada agent calls DeepSeek:
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+```
+
+PowerShell:
+
+```powershell
+$env:DEEPSEEK_API_KEY = "sk-..."
+```
+
+Do not put the key in a task file, trace, issue, or commit. Yada sends it only in
+the DeepSeek authorization header and removes secret-looking environment
+variables from repository subprocesses.
+
+## Model and endpoint
+
+The main `yada` command and the native `yada eval` agent share these settings:
+
+| Setting | Default | CLI | Environment |
+| --- | --- | --- | --- |
+| Model | `deepseek-v4-pro` | `--model` | `DEEPSEEK_MODEL` |
+| API base URL | `https://api.deepseek.com` | `--base-url` | `DEEPSEEK_BASE_URL` |
+| Thinking | enabled | `--thinking` / `--no-thinking` | — |
+| Reasoning effort | `max` | `--reasoning-effort high\|max` | — |
+| Maximum output tokens | `16384` | `--max-output-tokens` | — |
+| API timeout | 300 seconds | `--api-timeout` | — |
+
+CLI values override environment-backed defaults. For example:
+
+```bash
+uv run yada "Fix the failing test" \
+  --workspace /path/to/repository \
+  --model deepseek-v4-pro \
+  --reasoning-effort high
+```
+
+When thinking is enabled, Yada retains `reasoning_content` across tool-calling
+turns as required by DeepSeek. In non-thinking mode, Yada uses ordinary automatic
+tool selection.
+
+## Command execution policy
+
+Repository commands are independently validated and then handled by one of
+three policies:
+
+| Policy | Behavior |
+| --- | --- |
+| `ask` | Prompt before each command; this is the default. |
+| `allow` | Run approved command shapes without prompting. |
+| `deny` | Reject every repository command. |
+
+Choose a policy with `--command-policy`. `--yes` is an alias for
+`--command-policy allow`:
+
+```bash
+uv run yada --task-file issue.md \
+  --workspace /workspace \
+  --command-policy ask
+```
+
+Yada accepts argv arrays rather than shell command strings, disables `sh -c` and
+`bash -c`, restricts Git to read-only subcommands, and uses an executable
+allowlist. These are guardrails, not an OS sandbox. Tests and build scripts can
+still execute arbitrary code; use `allow` only in a trusted disposable VM or
+container.
+
+`--command-timeout` sets the default subprocess timeout in seconds. A model may
+request a per-command timeout between 1 and 1800 seconds.
+
+## Trace capture
+
+Choose one of two trace levels:
+
+| Level | Captured data |
+| --- | --- |
+| `summary` | Timing, responses, tools, compact request metrics; reasoning is replaced by length and SHA-256. |
+| `debug` | Everything above plus sanitized provider request payloads and reasoning text. |
+
+```bash
+uv run yada "Fix the parser" \
+  --workspace /path/to/repository \
+  --trace-level debug
+```
+
+Both levels redact common API-key, bearer-token, password, credential, and
+secret patterns. Debug traces can still contain reasoning, source code, prompts,
+patches, paths, and test output. Treat them as sensitive artifacts.
+
+By default, direct runs write to:
+
+```text
+WORKSPACE/.yada/runs/<task>__<system-local-time>.jsonl
+```
+
+Use `--trace PATH` to choose an exact location. Default names use local time at
+minute precision and append `(1)`, `(2)`, and so on when a name already exists.
+
+## Docker
+
+The included image isolates the mounted filesystem but does not block container
+network access:
+
+```bash
+docker build -t yada .
+docker run --rm -it \
+  -e DEEPSEEK_API_KEY \
+  -v "/path/to/repository:/workspace" \
+  yada "Fix the failing test" --workspace /workspace --yes
+```
+
+Use a stronger sandbox when the repository or its dependencies are untrusted.
diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md
new file mode 100644
index 0000000..856b58a
--- /dev/null
+++ b/docs/dev/architecture.md
@@ -0,0 +1,213 @@
+# Yada architecture
+
+Yada is a deliberately small DeepSeek-native coding harness: one model loop,
+five tools, an append-only conversation, checked patch application, and a
+verification gate. This document describes the internal boundaries contributors
+must preserve.
+
+For commands and public behavior, see the [CLI reference](../cli-reference.md).
+For tests and trace inspection, see [Debugging](debugging.md).
+
+## Design motivation
+
+Yada is a research vehicle for testing whether a small, model-specific harness
+can remain easier to audit and evaluate than a general orchestration framework.
+Its working hypotheses are:
+
+1. A small, stable tool schema reduces protocol failures.
+2. SHA-bound patches reject stale edits before they mutate the workspace.
+3. Structured, bounded command observations help the model recover from failures.
+4. An append-only conversation preserves DeepSeek tool-call reasoning and stable
+   prompt prefixes.
+
+New abstractions should be justified by a concrete evaluation or debugging need.
+Yada currently does not aim to provide a TUI, IDE integration, subagents,
+long-term memory, model routing, or automatic commits.
+
+## Package map
+
+```text
+run/cli.py
+    ├── agents/default.py
+    │   ├── agents/planning.py
+    │   ├── agents/executor.py
+    │   │   └── tools/runner.py
+    │   │       ├── environments/workspace.py
+    │   │       ├── environments/approval.py
+    │   │       └── tools/{search,read,patch,command,finish}.py
+    │   ├── models/base.py ← models/deepseek.py
+    │   └── traces/jsonl.py ← traces/report.py
+    └── evals/cli.py
+        └── evals/runner.py
+            ├── evals/benchmarks/{local,swebench}.py
+            └── evals/agents/{yada,command}.py
+```
+
+- `run`: parses public configuration and assembles a direct run.
+- `agents`: coordinates model turns, planning policy, and tool execution.
+- `models`: defines the completion boundary and DeepSeek transport.
+- `environments`: owns workspace containment and command approval.
+- `tools`: implements one handler per model-facing tool.
+- `traces`: writes append-only events and builds source-located reports.
+- `evals`: composes benchmark preparation/grading with interchangeable agents.
+- `benchmarks`: stores reproducible recipes, not generated checkouts or results.
+- `utils`: contains small mechanics shared across otherwise separate packages.
+
+Dependencies point inward through these boundaries. A tool does not know about
+the model loop, and the DeepSeek client does not know which tools execute calls.
+
+## Agent loop
+
+```text
+stable system prompt + tool schemas
+                ↓
+          DeepSeek completion
+                ↓
+     Planner validates next action
+                ↓
+     Executor runs ordered tool calls
+                ↓
+ append assistant + tool observations
+                ↓
+       repeat or verified finish
+```
+
+`Agent` in `agents/default.py` owns the append-only message list, step limit,
+usage accumulation, and top-level trace events. It does not implement tool
+policy or workspace mutation.
+
+The DeepSeek adapter keeps `reasoning_content` on assistant tool-call messages.
+The whole assistant message is appended before tool results, so subsequent model
+requests satisfy DeepSeek's thinking/tool-call contract.
+
+## Planner and executor
+
+The current `Planner` is deterministic; it is not another model call. It builds
+the initial prompt, interprets assistant output, recovers from text-only turns,
+and rejects unsafe batches such as `finish` mixed with another tool. It has no
+workspace access.
+
+The `Executor` parses tool arguments, preserves model-provided call order,
+invokes `ToolRunner`, and records correlated `tool_call` and `tool_result`
+events. A future planning model or remote executor can replace either side
+without weakening the workspace and tool contracts.
+
+## Tool system
+
+Yada exposes five tools:
+
+| Tool | Responsibility |
+| --- | --- |
+| `search_code` | Search repository text with ripgrep and a Python fallback. |
+| `read_file` | Return bounded, numbered text plus a SHA-256 content hash. |
+| `apply_patch` | Validate and apply a Git-style unified diff. |
+| `run_command` | Run an approved argv array and return bounded structured output. |
+| `finish` | End only after verification of the latest revision. |
+
+`ToolRunner` composes shared workspace, approval, output-limit, and verification
+state. Handlers remain otherwise stateless. File paths are resolved through the
+workspace boundary, which rejects absolute paths, `..` escapes, symlink escapes,
+and access to `.git` or `.yada` internals.
+
+## Patch transaction
+
+Patch application is intentionally stricter than ordinary text replacement:
+
+1. `read_file` returns the current file text and SHA-256.
+2. The model creates a unified diff with one `diff --git` header per target.
+3. `apply_patch` requires an `expected_files` entry for every target.
+4. Existing files must still match the exact hash returned by `read_file`.
+5. New files use the `NEW` sentinel instead of a hash.
+6. Yada rejects path escapes, unsupported binary/rename/copy/mode/symlink
+   operations, incomplete target declarations, and patches Git cannot check.
+7. Only after validation does `git apply` mutate the workspace.
+
+This is an optimistic transaction: a file changed after the model read it is a
+conflict, not permission to apply a stale edit. Every successful patch increments
+the workspace revision and invalidates earlier verification.
+
+## Commands and verification
+
+`run_command` accepts argv, not a shell string. It checks the executable
+allowlist, disables shell `-c`, restricts Git to read-only subcommands, applies
+the configured approval policy, sanitizes secret-looking environment variables,
+and separately records stdout, stderr, exit code, timeout, and duration.
+
+The model labels a command as `inspect`, `test`, or `build`. Only a successful
+`test` or `build` verifies the current workspace revision. `finish` rejects the
+run when:
+
+- no verification succeeded;
+- a patch was applied after the last successful verification; or
+- `git diff --check` fails.
+
+Thus a passing test before the final edit cannot satisfy completion.
+
+## Trace architecture
+
+JSONL is the crash-safe source of truth. Each completed event write is visible
+immediately and contains schema version, run ID, sequence, timestamp, elapsed
+time, event name, and event-specific data.
+
+The report layer keeps storage and presentation separate. It associates each
+record with its physical JSONL line, groups events into model steps, and pairs
+model requests/responses and tool calls/results by their correlation IDs.
+`yada-trace --events` exposes the flat source timeline when the grouped view is
+not enough.
+
+Summary traces redact reasoning to a length and hash. Debug traces add sanitized
+provider payloads and reasoning text. Both levels apply secret-pattern
+redaction, but debug traces still contain sensitive source and model context.
+See [Debugging](debugging.md) for the event vocabulary and inspection workflow.
+
+## Evaluation architecture
+
+The evaluation layer keeps the coding agent separate from task preparation and
+grading:
+
+```text
+BenchmarkAdapter ── load/prepare ──┐
+                                  ├─ EvalRunner ─ result.json
+AgentAdapter ────── run/patch ─────┤
+                                  └─ BenchmarkAdapter.grade
+```
+
+Its stable data boundaries are:
+
+- `EvalTask`: public issue text and non-secret metadata;
+- `PreparedTask`: isolated candidate workspace;
+- `AgentRunResult`: patch, usage, steps, trace, and agent status;
+- `GradeResult`: benchmark-owned verdict and test diagnostics.
+
+The native adapter runs Yada in process. The command adapter allows comparable
+external agents. Local and SWE-bench benchmark adapters own provenance, hidden
+grading inputs, and the final verdict. Gold patches and hidden tests never cross
+the public task boundary.
+
+Fair comparisons use the same instance, base commit, public prompt, model
+endpoint, token/cost and wall-time budgets, network policy, and official grader.
+Resolve rate is the primary outcome; tokens, steps, duration, and cost are
+diagnostics. See [CLI reference: `yada eval`](../cli-reference.md#yada-eval) for
+manifest and command examples.
+
+## Core invariants
+
+1. System prompt and tool schemas stay stable during a run.
+2. Conversation messages are append-only.
+3. DeepSeek reasoning is preserved across tool-call turns.
+4. File mutation occurs only through a checked unified diff.
+5. Existing patch targets must match their last-read SHA-256.
+6. Every patch invalidates previous verification.
+7. `finish` requires verification of the latest revision.
+8. Trace events are append-only and self-correlating.
+9. Benchmark grading happens outside the agent's tool boundary.
+
+## Security boundary
+
+Yada's path checks, argv policy, environment sanitization, and approval gate
+reduce accidental damage; they do not isolate arbitrary repository code. Test
+runners, interpreters, build systems, dependencies, and scripts can access the
+host permissions available to the process.
+
+Production evaluation should put each candidate workspace in a disposable
+container or VM and run hidden grading outside the agent environment.
diff --git a/docs/dev/debugging.md b/docs/dev/debugging.md
new file mode 100644
index 0000000..60dd920
--- /dev/null
+++ b/docs/dev/debugging.md
@@ -0,0 +1,253 @@
+# Debugging Yada
+
+This guide is for contributors diagnosing agent behavior, tests, traces, and
+reproducible benchmark failures. Start with [CONTRIBUTING.md](../../CONTRIBUTING.md)
+for environment setup and the [architecture](architecture.md) for component
+boundaries.
+
+## Fast diagnosis workflow
+
+1. Reproduce the failure with the smallest deterministic test or checked-in case.
+2. Capture a `debug` trace when model context matters.
+3. Use `yada-trace` to find the failing agent step.
+4. Follow the displayed `L<number>` references into the source JSONL.
+5. Add an offline regression test before changing behavior.
+6. Run the full local CI suite.
+
+## Run tests
+
+Install development dependencies once:
+
+```bash
+uv sync --locked --dev
+```
+
+Run a focused file or test while iterating:
+
+```bash
+uv run --frozen pytest tests/traces/test_trace_report.py -v
+uv run --frozen pytest \
+  tests/traces/test_trace_report.py::test_step_report_groups_correlated_events -v
+```
+
+Run all local checks before pushing:
+
+```bash
+uv run --frozen ruff check .
+uv run --frozen ruff format --check .
+uv run --frozen pytest tests/ -v
+```
+
+The suite includes a fully offline fake-model path through read → patch → test →
+finish. Prefer fake clients and temporary Git repositories for agent-loop tests;
+unit tests must not require a DeepSeek key or network access.
+
+## Capture a useful trace
+
+Direct run:
+
+```bash
+uv run yada "Fix the parser boundary issue and run the tests" \
+  --workspace /path/to/repository \
+  --trace-level debug
+```
+
+Checked-in evaluation case:
+
+```bash
+uv run yada eval \
+  --case benchmarks/swebench_verified/pytest-10051 \
+  --agent yada \
+  --yes \
+  --trace-level debug
+```
+
+Trace levels are fixed policies:
+
+| Level | Reasoning | Model request payload |
+| --- | --- | --- |
+| `summary` | Length and SHA-256 only | Context size metrics |
+| `debug` | Sanitized text | Complete sanitized provider payload |
+
+Use `debug` when investigating prompt construction, DeepSeek thinking, tool-call
+selection, or context growth. API-key-like text is redacted at both levels, but
+debug traces can contain source code, patches, prompts, reasoning, local paths,
+and test output. Do not attach one publicly without reviewing it.
+
+## Inspect by agent step
+
+Start with the grouped report:
+
+```bash
+uv run yada-trace TRACE.jsonl
+```
+
+It groups one model request, response, planning decision, and ordered tool batch
+into each step. Physical source locations connect the summary to JSONL evidence:
+
+```text
+Step 3/30 — DeepSeek  1.8s  1,246 tokens  [L30–L36]
+  Model call  [request L30 → response L31]
+    Finish reason: tool_calls
+    Reasoning: 381 chars
+  Tools:
+    [ok] search_code  42ms  [call L33 → result L34]
+    [error] run_command  1.4s  exit=1  [call L35 → result L36]
+```
+
+Expand the suspicious step or every grouped event:
+
+```bash
+uv run yada-trace TRACE.jsonl --step 3
+uv run yada-trace TRACE.jsonl --verbose
+```
+
+Show the flat, line-prefixed event timeline when correlation itself is under
+investigation:
+
+```bash
+uv run yada-trace TRACE.jsonl --events
+```
+
+Then inspect exact records using the line references:
+
+```bash
+sed -n '31p' TRACE.jsonl
+sed -n '33,34p' TRACE.jsonl
+```
+
+Line references are physical, one-based JSONL lines. Blank lines count. The
+persisted `sequence` field is deterministic event order and is not assumed to be
+the physical line number.
+
+## Event lifecycle
+
+Yada stores one append-only JSON object per event:
+
+```text
+run_start
+  step 1..N
+    model_request ──→ assistant ──→ plan_decision
+          │                              ├─→ protocol_reminder
+          └─→ model_error                ├─→ protocol_violation
+                                         └─→ tool_call ──→ tool_result
+run_end
+```
+
+Every schema v2 record contains `schema_version`, `run_id`, `sequence`, UTC
+`timestamp`, `elapsed_ms`, `event`, and an event-specific `data` object.
+
+| Event | Meaning | Main correlation |
+| --- | --- | --- |
+| `run_start` | Task, workspace, model config, trace level, and provenance. | `run_id` |
+| `model_request` | Attempted model turn; debug adds `payload`. | `step`, `request_id` |
+| `assistant` | Model message, usage, metadata, finish reason, and latency. | `step`, `request_id` |
+| `model_error` | Model request exception instead of an assistant response. | `step`, `request_id` |
+| `plan_decision` | Deterministic interpretation of the assistant message. | `step` |
+| `protocol_reminder` | Text-only turn caused Yada to remind the model. | `step` |
+| `protocol_violation` | Tool batch rejected before side effects. | `step` |
+| `tool_call` | Parsed or rejected tool request. | `step`, `tool_call_id` |
+| `tool_result` | Structured outcome for one tool call. | `step`, `tool_call_id` |
+| `run_end` | Outcome, steps, usage, summary, and final Git state. | `run_id` |
+
+Several tool calls can belong to one step. A crash or transport exception may
+leave no `run_end`; the report marks that trace interrupted rather than treating
+it as success. It also shows missing responses or unmatched tool results.
+
+## Assistant response channels
+
+A DeepSeek assistant message can contain three different channels:
+
+- `reasoning_content`: thinking state;
+- `tool_calls`: requested actions;
+- `content`: optional narration or final user-facing text.
+
+During tool use, non-empty reasoning plus `content=""` is normal; the tool call is
+the action. Yada appends the complete assistant message before tool results so
+reasoning remains available on later tool-call turns.
+
+## Query raw JSONL
+
+Count event types:
+
+```bash
+jq -r '.event' TRACE.jsonl | sort | uniq -c
+```
+
+Read the exact sanitized request captured for step 12:
+
+```bash
+jq 'select(.event == "model_request" and .data.step == 12) | .data.payload' \
+  TRACE.jsonl
+```
+
+Inspect response channels:
+
+```bash
+jq 'select(.event == "assistant") |
+  {step: .data.step,
+   finish_reason: .data.finish_reason,
+   content: .data.message.content,
+   reasoning_content: .data.message.reasoning_content,
+   tool_calls: .data.message.tool_calls}' TRACE.jsonl
+```
+
+Find rejected tools and non-zero command exits:
+
+```bash
+jq 'select(.event == "tool_result" and
+  (.data.result.ok == false or ((.data.result.exit_code // 0) != 0))) |
+  {step: .data.step, tool: .data.tool, result: .data.result}' TRACE.jsonl
+```
+
+For `run_command`, `result.ok` means the Yada tool protocol completed; the child
+process can still have a non-zero `exit_code`. Check both.
+
+## Reproduce an evaluation failure
+
+The checked-in pytest case is the shared development baseline:
+
+```bash
+uv run yada eval \
+  --case benchmarks/swebench_verified/pytest-10051 \
+  --agent yada \
+  --yes \
+  --trace-level debug
+```
+
+Keep the case, model, endpoint, base commit, budgets, command policy, and network
+policy fixed when comparing a change. The result JSON records status and metadata;
+its sibling `.artifacts` directory contains the workspace, patch, grader output,
+and `yada-trace.jsonl`.
+
+The local case verdict is useful for development but is not an official
+SWE-bench score. Use the official Docker grader for published results; see the
+[`yada eval` reference](../cli-reference.md#yada-eval).
+
+## Common failure signals
+
+- **`DEEPSEEK_API_KEY is not set`**: export the key in the shell launching Yada.
+- **No request payload in a trace**: rerun with `--trace-level debug`.
+- **`finish` rejected**: run a successful `test` or `build` after the latest patch.
+- **Tool reports `ok` but tests failed**: inspect the command `exit_code`.
+- **No `run_end`**: the process was interrupted or raised outside a graceful path.
+- **Step limit reached**: inspect repeated reminders, failed tools, context growth,
+  and the final unfinished summary before increasing the limit.
+- **Patch rejected as stale**: the target changed after its last `read_file`; read
+  it again and build a patch against the new hash.
+
+## Report a reproducible issue
+
+Include:
+
+- the exact command with secrets removed;
+- Yada commit/version, OS, Python, and uv versions;
+- task or benchmark case ID and base commit;
+- expected and actual behavior;
+- the smallest relevant `yada-trace --step N` output;
+- referenced JSONL lines after manual secret/source review;
+- whether the failure reproduces with the checked-in baseline or an offline test.
+
+Do not publish API keys, authorization headers, private source, or unreviewed
+reasoning. The trace reader accepts legacy records, but a newer unsupported
+schema is rejected explicitly rather than guessed.
diff --git a/docs/evaluation.md b/docs/evaluation.md
deleted file mode 100644
index 4eba07b..0000000
--- a/docs/evaluation.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# Evaluation architecture
-
-Yada's evaluation package separates the coding agent from task preparation and
-grading. The agent receives only a public problem statement and a candidate Git
-workspace. The benchmark adapter owns repository provenance, hidden tests, and
-the final verdict.
-
-```text
-BenchmarkAdapter ── load/prepare ──┐
-                                  ├─ EvalRunner ─ result.json
-AgentAdapter ────── run/patch ─────┤
-                                  └─ BenchmarkAdapter.grade
-```
-
-The package has four stable data boundaries:
-
-- `EvalTask`: public issue text and non-secret metadata.
-- `PreparedTask`: an isolated candidate workspace.
-- `AgentRunResult`: patch, usage, steps, trace, and agent status.
-- `GradeResult`: benchmark-owned resolved, unresolved, skipped, or error verdict.
-
-`EvalRunner` composes adapters and writes a schema-versioned result even when an
-ordinary adapter error occurs.
-
-## Local manifests
-
-The local adapter is useful for a frozen task, private benchmark, or development
-smoke test. A version 1 manifest looks like this:
-
-```json
-{
-  "schema_version": 1,
-  "instance_id": "example__repo-1",
-  "task_file": "task.md",
-  "workspace": "candidate",
-  "workspace_mode": "copy",
-  "base_commit": "0123456789abcdef",
-  "grader": {
-    "argv": ["python", "grader.py", "{workspace}"],
-    "timeout_seconds": 1800
-  }
-}
-```
-
-Paths are resolved relative to the manifest. `workspace_mode=copy` verifies a
-Git fixture is clean and copies the complete fixture into the run artifact
-directory, including generated Git-ignored files required by its pinned
-environment. Repeated agents therefore do not mutate the source fixture. The
-grader runs only after the agent exits. Its return code means:
-
-- `0`: resolved
-- `1`: unresolved
-- any other value: grading error
-
-The grader command may use `{workspace}`, `{patch}`, `{run_dir}`, and `{run_id}`.
-
-### Portable cases
-
-`--case DIRECTORY` is shorthand for a local `DIRECTORY/case.json`. Unlike a
-machine-local fixture, a portable case can declare a Git source and a locked uv
-environment:
-
-```json
-{
-  "schema_version": 1,
-  "instance_id": "owner__repo-1",
-  "instance_file": "instance.json",
-  "workspace": {
-    "type": "git",
-    "url": "https://github.com/owner/repo.git",
-    "cache_key": "verified/owner__repo-1"
-  },
-  "base_commit": "0123456789abcdef",
-  "environment": {
-    "type": "uv",
-    "project": ".",
-    "install_workspace": "editable",
-    "pythonpath": ["src"]
-  },
-  "grader": {
-    "argv": [".venv/bin/python", "grader.py", "{workspace}"]
-  }
-}
-```
-
-The Git checkout is cached under `--cache-dir` (default
-`.yada/cache/evals`) and never used directly as the agent workspace. `uv sync
---locked` prepares the case environment. `install_workspace` supports modern
-`editable` projects and `legacy-editable` projects that predate PEP 660.
-`pythonpath` entries are resolved inside the fresh agent workspace. This makes
-the Agent's own test commands and the external grader use the same locked
-dependencies while exercising the modified source.
-
-The committed pytest development case runs with:
-
-```bash
-uv run yada eval \
-  --case benchmarks/swebench_verified/pytest-10051 \
-  --agent yada \
-  --yes
-```
-
-The outer `uv run` selects Yada's environment. The case's nested uv project
-selects the task environment; `yada eval` does not otherwise assume that every
-benchmark uses uv.
-
-## Agent adapters
-
-The native adapter constructs Yada in process and records a normal JSONL trace.
-Use `--trace-level debug` to capture sanitized provider payloads for replayable
-step inspection, then use `yada-trace PATH --step N` or `--verbose` to expand it.
-The default `summary` level keeps request storage compact.
-It respects step and output-token budgets. A deployment-level container or
-process supervisor should enforce the hard wall-time limit.
-
-The command adapter runs any non-interactive argv without a shell. Its template
-supports `{task}`, `{task_file}`, `{workspace}`, `{output_patch}`, and
-`{run_dir}`. If the external agent does not write `{output_patch}`, Yada collects
-the complete Git diff, including untracked files.
-
-Example:
-
-```bash
-yada eval \
-  --benchmark local \
-  --manifest /path/to/task.local.json \
-  --agent command \
-  --agent-name another-agent \
-  --agent-command 'another-agent run --task-file {task_file} --workspace {workspace}' \
-  --output results/another-agent.json
-```
-
-## SWE-bench
-
-The SWE-bench adapter can load public instance metadata from either:
-
-- a JSON/JSONL `--instance-file`; or
-- Hugging Face when the optional `datasets` package is installed.
-
-Gold patches, test patches, and hidden test IDs are discarded at the public task
-boundary. The adapter checks out only the exact base commit, writes the official
-three-field `predictions.jsonl`, and delegates grading to
-`swebench.harness.run_evaluation`.
-
-Install the official SWE-bench package and Docker separately. Then run:
-
-```bash
-yada eval \
-  --benchmark swebench \
-  --instance pytest-dev__pytest-10051 \
-  --instance-file benchmarks/swebench_verified/pytest-10051/instance.json \
-  --workspace /path/to/clean/pytest-base-repo \
-  --agent yada \
-  --yes \
-  --swebench-python /path/to/swebench-env/bin/python \
-  --output results/yada-pytest-10051.json
-```
-
-`--workspace` is an optional clean source repository. If omitted, the adapter
-fetches the exact commit from GitHub. This prepares the agent workspace; it does
-not replace the official Docker grading environment.
-
-Use `--grade-mode none` to validate task preparation and prediction generation
-without Docker. Such a run is `skipped`, never `resolved`.
-
-The checked-in local grader is a fast feedback loop, not an official
-SWE-bench result. Only the Docker Harness path should be used for published
-resolve rates.
-
-## Fair comparisons
-
-Use the same instance IDs, base commits, public issue text, model endpoint,
-token or cost budget, wall-time limit, network policy, and official grader for
-every agent. Tool sets may differ when comparing complete agent systems, but
-the result should say so. Run multiple trials when the model is stochastic.
-
-The primary metric is resolve rate. Steps, tokens, duration, and cost are
-diagnostic dimensions rather than substitutes for the benchmark verdict.
diff --git a/docs/tracing.md b/docs/tracing.md
deleted file mode 100644
index 301975b..0000000
--- a/docs/tracing.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Yada trace reference
-
-Yada records one append-only JSON object per line. JSONL is the durable source of
-truth: a completed write remains inspectable if the agent later crashes, and the
-file can be streamed with ordinary tools. `yada-trace` is the terminal view over
-that source data.
-
-## Record envelope
-
-Schema v2 records have these top-level fields:
-
-| Field | Meaning |
-| --- | --- |
-| `schema_version` | Integer format version. Current value: `2`. |
-| `run_id` | Correlates every record produced by one agent run. |
-| `sequence` | One-based event order within the run. |
-| `timestamp` | UTC ISO 8601 wall-clock timestamp. |
-| `elapsed_ms` | Milliseconds since the `TraceWriter` was created. |
-| `event` | Event type described below. |
-| `data` | Event-specific object. |
-
-Readers must ignore unknown `data` fields. Adding an optional field does not
-require a schema-version increase; changing or removing an existing field does.
-`TraceWriter` accepts extension event names, but the ten names below are Yada's
-core event vocabulary.
-
-## Lifecycle and correlation
-
-```text
-run_start
-  step 1..N
-    model_request ──→ assistant ──→ plan_decision
-          │                              ├─→ protocol_reminder
-          └─→ model_error                ├─→ protocol_violation
-                                         └─→ tool_call ──→ tool_result
-run_end
-```
-
-- `step` groups one model request, its response, planning decision, and tools.
-- `request_id` joins `model_request` to `assistant` or `model_error`.
-- `tool_call_id` joins each `tool_call` to its `tool_result` and to the next
-  request's `role=tool` message.
-- Multiple tool calls can occur in one step and retain model-provided order.
-- A transport exception or process interruption can leave a trace without
-  `run_end`. Readers should report this as interrupted, not successful.
-
-The reporting layer normalizes these records into `TraceRun`, `TraceStep`,
-`TraceToolExecution`, and `LocatedTraceEvent` objects. A located event pairs the
-unchanged persisted record with its physical JSONL line number. The public
-`read_trace()` API still returns the original event dictionaries; source location
-metadata is available through `read_located_trace()` and is never written back to
-JSONL.
-
-## Core events
-
-| Event | Cardinality and meaning | Important `data` fields |
-| --- | --- | --- |
-| `run_start` | Once, before the loop. | `model`, `task`, `workspace`, `max_steps`, `trace_level`, `model_config`, `provenance` |
-| `model_request` | Once per attempted model turn. | `step`, `request_id`, `context`; debug traces also contain `payload` and `capture` |
-| `assistant` | Once after a successful model request. | `step`, `request_id`, `duration_ms`, `message`, `usage`, response metadata, `finish_reason` |
-| `model_error` | Instead of `assistant` when a request raises. | `step`, `request_id`, `duration_ms`, `error_type`, `error` |
-| `plan_decision` | Once after each `assistant`. | `step`, `action`, ordered `tools`, `rejection_error` |
-| `protocol_reminder` | When the assistant returns no tool call. | `step`, `text` |
-| `protocol_violation` | When a tool batch is rejected before side effects. | `step`, `error`, `call_count` |
-| `tool_call` | Before every attempted tool execution. | `step`, `tool_call_id`, `tool`, `arguments`; invalid calls use `raw_arguments`, rejected calls use `rejected` |
-| `tool_result` | After every `tool_call`, including rejected calls. | `step`, `tool_call_id`, `tool`, `duration_ms`, `result` |
-| `run_end` | Once after a graceful terminal outcome. | `finished`, `steps`, `summary`, accumulated `usage`, `final_state` |
-
-`tool_result.data.result.ok` means that the Yada tool protocol completed. For
-`run_command`, a process can still have a non-zero `exit_code`; check both fields
-when looking for failures.
-
-## Assistant message fields
-
-An assistant response is a compound message:
-
-- `content` is optional user-facing narration.
-- `reasoning_content` is DeepSeek thinking state.
-- `tool_calls` contains requested actions.
-
-A tool-calling response commonly has non-empty `reasoning_content`, one or more
-`tool_calls`, and `content=""`. That is a valid model response: the tool call is
-the action for the turn. Yada appends the whole assistant message to the
-conversation so DeepSeek reasoning is available on subsequent tool-call turns.
-
-The DeepSeek adapter normalizes an omitted `role` to `"assistant"` and an omitted
-`content` to `""`. Use `finish_reason` and `tool_calls` to interpret an empty
-content value: on a tool-calling turn, the tool call is the model's action.
-
-## Capture levels and sensitive data
-
-`--trace-level summary` records event timing, response data, tool activity, and
-compact request-context metrics. `--trace-level debug` additionally records the
-sanitized provider request payload built by the same client method used for the
-HTTP request.
-
-Summary traces replace reasoning with its character count and SHA-256 digest.
-Debug traces automatically retain reasoning because it is essential for
-understanding intermediate tool-calling turns where `content` may be empty.
-API-key-like fields and bearer, token, password, credential, and secret text are
-redacted in both capture levels. Redaction does not make a trace public: debug
-traces can contain reasoning, prompts, source code, patches, paths, and test
-output.
-
-## Inspection recipes
-
-Default paths include a sanitized task name and the system-local time at minute
-precision. A direct run resembles
-`.yada/runs/fix-parser-boundary-issue__2026-08-02_20-26.jsonl`. An evaluation
-stores its trace under a directory such as
-`eval-results/pytest-dev__pytest-10051__2026-08-02_20-26.artifacts/`. When a
-default name already exists, Yada adds `(1)`, `(2)`, and so on before the output
-suffix. The result JSON and artifacts directory share the same number. Explicit
-`--trace`, `--output`, and `--artifact-dir` values are never renamed.
-
-Render a run summary or expand one step:
-
-```bash
-uv run yada-trace TRACE.jsonl
-uv run yada-trace TRACE.jsonl --step 12
-uv run yada-trace TRACE.jsonl --verbose
-uv run yada-trace TRACE.jsonl --events
-```
-
-The default view groups events by agent step. Step headings show the complete
-physical line range, model calls identify their request and response lines, and
-tool executions identify their call and result lines. Protocol reminders and
-violations also carry line references. Blank JSONL lines still count as physical
-lines, while `sequence` remains the deterministic event-order field; the two are
-not interchangeable. `--events` keeps the previous flat timeline shape and
-prefixes every event with its physical line.
-
-Once a report identifies a suspicious step or tool execution, inspect the exact
-source records directly:
-
-```bash
-sed -n '31p' TRACE.jsonl
-sed -n '33,34p' TRACE.jsonl
-```
-
-List event counts:
-
-```bash
-jq -r '.event' TRACE.jsonl | sort | uniq -c
-```
-
-Show the exact sanitized request payload captured for step 12:
-
-```bash
-jq 'select(.event == "model_request" and .data.step == 12) | .data.payload' \
-  TRACE.jsonl
-```
-
-Show the response channels for every model turn:
-
-```bash
-jq 'select(.event == "assistant") |
-  {step: .data.step,
-   finish_reason: .data.finish_reason,
-   content: .data.message.content,
-   reasoning_content: .data.message.reasoning_content,
-   tool_calls: .data.message.tool_calls}' TRACE.jsonl
-```
-
-Find rejected tools and commands with non-zero exit codes:
-
-```bash
-jq 'select(.event == "tool_result" and
-  (.data.result.ok == false or ((.data.result.exit_code // 0) != 0))) |
-  {step: .data.step, tool: .data.tool, result: .data.result}' TRACE.jsonl
-```
-
-## Compatibility
-
-The reader accepts legacy records and rejects schema versions newer than it
-understands. Event order and correlation identifiers are the replay contract;
-timestamps are diagnostic and should not be used to reconstruct missing events.
-Yada currently records enough data for deterministic inspection, not automatic
-re-execution of model or shell side effects.