Reframe auth docs around two integration paths

auth/configuration.mdx

@@ -8,16 +8,16 @@ Managed Auth connections use the same configuration whether you collect credenti
 
 ## Credentials and Auto-Reauth
 
-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.
+by default, KERNEL saves durable credential fields after a successful login. these can support eligible automatic reauthentication attempts, including totp codes generated from an available secret. submitted one-time codes aren't saved and don't provide access to future codes. if a later login requires user input, your application must start a new interactive login.
 
 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`:
 
 - `health_checks` — whether the connection runs periodic health checks at all. When `false`, the system never automatically verifies the session and never triggers reauth on its own.
-- `auto_reauth` — whether a failed scheduled health check is allowed to attempt re-authentication. When `false`, expired sessions are marked `NEEDS_AUTH` instead of being repaired automatically.
+- `auto_reauth` — whether a scheduled health check that confirms the session is logged out may trigger an eligible automatic reauthentication attempt. when `false`, expired sessions are marked `NEEDS_AUTH` without an automatic recovery attempt.
 
-`auto_reauth` only has an effect on the automatic flow when `health_checks` is also `true`, because reauth is triggered by a failing scheduled health check. Manually triggering a health check via the API still works regardless of `health_checks`.
+`auto_reauth` only has an effect on the automatic flow when `health_checks` is also `true`, because reauthentication requires a scheduled health check to confirm the session is logged out. an inconclusive check doesn't trigger reauthentication. manually triggering a health check via the api still works regardless of `health_checks`.
 
 <CodeGroup>
 ```typescript TypeScript
@@ -443,7 +443,7 @@ After creating a connection, you can update its configuration with `auth.connect
 | `allowed_domains` | Update allowed redirect domains |
 | `health_check_interval` | Seconds between health checks (minimum varies by plan) |
 | `health_checks` | Whether periodic health checks run for this connection |
-| `auto_reauth` | Whether a failed scheduled health check is allowed to attempt automatic re-authentication |
+| `auto_reauth` | Whether a scheduled health check that confirms a logged-out session may trigger an eligible automatic reauthentication attempt |
 | `save_credentials` | Whether to save credentials on successful login |
 | `record_session` | Record a [replay](/browsers/replays) of every auth browser session for this connection (logins, health checks, and reauths) |
 | `browser.region` | Region for login, health-check, and reauth browsers. Takes effect on the next browser created for the connection |

auth/connection-lifecycle.mdx

@@ -88,7 +88,7 @@ After a successful login, Kernel saves the login flow. If a later attempt needs
 
 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.
+- **Switch to TOTP** — if the site supports authenticator apps, add a `totp_secret` to your credential. KERNEL generates codes on demand, removing the need to manually provide that authenticator code. this doesn't eliminate other challenges or guarantee unattended reauthentication. 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.
 
 ## Triggering re-auth manually

auth/credentials.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Credentials"
-description: "Use stored credentials for login and automatic reauthentication"
+title: "Managed Auth Credentials"
+description: "Use stored credentials for login and eligible automatic reauthentication attempts"
 ---
 
-Credentials let you store login information securely. Kernel can automatically authenticate credential-only flows and attempts to provide TOTP codes when needed.
+credentials let you store login information securely. KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. saving credentials or completing an interactive login doesn't guarantee unattended reauthentication. supplying a one-time code doesn't give KERNEL the ability to obtain future codes. if a site requires user input, start a new [interactive login](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval).
 
 **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)

auth/faq.mdx

@@ -4,15 +4,19 @@ title: FAQ
 
 ## How does automatic re-authentication work?
 
-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.
+with health checks and automatic reauthentication enabled, KERNEL attempts reauthentication when a scheduled health check confirms that an eligible connection is logged out. `can_reauth: true` means eligible to attempt, not guaranteed to succeed. stored credentials and an available totp secret can support unattended login, but a new code, choice, or approval that requires a user can leave the connection in `NEEDS_AUTH`. your application must start a new interactive login when user input is required. see [connection lifecycle](/auth/connection-lifecycle) for cadence options and eligibility rules.
+
+## Can managed auth automatically handle email or sms verification?
+
+not during unattended reauthentication. if a site requires an email or sms code, your application must start a new interactive login and bring the user back to provide it through the [hosted ui](/auth/hosted-ui), [react component](/auth/react), or [programmatic flow](/auth/programmatic). wait for successful authentication before resuming the automation. a code supplied during an earlier login doesn't give KERNEL access to future codes.
 
 ## 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 common credential, SSO, and multi-step login flows. Automatic reauthentication uses stored credentials and attempts to provide TOTP codes when needed.
+managed auth supports common credential, sso, and multi-step interactive login flows. automatic reauthentication is limited to eligible flows that can complete without human input. KERNEL can generate totp codes from an available secret; email and sms codes, approvals, and other user-required steps need an interactive login.
 
 <Warning>
 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.
@@ -24,7 +28,7 @@ Kernel surfaces an error code (`credentials_invalid`, `account_locked`, `bot_det
 
 ## Can I use Managed Auth with any website?
 
-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.
+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/managed-auth#why-managed-auth) and test your target flow.
 
 ## Is Managed Auth available during a trial?
 

auth/fill-from-vault.mdx

