Redesign the README and developer-facing docs for the Public Alpha, with status-tagged feature and provider matrices (LAUNCH-C)

Read AGENTS.md and docs/README.md first, then compare README.md, docs/usage.md, docs/configuration.md, docs/development.md, autoforge.example.yaml, and ADR 0008 against the issue’s verified baseline. Check provider defaults against default_config() and doctor, and trace each feature row to its evidence and dependencies. Done means the matrices, links, accuracy sweep, and release checklist meet the acceptance criteria and make check passes.

Artifact: implementation-ready issue (LAUNCH-C of the Public Alpha EPIC #255). This issue body is the authoritative copy; the working copy was drafted in the maintainer's local session scratchpad and is not kept elsewhere. Baseline: main at 711ff09, read on 2026-10-21 (UTC). Planning created this issue only: no code, branch or PR.

Parent: #255 · Priority: P0 · Gate: 6 (Documentation accuracy) · Blocked by: #240, #259, #260 [native] · Blocks: #263 [native]

Summary

Make the repository understandable in about a minute and actionable in about five, without overstating anything. A visitor should learn what AutoForge is, why it differs from running one agent, what works today, what is experimental, how to try it, and where its limits are — and every one of those statements must match main.

Verified current state (711ff09)

• README.md (382 lines) is accurate and candid but written for an operator who already knows the project: it opens with a "Phase 2" banner, a workflow diagram, a long "Key properties" list, installation as uv sync inside the clone, and a "Current maturity" section at the end (:346-382).
• Stale or incomplete statements: the maturity section omits Wave 2B (validation records, review certificates), and the README's Documentation table lists only ADRs 0001–0003 (README.md:342), and ADR status lines and docs/README.md rows are stale (#240 fixes these for ADRs 0004–0007); ADR 0008's own status line ("nothing in it is implemented") and its missing README row are not in #240's scope and belong here; autoforge.example.yaml:111-112 says "Automatic merge is disabled in this milestone" (it is implemented and opt-in); autoforge.example.yaml:228 says "No REMOTE phase runs these yet (#173)" (#173 has landed). These two example-file lines are not in #240's scope and belong here.
• There is no feature matrix, no provider support matrix, no demo link, no security-boundaries summary, no roadmap or contributing link aimed at newcomers.
• docs/README.md is a good index by intent; CHANGELOG.md exists.

Scope

1. README restructure (top to bottom, roughly): one-line value proposition and the supporting description (EPIC #255 section B; final wording approved by the maintainer); a 30-second "how it works" with the workflow diagram; why it is different (the differentiators the EPIC marks Supported, each linking its evidence); a feature matrix; a provider support matrix; install and Quick start (short, linking #259's guide); an example workflow and demo links (#261 — added when it lands, see Acceptance); human-in-the-loop (where a run stops, what the human decides; that agents cannot ask the operator anything mid-run today); security boundaries in a paragraph (linking #257's page); known limitations; links to the roadmap (#184), the troubleshooting guide (#260), CONTRIBUTING (#263) and the compatibility matrix (#256).
2. Feature matrix. Every capability row has exactly one status — Supported, Experimental, or Not available — and an evidence link. Use the EPIC's section B table and conditions C1–C7 as the starting point and re-verify each row against main; in particular Pi, epic run, controller merge / UPDATE_EPIC, sandbox.mode: required, validation.commands, acceptance actions (#211; #243 only if merged), SDK providers (Not available) and durable interactive handoff (Not available).
3. Provider matrix. Generated from, or tested against, default_config() and doctor's provider checks: provider, default phases, status, and a link to #256's compatibility matrix for each CLI's floor, verified versions and authentication (link, do not restate). A test fails if the README's default routing and default_config() disagree (or the matrix links a generated page instead of restating it).
4. Accuracy sweep of operator-facing text: README.md, docs/README.md, autoforge.example.yaml comments (including :111-112 and :228), ADR 0008's status line and its README / docs/README.md rows, and the opening sections of docs/usage.md and docs/configuration.md. Fix what is stale; do not edit ADR decisions (a status line is not a decision).
5. A documentation accuracy checklist (in docs/development.md or the release procedure from #256) that Gate 6 re-runs at the release candidate, split into offline items an agent or CI can check (commands that need no credential run as shown; matrices match code; no planned or experimental feature presented as supported; release notes match CHANGELOG.md; links resolve) and maintainer items that need credentials or judgement (credentialed commands run as shown; the positioning still holds).

Acceptance criteria

• A first-time reader can find, in the README's first screen (everything before the first ## heading), what AutoForge is, the status of the project (Public Alpha, not production-ready) and the link to get started.
• The feature matrix exists; every row has one status and an evidence link; no Experimental or Not-available capability is described as Supported anywhere in the README.
• The provider matrix matches default_config() and doctor, enforced by a test or generated.
• The two stale autoforge.example.yaml lines are corrected; the sweep's other fixes are listed in the PR.
• The README links #259's guide, #260's guide, #257's security page, #256's compatibility matrix, #184, and CONTRIBUTING once #263 adds it. The demo link (#261) is added by this issue if #261 is closed when this PR merges, otherwise by #263 — never a placeholder that suggests a demo exists.
• The documentation accuracy checklist exists; its offline items were run on the PR head (result in the PR) and its maintainer items by the maintainer (result on this issue).
• The positioning wording is approved by the maintainer in the PR review.
• make check passes.

Out of scope

ADR decisions; behaviour; #184's own text; launch posts and the demo (#263, #261).

Notes for the implementer

Read AGENTS.md and docs/README.md first. Never call a disabled or fallen-back launch sandboxed, and never describe the network as sandboxed (ADR 0005). #240 lands first (native link) and touches the same README lines; build on it. PR #254 (#243) also edits README.md, docs/README.md, the ADR 0004 status line and autoforge.example.yaml; whichever lands second rebases, and nothing describes #243's acceptance actions as available unless it has merged.