Restructure the documents for regular user and dev user

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.

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)。