auth: dedicated page for health checks and re-auth

[dprevoznik]

Summary

There's no single home for managed auth connection health checks / re-auth troubleshooting today — the content is scattered across the FAQ and lightly touched in Configuration. This adds a dedicated Health Checks & Re-Auth page under Auth.

The new page consolidates:

• the connection lifecycle (health check → auto-reauth → NEEDS_AUTH)
• cadence + plan minimums for health_check_interval
• behavior when session TTL is shorter than the check interval
• can_reauth eligibility rules and what blocks auto-reauth
• triggering manual re-auth via .login()
• login failure codes (credentials_invalid, bot_detected, captcha_blocked, unsupported_auth_method) and how to recover from each
• debugging via dashboard live view and record_session

FAQ entries that were the de-facto reference for this material are trimmed to a one-liner that links into the new page, so the FAQ stays focused on Q&A and the deep content has a stable URL. Overview's "Session monitoring" bullet also links to the new page.

Test plan

• Mintlify preview renders the new page in the Auth nav between Profiles and FAQ
• Anchor links from FAQ resolve (#when-a-login-fails, #triggering-re-auth-manually, #debugging-a-flaky-connection)
• Cross-links to /auth/configuration#custom-proxy, /auth/credentials, /integrations/1password, /browsers/replays, /browsers/bot-detection/overview all resolve

---

Note

Low Risk
Low risk documentation-only change that reorganizes Managed Auth guidance; main risk is broken links/anchors or navigation ordering issues.

Overview
Introduces a new auth/connection-lifecycle.mdx page that consolidates guidance on connection health checks, auto-reauth eligibility (can_reauth), manual .login() re-auth, failure codes/recovery, and debugging/recording.

Trims overlapping FAQ sections down to short link-outs to the new page, updates auth/overview.mdx to reference it for session monitoring/runtime behavior, and adds the new page to the Auth navigation in docs.json.

^{Reviewed by Cursor Bugbot for commit b2db039. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Kernel	🟢 Ready	View Preview	May 14, 2026, 2:18 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[masnwilliams]

overall i like the direction — same restructure pattern as #361 (pull scattered FAQ content into a stable URL, leave one-liners + links in the FAQ). a few things to consider before merge:

bug to fix — Start-Up minimum is wrong

The cadence table says Start-Up minimum is 15 minutes. The real value in packages/api/lib/temporal/managed_auth_workflow.go is 20 minutes:

const StartupMinHealthCheckIntervalSeconds = 1200   // 20 min

The original FAQ had the same wrong number — it got carried forward. Worth fixing in this PR.

reframe as "Connection Lifecycle"

"Health Checks" is narrower than what the page covers — health-check cadence is one of ~six sections (lifecycle, cadence, can_reauth, manual reauth, failure codes + recovery, debugging). Something like auth/connection-lifecycle.mdx ("Connection Lifecycle" or "How Connections Stay Authenticated") matches scope better and slots cleanly into the broader managed auth IA:

concern	page
what is it, why	auth/overview.mdx
setup — first login	auth/hosted-ui.mdx / auth/react.mdx / auth/programmatic.mdx
configure — shared connection options	auth/configuration.mdx
operate — how it stays alive, what to do when it breaks	this page
store — credentials + profiles	auth/credentials.mdx, auth/profiles.mdx
Q&A	auth/faq.mdx

Reading order: overview → pick integration → configure → understand how it runs/breaks.

nav placement

Currently placed between Profiles and FAQ. I'd put it right after configuration, before credentials/profiles — configuration → lifecycle is the natural reading order for someone who just created a connection.

sequencing with #361

The page links to /auth/configuration#custom-proxy in the bot_detected recovery section. That anchor only exists once #361 lands, so #361 should merge first (or they ship together).

mild duplication — debugging section

The Debugging a flaky connection section covers record_session at roughly the same depth as auth/configuration.mdx#record-sessions-for-debugging, then links to it anyway. Could be slimmer here — just show the per-login override pattern (the debugging-flow-specific bit) and link to configuration for the connection-wide flag. Otherwise the same content lives in two places.

minor — overlap with overview's "How It Works"

auth/overview.mdx already has a "How It Works" section, but it's the integration loop (create → login → use). This page is the runtime loop (check → reauth → NEEDS_AUTH). Worth a one-line pointer from overview to the lifecycle page so they don't compete.

verified

• unsupported_auth_method, credentials_invalid, bot_detected, captcha_blocked all exist in packages/api/lib/managedauth/errors.go ✓
• Enterprise 5min / Hobbyist 1hr ✓
• can_reauth eligibility matches the schema ✓

[cursor]

Stale comment

Risk assessment: Very Low

The current diff only changes documentation and Mintlify navigation: it adds auth/connection-lifecycle.mdx, shortens auth/faq.mdx by linking to the dedicated page, updates auth/overview.mdx links/copy, and adds the new page to docs.json. I found no production code, infrastructure, auth implementation, permissions, or prompt/model-instruction changes.

The PR is already approved, so I’m leaving the existing approval in place and not re-approving.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: This PR modifies documentation/content pages, not kernel API endpoints or Temporal workflows; please opt in manually if deploy monitoring is needed.

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

Stale comment

Risk assessment: Very Low

The synchronized diff only changes documentation and Mintlify navigation: it adds auth/connection-lifecycle.mdx, shortens auth/faq.mdx by linking to that dedicated page, updates a small amount of auth/overview.mdx copy/linking, and adds the new page to docs.json.

I found no production code, infrastructure, auth implementation, permissions, schema, or prompt/model-instruction changes. There’s no CODEOWNERS file in this checkout, and the PR is already approved, so I’m leaving the existing approval in place and not re-approving.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[cursor]

Risk assessment: Very Low

The current diff only changes documentation content and Mintlify navigation: it adds auth/connection-lifecycle.mdx, replaces expanded FAQ sections with links to that page, updates one overview link/copy section, and adds the new page to docs.json. I found no production code, infrastructure, auth implementation, permissions logic, or prompt/model-instruction changes.

No CODEOWNERS file is present in the repository metadata I checked. The PR is already approved, so I’m leaving that approval in place and not re-approving.

  

_{Sent by Cursor Automation: Assign PR reviewers}

[masnwilliams]

lgtm - absolutely money