Add Create, Control, Observe introduction guides (#370)

ehfeng · masnwilliams · claude · web-flow · commit cf1d2ab05f21 · 2026-05-23T13:54:51.000-04:00
* add Create, Control, Observe introduction guides Introduce three high-level concept guides under the Introduction group that orient new users around the core surface area: creating browsers, driving them (computer controls vs playwright execution), and observing them (live view, replays, screenshots, logs). * expand standby activity sources to include WebDriver and computer controls * reframe Control intro around three primitives (computer controls, CDP, BiDi) * add lifecycle strip, redirect create-a-browser, add CLI tabs to intro pages * lead with "Computer Use" framing, bridge to Computer Controls API * apply review suggestions: copy tweaks across create, control, observe * promote playwright execution to a peer primitive Add a Playwright Execution tab on Control (position 2, between Computer Use and CDP) and a parallel "Why playwright execution over a direct CDP connection" section. Swap the Create full example to use kernel.browsers.playwright.execute so the recommended path is the one readers see first. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * soften control framing, lead playwright execution with run-from-anywhere - Home page Control card now mentions playwright execution alongside the other three (was drifting from the page itself). - Reframe the Control intro from "four control primitives" to "four ways to drive a session" — playwright execution is a delivery mode on top of CDP, not a separate protocol. - Rewrite the playwright execution tab + bullets around the actual pitch: run any Playwright code from anywhere, no install, no Chromium, no CDP connection to manage. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * restore install snippet on Create, broaden computer-use vs playwright copy - Add the SDK install Info block back to Create (was on the old browsers/create-a-browser page). - Anchor the termination link to the automatic-deletion section. - Rewrite the "Computer use + playwright execution" intro: computer controls don't just lack DOM reads, they lack the whole programmatic surface (page.goto, file uploads, cookies, tab switching). Reach for playwright execution whenever you need any of that. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * Expand control.mdx with computer use + playwright execution patterns (#375) Adds three named patterns (tool, checkpoint, drop-the-agent) as short bullets under the existing recommended-pattern section. No new page. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> * drop checkpoint/drop-the-agent pattern bullets Two patterns that read more like marketing copy than guidance — the preceding paragraph already says what the combined pattern is for. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: ehfeng <279398+ehfeng@users.noreply.github.com> Co-authored-by: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
diff --git a/.docs/code-example-guide.md b/.docs/code-example-guide.md
@@ -360,7 +360,7 @@ Before publishing a code example, verify:
 ## Reference
 
 See these files for examples:
-- `browsers/create-a-browser.mdx` - Standard browser creation pattern
+- `introduction/create.mdx` - Standard browser creation pattern
 - `apps/develop.mdx` - App development pattern
 - `browsers/file-io.mdx` - Complex automation example
 
diff --git a/auth/faq.mdx b/auth/faq.mdx
@@ -36,7 +36,7 @@ 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](/browsers/create-a-browser) directly.
+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.
 
 ## How do I debug a managed auth session?
 
diff --git a/browsers/create-a-browser.mdx b/browsers/create-a-browser.mdx
diff --git a/browsers/pools/scaling.mdx b/browsers/pools/scaling.mdx
@@ -6,7 +6,7 @@ description: "Recommended practices for scaling"
 
 This guide explains how to architect production-scale browser automation systems using Kernel, how to handle high-concurrency workloads, and best practices for building resilient systems.
 
-After understanding the [basics](/browsers/create-a-browser) of our browsers, you should understand how to create and connect to individual browsers on-demand. This guide builds on that foundation to help you design systems using browser pools that can handle hundreds or thousands of concurrent browser tasks reliably.
+After understanding the basics of [creating](/introduction/create) and [controlling](/introduction/control) our browsers, you should understand how to create and connect to individual browsers on-demand. This guide builds on that foundation to help you design systems using browser pools that can handle hundreds or thousands of concurrent browser tasks reliably.
 
 ## Understanding your requirements
 
