docs: fix drift, broken samples, and inconsistencies across the docs set

[lesnik512]

Deep audit of all 23 doc pages, each cross-referenced against src/, architecture/, and pyproject.toml. Every code sample's imports/symbols/kwargs/defaults were verified; internal links + anchors all resolve; mkdocs build --strict passes; the testing.md examples were run against the fake broker.

High (correctness)

• how-it-works.md — a foreign-publish outage nacks via retry_strategy; the lease-expiry recovery path applies only to a mis-composed publisher chain (_OutboxConfigError). The old text had this backwards and contradicted architecture/relay.md and the Kafka tutorial.
• testing.md — the publisher example was missing the required session= and would raise TypeError (the publisher path is not session-patched like broker.publish). Also the rows == 1 assertion published to a handler-registered queue, where sync-mode dispatch acks/deletes the row → rows == []; switched to an unconsumed queue.
• alembic.md — the initial migration omitted the load-bearing outbox_lease_ck CHECK; a copy-paste built a table missing a constraint the broker depends on. Placement matches Alembic's rendered autogenerate output.

Medium (accuracy)

• add-kafka-relay.md — default outage budget corrected ~13-14 min → ~8-9 min (10 attempts, 1+2+…+256s ≈ 8.5 min).
• drain_timeout consistency sweep — instrumentation-seams six→seven events (+ list + comparison-table row), setup-prometheus-opentelemetry three→four OTel counters, observability counting reframed onto a consistent event basis.

Judgment calls (maintainer ruling)

• Python floor 3.13+ → 3.11+ in installation.md, first-outbox-app.md, and CLAUDE.md, to match requires-python = ">=3.11,<4", the classifiers, and CI.
• OutboxResponse reframed around session lifetime, not "FastAPI-specific" (it works anywhere the session outlives the handler return); broken link text fixed.

Low (~11)

Snippet-completeness fixes (undefined vars in schema-validation, messaging-service, fastapi, relay, testing fragments), relay missing await, subscriber validation-file attribution (config.py, not factory.py), timers past-dated activate_at example + activate_at clock-skew note, checklist 63-byte-guard wording (binds on the longest index name, not the channel), messaging-service timer_id wording, publisher broker.request note, index.md router table reordered to lead with the newcomer path, and the "Both seams" OTel example switched to spans-only to drop a dead unscraped meter path.

Outside docs/

architecture/subscriber.md corrected — an undersized pool does not block start() (it schedules loops via add_task); the loops stall on checkout at runtime. The user doc was already correct.

🤖 Generated with Claude Code