From bc2f43aa40cb8af390eeaefeb5680a870a66d8af Mon Sep 17 00:00:00 2001
From: Tianren Dong <tianrendong.dtr@gmail.com>
Date: Wed, 13 May 2026 02:03:03 -0400
Subject: pi-chrome 0.11.5: plain-English audit pass for /chrome-doctor,
 /chrome-background, /chrome-onboard, README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces remaining jargon in every user-facing string:

- /chrome-doctor: 'Local bridge: mode=server, url=...' -> 'This pi
  session is running the Chrome connection for this machine.'
  'EXTENSION VERSION MISMATCH ...' -> 'The Chrome companion extension
  is on an old version (X); this pi-chrome is Y.'
  'chrome_evaluate("1+1") = 2' -> 'pi-chrome can run code in the
  active Chrome tab.'
  'navigator.webdriver=true on current tab — site fingerprinting may
  flag automation.' -> 'Your Chrome is reporting itself as automated
  to websites. Some sites use this signal to block sign-ins or bot
  checks.'
- /chrome-background description + notify: drops 'silent/background
  mode', frames as 'quiet mode' vs 'watch mode'.
- /chrome-onboard: walks through the click-by-click steps instead of
  saying 'Developer mode -> Load unpacked'.
- session_start notify: drops 'Chrome profile bridge'; says 'pi-chrome
  connected' / 'waiting for the Chrome companion to connect'.
- README 'Trusted-input mode (CDP)' section rewritten as 'Click modes'
  with plain prose explaining quiet vs real-looking clicks and when
  each fails.

Tool descriptions (seen by the agent) keep precise terminology.
---
 README.md | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 8acd598..e9404a6 100644
--- a/README.md
+++ b/README.md
@@ -65,24 +65,25 @@ pi-chrome v<version>
 ✓ Companion Chrome extension responding (ID: <chrome-extension-id>, ext v<version>)
 ```
 
-## Trusted-input mode (CDP)
+## Click modes
 
-By default, `chrome_*` clicks and keystrokes are **synthetic** DOM events (`event.isTrusted === false`). They drive React/Vue/Angular state correctly but **do not** satisfy Chrome's user-activation gates: clipboard write, fullscreen, file picker, and autoplay all need a real user gesture.
+pi-chrome can drive Chrome two ways:
 
-pi-chrome can optionally route input through `chrome.debugger` (CDP `Input.dispatchMouseEvent` / `Input.dispatchKeyEvent`) so each event arrives as `isTrusted=true`, satisfies user-activation, and bypasses site bot-detection that filters synthetic events. The tradeoff: Chrome pins a *"Pi Chrome Connector started debugging this browser"* banner to the top of any debugged tab.
+- **Quiet clicks** — fast and unobtrusive. They work on most sites, but some pages (sign-in flows, copy-to-clipboard buttons, file pickers, autoplay videos, fullscreen, paywalls) ignore them because they don't look like a real human action.
+- **Real-looking clicks** — indistinguishable from a person clicking. They unlock the cases above, but Chrome shows a *"Pi Chrome Connector started debugging this browser"* banner at the top of every tab pi-chrome touches while it's working.
 
-Usage:
+Pick a mode with `/chrome-trusted`:
 
 ```text
-/chrome-trusted on       # all chrome_* tools dispatch via CDP
-/chrome-trusted off      # synthetic events only (default)
-/chrome-trusted auto     # CDP only when a tool passes trusted=true
-/chrome-trusted status   # show current mode and attached tabs
+/chrome-trusted auto     # default; quiet by default, real-looking only when needed
+/chrome-trusted off      # always quiet, no banner ever
+/chrome-trusted on       # always real-looking, banner stays up the whole session
+/chrome-trusted status   # show the current mode
 ```
 
-For a single call, pass `trusted: true` on `chrome_click`, `chrome_type`, `chrome_fill`, `chrome_key`, `chrome_hover`, `chrome_drag`, or `chrome_scroll`. The per-call value always wins over the session toggle.
+For a one-off call, pass `trusted: true` (or `false`) on `chrome_click`, `chrome_type`, `chrome_fill`, `chrome_key`, `chrome_hover`, `chrome_drag`, or `chrome_scroll`. The per-call value wins over the global mode.
 
-First time you upgrade to a pi-chrome that uses trusted input, Chrome will prompt to re-approve the extension's new `debugger` permission — do that once in `chrome://extensions`.
+First time you update pi-chrome to a version that supports real-looking clicks, Chrome will ask you to re-approve the extension. Open `chrome://extensions` and accept the new permission once.
 
 ## Background mode
 
-- 
cgit v1.2.3