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 skill uploads, site mapping, and the fast path

Shahriar00bfd9c3acb3
diff --git a/.claude/skills/voicelink/SKILL.md b/.claude/skills/voicelink/SKILL.md
index d24bf66..1634baa 100644
--- a/.claude/skills/voicelink/SKILL.md
+++ b/.claude/skills/voicelink/SKILL.md
@@ -110,5 +110,7 @@ You (an external MCP client) are not the only thing that can drive this browser.
- **Two drivers, one tab.** If a run is active while you act, you are interleaving with it. Tool calls stay correct (ids are correlated) but the page state can shift under either of you. `voicelink-mcp logs` shows agent runs starting and finishing.
- **Runs are gated, you are not.** Agent-run invocations pass an approval gate (`requireApproval` in `~/.voicelink/config.json`) and appear on the user's timeline; direct MCP invocations do neither. Do not assume something the agent was denied is something you should do instead.
-- **Skills live in `mcp/skills/*.md`** (user overrides in `~/.voicelink/skills/`, hot-reloaded per run). Front-matter routes by trigger words; `@name` prefix forces one. When asked to change how the in-extension agent behaves, that markdown — not this file — is usually the place.
+- **Skills live in `mcp/skills/*.md`**, with hand-written overrides in `~/.voicelink/skills/` and extension uploads in `~/voicelink/skills/`; all three are hot-reloaded per run and a later directory shadows an earlier one by name. Front-matter routes by trigger words; `@name` prefix forces one. A `category: site-exploration` skill is an overlay instead of a base — it stacks on top of the routed skill whenever the tab's host matches its `domains`. Skills load in two forms: flat `<name>.md` and `<name>/SKILL.md`. `voicelink-mcp skills` prints what the router can see.
+- **Site maps are generated skills.** `@site-mapper map this site` runs a read-only, host-locked crawl that writes `<name>/SKILL.md` plus screenshots into `~/voicelink/skills/`, staged under `.staging/` until the user activates it in the panel. A mapping run refuses anything that changes a page (`MAPPING_READ_ONLY`), anything off the mapped host (`MAPPING_OFF_SITE`) and relative or history navigation; it is pinned to one tab (`MAPPING_TAB_CHANGED`). Mapping mode requires the explicit `@site-mapper` prefix — trigger words alone will not start one. When asked to change how the in-extension agent behaves, that markdown — not this file — is usually the place.
+- **Not every instruction becomes a run.** A local intent funnel (`lib/intent/`) scores each utterance first, and confident single-step commands — back, reload, scroll down, open github.com, press enter, click Sign in — run in the extension itself. Those never touch the daemon, so they leave no trace in `voicelink-mcp logs` and never appear as agent runs; on the user's timeline they carry a ⚡. If a user reports "it did the thing but nothing shows in the log", that is this, not a failure. `npm run intent:check -- "<what they said>"` explains any single routing decision.
- **Debugging a run**: `NO_CLAUDE` means Claude Code is not on the daemon's PATH (set `claudeBin` in config.json); `RUN_IN_PROGRESS` means one instruction at a time; `RUN_INACTIVE` on a tool means the run was cancelled mid-call. Everything else lands in the daemon log.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8b874f0..b3e2212 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,8 @@ VoiceLink is an AI voice assistant Chrome extension (Manifest V3) built with WXT
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 compile # type-check only (tsc --noEmit)
+npm run intent:check # route the fixture table through lib/intent/ in plain Node; the only assertion-style check
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/
@@ -44,6 +45,8 @@ Docs and daemon-printed hints all use the bare `voicelink-mcp` name, so `mcp:lin
`npm run compile` depends on generated types in `.wxt/` — run `npm install` (its postinstall runs `wxt prepare`) if they're missing.
+`npm run intent:check` bundles `lib/intent/` with esbuild (already present via Vite; no new dependency) and runs it in Node against a fixture table of utterances, printing the threshold's headroom. There is no lint step and no other test runner. `npm run intent:check -- "<utterance>"` explains a single routing decision.
+
## Architecture
### WXT conventions
@@ -77,7 +80,7 @@ Call path: side panel / bridge → `invokeForHarness` → `browser.tabs.sendMess
- **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`.
+- **The wire protocol is v5** (`SOCKET_PROTOCOL_VERSION`): on top of the v1 request/reply frames, the extension may send `instruct`/`cancel`/`decision`/`reset`/`analyzeFile`/`saveSkill`/`deleteSkill`/`deleteSiteMap`/`activateSiteMap`/`discardSiteMap` unprompted, and the daemon streams `run` and `siteMapDraft` frames back. Any new extension-initiated frame must also be listed in `EXTENSION_REQUEST_FRAMES` — `isExtensionRequest()` keys on it, and a frame missing from that list is silently dropped by `ExtensionLink.receive` rather than erroring. `assertToolNamesRoundTrip` aside, protocol bumps require rebuilding both sides *and* reloading the extension — an older 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.
@@ -88,11 +91,37 @@ The reverse direction of the MCP harness: a free-text instruction typed (or spok
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`.
+- **Skills are markdown system prompts**, read from three directories on every run, each shadowing the last by name: `mcp/skills/*.md` (bundled, in git) → `~/.voicelink/skills/` (hand-written) → `~/voicelink/skills/` (uploaded from the extension; machine-managed, so the daemon only ever writes here). Front-matter: `name`, `description`, `triggers: [...]`, `default: true`, `category`, `domains: [...]`. The format's parser *and* serializer live in `lib/skills/format.ts`, shared by both ends — it must stay import-free so it loads in a worker and in bare Node.
+- **Category decides base vs overlay.** A `general` skill is the **base** prompt and competes on trigger hits (`@name` wins, else most hits, else `default: true`). A `category: site-exploration` skill is an **overlay**: never a base, forced `isDefault: false`, and applied on top of the base whenever the active tab's host matches its `domains` (suffix on a dot boundary, so `acme.com` covers `www.acme.com`). `@name` on one pins it regardless of host. The host comes from `instruct`'s `context.url` — URL only; a page controls its own title, so nothing else about the page reaches the system prompt. `buildSystemPrompt(base, overlays)` composes them under a frozen precedence line.
+- **The prompt is one argv element.** `--append-system-prompt` takes the whole thing, and Linux caps a single argument at 128 KB — hence the 32 KB body and 64 KB prompt caps in `format.ts`/`prompt.ts`. Over the budget, whole overlays are dropped with a log line rather than truncated mid-sentence.
+### Site mapping (`mcp/src/agent/{sitemap,mapping,site-map-store}.ts`)
+
+`@site-mapper map this site` (or the panel's Map button) crawls the current site and writes a site-exploration skill for it. The shape is three jobs at three privilege levels:
+
+- **Phase A — the sitemap** is plain Node in `sitemap.ts`, no model. It is where all the hostile-input handling lives, because the URLs come from a file the mapped site controls: `redirect: 'manual'` with per-hop scheme/host/**resolved-IP** validation (following only the final URL misses an SSRF bounce through `169.254.169.254`), the port pinned to the seed origin, DNS resolved once and reused (rebinding), streaming reads with a running byte counter (`content-length` is written by the peer), and `gunzipSync(..., { maxOutputLength })` (a 4 MB archive of zeros is gigabytes). It yields URL *patterns*, which no 12-page crawl can infer.
+- **Phase C — the crawl** is the ordinary run loop under four daemon-enforced gates in `mapping.ts`: a read-only allowlist, absolute same-origin `page.navigate` only (relative URLs are *rejected*, not resolved — the daemon would resolve against the mapped origin while [navigate.ts](lib/actions/page/navigate.ts) resolves against `location.href`), no `back`/`forward` (they name no URL and walk the user's real history), and a screenshot budget whose destination the daemon allocates. Plus an off-site latch read from `getPageInfo`'s `document.url` after every snapshot, and `tabId` pinning, since [invoke.ts](lib/bridge/invoke.ts) otherwise re-resolves the active tab on every call.
+- **Mapping mode turns on run identity, never front matter**: `routed.base.name === 'site-mapper' && source === 'bundled'`, and only with an explicit `@site-mapper` prefix. `~/.voicelink/skills` is parsed with no key allowlist, so a skill that could name its own privileges would be granting them to itself — and trigger scoring plus continuous voice input would otherwise let an overheard phrase start a ten-minute crawl.
+- **The agent's only persistence channel** is the reserved action `voicelink.saveSiteMap`, intercepted in `invokeForRun`. No wire work was needed: `actionNameFor` replaces only the *first* underscore, so `voicelink_saveSiteMap` already maps to it, and `server.ts`'s CallTool fall-through routes it with the run id attached. The tool is advertised only when `VOICELINK_AGENT_RUN` is set, and `daemon.invoke` refuses the whole `voicelink.` namespace, so an untagged MCP client cannot reach it.
+- **The report is typed, never markdown.** `renderSiteMapBody()` owns every heading; `validateSiteMapReport` flattens and caps every leaf (`lib/skills/site-map.ts`) with a ~3 KB total authored budget on top of the 12 KB body cap, re-parses each path against the mapped origin, and honours a screenshot reference only when the daemon actually wrote that file.
+- **Quarantine is a filesystem fact.** A map in flight lives under `<skillsDir>/.staging/<uuid>/`, and `readDir` skips dot-prefixed entries — so an unreviewed map is not merely unrouted, it is never opened. Activation is a directory rename. `requireApproval` could not serve as the gate: [run-timeline.tsx](components/run-timeline.tsx) renders the action name and a clipped summary, never `input`.
+- **Skills now load in two forms**: `<name>/SKILL.md` (what a map generates, since it needs somewhere for screenshots) and flat `<name>.md`; a flat file wins a collision and the collision is logged. `deleteSkill` removes only the flat file — a map has its own `deleteSiteMap` op, so removing a same-named upload cannot take a map's screenshots with it.
+- **Uploads: the extension's storage is the library, the disk is a projection.** `lib/bridge/skill-store.ts` holds the records (`storage.local`, index and bodies split like `file-store.ts`); `saveSkill` sends *structured fields*, never finished markdown, so the daemon composes the front matter and an upload can never set a key it was not offered — `serializeSkillFile` flattens every value to one line, which is what stops a newline in a description from smuggling in `default: true`. On reconnect the worker re-pushes only records that are not yet `saved`. `voicelink-mcp skills` lists what the router can actually see.
- **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`.
+### The local intent funnel (`lib/intent/`, `lib/bridge/fast-path.ts`)
+
+Every instruction — spoken or typed, popup or side panel — reaches `instruct()` in `run-port.ts`, and the local grammar gets first refusal before anything is sent to the daemon. A confident single-step command (back, reload, scroll down, open github.com, press enter, click Sign in) runs straight through `invokeForHarness` in the background worker; everything else escalates as an ordinary agent run with the text untouched.
+
+- **Scoring, not keyword matching.** `routeIntent()` = `normalize()` (strip openers/trailers, repair spoken domains, drop punctuation) → match the anchored `RULES` in `grammar.ts` → `rule.certainty × slot.confidence`, best match wins, must clear `ACT_THRESHOLD` (0.75). Certainty rates the *shape*, confidence rates the *slot* — which is what separates "click Sign in" (0.9) from "click it" (0.495). Nothing else scores below the threshold today, so the band is wide and new rules have room.
+- **Patterns are anchored at both ends**, so a quick command must be the whole utterance. That is why there is no partial-match/coverage term: anything with a tail simply does not match and escalates.
+- **The bias is toward escalating**, because the two errors are not symmetric — a needless escalation costs a round trip, a wrong local action spends a real click on the user's page. Hard stops (before any rule is tried): questions, `and then`-style multi-step, conditionals, `@skill` prefixes; and after matching, consequential labels (`CONSEQUENTIAL` in `grammar.ts`) escalate so the agent's **approval gate** sees them — a local invocation has no gate and no confirmation.
+- **A failed local action escalates too**, and its failed row stays on the timeline. `TARGET_NOT_FOUND` on "click Sign in" is exactly the case an agent that can snapshot the page handles better.
+- **Local steps are marked.** `RunEvent`'s tool variant carries `source?: 'local'` (never set by the daemon); the timeline draws a ⚡ and the summary reports elapsed ms.
+- **Adding a rule** means one entry in `RULES` plus fixtures in `scripts/check-intent.mjs` — in **both** directions, one utterance the rule should catch and one near-miss it must not. Run `npm run intent:check`. Keep `lib/intent/` free of `browser.*` and DOM: it is bundled and run in bare Node by that check.
+- Local runs never reach `~/.voicelink/daemon.log`, so "the command worked but the daemon log is empty" is the fast path, not a bug.
+
### 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:
@@ -108,6 +137,6 @@ One module per action: `lib/actions/page/<name>.ts` exporting `defineAction({ na
## 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`.
+- **Chat responses:** real — the side panel's composer sends instructions through the agent harness (see above); replies and tool activity stream back into `RunTimeline`. Quick commands never get that far: the local intent funnel answers them in the browser (see above).
- **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
index 552769d..9fd8c02 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,7 @@ 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 intent:check # route a fixture table of utterances through lib/intent/
npm run icons # regenerate placeholder icons in public/icon/
```
@@ -51,12 +52,15 @@ To load the production build manually: `chrome://extensions` → enable **Develo
| 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) |
+| Intent funnel | `lib/intent/` | Scores each instruction first; confident quick commands run in the browser instead of becoming a run (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/intent/ # the local intent funnel — quick commands the extension answers itself
lib/bridge/ # extension side of the harness (daemon socket, invoke path, speech hooks)
+lib/skills/ # the skill file format — parser + serializer, shared with the daemon
mcp/ # the installable MCP server + daemon
mcp/skills/ # markdown system prompts the daemon routes instructions to
lib/utils.ts # cn() helper
@@ -79,6 +83,87 @@ Type an instruction into the side panel (or the popup) of a paired browser and t
Requires [Claude Code](https://claude.com/claude-code) on your PATH (or `{"claudeBin": "/path/to/claude"}` in `~/.voicelink/config.json`).
+### Site notes — teaching it about one site
+
+The bundled skills are general: how to drive any page, how to read any page. What they cannot know is how *your* sites work. Open the book icon in the side panel's composer and upload a markdown file of notes — where things are, how a list loads, what a button is really called — tagged with the domains it applies to:
+
+```markdown
+---
+name: acme-admin
+description: Our internal admin tool.
+category: site-exploration
+domains: [admin.acme.com]
+---
+
+Search is `#q` and submits on Enter, not on the button.
+Results lazy-load — click "Load more" until it disappears before counting anything.
+```
+
+Uploaded skills are **overlays**, not replacements: on a matching site the notes are added *on top of* whichever skill routing picked, so `browser-control`'s driving loop and `page-research`'s read-only rules still apply. Off that site they are inert. `@acme-admin …` pins one on regardless of where you are.
+
+They are written to `~/voicelink/skills/` (override with `skillsDir` in `config.json`) — outside the repo, never committed, and re-read on every run so an edit takes effect on the next thing you ask. The extension keeps its own copy, so an upload made while the daemon was down lands when it comes back. `voicelink-mcp skills` lists everything the router can see and where it came from.
+
+### Mapping a site automatically
+
+Rather than writing those notes yourself, press **Map** in the Skills panel (or say `@site-mapper map this site`). VoiceLink reads the site's own `robots.txt`/`sitemap.xml`, looks up public background on the domain, then walks the site for a few minutes — screenshotting as it goes — and writes the skill for you:
+
+```
+~/voicelink/skills/acme-com/
+├── SKILL.md the routed skill: landmarks, pages, how they connect, quirks
+├── map.json the structured report behind it
+├── screenshots/ captures taken during the crawl
+├── evidence/ the raw sitemap and background it worked from
+└── pages/ longer per-page notes, kept out of the prompt
+```
+
+**Nothing takes effect until you say so.** The map is written to a staging directory the skill loader cannot see, and the panel shows you the exact markdown — literally, never rendered — with the domain it will match and where it landed. Activate arms it; Discard bins it.
+
+The crawl is **read-only and locked to one host**: it cannot click, fill, or submit (set `siteMap.allowClicks` if you want clicking), it cannot leave the site, and it is pinned to the tab it started in, so switching tabs mid-crawl stops it rather than following you. Bounds live in `config.json`:
+
+```json
+{ "siteMap": { "research": true, "allowClicks": false, "maxPages": 15, "maxScreenshots": 10, "timeoutMs": 600000 } }
+```
+
+> A mapped skill is written from pages the agent read, so treat it as you would any generated content — read it before activating. `research: true` lets the mapping run use web search, which is the one place a run both reads pages and can make outbound requests; set it to `false` to keep the run entirely inside the browser.
+
+## The fast path — what never reaches the agent (`lib/intent/`)
+
+"Go back." "Scroll to the top." "Open github.com." Sending those out to the daemon to be spawned
+as a Claude Code run costs a socket round trip and a few seconds of thinking to arrive at a tool
+call the extension could have made in milliseconds. So every instruction — typed or spoken, popup
+or side panel — first passes through a **local intent funnel** in the background worker.
+
+[`routeIntent()`](lib/intent/route.ts) normalizes the utterance ("Hey VoiceLink, could you scroll
+down a bit please?" → `scroll down`), matches it against a fixed grammar of quick commands, and
+scores the best match as `rule certainty × slot confidence`. Clear the threshold (0.75) and the
+extension runs the action itself and stops there; otherwise the untouched original text goes to the
+agent exactly as before. Steps taken locally appear on the timeline like any other, marked ⚡ and
+timed, so it is always visible which path handled a request.
+
+The funnel is biased toward escalating, because the two mistakes are not symmetric: escalating
+something it could have handled costs a round trip, while acting on something it misread spends a
+wrong action on your real page. Questions, multi-step asks, conditionals, consequential clicks
+("click Buy now"), vague targets ("click it") and anything the grammar does not recognize all go to
+the agent — as does any quick command that *runs and fails*, since a "Sign in" button the grammar
+could not find is exactly what an agent that can look at the page does better.
+
+| Handled locally | Sent to the agent |
+| --- | --- |
+| back / forward / reload | "is there a login button?" |
+| go to github.com · open gmail · open localhost:3000 | "open the settings menu" |
+| google &lt;something&gt; · search the web for &lt;something&gt; | "search for wireless headphones" |
+| scroll up/down/top/bottom · page down · scroll to the reviews | "scroll down and tell me what it says" |
+| press enter · hit escape · press arrow down | "click sign in and then fill in my email" |
+| click Sign in · tap Continue · click the Next button | "click Buy now" · "click it" |
+
+`npm run intent:check` routes a table of utterances through the funnel in plain Node and reports
+where the threshold sits relative to the best case it rejects and the worst it accepts — that table
+is where the threshold is tuned. Pass an utterance to see one decision explained:
+
+```sh
+npm run intent:check -- "take me to the checkout page"
+```
+
## Voice input
Dictation is live, on the browser's own **Web Speech API** (`webkitSpeechRecognition`) — Chrome
@@ -204,6 +289,7 @@ 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 skills # every skill the router can reach, and where it came from
voicelink-mcp logs # ~/.voicelink/daemon.log
voicelink-mcp stop
```
@@ -232,8 +318,10 @@ Everything the daemon persists lives under `~/.voicelink/`, outside the working
| `~/.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. |
+| `~/.voicelink/config.json` | Optional: `claudeBin`, `requireApproval`, `screenshotDir`, `skillsDir`. |
+| `~/.voicelink/skills/` | Optional hand-written skills that override the bundled ones by name. |
+| `~/voicelink/skills/` | Skills uploaded from the extension. Machine-managed — the daemon writes and deletes only here, so nothing hand-written is ever clobbered. |
+| `~/voicelink/screenshot/` | Where `page.screenshot { save: true }` writes. |
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