Audit: README/AGENTS.md doc-example accuracy, especially middleware ordering

[smiggleworth]

Purpose

Audit task, not a bug report — produces a verification table, doesn't fix anything. A closed issue (#16, "README's documented middleware order silently defeats token refresh on retry") shows this category has real yield here.

Procedure

1. Extract every fenced code block from README.md and AGENTS.md, especially middleware-ordering examples.
2. Verify each against current behavior — re-verify README's documented middleware order silently defeats token refresh on retry; retry+upstream-401-auth wastes the whole attempt budget #16's fix means the documented order is now actually correct, not just that the bug was patched without updating the doc to match.
3. File a gap issue for anything stale.

Definition of Done

• Table: doc file | section/snippet | ✅ verified accurate / 🔗 gap filed.
• README's documented middleware order silently defeats token refresh on retry; retry+upstream-401-auth wastes the whole attempt budget #16 explicitly re-verified: documented middleware order matches what's actually safe/correct.
• No row left unmarked.

[smiggleworth]

Documentation audit complete via PR #35.

File	Section / snippet	Result
README	Install command	✅ Package name matches manifest
README	Define and call API	✅ DSL/client/path/result contracts covered by tests
README	Multi-content request example	✅ #23 explicit bodyMediaType contract covered
README	Validator example	✅ safeParse validation/transform path covered
README	Parameter serialization	✅ styles plus null/undefined/NaN matrix covered
README	Middleware ordering	✅ #16 reverified by executable README-order test; retry precedes auth/logging/telemetry
README	Cancellation/timeouts	✅ timeout and caller-abort tests pass
README	Lower-level request	✅ createFetch path covered
README	Runtime version	🔗 Gap fixed in PR #35: corrected Node 20.19 claim to package engine Node 24
AGENTS.md	Fenced examples	✅ None present
AGENTS.md	Validation command	✅ npm run check passes

No documentation row remains unresolved.