Skip to content

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

docs: reorganizing the docs

Luigi Agostiea6182977b5b
diff --git a/README.md b/README.md
index 169c96d0..b47c201f 100644
--- a/README.md
+++ b/README.md
@@ -598,37 +598,6 @@ When you log into sites through Pinchtab's Chrome window, those sessions — coo
Think of Pinchtab like giving someone your unlocked laptop. Powerful if you trust them. Dangerous if you don't.
-## Contributors
-
-### Humans
-
-<a href="https://github.com/luigi-agosti">
- <img src="https://github.com/luigi-agosti.png" width="60" style="border-radius:50%" alt="Luigi Agosti"/><br/>
- <sub><b>Luigi Agosti</b> · Agent Manager</sub>
-</a>
-
-### Agents
-
-| | |
-|:---:|:---:|
-| <img src="assets/bosch-avatar.png" width="48"/> | <img src="assets/mario-avatar.png" width="48"/> |
-| **Bosch** | **Mario** |
-| Debugging the simulation 🔮 | First principles · ships fast |
-
-## Works with OpenClaw
+## Works with any agent
Pinchtab is built to work seamlessly with [OpenClaw](https://openclaw.ai) — the open-source personal AI assistant. Use Pinchtab as your agent's browser backend for faster, cheaper web automation.
-
-<p align="right">
- <img src="assets/pinchtab-openclaw.png" alt="Pinchtab + OpenClaw" height="140"/>
-</p>
-
-## Star History
-
-<a href="https://star-history.com/#pinchtab/pinchtab&Date">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=pinchtab/pinchtab&type=Date&theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=pinchtab/pinchtab&type=Date" />
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=pinchtab/pinchtab&type=Date" />
- </picture>
-</a>
diff --git a/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md b/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md
deleted file mode 100644
index 692971b8..00000000
--- a/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md
+++ /dev/null
@@ -1,293 +0,0 @@
-# Pinchtab API Misuse: Root Cause Analysis & Solutions
-
-**Date:** February 27, 2026
-**Summary:** Misunderstood Pinchtab API design led to silent failures. Root cause: inadequate documentation of API dependencies and workflows.
-
----
-
-## The Problem
-
-### What I Did Wrong
-```bash
-curl 'http://localhost:9867/snapshot?url=https://www.bbc.com&format=text'
- ↑
- This parameter doesn't exist!
-```
-
-### What Happened
-- Endpoint exists: `/snapshot` ✓
-- Parameter exists: `?format=text` ✓
-- Parameter `?url=...` does NOT exist ✗
-- API returned 200 OK (not an error!)
-- But with no tabId → defaulted to current tab (blank)
-- Result: `about:blank` response (silent failure)
-
-### Why It Was Confusing
-I didn't get an error. The API returned valid JSON:
-```json
-{
- "title": "",
- "url": "about:blank"
-}
-```
-
-This looked like Pinchtab was broken, not like I was using the API wrong.
-
----
-
-## Root Cause: Documentation Gaps
-
-### Problem 1: API Reference Assumes Too Much Context
-
-**File:** `skill/pinchtab/references/api.md`
-
-**Current documentation:**
-```bash
-# Snapshot (accessibility tree)
-curl /snapshot
-
-# Interactive elements only
-curl "/snapshot?filter=interactive"
-
-# Limit depth
-curl "/snapshot?depth=5"
-```
-
-**Why it's misleading:**
-- Shows isolated examples without dependencies
-- Doesn't mention `?tabId=...` (required parameter!)
-- No examples using `?tabId=X`
-- Implies you can just call `/snapshot` and get page content
-- Agent's mental model: "snapshot is like web_fetch, takes a URL"
-
-**Missing context:**
-- You CANNOT: `curl /snapshot?url=https://...`
-- You MUST: `curl /snapshot?tabId=<ID>&url=...` (and tabId comes from elsewhere)
-- Where does tabId come from? → Not explained in this section
-
----
-
-### Problem 2: Tab Management Section Exists But Isn't Connected
-
-**File:** `skill/pinchtab/references/api.md` (later in the document)
-
-**Current documentation:**
-```bash
-# Tab management
-curl /tabs
-
-# Open new tab
-curl -X POST /tab -H 'Content-Type: application/json' \
- -d '{"action": "new", "url": "https://example.com"}'
-
-# Close tab
-curl -X POST /tab -H 'Content-Type: application/json' \
- -d '{"action": "close", "tabId": "TARGET_ID"}'
-```
-
-**Problem:**
-- Shows how to CREATE a tab and get `tabId`
-- But `/snapshot` section (earlier) doesn't reference this
-- No explicit: "After creating a tab, use this tabId with /snapshot"
-- Two sections that need each other aren't connected
-
----
-
-### Problem 3: SKILL.md Conceptual But Not Practical
-
-**File:** `skill/pinchtab/SKILL.md`
-
-**Current documentation:**
-```markdown
-# Core Workflow: Actual API Calls
-
-The typical agent loop:
-
-1. **Navigate** to a URL
-2. **Snapshot** the accessibility tree (get refs)
-3. **Act** on refs (click, type, press)
-```
-
-**Problem:**
-- "Navigate to a URL" — but which endpoint?
- - `/navigate` (POST) — navigates current tab
- - `/tab {"action":"new","url":"..."}` (POST) — creates new tab
- - Documentation doesn't clarify the difference!
-- "Snapshot the accessibility tree" — assumes you already know you need a tabId
-- Missing the `→ curl` examples that show actual sequencing
-
----
-
-## The Correct API Flow
-
-### Step-by-Step (What Actually Works)
-
-```bash
-# ✅ STEP 1: Create tab + navigate (returns tabId)
-curl -X POST http://localhost:9867/tab \
- -H "Content-Type: application/json" \
- -d '{"action":"new","url":"https://www.bbc.com","timeout":10}'
-
-# Response:
-# {
-# "tabId": "7A2578741782B5C085640C984F511358",
-# "title": "BBC - Home",
-# "url": "https://www.bbc.co.uk/"
-# }
-
-# ✅ STEP 2: Use tabId to get snapshot
-curl "http://localhost:9867/snapshot?tabId=7A2578741782B5C085640C984F511358&format=text&maxTokens=2000"
-
-# Response:
-# # BBC - Home
-# # https://www.bbc.co.uk/
-# # 149 nodes
-#
-# e0 RootWebArea "BBC - Home" [focused]
-# e1 banner
-# e2 main
-# ... (semantic accessibility tree with clickable refs)
-```
-
-### Why This Design?
-
-Pinchtab is **tab-centric**, not URL-centric:
-- `/snapshot` operates on a tab, not a URL
-- Multiple tabs can exist simultaneously
-- Each tab has its own state, navigation history, cookies
-- Need to specify WHICH tab you're working with → `?tabId=X`
-
-This is correct design (matches CDP/browser model), but the documentation doesn't explain the "why".
-
----
-
-## Solutions Implemented
-
-### 1. **New Wrapper Script: `scripts/pinchtab-curl-wrapper.sh`**
-
-Hides complexity behind simple commands:
-```bash
-# Instead of:
-# Step 1: Create tab, extract tabId
-# Step 2: Call /snapshot with tabId
-# Step 3: Parse JSON, act on result
-
-# Just use:
-./pinchtab-curl-wrapper.sh text https://www.bbc.com
-./pinchtab-curl-wrapper.sh snapshot https://www.bbc.com compact
-./pinchtab-curl-wrapper.sh click https://www.bbc.com e5
-```
-
-**What it does:**
-- Handles tab creation internally
-- Manages tabId flow
-- Provides clean CLI
-- Error handling
-- Color output
-
----
-
-### 2. **Updated Documentation**
-
-#### In `pinchtab-clean-slate.md`
-- Added "Validation Method" section explaining API flow
-- Included sample response showing structure
-- Clarified why Pinchtab returns refs (e0, e1...) not just text
-- Provided working curl examples
-
-#### In PR Description
-- "Root Cause Analysis" section
-- Actual curl examples
-- Explanation of why it failed
-
-#### Recommendations for Future Docs
-1. Add **"Workflow Examples"** section BEFORE API reference
-2. Show complete end-to-end examples:
- ```markdown
- ### Example 1: Extract Text from a URL
- - Use: /tab to create tab
- - Then: /text to extract
-
- ### Example 2: Get Refs and Click Elements
- - Use: /tab to create tab
- - Then: /snapshot to get refs (e0, e1...)
- - Then: /action to click a ref
- - Then: /snapshot again to see result
- ```
-
-3. Add "Why This Design?" sections explaining:
- - Why /snapshot needs tabId (tab-centric, not URL-centric)
- - How it differs from web_fetch or OpenClaw (which are stateless)
- - When to use /navigate vs /tab?action=new
-
----
-
-## Lessons Learned
-
-### For API Design
-- **Document the dependencies**, not just the endpoints
-- **Show complete workflows** in addition to isolated commands
-- **Explain the "why"** — why is it tab-centric? Why not just pass URL?
-- **Connect related sections** (Tab Management + Snapshot)
-
-### For API Usage
-- **Read the entire reference**, not just the section you think you need
-- **Look for examples showing sequencing** (step 1, step 2, step 3)
-- **Try the wrapper/CLI first** before raw HTTP if it exists
-- **Debug silently by checking assumptions** — "is my tabId valid?" not "is the API broken?"
-
-### For Documentation
-- **Isolate reference docs** (api.md) from **practical guides** (getting-started.md)
-- **Use workflow diagrams** showing dependencies
-- **Include "common mistakes"** section
-
----
-
-## Real Data: Pinchtab is Excellent
-
-Once you use it correctly:
-
-| Metric | Value |
-|--------|-------|
-| Response size | 7.3-7.7 KB |
-| Tokens per page | 1,834-1,934 |
-| Includes JavaScript rendering | ✓ |
-| Returns clickable refs | ✓ (e0, e1, e2...) |
-| vs OpenClaw snapshot | 27x lighter |
-| vs web_fetch | 3.1-3.6x lighter |
-
-The API is well-designed. The documentation just needs a getting-started section.
-
----
-
-## Files Included
-
-- `API-MISUSE-ROOT-CAUSE-ANALYSIS.md` (this file)
-- `scripts/pinchtab-curl-wrapper.sh` (solution)
-- `pinchtab-clean-slate.md` (with empirical data + proper examples)
-- PR #52 with complete benchmark data
-
----
-
-## Recommendations
-
-### Short Term (PR Ready)
-- ✅ Add wrapper script
-- ✅ Update benchmark docs with real data
-- ✅ Document the proper API flow in pinchtab-clean-slate.md
-
-### Medium Term (Next Release)
-- [ ] Add "Workflow Examples" section to api.md
-- [ ] Add Getting-Started guide (different from reference docs)
-- [ ] Add "Common Mistakes" section
-- [ ] Update SKILL.md with actual curl examples
-- [ ] Add "Why This Design?" boxes
-
-### Long Term
-- [ ] Consider CLI-first approach (users learn \`pinchtab\` CLI before HTTP)
-- [ ] Add interactive tutorial: \`pinchtab interactive-tutorial\`
-- [ ] Add validation tool: \`pinchtab validate-setup\` (checks Pinchtab is running, port is open, etc.)
-
----
-
-**Bottom line:** The Pinchtab API is solid. The documentation just needs to show HOW to use it in addition to WHAT endpoints exist.
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index ee5a3fda..00000000
--- a/docs/README.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Pinchtab Documentation
-
-## Browser Content Extraction Analysis
-
-This folder contains comprehensive benchmarks comparing three web content extraction methods for AI agents: Snapshot (heavyweight), web_fetch (lightweight), and **Pinchtab** (ultra-lightweight).
-
-### Quick Links
-
-**Start here:**
-- 📊 **[Browser Extraction Spectrum](./browser-extraction-spectrum.md)** — The complete comparison (snapshot vs. web_fetch vs. Pinchtab)
-
-**Deep dives:**
-- 🖥️ **[Default Isolated Browser](./default-isolated-browser.md)** — OpenClaw's semantic snapshot analysis + token costs
-- 📝 **[web_fetch Lightweight Analysis](./web-fetch-lightweight.md)** — Text extraction via Readability parser
-- 📦 **[snapshot-test-results.zip](./snapshot-test-results.zip)** — Raw test data (BBC, Corriere, Daily Mail)
-
----
-
-## The Headline
-
-**For 1,000 pages/day:**
-- Snapshot: ~64K tokens/page
-- web_fetch: ~6.8K tokens/page
-- **Pinchtab: ~1.2K tokens/page** ← **98% lighter vs. snapshot**
-
-**Pinchtab wins on:**
-- ✅ Token efficiency (90% reduction)
-- ✅ Real Chrome rendering (handles JavaScript)
-- ✅ Scales efficiently at high volume
-- ✅ Agent-optimized output (no boilerplate)
-
-**Use Snapshot if:** You need to interact (click, fill forms)
-**Use web_fetch if:** Text-only, no JS rendering needed, want simplicity
-**Use Pinchtab if:** Real rendering + minimal tokens (the Goldilocks option)
-
----
-
-## Test Sites
-
-All benchmarks use real-world news sites:
-- **BBC.com** — Portal layout, low content density
-- **Corriere.it** — News hub, high content density
-- **Daily Mail.co.uk** — News + features, very high density
-
----
-
-## Files in This Folder
-
-| File | Purpose | Best For |
-|------|---------|----------|
-| `browser-extraction-spectrum.md` | Complete comparison across all three | Decision-making |
-| `default-isolated-browser.md` | Snapshot analysis + architecture | Deep technical understanding |
-| `web-fetch-lightweight.md` | web_fetch analysis + use cases | Text extraction scenarios |
-| `snapshot-test-results.zip` | Raw data (4.4 KB) | Verification, reproduction |
-| Other docs | Architecture, Docker, Chrome lifecycle | General Pinchtab info |
-
----
-
-## Key Insights
-
-### 1. Snapshot Overhead
-OpenClaw's default semantic snapshot includes full DOM + accessibility tree. This is powerful for UI agents but heavy for text extraction: **29x heavier than web_fetch on Corriere.it**.
-
-### 2. web_fetch Sweet Spot
-Readability parser removes ~70-90% of boilerplate automatically. Perfect for news articles, blogs, content extraction. **9x lighter than snapshot**, but can't handle JavaScript-heavy sites.
-
-### 3. Pinchtab's Advantage
-Real Chrome rendering + text optimization = best of both worlds. **5.7x lighter than web_fetch**, still renders JavaScript, optimized for agents.
-
-### 4. Scale Matters
-At 1,000+ pages/day, method choice has significant impact on token usage. At 10,000 pages/day, the differences compound substantially.
-
----
-
-## Citation
-
-When referencing these benchmarks:
-
-> Extracted from Pinchtab documentation (Feb 26, 2026). Tested against BBC.com, Corriere.it, Daily Mail.co.uk using OpenClaw v2026.2.23.
-
----
-
-## Questions?
-
-- **How do I use Pinchtab?** See [pinchtab-architecture.md](./pinchtab-architecture.md) and [docker.md](./docker.md)
-- **How is Pinchtab different from browser snapshots?** See [browser-extraction-spectrum.md](./browser-extraction-spectrum.md)
-- **What are Pinchtab's stealth levels?** See [agent-optimization.md](./agent-optimization.md)
-- **Can I run Pinchtab in Docker?** Yes, see [docker.md](./docker.md)
-
----
-
-**Last updated:** February 26, 2026 | **OpenClaw version:** 2026.2.23
diff --git a/docs/building.md b/docs/architecture/building.md
similarity index 100%
rename from docs/building.md
rename to docs/architecture/building.md
diff --git a/docs/chrome-lifecycle.md b/docs/architecture/chrome-lifecycle-and-orchestration.md
similarity index 100%
rename from docs/chrome-lifecycle.md
rename to docs/architecture/chrome-lifecycle-and-orchestration.md
diff --git a/docs/pinchtab-architecture.md b/docs/architecture/pinchtab-architecture.md
similarity index 100%
rename from docs/pinchtab-architecture.md
rename to docs/architecture/pinchtab-architecture.md
diff --git a/docs/docs.json b/docs/docs.json
new file mode 100644
index 00000000..7653aa12
--- /dev/null
+++ b/docs/docs.json
@@ -0,0 +1,26 @@
+{
+ "name": "PinchTab",
+ "navigation": {
+ "home": "overview.md",
+ "main": [
+ "overview.md",
+ "get-started.md",
+ "showcase.md"
+ ],
+ "references": [
+ "references/cli-commands.md",
+ "references/curl-commands.md"
+ ],
+ "architecture":[
+ "architecture/pinchtab-architecture.md",
+ "architecture/chrome-lifecycle-and-orchestration.md",
+ "building.md"
+ ],
+ "guides": [
+ "guides/cdp-url-shared-chrome.md",
+ "guides/docker.md",
+ "guides/headed-mode-guide.md",
+ "guides/identifing-instances.md"
+ ]
+ }
+}
diff --git a/docs/STRUCTURE.txt b/docs/extras/STRUCTURE.txt
similarity index 100%
rename from docs/STRUCTURE.txt
rename to docs/extras/STRUCTURE.txt
diff --git a/docs/agent-optimization.md b/docs/extras/agent-optimization.md
similarity index 100%
rename from docs/agent-optimization.md
rename to docs/extras/agent-optimization.md
diff --git a/docs/BENCHMARK-SUMMARY.md b/docs/extras/benckmark-summary.md
similarity index 100%
rename from docs/BENCHMARK-SUMMARY.md
rename to docs/extras/benckmark-summary.md
diff --git a/docs/browser-extraction-spectrum.md b/docs/extras/browser-extraction-spectrum.md
similarity index 100%
rename from docs/browser-extraction-spectrum.md
rename to docs/extras/browser-extraction-spectrum.md
diff --git a/docs/chrome-processes.md b/docs/extras/chrome-processes.md
similarity index 100%
rename from docs/chrome-processes.md
rename to docs/extras/chrome-processes.md
diff --git a/docs/default-isolated-browser.md b/docs/extras/default-isolated-browser.md
similarity index 100%
rename from docs/default-isolated-browser.md
rename to docs/extras/default-isolated-browser.md
diff --git a/docs/pinchtab-clean-slate.md b/docs/extras/pinchtab-clean-slate.md
similarity index 100%
rename from docs/pinchtab-clean-slate.md
rename to docs/extras/pinchtab-clean-slate.md
diff --git a/docs/web-fetch-lightweight.md b/docs/extras/web-fetch-lightweight.md
similarity index 100%
rename from docs/web-fetch-lightweight.md
rename to docs/extras/web-fetch-lightweight.md
diff --git a/docs/get-started.md b/docs/get-started.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/cdp-url-shared-chrome.md b/docs/guides/cdp-url-shared-chrome.md
similarity index 100%
rename from docs/cdp-url-shared-chrome.md
rename to docs/guides/cdp-url-shared-chrome.md
diff --git a/docs/docker.md b/docs/guides/docker.md
similarity index 100%
rename from docs/docker.md
rename to docs/guides/docker.md
diff --git a/docs/headed-mode-guide.md b/docs/guides/headed-mode-guide.md
similarity index 98%
rename from docs/headed-mode-guide.md
rename to docs/guides/headed-mode-guide.md
index cd2be066..56fc9c44 100644
--- a/docs/headed-mode-guide.md
+++ b/docs/guides/headed-mode-guide.md
@@ -1,9 +1,5 @@
# Headed Mode
-<div align="center" style="padding: 12px 0;">
- <img src="../assets/pinchtab-headed.png" width="256" alt="headed mode" />
-</div>
-
Most browser automation assumes you're either fully automated or fully manual. Real workflows aren't like that.
Your agent can fill out a 50-field form in seconds, but it can't solve a CAPTCHA. It can navigate to the right page, but it can't approve a bank transfer. It can scrape a dashboard, but first someone needs to log in with 2FA.
diff --git a/docs/identifying-instances.md b/docs/guides/identifying-instances.md
similarity index 100%
rename from docs/identifying-instances.md
rename to docs/guides/identifying-instances.md
diff --git a/docs/pinchtab.md b/docs/pinchtab.md
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/cli-commands.md b/docs/references/cli-commands.md
similarity index 100%
rename from docs/cli-commands.md
rename to docs/references/cli-commands.md
diff --git a/docs/curl-commands.md b/docs/references/curl-commands.md
similarity index 100%
rename from docs/curl-commands.md
rename to docs/references/curl-commands.md
diff --git a/docs/getting-started-api-workflows.md b/docs/showcase.md
similarity index 100%
rename from docs/getting-started-api-workflows.md
rename to docs/showcase.md
diff --git a/scripts/README.md b/scripts/README.md
deleted file mode 100644
index ec1da66c..00000000
--- a/scripts/README.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Scripts
-
-Development and CI helper scripts.
-
-## Security Scanning
-
-### `run-gosec.sh`
-
-Run the gosec security scanner locally with the same configuration as CI.
-
-**Usage:**
-```bash
-./scripts/run-gosec.sh
-```
-
-**What it checks:**
-- G112 (Slowloris vulnerability)
-- G204 (Command injection)
-
-**Performance notes:**
-- CI runs in ~1-2 minutes (GitHub runners)
-- Local runs may take 3-5+ minutes depending on your machine
-- **Tip:** If it's too slow, just push and let CI run it (with conditional execution, it only runs when Go files change)
-
-**CI behavior:**
-- ✅ Only runs when Go files (`.go`, `go.mod`, `go.sum`) change
-- ⏭️ Skipped when only docs/workflows change (path filtering)
-- Same exclusions as local scan
-- Faster on GitHub runners (optimized VMs)
-
-**First run:**
-- Installs gosec to `~/go/bin/gosec`
-- Results saved to `gosec-results.json`
-- Exits with code 1 if critical issues found (same as CI)
-
-**Alternative:**
-If gosec is too slow locally, you can:
-1. Just push your changes - CI will run it (only on Go changes)
-2. Use our conditional workflow - it skips when no Go files changed
-3. Trust the CI check - it's fast and runs on every PR