Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: general update of docs and organization for the site

Luigi Agostib5ccaaa92649
diff --git a/docs/architecture/chrome-lifecycle-and-orchestration.md b/docs/architecture/chrome-lifecycle-and-orchestration.md
deleted file mode 100644
index bc84985d..00000000
--- a/docs/architecture/chrome-lifecycle-and-orchestration.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Orchestration
-
-Pinchtab is a Go-based server and bridge system for Chrome. It doesn't just "run" a browser; it manages a fleet of isolated instances, hardened against detection and optimized for automation.
-
-## 1. Allocator Strategy
-
-The foundation of every managed Chrome instance is the chromedp allocator. Pinchtab primarily uses local launch:
-
-- **Managed Launch:** the server spawns a dedicated `pinchtab bridge` child process, which uses `NewExecAllocator` to launch Chrome with a dedicated profile and port.
-- **Attach:** separately, the server can register an externally managed Chrome instance through the attach API when attach policy allows it.
-
-## 2. Hardening & Launch Flags
-
-When launching locally, Pinchtab applies a comprehensive set of command-line flags to strip away automation markers and optimize the environment:
-
-- **Anti-Detection:** Flags like `--exclude-switches=enable-automation` and `--disable-infobars` are used to hide the standard "automated software" banner.
-- **Isolation:** Each instance is assigned its own `UserDataDir` (Profile), ensuring that cookies, local storage, and sessions are completely isolated between different "agents" or profiles.
-- **Stability:** Background throttling and renderer backgrounding are disabled to prevent Chrome from "sleeping" during long-running automation tasks.
-
-## 3. Instance Orchestration
-
-The orchestrator handles the lifecycle of multiple independent Chrome processes:
-
-- **Process Isolation:** Each instance runs as a separate OS process with its own PID.
-- **Health Monitoring:** After launching a process, the Orchestrator polls the instance's `/health` endpoint until it is ready to accept commands.
-- **Port Management:** It ensures each instance is assigned a unique port and verifies availability before launching.
-
-## 4. Pre-Flight Stealth Injection
-
-The most critical part of the "wrap" happens before any website is even loaded. Pinchtab performs a Pre-Flight Injection:
-
-- **`AddScriptToEvaluateOnNewDocument`:** The `stealth.js` script is registered to execute *before* any other script on a page. This masks `navigator.webdriver` and spoofs hardware identifiers (CPU cores, memory) before a website can fingerprint the browser.
-- **Environment Spoofing:** Timezone overrides and locale settings are applied immediately after startup to ensure the browser's "identity" is consistent.
-
-## 5. Resilience & Self-Healing
-
-Pinchtab includes logic to handle common browser startup failures:
-
-- **Lock File Cleanup:** If Chrome previously crashed, it might leave `SingletonLock` or `SingletonSocket` files that prevent it from restarting. Pinchtab automatically detects an "unclean exit" and deletes these locks.
-- **Retry Logic:** If Chrome fails to start within the `chromeStartTimeout` (15s), Pinchtab will clear the session data and attempt one retry to ensure service availability.
-
-## 6. Tab Management
-
-Once the browser is running, the `TabManager` (`tab_manager.go`) tracks all open targets (tabs). It provides:
-
-- **Context Lifecycle:** Manages the creation and cancellation of Go `context.Context` objects for each tab.
-- **Setup Hooks:** Automatically reapplies stealth and optimization scripts to every new tab opened by the user or by automation scripts.
-- **Tab Limits:** Enforces the configured max-tab policy to prevent runaway agents from consuming all memory.
-- **Stale Tab Cleanup:** Periodically removes tabs that no longer exist in Chrome.
diff --git a/docs/architecture/cli-design.md b/docs/architecture/cli-design.md
deleted file mode 100644
index 10002188..00000000
--- a/docs/architecture/cli-design.md
+++ /dev/null
@@ -1,263 +0,0 @@
-# CLI Design Guide
-
-This page describes the CLI that exists today in `cmd/pinchtab/cmd_cli.go` and `cmd/pinchtab/main.go`.
-
-## Process Modes
-
-Pinchtab has three startup modes:
-
-```bash
-pinchtab # Start full server (default)
-pinchtab server # Start full server explicitly
-pinchtab bridge # Start bridge-only runtime
-```
-
-The CLI commands below are client commands. They expect a running full server unless noted otherwise.
-
-## Core Rule
-
-The current CLI is split into three layers:
-
-1. startup and utility commands
-2. top-level browser control commands
-3. explicit instance and tab management commands
-
-The important constraint is that the CLI does **not** support a global `--instance` flag today.
-
-If you need to target a specific instance:
-- create or inspect it with `pinchtab instance ...`
-- open a tab inside it with `pinchtab instance navigate <instance-id> <url>` or the HTTP API
-- then operate on the returned tab ID with `pinchtab tab ...`
-
-## Startup And Utility Commands
-
-These commands are handled outside the main HTTP CLI dispatcher:
-
-```bash
-pinchtab --version
-pinchtab help
-
-pinchtab config init
-pinchtab config show
-pinchtab config path
-pinchtab config validate
-
-pinchtab connect <profile>
-pinchtab connect <profile> --json
-pinchtab connect <profile> --dashboard http://localhost:9867
-```
-
-Notes:
-- `connect` resolves a running profile to its bridge URL via `/profiles/{id}/instance`
-- there is no CLI command for `attach` yet; attach is API-only for now
-
-## Top-Level Browser Control
-
-These commands talk to the server shorthand endpoints:
-
-```bash
-pinchtab nav <url>
-pinchtab snap
-pinchtab click <ref>
-pinchtab type <ref> <text>
-pinchtab fill <ref|selector> <text>
-pinchtab press <key>
-pinchtab hover <ref>
-pinchtab scroll <ref|pixels>
-pinchtab select <ref> <value>
-pinchtab focus <ref>
-pinchtab text
-pinchtab ss
-pinchtab eval <expression>
-pinchtab pdf --tab <tabId>
-pinchtab health
-pinchtab quick <url>
-```
-
-These commands operate against the default routed tab context on the server.
-
-Supported flags:
-
-```bash
-pinchtab nav <url> [--new-tab] [--block-images] [--block-ads]
-
-pinchtab snap [-i|--interactive] [-c|--compact] [-d|--diff]
- [-s|--selector <css>] [--max-tokens N] [--depth N] [--tab <tabId>]
-
-pinchtab text [--raw] [--tab <tabId>]
-
-pinchtab ss [-o|--output <file>] [-q|--quality N] [--tab <tabId>]
-
-pinchtab pdf --tab <tabId> [-o|--output <file>] [--landscape] [--scale N]
- [--paper-width N] [--paper-height N]
- [--margin-top N] [--margin-bottom N]
- [--margin-left N] [--margin-right N]
- [--page-ranges RANGE]
- [--prefer-css-page-size]
- [--display-header-footer]
- [--header-template HTML]
- [--footer-template HTML]
- [--generate-tagged-pdf]
- [--generate-document-outline]
- [--file-output]
- [--path PATH]
-```
-
-## Instance Commands
-
-The current instance CLI shape is:
-
-```bash
-pinchtab instances
-
-pinchtab instance start [--profileId <id>] [--mode headed|headless] [--port <port>]
-pinchtab instance launch [--profileId <id>] [--mode headed|headless] [--port <port>]
-
-pinchtab instance navigate <instance-id> <url>
-
-pinchtab instance logs <instance-id>
-pinchtab instance logs --id <instance-id>
-
-pinchtab instance stop <instance-id>
-pinchtab instance stop --id <instance-id>
-```
-
-Important details:
-- `launch` is a CLI alias for `start`
-- both `start` and `launch` call `POST /instances/start` today
-- there is no `pinchtab instance <id> logs` grammar
-- there is no CLI subcommand for `attach`
-
-HTTP mapping:
-
-| CLI | HTTP |
-|---|---|
-| `pinchtab instances` | `GET /instances` |
-| `pinchtab instance start ...` | `POST /instances/start` |
-| `pinchtab instance launch ...` | `POST /instances/start` |
-| `pinchtab instance navigate <id> <url>` | `POST /instances/{id}/tabs/open` then `POST /tabs/{tabId}/navigate` |
-| `pinchtab instance logs <id>` | `GET /instances/{id}/logs` |
-| `pinchtab instance stop <id>` | `POST /instances/{id}/stop` |
-
-## Tab Commands
-
-The current tab CLI has two shapes:
-
-1. list or legacy lifecycle shortcuts
-2. explicit tab operations
-
-### List And Legacy Shortcuts
-
-```bash
-pinchtab tabs
-pinchtab tab
-
-pinchtab tabs new [url]
-pinchtab tab new [url]
-
-pinchtab tabs close <tabId>
-pinchtab tab close <tabId>
-```
-
-Notes:
-- `tabs` and `tab` are both accepted
-- `new` and `close` use the legacy `/tab` endpoint
-- `tab new` will auto-launch a default instance if none is running
-
-### Explicit Tab Operations
-
-The implemented grammar is:
-
-```bash
-pinchtab tab navigate <tabId> <url>
-pinchtab tab snapshot <tabId> [-i] [-c] [-d]
-pinchtab tab screenshot <tabId> [-o file] [-q N]
-pinchtab tab click <tabId> <ref>
-pinchtab tab type <tabId> <ref> <text>
-pinchtab tab fill <tabId> <ref> <text>
-pinchtab tab press <tabId> <key>
-pinchtab tab hover <tabId> <ref>
-pinchtab tab scroll <tabId> <direction|pixels>
-pinchtab tab select <tabId> <ref> <value>
-pinchtab tab focus <tabId> <ref>
-pinchtab tab text <tabId> [--raw]
-pinchtab tab eval <tabId> <expression>
-pinchtab tab pdf <tabId> [-o file] [--landscape] [--scale N]
-pinchtab tab cookies <tabId>
-pinchtab tab lock <tabId> [--owner name] [--ttl seconds]
-pinchtab tab unlock <tabId> [--owner name]
-pinchtab tab locks <tabId>
-pinchtab tab info <tabId>
-```
-
-Important detail:
-- the operation comes before the tab ID
-- the implemented syntax is `pinchtab tab screenshot <tabId>`
-- it is **not** `pinchtab tab <tabId> screenshot`
-
-## Profiles Command
-
-The implemented profile command is:
-
-```bash
-pinchtab profiles
-```
-
-Current behavior:
-- calls `GET /profiles`
-- prints a simple human-friendly list of names
-- does not currently expose create/update/delete operations through the CLI
-
-## Environment
-
-The CLI uses these environment variables:
-
-```bash
-PINCHTAB_URL # server base URL, default http://127.0.0.1:9867
-PINCHTAB_TOKEN # bearer token for API requests
-PINCHTAB_PORT # startup/server port
-CHROME_BIN # startup Chrome binary path
-```
-
-Use `PINCHTAB_TOKEN`, not `BRIDGE_TOKEN`.
-
-## Recommended Workflows
-
-### Basic Top-Level Flow
-
-```bash
-pinchtab
-
-pinchtab nav https://pinchtab.com
-pinchtab snap -i -c
-pinchtab click e5
-pinchtab text
-```
-
-### Explicit Instance Flow
-
-```bash
-INST=$(pinchtab instance start --mode headed | jq -r '.id')
-
-pinchtab instance navigate "$INST" https://pinchtab.com
-pinchtab tabs
-```
-
-### Tab-Targeted Flow
-
-```bash
-TAB=$(pinchtab tabs | jq -r '.[0].id')
-
-pinchtab tab snapshot "$TAB" -i -c
-pinchtab tab click "$TAB" e5
-pinchtab tab text "$TAB" --raw
-pinchtab tab pdf "$TAB" -o page.pdf
-```
-
-## Non-Goals For This Doc
-
-This page intentionally does not document commands that are not implemented yet, including:
-- a global `--instance` flag
-- `pinchtab instance attach`
-- full profile CRUD through the CLI
-- `pinchtab tab <tabId> <action>` grammar
diff --git a/docs/architecture/cli-quick-reference.md b/docs/architecture/cli-quick-reference.md
deleted file mode 100644
index 7474454e..00000000
--- a/docs/architecture/cli-quick-reference.md
+++ /dev/null
@@ -1,198 +0,0 @@
-# CLI Quick Reference
-
-This quick reference matches the current CLI implementation on this branch.
-
-## Startup
-
-```bash
-pinchtab
-pinchtab server
-pinchtab bridge
-```
-
-## Utility Commands
-
-```bash
-pinchtab --version
-pinchtab help
-
-pinchtab config init
-pinchtab config show
-pinchtab config path
-pinchtab config validate
-
-pinchtab connect <profile>
-pinchtab connect <profile> --json
-pinchtab connect <profile> --dashboard http://localhost:9867
-```
-
-## Environment
-
-```bash
-export PINCHTAB_URL=http://127.0.0.1:9867
-export PINCHTAB_TOKEN=secret_token
-```
-
-Startup-related envs:
-
-```bash
-PINCHTAB_PORT=9868 pinchtab
-PINCHTAB_BIND=0.0.0.0 pinchtab
-CHROME_BIN=/usr/bin/google-chrome pinchtab
-```
-
-## Top-Level Browser Control
-
-```bash
-pinchtab nav https://pinchtab.com
-pinchtab nav https://pinchtab.com --new-tab
-pinchtab nav https://pinchtab.com --block-images --block-ads
-
-pinchtab snap
-pinchtab snap -i
-pinchtab snap -i -c
-pinchtab snap -d
-pinchtab snap --selector 'main'
-pinchtab snap --tab <tabId>
-
-pinchtab click e5
-pinchtab type e12 "hello world"
-pinchtab fill e12 "value"
-pinchtab fill 'input[name=email]' "[email protected]"
-pinchtab press Enter
-pinchtab hover e5
-pinchtab scroll e5
-pinchtab scroll 500
-pinchtab select e7 option2
-pinchtab focus e7
-
-pinchtab text
-pinchtab text --raw
-pinchtab text --tab <tabId>
-
-pinchtab ss -o out.jpg
-pinchtab ss -q 85 -o out.jpg
-pinchtab ss --tab <tabId> -o out.jpg
-
-pinchtab eval "document.title"
-
-pinchtab pdf --tab <tabId> -o page.pdf
-pinchtab pdf --tab <tabId> -o page.pdf --landscape
-pinchtab pdf --tab <tabId> --scale 0.9 -o page.pdf
-
-pinchtab health
-pinchtab quick https://pinchtab.com
-```
-
-## Instance Commands
-
-```bash
-pinchtab instances
-
-pinchtab instance start
-pinchtab instance start --mode headed
-pinchtab instance start --profileId prof_123
-pinchtab instance start --port 9999
-
-pinchtab instance launch
-pinchtab instance launch --mode headed
-
-pinchtab instance navigate inst_abc123 https://pinchtab.com
-
-pinchtab instance logs inst_abc123
-pinchtab instance logs --id inst_abc123
-
-pinchtab instance stop inst_abc123
-pinchtab instance stop --id inst_abc123
-```
-
-Notes:
-- `launch` is a CLI alias for `start`
-- there is no CLI `attach` command yet
-- there is no `pinchtab instance <id> logs` grammar
-
-## Tabs
-
-### List And Legacy Lifecycle
-
-```bash
-pinchtab tabs
-pinchtab tab
-
-pinchtab tabs new https://pinchtab.com
-pinchtab tab new https://pinchtab.com
-
-pinchtab tabs close tab_xyz789
-pinchtab tab close tab_xyz789
-```
-
-### Explicit Tab Operations
-
-```bash
-pinchtab tab navigate tab_xyz789 https://google.com
-pinchtab tab snapshot tab_xyz789 -i -c
-pinchtab tab screenshot tab_xyz789 -o out.png
-pinchtab tab click tab_xyz789 e5
-pinchtab tab type tab_xyz789 e12 "hello world"
-pinchtab tab fill tab_xyz789 e12 "value"
-pinchtab tab press tab_xyz789 Enter
-pinchtab tab hover tab_xyz789 e5
-pinchtab tab scroll tab_xyz789 down
-pinchtab tab scroll tab_xyz789 500
-pinchtab tab select tab_xyz789 e7 option2
-pinchtab tab focus tab_xyz789 e7
-pinchtab tab text tab_xyz789 --raw
-pinchtab tab eval tab_xyz789 "document.title"
-pinchtab tab pdf tab_xyz789 -o page.pdf
-pinchtab tab cookies tab_xyz789
-pinchtab tab lock tab_xyz789 --owner my-agent --ttl 60
-pinchtab tab unlock tab_xyz789 --owner my-agent
-pinchtab tab locks tab_xyz789
-pinchtab tab info tab_xyz789
-```
-
-Important:
-- the implemented order is `pinchtab tab <operation> <tabId> ...`
-- not `pinchtab tab <tabId> <operation>`
-
-## Profiles
-
-```bash
-pinchtab profiles
-```
-
-Current behavior:
-- lists profile names from the server
-- prints human-friendly output, not a structured JSON array
-
-## Common Flows
-
-### Start And Drive A Page
-
-```bash
-pinchtab
-
-pinchtab nav https://github.com/pinchtab/pinchtab
-pinchtab snap -i -c
-pinchtab click e5
-pinchtab text --raw
-```
-
-### Launch An Instance Then Navigate It
-
-```bash
-INST=$(pinchtab instance start --mode headed | jq -r '.id')
-pinchtab instance navigate "$INST" https://pinchtab.com
-pinchtab tabs
-```
-
-### Work Directly With A Known Tab
-
-```bash
-TAB=tab_xyz789
-
-pinchtab tab snapshot "$TAB" -i -c
-pinchtab tab click "$TAB" e5
-pinchtab tab text "$TAB" --raw
-pinchtab tab pdf "$TAB" -o page.pdf
-```
diff --git a/docs/architecture/endpoints.md b/docs/architecture/endpoints.md
deleted file mode 100644
index 1e564f25..00000000
--- a/docs/architecture/endpoints.md
+++ /dev/null
@@ -1,827 +0,0 @@
-# API Reference
-
-Complete HTTP API reference for instances, tabs, and browser operations.
-
-## Overview
-
-Pinchtab uses a **server-first** API model:
-- the **Pinchtab server** listens on port `9867` and manages profiles and instances
-- each managed **instance** is backed by a single `pinchtab bridge` runtime
-- tab operations are tab-first under `/tabs/{id}/...`
-- instance lifecycle operations live under `/instances/...`
-- attach is the advanced path for registering externally managed Chrome
-
-```text
-HTTP Client
- │
- │ All requests: http://localhost:9867
- │
- ↓
-┌──────────────────────────────────────────┐
-│ PinchTab Server (HTTP, port 9867) │
-│ ┌────────────────────────────────────┐ │
-│ │ - Dashboard │ │
-│ │ - Instance management │ │
-│ │ - Profile management │ │
-│ │ - Routing to bridge runtimes │ │
-│ └────────────────────────────────────┘ │
-└─────┬──────────────────────────────────────┘
- │
- │ HTTP proxying to managed instances
- │
- ├─────────────────────────────────────┐
- │ │
- ↓ ↓
-┌──────────────────┐ ┌──────────────────┐
-│ Bridge Runtime 1 │ │ Bridge Runtime 2 │
-│ + Chrome │ │ + Chrome │
-│ profile: work │ │ profile: scraping│
-├──────────────────┤ ├──────────────────┤
-│ Tab 1: LinkedIn │ │ Tab 1: API │
-│ Tab 2: GitHub │ │ Tab 2: Data │
-│ Tab 3: Email │ └──────────────────┘
-└──────────────────┘
-```
-
-## API Summary
-
-| Category | Operations | Purpose |
-|---|---|---|
-| **Instance Management** | `POST /instances/start` `POST /instances/launch` `POST /instances/attach` `GET /instances` `GET /instances/{id}` `POST /instances/{id}/stop` | Create, attach, list, inspect, and stop instances |
-| **Navigation** | `POST /tabs/{id}/navigate` | Navigate an existing tab by tab ID |
-| **Tab Operations** | `POST /instances/{id}/tabs/open` `GET /instances/{id}/tabs` `POST /tabs/{tabId}/navigate` | Open/list tabs and navigate existing tab |
-| **Page Inspection** | `GET /tabs/{id}/snapshot` `GET /tabs/{id}/text` | Get accessibility tree, extract text |
-| **User Actions** | `POST /tabs/{id}/action` `POST /tabs/{id}/actions` | Click, type, fill, press, hover, focus, scroll, select |
-| **JavaScript** | `POST /tabs/{id}/evaluate` | Execute JavaScript in the page |
-| **Visual** | `GET /tabs/{id}/screenshot` `GET /tabs/{id}/pdf` | Take screenshot, export PDF |
-| **Profiles** | `GET /profiles` `POST /profiles` | List and create browser profiles |
-| **Aggregate** | `GET /tabs` | Get all tabs across all instances |
-
----
-
-## Base URL
-
-```
-http://127.0.0.1:9867 # PinchTab Server (all endpoints)
-```
-
-All requests go to port 9867. Instance-scoped proxy operations use `/instances/{id}/...`, while tab-first operations use `/tabs/{tabId}/...` (for example `POST /tabs/{tabId}/navigate` and `GET /tabs/{tabId}/screenshot`).
-
----
-
-## Instance Management API
-
-### Launch or Start Instance
-
-**Endpoint:**
-```
-POST /instances/start
-POST /instances/launch
-```
-
-**Request Body:**
-```json
-{
- "profileId": "work",
- "mode": "headed"
-}
-```
-
-**Parameters:**
-- `profileId` (string, optional) - profile ID or name
-- `name` (string, optional on `/instances/launch`) - instance/profile name when launching by name
-- `mode` (string, optional) - `headless` or `headed`
-- `port` (string, optional) - explicit port if you do not want auto-allocation
-
-**Behavior:**
-- Creates a managed instance record on the server
-- Spawns a `pinchtab bridge` child process for managed instances
-- Chrome may initialize lazily on the first browser request
-- Returns instance metadata used for later tab operations
-
-**Response (201 Created):**
-```json
-{
- "id": "inst_0a89a5bb",
- "profileId": "prof_278be873",
- "profileName": "work",
- "headless": false,
- "status": "starting",
- "port": "9868",
- "startTime": "2026-02-28T18:35:18Z"
-}
-```
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/instances/launch \
- -H "Content-Type: application/json" \
- -d '{"name":"work","mode":"headed"}'
-```
-
-### Attach Instance
-
-**Endpoint:**
-```
-POST /instances/attach
-```
-
-**Request Body:**
-```json
-{
- "name": "shared-chrome",
- "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/..."
-}
-```
-
-Attach is only available when enabled in config under `attach.enabled`, and the target must pass `allowHosts` and `allowSchemes` policy checks.
-
----
-
-### List All Instances
-
-**Endpoint:**
-```
-GET /instances
-```
-
-**Response:**
-```json
-[
- {
- "id": "work-9868",
- "profile": "work",
- "headless": false,
- "status": "running",
- "port": "9868",
- "startTime": "2026-02-28T18:35:18Z",
- "tabs": [
- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},
- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}
- ]
- },
- {
- "id": "scraping-9869",
- "profile": "scraping",
- "headless": true,
- "status": "running",
- "port": "9869",
- "startTime": "2026-02-28T18:35:20Z",
- "tabs": [
- {"id": "tab-3", "url": "https://api.pinchtab.com", "title": "API"}
- ]
- }
-]
-```
-
-**Example (curl):**
-```bash
-curl http://localhost:9867/instances
-```
-
----
-
-### Get Instance Details
-
-**Endpoint:**
-```
-GET /instances/{id}
-```
-
-**Response:**
-```json
-{
- "id": "work-9868",
- "profile": "work",
- "headless": false,
- "status": "running",
- "port": "9868",
- "startTime": "2026-02-28T18:35:18Z",
- "tabs": [
- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},
- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}
- ]
-}
-```
-
-**Example (curl):**
-```bash
-curl http://localhost:9867/instances/work-9868
-```
-
----
-
-### Stop Instance
-
-**Endpoint:**
-```
-POST /instances/{id}/stop
-```
-
-**Response:**
-```json
-{
- "id": "inst_0a89a5bb",
- "status": "stopped"
-}
-```
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/instances/inst_0a89a5bb/stop
-```
-
----
-
-## Instance Operations
-
-All operations target a specific instance via its ID or port.
-
-### Open Tab (Create Tab)
-
-**Endpoint:**
-```
-POST /instances/{id}/tabs/open
-```
-
-**Request Body:**
-- `url` (optional) — URL to open immediately in the new tab
-
-**Response:**
-```json
-{
- "tabId": "tab-1",
- "url": "https://pinchtab.com",
- "title": "Example Domain"
-}
-```
-
-**Notes:**
-- **Creates a NEW tab** every time
-- If `url` is provided, the new tab opens that URL
-- Use `POST /tabs/{tabId}/navigate` to navigate an existing tab later
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/instances/work-9868/tabs/open \
- -H "Content-Type: application/json" \
- -d '{"url":"https://linkedin.com"}'
-```
-
-**Example (bash):**
-```bash
-TAB_JSON=$(curl -s -X POST http://localhost:9867/instances/work-9868/tabs/open \
- -H "Content-Type: application/json" \
- -d '{"url":"https://pinchtab.com"}')
-TAB_ID=$(echo $TAB_JSON | jq -r '.tabId')
-echo "Opened tab: $TAB_ID"
-```
-
----
-
-### Get Instance Tabs
-
-**Endpoint:**
-```
-GET /instances/{id}/tabs
-```
-
-**Response:**
-```json
-[
- {"id": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},
- {"id": "tab-2", "url": "https://github.com", "title": "GitHub"}
-]
-```
-
-**Example (curl):**
-```bash
-curl http://localhost:9867/instances/work-9868/tabs
-```
-
----
-
-### Navigate Existing Tab
-
-**Endpoint:**
-```
-POST /tabs/{tabId}/navigate?url=<url>
-```
-
-**Query Parameters:**
-- `url` (required) — URL to navigate to
-
-**Response:**
-```json
-{
- "tabId": "tab-1",
- "url": "https://linkedin.com/login",
- "title": "LinkedIn Sign In"
-}
-```
-
-**Notes:**
-- Navigates the **existing tab** (reuses cookies, history, etc.)
-- Better for workflows that need session continuity
-
-**Example (curl):**
-```bash
-curl -X POST "http://localhost:9867/tabs/tab-1/navigate?url=https://linkedin.com/login"
-```
-
----
-
-### Get Snapshot
-
-**Endpoint:**
-```
-GET /tabs/{tabId}/snapshot
-```
-
-**Query Parameters:**
-- `filter` (optional) — `interactive` for buttons/links/inputs only
-- `format` (optional) — `compact` or `text`
-- `maxTokens` (optional) — Truncate to ~N tokens
-- `depth` (optional) — Max tree depth
-
-**Response:**
-```json
-{
- "elements": [
- {"ref": "e0", "role": "heading", "name": "LinkedIn Sign In"},
- {"ref": "e1", "role": "textbox", "name": "Email or phone"},
- {"ref": "e2", "role": "textbox", "name": "Password"},
- {"ref": "e3", "role": "button", "name": "Sign in"}
- ]
-}
-```
-
-**Example (curl):**
-```bash
-curl "http://localhost:9867/tabs/tab-1/snapshot?filter=interactive&format=compact"
-```
-
----
-
-### Click Element
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "click",
- "ref": "e3"
-}
-```
-
-**Response:**
-```json
-{"success": true}
-```
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/tabs/tab-1/action \
- -H "Content-Type: application/json" \
- -d '{"kind":"click","ref":"e3"}'
-```
-
----
-
-### Type Text
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "type",
- "ref": "e1",
- "text": "[email protected]"
-}
-```
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/tabs/tab-1/action \
- -H "Content-Type: application/json" \
- -d '{"kind":"type","ref":"e1","text":"[email protected]"}'
-```
-
----
-
-### Fill Input (Direct)
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "fill",
- "ref": "e1",
- "text": "value"
-}
-```
-
-Sets input value directly without triggering key events.
-
----
-
-### Press Key
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "press",
- "key": "Enter"
-}
-```
-
-**Keys:** `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, etc.
-
----
-
-### Hover Element
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "hover",
- "ref": "e5"
-}
-```
-
----
-
-### Focus Element
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "focus",
- "ref": "e5"
-}
-```
-
----
-
-### Scroll
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body (scroll to element):**
-```json
-{
- "kind": "scroll",
- "ref": "e5"
-}
-```
-
-**Request Body (scroll by pixels):**
-```json
-{
- "kind": "scroll",
- "pixels": 500
-}
-```
-
----
-
-### Select Dropdown
-
-**Endpoint:**
-```
-POST /tabs/{id}/action
-```
-
-**Request Body:**
-```json
-{
- "kind": "select",
- "ref": "e7",
- "value": "Option 2"
-}
-```
-
----
-
-### Extract Text
-
-**Endpoint:**
-```
-GET /tabs/{id}/text
-```
-
-**Query Parameters:**
-- `mode` (optional) — `raw` for raw innerText, default for readability extraction
-
-**Response:**
-```json
-{
- "text": "Example Domain\nThis domain is for use in examples...",
- "length": 234
-}
-```
-
-**Example (curl):**
-```bash
-curl "http://localhost:9867/tabs/tab-1/text?mode=raw"
-```
-
----
-
-### Execute JavaScript
-
-**Endpoint:**
-```
-POST /tabs/{id}/evaluate
-```
-
-**Request Body:**
-```json
-{
- "expression": "document.title"
-}
-```
-
-**Response:**
-```json
-{
- "result": "Example Domain"
-}
-```
-
-**Example (curl):**
-```bash
-curl -X POST http://localhost:9867/tabs/tab-1/evaluate \
- -H "Content-Type: application/json" \
- -d '{"expression":"document.title"}'
-```
-
----
-
-### Take Screenshot
-
-**Endpoint:**
-```
-GET /tabs/{id}/screenshot
-```
-
-**Query Parameters:**
-- `quality` (optional) — JPEG quality 0-100 (default: 90)
-
-**Response (image/jpeg):**
-```
-[Binary JPEG data]
-```
-
-**Example (curl):**
-```bash
-curl "http://localhost:9867/tabs/tab-1/screenshot?quality=85" \
- -o screenshot.jpg
-```
-
----
-
-### Export PDF
-
-**Endpoint:**
-```
-GET /tabs/{id}/pdf
-```
-
-**Query Parameters:**
-- `landscape` (optional) — `true` for landscape
-- `paperWidth`, `paperHeight` (optional) — Paper dimensions in inches
-- `marginTop`, `marginBottom`, `marginLeft`, `marginRight` (optional) — Margins in inches
-- `scale` (optional) — Print scale 0.1-2.0
-- `pageRanges` (optional) — Pages (e.g., "1-3,5")
-- `displayHeaderFooter` (optional) — `true` to show header/footer
-- `headerTemplate`, `footerTemplate` (optional) — HTML templates
-- `generateTaggedPDF` (optional) — `true` for accessible PDF
-- `generateDocumentOutline` (optional) — `true` for document outline
-- `output` (optional) — `json` (base64) or `file` (save to disk)
-
-**Response (application/pdf):**
-```
-[Binary PDF data]
-```
-
-**Example (curl):**
-```bash
-curl "http://localhost:9867/tabs/tab-1/pdf?landscape=true" \
- -o output.pdf
-```
-
----
-
-## Aggregate Endpoints
-
-### Get All Tabs (Across All Instances)
-
-**Endpoint:**
-```
-GET /tabs
-```
-
-**Response:**
-```json
-[
- {"instanceId": "work-9868", "tabId": "tab-1", "url": "https://linkedin.com", "title": "LinkedIn"},
- {"instanceId": "work-9868", "tabId": "tab-2", "url": "https://github.com", "title": "GitHub"},
- {"instanceId": "scraping-9869", "tabId": "tab-3", "url": "https://api.pinchtab.com", "title": "API"}
-]
-```
-
-**Example (curl):**
-```bash
-curl http://localhost:9867/tabs
-```
-
----
-
-## Complete Agent Workflow Example
-
-### Scenario: Login to LinkedIn, visit profile, take screenshot
-
-```bash
-#!/bin/bash
-
-BASE="http://localhost:9867"
-
-# 1. Create instance (headed mode to see what's happening)
-# This STARTS Chrome immediately with visible window
-echo "Creating instance..."
-INST=$(curl -s -X POST $BASE/instances \
- -H "Content-Type: application/json" \
- -d '{"profile":"linkedin","headless":false}')
-INST_ID=$(echo $INST | jq -r '.id')
-echo "Instance: $INST_ID (Chrome now running and visible)"
-
-# 2. Navigate to LinkedIn login (creates first tab)
-# Chrome is already running, navigation is fast
-echo "Navigating to LinkedIn..."
-NAV=$(curl -s -X POST "$BASE/instances/$INST_ID/tabs/open" \
- -H "Content-Type: application/json" \
- -d '{"action":"new","url":"https://linkedin.com/login"}')
-TAB_ID=$(echo $NAV | jq -r '.tabId')
-echo "Tab: $TAB_ID"
-
-# 3. Get page structure
-echo "Getting page structure..."
-SNAP=$(curl -s "$BASE/instances/$INST_ID/snapshot?filter=interactive&tabId=$TAB_ID")
-echo $SNAP | jq '.elements[]' | head -5
-
-# 4. Find email input (ref=e1) and type
-echo "Entering email..."
-curl -s -X POST "$BASE/instances/$INST_ID/action" \
- -H "Content-Type: application/json" \
- -d "{\"kind\":\"type\",\"ref\":\"e1\",\"text\":\"[email protected]\",\"tabId\":\"$TAB_ID\"}"
-
-# 5. Find password input (ref=e2) and type
-echo "Entering password..."
-curl -s -X POST "$BASE/instances/$INST_ID/action" \
- -H "Content-Type: application/json" \
- -d "{\"kind\":\"type\",\"ref\":\"e2\",\"text\":\"password123\",\"tabId\":\"$TAB_ID\"}"
-
-# 6. Find sign-in button (ref=e3) and click
-echo "Clicking sign in..."
-curl -s -X POST "$BASE/instances/$INST_ID/action" \
- -H "Content-Type: application/json" \
- -d "{\"kind\":\"click\",\"ref\":\"e3\",\"tabId\":\"$TAB_ID\"}"
-
-# 7. Wait for page load
-sleep 3
-
-# 8. Navigate to profile (creates new tab)
-echo "Navigating to profile..."
-NAV2=$(curl -s -X POST "$BASE/instances/$INST_ID/tabs/open" \
- -H "Content-Type: application/json" \
- -d '{"action":"new","url":"https://linkedin.com/in/myprofile"}')
-TAB_ID2=$(echo $NAV2 | jq -r '.tabId')
-echo "New tab: $TAB_ID2"
-
-# 9. Take screenshot
-echo "Taking screenshot..."
-curl -s "$BASE/tabs/$TAB_ID2/screenshot?quality=90" \
- -o profile.jpg
-echo "Saved: profile.jpg"
-
-# 10. List all tabs on instance
-echo "All tabs on instance:"
-curl -s "$BASE/instances/$INST_ID/tabs" | jq '.'
-```
-
----
-
-## Error Responses
-
-### 400 Bad Request
-```json
-{
- "error": "invalid request body",
- "details": "..."
-}
-```
-
-### 401 Unauthorized
-```json
-{
- "error": "authentication required"
-}
-```
-
-### 404 Not Found
-```json
-{
- "error": "instance not found",
- "id": "unknown-9868"
-}
-```
-
-### 500 Server Error
-```json
-{
- "error": "internal server error",
- "details": "..."
-}
-```
-
----
-
-## Authentication
-
-Include Bearer token if server requires auth:
-
-```bash
-curl -H "Authorization: Bearer YOUR_TOKEN" \
- http://localhost:9867/instances
-```
-
-Set via `PINCHTAB_TOKEN` when starting the server:
-
-```bash
-PINCHTAB_TOKEN=secret_token pinchtab
-```
-
----
-
-## Key Design Principles
-
-1. **Instance-Scoped** - All operations target a specific instance
-2. **Lazy Browser Init** - Chrome starts on first request, not at instance creation
-3. **Tab Creation on Navigate** - `/navigate` always creates new tabs
-4. **Profile & Mode per Instance** - Each instance has its own Chrome profile and headed/headless setting
-5. **Stateful Operations** - Cookies, history, and session state persist within an instance
-6. **Multi-Agent Safe** - Each agent gets its own instance with isolated state
-
----
-
-## CLI Equivalents
-
-Most endpoints have CLI shortcuts:
-
-```bash
-# Create instance
-pinchtab instances # List all
-pinchtab launch --profile work --headed # Create
-
-# Navigate & interact
-pinchtab nav https://pinchtab.com # Navigate (on default instance)
-pinchtab snap # Snapshot
-pinchtab click e5 # Click
-pinchtab type e1 "text" # Type
-
-# List tabs
-pinchtab tabs # All tabs across instances
-```
-
-See [CLI Commands Reference](cli-commands.md) for full CLI documentation.
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
new file mode 100644
index 00000000..5f4e6b99
--- /dev/null
+++ b/docs/architecture/index.md
@@ -0,0 +1,124 @@
+# Architecture
+
+PinchTab is a local HTTP control plane for Chrome aimed at agent-driven browser automation. Callers talk to PinchTab over HTTP and JSON; PinchTab translates those requests into browser work through Chrome DevTools Protocol.
+
+## Runtime Roles
+
+PinchTab has two runtime roles:
+
+- **Server**: `pinchtab` or `pinchtab server`
+- **Bridge**: `pinchtab bridge`
+
+Today, the main production shape is:
+
+- the **server** manages profiles, instances, routing, and the dashboard
+- each managed instance is a separate **bridge-backed** browser runtime
+- the bridge owns one browser context and serves the single-instance browser API
+
+PinchTab also supports an advanced attach path:
+
+- the server can register an externally managed Chrome instance through `POST /instances/attach`
+- attach is policy-gated by `attach.enabled`, `attach.allowHosts`, and `attach.allowSchemes`
+
+The current managed implementation is bridge-backed. Any direct-CDP-only managed model is architectural discussion elsewhere, not the default runtime path in this codebase.
+
+## System Overview
+
+```mermaid
+flowchart TD
+ A["Agent / CLI / HTTP Client"] --> S["PinchTab Server"]
+
+ S --> D["Dashboard + Config + Profiles API"]
+ S --> O["Orchestrator + Strategy Layer"]
+ S --> Q["Optional Scheduler"]
+
+ O --> M1["Managed Instance"]
+ O --> M2["Managed Instance"]
+
+ M1 --> B1["pinchtab bridge"]
+ M2 --> B2["pinchtab bridge"]
+
+ B1 --> C1["Chrome"]
+ B2 --> C2["Chrome"]
+
+ C1 --> T1["Tabs"]
+ C2 --> T2["Tabs"]
+
+ S -. "advanced attach path" .-> E["Registered External Chrome"]
+```
+
+## Request Flow
+
+For the normal multi-instance server path, the flow is:
+
+```mermaid
+flowchart LR
+ R["HTTP Request"] --> M["Auth + Middleware"]
+ M --> P["Policy Checks"]
+ P --> X["Routing / Instance Resolution"]
+ X --> B["Bridge Handler"]
+ B --> C["Chrome via CDP"]
+ C --> O["JSON / Text / PDF / Image Response"]
+```
+
+Important details:
+
+- auth and common middleware run at the HTTP layer
+- policy checks include attach policy and, when enabled, IDPI protections
+- tab-scoped routes are resolved to the owning instance before execution
+- the bridge runtime performs the actual CDP work
+
+In bridge-only mode, the orchestrator and multi-instance routing layers are skipped, but the same browser handler model still applies.
+
+## Current Architecture
+
+The current implementation centers on these pieces:
+
+- **Profiles**: persistent browser state stored on disk
+- **Instances**: running browser runtimes associated with profiles or external CDP URLs
+- **Tabs**: the main execution surface for navigation, extraction, and actions
+- **Orchestrator**: launches, tracks, stops, and proxies managed instances
+- **Bridge**: owns the browser context, tab registry, ref cache, and action execution
+
+The main instance types in practice are:
+
+- **managed bridge-backed instances** launched by the server
+- **attached external instances** registered through the attach API
+
+## Security And Policy Layer
+
+PinchTab's protection logic lives in the HTTP handler layer, not in the caller and not in Chrome itself.
+
+When `security.idpi` is enabled, the current implementation can:
+
+- block or warn on navigation targets using domain policy
+- scan `/text` output for common prompt-injection patterns
+- scan `/snapshot` content for the same class of patterns
+- wrap `/text` output in `<untrusted_web_content>` when configured
+
+Architecturally, this keeps policy separate from routing and execution:
+
+```text
+request -> middleware/policy -> routing -> execution -> response
+```
+
+## Design Principles
+
+- **HTTP for callers**: agents and tools talk to PinchTab over HTTP, not raw CDP
+- **A11y-first interaction**: snapshots and refs are the primary structured interface
+- **Instance isolation**: managed instances run separately and keep isolated browser state
+- **Tab-scoped execution**: once a tab is known, actions route to that tab's owning runtime
+- **Optional coordination layers**: strategy routing and the scheduler sit above the same browser execution surface
+
+## Code Map
+
+The most important packages for the current architecture are:
+
+- `cmd/pinchtab`: process startup modes and CLI entrypoints
+- `internal/orchestrator`: instance lifecycle, attach, and tab-to-instance proxying
+- `internal/bridge`: browser runtime, tab state, and CDP execution
+- `internal/handlers`: single-instance HTTP handlers
+- `internal/profiles`: persistent profile management
+- `internal/strategy`: server-side routing behavior for shorthand requests
+- `internal/scheduler`: optional queued task dispatch
+- `internal/config`: runtime and file config loading
diff --git a/docs/architecture/instance-charts.md b/docs/architecture/instance-charts.md
new file mode 100644
index 00000000..82778675
--- /dev/null
+++ b/docs/architecture/instance-charts.md
@@ -0,0 +1,110 @@
+# Instance Charts
+
+This page captures the current instance model in PinchTab.
+
+It is intentionally limited to the instance types and relationships that exist now in the codebase.
+
+## Chart 1: Current Instance Types
+
+```mermaid
+flowchart TD
+ I["Instance"] --> M["Managed"]
+ I --> A["Attached"]
+
+ M --> MB["Bridge-backed"]
+ A --> EX["External Chrome registration"]
+```
+
+Current meaning:
+
+- **managed** means PinchTab launches and owns the runtime lifecycle
+- **attached** means PinchTab registers an already running external Chrome
+- **bridge-backed** means the server reaches the browser through a `pinchtab bridge` runtime
+
+## Chart 2: Managed Instance Shape
+
+```mermaid
+flowchart LR
+ S["PinchTab Server"] --> O["Orchestrator"]
+ O --> B["pinchtab bridge child"]
+ B --> C["Chrome"]
+ C --> T["Tabs"]
+ O --> P["Profile directory"]
+```
+
+For managed instances today:
+
+- the orchestrator launches a bridge child process
+- the bridge owns one browser runtime
+- tabs live inside that runtime
+- browser state is tied to the associated profile directory
+
+## Chart 3: Attached Instance Shape
+
+```mermaid
+flowchart LR
+ S["PinchTab Server"] --> O["Orchestrator"]
+ O -. "attach via CDP URL" .-> E["External Chrome"]
+ E --> T["Tabs"]
+```
+
+For attached instances today:
+
+- PinchTab does not launch the browser
+- PinchTab stores registration metadata in the instance registry
+- ownership of the external browser process stays outside PinchTab
+- attached registration exists today, but the normal managed-instance tab proxy path is still centered on bridge-backed instances
+
+## Chart 4: Ownership Model
+
+```mermaid
+flowchart TD
+ I["Instance"] --> L["Lifecycle owner"]
+
+ L --> P["PinchTab"]
+ L --> X["External process owner"]
+
+ P --> M["Managed instance"]
+ X --> A["Attached instance"]
+```
+
+This is the key distinction:
+
+- managed instances are lifecycle-owned by PinchTab
+- attached instances are tracked by PinchTab but not process-owned by PinchTab
+
+## Chart 5: Routing Relationship
+
+```mermaid
+flowchart TD
+ I["Instance"] --> T["Tabs"]
+ T --> R["Tab-scoped routes"]
+ R --> O["Owning instance resolution"]
+```
+
+The important runtime rule is:
+
+- tabs belong to one instance
+- for managed bridge-backed instances, tab-scoped server routes are resolved to the owning instance before proxying
+
+## Current Instance Fields
+
+The main instance fields surfaced by the current API are:
+
+- `id`
+- `profileId`
+- `profileName`
+- `port`
+- `headless`
+- `status`
+- `startTime`
+- `error`
+- `attached`
+- `cdpUrl`
+
+Useful interpretation:
+
+- `attached: false` usually means a managed bridge-backed instance
+- `attached: true` means an externally registered instance
+- `port` is relevant for managed bridge-backed instances
+- `cdpUrl` is relevant for attached instances
diff --git a/docs/architecture/instance-model-charts.md b/docs/architecture/instance-model-charts.md
deleted file mode 100644
index 29d80c13..00000000
--- a/docs/architecture/instance-model-charts.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Instance Model Charts
-
-This page collects the visual mental model for Pinchtab instances.
-
-It complements:
-- [Architecture](pinchtab-architecture.md)
-- [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md)
-
-## Chart 1: Current High-Level Model
-
-```mermaid
-flowchart LR
- U["User / Agent"] --> S["Pinchtab Server"]
-
- S --> I1["Managed Instance"]
- I1 --> B["Bridge process"]
- B --> C["Chrome"]
- C --> T["Tabs"]
-
- S -. attach .-> E["External Chrome"]
- E --> T2["Tabs"]
-```
-
-## Chart 2: Instance Kinds
-
-```mermaid
-flowchart TD
- I["Instance"] --> K{"Kind"}
-
- K --> A["attached-external"]
- K --> B["managed-bridge"]
- K --> C["managed-direct-cdp"]
- K --> D["adopted / handover"]
-
- A --> A1["Pinchtab did not launch browser"]
- B --> B1["Pinchtab launched bridge process"]
- C --> C1["Pinchtab launched browser directly"]
- D --> D1["Browser was created elsewhere, then handed to server"]
-```
-
-## Chart 3: Communication Paths
-
-```mermaid
-flowchart LR
- S["Pinchtab Server"]
-
- S -->|HTTP| B["Bridge instance"]
- B -->|CDP| C1["Chrome"]
-
- S -->|CDP| C2["Direct-CDP instance"]
-
- S -->|CDP| C3["Attached external Chrome"]
-```
-
-## Chart 4: Lifecycle Ownership
-
-```mermaid
-flowchart TD
- M["Instance lifecycle"] --> L1["Launch by Pinchtab"]
- M --> L2["Attach existing browser"]
- M --> L3["Adopt then manage"]
- M --> L4["Create then hand over"]
-
- L1 --> X1["Pinchtab owns start/stop"]
- L2 --> X2["Pinchtab routes, but may not own process"]
- L3 --> X3["Pinchtab takes over ownership after attach"]
- L4 --> X4["Pinchtab creates browser, then another controller owns it"]
-```
-
-## Chart 5: Recommended Taxonomy
-
-```mermaid
-flowchart TD
- S["Pinchtab Server / Control Plane"]
-
- S --> R["Instance Registry"]
-
- R --> I1["managed-bridge"]
- R --> I2["managed-direct-cdp"]
- R --> I3["attached-external"]
-
- I1 --> P1["Transport: HTTP -> bridge -> CDP"]
- I2 --> P2["Transport: direct CDP"]
- I3 --> P3["Transport: direct CDP"]
-
- P1 --> T1["Tabs"]
- P2 --> T2["Tabs"]
- P3 --> T3["Tabs"]
-```
-
-## Recommended Reading Of These Charts
-
-The cleanest interpretation is:
-
-- `source` answers who introduced the instance
-- `runtime` answers how Pinchtab reaches the browser
-- `ownership` answers who controls lifecycle
-
-For the current architecture, the useful combinations are:
-
-- `managed + bridge + pinchtab`
-- `attached + direct-cdp + external`
-
-And the main future option is:
-
-- `managed + direct-cdp + pinchtab`
diff --git a/docs/architecture/orchestration.md b/docs/architecture/orchestration.md
new file mode 100644
index 00000000..0cb76165
--- /dev/null
+++ b/docs/architecture/orchestration.md
@@ -0,0 +1,155 @@
+# Orchestration
+
+This page describes the current orchestration layer in PinchTab: how the server launches, tracks, routes to, and stops browser instances.
+
+## Scope
+
+The orchestrator is part of server mode. It is responsible for:
+
+- launching managed instances as child `pinchtab bridge` processes
+- attaching externally managed Chrome instances when attach policy allows it
+- tracking instance status and metadata
+- routing tab-scoped requests to the owning managed instance
+- stopping managed instances and cleaning up registry state
+
+It does not execute browser actions directly. That work happens inside the bridge runtime.
+
+## Current Runtime Shape
+
+```mermaid
+flowchart TD
+ S["PinchTab Server"] --> O["Orchestrator"]
+
+ O --> M1["Managed Instance"]
+ O --> M2["Managed Instance"]
+ O -.->|attach| A1["Attached External Instance"]
+
+ M1 --> B1["pinchtab bridge child"]
+ M2 --> B2["pinchtab bridge child"]
+
+ B1 --> C1["Chrome"]
+ B2 --> C2["Chrome"]
+```
+
+## Launch Flow
+
+For a managed instance, the orchestration flow is:
+
+```mermaid
+flowchart LR
+ R["Start Request"] --> V["Validate profile + port"]
+ V --> W["Write child config"]
+ W --> P["Spawn pinchtab bridge"]
+ P --> H["Poll /health on loopback addresses"]
+ H --> S{"Healthy before timeout?"}
+ S -->|Yes| OK["Mark running"]
+ S -->|No| ER["Mark error"]
+```
+
+What the code does today:
+
+- validates the profile name before launch
+- allocates a port when one is not supplied
+- prevents more than one active managed instance per profile
+- prevents reusing a port already in use
+- writes a child config file under the profile state directory
+- launches `pinchtab bridge`
+- polls `/health` on `127.0.0.1`, `::1`, and `localhost`
+- moves the instance from `starting` to `running` or `error`
+
+## Attach Flow
+
+Attach is a separate path for an already running browser.
+
+```mermaid
+flowchart LR
+ R["POST /instances/attach"] --> P["Validate attach policy"]
+ P --> A["Register external instance"]
+ A --> L["Add to instance registry"]
+```
+
+Current attach behavior:
+
+- requires `attach.enabled`
+- validates the CDP URL against `attach.allowSchemes`
+- validates the host against `attach.allowHosts`
+- registers the instance as `attached: true`
+- does not start or stop an external Chrome process
+
+## Routing Model
+
+The orchestrator is also the routing layer for multi-instance server mode.
+
+```mermaid
+flowchart LR
+ R["Tab-scoped request"] --> T["Resolve tab owner"]
+ T --> C["Locator cache"]
+ C -->|hit| P["Proxy to instance port"]
+ C -->|miss| F["Fetch /tabs from running instances"]
+ F --> P
+```
+
+Today, tab routing works like this:
+
+- for routes such as `/tabs/{id}/navigate` and `/tabs/{id}/action`, the server resolves which instance owns the tab
+- it first tries the instance locator cache
+- on cache miss, it falls back to scanning running instances through `/tabs`
+- after resolution, it proxies the request to the owning bridge instance
+
+This keeps the public server API stable while the bridge instances remain isolated.
+
+Important limitation:
+
+- this routing path is fully shaped around managed bridge-backed instances that expose loopback HTTP ports
+- attached instances are registered and surfaced in the instance registry, but the normal tab-owner proxy path is not yet equally first-class for them
+
+## Stop Flow
+
+Stopping a managed instance is a server-owned lifecycle operation.
+
+```mermaid
+flowchart LR
+ R["Stop Request"] --> S["Mark stopping"]
+ S --> G["POST /shutdown to instance"]
+ G --> W{"Exited?"}
+ W -->|No| T["SIGTERM"]
+ T --> K{"Exited?"}
+ K -->|No| X["SIGKILL"]
+ W -->|Yes| D["Remove from registry"]
+ K -->|Yes| D
+ X --> D
+```
+
+Current stop behavior:
+
+- marks the instance as `stopping`
+- tries graceful shutdown through the instance HTTP API
+- falls back to process-group termination when needed
+- releases the allocated port
+- removes the instance from the registry and locator cache
+
+For attached instances, there is no child process to kill; the orchestrator only removes its own registration state.
+
+## Instance States
+
+The main statuses surfaced today are:
+
+- `starting`
+- `running`
+- `stopping`
+- `stopped`
+- `error`
+
+The orchestrator also emits lifecycle events such as:
+
+- `instance.started`
+- `instance.stopped`
+- `instance.error`
+- `instance.attached`
+
+## Relationship To Other Layers
+
+- **Strategy layer** decides how shorthand requests are exposed or routed in server mode
+- **Scheduler** is optional and sits above the same routed execution path
+- **Bridge** owns browser state, tab state, and CDP execution
+- **Profiles** provide persistent browser data on disk
diff --git a/docs/architecture/overall-system-chart.md b/docs/architecture/overall-system-chart.md
deleted file mode 100644
index 274575eb..00000000
--- a/docs/architecture/overall-system-chart.md
+++ /dev/null
@@ -1,195 +0,0 @@
-# Overall System Chart
-
-This page gives the full mental model of Pinchtab in one place.
-
-It combines:
-- the primary user path
-- the server/bridge runtime split
-- managed vs attached instances
-- current routing and execution
-- current security layer and future scheduling layer
-
-## Chart 1: Overall Product Shape
-
-```mermaid
-flowchart TD
- U["User / Agent / Tool"] --> S["Pinchtab Server"]
-
- S --> D["Dashboard / Profiles / Instance API"]
- S --> R["Routing / Orchestrator"]
- S --> X["Shorthand Browser API"]
-
- R --> M1["Managed Instance"]
- R --> A1["Attached Instance"]
-
- M1 --> B["pinchtab bridge"]
- B --> C1["Chrome"]
- C1 --> T1["Tabs"]
-
- A1 --> C2["External Chrome"]
- C2 --> T2["Tabs"]
-```
-
-## Chart 2: Primary Usage Path
-
-```mermaid
-flowchart LR
- I["Install Pinchtab"] --> P["Run: pinchtab"]
- P --> L["Local server on localhost:9867"]
- L --> A["Agent / Tool connects over HTTP"]
- A --> W["Browser work happens through Pinchtab"]
-```
-
-This is the primary user journey.
-
-The normal user should think:
-- install Pinchtab
-- run `pinchtab`
-- point the client at `http://localhost:9867`
-
-They should not need to think about `pinchtab bridge` directly.
-
-## Chart 3: Runtime Types
-
-```mermaid
-flowchart TD
- I["Instance"] --> S{"source"}
-
- S --> M["managed"]
- S --> A["attached"]
-
- M --> R1{"runtime"}
- A --> R2{"runtime"}
-
- R1 --> B["bridge"]
- R1 --> D["direct-cdp"]
-
- R2 --> D2["direct-cdp"]
-```
-
-Interpretation:
-- `source` = who introduced the instance
-- `runtime` = how the server reaches the browser
-
-## Chart 4: Current And Future Execution Layers
-
-```mermaid
-flowchart LR
- U["Agent Request"] --> P["Policy / Security Layer"]
- P --> Q["Task Scheduling Layer"]
- Q --> O["Orchestrator / Routing"]
- O --> E["Bridge Executor or Direct CDP"]
- E --> C["Chrome Tab"]
-```
-
-Meaning:
-- **Policy / Security** decides whether a request should be admitted or sanitized
-- **Task Scheduling** decides when and where admitted work should run
-- **Orchestrator / Routing** decides which instance/tab path is used
-- **Executor** performs the actual tab work
-
-Today:
-- execution exists
-- routing exists
-- security exists as a real IDPI defense layer
-- scheduling is still mostly direct execution plus concurrency control
-
-## Chart 4A: Current Security Layer
-
-```mermaid
-flowchart TD
- R["Request"] --> N{"Navigation?"}
- N -->|Yes| D["IDPI domain policy"]
- N -->|No| X["Continue"]
-
- D --> D2{"Allowed?"}
- D2 -->|No, strict| B["Block"]
- D2 -->|No, warn| W["Add warning header"]
- D2 -->|Yes| X
-
- X --> O{"Output content?"}
- O -->|Text or Snapshot| S["IDPI content scan"]
- O -->|Other| E["Execute / Return"]
-
- S --> S2{"Threat?"}
- S2 -->|No| E
- S2 -->|Yes, strict| B2["Block response"]
- S2 -->|Yes, warn| W2["Add warning metadata"]
-
- W2 --> WR{"Wrap text?"}
- WR -->|Yes| WT["Wrap as untrusted_web_content"]
- WR -->|No| E
- WT --> E
-```
-
-Current implementation shape:
-
-- navigation checks happen before the tab opens or re-navigates
-- content scanning happens on `/text` and `/snapshot`
-- text wrapping is applied to `/text` output when enabled
-- strict mode blocks, warn mode annotates
-
-## Chart 5: Current Execution Model
-
-```mermaid
-flowchart TD
- H["HTTP Request"] --> O["Orchestrator / Server"]
- O --> T["Target Tab"]
- T --> L["Per-tab lock"]
- L --> G["Global concurrency limit"]
- G --> E["Execute CDP action"]
-```
-
-This is the current model already present in the product:
-- per-tab sequential execution
-- bounded cross-tab parallelism
-- direct request execution
-
-That means the current architecture already has:
-
-- a **security layer** for admission and output safety
-- an **execution layer** for concurrency correctness
-
-What it does not yet have as a first-class subsystem is:
-
-- a true **task scheduling layer** with queued work, fairness, and dispatch policy
-
-## Chart 6: Recommended Future Model
-
-```mermaid
-flowchart TD
- H["HTTP Request"] --> A["Admission"]
- A --> B{"Allowed?"}
- B -->|No| X["Reject"]
- B -->|Yes| Q["Queue"]
- Q --> S["Scheduler"]
- S --> R["Instance / Tab selection"]
- R --> E["Executor"]
- E --> C["Chrome"]
-```
-
-This is the cleaner model for multi-agent and parallel execution:
-- requests become tasks
-- tasks are admitted or rejected
-- admitted tasks are queued
-- the scheduler chooses what runs next
-- existing executors still enforce per-tab correctness
-
-## Reading Guide
-
-Use the charts like this:
-
-- **Chart 1** for the product overview
-- **Chart 2** for onboarding and default usage
-- **Chart 3** for instance taxonomy
-- **Chart 4** for control-plane layering
-- **Chart 5** for how execution works today
-- **Chart 6** for the likely future scheduling architecture
-
-## Related Docs
-
-- [Architecture](pinchtab-architecture.md)
-- [Instance Model Charts](instance-model-charts.md)
-- [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md)
-- [Expert Guide: Attach](../guides/expert-attach.md)
-- [Expert Guide: Multi-Instance Strategies](../guides/expert-strategies.md)
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
deleted file mode 100644
index cc5a1984..00000000
--- a/docs/architecture/overview.md
+++ /dev/null
@@ -1,353 +0,0 @@
-# Architecture
-
-## Overview
-
-Pinchtab is an HTTP server that wraps Chrome DevTools Protocol (CDP) to give AI agents browser control via a simple REST API.
-
-The product has two process roles:
-- **Server** — the default `pinchtab` process that manages profiles, instances, routing, and the dashboard
-- **Bridge** — the single-instance `pinchtab bridge` runtime used for one managed browser
-
-**Managed mode (default):** the Pinchtab server launches and manages bridge-backed Chrome instances.
-
-```
-┌─────────────┐ HTTP ┌──────────────┐ CDP ┌──────────────┐
-│ AI Agent │ ────────────▶ │ Pinchtab │ ─────────────▶ │ Chrome │
-│ (any LLM) │ ◀──────────── │ (Go binary) │ ◀───────────── │ self-launched │
-└─────────────┘ JSON/text └──────────────┘ WebSocket └──────────────┘
-```
-
-**Attach mode (advanced):** the Pinchtab server can register an externally managed Chrome instance through the instance API when attach is enabled by policy.
-
-```
-┌─────────────┐ HTTP ┌──────────────┐ CDP ┌──────────────┐
-│ Multiple │ ────────────▶ │ Pinchtab │ ─────────────▶ │ External │
-│ Agents │ ◀──────────── │ Server │ ◀───────────── │ Chrome │
-│ │ JSON/text │ │ WebSocket │ Instance │
-└─────────────┘ └──────────────┘ └──────────────┘
-```
-
-Agents never touch CDP directly. They send HTTP requests, get back JSON.
-The accessibility tree (a11y) is the primary interface — not screenshots, not DOM.
-
-## Security Layer
-
-Pinchtab now has a real security layer for indirect prompt injection defense.
-
-This layer lives in the server path, not inside the agent and not inside Chrome.
-Its job is to inspect untrusted web input before that content is passed back to an LLM-driven caller.
-
-Current security responsibilities:
-
-- **domain policy on navigation** — block or warn before navigating to non-approved domains
-- **content scanning on output** — scan `/text` and `/snapshot` output for common prompt-injection phrases
-- **content wrapping** — wrap extracted text in `<untrusted_web_content>` delimiters with a safety advisory
-
-The important architectural distinction is:
-
-- **security** decides whether content should be admitted, annotated, or blocked
-- **routing** decides which instance/tab path handles the request
-- **execution** performs the actual browser action
-
-In other words:
-
-```text
-request
- -> security / policy
- -> routing
- -> execution
-```
-
-The security layer is configured through `security.idpi` in config and supports:
-
-- `enabled`
-- `allowedDomains`
-- `strictMode`
-- `scanContent`
-- `wrapContent`
-- `customPatterns`
-
-Strict mode blocks.
-Warn mode allows the request but annotates the response with an IDPI warning.
-
-## Instance Mental Model
-
-The cleanest way to think about instances is with two axes:
-
-- **Source** — who created or registered the instance
-- **Runtime** — how the server reaches the browser
-
-### Chart 1: Process Roles
-
-```text
-pinchtab server
- ├─ manages profiles
- ├─ manages instances
- ├─ routes requests
- └─ serves dashboard/API
-
-pinchtab bridge
- ├─ wraps one browser
- ├─ exposes single-instance HTTP API
- └─ is usually spawned by the server
-```
-
-### Chart 2: Instance Taxonomy
-
-```text
-Instance
- ├─ source: managed
- │ ├─ runtime: bridge
- │ └─ runtime: direct-cdp (possible future model)
- │
- └─ source: attached
- └─ runtime: direct-cdp
-```
-
-This separation matters:
-
-- `managed` means Pinchtab owns instance lifecycle
-- `attached` means Pinchtab registers an already running browser
-- `bridge` means the server talks HTTP to a child Pinchtab runtime
-- `direct-cdp` means the server talks to Chrome over CDP directly
-
-### Suggested Instance Schema
-
-If you model this explicitly in the instance object, the clean shape is:
-
-```json
-{
- "id": "inst_0a89a5bb",
- "name": "work",
- "source": "managed",
- "runtime": "bridge",
- "ownership": "pinchtab",
- "status": "starting",
- "profileId": "prof_278be873",
- "profileName": "work",
- "port": "9868",
- "baseUrl": "http://127.0.0.1:9868",
- "cdpUrl": "",
- "attached": false
-}
-```
-
-Recommended fields:
-
-- `id` — stable instance identifier
-- `name` — human-oriented instance/profile label
-- `source` — `managed` or `attached`
-- `runtime` — `bridge` or `direct-cdp`
-- `ownership` — `pinchtab`, `external`, or `adopted`
-- `status` — `starting`, `running`, `stopping`, `stopped`, `error`
-- `profileId` / `profileName` — associated profile, when relevant
-- `port` / `baseUrl` — bridge-facing address when the instance has an HTTP runtime
-- `cdpUrl` — discovered or attached CDP endpoint when relevant
-- `attached` — compatibility field for old clients; derivable from `source == "attached"`
-
-In other words:
-
-```text
-source = who introduced the instance
-runtime = how the server reaches it
-ownership = who controls its lifecycle
-```
-
-That gives these combinations:
-
-```text
-managed + bridge + pinchtab
-managed + direct-cdp + pinchtab
-attached + direct-cdp + external
-```
-
-### Chart 3: Routing Paths
-
-```text
-Managed + bridge
- server -> bridge -> Chrome -> tabs
-
-Managed + direct-cdp
- server -> Chrome -> tabs
-
-Attached + direct-cdp
- server -> external Chrome -> tabs
-```
-
-### Chart 4: What Lives In The Pool
-
-```text
-Pinchtab server
- └─ instance pool
- ├─ instance A
- │ └─ tabs
- ├─ instance B
- │ └─ tabs
- └─ instance C
- └─ tabs
-```
-
-The pool contains **instances**, not tabs.
-Tabs always belong to an instance.
-
-### Current And Future Scope
-
-Today, the intended architecture is:
-
-- `managed + bridge` for Pinchtab-launched instances
-- `attached + direct-cdp` for externally managed browsers
-
-A plausible future expansion is:
-
-- `managed + direct-cdp` to remove the extra HTTP hop when the server can own Chrome directly
-
-For a focused comparison, see [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md).
-For the visual version of the model, see [Instance Model Charts](instance-model-charts.md).
-For the full system picture, see [Overall System Chart](overall-system-chart.md).
-
-## Design Principles
-
-1. **A11y tree over screenshots** — 4x cheaper in tokens, works with any LLM
-2. **HTTP over WebSocket** — Stateless requests, no connection management for agents
-3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints
-4. **Self-contained by default** — Launches and manages Chrome itself unless you explicitly use attach
-5. **Layered Safety** — Security policy is enforced before untrusted web content reaches downstream agents
-6. **Decoupled Architecture** — Interface-driven design for testability and maintainability
-
-## Project Layout
-
-The project follows the standard Go `internal/` pattern to ensure encapsulation and clean boundaries:
-
-```
-pinchtab/
-├── cmd/pinchtab/ # Application entry points and CLI commands
-├── internal/
-│ ├── bridge/ # Core CDP logic, tab management, and state logic
-│ ├── handlers/ # HTTP API handlers and middleware
-│ ├── orchestrator/ # Multi-instance lifecycle and process management
-│ ├── profiles/ # Chrome profile management and identity discovery
-│ ├── dashboard/ # Backend logic and static assets for the web UI
-│ ├── assets/ # Centralized embedded files (stealth scripts, HTML)
-│ ├── human/ # Human-like interaction simulation (Bezier mouse, typing)
-│ ├── config/ # Centralized configuration management
-│ └── web/ # Shared HTTP and JSON utilities
-├── Dockerfile # Alpine + Chromium container image
-└── scripts/ # Deployment and automation scripts
-```
-
-## Core Components
-
-### Bridge (`internal/bridge`)
-
-The central state holder. Owns the Chrome browser context, tab registry, and snapshot caches. It implements the `BridgeAPI` interface.
-
-Key responsibilities:
-- **Tab lifecycle** — `CreateTab`, `CloseTab`, `TabContext` (resolve "" to first tab)
-- **Ref caching** — Each tab's last snapshot is cached. When `/action` receives `ref: "e5"`,
- it looks up the cached `BackendDOMNodeID` without re-fetching the a11y tree.
-- **State Logic** — Diffing snapshots and manage session persistence (`SaveState`/`RestoreState`).
-
-### Orchestrator (`internal/orchestrator`)
-
-Manages multiple isolated browser instances. It uses a `HostRunner` interface to decouple business logic from OS process management.
-
-Key responsibilities:
-- **Instance Registry** — Tracking running instances, their ports, and statuses.
-- **Process Management** — Spawning, signaling, and stopping instances.
-- **Health Monitoring** — Probing instance health via HTTP.
-
-### Profiles (`internal/profiles`)
-
-Handles Chrome user data directories and metadata.
-
-Key responsibilities:
-- **CRUD Operations** — Creating, importing, and resetting profiles.
-- **Identity Discovery** — Parsing internal Chrome JSON files to find user identity info.
-- **Activity Tracking** — Recording and analyzing agent actions per profile.
-
-### Snapshot Pipeline (`internal/bridge/snapshot.go`)
-
-The a11y tree is Pinchtab's core abstraction. Flow:
-
-```
-Chrome a11y tree (CDP)
- │
- ▼
- Raw JSON parse (RawAXNode) ← Manual parsing to avoid cdproto crash
- │ on "uninteresting" PropertyName values
- ▼
- Flatten to []A11yNode ← DFS walk, assign refs (e0, e1, e2...)
- │
- ├──▶ JSON (default) ← Full structured output
- ├──▶ Text (indented tree) ← Low-token format for agents
- └──▶ YAML ← Alternative structured format
-```
-
-**Ref caching**: When `/snapshot` is called, the ref→nodeID mapping is stored per tab.
-When `/action` receives `{"ref": "e5", "kind": "click"}`, it looks up `e5` in the cache.
-
-### Human Interaction (`internal/human`)
-
-Two main simulation engines for anti-detection:
-
-**`MouseMove`** — Cubic bezier curve from A to B:
-- Random control points for natural curvature
-- Step count scales with distance (5-30 steps)
-- Per-step jitter and variable timing
-
-**`Type`** — Keystroke-level simulation:
-- Base delay: 80ms/char (40ms in fast mode)
-- Random long pauses ("thinking")
-- Simulated typos and backspace corrections
-
-## Deployment
-
-### Binary (recommended)
-```bash
-# Build
-go build -o pinchtab ./cmd/pinchtab
-
-# Run
-PINCHTAB_TOKEN=secret ./pinchtab
-```
-
-### Docker
-```bash
-docker build -t pinchtab .
-docker run -d -p 9867:9867 -e PINCHTAB_TOKEN=secret pinchtab
-```
-
----
-
-## CDP Architecture
-
-PinchTab sits between your tools/agents and Chrome:
-
-```text
-┌─────────────────────────────────────────┐
-│ Your Tool/Agent │
-│ (CLI, curl, Python, Node.js, etc.) │
-└──────────────┬──────────────────────────┘
- │
- │ HTTP
- ↓
-┌─────────────────────────────────────────┐
-│ PinchTab HTTP Server (Go) │
-│ ┌─────────────────────────────────┐ │
-│ │ Tab Manager │ │
-│ │ (tracks tabs + sessions) │ │
-│ └─────────────────────────────────┘ │
-│ ┌─────────────────────────────────┐ │
-│ │ Chrome DevTools Protocol (CDP) │ │
-│ └─────────────────────────────────┘ │
-└──────────────┬──────────────────────────┘
- │
- │ CDP WebSocket
- ↓
-┌─────────────────────────────────────────┐
-│ Chrome Browser │
-│ (Headless, headed, or external) │
-└─────────────────────────────────────────┘
-```
-
-PinchTab wraps Chrome's DevTools Protocol (CDP) to translate HTTP requests into CDP commands, manage browser state, and deliver structured responses (accessibility trees, screenshots, PDFs) back to your agents.
diff --git a/docs/architecture/system-charts.md b/docs/architecture/system-charts.md
new file mode 100644
index 00000000..6fef3da8
--- /dev/null
+++ b/docs/architecture/system-charts.md
@@ -0,0 +1,107 @@
+# System Charts
+
+This page collects the main high-level charts for the current PinchTab architecture.
+
+## Chart 1: Product Shape
+
+```mermaid
+flowchart TD
+ U["Agent / CLI / Tool"] --> S["PinchTab Server"]
+
+ S --> D["Dashboard + Config + Profiles API"]
+ S --> O["Orchestrator + Strategy Layer"]
+
+ O --> M1["Managed Instance"]
+ O --> M2["Managed Instance"]
+
+ M1 --> B1["pinchtab bridge"]
+ M2 --> B2["pinchtab bridge"]
+
+ B1 --> C1["Chrome"]
+ B2 --> C2["Chrome"]
+
+ C1 --> T1["Tabs"]
+ C2 --> T2["Tabs"]
+
+ S -. "advanced attach path" .-> E["Registered External Chrome"]
+```
+
+This is the default system shape today:
+
+- agents talk to the server over HTTP
+- the server manages profiles, instances, and routing
+- managed instances are bridge-backed
+- attach exists as an advanced external-browser registration path
+
+## Chart 2: Primary Usage Path
+
+```mermaid
+flowchart LR
+ I["Install PinchTab"] --> R["Run: pinchtab"]
+ R --> L["Local server on localhost:9867"]
+ L --> A["Agent / CLI sends HTTP requests"]
+ A --> W["Browser work happens through PinchTab"]
+```
+
+This is the normal mental model for users. Most users should think about `pinchtab`, not `pinchtab bridge`.
+
+## Chart 3: Runtime Shapes
+
+```mermaid
+flowchart LR
+ subgraph S1["Server Mode"]
+ C1["Client"] --> P1["pinchtab server"]
+ P1 --> B1["pinchtab bridge"]
+ B1 --> CH1["Chrome"]
+ CH1 --> T1["Tabs"]
+ end
+
+ subgraph S2["Bridge Mode"]
+ C2["Client"] --> B2["pinchtab bridge"]
+ B2 --> CH2["Chrome"]
+ CH2 --> T2["Tabs"]
+ end
+```
+
+Meaning:
+
+- **server mode** is the multi-instance control-plane path
+- **bridge mode** is the single-instance browser runtime
+
+## Chart 4: Current Request Paths
+
+```mermaid
+flowchart TD
+ R["HTTP Request"] --> M["Auth + Middleware"]
+ M --> T{"Route Type"}
+
+ T -->|Direct browser route| X["Tab / Instance Resolution"]
+ T -->|Task route, when enabled| Q["Scheduler"]
+ T -->|Attach route| A["Attach Policy Check"]
+
+ Q --> X
+ X --> H["Bridge Handler"]
+ H --> P["Handler-Level Policy Checks"]
+ P --> C["Chrome via CDP"]
+ C --> O["JSON / Text / PDF / Image Response"]
+
+ A --> AR["Register External Instance"]
+```
+
+Important details:
+
+- auth and shared middleware run at the HTTP layer
+- attach policy is enforced on the attach route in the server
+- IDPI and similar browser-facing checks run in handlers such as navigation, text, and snapshot
+- tab-scoped routes are resolved to the owning instance before execution
+- the scheduler is optional, server-only, and applies to `/tasks`
+- bridge handlers perform the actual browser work
+
+## Reading Guide
+
+Use the charts like this:
+
+- **Chart 1** for the product shape
+- **Chart 2** for onboarding and default usage
+- **Chart 3** for the difference between server mode and bridge mode
+- **Chart 4** for the current execution path
diff --git a/docs/guides/memory-monitoring.md b/docs/guides/memory-monitoring.md
index d6df5653..d608a5ef 100644
--- a/docs/guides/memory-monitoring.md
+++ b/docs/guides/memory-monitoring.md
@@ -1,4 +1,4 @@
-# Memory Monitoring Guide
+# Memory Monitoring
PinchTab exposes memory information for the Chrome processes it launches. The current implementation measures browser memory at the process level and reports browser-wide aggregates for each instance.
diff --git a/docs/guides/multi-instance.md b/docs/guides/multi-instance.md
index 2aa7aabd..7c8e307e 100644
--- a/docs/guides/multi-instance.md
+++ b/docs/guides/multi-instance.md
@@ -1,4 +1,4 @@
-# Multi-Instance Workflows
+# Multi-Instance
PinchTab can run multiple isolated Chrome instances at the same time. Each running instance has its own browser process, port, tabs, and profile-backed state.
diff --git a/docs/implementations/index.md b/docs/implementations/index.md
new file mode 100644
index 00000000..400e135d
--- /dev/null
+++ b/docs/implementations/index.md
@@ -0,0 +1,5 @@
+# Implementations
+
+This section covers implementation-focused documents: how specific subsystems work in practice, what tradeoffs they make, and how the current code is structured.
+
+Use these pages when you want lower-level detail than the architecture overview, but do not need full API reference material.
diff --git a/docs/architecture/managed-bridge-vs-managed-direct-cdp.md b/docs/implementations/managed-bridge-vs-managed-direct-cdp.md
similarity index 100%
rename from docs/architecture/managed-bridge-vs-managed-direct-cdp.md
rename to docs/implementations/managed-bridge-vs-managed-direct-cdp.md
diff --git a/docs/architecture/parallel-tab-execution.md b/docs/implementations/parallel-tab-execution.md
similarity index 100%
rename from docs/architecture/parallel-tab-execution.md
rename to docs/implementations/parallel-tab-execution.md
diff --git a/docs/index.json b/docs/index.json
index 1b2afa40..9ffd4b25 100644
--- a/docs/index.json
+++ b/docs/index.json
@@ -18,15 +18,12 @@
"guides/raspberry-pi.md"
],
"architecture": [
- "architecture/overview.md",
- "architecture/overall-system-chart.md",
- "architecture/instance-model-charts.md",
- "architecture/managed-bridge-vs-managed-direct-cdp.md",
- "architecture/chrome-lifecycle-and-orchestration.md",
- "architecture/find.md",
- "architecture/scheduler.md"
+ "*"
],
"reference": [
"*"
+ ],
+ "implementations": [
+ "*"
]
}