dexterm-cli 0.1.3 → 0.1.4

package/dist/packages/mcp/assets/kb/docs/docs-login-with-x-what-is-read-and-when.md

@@ -0,0 +1,35 @@
+---
+id: docs-login-with-x-what-is-read-and-when
+title: Login with X › What is read, and when
+kind: docs
+page: login-with-x
+page_title: Login with X
+heading: What is read, and when
+anchor: what-is-read-and-when
+url: https://dexterm.xyz/docs/login-with-x#what-is-read-and-when
+tags:
+  - docs
+  - login-with-x
+  - read
+  - login
+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/login-with-x.md
+date: 2026-10-16
+---
+
+| what | endpoint (user context) | when | cached |
+|---|---|---|---|
+| posts about the open coin | `GET /2/tweets/search/recent` with `$SYMBOL OR <mint>` (`-is:retweet -is:reply`) | every 60 s while the token screen is open, only newer posts after the first page | 15 min per query |
+| your own X lists as KOL feeds | `GET /2/lists/:id/tweets` | every 5 min per enabled list | 15 min |
+| manual KOL lists and packs | `GET /2/tweets/search/recent` with `from:` handles, 20 per query | every 5 min | 15 min |
+| importing your lists | `GET /2/users/:id/owned_lists` + `GET /2/lists/:id/members` | only when you press `X` on the KOL screen or run `dexterm kol import-x` | – |
+| who you are | `GET /2/users/me` | once at login | – |
+
+Never: a filtered stream (economically unbounded), cashtag firehoses, search for every coin on the board, x.com pages, third-party mirrors. `⏎` on a post opens its URL in your browser; dexterm itself never fetches it.
+
+Every response goes through the rate limiter (one bucket for X, and every `x-rate-limit-*` header updates a per-endpoint window) and the health registry; a `429` pauses reads until X's reset time and the header shows `x-stream ◐ rate limited 5m`. Posts then flow through the social layer exactly like news and on-chain rows: near-duplicates collapse, account bursts are marked spam, cashtag squats are hidden, instruction-like posts are withheld from the model and flagged `INJ` for you.

package/dist/packages/mcp/assets/kb/docs/docs-login-with-x-what-you-set-up-once.md