diff --git a/browsers/standby.mdx b/browsers/standby.mdx
@@ -4,7 +4,16 @@ title: "Standby Mode"
 
 Kernel browsers enter standby mode during periods of inactivity. When a browser goes into standby mode, the browser's state remains the same but incurs zero usage costs.
 
-Kernel browsers automatically enter standby when no CDP or Live View client is connected for `five seconds`. After it enters standby, the browser's [timeout](/browsers/termination#automatic-deletion-via-timeout) countdown begins.
+Kernel browsers automatically enter standby after `five seconds` with no activity. After it enters standby, the browser's [timeout](/browsers/termination#automatic-deletion-via-timeout) countdown begins.
+
+A browser is considered active while any of the following is happening:
+
+- A CDP client is connected (Playwright, Puppeteer, or a raw CDP client)
+- A WebDriver/BiDi client is connected
+- A [Live View](/browsers/live-view) client is connected
+- A [computer controls](/browsers/computer-controls) API request is in flight (clicks, keypresses, screenshots, etc.)
+
+Any of the above resets the standby idle timer. As soon as none are active for five seconds, the browser enters standby.
 
 <Info>
     See [here](/browsers/termination) to learn about destroying browsers. GPU-accelerated browsers do not support standby mode.
diff --git a/browsers/termination.mdx b/browsers/termination.mdx
@@ -31,7 +31,7 @@ kernel.browsers.delete_by_id("htzv5orfit78e1m2biiifpbv")
 
 ## Automatic deletion via timeout
 
-If you don't manually delete a browser, it will be automatically deleted after a configurable `timeout` (default 60 seconds). The timeout begins when the browser does not see a CDP or live view connection.
+If you don't manually delete a browser, it will be automatically deleted after a configurable `timeout` (default 60 seconds). The timeout begins once the browser enters [standby](/browsers/standby) — i.e. when there's no CDP or WebDriver client, no Live View viewer, and no [computer controls](/browsers/computer-controls) request in flight.
 
 You can set a custom timeout of up to 72 hours when creating a browser:
 
diff --git a/changelog.mdx b/changelog.mdx
@@ -199,7 +199,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n
 
 ## Documentation updates
 
