Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs: document the harness, voice input, and local state

Shahriar06ec89bd477e
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8b874f0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Skills
+
+Project skills live in `.claude/skills/<name>/SKILL.md` and are invoked with a leading slash (`/<name>`) or picked up automatically when the request matches their `description` triggers.
+
+| Skill | Use it for |
+| --- | --- |
+| [`/voicelink`](.claude/skills/voicelink/SKILL.md) | Driving the user's real browser through the MCP harness — the preflight check, targeting strategy, the error-code → next-move table, navigation edge cases, and the safety rules that apply because these tools act on a live logged-in session. |
+
+Read the skill before calling any `page_*` or `voicelink_*` tool; it encodes failure modes that are not obvious from the tool schemas.
+
+## Project
+
+VoiceLink is an AI voice assistant Chrome extension (Manifest V3) built with WXT (Vite-based extension framework), React 19, TypeScript, Tailwind CSS v4, and shadcn/ui. Its core is a declarative **action layer** (`lib/actions/`) of page-control capabilities designed to double as MCP tool definitions. The AI chat and voice features are still mocked; the scaffold marks where to wire them in.
+
+## Commands
+
+```sh
+npm run dev # build + launch Chrome (throwaway profile) with the extension loaded, HMR
+npm run dev:firefox # same, for Firefox
+npm run build # production build → dist/chrome-mv3/
+npm run compile # type-check only (tsc --noEmit) — the only check tooling; no lint or tests configured
+npm run zip # store-ready zip
+npm run icons # regenerate placeholder icons in public/icon/
+npx shadcn@latest add <component> # add shadcn/ui components → components/ui/
+```
+
+The MCP harness lives in `mcp/` and is a **separate npm package** with its own `node_modules`, `tsconfig.json`, and dependency install:
+
+```sh
+npm run mcp:install # one-time; `npm install` at the root does NOT cover mcp/
+npm run mcp:build # tsup → mcp/dist/ (bundles lib/actions via the @/* path alias)
+npm run mcp:link # one-time; puts `voicelink-mcp` on PATH (npm run mcp:unlink undoes it)
+npm run compile:mcp # type-check mcp/ (the root `npm run compile` excludes it)
+npm run mcp:manifest # build + print the tool manifest from plain Node — no browser
+```
+
+Docs and daemon-printed hints all use the bare `voicelink-mcp` name, so `mcp:link` is effectively required for the documented workflow; without it, invoke `node mcp/dist/cli.js` instead.
+
+`npm run mcp:manifest` is the standing check that no action gained a top-level DOM reference: it loads the shipped bundle in bare Node, where `document` at module scope throws on import.
+
+`npm run compile` depends on generated types in `.wxt/` — run `npm install` (its postinstall runs `wxt prepare`) if they're missing.
+
+## Architecture
+
+### WXT conventions
+
+- **The manifest is generated.** WXT builds `manifest.json` from `wxt.config.ts` (name, permissions: `storage`, `activeTab`, `sidePanel`, `alarms`, `scripting` + host access for content-script re-injection) plus filesystem conventions in `entrypoints/`: `background.ts` → service worker, `content.ts` → content script, `popup/index.html` → action popup, `sidepanel/index.html` → side panel. Never edit anything in `dist/` or `.wxt/` — both are generated.
+- **Auto-imports.** In `entrypoints/`, `browser`, `defineBackground`, `defineContentScript`, etc. are globals injected by WXT (typed in `.wxt/types/`). Code in `lib/` imports explicitly from `wxt/browser` instead. The `@/` alias maps to the project root and comes from `.wxt/tsconfig.json`, which the root `tsconfig.json` extends.
+- **Styling.** Tailwind v4 via the `@tailwindcss/vite` plugin in `wxt.config.ts` — no `tailwind.config` file; the theme lives in `assets/globals.css`. Dark mode: each entrypoint's `main.tsx` adds `.dark` to `<html>` based on `prefers-color-scheme`.
+
+### The action layer (`lib/actions/`)
+
+Each action is a frozen value from `defineAction()` (`core.ts`): a namespaced name (`page.clickElement`), a one-line description, a zod input schema, and an `execute()` that runs **in the page** (content-script context). The same declarative shape drives typed in-extension calls today and MCP tool definitions later. The pieces:
+
+- `registry.ts` — the `Map` of all 17 actions, plus `describeActions()` → `[{ name, description, inputSchema }]` with JSON Schema (`io: 'input'`, so defaulted fields stay optional and the manifest matches what `dispatch` actually accepts).
+- `dispatch.ts` — validates input against the schema and runs the action; always returns the `{ ok: true, data } | { ok: false, error: { code, message } }` envelope, never throws (`UNKNOWN_ACTION`, `INVALID_INPUT`, or the action's own `ActionError` code).
+- `host.ts` — `exposeActions()`, called by the content script; listens on the `voicelink/action` channel and dispatches in the page.
+- `client.ts` — `invokeInTab` / `invokeInActiveTab`: typed callers usable from any extension context. Passing the action object (not the string name) gives compile-time input typing — and the `input` argument is *required* when the schema has required fields. Transport failures come back as `TAB_UNREACHABLE` / `NO_ACTIVE_TAB` rather than throwing.
+- `protocol.ts` — the two message channels: `voicelink/action` (extension → content script, one invocation) and `voicelink/bridge` (extension pages or external MCP harness → background worker; `op: 'describe'` returns the tool manifest, `op: 'invoke'` routes an action to the active tab). `background.ts` implements the bridge. `index.ts` re-exports the public API.
+- `page/dom.ts` — shared targeting: most actions take `target: { selector?, text?, role?, nth? }`, resolved by `resolveTarget()` (visible elements only; text matches against accessible text, keeping the innermost match). `resolveTarget(target, { includeHidden: true })` opts out of the visibility filter — only `wait-for-element.ts` does, so its `attached`/`hidden`/`detached` states can observe hidden elements.
+- `page/keyboard.ts` — `keyboardInit(key, modifiers)` builds a realistic `KeyboardEventInit`, including legacy `keyCode`/`which` so older handlers fire. Used by `press-key.ts` and `fill-input.ts`.
+
+Call path: side panel / bridge → `invokeForHarness` → `browser.tabs.sendMessage` → content script `exposeActions` → `dispatch` → `action.execute` in the page.
+
+### The MCP harness (`mcp/`, `lib/bridge/`)
+
+`mcp/` is an installable package (`voicelink-mcp` on stdio, `voicelink-mcpd` as the daemon) that exposes the registry as MCP tools. The daemon owns a loopback WebSocket server; the extension connects **out** to it, because an MV3 service worker cannot listen.
+
+- **Parity is structural, not conventional.** The daemon bundles `describeActions()` from `lib/actions/registry.ts` (tsup resolves `@/*` → repo root), so `tools/list` cannot drift from the registry within a build. Adding an action to `registry.ts` is the *only* step needed to expose a new MCP tool.
+- **Names.** MCP tool names cannot contain dots, so `page.clickElement` ⇄ `page_clickElement` via `lib/actions/tool-names.ts`. The mapping is only reversible while no action name segment contains an underscore — `assertToolNamesRoundTrip()` enforces this at startup and in `voicelink-mcp tools`.
+- **Wire types are shared, not copied.** `SocketFrame` and the `ActionResult` envelope both live in `lib/actions/protocol.ts` and are imported by both sides; `lib/actions/manifest.ts` hashes the manifest so a version-skewed extension is detected on connect.
+- **Never import `@/lib/actions` (the index) from `mcp/`** — it re-exports `client.ts`/`host.ts`, which import `wxt/browser` and break in Node. Import the specific modules.
+- **Auth is two independent gates.** At the HTTP upgrade the daemon classifies the peer by handshake `Origin` (extension scheme → extension path; `http(s)` → 403; absent → control client, lockfile token required). That only proves the peer is *an* extension; the `hello` frame must then carry a one-time `pairingToken` or a session key bound to that same origin. Credentials ride in the frame because the browser `WebSocket` API cannot set request headers, and a URL query would leak into logs.
+- **The extension is off by default.** `connectDaemon()` returns without dialing unless `storage.local` holds a session key, so an unpaired browser never contacts the daemon. Pairing state lives in `~/.voicelink/auth.json` (`0600`) — deliberately *not* the lockfile, which is deleted on shutdown.
+- Verified: Chrome does send `Origin: chrome-extension://<id>` from an MV3 worker.
+- **The wire protocol is v2**: on top of the v1 request/reply frames, the extension may send `instruct`/`cancel`/`decision`/`reset` unprompted, and the daemon streams `run` frames back. `assertToolNamesRoundTrip` aside, protocol bumps require rebuilding both sides *and* reloading the extension — a v1 worker is refused at `hello`.
+- **Navigation is special-cased** in `lib/bridge/invoke.ts`. It tries the in-page action first (pushes history) and falls back to `browser.tabs.update` only when `sendMessage` fails with "Receiving end does not exist" — a pre-delivery error proving the action never ran. Any other failure means the page already unloaded and is navigating, so re-issuing would navigate twice.
+- **Service-worker lifetime.** Daemon pings every 20s reset Chrome's 30s idle timer; a 1-minute `alarms` tick is the only thing that can revive the worker once it is torn down.
+
+### The agent harness (`mcp/src/agent/`, side panel)
+
+The reverse direction of the MCP harness: a free-text instruction typed (or spoken) into the extension travels **out** over the same socket, and the daemon runs it as an agent that drives the browser back. There is deliberately no Anthropic API client anywhere — the daemon spawns the user's own **Claude Code** (`claude -p`), so the user's existing login, model choice and limits apply, and no API key ever exists in this codebase.
+
+Call path: side panel/popup → `runtime.connect` port (`lib/bridge/run-port.ts`) → background → `instruct` frame (`lib/bridge/socket.ts`) → daemon → `AgentSession` (`mcp/src/agent/service.ts`) → `claude -p` (`mcp/src/agent/runner.ts`). The spawned Claude Code gets browser tools through our own stdio MCP server: `--mcp-config` points it back at `dist/cli.js` with `--strict-mcp-config`, so its tool calls loop through the daemon and out to the content script like any other MCP client's. Everything else it could touch is disabled via `--disallowedTools`.
+
+- **Run identity is the safety boundary.** The spawn carries `VOICELINK_AGENT_RUN=<runId>`; `RemoteBridge` attaches it to every invoke, and the daemon routes tagged invokes through `AgentSession.invokeForRun` — which emits the timeline `tool`/`toolResult` events, applies the approval gate (`requireApproval` in `~/.voicelink/config.json`, default `page.submitForm`), and refuses invokes whose run is no longer active (a cancelled agent cannot keep driving).
+- **Skills are markdown system prompts** in `mcp/skills/*.md` (bundled; `~/.voicelink/skills/` overrides by name, reloaded every run). Front-matter: `name`, `description`, `triggers: [...]`, `default: true`. Routing: `@name` prefix wins, else most trigger hits, else the default. The body is passed via `--append-system-prompt` on top of the frozen preamble in `mcp/src/agent/prompt.ts`.
+- **Conversation continuity is Claude Code's own session store**: first run passes `--session-id`, follow-ups `--resume`; the side panel's clear button sends `reset`, which just forgets the id.
+- **Run events** (`RunEvent` in `lib/actions/protocol.ts`) stream daemon → extension as `run` frames; the background worker fans them out to extension pages over a long-lived `runtime.connect` port (streamed text arrives token by token — `storage.session` would be wrong here). If no page is watching, the run is cancelled after a grace period.
+- `voicelink-mcp logs` is the debugging surface: every run start/finish, routed skill, and tool call lands in `~/.voicelink/daemon.log`.
+
+### Adding an action
+
+One module per action: `lib/actions/page/<name>.ts` exporting `defineAction({ name: 'page.<name>', … })`, then add it to the array in `registry.ts`. That single edit also publishes it as an MCP tool. The conventions below are load-bearing — breaking them fails at runtime or silently corrupts the MCP manifest, not at compile time:
+
+- **No top-level DOM access.** Touch `document`/`window` only inside `execute()`. `registry.ts` is imported by the background worker (for `describeActions()`), by the MCP daemon, and by plain Node, where a top-level DOM reference throws at import time. `npm run mcp:manifest` is the check.
+- **No underscores in action names** — they break the round trip to MCP tool names.
+- **`.describe()` every input field** — that text becomes the MCP tool's parameter documentation.
+- **No zod `.refine()`/`.transform()`** — they don't survive `z.toJSONSchema()`. Validate inside `execute()` with `throw new ActionError(msg, 'CODE')`, using a stable code: `INVALID_INPUT`, `INVALID_TARGET`, `TARGET_NOT_FOUND`, `TIMEOUT`, `UNSUPPORTED`.
+- **Return a small JSON-serializable result** (usually `describeElement(el)`). It crosses `sendMessage`, so never put a DOM node in it — read form attributes with `getAttribute('action')`, since a control named `action`/`method` shadows the IDL property with an element.
+- **Write to inputs through the native prototype setter** (`Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(el, next)`) then dispatch `input`/`change`. React/Vue ignore direct `.value` writes on controlled inputs. See `fill-input.ts`, `press-key.ts`, `select-option.ts`.
+- **Synthetic events perform no default action.** Dispatched keys don't insert text or submit forms, so actions emulate that explicitly — and honor cancellation by checking `dispatchEvent()`'s return value before emulating.
+- Keep comments to genuine DOM quirks only; the layer is deliberately low-noise.
+
+## AI integration points
+
+- **Chat responses:** real — the side panel's composer sends instructions through the agent harness (see above); replies and tool activity stream back into `RunTimeline`.
+- **Voice input:** real, via the browser's Web Speech API (`webkitSpeechRecognition` — Chrome streams the audio to Google to transcribe; no bundled model). `lib/bridge/use-speech.ts` wraps recognition (mic-permission prompt, continuous mode, silence-driven auto-restart, feature detection); `lib/bridge/use-voice-composer.ts` layers hands-free dictation on top — finalized phrases append to an editable buffer and auto-send after a short silence, with any of {more speech, typing, cancel} calling off the pending send. The **side panel** listens by default (persisted `voicelink:voiceEnabled`, toggled by the mic button); the **popup** is press-to-talk, since a popup dies on blur and can't hold continuous listening. Both surfaces fall back to typing when recognition is unavailable or the mic is blocked. STT swap-out point is `use-speech.ts` alone.
+- **Page context:** the side panel's paperclip button calls the `page.getPageInfo` action on the active tab and splices the result into the prompt.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..552769d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,247 @@
+# VoiceLink
+
+**Talk to any web page.** VoiceLink is a Manifest V3 Chrome extension that turns a spoken or typed
+instruction into real actions on the tab in front of you — clicking, filling, reading, navigating —
+and narrates what it did as it goes.
+
+Three pieces make that work:
+
+- **An action layer** (`lib/actions/`) — 17 declarative, self-describing page capabilities that run
+ in the content script.
+- **An MCP harness** (`mcp/`) — the same registry exposed as an MCP server, so Claude Code or any
+ other MCP client can drive your real, logged-in browser through a local daemon.
+- **An agent harness** (`mcp/src/agent/`) — the reverse direction: an instruction typed into the
+ side panel spawns **your own Claude Code**, which drives the browser back through that same
+ server. There is no Anthropic API client in this repo and no API key anywhere in it.
+
+Built with:
+
+- **[WXT](https://wxt.dev)** — Vite-powered extension framework (auto-generated manifest, HMR, multi-browser builds)
+- **React 19 + TypeScript** — UI entrypoints
+- **Tailwind CSS v4** — styling via `@tailwindcss/vite`
+- **[shadcn/ui](https://ui.shadcn.com)** — the component system used by most modern AI products (Radix primitives + CVA + `lucide-react` icons)
+- **[zod](https://zod.dev)** — one schema per action, doubling as its MCP tool definition
+
+## Getting started
+
+```sh
+npm install
+npm run dev # builds, launches Chrome with the extension loaded, and hot-reloads
+```
+
+Other commands:
+
+```sh
+npm run build # production build → dist/chrome-mv3/
+npm run build:firefox # firefox build
+npm run zip # store-ready zip
+npm run compile # type-check only (tsc --noEmit)
+npm run icons # regenerate placeholder icons in public/icon/
+```
+
+To load the production build manually: `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select `dist/chrome-mv3`.
+
+## What's included
+
+| Surface | File | Notes |
+| --- | --- | --- |
+| Popup | `entrypoints/popup/` | Press-to-talk mic, instruction box, pairing UI, "open side panel" |
+| Side panel | `entrypoints/sidepanel/` | The agent chat: always-on dictation, streamed replies, live tool timeline, approval prompts |
+| Background | `entrypoints/background.ts` | MV3 service worker + the action bridge (`describe`/`invoke`) + the MCP daemon link + the run port |
+| Content script | `entrypoints/content.ts` | Exposes the action layer in every page (`exposeActions()`) |
+| MCP harness | `mcp/` | Installable MCP server + daemon that drives the browser (see below) |
+| Agent harness | `mcp/src/agent/`, `mcp/skills/` | Turns typed instructions into agent runs by spawning your own Claude Code (see below) |
+
+```
+assets/globals.css # Tailwind v4 + shadcn theme (violet, dark-mode aware)
+components/ui/ # shadcn/ui components (button, badge, card, input, textarea, scroll-area)
+lib/actions/ # the declarative page-control action layer (see below)
+lib/bridge/ # extension side of the harness (daemon socket, invoke path, speech hooks)
+mcp/ # the installable MCP server + daemon
+mcp/skills/ # markdown system prompts the daemon routes instructions to
+lib/utils.ts # cn() helper
+public/icon/ # generated placeholder icons
+wxt.config.ts # manifest + Vite/Tailwind config
+components.json # shadcn CLI config
+```
+
+### Adding more shadcn/ui components
+
+```sh
+npx shadcn@latest add dialog dropdown-menu tooltip
+```
+
+Components land in `components/ui/` and import via the `@/` alias (provided by WXT).
+
+## The agent harness — instructions in, actions out
+
+Type an instruction into the side panel (or the popup) of a paired browser and the daemon runs it as an agent: it routes the text to a **skill** (a markdown system prompt from `mcp/skills/`, user-overridable in `~/.voicelink/skills/`), spawns **your own Claude Code** (`claude -p` — your login, your model, no API key anywhere in this repo), and hands it the browser through the same MCP server external clients use. Text streams back token by token; every `page_*` call shows up as a row on the side panel's timeline as it happens; gated actions (`page.submitForm` by default — edit `requireApproval` in `~/.voicelink/config.json`) pause for an Allow/Deny in the panel. Follow-ups resume the same Claude Code session, so "now click the second one" works.
+
+Requires [Claude Code](https://claude.com/claude-code) on your PATH (or `{"claudeBin": "/path/to/claude"}` in `~/.voicelink/config.json`).
+
+## Voice input
+
+Dictation is live, on the browser's own **Web Speech API** (`webkitSpeechRecognition`) — Chrome
+streams the audio to Google to transcribe, so there is no model bundled here and nothing to
+download.
+
+- [`use-speech.ts`](lib/bridge/use-speech.ts) wraps recognition itself: the mic-permission prompt,
+ continuous mode, silence-driven auto-restart, and feature detection.
+- [`use-voice-composer.ts`](lib/bridge/use-voice-composer.ts) layers hands-free dictation on top.
+ Finalized phrases append to an *editable* buffer and auto-send after ~1.6 s of silence; more
+ speech, typing, or an explicit cancel all call the pending send off, so you are never racing a
+ timer.
+
+The **side panel** listens by default (persisted under `voicelink:voiceEnabled`, toggled by the mic
+button, and muted while a run is in flight or the browser is unpaired). The **popup** is
+press-to-talk instead — a popup is destroyed the moment it loses focus and cannot hold continuous
+listening. Both surfaces fall back to plain typing when recognition is unavailable or the mic is
+blocked.
+
+Swapping in a different speech-to-text engine is a one-file change: [`use-speech.ts`](lib/bridge/use-speech.ts)
+is the only module that knows the Web Speech API exists.
+
+## The action layer (`lib/actions/`)
+
+A set of **declarative, first-class functions** that read and control the current web page. Each is a self-describing value — a semantic name, a one-line description, and a [zod](https://zod.dev) input schema — so the same registry drives in-extension calls today and an external **MCP harness** later.
+
+```ts
+// lib/actions/page/scroll-to.ts
+export const scrollTo = defineAction({
+ name: 'page.scrollTo',
+ description: 'Scroll the page to an element, an absolute position, or by one viewport.',
+ input: z.object({ target: targetSchema.optional(), /* … every field .describe()d */ }),
+ execute({ target, position, direction, behavior }) { /* the side effect */ },
+});
+```
+
+One action per module under `lib/actions/page/`:
+
+| Action | Effect |
+| --- | --- |
+| `page.getPageInfo` | Snapshot: metadata, viewport/scroll, **semantic layout tree + text diagram**, heading outline, inventory of links/buttons/fields/forms with stable selectors |
+| `page.scrollTo` | Scroll to an element, a position, or by a viewport (`up`/`down`/`top`/`bottom`) |
+| `page.clickElement` | Realistic click (pointer/mouse sequence + native `.click()`) |
+| `page.hoverElement` | Pointer/mouse hover sequence to trigger menus & tooltips |
+| `page.focusInput` | Focus an element and place the caret (`start`/`end`/`all`) |
+| `page.fillInput` | Type into an input/textarea/contenteditable (React/Vue-compatible), optional Enter |
+| `page.selectOption` | Choose a `<select>` option by value, label, or index |
+| `page.selectText` | Select an element's text, or the nth match of a phrase (spans inline markup) |
+| `page.extractText` | Read rendered text or HTML of an element or the page |
+| `page.pressKey` | Send a key with modifiers, with Enter-to-submit emulation |
+| `page.submitForm` | Submit a form via `requestSubmit()` (runs validation) |
+| `page.waitForElement` | Await `attached`/`visible`/`hidden`/`detached`, with timeout |
+| `page.highlightElement` | Flash a temporary overlay on an element |
+| `page.navigate` | Open a URL, or go `back`/`forward`/`reload` |
+| `page.screenshot` | Capture the tab (full scroll view, viewport, or a targeted element) as a PNG/JPEG — stitched in the background worker; optionally saved under `~/voicelink/screenshot/` and returned as an image the agent can see |
+| `page.listFiles` | List the user's files stored in VoiceLink, with their AI-generated summaries (resolved in the background from extension storage) |
+| `page.attachFile` | Attach a stored file (by id) to a page's `<input type="file">` — the background reads the bytes, the page sets `input.files` via a `DataTransfer` |
+
+**Targeting** is shared and declarative — most actions take a `target: { selector?, text?, role?, nth? }`, resolved by [`resolveTarget`](lib/actions/page/dom.ts) (visible elements only; text matches the innermost accessible element).
+
+### Calling actions
+
+```ts
+import { invokeInActiveTab } from '@/lib/actions/client';
+import { fillInput } from '@/lib/actions/page/fill-input';
+
+// Fully typed from the action's schema; returns { ok: true, data } | { ok: false, error }
+const res = await invokeInActiveTab(fillInput, { target: { text: 'Email' }, value: '[email protected]' });
+```
+
+- [`client.ts`](lib/actions/client.ts) — `invokeInTab` / `invokeInActiveTab`, typed end-to-end (input is compile-time required when the schema needs it).
+- [`host.ts`](lib/actions/host.ts) — `exposeActions()`, run by the content script ([content.ts](entrypoints/content.ts)), dispatches actions in the page.
+- [`dispatch.ts`](lib/actions/dispatch.ts) — validates input and returns the `{ ok }` envelope; unknown actions and bad input are structured failures, never throws.
+
+### The MCP harness (`mcp/`)
+
+[`@voicelink/mcp`](mcp/) turns the same registry into an MCP server, so Claude Code (or any MCP client) can drive the browser. It ships two binaries:
+
+| Binary | Role |
+| --- | --- |
+| `voicelink-mcp` | MCP server on stdio — what an MCP client spawns. Starts the daemon if needed. |
+| `voicelink-mcpd` | The daemon: a loopback WebSocket server on `127.0.0.1:8765` (falling back to 8766/8767) |
+
+```sh
+npm run mcp:install # one-time: install the package's own dependencies
+npm run mcp:build # → mcp/dist/
+npm run mcp:link # one-time: put `voicelink-mcp` on your PATH
+npm run mcp:manifest # print the tool manifest (no browser needed)
+
+claude mcp add voicelink -- voicelink-mcp
+```
+
+`mcp:link` runs `npm link`, symlinking both binaries into your npm prefix — rebuilds are picked up automatically, and `npm run mcp:unlink` removes them. Without it the CLI still works as `node mcp/dist/cli.js`, but every command below (and the hints the daemon prints) assumes the linked name.
+
+```
+Claude Code ──stdio──> voicelink-mcp ──ws(control)──┐
+ ▼
+ voicelink-mcpd (127.0.0.1:8765)
+ ▲
+ ws(extension, Origin-pinned)
+ │
+ background.ts ──> content script ──> execute()
+```
+
+The extension dials **out** to the daemon because an MV3 service worker cannot listen for connections. One daemon owns the browser link, so several MCP clients can share one browser.
+
+**Tool parity is structural.** The daemon bundles [`describeActions()`](lib/actions/registry.ts) from this repo, so `tools/list` *is* the registry — 17 page tools plus `voicelink_status`. Dots are illegal in MCP tool names, so `page.clickElement` is exposed as `page_clickElement` ([tool-names.ts](lib/actions/tool-names.ts) round-trips the mapping and refuses collisions). On connect both sides exchange a hash of their manifest ([manifest.ts](lib/actions/manifest.ts)); if an installed extension was built from a different registry the daemon adopts the browser's list and emits `tools/list_changed`.
+
+Three read-only resources avoid spending a tool call on page context: `voicelink://page/current` (full snapshot), `voicelink://page/diagram` (the layout diagram alone — the cheapest useful view), and `voicelink://page/text`.
+
+### Pairing — agent control is off until you turn it on
+
+A freshly installed extension connects to nothing. It dials the daemon only after you redeem a one-time code, so no agent can drive the browser without an explicit, deliberate act:
+
+```sh
+voicelink-mcp pair # prints e.g. PQC3-3RQ7 (single use, expires in 10 min)
+```
+
+Then open the VoiceLink popup, paste the code, and press **Connect**. The daemon consumes the code and issues a long-lived session key that the extension stores; it survives service-worker teardown, daemon restarts, and browser restarts, and dies only when you revoke it.
+
+```sh
+voicelink-mcp sessions # which browsers are paired, and which is live
+voicelink-mcp revoke # unpair everything (or pass one origin)
+voicelink-mcp status # daemon + extension state
+voicelink-mcp tools # the bundled manifest
+voicelink-mcp logs # ~/.voicelink/daemon.log
+voicelink-mcp stop
+```
+
+**How the daemon decides who may connect.** Any web page can open a WebSocket to loopback, so there are two independent gates:
+
+1. *At the HTTP upgrade*, by handshake `Origin`. Browsers set `Origin` themselves and pages can neither forge nor omit it, so the branches are mutually exclusive: an extension origin takes the extension path, `http(s)` origins get a flat 403, and a header-less local process (the CLI, the stdio server) must present the token from the `0600` lockfile. A web page can never reach the control path.
+2. *In the `hello` frame*, by credential. Reaching the extension door proves only that you are **an** extension — a pairing token or a valid session key proves you are **the paired** one. Credentials travel in the frame rather than the URL (the browser `WebSocket` API cannot set headers), so they never land in a log or a process list.
+
+Session keys are bound to the origin that paired them, pairing codes are consumed on first use, and revoking drops any live connection immediately. State lives in `~/.voicelink/auth.json` (`0600`), separate from the lockfile so shutting the daemon down never unpairs your browser.
+
+> The token gates *which browser*, not *which local process*. Anything running as your user can read the lockfile and drive an already-paired browser — that is the real perimeter. And a paired agent reading a malicious page is still susceptible to prompt injection; pairing controls access, not intent.
+
+Extension-page callers still use the in-process bridge on [background.ts](entrypoints/background.ts) (`{ channel: 'voicelink/bridge', op: 'describe' | 'invoke' }`); both routes share [`invokeForHarness`](lib/bridge/invoke.ts).
+
+### Adding an action
+
+Create `lib/actions/page/<name>.ts` exporting a `defineAction({ name: 'page.<name>', … })`, then add it to the array in [registry.ts](lib/actions/registry.ts). Keep every input field `.describe()`d and validate at runtime with `throw new ActionError(msg, 'CODE')` (no zod `.refine`/`.transform`, so schemas stay JSON-Schema-clean).
+
+## Local state & what never reaches the repo
+
+Everything the daemon persists lives under `~/.voicelink/`, outside the working tree:
+
+| Path | Contents |
+| --- | --- |
+| `~/.voicelink/auth.json` (`0600`) | Pairing session keys, bound to the extension origin that redeemed them. Survives daemon restarts; cleared by `voicelink-mcp revoke`. |
+| `~/.voicelink/daemon.json` | The lockfile — port and the control-client bearer token. Deleted on shutdown, so it is deliberately *not* where pairing state is kept. |
+| `~/.voicelink/daemon.log` | Run starts/finishes, routed skill, every tool call — `voicelink-mcp logs`. |
+| `~/.voicelink/config.json` | Optional: `claudeBin`, `requireApproval`. |
+| `~/.voicelink/skills/` | Optional user skills that override the bundled ones by name. |
+
+There are **no credentials in this repository and none to add** — the agent runs on your existing
+Claude Code login, and speech goes through the browser's built-in recognition. `.gitignore` still
+guards the paths above (plus `.env*`, key material, and the `mcp/bin/` + `mcp/lib/` symlinks that
+`npm run mcp:link` creates) so a stray copy of any of them cannot be committed by accident.
+
+## Notes
+
+- The manifest is generated by WXT from `wxt.config.ts` — edit permissions/name there, not in `dist/`.
+- Popup and side panel follow the system light/dark preference (`.dark` class toggled in each `main.tsx`).
+- The dark-launch Chrome profile used by `npm run dev` is throwaway; see [WXT's browser startup docs](https://wxt.dev/guide/essentials/config/browser-startup.html) to customize it.