@@ -0,0 +1,40 @@
+---
+id: docs-login-with-x-what-you-set-up-once
+title: Login with X › What you set up, once
+kind: docs
+page: login-with-x
+page_title: Login with X
+heading: What you set up, once
+anchor: what-you-set-up-once
+url: https://dexterm.xyz/docs/login-with-x#what-you-set-up-once
+tags:
+  - docs
+  - login-with-x
+  - set
+  - once
+  - login
+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/login-with-x.md
+date: 2026-10-16
+---
+
+1. **An X developer account** at developer.x.com (https://developer.x.com) (log in with the X account you want to read as).
+2. **A Project with an App** of type **Native App** (a *public* client: PKCE only, no client secret ever exists, so nothing secret ships with dexterm).
+3. In the app's **User authentication settings**: OAuth 2.0 on, type *Native App*, callback URL **exactly** `http://127.0.0.1:41287/callback` (X requires `127.0.0.1`, not `localhost`, and an exact match), any website URL, and a name/description for the consent screen.
+4. Copy the app's **Client ID** and store it (prompted on your terminal; never on the command line):
+
+```sh
+$ dexterm x set-client-id       # paste the Client ID when prompted
+$ dexterm x login               # opens your browser on x.com; approve; the tab says "linked"
+$ dexterm x status              # @handle, scopes, token age, file modes
+$ dexterm x logout              # revokes both tokens at X and deletes the local record
+```
+
+`dexterm doctor` has a **Login with X** line that tells you which of these is missing.
+
+Scopes requested: `tweet.read users.read list.read offline.access`. Nothing with `write` or `dm` is ever requested, and the app refuses to build an authorize URL with such a scope.

package/dist/packages/mcp/assets/kb/docs/docs-login-with-x-where-the-tokens-live.md

@@ -0,0 +1,27 @@
+---
+id: docs-login-with-x-where-the-tokens-live
+title: Login with X › Where the tokens live
+kind: docs
+page: login-with-x
+page_title: Login with X
+heading: Where the tokens live
+anchor: where-the-tokens-live
+url: https://dexterm.xyz/docs/login-with-x#where-the-tokens-live
+tags:
+  - docs
+  - login-with-x
+  - where
+  - tokens
+  - live
+  - login
+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/login-with-x.md
+date: 2026-10-16
+---
+
+`~/.dexterm/x/tokens.json` (mode `600`, directory `700`; `DEXTERM_HOME` moves it) next to `client-id`. The access token lasts two hours and is refreshed with the refresh token when needed; X may rotate the refresh token, so the record is rewritten. Tokens are never printed, never written to any log or recording, never put on a command line, and never part of what the analyst sees (the analyst gets firewalled post text inside `<untrusted>` blocks, nothing else). If X answers `401`, the header says `login revoked or expired at X · dexterm x login` and nothing is read until you log in again. You can also revoke at `x.com/settings/connected_apps`.

package/dist/packages/mcp/assets/kb/docs/docs-login-with-x.md

@@ -0,0 +1,26 @@
+---
+id: docs-login-with-x
+title: Login with X
+kind: docs
+page: login-with-x
+page_title: Login with X
+url: https://dexterm.xyz/docs/login-with-x
+tags:
+  - docs
+  - login-with-x
+  - login
+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/login-with-x.md
+date: 2026-10-16
+---
+
+Read X posts in the SOCIAL panel and on the trending board with your own X app and your own login; what to set up, what the free and paid API tiers allow, and what dexterm never does.
+
+dexterm can read X (Twitter) posts about the open coin and from the people you follow as KOLs. It does this **only through your own X developer app and your own X login** (OAuth 2.0 with PKCE, user context). There is no shared key, no dexterm account in the loop, no scraping, and dexterm never posts, likes, follows or reads DMs. Every tweet passes the same prompt firewall (https://dexterm.xyz/docs/analyst) as every other untrusted text before it is stored, shown or summarised.
+
+Without a login nothing breaks: the trending board runs on the keyless venues, the SOCIAL panel shows on-chain rows and news, and the header says `x-stream ○ logged out`.

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

@@ -0,0 +1,42 @@
+---
+id: docs-paper-trading-a-live-ticket
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › A LIVE ticket
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: A LIVE ticket
+anchor: a-live-ticket
+url: https://dexterm.xyz/docs/paper-trading#a-live-ticket
+tags:
+  - docs
+  - paper-trading
+  - live
+  - ticket
+  - 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
+---
+
+`L` on a ticket flips it LIVE when a wallet is linked and the signer is alive (otherwise the ticket says why and stays PAPER). The header shows `◉ LIVE · DEVNET`, or `⚠ LIVE · MAINNET — REAL FUNDS` in red with the caps. `⏎` asks the signer for a **PLAN**:
+
+1. **Quote** from Jupiter, bound to your order: the input and output mints, the mode and the exact input amount must match or the plan is refused (`quote-mismatch`).
+2. **Build** the unsigned transaction; **decode** it with dexterm's own wire decoder (legacy and v0, lookup tables included).
+3. **Policy**: every top-level instruction must fit the shape of a Jupiter swap: exactly one route-family instruction (by Anchor discriminator), token operations limited to SyncNative, InitializeAccount for your wallet and CloseAccount back to your wallet, a System transfer only into your own wrapped-SOL account that is synced and closed in the same transaction, associated-token creation only for your wallet. Transfers, burns, approvals, authority changes, direct DEX calls and unknown programs are refused by name.
+4. **Binding**: the route's `in_amount`, `quoted_out_amount` and `slippage_bps` must equal the quote; the platform fee must be zero with the "none" sentinel account (dexterm takes no fee); the transfer authority must be your wallet; the source and destination must be your own associated token accounts for the two mints.
+5. **Simulation** against the RPC, with your wallet **and your token accounts** in the requested post-state: the SOL leaving your wallet must not exceed the plan plus a fee allowance nor the SOL cap; a buy may not decrease any of your token balances; a sell may spend only the order mint's account and only up to the order amount (an address a lookup table loads counts as part of the transaction). If the balances cannot be read, the plan is refused rather than guessed.
+6. **Price**: the SOL leg times the signer's own SOL/USD, never Jupiter's `swapUsdValue`; on mainnet an unknown or $0 price refuses.
+
+The PLAN screen lists what will be signed instruction by instruction, what you pay and receive, the minimum received, the impact as a percent, the fee including any priority fee, the route, the simulation result, the SOL/USD price and its sources, the policy verdict and the caps verdict ("will be refused: …" when it would be).
+
+`Y` (or `⏎`) is the keypress gate. The signer re-checks the caps, **reserves** the USD against the daily ledger (atomically, so two trades cannot both pass), opens the sign page, and hands the bytes to Phantom. What comes back must be the **same message** with a valid Ed25519 signature by the linked wallet; the only tolerated difference is a Lighthouse assertion tail appended by Phantom. The signed bytes are decoded, policy-checked and bound again, **re-simulated** with fresh token balances, and only then submitted. A transport error after the send keeps the charge and shows the signature with "do not resend"; a definite rejection before broadcast refunds. Plans are single-use and expire after 90 s.

package/dist/packages/mcp/assets/kb/docs/docs-paper-trading-before-you-press-size-vs-caps.md

@@ -0,0 +1,34 @@
+---
+id: docs-paper-trading-before-you-press-size-vs-caps
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Before you press ⏎: size vs caps
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Before you press ⏎: size vs caps
+anchor: before-you-press-size-vs-caps
+url: https://dexterm.xyz/docs/paper-trading#before-you-press-size-vs-caps
+tags:
+  - docs
+  - paper-trading
+  - before
+  - press
+  - size
+  - caps
+  - 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
+---
+
+Since 2026-10-12 (`task-1368`) a LIVE buy ticket prices your size **at the signer's own SOL/USD** (the price its caps are enforced with) while you type, and shows it against the per-trade cap and what is left of the daily cap: `0.04 SOL ≈ $4.32 at SOL $108 · cap $5/trade · $20 left of $20 today`. When the size is over, the line turns red before you build anything: `0.05 SOL = $5.40 > $5 cap: use ≤ 0.043 SOL (f fits it; fees + token-account rent counted)`. `f` sets that size. The fit is the cap divided by the price minus 0.0025 SOL, rounded down to three decimals: the signer prices the *larger* of your planned SOL leg and the SOL the simulation actually moves out of the wallet, and a first buy of a token adds a token-account rent (0.00204 SOL) plus the fees on top of the size, so a size that is exactly the cap in USD would be refused at precheck. The daily remainder binds when it is smaller than the per-trade cap; with no SOL/USD from the signer the line says `$?` and the signer will refuse an unpriced trade on mainnet. The ticket's verdict is a preview; the signer still decides at precheck and again at confirm.

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

@@ -0,0 +1,35 @@
+---
+id: docs-paper-trading-devnet-signer-mainnet-token
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Devnet signer, mainnet token
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Devnet signer, mainnet token
+anchor: devnet-signer-mainnet-token
+url: https://dexterm.xyz/docs/paper-trading#devnet-signer-mainnet-token
+tags:
+  - docs
+  - paper-trading
+  - devnet
+  - signer
+  - mainnet
+  - token
+  - live
+  - trading
+  - 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
+---
+
+Jupiter has no devnet. A Jupiter route is built on **mainnet state** (its accounts, address-lookup tables and blockhash), so a devnet signer can never simulate or fill a swap of a real token: the simulation fails with an RPC error such as `invalid transaction: Transaction loads an address table account that doesn't exist`, and the caps refuse it (`simulation-failed`). The ticket now says this **before** you press ⏎ on any token while the signer is on devnet (`DEVNET cannot fill mainnet tokens: paper trade (L) or restart with --mainnet (real funds, caps $5/$20)`), and when a simulation does fail the PLAN shows the **full** RPC error over several lines (it used to be cut to `invalid transaction: Tr…`) with a plain-English hint when the pattern is this mismatch; the signer also writes the full error to the app log. Your two options are exactly those: paper trade the token with `L`, or run `dexterm --mainnet` with a funded mainnet wallet inside the caps (next section). The devnet signing path itself is proven by the probe, which is built for devnet on purpose.
+
+On **devnet** a Jupiter swap is refused at the caps step (`mainnet-not-enabled`): Jupiter has no devnet, so a real swap is a mainnet action. The signing path is proven on devnet instead by **`dexterm wallet probe`** (or `/wallet probe`): a transaction dexterm builds itself that wraps 0.001 SOL into your own wrapped-SOL account and closes it back, fees only, through exactly the same keypress → Phantom → verify → re-simulate → submit → confirm path, with its own policy (no route allowed) and never on mainnet.

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

@@ -0,0 +1,33 @@
+---
+id: docs-paper-trading-jupiter-rate-limits
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Jupiter rate limits
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Jupiter rate limits
+anchor: jupiter-rate-limits
+url: https://dexterm.xyz/docs/paper-trading#jupiter-rate-limits
+tags:
+  - docs
+  - paper-trading
+  - jupiter
+  - rate
+  - limits
+  - 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
+---
+
+Jupiter's keyless API allows about five requests per ten seconds per IP, answers `429` with no `Retry-After` but with a reset time, and its alternate host (`lite-api.jup.ag`) can answer `503` (both recorded on 2026-10-12 and kept as fixtures). A limit used to kill the plan (`build-failed: HTTP 429`) and park the preview on "fetching…" for half a minute. Now every keyless Jupiter call on the trade path is retried on the **other host** after the server's own reset (or `Retry-After`, with a jittered backoff), at most three attempts inside ten seconds; a `5xx` or a dropped connection alternates the same way; the LIVE preview, the signer's re-quote and the build go through the signer's **one** rate limiter and a quote fetched for the preview is reused by the build a moment later (two calls, not three). When the budget is spent, or the data layer's health gate is cooling the source down after two 429s in a minute, the ticket **keeps the plan**: it shows `Jupiter is rate limiting this IP (429 from api.jup.ag), retrying in Ns`, retries by itself when the wait ends, `r` retries now and `esc` cancels. Nothing is built or signed while it waits.

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

@@ -0,0 +1,32 @@
+---
+id: docs-paper-trading-link-a-wallet
+title: Paper trading, live trading and the safety model › Live trading (devnet first) › Link a wallet
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Link a wallet
+anchor: link-a-wallet
+url: https://dexterm.xyz/docs/paper-trading#link-a-wallet
+tags:
+  - docs
+  - paper-trading
+  - link
+  - wallet
+  - 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
+---
+
+`dexterm wallet link` (or `/wallet link` typed on the screener's `/` line or in the chat box) starts a one-shot server on `127.0.0.1:41291` (a fixed loopback port since `task-1368`; a random one only if it is busy, and the page then says so) with a single-use token, and opens your browser to it. The page asks Phantom to **connect** and **sign a message** (a dexterm nonce): no transaction, no approval of funds. The port is fixed because Phantom remembers which **origins** it trusts: link and every later sign page share `http://127.0.0.1:41291`, so after the first Connect prompt Phantom connects silently. dexterm verifies the Ed25519 proof and stores **only your public key** in `~/.dexterm/wallet-link.json`. `dexterm wallet status`, `unlink`, `/wallet`, `/wallet unlink` show or remove it. No private key, seed or password ever reaches dexterm; it has no code that could hold one.

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

@@ -0,0 +1,30 @@
+---
+id: docs-paper-trading-live-trading-devnet-first
+title: Paper trading, live trading and the safety model › Live trading (devnet first)
+kind: docs
+page: paper-trading
+page_title: Paper trading, live trading and the safety model
+heading: Live trading (devnet first)
+anchor: live-trading-devnet-first
+url: https://dexterm.xyz/docs/paper-trading#live-trading-devnet-first
+tags:
+  - docs
+  - paper-trading
+  - 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
+---
+
+**Status: in progress.** The code is on main and verified against fakes, a hand-built attack suite and a real recorded Jupiter transaction; the one thing not yet observed is a transaction signed by the real Phantom extension on devnet, which the maintainers' probe run will settle. Nothing here has touched mainnet.

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.