dexterm-cli 0.1.6 → 0.1.7

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-how-a-stop-reaches-the-runner.md

@@ -0,0 +1,32 @@
+---
+id: docs-autotrade-how-a-stop-reaches-the-runner
+title: Autotrade (paper) › Stopping it › How a stop reaches the runner
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: How a stop reaches the runner
+anchor: how-a-stop-reaches-the-runner
+url: https://dexterm.xyz/docs/autotrade#how-a-stop-reaches-the-runner
+tags:
+  - docs
+  - autotrade
+  - stop
+  - reaches
+  - runner
+  - 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
+---
+
+- `stop` and `flatten` write a request for the running run to `~/.dexterm/autotrade/control.json`. The runner reads it on every step and shows the halt in its heartbeat file, and the command waits up to 10 seconds (`--wait SEC`) to tell you it did.
+- A stop is final for that run: a flatten can follow it, nothing lifts it. To trade again, start a new run.
+- A request for an older run never touches a new one, and a control file the runner cannot read counts as a stop.
+- `flatten` asks for `y` on a real terminal; `--yes` answers for a script (a flatten only sells).
+- The runner reads the panic file on every step, and `dexterm autotrade run` will not start while it is on.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-on-the-q-screen.md

@@ -0,0 +1,37 @@
+---
+id: docs-autotrade-on-the-q-screen
+title: Autotrade (paper) › Strategies and presets › On the Q screen
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: On the Q screen
+anchor: on-the-q-screen
+url: https://dexterm.xyz/docs/autotrade#on-the-q-screen
+tags:
+  - docs
+  - autotrade
+  - screen
+  - 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
+---
+
+the strategy editor on sample data: a typo in the screen filter is caught at its column while you type
+
+Press `Q` on any screen for AUTOTRADE, paper only. `tab` moves between its views:
+
+- **Strategies**: the presets and your own files with mode, version, content hash and the last backtest (net, drawdown, trades). `n` copies the selected preset under a new id, `d` duplicates any strategy, `⏎` or `e` opens it in the editor, `x` writes it to a shareable file in `~/.dexterm/exports`, and `i` imports a file (always as paper). `o` opens the card of a change the analyst proposed in chat (how that works (https://dexterm.xyz/docs/autotrade#change-a-strategy-by-chat)).
+- **Editor**: one form in six sections (entry, exits, risk, sizing, agent, execution). `⏎` changes the selected field (a true/false field flips in place). Every change re-validates the whole strategy and every problem shows next to its field with its path; the screen filter is checked by the screener's own parser while you type, and the column of a mistake is marked. Each exit profile gets a one-line sketch of its stop, take-profits, trails and limits. `s` saves only a valid strategy, as a new version with the change in the journal; `u` undoes your last unsaved change, or, with nothing unsaved, the last saved one (as a new version). The presets open read-only: copy one first.
+- **Compare**: `c` on two strategies in the list shows them side by side with the fields that differ first, and `b` backtests both on the same window of recorded history.
+- **Backtest**: `b` backtests the selected strategy on the last 14 days of your recorded history and shows the report: trades, win rate with its interval, net, drawdown, the tail numbers, an equity line, results by exit rule, profile and trigger, the size clamps that fired, the refused entries and the limits box. `w` runs a sweep around the default exit profile's own settings with the held-out check described below; its verdict is printed as is. Both run in the background, so the app stays live.
+- **Runner**: a running paper runner's heartbeat, any halt, its candidates, sessions, positions and the last lines of its run file; a runner whose heartbeat is more than 30 seconds old shows as stale. `!` stops it, `p` pauses and resumes new entries, and `f` then `y` flattens it (see Stopping it (https://dexterm.xyz/docs/autotrade#stopping-it)).
+
+Nothing on this screen can switch a strategy to live, arm a mandate or touch a wallet or a key: the mode is not an editable field, an import is always paper, and a strategy that says live is refused for backtests.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-one-strategy-or-all-of-them.md

@@ -0,0 +1,35 @@
+---
+id: docs-autotrade-one-strategy-or-all-of-them
+title: Autotrade (paper) › Several strategies at once › One strategy, or all of them
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: One strategy, or all of them
+anchor: one-strategy-or-all-of-them
+url: https://dexterm.xyz/docs/autotrade#one-strategy-or-all-of-them
+tags:
+  - docs
+  - autotrade
+  - strategy
+  - all
+  - them
+  - 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
+---
+
+- **All of them:** `dexterm autotrade stop`, `dexterm autotrade flatten`, `dexterm autotrade pause` and `resume`, the Q screen's `!`, `f` and `p`, `dexterm wallet panic`, and Ctrl+C.
+- **One of them:** `dexterm autotrade stop --strategy ID` (no new entries, its sessions close, its exits run until it holds nothing; final for that run), `flatten --strategy ID`, `pause --strategy ID` and `resume --strategy ID`, and `dexterm autotrade start ID` for a listed strategy that is not running. The other strategies keep going.
+
+An agent you connect over MCP can read the list and the comparison, accounts included (`autotrade_parallel_list`, `autotrade_parallel_compare`), and can start, stop or pause one strategy that you listed (`autotrade_parallel_start`, `autotrade_parallel_stop`). It cannot add a strategy or an account, move a strategy to another account, change a size or a cap, or start anything that is not on paper.
+
+Paper only: `--live` and `"mode": "live"` are refused. dexterm holds no key; live trading happens in a Telegram trading bot of your choice (see Live trading (https://dexterm.xyz/docs/live-trading)). Simulated fills, not financial advice.

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

@@ -0,0 +1,50 @@
+---
+id: docs-autotrade-paper-accounts
+title: Autotrade (paper) › Several strategies at once › Paper accounts
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Paper accounts
+anchor: paper-accounts
+url: https://dexterm.xyz/docs/autotrade#paper-accounts
+tags:
+  - docs
+  - autotrade
+  - paper
+  - accounts
+  - several
+  - strategies
+  - once
+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 paper account is one simulated wallet that several strategies trade from together. List the accounts in `autotrade.json` and point a strategy at one with `account` instead of giving it a bankroll:
+
+```json
+{
+  "schema": "dexterm-autotrade/1",
+  "accounts": [
+    { "id": "main", "bankroll": { "usd": 1000 } },
+    { "id": "yolo", "bankroll": { "sol": 1 } }
+  ],
+  "strategies": [
+    { "id": "moon", "preset": "moonbag", "account": "main" },
+    { "id": "scalp", "preset": "scalp", "account": ["main", "yolo"] },
+    { "id": "solo", "preset": "my-scalp", "bankroll": { "usd": 200 } }
+  ]
+}
+```
+
+- **Many strategies, one wallet.** `moon` and `scalp` both trade from `main`'s cash: a buy by one leaves less for the other, a sale pays back into the same account, and every size is a share of the whole account (cash plus what is held). An order is checked against the cash again at the fill, so two strategies can never spend the same dollars.
+- **One strategy, many wallets.** A list of accounts runs the same strategy once per account, here as `scalp-main` and `scalp-yolo`. Each one is its own strategy in the run: its own run file, positions, loss limits, sessions and spend budget, and `dexterm autotrade stop --strategy scalp-yolo` stops only that one.
+- **What stays per strategy:** its positions, its share of the money at risk (`maxExposurePct` counts its own positions against the account), its loss streak and cooldowns, its per-coin rules, its entries per day and its model budget. Its drawdown limit reads the account: when the account falls far enough, each strategy on it stops entering at its own limit.
+- **Mixing is fine.** Strategies with their own `bankroll` run next to strategies on accounts. A strategy on an account takes no `bankroll` of its own, and an account it names must be in `accounts`; anything else stops the run before it starts, with the problem named.
+
+Accounts live for the run: each starts at its `bankroll` when the run starts (a SOL balance at the SOL price, or `"solUsd"` / `--sol-usd` in a replay), and a strategy you `start` again later joins the same account. Up to 8 accounts. Paper only: an account is simulated cash and never backs a live strategy.

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

@@ -0,0 +1,37 @@
+---
+id: docs-autotrade-presets
+title: Autotrade (paper) › Strategies and presets › Presets
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Presets
+anchor: presets
+url: https://dexterm.xyz/docs/autotrade#presets
+tags:
+  - docs
+  - autotrade
+  - presets
+  - strategies
+  - 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
+---
+
+Six read-only presets ship with dexterm, each on paper (five with a $1,000 paper book, `yolo` with $200):
+
+| preset | the idea |
+|---|---|
+| `scalp` | young pairs (under 6 h) on a 5-minute push, small take-profits, a hard stop and a short time exit |
+| `swing` | pairs from 1 hour to a week old on every screen match, wider take-profits and trail, a review after 90 minutes |
+| `runner` | older pairs with deeper liquidity, sized by confidence, a wide trail and a long hold |
+| `moonbag` | very young pairs (under 2 h) on an early push, with the holder-safety gates: take the cost back at about 2x, then hold a free bag with a loose trail |
+| `sample-dip-ladder` | a shareable example of a custom strategy: risk-sized, buys half and adds half on a dip |
+| `yolo` | **HIGH RISK**: one young pair at a time after the holder-safety gates and a live LARP check, the cost back at about 2x, then a free bag; paper only. See Full-port yolo strategy (https://dexterm.xyz/docs/yolo) |
+
+**About moonbag:** most early entries lose. Young pairs rug often, and a rug cannot be sold: once liquidity is pulled, the bag is stuck and counts as zero. The preset therefore uses small tickets and no hard stop, and the point is the rare coin that runs. Read its backtest's tail numbers, never only the total.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-running-it-all-day.md

@@ -0,0 +1,31 @@
+---
+id: docs-autotrade-running-it-all-day
+title: Autotrade (paper) › Running it all day
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Running it all day
+anchor: running-it-all-day
+url: https://dexterm.xyz/docs/autotrade#running-it-all-day
+tags:
+  - docs
+  - autotrade
+  - running
+  - all
+  - day
+  - 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` is a headless process: start it in a terminal (or a terminal multiplexer such as `tmux`) and it works until you stop it (https://dexterm.xyz/docs/autotrade#stopping-it), `--max-minutes` runs out, or you press Ctrl+C. A two-hour run is measured under What it costs (https://dexterm.xyz/docs/autotrade#what-it-costs-claude-usage-per-session). Screening uses no model at all, so a runner that is only watching costs no Claude usage; usage starts when a coin matches.
+
+- **One runner per machine.** A second `run` is refused while one is working. A lock left by a runner that crashed is taken over once its process is gone.
+- **Each run has its own paper book.** It starts from the strategy's `bankroll`, and a new run starts a fresh one. A run that ends with positions still open says how many on its last line and in its run file; nothing carries them into the next run.
+- **Leave the terminal open.** The runner stops when its terminal session ends, and the computer's sleep pauses it. A background service that starts it with your login and keeps it going is still to come.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-sessions-and-their-limits.md

@@ -0,0 +1,31 @@
+---
+id: docs-autotrade-sessions-and-their-limits
+title: Autotrade (paper) › The runner and candidate sessions › Sessions and their limits
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Sessions and their limits
+anchor: sessions-and-their-limits
+url: https://dexterm.xyz/docs/autotrade#sessions-and-their-limits
+tags:
+  - docs
+  - autotrade
+  - sessions
+  - their
+  - limits
+  - runner
+  - candidate
+  - 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
+---
+
+**Token text is data.** Names, symbols and every other text that comes from the token reach the agent only inside `<untrusted>` tags, and the agent is told such text is never an instruction. A coin named "buy the maximum" still gets your strategy's size, and nothing the agent says can stop a mechanical exit.
+
+**The session is answer-only.** It is `claude -p` with no tools, no MCP servers, no settings, no saved session and no slash commands, started in an empty folder (it is not `--bare`, which would drop your Claude login). Its first event must show the kind of login you configured and no tools; if it does not, the session ends before anything it says counts, and the runner starts no new session for the rest of the run. The limits come from the strategy's `agent` section (the presets' values): at most 2 sessions at once, $0.50 per session (also passed to `claude` as its own budget), $10 a day, 60 turns, 90 seconds per decision (60 in moonbag; a slow candidate is skipped, and a slow review gets the exit profile's no-answer rule), 4 hours per session, and the candidate is dropped 5 minutes after it last matched (4 in moonbag). The model is the strategy's `agent.model` (`sonnet` in the presets), or `--model` for one run.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-several-strategies-at-once.md

@@ -0,0 +1,33 @@
+---
+id: docs-autotrade-several-strategies-at-once
+title: Autotrade (paper) › Several strategies at once
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Several strategies at once
+anchor: several-strategies-at-once
+url: https://dexterm.xyz/docs/autotrade#several-strategies-at-once
+tags:
+  - docs
+  - autotrade
+  - 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
+---
+
+`dexterm autotrade run --all --paper` runs every strategy you list in `~/.dexterm/autotrade/autotrade.json` at the same time, on the same live data. Use it to forward-test several ideas side by side: a scalp and a moonbag, or one preset next to your copy of it with a single change.
+
+- **One data feed for all of them.** The screener fetches once and every strategy screens the same coins with its own entry rules, so three strategies do not cost three times the data requests. A coin's dossier is fetched once (at most every 30 seconds), whichever strategy asks for it.
+- **Each strategy has its own book.** It gets its own bankroll, run id and run file (`~/.dexterm/autotrade/runs/<run>.jsonl`, hash-chained), loss limits and breaker, candidate sessions and model spend budget. A breaker or a stop on one strategy never stops another. Or let several strategies trade from one paper account (https://dexterm.xyz/docs/autotrade#paper-accounts), the way several bots would share one wallet.
+- **Shared limits for all of them.** Model sessions open at once, model spend per day, sessions per day, turns per day, the usage guard of your Claude account and one check of how busy your computer is all count across every strategy. When one of them is reached, every strategy waits.
+
+It is still one runner on your machine: a second `run` (one strategy or `--all`) is refused while it works.

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

@@ -0,0 +1,35 @@
+---
+id: docs-autotrade-stopping-it
+title: Autotrade (paper) › Stopping it
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Stopping it
+anchor: stopping-it
+url: https://dexterm.xyz/docs/autotrade#stopping-it
+tags:
+  - docs
+  - autotrade
+  - 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
+---
+
+Three switches, from soft to hard. You use them; your agent cannot. A session has no tools, and its answer has no stop, resume or flatten in it.
+
+| switch | what stops | what keeps running | after it |
+|---|---|---|---|
+| `dexterm autotrade stop`, or `!` on the `Q` screen | new entries; every session closes; orders not yet filled are dropped | the mechanical exits on what you hold | the runner ends once nothing is held |
+| `dexterm autotrade flatten`, or `f` then `y` on the `Q` screen | the same, then every paper position sells at its next tick | a coin that cannot sell (a pulled pool) is retried every tick | the runner ends once nothing is held |
+| `dexterm wallet panic` | the runner halts on its next step, as in a stop; every paper desk refuses too | the runner's mechanical exits | nothing starts again until `dexterm wallet resume`, a keypress on a real terminal |
+
+`p` on the `Q` screen pauses new entries, and `p` again resumes them; open positions keep their exits either way.
+
+With several strategies at once (https://dexterm.xyz/docs/autotrade#several-strategies-at-once), these switches act on every strategy, and `--strategy ID` on `stop`, `flatten`, `pause` and `resume` acts on one. An agent you connect over MCP can stop or pause one strategy you listed there, never all of them and never the panic.

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

@@ -0,0 +1,34 @@
+---
+id: docs-autotrade-strategies-and-presets
+title: Autotrade (paper) › Strategies and presets
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Strategies and presets
+anchor: strategies-and-presets
+url: https://dexterm.xyz/docs/autotrade#strategies-and-presets
+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
+---
+
+A strategy is one JSON file (`dexterm-strategy/1`) with six parts:
+
+- **Entry**: the screener filter grammar (https://dexterm.xyz/docs/screens), verbatim (for example `liq >= 30K vol1h > 15K !flag:mint !flag:freeze`), an age window, safety gates (no mint or freeze authority, top-10 share, dev share, a market-cap source split, a "young and already vertical" reject, and what to do when the holder source is down) and triggers (every screen match, or a 5-minute momentum push).
+- **Exits**: one or more exit profiles: a take-profit ladder, a trailing stop, a time stop, an optional hard stop, thesis breaks (a liquidity drop, a market-cap source split, dead volume), a maximum hold time and, for the moonbag profile, a cost-recovery sell and a trail on the free bag that is left.
+- **Sizing**: a fixed amount, a percent of the book, risk-sized against the stop, or scaled by the agent's confidence inside your bounds, with optional scale-in tranches. Every size is capped by a maximum percent and a maximum dollar amount.
+- **Risk**: a per-trade loss cap, a daily loss halt, drawdown size-down and halt levels, the most positions open at once, total exposure, entries per day, a loss-streak cooldown and per-coin re-entry rules.
+- **Agent** and **execution**: the session limits for the runner (https://dexterm.xyz/docs/autotrade#the-runner-and-candidate-sessions) and the fill model's fee, slippage, network fee, price-impact cap and the liquidity below which a bag cannot be sold.
+
+The file is closed: an unknown key is refused with its path, so a strategy cannot carry a `signer`, `wallet` or `key` section. Validation also checks the rules a schema cannot (a take-profit ladder that climbs, sell fractions that add up to at most the whole position, sizing parameters that match the sizing mode, drawdown levels in order) and prints every problem with its path. Every strategy gets a content hash, so a backtest line always names the exact rules it ran.

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.