gazesight 0.3.5 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 **Let your coding agent see what you see.**
 
-GazeSight lets coding agents inspect the browser tab you're already using, without launching another browser session. Firefox is fully supported and Mozilla-approved (0.3.4). Chrome is supported via manual installation while it awaits Chrome Web Store review. Node.js 20+ and an MCP coding agent with image support are required. Technical decisions and measured results live in `GAZESIGHT_MASTER_SPEC.md` in the source repository.
+GazeSight lets coding agents inspect the browser tab you're already using, without launching another browser session. Firefox is fully supported and publicly available from Mozilla Add-ons (0.4.0). Chrome is supported via manual installation while it awaits Chrome Web Store publication. Node.js 20+ and an MCP coding agent with image support are required. Technical decisions and measured results live in `GAZESIGHT_MASTER_SPEC.md` in the source repository.
 
 ## Install and first capture
 
@@ -12,23 +12,31 @@ GazeSight lets coding agents inspect the browser tab you're already using, witho
 npx gazesight setup
 ```
 
-This is not yet published to the npm registry (see [Release maintainers](#release-maintainers)). Until it is, install the tarball supplied with this preview:
+Published on the public npm registry: https://www.npmjs.com/package/gazesight. `npx gazesight setup` and `npm install -g gazesight && gazesight setup` are equivalent entrypoints.
+
+To configure a specific coding agent non-interactively (`setup` otherwise prompts when run in a real terminal):
 
 ```sh
