docs: fix dead links, toolchain gaps, and document index (#402)

* docs: fix dead links, toolchain gaps, and document index

- Fix CHANGELOG dead links: docs/ARCHITECTURE.md -> docs/architecture/,
  and src/conf/kiwi.conf -> kiwi --sample-config generation
- Complete English README Prerequisites: add macOS cmake and full Linux
  C/C++ toolchain (clang, cmake, libclang-dev, llvm-dev, pkg-config);
  add Windows protoc parity note
- Unify docs/development.md Python integration test commands to
  `make -C tests install-deps` + `make -C tests test-python`
- Complete README documentation tables (en/cn): prd, quality-gates,
  personas, docs index, superpowers
- Add Implementation Status section linking code-review-findings.md
- Add docs/INDEX.md reading roadmap
- Fix placeholder image alt text in docs/key-encoding.md
- Include code-review-findings.md so the new status link resolves

* docs: correct documentation claims and commands

Remove the unverified review report and its authoritative-entry links. Correct sample-config redirection, isolated Python integration instructions, planning paths, design-history pairing guidance, and architecture links.

Tested: git diff --cached --check; local Markdown link target scan; bash -n on the committed integration-runner blob; changed-path ownership check.

Not-tested: Rust builds and tests were not rerun because this follow-up changes documentation only; the new Head will be validated by GitHub CI after push.

Co-authored-by: OmX <omx@oh-my-codex.dev>

---------

Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: AlexStocks

CHANGELOG.md

@@ -20,15 +20,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Recovery management for degraded storage states
   - Comprehensive health monitoring and statistics
   - Backpressure handling to prevent overload
-- Architecture documentation in `docs/ARCHITECTURE.md`
+- [Architecture documentation](docs/architecture/)
 - Runtime configuration options for thread pool sizing
 - Independent health checks for network and storage runtimes
 
 ### Changed
 
 - **BREAKING CHANGE**: Default port changed from `9221` to `7379` for Redis compatibility
   - The configuration system has been migrated to Redis-style format (similar to `redis.conf`)
-  - Configuration file moved from INI format to Redis-style format at `src/conf/kiwi.conf`
+  - Configuration file moved from INI format to Redis-style format; generate it with `kiwi --sample-config > kiwi.conf` (`kiwi --full-sample-config > kiwi.conf` for all keys), then start Kiwi with `kiwi --config kiwi.conf`
   - Default port is now `7379` (a Redis-compatible variant of the standard `6379` port)
 - **BREAKING CHANGE**: Storage initialization now requires `RuntimeManager::initialize_storage_components()`
   - Must be called after `RuntimeManager::start()` and before starting storage server
@@ -50,11 +50,11 @@ If you are upgrading from a previous version that used port `9221`:
    - Old format: `config.ini` with `port=9221`
    - New format: `kiwi.conf` with `port 7379`
 
-4. **Custom port configuration**: If you need to use a different port, update the `port` setting in `src/conf/kiwi.conf`:
-   ```conf
-   # Accept connections on the specified port, default is 7379.
-   # port 7379
-   port YOUR_CUSTOM_PORT
+4. **Custom port configuration**: If you need to use a different port, redirect the generated configuration to a file, update its `port` setting, and start Kiwi with that file:
+   ```bash
+   kiwi --sample-config > kiwi.conf
+   # Edit kiwi.conf and set: port YOUR_CUSTOM_PORT
+   kiwi --config kiwi.conf
    ```
 
 5. **Docker/Container deployments**: Update any port mappings from `9221` to `7379`
@@ -102,7 +102,7 @@ If you have custom code that integrates with Kiwi:
    - `channel_buffer_size` - Message channel buffer size
    - `request_timeout` - Default request timeout
 
-See `docs/ARCHITECTURE.md` for detailed architecture documentation.
+See the [architecture documentation](docs/architecture/) for details.
 
 ### Fixed
 

README.md

@@ -78,13 +78,19 @@ the project in addition to `protoc`. See the platform-specific commands in the
 # Install rustup; rust-toolchain.toml selects Rust 1.97.1 stable in this repo
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
-# protobuf compiler (macOS)
-brew install protobuf
+# macOS: Xcode CLT + protobuf compiler + CMake (required to build RocksDB from source)
+xcode-select --install
+brew install protobuf cmake
 
-# protobuf compiler (Linux)
-apt install protobuf-compiler
+# Debian/Ubuntu Linux: native C/C++ toolchain + protobuf compiler
+sudo apt install clang cmake libclang-dev llvm-dev pkg-config protobuf-compiler
 ```
 
+On Windows, use the same official Protobuf 27.1 release as CI. Download and
+extract `protoc-27.1-win64.zip`, add its `bin` directory to `PATH`, and run
+`protoc --version`. See the [development guide](docs/development.md#prerequisites)
+for the PowerShell commands.
+
 Dated nightly toolchains are reserved for specialized checks such as
 Sanitizers. They do not define the normal development or release baseline.
 
@@ -130,8 +136,13 @@ See [docs/cluster.md](docs/cluster.md) for the manual step-by-step procedure and
 | [System stability gate](docs/quality/system-stability-gate.md) | Required evidence before deferred hot-tier work can be reconsidered |
 | [Deferred native ABI contract](docs/architecture/redis-hot-tier-native-abi.md) | Future interface design; not an implementation authorization |
 | [Combined distribution licensing](docs/architecture/combined-distribution-licensing.md) | Future Redis-derived library and source-distribution obligations |
-| `kiwi --sample-config` | Generate a default config file |
-| `kiwi --full-sample-config` | Generate a config with all available keys |
+| [Product requirements (PRD)](docs/prd.md) | Goals, scope, and Redis 8.8.1 compatibility target |
+| [Engineering quality gates](docs/quality/quality-gates.md) | Code, test, and release quality gates |
+| [Personas and user stories](docs/personas-and-user-stories.md) | Target users and usage scenarios |
+| [Documentation index](docs/INDEX.md) | Map of the whole `docs/` tree and suggested reading order |
+| [Design plans & specs](docs/superpowers/) | Dated design records (plans + specs) |
+| `kiwi --sample-config > kiwi.conf` | Write the default configuration to `kiwi.conf` |
+| `kiwi --full-sample-config > kiwi.conf` | Write all available configuration keys to `kiwi.conf` |
 
 ## Dependencies
 

README_CN.md

@@ -137,8 +137,13 @@ redis-cli -p 7379 get foo         # "bar"
 | [系统稳定性门禁](docs/quality/system-stability-gate.md) | 重新评估延期热层工作前的 required 证据 |
 | [延期的 Native ABI 合同](docs/architecture/redis-hot-tier-native-abi.md) | 未来接口设计，不构成实现授权 |
 | [组合发行许可证设计](docs/architecture/combined-distribution-licensing.md) | 未来 Redis 派生库和源码发行义务 |
-| `kiwi --sample-config` | 生成默认配置文件 |
-| `kiwi --full-sample-config` | 生成包含所有配置项的完整配置文件 |
+| [产品需求文档 (PRD)](docs/prd.md) | 目标、范围与 Redis 8.8.1 兼容基线 |
+| [工程质量门禁](docs/quality/quality-gates.md) | 代码、测试与发布质量门禁 |
+| [人物角色与用户故事](docs/personas-and-user-stories.md) | 目标用户与使用场景 |
+| [文档索引](docs/INDEX.md) | 整个 `docs/` 树的地图与建议阅读顺序 |
+| [设计计划与规格](docs/superpowers/) | 带日期的设计记录（plans + specs） |
+| `kiwi --sample-config > kiwi.conf` | 将默认配置写入 `kiwi.conf` |
+| `kiwi --full-sample-config > kiwi.conf` | 将包含所有配置项的完整配置写入 `kiwi.conf` |
 
 ## 依赖说明
 

docs/INDEX.md

@@ -0,0 +1,75 @@
+# Documentation Index
+
+A map of the Kiwi documentation tree and a suggested reading order. If you are not
+sure where to start, follow the **Newcomer** path below.
+
+## Top-level entry points
+
+| Document | Audience | What it covers |
+|----------|----------|----------------|
+| [`README.md`](../README.md) / [`README_CN.md`](../README_CN.md) | Everyone | Project intro, features, quickstart, toolchain, and documentation entry points |
+| [`CLAUDE.md`](../CLAUDE.md) (a.k.a. `AGENTS.md`) | Contributors / AI agents | Dev commands, crate layout, code style, behavioral guidelines |
+| [`CONTRIBUTING.md`](../CONTRIBUTING.md) | Contributors | How to contribute |
+| [`CHANGELOG.md`](../CHANGELOG.md) | Everyone | Notable changes (history) |
+
+## Planning & requirements (source of truth for roadmap)
+
+The `.planning/` directory holds the north star, requirements, milestones, current
+state, and Kanban. These files are referenced from the README and the PRD and are
+the authoritative tracking surface:
+
+- `.planning/PROJECT.md` — constitution / north star
+- `.planning/REQUIREMENTS.md` — acceptance requirements (`REQ-*`)
+- `.planning/ROADMAP.md` — milestones (`M0`–`M10`)
+- `.planning/STATE.md` — current state
+- `.planning/KANBAN.md` — work board
+- `.planning/DECISIONS.md` / `.planning/OPEN_QUESTIONS.md` / `.planning/REFERENCES.md`
+
+## Developer docs
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/development.md`](development.md) | Dev environment, build optimization, sccache, lint rules, testing (incl. Python integration) |
+| [`docs/cluster.md`](cluster.md) | Raft cluster quickstart and write-path verification |
+| [`docs/key-encoding.md`](key-encoding.md) | Key/value encoding internals (Chinese, with diagrams) |
+
+## Product & compatibility
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/prd.md`](prd.md) | Product requirements; goals, scope, Redis 8.8.1 compatibility target |
+| [`docs/personas-and-user-stories.md`](personas-and-user-stories.md) | Target users and usage scenarios |
+| [`docs/compatibility/redis-8.8.1.md`](compatibility/redis-8.8.1.md) | Exact Oracle, raw RESP, TCL, and client-test boundaries |
+| [`docs/compatibility/redisraft-public-profile.md`](compatibility/redisraft-public-profile.md) | RedisRaft public compatibility profile |
+
+## Architecture
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/architecture/redis-8.8.1-system-boundaries.md`](architecture/redis-8.8.1-system-boundaries.md) | Cache OFF request, storage, and consensus boundaries |
+| [`docs/architecture/redis-hot-tier-native-abi.md`](architecture/redis-hot-tier-native-abi.md) | Deferred native ABI contract (future design, not an implementation authorization) |
+| [`docs/architecture/combined-distribution-licensing.md`](architecture/combined-distribution-licensing.md) | Future Redis-derived library and source-distribution licensing obligations |
+
+## Quality & stability
+
+| Document | What it covers |
+|----------|----------------|
+| [`docs/quality/system-stability-gate.md`](quality/system-stability-gate.md) | Required evidence (G1–G7) before deferred hot-tier work is reconsidered |
+| [`docs/quality/quality-gates.md`](quality/quality-gates.md) | Code, test, and release quality gates |
+| [`docs/performance/storage-runtime-baseline.md`](performance/storage-runtime-baseline.md) | Storage-runtime performance baseline |
+
+## Design history (`docs/superpowers/`)
+
+`docs/superpowers/plans/` and `docs/superpowers/specs/` contain **dated design
+records** (filename prefix `YYYY-MM-DD-`). They are historical decision logs, not
+a second roadmap. Follow related specs and plans by topic and by their explicit
+cross-references; dates do not define a one-to-one pairing. For the current
+authoritative plan, prefer `.planning/ROADMAP.md` and the gate documents above.
+
+## Suggested reading order
+
+- **Newcomer**: `README.md` → `docs/development.md` → `docs/cluster.md` → `docs/key-encoding.md`
+- **Contributor**: `CLAUDE.md` → `docs/development.md` → `docs/quality/quality-gates.md`
+- **Architecture / compatibility**: `docs/prd.md` → `docs/compatibility/redis-8.8.1.md` → `docs/architecture/redis-8.8.1-system-boundaries.md`
+- **Stability & quality**: `docs/quality/system-stability-gate.md` → `docs/quality/quality-gates.md` → `docs/performance/storage-runtime-baseline.md`
+- **Design history**: `docs/superpowers/plans/` + `docs/superpowers/specs/` (follow by topic and explicit cross-references)

docs/development.md

@@ -172,17 +172,24 @@ cargo test --package storage      # tests for a specific crate
 cargo test test_redis_mset        # run a single test by name
 ```
 
-Python integration tests require a running Kiwi server:
+The Python integration runner starts an isolated Kiwi server on `127.0.0.1:6379`,
+runs the test suite against it, and stops the server afterward:
 
 ```bash
-# Terminal 1
-cargo run --bin kiwi
+# Build the debug binary used by the runner and install the test dependencies
+cargo build --bin kiwi
+make -C tests install-deps
 
-# Terminal 2
-pip install redis pytest
-pytest tests/python/ -v
+# Start the isolated server and run the Python integration suite
+./tests/run_python_integration.sh
 ```
 
+`make -C tests install-deps` installs the version-constrained dependencies from
+`tests/python/requirements.txt`. The runner sets `KIWI_TEST_REQUIRE_SERVER=1` and
+`KIWI_TEST_ISOLATED_SERVER=1` so tests cannot silently pass by skipping server-
+dependent cases. See [tests/README.md](../tests/README.md) and
+[tests/NEW_TESTS_GUIDE.md](../tests/NEW_TESTS_GUIDE.md) for details.
+
 Storage tests use `tempfile::tempdir()` for isolated RocksDB instances.
 
 ## Gotchas

docs/key-encoding.md

@@ -7,13 +7,13 @@
 ## String 结构的存储
 
 
-![img.png](images/01-string编码.png)
+![String 编码结构](images/01-string编码.png)
 
 ## Hash 结构的存储
 
 Hash 类型数据结构由两部分构成，元数据（meta_key，meta_value）和普通数据（data_key，data_value）。每个 Hash 类型数据对应一条元数据，每个 field 对应一条普通数据。具体格式如下图所示。
 
-![img.png](images/01-hash编码.png)
+![Hash 编码结构](images/01-hash编码.png)
 
 元数据中的 key 由前缀保留字段，编码后的 user key 以及后缀保留字段构成，value 中记录了 hash 中元素个数，最新版本号，保留字段，数据写入时间以及数据过期时间。version 字段使用 u64 little-endian 编码，并用于实现秒删功能。
 
@@ -29,13 +29,13 @@ Hash 类型数据结构由两部分构成，元数据（meta_key，meta_value）
 
 set 结构与 hash 类型的存储格式基本相同，也是由元数据和普通数据两部分构成。不同的是，set 类型由于没有 value字段，所以其 data value 中只需要记录保留字段和数据写入时间即可。具体格式如下所示：
 
-![img.png](images/01-set编码.png)
+![Set 编码结构](images/01-set编码.png)
 
 ## List 结构的存储
 
 list 由两部分构成，元数据(meta_key, meta_value), 和普通数据(data_key, data_value)。 元数据中存储的主要是 list 链表的一些信息， 比如说当前 list 链表结点的的数量以及当前 list 链表的版本号和过期时间(用做秒删功能), 还有当前 list 链表的左右边界, 普通数据实际上就是指的 list 中每一个结点中的数据，作为具体最后 RocksDB 落盘的 KV 格式，具体格式如下所示：
 
-![img.png](images/01-list编码.png)
+![List 编码结构](images/01-list编码.png)
 
 元数据中记录了一个 list 的信息，包括 list 元素个数，左右边界 Index，最新 version以及数据写入时间和过期时间。普通数据的 key 拼接了 list key 和 Index，value 记录用户写入数据以及写入时间。
 
@@ -47,7 +47,7 @@ list 由两部分构成，元数据(meta_key, meta_value), 和普通数据(data_
 
 zset 由两部分构成，元数据(meta_key, meta_value) 和普通数据(data_key, data_value)。元数据中存储的主要是 zset 集合的一些信息，比如当前 zset 集合中 member 的数量以及当前 zset 集合的版本号和过期时间（用于秒删功能），而普通数据就是指 zset 中每个 member 以及对应的 score。由于 zset 这种数据结构比较特殊，需要按照 member 排序，也需要按照 score 排序，所以我们会按不同格式存储两份普通数据，在这里称为 member to score 和 score to member。作为最终 RocksDB 落盘的 KV 格式，具体如下：
 
-![img.png](images/01-zset编码.png)
+![ZSet 编码结构](images/01-zset编码.png)
 
 Meta KV 记录的是一个 zset 的元信息，包括集合元素个数，最新版本号，数据写入时间以及数据过期时间。对 zset 类型数据的读写删除操作都需要先获取元数据。