Audit 0.4.0 Release Readiness

[GefMar]

Goal

Run the final release-readiness pass that lets 0.4.0 be published as the "functional, production-ready" milestone: docs, examples, limitations, README, release notes and public-surface claims all match the merged code.

Context

Release scope: 0.4.0 - Production-Ready Observability & Stability (capstone, runs last).
0.4.0 is the milestone where FogHTTP claims production readiness for its positioning: high-concurrency outbound HTTP with observability and predictable resource control. By the time this issue runs, proxy/trust_env (0.3.4), uploads (0.3.5), runtime/resource hardening (0.3.6), policy seam + security (0.3.7), reliability (0.3.8) and auth/cookies (0.3.9) are merged. This issue is the equivalent of the #125 streaming release-readiness audit done before 0.3.2, scaled to the whole milestone.
It is an audit/verification task, not a place to add new features. Any defect found should be a small fix or a separate follow-up task.

Scope

• Audit README, docs/ (index, limitations, use-cases, request-builder, tls, proxies, streaming, timeouts, telemetry, lifecycle), examples and OSS docs against the merged 0.4.x surface.
• Verify the "Not Yet" / limitations matrices are accurate: proxy, uploads, auth, cookies, retry, SSRF, connection limits, exporters now reflect real status.
• Verify public API surface (constructors, Limits, Timeouts, telemetry/exporter config, auth/cookie/retry APIs) is documented and typed.
• Verify redaction claims hold across new surfaces (proxy/auth/cookie credentials in repr/errors/telemetry/logs/exporters).
• Confirm benchmark/perf positioning statements are honest (success-only rows, bounded memory) and link the current baseline.
• Draft the 0.4.0 release notes entry and confirm version bumps (Python + Rust) and wheel smoke.

Out Of Scope

• New features or API changes beyond doc/claim corrections.
• Performance optimization work (separate perf tasks).
• Publishing the GitHub Release (done manually at publish time).

Acceptance Criteria

• No doc/example/README claim contradicts the merged 0.4.x public surface.
• Limitations/"Not Yet" matrices are accurate for the milestone.
• New credential-bearing surfaces are confirmed redacted in docs and behavior.
• 0.4.0 release notes drafted; version bumps and wheel smoke confirmed.
• Remaining gaps are captured as explicit follow-up tasks, not left implicit.

Test And Check Strategy

• Doc/surface review against code and stubs.
• Run full test suite, mypy, cargo checks and pre-commit as the release gate.
• Wheel install smoke per the existing release workflow.
• Commands: uv run pytest, uv run mypy foghttp, cargo test --all-targets, uv run pre-commit run --all-files.

Documentation Impact

• This issue is primarily documentation/release verification; its output is corrected docs plus drafted release notes.

Risks

• Risk: docs drift silently during the long 0.3.x arc and 0.4.0 ships inaccurate claims.
  Mitigation: explicit claim-by-claim diff against the public surface.
• Risk: audit turns into scope creep / new features.
  Mitigation: only doc/claim fixes inline; everything else becomes a tracked follow-up.