docs: add Observability sections to all handler docs

[github-actions]

Summary

The recent "Add missing 500 error logs" (#215) commit added slog.ErrorContext calls before every HTTP 500 response across all handler files. This PR updates the documentation to reflect that change.

What changed

Every handler documentation page (docs/handler/) now includes an Observability section with a structured table listing:

Column	Description
Event	Human-readable description of the failure
Level	ERROR or WARN
slog message	Exact string used in the source
Endpoint	Which HTTP handler emits it

A brief introductory section is also added to docs/handler/index.md explaining the general pattern (all 500 paths log via slog.ErrorContext; slog.WarnContext for non-fatal degradations; the global slog handler is never replaced).

Files changed

File	Change
docs/handler/index.md	General Observability section
docs/handler/auth.md	Table: 11 events across Signup, Login, Logout, RefreshToken, Me, UpdateProfile, ChangePassword
docs/handler/api-keys.md	Table: 4 events across List, Create, Delete
docs/handler/sessions.md	Table: 3 events across List, Revoke, RevokeAll
docs/handler/totp.md	Table: 7 events across Generate, Enroll, Verify, Status, Disable
docs/handler/magic-links.md	Table: 5 events across RequestMagicLink, VerifyMagicLink
docs/handler/oidc.md	Table: 9 events across Login, Callback, CreateLinkNonce, Link
docs/handler/oauth2.md	Table: 9 events across Login, Callback, CreateLinkNonce, Link
docs/handler/passkeys.md	Table: 12 events across all endpoints
docs/handler/email-verification.md	Table: 6 events across SendVerification, VerifyEmail
docs/handler/password-reset.md	Table: 10 events across RequestReset, ResetPassword

Style

Follows the logging-table pattern established in docs/auth/middleware.md.

Generated by Update Docs · ● 2.2M · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This PR adds an Observability section to every handler documentation page, documenting the structured slog events emitted before HTTP 500 responses (and a handful of non-fatal WARN-level events). It also adds an overview section to docs/handler/index.md explaining the general logging pattern.

• All 11 documentation files now include a table of slog messages, their level, and the endpoint(s) that emit them; slog messages, levels, and endpoint attributions were verified against the source handler files.
• Previously flagged issues from earlier review rounds (missing issueTokens helper events, incorrect endpoint attribution for OIDC/OAuth2 link-flow errors, HTTP 200 vs 500 distinctions in email-verification.md, password-reset.md, and oauth2.md) have been addressed.
• One remaining inaccuracy: the endpoint label for "skipping corrupted passkey credential" in passkeys.md says (internal, during listing) but loadWebAuthnCredentials is never called from ListCredentials; it fires during BeginRegistration, FinishRegistration, and FinishAuthentication.

Confidence Score: 5/5

Documentation-only change; no production code is modified.

Every slog message, log level, and endpoint attribution in all 11 tables was verified against the handler source files. The only remaining issue is a misleading endpoint label in the passkeys table that names the wrong handler as the source of a WARN event — a minor doc inaccuracy with no runtime impact.

docs/handler/passkeys.md — the "skipping corrupted passkey credential" endpoint label should reference BeginRegistration, FinishRegistration, and FinishAuthentication rather than "(internal, during listing)".

Important Files Changed

Filename	Overview
docs/handler/passkeys.md	Adds a 16-row Observability table covering all PasskeyHandler slog events; the endpoint label for the "skipping corrupted passkey credential" WARN is incorrect (see inline comment).
docs/handler/auth.md	Adds an Observability section with 14 events; all slog messages, levels, and endpoint attributions match auth.go and helpers.go exactly.
docs/handler/oidc.md	Adds a 16-row Observability table; issueTokens helper events and handleLinkCallback redirect-path events are correctly attributed and the footer accurately distinguishes HTTP 500 from redirect outcomes.
docs/handler/oauth2.md	Adds a 16-row Observability table; "OAuth2 FetchUserInfo failed" is correctly noted as HTTP 401 in the footer, and handleLinkCallback redirect-path events are accurately separated.
docs/handler/email-verification.md	Adds a 6-row Observability table; footer correctly distinguishes the five SendVerification HTTP-200 events from the two VerifyEmail HTTP-500 events.
docs/handler/password-reset.md	Adds a 10-row Observability table; footer explicitly lists the email-delivery, cleanup, and token-consumption events that return HTTP 200 rather than 500.
docs/handler/magic-links.md	Adds a 9-row Observability table including issueTokens helper events; footer correctly notes the email-delivery failure returns HTTP 200.
docs/handler/api-keys.md	Adds a 4-row Observability table; all events verified against apikey.go and correctly annotated as HTTP 500 paths.
docs/handler/sessions.md	Adds a 3-row Observability table; all events verified against session.go.
docs/handler/totp.md	Adds a 7-row Observability table; all events verified against totp.go, endpoint attributions are accurate.
docs/handler/index.md	Adds a general Observability overview; accurately describes the slog.ErrorContext/WarnContext pattern, the global handler non-replacement guarantee, and the missing error attribute on the misconfiguration message.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/handler/passkeys.md:141
The endpoint label `(internal, during listing)` is misleading. `loadWebAuthnCredentials` is never called from `ListCredentials` — that handler converts raw `PasskeyCredential` DTOs directly without parsing the WebAuthn credential JSON. The WARN fires inside `BeginRegistration` (line 179 of `passkey.go`), `FinishRegistration` (line 237), and `FinishAuthentication` (line 325, inside the discoverable-user closure) — not from any credential-listing endpoint. Operators building log-based alerts on this message expecting it only during listing operations will be confused when it appears during registration or authentication instead.

```suggestion
| Corrupted credential skipped during decode | `WARN` | `"skipping corrupted passkey credential"` | `BeginRegistration`, `FinishRegistration`, `FinishAuthentication` |
```

_{Reviews (5): Last reviewed commit: "docs(oauth2): correct observability foot..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR updates the handler documentation (docs/handler/) to reflect the project’s structured logging behavior (notably the slog.ErrorContext/slog.WarnContext events emitted around error paths), by adding per-handler “Observability” sections and a general overview on the handler docs index.

Changes:

• Add a general “Observability” section to docs/handler/index.md describing the logging pattern.
• Add per-handler observability tables (event/level/message/endpoint) across handler docs pages.
• Document non-fatal ERROR/WARN events (e.g., email delivery failures that still return 200, best-effort linking warnings, passkey counter update warnings).

Show a summary per file

File	Description
docs/handler/index.md	Adds global observability guidance for handlers and structured logging conventions.
docs/handler/auth.md	Adds an observability table covering AuthHandler log events across key endpoints.
docs/handler/api-keys.md	Adds an observability table for APIKeyHandler error logs.
docs/handler/sessions.md	Adds an observability table for SessionHandler error logs.
docs/handler/totp.md	Adds an observability table for TOTPHandler error logs.
docs/handler/magic-links.md	Adds an observability table for MagicLinkHandler error logs and non-fatal email failures.
docs/handler/oidc.md	Adds an observability table for OIDCHandler logs across login/link flows.
docs/handler/oauth2.md	Adds an observability table for OAuth2Handler logs across login/link flows.
docs/handler/passkeys.md	Adds an observability table for PasskeyHandler error/warn logs (including internal WARN cases).
docs/handler/email-verification.md	Adds an observability table for EmailVerificationHandler logs and non-fatal email failures.
docs/handler/password-reset.md	Adds an observability table for PasswordResetHandler logs and non-fatal email failures.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 11/11 changed files
• Comments generated: 6