dexterm-cli 0.1.4 → 0.1.6

package/dist/packages/data/src/trade/plans/mandate.js

@@ -13,6 +13,15 @@ export const HARD = Object.freeze({
     tipBudgetLamports: 500_000_000, maxTipLamportsPerTx: 10_000_000, maxPriorityFeeLamportsPerTx: 10_000_000,
     ttlMs: 24 * 3600_000, maxSendsPerSec: 20,
 });
+/**
+ * task-1469: ceilings for a PAPER-ONLY mandate (`dexterm mandate draft --paper`). Only the agent paper desk reads
+ * one: the plan engine refuses to arm a plan into it, fire under it or copy-trade through it, so these numbers never
+ * reach a signer, and HARD (above) stays the ceiling of every mandate a real fill can use. Fills are still priced
+ * on a live quote, so a bigger paper size pays its real price impact.
+ */
+export const PAPER_HARD = Object.freeze({
+    ...HARD, totalUsd: 10_000, perTradeUsd: 2_000, perCoinUsd: 2_000, dailyLossUsd: 10_000, maxPriceImpactPct: 10,
+});
 /** Confirmation tiers and the multiplier they apply to a mandate's per-trade cap for plans confirmed that way. */
 export const TIERS = Object.freeze({
     'keypress': { rank: 0, perTradeMultiplier: 1.0, canArmMandate: true, canArmBatch: true },
@@ -37,6 +46,8 @@ function clamp(v, dflt, hardMax) {
 export function draftMandate(input, ctx) {
     const x = input ?? {};
     const now = ctx.clock.now();
+    const paper = x.paperOnly === true;
+    const H = paper ? PAPER_HARD : HARD;
     const actions = Array.isArray(x.actions) ? x.actions.filter((a) => a === 'buy' || a === 'sell') : ['buy', 'sell'];
     if (actions.length === 0)
         throw new MandateError('bad-request', 'at least one of buy/sell');
@@ -45,23 +56,23 @@ export function draftMandate(input, ctx) {
         id: ctx.id ?? `mandate_${now.toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
         wallet: 'fast', // the capped fast wallet; the main wallet is never named here
         budget: {
-            totalUsd: clamp(x.totalUsd, 100, HARD.totalUsd),
-            perTradeUsd: clamp(x.perTradeUsd, 20, HARD.perTradeUsd),
-            perCoinUsd: clamp(x.perCoinUsd, 40, HARD.perCoinUsd),
-            dailyLossUsd: clamp(x.dailyLossUsd, 50, HARD.dailyLossUsd),
+            totalUsd: clamp(x.totalUsd, 100, H.totalUsd),
+            perTradeUsd: clamp(x.perTradeUsd, 20, H.perTradeUsd),
+            perCoinUsd: clamp(x.perCoinUsd, 40, H.perCoinUsd),
+            dailyLossUsd: clamp(x.dailyLossUsd, 50, H.dailyLossUsd),
         },
         limits: {
-            maxArmedPlans: clamp(x.maxArmedPlans, 20, HARD.maxArmedPlans),
-            maxInFlight: clamp(x.maxInFlight, 5, HARD.maxInFlight),
-            maxOpenPositions: clamp(x.maxOpenPositions, 20, HARD.maxOpenPositions),
-            maxSlippageBps: clamp(x.maxSlippageBps, 500, HARD.maxSlippageBps),
-            maxPriceImpactPct: clamp(x.maxPriceImpactPct, 3, HARD.maxPriceImpactPct),
-            maxSendsPerSec: clamp(x.maxSendsPerSec, 5, HARD.maxSendsPerSec),
+            maxArmedPlans: clamp(x.maxArmedPlans, 20, H.maxArmedPlans),
+            maxInFlight: clamp(x.maxInFlight, 5, H.maxInFlight),
+            maxOpenPositions: clamp(x.maxOpenPositions, 20, H.maxOpenPositions),
+            maxSlippageBps: clamp(x.maxSlippageBps, 500, H.maxSlippageBps),
+            maxPriceImpactPct: clamp(x.maxPriceImpactPct, 3, H.maxPriceImpactPct),
+            maxSendsPerSec: clamp(x.maxSendsPerSec, 5, H.maxSendsPerSec),
         },
         fees: {
-            tipBudgetLamports: clamp(x.tipBudgetLamports, 50_000_000, HARD.tipBudgetLamports),
-            maxTipLamportsPerTx: clamp(x.maxTipLamportsPerTx, 1_000_000, HARD.maxTipLamportsPerTx),
-            maxPriorityFeeLamportsPerTx: clamp(x.maxPriorityFeeLamportsPerTx, 2_000_000, HARD.maxPriorityFeeLamportsPerTx),
+            tipBudgetLamports: clamp(x.tipBudgetLamports, 50_000_000, H.tipBudgetLamports),
+            maxTipLamportsPerTx: clamp(x.maxTipLamportsPerTx, 1_000_000, H.maxTipLamportsPerTx),
+            maxPriorityFeeLamportsPerTx: clamp(x.maxPriorityFeeLamportsPerTx, 2_000_000, H.maxPriorityFeeLamportsPerTx),
         },
         allowed: {
             actions,
@@ -70,8 +81,9 @@ export function draftMandate(input, ctx) {
         },
         maxTier: (typeof x.maxTier === 'string' && x.maxTier in TIERS) ? x.maxTier : 'keypress',
         createdAt: now,
-        expiresAt: now + clamp(x.ttlMs, 4 * 3600_000, HARD.ttlMs),
+        expiresAt: now + clamp(x.ttlMs, 4 * 3600_000, H.ttlMs),
         status: 'draft', armedAt: null, armedBy: null, revokedAt: null, revokedReason: null,
+        ...(paper ? { paperOnly: true } : {}),
     };
     // perTrade can never exceed total; perCoin never exceeds total.
     m.budget.perTradeUsd = Math.min(m.budget.perTradeUsd, m.budget.totalUsd);
@@ -117,7 +129,8 @@ export function revokeMandate(m, reason, ctx) {
 }
 /** Hash of the caps a gesture arms — the proof binds to these numbers, not to the mandate id alone. */
 export function capsHash(m) {
-    return createHash('sha256').update(JSON.stringify({ b: m.budget, l: m.limits, f: m.fees, a: m.allowed, t: m.maxTier, e: m.expiresAt, w: m.wallet })).digest('hex').slice(0, 16);
+    // task-1469: the paper-only flag is part of what a gesture arms; a normal mandate hashes exactly as before.
+    return createHash('sha256').update(JSON.stringify({ b: m.budget, l: m.limits, f: m.fees, a: m.allowed, t: m.maxTier, e: m.expiresAt, w: m.wallet, ...(m.paperOnly === true ? { p: 1 } : {}) })).digest('hex').slice(0, 16);
 }
 /** Alive = armed and not expired. Expiry is checked on every call, never cached. */
 export function mandateAlive(m, now) {

package/dist/packages/data/src/trade/plans/service.js

@@ -149,7 +149,7 @@ export class PlanService {
             return {
                 id: x.m.id, status: x.m.status, wallet: x.m.wallet, totalUsd: x.m.budget.totalUsd, perTradeUsd: x.m.budget.perTradeUsd,
                 perCoinUsd: x.m.budget.perCoinUsd, maxTier: x.m.maxTier, reservedUsd: L.reservedUsd, spentUsd: L.spentUsd,
-                realizedUsd: L.realizedUsd, lossUsd: L.lossUsd, expiresAt: x.m.expiresAt,
+                realizedUsd: L.realizedUsd, lossUsd: L.lossUsd, expiresAt: x.m.expiresAt, paperOnly: x.m.paperOnly === true,
             };
         });
     }

package/dist/packages/mcp/assets/kb/app-help/agent-paper-trade.md

@@ -0,0 +1,38 @@
+---
+id: agent-paper-trade
+title: Let an agent paper trade
+kind: app-help
+screen: all
+feature: mcp
+tags:
+  - app-help
+  - agent
+  - mcp
+  - paper
+  - autonomous
+  - experimental
+  - confirm
+  - close
+  - simulated
+flags:
+  - --agent-paper
+tools:
+  - paper_open_ticket
+  - paper_size_ticket
+  - paper_confirm
+  - paper_close
+  - paper_positions
+  - paper_pnl
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+Experimental, paper only, off by default. Arm a mandate yourself (its caps, by keypress), then start `dexterm --spectate-mcp --agent-paper <mandate-id>`: an agent connected through `dexterm mcp` can then open, size, confirm and close SIMULATED (paper) trades inside those caps with paper_open_ticket / paper_size_ticket / paper_confirm / paper_close, and read paper_positions / paper_pnl. The agent is untrusted: it can never sign, send a real transaction, touch keys, or raise a cap; its per-trade cap is a quarter of the mandate's, and a size over any cap is refused. Caps are re-read from your armed mandate on every call, so revoking it or the panic key stops the agent. Every call is journaled and shows in this terminal's agent activity; Ctrl+P pauses, Ctrl+K stops for the rest of the run, any key takes over, and quitting turns it off. Figures are simulated and are not a result.

package/dist/packages/mcp/assets/kb/app-help/ask-the-analyst.md

@@ -38,6 +38,6 @@ sources:
 date: 2026-10-16
 ---
 
-The analyst is your own `claude` login. ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.
+The analyst is your own `claude` login (or your own `codex` login: `/engine codex`, see "Run the analyst on Codex"). ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.
 
 Keys: `a`, `⏎` (screener).

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

@@ -34,6 +34,6 @@ sources:
 date: 2026-10-16
 ---
 
-`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.
+`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`, or set up Claude Code, Claude Desktop, Cursor or Codex in one command with `dexterm mcp install <client>`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.
 
 CLI: `dexterm mcp`.

package/dist/packages/mcp/assets/kb/app-help/dev-history.md

@@ -0,0 +1,32 @@
+---
+id: dev-history
+title: Check if a coin's creator rugged before (dev history)
+kind: app-help
+screen: token
+feature: token-intel
+tags:
+  - app-help
+  - dev
+  - deployer
+  - creator
+  - serial
+  - rugger
+  - rugged
+  - history
+  - launches
+tools:
+  - dev_history
+  - get_dev_history
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+The token screen's ON-CHAIN panel shows the creator's recorded track record (0.1.5): `Dev rugs` (rugs out of labelled prior launches, e.g. `2/3 · n=3 · rec 7d`), `Dev launches` (`n=3 · rec 2h · dev:jup`: which feed named the creator), `Dev sold bag` (median minutes to the dev's exit, `med 20m · n=3 · rec 1d`), `Dev linked` (funder or cluster from the wallet-intel scan, with the scan's age) and `Linked dev rugs` (rugs by other wallets in that cluster). Every value names its source (`rec` = the recorder, `scan` = the wallet-intel scan), its sample (n=) and the age of its newest datum. It comes from dexterm's own local history recorder (keyless creator links + code-only outcome labels), so it says `unknown` when there is no record; it is a risk flag from observed history, never a certificate. Alert on it with the rule field `devrugs`, e.g. `when devrugs >= 2 then alert(warn, "new coin from a wallet that rugged before") scope newpairs`. Agents and the analyst use the `dev_history` MCP tool.

package/dist/packages/mcp/assets/kb/app-help/larp-check.md

@@ -15,12 +15,16 @@ tags:
   - domain
   - github
   - vet
+  - score
+  - x
+  - twitter
 tools:
   - larp_check
   - get_links
   - fetch_page
   - check_domain
   - check_github
+  - check_x
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -33,4 +37,4 @@ sources:
 date: 2026-10-16
 ---
 
-The LARP check vets whether a real product exists (website, domain age, GitHub) read-only — it is not a price call. Ask the analyst "is <coin> a larp?" (skill `larp-check`), or an agent can call the `larp_check` MCP tool. A grade is a risk flag, never a certificate; it never recommends buy/sell.
+The LARP check vets whether a real product exists (website, domain age, GitHub, the X account) read-only — it is not a price call. Ask the analyst "is <coin> a larp?" (skill `larp-check`), or an agent can call the `larp_check` MCP tool. It returns a 0-100 LARP score: the sum of named flags with their points (low under 25, medium 25-49, high 50+), plus a list of what could not be read, which widens the range instead of lowering the score. A score is a summary of flags, never a certificate; it never recommends buy/sell.

package/dist/packages/mcp/assets/kb/app-help/paper-trade.md

@@ -31,6 +31,6 @@ sources:
 date: 2026-10-16
 ---
 
-Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The analyst can open a PAPER ticket but can never size, confirm or send it.
+Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The in-app analyst can open a PAPER ticket but can never size, confirm or send it. If you separately arm a mandate and enable agent paper trading, a connected agent can open, size, confirm and close PAPER trades inside your caps (never raising them, never signing) — see "Let an agent paper trade".
 
 Keys: `B` (token), `S` (token).

package/dist/packages/mcp/assets/kb/app-help/scan-mode.md

@@ -32,6 +32,6 @@ sources:
 date: 2026-10-16
 ---
 
-Scan mode is an observe-only AI watcher (off by default, zero extra requests). Toggle it with `Z` (or `/scan on|off` on the screener line, or `--scan` at launch); `R` resumes a paused scan. It can only surface findings, never take a UI action or trade (structurally observe-only). The analyst can turn it on or off for you.
+Scan mode is an observe-only AI watcher (off by default, zero extra requests). Toggle it with `Z` (or `/scan on|off` on the screener line, or `--scan` at launch); `R` resumes a paused scan. It can only surface findings, never take a UI action or trade (structurally observe-only). While it is on, the token screen's analyst panel shows its brain view: the scan log (locks, refreshes, releases, blocked actions) with the read streaming under it, the vetting checklist and the data strip. While it runs and you hold a paper or live position, a PnL chip shows it on the band under the header of every screen and on the chart popup; display only. The analyst can turn it on or off for you.
 
 Keys: `Z`, `R`.

package/dist/packages/mcp/assets/kb/app-help/screen-positions.md

@@ -116,6 +116,9 @@ actions:
   - workspace.popups
   - workspace.default
   - screen.rules
+tools:
+  - paper_positions
+  - paper_pnl
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -127,7 +130,7 @@ sources:
 date: 2026-10-16
 ---
 
-Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow.
+Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow. An agent you enabled can read these over MCP with the read-only paper_positions and paper_pnl tools.
 
 Keys on this screen:
   `q/^C` — quit

package/dist/packages/mcp/assets/kb/app-help/screen-token.md

@@ -63,6 +63,7 @@ keys:
   - T
   - L
   - C
+  - A
   - I
   - F
   - Z
@@ -132,6 +133,7 @@ actions:
   - open.tg
   - open.links
   - popup.chart
+  - display.chartAxis
   - popup.token
   - tape.toggle
   - scan.toggle
@@ -159,6 +161,7 @@ tools:
   - get_trades
   - get_candles
   - get_dev_history
+  - dev_history
   - rugcheck
 confidence: high
 owner: maintainers
@@ -217,6 +220,7 @@ Keys on this screen:
   `T` — open TG
   `L` — links
   `C` — chart popup
+  `A` — chart axis mcap ⇄ price
   `I` — token popup
   `F` — flow ⇄ tape
   `Z` — AI scan

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/app-help/use-codex-analyst.md

@@ -0,0 +1,31 @@
+---
+id: use-codex-analyst
+title: Run the analyst on Codex instead of Claude
+kind: app-help
+screen: all
+feature: analyst
+tags:
+  - app-help
+  - codex
+  - openai
+  - chatgpt
+  - engine
+  - analyst
+  - claude
+  - switch
+  - backend
+flags:
+  - --analyst-engine
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+The analyst can run on your own Codex CLI login instead of Claude (0.1.5). Pick it with `--analyst-engine codex`, `DEXTERM_ANALYST_ENGINE=codex`, `"analyst": {"engine": "codex"}` in `~/.dexterm/config.json`, or type `/engine codex` in the chat box (new conversations; `/engine` alone shows the engine and what is installed). The default `auto` uses claude when it is installed, else codex. dexterm stores no credentials: your `codex login` does the work. The Codex run is locked read-only: only the read-only dexterm tools (plus the UI actions the session allows, none in scan mode), no shell, no file edits, no web search, no other MCP server; a turn that tries anything else is stopped. `dexterm doctor` shows a Codex CLI line (installed, version, logged in). Codex is also supported as an MCP client: `dexterm mcp install codex`.

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

@@ -0,0 +1,51 @@
+---
+id: docs-agents-agent-paper-trading
+title: Bring your own agent › Agent paper trading
+kind: docs
+page: agents
+page_title: Bring your own agent
+heading: Agent paper trading
+anchor: agent-paper-trading
+url: https://dexterm.xyz/docs/agents#agent-paper-trading
+tags:
+  - docs
+  - agents
+  - agent
+  - paper
+  - trading
+  - bring
+  - own
+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/agents.md
+date: 2026-10-16
+---
+
+**Status: experimental, paper only, off by default (since 0.1.5).** By default an agent can only read and navigate; it cannot trade at all. If you choose to, you can let an agent you connected over `dexterm mcp` run a full **paper** trade loop inside a **trading mandate** you armed yourself. Nothing here is live: every fill books the **simulated** paper wallet.
+
+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. 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:
+
+- `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. 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.
+
+Figures are simulated. They are for learning the flow, not a result, and never a prediction or a recommendation. This is not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-agents-directory-metadata-prepared-not-submitted.md

@@ -0,0 +1,36 @@
+---
+id: docs-agents-directory-metadata-prepared-not-submitted
+title: Bring your own agent › Install in one command › Directory metadata (prepared, not submitted)
+kind: docs
+page: agents
+page_title: Bring your own agent
+heading: Directory metadata (prepared, not submitted)
+anchor: directory-metadata-prepared-not-submitted
+url: https://dexterm.xyz/docs/agents#directory-metadata-prepared-not-submitted
+tags:
+  - docs
+  - agents
+  - directory
+  - metadata
+  - prepared
+  - submitted
+  - install
+  - command
+  - bring
+  - own
+  - 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/agents.md
+date: 2026-10-16
+---
+
+The source repository includes an official MCP Registry `server.json` and a
+Smithery MCPB manifest. They describe the same local stdio command and the same
+(generated from the app: see https://dexterm.xyz/docs/agents#directory-metadata-prepared-not-submitted; app-help has the exact keys and commands)-tool surface that `dexterm mcp doctor` reports. No directory
+listing is implied: publication remains a separate maintainer action, and the
+Registry package marker must first ship in a new `dexterm-cli` release.

package/dist/packages/mcp/assets/kb/docs/docs-agents-install-in-one-command.md

@@ -47,3 +47,5 @@ $ dexterm mcp doctor                   # spawn the server and list the tools you
 Flags: `--config FILE` writes to a specific file instead of the client default; `--print` only prints; `--node` emits a `node <path> mcp` command for when `dexterm` is not on your PATH; `--yes` skips the confirmation prompt. On a non-interactive shell the command prints the plan and writes nothing unless you pass `--yes`.
 
 `dexterm mcp doctor` spawns the server over stdio, does the MCP handshake, and lists the tools, prompts and resources the agent sees — proof the connection works before you point an agent at it.
+
+Codex is supported both ways: as an MCP client here (`dexterm mcp install codex`), and, since 0.1.5, as the engine that runs the in-app analyst on your own Codex login (use Codex instead of Claude (https://dexterm.xyz/docs/analyst#use-codex-instead-of-claude)).

package/dist/packages/mcp/assets/kb/docs/docs-analyst-if-claude-is-missing.md

@@ -22,4 +22,4 @@ sources:
 date: 2026-10-16
 ---
 
-The panel shows a one-line fix (`npm i -g @anthropic-ai/claude-code && claude login`) and the rest of dexterm keeps working. `dexterm doctor` reports the Claude CLI line as a warning, not a failure.
+The panel shows a one-line fix (`npm i -g @anthropic-ai/claude-code && claude login`) and the rest of dexterm keeps working. `dexterm doctor` reports the Claude CLI line as a warning, not a failure. With Codex installed, `auto` runs the analyst on Codex instead.

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-analyst-use-codex-instead-of-claude.md

@@ -0,0 +1,35 @@
+---
+id: docs-analyst-use-codex-instead-of-claude
+title: The analyst › Use Codex instead of Claude
+kind: docs
+page: analyst
+page_title: The analyst
+heading: Use Codex instead of Claude
+anchor: use-codex-instead-of-claude
+url: https://dexterm.xyz/docs/analyst#use-codex-instead-of-claude
+tags:
+  - docs
+  - analyst
+  - use
+  - codex
+  - instead
+  - claude
+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/analyst.md
+date: 2026-10-16
+---
+
+*Since 0.1.5.* The analyst can run on **your own Codex CLI login** instead of Claude. dexterm ships no key and reads no credential: the `codex` you set up and signed in to does the work, on your plan.
+
+- **Pick it:** `--analyst-engine codex` at launch, `DEXTERM_ANALYST_ENGINE=codex`, `"analyst": {"engine": "codex"}` in `~/.dexterm/config.json`, or type `/engine codex` in the chat box (it applies to new conversations; `/engine` alone shows the current engine and which CLIs it found). The default, `auto`, prefers Claude Code and falls back to Codex. Only you choose: the analyst cannot change its own engine.
+- **Same guarantees, enforced in the Codex CLI itself.** dexterm runs `codex exec --json` with your Codex config and rules files ignored, apps, plugins, hooks, skills discovery and sub-agents off, the shell and exec tools removed, the sandbox read-only, approvals `never` and web search off. Its only MCP server is the read-only `dexterm mcp`, limited by an allow-list: the read tools plus the UI actions the session allows (none in scan mode (https://dexterm.xyz/docs/scan)), never a paper or trade tool. If Codex still reports a command, a file change, a web search or any other tool, dexterm stops the turn and says so. The firewalled CONTEXT block, the skills and your own skill overlays are the same; the skill playbook is passed inline because Codex has no plugin directory.
+- **What is different.** Codex reports whole messages, so an answer appears per message rather than word by word. The caption shows `codex plan` instead of a dollar cost (Codex reports tokens, not cost). The model is your Codex default for your login; pin one with `DEXTERM_CODEX_MODEL`. Which models a ChatGPT plan allows is decided by your plan, not by dexterm.
+- **Codex errors are one line each:** no Codex CLI (`npm i -g @openai/codex && codex login`), a logged-out Codex (`codex login`), or an old one (update; the lock needs codex-cli 0.163.0 or newer, and an unknown lock flag fails the run instead of loosening it). `dexterm doctor` shows a Codex CLI line with the version and whether you are logged in. On Windows dexterm only starts a `codex.exe` on PATH; the npm `codex.cmd` shim is not started.
+- **How we checked.** Offline tests drive a fake `codex` through the real app path, and a measurement harness runs the real codex-cli 0.163.0 against a local mock model (no account, no model): the tool list Codex sends is the dexterm allow-list only, and forged shell, exec, patch, sub-agent and ticket calls come back "unsupported" without running. Answer quality and speed against Claude have not been benchmarked.
+
+Codex is also supported the other way round, as an MCP client that drives dexterm: `dexterm mcp install codex` (see bring your own agent (https://dexterm.xyz/docs/agents#install-in-one-command)).

package/dist/packages/mcp/assets/kb/docs/docs-beginners-macos-or-linux-npm.md

@@ -36,4 +36,4 @@ date: 2026-10-16
 npm i -g dexterm-cli
 ```
 
-Linux x64 with Node 22 and 24 and macOS on Intel processors have passed the full automated tests plus a clean install-and-start check. Apple Silicon macOS has not yet run the project's written automated test. No `sudo` (the command that grants administrator power) is required for this npm path.
+Linux x64 with Node 22 and 24 and macOS on Intel processors have passed the full automated tests plus a clean install-and-start check. Apple Silicon macOS passed the same automated tests in CI for 0.1.4. No `sudo` (the command that grants administrator power) is required for this npm path.

package/dist/packages/mcp/assets/kb/docs/docs-beginners-windows-expectations.md

@@ -26,4 +26,4 @@ sources:
 date: 2026-10-16
 ---
 
-Windows x64 is experimental and has not yet run the written CI job. File permissions rely on your Windows user profile; voice has no Windows speech engine; browser-opening actions show a URL instead; `doctor` may print a macOS/Linux repair command; and the npm-installed `claude.cmd` is not detected as a usable analyst binary. These limits do not change the key rule: dexterm never holds your wallet keys.
+Windows x64 is experimental: the full CI suite passed for 0.1.4, though some file-permission checks are skipped. File permissions rely on your Windows user profile; voice has no Windows speech engine; browser-opening actions show a URL instead; `doctor` may print a macOS/Linux repair command; and the npm-installed `claude.cmd` is not detected as a usable analyst binary. These limits do not change the key rule: dexterm never holds your wallet keys.

package/dist/packages/mcp/assets/kb/docs/docs-beginners-windows-powershell-experimental.md

@@ -36,4 +36,4 @@ Install Node.js LTS first, reopen PowerShell, and run:
 npm i -g dexterm-cli
 ```
 
-The Windows path is experimental and not yet tested by the project. The core read-only screens are expected to work, but voice has no Windows engine, browser-opening shortcuts do not work, and some repair instructions are written for macOS/Linux. See Windows expectations (https://dexterm.xyz/docs/beginners#windows-expectations).
+The Windows path is experimental: the project's CI suite passed for 0.1.4, but nobody has used it much by hand. The core read-only screens are expected to work, but voice has no Windows engine, browser-opening shortcuts do not work, and some repair instructions are written for macOS/Linux. See Windows expectations (https://dexterm.xyz/docs/beginners#windows-expectations).

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-environment-variables.md

@@ -33,6 +33,8 @@ date: 2026-10-16
 | `DEXTERM_INTENSITY` | `off` · `normal` · `fever` |
 | `DEXTERM_OFFLINE=1` | refuse live data; `--fixtures` or `--replay` only (tests and CI) |
 | `DEXTERM_ANALYST_MODEL` | the Claude model for analyst turns (default `(generated from the app: see https://dexterm.xyz/docs/configuration#environment-variables; app-help has the exact keys and commands)`) |
+| `DEXTERM_ANALYST_ENGINE` | `auto` (default) · `claude` · `codex`: which of your CLIs runs the analyst (since 0.1.5; also `--analyst-engine` and `analyst.engine` in `config.json`) |
+| `DEXTERM_CODEX_MODEL` | pin the Codex model for analyst turns (default: your Codex default) |
 | `DEXTERM_POPUP_SHELL` | path to a prebuilt native chart window |
 | `DEXTERM_POPUP_HOTKEY` · `DEXTERM_POPUP_HOTKEY_CLOSE` | override the popup chords without a config file |
 | `DEXTERM_RECORDER=0` | history recorder off (same as `--no-recorder`; `off`, `false` and `no` work too) |

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-configuration-rules-engine.md

@@ -31,6 +31,7 @@ vol5m.velocity > 3 and cluster < 20 and liq > 25K for 2 ticks then alert(up, "su
 ```
 
 - The open token's live holder and rug signals (https://dexterm.xyz/docs/screens#live-holder-and-rug-signals) are rule fields too: `top10`, `dev`, `bundled`, `snipers`, `fresh`, `cluster`, `lplocked`, `bonding`, `mintable`, `freezable`, with `.delta` and `.velocity` (`dexterm rules fields` lists them all).
+- Since 0.1.5: `devrugs` is the coin's creator's labelled prior rugs from the local record (dev history (https://dexterm.xyz/docs/screens#dev-history); unknown = no match), e.g. `when devrugs >= 2 then alert(warn, "new coin from a wallet that rugged before") scope newpairs`.
 - The text is parsed, never evaluated as code. Every rule has a cooldown (default 10 m) and a max per hour (default 12, hard cap 120), so a bad rule is annoying, not dangerous.
 - Rules can **alert**, annotate your own watchlist (`tag`, `watch`), open the read-only windows and ring the bell, or **propose**. `ticket` and `ask` do not act: each fire becomes a proposal card on the rules screen (status proposal, your keypress required, armed by nobody); acting on it opens the PAPER ticket in its editing phase, where you size and confirm, or asks the analyst. Nothing a rule does reaches an order plan, a mandate, the signer or the gate, and a rule argument named like money (`arm`, `auto`, `confirm`, `execute`, `sign`, `send`) is refused at parse time, in text and in JSON.
 - `ctrl+r` opens the RULES screen: the list with enabled / last fired / source, `i` types a new rule with a live "would match N of M rows right now" dry-run, `tab` the proposals pane, `space` toggles, `d` removes. `dexterm rules list | add "<rule>" | remove | enable | disable <id> | check "<rule>" | dry-run "<rule>" | fields`. Rules live in `config.json`, every change through the journal.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-the-analyst-s-launch.md

@@ -25,3 +25,5 @@ date: 2026-10-16
 ---
 
 For the record, the analyst is spawned as `claude -p` with `--output-format stream-json`, `--tools ''` (no built-in tools), `--strict-mcp-config` pointing at the dexterm server only, `--allowedTools mcp__dexterm__*`, `--permission-mode dontAsk`, `--setting-sources ''` (none of your Claude Code settings or other plugins), the dexterm plugin directory for the skills, the analyst system prompt appended, a JSON schema for structured skills, and `--disallowedTools` for the action tools in scan mode. It cannot read files, run commands or reach any other MCP server from inside dexterm.
+
+On Codex (since 0.1.5) it is spawned as `codex exec --json` with `--ignore-user-config` and `--ignore-rules`, `--disable` for `shell_tool`, `unified_exec`, `apps`, `plugins`, `hooks`, `multi_agent`, `browser_use` and `computer_use` (an unknown name fails the run), `sandbox_mode="read-only"`, `approval_policy="never"`, `web_search="disabled"`, the system prompt as `developer_instructions`, one `dexterm` MCP server with an `enabled_tools` allow-list and its environment forwarded by name (no value on the command line), and `--output-schema` for structured skills. The same lock is repeated on every resumed turn. `analyst.engine` in `config.json` is yours alone: a model or agent proposal that touches it is refused.