docs: fix missing Pragma: no-cache and clarify silent-200 behaviours

[github-actions]

Summary

Four documentation gaps found by cross-referencing the README against the handler source files.

Changes

1. APIKeyHandler.Create — add missing Pragma: no-cache

The code sets both Cache-Control: no-store and Pragma: no-cache on the Create (201) response, but the README response table only mentioned Cache-Control: no-store. Updated to match the code, consistent with how other handlers (AuthHandler, MagicLinkHandler, TOTPHandler) document the same header pair.

Files: handler/apikey.go:105-106

2. MagicLinkHandler.RequestMagicLink — document email-delivery-failure → 200

When Sender is non-nil but returns an error, the handler logs the failure and continues to return HTTP 200 (see the // Do not surface delivery failures comment in handler/magiclink.go). This was undocumented. Added a blockquote note after the error table.

Files: handler/magiclink.go:84-87

3. EmailVerificationHandler.SendVerification — clarify all internal failures return 200

The section said the handler "prevents enumeration" for the user-not-found case, but didn't make clear that all internal failures (store errors, token generation failures, email delivery failures) also return 200. Added a blockquote note after the error table explaining this intentional anti-enumeration design.

Files: handler/email_verification.go:62-102

4. PasswordResetHandler.RequestReset — state that email-send failure returns 200

The existing prose described the orphaned-token cleanup on email failure but never explicitly said the response was still HTTP 200. Added "and still returns HTTP 200" to make the control flow unambiguous.

Files: handler/password_reset.go:96-107

---

Testing

Documentation-only changes. No behaviour was altered. The Go toolchain required by the repository (go1.26.1) is not available in the CI sandbox, so automated tests could not be run; all changes are verified by reading the source code directly.

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by Update Docs · ● 2.5M · ◷

To install this agentic workflow, run

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

Greptile Summary

This PR adds four documentation corrections to README.md, each cross-verified against the corresponding handler source. All changes accurately reflect the code: Pragma: no-cache is confirmed at apikey.go:98, the MagicLink silent-200 path is confirmed at magiclink.go:77-84, all five SendVerification anti-enumeration 200 paths (including the previously-missing already-verified case) are confirmed at email_verification.go:62-101, and the PasswordReset email-failure 200 return is confirmed at password_reset.go:96-110.

Confidence Score: 5/5

Safe to merge — documentation-only changes that accurately reflect the source code.

All four documentation changes were verified line-by-line against the corresponding handler source files. No behaviour was altered. The previously-flagged omission of the already-verified 200 path in SendVerification has been correctly addressed in this PR.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Four accurate documentation fixes: adds missing Pragma: no-cache to APIKeyHandler.Create, documents MagicLink delivery-failure → 200 behaviour, documents all SendVerification anti-enumeration 200 paths (including the previously-missing already-verified case), and clarifies PasswordReset email-failure still returns 200.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[RequestMagicLink] --> B{Sender == nil?}
    B -- Yes --> C[503 Service Unavailable]
    B -- No --> D{Sender returns error?}
    D -- Yes --> E[Log failure, continue]
    D -- No --> F[200 OK]
    E --> F

    G[SendVerification] --> H{email empty?}
    H -- Yes --> I[400 Bad Request]
    H -- No --> J{User found?}
    J -- No --> K[200 OK — silent]
    J -- Yes --> L{Already verified?}
    L -- Yes --> K
    L -- No --> M{Token generation OK?}
    M -- No --> K
    M -- Yes --> N{Store OK?}
    N -- No --> K
    N -- Yes --> O{SendEmail != nil?}
    O -- No --> P[200 OK]
    O -- Yes --> Q{Delivery error?}
    Q -- Yes --> R[Log, continue]
    Q -- No --> P
    R --> P

    S[RequestReset] --> T{User found?}
    T -- No --> U[200 OK — silent]
    T -- Yes --> V{Store token OK?}
    V -- No --> W[500 Internal Server Error]
    V -- Yes --> X{SendResetEmail != nil?}
    X -- No --> U
    X -- Yes --> Y{Delivery error?}
    Y -- Yes --> Z[Attempt token cleanup, 200 OK]
    Y -- No --> U

Loading

_{Reviews (2): Last reviewed commit: "docs: add 'already verified' path to Sen..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates README documentation to accurately reflect existing handler behaviors around anti-caching headers and intentionally “silent 200” responses (anti-enumeration / non-disclosure of email delivery failures).

Changes:

• Document Pragma: no-cache alongside Cache-Control: no-store for APIKeyHandler.Create responses.
• Add explicit notes that certain email-delivery and internal failures intentionally still return HTTP 200 for MagicLinkHandler.RequestMagicLink, EmailVerificationHandler.SendVerification, and PasswordResetHandler.RequestReset.

Show a summary per file

File	Description
README.md	Aligns documented response headers and “silent 200” semantics with current handler implementations.

Copilot's findings

Tip

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

• Files reviewed: 1/1 changed files
• Comments generated: 0