dexterm-cli 0.1.3 → 0.1.5

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

@@ -0,0 +1,31 @@
+---
+id: docs-paper-trading-mainnet
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Mainnet
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Mainnet
+anchor: mainnet
+url: https://dexterm.xyz/docs/paper-trading#mainnet
+tags:
+  - docs
+  - paper-trading
+  - mainnet
+  - live
+  - trading
+  - devnet
+  - first
+  - paper
+  - 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
+---
+
+Only with `--mainnet`. The banner is red, the caps are $5 per trade and $20 per day by default (raise them only with the flag, never above $500 / $2000), 1 SOL out per transaction, 3% impact, 500 bps slippage. dexterm takes no fee; you pay network fees only. Nobody has run a mainnet trade through this path yet, and nothing on this page authorizes one.

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

@@ -0,0 +1,44 @@
+---
+id: docs-paper-trading-order-plans-and-standing-mandates
+title: Paper trading, live trading and the safety model › Order plans and standing mandates
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Order plans and standing mandates
+anchor: order-plans-and-standing-mandates
+url: https://dexterm.xyz/docs/paper-trading#order-plans-and-standing-mandates
+tags:
+  - docs
+  - paper-trading
+  - order
+  - plans
+  - standing
+  - mandates
+  - 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
+---
+
+Merged 2026-10-11 (`task-1355`) and labelled **in progress**: the engine, the typed and spoken proposal paths, the `O` screen, the popup and the audit journal are on main and every default run is **paper**. Since 2026-10-12 (`task-1363`) a **live fire path on devnet** exists behind a held keypress: fills go through the signer process and a separate capped fast wallet, described in the live fire path (https://dexterm.xyz/docs/paper-trading#the-live-fire-path-devnet-the-fast-wallet) below. No plan has moved mainnet funds; there is no mainnet fast wallet.
+
+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.

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

@@ -0,0 +1,31 @@
+---
+id: docs-paper-trading-panic
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Panic
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Panic
+anchor: panic
+url: https://dexterm.xyz/docs/paper-trading#panic
+tags:
+  - docs
+  - paper-trading
+  - panic
+  - live
+  - trading
+  - devnet
+  - first
+  - paper
+  - 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
+---
+
+`/wallet panic` in the app, or `dexterm wallet panic` from any shell, any time: it writes a kill-switch file every signer re-reads on every plan and confirm, locks the shared cap ledger so no reservation can be taken, tells the running signer to forget its plans and flips an open LIVE ticket to refused. The only way back is `dexterm wallet resume` in a real terminal: it needs a physical keypress on a TTY and refuses piped input.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-pnl-cards.md

@@ -0,0 +1,37 @@
+---
+id: docs-paper-trading-pnl-cards
+title: Paper trading, live trading and the safety model › PnL cards
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: PnL cards
+anchor: pnl-cards
+url: https://dexterm.xyz/docs/paper-trading#pnl-cards
+tags:
+  - docs
+  - paper-trading
+  - pnl
+  - cards
+  - 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
+---
+
+`H` on a token, on the positions screen (`P`) or on the followed-wallets screen (`U`) opens a preview of a **PnL card** for a coin you have fills for: ticker and image, average entry and exit (or the mark for an open position), the PnL %, hold time, size, the dates, and a dexterm footer. It is saved as a 1200×675 PNG (the X card size), a 1080×1080 PNG and a text file in `~/.dexterm/exports/`.
+
+- **The stamp cannot be removed.** A card says where its numbers came from: **PAPER** (the simulated wallet, no real funds), **LIVE** (transactions your own wallet signed, confirmed on chain; a devnet fill says *DEVNET TEST FUNDS*) or **TRACKED WALLET** (a followed wallet's public history, read-only). The stamp is a solid block, the frame colour and a repeating strip, and no option hides it.
+- **Numbers come only from the records.** The PnL is computed from the fills, net of fees (realized for a closed position; realized plus unrealized at the latest price mark for an open one, which waits for a mark). You cannot type a number into a card. Each card prints its time window, the fee basis, what it leaves out (a tracked wallet's token-to-token swaps, transfers or airdrops) and the age of its data.
+- **Private by default.** The wallet address and LIVE transaction signatures are hidden, and the size shows as a band (`0.5-1 SOL`). `a` shows the wallet and signatures, `z` the exact size; no balance or key is ever on a card.
+- **Sharing is yours.** `x` saves the card, copies the image to the clipboard where your OS allows it (macOS; Linux with `wl-copy` or `xclip`) and opens X's compose page in your browser with a short neutral text (the stamp in words, no coin and no numbers). You paste the image and post. dexterm does not post, has no X credentials for this and sends nothing. `t` copies the text version, `s` only saves; `f` flips 16:9 and 1:1, `←`/`→` move between coins, `esc` closes.
+
+A card shows one position's own fills. It is not a track record, and trading in dexterm is still experimental; the footer says so, along with "not financial advice".

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-the-live-fire-path-devnet-the-fast-wallet.md

@@ -0,0 +1,41 @@
+---
+id: docs-paper-trading-the-live-fire-path-devnet-the-fast-wallet
+title: Paper trading, live trading and the safety model › Order plans and standing mandates › The live fire path (devnet, the fast wallet)
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: The live fire path (devnet, the fast wallet)
+anchor: the-live-fire-path-devnet-the-fast-wallet
+url: https://dexterm.xyz/docs/paper-trading#the-live-fire-path-devnet-the-fast-wallet
+tags:
+  - docs
+  - paper-trading
+  - live
+  - fire
+  - path
+  - devnet
+  - fast
+  - wallet
+  - order
+  - plans
+  - standing
+  - mandates
+  - paper
+  - trading
+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
+---
+
+A standing mandate is meant to fire at machine speed, which a Phantom approval per fill cannot do. So the live path uses a second, **capped fast wallet**: the one key dexterm ever holds, created only by `dexterm wallet fast create` after a real keypress on a TTY, stored at `~/.dexterm/fast-wallet.json` at mode 600, **devnet only** (the record says so, the signer process loads it only against a devnet RPC, and there is no mainnet variant, no export and no import). `dexterm wallet fast status` shows its public key and devnet balance, `dexterm wallet fast airdrop` asks the devnet faucet, `dexterm wallet fast remove` deletes it (refused while it still holds SOL unless `--force`). Your main wallet is never named by a mandate and the fast wallet never signs for it: the signer refuses either crossing before caps, reservation or signing.
+
+`L` on the `O` screen raises the fire-path prompt; a held keypress switches plan fills from PAPER to **LIVE · DEVNET · fast wallet** (and back), journaled as `settings.executor`. The switch is refused by voice, an agent, a pipe or the popup (it takes nothing but a keypress), while any plan is armed or holding (its legs would strand on the other ledger), when the run has no signer process (replay, offline, `--no-live`), when the signer is not on devnet, or when no fast wallet is loaded. Every run starts on paper; the journal never recovers a live switch.
+
+When an armed plan fires on the live path, the engine asks the signer to **build a devnet fill** for its leg. Jupiter has no devnet, so the transaction is the probe's wrap-and-unwrap shape sized to the plan's SOL leg (0.02 SOL for a $3 entry at $150/SOL), with an on-chain memo naming the plan leg; the signer decodes it, runs the probe-shape policy and the program allow-list, simulates it with the fast wallet's token balances, prices the SOL leg from its own SOL/USD feed and **enforces its USD per-trade and daily caps on devnet too** (a fill with no trustworthy price, or above the per-trade or remaining daily budget, is refused and the reason, `per-trade-cap`, `daily-cap`, `no-usd-value`, is what the plans journal records) plus a hard **0.05 SOL per-fill ceiling**. The confirm re-checks and reserves the USD, has the fast wallet sign, verifies the signature and the message, re-simulates the signed bytes, submits and confirms. The engine journals an intent before anything is sent, treats the send as in flight until the signer answers, settles it by lookup and never resends; an outcome the signer could not determine expires in the engine after 90 seconds as unseen (the fast wallet is capped, so exposure is bounded). The plan's **token leg is modelled** from the fire-time price, because no token changes hands on devnet, and the journal labels the fill `devnet-fill` with `modelledTokens: true`, the real signature and the real SOL delta (the fees). A mainnet fill through the fast wallet is refused by construction.
+
+What is proven here, on fakes with the real decoder, the real Ed25519 signer and the real executor pipeline: a fill is built, signed by the fast wallet (Phantom is never asked), confirmed and booked with the USD ledger charged; the ceiling, a missing price, the per-trade cap and the daily cap each refuse before anything signs; a mainnet signer or a missing fast wallet refuses the build; a fast-lane plan confirmed with the main wallet's key, or a main-lane plan built for the fast wallet, is `signer-mismatch`; the whole path works over the real authenticated child-process channel; and the engine-side adapter turns the signer's answers into the journal rows above. What is not: a fill confirmed on devnet with real faucet SOL (the public faucet answered an internal error on the day), and any mainnet action.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-the-signer-process.md

@@ -0,0 +1,34 @@
+---
+id: docs-paper-trading-the-signer-process
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › The signer process
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: The signer process
+anchor: the-signer-process
+url: https://dexterm.xyz/docs/paper-trading#the-signer-process
+tags:
+  - docs
+  - paper-trading
+  - signer
+  - process
+  - live
+  - trading
+  - devnet
+  - first
+  - paper
+  - 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
+---
+
+The first LIVE action starts a **separate signer process** with exactly the caps flags you started dexterm with (`--max-usd`, `--daily-usd`, `--max-sol-out`, `--max-slippage-bps`, `--trade-rpc`, `--mainnet`). It talks to the terminal over an authenticated pipe whose only methods are `status · plan · probe · precheck · confirm · drop · panic`: there is no `sign(bytes)`, no `submit`, no `setCaps`, and no way to name a wallet other than the one in the signer's own link file. If the signer dies it is never respawned; LIVE stays off until you restart.
+
+The signer owns: the caps and their hard ceilings; the **daily USD ledger** (SQLite, shared by every dexterm process on the machine, survives a restart); the **kill switch**; its own HTTP client for Jupiter and the RPC; its own **SOL/USD feed** (DexScreener and CoinGecko, timestamped, both required within 3% and under 60 s on mainnet); and the wallet bridge. The network it reports and caps by is classified from the RPC endpoint it actually talks to, by exact hostname, never from a flag or a label.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-the-ticket.md

@@ -0,0 +1,31 @@
+---
+id: docs-paper-trading-the-ticket
+title: Paper trading, live trading and the safety model › The ticket
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: The ticket
+anchor: the-ticket
+url: https://dexterm.xyz/docs/paper-trading#the-ticket
+tags:
+  - docs
+  - paper-trading
+  - ticket
+  - 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
+---
+
+`B` or `S` on a token opens a buy or sell ticket. It shows the side, the size (SOL or % of balance when buying; % of the position when selling), slippage in bps, and a rolling Jupiter quote refreshed every (generated from the app: see https://dexterm.xyz/docs/paper-trading#the-ticket; app-help has the exact keys and commands) s while you edit: what you pay, what you receive, price in SOL and USD, price impact (as a percent; Jupiter reports a 0..1 fraction and the app converts it once), the simulated fee, the route and the minimum received. Keys: digits type, `tab` switches field, `←`/`→` flips the side, `u` toggles the unit, `⏎` reviews, `esc` cancels, `L` flips PAPER ⇄ LIVE (see below). Token amounts are shown as quantities, so a small buy of an expensive token reads `0.0144 AVGOx`, never `0`; until the token's decimals are known the ticket says so instead of printing a guess.
+
+The **confirm gate** is on by default. `⏎` arms the order; `y` (or `⏎` again) confirms. For a notional above (generated from the app: see https://dexterm.xyz/docs/paper-trading#the-ticket; app-help has the exact keys and commands) SOL you must type the size back digit for digit before the confirm counts. Any other key during the confirm step cancels the arm: a stray key can never confirm, and `q` or a screen number cannot navigate out from under an armed order. The fill is computed from a **fresh quote at confirm time**, never from the quote on screen, and is booked into the paper wallet in one SQLite transaction. If Jupiter rate-limits during the confirm the ticket says so, retries for up to 8 s, then lands in an error state you can retry or cancel; it never hangs.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-the-wallet.md

@@ -0,0 +1,34 @@
+---
+id: docs-paper-trading-the-wallet
+title: Paper trading, live trading and the safety model › The wallet
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: The wallet
+anchor: the-wallet
+url: https://dexterm.xyz/docs/paper-trading#the-wallet
+tags:
+  - docs
+  - paper-trading
+  - wallet
+  - 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
+---
+
+- starts at (generated from the app: see https://dexterm.xyz/docs/paper-trading#the-wallet; app-help has the exact keys and commands) SOL (configurable), persisted in the same SQLite file as the cache and watchlist (`--db`; `:memory:` for a throwaway session);
+- books every fill append-only with the simulated fee (5 000 lamports per fill, labelled as a simulation);
+- marks positions from DexScreener's USD price over the live SOL price every (generated from the app: see https://dexterm.xyz/docs/paper-trading#the-wallet; app-help has the exact keys and commands) s on the positions screen;
+- shows a `◈ POSITION · PAPER` row under the chart on any token you hold, and the same row plus entry line and fill markers in the chart popup (https://dexterm.xyz/docs/popup-chart). A confirmed LIVE fill shows the same way, marked live, read from the signer's own ledger.
+
+The analyst can open a PAPER ticket for you (`open_ticket`, pre-filled, editing phase) when you ask it to buy or sell. It cannot size it past what you typed, arm it, confirm it, or flip it LIVE; it tells you to confirm yourself.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-trade-moments.md

@@ -0,0 +1,32 @@
+---
+id: docs-paper-trading-trade-moments
+title: Paper trading, live trading and the safety model › Trade moments
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Trade moments
+anchor: trade-moments
+url: https://dexterm.xyz/docs/paper-trading#trade-moments
+tags:
+  - docs
+  - paper-trading
+  - trade
+  - moments
+  - 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
+---
+
+The cyberspace look reacts to a trade, but only to its **result**. A confirmed buy fires a green shockwave from the ticket with coins streaming up; a profitable sell a gold burst and gold rain; a loss red static that collapses down the screen (no shake, no mockery); a signer refusal or a failed send a red lockout flicker in the bands; and while a send is in flight a neutral cyan scanning sweep that is never a verdict. Normal and fever tiers differ in length and density; `--calm` shows none of it and the result card still lands at once; any key skips a running moment.
+
+Two things are mechanical, not conventions. **Only a settled outcome can fire a moment:** the ticket reports exactly one outcome per booked paper fill, confirmed live fill, signer refusal or send failure, and the effects engine refuses anything without a confirmed-or-failed status; a quote, a PLAN, an armed order or a `send-unknown` (the chain may still confirm it) fires nothing, and a test checks the one call site. **The ticket is shielded:** every cell of the ticket and the PAPER / LIVE banner is marked off-limits on the cell buffer, so rain, glitch, datamosh, scanlines and the moments cannot write a glyph, a colour or a background into it in any phase (tested byte-identical against a calm render at 176, 120 and 90 columns). `--sound` (or `DEXTERM_SOUND=1`) adds short synthesized cues after the same outcome: a buy chirp, a sell sweep then a chime or a thud, a buzz on a failure. Muted by default; the WAVs are written once to `~/.dexterm/sounds` and played detached so the render loop never waits.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-what-the-live-path-keeps.md

@@ -0,0 +1,37 @@
+---
+id: docs-paper-trading-what-the-live-path-keeps
+title: Paper trading, live trading and the safety model › What the live path keeps
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: What the live path keeps
+anchor: what-the-live-path-keeps
+url: https://dexterm.xyz/docs/paper-trading#what-the-live-path-keeps
+tags:
+  - docs
+  - paper-trading
+  - live
+  - path
+  - keeps
+  - paper
+  - trading
+  - 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
+---
+
+These are the invariants from the spec; hold us to them:
+
+1. **Non-custodial.** You hold the keys. dexterm builds, simulates and hands off; your wallet signs. The Phantom bridge stores only your public key.
+2. **Keypress gate on by default.** Models and voice create proposals; arming needs a physical keypress or a wallet approval. Opting out, if ever offered, needs an explicit "this is less safe" confirmation, is local, logged and reversible, and the signer caps still apply.
+3. **Caps live in the signer, not the UI.** The signer re-simulates and re-checks every transaction (per-trade and daily USD caps, price-impact and slippage ceilings, the SOL-out cap, the token-balance diff, a positive description of what a Jupiter swap looks like: exactly one route instruction bound to your order, no token transfers, burns or approvals to anyone) and refuses out of policy even if the UI, the model or a popup is compromised.
+4. **The AI has no interface to the signer.** No build, sign or send tool exists for the model. Its write-shaped tools are paper only: `open_ticket` opens a PAPER ticket, and (from 0.1.5, only if you start `--agent-paper` on a mandate you armed) an agent you connected can use the `paper_*` tools to book the **simulated** ledger inside that mandate. A registry test enumerates every MCP tool and fails if any could reach a signing, sending or cap-changing path, and the paper path imports nothing signer-shaped. Even on a live-capable context the model's ticket yields a paper ticket and the signer is never called. The scan mode and the MCP server import nothing signer-shaped.
+
+> warn: paper results are not predictive, and live results are real. Paper fills take the quote at its word; a real fill pays real slippage, priority fees and failed transactions, and most memecoins go to zero. Nothing here is financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-your-first-live-trade.md

@@ -0,0 +1,41 @@
+---
+id: docs-paper-trading-your-first-live-trade
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Your first live trade
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Your first live trade
+anchor: your-first-live-trade
+url: https://dexterm.xyz/docs/paper-trading#your-first-live-trade
+tags:
+  - docs
+  - paper-trading
+  - first
+  - live
+  - trade
+  - trading
+  - devnet
+  - paper
+  - 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
+---
+
+A walkthrough for one small, real swap inside the default caps. It is the path the verifier follows with a devnet signer (every step up to the confirm behaves the same, and the devnet wall above is where it stops) and on fixtures; nobody has yet run it to a mainnet fill, and nothing here is advice to.
+
+1. **Link your wallet.** `dexterm wallet link` opens Phantom on a loopback page; connect and sign the nonce. `dexterm wallet status` shows the public key. dexterm never sees a key.
+2. **Fund a small mainnet wallet.** Use a wallet that holds only what you are willing to lose plus fees: for a $5 trade at SOL $108 that is about 0.06 SOL (0.046 for the swap, the rest for the token-account rent of 0.00204 SOL, network and priority fees and a reserve). The per-trade cap is $5 and the daily cap $20 by default; the hard ceilings are $500 and $2000 and only `--mainnet` can raise anything.
+3. **Start on mainnet with the caps you mean.** `dexterm --mainnet --max-usd 5` (add `--daily-usd 20`, `--max-sol-out 1`, `--max-slippage-bps 500` to be explicit). The ticket header turns red: `⚠ LIVE · MAINNET — REAL FUNDS · caps $5/trade $20/day`. The signer process starts on the first LIVE action with exactly these flags, classifies the network from the RPC it talks to, and needs two independent SOL/USD sources within 3% before it will price anything.
+4. **Open a ticket and size it under the cap.** `B` on a token, `L` to flip LIVE, type a size; watch the cap line and press `f` if it is red (it sets the largest size that fits, fees and rent included). Slippage stays at 50 bps unless you change it; impact over 3% is refused.
+5. **Build the plan.** `⏎`. If Jupiter rate-limits, the ticket waits and retries by itself (`r` now, `esc` cancels). The PLAN lists what will be signed, what you pay and receive, the minimum received, the fee, the route, the simulation result (how much SOL leaves your wallet), the SOL/USD price and its sources, and the caps verdict; `within caps` means the signer will not refuse it at this moment.
+6. **Confirm.** `Y`. The signer re-checks the caps, reserves the USD on the daily ledger, opens the sign page. The page **connects first** (a Connect prompt the first time on this origin, silent after that), shows the connected account and refuses one that is not the linked wallet (`Phantom is on account … but dexterm linked …`), then asks Phantom to sign; approve in Phantom. If Phantom answers 4100 ("not authorized") the page says so and what to do: press Approve again and accept the Connect prompt, or allow `127.0.0.1:41291` under Phantom's Trusted apps, then confirm the trade again in dexterm; nothing was signed. The signed bytes must be the same message with your signature (a Lighthouse tail appended by Phantom is the one tolerated change); they are decoded, policy-checked, bound and re-simulated with fresh balances, then submitted and confirmed.
+7. **Expected outcome.** `✓ LIVE MAINNET BUY confirmed — 0.0144 AVGOx @ 2.778 SOL · sig …` with the signature; the position appears under the chart marked live and on the positions screen under LIVE POSITIONS; the daily ledger shows the spend (`Caps … spent $4.32`). A refusal (`✗ REFUSED by the signer — per-trade-cap: …`) means nothing was signed or sent. `send-unknown` with a signature means the transaction may have been broadcast: check the explorer, do not resend.
+8. **Panic key.** `/wallet panic` in the app or `dexterm wallet panic` from any shell disables live signing everywhere at once (kill-switch file, locked ledger, plans forgotten). `dexterm wallet resume` on a real TTY is the only way back.
+9. **Read the journal.** `dexterm wallet status` shows the linked key, the signer's network and caps, today's spend and the panic state. Confirmed real fills live in `~/.dexterm/live-trades.sqlite` (the signer's own ledger, read by the positions screen); the daily USD reservations in the shared cap ledger `~/.dexterm/caps.sqlite`; the signer's log lines (including the full text of any failed simulation) go to the app log. Order plans, if you use them, append to `~/.dexterm/plans.journal`, which `dexterm plan journal --verify` recomputes.

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

@@ -0,0 +1,32 @@
+---
+id: docs-paper-trading
+title: Paper trading, live trading and the safety model
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+url: https://dexterm.xyz/docs/paper-trading
+tags:
+  - docs
+  - paper-trading
+  - 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
+---
+
+The PAPER ticket, the simulated wallet, the confirm gate; the LIVE path behind a separate signer process (devnet first), and the invariants it keeps.
+
+Trading in dexterm is **PAPER by default**: a simulated wallet priced from live, keyless Jupiter quotes. Nothing is signed, no key is held, no transaction is sent, and the paper code imports no wallet or signing library of any kind. Every ticket and positions frame says so in a banner that is never hidden.
+
+A **LIVE** path exists on main, devnet first and labelled in progress: your own Phantom signs, a separate signer process holds the caps, and a Jupiter swap (a mainnet transaction) is refused unless you start dexterm with `--mainnet`. It is described in Live trading (devnet first) (https://dexterm.xyz/docs/paper-trading#live-trading-devnet-first) below.
+
+PAPER positions on sample data

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

@@ -0,0 +1,27 @@
+---
+id: docs-popup-chart-bubble-map-popup
+title: Popup chart › Bubble map popup
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Bubble map popup
+anchor: bubble-map-popup
+url: https://dexterm.xyz/docs/popup-chart#bubble-map-popup
+tags:
+  - docs
+  - popup-chart
+  - bubble
+  - map
+  - popup
+  - chart
+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/popup-chart.md
+date: 2026-10-16
+---
+
+`M` on the bubble map screen (https://dexterm.xyz/docs/screens#bubble-map) opens the same holder graph as real circles in a second HUD window (the chart can stay open). Hover a bubble for the rule behind its colour; click to select it, and the terminal selects the same holder; `m` flips to a treemap, `z` zooms the selected cluster, `esc` closes. The strip under the map carries the sample-captioned insights (top-10 raw and ex-pool, and the main-risk line when a counted owner holds more than 30 %) and a WHY THIS LABEL panel that leads with the selected holder's class (POOL, CURVE, VAULT, LOCK, CEX, BURN, DEV, LINKED or UNLABELLED) and its on-chain reason, then every rule, confidence and evidence line. The page receives a **text-only view model** over the local WebSocket (addresses, shares, rule text, numbers): no keys, no URLs, no fetches of its own; an unavailable or degraded scan shows a banner and never a fake map. Same server, ticket, CSP and event allow-list as the chart; the only event the page may send back is the validated address of a clicked holder.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-build-the-native-window.md

@@ -0,0 +1,33 @@
+---
+id: docs-popup-chart-build-the-native-window
+title: Popup chart › Build the native window
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Build the native window
+anchor: build-the-native-window
+url: https://dexterm.xyz/docs/popup-chart#build-the-native-window
+tags:
+  - docs
+  - popup-chart
+  - build
+  - native
+  - window
+  - popup
+  - chart
+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/popup-chart.md
+date: 2026-10-16
+---
+
+```sh
+$ cd packages/popup && npm run build:shell     # cargo build --release, about a minute the first time
+$ dexterm popup --self-test                     # which path is active, hotkey registration, measured fps
+```
+
+`install.sh` builds it when `cargo` is present (`DEXTERM_SKIP_SHELL=1` skips); `dexterm doctor` has a "Chart window" line that says ready or prints the command. `DEXTERM_POPUP_SHELL` points at a prebuilt binary. Without the shell every feature works in the browser; the native window is an enhancement, never a requirement.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-config-dexterm-popup-json.md

@@ -0,0 +1,38 @@
+---
+id: docs-popup-chart-config-dexterm-popup-json
+title: Popup chart › Config: ~/.dexterm/popup.json
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Config: ~/.dexterm/popup.json
+anchor: config-dexterm-popup-json
+url: https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json
+tags:
+  - docs
+  - popup-chart
+  - config
+  - dexterm
+  - popup
+  - json
+  - chart
+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/popup-chart.md
+date: 2026-10-16
+---
+
+```json
+{
+  "hotkey": "(generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands)",
+  "hotkeyClose": "(generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands)",
+  "dock": { "enabled": true, "width": (generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands), "follow": true, "followEvery": (generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands) },
+  "rain": { "enabled": true, "speedScale": 1, "density": (generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands) },
+  "fpsCap": (generated from the app: see https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json; app-help has the exact keys and commands)
+}
+```
+
+Everything is optional; a missing or malformed file falls back to these defaults and never stops a popup from opening. An empty hotkey string disables that chord. `DEXTERM_HOME` moves the directory.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-docking-macos.md

@@ -0,0 +1,27 @@
+---
+id: docs-popup-chart-docking-macos
+title: Popup chart › Docking (macOS)
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Docking (macOS)
+anchor: docking-macos
+url: https://dexterm.xyz/docs/popup-chart#docking-macos
+tags:
+  - docs
+  - popup-chart
+  - docking
+  - macos
+  - popup
+  - chart
+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/popup-chart.md
+date: 2026-10-16
+---
+
+The window opens flush right of your terminal window with the same top and height; left of it when the right has no room; pinned at the screen edge (on top) when neither side fits; at the main screen's right edge when the terminal is not Terminal.app or iTerm2. It follows the terminal while open (one lightweight loop, about 0.3% CPU) until you drag the chart's title strip. It has no Dock icon. The terminal may ask once for Automation permission to read its own window bounds; if you deny, the chart opens at the screen edge instead of docked.

package/dist/packages/mcp/assets/kb/docs/docs-popup-chart-keys-in-the-popup.md

@@ -0,0 +1,30 @@
+---
+id: docs-popup-chart-keys-in-the-popup
+title: Popup chart › Keys in the popup
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Keys in the popup
+anchor: keys-in-the-popup
+url: https://dexterm.xyz/docs/popup-chart#keys-in-the-popup
+tags:
+  - docs
+  - popup-chart
+  - keys
+  - popup
+  - chart
+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/popup-chart.md
+date: 2026-10-16
+---
+
+Click the window first: it opens unfocused so it never steals the terminal's keyboard. (generated from the app: see https://dexterm.xyz/docs/popup-chart#keys-in-the-popup; app-help has the exact keys and commands)
+
+(generated from the app: see https://dexterm.xyz/docs/popup-chart#keys-in-the-popup; app-help has the exact keys and commands)
+
+Global hotkeys (configurable in `popup.json`): `(generated from the app: see https://dexterm.xyz/docs/popup-chart#keys-in-the-popup; app-help has the exact keys and commands)` shows or hides every popup, `(generated from the app: see https://dexterm.xyz/docs/popup-chart#keys-in-the-popup; app-help has the exact keys and commands)` closes them all.

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

@@ -0,0 +1,28 @@
+---
+id: docs-popup-chart-market-cap-axis
+title: Popup chart › Market cap axis
+kind: docs
+page: popup-chart
+page_title: Popup chart
+heading: Market cap axis
+anchor: market-cap-axis
+url: https://dexterm.xyz/docs/popup-chart#market-cap-axis
+tags:
+  - docs
+  - popup-chart
+  - market
+  - cap
+  - axis
+  - popup
+  - chart
+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/popup-chart.md
+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.