@cregis-dev/cckit 0.3.0 → 0.4.1

package/templates/ext-skills/pinchtab/SKILL.md

@@ -13,224 +13,90 @@ metadata:
     emoji: "🦀"
     requires:
       bins: ["pinchtab"]
-      env:
-        - name: BRIDGE_TOKEN
-          secret: true
-          optional: true
-          description: "Bearer auth token for Pinchtab API"
-        - name: BRIDGE_BIND
-          optional: true
-          description: "Bind address (default: 127.0.0.1, set 0.0.0.0 for network access)"
-        - name: BRIDGE_PORT
-          optional: true
-          description: "HTTP port (default: 9867)"
-        - name: BRIDGE_HEADLESS
-          optional: true
-          description: "Run Chrome headless (true/false)"
-        - name: BRIDGE_PROFILE
-          optional: true
-          description: "Chrome profile directory (default: ~/.pinchtab/chrome-profile)"
-        - name: BRIDGE_STATE_DIR
-          optional: true
-          description: "State/session storage directory (default: ~/.pinchtab)"
-        - name: BRIDGE_NO_RESTORE
-          optional: true
-          description: "Skip restoring tabs from previous session (true/false)"
-        - name: BRIDGE_STEALTH
-          optional: true
-          description: "Stealth level: light (default, basic) or full (canvas/WebGL/font spoofing)"
-        - name: BRIDGE_MAX_TABS
-          optional: true
-          description: "Maximum number of open tabs (default: 20, 0 = unlimited)"
-        - name: BRIDGE_BLOCK_IMAGES
-          optional: true
-          description: "Block image loading for faster, lower-bandwidth browsing (true/false)"
-        - name: BRIDGE_BLOCK_MEDIA
-          optional: true
-          description: "Block all media: images + fonts + CSS + video (true/false)"
-        - name: BRIDGE_NO_ANIMATIONS
-          optional: true
-          description: "Disable CSS animations/transitions globally (true/false)"
-        - name: BRIDGE_TIMEZONE
-          optional: true
-          description: "Force browser timezone (IANA tz, e.g. Europe/Rome)"
-        - name: BRIDGE_CHROME_VERSION
-          optional: true
-          description: "Chrome version string used by fingerprint rotation profiles"
-        - name: CHROME_BINARY
-          optional: true
-          description: "Path to Chrome/Chromium binary (auto-detected if not set)"
-        - name: CHROME_FLAGS
-          optional: true
-          description: "Extra Chrome flags, space-separated"
-        - name: BRIDGE_CONFIG
-          optional: true
-          description: "Path to config JSON file (default: ~/.pinchtab/config.json)"
-        - name: BRIDGE_TIMEOUT
-          optional: true
-          description: "Action timeout in seconds (default: 15)"
-        - name: BRIDGE_NAV_TIMEOUT
-          optional: true
-          description: "Navigation timeout in seconds (default: 30)"
-        - name: CDP_URL
-          optional: true
-          description: "Connect to existing Chrome DevTools instead of launching"
-        - name: BRIDGE_NO_DASHBOARD
-          optional: true
-          description: "Disable dashboard/orchestrator endpoints on instance processes"
-        - name: PINCHTAB_AUTO_LAUNCH
-          optional: true
-          description: "Dashboard mode: auto-launch default profile instance on startup"
-        - name: PINCHTAB_DEFAULT_PROFILE
-          optional: true
-          description: "Dashboard mode: default profile name for auto-launch"
-        - name: PINCHTAB_DEFAULT_PORT
-          optional: true
-          description: "Dashboard mode: default port for auto-launched profile"
-        - name: PINCHTAB_HEADED
-          optional: true
-          description: "Dashboard mode: when set, auto-launched profile runs headed"
-        - name: PINCHTAB_DASHBOARD_URL
-          optional: true
-          description: "Base dashboard URL used by `pinchtab connect` helper"
+      env: |
+        BRIDGE_TOKEN (optional, secret) - Bearer auth token for Pinchtab API
+        BRIDGE_PORT (optional) - HTTP port, default 9867
+        BRIDGE_HEADLESS (optional) - true/false for headless Chrome
+        BRIDGE_PROFILE (optional) - Chrome profile directory
+        BRIDGE_BIND (optional) - Bind address, default 127.0.0.1
 ---
 
 # Pinchtab
 
 Fast, lightweight browser control for AI agents via HTTP + accessibility tree.
 
