dexterm-cli 0.1.5 → 0.1.6

package/dist/packages/mcp/assets/kb/app-help/spectate-an-agent.md

@@ -22,6 +22,7 @@ commands:
 flags:
   - --replay
   - --spectate-mcp
+  - --spectate-thoughts
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -34,6 +35,6 @@ sources:
 date: 2026-10-16
 ---
 
-Watch an agent work. For an agent on the loopback bus, `dexterm agent serve --spectator-popup` opens the AGENT ACTIVITY window, `--spectate` starts the read-only, token-gated, loopback stream, and `--record FILE` saves a redacted session. For an agent connected over MCP (`dexterm mcp install`), run the app with `dexterm --spectate-mcp`: the running terminal then follows the agent — a navigation call moves the screen, a status line shows `agent <name>: opened <coin>`, ctrl+p pauses, ctrl+k stops and any key you press takes control. `dexterm spectate --replay FILE` replays a saved session step by step and `dexterm spectate --info` shows the live stream endpoint. Every shared copy is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act. Full docs: https://dexterm.xyz/docs/spectator/
+Watch an agent work. For an agent on the loopback bus, `dexterm agent serve --spectator-popup` opens the AGENT ACTIVITY window, `--spectate` starts the read-only, token-gated, loopback stream, and `--record FILE` saves a redacted session. For an agent connected over MCP (`dexterm mcp install`), run the app with `dexterm --spectate-mcp`: the running terminal follows the agent and an agent dock appears under the screen — a phase rail (SCANNING > VETTING > SIZING > EXECUTING > HOLDING > EXITING) with a heartbeat, the call timeline with result chips, the rows it scans glow and a cursor marks the coin it opens, a vetting card fills its checks and LARP evidence, and a PAPER trade shows its ticket, the fill, a live position with the mark PnL and a result card. `--spectate-thoughts FILE` streams the agent's own words into a thought ribbon from a JSONL file it writes (for example `claude -p --output-format stream-json`); display only. PAPER is always on screen; ctrl+p pauses, ctrl+k kills (a hard stop) and any key you press takes control; calm mode drops the motion. While the agent is active, the token screen's analyst panel is its BRAIN VIEW: the reasoning stream with phase tags (or dexterm's narration when there is no thoughts feed), the vetting checklist with the app's numbers and pass/warn/fail/pending, a data strip, the PAPER plan and position, and the session's decision log with a simulated scoreboard. While it holds a PAPER position, a PnL chip shows coin, PnL, entry to mark, peak, drawdown, time held and the take-profit it said, on every terminal screen (in the dock, or on the band under the header on terminals under 24 rows) and on the chart popup; display only. `dexterm spectate --replay FILE` replays a saved session step by step and `dexterm spectate --info` shows the live stream endpoint. Every shared copy is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act. Full docs: https://dexterm.xyz/docs/spectator/
 
 CLI: `dexterm spectate`.

package/dist/packages/mcp/assets/kb/docs/docs-agents-agent-paper-trading.md

@@ -29,7 +29,7 @@ date: 2026-10-16
 
 Two steps, both yours:
 
-1. Draft and arm a mandate (`dexterm mandate draft` / `arm`, or the plans screen). Its caps are per-trade, per-coin and total size, a loss limit, open positions, price impact, allowed sides and an optional mint allow-list, and arming needs a physical keypress.
+1. Draft and arm a mandate (`dexterm mandate draft` / `arm`, or the plans screen). Its caps are per-trade, per-coin and total size, a loss limit, open positions, price impact, allowed sides and an optional mint allow-list, and arming needs a physical keypress. For bigger simulated sizes, draft a **paper-only** mandate with `dexterm mandate draft --paper` (see paper-only mandates (https://dexterm.xyz/docs/paper-trading#paper-only-mandates)): only the agent paper desk can use it.
 2. Start the terminal with the agent activity view and name that mandate: `dexterm --spectate-mcp --agent-paper <mandate-id>`. Quitting turns it off again.
 
 While it is on, the agent can use six tools:
@@ -37,13 +37,14 @@ While it is on, the agent can use six tools:
 - `paper_open_ticket` opens a simulated ticket for a mint and side. It stays inert until confirmed.
 - `paper_size_ticket` sets the simulated size. A buy over any cap is **refused**, never clamped up.
 - `paper_confirm` re-checks the caps and your controls, fetches a fresh keyless quote and books the simulated fill.
-- `paper_close` closes a fraction of a held simulated position.
+- `paper_close` closes a fraction of a held simulated position. If the keyless quote for that close is rate-limited, the desk waits briefly and asks for a fresh quote by itself (up to 4 tries in about 25 seconds, each retry shown in the agent activity) and books the fill on that later quote, never on an old one.
 - `paper_positions` and `paper_pnl` read the simulated positions and PnL. They are read-only.
 
 The guarantees, each covered by tests:
 
 - **It can never sign or send.** No MCP tool can build, sign or send a real transaction, touch a wallet or key, or change a cap. The paper tools book the simulated ledger only. A registry test enumerates every MCP tool, fails on any tool not on its reviewed allow-list, and checks that the paper path imports nothing that signs, sends or arms.
 - **Caps come from your mandate.** The agent's tools never carry caps: on every call the server re-reads the mandate from the hash-chained plans journal you armed it in, and a journal that fails its hash check is refused. That protects the mandate from the agent's tools; it is not tamper-proofing against other software running as your own user. The agent runs at the most restricted confirmation tier, so its per-trade cap is a quarter of the mandate's. Revoking the mandate, letting it expire or pressing the panic key stops the agent on its next call.
+- **The terminal shows what the agent looks at.** While you follow it, `open_token` from the agent moves your screen to coins it was shown by its own reads (the screen, `screener_query`, `narrative_board`) or holds a paper position in, view-only.
 - **You stay in control, and you see everything.** Every call and every refusal shows in this terminal's agent activity, labelled PAPER, and is appended to its own hash-chained audit journal. Ctrl+P pauses and resumes, Ctrl+K stops it for the rest of the run, and any key while the agent is driving takes over; all of them halt its paper calls. Trading calls are refused while nothing is watching.
 - **Only the agent you connected.** The in-app analyst and the scan never get the paper tools. The loopback agent bus does not offer them either.
 

package/dist/packages/mcp/assets/kb/docs/docs-analyst-starting-a-run.md

@@ -30,4 +30,6 @@ Nothing runs behind your back. Opening a token with `⏎` is free. A paid run st
 - type a question (`i` or `⏎` to focus, `⏎` to send). A question is a chat turn on the warm session, or a new session with that question as its first turn, never a structured skill run;
 - let AI scan mode (https://dexterm.xyz/docs/scan) lock a coin.
 
+In an auto mode (following an agent with `--spectate-mcp`, or AI scan mode (https://dexterm.xyz/docs/scan#the-read)), the token screen's analyst panel shows the brain view (https://dexterm.xyz/docs/spectator#the-brain-view-and-the-pnl-chip) until you type into it.
+
 Each token keeps its own conversation for the run; the analyst tab has its own. `esc` interrupts a running answer from any screen. The caption under an answer shows cost, latency, tool calls and the model.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-chart-y-axis.md

@@ -0,0 +1,32 @@
+---
+id: docs-configuration-chart-y-axis
+title: Configuration and files on disk › Chart Y axis
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Chart Y axis
+anchor: chart-y-axis
+url: https://dexterm.xyz/docs/configuration#chart-y-axis
+tags:
+  - docs
+  - configuration
+  - chart
+  - axis
+  - files
+  - disk
+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/configuration.md
+date: 2026-10-16
+---
+
+Both charts, the terminal token chart and the popup chart (https://dexterm.xyz/docs/popup-chart#market-cap-axis), plot **market cap** on the Y axis by default, for new and existing configs alike. It is separate from the price display mode (https://dexterm.xyz/docs/configuration#price-display-mode): `A` on the token screen (or the popup's **MCAP | PRICE** control) flips the axis between market cap and USD price and saves it as `"display": { "chartAxis": "price" }` (or `"mcap"`; absent means `mcap`) through the journal, so `ctrl+z` undoes it. `dexterm display` prints both settings.
+
+- Axis labels, the last-value tag, the crosshair legend and the volume use one compact formatter: a lowercase k for thousands, then M, B, T; one decimal below 10 of the unit and none after (`$4.9k`, `$42k`, `$487k`, `$1.2M`, `$48M`, `$1.3B`), never scientific notation. When two neighbouring ticks would read the same, the axis adds one decimal (`48.3M`).
+- Historical candles are scaled by the **current** supply, and the chart title says `MCAP (current supply)` so nobody reads it as the exact market cap at that time (a burn or a mint since then is not reflected). The bars stay USD prices underneath, so indicators, PAPER entry / stop / target lines and fills keep their meaning; only the labels change.
+- A token without a known supply plots its price and the title says `price (mcap unavailable)`. In price mode tiny prices use the subscript form (`0.0₅493`).
+- While following an agent, the HUD's PAPER position card reads entry and mark as market cap (`entry MC $4.7k`) when the axis is market cap and the supply is known.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-price-display-mode.md

@@ -27,9 +27,9 @@ date: 2026-10-16
 
 Memecoin traders think in market cap, so every token price can be shown as **market cap** instead of the USD price per token. It is a display mode only: the same data underneath, no extra requests, and nothing that trades (signer, caps, tickets, plans, the confirm gate) reads it.
 
-- `$` flips price ⇄ market cap on every screen and both charts, and saves it to `config.json` as `"display": { "priceMode": "mcap" }` (or `"price"`, the default) through the journal, so `ctrl+z` undoes it. `dexterm display [price|mcap]` shows or sets it from the command line; `--price-mode price|mcap` overrides it for one run; a workspace may carry `"priceMode"` and switches to it while active.
+- `$` flips price ⇄ market cap on every screen (the charts have their own Y axis setting (https://dexterm.xyz/docs/configuration#chart-y-axis)), and saves it to `config.json` as `"display": { "priceMode": "mcap" }` (or `"price"`, the default) through the journal, so `ctrl+z` undoes it. `dexterm display [price|mcap]` shows or sets it from the command line; `--price-mode price|mcap` overrides it for one run; a workspace may carry `"priceMode"` and switches to it while active.
 - Market cap = price × supply, where the supply is what the data sources already report (the row's market cap ÷ its price at the latest tick). The screener, watchlist and new pairs lead with **MCAP** (the PRICE column moves to MCAP's old place, every sort key works as before, `mcap` still sorts by market cap); the watchlist's entry becomes **ENTRY MC**; spotlights and the token header lead with the market cap and keep the price beside it.
-- Charts: the terminal chart and the popup chart (https://dexterm.xyz/docs/popup-chart#market-cap-axis) label the Y axis in K / M / B (`300K`, `1.2M`). Historical candles are scaled by the **current** supply, and the chart title says `mcap (current supply)` so nobody reads it as the exact market cap at that time (a burn or a mint since then is not reflected).
+- Charts have their own setting, the chart Y axis (https://dexterm.xyz/docs/configuration#chart-y-axis) (market cap by default); `$` does not change it.
 - Order plans already trigger on market cap: the `O` screen and the plans popup show each level with both numbers (`entry mc ≤ $300K ($0.0₃3)`), the price taken from the plan's own supply snapshot. Position rows read **AVG MC** / **MCAP**; profit and loss stay in USD (or SOL on the paper screen).
-- A token without a known supply falls back to its price and says so: `ᵖ` after the number in a table (the panel caption counts them), `supply unknown · showing price` on the spotlight, the header and the chart title. Nothing is estimated.
+- A token without a known supply falls back to its price and says so: `ᵖ` after the number in a table (the panel caption counts them), `supply unknown · showing price` on the spotlight and the header. Nothing is estimated.
 - `config.json` moved to **v4** for this: an older file is migrated on load (`display.priceMode = price` added, a backup kept as `config.json.bak-v3`), nothing else changes.

package/dist/packages/mcp/assets/kb/docs/docs-getting-started-install.md

@@ -41,10 +41,10 @@ $ dexterm doctor
 The package is named `dexterm-cli` because npm refuses the name `dexterm` as too similar to `xterm`. The command it installs is `dexterm`. The package ships compiled JavaScript, so it needs no build step. Every GitHub release carries a build-provenance attestation and `SHA256SUMS` you can verify (see the trust page (https://dexterm.xyz/trust/)).
 
 ```sh install from the release
-$ # download dexterm-0.1.5-src.tar.gz and SHA256SUMS from the releases page, then:
+$ # download dexterm-0.1.6-src.tar.gz and SHA256SUMS from the releases page, then:
 $ shasum -a 256 -c SHA256SUMS --ignore-missing
-$ gh attestation verify dexterm-0.1.5-src.tar.gz --repo dexterm-xyz/dexterm
-$ tar -xzf dexterm-0.1.5-src.tar.gz && cd dexterm-0.1.5
+$ gh attestation verify dexterm-0.1.6-src.tar.gz --repo dexterm-xyz/dexterm
+$ tar -xzf dexterm-0.1.6-src.tar.gz && cd dexterm-0.1.6
 $ ./install.sh
 $ dexterm doctor
 ```

package/dist/packages/mcp/assets/kb/docs/docs-getting-started-requirements.md

@@ -32,4 +32,4 @@ date: 2026-10-16
 | optional: a free RPC key | the ranked top-20 holder list and faster chain reads | Helius, Alchemy, QuickNode or Ankr free tier; see configuration (https://dexterm.xyz/docs/configuration). |
 | optional: Rust (`cargo`) | the native docked chart window | without it the chart popup opens in your browser; see popup chart (https://dexterm.xyz/docs/popup-chart). |
 
-> note: dexterm 0.1.5 is out (2026-10-18), open source under AGPL-3.0-only at github.com/dexterm-xyz/dexterm (https://github.com/dexterm-xyz/dexterm). It is early: trading is experimental and has known bugs. The release ships checksums, a build-provenance attestation and an SBOM, and its VirusTotal result (including flags we explain) is on the trust page (https://dexterm.xyz/trust/). It is also on npm as `dexterm-cli` (https://www.npmjs.com/package/dexterm-cli); the command it installs is still `dexterm`.
+> note: dexterm 0.1.6 is out (2026-10-20), open source under AGPL-3.0-only at github.com/dexterm-xyz/dexterm (https://github.com/dexterm-xyz/dexterm). It is early: trading is experimental and has known bugs. The release ships checksums, a build-provenance attestation and an SBOM, and its VirusTotal result (including flags we explain) is on the trust page (https://dexterm.xyz/trust/). It is also on npm as `dexterm-cli` (https://www.npmjs.com/package/dexterm-cli); the command it installs is still `dexterm`.

package/dist/packages/mcp/assets/kb/docs/docs-getting-started-running-the-tests.md

@@ -25,7 +25,7 @@ sources:
 date: 2026-10-16
 ---
 
-From a source checkout, `npm install` and then `npm test` runs the typecheck and three test lanes, in order (from 0.1.4, not in a release yet):
+From a source checkout, `npm install` and then `npm test` runs the typecheck and three test lanes, in order (since 0.1.4):
 
 - **parallel**: every `packages/*/test/*.test.ts` file at once, one process each.
 - **serial** (`npm run test:serial`, `packages/*/test/serial/`): the tests that drive a real terminal through a pty, run the real binary, or assert a wall-clock bound (the under-a-second quit, the 50 ms filter fuzz). They run one file at a time after the parallel lane, so they never share the CPU with it.

package/dist/packages/mcp/assets/kb/docs/docs-larp-measured-accuracy.md

@@ -29,6 +29,7 @@ date: 2026-10-16
 
 - **LARP check, links only.** The links-based baseline is a weak signal: MCC 0.039 before tuning, 0.054 after. Its tuned `LARP` grade caught 4 of 14 bad coins, too few to rate. `EARLY_BUT_REAL` coins still went bad 10.3 % of the time, and coins with no website 29.2 %. The skill now treats the baseline as a weak prior and never calls `LARP` from links alone.
 - **Rug check.** The verdict rules improved from MCC 0.043 to 0.159. Liquidity under $5k is the one strong signal (`SPECULATIVE` coins went bad 54.8 % of the time, `WATCH` 14.4 %). Dev percentage, organic score and top-10 share did not predict a worse 72 h outcome and now only lower confidence.
+- **LARP score, link-shape part** (`dexterm backtest --subject larp-score`, task-1471). Points fitted on the train split only. On the 328 held-out coins its AUROC is 0.69 (0.73 on train): a modest ranking signal. 27 of 218 low-band coins went bad (12.4 %), 34 of 110 medium-band coins (30.9 %), against 18.6 % overall; no coin reaches the high band from link shape alone. The page, domain, GitHub and X points are not measured: that evidence was not recorded at the time, and looking it up now would leak the outcome (dead coins' sites and accounts disappear).
 - **Not measured.** The model stage (fetched pages, RDAP, GitHub) cannot be replayed: a past page cannot be fetched as it was. It is measured going forward with `dexterm backtest --subject larp`, below.
 
 The method, every number and the limits are in the repository at `packages/packs/eval/README.md`. A grade is a risk flag, not a certificate.

package/dist/packages/mcp/assets/kb/docs/docs-larp-the-larp-score.md

@@ -0,0 +1,60 @@
+---
+id: docs-larp-the-larp-score
+title: LARP detector › The LARP score
+kind: docs
+page: larp
+page_title: LARP detector
+heading: The LARP score
+anchor: the-larp-score
+url: https://dexterm.xyz/docs/larp#the-larp-score
+tags:
+  - docs
+  - larp
+  - score
+  - detector
+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/larp.md
+date: 2026-10-16
+---
+
+`larp_check` also returns a **LARP score from 0 to 100**: the sum of named flags, each with its points and the evidence that raised it. Higher means more of the things that went with LARP coins showed up. It summarises the flags; it is not a verdict and does not replace the one above.
+
+| band | score | |
+|---|---|---|
+| low | under 25 | few flags |
+| medium | 25 to 49 | several flags; link shape alone tops out here |
+| high | 50 or more | needs page, domain, GitHub or X evidence, not link shape alone |
+
+| flag | points | weight |
+|---|---|---|
+| no Telegram advertised | 12 | fitted |
+| no X account advertised | 10 | fitted |
+| no website advertised | 9 | fitted |
+| X link is a single post or a community, not an account | 5 | fitted |
+| the "website" is a social page | 1 | fitted |
+| the domain does not name the token · throwaway-priced TLD | 0 | fitted (did not go with bad outcomes, so not listed) |
+| launchpad / link-hub / free-host page as the website | 4 / 2 / 2 | prior (too rare to fit) |
+| sources advertise different sites or X accounts | 8 | prior |
+| wallet-drainer markers on the page | 30 | prior |
+| default or placeholder page | 15 | prior |
+| asks to connect a wallet · never names the token | 8 · 8 | prior |
+| domain under 30 days old · registrant privacy | 8 · 2 | prior |
+| no GitHub advertised · archived · a fork · no push in 180 days | 2 · 4 · 4 · 4 | prior |
+| X account suspended · does not exist | 20 · 15 | prior |
+| X account under 7 days old (or under 30 days) | 12 (6) | prior |
+| under 50 followers · no posts in 30 days | 5 · 6 | prior |
+| the website's X link and the advertised account differ | 10 | prior |
+| a linked post now shows another handle · the account does not link the site | 5 · 3 | prior |
+
+**Fitted** points come from the recorded history below (link shape is the only part of the check that history can replay). **Prior** points were written from the skill's rules before any data and are labelled `prior` in every result.
+
+**Missing data never lowers the score.** A page that could not be read, an RDAP or X lookup that failed, goes to a `missing` list with the points it could have added, and the result shows the range: "37, could be up to 58". Nothing unread is scored as clean.
+
+Where it shows: the `larp_check` MCP result (`score`, `band`, and `larp_score` with every flag, its points, its weight and its evidence, the range and the `missing` list; the existing fields are unchanged), the analyst panel after a LARP check (a gauge with the three biggest reasons, drawn from the tool's own result, never from the model's text).
+
+> warn: a LARP verdict is a risk flag, not a certificate. Public HTML cannot prove a working product, a team's identity or who owns an account; domain age, a clean script scan and a GitHub with commits are evidence, not proof, and a real product can still go to zero.

package/dist/packages/mcp/assets/kb/docs/docs-larp-the-verdict.md

@@ -25,5 +25,3 @@ date: 2026-10-16
 The `larp-check` skill returns a structured assessment: `REAL_PRODUCT` · `EARLY_BUT_REAL` · `LARP` · `UNVERIFIABLE` · `AMBIGUOUS`, with a confidence, a status per claim (supported, contradicted, unverifiable), `missing_data`, the facts and flags it used, `injection_detected` and a short summary. It is separate from the dossier's risk verdict and does not replace it.
 
 Once computed, a badge appears in the screener's FLAGS column and in the token screen's title strip for that mint only: **LARP** (red), **REAL** (green), **REAL?** (mixed), **UNKNOWN** for unverifiable or ambiguous. Nothing shows before you vet a coin. A `LARP` verdict also vetoes an AI scan (https://dexterm.xyz/docs/scan) lock on that coin.
-
-> warn: a LARP verdict is a risk flag, not a certificate. Public HTML cannot prove a working product, a team's identity or who owns an account; domain age, a clean script scan and a GitHub with commits are evidence, not proof, and a real product can still go to zero.

package/dist/packages/mcp/assets/kb/docs/docs-larp-what-it-looks-at.md

@@ -29,5 +29,8 @@ date: 2026-10-16
 | the domain | RDAP lookup of the exact advertised domain (`check_domain`) | registration age, registrar, registrant privacy. A days-old domain behind privacy is a mild signal, not proof. Novelty TLDs without an RDAP server come back as unverifiable. |
 | GitHub | the keyless GitHub API (`check_github`) for a `github.com/owner/repo` link | created and last-push dates, stars, open issues, archived or fork, up to five real commit hashes with dates |
 | pump.fun metadata | the metadata URI GoPlus reports, through the same safe fetch | the advertised description and links, when they exist |
+| the X account | a keyless public lookup (`check_x`): FxTwitter, then vxtwitter's cached copy, then X's own oEmbed. No login, no API key, one handle per check, cached 30 minutes, at least a second between calls to each host | whether the account exists, is suspended or is gone; when it was created; followers, following and posts; the last post date; whether the bio names the token and links the site; whether the website's own X link matches the advertised one; and, for a link to a single post, whether that post now shows another handle |
 
-X is usually login-walled keyless, so account age and follower counts are reported as unverifiable rather than guessed. Every fetched string reaches the model through the prompt firewall: normalised, control and bidi characters stripped, URLs and addresses masked, wrapped as untrusted data, tags stripped so a planted closing tag cannot break out.
+**How the X lookup decides.** No single source is trusted on its own. On 2026-10-19 FxTwitter answered "user not found" for accounts that exist on roughly one call in six, so one "not found" is never enough: an account is `not_found` only when two independent sources (vxtwitter and X oEmbed) agree, `suspended` when a source says so, and otherwise `unavailable`. vxtwitter serves a cached copy, so its counts carry the time it was taken. Nitter-style mirrors and the X embed timeline were down or rate-limited every time and are not used. Each source has a circuit breaker and backs off when it keeps failing. Anything the lookup could not read is listed as unavailable, never guessed and never counted as clean. The bio is untrusted text like any page.
+
+Every fetched string reaches the model through the prompt firewall: normalised, control and bidi characters stripped, URLs and addresses masked, wrapped as untrusted data, tags stripped so a planted closing tag cannot break out.

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

@@ -19,6 +19,6 @@ sources:
 date: 2026-10-16
 ---
 
-Vet the product behind a coin: its website, domain registration and GitHub, read-only, only when you ask.
+Vet the product behind a coin: its website, domain registration, GitHub and X account, read-only, only when you ask, with a 0-100 LARP score that shows every point.
 
 A memecoin's advertised website, X and Telegram are claims. The LARP detector fetches what it can, reads it mechanically, and lets the analyst grade the claims against what it found. It runs only when you press `V` on a live token; nothing is fetched automatically.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-order-plans-and-standing-mandates.md

@@ -33,12 +33,4 @@ Merged 2026-10-11 (`task-1355`) and labelled **in progress**: the engine, the ty
 
 An **order plan** is "buy this coin if it dips to 300k market cap, sell half at 600k, keep the rest as a moon bag", written down once: one entry trigger (market cap or price, below or above, or immediate), a ladder of take-profit tranches (each an above-trigger with a fraction; whatever the fractions leave is the moon bag), an optional stop (a below-trigger, below the entry), slippage and impact ceilings and an expiry (4 h by default, 7 days at most). `dexterm plan propose --mint M --size 20 --entry mc-below:300k --tp mc-above:600k:50% --stop mc-below:150k` writes one; so does saying it to Jarvis (https://dexterm.xyz/docs/voice) or an agent's `propose_order_plan` tool. All three produce the same thing: an **inert proposal** with a SHA-256 hash of its material fields and a plain-language read-back. A proposal fires nothing.
 
-A **standing mandate** is the budget a set of plans may spend: a total, a per-trade cap, a per-coin cap, a daily-loss cap, the highest confirmation tier it accepts and a time-to-live. Every cap is clamped to a hard ceiling ($2000 total, $500 per trade, $1000 per coin, $2000 daily loss, 24 h) and nothing is ever coerced upward: there is no "raise cap" anywhere; a different cap is a new draft that needs a new arming gesture. `dexterm mandate draft --total 100 --per-trade 20 --ttl-hours 4` writes one.
-
-**Arming** a plan under a mandate is the only step that lets anything fire, and it is a physical gesture: a key held at the terminal on the `O` screen (`a`) or `dexterm plan arm <id> --mandate <id>` on a real TTY, which refuses a pipe or a subprocess. The gesture proof is bound to the plan hash, single-use and expiring, so an edited plan voids every earlier confirmation. Once armed, a monitor fed by the prices the terminal already shows (the screener rows, the watchlist, the open token; never fixture data) fires the entry, each take-profit tranche and the stop **only inside the armed plan and only through the executor**, which re-checks the mandate caps on every fill (and, on the live path, the signer re-checks its own caps, allow-lists and the panic marker on top). `dexterm plan amend <id> --size 25 --entry mc-below:280k` edits a **proposed** plan: the edit is a new plan with a new hash, the old proposal is superseded and every earlier confirmation is void, so arming it is a new keypress; an armed plan cannot be edited (cancel it first). Cancel (`c`), revoke (`r`) and panic (`!`, or `dexterm wallet panic`) stop a plan at once; nothing resumes a paused plan without a new keypress.
-
-Two **confirmation tiers** beyond the keypress exist in the model and are off by default: `ptt-held` (push-to-talk held while you speak the confirmation) fires at 0.5× the per-trade cap and `hands-free` at 0.25×, and neither can arm a mandate or a batch. Turning hands-free on is the only "less safe" switch in dexterm: `G` on the `O` screen raises a prompt that says so, it is accepted by a keypress only (a spoken, agent or Phantom "yes" is refused), it is journaled, it expires after 24 h and `G` again restores the gate.
-
-The **journal** (`~/.dexterm/plans.journal`) is append-only and hash-chained; every proposal, arm, fire, fill, cancel, revoke, gate change and refusal is a row, `dexterm plan journal --verify` recomputes the chain and `--export` dumps it, and it is the source the service recovers from after a crash. The popup is a read-only HUD fed view models only (never a key, a secret or an arm capability); its single write is "cancel this plan", re-validated at the server allow-list and again at the terminal.
-
-What is proven, on fixtures and a fake clock: the north-star plan fills end to end on the paper executor; a replayed price stream fires each leg once; and a compromised-model suite shows that spoken text, agent text, a forged proof, a replayed proof, a widened mandate and an edited plan with an old confirmation all fail to arm, raise a cap, widen a mandate, resume a paused plan, accept the risk prompt or switch the fire path.
+A **standing mandate** is the budget a set of plans may spend: a total, a per-trade cap, a per-coin cap, a daily-loss cap, the highest confirmation tier it accepts and a time-to-live. Every cap is clamped to a hard ceiling ($2000 total, $500 per trade, $1000 per coin, $2000 daily loss, 24 h) and nothing is ever coerced upward: there is no "raise cap" anywhere; a different cap is a new draft that needs a new arming gesture. `dexterm mandate draft --total 100 --per-trade 20 --ttl-hours 4` writes one; `--max-open N` and `--max-impact PCT` set the open-position and price-impact limits (clamped the same way).

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-paper-only-mandates.md

@@ -0,0 +1,41 @@
+---
+id: docs-paper-trading-paper-only-mandates
+title: Paper trading, live trading and the safety model › Order plans and standing mandates › Paper-only mandates
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Paper-only mandates
+anchor: paper-only-mandates
+url: https://dexterm.xyz/docs/paper-trading#paper-only-mandates
+tags:
+  - docs
+  - paper-trading
+  - paper-only
+  - mandates
+  - order
+  - plans
+  - standing
+  - paper
+  - trading
+  - live
+  - safety
+  - model
+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/paper-trading.md
+date: 2026-10-16
+---
+
+`dexterm mandate draft --paper` drafts a **paper-only** mandate for agent paper trading (https://dexterm.xyz/docs/agents#agent-paper-trading). It has its own, higher paper ceilings ($10,000 total, $2000 per trade, $2000 per coin, $10,000 daily loss, 10% price impact) so an agent can practise at a realistic size, and it still needs your physical keypress to arm. Only the agent paper desk reads it: the plan engine refuses to arm a plan into it, fire a plan under it or run copy trading through it, so it can never reach a signer, and every other mandate keeps the ceilings above. The agent still gets a quarter of its per-trade cap, and every fill is priced on a live quote, so a bigger simulated size pays its real price impact.
+
+**Arming** a plan under a mandate is the only step that lets anything fire, and it is a physical gesture: a key held at the terminal on the `O` screen (`a`) or `dexterm plan arm <id> --mandate <id>` on a real TTY, which refuses a pipe or a subprocess. The gesture proof is bound to the plan hash, single-use and expiring, so an edited plan voids every earlier confirmation. Once armed, a monitor fed by the prices the terminal already shows (the screener rows, the watchlist, the open token; never fixture data) fires the entry, each take-profit tranche and the stop **only inside the armed plan and only through the executor**, which re-checks the mandate caps on every fill (and, on the live path, the signer re-checks its own caps, allow-lists and the panic marker on top). `dexterm plan amend <id> --size 25 --entry mc-below:280k` edits a **proposed** plan: the edit is a new plan with a new hash, the old proposal is superseded and every earlier confirmation is void, so arming it is a new keypress; an armed plan cannot be edited (cancel it first). Cancel (`c`), revoke (`r`) and panic (`!`, or `dexterm wallet panic`) stop a plan at once; nothing resumes a paused plan without a new keypress.
+
+Two **confirmation tiers** beyond the keypress exist in the model and are off by default: `ptt-held` (push-to-talk held while you speak the confirmation) fires at 0.5× the per-trade cap and `hands-free` at 0.25×, and neither can arm a mandate or a batch. Turning hands-free on is the only "less safe" switch in dexterm: `G` on the `O` screen raises a prompt that says so, it is accepted by a keypress only (a spoken, agent or Phantom "yes" is refused), it is journaled, it expires after 24 h and `G` again restores the gate.
+
+The **journal** (`~/.dexterm/plans.journal`) is append-only and hash-chained; every proposal, arm, fire, fill, cancel, revoke, gate change and refusal is a row, `dexterm plan journal --verify` recomputes the chain and `--export` dumps it, and it is the source the service recovers from after a crash. The popup is a read-only HUD fed view models only (never a key, a secret or an arm capability); its single write is "cancel this plan", re-validated at the server allow-list and again at the terminal.
+
+What is proven, on fixtures and a fake clock: the north-star plan fills end to end on the paper executor; a replayed price stream fires each leg once; and a compromised-model suite shows that spoken text, agent text, a forged proof, a replayed proof, a widened mandate and an edited plan with an old confirmation all fail to arm, raise a cap, widen a mandate, resume a paused plan, accept the risk prompt or switch the fire path.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-market-cap-axis.md

@@ -25,4 +25,4 @@ sources:
 date: 2026-10-16
 ---
 
-When the terminal is in market cap mode (https://dexterm.xyz/docs/configuration#price-display-mode) (`$`), the popup follows it within a tick: the Y axis, the last-value and position-line labels, the EMA / VWAP values and the header read **market cap** in K / M / B (`300K`, `1.2M`), and the crosshair legend shows the market cap with the price in parentheses (`C 1.2M ($0.0₃12)`). The window title says `mcap (current supply)`: every bar is scaled by today's supply (market cap ÷ price at the latest tick, as the terminal knows it), so older bars are not the exact market cap of their time. The bars themselves stay USD prices, so the entry, stop and target lines and the fill markers keep their meaning; only the labels change. When the coin has no known supply the popup keeps prices and the title says `supply unknown · showing price`. The position row reads AVG MC / MCAP; profit and loss stay in USD.
+The Y axis shows **market cap by default**. The **MCAP | PRICE** control in the toolbar, `A` or `y` in the popup, or `A` on the terminal's token screen switches it; the terminal saves the choice (`display.chartAxis`, see chart Y axis (https://dexterm.xyz/docs/configuration#chart-y-axis)) and the popup follows within a tick. In market cap the Y axis, the last-value and position-line labels (ENTRY, STOP, TARGET), the EMA / VWAP values and the header read **market cap** in compact form with a lowercase k (`4.9k`, `487k`, `1.2M`, `1.3B`), and the crosshair legend shows the market cap with the price in parentheses (`C 1.2M ($0.0₃12)`). The volume pane stays USD, also compact (`$20k`). In price mode the axis uses the subscript form for tiny prices (`0.0₅493`), never scientific notation. The window title says `mcap (current supply)`: every bar is scaled by today's supply (market cap ÷ price at the latest tick, as the terminal knows it), so older bars are not the exact market cap of their time. The bars themselves stay USD prices, so the entry, stop and target lines and the fill markers keep their meaning; only the labels change. When the coin has no known supply the popup keeps prices and the title says `price (mcap unavailable)`. The position row reads AVG MC / MCAP; profit and loss stay in USD.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-what-it-shows.md

@@ -27,4 +27,5 @@ date: 2026-10-16
 - the last-price line, and a dotted **LIVE** price line while the terminal's fast lane is streaming the coin; a `◌ STALE Ns` badge when no tick has arrived for 20 s.
 - buy and sell markers from the trade tape, EMA 9/21, VWAP (anchored to the UTC day), a volume 20-MA, horizontal and trend lines you draw (page memory only; they go when the popup closes).
 - when you hold a PAPER position in the coin: an ENTRY line labelled with size and PnL %, BUY and SELL fill markers for the current position, STOP and TARGET lines when a ledger sets them, and the same position row the terminal shows under its chart.
+- while an auto mode runs and a position is open (an agent you follow holds a PAPER position, or AI scan mode with your own position), the PnL chip (https://dexterm.xyz/docs/spectator#the-brain-view-and-the-pnl-chip) under the toolbar, with the same fields as the terminal's. It is about the held coin, which need not be the coin on the chart. Display only.
 - the six timeframes are the popup's own. 5m and 15m are derived from the cached 1m base, 4h and 1d from the cached 1h base, so switching costs no fetch; a base the terminal has not fetched yet shows an honest "warming … no extra requests" banner until it lands. **1s is not offered:** the only trade source is a ≤60-trade tape refreshed at most every 20 s, so 1-second bars would be sparse and stale.

package/dist/packages/mcp/assets/kb/docs/docs-scan-the-read.md

@@ -23,3 +23,5 @@ date: 2026-10-16
 ---
 
 A lock opens the coin exactly as `⏎` would (the same loader, the same fetches that token costs anyway) and starts a chat turn asking for the short read, with the WHY reasons passed as **numbers only, never token text**. Refreshes ask the same warm session what changed. Answers follow the short style (https://dexterm.xyz/docs/analyst#answer-style): call, why, levels, size, one risk.
+
+While the scan is on, the token screen's analyst panel is the scan's **brain view** (on the locked coin, or on any coin while it is still scanning). It shows the scan's own log (on, locks with their score and reasons, refreshes, releases, cancels and blocked actions) with the scan analyst's answer streaming under it, the vetting checklist and data strip for the coin with the app's numbers, and a `SCAN LOG` with `locks · reads · ai usage · observe-only · never trades`. It is the same layout as the agent brain view (https://dexterm.xyz/docs/spectator#the-brain-view-and-the-pnl-chip), with no position block, because the scan never trades. Typing into the analyst, or stopping the scan, brings the normal panel back. While the scan runs and you hold a paper or live position yourself, the PnL chip (https://dexterm.xyz/docs/spectator#the-brain-view-and-the-pnl-chip) shows it on the band under the header of every screen and on the chart popup. It shows the coin the scan locked if you hold it, otherwise the coin on screen, otherwise your first open position. The peak is this session's highest mark, and TP is the ledger's target (`TP not set` when there is none). The scan still never trades.

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

@@ -25,16 +25,19 @@ date: 2026-10-16
 
 *Since 0.1.5.* "Has this deployer rugged before?" The ON-CHAIN panel adds the creator's **recorded** track record, from dexterm's own history recorder (https://dexterm.xyz/docs/configuration#history-recorder), keyless:
 
-| row | what it shows |
-| --- | --- |
-| Dev rugs (recorded) | rugs out of the creator's **labelled** prior launches, with the sample (`2/5 · n=5`); red at two or more (the `serial_rugger` flag), `unknown` with no labelled record |
-| Dev launches seen | prior launches the recorder linked to this wallet, and which source named the creator |
-| Dev sold its bag | median minutes from launch to the dev's exit on prior launches (held over 0.5 % of supply, then 0.1 % or less), with n |
-| Dev linked | the creator's funder or the linked cluster it sits in (same funder, same-block bundle, transfers) from the wallet-intel scan (https://dexterm.xyz/docs/screens#bubble-map), and how many of those wallets launched coins that rugged |
+| row | what it shows | example |
+| --- | --- | --- |
+| Dev rugs | rugs out of the creator's **labelled** prior launches, the sample, and how long ago the newest of those labels settled; red at two or more (the `serial_rugger` flag), `unknown` with no labelled record | `2/5 · n=5 · rec 3d` |
+| Dev launches | prior launches the recorder linked to this wallet, how long ago the newest was seen, and which feed named the creator (`jup`, `pump`, `rc`) | `n=5 · rec 2h · dev:jup` |
+| Dev sold bag | median minutes from launch to the dev's exit on prior launches (held over 0.5 % of supply, then 0.1 % or less), the sample, and the age of the newest exit seen | `med 20m · n=3 · rec 1d` |
+| Dev linked | the creator's funder or the linked cluster it sits in (same funder, same-block bundle, transfers) from the wallet-intel scan (https://dexterm.xyz/docs/screens#bubble-map), and how long ago that scan ran | `funder 3w · scan 4m` |
+| Linked dev rugs | labelled rugs by the other wallets in that cluster that dexterm saw launching coins, how many such wallets, and the age of their newest label | `1 · n=1 devs · rec 7d` |
+
+`rec` is dexterm's own recorder, `scan` the wallet-intel scan; every age is how old the newest datum behind the number is.
 
 - **Where the creator comes from.** The wallet a keyless source names when dexterm sees the coin: Jupiter's `dev` field on every token row, a PumpPortal create, or RugCheck's new-token feed. The first source wins and is recorded with the time. GoPlus is asked only by the MCP tool, as a last resort.
 - **Where the outcomes come from.** The recorder's code-only labels (rug, dead, fade, flat, runner; the 72-hour label when known, else the longest one settled). They are the keyless-proxy tier: a rug is a liquidity collapse the recorder saw, not a verified on-chain drain.
-- **Honest by construction.** Every number names its sample and age. No record is `unknown`, never "clean". Only coins this machine's recorder saw count, so a deployer's launches dexterm never saw are missing; run `dexterm record` (https://dexterm.xyz/docs/configuration#headless-recorder-dexterm-record) to keep it fed. It is a risk flag from observed history, never a certificate.
+- **Honest by construction.** Every row names its source, its sample and the age of its newest datum. No record is `unknown`, never "clean". Only coins this machine's recorder saw count, so a deployer's launches dexterm never saw are missing; run `dexterm record` (https://dexterm.xyz/docs/configuration#headless-recorder-dexterm-record) to keep it fed. It is a risk flag from observed history, never a certificate. On a window too short for every ON-CHAIN row, the red, then amber rows stay and the last line says how many rows are hidden (`+3 rows hidden`).
 - **Alerts.** The rule field `devrugs` is the creator's labelled rugs (unknown = no match). A brand-new pair from a wallet with a record joins the rule rows, so this fires on launch:
 
 ```text

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

@@ -32,7 +32,7 @@ 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. From 0.1.5, if you start with `--agent-paper <mandate-id>`, the agent's **simulated** trades show here too as `PAPER …` rows. They never move your screen, and Ctrl+P, Ctrl+K and taking over halt them (agent paper trading (https://dexterm.xyz/docs/agents#agent-paper-trading)).
+- A **navigation** call (open a token, switch screen or feed, set a filter, highlight a row, open the paper ticket) moves the real screen. The agent HUD (https://dexterm.xyz/docs/spectator#the-agent-hud-spectator-v2) shows the move (a terminal shorter than 24 rows gets a status line like `agent <name>: opened BONK` instead). These are the same read-only moves the analyst makes; nothing an agent does here can size, confirm, sign, send or raise a cap. From 0.1.5, if you start with `--agent-paper <mandate-id>`, the agent's **simulated** trades show here too as `PAPER …` rows. They never move your screen, and Ctrl+P, Ctrl+K and taking over halt them (agent paper trading (https://dexterm.xyz/docs/agents#agent-paper-trading)).
 - 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.
 

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

@@ -29,6 +29,8 @@ Stated plainly, as of `(generated from the app: see https://dexterm.xyz/docs/spe
 
 - **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`.
+- **The thought ribbon only shows what the agent writes down.** dexterm cannot read an agent's mind: without `--spectate-thoughts FILE`, the ribbon narrates the calls themselves. The agent label in the dock is the one this terminal gives it (`mcp-agent`); the MCP server does not tell the app which client is calling.
+- **The mark PnL is approximate.** It is the move of the coin's price since the paper entry, at this terminal's last price for it (or the last price a tool call returned), before fees. The paper ledger's own numbers are on the fill, the position panel and the result card.
 - **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.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-the-agent-hud-spectator-v2.md

@@ -0,0 +1,58 @@
+---
+id: docs-spectator-the-agent-hud-spectator-v2
+title: Spectator view (watch the agent cook) › Follow over MCP in the running terminal › The agent HUD (spectator v2)
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: The agent HUD (spectator v2)
+anchor: the-agent-hud-spectator-v2
+url: https://dexterm.xyz/docs/spectator#the-agent-hud-spectator-v2
+tags:
+  - docs
+  - spectator
+  - agent
+  - hud
+  - follow
+  - over
+  - mcp
+  - running
+  - terminal
+  - 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
+---
+
+While the terminal follows an MCP agent, it shows the agent working, not a list of calls. The app's own screen renders a few rows shorter, so nothing of it is hidden, and an **agent dock** sits under it:
+
+- **The heartbeat and the phase rail.** A heartbeat trace beats faster as the agent calls more tools. The rail `SCANNING ─ VETTING ─ SIZING ─ EXECUTING ─ HOLDING ─ EXITING` lights the phase it is in. While it holds a position and checks other coins, the rail stays on HOLDING and shows the side activity next to it.
+- **The thought ribbon.** The agent's own words, typed in as it thinks, when you pass `--spectate-thoughts FILE` (see below). Otherwise dexterm narrates what each call did, from the call's own numbers ("scanning 12 rows · 3 moving up", "verdict WATCH · rug heuristic 11%").
+- **The call timeline.** Each call is a node, newest on the right, spaced by the time between calls. Under each node is a result chip: green for ok, amber for slow, red for a failure or a refusal. PAPER calls are marked.
+- **`PAPER` and the controls are always on screen**: **^P** pause, **^K** kill.
+
+Over the screen itself:
+
+- The **rows the agent scans glow**, with a beam sweeping down them. The row it opens gets the **agent cursor** (`▶ … ◀ AGENT`), and the token screen assembles top-down as it opens.
+- A **vetting card** fills in the checks the agent ran (price, tape, chart, holders, rug, dev, LARP, verdict). Its **LARP gauge** sweeps to the number of evidence flags `larp_check` found; that number is evidence, not a verdict.
+- **The PAPER execution moment** (with `--agent-paper`): an order ticket assembles with the size, your per-trade cap and the gate as it really is (your keypress armed the mandate; inside it there is no keypress per paper trade, and the desk enforces the caps). Then the fill lands with a flash and the entry from the paper fill, and the ticket turns into a **position panel**. That panel shows the mark PnL as a big number with a trace, the peak and the time held. The mark is this terminal's own price for the coin, or the price a tool call returned, never a number the agent typed. Each exit flashes. When the position is flat, a **result card** shows the realized PAPER result, the hold time and the exits.
+- **Kill is a hard stop.** **^K** cuts the screen with a red flash and a short glitch, stamps `KILLED`, closes the agent's session and stops its paper desk for the rest of the run. The dock then stays on `AGENT KILLED`. **^P** pauses (the band under the header says so and the screen is framed in amber), and any other key hands the screen to you.
+
+Every number the HUD shows comes from the app: a tool's own result (the rows a scan returned, the verdict, the paper ticket, fill and position, the caps the desk replayed) or this terminal's price. The agent's text is display only: it is scrubbed and clipped, and nothing in it is acted on.
+
+**Motion and colour.** Calm mode (`--calm` or the `C` key) is the reduced-motion setting here as everywhere else. The sweeps, flashes, the glitch and the typing go away, and every card and number appears at once. With `NO_COLOR` the meaning stays in glyphs: `▸` marks the active phase, chips carry `✓ ! ✗`, and the cursor is `▶`. A terminal shorter than 24 rows gets no HUD; the status lines are shown as toasts instead, and the PnL chip moves to the band under the header.
+
+#### The thought ribbon: `--spectate-thoughts FILE`
+
+dexterm cannot see inside your agent, so its words come from a file the agent writes. Pass `--spectate-thoughts FILE` (with `--spectate-mcp`). The file can be:
+
+- Claude Code's stream output (`claude -p --output-format stream-json --verbose … > FILE`): text and thinking blocks;
+- a JSONL file with `{"thought": "…"}` lines.
+
+The file is tailed for display only, and each line is scrubbed: control and bidirectional characters are removed, addresses are masked and markdown is dropped. One message becomes one short line.

package/dist/packages/mcp/assets/kb/docs/docs-spectator-the-brain-view-and-the-pnl-chip.md

@@ -0,0 +1,46 @@
+---
+id: docs-spectator-the-brain-view-and-the-pnl-chip
+title: Spectator view (watch the agent cook) › Follow over MCP in the running terminal › The brain view and the PnL chip
+kind: docs
+page: spectator
+page_title: Spectator view (watch the agent cook)
+heading: The brain view and the PnL chip
+anchor: the-brain-view-and-the-pnl-chip
+url: https://dexterm.xyz/docs/spectator#the-brain-view-and-the-pnl-chip
+tags:
+  - docs
+  - spectator
+  - brain
+  - view
+  - pnl
+  - chip
+  - follow
+  - over
+  - mcp
+  - running
+  - terminal
+  - 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
+---
+
+While the agent is active (it made a call in the last 3 minutes, or it holds a PAPER ticket or position), the **ANALYST panel on the token screen becomes the agent's BRAIN VIEW** instead of the "press a for a dossier" help. Top to bottom:
+
+- **REASONING.** The agent's thoughts (from `--spectate-thoughts`) typing in, newest at the bottom, each with its clock time and the phase it was in (`SCANNING`, `VETTING`, `SIZING`, ...). Older lines dim, and long lines are clipped. With no thoughts feed, the header says `dexterm narration · no thoughts feed` and the lines are dexterm's own narration of each call. Lines a demo or stand-in feed marks as scripted (`"demo": true`) carry the coral `claude lines: demo text` tag.
+- **VETTING $COIN.** The checklist for the coin on screen: momentum, liquidity against the $10K floor, tape buys/sells and wallet count, top-10 concentration, mint/freeze authority, LP lock, dev history, LARP flags, the rug heuristic and the verdict. Each box shows the number the app computed and `pass`, `warn`, `fail` or `pending` (pending = that number is not in yet). `◆` marks the checks the agent itself ran.
+- **DATA.** Market cap, price, liquidity, 5m and 1h moves, buy/sell flow and holders, with a candle trace. These are the numbers already on screen; there is no extra fetch.
+- **PLAN / POSITION** (while a PAPER ticket or position is open): entry, size, the take-profit and stop the agent *said* (labelled `agent's plan`, or `no stop`), mark PnL in % and paper $, peak, drawdown from the peak, time held, and what it is waiting for. A desk refusal is stamped here.
+- **DECISIONS.** The session log (`rejected DECOY · verdict AVOID`, `entered`, `sold`, `desk refused`) and a scoreboard: `PAPER simulated · vetted · entries · closed · realized SOL`.
+
+The normal analyst panel returns when the agent is killed, goes quiet, or before its first call, and also while you type into the analyst. Smaller panels drop blocks in order: the decision log first, then the data strip, then the checklist folds into two columns. The plan and the reasoning stay.
+
+**The PnL chip.** While the agent holds a PAPER position, a chip shows it: `PAPER $COIN │ ▲ +24.0% +$2.40 │ peak +31.0% │ $0.0100 → $0.0124 │ held 1m04s │ dd −5.3% │ TP +40%`. It is on every terminal screen (screener, new pairs, watchlist, token screen, analyst) and on the chart popup (https://dexterm.xyz/docs/popup-chart#what-it-shows). On a terminal with 24 rows or more it sits in the dock's top row. On a shorter terminal there is no dock, and the chip sits on the band under the header instead. It updates on every mark tick and flashes on a new peak (a `★` under calm mode and `NO_COLOR`). Fields drop from the right on narrower terminals. The held coin stays in the fast price lane, so the chip keeps marking after the coin scrolls off the screener. In AI scan mode (https://dexterm.xyz/docs/scan#the-read) the same chip shows your own open paper or live position. The chip only shows in these two auto modes. The other popups (token, bubble map, feeds) do not carry it.
+
+Both are display only. They have no input and cannot arm, size, sign, confirm or raise a cap. The agent's text is scrubbed and clipped, and addresses are shortened.

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

@@ -30,7 +30,7 @@ All three read the same events from one in-memory hub, which `agent serve` creat
 
 | 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 |
+| AGENT ACTIVITY window | `dexterm agent serve --spectator-popup` | a window titled "watch the agent cook": the agent's phase rail and heartbeat, its thought ribbon, a call timeline with result chips, the coin it is vetting and its PAPER trade, over the live activity, with 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 |
 

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

@@ -22,7 +22,7 @@ sources:
 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.
+Watch a connected agent work in real time. The agent HUD in the running terminal (phase rail, heartbeat, thought ribbon, call timeline, the PAPER execution moment), 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.
 

package/dist/packages/mcp/src/paper-agent.js

@@ -55,7 +55,7 @@ async function refreshSolUsd(data) {
  * Re-reads the rendezvous (mtime-cached) so enabling/disabling in the running app is picked up; the mandate
  * and the control state are re-read inside the desk on every call, not cached across journal changes.
  */
-export async function resolvePaperAgentDesk(data, env = process.env) {
+export async function resolvePaperAgentDesk(data, env = process.env, opts = {}) {
     const mtimeMs = rendezvousMtimeMs(env);
     if (mtimeMs === 0) {
         teardown();
@@ -79,7 +79,8 @@ export async function resolvePaperAgentDesk(data, env = process.env) {
         executor,
         // 'high', like the human ticket (task-1387): a paper exit must not queue behind the agent's own read polling on
         // the shared keyless `jupiter` bucket (task-1443 live run: a scale-out was refused on a 429 mid-poll).
-        quote: (req, signal) => withPriority('high', () => data.jupiterSwap.quote(req, signal)),
+        quote: (req, signal) => withPriority('high', () => (opts.quoteData?.() ?? data).jupiterSwap.quote(req, signal)),
+        ...(opts.onQuoteRetry ? { onQuoteRetry: opts.onQuoteRetry } : {}),
         solUsd: () => (sol && Date.now() - sol.at <= PAPER_SOL_USD_MAX_AGE_MS ? sol.price : null),
         control: () => readDeskControl(env),
         journal: new SharedJournal(paperAgentJournalPath(env), systemClock),