docs: content drift between README and docs site — proposed phased fix #774
Description
While exploring the docs, I noticed a few things that seem worth fixing.
1. Factual error in ios/page.mdx
The "Differences from desktop" table lists Chromium/Firefox/WebKit as the desktop browser. The codebase only has launchers for Chrome and Lightpanda (both via CDP — cdp/chrome.rs, cdp/lightpanda.rs). Firefox and WebKit have no launcher and are not supported. The cell should read Chrome, Lightpanda.
2. Provider docs are incomplete and in the wrong place
cdp-mode/page.mdx has a "Cloud providers" section, but it only shows an API key export and one command per provider. The README has significantly more: env var tables, provider-specific options, behavioral notes.
The placement is also a mismatch. CDP Mode is about connecting to an already-running browser. Providers provision a managed browser on demand — the CDP connection is an internal detail the user never touches. These are different user journeys.
One more thing: the README documents incorrect defaults for Kernel vs. the source code (providers.rs):
| Variable | README | Code |
|---|---|---|
KERNEL_HEADLESS |
false |
true |
KERNEL_STEALTH |
true |
false |
3. A few features have no dedicated docs coverage
--headed and --allow-file-access each appear as a one-line table row in cdp-mode's options table. Both have fuller explanations in the README that aren't reflected anywhere in the docs site.
4. MDX metadata renders as JS on GitHub
Most page.mdx files open with:
import { pageMetadata } from "@/lib/page-metadata"
export const metadata = pageMetadata("slug")GitHub renders this as plain text. installation/page.mdx already uses YAML frontmatter — that pattern avoids the problem entirely.