-## Setup
-
-Start Pinchtab in one of these modes:
-
-```bash
-# Headless (default) — no UI, pure automation (lowest token cost when using /text and filtered snapshots)
-pinchtab &
-
-# Headed — visible Chrome for human + agent workflows
-BRIDGE_HEADLESS=false pinchtab &
-
-# Dashboard/orchestrator — profile manager + launcher, no browser in dashboard process
-pinchtab dashboard &
-```
-
-Default port: `9867`. Override with `BRIDGE_PORT=9868`.
-Auth: set `BRIDGE_TOKEN=<secret>` and pass `Authorization: Bearer <secret>`.
-
-Base URL for all examples: `http://localhost:9867`
-
-Token savings come from the API shape (`/text`, `/snapshot?filter=interactive&format=compact`), not from headless vs headed alone.
-
-### Headed mode definition
+**Security Note:** Pinchtab runs entirely locally. It does not contact external services, send telemetry, or exfiltrate data. However, it controls a real Chrome instance — if pointed at a profile with saved logins, agents can access authenticated sites. Always use a dedicated empty profile and set BRIDGE_TOKEN when exposing the API. See [TRUST.md](TRUST.md) for the full security model.
 
-Headed mode means a real visible Chrome window managed by Pinchtab.
+## Quick Start (Agent Workflow)
 
-- Human can open profile(s), log in, pass 2FA/captcha, and validate page state
-- Agent then calls Pinchtab HTTP APIs against that same running profile instance
-- Session state persists in the profile directory, so follow-up runs reuse cookies/storage
-
-In dashboard workflows, the dashboard process itself does not launch Chrome; it launches profile instances that run Chrome (headed or headless).
-
-To resolve a running profile endpoint from dashboard state:
+The 30-second pattern for browser tasks:
 
 ```bash
-pinchtab connect <profile-name>
-```
-
-Recommended human + agent flow:
-
-```bash
-# human
-pinchtab dashboard
-# setup profile + launch profile instance
-
-# agent
-PINCHTAB_BASE_URL="$(pinchtab connect <profile-name>)"
-curl "$PINCHTAB_BASE_URL/health"
-```
-
-## Profile Management (Dashboard Mode)
-
-When running `pinchtab dashboard`, profiles are managed via the dashboard API on port 9867.
-
-### List profiles
+# 1. Start Pinchtab (runs forever, local on :9867)
+pinchtab &
 
-```bash
-curl http://localhost:9867/profiles
+# 2. In your agent, follow this loop:
+#    a) Navigate to a URL
+#    b) Snapshot the page (get refs like e0, e5, e12)
+#    c) Act on a ref (click e5, type e12 "search text")
+#    d) Snapshot again to see the result
+#    e) Repeat step c-d until done
 ```
 
-Returns array of profiles with `id`, `name`, `accountEmail`, `useWhen`, etc.
+**That's it.** Refs are stable—you don't need to re-snapshot before every action. Only snapshot when the page changes significantly.
 
-### Start a profile by ID
+### Recommended Secure Setup
 
 ```bash
-# Auto-allocate port (recommended)
-curl -X POST http://localhost:9867/profiles/278be873adeb/start
-
-# With specific port and headless mode
-curl -X POST http://localhost:9867/profiles/278be873adeb/start \
-  -H 'Content-Type: application/json' \
-  -d '{"port": "9868", "headless": true}'
-
-# Short alias (same behavior)
-curl -X POST http://localhost:9867/start/278be873adeb
+# Best practice for AI agents
+BRIDGE_BIND=127.0.0.1 \
+BRIDGE_TOKEN="your-strong-secret" \
+BRIDGE_PROFILE=~/.pinchtab/automation-profile \
+pinchtab &
 ```
 
-Returns the instance info including the allocated `port`. Use that port for all subsequent API calls (navigate, snapshot, action, etc.).
+**Never expose to 0.0.0.0 without a token. Never point at your daily Chrome profile.**
 
-### Stop a profile by ID
+## Setup
 
 ```bash
-curl -X POST http://localhost:9867/profiles/278be873adeb/stop
-
-# Short alias
-curl -X POST http://localhost:9867/stop/278be873adeb
-```
-
-### Check profile instance status
+# Headless (default) — no visible window
+pinchtab &
 
-```bash
-# By profile ID (recommended)
-curl http://localhost:9867/profiles/278be873adeb/instance
+# Headed — visible Chrome window for human debugging
+BRIDGE_HEADLESS=false pinchtab &
 
-# By profile name (also works)
-curl http://localhost:9867/profiles/Pinchtab%20org/instance
-```
+# With auth token
+BRIDGE_TOKEN="your-secret-token" pinchtab &
 
