Skip to content

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

docs: add TODO and new API structure reference

Mariobb1fe4cc959f
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 00000000..993c3d81
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,479 @@
+# PinchTab API Refactoring TODO
+
+## Overview
+
+Refactor from deeply nested instance-centric API to flatter, resource-centric API focused on **tabs** as the primary resource.
+
+**Current (nested):** `POST /instances/{id}/navigate` + `POST /instances/{id}/tab` + `POST /instances/{id}/action`
+**New (flat):** `POST /navigate {tabId, url}` + `POST /tabs/new {instanceId}` + `POST /action {tabId, ...}`
+
+---
+
+## New API Structure
+
+### Phase 1: Profile Management (Already ~complete)
+```
+GET /profiles List profiles
+POST /profiles Create profile
+GET /profiles/{id} Get profile
+DELETE /profiles/{id} Delete profile
+```
+
+### Phase 2: Instance Management (Simplify current)
+```
+GET /instances List running instances
+POST /instances/start Start instance with profile
+ {profile: "name", mode: "headed|headless", port: optional}
+ → {id: "inst_xyz", profileId, port, mode, status}
+
+POST /instances/{id}/stop Stop instance
+GET /instances/{id}/logs View instance logs
+```
+
+### Phase 3: Tab Management (NEW - Main focus)
+```
+POST /tabs/new Create new tab in instance
+ {instanceId: "inst_xyz", url: optional}
+ → {id: "tab_abc", instanceId, url, status}
+
+GET /tabs List all tabs (across all instances)
+GET /tabs?instanceId=... List tabs in specific instance
+GET /tabs/{id} Get tab info
+POST /tabs/{id}/close Close tab
+```
+
+### Phase 4: Tab Operations (Flatten from /instances/{id}/...)
+```
+POST /tabs/{id}/navigate Navigate tab
+ {url, timeout, blockImages, blockAds}
+
+GET /tabs/{id}/snapshot Get page structure
+ ?interactive, ?compact, ?depth, ?maxTokens
+
+GET /tabs/{id}/screenshot Screenshot
+ ?format=png|jpeg, ?quality=80
+
+POST /tabs/{id}/action Single action
+ {kind: "click"|"type"|"press"|"fill"|"hover"|"scroll"|"select"|"focus", ...}
+
+POST /tabs/{id}/actions Multiple actions
+ {actions: [{kind, ...}, ...]}
+
+GET /tabs/{id}/text Extract visible text
+POST /tabs/{id}/evaluate Run JavaScript
+ {expression, await}
+
+GET /tabs/{id}/pdf Export as PDF
+ ?landscape, ?margins, ?scale, ?pages
+
+POST /tabs/{id}/cookies Get/set cookies
+GET /tabs/{id}/cookies
+
+POST /tabs/{id}/lock Lock tab (exclusive access)
+ {owner: "agent-name", ttl: 60}
+
+POST /tabs/{id}/unlock Unlock tab
+ {owner: "agent-name"}
+
+GET /tabs/{id}/locks Check lock status
+POST /tabs/{id}/fingerprint/rotate Rotate fingerprint
+```
+
+---
+
+## Current Endpoints (To Deprecate/Refactor)
+
+### Instance-scoped endpoints (Remove after migration)
+```
+❌ POST /instances/{id}/navigate → POST /tabs/{id}/navigate
+❌ GET /instances/{id}/snapshot → GET /tabs/{id}/snapshot
+❌ GET /instances/{id}/screenshot → GET /tabs/{id}/screenshot
+❌ POST /instances/{id}/action → POST /tabs/{id}/action
+❌ POST /instances/{id}/actions → POST /tabs/{id}/actions
+❌ GET /instances/{id}/text → GET /tabs/{id}/text
+❌ POST /instances/{id}/evaluate → POST /tabs/{id}/evaluate
+❌ GET /instances/{id}/pdf → GET /tabs/{id}/pdf
+❌ POST /instances/{id}/tab → POST /tabs/new {instanceId}
+❌ GET /instances/{id}/tabs → GET /tabs?instanceId={id}
+❌ POST /instances/{id}/tab/lock → POST /tabs/{id}/lock
+❌ POST /instances/{id}/tab/unlock → POST /tabs/{id}/unlock
+❌ GET /instances/{id}/cookies → GET /tabs/{id}/cookies
+❌ POST /instances/{id}/cookies → POST /tabs/{id}/cookies
+❌ GET /instances/{id}/download → GET /tabs/{id}/download (future)
+❌ POST /instances/{id}/upload → POST /tabs/{id}/upload (future)
+❌ POST /instances/{id}/ensure-chrome (Keep for health check, but hidden)
+```
+
+### Old instance launch endpoint
+```
+❌ POST /instances/launch {name, headless, port}
+ → POST /instances/start {profile, mode, port}
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Add New Tab-focused Endpoints
+- [ ] Create `POST /tabs/new {instanceId, url}` handler
+ - Calls bridge.CreateTab(url)
+ - Returns tab info with ID
+ - Stores mapping of tabId → (instanceId, tabHandle)
+
+- [ ] Create `GET /tabs` handler (list all)
+ - Queries all instances for their tabs
+ - Returns flattened list with tabId, instanceId, url, title
+
+- [ ] Create `GET /tabs?instanceId=...` handler
+ - Filters to specific instance
+ - Reuses GetTabs logic
+
+- [ ] Create `GET /tabs/{id}` handler
+ - Returns single tab info
+
+- [ ] Create tab operation handlers (refactored from instance handlers)
+ - `/tabs/{id}/navigate` → Extract from `/instances/{id}/navigate`
+ - `/tabs/{id}/snapshot` → Extract from `/instances/{id}/snapshot`
+ - `/tabs/{id}/screenshot` → Extract from `/instances/{id}/screenshot`
+ - `/tabs/{id}/action` → Extract from `/instances/{id}/action`
+ - `/tabs/{id}/actions` → Extract from `/instances/{id}/actions`
+ - `/tabs/{id}/text` → Extract from `/instances/{id}/text`
+ - `/tabs/{id}/evaluate` → Extract from `/instances/{id}/evaluate`
+ - `/tabs/{id}/pdf` → Extract from `/instances/{id}/pdf`
+ - `/tabs/{id}/cookies` (GET/POST) → Extract from `/instances/{id}/cookies`
+ - `/tabs/{id}/lock` → Extract from `/instances/{id}/tab/lock`
+ - `/tabs/{id}/unlock` → Extract from `/instances/{id}/tab/unlock`
+
+### Phase 2: Add Tab ID Resolution Layer
+- [ ] Create `TabResolver` interface
+ - Method: `ResolveTab(tabId) → (instanceId, tabHandle, error)`
+ - Method: `ResolveInstance(tabId) → (instanceId, error)`
+
+- [ ] Add to orchestrator
+ - Maps tabId → instanceId globally
+ - Routes tab operations to correct instance
+
+- [ ] Update Bridge interface
+ - Add method: `TabByID(tabId) → (tab.Info, error)`
+
+### Phase 3: Refactor Handler Logic
+- [ ] Extract common logic from instance handlers
+ - TabResolver lookup
+ - Parameter passing to instance
+ - Response formatting
+
+- [ ] Create tab-specific handler package
+ - `handlers/tabs/navigate.go`
+ - `handlers/tabs/snapshot.go`
+ - `handlers/tabs/action.go`
+ - etc.
+
+- [ ] Update Handlers struct
+ - Add `TabResolver` field
+ - Keep Bridge for backward compat (bridge mode)
+
+### Phase 4: Deprecate Old Endpoints
+- [ ] Add deprecation warnings to old endpoints
+ - Log "DEPRECATED: Use /tabs/... instead"
+ - Return 307 Temporary Redirect or 308 Permanent Redirect
+
+- [ ] Keep old endpoints working
+ - Translate to new handlers internally
+ - `POST /instances/{id}/navigate` → calls `/tabs/{id}/navigate` internally
+
+- [ ] Document migration path
+ - Example: old curl → new curl
+
+### Phase 5: Update CLI Commands
+- [ ] Update CLI to use new endpoints
+ - `pinchtab nav <url>` → stays same (auto-detects tab)
+ - `pinchtab --instance <id> nav <url>` → `pinchtab --tab <id> nav <url>`
+ - `pinchtab snap` → `pinchtab --tab <id> snap`
+
+- [ ] Add `--tab` flag support
+ - Alternative to `--instance`
+ - Auto-detects instance from tab
+
+- [ ] Update docs/cli-*.md
+ - Reflect new structure
+
+### Phase 6: Update Documentation
+- [ ] Update API reference (docs/references/api-reference.json)
+ - Add all new endpoints
+ - Mark old endpoints as deprecated
+
+- [ ] Update architecture docs
+ - Explain tab-centric design
+ - Show tabId routing
+
+- [ ] Update get-started guide
+ - Profile → Instance → Tab workflow
+
+- [ ] Update examples
+ - Curl examples with new endpoints
+ - CLI examples
+
+---
+
+## Endpoint Mapping (Migration Guide)
+
+### Example: Click Element
+
+**Old (instance-centric):**
+```bash
+curl -X POST http://localhost:9867/instances/inst_abc123/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+
+**New (tab-centric):**
+```bash
+# First, get tab ID
+TAB=$(curl -s http://localhost:9867/tabs?instanceId=inst_abc123 | jq -r '.[0].id')
+
+# Then operate on tab
+curl -X POST http://localhost:9867/tabs/$TAB/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+
+Or just:
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz789/action \
+ -H "Content-Type: application/json" \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+
+**CLI (both work):**
+```bash
+# Old
+pinchtab --instance inst_abc123 click e5
+
+# New (cleaner - direct tab reference)
+pinchtab --tab tab_xyz789 click e5
+
+# Or still support old way internally
+pinchtab --instance inst_abc123 click e5 # Auto-detects default tab
+```
+
+---
+
+## Example: Full Workflow
+
+### New (Flat, Tab-centric)
+
+**Step 1: Create profile**
+```bash
+curl -X POST http://localhost:9867/profiles \
+ -d '{"name": "my-profile"}'
+# → {id: "prof_123", name: "my-profile"}
+```
+
+**Step 2: Start instance**
+```bash
+curl -X POST http://localhost:9867/instances/start \
+ -d '{"profile": "my-profile", "mode": "headed", "port": 9868}'
+# → {id: "inst_abc", profileId: "prof_123", port: 9868, status: "running"}
+```
+
+**Step 3: Create tab**
+```bash
+curl -X POST http://localhost:9867/tabs/new \
+ -d '{"instanceId": "inst_abc"}'
+# → {id: "tab_xyz", instanceId: "inst_abc", status: "ready"}
+```
+
+**Step 4: Navigate (direct to tab)**
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz/navigate \
+ -d '{"url": "https://example.com"}'
+```
+
+**Step 5: Get page structure**
+```bash
+curl -s http://localhost:9867/tabs/tab_xyz/snapshot?interactive=true | jq .
+```
+
+**Step 6: Click element**
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz/action \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+
+**Step 7: Extract text**
+```bash
+curl -s http://localhost:9867/tabs/tab_xyz/text | jq .
+```
+
+**Step 8: Close tab**
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz/close
+```
+
+**Step 9: Stop instance**
+```bash
+curl -X POST http://localhost:9867/instances/inst_abc/stop
+```
+
+---
+
+## Benefits of New Structure
+
+| Aspect | Old (Nested) | New (Flat) |
+|--------|--------------|-----------|
+| **Focus** | Instance-centric | Tab-centric |
+| **Main resource** | Instance ID | Tab ID |
+| **URL depth** | 3-4 levels | 2 levels |
+| **Parameter passing** | Via path segments | Via body/query |
+| **Scaling** | Hard (more nesting) | Easy (flat) |
+| **Tab switching** | Change instance | Change tab |
+| **Multi-tab workflows** | Complex (one instance) | Simple (many tabs) |
+| **CLI complexity** | `--instance --tab` flags | Just `--tab` flag |
+| **HTTP cacheability** | Low (deep paths) | Higher (flat paths) |
+
+---
+
+## Code Structure Changes
+
+### Current
+```
+handlers/
+ handlers.go (bridge-only, ~30 handlers)
+ - HandleNavigate
+ - HandleSnapshot
+ - HandleAction
+ - HandleTab
+ - HandleTabs
+ - etc.
+
+orchestrator/
+ handlers.go (~40 endpoints routed to instances)
+ - handleLaunchByName
+ - handleStopByInstanceID
+ - handleNavigate (proxies to /instances/{id}/navigate)
+ - etc.
+```
+
+### New
+```
+handlers/
+ handlers.go (bridge-only, ~30 handlers) [UNCHANGED]
+ tabs/
+ resolver.go (tab ID → instance mapping)
+ navigate.go (POST /tabs/{id}/navigate)
+ snapshot.go (GET /tabs/{id}/snapshot)
+ action.go (POST /tabs/{id}/action)
+ actions.go (POST /tabs/{id}/actions)
+ text.go (GET /tabs/{id}/text)
+ evaluate.go (POST /tabs/{id}/evaluate)
+ pdf.go (GET /tabs/{id}/pdf)
+ screenshot.go (GET /tabs/{id}/screenshot)
+ cookies.go (GET/POST /tabs/{id}/cookies)
+ lock.go (POST /tabs/{id}/lock)
+ unlock.go (POST /tabs/{id}/unlock)
+
+orchestrator/
+ handlers.go (refactored)
+ - handleListTabs
+ - handleNewTab
+ - handleCloseTab
+ - [Proxy to handlers/tabs/]
+
+ tabs/
+ handler.go (routes to handlers/tabs/*)
+ resolver.go (tab ID lookup)
+```
+
+---
+
+## Migration Path
+
+### For Users
+1. **No breaking changes initially** — Old endpoints still work
+2. **Gradual migration** — Update to new endpoints at own pace
+3. **CLI stays compatible** — `pinchtab --instance` still works
+
+### For Maintainers
+1. **Phase 1-3** — Add new endpoints alongside old
+2. **Phase 4** — Mark old as deprecated (deprecation headers)
+3. **Phase 5-6** — Update CLI & docs to prefer new
+4. **Maintenance window** — After N months, remove old endpoints
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- [ ] Tab resolver tests
+ - Resolve valid tabId → instanceId
+ - Handle invalid tabId
+ - Handle cross-instance tab access
+
+- [ ] Tab operation tests
+ - Navigate to URL
+ - Get snapshot
+ - Execute actions
+ - Lock/unlock
+
+### Integration Tests
+- [ ] Full workflow (profile → instance → tab → actions)
+- [ ] Multi-tab scenario
+- [ ] Tab lifecycle (create, use, close)
+- [ ] Cross-instance tab access (should fail appropriately)
+
+### Backward compat tests
+- [ ] Old endpoints still work
+- [ ] Old endpoints return deprecation headers
+- [ ] CLI with `--instance` flag still works
+
+---
+
+## Effort Estimation
+
+| Phase | Task | Effort | Days |
+|-------|------|--------|------|
+| 1 | Add new tab endpoints | Medium | 2-3 |
+| 2 | Tab resolver layer | Medium | 1-2 |
+| 3 | Refactor handlers | Medium | 2-3 |
+| 4 | Deprecation + compat | Small | 1 |
+| 5 | Update CLI | Medium | 1-2 |
+| 6 | Update docs | Small | 1 |
+| | **Tests & QA** | Medium | 2-3 |
+| | **TOTAL** | | ~11-17 days |
+
+---
+
+## Success Criteria
+
+- [x] All new endpoints documented and in API reference
+- [x] CLI commands work with `--tab` flag
+- [x] Old endpoints still work (deprecated)
+- [x] Documentation updated
+- [x] Examples updated
+- [x] All tests passing
+- [x] No breaking changes for users
+
+---
+
+## Related Files to Update
+
+1. **Endpoint docs**
+ - [ ] docs/references/api-reference.json (add 15+ new endpoints)
+ - [ ] docs/references/cli-design.md (update patterns)
+ - [ ] docs/references/cli-implementation.md (update code examples)
+ - [ ] docs/references/cli-quick-reference.md (update curl examples)
+
+2. **Code**
+ - [ ] internal/handlers/handlers.go (add tab operation handlers to bridge)
+ - [ ] internal/orchestrator/handlers.go (add tab endpoints + routing)
+ - [ ] cmd/pinchtab/cmd_cli.go (add --tab support)
+ - [ ] internal/bridge/bridge.go (add TabByID method if needed)
+
+3. **Tests**
+ - [ ] internal/handlers/*_test.go (add tab tests)
+ - [ ] internal/orchestrator/*_test.go (add tab routing tests)
+ - [ ] tests/integration/*_test.go (add workflow tests)
+
+4. **Architecture docs**
+ - [ ] docs/architecture/architecture-overview.md (explain tab-centric model)
+ - [ ] docs/core-concepts.md (update concepts with tabs as primary resource)
diff --git a/docs/references/api-structure-new.md b/docs/references/api-structure-new.md
new file mode 100644
index 00000000..82978e81
--- /dev/null
+++ b/docs/references/api-structure-new.md
@@ -0,0 +1,425 @@
+# PinchTab API Structure: New (Tab-centric)
+
+## Simplified, Flat API Focused on Tabs as Primary Resource
+
+### Resource Hierarchy
+
+```
+Profile
+ ↓ (create instance with profile)
+Instance (orchestrator resource)
+ ↓ (create tab in instance)
+Tab (primary resource - where all work happens)
+ ├─ Navigate
+ ├─ Snapshot
+ ├─ Action / Actions
+ ├─ Text
+ ├─ Evaluate
+ ├─ Screenshot
+ ├─ PDF
+ ├─ Cookies
+ ├─ Lock / Unlock
+ └─ Close
+```
+
+---
+
+## Complete Endpoint List
+
+### Profile Management
+| Method | Path | Payload | Response | Purpose |
+|--------|------|---------|----------|---------|
+| GET | `/profiles` | - | `[{id, name, createdAt, usedAt}]` | List profiles |
+| POST | `/profiles` | `{name}` | `{id, name, createdAt}` | Create profile |
+| GET | `/profiles/{id}` | - | `{id, name, createdAt, usedAt}` | Get profile info |
+| DELETE | `/profiles/{id}` | - | `{id, deleted: true}` | Delete profile |
+
+### Instance Management
+| Method | Path | Payload | Response | Purpose |
+|--------|------|---------|----------|---------|
+| GET | `/instances` | - | `[{id, profileId, port, mode, status, startTime}]` | List instances |
+| POST | `/instances/start` | `{profile, mode?, port?}` | `{id, profileId, port, mode, status}` | Start instance |
+| POST | `/instances/{id}/stop` | - | `{id, stopped: true}` | Stop instance |
+| GET | `/instances/{id}/logs` | - | `text` | Get instance logs |
+
+### Tab Management (NEW)
+| Method | Path | Payload | Response | Purpose |
+|--------|------|---------|----------|---------|
+| POST | `/tabs/new` | `{instanceId, url?}` | `{id, instanceId, url?, status}` | Create tab |
+| GET | `/tabs` | - | `[{id, instanceId, url, title, type}]` | List all tabs |
+| GET | `/tabs?instanceId={id}` | - | `[{id, instanceId, url, title}]` | List instance tabs |
+| GET | `/tabs/{id}` | - | `{id, instanceId, url, title, type, status}` | Get tab info |
+| POST | `/tabs/{id}/close` | - | `{id, closed: true}` | Close tab |
+
+### Tab Operations (NEW - Replaces /instances/{id}/...)
+| Method | Path | Query/Body | Response | Purpose |
+|--------|------|-----------|----------|---------|
+| **Navigate** |
+| POST | `/tabs/{id}/navigate` | `{url, timeout?, blockImages?, blockAds?}` | `{url, status, title}` | Navigate to URL |
+| **Snapshot** |
+| GET | `/tabs/{id}/snapshot` | `?interactive&compact&depth=3&maxTokens=2000` | `{elements: [], tree: ...}` | Page structure |
+| **Action** |
+| POST | `/tabs/{id}/action` | `{kind, ref?, text?, key?, value?, ...}` | `{kind, result?, error?}` | Single action |
+| POST | `/tabs/{id}/actions` | `{actions: [{kind, ...}, ...]}` | `{results: [...]}` | Multiple actions |
+| **Text & Evaluation** |
+| GET | `/tabs/{id}/text` | `?raw` | `{text: "...", elements: [...]}` | Extract text |
+| POST | `/tabs/{id}/evaluate` | `{expression, await?}` | `{result: any, type: string}` | Run JS |
+| **Media** |
+| GET | `/tabs/{id}/screenshot` | `?format=png&quality=80` | `binary (PNG/JPEG)` | Screenshot |
+| GET | `/tabs/{id}/pdf` | `?landscape&margins=0.5&scale=1.0&pages=1-3` | `binary (PDF)` | PDF export |
+| **Cookies** |
+| GET | `/tabs/{id}/cookies` | - | `[{name, value, domain, ...}]` | Get cookies |
+| POST | `/tabs/{id}/cookies` | `{action: "set"|"delete", cookies: [...]}` | `{set: [...], deleted: [...]}` | Manage cookies |
+| **Locking** |
+| POST | `/tabs/{id}/lock` | `{owner: string, ttl: number}` | `{locked: true, owner, expiresAt}` | Lock tab |
+| POST | `/tabs/{id}/unlock` | `{owner: string}` | `{unlocked: true}` | Unlock tab |
+| GET | `/tabs/{id}/locks` | - | `{locked: bool, owner?, expiresAt?}` | Check lock |
+| **Fingerprinting** |
+| POST | `/tabs/{id}/fingerprint/rotate` | - | `{rotated: true, userAgent, ...}` | Rotate fingerprint |
+| GET | `/tabs/{id}/fingerprint/status` | - | `{stealth: "light"|"full", ua, ...}` | Get fingerprint |
+
+---
+
+## Comparison: Old vs New
+
+### Example 1: Click Element
+
+**OLD (instance-scoped):**
+```bash
+curl -X POST http://localhost:9867/instances/inst_abc123/action \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+- Requires instance ID
+- Path has 3 segments
+
+**NEW (tab-scoped):**
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz789/action \
+ -d '{"kind": "click", "ref": "e5"}'
+```
+- Requires tab ID (which identifies instance)
+- Path has 2 segments
+- Cleaner for multi-tab workflows
+
+---
+
+### Example 2: Navigate to URL
+
+**OLD:**
+```bash
+curl -X POST http://localhost:9867/instances/inst_abc123/navigate \
+ -d '{"url": "https://example.com"}'
+```
+
+**NEW:**
+```bash
+curl -X POST http://localhost:9867/tabs/tab_xyz789/navigate \
+ -d '{"url": "https://example.com"}'
+```
+
+---
+
+### Example 3: Create Tab
+
+**OLD:**
+```bash
+curl -X POST http://localhost:9867/instances/inst_abc123/tab \
+ -d '{}'
+# Response: {id: "tab_xyz", ...}
+```
+
+**NEW:**
+```bash
+curl -X POST http://localhost:9867/tabs/new \
+ -d '{"instanceId": "inst_abc123"}'
+# Response: {id: "tab_xyz", ...}
+```
+
+---
+
+### Example 4: List tabs
+
+**OLD:**
+```bash
+curl http://localhost:9867/instances/inst_abc123/tabs
+# Returns just tabs from that instance
+```
+
+**NEW:**
+```bash
+# All tabs (across instances)
+curl http://localhost:9867/tabs
+
+# Specific instance
+curl http://localhost:9867/tabs?instanceId=inst_abc123
+```
+
+---
+
+## Query Parameters vs Body
+
+### Query Parameters (GET)
+```bash
+# Snapshot with options
+curl 'http://localhost:9867/tabs/tab_xyz/snapshot?interactive&compact&depth=2&maxTokens=2000'
+
+# Screenshot with format
+curl 'http://localhost:9867/tabs/tab_xyz/screenshot?format=jpeg&quality=85'
+
+# List with filter
+curl 'http://localhost:9867/tabs?instanceId=inst_abc123'
+```
+
+### Body (POST)
+```bash
+# Navigate with options
+curl -X POST http://localhost:9867/tabs/tab_xyz/navigate \
+ -d '{
+ "url": "https://example.com",
+ "timeout": 30,
+ "blockImages": true,
+ "blockAds": false
+ }'
+
+# Action (already body-based)
+curl -X POST http://localhost:9867/tabs/tab_xyz/action \
+ -d '{
+ "kind": "click",
+ "ref": "e5",
+ "timeout": 5
+ }'
+```
+
+---
+
+## HTTP Status Codes
+
+| Code | Meaning | Example |
+|------|---------|---------|
+| **200** | Success (GET/action) | Snapshot returned, action completed |
+| **201** | Created | Tab created, instance started |
+| **204** | No content | Close successful |
+| **400** | Bad request | Invalid action kind, malformed JSON |
+| **404** | Not found | Tab ID doesn't exist, instance stopped |
+| **409** | Conflict | Tab locked by another agent, port in use |
+| **500** | Server error | Chrome crashed, internal error |
+| **503** | Unavailable | Chrome not initialized, instance starting |
+
+---
+
+## Response Format
+
+### Success Response
+```json
+{
+ "kind": "action",
+ "result": {
+ "text": "Element text",
+ "visible": true,
+ "rect": {...}
+ }
+}
+```
+
+### Error Response
+```json
+{
+ "error": "tab not found",
+ "code": "ERR_TAB_NOT_FOUND",
+ "statusCode": 404
+}
+```
+
+### Snapshot Response
+```json
+{
+ "elements": [
+ {
+ "ref": "e1",
+ "tag": "button",
+ "text": "Click me",
+ "interactive": true,
+ "rect": {"x": 100, "y": 50, "w": 80, "h": 30}
+ }
+ ],
+ "tree": {...},
+ "meta": {"count": 45, "interactive": 12}
+}
+```
+
+---
+
+## CLI Command Mapping
+
+### Profile Management
+```bash
+# List
+pinchtab profiles
+
+# Create
+pinchtab profile create my-profile
+
+# Delete
+pinchtab profile delete my-profile
+```
+
+### Instance Management
+```bash
+# List
+pinchtab instances
+
+# Start
+pinchtab instance start --profile my-profile --mode headed --port 9868
+
+# Stop
+pinchtab instance stop inst_abc123
+
+# Logs
+pinchtab instance logs inst_abc123
+```
+
+### Tab Management
+```bash
+# List all tabs
+pinchtab tabs
+
+# List instance tabs
+pinchtab --instance inst_abc123 tabs
+
+# Create tab
+pinchtab --instance inst_abc123 tab new https://example.com
+# → tab_xyz789
+
+# Close tab
+pinchtab --tab tab_xyz789 close
+```
+
+### Tab Operations
+```bash
+# Navigate
+pinchtab --tab tab_xyz789 nav https://example.com
+
+# Snapshot
+pinchtab --tab tab_xyz789 snap -i -c
+
+# Click
+pinchtab --tab tab_xyz789 click e5
+
+# Get text
+pinchtab --tab tab_xyz789 text
+
+# Run action
+cat << 'EOF' | pinchtab --tab tab_xyz789 action
+{
+ "kind": "actions",
+ "actions": [
+ {"kind": "click", "ref": "e1"},
+ {"kind": "type", "ref": "e2", "text": "search"},
+ {"kind": "press", "key": "Enter"}
+ ]
+}
+EOF
+
+# Lock tab (exclusive access)
+pinchtab --tab tab_xyz789 lock --owner my-agent --ttl 60
+
+# Unlock
+pinchtab --tab tab_xyz789 unlock --owner my-agent
+```
+
+---
+
+## Full Workflow Example
+
+### Setup
+```bash
+# 1. Create profile
+PROF=$(pinchtab profile create my-app | jq -r .id)
+
+# 2. Start instance
+INST=$(pinchtab instance start --profile my-app --mode headed | jq -r .id)
+
+# 3. Create tab
+TAB=$(pinchtab --instance $INST tab new | jq -r .id)
+```
+
+### Work
+```bash
+# 4. Navigate
+pinchtab --tab $TAB nav https://example.com
+
+# 5. Get page structure
+pinchtab --tab $TAB snap -i -c | jq .
+
+# 6. Interact
+pinchtab --tab $TAB click e5
+pinchtab --tab $TAB type e12 "search text"
+pinchtab --tab $TAB press Enter
+
+# 7. Check result
+pinchtab --tab $TAB snap -d | jq .
+
+# 8. Extract data
+pinchtab --tab $TAB text
+```
+
+### Cleanup
+```bash
+# 9. Close tab (optional, instance cleanup closes all)
+pinchtab --tab $TAB close
+
+# 10. Stop instance
+pinchtab instance stop $INST
+```
+
+---
+
+## Data Flow
+
+### Request Path
+```
+CLI Command
+ ↓
+HTTP Request (curl or SDK)
+ ↓
+Orchestrator Server (9867)
+ ↓
+Tab Resolver (tab ID → instance ID)
+ ↓
+Route to Instance (HTTP call to 9868+)
+ ↓
+Bridge Server
+ ↓
+Chrome (DevTools Protocol)
+```
+
+### Response Path
+```
+Chrome responds
+ ↓
+Bridge returns JSON
+ ↓
+Instance Server returns JSON
+ ↓
+Orchestrator aggregates/proxies
+ ↓
+CLI/SDK receives JSON
+```
+
+---
+
+## Deprecation Timeline
+
+### Phase 1 (Now - v1.0)
+- New tab endpoints available
+- Old instance endpoints still work
+- Deprecation headers on old endpoints
+
+### Phase 2 (v1.1)
+- CLI prefers `--tab` over `--instance`
+- Documentation focuses on new API
+- Users migrated gradually
+
+### Phase 3 (v2.0)
+- Old instance endpoints removed
+- Only tab-centric API