agent-wire-cli 0.2.4__tar.gz → 0.2.5__tar.gz

agent_wire_cli-0.2.5/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "agent-wire",
+  "description": "Agent Wire by uncoalesced: live web, search and platform reads for AI agents from one local MCP server, compressed and shielded against prompt injection.",
+  "owner": {
+    "name": "uncoalesced"
+  },
+  "plugins": [
+    {
+      "name": "agent-wire",
+      "source": "./plugin",
+      "description": "Live web, search and platform reads for agents, compressed and shielded against prompt injection."
+    }
+  ]
+}

{agent_wire_cli-0.2.4 → agent_wire_cli-0.2.5}/.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install
         run: uv sync --extra dev --locked
       - name: Ruff lint
-        run: uv run ruff check src tests .github/scripts
+        run: uv run ruff check src tests
       - name: Ruff format
         run: uv run ruff format --check .
       - name: No temp-dir writes in the package
@@ -109,8 +109,6 @@ jobs:
           out=$(uvx --python ${{ matrix.python }} --from "$whl" wire run -e "return 6 * 7")
           echo "$out"
           grep -q '^42$' <<<"$out"
-      - name: MCP server over stdio (both modes)
+      - name: Self-test (every subsystem, MCP over stdio in both modes, no network)
         shell: bash
-        run: >-
-          uv run --isolated --no-project --python ${{ matrix.python }}
-          --with "$(ls dist/*.whl)" python .github/scripts/mcp_smoke.py
+        run: uvx --python ${{ matrix.python }} --from "$(ls dist/*.whl)" wire selftest

{agent_wire_cli-0.2.4 → agent_wire_cli-0.2.5}/.github/workflows/release.yml

@@ -27,6 +27,7 @@ jobs:
           test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v$v"; exit 1; }
       - run: uv sync --extra dev --locked
       - run: uv run pytest -q
