Docs v2: rewritten documentation (do not merge until cutover)

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

README.md

@@ -1,24 +1,41 @@
-# Driver Docs
+# Driver docs
 
-Documentation for Driver's managed browser API.
+Documentation for [docs.driver.dev](https://docs.driver.dev), written from scratch on 2026-09-17. Mintlify project:
+`docs.json` is the navigation and theme, `docs/**` the guides, `api-reference/` the generated reference.
 
-## Structure
+## Principles
 
-- `docs/index.mdx` — API overview and core session flow
-- `docs/introduction/` — introductory getting-started pages
-- `docs/fundamentals/` — browser session lifecycle, usage, viewer, and management
-- `docs/features/` — profiles, geolocation, node targeting, proxies, and window size
-- `docs/integrations/` — Playwright, Puppeteer, Browser-Use, Crawl4AI, and Stagehand
-- `docs.json` — Mintlify navigation and site configuration
-- `api-reference/openapi.json` — Mintlify OpenAPI reference generated from the live Driver API spec with docs-specific simplifications
+- **The live API document is the ground truth.** `api-reference/openapi.json` is produced by `npm run sync` from
+  `https://api.driver.dev/doc` (what Scalar renders at `/scalar`). Guides describe options that exist there; nothing
+  else. When the API changes, run the sync and fix the guides that mention the changed field.
+- **Written for engineers and agents alike.** Short pages, one job each, a table of options with defaults, one
+  example per language, and a "For agents" page plus `llms.txt` (generated by Mintlify) that state the rules outright.
+- **Patchright is the recommended client.** Every framework page says why, and the stock Playwright and Puppeteer
+  pages carry the warning.
+- **Best practices stay.** `docs/start/best-practices.mdx` carries the CDP-hygiene guidance forward.
 
-The API Reference tab is generated from `api-reference/openapi.json`. The local OpenAPI file is based on `https://api.driver.dev/doc` with docs-specific corrections.
+## Deprecated surface
 
-## Preview Locally
+The teracrawl scrape/search endpoints and the `consumer_distributed` browser type are deprecated and deliberately
+absent: `scripts/sync-openapi.mjs` drops them from the generated reference, and no guide mentions them.
+
+## Working on it
 
 ```bash
-npm i -g mint
-mint dev
+npm install          # Mintlify CLI
+npm run sync         # refresh api-reference/openapi.json from the live API
+npm run dev          # http://localhost:3000
+npm run check        # broken links (reports every link as broken on Windows; a CLI path bug, not the docs)
+npm run countries    # regenerate docs/options/countries.mdx from scripts/data/ (the gateway's locale catalog)
 ```
 
-Open `http://localhost:3000`.
+Old URLs redirect to their new homes (see `redirects` in `docs.json`), so links from the dashboard and the landing
+page keep working.
+
+## Battle-tested
+
+On 2026-09-19 five fresh agents (Node, Python, REST-only, framework migration, coding-agent handoff) integrated Driver
+from this folder alone and reported every gap; the fixes are in the git history of that day. Re-run the exercise after
+big changes: the reports live in the dashboard repo's docs/STATUS-LOG.md entry for that date. `scripts/sync-openapi.mjs`
+also corrects four things the generator gets wrong (duration bound, negative balances, PATCH 400, branding); keep
+those corrections when the source changes.