Skip to content

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

docs: comprehensive overview and getting started guides

Mario8be35a66d321
diff --git a/docs/get-started.md b/docs/get-started.md
index e69de29b..cd810d2b 100644
--- a/docs/get-started.md
+++ b/docs/get-started.md
@@ -0,0 +1,666 @@
+# Getting Started with Pinchtab
+
+Get Pinchtab running in 5 minutes, from zero to browser automation.
+
+---
+
+## Installation (Choose One)
+
+### Option 1: One-Liner (Recommended)
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://pinchtab.com/install.sh | bash
+```
+
+Then verify:
+```bash
+pinchtab --version
+```
+
+### Option 2: npm
+
+**Requires:** Node.js 18+
+
+```bash
+npm install -g pinchtab
+pinchtab --version
+```
+
+**Troubleshooting npm:**
+```bash
+# If "command not found", add npm to PATH
+export PATH="$(npm config get prefix)/bin:$PATH"
+# Add to ~/.bashrc or ~/.zshrc to persist
+```
+
+### Option 3: Docker
+
+**Requires:** Docker
+
+```bash
+docker run -d -p 9867:9867 pinchtab/pinchtab
+curl http://localhost:9867/health
+```
+
+### Option 4: Build from Source
+
+**Requires:** Go 1.25+, Git, Chrome/Chromium
+
+```bash
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+go build -o pinchtab ./cmd/pinchtab
+./pinchtab --version
+```
+
+**[Full build guide →](architecture/building.md)**
+
+---
+
+## Quick Start (5 Minutes)
+
+### Step 1: Start the Server
+
+**Terminal 1:**
+```bash
+pinchtab
+```
+
+**Expected output:**
+```
+🦀 PINCH! PINCH! port=9867 cdp= stealth=light
+auth disabled (set BRIDGE_TOKEN to enable)
+startup configuration bind=127.0.0.1 port=9867 headless=true ...
+```
+
+The server is running on `http://127.0.0.1:9867`.
+
+### Step 2: Run Your First Command
+
+**Terminal 2:**
+```bash
+pinchtab quick https://example.com
+```
+
+**What happens:**
+1. Navigates to the URL
+2. Shows page structure
+3. Lists interactive elements
+4. Suggests next actions
+
+**Output:**
+```
+🦀 Navigating to https://example.com ...
+
+📋 Page structure:
+[accessibility tree...]
+
+📌 Title: Example Domain
+🔗 URL: https://example.com/
+
+💡 Quick actions:
+ pinchtab click <ref> # Click an element
+ pinchtab type <ref> <text> # Type into input
+ pinchtab screenshot # Take a screenshot
+ pinchtab pdf -o output.pdf # Save as PDF
+```
+
+✅ **You're running Pinchtab!**
+
+---
+
+## Common First Commands
+
+### Get Page Content
+
+```bash
+# Read the page as text
+pinchtab text
+
+# See interactive elements
+pinchtab snap -i -c
+
+# Get raw HTML content
+pinchtab text --raw
+```
+
+### Take a Screenshot
+
+```bash
+pinchtab screenshot -o page.jpg
+pinchtab screenshot -o page.jpg -q 75 # Lower quality
+```
+
+### Export as PDF
+
+```bash
+pinchtab pdf -o output.pdf
+pinchtab pdf -o report.pdf --landscape
+```
+
+### Interact with the Page
+
+```bash
+# First, get interactive elements
+pinchtab snap -i -c
+
+# Then click one (replace 'e5' with a real ref)
+pinchtab click e5
+
+# Verify the change
+pinchtab snap -i -c
+
+# Or fill a form
+pinchtab fill e3 "[email protected]"
+pinchtab fill e5 "password"
+pinchtab click e7 # Submit button
+```
+
+### Multiple Tabs
+
+```bash
+# Open second tab
+pinchtab tabs new https://github.com
+
+# List all tabs
+pinchtab tabs
+
+# Get snapshot from specific tab (replace tabId)
+pinchtab snap --tab abc123def456
+```
+
+---
+
+## Understanding the Workflow
+
+### Key Concept: Tab-Centric
+
+Pinchtab is **tab-centric**, not URL-centric:
+
+```
+❌ WRONG: pinchtab snap https://example.com
+✅ CORRECT:
+ 1. pinchtab nav https://example.com (uses current tab)
+ 2. pinchtab snap (snapshots current tab)
+```
+
+**Why?** Because a tab has state (cookies, history, focus, loaded content). Multiple tabs can exist. You need to specify which tab to work with.
+
+### Typical Workflow
+
+```
+1. Navigate to a page
+ pinchtab nav https://example.com
+
+2. Get page structure
+ pinchtab snap -i -c # See buttons, links, inputs
+
+3. Interact with page
+ pinchtab click e5 # Click element
+ pinchtab type e3 "text" # Type text
+
+4. Verify changes
+ pinchtab snap -i -c # Check new state
+
+5. Capture result
+ pinchtab screenshot # Take screenshot
+ pinchtab pdf -o out.pdf # Export PDF
+```
+
+---
+
+## Using with curl (HTTP API)
+
+You don't need the CLI. Pinchtab is HTTP:
+
+```bash
+# Health check
+curl http://localhost:9867/health
+
+# Navigate (returns tabId)
+curl -X POST http://localhost:9867/tab \
+ -H "Content-Type: application/json" \
+ -d '{"action":"new","url":"https://example.com"}'
+
+# Get snapshot
+curl "http://localhost:9867/snapshot?tabId=abc123"
+
+# Extract text
+curl "http://localhost:9867/text?tabId=abc123"
+```
+
+**Full API reference** → [curl-commands.md](references/curl-commands.md)
+
+---
+
+## Using with Python
+
+```python
+import requests
+import json
+
+BASE = "http://localhost:9867"
+
+# Create tab + navigate
+resp = requests.post(f"{BASE}/tab", json={
+ "action": "new",
+ "url": "https://example.com"
+})
+tab_id = resp.json()["tabId"]
+
+# Get snapshot
+snapshot = requests.get(f"{BASE}/snapshot", params={
+ "tabId": tab_id,
+ "filter": "interactive"
+}).json()
+
+# Print interactive elements
+for elem in snapshot["elements"]:
+ print(f"{elem['ref']}: {elem['role']} - {elem['name']}")
+
+# Click an element
+requests.post(f"{BASE}/action", json={
+ "kind": "click",
+ "ref": "e5",
+ "tabId": tab_id
+})
+```
+
+---
+
+## Using with Node.js
+
+```javascript
+const fetch = require('node-fetch');
+
+const BASE = "http://localhost:9867";
+
+async function main() {
+ // Create tab
+ const navResp = await fetch(`${BASE}/tab`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ action: "new",
+ url: "https://example.com"
+ })
+ });
+ const nav = await navResp.json();
+ const tabId = nav.tabId;
+
+ // Get snapshot
+ const snapResp = await fetch(
+ `${BASE}/snapshot?tabId=${tabId}&filter=interactive`
+ );
+ const snap = await snapResp.json();
+
+ // Click element
+ await fetch(`${BASE}/action`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ kind: "click",
+ ref: "e5",
+ tabId: tabId
+ })
+ });
+}
+
+main();
+```
+
+---
+
+## Configuration
+
+### Basic Configuration
+
+```bash
+# Custom port
+BRIDGE_PORT=9868 pinchtab
+
+# Visible window
+BRIDGE_HEADLESS=false pinchtab
+
+# Stealth mode (bypass bot detection)
+BRIDGE_STEALTH=full pinchtab
+
+# Block ads
+BRIDGE_BLOCK_ADS=true pinchtab
+
+# Custom Chrome
+CHROME_BINARY=/usr/bin/google-chrome pinchtab
+```
+
+### Combined
+
+```bash
+BRIDGE_PORT=9868 \
+BRIDGE_STEALTH=full \
+BRIDGE_BLOCK_ADS=true \
+BRIDGE_HEADLESS=false \
+pinchtab
+```
+
+**[Full configuration →](architecture/pinchtab-architecture.md)**
+
+---
+
+## Common Scenarios
+
+### Scenario 1: Scrape a Website
+
+```bash
+# Navigate
+pinchtab nav https://example.com/article
+
+# Extract readable text
+pinchtab text > article.txt
+
+# Or with curl
+curl http://localhost:9867/text > article.json
+jq '.text' article.json
+```
+
+### Scenario 2: Fill a Form
+
+```bash
+# Navigate to form
+pinchtab nav https://example.com/contact
+
+# Get interactive elements
+pinchtab snap -i -c
+
+# Fill form fields (use refs from snapshot)
+pinchtab fill e3 "John Doe"
+pinchtab fill e5 "[email protected]"
+pinchtab fill e7 "My message here"
+
+# Click submit
+pinchtab click e10
+
+# Verify success
+pinchtab snap
+```
+
+### Scenario 3: Login + Stay Logged In
+
+```bash
+# Login
+pinchtab nav https://example.com/login
+pinchtab fill e3 "[email protected]"
+pinchtab fill e5 "password"
+pinchtab click e7
+
+# Later, even after restarting Pinchtab, you're still logged in
+pkill pinchtab
+sleep 2
+pinchtab &
+
+# Tab and session restored
+pinchtab nav https://example.com/dashboard
+pinchtab snap # Already authenticated
+```
+
+### Scenario 4: Generate PDF Report
+
+```bash
+# Navigate to report page
+pinchtab nav https://reports.example.com/monthly
+
+# Export as PDF with header/footer
+pinchtab pdf -o report.pdf \
+ --landscape \
+ --display-header-footer \
+ --header-template "<div>Monthly Report</div>" \
+ --footer-template "<div>Page <span class='pageNumber'></span></div>"
+```
+
+### Scenario 5: Multi-Tab Workflow
+
+```bash
+# Open first tab
+pinchtab nav https://source.example.com
+SOURCE_TAB=$(pinchtab tabs | jq -r '.[0].id')
+
+# Open second tab
+pinchtab tabs new https://destination.example.com
+DEST_TAB=$(pinchtab tabs | jq -r '.[1].id')
+
+# Extract from source
+DATA=$(curl "http://localhost:9867/text?tabId=$SOURCE_TAB")
+
+# Fill in destination
+curl -X POST http://localhost:9867/action \
+ -d "{\"kind\":\"fill\",\"ref\":\"e3\",\"text\":\"$DATA\",\"tabId\":\"$DEST_TAB\"}"
+```
+
+---
+
+## Troubleshooting
+
+### "connection refused" / "Cannot connect"
+
+**Problem:** Server not running
+
+**Solution:**
+```bash
+# Terminal 1: Start server
+pinchtab
+
+# Terminal 2: Use client (once server is running)
+pinchtab snap
+```
+
+### "Port already in use"
+
+**Problem:** Port 9867 is taken
+
+**Solution:**
+```bash
+# Use different port
+BRIDGE_PORT=9868 pinchtab
+
+# Or kill the process using 9867
+lsof -i :9867
+kill -9 <PID>
+```
+
+### "Chrome not found"
+
+**Problem:** Chrome/Chromium not installed
+
+**Solution:**
+```bash
+# macOS
+brew install chromium
+
+# Linux (Ubuntu/Debian)
+sudo apt install chromium-browser
+
+# Or specify custom Chrome
+CHROME_BINARY=/path/to/chrome pinchtab
+```
+
+### "Empty snapshot / about:blank"
+
+**Problem:** Tab not navigated yet
+
+**Solution:**
+```bash
+# Always navigate first
+pinchtab nav https://example.com
+
+# Then snapshot
+pinchtab snap
+```
+
+### "ref e5 not found"
+
+**Problem:** Ref changed (page updated)
+
+**Solution:**
+```bash
+# Get fresh snapshot
+pinchtab snap -i -c
+
+# Use new refs from this snapshot
+pinchtab click <new-ref>
+```
+
+---
+
+## Next Steps
+
+### 1. Try Some Workflows
+→ [Practical examples & workflows](showcase.md)
+
+### 2. Learn the CLI
+→ [CLI commands reference](references/cli-commands.md)
+
+### 3. Use the HTTP API
+→ [API reference with curl examples](references/curl-commands.md)
+
+### 4. Advanced Usage
+→ [API workflows & patterns](showcase.md)
+
+### 5. Production Deployment
+→ [Docker deployment guide](guides/docker.md)
+
+### 6. Understand the Architecture
+→ [How Pinchtab works](architecture/pinchtab-architecture.md)
+
+---
+
+## Common Features
+
+### Extract Text Efficiently
+
+```bash
+# Readable text (strips ads, nav)
+pinchtab text # 800 tokens
+
+# Raw text (full page)
+pinchtab text --raw # ~1,500 tokens
+
+# Filter by selector
+pinchtab snap -s "main" # Only <main> element
+
+# Limit tokens
+pinchtab snap --max-tokens 1000
+```
+
+### Interact Precisely
+
+```bash
+# Get clickable elements only
+pinchtab snap -i
+
+# Click by ref
+pinchtab click e5
+
+# Type text
+pinchtab type e3 "hello"
+
+# Press keys
+pinchtab press Enter
+pinchtab press Tab
+pinchtab press Escape
+
+# Focus element
+pinchtab focus e5
+
+# Hover over element
+pinchtab hover e5
+
+# Select dropdown
+pinchtab select e8 "Option 2"
+```
+
+### Run JavaScript
+
+```bash
+# Get page title
+curl -X POST http://localhost:9867/execute \
+ -d '{"expression":"document.title"}'
+
+# Count links
+curl -X POST http://localhost:9867/execute \
+ -d '{"expression":"document.querySelectorAll(\"a\").length"}'
+
+# Complex logic
+curl -X POST http://localhost:9867/execute \
+ -d '{"expression":"JSON.stringify({title: document.title, url: location.href})"}'
+```
+
+---
+
+## Performance Tips
+
+### Token Efficiency
+
+```bash
+# Use text, not screenshot
+pinchtab text # 800 tokens
+pinchtab screenshot # 10,000+ tokens
+
+# Filter to interactive elements only
+pinchtab snap -i -c # ~1,000 tokens
+pinchtab snap # ~3,600 tokens
+
+# Limit by tokens
+pinchtab snap --max-tokens 1000
+```
+
+### Speed
+
+```bash
+# Parallel tabs for concurrent work
+pinchtab tabs new https://...
+pinchtab tabs new https://...
+# Process multiple tabs in parallel
+
+# Cache responses when possible
+# Snapshot once, extract refs, then interact
+pinchtab snap > snapshot.json
+# Use refs from snapshot.json multiple times
+```
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Start server | `pinchtab` |
+| Health check | `curl http://localhost:9867/health` |
+| Navigate | `pinchtab nav https://...` |
+| See structure | `pinchtab snap -i -c` |
+| Get text | `pinchtab text` |
+| Click element | `pinchtab click e5` |
+| Type text | `pinchtab type e3 "hello"` |
+| Screenshot | `pinchtab screenshot -o page.jpg` |
+| PDF export | `pinchtab pdf -o out.pdf` |
+| List tabs | `pinchtab tabs` |
+| New tab | `pinchtab tabs new https://...` |
+| Show help | `pinchtab help` |
+
+---
+
+## Getting Help
+
+- **Issues** → [GitHub Issues](https://github.com/pinchtab/pinchtab/issues)
+- **Q&A** → [GitHub Discussions](https://github.com/pinchtab/pinchtab/discussions)
+- **Docs** → [Full documentation](overview.md)
+
+---
+
+## What's Next?
+
+1. ✅ You've installed and run Pinchtab
+2. 📚 Learn more → [Full documentation](overview.md)
+3. 🎯 Try workflows → [Practical examples](showcase.md)
+4. 🔧 Go deeper → [Architecture docs](architecture/)
+
+**Happy automating!** 🦀
diff --git a/docs/overview.md b/docs/overview.md
index e69de29b..2d1aa8ea 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -0,0 +1,363 @@
+# Pinchtab Documentation
+
+Welcome to Pinchtab — browser control for AI agents, scripts, and automation workflows.
+
+## What is Pinchtab?
+
+Pinchtab is a **standalone HTTP server** that gives you direct control over a Chrome browser. Instead of being locked into a specific agent framework, you can interact with it from anywhere — any AI agent, any programming language, or even `curl`.
+
+```bash
+# It's just HTTP. Use it anywhere.
+curl http://localhost:9867/health
+curl http://localhost:9867/text?tabId=abc123
+curl -X POST http://localhost:9867/action -d '{"kind":"click","ref":"e5"}'
+```
+
+---
+
+## Why Pinchtab?
+
+### The Problem
+
+Most browser automation tools are **framework-locked**:
+- OpenClaw Browser → only works in OpenClaw
+- Playwright MCP → only works with your MCP client
+- Browser Use → only works in its own system
+
+You can't use the same browser automation across different agents.
+
+### The Solution
+
+Pinchtab is **framework-agnostic HTTP server**:
+- ✅ Works with any AI agent (Claude, ChatGPT, local models)
+- ✅ Works with any language (bash, Python, Node.js, Go)
+- ✅ Works with any tool (curl, Postman, your own scripts)
+- ✅ Persistent sessions (log in once, stays logged in)
+- ✅ Stealth mode (bypass bot detection)
+- ✅ Token efficient (5-13x cheaper than alternatives)
+
+---
+
+## Key Features
+
+### 🌲 Accessibility Tree
+Structured tree with stable refs (e0, e1...) for click, type, and read. Deterministic — no coordinate guessing.
+
+### 🎯 Smart Filters
+`?filter=interactive` returns only buttons, links, and inputs. Fewer tokens per snapshot.
+
+### 🕵️ Stealth Mode
+Patches `navigator.webdriver`, spoofs UA, and hides automation flags to pass major bot checks.
+
+### 💾 Persistent Sessions
+Cookies, auth, and tabs survive restarts. Log in once and keep the session alive.
+
+### 📝 Text Extraction
+Readability mode strips nav and ads. Raw mode keeps full text for parser workflows.
+
+### 🖱️ Direct Actions
+Click, type, fill, press, focus, hover, select, and scroll by ref or selector.
+
+### ⚡ JS Evaluation
+Escape hatch for any workflow gap. Execute JavaScript in any tab on demand.
+
+### 📸 Screenshots
+JPEG output with quality control for visual verification and downstream auditing.
+
+### 📄 PDF Export
+Export full pages as PDF for sharing, archiving, and offline review.
+
+### 🎭 Multi-Tab Support
+Create, switch, and close tabs. Work with multiple pages simultaneously.
+
+---
+
+## Quick Comparison
+
+| Feature | Pinchtab | OpenClaw Browser | Playwright | Selenium |
+|---------|----------|------------------|-----------|----------|
+| **Interface** | HTTP (any agent) | Framework-locked | Framework-locked | WebDriver |
+| **Tokens/page** | ~800 (text) | ~10,000+ | N/A | N/A |
+| **Stealth mode** | ✅ | ❌ | ❌ | ❌ |
+| **Persistent sessions** | ✅ | ❌ | ❌ | ❌ |
+| **Self-contained binary** | ✅ 12MB | ❌ | ❌ | ❌ |
+| **Accessibility tree** | ✅ | ✅ | ❌ | ❌ |
+| **PDF export** | ✅ | ❌ | ✅ | ❌ |
+| **Tab-centric design** | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Real Performance Numbers
+
+### Token Efficiency
+
+```
+Reading a 1,500-word article:
+ Pinchtab /text: 800-900 tokens (5-13x cheaper)
+ OpenClaw snapshot: ~3,600 tokens
+ Full screenshot: ~10,000 tokens
+ Vision + screenshot: ~20,000 tokens
+```
+
+### Response Times
+
+```
+Navigate + snapshot: 1-3 seconds
+Click + verify: 200-500ms
+Text extraction: 100-300ms
+PDF generation: 2-5 seconds
+```
+
+### Binary Size
+
+```
+Pinchtab: 12MB (includes Chrome)
+Node.js equivalent: 100MB+
+Python equivalent: 200MB+
+```
+
+---
+
+## Architecture
+
+### High-Level Design
+
+```
+┌─────────────────────────────────────────┐
+│ Your Tool/Agent │
+│ (curl, Python, Node.js, etc.) │
+└──────────────┬──────────────────────────┘
+ │
+ │ HTTP
+ ↓
+┌─────────────────────────────────────────┐
+│ Pinchtab HTTP Server (Go) │
+│ ┌─────────────────────────────────┐ │
+│ │ Tab Manager (multi-tab) │ │
+│ │ ┌────────────┐ ┌────────────┐ │ │
+│ │ │ Tab 1 │ │ Tab 2 │ │ │
+│ │ │ DOM │ │ DOM │ │ │
+│ │ │ History │ │ History │ │ │
+│ │ └────────────┘ └────────────┘ │ │
+│ └─────────────────────────────────┘ │
+│ ┌─────────────────────────────────┐ │
+│ │ Chrome DevTools Protocol │ │
+│ │ (WebSocket to Chrome) │ │
+│ └─────────────────────────────────┘ │
+└──────────────┬──────────────────────────┘
+ │
+ │ CDP
+ ↓
+┌─────────────────────────────────────────┐
+│ Chrome Browser (Headless) │
+│ ┌────────────┐ ┌────────────┐ │
+│ │ Tab 1 │ │ Tab 2 │ │
+│ │ (website) │ │ (website) │ │
+│ └────────────┘ └────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+### What Makes It Different
+
+1. **Tab-Centric** — Everything revolves around tabs, not URLs
+2. **Stateful** — Sessions persist between requests
+3. **Accessibility-First** — Uses accessibility tree, not coordinates
+4. **HTTP API** — Standard web interface, no proprietary protocols
+5. **Multi-Agent Safe** — Tab locking for agent coordination
+
+---
+
+## Getting Started
+
+### Installation (30 seconds)
+
+```bash
+# macOS / Linux
+curl -fsSL https://pinchtab.com/install.sh | bash
+
+# Or with npm
+npm install -g pinchtab
+
+# Or build from source
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+go build -o pinchtab ./cmd/pinchtab
+```
+
+### First Steps
+
+```bash
+# Terminal 1: Start the server
+pinchtab
+
+# Terminal 2: Try a command
+curl http://localhost:9867/health # Health check
+pinchtab quick https://example.com # Quick start
+pinchtab snap -i -c # Get interactive elements
+```
+
+### Next
+
+- **Quick Start Guide** → [get-started.md](get-started.md)
+- **CLI Commands** → [references/cli-commands.md](references/cli-commands.md)
+- **API Reference** → [references/curl-commands.md](references/curl-commands.md)
+- **Practical Examples** → [showcase.md](showcase.md)
+- **Architecture Deep-Dive** → [architecture/pinchtab-architecture.md](architecture/pinchtab-architecture.md)
+
+---
+
+## Use Cases
+
+### 1. AI Agent Automation
+Any AI agent (Claude, ChatGPT, Anthropic models) can control browsers:
+```bash
+# Agent uses Pinchtab to fill forms, navigate, extract data
+pinchtab nav https://example.com
+pinchtab snap -i -c # Get interactive elements
+pinchtab click e5 # Agent decides based on snapshot
+```
+
+### 2. Data Scraping
+Extract text from complex websites:
+```bash
+pinchtab nav https://example.com/article
+pinchtab text # 800 tokens instead of 10,000 with vision
+```
+
+### 3. Testing & QA
+End-to-end testing with persistence:
+```bash
+# Login once
+pinchtab nav https://myapp.com/login
+pinchtab fill e3 username
+pinchtab fill e5 password
+pinchtab click e7 # Submit
+
+# Subsequent tests reuse the session
+pinchtab nav https://myapp.com/dashboard
+pinchtab snap # Already logged in
+```
+
+### 4. Report Generation
+Create PDFs from web pages:
+```bash
+pinchtab nav https://analytics.example.com/report
+pinchtab pdf -o report.pdf --landscape --displayHeaderFooter
+```
+
+### 5. Bot Detection Bypass
+Stealth mode fools modern bot detection:
+```bash
+BRIDGE_STEALTH=full pinchtab
+pinchtab nav https://protected-site.com # Bypasses detection
+```
+
+---
+
+## Documentation Structure
+
+```
+docs/
+├── overview.md (you are here)
+├── get-started.md ← Start here for quick setup
+├── showcase.md ← Practical examples
+├── architecture/ ← How it works inside
+│ ├── pinchtab-architecture.md
+│ ├── chrome-lifecycle-and-orchestration.md
+│ └── building.md
+├── guides/ ← How-to guides
+│ ├── docker.md
+│ ├── headed-mode-guide.md
+│ ├── cdp-url-shared-chrome.md
+│ └── identifying-instances.md
+├── references/ ← API documentation
+│ ├── cli-commands.md
+│ └── curl-commands.md
+└── extras/ ← Background reading
+ ├── pinchtab-clean-slate.md
+ ├── agent-optimization.md
+ └── browser-extraction-spectrum.md
+```
+
+---
+
+## Support & Community
+
+- **GitHub Issues** — https://github.com/pinchtab/pinchtab/issues
+- **Discussions** — https://github.com/pinchtab/pinchtab/discussions
+- **Twitter/X** — [@pinchtabdev](https://x.com/pinchtabdev)
+
+---
+
+## Core Concepts (Brief)
+
+### Tab-Centric Design
+Every operation works on a tab, not a URL. Create a tab first, then use its `tabId`:
+
+```bash
+# Create tab + navigate → returns tabId
+curl -X POST http://localhost:9867/tab \
+ -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'
+# "abc123"
+
+# Use tabId for all operations
+curl "http://localhost:9867/snapshot?tabId=abc123"
+curl "http://localhost:9867/text?tabId=abc123"
+curl -X POST http://localhost:9867/action \
+ -d '{"kind":"click","ref":"e5","tabId":"abc123"}'
+```
+
+### Refs Instead of Coordinates
+The accessibility tree gives you stable refs (e0, e1, e2...) instead of pixel coordinates:
+
+```json
+{
+ "elements": [
+ {"ref": "e0", "role": "heading", "name": "Title"},
+ {"ref": "e5", "role": "button", "name": "Click Me"},
+ {"ref": "e8", "role": "link", "name": "Learn More"}
+ ]
+}
+```
+
+Then interact by ref:
+```bash
+curl -X POST http://localhost:9867/action \
+ -d '{"kind":"click","ref":"e5"}'
+```
+
+### Persistent Sessions
+Tabs and cookies survive restarts:
+
+```bash
+# Login in one session
+pinchtab nav https://example.com/login
+pinchtab fill e3 [email protected]
+pinchtab fill e5 password
+pinchtab click e7
+
+# Restart Pinchtab, tab is still there + still logged in
+pkill pinchtab
+./pinchtab
+# Tab is restored, cookies intact
+```
+
+---
+
+## Next Steps
+
+1. **Install:** Follow [get-started.md](get-started.md)
+2. **Try it:** Run the quick start examples
+3. **Learn:** Read [showcase.md](showcase.md) for workflows
+4. **Build:** Check [architecture/](architecture/) for how it works
+5. **Deploy:** See [guides/](guides/) for production setups
+
+---
+
+## License
+
+Apache 2.0 — Free and open source.
+
+---
+
+**Ready?** → [Get Started](get-started.md)