+      - run: uv run wire selftest
       - run: uv build
       - run: uvx twine check --strict dist/*
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2

agent_wire_cli-0.2.5/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to agent-wire (`agent-wire-cli` on PyPI, the `agent-wire` Claude plugin).
+
+## 0.2.5 (2026-11-15)
+
+### Added
+- **`wire selftest`.** Checks every subsystem in one offline run, and a guard fails the run on any network attempt. It covers:
+  - all 31 channels, on canned responses
+  - the inbound and outbound firewalls, and the SSRF guard
+  - Shield Alerts and the alert ledger
+  - compression, the delta buffer and the route ledger
+  - the cookie vault and Code Mode
+  - research and `wire_cite`
+  - the 11 client installers
+  - the MCP server, in-process and over stdio
+
+  `--live` adds one real request per channel (Reddit with no API key) and counts shield false positives on the 16 README benchmark pages. `--only` and `--json` narrow and format the run. CI and the release workflow run the offline check.
+- **Shield Alerts.** Stripped hidden prompt injections, forged delimiters and refused outbound requests are reported to you out of band: a desktop notification, a stderr line, and a trusted `[WIRE SHIELD | ...]` line ahead of the quoted content. Alerts are kept in a hash-chained `alerts.db`. New commands: `wire alerts`, `show`, `tail`, `verify`, `demo`.
+- **Root policy documents:** `PRIVACY.md`, `TERMS.md`, `DOCUMENTATION.md`, `SUPPORT.md`.
+
+### Changed
+- **The Claude plugin now lives in `plugin/`.** It launches the published package with `uvx agent-wire-cli==0.2.5 serve`.
+  - Optional credentials come from the plugin's `userConfig`, marked sensitive. Each one is sent only to its own service.
+  - The plugin never shells out to `gh`.
+- **`WIRE_HOME` prefers `CLAUDE_PLUGIN_DATA`,** so plugin updates keep your data.
+- **`rookiepy` is now the `[browser-cookies]` extra,** and `wire_status` no longer looks at browser profiles.
+- **Server tool descriptions describe the tools only.** When-to-use guidance stays in the skill, whose description no longer tells the model to act "automatically".
+- **Setting a transcription API key turns transcription on.** This is what the plugin's `transcribe_api_key` option implied all along. `WIRE_TRANSCRIBE=0` still turns it off.
+- **Token counting falls back to an approximation** when the tokenizer file can't be downloaded on first run, so reads keep working offline.
+- **The lock moves dnspython to 2.9.2 and opentelemetry-api to 1.45.2** (CVE-2026-128089, CVE-2026-126360; both are transitive dependencies through fastmcp).
+- **`joserfc>=1.8.0` is required** (GHSA-jpxq-7h8p-2q76, GHSA-9pg5-8c7x-5hfx). agent-wire itself never parses JWS or JWE.
+- **The HTTP/SSE transport binds `127.0.0.1` explicitly.**
+
+### Fixed
+- **Hidden-text stripping now catches:**
+  - text hidden by the page's own stylesheet (`.x{display:none}`, `#id{visibility:hidden}`)
+  - text hidden by the `sr-only`, `visually-hidden`, `hidden` and `d-none` classes
+  - text hidden with `clip`, `clip-path`, a transparent color, or off-screen `top`/`right`/`margin`
+- **Invisible characters written as HTML entities** (`󠁁`, `​`) are now removed after parsing.
+
+### Measured
+- **Attack corpus:** 12 of 12 hiding techniques detected and stripped.
+- **Benign corpus:** 0 alerts across 9 cases.
+- **`wire selftest --live`, 2026-11-15:**
+  - **Benchmark pages:** none raised an alert, over two runs (16 of 16 read on the first; on the second, the Cloudflare challenge page needed the stealth browser, so 15 were read).
+  - **Channels:** 26 of 31 answered with no keys or logins, including Reddit.
+  - **Skipped (5):**
+    - Zhihu and Boss Zhipin need a login or the stealth browser.
+    - TikTok's oEmbed refused the probe.
+    - Xiaohongshu and Xiaoyuzhou have no stable public URL to probe.
+
+## Earlier releases
+
+See the [GitHub releases page](https://github.com/uncoalesced/agent-wire/releases).

agent_wire_cli-0.2.5/DOCUMENTATION.md

@@ -0,0 +1,112 @@
+# Agent Wire documentation
+
+Agent Wire by uncoalesced is a local MCP server that gives AI agents live web pages, web search and platform reads. On PyPI it's `agent-wire-cli`, the shell command is `wire`, and the Claude plugin is `agent-wire`. The [README](README.md) covers the same ground with benchmarks and background; this page is the reference.
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/).
+
+- **Claude Code plugin:** `/plugin install agent-wire --marketplace uncoalesced/agent-wire`. It starts `uvx agent-wire-cli==<version> serve` and asks for optional keys when you enable it.
+- **Any other client:** `uvx agent-wire-cli install --client auto` finds the agent clients on your machine (Claude Code, Claude Desktop, Codex, Cursor, Windsurf, VS Code, Roo, Gemini CLI, Hermes, Antigravity, Peridot), shows what it will write, and asks first. `--client <name>`, `--dry-run`, `--global` and `--project PATH` narrow it down.
+- **By hand:** run `uvx agent-wire-cli serve` as a stdio MCP server.
+
+Optional extras: `agent-wire-cli[stealth]` (headless browser for Cloudflare-protected pages and the `wire auth login` window), `agent-wire-cli[browser-cookies]` (import a login from Chrome, Edge or Brave), `agent-wire-cli[local-whisper]` (local podcast transcription).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `wire_read(urls, query, section, include_comments, max_tokens, force)` | Reads up to 10 URLs. `query` keeps the parts that answer it; `#L10-L50` and `#heading` anchors work. A page read again returns only what changed. |
+| `wire_search(query, platforms, limit, sort, auto_expand_top, max_tokens)` | Searches the web or specific platforms and reads the top hits in the same call. |
+| `wire_feed(platform, target, sort, limit)` | A subreddit, an `@user` timeline, GitHub trending, an arXiv category, a stock watchlist, an RSS feed. |
+| `wire_me(platform, target, limit)` | Your own posts, likes, bookmarks, notifications or stats, through a session you saved. |
+| `wire_research(topic, days, ...)` | One cited brief of what people said about a topic in the last N days, an "A vs B" comparison, or what's trending. |
+| `wire_cite(text, check_quotes)` | Opens every link in a text and reports dead, archived-only, bot-blocked and soft-404 pages, quotes missing from their page, and `[[UNSOURCED]]` claims. |
+| `wire_run(code, max_tokens)` | Code Mode: one sandboxed JavaScript script that calls `wire.read/search/feed/research/cite` and returns only what the script returns. |
+| `wire_status(refresh)` | Channels, saved logins, route cache and alert counts. |
+
+Every result starts with a `[WIRE | ...]` line, then any `[WIRE SHIELD | ...]` alert lines, then the page content inside an `[UNTRUSTED_EXTERNAL_DATA]` block. Everything inside that block is quoted material from the web, not instructions.
+
+How an agent should use the tools (when to call each one, citation rules) is in the skill and rule files the installer writes: [`skills/agent-wire/SKILL.md`](skills/agent-wire/SKILL.md), and the Cursor, Windsurf and Hermes files in [`manifests/`](manifests/).
+
+## Logins
+
+Most sites need no login. For your own account (`wire_me`) and login-only sites:
+
+- `wire auth login <site>` opens a login window (needs the `[stealth]` extra) and saves that site's cookies to an encrypted vault.
+- `wire auth login <site> --from-browser` copies that one site's cookies from a browser you're signed in to. Firefox works out of the box; Chrome, Edge and Brave need `[browser-cookies]`.
+- `wire auth list` shows saved sites (names only); `wire auth logout <site>` forgets one.
+
+A saved login is sent only to its own site, only on GET or HEAD requests, never to account pages such as messages, settings or billing, and never across a redirect.
+
+## Configuration
+
+| Setting | Effect |
+|---|---|
+| `WIRE_HOME` | Where agent-wire keeps its files. The Claude plugin uses its plugin data folder. |
+| `GITHUB_TOKEN` | Higher GitHub rate limits and `wire_me github`. Outside the plugin, `gh auth token` is used if set up; `WIRE_NO_GH_CLI=1` turns that off. |
+| `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` | Reddit's official app login, for networks where anonymous access is blocked. |
+| `WIRE_SEARXNG_URL`, `EXA_API_KEY` | Extra web search engines. |
+| `WIRE_TRANSCRIBE=1` (+ `WIRE_TRANSCRIBE_API_KEY`, `_URL`, `_MODEL`) | Podcast transcription, locally or through an OpenAI-compatible API. Setting `WIRE_TRANSCRIBE_API_KEY` alone also turns it on; `WIRE_TRANSCRIBE=0` turns it off. |
+| `WIRE_ALLOW_PRIVATE=1` | Let reads reach private and internal addresses. Off by default. |
+| `WIRE_SHIELD_NOTIFY=0` | No desktop notifications for alerts. |
+| `WIRE_SHIELD_VERBOSE=1` | Also record every routine removal (hidden menus, zero-width spaces) in the alert ledger. |
+
+In the Claude plugin, the keys are plugin settings (`userConfig`) stored in Claude Code's secure storage, and the plugin never reads credentials from your machine.
+
+## Shield Alerts
+
+agent-wire removes text a human reader can't see before the model reads a page, and refuses requests a page may have steered. Shield Alerts tells you when that happened, without relying on the model to mention it: a hijacked or distracted agent could leave the warning out.
+
+**What raises an alert.**
+
+| Tier | Examples | What you get |
+|---|---|---|
+| info | A hidden menu, a cookie banner, a zero-width space, a fake chat token in a comment | A counter in `wire_status`. Recorded in full only with `WIRE_SHIELD_VERBOSE=1`. |
+| alert | Hidden text that reads like an instruction to an AI ("ignore previous instructions", "you are now", chat tokens, tool names, "don't tell the user", "send the API keys to"); text smuggled in Unicode tag characters; a forged end-of-data marker; visible text that names agent-wire's tools, asks the model to hide something from you, or asks it to send secrets somewhere | Notification, stderr line, header line, ledger row |
+| high | A refused request: a private or internal address, a non-web URL scheme, a logged-in request that would write or reach an account page | Same, worded as a refused request |
+
+Visible text is judged more strictly than hidden text. A security article that quotes "ignore previous instructions" in plain view is not an attack on you and raises nothing; the same words hidden with CSS do.
+
+**What each alert says it did.** `stripped` (removed before the model saw it), `escaped` (neutralized in place), `refused` (never sent), `flagged-only` (visible text: it stays in the quoted content, marked as untrusted, because removing visible text would censor the page).
+
+**Where alerts go.**
+
+1. `WIRE_HOME/alerts.db`, one row per alert, chained by SHA-256 so edits are detectable (`wire alerts verify`).
+2. A desktop notification (Windows toast, macOS Notification Center, Linux `notify-send`). At most one per site per minute and five per minute overall. It never contains page text.
+3. A `[wire-shield] ...` line on stderr, which some clients show as server logs.
+4. A `[WIRE SHIELD | ...]` line in the tool result, after the `[WIRE | ...]` line and before the untrusted block, so the model can tell you too. It never contains page text either.
+
+**Commands.**
+
+- `wire alerts`: recent alerts, newest first (`--all` adds info events).
+- `wire alerts show <id>`: everything recorded about one alert: the URL (query values removed), where on the page it was (an element path such as `body > article > div.promo-note`), the caught text (up to 120 characters, secrets scrubbed, control characters removed) and any decoded hidden text.
+- `wire alerts tail`: print new alerts as they arrive.
+- `wire alerts verify`: check the ledger's hash chain.
+- `wire alerts demo`: run the shield on a bundled page with three hidden attacks and one honest quote, offline, and show what the model receives.
+
+**Limits.** Locations are element paths, not line numbers: the HTML parser doesn't keep source positions. Only `<style>` blocks inside the page are applied, and only simple `.class`, `#id` and `tag.class` selectors outside `@media` and similar blocks; the common hiding classes (`sr-only`, `visually-hidden`, `hidden`, `d-none`, `invisible`) are recognised by name, unless a responsive class such as `md:block` or `d-lg-block` shows the element again. Detection rules are patterns, so a novel phrasing in visible text may not be flagged; hidden text is removed either way.
+
+## Citations
+
+Write `[[UNSOURCED]]` after a claim with no source, and run `wire_cite` on an answer before sending it. It reports `OK`, `DEAD`, `ARCHIVED` (with the Wayback copy), `SOFT_404`, `BLOCKED`, `QUOTE_MISSING`, and links agent-wire never returned this session.
+
+## Code Mode
+
+`wire serve --code-mode` exposes only `wire_run` and `wire_status`. Scripts run in a QuickJS sandbox with no filesystem, network, timers or modules, and with memory, CPU, wall-clock and call limits. They can't reach `wire_me`.
+
+## Transports
+
+`wire serve` uses stdio. `--transport http` or `sse` binds to `127.0.0.1` only and has no authentication; don't expose it to other machines.
+
+## Self-test
+
+`wire selftest` checks every subsystem in one run, offline: all 31 channels on canned responses, the inbound and outbound firewalls, the SSRF guard, Shield Alerts and the ledger, compression, the delta buffer and route ledger, the cookie vault, Code Mode, research, `wire_cite`, the client installers, and the MCP server in-process and over stdio. A guard blocks the network for the whole run and reports any attempt as a failure.
+
+- `wire selftest --live`: one real request per channel, keyless Reddit, and the shield false-positive count on the 16 README benchmark pages. Channels that need a login or the stealth browser are reported as skipped, not failed.
+- `wire selftest --only mcp` (or `shield`, `reddit`, any group or channel): run part of it.
+- `wire selftest --json`: results as JSON. Exit code 1 when a check fails.
+
+## Policies and help
+
+[Privacy Policy](PRIVACY.md) · [Terms of Use](TERMS.md) · [Support](SUPPORT.md) · [Security](SECURITY.md) · [License](LICENSE)

agent_wire_cli-0.2.4/README.md → agent_wire_cli-0.2.5/PKG-INFO

@@ -1,9 +1,41 @@
+Metadata-Version: 2.5
+Name: agent-wire-cli
+Version: 0.2.5
+Summary: High-speed, privacy-first, token-compressed live web and multi-platform intelligence engine for AI agents.
+Project-URL: Homepage, https://github.com/uncoalesced/agent-wire
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=50.0.2
+Requires-Dist: curl-cffi>=0.16.3
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastmcp>=4.1.2
+Requires-Dist: joserfc>=1.8.0
+Requires-Dist: orjson>=3.13.0
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: quickjs-ng>=0.17.0.2
+Requires-Dist: selectolax>=1.0.0
+Requires-Dist: tiktoken>=0.14.0
+Requires-Dist: trafilatura>=2.3.1
+Requires-Dist: typer>=0.27.3
+Requires-Dist: zstandard>=0.25.0
+Provides-Extra: browser-cookies
+Requires-Dist: rookiepy>=0.5.6; (python_full_version < '3.13') and extra == 'browser-cookies'
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.17.1; extra == 'dev'
+Provides-Extra: local-whisper
+Requires-Dist: faster-whisper>=1.1.0; extra == 'local-whisper'
+Provides-Extra: stealth
+Requires-Dist: playwright>=1.48.0; extra == 'stealth'
+Description-Content-Type: text/markdown
+
 <!-- Engineered by uncoalesced -->
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png">
     <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner-light.png">
-    <img alt="agent-wire: agents wired to the live internet. One MCP server, 31 platforms, local." src="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png" width="100%">
+    <img alt="agent-wire: agents wired to the live internet. One local MCP server for the web and 31 platform channels." src="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png" width="100%">
   </picture>
 </p>
 
@@ -31,7 +63,9 @@
   <a href="#privacy-and-prompt-injection">Privacy</a>
 </p>
 
-agent-wire is an MCP server that lets an AI agent read the live web and 31 platforms from your own machine. Pages come back as small, clean text instead of raw HTML, your logins stay out of the model's context, and the common cases need no API keys. It's free, MIT licensed, and nothing is hosted.
+**Agent Wire by uncoalesced.** On PyPI it's `agent-wire-cli`; the Claude plugin is `agent-wire`.
+
+agent-wire is an MCP server that lets an AI agent read the live web and 31 platform channels from your own machine (most need no login; the table under "Where it works" lists the few that do). Pages come back as small, clean text instead of raw HTML, your logins stay out of the model's context, and the common cases need no API keys. It's free, MIT licensed, and nothing is hosted.
 
 > [!NOTE]
 > It's young. If a site stops parsing, please open an issue with the URL.
@@ -92,6 +126,8 @@ If you prefer the plugin, it bundles the server, a skill that tells Claude when
 /plugin install agent-wire@agent-wire
 ```
 
+The plugin starts the exact PyPI release with `uvx agent-wire-cli==<version> serve`, keeps its data in the plugin data folder Claude Code provides, and asks for optional keys (GitHub token, Reddit app, Exa, SearXNG, transcription) when you enable it. Keys you enter there go to secure storage, not to a settings file. It never reads `gh` or other credentials from your machine.
+
 Use one route or the other, not both. Restart Claude Code, then run `/mcp` and look for `agent_wire`.
 
 </details>
@@ -612,11 +648,29 @@ wire run -e "return (await wire.search('sqlite wal', {platforms: ['hn', 'stackov
 
 ## Privacy and prompt injection
 
-agent-wire never reads your browsers on its own. The only cookies it sends are ones you saved for a specific site with `wire auth login <site>`, either through a login window or with `--from-browser`, which copies that one site's cookies from a browser you're already signed in to. `wire auth list` shows what's saved and `wire auth logout <site>` forgets it. Saved sessions are used for `wire_me`, for login-only sites (LinkedIn, Instagram, Xiaohongshu, X search), and when a public request hits a login wall. Link checks in `wire_cite` and `wire_research` never send saved sessions, even when a page asks for a login.
+agent-wire never reads your browsers on its own. The only cookies it sends are ones you saved for a specific site with `wire auth login <site>`, either through a login window or with `--from-browser`, which copies that one site's cookies from a browser you're already signed in to. `--from-browser` reads Firefox out of the box; Chrome, Edge and Brave need the opt-in extra `agent-wire-cli[browser-cookies]`, so the default install carries no browser-credential reader. `wire auth list` shows what's saved and `wire auth logout <site>` forgets it. Saved sessions are used for `wire_me`, for login-only sites (LinkedIn, Instagram, Xiaohongshu, X search), and when a public request hits a login wall. Link checks in `wire_cite` and `wire_research` never send saved sessions, even when a page asks for a login.
 
 A cookie-bearing request may only read (GET or HEAD). Account paths such as `/messages`, `/settings`, `/billing` and `/password` are refused before anything leaves your machine, and cookies never follow a redirect to another site. JSON from logged-in requests has keys like `viewer`, `email` and `csrf_token` removed, and the final text is scrubbed for bearer tokens, session cookies and private IP addresses.
 
-Pages get the opposite treatment. Anything a person reading the page couldn't see is removed before extraction: `display:none`, zero-size or off-screen text, `aria-hidden` blocks, HTML comments, and Unicode tag, zero-width and bidi characters. Code blocks and visible text are kept as they are, so a tutorial about prompt injection still reads correctly. In user comments, fake control tags such as `</tool_result>` or `<|im_start|>` are escaped, and a page can't close the `UNTRUSTED_EXTERNAL_DATA` block early.
+Pages get the opposite treatment. Anything a person reading the page couldn't see is removed before extraction: `display:none`, zero-size, clipped, transparent or off-screen text (inline, through the page's own stylesheet, or through the usual `sr-only` / `visually-hidden` / `hidden` classes), `aria-hidden` blocks, HTML comments, and Unicode tag, zero-width and bidi characters, including ones written as HTML entities. Code blocks and visible text are kept as they are, so a tutorial about prompt injection still reads correctly. In user comments, fake control tags such as `</tool_result>` or `<|im_start|>` are escaped, and a page can't close the `UNTRUSTED_EXTERNAL_DATA` block early.
+
+**Shield Alerts.** When a page tries to steer the agent, you find out without reading the transcript:
+
+- **Desktop notification.** A Windows, macOS or Linux notification, grouped per site.
+- **stderr line.** For clients that show server logs.
+- **Line above the quoted content.** A trusted `[WIRE SHIELD | ...]` line, outside the untrusted block.
+- **Local record.** Each alert is saved in `WIRE_HOME/alerts.db`.
+
+Alerts carry no page text, only what agent-wire did and where. `wire alerts` lists them, `wire alerts show <id>` shows the text that was caught and where on the page it was, `wire alerts tail` follows new ones, and `wire alerts demo` runs the shield on a bundled page so you can see one.
+
+Each alert states what happened:
+
+- `stripped`: hidden text removed before the model saw it.
+- `escaped`: a forged marker neutralized.
+- `refused`: a request never sent, such as a private address or a logged-in write.
+- `flagged-only`: visible text that names agent-wire's tools or tells the model to hide something from you. It stays in the quoted content, because removing visible text would censor the page.
+
+A page that only quotes "ignore previous instructions" in plain view doesn't raise an alert. Set `WIRE_SHIELD_NOTIFY=0` to turn notifications off, or `WIRE_SHIELD_VERBOSE=1` to also record every routine removal. The full design is in [DOCUMENTATION.md](DOCUMENTATION.md#shield-alerts).
 
 Logins you add with `wire auth login <site>` live in an AES-GCM vault whose key is protected by Windows DPAPI, or by a 0600 key file on macOS and Linux.
 
@@ -635,16 +689,18 @@ A lot of recent malware has arrived through package registries: a hijacked npm p
 To check a release yourself:
 
 ```bash
-uvx --from pypi-attestations pypi-attestations verify pypi --repository https://github.com/uncoalesced/agent-wire pypi:agent_wire_cli-0.2.3-py3-none-any.whl
+uvx --from pypi-attestations pypi-attestations verify pypi --repository https://github.com/uncoalesced/agent-wire pypi:agent_wire_cli-0.2.5-py3-none-any.whl
 ```
 
 ## Privacy Policy
 
+This is a summary. The full policy is [PRIVACY.md](PRIVACY.md).
+
 agent-wire runs on your machine. There's no agent-wire server, no account, no analytics and no telemetry.
 
 **What it stores.** Pages and results you ask for are processed in memory and kept in a session buffer while the server runs. Route memory is cached in `WIRE_HOME` and expires after 24 hours. If you call `wire_research` with `store=True`, the run is saved to `research.db` in `WIRE_HOME`, and it stays there until you delete it. Logins you add with `wire auth login <site>` go in an encrypted local vault (AES-GCM, with the key protected by Windows DPAPI, or a 0600 key file on macOS and Linux). Nothing is uploaded to uncoalesced. `wire auth logout <site>` removes a saved login, and deleting `WIRE_HOME` removes everything local.
 
-**Who sees your requests.** Only the services needed to answer them: the platforms you ask about, plus public fallbacks (Reddit's PullPush and Arctic Shift archives, OpenAlex, Semantic Scholar, Google News), and Exa or a SearXNG instance if you set one up. If you turn on transcription with an external API (`WIRE_TRANSCRIBE=1`), the audio goes to that API. A saved cookie goes only to the site it belongs to, only on read requests, and never follows a redirect to another site.
+**Who sees your requests.** Only the services needed to answer them: the platforms you ask about, plus public fallbacks (Reddit's PullPush and Arctic Shift archives, OpenAlex, Semantic Scholar, Google News), and Exa or a SearXNG instance if you set one up. If you turn on transcription with an external API (`WIRE_TRANSCRIBE=1`, or by setting a transcription API key), the audio goes to that API. A saved cookie goes only to the site it belongs to, only on read requests, and never follows a redirect to another site.
 
 **What your model sees.** Page text, after the scrub strips tokens, cookies, private IP addresses and, on logged-in pages, emails. Your cookies and identity never reach it.
 
@@ -652,6 +708,8 @@ agent-wire runs on your machine. There's no agent-wire server, no account, no an
 
 ## Terms of Use
 
+This is a summary. The full terms are [TERMS.md](TERMS.md). Help: [SUPPORT.md](SUPPORT.md).
+
 agent-wire is open-source software under the [MIT license](LICENSE), provided as is and without warranty. It runs on your machine, and you are responsible for how you use it.
 
 - **Respect the sites you read.** agent-wire fetches public pages and, if you save a login, pages from your own accounts. Whether that is allowed depends on each site's terms and on your local law, and that is your call, not ours.
@@ -666,11 +724,11 @@ Everything works without configuration. These are optional:
 
 | Variable | Effect |
 |---|---|
-| `WIRE_HOME` | Where the cache, route memory and vault live. By default it's a `.wire/` folder inside the agent client that started the server, falling back to `~/.config/agent-wire` or `%APPDATA%\agent-wire`. A `.gitignore` is written there so nothing gets committed. |
-| `GITHUB_TOKEN` | Higher GitHub rate limits and `wire_me github`. `gh auth token` is used automatically if it's set up. |
+| `WIRE_HOME` | Where the cache, route memory and vault live. In the Claude plugin it's the plugin's data folder. Otherwise it's a `.wire/` folder inside the agent client that started the server, falling back to `~/.config/agent-wire` or `%APPDATA%\agent-wire`. A `.gitignore` is written there so nothing gets committed. |
+| `GITHUB_TOKEN` | Higher GitHub rate limits and `wire_me github`. Outside the Claude plugin, `gh auth token` is used automatically if it's set up; `WIRE_NO_GH_CLI=1` turns that off. |
 | `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` | Reddit's official app login for networks where anonymous access is blocked. |
 | `WIRE_SEARXNG_URL`, `EXA_API_KEY` | Extra web search engines. |
-| `WIRE_TRANSCRIBE=1` | Transcribe podcast audio, either locally with `agent-wire-cli[local-whisper]` or through an OpenAI-compatible API (`WIRE_TRANSCRIBE_API_KEY`, `WIRE_TRANSCRIBE_URL`, `WIRE_TRANSCRIBE_MODEL`). The API route uploads the audio, so it's opt-in. |
+| `WIRE_TRANSCRIBE=1` | Transcribe podcast audio, either locally with `agent-wire-cli[local-whisper]` or through an OpenAI-compatible API (`WIRE_TRANSCRIBE_API_KEY`, `WIRE_TRANSCRIBE_URL`, `WIRE_TRANSCRIBE_MODEL`). The API route uploads the audio, so it's opt-in: setting `WIRE_TRANSCRIBE_API_KEY` counts as opting in, and `WIRE_TRANSCRIBE=0` turns it off. |
 | `WIRE_ALLOW_PRIVATE=1` | Let reads reach private and internal addresses (localhost, LAN, link-local, `fd00::/8`). Off by default, so a prompt-injected page or script can't point agent-wire at your router or a cloud metadata endpoint. Set it only to read your own intranet. Your `WIRE_SEARXNG_URL`, transcription URL and watch webhooks are always allowed. |
 
 ## Development
@@ -683,7 +741,15 @@ uv sync --extra dev
 uv run pytest
 ```
 
-The tests run against small fixture payloads shaped like each site's real responses (a few download a tokenizer file on first run). They cover the firewalls, the fetch waterfall, every channel's parser, the research pipeline, the MCP server and the installer. CI runs them on Linux, macOS and Windows with Python 3.11 and 3.14, and builds the wheel.
+The tests run against small fixture payloads shaped like each site's real responses (a few download a tokenizer file on first run; without it, token counts fall back to an approximation). They cover the firewalls, the fetch waterfall, every channel's parser, the research pipeline, the MCP server and the installer. CI runs them on Linux, macOS and Windows with Python 3.11 and 3.14, and builds the wheel.
+
+To check a whole install at once, run the self-test. It drives every part through its real entry point: all 31 channels on canned responses, the firewalls and SSRF guard, the shield and its alert ledger, compression, the caches, the cookie vault, Code Mode, research, citations, the installers, and the MCP server both in-process and as a stdio subprocess. A guard fails the run if anything reaches the network.
+
+```bash
+wire selftest
+```
+
+`wire selftest --live` adds one real request per channel (Reddit with no API key, to show which fallback answered) and reads the 16 benchmark pages to count shield false positives. `--only <group or channel>` narrows the run, `--json` prints machine-readable results, and the exit code is 1 when any check fails. CI and the release workflow run the offline self-test.
 
 Releases are published to PyPI by `.github/workflows/release.yml` when a `v*` tag matching the version in `pyproject.toml` is pushed. It uses PyPI trusted publishing, so no token is stored in the repo.
 

agent_wire_cli-0.2.5/PRIVACY.md

@@ -0,0 +1,54 @@
+# Privacy Policy
+
+Agent Wire by uncoalesced (`agent-wire-cli` on PyPI, the `agent-wire` Claude plugin). Last updated 2026-11-11.
+
+agent-wire is software that runs on your own machine. There is no agent-wire server, no account and no sign-up. It sends no analytics and no telemetry. Nothing it reads or stores is uploaded to uncoalesced.
+
+## What it stores, and where
+
+Everything lives in one local folder, `WIRE_HOME`. For the Claude plugin, that's the plugin's data folder that Claude Code gives it. Otherwise it's a `.wire/` folder inside the agent client that started the server, falling back to `~/.config/agent-wire` (macOS, Linux) or `%APPDATA%\agent-wire` (Windows). You can set `WIRE_HOME` to choose.
+
+| What | File | How long |
+|---|---|---|
+| Pages and results you asked for | Memory only (a session buffer) | Until the server stops |
+| Which fetch stage worked for each site ("route memory") | `cache.db` | Ignored after 24 hours |
+| Saved logins (`wire auth login <site>`) | `vault.enc`, encrypted with AES-GCM; the key is protected by Windows DPAPI, or kept in a 0600 file (`vault.key`) on macOS and Linux | Until you run `wire auth logout <site>` |
+| Research runs, only if you pass `store=True` or use `wire watch` | `research.db` | Until you delete them |
+| Shield alerts: what agent-wire stripped, escaped or refused, where, and up to 120 characters of the page text it caught (with secrets scrubbed and URL query values removed) | `alerts.db` | Until you delete it |
+| Browser profile for the optional stage 4 browser (`[stealth]` extra) | `browser-profile/` | Until you delete it |
+| Tokenizer data downloaded on first use | `tiktoken/` | Until you delete it |
+
+Deleting `WIRE_HOME` removes everything agent-wire stored.
+
+A login window (`wire auth login <site>`) uses a temporary browser profile that is deleted as soon as the cookies are saved to the vault. `wire auth login <site> --from-browser` reads that one site's cookies from a browser on your machine, only when you run the command yourself. Chrome, Edge and Brave need the optional `agent-wire-cli[browser-cookies]` extra. The MCP server never reads browser profiles.
+
+## Who receives requests
+
+agent-wire only sends requests needed to answer what you or your agent asked:
+
+- **The sites you ask it to read or search**: the web page itself, or platforms such as GitHub, Reddit, Hacker News, YouTube, X, Wikipedia, Stack Exchange, arXiv, Bluesky, Mastodon, Polymarket, Bilibili and the other channels listed in the README.
+- **Public services it uses to search and fall back**: DuckDuckGo and Brave Search for web search, Google News and Techmeme for news, the Wayback Machine (archive.org), PullPush and Arctic Shift (Reddit archives), OpenAlex and Semantic Scholar (papers), and fxtwitter, vxtwitter and X's syndication endpoint for single X posts.
+- **Services you configure yourself**: Exa (with your Exa key), your own SearXNG instance, an OpenAI-compatible transcription API (only when you set `WIRE_TRANSCRIBE=1` or give a transcription API key; the audio goes to it), and webhooks you add with `wire watch add`.
+- **The tokenizer download**: on first use, `tiktoken` downloads its encoding file from OpenAI's public file host. Nothing about you is sent with it.
+
+Each of those services handles requests under its own privacy policy.
+
+## Your credentials
+
+Optional keys (GitHub token, Reddit app ID and secret, Exa key, transcription key) are read only from your environment, or in the Claude plugin from settings you choose to enter, which Claude Code keeps in secure storage. Each one goes only to its own service. A saved login cookie is sent only to the site it belongs to, only on GET or HEAD requests, never to account pages such as messages, settings or billing, and never across a redirect to another site.
+
+## What your AI model sees
+
+Page text after agent-wire removes hidden content and scrubs tokens, cookies, private IP addresses, well-known API key formats, your saved vault values and, on logged-in pages, email addresses. Your cookies and identity are not passed to the model. Whatever your model provider does with the text it receives is covered by that provider's policy, not this one.
+
+## Children
+
+agent-wire is a developer tool and is not directed at children.
+
+## Changes
+
+Changes to this policy are made in this file and recorded in the repository history.
+
+## Contact
+
+mail@uncoalesced.com, or an issue at [github.com/uncoalesced/agent-wire/issues](https://github.com/uncoalesced/agent-wire/issues). Report security problems privately as described in [SECURITY.md](SECURITY.md).

agent_wire_cli-0.2.4/PKG-INFO → agent_wire_cli-0.2.5/README.md

@@ -1,39 +1,9 @@
-Metadata-Version: 2.5
-Name: agent-wire-cli
-Version: 0.2.4
-Summary: High-speed, privacy-first, token-compressed live web and multi-platform intelligence engine for AI agents.
-Project-URL: Homepage, https://github.com/uncoalesced/agent-wire
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: cryptography>=50.0.2
-Requires-Dist: curl-cffi>=0.16.3
-Requires-Dist: defusedxml>=0.7.1
-Requires-Dist: fastmcp>=4.1.2
-Requires-Dist: orjson>=3.13.0
-Requires-Dist: pydantic>=2.14.1
-Requires-Dist: quickjs-ng>=0.17.0.2
-Requires-Dist: rookiepy>=0.5.6; python_full_version < '3.13'
-Requires-Dist: selectolax>=1.0.0
-Requires-Dist: tiktoken>=0.14.0
-Requires-Dist: trafilatura>=2.3.1
-Requires-Dist: typer>=0.27.3
-Requires-Dist: zstandard>=0.25.0
-Provides-Extra: dev
-Requires-Dist: pytest>=9.1.1; extra == 'dev'
-Requires-Dist: ruff>=0.17.1; extra == 'dev'
-Provides-Extra: local-whisper
-Requires-Dist: faster-whisper>=1.1.0; extra == 'local-whisper'
-Provides-Extra: stealth
-Requires-Dist: playwright>=1.48.0; extra == 'stealth'
-Description-Content-Type: text/markdown
-
 <!-- Engineered by uncoalesced -->
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png">
     <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner-light.png">
-    <img alt="agent-wire: agents wired to the live internet. One MCP server, 31 platforms, local." src="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png" width="100%">
+    <img alt="agent-wire: agents wired to the live internet. One local MCP server for the web and 31 platform channels." src="https://raw.githubusercontent.com/uncoalesced/agent-wire/main/assets/agent-wire-banner.png" width="100%">
   </picture>
 </p>
 
@@ -61,7 +31,9 @@ Description-Content-Type: text/markdown
   <a href="#privacy-and-prompt-injection">Privacy</a>
 </p>
 
-agent-wire is an MCP server that lets an AI agent read the live web and 31 platforms from your own machine. Pages come back as small, clean text instead of raw HTML, your logins stay out of the model's context, and the common cases need no API keys. It's free, MIT licensed, and nothing is hosted.
+**Agent Wire by uncoalesced.** On PyPI it's `agent-wire-cli`; the Claude plugin is `agent-wire`.
+
+agent-wire is an MCP server that lets an AI agent read the live web and 31 platform channels from your own machine (most need no login; the table under "Where it works" lists the few that do). Pages come back as small, clean text instead of raw HTML, your logins stay out of the model's context, and the common cases need no API keys. It's free, MIT licensed, and nothing is hosted.
 
 > [!NOTE]
 > It's young. If a site stops parsing, please open an issue with the URL.
@@ -122,6 +94,8 @@ If you prefer the plugin, it bundles the server, a skill that tells Claude when
 /plugin install agent-wire@agent-wire
 ```
 
+The plugin starts the exact PyPI release with `uvx agent-wire-cli==<version> serve`, keeps its data in the plugin data folder Claude Code provides, and asks for optional keys (GitHub token, Reddit app, Exa, SearXNG, transcription) when you enable it. Keys you enter there go to secure storage, not to a settings file. It never reads `gh` or other credentials from your machine.
+
 Use one route or the other, not both. Restart Claude Code, then run `/mcp` and look for `agent_wire`.
 
 </details>
@@ -642,11 +616,29 @@ wire run -e "return (await wire.search('sqlite wal', {platforms: ['hn', 'stackov
 
 ## Privacy and prompt injection
 
-agent-wire never reads your browsers on its own. The only cookies it sends are ones you saved for a specific site with `wire auth login <site>`, either through a login window or with `--from-browser`, which copies that one site's cookies from a browser you're already signed in to. `wire auth list` shows what's saved and `wire auth logout <site>` forgets it. Saved sessions are used for `wire_me`, for login-only sites (LinkedIn, Instagram, Xiaohongshu, X search), and when a public request hits a login wall. Link checks in `wire_cite` and `wire_research` never send saved sessions, even when a page asks for a login.
+agent-wire never reads your browsers on its own. The only cookies it sends are ones you saved for a specific site with `wire auth login <site>`, either through a login window or with `--from-browser`, which copies that one site's cookies from a browser you're already signed in to. `--from-browser` reads Firefox out of the box; Chrome, Edge and Brave need the opt-in extra `agent-wire-cli[browser-cookies]`, so the default install carries no browser-credential reader. `wire auth list` shows what's saved and `wire auth logout <site>` forgets it. Saved sessions are used for `wire_me`, for login-only sites (LinkedIn, Instagram, Xiaohongshu, X search), and when a public request hits a login wall. Link checks in `wire_cite` and `wire_research` never send saved sessions, even when a page asks for a login.
 
 A cookie-bearing request may only read (GET or HEAD). Account paths such as `/messages`, `/settings`, `/billing` and `/password` are refused before anything leaves your machine, and cookies never follow a redirect to another site. JSON from logged-in requests has keys like `viewer`, `email` and `csrf_token` removed, and the final text is scrubbed for bearer tokens, session cookies and private IP addresses.
 
-Pages get the opposite treatment. Anything a person reading the page couldn't see is removed before extraction: `display:none`, zero-size or off-screen text, `aria-hidden` blocks, HTML comments, and Unicode tag, zero-width and bidi characters. Code blocks and visible text are kept as they are, so a tutorial about prompt injection still reads correctly. In user comments, fake control tags such as `</tool_result>` or `<|im_start|>` are escaped, and a page can't close the `UNTRUSTED_EXTERNAL_DATA` block early.
+Pages get the opposite treatment. Anything a person reading the page couldn't see is removed before extraction: `display:none`, zero-size, clipped, transparent or off-screen text (inline, through the page's own stylesheet, or through the usual `sr-only` / `visually-hidden` / `hidden` classes), `aria-hidden` blocks, HTML comments, and Unicode tag, zero-width and bidi characters, including ones written as HTML entities. Code blocks and visible text are kept as they are, so a tutorial about prompt injection still reads correctly. In user comments, fake control tags such as `</tool_result>` or `<|im_start|>` are escaped, and a page can't close the `UNTRUSTED_EXTERNAL_DATA` block early.
+
+**Shield Alerts.** When a page tries to steer the agent, you find out without reading the transcript:
+
+- **Desktop notification.** A Windows, macOS or Linux notification, grouped per site.
+- **stderr line.** For clients that show server logs.
+- **Line above the quoted content.** A trusted `[WIRE SHIELD | ...]` line, outside the untrusted block.
+- **Local record.** Each alert is saved in `WIRE_HOME/alerts.db`.
+
+Alerts carry no page text, only what agent-wire did and where. `wire alerts` lists them, `wire alerts show <id>` shows the text that was caught and where on the page it was, `wire alerts tail` follows new ones, and `wire alerts demo` runs the shield on a bundled page so you can see one.
+
+Each alert states what happened:
+
+- `stripped`: hidden text removed before the model saw it.
+- `escaped`: a forged marker neutralized.
+- `refused`: a request never sent, such as a private address or a logged-in write.
+- `flagged-only`: visible text that names agent-wire's tools or tells the model to hide something from you. It stays in the quoted content, because removing visible text would censor the page.
+
+A page that only quotes "ignore previous instructions" in plain view doesn't raise an alert. Set `WIRE_SHIELD_NOTIFY=0` to turn notifications off, or `WIRE_SHIELD_VERBOSE=1` to also record every routine removal. The full design is in [DOCUMENTATION.md](DOCUMENTATION.md#shield-alerts).
 
 Logins you add with `wire auth login <site>` live in an AES-GCM vault whose key is protected by Windows DPAPI, or by a 0600 key file on macOS and Linux.
 
@@ -665,16 +657,18 @@ A lot of recent malware has arrived through package registries: a hijacked npm p
 To check a release yourself:
 
 ```bash
-uvx --from pypi-attestations pypi-attestations verify pypi --repository https://github.com/uncoalesced/agent-wire pypi:agent_wire_cli-0.2.3-py3-none-any.whl
+uvx --from pypi-attestations pypi-attestations verify pypi --repository https://github.com/uncoalesced/agent-wire pypi:agent_wire_cli-0.2.5-py3-none-any.whl
 ```
 
 ## Privacy Policy
 
+This is a summary. The full policy is [PRIVACY.md](PRIVACY.md).
+
 agent-wire runs on your machine. There's no agent-wire server, no account, no analytics and no telemetry.
 
 **What it stores.** Pages and results you ask for are processed in memory and kept in a session buffer while the server runs. Route memory is cached in `WIRE_HOME` and expires after 24 hours. If you call `wire_research` with `store=True`, the run is saved to `research.db` in `WIRE_HOME`, and it stays there until you delete it. Logins you add with `wire auth login <site>` go in an encrypted local vault (AES-GCM, with the key protected by Windows DPAPI, or a 0600 key file on macOS and Linux). Nothing is uploaded to uncoalesced. `wire auth logout <site>` removes a saved login, and deleting `WIRE_HOME` removes everything local.
 
-**Who sees your requests.** Only the services needed to answer them: the platforms you ask about, plus public fallbacks (Reddit's PullPush and Arctic Shift archives, OpenAlex, Semantic Scholar, Google News), and Exa or a SearXNG instance if you set one up. If you turn on transcription with an external API (`WIRE_TRANSCRIBE=1`), the audio goes to that API. A saved cookie goes only to the site it belongs to, only on read requests, and never follows a redirect to another site.
+**Who sees your requests.** Only the services needed to answer them: the platforms you ask about, plus public fallbacks (Reddit's PullPush and Arctic Shift archives, OpenAlex, Semantic Scholar, Google News), and Exa or a SearXNG instance if you set one up. If you turn on transcription with an external API (`WIRE_TRANSCRIBE=1`, or by setting a transcription API key), the audio goes to that API. A saved cookie goes only to the site it belongs to, only on read requests, and never follows a redirect to another site.
 
 **What your model sees.** Page text, after the scrub strips tokens, cookies, private IP addresses and, on logged-in pages, emails. Your cookies and identity never reach it.
 
@@ -682,6 +676,8 @@ agent-wire runs on your machine. There's no agent-wire server, no account, no an
 
 ## Terms of Use
 
+This is a summary. The full terms are [TERMS.md](TERMS.md). Help: [SUPPORT.md](SUPPORT.md).
+
 agent-wire is open-source software under the [MIT license](LICENSE), provided as is and without warranty. It runs on your machine, and you are responsible for how you use it.
 
 - **Respect the sites you read.** agent-wire fetches public pages and, if you save a login, pages from your own accounts. Whether that is allowed depends on each site's terms and on your local law, and that is your call, not ours.
@@ -696,11 +692,11 @@ Everything works without configuration. These are optional:
 
 | Variable | Effect |
 |---|---|
-| `WIRE_HOME` | Where the cache, route memory and vault live. By default it's a `.wire/` folder inside the agent client that started the server, falling back to `~/.config/agent-wire` or `%APPDATA%\agent-wire`. A `.gitignore` is written there so nothing gets committed. |
-| `GITHUB_TOKEN` | Higher GitHub rate limits and `wire_me github`. `gh auth token` is used automatically if it's set up. |
+| `WIRE_HOME` | Where the cache, route memory and vault live. In the Claude plugin it's the plugin's data folder. Otherwise it's a `.wire/` folder inside the agent client that started the server, falling back to `~/.config/agent-wire` or `%APPDATA%\agent-wire`. A `.gitignore` is written there so nothing gets committed. |
+| `GITHUB_TOKEN` | Higher GitHub rate limits and `wire_me github`. Outside the Claude plugin, `gh auth token` is used automatically if it's set up; `WIRE_NO_GH_CLI=1` turns that off. |
 | `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` | Reddit's official app login for networks where anonymous access is blocked. |
 | `WIRE_SEARXNG_URL`, `EXA_API_KEY` | Extra web search engines. |
-| `WIRE_TRANSCRIBE=1` | Transcribe podcast audio, either locally with `agent-wire-cli[local-whisper]` or through an OpenAI-compatible API (`WIRE_TRANSCRIBE_API_KEY`, `WIRE_TRANSCRIBE_URL`, `WIRE_TRANSCRIBE_MODEL`). The API route uploads the audio, so it's opt-in. |
+| `WIRE_TRANSCRIBE=1` | Transcribe podcast audio, either locally with `agent-wire-cli[local-whisper]` or through an OpenAI-compatible API (`WIRE_TRANSCRIBE_API_KEY`, `WIRE_TRANSCRIBE_URL`, `WIRE_TRANSCRIBE_MODEL`). The API route uploads the audio, so it's opt-in: setting `WIRE_TRANSCRIBE_API_KEY` counts as opting in, and `WIRE_TRANSCRIBE=0` turns it off. |
 | `WIRE_ALLOW_PRIVATE=1` | Let reads reach private and internal addresses (localhost, LAN, link-local, `fd00::/8`). Off by default, so a prompt-injected page or script can't point agent-wire at your router or a cloud metadata endpoint. Set it only to read your own intranet. Your `WIRE_SEARXNG_URL`, transcription URL and watch webhooks are always allowed. |
 
 ## Development
@@ -713,7 +709,15 @@ uv sync --extra dev
 uv run pytest
 ```
 
-The tests run against small fixture payloads shaped like each site's real responses (a few download a tokenizer file on first run). They cover the firewalls, the fetch waterfall, every channel's parser, the research pipeline, the MCP server and the installer. CI runs them on Linux, macOS and Windows with Python 3.11 and 3.14, and builds the wheel.
+The tests run against small fixture payloads shaped like each site's real responses (a few download a tokenizer file on first run; without it, token counts fall back to an approximation). They cover the firewalls, the fetch waterfall, every channel's parser, the research pipeline, the MCP server and the installer. CI runs them on Linux, macOS and Windows with Python 3.11 and 3.14, and builds the wheel.
+
+To check a whole install at once, run the self-test. It drives every part through its real entry point: all 31 channels on canned responses, the firewalls and SSRF guard, the shield and its alert ledger, compression, the caches, the cookie vault, Code Mode, research, citations, the installers, and the MCP server both in-process and as a stdio subprocess. A guard fails the run if anything reaches the network.
+
+```bash
+wire selftest
+```
+
+`wire selftest --live` adds one real request per channel (Reddit with no API key, to show which fallback answered) and reads the 16 benchmark pages to count shield false positives. `--only <group or channel>` narrows the run, `--json` prints machine-readable results, and the exit code is 1 when any check fails. CI and the release workflow run the offline self-test.
 
 Releases are published to PyPI by `.github/workflows/release.yml` when a `v*` tag matching the version in `pyproject.toml` is pushed. It uses PyPI trusted publishing, so no token is stored in the repo.