docs: fix the improvement tail (P1–P18)

[lesnik512]

Closes out the improvement tail (P1–P18) from the 2026-06-13 docs audit
(planning/audits/2026-06-13-docs-audit-findings.md) — convenience,
readability, and gap fixes. Signatures/defaults verified against source;
mkdocs build --strict is clean (all new internal anchors resolve).

With this merged, every finding from the audit (B1–B5, C1–C3, I1–I15,
P1–P18) is resolved.

Findings fixed

ID	Page	Fix
P1	subscriber.md	Document propagate_inbound_headers in the options table
P2	subscriber.md	Note the standard passthrough kwargs (dependencies, parser, decoder, AsyncAPI fields)
P3	subscriber.md	Add a retry-strategy params/defaults table + shared caps
P4	publisher.md	Show the broker.publisher(...) constructor signature
P5	publisher.md	FastAPI-specific callout on the OutboxResponse chained-publish example (session must outlive the handler return)
P6	index.md	Signpost the three observability entries (concept / reference / step-by-step)
P7	instrumentation-seams.md	State the recorder "must not block" constraint
P8	observability.md	Add a bundled-adapter wiring snippet
P9	comparison.md	Bullet the "vs. writing your own" feature wall
P10	comparison.md	Add an at-a-glance decision matrix
P11	comparison.md	Give the CDC verdict a falsifiable detail
P12	how-it-works.md	Flesh out the relay stub
P13	how-it-works.md	Dedupe the idempotency note
P14	testing.md	Runnable loop-mode feed() + poll example
P15	testing.md	Drop the inconsistent @pytest.mark.asyncio marker
P16	troubleshooting.md	Name the missing-timer_id DLQ migration cause
P17	basic.md	Drop the unexplained max_workers=4
P18	relay.md	Setup note + OutboxResponse import in the anti-pattern

🤖 Generated with Claude Code