From 9a81c993abb23de3be1fe671fb373ebe650c5563 Mon Sep 17 00:00:00 2001
From: Gahow Wang <gahow.wang@gmail.com>
Date: Tue, 12 May 2026 23:58:56 +0800
Subject: [PATCH] docs(onboarding): link new audit / design / eval docs from
 the root README + AGENTS.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Without this, the four docs added on this branch
(AUDIT_AND_ROADMAP, INDEX, BLOCK_LEVEL_EVICTION_DESIGN,
D_TO_P_SYNC_CONTRACT, EVALUATION_PROTOCOL) are reachable
only by listing docs/. This wires them into the two entry
points an agent or collaborator hits first.

README.md changes:
  - top-of-page pointer to INDEX_ZH for new collaborators
  - pointer to AUDIT_AND_ROADMAP_ZH for project state
  - "单元测试 (无 GPU)" section: how to run pytest
  - "评测脚本" section: invocations for the two new
    analysis scripts

AGENTS.md changes:
  - top section "For new collaborators / agents" before
    the existing "Environment" block, pointing at INDEX_ZH,
    AUDIT_AND_ROADMAP_ZH, the two ready-to-pick-up design
    docs, and EVALUATION_PROTOCOL_ZH
  - pytest invocation under Environment
---
 AGENTS.md | 24 ++++++++++++++++++++++++
 README.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index d6b696a..8cf9eb9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,9 +1,33 @@
 # AGENTS.md
 
+## For new collaborators / agents
+
+Before doing anything else, read [docs/INDEX_ZH.md](docs/INDEX_ZH.md). It points to the
+3 must-read docs and a role-based reading path (new SWE, paper reviewer,
+reproducing student, control-plane reader).
+
+Cross-branch progress, weaknesses, and roadmap live in
+[docs/AUDIT_AND_ROADMAP_ZH.md](docs/AUDIT_AND_ROADMAP_ZH.md). It is the single source of truth
+for "what's done, what's broken, what to do next."
+
+Two engineering work items are pre-specced and ready to pick up:
+- block-level eviction refactor — [docs/BLOCK_LEVEL_EVICTION_DESIGN_ZH.md](docs/BLOCK_LEVEL_EVICTION_DESIGN_ZH.md)
+- D→P incremental KV sync — [docs/D_TO_P_SYNC_CONTRACT_ZH.md](docs/D_TO_P_SYNC_CONTRACT_ZH.md)
+
+Evaluation protocol (paper-quality N, paired CI, stratification,
+baselines) is in [docs/EVALUATION_PROTOCOL_ZH.md](docs/EVALUATION_PROTOCOL_ZH.md).
+
 ## Environment
 
 Use `uv` to manage all python environment. `uv add` to manage deps so that we can `uv sync` to get exactly same runnable environment each time.
 
+Algorithm-layer unit tests (no GPU, no SGLang):
+
+```bash
+uv sync --group test
+uv run pytest
+```
+
 ## Goal
 
 Build a minimal prototype on top of **SGLang xPyD** to test whether **session-aware / KV-cache-aware P/D routing** can improve **end-to-end latency** for agentic coding workloads.
diff --git a/README.md b/README.md
index 63e3193..5932800 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,9 @@
 
 更完整但仍然简洁的说明见 [docs/PROJECT_OVERVIEW.md](docs/PROJECT_OVERVIEW.md)。
 
+新加入的合作者：先看 [docs/INDEX_ZH.md](docs/INDEX_ZH.md)，按"我是谁"选 3 篇必读文档。
+项目当前进度、薄弱点、路线图总览见 [docs/AUDIT_AND_ROADMAP_ZH.md](docs/AUDIT_AND_ROADMAP_ZH.md)。
+
 ## 当前做了什么
 
 - 启动单机 SGLang P/D 栈。
@@ -99,3 +102,28 @@ uv run agentic-pd-hybrid replay \
 - SGLang 改动：`feat(sglang): ...` / `fix(sglang): ...`。
 - `third_party/sglang` 的基线是 clean SGLang `v0.5.10` snapshot。
 - 不提交 `outputs/`、日志、`__pycache__`、虚拟环境。
+
+## 单元测试（无 GPU）
+
+算法层（policies、Algorithm 1 / Theorem 1）有 pure-Python 单测，跑测试不需要 GPU、不需要 SGLang：
+
+```bash
+uv sync --group test
+uv run pytest
+```
+
+详见 [tests/README.md](tests/README.md)。
+
+## 评测脚本
+
+按 [docs/EVALUATION_PROTOCOL_ZH.md](docs/EVALUATION_PROTOCOL_ZH.md) 跑数据后：
+
+```bash
+# M3: 按 turn_id / input_length / overlap_ratio / append_tokens 分桶
+scripts/analysis/stratified.py outputs/<run>/request-metrics.jsonl
+
+# M2: paired-on-same-trial bootstrap 95% CI
+scripts/analysis/paired_compare.py \
+    --baseline outputs/run-dp/request-metrics.jsonl \
+    --candidate outputs/run-kvc/request-metrics.jsonl
+```