Skip to content

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

docs: changes to documenation

Luigi Agostic67251eff894
diff --git a/docs/architecture/architecture-overview.md b/docs/architecture/architecture-overview.md
new file mode 100644
index 00000000..d2a1fe43
--- /dev/null
+++ b/docs/architecture/architecture-overview.md
@@ -0,0 +1,30 @@
+## Architecture
+
+PinchTab sits between your tools/agents and Chrome:
+
+```text
+┌─────────────────────────────────────────┐
+│ Your Tool/Agent │
+│ (CLI, curl, Python, Node.js, etc.) │
+└──────────────┬──────────────────────────┘
+ │
+ │ HTTP
+ ↓
+┌─────────────────────────────────────────┐
+│ PinchTab HTTP Server (Go) │
+│ ┌─────────────────────────────────┐ │
+│ │ Tab Manager │ │
+│ │ (tracks tabs + sessions) │ │
+│ └─────────────────────────────────┘ │
+│ ┌─────────────────────────────────┐ │
+│ │ Chrome DevTools Protocol (CDP) │ │
+│ └─────────────────────────────────┘ │
+└──────────────┬──────────────────────────┘
+ │
+ │ CDP WebSocket
+ ↓
+┌─────────────────────────────────────────┐
+│ Chrome Browser │
+│ (Headless, headed, or external) │
+└─────────────────────────────────────────┘
+```
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
new file mode 100644
index 00000000..50af1b41
--- /dev/null
+++ b/docs/core-concepts.md
@@ -0,0 +1,74 @@
+# Core Concepts
+
+## Tab-Centric Design
+
+Every operation targets a specific tab by `tabId`. Create a tab first:
+
+```bash
+curl -X POST http://localhost:9867/tab \
+ -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'
+# Returns: "abc123"
+```
+
+Then use that `tabId` for all subsequent operations.
+
+**Get page snapshot:**
+```bash
+curl "http://localhost:9867/snapshot?tabId=abc123"
+```
+
+**Extract text:**
+```bash
+curl "http://localhost:9867/text?tabId=abc123"
+```
+
+**Perform action (click):**
+```bash
+curl -X POST http://localhost:9867/action \
+ -d '{"kind":"click","ref":"e5","tabId":"abc123"}'
+```
+
+## Refs Instead of Coordinates
+
+The accessibility tree provides **stable element references** instead of pixel coordinates:
+
+```json
+{
+ "elements": [
+ {"ref": "e0", "role": "heading", "name": "Title"},
+ {"ref": "e5", "role": "button", "name": "Submit"},
+ {"ref": "e8", "role": "input", "name": "Email"}
+ ]
+}
+```
+
+Click or interact by ref:
+
+```bash
+curl -X POST http://localhost:9867/action \
+ -d '{"kind":"click","ref":"e5","tabId":"abc123"}'
+```
+
+## Persistent Sessions
+
+Tabs, cookies, and login state survive server restarts:
+
+```bash
+# Login
+pinchtab nav https://example.com/login
+pinchtab fill e3 [email protected]
+pinchtab fill e5 password
+pinchtab click e7
+
+# Restart the server
+pkill pinchtab
+sleep 2
+./pinchtab
+
+# Tab is restored, still logged in
+pinchtab nav https://example.com/dashboard
+pinchtab snap
+# Works without re-login
+```
+
+---
\ No newline at end of file
diff --git a/docs/index.json b/docs/index.json
index 3b301edd..6463e410 100644
--- a/docs/index.json
+++ b/docs/index.json
@@ -2,13 +2,15 @@
"main": [
"overview.md",
"get-started.md",
- "showcase.md"
+ "showcase.md",
+ "core-concepts.md"
],
"references": [
"references/cli-commands.md",
"references/curl-commands.md"
],
"architecture": [
+ "architecture/architecture-overview.md",
"architecture/pinchtab-architecture.md",
"architecture/chrome-lifecycle-and-orchestration.md",
"architecture/building.md"
diff --git a/docs/overview.md b/docs/overview.md
index 23a338b5..62e8dac8 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -34,7 +34,7 @@ curl -s -X POST http://localhost:9867/action \
---
-## Core Characteristics
+## Characteristics
- **Tab-Centric** — Everything revolves around tabs, not URLs
- **Stateful** — Sessions persist between requests. Log in once, stay logged in across restarts
@@ -44,7 +44,7 @@ curl -s -X POST http://localhost:9867/action \
---
-## Key Features
+## Features
- 🌲 **Accessibility Tree** — Structured DOM with stable refs (e0, e1...) for click, type, read. No coordinate guessing.
- 🎯 **Smart Filters** — `?filter=interactive` returns only buttons, links, inputs. Fewer tokens per snapshot.
@@ -58,113 +58,6 @@ curl -s -X POST http://localhost:9867/action \
---
-## Architecture
-
-PinchTab sits between your tools/agents and Chrome:
-
-```text
-┌─────────────────────────────────────────┐
-│ Your Tool/Agent │
-│ (CLI, curl, Python, Node.js, etc.) │
-└──────────────┬──────────────────────────┘
- │
- │ HTTP
- ↓
-┌─────────────────────────────────────────┐
-│ PinchTab HTTP Server (Go) │
-│ ┌─────────────────────────────────┐ │
-│ │ Tab Manager │ │
-│ │ (tracks tabs + sessions) │ │
-│ └─────────────────────────────────┘ │
-│ ┌─────────────────────────────────┐ │
-│ │ Chrome DevTools Protocol (CDP) │ │
-│ └─────────────────────────────────┘ │
-└──────────────┬──────────────────────────┘
- │
- │ CDP WebSocket
- ↓
-┌─────────────────────────────────────────┐
-│ Chrome Browser │
-│ (Headless, headed, or external) │
-└─────────────────────────────────────────┘
-```
-
----
-
-## Core Concepts
-
-### Tab-Centric Design
-
-Every operation targets a specific tab by `tabId`. Create a tab first:
-
-```bash
-curl -X POST http://localhost:9867/tab \
- -d '{"action":"new","url":"https://example.com"}' | jq '.tabId'
-# Returns: "abc123"
-```
-
-Then use that `tabId` for all subsequent operations.
-
-**Get page snapshot:**
-```bash
-curl "http://localhost:9867/snapshot?tabId=abc123"
-```
-
-**Extract text:**
-```bash
-curl "http://localhost:9867/text?tabId=abc123"
-```
-
-**Perform action (click):**
-```bash
-curl -X POST http://localhost:9867/action \
- -d '{"kind":"click","ref":"e5","tabId":"abc123"}'
-```
-
-### Refs Instead of Coordinates
-
-The accessibility tree provides **stable element references** instead of pixel coordinates:
-
-```json
-{
- "elements": [
- {"ref": "e0", "role": "heading", "name": "Title"},
- {"ref": "e5", "role": "button", "name": "Submit"},
- {"ref": "e8", "role": "input", "name": "Email"}
- ]
-}
-```
-
-Click or interact by ref:
-
-```bash
-curl -X POST http://localhost:9867/action \
- -d '{"kind":"click","ref":"e5","tabId":"abc123"}'
-```
-
-### Persistent Sessions
-
-Tabs, cookies, and login state survive server restarts:
-
-```bash
-# Login
-pinchtab nav https://example.com/login
-pinchtab fill e3 [email protected]
-pinchtab fill e5 password
-pinchtab click e7
-
-# Restart the server
-pkill pinchtab
-sleep 2
-./pinchtab
-
-# Tab is restored, still logged in
-pinchtab nav https://example.com/dashboard
-pinchtab snap # Works without re-login
-```
-
----
-
## Support & Community
- **GitHub Issues** — https://github.com/pinchtab/pinchtab/issues
@@ -175,4 +68,4 @@ pinchtab snap # Works without re-login
## License
-Apache 2.0 — Free and open source.
+[MIT](https://github.com/pinchtab/pinchtab?tab=MIT-1-ov-file#readme)