docs: refresh README + docs, add troubleshooting page

[jmasud]

Summary

• README refresh — badges (CI, CodeQL, Go reference, license), prereqs section, portal screenshot, "why not httpbin/mockoon/Prism?" angle. Drop "Coming in later milestones" roadmap (streaming / pagination / methods / security / export are all shipped).
• New docs/operations/troubleshooting.md — covers 401s everywhere, portal JSON-stub fallback, empty audit log, OIDC redirect loops, make integration hangs, local-passes-CI-fails, Plexara unreachable. Wired into the Operations nav in mkdocs.yml.
• Factual drift fixes — gateway-testing.md was pointing at /v1/page/* paths that don't exist (real routes are /v1/pagination/{link,odata,cursor}); releases.md marked M3 "in progress" and M4 "planned" when both are released; deployment.md had a dangling "Prometheus metrics endpoint lands in." sentence (no /metrics is planned today).
• Honest config docs — auth.require_for_api and auth.require_for_portal are loaded into config but never read elsewhere; reference page now says so, with a note covering what actually gates each surface today.
• Expand methods.md and security.md — per-endpoint response schemas, "what to assert" tables, audit-log perspective (route_name per verb), and design rationale for why probes return 200 instead of 4xx.
• Cross-linking — architecture↔audit, configuration/auth→identity, audit→deployment for request_id correlation.
• Observability — sample access-log JSON line, field-source table (which middleware writes which field), and the SQL pattern for joining audit rows on request_id.

Test plan

• make verify passes locally (full CI-equivalent gate: fmt, mod-tidy, build-all, lint, gosec, govulncheck, semgrep, coverage ≥80%, integration via testcontainers Postgres, CodeQL, ui-verify)
• CI green on this PR (docs.yml will rebuild the mkdocs site under --strict and catch any broken markdown links/anchors)
• Spot-check rendered docs site for the new troubleshooting page and the cross-link additions