docs: bring the documentation to the suite standard; cover bff and pep

[ovander]

What and why

This brings the README, the integration guide and the contributor files to the documentation standard of the owner's public repos (ascenda-frontend, ascenda-backend, ha-vigie). It also fixes the places where the docs no longer matched the code. It is docs only: no .go, go.mod or workflow changes.

README:

• It now opens with a pitch and a paragraph that cover bff (the Backend-for-Frontend runtime) and pep (central policy enforcement), which are now the library's main features and were previously missing from the pitch, the "Why" and the diagram.
• The architecture diagram is redrawn; its borders were misaligned.
• The intra-module import rule now reads the same in all three places (README, package table, CONTRIBUTING). The README had said "only ctxutil/apierror".
• The httpware table gains Metrics(service) / MetricsHandler().
• The Requirements paragraph no longer says ctxutil needs Socrate.
• Package sections are kept, as CLAUDE.md requires, but tightened, each with a pkg.go.dev link. Content that duplicated the guide was removed.
• "Production usage" with unverifiable names became Used by: oauth2-admin, oauth2-monitoring and ascenda-backend, each checked against its go.mod and imports.
• The Go Report Card badge is removed because its target cannot be verified. pkg.go.dev and CI stay.

docs/CLIENT-INTEGRATION.md:

• Now says OAuth 2.1 / OpenID Connect.
• New §7.1: browser apps use a BFF, with the /bff/session CSRF pattern, and a new section on pep. Both examples were compiled against the real API in a throwaway module.
• The old SPA-held-token flows are kept, labelled as an alternative for non-browser or legacy clients, with a ⚠️ callout stating the risks. They had been presented as the recommended path, which contradicted the suite's "no tokens in the browser" stance.
• Socrate's admin port is described as "8081 in the default deployment", not as a fixed fact.

Public-visitor hygiene:

• There are no hyperlinks into the still-private ovander/go-oauth2; it is named in plain text.
• The issue config links only the security advisory form.
• Internal names ("A4") in user docs are replaced.
• The CHANGELOG keeps its F-n/INV-n IDs as history, but its references to files that do not exist (SECURITY-AUDIT.md, SECURITY-ARCHITECTURE.md, CR-…pass2/3.md) are reworded. It gains the standard header and link references for 1.8.0–1.13.0.

PR template: the checklist is now the full local gate, including govulncheck.

How it was tested

• go build ./... && go vet ./... pass. No code changed.
• The new bff and pep examples and the new README snippets compile against the module (throwaway main with a replace directive, deleted afterwards).
• Every relative link and anchor in the changed markdown resolves.
• No go-oauth2 hyperlinks, Go Report Card badge, or references to missing files remain.
• A line is added under ## [Unreleased] in CHANGELOG.md.

Not verified: older snippets for tiering, aigateway and ailang were checked against signatures but not compiled. The server endpoints described in the guide were spot-checked, not exhaustively checked against the server.

Compatibility

No exported API change. Documentation only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GKRxaeYxyDhmt42cehLsGA

---

Generated by Claude Code