# Documentation index

> **Repository-only paths.** Everything this index links to (except `docs/driving.md` and `docs/driving.zh.md`) lives in the repository and is **not published** with the package; a reader holding only the tarball needs `docs/driving.*`. This index itself is inside the tarball only because npm always packs files named `README` — it describes the repository, not the package.

Where each document lives, what language it is in, and whether it still describes the current build. Naming rule: `kebab-case`, with a `.zh` suffix when the text is Chinese (English carries no suffix). Superseded documents move to [`archive/`](./archive/) unchanged — the banner at the top of each one names what replaced it.

| Path | Language | What it is | Status |
|---|---|---|---|
| [design.zh.md](./design.zh.md) | zh | Design decisions and round-by-round history (M1 → fifth round) | Background; two claims it makes were reversed later — see its header |
| [standards.zh.md](./standards.zh.md) | zh | **提交之前必须成立的硬规则**（S1–S8）：假绿的三种形态、`node --check` 的边界、还债必须同提交改账本、`lib/` 与 `src/` 同步、类型基线、推送前的检查清单。每条都对应本项目真实发生过、且本可本地拦下的失败 | Active; read this before committing |
| [lessons.zh.md](./lessons.zh.md) | zh | **按 tag 取用的经验库**：14 个 tag（假绿、运行时引用、账本、CI 红循环、CI 延迟、真机强度分级、本机环境、协作…）。顶部有索引表，`grep '<tag>'` 定位后**只读那一节** | Active; read on demand |
| [patterns.zh.md](./patterns.zh.md) | zh | **三套对照装置**（故意红账本、故障可见性、差异账本）：每套的形状、规则本体住在哪个文件、被哪些真实帧逼成今天的样子，以及它治不了什么 | Active — 说明性文档，不被闸门当作判据读取；与它链接的文件冲突时以文件为准 |
| [CHECK-CATALOG.md](./CHECK-CATALOG.md) | en | The single inventory of every test, gate and manual pass: command, prerequisites, CI home, and what still needs a human | Active — added by #41, and it lists this index's own gate in bucket A |
| [GATE-MAP.md](./GATE-MAP.md) | zh | 门禁地图的阅读版：每道闸守哪类缺陷（A 宿主漂移 / B 不可能失败的断言 / C 输入形状与前端状态 / D 只在真机现形）、跑在哪台机器、红灯时按哪条线索归因；文末是装置体积红线（`test:apparatus-size`） | Active — 由阶段 0 的瘦身建立；改任何一道闸之前先在这里找它，找不到就说明它不守任何一类缺陷 |
| [runbook.zh.md](./runbook.zh.md) | zh | **维护者回路手册**：按"现在要做什么"组织的入口——日常 / 合并前 / 发布三个回路、说不得台账、节奏与交接。不复抄数字与清单，权威在 TESTING/GATE-MAP/CHECK-CATALOG | Active — 叙述性文档，不被闸门读取 |
| [translations/](./translations/) | 7 languages | The seven condensed translated READMEs (ja / ko / fr / de / es / pt / ru) — the original author's deliberate choice, kept in the repository. Since 0.7.10 they are **not installed**: the npm tarball carries English and Chinese only, and these seven are hand-kept with no gate watching (the docs-parity gate retired 2026-10-21) | Active |
| [compatibility-evidence.md](./compatibility-evidence.md) | en | Per-release verification evidence, appended run by run | Active |
| [issue-87-zh.md](./issue-87-zh.md) | zh | #87 的修复记录（外部贡献者 `nailongzhanshen666` 原文，逐字保留）：`{{cwd}}` 为什么在 0.2.x 是致命引用、为什么只有**三个**变体中招（`wsl-minimal` 带 `complete: true`，从不被追加）、以及这类"上游悄悄撤掉一个注册变量"的版本竞态该怎么复核 | Active — 叙述性记录，不被闸门当作判据读取。它文末提到的验证器 `verify-issue-87.mjs` 与 `asar-presets/` 留在贡献者本机、未随 PR 提交；本仓的等价装置已经落进 `tests/host-materialize.mjs`（见 CHECK-CATALOG 那一行），所以复跑不再需要仓外的东西 |
| [tty-triage.md](./tty-triage.md) | en | Triage sheet for `bash` calls: which symptom belongs to the pipe, to the pseudo-terminal, or to the host's PTY tier, with the one re-run that settles each | Active — every line it names is asserted by a cell in `scripts/compatibility/bash-session-real.mjs` |
| [bash-parity.md](./bash-parity.md) | en | The ledger of every difference between this plugin's session `bash` and the host's own `bash` tool, each row naming whose behaviour it is and what the user sees | Active — read by `tests/wsl-bash-parity.test.ts` and `scripts/compatibility/bash-parity-real.mjs`, which fail when a difference is undeclared or a declared one disappears |
| [CONSUMER-COVERAGE.md](./CONSUMER-COVERAGE.md) | zh | **消费方台账**：谁在我们生成的世界里、跨过我们切断的 realm，向 `fs`／`sandbox`／`shell`／`terminals` 伸手要服务。`未挂载`／`挂载未调用` 由派生判定，`已调用` 是唯一的人写断言且必须给可核对的凭据（`文件 :: 锚点`）；这张表存在的理由是**挂载过 ≠ 调用过**：本仓所有装置都从我们注册的工具进，#54/#78/#60 三条全是从宿主那一侧进来的 | Active — read by `tests/consumer-coverage.test.mjs`（在 `npm run test:node` 里——它读 `ci/deps` 那个钉住的宿主闭包，所以必须住在装了它的 job；放在 `test:unit` 时 ubuntu 上 `lint-build` 没有该闭包，闸的防空跑断言当帧就把桶选错报成红）；派生规则 `tests/support/consumer-ledger.mjs`。少一行、多一行、状态与引用该包的装置文件数不符、凭据锚点不在那个文件里、或未覆盖行数超过棘轮（今天 44/45），都变红 |
| [engineering-review-0.7.5.md](./engineering-review-0.7.5.md) | en | Point-in-time review of the `0.7.5` frame: findings graded by how they were measured, the end-to-end and silent-failure catalogues, and the ranked cost reductions | Snapshot at `c8c4185` — its 13 ranked reductions are re-audited against today's tree in [slimming-analysis-0.7.7.md](./slimming-analysis-0.7.7.md) §5 |
| [slimming-analysis-0.7.7.md](./slimming-analysis-0.7.7.md) | en | Where the bulk actually is, measured: the published tarball's composition (82% screenshots and a second copy of `src/`), the prose-vs-code growth of `src/`, the multi-home release narrative, and a re-audit of the 0.7.5 reduction list with 11 ranked actions | Snapshot at `a903147` — item 1 (the payload) is now #69; the rest remains analysis |
| [ci-speed-0.7.7.md](./ci-speed-0.7.7.md) | en | Where CI's minutes go, read from the Actions API's own timestamps: 96% of billed time in four windows jobs, and 215 s of one WSL1 job sitting in five cells that were waiting deadlines whose *length* was never the claim. The change that took 62 s off that step, measured on #172, and five options priced but not taken | Snapshot at frames #169–#68 — §2 and §3 are implemented and green on this branch; §1b/§1c record that the saving is a step-elapsed claim, not a wall-clock one, because run wall swings ±94 s across frames of the same code |
| [release-behaviour-matrix.zh.md](./release-behaviour-matrix.zh.md) | zh | **上线前必须在真 dsh 里逐条跑完的行为矩阵**：12 组、基准是"无故障原生 bash"而不是 dsh 里坏掉的 bash，每行只许落 MATCH / PARITY-NOT-DEFECT / DEFECT 三格；含取读数规程、发给 dsh 的话术、以及哪些行已经下沉成格子 | Active — read by `npm run test:matrix` (`scripts/check-release-matrix.mjs`): a row that lost a column, a verdict naming a row that does not exist, or a DEFECT with no ledger line turns that gate red, and its `--self-test` mutates four copies every frame so the gate cannot rot into an always-green one |
| [archive/publish-checklist.zh.md](./archive/publish-checklist.zh.md) | zh | One-off checklist for turning the plugin directory into a GitHub repo | Superseded 2026-09-30, kept verbatim |
| [archive/compatibility-summary-0.4.1.zh.md](./archive/compatibility-summary-0.4.1.zh.md) | zh | Compatibility conclusions as of 0.4.1 | Superseded 2026-09-30, kept verbatim |

