dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-the-autotrade-json-file.md

@@ -0,0 +1,48 @@
+---
+id: docs-autotrade-the-autotrade-json-file
+title: Autotrade (paper) › Several strategies at once › The autotrade.json file
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: The autotrade.json file
+anchor: the-autotrade-json-file
+url: https://dexterm.xyz/docs/autotrade#the-autotrade-json-file
+tags:
+  - docs
+  - autotrade
+  - json
+  - file
+  - several
+  - strategies
+  - once
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+```json
+{
+  "schema": "dexterm-autotrade/1",
+  "strategies": [
+    { "id": "moon-a", "preset": "moonbag", "bankroll": { "usd": 500 } },
+    { "id": "fast", "preset": "my-scalp", "bankroll": { "sol": 1 }, "caps": { "modelUsdPerDay": 2, "maxSessions": 1 } },
+    { "id": "dip", "file": "/Users/you/strategies/dip.json", "bankroll": { "usd": 200 }, "enabled": false }
+  ],
+  "global": { "maxConcurrentSessions": 3, "modelUsdPerDay": 15 }
+}
+```
+
+- **`id`** names the strategy in this run: in its run file, on the Q screen and in every alert. Each id is used once.
+- **`preset`** is a shipped preset or one of your own strategies; **`file`** is an absolute path to a strategy file. Give exactly one.
+- **`bankroll`** is in USD, or in SOL (converted at the SOL price when the run starts; a replay takes `"solUsd"` or `--sol-usd`). Without it the strategy's own bankroll applies.
+- **`caps`** can only tighten a strategy: `maxSessions`, `modelUsdPerDay`, `candidateSessionsPerDay`, `positionSessionsPerDay` and `turnsPerDay`. The stricter of the strategy, these caps, `runner.json` and `global` always applies.
+- **`enabled: false`** keeps a strategy in the list without starting it. `dexterm autotrade start <id>` starts it later in the running run.
+- **`global`** holds the shared limits. The defaults are 3 sessions open at once, $20 of model spend a day, 96 candidate and 96 position sessions a day, and 4,000 turns a day. The day caps in `runner.json` still apply on top.
+
+Up to 8 strategies (a strategy on several paper accounts counts once per account). Every strategy must check out before anything starts: a typo, an unknown preset or a strategy that is not on paper stops the whole run with each problem named. `--config FILE` reads another file. The file is yours: no tool, chat or agent can add a strategy to it or change a bankroll or a cap.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-the-heartbeat.md

@@ -0,0 +1,27 @@
+---
+id: docs-autotrade-the-heartbeat
+title: Autotrade (paper) › Stopping it › The heartbeat
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: The heartbeat
+anchor: the-heartbeat
+url: https://dexterm.xyz/docs/autotrade#the-heartbeat
+tags:
+  - docs
+  - autotrade
+  - heartbeat
+  - stopping
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+- The runner rewrites `runner-status.json` every 10 seconds. If it cannot (a full disk, a removed folder), it takes no new entries until it can again, because the `Q` screen and the exit monitor would see it as gone. With no fresh heartbeat the `Q` screen shows the runner as stale.
+- Each position keeps its own `maxHoldMinutes` exit, and a session that dies or times out never holds up an exit.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-the-run-file-and-the-heartbeat.md

@@ -0,0 +1,34 @@
+---
+id: docs-autotrade-the-run-file-and-the-heartbeat
+title: Autotrade (paper) › The runner and candidate sessions › The run file and the heartbeat
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: The run file and the heartbeat
+anchor: the-run-file-and-the-heartbeat
+url: https://dexterm.xyz/docs/autotrade#the-run-file-and-the-heartbeat
+tags:
+  - docs
+  - autotrade
+  - run
+  - file
+  - heartbeat
+  - runner
+  - candidate
+  - sessions
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+Every step goes to `~/.dexterm/autotrade/runs/<run>.jsonl`, written as it happens: each message sent, each raw reply and parsed decision, the clamp with its cuts, fills, events, refusals, session costs and the usage readings. Each line carries the hash of the one before it, so an edited, missing or reordered line shows. A summary sits next to it, and `~/.dexterm/autotrade/runner-status.json` (candidates, sessions, positions, spend and the last steps) is rewritten every 10 seconds as the runner's heartbeat. The coins it is working are also handed to the recorder's 5-second sampling (`dexterm record run --focus-ticks`).
+
+**Today's limits.** Orders fill on the runner's own paper book with the backtest's fill model (price impact on the pool, fee, slippage). Filling through the paper desk and the exit monitor as its own process are still to come. To stop the runner, see Stopping it (https://dexterm.xyz/docs/autotrade#stopping-it).
+
+Paper only: `--live` is refused, a strategy in live mode is refused, and nothing in the runner can arm a mandate, sign, or touch a wallet or a key.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-the-runner-and-candidate-sessions.md

