docs: fix RefreshCookieName described as optional in quick start

[github-actions]

Summary

The inline comment in docs/index.md and the struct field comment in handler/auth.go both implied that RefreshCookieName is optional when Sessions is set. This conflicts with the actual runtime behaviour: issueTokens (in handler/helpers.go) returns HTTP 500 "server misconfiguration" when Sessions is non-nil but RefreshCookieName is empty.

This same inaccuracy was corrected in the handler-specific docs (auth.md, passkeys.md, magic-links.md) by the previous PR (#199), but the top-level quick start example and the struct comment were not updated at that time.

Changes

• docs/index.md — Quick start code snippet: changed

  RefreshCookieName: "refresh",  // optional: deliver refresh token via cookie

  to

  RefreshCookieName: "refresh",  // required when Sessions is set

• handler/auth.go — AuthHandler.RefreshCookieName struct comment: replaced

  When empty the refresh token is only returned in the response body.

  with accurate language:

  Required when Sessions is non-nil; omitting it causes token issuance to return HTTP 500 "server misconfiguration".

Why this matters

A developer reading the quick start or hovering over the struct field in their IDE would conclude that omitting RefreshCookieName is safe. In practice it causes a silent HTTP 500 at runtime on the first login attempt. The fix ensures the quick start and field documentation agree with both the runtime guard and the handler-level docs updated by #199.

Testing

No logic was changed. The existing test suite covers the issueTokens misconfiguration path.

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 · ● 1.6M · ◷

To install this agentic workflow, run

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

Greptile Summary

This PR corrects two documentation inaccuracies: the inline comment in docs/index.md and the struct-field GoDoc comment in handler/auth.go both previously implied RefreshCookieName was optional when Sessions is set, when in fact issueTokens in handler/helpers.go returns HTTP 500 "server misconfiguration" if Sessions != nil and RefreshCookieName == "". The updated comments now accurately reflect the enforced runtime requirement, consistent with the handler-specific docs fixed in PR #199.

Confidence Score: 5/5

Safe to merge — documentation-only fix with no logic changes.

Both changed lines are comments/GoDoc. The correction is verified accurate against the runtime guard in handler/helpers.go lines 38–42. No code behaviour is altered.

No files require special attention.

Important Files Changed

Filename	Overview
docs/index.md	Inline comment for RefreshCookieName corrected from "optional" to "required when Sessions is set" — accurate per runtime guard in helpers.go.
handler/auth.go	GoDoc comment for RefreshCookieName updated to state the field is required when Sessions is non-nil and describes the HTTP 500 consequence — matches actual issueTokens behaviour.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler
    participant issueTokens
    participant SessionStore

    Client->>Handler: POST /login
    Handler->>issueTokens: sessions, refreshCookieName, ...
    alt Sessions != nil && RefreshCookieName == ""
        issueTokens-->>Handler: HTTP 500 "server misconfiguration"
        Handler-->>Client: 500 Internal Server Error
    else Sessions != nil && RefreshCookieName set
        issueTokens->>SessionStore: CreateSession(...)
        SessionStore-->>issueTokens: session
        issueTokens-->>Handler: accessToken, refreshToken, ok=true
        Handler-->>Client: 200 OK + cookies
    end

Loading

_{Reviews (1): Last reviewed commit: "docs: fix RefreshCookieName described as..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Updates top-level docs and AuthHandler field documentation to accurately reflect the runtime requirement that RefreshCookieName must be set when Sessions is configured (since token issuance otherwise fails fast with HTTP 500 "server misconfiguration").

Changes:

• Adjust quick start snippet in docs/index.md to mark RefreshCookieName as required when Sessions is set.
• Update handler/auth.go’s AuthHandler.RefreshCookieName comment to describe the real failure mode when omitted.

Show a summary per file

File	Description
docs/index.md	Fixes quick start comment to match issueTokens misconfiguration behavior.
handler/auth.go	Corrects RefreshCookieName struct field comment to reflect the runtime guard (HTTP 500 on misconfig).

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: 0