dexterm-cli 0.1.2 → 0.1.4

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

@@ -0,0 +1,35 @@
+---
+id: docs-screens-1-screener
+title: Screens tour › 1 · Screener
+kind: docs
+page: screens
+page_title: Screens tour
+heading: 1 · Screener
+anchor: 1-screener
+url: https://dexterm.xyz/docs/screens#1-screener
+tags:
+  - docs
+  - screens
+  - screener
+  - 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 on sample data
+
+A live table of DexScreener + Jupiter rows refreshed every (generated from the app: see https://dexterm.xyz/docs/screens#1-screener; app-help has the exact keys and commands) s through a rate limiter. Columns: price, 5m/1h/6h/24h change, volume, liquidity, market cap, age, holders, organic score, `P(RUG)`, flags, a sparkline. Cells whose source is down show `—` and the panel caption names the column and the reason; safety checks the keyless sources cannot answer render `○ … needs key`, never a pass or a fail.
+
+`P(RUG)` is a **model output, not a fact**: the pre-registered `H1-v0.1` heuristic (an additive points rule, not a learned model) scored from the row's own liquidity, cap, age, holders, organic score, top-10 and dev share and mint/freeze authorities. The panel caption names the model (`p(rug) = H1-v0.1 heuristic`), the spotlight card repeats the value with the model and, on the line under it, how old the scored data is (`p(rug) 0.45 · H1-v0.1 heuristic` / `model output · data 12s old`), and a row with nothing to score shows `—`. Red at or above the model's own flag line (0.50), amber from 0.35. `rug` is a sort key (safest first). Like `FLAGS`, the column is shed first when the table is narrow: with the spotlight open it needs about 184 columns; below that the caption and the spotlight still carry the value and the model id. How well H1 does is measured, not assumed: see backtests (https://dexterm.xyz/docs/analyst#mcp-tools) and the changelog (https://dexterm.xyz/changelog/) for the latest numbers and their sample size.
+
+- `/` opens the filter line. The grammar: space-separated clauses, ANDed. `vol24 > 250K liq > 50K age < 30d org >= 60 launchpad:pump !flag:mint`. Fields and aliases are in the CLI reference (https://dexterm.xyz/docs/cli#filter-grammar). Errors show inline with the column that failed. `\` clears the filter.
+- `s` opens the sort menu; `⏎` on the current key flips the direction.
+- `\[` and `\`] step through the presets: (generated from the app: see https://dexterm.xyz/docs/screens#1-screener; app-help has the exact keys and commands). Gated presets say why they are unavailable (Graduating waits on the bonding feed; Smart money needs a Tier-1 key).
+- `w` watches the highlighted row, `b` proposes a liquidity alert, `⏎` opens the token.
+- The cursor resting on a row for a third of a second prefetches that token's candles when the chart source is idle (capped at 3 a minute), so `⏎` paints the chart instantly.

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

@@ -0,0 +1,28 @@
+---
+id: docs-screens-2-new-pairs
+title: Screens tour › 2 · New pairs
+kind: docs
+page: screens
+page_title: Screens tour
+heading: 2 · New pairs
+anchor: 2-new-pairs
+url: https://dexterm.xyz/docs/screens#2-new-pairs
+tags:
+  - docs
+  - screens
+  - new
+  - pairs
+  - 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
+---
+
+new pairs on sample data
+
+A push stream of pump.fun creates and migrations from PumpPortal on one WebSocket, plus Jupiter `recent` and RugCheck `new_tokens` polls. Bonding progress is estimated from the curve's virtual reserves at create time and says so. The SNIPE and BUNDLE columns and the spotlight's Snipers and Bundled rows come from the wallet-intel scan (https://dexterm.xyz/docs/screens#bubble-map) of the row your cursor rests on, after about 2 s. The scan only runs with a free Helius key, because only Helius history can read the launch window. An unscanned row shows a dash, a scan in flight shows `…`, and without the key the spotlight says `needs Helius key`. No number is guessed. The highlight follows the coin you picked by mint, so a new arrival never shifts your cursor onto another row.

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

@@ -0,0 +1,27 @@
+---
+id: docs-screens-3-watchlist
+title: Screens tour › 3 · Watchlist
+kind: docs
+page: screens
+page_title: Screens tour
+heading: 3 · Watchlist
+anchor: 3-watchlist
+url: https://dexterm.xyz/docs/screens#3-watchlist
+tags:
+  - docs
+  - screens
+  - watchlist
+  - 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 watchlist on sample data
+
+A local SQLite watchlist priced every (generated from the app: see https://dexterm.xyz/docs/screens#3-watchlist; app-help has the exact keys and commands) s, with the LIVE/POLL badge per row. Alerts are proposals until you arm them with `y`; armed rules fire once into the ALERTS log. `d` removes a row. Nothing here trades.

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

@@ -0,0 +1,28 @@
+---
+id: docs-screens-4-analyst-tab
+title: Screens tour › 4 · Analyst tab
+kind: docs
+page: screens
+page_title: Screens tour
+heading: 4 · Analyst tab
+anchor: 4-analyst-tab
+url: https://dexterm.xyz/docs/screens#4-analyst-tab
+tags:
+  - docs
+  - screens
+  - analyst
+  - tab
+  - 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 analyst tab on sample data (the transcript is demo text; a real run spawns your own claude)
+
+A chat beside a navigable coin list. `↑`/`↓` change the selected coin (which updates the context the analyst sees next turn); `PgUp`/`PgDn` scroll the transcript; `i` or `⏎` focuses the input. When an answer lists coins it renders as a table you can navigate: `⏎` opens the coin, `o` opens its PAPER ticket. Details in the analyst (https://dexterm.xyz/docs/analyst).

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

@@ -0,0 +1,32 @@
+---
+id: docs-screens-bubble-map
+title: Screens tour › Bubble map
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Bubble map
+anchor: bubble-map
+url: https://dexterm.xyz/docs/screens#bubble-map
+tags:
+  - docs
+  - screens
+  - bubble
+  - map
+  - 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
+---
+
+`M` on a token opens the holder graph. Each of the top token accounts (merged by owner) is a disc whose **area is its share of supply**, drawn on a half-row pixel grid so it is round in the terminal without any image protocol. **Colour is the rule that labelled the wallet, never a judgement:** yellow dev / dev-linked, magenta bundle, green linked by a shared funder (orange for a direct transfer), red sniper, cyan pool / LP / program-owned vault, grey exchange or multi-token whale, dim unlinked. Linked wallets sit inside a dotted ring with a tag like `B·C1 6w 12.0%`; `j`/`k` select a holder (phosphor, with dotted edges to its cluster mates), `m` flips to a treemap (share, not linkage), `z` zooms the selected cluster, `D` forces a deep scan, `r` rescans, `M` opens the popup window (https://dexterm.xyz/docs/popup-chart#bubble-map-popup).
+
+The rules (from the task-1286 spike, replay-tested against its recordings): **P1 pool** (the selling counterparty in ≥ 25 % of launch transactions), **D1 creator** (fee payer of the first transaction referencing the mint), **R1 funder** (two holders share a funding source; a shared exchange funder is a veto, not a link), **R1b** (a holder funded another holder), **R2 bundle** (same-slot buys **and** a shared funder; same-slot alone is a cohort), **R3 transfer** (a direct token move between two holders, pools excluded), **R4 dev-linked** (funded by the creator), **R5 same-slot-created** (weak, shown, never links), **S1 sniper** (bought in the first 3 slots after the first pool trade), **F1 fresh-at-buy** (the wallet's first transactions already move this token), **X1 multi-token-top20**, and **L0** static lists. The **WHY THIS LABEL** panel leads with the holder's class (POOL, CURVE, VAULT, LOCK, CEX, BURN, DEV, LINKED or UNLABELLED) and the on-chain reason, then prints each rule with its confidence (`on-chain`, `program-authority`, `derived`, `seed`, `weak`) and up to three evidence lines; exchange labels come from a typed seed list and always read **unverified**. Cabal-class labels (cabal-candidate, smart, bot, follower, call-group) are hidden until their precision is measured.
+
+**HOLDER INSIGHTS** print their sample every time (`sample top 20 accts of 142.5K holders · 55% supply · funders 7/20 · launch 300 txs`): top-10 raw (by token account, the explorer number), **ex-pool** (POOL / CURVE / VAULT / LOCK / BURN owners dropped; the cluster-adjusted figure, with linked owners merged and exchanges dropped too, rides underneath), a red **main risk** line when a counted owner holds more than 30 %, snipers, bundled supply, dev share (an upper bound when the creator is outside the sample) and fresh wallets. The token screen's Snipers and Bundled supply rows, the new-pairs SNIPE / BUNDLE columns and the `I` token popup read the same scan.
+
+Two scan tiers, both through the limiter, the health registry and the Helius credit meter: **light** when a token opens (top-20 accounts, owner kinds, funders for the 7 largest wallets, the first 100 launch transactions; about 80 credits, less once funders are cached, since a wallet's first inflow never changes) and **deep** for watchlist coins or on `D` (every top wallet, 300 launch transactions). Funders and the launch window are Helius-only (`getTransactionsForAddress`): **keyless, the map still draws** from the public RPC holder list with static labels and says plainly that a free Helius key adds funders and the launch window; when no endpoint serves the ranked holder list at all, the screen says `unavailable` with the reason and the fix, never a fake map.

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

@@ -0,0 +1,32 @@
+---
+id: docs-screens-coin-images
+title: Screens tour › Coin images
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Coin images
+anchor: coin-images
+url: https://dexterm.xyz/docs/screens#coin-images
+tags:
+  - docs
+  - screens
+  - coin
+  - images
+  - 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
+---
+
+Every row in the screener, new pairs and watchlist carries the coin's picture as a 2-cell icon (dropped silently when the frame is too narrow); the token screen shows an 8×4 picture at the left of its header, the screener's spotlight card a 6×3 one, and the chart popup a 16 px one in its title strip.
+
+- **Real pixels** in terminals with an inline-image protocol: kitty graphics (kitty, Ghostty, WezTerm, Konsole), iTerm2 inline images (iTerm2), sixel where the terminal advertises it. At startup dexterm sends one short capability query to the terminal (≤ 150 ms) and picks the richest protocol it actually answers.
+- **Everywhere else, Apple Terminal.app included: block art.** The picture is sampled into half-block and quadrant cells and, on a 256-colour terminal, dithered into the xterm palette so round logos keep their disc. Not a photo, but recognisable at a glance. `dexterm doctor` has a **Coin images** line that says which path you get; Ghostty or iTerm2 (both free) give the real pictures.
+- **A placeholder, never an error:** while a picture loads, when a coin has none, or when its host is down, the box shows the ticker's initial on a colour hashed from the symbol.
+- **Off switch:** `--no-images`, `DEXTERM_IMAGES=0`, or `~/.dexterm/images.json` (`{"enabled": false}`). Replays and offline runs have no network, so pictures there could only come from the cache: they stay off unless asked.
+- **Privacy:** fetching a picture contacts the host that serves it (DexScreener's image CDN for most coins, otherwise the token's own metadata host). dexterm fetches once through its own local cache and the chart popup is served the cached copy, so an image host never sees a popup load and a coin seen before is never fetched again. `--no-images` keeps every image host from ever seeing your IP. Bytes are treated as hostile: sniffed by magic bytes, capped, and decoded by dexterm's own pure-TypeScript decoders (PNG, JPEG, GIF) — nothing executes. The trust page (https://dexterm.xyz/trust/#privacy) has the statement.

package/dist/packages/mcp/assets/kb/docs/docs-screens-live-holder-and-rug-signals.md

@@ -0,0 +1,51 @@
+---
+id: docs-screens-live-holder-and-rug-signals
+title: Screens tour › Live holder and rug signals
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Live holder and rug signals
+anchor: live-holder-and-rug-signals
+url: https://dexterm.xyz/docs/screens#live-holder-and-rug-signals
+tags:
+  - docs
+  - screens
+  - live
+  - holder
+  - rug
+  - signals
+  - 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
+---
+
+While a token is open, its holder and rug-risk reads update as the data moves, not only when you open the screen. When a reading crosses a threshold, a **LIVE SIGNALS** strip in the ON-CHAIN panel shows a line like `⚑ top-10 concentration 31% → 38% (pools excluded)` with its **source** and the **age** of the data, and a short notice flashes. Each signal is a risk flag to check, not a verdict.
+
+| signal | fires when |
+| --- | --- |
+| dev sell | the creator's share drops by 1 point or more |
+| concentration | the top-10 share (pools excluded) moves by 3 points or more |
+| LP unlock | the locked share of the liquidity drops by 1 point or more |
+| liquidity | liquidity falls by 25 % or more |
+| authority | the mint or freeze authority appears or is revoked |
+| bundle / sniper | bundled supply rises by 1 point, or another sniper appears |
+| fresh wallets | the share of fresh-at-buy wallets rises by 5 points |
+| bonding / migrated | bonding-curve progress rises by 5 points, or the coin migrates |
+
+- **Three cadences, each honest about its source.** Authorities, LP, liquidity and the top-10 share refresh with the token poll (every (generated from the app: see https://dexterm.xyz/docs/screens#live-holder-and-rug-signals; app-help has the exact keys and commands) s). Bonding progress streams sub-second from the same on-chain push as the LIVE price badge. Holder, bundle, sniper and fresh-wallet reads re-scan every 45 s while the token is open, and only with a free Helius key. Keyless, they show a dash and spend no requests.
+- **Stale never fires.** The first reading of each field is a baseline and fires nothing. A reading older than 60 s, or one its source marks stale, never fires a signal and is shown as **stale**, never hidden or filled in. A migration is caught on the next token refresh, not sub-second.
+- **Every signal is an alert trigger.** The rules engine (https://dexterm.xyz/docs/configuration#rules-engine) reads the open token's live fields `top10`, `dev`, `bundled`, `snipers`, `fresh`, `cluster`, `lplocked`, `bonding`, `mintable` and `freezable` (1 when that authority is present), with `.delta` and `.velocity`. A rule can then reach your push channels (https://dexterm.xyz/docs/configuration#push-alerts-and-dexterm-watch):
+
+```text
+when dev.delta < -2 then alert(down, "dev selling")
+when mintable > 0 then alert(warn, "mint authority present")
+when top10.delta > 5 then alert(warn, "concentration up")
+```
+
+The signals read the same keyless and free-tier sources as the rest of the token screen, through the same rate limiter. They raise flags; they cannot trade, arm or sign anything.

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

@@ -0,0 +1,26 @@
+---
+id: docs-screens-order-plans
+title: Screens tour › Order plans
+kind: docs
+page: screens
+page_title: Screens tour
+heading: Order plans
+anchor: order-plans
+url: https://dexterm.xyz/docs/screens#order-plans
+tags:
+  - docs
+  - screens
+  - order
+  - plans
+  - 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
+---
+
+`O` from anywhere opens the order-plans screen: a PLANS / MANDATES tab strip (`tab` flips), each plan on one line with its status tone (proposed, armed, filled, done, cancelled, expired) and the signer's read-back of what it will do. `a` on a row opens a hold-to-arm prompt; only a key held at the terminal arms, and the prompt is unreachable from the popup, voice, an agent or piped input. `c` cancels a plan, `r` revokes a mandate, `!` is panic (revoke everything), `M` opens the read-only plans popup, `G` shows the hands-free gate setting (GATE ON by default), and `L` raises the fire-path prompt: a held keypress switches plan fills between PAPER and LIVE · DEVNET · fast wallet (refused while plans are armed, without the signer process, off devnet or without a fast wallet). The header says PAPER unless a fill path is provably live. Plans, mandates, caps and the journal are in order plans and standing mandates (https://dexterm.xyz/docs/paper-trading#order-plans-and-standing-mandates).

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.