@@ -0,0 +1,45 @@
+---
+id: docs-autotrade-the-runner-and-candidate-sessions
+title: Autotrade (paper) › The runner and candidate sessions
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: The runner and candidate sessions
+anchor: the-runner-and-candidate-sessions
+url: https://dexterm.xyz/docs/autotrade#the-runner-and-candidate-sessions
+tags:
+  - docs
+  - autotrade
+  - runner
+  - candidate
+  - sessions
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+```
+dexterm autotrade run my-swing --paper                                  # live data, your own Claude login
+dexterm autotrade run my-swing --paper --replay tape.json               # a recorded tape, paced
+dexterm autotrade run my-swing --paper --stub --replay tape.json        # a scripted agent: no Claude usage
+```
+
+`dexterm autotrade run` works one strategy on paper, headless, and only one runner runs per machine. It screens the same live data as the app with the app's free sources and request limits: the screener's coins every 10 seconds, and the coins it is working (candidates and positions) every 5 seconds, 30 coins per DexScreener call, under a daily call ceiling. `--replay FILE` paces a tape saved with `dexterm autotrade extract` instead; `--max-minutes N` stops after N minutes; Ctrl+C stops it cleanly.
+
+**It talks in market cap.** The run's lines (`BUY ABC [swing]: $25.00 at $69.7K mcap`), the candidate's DOSSIER, the ENGINE notes and the EVENTs your agent reads give levels as market caps by default (with the price beside them in the DOSSIER), and your agent is told to say levels the same way. `--price` (or `display.priceMode: "price"`) switches the wording to prices; the trades are the same either way, because the engine only reads prices. The run file's fills keep `price` and add `mcap`.
+
+**A candidate gets one session.** A coin that passes your entry rules, and that your strategy would still allow an entry for (a free slot, cash, no halt), becomes a candidate and gets one session on your own `claude` login:
+
+- The first message is the full picture: the market now and its recent history, holders and concentration (the top-10 share the strategy's top-10 gate reads, which is Jupiter's, next to the top-10 of the largest accounts from your RPC with pools, bonding curves, launch vaults, locks and burns left out, each named with its source; when the two disagree the message says so), security (authorities and the RugCheck read), candles, recent trades, the coin's creator, and which of these are unavailable and why, plus your bounds (the exit profiles, the largest size your strategy allows, the paper book, open positions).
+- After that, only what changed, with each change in percent: every 15 seconds (`agent.deltaEverySec`), or at once on a fast move (8% in price or a 15% drop in liquidity). Updates that pile up while the agent is thinking go as one message.
+- Your agent answers every message with one typed decision: `enter`, `wait` or `skip` before a position; `hold`, `exit`, `tighten` or `reprofile` once it holds one. Anything outside that closed form (an unknown field, a size out of range) does nothing.
+- An `enter` is clamped by your strategy, and every cut is named in the run file; the order fills on the paper book after the strategy's latency, and is refused if the price ran past the slippage tolerance in between. Fills and refusals reach the agent as notes on its next message.
+- With a position, the exits in your profile run on their own; the agent hears about them as events and can only lower the risk (exit, trim, tighten) or move along the profile's allowed edges. When the position closes, its session ends.
+- A reply that arrives after its candidate was dropped (it stopped matching, the agent skipped, the session ran out) is written down and never executed.
+- With `agent.respawnOnWake` in the strategy, a judgement call on a position whose session has already ended opens a short position session that answers once.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-what-each-session-shows-first.md

@@ -0,0 +1,31 @@
+---
+id: docs-autotrade-what-each-session-shows-first
+title: Autotrade (paper) › Stopping it › What each session shows first
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: What each session shows first
+anchor: what-each-session-shows-first
+url: https://dexterm.xyz/docs/autotrade#what-each-session-shows-first
+tags:
+  - docs
+  - autotrade
+  - each
+  - session
+  - shows
+  - first
+  - stopping
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+Before its first answer counts, a session's start event must list no tools and no MCP servers; otherwise the session ends. The run file also records how many plugins, agents and skills your Claude reports for the session: your own plugins and agents can still list as loaded, and with no tools they cannot act.
+
+Paper only. Not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-what-it-costs-claude-usage-per-session.md

