docs: fix all findings from the documentation audit

[andybons]

What

Fixes every confirmed finding from a full adversarially-verified documentation audit of this repo (5 audit agents → 2 sweep lenses → 37 independent verifiers → synthesis, with human re-verification of disputed refutations).

Two commits:

1. fix(examples): gen-ca.sh rewritten to generate from an explicit OpenSSL config instead of -addext, and EC keygen split into ecparam + req. The old script produced CAs Go rejects on Homebrew OpenSSL 1.1.1 (duplicate extension with OID "2.5.29.19") and macOS LibreSSL 3.3.6 (invalid ECDSA parameters). Both failures were reproduced live before the fix and the new script verified through proxy.LoadCA on both toolchains.

2. docs: every doc correction —

   • Reproduced breakages: quick-start now works as literally written (verified end-to-end with a real intercepted request); the install verify step no longer claims --config /dev/null errors (it starts and blocks — replaced with the no-config exit-1 path).
   • Factually wrong claims fixed: LLM policy denial is 400 not 200; KeepEngines is scope-keyed (llm-gateway/http/mcp-<server>) with a hardcoded api.anthropic.com gate, not hostname-keyed; grant documents the claude tie-break; token-exchange cache TTL is a 1-minute hard cap, not a 5-minute default; credential host matching strips any port and rejects : in config (the 80/443 semantics belong to network policy); MCP SSE uses a per-chunk-flushing loop, not io.Copy; injected_headers values are lowercased.
   • Newly documented: HTTP-scope Keep policy (403 + X-Moat-Blocked: keep-policy), 401/403 credential invalidation + 10s cooldown, OTEL_SDK_DISABLED, the daemon-mode /mcp/{token}/{server} path, ALPN negotiation, five missing canonical-log fields, postgres in proxy_type.
   • Top-level: README gains MCP relay / LLM policy / host gateway sections, a docs link, and the ghcr.io install path; AGENTS.md architecture tree completed and OTel section updated; docs/token-exchange-endpoint.md de-orphaned and reconciled (singleflight); changelog PR links restored (fix(proxy): match wildcard host patterns in credential lookup #43–fix(otel): stop OTel export failures from flooding INFO logs #47) and a v0.17.1 entry added.

Every changed claim was re-verified against code by the fixing agent and independently re-checked in review (including running the new gen-ca.sh on both OpenSSL builds and confirming the claude tie-break direction against selectWinners).

Verification

• go build ./... clean (docs + one shell script; no Go changes)
• shellcheck examples/gen-ca.sh clean
• Quick-start executed end-to-end as written post-fix
• All new internal doc links resolve

[claude]

Claude finished @andybons's task in 2m 33s —— View job

---

Reviewing PR #49

• Gather context (PR diff, changed files)
• Review examples/gen-ca.sh and doc changes against source
• Verify high-risk factual claims against code
• Post summary

Summary

This PR is docs-only plus a rewrite of examples/gen-ca.sh. I fact-checked the highest-risk claims (the ones the PR body flags as "factually wrong claims fixed" or "newly documented") directly against the source, since that's exactly the bug class this PR targets:

• LLM policy denial status — confirmed http.StatusBadRequest (400), not 200 (proxy/proxy.go:2496,2507,2519).
• KeepEngines scope keys — confirmed "llm-gateway", "http", "mcp-<server>", with a hardcoded host == "api.anthropic.com" gate (proxy/proxy.go:2747-2749, proxy/mcp.go:274).
• grant: claude tie-break — confirmed opposite-direction tie-break logic exists exactly as documented (proxy/proxy.go:1320-1334,1363-1364).
• Token-exchange cache TTL — confirmed maxTokenTTL = time.Minute hard cap, not a 5-minute default (credentialsource/tokenexchange.go:153).
• Credential invalidation cooldown — confirmed defaultInvalidateCooldown = 10 * time.Second (credentialsource/tokenexchange.go:164).
• Credential host matching — confirmed isValidHost rejects : (proxy/proxy.go:1006-1019) and lookupHostKeyed/bareHost strip the port unconditionally with no 80/443 default.
• MCP SSE streaming — confirmed a 4096-byte per-chunk flush loop (streamResponseBody, proxy/stream.go), used by mcp.go:484, not io.Copy.
• injected_headers lowercased — confirmed InjectedHeaders keys are produced via strings.ToLower(headerName) throughout.
• HTTP-scope Keep policy — confirmed 403 + X-Moat-Blocked: keep-policy (proxy/proxy.go:2930-2932), distinct from network policy's 407/request-rule.
• OTEL_SDK_DISABLED — confirmed strings.EqualFold(getenv("OTEL_SDK_DISABLED"), "true") (cmd/gatekeeper/main.go:36).
• Daemon-mode /mcp/{token}/{server} path — confirmed in handleDirectMCPRelay (proxy/proxy.go:1777-1797).
• ALPN negotiation / http2.Transport — confirmed NextProtos: []string{http2.NextProtoTLS, "http/1.1"} and the h2/http.Transport split (proxy/proxy.go:2590,2626).
• Canonical log fields — confirmed RequestSize, ResponseSize, RequestMessages, ResponseMessages fields exist with the documented semantics (proxy/proxy.go:178-181).

All matched the docs. I didn't find any remaining doc/code mismatches in the sampled claims.

examples/gen-ca.sh — the rewrite (heredoc'd OpenSSL config + split ecparam/req steps) is a straightforward, correct fix for the two described toolchain failures. No shell scripting bugs (proper set -euo pipefail, quoted variables, trap cleanup for the temp config file). One minor, pre-existing (not introduced by this diff) note: ca.key is written by openssl ecparam before the chmod 0600 on the next line, so there's a brief window where the key file has default umask permissions — same as the original script's behavior via -keyout, not a regression, and low-severity for a local example/dev script.

No inline comments filed — nothing rose to the level of a code defect.