docs(readme): restructure for scan-ability, relocate depth into docs/

[abrichr]

Why

The README was ~8,055 words. PR #410 added the right launch elements — badges and stars, the quick-links row, the evidence table, the mermaid flow, the comparison block, the FAQ — but the pre-existing body was long enough to bury them. A reader arriving from a link should hit what it is, the try-it link, install, quickstart, the evidence, and how it works within the first two screens.

What changed

The linear read is now ~2,580 words, down from 8,055. Nothing was deleted. Every relocated section has a specific bridging link from the README, so any moved fact is one click away.

Relocation ledger

Section that moved	New home	Bridging link text in the README
Tutorial walkthrough, --break-it, --guided, hand-driven stages, packaging and browser provisioning	docs/TUTORIAL.md	the bundled tutorial, end to end
Parameter proposals, profile selection, transaction_outcome, lint/certify detail	docs/PARAMETERS.md	parameters, profiles, and run outcomes
Page-local secrets, identity vs reflected evidence, URL structure reduction	docs/SECRETS_AND_EVIDENCE.md	secrets and the captured-evidence contract
The closed allow-list receipt contract	docs/RECEIPTS.md	share a result without sharing the record
"From trace to program" bullets, "Answer a halt from a phone"	docs/CAPABILITIES.md	from trace to program
OpenEMR / MockMed / Frappe lending / EffectBench method and caveats	docs/BENCHMARKS.md	benchmarks: method, numbers, and caveats
Local-first posture, seal, cloud connectivity and its boundary rules	docs/HOSTED.md	local-first, with an optional hosted path
The two admissions, what is qualified today, machine-checked claims	docs/CLAIMS_AND_QUALIFICATION.md	capability, qualification, and machine-checked claims
Resolution-ladder rungs, vision-first framing, armed-step coverage	docs/RESOLUTION_LADDER.md	the resolution ladder
Execution-boundary table, per-substrate evidence matrix, what record observes, browser attach mode	docs/SURFACES.md (extended)	backends and surface support
The emitted MockMed mermaid and how to read its target labels	docs/VISUALIZE.md (extended)	the compiled-program visualizer

Kept inline

The badges, quick-links row, lede, demo GIF, evidence table, install and quickstart, the how-it-works mermaid with its PyPI text fallback, the CI proof scenarios, the comparison table, the benchmark headline, the product-state paragraph, the privacy summary, the FAQ, development setup, and the license paragraph. The six CI proof scenarios sit in one <details> block so the table does not dominate the scan while the proof stays on the page.

Verification

• Every number and its framing is unchanged. 19/20 is still 19/20 with the safe-halt note; a scripted check confirms every numeric token and every backticked identifier from the old README still appears in the README or in the docs tree.
• scripts/check_consistency.py, scripts/check_bundle_phi.py, scripts/validate_claims.py --check --structure-only, and tests/test_consistency.py all pass locally.
• Every relative link in the README and in the new pages resolves; relative depth was fixed for the paths that moved into docs/.

Follow-up for the docs site

docs.openadapt.ai is published from openadapt-ops, so this PR does not touch it. Two of the new pages are good candidates to surface there rather than only in the repo: docs/TUTORIAL.md as a getting-started page, and docs/BENCHMARKS.md alongside the existing evidence pages. Noted here for the docs-site owner; this PR does not file it.

🤖 Generated with Claude Code