docs: clarify ErrOIDCSubjectAlreadyLinked sentinel description in auth/index.md

[github-actions]

Problem

The sentinel error table in docs/auth/index.md described auth.ErrOIDCSubjectAlreadyLinked as a "benign no-op" without qualification:

| `auth.ErrOIDCSubjectAlreadyLinked` | `LinkOIDCSubject` called when the subject is already linked to the user (benign no-op) |

This is misleading. The sentinel is only suppressed in the best-effort login path (linkOIDCSubjectBestEffort). The interactive link callback (handleLinkCallback) treats any non-nil return from LinkOIDCSubject as a failure and redirects with oidc_link_error=Failed+to+link — including this sentinel.

docs/auth/store-interfaces.md already documents the correct implementation pattern (idempotent upsert returning nil), but the quick-reference table in auth/index.md contradicted it.

Change

Updated the auth/index.md sentinel table to:

• Accurately describe which code path suppresses the sentinel (best-effort login only)
• Warn that the interactive link callback treats it as a failure
• Cross-link to the store-interfaces.md#userstore section for the full implementation recommendation

No code changes

This is a documentation-only fix. No Go source files were modified.

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 documentation-only PR corrects the quick-reference description of auth.ErrOIDCSubjectAlreadyLinked in docs/auth/index.md, which previously called it a "benign no-op" without qualification. The new description accurately notes that the sentinel is suppressed only in the best-effort login path and is treated as a failure by the interactive link callback, and cross-links to the authoritative guidance in store-interfaces.md#userstore. The update is consistent with the existing detail in store-interfaces.md.

Confidence Score: 5/5

This PR is safe to merge — documentation-only change with no code modifications.

Single-line doc update to a sentinel error table; the new description is factually accurate and consistent with the authoritative store-interfaces.md reference. Cross-link anchor #userstore matches the target heading. No code, no tests, no config changed.

No files require special attention.

Important Files Changed

Filename	Overview
docs/auth/index.md	Updated ErrOIDCSubjectAlreadyLinked sentinel description to accurately distinguish best-effort vs. interactive-link-callback behavior and cross-link to store-interfaces.md#userstore; content is consistent with the authoritative reference in store-interfaces.md.

Sequence Diagram

sequenceDiagram
    participant Client
    participant linkOIDCSubjectBestEffort as Best-Effort Login Path
    participant handleLinkCallback as Interactive Link Callback
    participant Store as UserStore.LinkOIDCSubject

    Client->>linkOIDCSubjectBestEffort: OIDC login (subject already linked)
    linkOIDCSubjectBestEffort->>Store: LinkOIDCSubject(ctx, userID, subject)
    Store-->>linkOIDCSubjectBestEffort: ErrOIDCSubjectAlreadyLinked
    linkOIDCSubjectBestEffort-->>Client: Suppressed — login continues normally

    Client->>handleLinkCallback: Interactive OIDC link (subject already linked)
    handleLinkCallback->>Store: LinkOIDCSubject(ctx, userID, subject)
    Store-->>handleLinkCallback: ErrOIDCSubjectAlreadyLinked (any non-nil)
    handleLinkCallback-->>Client: Redirect with oidc_link_error=Failed+to+link

    Note over Store: Recommended: idempotent upsert returning nil avoids the callback-path failure entirely

Loading

_{Reviews (1): Last reviewed commit: "docs: clarify ErrOIDCSubjectAlreadyLinke..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates the auth package documentation to correct the quick-reference description of the auth.ErrOIDCSubjectAlreadyLinked sentinel so it matches actual handler behavior and the implementation guidance already documented for stores.

Changes:

• Clarifies that auth.ErrOIDCSubjectAlreadyLinked is only suppressed in the best-effort login path (linkOIDCSubjectBestEffort).
• Warns that the interactive link callback treats any non-nil LinkOIDCSubject error (including this sentinel) as a failure redirect.
• Adds a cross-link to the recommended UserStore.LinkOIDCSubject idempotent-upsert behavior in store-interfaces.md#userstore.

Show a summary per file

File	Description
docs/auth/index.md	Updates the sentinel error table entry for ErrOIDCSubjectAlreadyLinked to reflect real handler behavior and link to the fuller store guidance.

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