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

[AlexStocks]

Summary

Documentation maintenance fixes based on a full review of the Kiwi doc tree. No code changes.

Dead links fixed (P0)

• CHANGELOG.md: docs/ARCHITECTURE.md → docs/architecture/ (×2); src/conf/kiwi.conf → kiwi --sample-config generation (×2). Neither docs/ARCHITECTURE.md nor src/conf/kiwi.conf exists in the repo.

Toolchain completeness (P0)

• README.md (English) Prerequisites was missing macOS cmake and the entire Linux C/C++ toolchain, which would break the from-source RocksDB build. Now matches the Chinese README (brew install protobuf cmake + sudo apt install clang cmake libclang-dev llvm-dev pkg-config protobuf-compiler), and adds a Windows protoc parity note.

Consistency (P1)

• docs/development.md: Python integration test commands updated to the project-canonical make -C tests install-deps + make -C tests test-python (was the outdated pip install redis pytest + pytest tests/python/).
• README.md / README_CN.md Documentation tables: added missing rows for docs/prd.md, docs/quality/quality-gates.md, docs/personas-and-user-stories.md, docs/INDEX.md, and docs/superpowers/.
• Added an "Implementation Status" section to both READMEs linking code-review-findings.md, making that previously-unreferenced review record discoverable and clarifying that Redis 8.8.1 compatibility is an in-progress goal.

Discoverability / hygiene (P2)

• Added docs/INDEX.md — a map of the whole docs/ tree with a suggested reading order by audience.
• Fixed placeholder img.png alt text in docs/key-encoding.md.
• Committed code-review-findings.md (was untracked) so the new status link resolves.

Test plan

• grep confirms zero remaining docs/ARCHITECTURE.md / src/conf/kiwi.conf references across all .md.
• README tables verified free of duplicate rows.
• CI lint/link check (if any) passes.

🤖 Generated with WorkBuddy

Summary by CodeRabbit

• Documentation
  • Added a centralized documentation index covering requirements, architecture, development, quality, and design resources.
  • Expanded setup guidance for macOS, Debian/Ubuntu, and Windows environments.
  • Clarified sample configuration commands and custom port migration instructions.
  • Updated Python integration testing instructions with an automated build, dependency installation, and isolated server workflow.
  • Improved architecture references and replaced ambiguous image filenames in encoding documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request updates project documentation, configuration instructions, platform prerequisites, the documentation index, Python integration-test workflow, migration guidance, and encoding diagram references.

Changes

Documentation Updates

Layer / File(s)	Summary
Configuration and architecture guidance CHANGELOG.md, README.md, README_CN.md	Configuration instructions now show generated kiwi.conf files and custom-port migration steps. Architecture references point to docs/architecture/.
Documentation index and build prerequisites README.md, README_CN.md, docs/INDEX.md	README files add platform-specific build prerequisites and project documentation links. docs/INDEX.md organizes documentation categories and recommended reading paths.
Developer workflow and encoding references docs/development.md, docs/key-encoding.md	Python integration testing now uses the Kiwi build and test runner. Encoding diagrams use descriptive image filenames.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• arana-db/kiwi#303: Related README, development-guide, and key-encoding documentation updates.
• arana-db/kiwi#387: Related correction to use the kiwi binary in integration-test instructions.

Suggested labels: 📒 Documentation, 🧹 Updates

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the changes and test plan, but it omits the template's required Description, Type of Change, Checklist, and Additional Context sections.	Add the required template headings, select Documentation update, complete the checklist, and state the issue or mark it as not applicable.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the documentation changes, including dead-link fixes, toolchain updates, and the documentation index.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/fix-doc-links-and-consistency

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 105: Update the architecture reference in CHANGELOG.md to use clickable
Markdown link syntax targeting docs/architecture/. Preserve the existing wording
while making the documentation directly navigable.

In `@code-review-findings.md`:
- Around line 4-5: Align the review scope and completion statements in
code-review-findings.md: make the crate list match the claimed 13-crate
coverage, and update the section around the Raft-focused review so it no longer
both omits raft and marks that review as pending. If Raft was not reviewed,
narrow the overall scope and completion claims consistently instead.
- Around line 1-5: Make the dated-record claim accurate by adding explicit
review or update date metadata near the title in code-review-findings.md. In
README.md lines 63-66 and docs/INDEX.md lines 10-15, retain the “dated” wording
only when referring to that metadata; otherwise remove or revise the wording so
both descriptions match the source document.

In `@docs/INDEX.md`:
- Around line 22-27: Update the planning-file list in the documentation index so
both OPEN_QUESTIONS.md and REFERENCES.md use the .planning/ prefix, matching
DECISIONS.md and all other entries. Preserve the existing descriptions and
formatting.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d4aeb36-948e-44d4-90ad-303e56230429

📥 Commits

Reviewing files that changed from the base of the PR and between cbc2895 and c1f0f9d.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• README_CN.md
• code-review-findings.md
• docs/INDEX.md
• docs/development.md
• docs/key-encoding.md

[coderabbitai]

🧹 Nitpick comments (1)

README.md (1)

144-145: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep sample-configuration commands separate from document links.

Both README files place shell commands in tables labeled for documents. Use a dedicated configuration subsection and code block, or rename the table schema to support mixed resources.

• README.md#L144-L145: move the two sample-configuration commands to a dedicated configuration section.
• README_CN.md#L145-L146: apply the same structural change in the Chinese README.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 144 - 145, Move the sample-configuration command
entries from the document-links table into a dedicated configuration subsection
or code block in README.md (lines 144-145) and README_CN.md (lines 145-146),
preserving both commands and their descriptions while keeping the document
tables limited to document links.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@README.md`:
- Around line 144-145: Move the sample-configuration command entries from the
document-links table into a dedicated configuration subsection or code block in
README.md (lines 144-145) and README_CN.md (lines 145-146), preserving both
commands and their descriptions while keeping the document tables limited to
document links.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 73a5345c-542e-4cdb-ad52-9f361fa6ee72

📥 Commits

Reviewing files that changed from the base of the PR and between c1f0f9d and 9833548.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• README_CN.md
• docs/INDEX.md
• docs/development.md

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/INDEX.md
• CHANGELOG.md