mirror of
https://github.com/ranxianglei/billion-context.git
synced 2026-11-21 17:37:42 +08:00
[PR] fix: #7156 storage-corruption fallout — webSummaryRows json_valid guard, .chk close-time gate, first-write corruption classification
Documentation
All system documentation for billion-context lives in this directory. The repo root keeps only four core entry files — README.md, README.zh-CN.md, AGENTS.md, CHANGELOG.md — and recognized community-maintained README translations (README.<locale>.md, e.g. README.ja.md, approved 2026-11-09, #6000). Former root doc paths keep one-line redirect stubs at the root (tracked in lifecycle §5).
Full catalog: index.md / index.zh-CN.md — every doc with a one-line description. This page is the directory landing: where things are and which rules keep them live.
Sections
| Section | Docs | What you'll find |
|---|---|---|
| Start here | configuration · clients · how-it-works | Full configuration reference (generated, drift-guarded) · per-client integration deep dives · one diagram of the whole flow |
| System architecture | architecture / 中文 | LIVE hub: overall diagram + one page per module (pipeline / lanes / kernel / identity / fastpaths / storage / webui / update), each with its own diagram — freshness is CI-enforced (architecture-docs lane) |
| Identity & protocol | message-identity · session-identity · session-identity-resolution · identity-channels · msgid-infrastructure · opencode-responses-websocket · plugin-protocol | The identity doctrine (msg id, session id, persona forks, the #5825 channel wiring) and per-client protocol notes |
| Engineering & operations | technical-notes · lifecycle · auto-merge-guardrails · unified-loop-spec | Mechanism deep-dives · the transition/retirement ledger (CI-enforced) · the evidence appendix behind AGENTS.md §7 · historical design (superseded by code) |
Rules of the road (why this directory stays readable)
- Bilingual by default — English base name +
*.zh-CN.mdmirror; a single-language doc must say why in its index entry. - Every new or moved doc is listed in index.md + index.zh-CN.md in the same PR — an unlisted doc does not exist.
- Architecture docs are LIVE — structural changes update the affected page, diagram, and hub ledger row in the same PR; CI lane
architecture-docsenforces the mechanical parts. - Procedures live in
../reference/, not here —docs/is decision/reviewer-facing reference;reference/holds the lazy-loaded how-to material (testing / release / git-pr / env-vars / the KDD full-text ledger). - Moves leave a stub — a one-line redirect at the old path + a hygiene-ledger entry in lifecycle.md §5 with an explicit removal condition.
The authoritative wording of these rules: AGENTS.md §3 "Documentation Layout".