## Outside `docs/`

| Path | Language | What it is |
|---|---|---|
| [README.md](../README.md) | en | Canonical entry point: install, declared compatibility, usage, current behaviour |
| [README.zh.md](../README.zh.md) | zh | Same content, Chinese — the two languages the installed package carries; the seven other translations live in [translations/](./translations/) |
| [CHANGELOG.md](../CHANGELOG.md) / [CHANGELOG.zh.md](../CHANGELOG.zh.md) | en / zh | Release history, newest first, every version |
| [TESTING.md](../TESTING.md) | en | How to verify a change or a release, with the fast path CI runs; the per-check inventory is [CHECK-CATALOG.md](./CHECK-CATALOG.md). Shipped in the npm tarball (`package.json` `files`), so it stays at the repository root |
| [LICENSE](../LICENSE) / [NOTICE](../NOTICE) | en | Licence text and the third-party attribution list |
| [src/client/locales.ts](../src/client/locales.ts) | zh + en | The dialog's "?" help panel: the product-side copy of usage and known limitations. Not prose documentation — it is what the shipped build renders, and its version label is hard-coded there |

## What keeps this honest

Two checks read the prose, and neither is optional:

- `node --test tests/readme-compat.test.mjs` — upstream of this index: both full READMEs must list exactly the releases `package.json` declares, and the READMEs plus the help panel must name the same repository the manifest does.
Retired 2026-10-21: `node scripts/check-docs-parity.mjs` (`npm run test:docs`) used to be this index's gate — declared README section names, the eight behaviour bullets, the language-neutral tool tokens, no stale claim in a translation, the link graph, and the CHANGELOG pair agreeing with `package.json`. The replay ruler showed none of the 20 real defects depends on it, so it was cut, and what that costs is stated here rather than discovered later: **the ten READMEs and the two CHANGELOGs are now kept in step by hand**. The part still under a gate is the narrow one in `node --test tests/readme-compat.test.mjs` (the release list and the repository name), which stays in `test:unit`.