dexterm-cli 0.1.3 → 0.1.4

package/dist/packages/mcp/assets/kb/docs/docs-screens-paper-ticket-and-positions.md

@@ -0,0 +1,29 @@
+---
+id: docs-screens-paper-ticket-and-positions
+title: Screens tour › PAPER ticket and positions
+kind: docs
+page: screens
+page_title: Screens tour
+heading: PAPER ticket and positions
+anchor: paper-ticket-and-positions
+url: https://dexterm.xyz/docs/screens#paper-ticket-and-positions
+tags:
+  - docs
+  - screens
+  - paper
+  - ticket
+  - positions
+  - tour
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/screens.md
+date: 2026-10-16
+---
+
+a PAPER ticket on sample data
+
+`B` or `S` on a token opens a simulated ticket priced from a keyless Jupiter quote; `P` from anywhere opens the positions screen (equity, cash, realized and unrealized PnL, trade history). Every frame carries the PAPER banner. The confirm gate is on by default and sizes above (generated from the app: see https://dexterm.xyz/docs/screens#paper-ticket-and-positions; app-help has the exact keys and commands) SOL must be typed back. The model is in paper trading and safety (https://dexterm.xyz/docs/paper-trading).

package/dist/packages/mcp/assets/kb/docs/docs-screens-the-look.md

@@ -0,0 +1,29 @@
+---
+id: docs-screens-the-look
+title: Screens tour › The look
+kind: docs
+page: screens
+page_title: Screens tour
+heading: The look
+anchor: the-look
+url: https://dexterm.xyz/docs/screens#the-look
+tags:
+  - docs
+  - screens
+  - look
+  - tour
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/screens.md
+date: 2026-10-16
+---
+
+the rain follows the market: gold on a pump
+
+Matrix rain made of your own tickers, mint prefixes and transaction tails lives in the gutters and the blank parts of panels. Its colour and speed come from the data: gold on a pump, red on a dump, driven by the open token's candles or the rows on screen. Two masks on the cell buffer make it impossible for an effect to overdraw a number: data glyphs are marked hard, effects can only write to blank, unmarked cells, and a contrast gate in the test suite proves every numeric cell stays at 4.5:1 or better with effects on.
+
+`c` toggles calm mode (no rain, glitch, blink or scanlines); `--intensity normal` is 15 fps with sparser rain; `NO_COLOR` implies calm. After (generated from the app: see https://dexterm.xyz/docs/screens#the-look; app-help has the exact keys and commands) s without a key the ambient rain drops to (generated from the app: see https://dexterm.xyz/docs/screens#the-look; app-help has the exact keys and commands) fps so an idle terminal costs about 2% CPU; the next key snaps it back.

package/dist/packages/mcp/assets/kb/docs/docs-screens-token-screen.md

@@ -0,0 +1,36 @@
+---
+id: docs-screens-token-screen
+title: Screens tour › Token screen
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Token screen
+anchor: token-screen
+url: https://dexterm.xyz/docs/screens#token-screen
+tags:
+  - docs
+  - screens
+  - token
+  - screen
+  - tour
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/screens.md
+date: 2026-10-16
+---
+
+a token on sample data (the seeded renderer shows the raw tape where the live screen shows the BUY/SELL FLOW panel)
+
+Everything about one coin: candles (1m to 1d, `1`–`6`), market stats, mint and freeze authority from the chain, holder count and top-10 concentration from Jupiter (the ranked top-20 list needs a free RPC key and says so), RugCheck summary, GoPlus second opinion, and in the lower right the **BUY/SELL FLOW** panel: buys versus sells for 1m, 5m, 1h, 6h and 24h with a ratio bar, USD volume and a trend arrow versus the previous window. `F` swaps it for the raw trade tape.
+
+The price badge says **LIVE** only while a fresh on-chain push is flowing for that coin over the fast lane (one WebSocket on its pump.fun bonding curve), otherwise **POLL**. When you hold a PAPER position in the coin a `◈ POSITION · PAPER` row renders under the chart with side, size, value, average entry, price and unrealized PnL.
+
+**Who holds it.** Once the wallet-intel scan (https://dexterm.xyz/docs/screens#bubble-map) lands (about 1.5 s after the token opens), every row of the HOLDERS panel carries a class read from the chain, never guessed: **POOL** (an AMM / CLMM / DLMM pool vault: Raydium, Orca, Meteora, PumpSwap), **CURVE** (a bonding curve: pump.fun, Meteora DBC for Jupiter Studio and Meteora launches, Raydium LaunchLab), **VAULT** (Meteora dynamic and Alpha vaults), **LOCK** (a Streamflow or Jupiter Lock escrow), **CEX** (seed-list exchange wallet, always *unverified*), **BURN** (the incinerator), **DEV** (the creator), **LINKED** (tied to another top holder by a funder, bundle or transfer rule) and **UNLABELLED** for everything else, including an account of a program dexterm does not list. The class comes from the token account's owner and the owner account's program (the same account lookup the scan already makes, no new request); the constant pool-authority addresses are re-derived in the tests. The single Top 10 holders row then becomes two: **Top 10 ex-pool** drops POOL / CURVE / VAULT / LOCK / BURN owners and is what the colour reads, **Top 10 raw** is what explorers show, so a fresh launch whose curve still holds 70 % no longer reads as a 78 % whale. Unlabelled owners are always counted. When a counted owner holds more than 30 % the panel says so on its first line (`⚠ main risk: UNLABELLED Ab12…Cd34 holds 71.6%`); when the biggest holder is a venue it says which (`· top holder 70.0% is CURVE (Meteora DBC): not counted in ex-pool`). A lock or vault names its escrow and program; dexterm does not decode the unlock schedule yet and says so.
+
+When the Snipers and Bundled supply rows have no number they give the reason: `needs Helius key` only when no key is configured, otherwise `Helius paused · r` (rate-limited), `Helius cap today` (the daily credit budget is spent), `history failed · r` (the history call errored) or `no launch txs read`. `r` on the token screen re-runs a scan whose launch window did not land.
+
+Keys here: `B`/`S` PAPER buy/sell, `C` chart popup, `M` bubble map (below), `V` vet the product (LARP detector), `W`/`X`/`T` open the advertised site/X/Telegram, `L` list every advertised link, `y` copy the contract address, `a` run the analyst dossier, `i` or `⏎` type a question, `s` the SOCIAL panel (below), `H` a PnL card (https://dexterm.xyz/docs/paper-trading#pnl-cards) when you have fills in the coin.

package/dist/packages/mcp/assets/kb/docs/docs-screens-trending-social-and-kol-lists.md

@@ -0,0 +1,34 @@
+---
+id: docs-screens-trending-social-and-kol-lists
+title: Screens tour › Trending, social and KOL lists
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Trending, social and KOL lists
+anchor: trending-social-and-kol-lists
+url: https://dexterm.xyz/docs/screens#trending-social-and-kol-lists
+tags:
+  - docs
+  - screens
+  - trending
+  - social
+  - kol
+  - lists
+  - tour
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/screens.md
+date: 2026-10-16
+---
+
+Three views over a social layer that is keyless by default and reads X only through your own login (https://dexterm.xyz/docs/login-with-x). There is no scraping, and nothing is ever posted; every post and headline passes the same prompt firewall as token text before it is stored or shown.
+
+- **`T` TRENDING IN THE SPACE** (from every screen except the token screen, where `T` still opens Telegram). Coins ranked from public lists: Jupiter trending and organic score, GeckoTerminal trending pools, and CoinGecko trending for macro context; a DexScreener paid boost counts *against* a coin. With no posts to count, a coin's velocity falls back to its last-hour volume against its 24 h average. Sub-panels: NARRATIVES (coins linked by shared KOL threads or co-mentions) and NEWS (CoinDesk, Cointelegraph, The Block and Decrypt official RSS, every 10 min; context, not signal). `f` source filter, `x` show the rows held back as spam or cashtag squats, `n` narrative filter, `s` sources and their health, `a` one board summary from your own claude (at most every 5 min), `⏎` open the coin, `M` the feeds popup (https://dexterm.xyz/docs/popup-chart#token-and-feeds-popups).
+- **`s` SOCIAL panel on the token screen** replaces ON-CHAIN/HOLDERS. In live mode it holds rule-written on-chain rows only (labelled holders, tracked wallets, trades of $5K or more, and the wallet-intel scan (https://dexterm.xyz/docs/screens#bubble-map)'s linked clusters and launch snipers, each naming the rule that linked them, such as `12.0% of supply sits in 4 wallets that bought in the same slot and share a funder (bundle, R2)`); X and Telegram posts appear only in the `--fixtures` demo, because no keyless post source is wired. Near-duplicates collapse into one row, bursts from fresh accounts are marked spam, and instruction-like posts are withheld from the model entirely.
+- **`K` KOL lists**: your own handle lists and imported packs, stored in the local database. A pack is a hash-locked directory and a tampered one is refused. `space` enables or disables a list, `m` mutes a handle, `d` removes one, `i` adds one. The same is scriptable with `dexterm kol` (see the CLI reference (https://dexterm.xyz/docs/cli#subcommands)).
+
+- **X posts** appear in both views after `dexterm x login` (Login with X (https://dexterm.xyz/docs/login-with-x)): the open coin's posts in the SOCIAL panel (searched every 60 s, newer posts only), and your KOL lists' posts on the board. The band shows the state and never pretends: `x-stream ○ logged out`, `●4s @you` while reading, `◐ rate limited 5m`, `◐ daily budget`, `◐ app tier (no search)` on a Free-tier app. On the KOL screen `X` imports the lists your X account owns (handles only) and `o` narrows the board and the panel to the selected handle (`o` again or `f` clears).

package/dist/packages/mcp/assets/kb/docs/docs-screens.md

@@ -0,0 +1,26 @@
+---
+id: docs-screens
+title: Screens tour
+kind: docs
+page: screens
+page_title: Screens tour
+url: https://dexterm.xyz/docs/screens
+tags:
+  - docs
+  - screens
+  - tour
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/screens.md
+date: 2026-10-16
+---
+
+The screener, token screen, new pairs, watchlist, analyst tab, PAPER ticket and positions.
+
+dexterm is five screens on one keyboard model, plus the PAPER ticket and positions. The header carries the SOL price, the live/degraded status of the feed, the Helius credit meter when a key is configured, and the AI scan indicator when the scan is on. The footer lists the keys that matter on the current screen; `?` lists all of them.
+
+Every screenshot on this site is the real app on seeded sample data with made-up tickers; the header reads `◌ sample data`. The one exception is the analyst beat on the home page: a labelled, scripted replay of real historical $WIF data from the 2023-12-14 daily close (header `◌ replay · historical data · scripted demo`). It is not a live recommendation and not financial advice; nowhere else on the site is a real token paired with a price.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-1-the-agent-activity-window-follow-mode.md

@@ -0,0 +1,56 @@
+---
+id: docs-spectator-1-the-agent-activity-window-follow-mode
+title: Spectator view (watch the agent cook) › The three surfaces › 1. The AGENT ACTIVITY window (follow mode)
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: 1. The AGENT ACTIVITY window (follow mode)
+anchor: 1-the-agent-activity-window-follow-mode
+url: https://dexterm.xyz/docs/spectator#1-the-agent-activity-window-follow-mode
+tags:
+  - docs
+  - spectator
+  - agent
+  - activity
+  - window
+  - follow
+  - mode
+  - three
+  - surfaces
+  - view
+  - watch
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+`--spectator-popup` opens the spectator window through dexterm's popup host. It is the docked native window on macOS when the native shell is built, and a browser tab on loopback otherwise, as with the chart popup (https://dexterm.xyz/docs/popup-chart#build-the-native-window). `agent serve` prints which one it opened. The window refreshes once a second and shows:
+
+- **screen**: the screen the agent asked to show (screener, token, watchlist, ticket) with the token, feed, filter and highlight it picked. This line comes from the agent's navigation events. See limits (https://dexterm.xyz/docs/spectator#limits) for what it is not.
+- **agents**: each connected agent with an `agent` badge, its tier (`observe`, `annotate` or `propose`), its status (`active`, `paused` or `killed`) and when it last did something.
+- **activity**: newest first, up to 80 lines (the window keeps the last 200 events). Each line shows how long ago it happened, the agent, the phase, the tool, a short summary, the time the call took in ms and the age of the data it returned. Refused calls are marked.
+
+| phase | meaning |
+| --- | --- |
+| `connect` / `disconnect` | an agent opened or closed a session (with its client and any mandate) |
+| `result` | a read tool returned (`ok` or an error) |
+| `nav` | a navigation tool asked the screen to move (`open_token`, `show_in_screener`, `switch_feed`, `add_to_watchlist`, `open_ticket`) |
+| `proposal` | the agent made a proposal you would have to confirm (an alert, an order-plan draft, a watchlist add) |
+| `refused` | the gate refused the call, with its reason (`never`, `tier`, `mandate`, `spoof`, …) |
+| `note` / `subscribe` | the agent wrote a note, or subscribed to a live stream |
+| `control` | you paused, resumed or killed the agent |
+
+**Controls.** Each agent row has buttons:
+
+- **pause**: the gate refuses the agent's next call. The agent stays connected and visible.
+- **take over**: pauses the agent and marks you as the driver. The window shows `YOU HAVE TAKEN OVER`, and the agent stays frozen but visible.
+- **resume**: shown for a paused agent. Its calls go through again and control goes back to the agent.
+- **kill** (the panic button): closes every live session for that agent now and leaves it paused, so a reconnect stays frozen. To revoke the agent for good, run `dexterm agent rotate <name>` or `dexterm agent remove <name>`.
+
+These four are the only messages the window can send, and each carries just an agent name. The `agent serve` process maps them to the bus's own pause, resume and kick, the same controls the roster popup uses, and checks them again before acting. The window has no button, message or path that can arm, sign, confirm, send or raise a cap.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-2-the-read-only-stream-spectate.md

@@ -0,0 +1,42 @@
+---
+id: docs-spectator-2-the-read-only-stream-spectate
+title: Spectator view (watch the agent cook) › The three surfaces › 2. The read-only stream (--spectate)
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: 2. The read-only stream (--spectate)
+anchor: 2-the-read-only-stream-spectate
+url: https://dexterm.xyz/docs/spectator#2-the-read-only-stream-spectate
+tags:
+  - docs
+  - spectator
+  - read-only
+  - stream
+  - spectate
+  - three
+  - surfaces
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+`dexterm agent serve --spectate` starts a WebSocket server on `127.0.0.1` on a random port and prints the port. The per-session token goes to `~/.dexterm/spectator.json` (mode 0600). It is never printed and never on a command line. `dexterm spectate --info` shows the endpoint (`--json` for scripts).
+
+A viewer connects, then sends `{"method":"hello","token":"…"}` with the token from that file within 10 seconds, or the connection is closed. After a good hello it receives:
+
+```text
+{"type":"welcome","protocol":"dexterm-spectator/1","redacted":true,"t":…}
+{"type":"event","snapshot":true,"event":{…}}     # the recent backlog, oldest first
+{"type":"event","snapshot":false,"event":{…}}    # then each new event as it happens
+```
+
+Each `event` has the same fields the window uses: `seq`, `t`, `phase`, `agent`, `tier`, `transport`, `tool`, `summary`, `ok`, `ms`, `dataAgeSec`, `refusal`, `nav`, and `redacted: true`. The server honours exactly two inbound messages: `hello` and `ping` (answered with `pong`). Anything else is counted as dropped and ignored. dexterm does not ship a viewer for the raw stream. It is meant for your own overlay or tooling on the same machine.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-3-save-and-replay-record-file-dexterm-spectate.md

@@ -0,0 +1,41 @@
+---
+id: docs-spectator-3-save-and-replay-record-file-dexterm-spectate
+title: Spectator view (watch the agent cook) › The three surfaces › 3. Save and replay (--record FILE, dexterm spectate)
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: 3. Save and replay (--record FILE, dexterm spectate)
+anchor: 3-save-and-replay-record-file-dexterm-spectate
+url: https://dexterm.xyz/docs/spectator#3-save-and-replay-record-file-dexterm-spectate
+tags:
+  - docs
+  - spectator
+  - save
+  - replay
+  - record
+  - file
+  - dexterm
+  - spectate
+  - three
+  - surfaces
+  - view
+  - watch
+  - agent
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+`dexterm agent serve --record FILE` appends every event to `FILE` as one JSON line, **redacted**, with the file created mode 0600. The redaction makes the file fit to share in a bug report or a demo.
+
+```sh
+$ dexterm spectate --replay session.jsonl          # SCREEN, AGENTS and ACTIVITY as text
+$ dexterm spectate --replay session.jsonl --json   # {"meta":…,"view":…} for scripts
+```
+
+Replay is offline and deterministic. It folds the saved events back into the same screen picture and activity list the window uses, then prints them in the terminal. It does not reopen the window. Don't confuse this with `dexterm --record FILE` on the main app, which saves raw data responses for `--replay` (see the CLI reference (https://dexterm.xyz/docs/cli)). The two flags share a name and do different things.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-follow-over-mcp-in-the-running-terminal.md

@@ -0,0 +1,39 @@
+---
+id: docs-spectator-follow-over-mcp-in-the-running-terminal
+title: Spectator view (watch the agent cook) › Follow over MCP in the running terminal
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: Follow over MCP in the running terminal
+anchor: follow-over-mcp-in-the-running-terminal
+url: https://dexterm.xyz/docs/spectator#follow-over-mcp-in-the-running-terminal
+tags:
+  - docs
+  - spectator
+  - follow
+  - over
+  - mcp
+  - running
+  - terminal
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+An agent connected over MCP (Claude Code, Claude Desktop, Cursor, Codex — set up with `dexterm mcp install`) runs the `dexterm mcp` server as its own process, which the app cannot see into. Since 0.1.4, run the app with `dexterm --spectate-mcp` and the running terminal **follows** that agent:
+
+- While the flag is on, the app writes a small local rendezvous under `~/.dexterm` (mode 0600). The `dexterm mcp` server notices it and starts emitting one record per tool call to a local channel the app tails. When you are not following, the file is absent and the server writes nothing — there is no cost when nobody is watching.
+- A **navigation** call (open a token, switch screen or feed, set a filter, highlight a row, open the paper ticket) moves the real screen, with a status line like `agent <name>: opened BONK`. These are the same read-only moves the analyst makes; nothing an agent does here can size, confirm, sign, send or raise a cap.
+- The controls are at your keyboard: **ctrl+p** pauses and resumes the mirroring, **ctrl+k** stops following (it removes the rendezvous, so the server stops emitting), and **any other key** hands control back to you — the agent can never move the screen out from under you.
+- A read-only, loopback, token-gated stream opens too, so `dexterm spectate --info` shows its endpoint while you follow. Every record is authenticated by the rendezvous token before it is folded, and every shared copy is redacted (see what is redacted (https://dexterm.xyz/docs/spectator#what-is-redacted)). This is on the owner's own machine, so follow mode itself shows full detail.
+
+The built-in analyst (the in-app `ask Claude`) already drives the terminal through its own action channel and shows `analyst did X`; this is the same idea for an agent you connected yourself over MCP.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-limits.md

@@ -0,0 +1,36 @@
+---
+id: docs-spectator-limits
+title: Spectator view (watch the agent cook) › Limits
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: Limits
+anchor: limits
+url: https://dexterm.xyz/docs/spectator#limits
+tags:
+  - docs
+  - spectator
+  - limits
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+Stated plainly, as of `(generated from the app: see https://dexterm.xyz/docs/spectator#limits; app-help has the exact keys and commands)`:
+
+- **The AGENT ACTIVITY window is a separate window with its own screen model.** Its `screen` line shows the screen the agent *asked for*, built from its navigation events, and the bus runs in its own process (`dexterm agent serve`), so that window is not a mirror of your terminal. The running terminal itself **does** move when you follow with `dexterm --spectate-mcp` (follow mode) — that is a different surface from the popup window.
+- **MCP agents are shown in follow mode, which you turn on.** Agents connected through `dexterm mcp` (Claude Code, Claude Desktop, Cursor or Codex, set up with `dexterm mcp install`) appear once you run the app with `dexterm --spectate-mcp`; the terminal then follows them and a read-only stream opens. Without the flag the MCP server emits nothing. The built-in analyst drives the terminal through its own action channel and shows `analyst did X`.
+- **Replay is text.** `dexterm spectate --replay` prints the session in the terminal. It does not reopen the window.
+- **No stream viewer ships.** The raw stream is for your own tooling.
+- **Redaction matches patterns.** It masks anything shaped like an address or a key. Other text, such as a token symbol, a filter or a number, is shown as it is.
+- **The window keeps the last 200 events** and shows 80.
+- **The native window is macOS-only** and needs the native shell built. Everywhere else the window opens in your browser on loopback.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-quick-start.md

@@ -0,0 +1,37 @@
+---
+id: docs-spectator-quick-start
+title: Spectator view (watch the agent cook) › Quick start
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: Quick start
+anchor: quick-start
+url: https://dexterm.xyz/docs/spectator#quick-start
+tags:
+  - docs
+  - spectator
+  - quick
+  - start
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+```sh
+$ dexterm agent add scanbot --tier observe          # once: register the agent, prints a one-time token
+$ export DEXTERM_AGENT_TOKEN=dxa_…                  # in the agent's environment, never on a command line
+$ dexterm agent serve --spectator-popup --record session.jsonl
+$ # now start your agent; it connects to the bus with its name and token
+$ dexterm spectate --replay session.jsonl           # later: replay what it did
+```
+
+`dexterm agent serve` runs on **fixtures** (canned data, no network) unless you pass `--live` for keyless live reads. Fixtures are the right choice for a first try and for any recording you plan to show.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-security-model.md

@@ -0,0 +1,35 @@
+---
+id: docs-spectator-security-model
+title: Spectator view (watch the agent cook) › Security model
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: Security model
+anchor: security-model
+url: https://dexterm.xyz/docs/spectator#security-model
+tags:
+  - docs
+  - spectator
+  - security
+  - model
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+- **Loopback only.** The stream binds `127.0.0.1` on a random port and refuses any connection whose remote address is not loopback. It never binds a LAN address or `::`.
+- **Per-session token.** 32 random bytes, generated when the stream starts, compared in constant time, stored in `~/.dexterm/spectator.json` (0600) and never passed as an argument. A connection without the token in its first 10 seconds is closed.
+- **No inbound command path.** The stream server holds only the event hub. It has no reference to the bus, the agent registry, the tool executor or any control, so no code path leads from the socket to anything that can change state. A test sends `tools/call`, `pause` and `roster.kick` at it and checks that the bus is untouched and the socket only ever sent events.
+- **The window uses the popup host's security unchanged**: a single-use ticket and a one-time WebSocket token per window, loopback bind, strict Host and Origin checks, a nonce CSP, and an allow-list that admits only the four `spectator.*` control events. Every string is drawn as text, never as HTML.
+- **Agents stay untrusted and cannot sign.** The spectator view only observes calls the gate already allowed or refused. No agent at any tier has a tool that can arm, sign, confirm, send, raise a cap, change the gate or touch a wallet, a mandate or the signer, and the spectator view adds no event or control that could. Watching an agent never gives it more power.
+
+The trust page (https://dexterm.xyz/trust/#spectator) has the short version.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-see-also.md

@@ -0,0 +1,29 @@
+---
+id: docs-spectator-see-also
+title: Spectator view (watch the agent cook) › See also
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: See also
+anchor: see-also
+url: https://dexterm.xyz/docs/spectator#see-also
+tags:
+  - docs
+  - spectator
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+- Bring your own agent (https://dexterm.xyz/docs/agents): connecting an agent, tiers, mandates and the untrusted-by-default model.
+- Trust (https://dexterm.xyz/trust/#agents): what any connected agent can never do.
+- `dexterm help spectate`: the same topic from the command line, offline.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-streaming-it.md

@@ -0,0 +1,32 @@
+---
+id: docs-spectator-streaming-it
+title: Spectator view (watch the agent cook) › Streaming it
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: Streaming it
+anchor: streaming-it
+url: https://dexterm.xyz/docs/spectator#streaming-it
+tags:
+  - docs
+  - spectator
+  - streaming
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+- **Capture the window**, not a port. Point your capture tool's window capture at the "watch the agent cook" window, or at the browser window if you're on the browser fallback. "Shareable" here means you capture a window on your own screen. Nothing binds a public address, and you shouldn't forward or tunnel the stream port.
+- **Keep secrets off screen.** Don't show `~/.dexterm/spectator.json`, the `DEXTERM_AGENT_TOKEN` line or `dexterm agent add` output (it prints the agent's token once). `agent serve` prints the token's file path, never the token.
+- **Use fixtures for a show.** `agent serve` without `--live` uses canned data, so no real coin names or market numbers appear. With `--live`, a capture shows whatever real coins the agent looks at.
+- **Record and replay.** Add `--record FILE` so you can share the session afterwards. The file is redacted, so you can attach it to a bug report.
+- The window and the stream show model and agent activity, not advice. Whatever an agent concludes is its own reading of tool results.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-the-three-surfaces.md

@@ -0,0 +1,37 @@
+---
+id: docs-spectator-the-three-surfaces
+title: Spectator view (watch the agent cook) › The three surfaces
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: The three surfaces
+anchor: the-three-surfaces
+url: https://dexterm.xyz/docs/spectator#the-three-surfaces
+tags:
+  - docs
+  - spectator
+  - three
+  - surfaces
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+All three read the same events from one in-memory hub, which `agent serve` creates only when you ask for one of them. Each surface redacts its own copy (see what is redacted (https://dexterm.xyz/docs/spectator#what-is-redacted)). The hub keeps the original events, and they never leave the process.
+
+| surface | start it with | what you get |
+| --- | --- | --- |
+| AGENT ACTIVITY window | `dexterm agent serve --spectator-popup` | a window titled "watch the agent cook" with live activity and the pause, take over and kill controls |
+| read-only stream | `dexterm agent serve --spectate` | a loopback WebSocket that sends events out and accepts no commands |
+| save and replay | `dexterm agent serve --record FILE`, then `dexterm spectate --replay FILE` | a redacted JSONL file of the session that you can replay offline |
+
+The flags combine: `--spectator-popup --spectate --record FILE` runs all three at once, and `--roster` adds the agent roster (https://dexterm.xyz/docs/agents#untrusted-by-default) popup.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-what-is-redacted.md

@@ -0,0 +1,35 @@
+---
+id: docs-spectator-what-is-redacted
+title: Spectator view (watch the agent cook) › What is redacted
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: What is redacted
+anchor: what-is-redacted
+url: https://dexterm.xyz/docs/spectator#what-is-redacted
+tags:
+  - docs
+  - spectator
+  - redacted
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+Redaction runs on every copy that leaves the hub: the stream, the saved file and the AGENT ACTIVITY window.
+
+- **Wallet and token addresses**: any base58 run of 32 to 44 characters becomes `head4…tail4` (`7xKX…gAsU`), the same short form the app uses elsewhere. A full address never appears.
+- **Key material**: any base58 run of 45 or more characters, or a hex run of 64 or more, becomes `[key]` with nothing kept. The gate already refuses every key and signer tool, so key material should never reach an event, and this rule covers it anyway.
+- **Every string field, not just the summary.** The tool name, the refusal reason, the agent's name and every navigation field (screen, token, feed, filter, highlight, side) are scrubbed too. An untrusted agent might put an address or a key in an unknown tool name to smuggle it into the stream. The bus cuts a refused tool name to 64 characters and redaction masks what is left. A test drives that exact attack through the real bus and checks the stream and the saved file.
+- **Sensitive events**: an event marked sensitive keeps only `[sensitive]` as its summary.
+
+What stays readable: phases, tool names, tiers, timings, data ages, refusal codes and verdict labels, which is what makes the stream worth watching. A token symbol, a filter or a number in a summary is shown as it is. If you don't want real coin names in a capture, run on fixtures (the default).

package/dist/packages/mcp/assets/kb/docs/docs-spectator.md

@@ -0,0 +1,29 @@
+---
+id: docs-spectator
+title: Spectator view (watch the agent cook)
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+url: https://dexterm.xyz/docs/spectator
+tags:
+  - docs
+  - spectator
+  - view
+  - watch
+  - agent
+  - cook
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/spectator.md
+date: 2026-10-16
+---
+
+Watch a connected agent work in real time. An AGENT ACTIVITY window with pause, take over and kill, a read-only loopback stream, and redacted save and replay. Covers what is redacted, the security model, how to capture it for a stream, and its limits.
+
+The spectator view lets you watch an agent work: each time a connected agent calls a tool (opens a token, runs a LARP check, scans new pairs, reads a bubble map, makes a proposal, gets refused), the call shows up with its result, how long it took and how old its data was. It is for watching and for demos ("watch the agent cook"). It adds no new power: agents stay untrusted (https://dexterm.xyz/docs/agents#untrusted-by-default), and nothing in the spectator view can arm, sign, confirm or send anything.
+
+It works with agents connected to the **loopback agent bus** that `dexterm agent serve` runs (see bring your own agent (https://dexterm.xyz/docs/agents#two-ways-to-connect)), and — since 0.1.4 — with agents connected over **MCP** (`dexterm mcp install`): run the app with `dexterm --spectate-mcp` and the **running terminal follows the agent** as it works (see follow an MCP agent (https://dexterm.xyz/docs/spectator#follow-over-mcp-in-the-running-terminal)). Read limits (https://dexterm.xyz/docs/spectator#limits) before you rely on it.