-npm install -g ./gazesight-0.3.4.tgz
-gazesight setup
+npx gazesight setup --client claude
+npx gazesight setup --client codex
+npx gazesight setup --client both
 ```
 
-After publication, `npx gazesight setup` and `npm install -g gazesight && gazesight setup` are equivalent entrypoints.
+```sh
+npx gazesight doctor
+```
 
-1. **Firefox**: install the separately supplied **Mozilla-signed GazeSight 0.3.4** XPI through about:addons > gear > Install Add-on From File. Do not disable signature verification. Developers can load the manifest printed by setup temporarily in about:debugging; this is a development fallback only.
-   **Chrome**: open chrome://extensions, enable Developer mode, click "Load unpacked", and select the `dist/chrome` directory printed by setup. Chrome Web Store listing is prepared but not yet submitted; this manual path is the only installation method until then.
-2. Open the extension's options page (Firefox: extension options; Chrome: right-click the toolbar icon > Options, or chrome://extensions > Details > Extension options). Import the local config JSON at the path printed by setup, then save. No token copy is required.
-3. Run `gazesight setup` in a real terminal (not piped/scripted). It detects Claude Code and/or Codex on your PATH and asks which to configure — or configure both non-interactively with `gazesight setup --client both` (or `--client claude` / `--client codex`). When a client is detected, setup registers GazeSight with it directly (`claude mcp add` / `codex mcp add` under the hood, at user scope) — no manual file editing, and re-running is safe (it detects an existing registration and leaves it unchanged). If a client isn't detected on PATH, setup instead prints the manual `.mcp.json`/`config.toml` snippet for you to merge by hand. Restart the agent to load MCP.
-4. Open your local project in your browser, keep its tab active, and click the GazeSight toolbar icon ("Use this tab").
-5. Run `gazesight doctor`. Run it **while your coding agent's MCP connection to GazeSight is active** — the health checks it reports depend on that session being live, the same way any MCP tool call would.
+1. Run `gazesight setup` in a real terminal. It configures Claude Code, Codex, or both, then keeps a temporary loopback pairing listener open. Re-running setup is safe and leaves existing client registrations unchanged.
+2. Install a compatible extension: **Firefox 0.4.0+** from Mozilla Add-ons or **Chrome 0.2.0+** by loading the packaged extension manually while Chrome Web Store publication remains pending.
+3. Open GazeSight and click **Connect to GazeSight**. Confirm that the six-digit verification code matches the terminal, then explicitly approve it there. The code expires and is not the permanent credential.
+4. Open your local project in your browser, keep its tab active, and click **Use this tab**. Pairing never selects or authorizes a tab automatically.
+5. Restart your coding agent to load MCP, then run `gazesight doctor` while its GazeSight connection is active.
 6. Ask your agent: "Use GazeSight visual_capture to inspect my active preview tab." The image arrives directly as MCP image content.
 
+Compatibility: npm/MCP 0.4.x pairs with Firefox 0.4.x and Chrome 0.2.x. The prepared 0.5.x runtime/Firefox and 0.3.x Chrome candidates remain unpublished until their release gates are approved. The published npm 0.3.5 runtime remains compatible with Firefox 0.3.4 through Advanced manual configuration; zero-friction pairing is not available in those older builds. New and legacy browser credentials are scoped independently, and importing a legacy JSON configuration remains a recovery fallback rather than a pairing prerequisite.
+
+Claude Code and Codex can both be configured, but the current local architecture allows only one GazeSight MCP process to own a configured bridge port at a time. A second process exits explicitly with `GS_PORT_IN_USE`; close the first client session before starting the other, or use a separate config and port. GazeSight does not terminate or silently take over another process.
+
 Claude Code stores user-scope servers in `~/.claude.json`; Codex uses `~/.codex/config.toml` with `[mcp_servers.gazesight]`. Setup generates installation-specific Node/CLI paths; it never relies on a developer's source checkout. See [Claude Code MCP docs](https://code.claude.com/docs/en/mcp-quickstart) and [Codex MCP docs](https://developers.openai.com/codex/mcp/).
 
 ## Capture and permissions
@@ -46,6 +54,8 @@ gazesight --help
 
 Doctor is read-only and reports corrective actions for Node/build, MCP/port, connection/pairing, target and capture permission. **Run it while your coding agent's MCP session is active** — the MCP server's own health-check endpoint only stays reachable while a real MCP client holds its stdio connection open (this is intentional: the same signal that tells GazeSight a session ended). Only one GazeSight server can own a port; stop a competing agent or configure a different port with `gazesight setup --config PATH --port PORT` and import that config into the extension. Existing config is reused without overwriting its token or port. `GS_NO_TARGET_TAB`: select a local preview with the icon. `GS_NOT_CONNECTED`: check extension options and agent MCP startup. An inactive target is refused; return to that tab. Nothing launches a browser for you.
 
+Use `gazesight pair` to pair a second browser or recover after reinstalling an extension. Use `gazesight pair --revoke ID` (or `--revoke all`) to revoke stored extension credentials. Manual JSON import remains available under **Advanced manual configuration** for legacy recovery only.
+
 ## Local configuration
 
 Windows: `%APPDATA%/GazeSight/config.json`. macOS: `~/Library/Application Support/GazeSight/config.json`. Linux: `$XDG_CONFIG_HOME/gazesight/config.json`, or `~/.config/gazesight/config.json`. Override with `--config PATH` or `GAZESIGHT_CONFIG_FILE`. Run GazeSight setup to create a fresh pairing configuration. No previous configuration or token is copied or deleted. Files are created exclusively with mode 0600 where supported; Windows uses inherited directory ACLs. Keep the private config in your own user directory.
@@ -84,7 +94,7 @@ Root `package.json` is the canonical version; `npm run build` synchronizes inter
 
 ### npm publication
 
-The `gazesight` name is unclaimed on the npm registry (verified via `npm view gazesight`, HTTP 404). Root `package.json` has `"private": true` as a deliberate guard against an accidental `npm publish`; removing it is a conscious, separate step the maintainer takes immediately before a real publish, not something any build/release script does automatically. Prefer npm's Trusted Publishing (OIDC from a GitHub Actions workflow, no long-lived `NPM_TOKEN` stored anywhere) if you set up CI for this; otherwise publish from a trusted local machine with 2FA/OTP. Never commit an npm token to this repository. After a real publish, verify from a clean environment:
+Published: https://www.npmjs.com/package/gazesight — first public release, `gazesight@0.3.5`, `latest` dist-tag. Published from a trusted local machine using a granular npm access token (bypass-2FA, revoked immediately after use; the account's normal interactive OTP/2FA prompt did not trigger reliably from the CLI in this environment). Root `package.json`'s `"private": true` guard was removed as the one deliberate, explicit step immediately preceding the real publish — never something a build/release script does automatically. Verified independently after publishing: `npm view gazesight@0.3.5` against the live registry, the published tarball downloaded and compared byte-for-byte (SHA-256) against the locally-built one, and a real `@modelcontextprotocol/client` connection through a fresh `npx --yes gazesight@0.3.5 mcp` confirming all 25 tools. For future releases, prefer npm's Trusted Publishing (OIDC from a GitHub Actions workflow, no long-lived token stored anywhere) if CI is set up for this project; otherwise a local publish with a short-lived granular token remains the fallback. Never commit an npm token to this repository. Verify any future publish from a clean environment:
 
 ```sh
 npx --yes gazesight@latest setup