docs: update Link endpoint — 404 for user-not-found, 409 for already-linked

[github-actions]

Summary

PR #231 fixed the OIDC and OAuth2 Link endpoint to return 404 Not Found when Users.FindByID returns ErrNotFound, instead of conflating it with 409 Conflict (reserved for the "account already linked" case).

This PR updates the HTTP status code reference tables in the handler documentation to accurately reflect that distinction.

Changes

• docs/handler/oidc.md — split the Link | 409 Conflict row into:
  • Link | 404 Not Found — user not found (ErrNotFound from Users.FindByID)
  • Link | 409 Conflict — account already linked to an OIDC identity
• docs/handler/oauth2.md — same split for OAuth2Handler

Motivation

Before this fix, clients following the API reference would incorrectly expect 409 when a user account had been deleted between nonce issuance and link initiation. The 404 response is semantically correct and more actionable for API consumers.

Testing

Documentation-only change; no functional code modified.

Generated by Update Docs · ● 799.5K · ◷

To install this agentic workflow, run

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

Greptile Summary

This PR updates the HTTP status code reference tables in docs/handler/oidc.md and docs/handler/oauth2.md to reflect the fix from PR #231, which made the Link endpoint return 404 Not Found when Users.FindByID returns ErrNotFound instead of conflating it with 409 Conflict.

• oidc.md — splits the old combined Link | 409 row into a 404 row (user not found) and a 409 row (account already linked); the existing 500 description already covers the DB-error case.
• oauth2.md — same split; however, the 500 description for Link omits the "DB error when looking up user by ID" case that exists in the handler code and is documented in oidc.md.

Confidence Score: 5/5

Documentation-only change; no functional code modified, safe to merge.

Both doc files correctly split the old combined row into the accurate 404 and 409 responses, matching the handler implementations. The one gap — the missing DB-error note in oauth2.md's 500 row — is a minor doc omission with no impact on the running service.

docs/handler/oauth2.md — the Link 500 description is slightly less complete than its oidc.md counterpart.

Important Files Changed

Filename	Overview
docs/handler/oauth2.md	Correctly splits the old combined 409 row into 404 (user not found) and 409 (already linked); the 500 description for Link omits the DB-error-on-FindByID case that is present in oidc.md and in the handler code.
docs/handler/oidc.md	Correctly splits the old combined 409 row into 404 (user not found) and 409 (already linked); 500 description already mentions the DB-error case.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Link handler called] --> B{LinkNonces nil?}
    B -- Yes --> C[503 Service Unavailable]
    B -- No --> D{Nonce in query?}
    D -- No --> E[400 Bad Request]
    D -- Yes --> F[consumeLinkNonce]
    F --> G{Error?}
    G -- ErrNotFound --> H[401 Unauthorized]
    G -- Other error --> I[500 Internal Server Error]
    G -- nil --> J[Users.FindByID]
    J --> K{Error?}
    K -- ErrNotFound --> L[404 Not Found]
    K -- Other error --> M[500 Internal Server Error]
    K -- nil --> N{OIDCSubject != nil?}
    N -- Yes --> O[409 Conflict]
    N -- No --> P[302 Found — redirect to provider]

Loading

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/oauth2.md:180
The `Link | 500` description omits the case where `Users.FindByID` returns a non-`ErrNotFound` error. The OAuth2 handler code writes `http.StatusInternalServerError` for that path (same as the OIDC handler), and `oidc.md` explicitly documents it as "DB error when looking up user by ID". Without this note, API consumers won't know that a transient database error during link initiation can also produce a 500.

```suggestion
| `Link` | 500 Internal Server Error | Nonce store error, DB error when looking up user by ID, or failed to initiate redirect |
```

_{Reviews (2): Last reviewed commit: "docs: use "external identity" for 409 Li..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates the handler documentation to reflect the corrected semantics of the OIDC/OAuth2 Link endpoints: returning 404 Not Found when the linking user no longer exists, while reserving 409 Conflict for the “already linked” case (aligning docs with PR #231 behavior).

Changes:

• Update OIDCHandler docs to split the previous combined 409 case into distinct 404 (user missing) and 409 (already linked) entries.
• Update OAuth2Handler docs similarly (with one wording inconsistency noted in a review comment).

Show a summary per file

File	Description
docs/handler/oidc.md	Splits Link status table entries to document 404 (user missing) vs 409 (already linked).
docs/handler/oauth2.md	Splits Link status table entries to document 404 (user missing) vs 409 (already linked); 409 wording needs alignment with actual behavior.

Copilot's findings

Tip

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

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