dexterm-cli 0.1.6 → 0.2.0

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,50 @@
+---
+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 you switch to **real** yourself, on your own terminal, runs the same way and also sends each trade to your own executor as a signal: see real mode (https://dexterm.xyz/docs/real-mode) (experimental; dexterm still holds no key and signs nothing). A strategy that says `"mode": "live"` (the removed local signer) validates with a warning and never runs.
+
+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.
+
+The rest of the automated trading suite has its own pages:
+
+- Build a strategy by chat (https://dexterm.xyz/docs/build-a-strategy-by-chat): the ladder from a chat proposal to a backtest, a paper forward test on live data, always on and, only if you choose, real, one rung at a time on evidence.
+- The always-on service (https://dexterm.xyz/docs/autotrade#the-always-on-service): your listed strategies keep running from login and come back after a crash.
+- Real mode (https://dexterm.xyz/docs/real-mode) (experimental): a strategy you arm on your own terminal sends each trade as a signal to your own executor; dexterm never holds a key.
+- Going real, safely (https://dexterm.xyz/docs/going-real): your own limits for every number, the executor kit, executor health and the digest.
+
+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: 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 (or script) of your choice, outside dexterm (see Live trading (https://dexterm.xyz/docs/live-trading)); in real mode (https://dexterm.xyz/docs/real-mode) dexterm sends that executor a signal for each trade and it decides.
+- **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-build-a-strategy-by-chat-1-ask-for-a-strategy.md

@@ -0,0 +1,27 @@
+---
+id: docs-build-a-strategy-by-chat-1-ask-for-a-strategy
+title: Build a strategy by chat › 1. Ask for a strategy
+kind: docs
+page: build-a-strategy-by-chat
+page_title: Build a strategy by chat
+heading: 1. Ask for a strategy
+anchor: 1-ask-for-a-strategy
+url: https://dexterm.xyz/docs/build-a-strategy-by-chat#1-ask-for-a-strategy
+tags:
+  - docs
+  - build-a-strategy-by-chat
+  - ask
+  - strategy
+  - build
+  - chat
+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/build-a-strategy-by-chat.md
+date: 2026-10-16
+---
+
+Open the analyst and say what you want, for example: "build me a strategy that buys young pairs on a 5-minute push, takes the cost back at 2x and lets the rest ride". The analyst works only through typed tools: it reads the presets, then **proposes** a new strategy (a copy of a preset with its changes) and any edits after that. Each proposal arrives on the `Q` screen as a card with the fields that change, the validation result and TIGHTER, NEUTRAL or LOOSER; `o` opens it, `y` applies it (a looser edit needs a second `y`), `n` dismisses it. Nothing exists until you apply it, and a new strategy always starts on paper. Your mode, bankroll, model budget and exit-liquidity floor stay yours: the analyst cannot change them. See changing a strategy by chat (https://dexterm.xyz/docs/autotrade#change-a-strategy-by-chat).

package/dist/packages/mcp/assets/kb/docs/docs-build-a-strategy-by-chat-2-backtest-it-held-out-split.md

@@ -0,0 +1,31 @@
+---
+id: docs-build-a-strategy-by-chat-2-backtest-it-held-out-split
+title: Build a strategy by chat › 2. Backtest it (held-out split)
+kind: docs
+page: build-a-strategy-by-chat
+page_title: Build a strategy by chat
+heading: 2. Backtest it (held-out split)
+anchor: 2-backtest-it-held-out-split
+url: https://dexterm.xyz/docs/build-a-strategy-by-chat#2-backtest-it-held-out-split
+tags:
+  - docs
+  - build-a-strategy-by-chat
+  - backtest
+  - held-out
+  - split
+  - build
+  - strategy
+  - chat
+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/build-a-strategy-by-chat.md
+date: 2026-10-16
+---
+
+`dexterm autotrade backtest <id>` (or `b` on the `Q` screen's journey view, or asking the analyst, which calls `strategy_backtest`) runs the strategy on your recorded history, then runs it again on each half of a **held-out split**: the newest 30% of coins, which nothing was ever tuned on, against the rest. The result is recorded as the strategy's backtest evidence.
+
+The evidence rule is strict: gain wording is allowed only with **at least 20 trades in both halves and a held-out net above 0**. Below that the report says "too few trades to claim anything", and the analyst is told to quote the trade counts and nothing more. A backtest is modelled fills on recorded snapshots, not a prediction; its data limits (https://dexterm.xyz/docs/autotrade#backtests-and-their-limits) are printed with it.

package/dist/packages/mcp/assets/kb/docs/docs-build-a-strategy-by-chat-3-forward-test-it-on-live-data.md

@@ -0,0 +1,44 @@
+---
+id: docs-build-a-strategy-by-chat-3-forward-test-it-on-live-data
+title: Build a strategy by chat › 3. Forward-test it on live data (paper)
+kind: docs
+page: build-a-strategy-by-chat
+page_title: Build a strategy by chat
+heading: 3. Forward-test it on live data (paper)
+anchor: 3-forward-test-it-on-live-data-paper
+url: https://dexterm.xyz/docs/build-a-strategy-by-chat#3-forward-test-it-on-live-data-paper
+tags:
+  - docs
+  - build-a-strategy-by-chat
+  - forward-test
+  - live
+  - data
+  - paper
+  - build
+  - strategy
+  - chat
+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/build-a-strategy-by-chat.md
+date: 2026-10-16
+---
+
+A forward test runs the same version on the **live** tape, on paper, with its own bankroll and its own run file, for a window you choose:
+
+```
+dexterm autotrade forward start <id> --hours 24          # or --trades 30, or both (whichever comes first)
+dexterm autotrade forward status [<id>]
+dexterm autotrade forward stop <id>
+dexterm autotrade forward report <id> [--json]
+```
+
+- It starts in the background and runs next to the always-on service (it does not take the runner's lock). `--foreground` keeps it in your terminal; `--bankroll-usd N` sets its paper bankroll (default: the strategy's own).
+- The strategy is frozen at the version it started with. A forward test of a strategy in real mode runs its paper twin: it never sends a signal.
+- At the end of its window it sells everything at the next tick (so its numbers are closed numbers), writes its report and records the result. The panic switch stops it like any run.
+- The analyst can start and stop one too (`strategy_forward_start`, `strategy_forward_stop`), after a backtest, for at most 72 hours or 200 trades, with the strategy's own bankroll. On the `Q` screen's journey view, `F` starts a 24-hour test and `X` stops it.
+- Only a test that ran its **whole window on live data** counts as the forward-tested rung. A test stopped early, run on a replay (`--replay` is a smoke run) or whose process died is shown, never counted.
+- A strategy that needs a chat approval for every entry cannot be forward-tested: no tap reaches a forward test. Model sessions of an agent strategy run on your own engine within the strategy's budgets, as in any run.

package/dist/packages/mcp/assets/kb/docs/docs-build-a-strategy-by-chat-4-promote-it-to-always-on-paper.md

@@ -0,0 +1,36 @@
+---
+id: docs-build-a-strategy-by-chat-4-promote-it-to-always-on-paper
+title: Build a strategy by chat › 4. Promote it to always-on (paper)
+kind: docs
+page: build-a-strategy-by-chat
+page_title: Build a strategy by chat
+heading: 4. Promote it to always-on (paper)
+anchor: 4-promote-it-to-always-on-paper
+url: https://dexterm.xyz/docs/build-a-strategy-by-chat#4-promote-it-to-always-on-paper
+tags:
+  - docs
+  - build-a-strategy-by-chat
+  - promote
+  - always-on
+  - paper
+  - build
+  - strategy
+  - chat
+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/build-a-strategy-by-chat.md
+date: 2026-10-16
+---
+
+When the forward test is done, the analyst can **propose** the promotion (`strategy_promote_propose`) or you can ask for it yourself:
+
+```
+dexterm autotrade promote <id> --to always-on
+dexterm autotrade promote list | show <pp-id> | apply <pp-id> | dismiss <pp-id>
+```
+
+Every promotion shows an evidence card first: the ladder, the backtest, the forward test and the comparison. Applying it needs your `y` on your own terminal (a pipe, a flag or an agent cannot give it), or `A` then `y` on the `Q` screen's journey view. The strategy then joins `autotrade.json` as a paper member, next to your other entries, and the always-on service runs it from its next start (`dexterm autotrade service status`).

package/dist/packages/mcp/assets/kb/docs/docs-build-a-strategy-by-chat-5-real-only-if-you-choose.md

@@ -0,0 +1,36 @@
+---
+id: docs-build-a-strategy-by-chat-5-real-only-if-you-choose
+title: Build a strategy by chat › 5. Real, only if you choose
+kind: docs
+page: build-a-strategy-by-chat
+page_title: Build a strategy by chat
+heading: 5. Real, only if you choose
+anchor: 5-real-only-if-you-choose
+url: https://dexterm.xyz/docs/build-a-strategy-by-chat#5-real-only-if-you-choose
+tags:
+  - docs
+  - build-a-strategy-by-chat
+  - real
+  - only
+  - choose
+  - build
+  - strategy
+  - chat
+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/build-a-strategy-by-chat.md
+date: 2026-10-16
+---
+
+Real mode sends each of the strategy's trades as a LIVE TRADE FIRE signal to your own executor; dexterm still holds no key and signs nothing. On this ladder it is the last rung and it is entirely yours:
+
+1. Set your own limits: `dexterm autotrade limits set perTradeSol=X dailySol=Y buysPerDay=N maxOpenPositions=N` and any of the others (Going real, safely (https://dexterm.xyz/docs/going-real#your-limits)); `signal caps set` sets the same four. A promotion to real refuses until you have.
+2. Set up a channel your executor reads (`dexterm autotrade signal channels ...`).
+3. Have the evidence: a completed forward test of these exact rules with at least 10 closed paper trades (your limit `minForwardTrades`) and a backtest on record. Below that the promotion refuses and says what is missing.
+4. `dexterm autotrade promote <id> --to real` (or `promote apply <pp-id>` for one the analyst proposed) hands over to `dexterm autotrade signal arm <id>`: the evidence panel, now with the journey line and the held-out verdict, then a typed phrase with a one-time code.
+
+The analyst can propose real (never below the evidence floor), never apply it, set a cap, choose a bankroll, lower the floor or arm anything. Arming directly with `signal arm` when a rung is missing, or below the evidence floor, refuses unless you type the OVERRIDE phrase it shows on your own terminal; the override is journaled. A real strategy runs in the foreground with `dexterm autotrade run <id> --real`; in 0.2.0 the always-on service runs paper strategies only, so stop the service while a real run is on (one runner per computer). See real mode (https://dexterm.xyz/docs/real-mode).