ghost-hands 0.3.0__tar.gz

ghost_hands-0.3.0/.github/workflows/pages.yml

@@ -0,0 +1,40 @@
+name: Deploy site to Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy site to GitHub Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload site artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

ghost_hands-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check the distributions
+        run: twine check dist/*
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

ghost_hands-0.3.0/LAUNCH.md

@@ -0,0 +1,307 @@
+# Ghost Hands — Launch Package
+
+> **STATUS: DRAFT — STAGED LOCALLY ONLY.**
+> Nothing in this file has been published, posted, pushed, or deployed.
+> Every step below runs only on Ryan's explicit go. All copy is DRAFT.
+> Numbers cited are the verified v0.3.0 numbers (see "Honest-claims
+> checklist" at the bottom) — do not inflate them anywhere.
+
+---
+
+## Positioning
+
+**Ghost Hands is the governed agent-hands layer for the web: every action
+an agent takes is classified, judged against policy, recorded before it
+runs, and — when it matters — gated on a human approval. And the browser
+stack underneath is our own: a zero-dependency CDP client driving Chromium
+directly. No Playwright. No Selenium. Nobody else's automation stack.**
+
+One-liner (primary): *Playwright drives. Stagehand thinks. Browser Use
+wanders. Ghost Hands answers for every move.*
+
+### Tagline options (pick one at launch)
+1. "Agent hands with a conscience — classified, approved, and on the record."
+2. "Your agent's hands, on a leash you hold: policy gates, approval prompts, and a replayable trail."
+3. "We didn't wrap Playwright. We built the hands — governor included."
+
+### The wedge (why this exists)
+- Every tool in the field will click "Pay", "Send", or "Delete" the moment
+  a model tells it to. Ghost Hands classifies first (`readonly` / `write` /
+  `consequential`), applies a policy, and stops for a human on the
+  consequential ones. No approver present = denied. Silence is never consent.
+- Every run writes a provenance trail *before* actions execute — audit it,
+  diff it, replay it.
+- Finished runs graduate into deterministic, model-free scripts (Chromium
+  or fake body): explore with a model once, re-run forever for free.
+- Perception is cheap on purpose: numbered element maps, ~174 tokens for
+  the demo page — not screenshot firehoses.
+- Self-healing targets: if the page mutates between seeing and acting, the
+  hands re-find the element by what it *is*, retry once, and log the heal.
+- Local-first: your Chromium, your keys (env only, never stored), zero
+  runtime dependencies, no cloud-browser upsell.
+
+---
+
+## Show HN (DRAFT)
+
+**Title:** Show HN: Ghost Hands – governed agent hands for the web (own CDP stack, zero deps)
+
+**Body:**
+
+> Hi HN — I run a one-person studio in Tennessee and kept running into the
+> same problem with browser agents: every tool I tried (Playwright MCP,
+> Stagehand, Browser Use) hands an LLM raw browser power with no judgment
+> attached. Ask for the wrong thing, or let a page prompt-inject the model,
+> and it will cheerfully click submit/pay/delete.
+>
+> Ghost Hands is the layer I wanted instead. It's a zero-dependency Python
+> package that gives an agent hands on the web — and a governor:
+>
+> - Every action is classified before it runs: readonly / write /
+>   consequential. Consequential actions (form submits, anything that
+>   smells like pay/send/delete/publish) hit a policy: allow, ask a human,
+>   or deny. With no approver attached, "ask" means deny.
+> - Record-before-execute: the decision and the action hit a JSONL
+>   provenance trail before the driver moves, so a run can be audited or
+>   replayed even if it crashes mid-step.
+> - Trails graduate into deterministic, model-free scripts — explore with
+>   a model once, then re-run the same steps with no model in the loop.
+> - The browser body is our own stdlib CDP client over
+>   --remote-debugging-pipe. No Playwright, no Selenium — the maintainer of
+>   our stack is us. (We drive Chromium, the browser; we didn't write a
+>   browser engine.)
+> - Perception is a numbered element map (Jev-style): the demo run reads a
+>   page in ~174 estimated tokens. Stuck detection stops and reports
+>   instead of wandering.
+>
+> v0.2.0 adds tabs, session save/load (cookies + localStorage),
+> self-healing targets (page mutates between perception and action → the
+> element is re-found by descriptor, retried once, heal logged), real
+> screenshots to disk, and an OpenAI-compatible decider whose wire protocol
+> is proven against a local stub. v0.3.0 adds a second pair of eyes
+> (Accessibility-tree maps alongside the shadow-piercing DOM walk),
+> one-action form filling, downloads/uploads, network capture on the
+> trail, structured extract, dialog policy, PDF, viewport presets,
+> richer input (hover/drag/chords/raw coordinates), and wait-for
+> conditions — every one classified and trailed like the rest.
+> It's verified by a 170-test pytest suite and an 82-case bench,
+> including live runs against example.com and a real Wikipedia search
+> driven end-to-end by the deterministic decider.
+>
+> The honest limits: the LLM decider's protocol is proven against a stub;
+> how well any given live model drives it is that model's business.
+> Chromium only, for now — the same action protocol is designed to gain an
+> Android body from our phone agent (MrGhosty) later.
+>
+> MIT. I'd love feedback on the governance model in particular — is
+> classify-and-approve the right default, or should read/write/consequential
+> be split differently?
+
+---
+
+## r/Python post (DRAFT)
+
+**Title:** Ghost Hands 0.2 — zero-dependency, governed browser automation for agents (own CDP client, approval gates, replayable trails)
+
+**Body:**
+
+> I built Ghost Hands because every agent-browser tool I tried would
+> execute whatever the model said — including "submit", "pay", and
+> "delete". Ghost Hands puts a governor between the brain and the hands:
+>
+> - **Classify → policy → record → act.** Every action is readonly, write,
+>   or consequential. Consequential actions need policy approval (or a
+>   human's). Everything is written to a JSONL trail *before* it executes.
+> - **Own CDP stack.** The Chromium driver is a stdlib Chrome DevTools
+>   Protocol client over `--remote-debugging-pipe` — no Playwright, no
+>   Selenium, `dependencies = []` in pyproject. Driving a real tab,
+>   session save/load (cookies + localStorage), and screenshots included.
+> - **Cheap eyes.** Numbered element maps parsed from HTML — the bundled
+>   demo reads a page in ~174 estimated tokens.
+> - **Runs graduate.** Any trail exports into a deterministic Ghost Hands
+>   script (no model) — the bench actually executes a graduated script on
+>   real Chromium to prove it.
+> - **Self-healing targets** (new in 0.2): if the page mutates between
+>   perception and action, the target is re-found by descriptor and
+>   retried once; the heal is a trail event.
+> - **Deciders are pluggable:** scripted, deterministic rules (offline),
+>   or any OpenAI-compatible endpoint (key from env only; wire protocol
+>   tested against a local stub server).
+> - Plus a stdlib MCP server (`hands_perceive` / `hands_act` / `hands_run`
+>   / `hands_trail`) — Playwright MCP's surface, with the governor attached.
+>
+> Verified locally: 170 pytest tests, 82 bench cases, plus live cases
+> (example.com link-follow; a real Wikipedia search for "Oakdale,
+> Tennessee" driven end-to-end by the rules decider). MIT licensed.
+> Feedback on the classification model especially welcome.
+
+## r/opensource post (DRAFT)
+
+**Title:** Ghost Hands — open-source agent hands that ask before they pay (zero-dep Python, own CDP stack)
+
+**Body:**
+
+> Open-sourcing the browser-hands layer from our studio's agent stack.
+> The idea: agents shouldn't get raw browser power. Ghost Hands classifies
+> every action (readonly / write / consequential), enforces a policy with
+> human approval for the consequential ones, records everything to a
+> provenance trail before it runs, and can graduate a finished run into a
+> deterministic script that needs no model. The browser automation layer
+> is our own — a zero-dependency stdlib CDP client — because we didn't
+> want to ship someone else's stack as our product. MIT. Links + a
+> 82-case bench and 170 tests in the repo; live example (real Wikipedia
+> search, governed) in the README.
+
+---
+
+## X / TikTok short copy (DRAFT)
+
+**X (post):**
+> Playwright drives. Stagehand thinks. Browser Use wanders.
+> Ghost Hands answers for every move.
+>
+> Governed agent hands for the web: every action classified, consequential
+> ones gated on YOUR approval, everything recorded before it runs — on our
+> own zero-dependency CDP stack. No Playwright under the hood. 👻🖐️
+> #buildinpublic #python #aiagents
+
+**X (follow-up):**
+> The demo reads a whole page in ~174 tokens.
+> A checkout click with no approver attached? Denied — and the trail shows
+> exactly why. That's the whole product: hands you can audit.
+
+**TikTok caption:**
+> I built my AI agent a pair of hands — then I built it a conscience.
+> Ghost Hands: it classifies every click before it clicks, asks me before
+> anything that costs money, and writes down everything it did. Oh — and
+> we didn't wrap Playwright. We wrote our own browser stack. 👻
+> #buildinpublic #devtools #aiagent #python #ghostdevstudio
+
+---
+
+## Build in Public episode outline (DRAFT)
+
+**Working title:** "We Built Our Own Playwright — With a Conscience"
+**Format:** vertical, studio standard; show artifacts, not gaps.
+
+1. **Cold open (the problem):** on camera — an ungoverned agent (any
+   competitor) one prompt away from clicking "Place order". Freeze frame:
+   "Would you let your agent do that unsupervised?"
+2. **The bench moment:** run `ghost-hands bench` live on screen — 82/82,
+   call out the money case: "checkout blocked without approval."
+3. **Show the trail:** open a trail file; walk one step: perceive →
+   decide → govern → execute → result. "Receipts for every move."
+4. **Show the hands are ours:** the CDP pipe client, zero dependencies —
+   print the import audit. "No Playwright. No Selenium. Ours."
+5. **Live proof:** the Wikipedia run — RuleDecider types "Oakdale,
+   Tennessee", the Search click classifies *consequential*, approval
+   granted, lands on the Oakdale article. Real browser, real site.
+6. **The heal:** mutation demo — banner appears mid-run, target shifts,
+   `heal` event in the trail, action still lands.
+7. **Graduation:** export a trail → run the graduated script with no
+   model. "Explore once with AI. Replay forever free."
+8. **Close:** what's next (Android body — the same hands on a phone),
+   launch ask: star/feedback; no mention of anything unfinished as a lack
+   — frame purely as what's coming.
+
+---
+
+## Product Hunt draft (DRAFT)
+
+**Name:** Ghost Hands
+**Tagline:** Governed agent hands for the web — approval gates, provenance trails, zero dependencies
+**Description:**
+> Ghost Hands gives AI agents hands on the web — with a governor attached.
+> Every action is classified (readonly / write / consequential), judged
+> against a policy, written to a replayable provenance trail before it
+> executes, and gated on human approval when it matters. Finished runs
+> graduate into deterministic scripts that re-run with no model. Under the
+> hood is our own zero-dependency CDP client driving Chromium — no
+> Playwright, no Selenium — plus cheap numbered element maps (~174 tokens
+> for the demo page), tabs, session save/load, self-healing targets, and
+> an MCP server. MIT, from Ghost Developer Studio.
+**Makers:** Ryan Cotten (Ghost Developer Studio)
+**Topics:** Developer Tools, Artificial Intelligence, Open Source, Automation
+**First comment (draft):** the Show HN body, lightly trimmed.
+
+---
+
+## Publish steps (run ONLY on Ryan's explicit go, in order)
+
+1. **Final local verification:** `pytest -q` (expect 170 passed),
+   `ghost-hands bench` (expect 82/82), `ghost-hands bench --live`
+   (expect 2/2), `python -m build` (0.3.0 wheel + sdist), clean-venv
+   install + `ghost-hands demo` + MCP smoke. Record the numbers; update
+   README/this file if they moved.
+2. **Create the GitHub repo** `littlestjames82-sys/ghost-hands` (public,
+   MIT) via the GitHub API with the stored connector (same route used for
+   agent-seatbelt / ghostbus): push the tree at `~/workspace/ghost-hands/`
+   (src layout, tests, examples, README, LICENSE, PLAN.md, LAUNCH.md,
+   site/) as the initial commit.
+3. **Tag `v0.3.0`** on that commit and cut a GitHub release with the notes
+   from the README changelog; attach the built wheel + sdist from `dist/`.
+4. **PyPI trusted publishing** (mirror the ghost-seatbelt flow exactly):
+   a. On PyPI: "Publishing → Add a new pending publisher" — project name
+      `ghost-hands`, owner `littlestjames82-sys`, repository `ghost-hands`,
+      workflow `release.yaml`, environment `pypi`.
+      (Name availability re-verify immediately before: `ghost-hands`
+      returned 404 on Oct 8, 2026.)
+   b. Commit `.github/workflows/release.yaml` (build + `pypa/gh-action-pypi-publish`
+      with OIDC, environment `pypi`) — same shape as agent-seatbelt's.
+   c. Trigger the workflow from the v0.3.0 release; verify
+      `pip install ghost-hands` in a clean venv + `ghost-hands demo`.
+   d. After the first successful publish, delete the "pending" nature by
+      confirming the project page lists 0.3.0 files (wheel + sdist).
+5. **Enable GitHub Pages** for the repo: the landing page lives at
+   `site/` in the repo root, so publish that directory — either add the
+   standard static-pages workflow (`actions/upload-pages-artifact` with
+   `path: site`, Pages source = GitHub Actions) or serve a `gh-pages`
+   branch containing the contents of `site/`. Verify the logo path
+   (`assets/ghost-developer-studio-logo.png`, relative to `site/index.html`)
+   resolves on the live URL before announcing it.
+6. **Announce** (each is its own approval): Show HN (weekday 8–9am ET),
+   r/Python + r/opensource posts, X/TikTok copy, Product Hunt submission,
+   Build in Public episode. Re-check every number in the copy against the
+   honest-claims checklist below on the day.
+
+---
+
+## Honest-claims checklist (verified Oct 8, 2026 — re-verify on launch day)
+
+- [x] pytest: **170 passed** (v0.3.0 tree).
+- [x] Bench (offline): **82/82 passed**, including live-Chrome fixture
+      cases (perceive/type/click, session roundtrip, tabs, screenshot,
+      graduated-script execution) and the full v0.3 capability set on
+      real Chromium (AX eyes, shadow DOM, frames, dialogs, downloads,
+      uploads, network capture, fill_form, structured extract, hover,
+      drag, chords, PDF, viewport, wait_for, click_at).
+- [x] Bench (live): **2/2 passed** — example.com (title "Example Domain",
+      IANA link followed to https://www.iana.org/help/example-domains,
+      landed title "Example Domains") and Wikipedia (RuleDecider searched
+      "Oakdale, Tennessee", 3 executed steps, landed on
+      https://en.wikipedia.org/wiki/Oakdale,_Tennessee, title
+      "Oakdale, Tennessee - Wikipedia"). Note: one transient failure was
+      observed during the v0.3 round (the sandbox egress proxy closing
+      connections across several hosts, `net::ERR_CONNECTION_CLOSED`);
+      the re-run passed 2/2 and adjacent probes loaded Wikipedia with
+      the same code — environmental, not a regression.
+- [x] Dist sizes (0.3.0): wheel **76,665 B**, sdist **366,151 B** (the
+      sdist ships the full test suite + bench fixtures).
+- [x] Demo perception: **696 map chars ≈ 174 tokens (chars/4)** for the
+      bundled demo run; demo completes in 8 steps.
+- [x] Zero runtime dependencies: pyproject `dependencies = []`; import
+      audit = stdlib only.
+- [x] No Playwright / Selenium code: grep shows only negative assertions
+      and comparison copy (tests assert exports do NOT contain them).
+- [x] example.com link label: as served Oct 2026 it reads **"Learn more"**
+      (href https://iana.org/help/example-domains) — do not claim a
+      "More information" label in copy.
+- [ ] LLM decider: protocol proven vs a **local stub** only. Never claim
+      live-model performance, success rates, or benchmarks.
+- [ ] ChromiumDriver vs arbitrary third-party sites: proven on
+      example.com + Wikipedia only. No broad compatibility claims.
+- [ ] No speed claims vs Playwright/Stagehand/Browser Use — we have not
+      benchmarked head-to-head; the comparison table describes features,
+      not performance.
+- [ ] PyPI/GitHub: NOT live until step 2–4 above are done. All install
+      commands in copy are future tense until then.

ghost_hands-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ghost Developer Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghost_hands-0.3.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.5
+Name: ghost-hands
+Version: 0.3.0
+Summary: Governed agent hands for the web: numbered element maps, classified actions, an approval governor, and a replayable provenance trail.
+Project-URL: Homepage, https://github.com/littlestjames82-sys/ghost-hands
+Project-URL: Repository, https://github.com/littlestjames82-sys/ghost-hands
+Author: Ghost Developer Studio
+License: MIT
+License-File: LICENSE
+Keywords: agent,browser-automation,cdp,governance,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Ghost Hands
+
+**Playwright drives. Stagehand thinks. Browser Use wanders. Ghost Hands answers for every move.**
+
+Ghost Hands is a standalone, zero-dependency Python package that gives an
+agent *hands* on the web — and a conscience to go with them. Every action an
+agent takes is classified before it runs (`readonly` / `write` /
+`consequential`), judged against a policy, written to a provenance trail
+*before* it executes, and — when it matters — gated on a human approval.
+Finished runs graduate into deterministic, model-free Ghost Hands scripts
+you can re-run for free.
+
+The browser body is **our own**: a stdlib Chrome DevTools Protocol client
+drives Chromium directly over the `--remote-debugging-pipe` transport.
+There is no Playwright, no Selenium, and no other automation library under
+the hood — the automation layer is 100% ours. (We drive Chromium, the
+browser; we did not write a browser engine and don't claim to have.)
+
+From [Ghost Developer Studio](https://github.com/littlestjames82-sys).
+MIT licensed.
+
+> Status: v0.3.0 — **live on GitHub**:
+> [github.com/littlestjames82-sys/ghost-hands](https://github.com/littlestjames82-sys/ghost-hands),
+> site at [littlestjames82-sys.github.io/ghost-hands](https://littlestjames82-sys.github.io/ghost-hands/).
+> The PyPI listing (`ghost-hands`) is being registered and lands at launch.
+
+## What's new in 0.3.0
+
+- **Two kinds of eyes.** DOM eyes now walk the composed tree — open
+  shadow roots pierced, same-page iframes included and tagged — so web
+  components and framed controls are numbered like everything else.
+  Or switch to **AX eyes** (`eyes="ax"`): the map is built from the CDP
+  Accessibility tree (role + name + states) and actions resolve back
+  through `backendNodeId`.
+- **Forms in one move.** `fill_form` fills a whole form from
+  `{label: value}` pairs, resolving each field by label, name,
+  placeholder, or aria-label, and reports per-field results — failures
+  named, never silent. With `submit: true` it is classified
+  consequential and takes the normal approval path.
+- **Files both ways.** `download` clicks through and waits for the file
+  to complete on disk (filename + byte size reported, completion on the
+  trail); `set_file` uploads a local file into a file input
+  (`DOM.setFileInputFiles`), refusing missing paths and directories.
+- **Network on the record.** The Network domain is captured during
+  runs (method, URL, status, type) into `net` trail events, capped at
+  200 per run with truncation noted; `extract` mode `network` returns
+  the captured list.
+- **Structured extract.** `extract` modes: `text` (default), `list`
+  (links → `[{text, href}]`), `table` (→ list of row dicts), `network`.
+- **Dialogs handled, on the record.** `confirm`/`alert`/`prompt` are
+  answered per the driver policy (`dialog_policy="dismiss"|"accept"`,
+  default dismiss) and every dialog + decision lands on the trail.
+- **Richer input.** `hover`, `double_click`, `right_click`, `drag`
+  (target → target), key chords in `press` (`"Control+a"`), and
+  `click_at(x, y)` — the raw-coordinate fallback, classified `write`
+  and marked `raw: true` on the trail.
+- **PDF + viewport.** `pdf` prints the page to a real PDF file
+  (`Page.printToPDF`); `set_viewport` switches named presets
+  (desktop 1280×800, mobile 390×844 + touch) and perception reflects
+  the emulated layout, media queries included.
+- **Wait-for conditions.** `wait_for` waits for text to appear, an
+  element matching a descriptor, or a URL substring — with a timeout
+  that fails honestly, on the record.
+- All new actions work through the CLI runner and MCP `hands_act`
+  unchanged, and every one of them is still classified by the governor
+  and written to the trail. (HTML-snapshot eyes do not pierce shadow
+  roots or frames — that is what the live-element map is for.)
+
+## What's new in 0.2.0
+
+- **Live-web proven.** The Chromium driver has now driven real sites end
+  to end: example.com (followed the IANA link to the Example Domains
+  page) and a real Wikipedia search — the deterministic RuleDecider typed
+  "Oakdale, Tennessee", submitted, and landed on the Oakdale article.
+  Reproduce with `ghost-hands bench --live` (2 cases, verified Oct 8,
+  2026 from the studio sandbox).
+- **Self-healing targets.** If the page mutates between perception and
+  action, the stale target is detected, re-found by its recorded
+  descriptor, retried exactly once, and the heal is written to the trail
+  as its own event.
+- **Tabs.** `open_tab` / `switch_tab` / `list_tabs` — each tab is its own
+  CDP target; perception and actions apply to the active tab.
+- **Session state.** `save_session` / `load_session`: cookies
+  (Network.getAllCookies / setCookie) plus the current origin's
+  localStorage, in a small versioned JSON format.
+- **Screenshots to disk.** The screenshot action now writes a real PNG
+  (`Page.captureScreenshot`) to the action's `path`.
+- **Proxy support.** The driver honors `HTTPS_PROXY` / `https_proxy`
+  (opt out with `proxy=""`). Authenticated proxies work via a built-in
+  local relay that injects the credentials Chrome itself can't accept;
+  `ignore_cert_errors=True` is available for TLS-intercepting proxies.
+- **Decider wire proof.** The OpenAI-compatible decider's protocol —
+  request shape, env gating, reply parsing, the full Runner loop — is
+  covered by tests and a bench case against a local stub
+  `/chat/completions` server. Live-model driving quality remains
+  unproven (see "Honest status").
+- **Graduated scripts, executed.** Replay export now takes `driver=`
+  (chromium or fake-with-embedded-pages) and `start_url=`; the bench
+  actually *executes* a graduated script against fixture pages on real
+  Chromium and checks its completion marker.
+
+## Quickstart
+
+```bash
+pip install ghost-hands        # (once published; for now: pip install . from a checkout)
+ghost-hands demo               # scripted run over a built-in fake mini-web — no browser needed
+ghost-hands bench              # the verification suite
+```
+
+Drive a real page:
+
+```python
+from ghost_hands import ChromiumDriver, Runner, ScriptedDecider
+
+driver = ChromiumDriver()  # finds Chromium/Chrome; $GHOST_HANDS_CHROME overrides
+runner = Runner(driver, ScriptedDecider([
+    {"kind": "navigate", "url": "https://example.com"},
+    {"kind": "extract"},
+    {"kind": "done", "summary": "looked at the page"},
+]))
+report = runner.run("look at example.com")
+print(report.stop_reason, report.summary)
+driver.close()
+```
+
+## How it works
+
+| Layer | What it does |
+|---|---|
+| **Eyes** (`eyes.py`) | Numbered **ElementMap** — `[3] <button> "Sign in"` — compact text with a character budget. No screenshots, no vision model. Two sources: an HTML snapshot parse (offline body), or the live browser — a composed-tree DOM walk (shadow roots + iframes) or the CDP Accessibility tree. |
+| **Hands** (`actions.py`) | Typed, JSON-serializable actions: navigate, click, type, press (with key chords), select, scroll, hover, double/right click, drag, click_at (raw coordinates), fill_form, set_file, download, extract (text/list/table/network), screenshot (to a real PNG file), pdf, set_viewport, wait / wait_for, tabs, session save/load, done. Targets are element numbers, never raw selectors. |
+| **Governor** (`governor.py`) | Classifies every action *before* execution and applies a policy: allow / ask / deny per class, a domain allowlist, blocked domains. Form submits and anything smelling like pay / send / delete / publish / transfer is **consequential**. |
+| **Trail** (`trail.py`) | JSONL provenance: perceive → decide → govern → execute → result → stop (plus `heal`, `dialog`, `net`, and `download` events), with per-run accounting (steps, perception chars, ~tokens at chars/4, actions by class). Govern + execute are recorded **before** the action runs. |
+| **Bodies** (`drivers.py`) | `FakeDriver` (in-memory mini-web for tests/demos) and `ChromiumDriver` (real Chromium via our own CDP client: auto-wait, tabs, session save/load, screenshots to disk, downloads/uploads, network capture, dialog policy, viewport emulation, PDF, env-proxy support with a credential-injecting local relay, stale-target detection). |
+| **Brains** (`deciders.py`) | `ScriptedDecider` (explicit steps), `RuleDecider` (deterministic offline rules — "go to…", "click…", "type… into…", "search for…"), `OpenAICompatibleDecider` (any OpenAI-compatible endpoint; key from env only, never stored; wire protocol proven against a local stub server). |
+| **Runner** (`runner.py`) | The loop, with a step budget, stuck detection (same action 3×, or an unchanged map for 3 steps), and self-healing: a target that moved mid-flight is re-found by descriptor and retried once, heal logged. Honest stop reasons: `done` / `budget` / `denied` / `stuck` / `error`. Silence is never consent: an "ask" with no approver is a denial. |
+| **Replay export** (`export.py`) | Graduate a trail into a standalone Ghost Hands script that replays the executed steps deterministically — no model, still governed. Chromium body, or a fake body with the mini-web embedded. |
+| **MCP server** (`mcp_server.py`) | Stdlib-only stdio MCP: `hands_perceive`, `hands_act`, `hands_run`, `hands_trail`. Consequential actions are denied on this channel (no approver) with an explanation. |
+
+## CLI
+
+```bash
+ghost-hands demo                                   # built-in fake-web demo
+ghost-hands bench                                  # 82-case verification suite
+ghost-hands bench --live                           # + live cases: example.com, Wikipedia
+ghost-hands run --script steps.json --driver fake  # or --driver chromium
+ghost-hands run --script steps.json --policy policy.json --approve-all
+ghost-hands export trail.jsonl -o replay.py        # graduate a trail into a script
+ghost-hands export trail.jsonl --driver fake --pages pages.json -o replay.py
+ghost-hands mcp                                    # MCP server on stdio
+```
+
+See `examples/steps.json` and `examples/policy.json` for the file formats.
+
+## How it compares
+
+| | Driver stack | Intent layer | Governance / approval gate | Provenance trail | Run → script replay | Bodies |
+|---|---|---|---|---|---|---|
+| **Playwright** | Own protocol drivers for Chromium/Firefox/WebKit | None — deterministic scripts | None | Trace viewer for tests | Codegen records scripts | Web |
+| **Playwright MCP** | Playwright via MCP (23+ raw tools) | The calling model, unmediated | None | None built in | No | Web |
+| **Stagehand** | Playwright + AI primitives (act/observe/extract/agent) | Per-step LLM calls | None | Session logs | Action caching | Web (cloud browsers upsell) |
+| **Browser Use** | Own browser agent loop | Full autonomous LLM loop | None | Run history | No | Web |
+| **Jev** | Numbered control list, cheap decision pass | Single cheap pass per step | None (we built Agent Seatbelt for it) | Minimal | No | Web |
+| **Ghost Hands** | **Own CDP stack, zero dependencies — no Playwright, no Selenium under the hood** | Pluggable: scripted, deterministic rules, or any OpenAI-compatible model | **Classify + policy + approval before every action; record-before-execute** | **Full JSONL trail with per-run accounting** | **Yes — trails graduate into Ghost Hands scripts** | Web today; phone (Android via MrGhosty) on the roadmap |
+
+### Capabilities, feature by feature
+
+Surveyed from each project's public docs (Oct 2026); "—" means not a
+built-in of the tool as documented. Every Ghost Hands row is proven by
+a named bench case on real Chromium unless marked (fake) — the bench
+says which body each case ran on.
+
+| Capability | Playwright | Stagehand | Browser Use | Ghost Hands |
+|---|---|---|---|---|
+| Numbered element map for a model | Via MCP / snapshots | observe | Yes (own format) | **Yes — DOM or Accessibility-tree eyes** |
+| Shadow DOM controls | Yes | Yes | Partial | **Yes — open roots pierced (live map)** |
+| Iframe controls | Yes | Yes | Partial | **Yes — same-page frames, tagged** |
+| JS dialogs (confirm/alert) | Yes | Yes | Yes | **Yes — policy-driven, decision on the trail** |
+| Downloads | Yes | Yes | Yes | **Yes — completion + size on the trail** |
+| File upload | Yes | Yes | Yes | **Yes — `set_file`** |
+| Network capture | Yes (HAR/request APIs) | Via Playwright | Limited | **Yes — `net` trail events + extract mode** |
+| Fill a whole form in one step | No (per-field API) | act per field | Agent loop | **Yes — `fill_form`, per-field results** |
+| Structured extract (list/table) | Manual locators | extract (LLM schema) | Agent loop | **Yes — deterministic, no model call** |
+| Hover / double / right click / drag | Yes | Via act | Yes | **Yes** |
+| Key chords (Control+a) | Yes | Via act | Yes | **Yes** |
+| Raw coordinate clicks | Yes | — | Yes | **Yes — classified `write`, marked raw** |
+| PDF export | Yes (Chromium) | Via Playwright | — | **Yes** |
+| Device/viewport emulation | Yes | Via Playwright | Viewport opts | **Yes — named presets, perception follows** |
+| Wait for text/element/URL | Yes | Via act | Agent loop | **Yes — honest timeout on the record** |
+| **Every action classified + approval-gated** | **No** | **No** | **No** | **Yes — the whole point** |
+| **Run graduates into a replayable script** | Codegen (records new) | Action cache | No | **Yes — from the trail** |
+
+## Honest status
+
+What is proven, and what is not — as of v0.3.0 (Oct 8, 2026):
+
+- **Proven:** the full offline suite (170 pytest tests, 82 bench cases);
+  the Chromium driver on fixture pages (perceive / type / click / tabs /
+  session roundtrip / screenshots / graduated-script execution) and the
+  full v0.3 capability set on real Chromium (see the matrix note);
+  live runs on example.com and Wikipedia (`ghost-hands bench --live`,
+  2/2); the LLM decider's wire protocol against a local stub endpoint.
+- **Unproven:** live-model driving quality (bring your own model; how
+  well it drives is the model's business, and no benchmark is claimed);
+  the Chromium driver against arbitrary third-party websites beyond the
+  two live cases above; head-to-head speed vs any other tool (never
+  measured, never claimed).
+
+## Safety posture
+
+- **No stealth.** Ghost Hands identifies honestly and never disguises
+  automation. Governance is the product; evasion is not a feature.
+- **No stored keys.** The OpenAI-compatible decider reads
+  `GHOST_HANDS_API_KEY` / `GHOST_HANDS_BASE_URL` / `GHOST_HANDS_MODEL` from
+  the environment only.
+- **Denied means denied.** A blocked, denied, or unapproved action never
+  executes — and the trail shows the verdict and the reason.
+
+## Roadmap
+
+- **Android body** — MrGhosty's accessibility service speaking the same
+  action protocol: one hands, phone + web.
+- **GhostBus transport** — hands as a bus agent other agents can task.
+- **Policy packs** — Seatbelt/GhostGuard policy bundles; approvals routed
+  over GhostBus or phone push.
+
+## License
+
+MIT — see `LICENSE`. © 2026 Ghost Developer Studio.