-- Renamed "Scaling in Production" to [Reserved Browsers](/browsers/pools/overview) and added a new [On-Demand Browsers](/browsers/create-a-browser) section for clearer guidance on browser provisioning strategies.
+- Renamed "Scaling in Production" to [Reserved Browsers](/browsers/pools/overview) and added a new [On-Demand Browsers](/introduction/create) section for clearer guidance on browser provisioning strategies.
 - Added [mobile and tablet viewport configurations](/browsers/viewport) with supported screen sizes and usage guidance.
 - Added [proxy-bypass-hosts](https://www.kernel.sh/docs/proxies/overview#bypass-hosts) documentation for configuring proxy bypass lists on browser pools.
 - Documented the `--force` flag for [viewport resizing](/browsers/viewport) during active recordings.
diff --git a/docs.json b/docs.json
@@ -11,6 +11,7 @@
     { "source": "/auth/agent/programmatic", "destination": "/auth/programmatic" },
     { "source": "/auth/agent/faq", "destination": "/auth/faq" },
     { "source": "/browsers/hardware-acceleration", "destination": "/browsers/gpu-acceleration" },
+    { "source": "/browsers/create-a-browser", "destination": "/introduction/create" },
     { "source": "/introduction", "destination": "/" },
     { "source": "/quickstart", "destination": "/" },
     { "source": "/home", "destination": "/" }
@@ -64,9 +65,12 @@
         "tab": "Guides",
         "groups": [
           {
-            "group": "home",
+            "group": "Introduction",
             "pages": [
-              "index"
+              "index",
+              "introduction/create",
+              "introduction/control",
+              "introduction/observe"
             ]
           },
           {
@@ -76,7 +80,6 @@
                 "group": "Basics",
                 "expanded": true,
                 "pages": [
-                  "browsers/create-a-browser",
                   "browsers/live-view",
                   "browsers/termination",
                   "browsers/standby",
diff --git a/index.mdx b/index.mdx
@@ -8,7 +8,7 @@ mode: "wide"
 We build crazy fast, open source infra for AI agents to access the internet. Trusted by Cash App, Framer, and 3,000+ teams.
 
 <Columns className="responsive-columns" cols={4}>
-  <Card title="Sandboxed Chromium" img="/images/chromium.svg" href="/browsers/create-a-browser">
+  <Card title="Sandboxed Chromium" img="/images/chromium.svg" href="/introduction/create">
     We spin up cloud browsers in &lt;30ms with GPU acceleration when needed.
   </Card>
   <Card title="Auth" img="/images/auth.svg" href="/auth/overview">
@@ -17,11 +17,25 @@ We build crazy fast, open source infra for AI agents to access the internet. Tru
   <Card title="Stealth Mode" img="/images/stealth.svg" href="/browsers/bot-detection/overview">
     We solve CAPTCHAs and manage residential proxies to help you see fewer of them.
   </Card>
-  <Card title="o11y" img="/images/o11y.svg" href="/browsers/replays">
+  <Card title="o11y" img="/images/o11y.svg" href="/introduction/observe">
     You can view sessions live and record them as MP4s for debugging.
   </Card>
 </Columns>
 
+## start here
+
+<Columns cols={3}>
+  <Card title="Create" href="/introduction/create">
+    Spin up a browser and pick the shape — headless, stealth, GPU, profiles.
+  </Card>
+  <Card title="Control" href="/introduction/control">
+    Drive it with computer use, playwright execution, CDP, or WebDriver BiDi.
+  </Card>
+  <Card title="Observe" href="/introduction/observe">
+    Watch it live, record replays, and capture screenshots.
+  </Card>
+</Columns>
+
 import { CopyPromptButton } from '/snippets/copy-prompt-button.jsx';
 
 <div className="tinker-box">
diff --git a/integrations/notte.mdx b/integrations/notte.mdx
@@ -118,7 +118,7 @@ if __name__ == "__main__":
 
 ## Next steps
 
-- Learn about [creating browsers](/browsers/create-a-browser) on Kernel
+- Learn about [creating browsers](/introduction/create) on Kernel
 - Check out [live view](/browsers/live-view) for debugging your automations
 - Learn about [stealth mode](/browsers/bot-detection/stealth) for avoiding detection
 - Explore [Profiles](/auth/profiles) for maintaining browser state across sessions
diff --git a/integrations/overview.mdx b/integrations/overview.mdx
@@ -46,4 +46,4 @@ Kernel provides detailed guides for popular agent frameworks:
 
 ## Custom Integrations
 
-Kernel works with any tool that supports CDP. Check out our [browser creation guide](/browsers/create-a-browser) to learn how to connect any other agent framework.
+Kernel works with any tool that supports CDP. Check out our [browser control guide](/introduction/control) to learn how to connect any other agent framework.
diff --git a/integrations/vercel/ai-sdk.mdx b/integrations/vercel/ai-sdk.mdx
@@ -181,6 +181,6 @@ So, any code you can run through the SDK can be run via the tool.
 ## Related
 
 - [Vercel Marketplace Integration](/integrations/vercel/marketplace)
-- [Browser Creation](/browsers/create-a-browser)
+- [Browser Creation](/introduction/create)
 - [Stealth Mode](/browsers/bot-detection/stealth)
 - [Live View](/browsers/live-view)
diff --git a/integrations/vercel/marketplace.mdx b/integrations/vercel/marketplace.mdx
@@ -95,7 +95,7 @@ finally:
 ```
 </CodeGroup>
 
-For more examples and features like profiles, stealth mode, and live view, check out the [Browsers documentation](/browsers/create-a-browser).
+For more examples and features like profiles, stealth mode, and live view, check out the [Browsers documentation](/introduction/create).
 
 <Info>
   Check out our [integration guides](/integrations/overview) to learn how to use Vercel + Kernel with your preferred browser automation framework.
diff --git a/introduction/control.mdx b/introduction/control.mdx
diff --git a/introduction/create.mdx b/introduction/create.mdx
diff --git a/introduction/observe.mdx b/introduction/observe.mdx