-### Launch by name (dashboard style)
+# Custom port
+BRIDGE_PORT=8080 pinchtab &
 
-```bash
-curl -X POST http://localhost:9867/instances/launch \
-  -H 'Content-Type: application/json' \
-  -d '{"name": "work", "port": "9868"}'
+# Dashboard/orchestrator — profile manager + tab launcher
+pinchtab dashboard &
 ```
 
-### Typical agent flow with profiles
+Default: **port 9867**, no auth required (local). Set `BRIDGE_TOKEN` for remote access.
 
-```bash
-# 1. List profiles to find the right one
-PROFILES=$(curl -s http://localhost:9867/profiles)
-# Pick the profile ID you need (12-char hex, e.g. "278be873adeb")
-
-# 2. Start the profile (auto-allocates port)
-INSTANCE=$(curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/start)
-PORT=$(echo $INSTANCE | jq -r .port)
+For advanced setup, see [references/profiles.md](references/profiles.md) and [references/env.md](references/env.md).
 
-# 3. Use the instance (all API calls go to the instance port)
-curl -X POST http://localhost:$PORT/navigate -H 'Content-Type: application/json' \
-  -d '{"url": "https://mail.google.com"}'
-curl http://localhost:$PORT/snapshot?maxTokens=4000
+## What a Snapshot Looks Like
 
-# 4. Check instance status
-curl http://localhost:9867/profiles/$PROFILE_ID/instance
+After calling `/snapshot`, you get the page's accessibility tree as JSON—flat list of elements with refs:
 
-# 5. Stop when done
-curl -s -X POST http://localhost:9867/profiles/$PROFILE_ID/stop
+```json
+{
+  "refs": [
+    {"id": "e0", "role": "link", "text": "Sign In", "selector": "a[href='/login']"},
+    {"id": "e1", "role": "textbox", "label": "Email", "selector": "input[name='email']"},
+    {"id": "e2", "role": "button", "text": "Submit", "selector": "button[type='submit']"}
+  ],
+  "text": "... readable text version of page ...",
+  "title": "Login Page"
+}
 ```
 
-### Profile IDs
-
-Each profile gets a stable 12-char hex ID (SHA-256 of name, truncated) stored in `profile.json`. The ID is generated at creation time and never changes. Use IDs instead of names in automation — they're URL-safe and stable.
+Then you act on refs: `click e0`, `type e1 "user@example.com"`, `press e2 Enter`.
 
 ## Core Workflow
 
@@ -243,268 +109,22 @@ The typical agent loop:
 
 Refs (e.g. `e0`, `e5`, `e12`) are cached per tab after each snapshot — no need to re-snapshot before every action unless the page changed significantly.
 
-## API Reference
-
-### Navigate
-
-```bash
-curl -X POST http://localhost:9867/navigate \
-  -H 'Content-Type: application/json' \
-  -d '{"url": "https://example.com"}'
-
-# With options: custom timeout, block images, open in new tab
-curl -X POST http://localhost:9867/navigate \
-  -H 'Content-Type: application/json' \
-  -d '{"url": "https://example.com", "timeout": 60, "blockImages": true, "newTab": true}'
-```
-
-### Snapshot (accessibility tree)
-
-```bash
-# Full tree
-curl http://localhost:9867/snapshot
-
-# Interactive elements only (buttons, links, inputs) — much smaller
-curl "http://localhost:9867/snapshot?filter=interactive"
-
-# Limit depth
-curl "http://localhost:9867/snapshot?depth=5"
-
-# Smart diff — only changes since last snapshot (massive token savings)
-curl "http://localhost:9867/snapshot?diff=true"
-
-# Text format — indented tree, ~40-60% fewer tokens than JSON
-curl "http://localhost:9867/snapshot?format=text"
-
-# Compact format — one-line-per-node, 56-64% fewer tokens than JSON (recommended)
-curl "http://localhost:9867/snapshot?format=compact"
-
-# YAML format
-curl "http://localhost:9867/snapshot?format=yaml"
-
-# Scope to CSS selector (e.g. main content only)
-curl "http://localhost:9867/snapshot?selector=main"
-
-# Truncate to ~N tokens
-curl "http://localhost:9867/snapshot?maxTokens=2000"
-
-# Combine for maximum efficiency
-curl "http://localhost:9867/snapshot?format=compact&selector=main&maxTokens=2000&filter=interactive"
-
-# Disable animations before capture
-curl "http://localhost:9867/snapshot?noAnimations=true"
-
-# Write to file
-curl "http://localhost:9867/snapshot?output=file&path=/tmp/snapshot.json"
-```
-
-Returns flat JSON array of nodes with `ref`, `role`, `name`, `depth`, `value`, `nodeId`.
-
-**Token optimization**: Use `?format=compact` for best token efficiency. Add `?filter=interactive` for action-oriented tasks (~75% fewer nodes). Use `?selector=main` to scope to relevant content. Use `?maxTokens=2000` to cap output. Use `?diff=true` on multi-step workflows to see only changes. Combine all params freely.
-
-### Act on elements
+### Quick examples
 
 ```bash
