# Brief: rewrite `docs/Disaggregated/` into a clear, concise design + architecture document set

## The user's instruction (verbatim, this is the goal)
"make documentations in `docs/Disaggregated` clear and concise. Make it just clearly describe the design and architecture, rather than decision dilemmas."

## What exists today (branch `feat/disaggregated`, WSL tree `~/w7/pipe`, HEAD 458ccde1)
- `docs/Disaggregated/PLAN.md` (~312 KB, Chinese): the single implementation plan for MGPipe — the gallium-style explicit frontend/backend interface + backend-owned state machine + two-process split. It grew out of a design competition and three adversarial review rounds, so it is full of "v1 said X, v2 corrected to Y", "（P0 实测修正）…" patches, rejected alternatives, risk tables arguing with reviewers, and "待证/已证" bookkeeping. The design itself is settled; the prose is not.
- `docs/Disaggregated/REVIEW.md`: the design-competition and adversarial-review record.
- `scripts/check_doc_citations.py`: CI lint (job `pipe-gates` in `.github/workflows/test.yml`) that requires every `file:line` citation in `docs/Disaggregated/*.md` to resolve on the baseline commit. Run it and keep it green (read the script for its exact contract, base commit and invocation; `python3 scripts/check_doc_citations.py --help` or read the CI job).
- Code that already exists and that the docs must describe accurately (read it, do not guess): `MobileGL/MG_Pipe/` (PipeCalls.def — 71 calls after P-2 — MGPipeTypes.h, MGPipeHandles.h, MGPipeCallbacks.h, MGPipeHostSpan.h, MGPipe.h, Coverage.def, generated/), `scripts/gen_pipe.py`, `scripts/gen_pipe_dirty_surface.py`, `scripts/gen_protocol.py`, `MobileGL/MG_Remote/{Protocol,Transport}` (protocol.fbs, Ring/RingControl, Doorbell, ShmSegment, FdPassing, InProcessTransport, Framing), `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}`, ConfigLoader's `MOBILEGL_PIPE_*` knobs, `tools/spikes/{server_stub,extmem_probe}`, `MobileGL/MG_Test/Pipe`, `MobileGL/MG_Test/Wire`, `MobileGL/MG_Test/Util/PipeStatsTest.cpp`.
- Measured facts from P0 (these replace every "待证 / 设备锁 / 欠着" sentence in the current PLAN.md): read `<this directory>/p0-device-findings.md` — spike A (exec a second native binary from the app's own `untrusted_app` process) is proven on both devices; spike B's external-memory tiers per device; the on-device MGPipe stats baselines (accessor calls per draw, bytes per frame per class, upload shapes, memo gates) for four traces on both backends; the harness facts (JSON dump never fires on device, `MOBILEGL_PIPE_STATS_PERIOD`, serial device runs); and that the create-indirect fixture's failure on Adreno 830 is pre-existing at `dev@81b17c0b` (verified with a baseline APK), i.e. not caused by this branch.

## What to produce
Rewrite `docs/Disaggregated/` so a reader who has never seen the reviews can understand the design and the architecture and go implement the next phase. Chinese, same as today (technical identifiers in English). Suggested shape — adjust if the material argues for something else, but keep it small:
1. `README.md` — one page: what MGPipe is, the one-paragraph architecture (client tracker → MGPipe verbs → server object table → backend; monolith vs split build shapes), the status line (P0 landed at 458ccde1; P0.5/P1/P2 next; GO/NO-GO at day 43), and a map of the other files.
2. `ARCHITECTURE.md` — the design as decided: handles and generations; the call catalogue by group (screen / ctx-query / CSO / state / object / verb) and the record layout conventions (payload structs, var-tails, host spans, chunking bound = half the ring); render state as blob + CSO identity subset + `set_dynamic_state`; push-at-validate; texture subdata accumulation and `resource_subdata` (union box + region list); shader state = SPIR-V + reflection (the P0.5 header extraction it depends on); the reverse channel (callbacks + `resource_subdata_complete`); persistent maps and the external-memory tiers as measured; restart rewrite / multi-draw tiering on the server with the index host mirror; the transport (SPSC shm ring, RingControl cursors, doorbells, FlatBuffers control plane, SCM_RIGHTS, present credit); process/EGL/Android delivery (lib*.so executable, fork+execve, marker files); build shapes and purity gates; the verification strategy (PipeInputs strangler, `MOBILEGL_PIPE_VERIFY`, generation poison, the CI gates that exist). State each decision as a decision with its one-line reason; do NOT reproduce the dilemma, the rejected options or the review argument. Where a number justifies a decision, cite the measured number (from the findings file or PLAN.md's measured sections), not the estimate it replaced.
3. `ROADMAP.md` — phases P0…P13 as a compact table (what lands, acceptance gate, dependency), the day-43 GO/NO-GO criteria as a checklist, and the genuinely open questions as a short list (drop the ones P0 answered).
4. `MEASUREMENTS.md` (or a section) — the P0 baselines and spike results as tables, with the exact device / commit / command so they can be reproduced.
5. Delete `REVIEW.md` from this directory (the review record lives in git history: mention the commit range in README). Delete `PLAN.md` once its content is fully carried over — nothing that is still true and still needed may be lost, so do the carry-over section by section and keep a checklist in your notes; what is lost on purpose is the dilemma prose, superseded estimates, "v1/v2" archaeology and reviewer back-and-forth.
6. Every `file:line` you keep or add must be verified against the tree (open the file, check the line) and must pass `scripts/check_doc_citations.py`. Prefer citing a symbol name plus file over a raw line number when the doc will outlive the line.

## Constraints
- Docs only. Do not touch code, scripts, workflows or tests (the citation checker's config is the one exception if a deleted file name must be dropped from it — then say so).
- Work in a git worktree: `cd ~/w7/pipe && git worktree add ~/w7/p0-docs -b p0/docs-rewrite feat/disaggregated`. Commit there in one or a few commits; do not push. Commit message: single-line subject `[Docs] (Disaggregated): …` + blank line + `- ` bullets; no Co-Authored-By.
- Long outputs go to files, never into your return value: write your carry-over checklist to `~/w7/p0-docs-notes.md` and return only the branch name, commit hashes, the doc file list with sizes, the citation-check result, and anything you deliberately dropped that a reader might miss.
- Keep it concise: the target is roughly a quarter of today's volume or less. Concise means no repetition and no argument, not omitted design.