Docs UX audit + fix all 16 Medium findings

[lesnik512]

What

A reader-experience audit of the documentation (onboarding-weighted), plus fixes for all 16 Medium-severity findings it produced. Complements the 2026-06-12 correctness audit by focusing on whether docs are convenient, understandable, readable, and consistent — and whether a brand-new user reaches first success quickly.

Audit

• Multi-agent sweep across docs/, README.md, architecture/, and docstrings; every Medium adversarially verified.
• Result: 0 High, 16 Medium, 54 Low. Full report: planning/audits/2026-06-13-docs-ux-audit-report.md.
• Bundles: planning/changes/active/2026-06-13.01-docs-ux-audit/ (audit) and 2026-06-13.02-docs-ux-fixes/ (this fix plan).

Fixes (16 Mediums)

Onboarding path

• O-1/R-1 — README now has an install line + a runnable Quick Start (was badges + links only).
• O-2 — index.md Quickstart leads with a runnable sync example (the old async-only one never called asyncio.run → silent no-op).
• O-4 / X-1 / D-11 — context.md reordered to a manual-first Basic Usage, adds a "When no value is set" section (None vs ArgumentResolutionError), and gains cross-links + See also.
• O-7 — architecture/scopes.md worked example: add Group import, use providers.CacheSettings().

Non-runnable / wrong examples

• O-3 — to-2.x.md Dict/List replacement now resolves (primitive fields supplied via kwargs).
• O-5 — Litestar websocket snippet is self-contained (MyService/ALL_GROUPS defined); confirmed against modern-di-litestar that di_container auto-resolves by name.
• D-1 — container.md "Explicit Injection" example actually uses the container + says when to prefer it.

Accuracy / consistency

• X-2 — duplicate-type-error.md corrected RuntimeError → DuplicateProviderTypeError (+ hierarchy note, cross-link).
• A-3 — architecture/providers.md documents UnsupportedCreatorParameterError (verified the trigger).
• O-6 — from-that-depends.md reconciles the two FastAPI wirings; confirmed via modern-di-fastapi that setup_di merges lifespans and closes the container (so don't also async with container).

Migration / contributing / rendering

• D-21/X-4 — to-2.x.md adds a .cast → type-based-wiring/kwargs/ContextProvider migration recipe.
• D-23 / D-25 — contributing.md fixes the git clone command and adds a "Submitting changes" section (coverage gate, lint/test, planning convention).
• D-19 — numbered install/usage steps now render correctly across pytest.md + the 4 integration pages (converted to numbered ### headings, consistent with index.md; the report's index.md mention was a false positive — already headings). X-3 — split container.md's low-level API into a new Advanced / low-level API page and moved the context-propagation warning to context.md.

Verification

• Every runnable snippet executed with uv run python (README, index, Dict/List, explicit-injection, exception hierarchy, scope wiring) — all pass.
• mkdocs build --strict passes (exit 0, no broken-link/nav warnings).
• Rendered HTML confirmed: previously each step rendered as its own <ol start=1>; now single ordered list / clean headings.
• Docs-only; no modern_di/ code changed.

The 54 Low findings are out of scope for this PR (listed in the report for a follow-up).

🤖 Generated with Claude Code