-# Click by ref
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "click", "ref": "e5"}'
-
-# Type into focused element (click first, then type)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "click", "ref": "e12"}'
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "type", "ref": "e12", "text": "hello world"}'
-
-# Press a key
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "press", "key": "Enter"}'
-
-# Focus an element
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "focus", "ref": "e3"}'
-
-# Fill (set value directly, no keystrokes)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "fill", "selector": "#email", "text": "user@example.com"}'
-
-# Hover (trigger dropdowns/tooltips)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "hover", "ref": "e8"}'
-
-# Select dropdown option (by value or visible text)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "select", "ref": "e10", "value": "option2"}'
-
-# Scroll to element
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "scroll", "ref": "e20"}'
-
-# Scroll by pixels (infinite scroll pages)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "scroll", "scrollY": 800}'
-
-# Click and wait for navigation (link clicks)
-curl -X POST http://localhost:9867/action \
-  -H 'Content-Type: application/json' \
-  -d '{"kind": "click", "ref": "e5", "waitNav": true}'
+pinchtab nav https://example.com
+pinchtab snap -i -c                    # interactive + compact
+pinchtab click e5
+pinchtab type e12 hello world
+pinchtab press Enter
+pinchtab text                          # readable text (~1K tokens)
+pinchtab text | jq .text               # pipe to jq
+pinchtab ss -o page.jpg                # screenshot
+pinchtab eval "document.title"         # run JavaScript
+pinchtab pdf -o page.pdf               # export PDF
 ```
 
-### Extract text
-
-```bash
-# Readability mode (default) — strips nav/footer/ads, keeps article/main content
-curl http://localhost:9867/text
-
-# Raw innerText (old behavior)
-curl "http://localhost:9867/text?mode=raw"
-```
-
-Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).
-
-### Download files
-
-```bash
-# Download using browser session (preserves cookies, auth, stealth)
-# Returns base64 JSON by default
-curl "http://localhost:9867/download?url=https://site.com/report.pdf"
-
-# Raw bytes (pipe to file)
-curl "http://localhost:9867/download?url=https://site.com/image.jpg&raw=true" -o image.jpg
-
-# Save directly to disk
-curl "http://localhost:9867/download?url=https://site.com/export.csv&output=file&path=/tmp/export.csv"
-```
-
-Key use case: downloading files from authenticated sites — the browser's cookies and stealth settings are used automatically. No need to extract cookies and use curl separately.
-
-### Upload files
-
-```bash
-# Upload a local file to a file input
-curl -X POST "http://localhost:9867/upload?tabId=TAB_ID" \
-  -H "Content-Type: application/json" \
-  -d '{"selector": "input[type=file]", "paths": ["/tmp/photo.jpg"]}'
-
-# Upload base64-encoded data
-curl -X POST "http://localhost:9867/upload" \
-  -H "Content-Type: application/json" \
-  -d '{"selector": "#avatar-input", "files": ["data:image/png;base64,iVBOR..."]}'
-
-# Combine both — local files + base64
-curl -X POST "http://localhost:9867/upload" \
-  -H "Content-Type: application/json" \
-  -d '{"selector": "input[type=file]", "paths": ["/tmp/doc.pdf"], "files": ["data:image/png;base64,..."]}'
-```
-
-Sets files on `<input type=file>` elements via CDP. The browser fires `change` events as if the user picked files. Selector defaults to `input[type=file]` if omitted. Supports base64 data URLs, raw base64 strings, and local file paths.
-
-### Screenshot
-
-```bash
-# Raw JPEG bytes
-curl "http://localhost:9867/screenshot?raw=true" -o screenshot.jpg
-
-# With quality setting (default 80)
-curl "http://localhost:9867/screenshot?raw=true&quality=50" -o screenshot.jpg
-```
-
-### Evaluate JavaScript
-
-```bash
-curl -X POST http://localhost:9867/evaluate \
-  -H 'Content-Type: application/json' \
-  -d '{"expression": "document.title"}'
-```
-
-### Tab management
-
-```bash
-# List tabs
-curl http://localhost:9867/tabs
-
-# Open new tab
-curl -X POST http://localhost:9867/tab \
-  -H 'Content-Type: application/json' \
-  -d '{"action": "new", "url": "https://example.com"}'
-
-# Close tab
-curl -X POST http://localhost:9867/tab \
-  -H 'Content-Type: application/json' \
-  -d '{"action": "close", "tabId": "TARGET_ID"}'
-```
-
-Multi-tab: pass `?tabId=TARGET_ID` to snapshot/screenshot/text, or `"tabId"` in POST body.
-
-### Tab locking (multi-agent)
-
-```bash
-# Lock a tab (default 30s timeout, max 5min)
-curl -X POST http://localhost:9867/tab/lock \
-  -H 'Content-Type: application/json' \
-  -d '{"tabId": "TARGET_ID", "owner": "agent-1", "timeoutSec": 60}'
-
-# Unlock
-curl -X POST http://localhost:9867/tab/unlock \
-  -H 'Content-Type: application/json' \
-  -d '{"tabId": "TARGET_ID", "owner": "agent-1"}'
-```
-
-Locked tabs show `owner` and `lockedUntil` in `/tabs`. Returns 409 on conflict.
-
-### Batch actions
-
-```bash
-# Execute multiple actions in sequence
-curl -X POST http://localhost:9867/actions \
-  -H 'Content-Type: application/json' \
-  -d '{"actions":[{"kind":"click","ref":"e3"},{"kind":"type","ref":"e3","text":"hello"},{"kind":"press","key":"Enter"}]}'
-
-# Stop on first error (default: false, continues through all)
-curl -X POST http://localhost:9867/actions \
-  -H 'Content-Type: application/json' \
-  -d '{"tabId":"TARGET_ID","actions":[...],"stopOnError":true}'
-```
-
-### Cookies
-
-```bash
-# Get cookies for current page
-curl http://localhost:9867/cookies
-
-# Set cookies
-curl -X POST http://localhost:9867/cookies \
-  -H 'Content-Type: application/json' \
-  -d '{"url":"https://example.com","cookies":[{"name":"session","value":"abc123"}]}'
-```
-
-### Stealth
-
-```bash
-# Check stealth status and score
-curl http://localhost:9867/stealth/status
-
-# Rotate browser fingerprint
-curl -X POST http://localhost:9867/fingerprint/rotate \
-  -H 'Content-Type: application/json' \
-  -d '{"os":"windows"}'
-# os: "windows", "mac", or omit for random
-```
-
-### Health check
-
-```bash
-curl http://localhost:9867/health
-```
+For the full HTTP API (curl examples, download, upload, cookies, stealth, batch actions, PDF export with full parameter control), see [references/api.md](references/api.md).
 
 ## Token Cost Guide
 
@@ -513,58 +133,41 @@ curl http://localhost:9867/health
 | `/text` | ~800 | Reading page content |
 | `/snapshot?filter=interactive` | ~3,600 | Finding buttons/links to click |
 | `/snapshot?diff=true` | varies | Multi-step workflows (only changes) |
-| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best token efficiency |
-| `/snapshot?format=text` | ~40-60% less | Indented tree, cheaper than JSON |
+| `/snapshot?format=compact` | ~56-64% less | One-line-per-node, best efficiency |
 | `/snapshot` | ~10,500 | Full page understanding |
 | `/screenshot` | ~2K (vision) | Visual verification |
+| `/pdf` | 0 (binary) | Export page as PDF (no token cost) |
 
-**Strategy**: Start with `/snapshot?filter=interactive`. Use `?diff=true` on subsequent snapshots in multi-step tasks. Use `/text` when you only need the readable content. Use `?format=text` to cut token costs further. Use full `/snapshot` only for complete page understanding.
+**Strategy**: Start with `?filter=interactive&format=compact`. Use `?diff=true` on subsequent snapshots. Use `/text` when you only need readable content. Full `/snapshot` only when needed.
 
-## Environment Variables
+## Agent Optimization
 
-### Core runtime
+**Validated Feb 2026**: Testing with AI agents revealed a critical pattern for reliable, token-efficient scraping.
 
-| Var | Default | Description |
-|---|---|---|
-| `BRIDGE_BIND` | `127.0.0.1` | Bind address — localhost only by default. Set `0.0.0.0` for network access |
-| `BRIDGE_PORT` | `9867` | HTTP port |
-| `BRIDGE_HEADLESS` | `true` | Run Chrome headless |
-| `BRIDGE_TOKEN` | (none) | Bearer auth token (recommended when using `BRIDGE_BIND=0.0.0.0`) |
-| `BRIDGE_PROFILE` | `~/.pinchtab/chrome-profile` | Chrome profile dir |
-| `BRIDGE_STATE_DIR` | `~/.pinchtab` | State/session storage |
-| `BRIDGE_NO_RESTORE` | `false` | Skip tab restore on startup |
-| `BRIDGE_STEALTH` | `light` | Stealth level: `light` or `full` |
-| `BRIDGE_MAX_TABS` | `20` | Max open tabs (0 = unlimited) |
-| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading |
-| `BRIDGE_BLOCK_MEDIA` | `false` | Block all media (images + fonts + CSS + video) |
-| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions |
-| `BRIDGE_TIMEZONE` | (none) | Force browser timezone (IANA tz) |
-| `BRIDGE_CHROME_VERSION` | `144.0.7559.133` | Chrome version string used by fingerprint rotation |
-| `CHROME_BINARY` | (auto) | Path to Chrome/Chromium binary |
-| `CHROME_FLAGS` | (none) | Extra Chrome flags (space-separated) |
-| `BRIDGE_CONFIG` | `~/.pinchtab/config.json` | Path to config JSON file |
-| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |
-| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |
-| `CDP_URL` | (none) | Connect to existing Chrome DevTools |
-| `BRIDGE_NO_DASHBOARD` | `false` | Disable dashboard/orchestrator endpoints on instance processes |
-
-### Dashboard mode (`pinchtab dashboard`)
-
-| Var | Default | Description |
-|---|---|---|
-| `PINCHTAB_AUTO_LAUNCH` | `false` | Auto-launch a default profile at dashboard startup |
-| `PINCHTAB_DEFAULT_PROFILE` | `default` | Profile name for auto-launch |
-| `PINCHTAB_DEFAULT_PORT` | `9867` | Port for auto-launched profile |
-| `PINCHTAB_HEADED` | (unset) | If set, auto-launched profile is headed; unset means headless |
-| `PINCHTAB_DASHBOARD_URL` | `http://localhost:$BRIDGE_PORT` | CLI helper base URL for `pinchtab connect` |
+**See the full guide:** [docs/agent-optimization.md](../../docs/agent-optimization.md)
+
+### Quick Summary
+
+**The 3-second pattern** — wait after navigate before snapshot:
+
+```bash
+curl -X POST http://localhost:9867/navigate \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}' && \
+sleep 3 && \
+curl http://localhost:9867/snapshot | jq '.nodes[] | select(.name | length > 15) | .name'
+```
+
+**Token savings:** 93% reduction (3,842 → 272 tokens) when using prescriptive instructions vs. exploratory agent approach.
+
+For detailed findings, system prompt templates, and site-specific notes, see [docs/agent-optimization.md](../../docs/agent-optimization.md).
 
 ## Tips
 
-- **Always pass `tabId` explicitly** when working with multiple tabs — active tab tracking can be unreliable
+- **Always pass `tabId` explicitly** when working with multiple tabs
 - Refs are stable between snapshot and actions — no need to re-snapshot before clicking
-- After navigation or major page changes, take a new snapshot to get fresh refs
-- Use `filter=interactive` by default, fall back to full snapshot when needed
+- After navigation or major page changes, take a new snapshot for fresh refs
 - Pinchtab persists sessions — tabs survive restarts (disable with `BRIDGE_NO_RESTORE=true`)
 - Chrome profile is persistent — cookies/logins carry over between runs
-- Chrome uses its native User-Agent by default — `BRIDGE_CHROME_VERSION` only affects fingerprint rotation
-- Use `BRIDGE_BLOCK_IMAGES=true` or `"blockImages": true` on navigate for read-heavy tasks — reduces bandwidth and memory
+- Use `BRIDGE_BLOCK_IMAGES=true` or `"blockImages": true` on navigate for read-heavy tasks
+- **Wait 3+ seconds after navigate before snapshot** — Chrome needs time to render 2000+ accessibility tree nodes