vercel-labs · Railly · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026 · Sep 18, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -41,6 +41,42 @@ jobs:
       - name: Run launcher tests
         run: pnpm run test:launcher
 
+  docs:
+    name: Docs (${{ matrix.environment }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        environment: [production, preview]
+    env:
+      VERCEL_ENV: ${{ matrix.environment }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Test original documentation contract
+        run: pnpm --filter docs test
+
+      - name: Typecheck documentation
+        run: pnpm --filter docs type-check
+
+      - name: Build documentation
+        run: pnpm --filter docs build
+
+      - name: Verify public documentation routes
+        run: pnpm --filter docs test:routes ${{ matrix.environment == 'preview' && '--preview' || '' }}
+
   rust:
     name: Rust
     runs-on: ubuntu-latest

diff --git a/AGENTS.md b/AGENTS.md
@@ -22,7 +22,7 @@ When adding or changing user-facing features (new flags, commands, behaviors, en
 1. `cli/src/output.rs` — `--help` output (flags list, examples, environment variables)
 2. `README.md` — Options table, relevant feature sections, examples
 3. `skill-data/core/SKILL.md` (and its `references/`) — so AI agents know about the feature when they load the core skill. Edit `skill-data/core/SKILL.md` for overview/workflow changes; edit `skill-data/core/references/*.md` for detailed reference content. Do **not** put feature content in `skills/agent-browser/SKILL.md` — that file is an intentionally thin discovery stub for `npx skills add` and exists only to redirect agents to `agent-browser skills get core`.
-4. `docs/src/app/` — the Next.js docs site (MDX pages)
+4. `docs/content/docs/` — the Geistdocs site (MDX pages); routing and API handlers live in `docs/src/app/`
 5. Inline doc comments in the relevant source files
 
 This applies to changes that either human users or AI agents would need to know about. Do not skip any of these locations.
@@ -31,7 +31,11 @@ This applies to changes that either human users or AI agents would need to know
 
 When adding or changing any CLI command, flag, behavior, output, environment variable, or parser semantics, update the MCP server in `cli/src/mcp.rs` in the same change. MCP tools should stay in sync with canonical CLI behavior by delegating through the normal CLI parser where possible. If a CLI command has no dedicated MCP tool, add one or document why it is intentionally omitted. Add or update tests that prove the CLI and MCP surfaces remain aligned.
 
-In the `docs/src/app/` MDX files, always use HTML `<table>` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site.
+In the `docs/content/docs/` MDX files, always use HTML `<table>` syntax for tables (not markdown pipe tables). This matches the existing convention across the docs site. Page titles and descriptions live in frontmatter; do not duplicate the title as an H1 in the body.
+
+For documentation changes, run `pnpm --filter docs test`, `pnpm --filter docs type-check`, `pnpm --filter docs build`, and `pnpm --filter docs test:routes`. The route suite starts its own production server. Its frozen migration fixtures cover the original public routes, metadata, content, anchors, and API contracts; only update affected fixtures when deliberately changing that contract.
+
+The Vercel docs project uses `docs` as its Root Directory and must enable **Include source files outside of the Root Directory in the Build Step** (`sourceFilesOutsideRootDirectory`). Installation requires the repository's `pnpm-workspace.yaml`, root `pnpm-lock.yaml`, and `patches/`. Keep the docs `packageManager` pin aligned with the root and use the Corepack commands in `docs/vercel.json`; do not create a separate docs lockfile or disable frozen installs.
 
 ## Dashboard (packages/dashboard)
 
@@ -48,7 +52,7 @@ To prepare a release:
 2. Bump `version` in `package.json`
 3. Run `pnpm version:sync` to update `cli/Cargo.toml`, `cli/Cargo.lock`, and `packages/dashboard/package.json`
 4. Write the changelog entry in `CHANGELOG.md` at the top, under a new `## <version>` heading, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry so only the new release has markers.
-5. Add a matching entry to `docs/src/app/changelog/page.mdx` at the top (below the `# Changelog` heading)
+5. Add a matching entry to `docs/content/docs/changelog.mdx` at the top (below the frontmatter)
 6. Open a PR and merge to `main`
 
 When the PR merges, CI compares `package.json` version to what's on npm. If it differs, it builds all 7 platform binaries, publishes to npm, and creates the GitHub release automatically. The GitHub release body is extracted from the content between the `<!-- release:start -->` and `<!-- release:end -->` markers in `CHANGELOG.md`.
@@ -85,7 +89,7 @@ Do not prefix entries with commit hashes. Do not use the changesets `### Patch C
 
 ### Docs changelog
 
-The docs changelog at `docs/src/app/changelog/page.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
+The docs changelog at `docs/content/docs/changelog.mdx` mirrors `CHANGELOG.md` but uses a slightly different format. Each entry uses:
 
 - A `v` prefix on the version (e.g. `## v0.24.0`)
 - A date line with the full date: `<p className="text-[#888] text-sm">March 30, 2026</p>`

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -15,6 +15,7 @@
 
 # next.js
 /.next/
+/.source/
 /out/
 
 # production

diff --git a/docs/src/app/cdp-mode/page.mdx → docs/content/docs/cdp-mode.mdx b/docs/src/app/cdp-mode/page.mdx → docs/content/docs/cdp-mode.mdx
@@ -1,4 +1,7 @@
-# CDP Mode
+---
+title: "CDP Mode"
+navTitle: "CDP Mode"
+---
 
 Connect to an existing browser via Chrome DevTools Protocol:
 

diff --git a/docs/src/app/changelog/page.mdx → docs/content/docs/changelog.mdx b/docs/src/app/changelog/page.mdx → docs/content/docs/changelog.mdx
@@ -1,4 +1,7 @@
-# Changelog
+---
+title: "Changelog"
+navTitle: "Changelog"
+---
 
 ## v0.38.1
 

diff --git a/docs/src/app/commands/page.mdx → docs/content/docs/commands.mdx b/docs/src/app/commands/page.mdx → docs/content/docs/commands.mdx
@@ -1,4 +1,7 @@
-# Commands
+---
+title: "Commands"
+navTitle: "Commands"
+---
 
 ## Core
 

diff --git a/docs/src/app/configuration/page.mdx → docs/content/docs/configuration.mdx b/docs/src/app/configuration/page.mdx → docs/content/docs/configuration.mdx
@@ -1,4 +1,7 @@
-# Configuration
+---
+title: "Configuration"
+navTitle: "Configuration"
+---
 
 Create an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.
 

diff --git a/docs/src/app/dashboard/page.mdx → docs/content/docs/dashboard.mdx b/docs/src/app/dashboard/page.mdx → docs/content/docs/dashboard.mdx
@@ -1,4 +1,7 @@
-# Observability Dashboard
+---
+title: "Observability Dashboard"
+navTitle: "Dashboard"
+---
 
 Monitor agent-browser sessions in real time with a local web dashboard showing a live browser viewport and command activity feed.
 

diff --git a/docs/src/app/debugging/page.mdx → docs/content/docs/debugging.mdx b/docs/src/app/debugging/page.mdx → docs/content/docs/debugging.mdx
@@ -1,4 +1,7 @@
-# Debugging
+---
+title: "Debugging"
+navTitle: "Debugging"
+---
 
 Use debugging commands to inspect browser logs, page errors, JavaScript dialogs, Chrome DevTools traces, highlighted elements, and the live DevTools frontend during automation.
 

diff --git a/docs/src/app/diffing/page.mdx → docs/content/docs/diffing.mdx b/docs/src/app/diffing/page.mdx → docs/content/docs/diffing.mdx
@@ -1,6 +1,9 @@
+---
+title: "Diffing"
+navTitle: "Diffing"
+---
 import { DiffDemo } from "@/components/diff-demo"
 
-# Diffing
 
 Compare page states to detect changes -- structurally via accessibility tree snapshots, visually via pixel comparison, or across two different URLs.
 

diff --git a/docs/src/app/engines/chrome/page.mdx → docs/content/docs/engines/chrome.mdx b/docs/src/app/engines/chrome/page.mdx → docs/content/docs/engines/chrome.mdx
@@ -1,4 +1,7 @@
-# Chrome
+---
+title: "Chrome"
+navTitle: "Chrome"
+---
 
 Chrome (and Chromium) is the default browser engine. agent-browser discovers, launches, and manages the Chrome process automatically via the Chrome DevTools Protocol (CDP).
 

diff --git a/docs/src/app/engines/lightpanda/page.mdx → docs/content/docs/engines/lightpanda.mdx b/docs/src/app/engines/lightpanda/page.mdx → docs/content/docs/engines/lightpanda.mdx
@@ -1,4 +1,7 @@
-# Lightpanda
+---
+title: "Lightpanda"
+navTitle: "Lightpanda"
+---
 
 [Lightpanda](https://lightpanda.io/) is a headless browser engine built from scratch in Zig for machines. It starts instantly, uses 10x less memory than Chrome, and executes 10x faster.
 

diff --git a/docs/content/docs/engines/meta.json b/docs/content/docs/engines/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Engines",
+  "pages": ["chrome", "lightpanda"]
+}
diff --git a/docs/src/app/eve/page.mdx → docs/content/docs/eve.mdx b/docs/src/app/eve/page.mdx → docs/content/docs/eve.mdx
@@ -1,4 +1,7 @@
-# eve Extension
+---
+title: "eve Extension"
+navTitle: "eve Extension"
+---
 
 `@agent-browser/eve` mounts the full agent-browser tool set into an [eve](https://eve.dev) agent. The tools run `agent-browser` inside the agent sandbox, so the browser process, downloads, screenshots, and state stay out of the Next.js runtime.
 

diff --git a/docs/src/app/files/page.mdx → docs/content/docs/files.mdx b/docs/src/app/files/page.mdx → docs/content/docs/files.mdx
@@ -1,4 +1,7 @@
-# Files & Clipboard
+---
+title: "Files & Clipboard"
+navTitle: "Files & Clipboard"
+---
 
 agent-browser can upload files, capture downloads, read local files through `file://` URLs, write PDFs and screenshots, and interact with the browser clipboard.
 

diff --git a/docs/src/app/page.mdx → docs/content/docs/index.mdx b/docs/src/app/page.mdx → docs/content/docs/index.mdx
@@ -1,4 +1,7 @@
-# agent-browser
+---
+title: "agent-browser"
+navTitle: "Introduction"
+---
 
 Browser automation CLI designed for AI agents. Compact text output minimizes context usage. 100% native Rust.
 

diff --git a/docs/src/app/init-scripts/page.mdx → docs/content/docs/init-scripts.mdx b/docs/src/app/init-scripts/page.mdx → docs/content/docs/init-scripts.mdx
@@ -1,4 +1,7 @@
-# Init Scripts & Extensions
+---
+title: "Init Scripts & Extensions"
+navTitle: "Init Scripts"
+---
 
 Init scripts run before page JavaScript. Use them to install hooks, polyfills, instrumentation, or test helpers before the first navigation.
 

diff --git a/docs/src/app/installation/page.mdx → docs/content/docs/installation.mdx b/docs/src/app/installation/page.mdx → docs/content/docs/installation.mdx
@@ -1,4 +1,7 @@
-# Installation
+---
+title: "Installation"
+navTitle: "Installation"
+---
 
 ## Global installation (recommended)
 

diff --git a/docs/src/app/ios/page.mdx → docs/content/docs/ios.mdx b/docs/src/app/ios/page.mdx → docs/content/docs/ios.mdx
@@ -1,4 +1,7 @@
-# iOS Simulator
+---
+title: "iOS Simulator"
+navTitle: "iOS Simulator"
+---
 
 Control real Mobile Safari in the iOS Simulator for authentic mobile web testing. Uses Appium with XCUITest for native automation.
 

diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
@@ -0,0 +1,41 @@
+{
+  "pages": [
+    "index",
+    "installation",
+    "quick-start",
+    "skills",
+    "---Reference---",
+    "commands",
+    "configuration",
+    "plugins",
+    "selectors",
+    "snapshots",
+    "---Features---",
+    "sessions",
+    "dashboard",
+    "diffing",
+    "network",
+    "cdp-mode",
+    "webmcp",
+    "streaming",
+    "recording",
+    "webgpu",
+    "debugging",
+    "profiler",
+    "react",
+    "files",
+    "init-scripts",
+    "proxy",
+    "ios",
+    "security",
+    "next",
+    "eve",
+    "native-mode",
+    "---Providers---",
+    "...providers",
+    "---Engines---",
+    "...engines",
+    "---",
+    "changelog"
+  ]
+}
diff --git a/docs/src/app/native-mode/page.mdx → docs/content/docs/native-mode.mdx b/docs/src/app/native-mode/page.mdx → docs/content/docs/native-mode.mdx
@@ -1,4 +1,7 @@
-# Native Mode
+---
+title: "Native Mode"
+navTitle: "Native Mode"
+---
 
 agent-browser is now 100% native Rust by default. The Node.js/Playwright daemon has been removed.
 

diff --git a/docs/src/app/network/page.mdx → docs/content/docs/network.mdx b/docs/src/app/network/page.mdx → docs/content/docs/network.mdx
@@ -1,4 +1,7 @@
-# Network
+---
+title: "Network"
+navTitle: "Network"
+---
 
 Use network commands to intercept requests, mock responses, inspect traffic, and export HAR files during browser automation.
 

diff --git a/docs/src/app/next/page.mdx → docs/content/docs/next.mdx b/docs/src/app/next/page.mdx → docs/content/docs/next.mdx
@@ -1,4 +1,7 @@
-# Next.js + Vercel
+---
+title: "Next.js + Vercel"
+navTitle: "Next.js + Vercel"
+---
 
 Run agent-browser from a Next.js app on Vercel using Vercel Sandbox. A Linux microVM spins up on demand, runs agent-browser + Chrome, and shuts down. No binary size limits, no Chromium bundling complexity.
 

diff --git a/docs/src/app/plugins/page.mdx → docs/content/docs/plugins.mdx b/docs/src/app/plugins/page.mdx → docs/content/docs/plugins.mdx
@@ -1,4 +1,7 @@
-# Plugins
+---
+title: "Plugins"
+navTitle: "Plugins"
+---
 
 Plugins let agent-browser integrate with external tools without adding those tools to core. A plugin is a local executable that reads one JSON request from stdin and writes one JSON response to stdout.
 

diff --git a/docs/src/app/profiler/page.mdx → docs/content/docs/profiler.mdx b/docs/src/app/profiler/page.mdx → docs/content/docs/profiler.mdx
@@ -1,4 +1,7 @@
-# Profiler
+---
+title: "Profiler"
+navTitle: "Profiler"
+---
 
 Capture Chrome DevTools performance profiles during browser automation. Use profiles to diagnose slow page loads, expensive JavaScript, layout thrashing, and other performance bottlenecks in agentic workflows.
 

diff --git a/docs/src/app/providers/agentcore/page.mdx → docs/content/docs/providers/agentcore.mdx b/docs/src/app/providers/agentcore/page.mdx → docs/content/docs/providers/agentcore.mdx
@@ -1,4 +1,7 @@
-# AgentCore
+---
+title: "AgentCore"
+navTitle: "AgentCore"
+---
 
 [AWS Bedrock AgentCore](https://aws.amazon.com/bedrock/agentcore/) provides cloud browser sessions with SigV4 authentication. Use it when running agent-browser in AWS environments or when you need managed cloud browsers backed by AWS infrastructure.
 

diff --git a/docs/src/app/providers/browser-use/page.mdx → docs/content/docs/providers/browser-use.mdx b/docs/src/app/providers/browser-use/page.mdx → docs/content/docs/providers/browser-use.mdx
@@ -1,4 +1,7 @@
-# Browser Use
+---
+title: "Browser Use"
+navTitle: "Browser Use"
+---
 
 [Browser Use](https://browser-use.com) is an open-source browser automation project for AI agents with [over 100,000 GitHub stars](https://github.com/browser-use/browser-use), plus a managed Cloud browser service. Browser Use Cloud is useful when running agent-browser in environments where a local browser isn't available, such as serverless and CI environments.
 

diff --git a/docs/src/app/providers/browserbase/page.mdx → docs/content/docs/providers/browserbase.mdx b/docs/src/app/providers/browserbase/page.mdx → docs/content/docs/providers/browserbase.mdx
@@ -1,4 +1,7 @@
-# Browserbase
+---
+title: "Browserbase"
+navTitle: "Browserbase"
+---
 
 [Browserbase](https://browserbase.com) provides remote browser infrastructure to make deployment of agentic browsing agents easy. Use it when running agent-browser in environments where a local browser isn't feasible.
 

diff --git a/docs/src/app/providers/browserless/page.mdx → docs/content/docs/providers/browserless.mdx b/docs/src/app/providers/browserless/page.mdx → docs/content/docs/providers/browserless.mdx
@@ -1,4 +1,7 @@
-# Browserless
+---
+title: "Browserless"
+navTitle: "Browserless"
+---
 
 [Browserless](https://browserless.io) provides cloud browser infrastructure with a Sessions API. Use it when running agent-browser in environments where a local browser isn't available.
 

diff --git a/docs/src/app/providers/kernel/page.mdx → docs/content/docs/providers/kernel.mdx b/docs/src/app/providers/kernel/page.mdx → docs/content/docs/providers/kernel.mdx
@@ -1,4 +1,7 @@
-# Kernel
+---
+title: "Kernel"
+navTitle: "Kernel"
+---
 
 [Kernel](https://www.kernel.sh) provides cloud browser infrastructure for AI agents with features like stealth mode and persistent profiles.
 

diff --git a/docs/content/docs/providers/meta.json b/docs/content/docs/providers/meta.json
@@ -0,0 +1,11 @@
+{
+  "title": "Providers",
+  "pages": [
+    "agentcore",
+    "browser-use",
+    "browserbase",
+    "browserless",
+    "kernel",
+    "remote-agent-browser"
+  ]
+}
diff --git a/...p/providers/remote-agent-browser/page.mdx → ...t/docs/providers/remote-agent-browser.mdx b/...p/providers/remote-agent-browser/page.mdx → ...t/docs/providers/remote-agent-browser.mdx
@@ -1,4 +1,7 @@
-# Remote Agent Browser
+---
+title: "Remote Agent Browser"
+navTitle: "Remote Agent Browser"
+---
 
 [Remote Agent Browser](https://github.com/vercel-labs/remote-agent-browser) runs agent-browser inside an isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). Use it when a TypeScript application needs to provision a browser on demand without managing a local Chrome process.
 

diff --git a/docs/src/app/proxy/page.mdx → docs/content/docs/proxy.mdx b/docs/src/app/proxy/page.mdx → docs/content/docs/proxy.mdx
@@ -1,4 +1,7 @@
-# Proxy
+---
+title: "Proxy"
+navTitle: "Proxy"
+---
 
 Use proxies for corporate networks, geo-testing, scraping infrastructure, and traffic routing through a controlled egress point.
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,6 +15,7 @@ @@
     # next.js
     /.next/
+    /.source/
     /out/
     # production
@@ Expand Down @@