docs: restructure docs.openadapt.ai into Diátaxis sections (for review)

[abrichr]

For review. Please don't merge without a product and copy decision: this changes the information architecture of docs.openadapt.ai.

What changes

The sidebar now uses Diátaxis sections. Every page sits in exactly one section (84 nav pages, no duplicates).

• Evaluate: unchanged, the plain-language path with no install.
• Get started: three separate tracks. The Command line track (get-started/cli.md, new) and the Connect an agent over MCP track (get-started/agent-mcp.md, new) sit next to the existing Desktop app page, followed by Author a workflow and What you get. get-started/index.md is now a chooser: operating-system permission warnings come first, and the job-link (openadapt.ai/j/{id}) case has its own short section.
• Concepts: grouped into how a workflow is built, how a run is checked, when a run stops, and where it runs. Each concept page ends with a Try it section that links to its how-to.
• How-to guides: grouped into record and compile, qualify and certify, and run and operate.
• Reference: CLI, run outcomes and halt reasons, bundle format, deployment config, env vars, backends, Execute, versions, glossary, What's New, changelog.
• Security & enterprise: the security review, data handling, account security, PHI handling, qualification evidence, Production admission, and vulnerability disclosure, with the commercial pages nested under it.
• Contributing & research (new contributing/index.md): product components and release admission, documentation source of truth, Seal as an RL reward, and the paper.

The home page is rewritten. It covers what OpenAdapt is, a demonstrate → compile/certify → execute-and-verify diagram, a 3-command try-it, role-based paths, when it fits, who approves what, and the caller-contract table (transaction outcome → label people see → MCP outcome → what the caller may do).

Security consolidation: hosted retention had three copies of the same facts, so it now has one canonical section in Security and data handling, with short summaries linking to it. The release-integrity paragraph now points to the security review's fuller section. The other overlaps differ in depth on purpose, so they stay.

Glossary: a new Admission entry, plus an intro that points to the qualification, certification, and policy definitions. docs/QUALIFICATION_TERMS.md (openadapt-flow #532) isn't merged, so there's an HTML-comment TODO in its place.

Machine-readable files: agents.txt now uses the current MCP commands (uvx --python 3.12 …) and the real outcome vocabulary. The old REFUSED/TIMEOUT/ERROR values don't exist in openadapt-agent. llms.txt follows the new sections and now lists every nav page, including the commercial ones it was missing.

Validator: the get-started/index.md markers move to the track that owns them (cli.md, agent-mcp.md). The ecosystem catalog may now sit under "Contributing & research". Tests are added for both.

URLs and redirects

No file moved, so no published URL changes and no new redirects are needed. All 129 built files from main still exist. The sitemap goes from 81 to 84 URLs, with none dropped. The existing redirect_to stubs still resolve: /start/, /getting-started/, /cli/, /architecture/, /packages/*.

Checked against the code

• The tutorial output layout, report.json, and receipt.json (VERIFIED runs only) match a live run of uvx --python 3.12 openadapt flow tutorial (VERIFIED) and openadapt quickstart --break-it on macOS.
• The broken rerun ends HALTED with transaction outcome RECONCILIATION_REQUIRED ("Check the record"), not "nothing was written". The new copy says this.
• Approval modes come from openadapt_flow/approval_mode: each_item (the default), not_gated, and problems_only (not available to customers yet). The copy names no batch, rule, or delegated approval, because none is on main.
• MCP outcomes and the mapping come from openadapt_agent/contract.py. Labels come from openadapt_flow/plain_outcome.py.

Build

• mkdocs build --strict passes.
• scripts/validate_docs.py passes.
• pytest: 546 passed.
• A link and anchor check over the built site found 0 broken internal links out of 14,359.

Added before merge

• get-started/cli.md: a "What these look like" section under the output table, with the receipt.png from a real openadapt flow tutorial run (openadapt 1.17.0, lossless WebP, 10 KB, docs/assets/screenshots/tutorial-receipt.webp) and trimmed excerpts of that run's report.json and receipt.json.
• index.md: the VERIFIED paragraph now says a system-of-record read is the strongest independent read and a separate UI session is weaker, instead of listing them as equal.