clarify managed auth reauthentication scope

auth/configuration.mdx

@@ -4,13 +4,13 @@ sidebarTitle: "Configuration"
 description: "Shared options for managed auth connections, regardless of integration flow"
 ---
 
-Managed Auth Connections are configured the same way regardless of how you collect credentials — via [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). The options below live on the connection itself and apply to the initial login, every background health check, and every automatic re-authentication.
+Managed Auth connections use the same configuration whether you collect credentials through the [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). These options apply to the initial login, every background health check, and each automatic reauthentication attempt.
 
 ## Credentials and Auto-Reauth
 
-Credentials are saved after every successful login, enabling automatic re-authentication when the session expires. One-time codes (TOTP, SMS, etc.) are not saved.
+By default, Kernel saves durable credential fields after a successful login. Kernel can automatically reauthenticate credential-only flows and attempts to provide TOTP codes when needed. Submitted one-time codes (TOTP, SMS, etc.) aren't saved.
 
-To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for more on automated authentication.
+To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for configuration examples.
 
 Automatic re-authentication is gated by two boolean flags that both default to `true`:
 
@@ -56,7 +56,9 @@ _ = auth
 
 Both flags can be flipped on an existing connection with `auth.connections.update`; changes take effect immediately on the running connection.
 
-Setting `auto_reauth: true` is an opt-in only — it doesn't guarantee reauth is feasible. The system still needs what it requires to perform the login (e.g. saved credentials for the required fields). If those preconditions aren't met when a health check fails, the connection transitions to `NEEDS_AUTH` even with `auto_reauth: true`.
+Automatic reauthentication requires a previously successful login and saved credentials for the durable login fields. Setting `auto_reauth: true` permits Kernel to attempt it but doesn't guarantee the next login will succeed.
+
+If Kernel can't complete an automatic attempt, the connection transitions to `NEEDS_AUTH` so you can start a new login.
 
 ## Custom Login URL
 
@@ -96,7 +98,7 @@ _ = auth
 
 ## SSO/OAuth Support
 
-Sites with "Sign in with Google/GitHub/Microsoft" are supported. The user completes the OAuth flow with the provider, and the authenticated session is automatically saved to the Kernel profile.
+Managed Auth supports common "Sign in with Google/GitHub/Microsoft" flows. The user completes the OAuth flow with the provider, and Kernel saves the authenticated session to the profile. Automatic reauthentication depends on the provider's login requirements. See [Can this connection auto-reauth?](/auth/connection-lifecycle#can-this-connection-auto-reauth) for how Kernel determines eligibility.
 
 Common SSO provider domains are automatically allowed by default, including Google, Microsoft/Azure AD, Okta, Auth0, Apple, GitHub, Facebook, LinkedIn, Amazon Cognito, OneLogin, and Ping Identity. You don't need to add these to `allowed_domains`.
 

auth/connection-lifecycle.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "Lifecycle"
 description: "How connections stay authenticated, and what to do when one breaks"
 ---
 
-Once a Managed Auth connection is `AUTHENTICATED`, Kernel runs periodic health checks and automatic re-authentication to keep the session valid. This page covers the runtime lifecycle of a connection: how the check-and-reauth loop works, how to tune it, what blocks auto-reauth, and how to debug a connection that won't stay logged in.
+Once a Managed Auth connection is `AUTHENTICATED`, Kernel runs periodic health checks. For eligible flows, Kernel can automatically reauthenticate the session to keep it valid. This page covers the runtime lifecycle, configuration options, and recovery steps.
 
 ## The lifecycle
 
@@ -17,12 +17,12 @@ After the initial login, every connection moves through this loop:
     A check needs concrete evidence to conclude. If the site returns a challenge page, times out, partially loads, or shows something ambiguous, the result is inconclusive and the connection is left exactly as it was. Nothing happens until the next check.
   </Step>
   <Step title="Auto-reauth (if eligible)">
-    If the check finds the session **definitely** expired and the connection's `can_reauth` is `true`, Kernel runs the saved login flow with the stored credentials in the background. A successful login resets the loop.
+    If the check finds the session **definitely** expired and the connection's `can_reauth` is `true`, Kernel runs the saved credential-based login flow in the background. A successful login resets the loop.
 
     An inconclusive check never triggers reauth. Kernel would rather check again on the next cycle than log in again unnecessarily — a spurious login can trip risk checks on the site, prompt a device-verification email, or invalidate a working session.
   </Step>
