Merge pull request #16 from tianrendong/docs/readme-0.15.50

docs: clarify background controls and release 0.15.50

5 files changed, 11 insertions, 43 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c40b76e..6222aaf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 All notable user-facing changes to `pi-chrome`.
 
+## 0.15.50 — 2026-09-10
+
+- **README clarity.** Lead with workflow examples, correct setup ordering and platform-specific onboarding instructions, and clarify privacy guidance. Describe background behavior and the on/off/status controls directly.
+- **Documentation-only release.** Browser behavior and permissions are unchanged. The companion version matches the npm package version.
+
 ## 0.15.49 — 2026-09-10
 
 - **Validation scope.** Node regression suites passed. Live browser validation remains incomplete: an input attempt encountered `Input.dispatchMouseEvent: Detached while handling command.`; a subsequent retest was blocked by a disconnected companion. No live-browser pass is claimed for these changes.
diff --git a/README.md b/README.md
index 3244fae..7ebe1eb 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,7 @@
 
 Debug your app, inspect signed-in dashboards, and capture screenshots using your existing Chrome profile—without setting up a separate automation browser.
 
-Built for the [Pi coding agent](https://pi.dev). Pi's Chrome tools stay locked until you authorize the current session.
-
-[Quick start](#quick-start) · [Examples](./docs/EXAMPLES.md) · [Safety](#safety) · [Contributing](./CONTRIBUTING.md)
-
-[![npm version](https://img.shields.io/npm/v/pi-chrome.svg)](https://www.npmjs.com/package/pi-chrome)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+Built for the [Pi coding agent](https://pi.dev).
 
 ## What you can do
 
@@ -84,9 +79,7 @@ Run `/chrome revoke` when finished. Use `/chrome authorize` again whenever you w
 - **Per-session approval.** Pi's Chrome tools require `/chrome authorize`. `/chrome revoke` locks them and requests cleanup of that session's owned automation tabs. Cleanup preserves existing user tabs.
 - **Separate targets by default.** Page actions without an explicit target use a session-owned automation window or tab. The agent can deliberately target an existing tab when your task calls for it.
 - **Local transport, not a sandbox.** The bridge binds to `127.0.0.1:17318` and rejects browser-origin command requests. It does not authenticate arbitrary non-browser local callers; it is not protection against hostile processes on your machine.
-- **Background mode by default.** Tools cannot override it to explicitly focus Chrome or activate tabs. This is not a zero-focus guarantee: page scripts, trusted input, native prompts, and Chrome/OS behavior can still affect focus. Chrome may also show its debugger banner while attached.
-
-Read the [security policy](./SECURITY.md) and [background-mode scope and risks](./docs/ARCHITECTURE.md#scope-and-risks) before using it with sensitive accounts.
+- **Background mode:** `/chrome background on` (default) blocks pi-chrome tools from directly bringing Chrome to the front or switching your selected tab. Use `/chrome background off` to allow those actions, and `/chrome background status` to check the setting.
 
 ### Limits
 
@@ -114,33 +107,3 @@ Tool parameters are documented inline in Pi. See [architecture](./docs/ARCHITECT
 ### Updating and troubleshooting
 
 After `pi update npm:pi-chrome`, run `/reload` in Pi and reload **Pi Chrome Connector** in `chrome://extensions`. Run `/chrome doctor` to check the connection and companion version.
-
-If Chrome is not responding, confirm the companion is enabled and keep Chrome open. If page checks fail on a Chrome internal page, try a regular web page and run Doctor again. Follow its version-mismatch or session-restart instructions when shown.
-
-### Typing into rich editors
-
-`chrome_type` and `chrome_fill` use one native CDP `Input.insertText` operation for focused contenteditables. This avoids per-character delays for long text and preserves Unicode/newlines. Ordinary inputs and textareas retain individual key events.
-
-For an editor that needs a `keydown` for every character, pass `perCharacter:true`. Bulk insertion still uses Chrome's input system, but does not emit per-character key events or a clipboard `paste` event. Use `includeSnapshot:true` to verify the result; `chrome_fill` still honors `domFallback:false` when synthetic fallback is unwanted.
-
-## Tests and documentation
-
-The [benchmark suite](./test-suite/README.md) includes **44 browser challenges**, hermetic multi-step tasks, and mocked regression tests for input, screenshots, session cleanup, and background policy. These are reproducible test cases—not a guarantee that every website or OS interaction works.
-
-Run mocked regressions with `npm test` (Node.js 22.13+; no live Chrome required). Follow the benchmark guide for live browser checks.
-
-- [Examples](./docs/EXAMPLES.md) — prompts and workflows to try.
-- [FAQ](./docs/FAQ.md) — compatibility, setup questions, and limitations.
-- [Architecture](./docs/ARCHITECTURE.md) — bridge, session lifecycle, and background policy.
-- [Comparison](./docs/COMPARISON.md) — where pi-chrome fits among browser tools.
-- [Changelog](./CHANGELOG.md) — release history.
-
-## Contributing
-
-Bug reports, reproducible browser challenges, and real workflow demos are welcome. Include `/chrome doctor` output and reproduction steps; redact private URLs and page content. See [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-If pi-chrome is useful, consider starring the repo or sharing a workflow that worked for you.
-
-## License
-
-MIT. See [LICENSE](./LICENSE).
diff --git a/extensions/chrome-profile-bridge/browser-extension/manifest.json b/extensions/chrome-profile-bridge/browser-extension/manifest.json
index 2fd4915..5f968a8 100644
--- a/extensions/chrome-profile-bridge/browser-extension/manifest.json
+++ b/extensions/chrome-profile-bridge/browser-extension/manifest.json
@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Pi Chrome Connector",
-  "version": "0.15.49",
+  "version": "0.15.50",
   "description": "Lets Pi control tabs in Chrome via a local connector at 127.0.0.1.",
   "permissions": [
     "tabs",
diff --git a/package-lock.json b/package-lock.json
index f7edadd..425f2bd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
 	"name": "pi-chrome",
-	"version": "0.15.49",
+	"version": "0.15.50",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-chrome",
-			"version": "0.15.49",
+			"version": "0.15.50",
 			"license": "MIT",
 			"peerDependencies": {
 				"@earendil-works/pi-coding-agent": "*",
diff --git a/package.json b/package.json
index 0a705bb..d1e872f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "pi-chrome",
-	"version": "0.15.49",
+	"version": "0.15.50",
 	"scripts": {
 		"test": "node test-suite/unit/csp-eval.test.mjs && node test-suite/unit/automation-target.test.mjs && node test-suite/unit/session-cleanup.test.mjs && node test-suite/unit/background-policy.test.mjs && node test-suite/unit/input-reliability.test.mjs",
 		"version": "node scripts/sync-manifest-version.js",