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.mdindex 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 — cooThink 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 agentPinchtab 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.23diff --git a/docs/building.md b/docs/architecture/building.mdsimilarity index 100%rename from docs/building.mdrename to docs/architecture/building.mddiff --git a/docs/chrome-lifecycle.md b/docs/architecture/chrome-lifecycle-and-orchestration.mdsimilarity index 100%rename from docs/chrome-lifecycle.mdrename to docs/architecture/chrome-lifecycle-and-orchestration.mddiff --git a/docs/pinchtab-architecture.md b/docs/architecture/pinchtab-architecture.mdsimilarity index 100%rename from docs/pinchtab-architecture.mdrename to docs/architecture/pinchtab-architecture.mddiff --git a/docs/docs.json b/docs/docs.jsonnew file mode 100644index 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.txtsimilarity index 100%rename from docs/STRUCTURE.txtrename to docs/extras/STRUCTURE.txtdiff --git a/docs/agent-optimization.md b/docs/extras/agent-optimization.mdsimilarity index 100%rename from docs/agent-optimization.mdrename to docs/extras/agent-optimization.mddiff --git a/docs/BENCHMARK-SUMMARY.md b/docs/extras/benckmark-summary.mdsimilarity index 100%rename from docs/BENCHMARK-SUMMARY.mdrename to docs/extras/benckmark-summary.mddiff --git a/docs/browser-extraction-spectrum.md b/docs/extras/browser-extraction-spectrum.mdsimilarity index 100%rename from docs/browser-extraction-spectrum.mdrename to docs/extras/browser-extraction-spectrum.mddiff --git a/docs/chrome-processes.md b/docs/extras/chrome-processes.mdsimilarity index 100%rename from docs/chrome-processes.mdrename to docs/extras/chrome-processes.mddiff --git a/docs/default-isolated-browser.md b/docs/extras/default-isolated-browser.mdsimilarity index 100%rename from docs/default-isolated-browser.mdrename to docs/extras/default-isolated-browser.mddiff --git a/docs/pinchtab-clean-slate.md b/docs/extras/pinchtab-clean-slate.mdsimilarity index 100%rename from docs/pinchtab-clean-slate.mdrename to docs/extras/pinchtab-clean-slate.mddiff --git a/docs/web-fetch-lightweight.md b/docs/extras/web-fetch-lightweight.mdsimilarity index 100%rename from docs/web-fetch-lightweight.mdrename to docs/extras/web-fetch-lightweight.mddiff --git a/docs/get-started.md b/docs/get-started.mdnew file mode 100644index 00000000..e69de29bdiff --git a/docs/cdp-url-shared-chrome.md b/docs/guides/cdp-url-shared-chrome.mdsimilarity index 100%rename from docs/cdp-url-shared-chrome.mdrename to docs/guides/cdp-url-shared-chrome.mddiff --git a/docs/docker.md b/docs/guides/docker.mdsimilarity index 100%rename from docs/docker.mdrename to docs/guides/docker.mddiff --git a/docs/headed-mode-guide.md b/docs/guides/headed-mode-guide.mdsimilarity index 98%rename from docs/headed-mode-guide.mdrename to docs/guides/headed-mode-guide.mdindex 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.mdsimilarity index 100%rename from docs/identifying-instances.mdrename to docs/guides/identifying-instances.mddiff --git a/docs/pinchtab.md b/docs/pinchtab.mdnew file mode 100644index 00000000..e69de29bdiff --git a/docs/cli-commands.md b/docs/references/cli-commands.mdsimilarity index 100%rename from docs/cli-commands.mdrename to docs/references/cli-commands.mddiff --git a/docs/curl-commands.md b/docs/references/curl-commands.mdsimilarity index 100%rename from docs/curl-commands.mdrename to docs/references/curl-commands.mddiff --git a/docs/getting-started-api-workflows.md b/docs/showcase.mdsimilarity index 100%rename from docs/getting-started-api-workflows.mdrename to docs/showcase.mddiff --git a/scripts/README.md b/scripts/README.mddeleted file mode 100644index 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