[DOCS] MUT-030, MUT-031, MUT-032, MUT-033, MUT-064: Docs lag 0.2.0 release and observe-only Hosted #77

Problem

User-facing docs still lag the 0.2.0 release and the observe-only Hosted pivot in several places:

• MUT-030: The advertised loop is run → test → PASS after a fix. The sample never documents the fix. Sample “recommended” path starts Hosted. Root README is local-first. CLI prints “Next: fix the agent, then mutiny test.” Release script flips enforce_refund_policy. Sample mutiny test exited 1 (FAIL refund_limit) — expected, unexplained for a newcomer.
• MUT-031: FAQ still says “Until 0.2.0 is uploaded, the index may still serve 0.1.0”. PyPI has 0.2.0; tag v0.2.0. PRODUCTION_READINESS Target A still has unchecked pip install / sample run / FAIL→PASS / “Version ≥ 0.2.0 tagged.” CHANGELOG [Unreleased] has no entries for post-tag work (bd6a37b, 75dfbdd, --version, etc.). GFI catalog may still list shipped items as open.
• MUT-032: docs/CLI.md claims to be generated from --help but usage is mutiny [-h] {init,run,test}. Actual --help is {db,init,run,test}. ARCHITECTURE still says CLI “Owns (planned)” and omits db.
• MUT-033: Two visual canons. Running UI is Sentry-purple (DESIGN.md / globals.css). docs/DESIGN.md says canonical is root DESIGN.md then describes Inngest charcoal/salmon. ADR-015 still pins Inngest.
• MUT-064: Numeric string coercion (bd6a37b / policy: coerce numeric-looking string args for gt/gte/lt/lte constraints #42) landed after the 0.2.0 tag and is not in CHANGELOG. PyPI 0.2.0 wheels do not include it. FAQ tells people to install 0.2.0. This is a user-facing surprise, not a code bug — needs a changelog / “git vs PyPI” note (or a 0.2.1). Needs verification as a packaging surprise; the git history is real.

Why it matters

Users hesitate or install 0.1.0 “to be safe.” Contributors think regression replay is broken, or that Hosted is required. A first Hosted-UI PR following ADR-015 would fight the actual CSS. “Latest git” and “latest PyPI” disagree on policy evaluation.

Evidence

• Audit IDs: MUT-030–033 (confirmed docs), MUT-064 (needs verification as surprise; post-tag commits exist).
• README FAQ ~L450; docs/CLI.md L7–11; docs/ARCHITECTURE.md CLI section; docs/DESIGN.md vs root DESIGN.md; CHANGELOG.md [Unreleased].
• examples/openai_support_agent/README.md vs scripts/verify_release_artifacts.sh.

--version is already shipped (#26) — do not re-document it as missing.

Reproduction

Read the cited files vs mutiny --help and PyPI 0.2.0. Sample FAIL-without-docs was observed in the audit CLI smoke.

Expected behavior

FAQ: latest is 0.2.0. Sample README: local-first; FAIL is expected until enforce_refund_policy=True. CLI.md usage matches --help. One visual canon (root DESIGN.md). CHANGELOG Unreleased lists post-0.2.0 commits and notes git-only policy coercion until the next upload (or maintainers cut 0.2.1).

Suggested implementation direction

Docs-only PR (plus CHANGELOG). Do not bump PyPI in this issue unless maintainers ask. Make docs/DESIGN.md a pointer; supersede ADR-015.

Acceptance criteria

• README FAQ does not imply 0.2.0 might be unpublished.
• Sample README documents local-first FAIL→fix (enforce_refund_policy).
• docs/CLI.md usage includes db; ARCHITECTURE does not say CLI is “planned” only.
• docs/DESIGN.md defers to root DESIGN.md; ADR-015 superseded or annotated.
• CHANGELOG Unreleased mentions post-tag items including policy string coercion (policy: coerce numeric-looking string args for gt/gte/lt/lte constraints #42) and that PyPI 0.2.0 may lack them.
• PRODUCTION_READINESS Target A checkboxes that are done are marked done (or dated).
• No code behavior changes.

Scope

Markdown / CHANGELOG / ADR. Out of scope: leftover Hosted-exec sample comments (MUT-009 — separate), version numbers in pyproject.toml (MUT-035).

Related audit findings

MUT-030, MUT-031, MUT-032, MUT-033, MUT-064. Related: MUT-009, MUT-035, #26 (done).

Contributor notes

Generated from the Mutiny deep audit.

help wanted. Large docs sweep — not a good-first-issue unless split (FAQ+CHANGELOG vs DESIGN vs sample README).