@@ -0,0 +1,91 @@
+---
+title: "Overview"
+description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow"
+---
+
+import CreateCredentialVault from "/snippets/create-credential-vault.mdx";
+import AttachCredentialVault from "/snippets/attach-credential-vault.mdx";
+import CollectBrowserCredentials from "/snippets/collect-browser-credentials.mdx";
+import FillBrowserCredentials from "/snippets/fill-browser-credentials.mdx";
+
+Fill from Vault is an integration path where your application or agent controls the login workflow. vaults store encrypted credential items. our `fill` api call writes selected values from an item into browser fields, without exposing secrets to your application or agent. your application or agent owns navigation, field selection, submission, and recovery.
+
+start with the [end-user auth workflow cookbook](/browsers/use-vault-credentials-in-browser-agent) for an end-to-end example of secure collection, browser attachment, the `fill` operation, form submission, and cleanup.
+
+KERNEL collects credential values from the user or accepts them from a trusted backend. when invoking `fill`, your controller sends field names and selectors rather than credential values. KERNEL reads the encrypted item and returns value-free outcomes, keeping stored secrets out of agent prompts and browser-automation payloads.
+
+<Note>
+  `fill` only writes stored values into fields you select. it doesn't discover fields, navigate, submit forms, verify authentication, monitor the session, or reauthenticate. your application or agent owns each of those steps.
+</Note>
+
+
+## When to use it
+
+Fill from Vault works best when:
+
+- a login or authentication prompt can appear in the middle of a workflow, in the same browser session.
+- your product needs to control the credential collection experience.
+- your application or agent already handles browser navigation and site-specific recovery.
+- you don't need KERNEL to monitor the session or reauthenticate it automatically.
+
+choose [managed auth](/auth/managed-auth) instead when you want KERNEL to run the login flow, save the authenticated state, monitor the connection, and attempt reauthentication for eligible flows.
+
+## How it works
+
+these examples continue in order, using hacker news as the login destination. set `KERNEL_API_KEY` in your trusted backend environment. all examples use the default project; keep the vault and browser in the same project if you select a different one.
+
+<Steps>
+  <Step title="Create a Vault">
+    create a [vault](/vaults/overview) for each end user or credential-sharing boundary. A vault groups the items that an attached browser session can use.
+
+    <CreateCredentialVault />
+  </Step>
+  <Step title="Attach the Vault to a Browser">
+    attach the vault when you create the browser. The attachment can't change during the session and grants access to every item in that vault.
+
+    <AttachCredentialVault />
+  </Step>
+  <Step title="Navigate and Collect Credentials">
+    your application or agent navigates to the login page and identifies its fields before defining a [credential item](/vaults/credentials). hacker news has both login and create-account forms; the selectors in the next step target the login form. inspect the page and recheck them if it changes.
+
+    <CollectBrowserCredentials />
+
+    present the collection url only in the intended user's authenticated interface or private conversation. don't log it or open it in the agent-controlled browser. wait for the user to finish before continuing. an existing ready item may omit the collection action; reuse it or follow [credential collection](/vaults/credentials#collect-values-from-the-user) to reopen the form.
+  </Step>
+  <Step title="Invoke the Fill Operation">
+    retrieve the same item, require readiness and an advertised `fill` operation, then invoke [`fill`](/vaults/fill) with field names and selectors. readiness means values exist, not that the website has accepted them. your application must authorize the destination before filling.
+
+    <FillBrowserCredentials />
+
+    `completed` means the selected fields were filled, not that login succeeded. if `fill` fails, returns an uncertain outcome, or loses its response, stop and [inspect the outcome](/vaults/fill#handle-the-outcome) rather than automatically retrying.
+  </Step>
+  <Step title="Submit and Handle the Response">
+    after `fill` completes, your application or agent submits the login form once and verifies the site's response. `fill` doesn't perform either step. handle any additional authentication prompts before continuing the task.
+
+    delete the demo browser when finished, and delete the vault only if you created it for this demo and no longer need its credentials. see the [cookbook](/browsers/use-vault-credentials-in-browser-agent) for the complete agent handoff and cleanup guidance.
+  </Step>
+</Steps>
+
+## Credential sources
+
+you can collect values from an end user with KERNEL's hosted collection form or [copy them from an existing credential vault](/vaults/existing-credential-vault) that your trusted backend can read. both paths produce a ready credential item and use the same `fill` operation.
+
+today, copying values stores an encrypted KERNEL copy. `fill` doesn't accept raw values or a third-party vault reference in its request.
+
+## Session state
+
+`fill` completes one part of the workflow. it doesn't monitor the resulting session or reauthenticate it later. if you want to reuse the authenticated state, create the browser with a [profile](/browsers/profiles) and save its changes after the login succeeds.
+
+## Next steps
+
+<CardGroup cols={3}>
+  <Card title="Credential Items" icon="lock" href="/vaults/credentials">
+    define fields, collect values, and update credentials without returning sensitive values.
+  </Card>
+  <Card title="Fill Browser Fields" icon="input-text" href="/vaults/fill">
+    map credential fields to browser inputs and handle completed, failed, or unknown outcomes.
+  </Card>
+  <Card title="Build an End-User Auth Workflow" icon="user-lock" href="/browsers/use-vault-credentials-in-browser-agent">
+    follow the complete collection and browser fill workflow with the sdk or cli.
+  </Card>
+</CardGroup>

auth/hosted-ui.mdx

@@ -93,7 +93,7 @@ The user will:
 3. Complete 2FA or another verification step if needed
 
 <Info>
-Kernel can automatically reauthenticate credential-only flows and attempts to provide TOTP codes when needed.
+KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. completing this interactive login doesn't guarantee unattended reauthentication. supplying an email or sms code doesn't give KERNEL access to future codes. when the connection needs user input again, start a new login and direct the user to its `hosted_url`. see [connection recovery](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval).
 </Info>
 
 ### 4. Stream until completion