docs: split README — move Architecture & Why into decentralized docs

[zackees]

Summary

The top-level README.md is 1201 lines. The first 140 lines are a wall of per-platform build-status badges. Deep-in-the-file sections (## Architecture at line 932, # Why at line 1179, ## Key Benefits at 915, ## Project Structure at 1081) bury the action-oriented content humans and agents actually need first: install, examples, CLI usage, platformio.ini reference.

Proposal

Split the README and ship a decentralized docs index that both humans and LLM agents can navigate quickly.

Main README (keep)

• Project name + one-line pitch
• Badges (collapsed into a single "CI status" row; move the per-platform board matrix behind a collapsed <details> or into docs/BOARD_STATUS.md)
• Quick Start (install → first build → first deploy → first monitor)
• Examples
• CLI Usage (top-level only; defer sub-flag detail to docs/cli/)
• platformio.ini reference summary with a link to docs/config/platformio-ini.md
• Links to the decentralized docs

Move out of README

• ## Architecture (line 932) → merge into docs/architecture/ (already exists). Extract anything not already covered and retire the top-level duplicate.
• ## Key Benefits + ## Performance (transparency/reliability/speed/etc.) → docs/WHY.md or fold into docs/DESIGN_DECISIONS.md as a "Philosophy" section.
• # Why (line 1179) → same destination as above.
• ## Project Structure (line 1081) → crates/CLAUDE.md already has the canonical dependency graph. Link to it instead.
• ## Testing, ## Troubleshooting, ## Development → docs/DEVELOPMENT.md (new).
• Per-platform build status (lines 19–109) → docs/BOARD_STATUS.md with the live matrix and a one-line link from the main README.

Discoverability (the important part)

Build a single docs/INDEX.md that both humans and agents can grep:

| Question                              | File                                |
|---------------------------------------|-------------------------------------|
| How do I install fbuild?              | README.md#install                   |
| Why does fbuild exist?                | docs/WHY.md                         |
| What's the crate dependency graph?    | crates/CLAUDE.md                    |
| How does the daemon work?             | docs/architecture/runtime.md        |
| Why did we choose X over Y?           | docs/DESIGN_DECISIONS.md            |
| Is my board supported?                | docs/BOARD_STATUS.md                |
| How do I add a new board?             | docs/contributing/adding-a-board.md |
| ...                                   | ...                                 |

The existing docs/CLAUDE.md already does this for architecture docs — generalize the same pattern across all doc types.

Recruit a README agent

Add a small .claude/agents/docs-maintainer.md (or a /docs skill) that:

• Knows the decentralized layout.
• Enforces the split: refuses to add Architecture/Why content back into the top-level README.
• On every PR that edits docs/, auto-rebuilds docs/INDEX.md.
• Can be invoked as Agent(subagent_type=\"docs-maintainer\", ...) for future doc reorgs.

Acceptance criteria

• Main README.md is under 400 lines and leads with install + Quick Start.
• No content is lost — every section removed from README lives somewhere under docs/ and is linked from docs/INDEX.md.
• docs/INDEX.md exists and answers the top ~15 FAQ-style questions with direct links.
• docs/CLAUDE.md cross-references docs/INDEX.md so the LLM path and human path converge.
• A /docs skill or docs-maintainer agent is added under .claude/ so future doc edits stay consistent.
• CI: add a simple markdown-link checker (lychee or similar) so moved links don't rot.

Non-goals

• Rewriting the content itself. This is a restructuring issue, not a content-quality issue.
• Changing CLAUDE.md semantics — it stays as the LLM-entry file at repo root.