@@ -0,0 +1,58 @@
+---
+id: docs-autotrade-what-it-costs-claude-usage-per-session
+title: Autotrade (paper) › What it costs (Claude usage per session)
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: What it costs (Claude usage per session)
+anchor: what-it-costs-claude-usage-per-session
+url: https://dexterm.xyz/docs/autotrade#what-it-costs-claude-usage-per-session
+tags:
+  - docs
+  - autotrade
+  - costs
+  - claude
+  - usage
+  - per
+  - session
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+A session costs Claude usage on your own account, counted from what `claude` reports (`total_cost_usd`; on a subscription that figure is notional, but it is what the runner's caps count). The screening itself uses no model at all: Claude is only called when a coin matches.
+
+**Measured on `sonnet`** (the presets' model) on 2026-10-21: a two-hour run of the `moonbag` preset on live data, with the strategy's own session limits and a $2.75 day cap in `runner.json`:
+
+| in that run | measured |
+|---|---|
+| coins that matched and got a session | 17 in two hours |
+| turns | 24: 16 skips, 5 waits, 1 entry and 2 answers about the position |
+| a first look at a coin (one turn) | $0.006 to $0.010 |
+| a coin watched for a few updates, then skipped (2 to 3 turns) | $0.012 to $0.018 |
+| the one full loop: entry, a cost-recovery event, the close (3 turns) | $0.017 |
+| **the whole run** | **$0.17**, well under its cap |
+
+Replies took 2.6 to 8.8 seconds (median 5.3), and the first message was about 1.1 KB. The run file of that run verifies with `dexterm autotrade audit --verify`.
+
+How much a run costs depends mostly on how many coins match your entry rules and how long each one is watched: every update your agent reads is a turn, and a held position adds a turn for each event. Your caps bound it either way: $0.50 per session and $10 a day from the strategy, and the day caps and usage guard in `runner.json`.
+
+**Measured on `haiku`** (`--model haiku`), on one recorded coin replayed at a 1.5-second pace with the `swing` preset and its session budget cut to $0.05:
+
+| session | what happened | turns | cost |
+|---|---|---|---|
+| 1 | full picture → wait, update → skip | 2 | $0.0009 |
+| 2 | full picture → wait, two updates → skip | 3 | $0.0012 |
+| 3 | full picture → updates → enter (clamped to $80), two take-profit events → hold, trail exit → acknowledged, session ended | 7 | $0.0023 |
+
+Three sessions, 12 turns, **$0.0044 in all**; on haiku a full candidate → position → close loop was **$0.0023**. Replies took 1.3 to 4.9 seconds (median 2.8).
+
+The run file has each session's cost, and `runner-status.json` today's total.
+
+Paper only. Not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-what-it-is-paper-self-directed.md

@@ -0,0 +1,43 @@
+---
+id: docs-autotrade-what-it-is-paper-self-directed
+title: Autotrade (paper) › What it is (paper, self-directed)
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: What it is (paper, self-directed)
+anchor: what-it-is-paper-self-directed
+url: https://dexterm.xyz/docs/autotrade#what-it-is-paper-self-directed
+tags:
+  - docs
+  - autotrade
+  - paper
+  - self-directed
+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/autotrade.md
+date: 2026-10-16
+---
+
+Autotrade (paper) is a strategy file plus an engine that replays it. You write the rules: which coins count as candidates, how a position is sized, how it is exited, and how much loss is allowed. The engine applies exactly those rules, and every size is clamped by them. It runs on **paper** by default: there is no key, wallet or signer anywhere in a strategy, and a paper run never signs or sends anything. A strategy that says `"mode": "live"` validates with a warning and runs only with `dexterm autotrade run --live`, through the live signer (https://dexterm.xyz/docs/live-trading) and its caps (experimental, can lose all the funds in the trading wallet).
+
+It is self-directed: your strategies, on your machine, with your own recorded history. Nobody runs a strategy for you, and a preset is an example, not a recommendation.
+
+What ships today, covered below:
+
+- Strategies and presets (https://dexterm.xyz/docs/autotrade#strategies-and-presets): presets, your own strategy files, validation and the change journal, on the command line or on the `Q` screen (https://dexterm.xyz/docs/autotrade#on-the-q-screen).
+- Backtests and their limits (https://dexterm.xyz/docs/autotrade#backtests-and-their-limits): replays on recorded history, the held-out check, and what the data cannot tell you.
+- The runner and candidate sessions (https://dexterm.xyz/docs/autotrade#the-runner-and-candidate-sessions): `dexterm autotrade run --paper`, your own Claude working each candidate the screener finds, every size clamped by your strategy.
+- Exits and wakes (https://dexterm.xyz/docs/autotrade#exits-and-wakes): the exits that run on their own, the judgement calls your agent is woken for, and what it can and cannot do with them.
+- Change a strategy by chat (https://dexterm.xyz/docs/autotrade#change-a-strategy-by-chat): the analyst proposes, you see the diff and apply it with a key (a less-safe change needs a second key).
+- Running it all day (https://dexterm.xyz/docs/autotrade#running-it-all-day): how long a run lasts, which Claude account it uses, the day caps and the usage guard.
+- Stopping it (https://dexterm.xyz/docs/autotrade#stopping-it): a soft stop, a flatten and the panic switch, the heartbeat, and checking the record of a run.
+- What it costs (https://dexterm.xyz/docs/autotrade#what-it-costs-claude-usage-per-session): the Claude usage of a session, measured.
+- What it will not do (https://dexterm.xyz/docs/autotrade#what-it-will-not-do): live money, copy-trading automation, managing anyone else's money.
+
+On your phone: your own Telegram bot (https://dexterm.xyz/docs/telegram) sends the entries, exits, PnL cards and halts, takes `/pause` and `/kill`, and can make every entry wait for your tap (`entry.decide: "agent+approve"`).
+
+Still to come, documented here when it lands: a background service that keeps the runner going without a terminal, and the runner filling through the paper desk (https://dexterm.xyz/docs/autotrade#exits-and-wakes) with the exit monitor as its own process.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-what-it-will-not-do.md

@@ -0,0 +1,31 @@
+---
+id: docs-autotrade-what-it-will-not-do
+title: Autotrade (paper) › What it will not do
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: What it will not do
+anchor: what-it-will-not-do
+url: https://dexterm.xyz/docs/autotrade#what-it-will-not-do
+tags:
+  - docs
+  - autotrade
+  - will
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+- **Live money.** A run never signs and never sends a transaction: `--live` and a strategy in live mode are refused, and the runner holds no key. Live trading happens in a Telegram trading bot of your choice, outside dexterm (see Live trading (https://dexterm.xyz/docs/live-trading)).
+- **Copy-trading automation.** It does not copy anyone's trades.
+- **Managing anyone else's money.** It runs your strategies on your machine, with your own Claude login and your own paper book. Nobody runs a strategy for you: there are no hosted runners, no pooled accounts, no fee on its trades and no strategy marketplace.
+- **Decide outside your rules.** Your agent chooses only inside the bounds you wrote. It cannot raise a size, block an exit, lift a stop or apply a strategy change; you apply a change with a key.
+- **Promise results.** Presets are examples, and every backtest prints the limits of its data.
+
+Paper only. Not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-which-account-day-caps-and-the-usage-guard.md

@@ -0,0 +1,44 @@
+---
+id: docs-autotrade-which-account-day-caps-and-the-usage-guard
+title: Autotrade (paper) › Running it all day › Which account, day caps and the usage guard
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Which account, day caps and the usage guard
+anchor: which-account-day-caps-and-the-usage-guard
+url: https://dexterm.xyz/docs/autotrade#which-account-day-caps-and-the-usage-guard
+tags:
+  - docs
+  - autotrade
+  - which
+  - account
+  - day
+  - caps
+  - usage
+  - guard
+  - running
+  - all
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+These come from `~/.dexterm/autotrade/runner.json` (`dexterm-runner/1`), which stays on your machine and is never part of a strategy or a shared file. Without it the runner uses your default `claude` login and these defaults:
+
+```json
+{ "schema": "dexterm-runner/1",
+  "account": { "kind": "native" },
+  "caps": { "candidateSessionsPerDay": 48, "positionSessionsPerDay": 48, "modelUsdPerDay": 20, "turnsPerDay": 2000 },
+  "allowanceGuard": { "fiveHourMax": 0.6, "sevenDayMax": 0.8, "onLimit": "pause-until-reset" } }
+```
+
+- `account.kind` is `native` (your default login), `oauth-token` (a long-lived Claude login token from a helper command or a keychain item, handed to `claude` on a file descriptor; it is never on a command line, in a file or in the run file), `config-dir` (a separate Claude config folder with its own login) or `api-key` (a pay-as-you-go key from a helper or the keychain, in the session's environment only). The file names where to fetch a secret, never the secret.
+- The stricter of `runner.json` and the strategy applies.
+- A day is a real day by the clock (it starts at 00:00 UTC), also in a `--replay`: a fast replay of many recorded days still spends at most one day's caps per real day.
+- The usage guard reads the usage your Claude sessions report: above 60% of the five-hour or 80% of the seven-day allowance no new session starts, and after a usage limit the runner waits for the reset.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-your-strategies.md

@@ -0,0 +1,37 @@
+---
+id: docs-autotrade-your-strategies
+title: Autotrade (paper) › Strategies and presets › Your strategies
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Your strategies
+anchor: your-strategies
+url: https://dexterm.xyz/docs/autotrade#your-strategies
+tags:
+  - docs
+  - autotrade
+  - strategies
+  - presets
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+Your strategies live in `~/.dexterm/strategies/<id>.json` (or `$DEXTERM_HOME/strategies`), one file each. Every change is validated first (an invalid file is never written) and appended to `~/.dexterm/strategies/.journal.jsonl` with who made it, the change, and the content hash before and after. Removing a strategy moves it to `.removed/`, never deletes it.
+
+```
+dexterm autotrade list                          # your strategies and the presets: version, hash, mode, last backtest
+dexterm autotrade new my-swing --from swing     # copy a preset to edit
+dexterm autotrade validate my-swing             # every problem, with its path
+dexterm autotrade import ./shared.json          # store a strategy file (always as paper)
+dexterm autotrade journal my-swing              # the change history
+dexterm autotrade remove my-swing
+```
+
+A file of yours with a preset's id is used instead of that preset. Importing always sets the mode to paper, whatever the file says.

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

@@ -0,0 +1,22 @@
+---
+id: docs-autotrade
+title: Autotrade (paper)
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+url: https://dexterm.xyz/docs/autotrade
+tags:
+  - docs
+  - autotrade
+  - paper
+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/autotrade.md
+date: 2026-10-16
+---
+
+Strategies you write or copy from presets, validated in one file, and backtests on your own recorded history with a held-out check. Paper only, self-directed, not financial advice.

package/dist/packages/mcp/assets/kb/docs/docs-beginners-before-any-experimental-trading.md

@@ -28,6 +28,6 @@ sources:
 date: 2026-10-16
 ---
 
-Stop here until you are comfortable reading the app. Trading is experimental and has known bugs. It begins in PAPER simulation, which uses pretend funds. In the wallet path, Phantom shows and approves each wallet action, the keypress gate (a required physical key press) is on by default, and hard spending limits remain enforced in a separate signing process. No analyst, voice, or connected program can arm or sign.
+Stop here until you are comfortable reading the app. Trading in dexterm is PAPER simulation, which uses pretend funds, and the keypress gate (a required physical key press) is on by default. dexterm signs nothing and sends no transaction; live trading happens in a Telegram trading bot of your choice, outside dexterm. No analyst, voice, or connected program can trade.
 
-Never enter a seed phrase, private key, password, API key, or authentication token. Read the paper and wallet guide (https://dexterm.xyz/docs/paper-trading) before considering anything beyond the read-only walkthrough.
+Never enter a seed phrase, private key, password, API key, or authentication token. Read the paper trading guide (https://dexterm.xyz/docs/paper-trading) and live trading (https://dexterm.xyz/docs/live-trading) before considering anything beyond the read-only walkthrough.

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

@@ -26,4 +26,4 @@ A no-jargon, ten-minute path from opening a terminal to safely reading your firs
 
 This guide is for you if you have never used a terminal. Your first win is simple: install dexterm, open one real coin in **read-only** mode (display information without changing anything or trading), understand the safety and holder panels, save the result, and quit. It is **not** a trade and it does not require a wallet.
 
-> warn: Never paste a seed phrase, private key, password, API key, login token, or authentication token into a terminal, dexterm, a chat, a command, a URL, or a log. dexterm never needs your wallet keys and never holds them. The experimental trading path asks **Phantom** to approve each wallet action. If anything claiming to be dexterm asks for a secret, stop.
+> warn: Never paste a seed phrase, private key, password, API key, login token, or authentication token into a terminal, dexterm, a chat, a command, a URL, or a log. dexterm never needs your wallet keys and never holds them: it has no trading wallet and signs nothing. If anything claiming to be dexterm asks for a secret, stop.

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

@@ -0,0 +1,30 @@
+---
+id: docs-configuration-chart-markers
+title: Configuration and files on disk › Chart markers
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Chart markers
+anchor: chart-markers
+url: https://dexterm.xyz/docs/configuration#chart-markers
+tags:
+  - docs
+  - configuration
+  - chart
+  - markers
+  - 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 mark your own fills: the terminal token chart and the popup chart (https://dexterm.xyz/docs/popup-chart#buy-and-sell-markers). Every fill of the coin in the paper ledger and the live ledger is a `B` or `S` at its time and price, hollow `△ ▽` for PAPER and solid `▲ ▼` for live, so it reads with `NO_COLOR` too. A dashed `avg` line marks the average entry while a position is open. Markers are on by default; the popup's **MARKERS** control (or `k` in the popup) turns them off and on, and saves `"display": { "chartMarkers": "off" }` (or `"on"`; absent means `on`) through the journal, so `ctrl+z` undoes it. `dexterm display markers [on|off]` shows or sets it from the command line. Display only: nothing that trades reads it.
+
+- The terminal chart puts the glyph and letter on the fill's candle (`△B`, `▽S`; a count when one candle holds several fills), labels the newest marker with its price or market cap, and prints a one-line legend with how many fills are off the chart.
+- When the agent HUD or the brain view is up, the brain view's candle trace shows a `B` or `S` cell on each fill's candle, and the agent's PAPER position card marks its fills under its PnL trace.

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 and ticket read entry and mark as market cap (`entry MC $4.7k`) when the price display mode (https://dexterm.xyz/docs/configuration#price-display-mode) is market cap (the default) and the supply is known.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-environment-variables.md

@@ -33,7 +33,10 @@ 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_ANALYST_ENGINE` | `auto` (default) · `claude` · `codex` · `ollama`: which engine runs the analyst (since 0.1.5; `ollama` = a local model (https://dexterm.xyz/docs/ollama); also `--analyst-engine` and `analyst.engine` in `config.json`) |
+| `DEXTERM_AI_PROVIDER` | `auto` · `claude` · `codex` · `ollama`: the engine for every surface, over `~/.dexterm/ai.json` (see local model (https://dexterm.xyz/docs/ollama#pick-the-engine-globally-or-per-surface)) |
+| `DEXTERM_OLLAMA_HOST` · `DEXTERM_OLLAMA_MODEL` | the Ollama host (default `http://127.0.0.1:11434`; another machine is warned about) and the local model |
+| `DEXTERM_AI_RESTRICTIONS` | `observe` · `propose` · `paper` · `full`: can only LOWER the local engine's profile for this run |
 | `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 |

package/dist/packages/mcp/assets/kb/docs/docs-configuration-files-on-disk.md

@@ -35,6 +35,7 @@ date: 2026-10-16
 | `~/.dexterm/piper/` · `~/.dexterm/models/` | the neural voice: a private Python environment with Piper (macOS, written by `dexterm voice setup`), and the downloaded voice models (`en_GB-alan-medium`, whisper `base.en`) | optional; `dexterm voice uninstall` removes the runtime, `--purge-model` the Piper voice too. See voice (https://dexterm.xyz/docs/voice#the-voice-neural-by-default) |
 | `~/.dexterm/exports/` | PNG and text files from `E` (export a view) and `H` (PnL cards (https://dexterm.xyz/docs/paper-trading#pnl-cards)) | directory 700, files 600; local only, nothing is uploaded |
 | `~/.dexterm/spectator.json` | the spectator stream (https://dexterm.xyz/docs/spectator#2-the-read-only-stream-spectate)'s loopback port and per-session token, while `dexterm agent serve --spectate` runs | mode 600; never printed or passed as an argument |
+| `~/.dexterm/wallet-link.json` · `~/.dexterm/trading.panic` | a linked wallet's **public key** (from `dexterm wallet link`; never a private key), and the kill switch while `dexterm wallet panic` is engaged | optional; dexterm holds no key and has no trading wallet |
 | `~/.local/bin/dexterm` | the launcher `install.sh` writes | user-level |
 | `packages/popup/shell/wry/target/release/dexterm-shell-wry` | the native chart window, if built | `DEXTERM_POPUP_SHELL` points elsewhere |
 

package/dist/packages/mcp/assets/kb/docs/docs-configuration-headless-recorder-dexterm-record.md

@@ -36,9 +36,11 @@ $ dexterm record status                   # db size, snapshots, outcomes, today'
 $ dexterm record install --dry-run        # print the macOS LaunchAgent it would write; writes nothing
 $ dexterm record install --load           # write it to ~/Library/LaunchAgents (no sudo) and load it
 $ dexterm record uninstall --unload       # stop and remove it
+$ dexterm record run --focus-ticks --retention-mb 3000   # also sample focus coins every 5-10 s; evict old history at 3 GB
 ```
 
 - **Nothing turns itself on.** The collector runs only when you start it. `install` writes a user-level LaunchAgent and loads it only with `--load`. A LaunchAgent does not start before you log in.
 - **Same budgets as the app.** Every request goes through the data layer's rate limiter and health gate, and the outcome sweeps keep their own per-sweep and per-day caps. It never builds a signer, never trades and never prints an RPC key.
-- **A disk cap.** Above `--max-db-mb` (1024 by default) it pauses new observations, while labels and retention keep running, so the database cannot grow without bound.
+- **A disk cap.** Above `--max-db-mb` (1024 by default) it pauses new observations, while labels and retention keep running, so the database cannot grow without bound. With `--retention-mb N` it never pauses: once the used space reaches N MB the oldest history goes first (the newest hour is always kept). `--retention-days D` expires snapshot rows, outcome re-checks included, after D days instead of 90.
+- **Focus ticks for autotrade backtests** (`--focus-ticks`): a sample every 5 seconds for coins you hold on paper or have open and every 10 seconds for your watchlist and autotrade candidates, plus 1-minute candles built from those samples, in DexScreener batches of 30 with a daily call ceiling. What is kept and for how long is in recorded history (https://dexterm.xyz/docs/data-sources#recorded-history-and-retention). `install` writes these flags into the LaunchAgent only when you pass them.
 - **Recurring backtests.** 0.1.3 also ships the logic behind recurring skill backtests: a rolling held-out window, a frozen comparison set, and a gate that only *proposes* a tuning when it beats the noise. Nothing changes a skill on your machine. A tuning reaches you only through a normal release, with its measured numbers, including weak ones (see LARP detector (https://dexterm.xyz/docs/larp)).

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

@@ -25,11 +25,13 @@ sources:
 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.
+Memecoin traders think in market cap, so dexterm shows and talks about every coin in **market cap by default**: the screens, the CLI text, the chat assistant and the autotrade agents ("entered at $69.7K, exited at $264.9K, 3.8x"). USD price per token is the alternative. It is a display and wording setting only: the same data underneath, no extra requests, and nothing that trades (signer, caps, tickets, plans, the confirm gate, the autotrade engine) 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.
-- 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).
-- 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.
-- `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.
+- The setting is `"display": { "priceMode": "mcap" }` in `config.json` (`"price"` for USD price). `$` flips it on every screen and saves it through the journal, so `ctrl+z` undoes it; `/display mcap|price` in the chat box (also `/basis …`, `/set basis …`) does the same, and `/display` alone says which is on. `dexterm display [mcap|price]` shows or sets it from the command line. For one run: `--mcap` / `--price` on any command (`dexterm --price autotrade run …`), `--price-mode mcap|price`, or `DEXTERM_PRICE_BASIS=mcap|price`; nothing is saved. A workspace may carry `"priceMode"` and switches to it while active.
+- Market cap = price × a **known** supply: the market cap a source reports at the same tick (its market cap ÷ its price), the recorded FDV ÷ price, or pump.fun's fixed 1B for a pump.fun coin (the same rule as the PnL cards (https://dexterm.xyz/docs/paper-trading)). A supply is never guessed: without one the slot shows the price and says so (`ᵖ` after the number in a table, the panel caption counts them; `supply unknown · showing price` on a spotlight or header; `price; supply unknown` in a sentence).
+- Screens: the screener, watchlist and new pairs lead with **MCAP** (PRICE moves to MCAP's old column, every sort key works as before); the watchlist's entry becomes **ENTRY MC**; spotlights, the token header and the export report lead with the market cap and keep the price beside it. Position rows read **AVG MC** / **MCAP**, and STOP / TARGET, the trade tape, the ticket's price line and PAPER fill line (`@ $69.7K mcap (0.0000004 SOL)`), the trade history, the PnL chip, the brain view and the agent HUD's cards read market caps too. Profit and loss stay in USD (or SOL on the paper screen). The analyst's coin tables lead with MCAP.
+- 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.
+- The assistants speak the same basis, read at run time: the chat assistant's instructions and its live context (cap at entry, cap now, cap targets and stops, x-multiples), the autotrade candidate and position agents (their DOSSIER, ENGINE notes and EVENTs), and the MCP tools (https://dexterm.xyz/docs/analyst#mcp-tools): every price field has a market-cap twin (`mcap`, `entryMcap`, `lastMcap`, …; `null` when the supply is unknown) and the tool descriptions tell an external agent to talk in market cap unless the user chose price.
+- JSON keeps **both** numbers always: a price field is never removed or renamed, its cap twin sits beside it (the autotrade ledger's fills carry `price` and `mcap`, `avgPrice` and `avgMcap`). Only the human-facing text switches.
+- `config.json` moved to **v5** for this: a file saved with the old default (`priceMode: "price"`, written by every first save) is moved to market cap on load, with a backup kept as `config.json.bak-v4`; a `price` you chose yourself (`$`, `dexterm display price`, an approved proposal, all in the journal) is kept.

package/dist/packages/mcp/assets/kb/docs/docs-copy-trading-stage-2-the-one-key-mirror-ticket-a-proposal.md

@@ -53,4 +53,4 @@ $ dexterm follow mirror <addr> --propose      # write it as an INERT proposed or
 $ dexterm follow mirror <addr> --json         # machine-readable preview
 ```
 
-A refused mirror prints every failed check and exits non-zero. `--propose` writes a plan with status `proposed` and no mandate. The command has no arm, sign or execute path, so the plan can only be armed in the app through the keypress or Phantom gate. A replay test drives a followed wallet's buy through `--propose` and checks that the plan exists, is not armed and that no execute path was reached. This is the copy-trade mirror ticket of the 0.1.3 release (its first copy-trading step in the release notes): **a proposal only. Nothing arms or fires on its own.**
+A refused mirror prints every failed check and exits non-zero. `--propose` writes a plan with status `proposed` and no mandate. The command has no arm, sign or execute path, so the plan can only be armed in the app through the keypress gate. A replay test drives a followed wallet's buy through `--propose` and checks that the plan exists, is not armed and that no execute path was reached. This is the copy-trade mirror ticket of the 0.1.3 release (its first copy-trading step in the release notes): **a proposal only. Nothing arms or fires on its own.**

package/dist/packages/mcp/assets/kb/docs/docs-copy-trading-stage-3-capped-auto-mirror-default-off-less.md

@@ -32,7 +32,7 @@ sources:
 date: 2026-10-16
 ---
 
-`A` on a followed wallet raises the **AUTO-MIRROR** prompt. Turning it on is a held physical keypress, and it is refused unless the plan engine's own "this is less safe" popup (`G` on the `O` screen, keypress-only, 24 h expiry) is active. That one gesture drafts and arms a **copy mandate** in the plan engine, the signer trust domain: buy-only, `maxTier: hands-free`, with exactly the policy's caps, clamped to the engine's hard ceilings.
+`A` on a followed wallet raises the **AUTO-MIRROR** prompt. Turning it on is a held physical keypress, and it is refused unless the plan engine's own "this is less safe" popup (`G` on the `O` screen, keypress-only, 24 h expiry) is active. That one gesture drafts and arms a **copy mandate** in the plan engine: buy-only, `maxTier: hands-free`, with exactly the policy's caps, clamped to the engine's hard ceilings.
 
 Every later buy by that wallet then runs the Stage 2 checks and, if they pass, is proposed and armed automatically with the **weakest confirmation tier**. The engine therefore sizes it at **¼ of the per-trade cap** (the same rule a spoken confirmation gets) and re-checks the per-trade, per-coin, total and daily-loss caps, the allow-list and the panic state at arming and on every fill. On top, the policy keeps a per-wallet **daily cap** (the mandate's total), **max open mirrors**, a **cooldown** between mirrors, a **size factor** against the leader, and an **auto-disarm streak**: that many refused or failed mirrors in a row turn it off.