-  <Step title="NEEDS_AUTH (if not eligible, or auto-reauth fails)">
-    If auto-reauth isn't possible — credentials aren't linked, the saved flow requires human input, or the login keeps failing — the connection's `status` flips to `NEEDS_AUTH` and a new login session is required.
+  <Step title="NEEDS_AUTH (when action is required)">
+    If automatic reauthentication isn't possible — for example, credentials are missing, human input is required, or the login keeps failing — the connection's `status` changes to `NEEDS_AUTH`. Start a new login session to continue.
   </Step>
 </Steps>
 
@@ -66,24 +66,27 @@ if err != nil {
 
 ### Sessions that expire faster than the interval
 
-Kernel keeps re-authenticating even when every health check finds the session expired. A successful login resets the auto-reauth state, so a site whose session TTL is shorter than your health check interval is re-authenticated on every cycle rather than being given up on.
+For an eligible connection, Kernel continues reauthenticating when every health check finds the session expired. A successful login resets the automatic reauthentication state, so a site whose session TTL is shorter than your health check interval is reauthenticated on every cycle.
 
 If you're seeing the connection flip to `NEEDS_AUTH` frequently and want shorter detection windows, lower `health_check_interval` toward your plan's minimum.
 
 ## Can this connection auto-reauth?
 
-Check the `can_reauth` boolean on a connection. It's `true` only when **both** of these hold:
+Check the `can_reauth` boolean on a connection. It describes eligibility to attempt reauthentication, not whether the next login will succeed. It's `true` only when all of these conditions hold:
 
-1. **A credential is linked** — stored in Kernel or sourced via [1Password](/integrations/1password).
-2. **No known human-only requirement is recorded** — for example, an sms/email code, push approval, or other external action.
+1. **A previous login succeeded** — Kernel has recorded the result of a completed login.
+2. **A credential is linked** — It's stored in Kernel or sourced from [1Password](/integrations/1password).
+3. **No blocking requirement is recorded** — Kernel hasn't recorded a requirement that prevents an automatic attempt.
 
-If either fails, the connection will move to `NEEDS_AUTH` on the next expired session and wait for a fresh login. A site can still present a new or conditional challenge during reauth; if Kernel can't resolve it safely, reauth stops and the connection moves to `NEEDS_AUTH`.
+Use `can_reauth_reason` to see why the connection is or isn't eligible. See [Get auth connection](https://kernel.sh/docs/api-reference/managed-auth/get-auth-connection) for the possible values.
 
-### External actions that block auto-reauth
+`can_reauth` reflects what Kernel knows about the previous login. A site can introduce a new requirement during a later attempt. If Kernel needs input, a choice, or approval, the connection moves to `NEEDS_AUTH` so you can start a new login.
 
-After a successful login, Kernel saves the login flow. If that flow includes steps that require human action, the connection can't auto-reauth because those steps can't be replayed without user input.
+### Flows that need input, a choice, or approval
 
-If your flow requires one of these, you can still automate around it:
+After a successful login, Kernel saves the login flow. If a later attempt needs input, a choice, or approval, the connection moves to `NEEDS_AUTH` instead of guessing how to proceed.
+
+You can handle these flows in two ways:
 
 - **Switch to TOTP** — If the site supports authenticator apps, add a `totp_secret` to your credential. Codes are generated on demand, so the flow no longer needs external action. If a code expires before the site accepts it, Kernel retries with a fresh one.
 - **Trigger manual re-auth** — Start a new login session and route the user through the [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic) flow.

auth/credentials.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Credentials"
-description: "Automate authentication with stored credentials"
+description: "Use stored credentials for login and automatic reauthentication"
 ---
 
-Credentials allow you to store login information securely and enable Kernel's automated re-authentication without requiring user interaction.
+Credentials let you store login information securely. Kernel can automatically authenticate credential-only flows and attempts to provide TOTP codes when needed.
 
 **There are three ways to provide credentials:**
 - **Automatically save during login** — Capture credentials directly from the user when they log in via [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic)
-- **Pre-store in Kernel** — Create credentials before any login for fully headless automation
+- **Pre-store in Kernel** — Create credentials before login for supported headless authentication flows
 - **Connect 1Password** — Use credentials from your existing 1Password vaults
 
 <Card title="1Password Integration" icon="key" href="/integrations/1password">
@@ -16,7 +16,7 @@ Credentials allow you to store login information securely and enable Kernel's au
 
 ## Save credentials during login
 
-By default, credentials entered during login are automatically saved for re-authentication. No extra parameters are needed:
+By default, Kernel saves durable credential fields entered during login so they can be used for eligible reauthentication attempts. No extra parameters are needed:
 
 <CodeGroup>
 ```typescript TypeScript
@@ -36,7 +36,7 @@ _ = login
 ```
 </CodeGroup>
 
-Once saved, browser profiles stay authenticated automatically. When the session expires, Kernel re-authenticates using the stored credentials. Credentials are updated after every successful login. One-time codes (TOTP, SMS, etc.) are not saved.
+Once saved, the browser profile reuses its authenticated session until the site expires it. For supported credential-based flows, Kernel can then reauthenticate with the stored values. Credentials are updated after every successful login. Submitted one-time codes aren't saved; Kernel generates TOTP codes from a stored `totp_secret`.
 
 To opt out of credential saving, set `save_credentials: false` when creating the connection:
 
@@ -74,7 +74,7 @@ _ = auth
 
 ## Pre-store credentials
 
-For fully automated flows where no user is involved, create credentials upfront:
+For credential-based flows that you want to run without user input, create credentials upfront:
 
 <CodeGroup>
 ```typescript TypeScript
@@ -127,7 +127,7 @@ const auth = await kernel.auth.connections.create({
   credential: { name: credential.name },
 });
 
-// Start login - authenticates automatically using stored credentials
+// Start login with stored credentials
 const login = await kernel.auth.connections.login(auth.id);
 ```
 
@@ -138,7 +138,7 @@ auth = await kernel.auth.connections.create(
     credential={"name": credential.name},
 )
 
-# Start login - authenticates automatically using stored credentials
+# Start login with stored credentials
 login = await kernel.auth.connections.login(auth.id)
 ```
 
@@ -156,7 +156,7 @@ if err != nil {
 	panic(err)
 }
 
-// Start login - authenticates automatically using stored credentials
+// Start login with stored credentials
 login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{})
 if err != nil {
 	panic(err)
@@ -167,7 +167,7 @@ _ = login
 
 ### 2FA with TOTP
 
-For sites with authenticator app 2FA, include `totp_secret` to fully automate login:
+For sites with authenticator app 2FA, include `totp_secret` so Kernel can generate a fresh code during automatic login and reauthentication:
 
 <CodeGroup>
 ```typescript TypeScript
@@ -215,9 +215,9 @@ _ = credential
 
 ### SSO / OAuth
 
-For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` and Kernel automatically clicks the matching SSO button and completes OAuth.
+For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements.
 
-Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are automatically allowed — you don't need to add them to `allowed_domains`:
+Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are allowed by default, so you don't need to add them to `allowed_domains`:
 
 <CodeGroup>
 ```typescript TypeScript

auth/faq.mdx

@@ -4,18 +4,18 @@ title: FAQ
 
 ## How does automatic re-authentication work?
 
-When you link credentials to a connection, Kernel runs periodic health checks, detects logged-out sessions, and re-authenticates in the background so the profile stays logged in. See [Connection Lifecycle](/auth/connection-lifecycle) for the full lifecycle, cadence options, and `can_reauth` rules.
+When you link credentials to a connection, Kernel runs periodic health checks and can reauthenticate supported credential-based flows in the background. This includes TOTP when Kernel can provide the authenticator code. See [Connection Lifecycle](/auth/connection-lifecycle) for the full lifecycle, cadence options, and `can_reauth` rules.
 
 ## What are auth choices?
 
 Auth choices are visible routes a site presents during login, including mfa methods, sso providers, account pickers, and organization selectors. They appear in the canonical `choices` array. Submit the exact returned id with `interaction_id` and `selected_choice_id`. See the [programmatic flow guide](/auth/programmatic#choices) for examples.
 
 ## Which authentication methods are supported?
 
-Managed Auth supports username/password authentication and most SSO providers. 
+Managed Auth supports common credential, SSO, and multi-step login flows. Automatic reauthentication uses stored credentials and attempts to provide TOTP codes when needed.
 
 <Warning>
-Passkey-based authentication (e.g., Google accounts with passkeys enabled) is not currently supported. If a user's SSO provider requires a passkey, the login will fail with the `unsupported_auth_method` error code.
+Passkey-only authentication isn't currently supported. If a site's SSO provider requires a passkey, the login returns `unsupported_auth_method`. Switch the account to a supported sign-in method, such as password and TOTP, then start a new login.
 </Warning>
 
 ## What happens if login fails?
@@ -24,7 +24,7 @@ Kernel surfaces an error code (`credentials_invalid`, `account_locked`, `bot_det
 
 ## Can I use Managed Auth with any website?
 
-Managed Auth works with most websites. Sites with aggressive bot detection may require additional configuration (stealth mode, proxies). Passkeys and hardware security keys are not currently supported.
+Managed Auth covers common login flows across a broad range of websites. Site-specific authentication and bot detection can require additional configuration. See [what Managed Auth supports](/auth/overview#why-managed-auth) and test your target flow.
 
 ## Is Managed Auth available during a trial?
 
@@ -36,25 +36,25 @@ Call `.login()` on the connection to trigger auth immediately. See [Triggering r
 
 ## What types of flows does Managed Auth support?
 
-Managed Auth handles login and authentication flows end-to-end: entering credentials, multi-step login forms (e.g. email on one page, password on the next), SSO redirects, MFA challenges, and keeping sessions alive. For post-login browser work like form filling, sign-ups, or other workflows, use [Kernel's browser automation](/introduction/control) directly.
+Managed Auth navigates login pages, enters stored credentials, follows SSO redirects, guides users through additional authentication steps, and saves the resulting browser session. For post-login work like form filling, sign-ups, or other workflows, use [Kernel's browser automation](/introduction/control) directly.
 
 ## How do I debug a managed auth session?
 
 Use the **Browser Sessions** tab in the dashboard for live view, or set `record_session: true` to capture replays of every auth browser session. See [Debugging a flaky connection](/auth/connection-lifecycle#debugging-a-flaky-connection) for details.
 
 ## Can I attach multiple auth connections to one profile?
 
-Yes. A profile can have any number of auth connections, each for a different domain. When you create a browser with that profile, it is already logged in to every connected domain.
+Yes. A profile can have any number of auth connections, each for a different domain. When you create a browser with that profile, it loads the saved authentication state for every connected domain.
 
 This is useful for two common patterns:
 
-- **Multi-site workflows** — Your agent visits multiple sites in a single run (e.g., reads email in Gmail, posts a summary in Slack, and updates a CRM). Attach one auth connection per site to a single profile, and the browser starts logged in to all of them.
+- **Multi-site workflows** — Your agent visits multiple sites in a single run (e.g., reads email in Gmail, posts a summary in Slack, and updates a CRM). Attach one auth connection per site to a single profile, and each browser loads the saved authentication state for all of them.
 - **User-to-profile mapping** — Each end user on your platform gets one profile. All of that user's accounts (Gmail, LinkedIn, GitHub, etc.) are auth connections on their profile. When the user triggers a workflow, launch a browser with their profile.
 
 See [Profiles — Multiple auth connections per profile](/auth/profiles#multiple-auth-connections-per-profile) for code examples.
 
 ## How is Managed Auth billed?
 
-Managed Auth is included on all plans with no per-connection fees. It uses browser sessions to log in and keep your sessions fresh—these count toward your browser usage like any other browser session.
+Managed Auth is included on all plans with no per-connection fees. It uses browser sessions for login, health checks, and eligible reauthentication attempts. These count toward your browser usage like any other browser session.
 
-Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and re-authenticates automatically when sessions expire—most stay valid for days. For example, keeping 100 auth connections logged in typically costs less than $5/month in browser usage. See [Pricing & Limits](/info/pricing#managed-auth) for details.
+Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and can automatically reauthenticate eligible credential-based flows when sessions expire. Most sessions stay valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. See [Pricing & Limits](/info/pricing#managed-auth) for details.