dexterm-cli 0.1.3 → 0.1.4

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

@@ -0,0 +1,25 @@
+---
+id: docs-cli
+title: CLI flags and commands
+kind: docs
+page: cli
+page_title: CLI flags and commands
+url: https://dexterm.xyz/docs/cli
+tags:
+  - docs
+  - cli
+  - flags
+  - commands
+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/cli.md
+date: 2026-10-16
+---
+
+Every flag parseArgs accepts, the subcommands, the filter grammar, sort keys and presets.
+
+Generated from `packages/cli/src/main.ts` (`parseArgs`, the subcommand dispatch and `dexterm --help`), `scan/command.ts` (the `--scan-*` table), `screener/filter.ts`, `screener/sort.ts` and `screener/presets.ts` at commit `(generated from the app: see https://dexterm.xyz/docs/cli; app-help has the exact keys and commands)`. `npm run docs:check` fails if a flag here does not exist or an accepted flag is undocumented.

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

@@ -0,0 +1,45 @@
+---
+id: docs-configuration-environment-variables
+title: Configuration and files on disk › Environment variables
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Environment variables
+anchor: environment-variables
+url: https://dexterm.xyz/docs/configuration#environment-variables
+tags:
+  - docs
+  - configuration
+  - environment
+  - variables
+  - 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
+---
+
+| variable | effect |
+|---|---|
+| `DEXTERM_HOME` | the directory for `state.json`, `helius.key`, `popup.json`, `config.json`, workspaces, themes and packs (default `~/.dexterm`) |
+| `DEXTERM_DB_PATH` | set by the app for its analyst MCP child so it shares the same cache file; you normally use `--db` |
+| `DEXTERM_RPC_URL` · `DEXTERM_RPC_URLS` | read-only RPC endpoints (see above) |
+| `DEXTERM_CALM=1` | effects off (same as `--calm`) |
+| `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_POPUP_SHELL` | path to a prebuilt native chart window |
+| `DEXTERM_POPUP_HOTKEY` · `DEXTERM_POPUP_HOTKEY_CLOSE` | override the popup chords without a config file |
+| `DEXTERM_RECORDER=0` | history recorder off (same as `--no-recorder`; `off`, `false` and `no` work too) |
+| `DEXTERM_TRACE` | write first-frame and first-rows milestones to a file (boot measurements) |
+| `DEXTERM_VOICE_STT` · `DEXTERM_VOICE_TTS` | pick the voice (https://dexterm.xyz/docs/voice) engines: `auto` (default) · `apple` · `whisper` · `none`, and `auto` · `say` · `none` |
+| `DEXTERM_VOICE_RECORD=1` | keep the whisper path's temporary WAV instead of deleting it after transcription |
+| `DEXTERM_WHISPER_MODEL` · `DEXTERM_VOICE_HELPER_DIR` · `DEXTERM_SWIFTC` | the whisper model file (default `~/.dexterm/models/ggml-base.en.bin`), the compiled Apple Speech helper's cache dir (default `~/.dexterm/voice-helper`), the Swift compiler |
+| `DEXTERM_SCREEN_STATE` | set by the app for its MCP child (the current screen context); not for you |
+| `NO_COLOR` · `FORCE_COLOR` · `COLORTERM` · `TERM` | colour depth detection; `NO_COLOR` also implies calm |
+| `LANG` / `LC_ALL` | a non-UTF-8 locale switches the rain to hex glyphs (`--ascii-rain` forces it) |

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

@@ -0,0 +1,41 @@
+---
+id: docs-configuration-files-on-disk
+title: Configuration and files on disk › Files on disk
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Files on disk
+anchor: files-on-disk
+url: https://dexterm.xyz/docs/configuration#files-on-disk
+tags:
+  - docs
+  - configuration
+  - 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
+---
+
+| path | what | notes |
+|---|---|---|
+| `~/.local/share/dexterm/dexterm.db` | SQLite: the data cache, your watchlist and alerts, the feed snapshot, the request and credit meters, the PAPER wallet (balance, positions, trades), your KOL lists and mutes, and the history recorder (https://dexterm.xyz/docs/configuration#history-recorder)'s tables | `--db PATH` moves it, `--db :memory:` skips it. `$XDG_DATA_HOME/dexterm/dexterm.db` when set; `%APPDATA%\dexterm\dexterm.db` on Windows. |
+| `~/.dexterm/state.json` | how many times dexterm has booted (the first launch gets the full boot and the welcome card) | `DEXTERM_HOME` moves the directory |
+| `~/.dexterm/helius.key` | your optional free Helius key, mode 600 | read in code, URL built in memory, never printed. Optional. |
+| `~/.dexterm/popup.json` | chart popup hotkeys, docking, rain, fps cap | optional; see popup chart (https://dexterm.xyz/docs/popup-chart#config-dexterm-popup-json) |
+| `~/.dexterm/config.json` · `config.journal.jsonl` | the customization config (v4: theme overrides, keymap, rules, installed packs, widget consent, the price display mode (https://dexterm.xyz/docs/configuration#price-display-mode)) and its journal of applied changes with their inverses | machine-written, mode 600; `ctrl+z` in the app undoes the last change. Holds no secrets by construction: the schema has no key field, and an older config that carried one gets it moved out to `<name>.key`. See workspaces (https://dexterm.xyz/docs/configuration#workspaces), rules (https://dexterm.xyz/docs/configuration#rules-engine), packs (https://dexterm.xyz/docs/configuration#packs) |
+| `~/.dexterm/workspaces/<name>.json` · `themes/<name>.json` | your workspaces and themes, one file each | `dexterm workspace`, `dexterm theme` |
+| `~/.dexterm/packs/<name>@<version>/` · `allowed_signers` · `reviewed-packs.json` | installed packs (exactly the files their lock names), the publisher keys you pinned, pack hashes you marked reviewed | `dexterm pack` |
+| `~/.dexterm/voice-helper/` | the Apple Speech helper (`recognize.swift`, its compiled binary and a source hash), built once by `swiftc` on the first voice use | optional; see voice (https://dexterm.xyz/docs/voice). No audio or transcript is ever written here |
+| `~/.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 |
+| `~/.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 |
+
+Delete the first three and dexterm forgets everything.

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

@@ -0,0 +1,44 @@
+---
+id: docs-configuration-headless-recorder-dexterm-record
+title: Configuration and files on disk › History recorder › Headless recorder (dexterm record)
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Headless recorder (dexterm record)
+anchor: headless-recorder-dexterm-record
+url: https://dexterm.xyz/docs/configuration#headless-recorder-dexterm-record
+tags:
+  - docs
+  - configuration
+  - headless
+  - recorder
+  - dexterm
+  - record
+  - history
+  - 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
+---
+
+The recorder above only grows while the terminal is open. `dexterm record` is **opt-in**. It runs the same recorder jobs with no terminal UI: snapshots and feed membership, the new-pairs stream, the 1 h to 72 h outcome sweeps, labels and retention. Your local history keeps growing for backtests while dexterm is closed.
+
+```sh
+$ dexterm record run --once --verbose     # one observation pass + one maintenance pass, then exit
+$ dexterm record run                      # keep going: a feed refresh every 60 s (--interval S)
+$ dexterm record status                   # db size, snapshots, outcomes, today's sweep calls, LaunchAgent state
+$ 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
+```
+
+- **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.
+- **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-history-recorder.md

@@ -0,0 +1,33 @@
+---
+id: docs-configuration-history-recorder
+title: Configuration and files on disk › History recorder
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: History recorder
+anchor: history-recorder
+url: https://dexterm.xyz/docs/configuration#history-recorder
+tags:
+  - docs
+  - configuration
+  - history
+  - recorder
+  - 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
+---
+
+In live mode dexterm keeps a local history of what it saw, for the rug model and backtests on the roadmap (https://dexterm.xyz/roadmap/): a row per coin when its price, liquidity, holders or volume changed materially (plus an hourly anchor), which feeds listed it, and a code-only outcome label per anchor at 1 h, 2 h, 6 h, 24 h and 72 h (no model is involved). It lives in the same `--db` file; nothing is uploaded.
+
+- **Requests:** recording reuses data the screens already fetched. Outcome checks re-ask DexScreener about coins whose window is due, at the lowest priority inside the app's own limiter: at most 6 calls a minute and 1,500 a day, skipped while DexScreener is rate-limiting.
+- **When it runs:** the first maintenance pass (outcome check, labels, retention) runs 5 seconds after launch and then once a minute, and quitting labels whatever is due before the database closes. Until 2026-10-12 the first pass waited a full minute and nothing ran at quit, so two days of short runs on the development machine left 1,676 anchors and 0 outcomes; `dexterm recorder label` labels an older database's backlog in one go.
+- **Size:** measured at about 100 MB per 8-hour live day with the current rules. Raw JSON is dropped after 7 days, rows are thinned to one per coin per minute after 24 hours, and columns expire after 90 days; outcome labels are kept. `dexterm recorder stats` shows the size, `dexterm recorder prune` runs retention now.
+- **Off:** `--no-recorder` or `DEXTERM_RECORDER=0`. It never runs with `--fixtures`, `--replay` or `--db :memory:`.
+- **Export:** `dexterm recorder export` writes one record per anchor with its later outcomes (see the CLI reference (https://dexterm.xyz/docs/cli#subcommands)).

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

@@ -0,0 +1,38 @@
+---
+id: docs-configuration-packs
+title: Configuration and files on disk › Packs
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Packs
+anchor: packs
+url: https://dexterm.xyz/docs/configuration#packs
+tags:
+  - docs
+  - configuration
+  - packs
+  - 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
+---
+
+A pack is a directory you can share: `pack.json` (name, version, publisher, what it contains), then `workspaces/*.json`, `themes/*.json`, `rules/*.rules`, `keymap.json` and `widgets/<name>/` (see widgets (https://dexterm.xyz/docs/configuration#widgets)), plus a generated `pack.lock` (sha256 per file and a pack hash) and an optional `pack.lock.sig` from `ssh-keygen -Y sign` (no new dependency; the key everyone already has).
+
+```sh
+$ dexterm pack verify ./trenches                 # the install card: integrity, signature, trust, contents, refusals
+$ dexterm pack add ./trenches --accept-unsigned  # install into ~/.dexterm/packs/trenches@1.0.0
+$ dexterm pack export ./mine --name mine --workspace hud --theme amber --rules --keymap
+$ dexterm pack sign ./mine --key ~/.ssh/id_ed25519 ; dexterm pack trust alice "ssh-ed25519 AAAA…"
+```
+
+- **Trust tiers decide defaults, never powers.** `reviewed` (the pack hash is on the list dexterm ships or in your `reviewed-packs.json`) > `signed` (a publisher key you pinned with `dexterm pack trust`) > `unsigned` (needs `--accept-unsigned`: the risk card). Rules from a reviewed or signed pack load enabled; from an unsigned pack they load disabled and you enable each one on the rules screen (that makes your own copy). A pack keymap is shown and merged only by `dexterm pack keymap <name> --merge`, through the same reserved-key checks as your own. Widgets install disabled.
+- **A pack never runs code.** It is plain files; there is no entry script, no dependency, no network. Refused outright, not skipped: paths with `..` or an absolute root, symlinks anywhere, hidden files, `node_modules`, more than 200 files or 2 MB, a `__proto__` key in any JSON, a capability or enabled field on a widget, a rule that tries to arm or oversize, a keymap that rebinds a reserved key. The hash is pinned at install and re-checked on every load: a pack edited after install is skipped and reported, and a directory copied into `packs/` without a record is not an install.
+- **Export refuses secrets.** Anything in your exported files that looks like a base58 private key, a Helius token, a 32-byte hex string or a high-entropy blob stops the export before a file is written.
+- **Not built yet:** `pack add` from a git URL or a zip (install is from a directory you already have), and a shipped reviewed list (empty until a first-party pack is reviewed). The example pack is `packs/example-widgets` in the repo.

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

@@ -0,0 +1,35 @@
+---
+id: docs-configuration-price-display-mode
+title: Configuration and files on disk › Price display mode
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Price display mode
+anchor: price-display-mode
+url: https://dexterm.xyz/docs/configuration#price-display-mode
+tags:
+  - docs
+  - configuration
+  - price
+  - display
+  - mode
+  - 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
+---
+
+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.
+
+- `$` 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.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-push-alerts-and-dexterm-watch.md

@@ -0,0 +1,45 @@
+---
+id: docs-configuration-push-alerts-and-dexterm-watch
+title: Configuration and files on disk › Push alerts and dexterm watch
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Push alerts and dexterm watch
+anchor: push-alerts-and-dexterm-watch
+url: https://dexterm.xyz/docs/configuration#push-alerts-and-dexterm-watch
+tags:
+  - docs
+  - configuration
+  - push
+  - alerts
+  - dexterm
+  - watch
+  - 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
+---
+
+Rules (above) already alert inside the running terminal. To hear about a match when the terminal is closed, pick where alerts go and run your rules headless.
+
+```sh
+dexterm alerts status                 # which channels are on
+dexterm alerts set-telegram           # your own Telegram bot (token + chat id read from the environment or stdin, never argv)
+dexterm alerts set-discord            # your own Discord webhook URL
+dexterm alerts enable desktop         # a desktop notification (macOS, Linux)
+dexterm alerts test                   # send one test alert to every enabled channel
+dexterm watch                         # run your rules with no terminal UI and deliver alerts
+dexterm watch --once                  # one pass, then exit (good for cron)
+```
+
+- **Off by default.** Nothing is sent anywhere until you configure and enable a channel. `dexterm alerts disable` turns a channel off again.
+- **Your credentials, stored locally.** A Telegram bot token or a Discord webhook lives in your home folder with mode 0600 and is never logged or printed. dexterm ships no bot and no webhook of its own.
+- **Triggers are plain rules.** A price level, a holder-concentration change, a LARP grade change, or a new pair that matches a filter are all rule lines (see the rules section); the LARP grade is a numeric field, so "downgraded" is `when larp.delta < 0`.
+- **Proposals only.** A rule can raise an alert, open a ticket proposal or ask the analyst. There is no path from a rule, or from `dexterm watch`, to signing, arming or raising a cap.
+- **Untrusted text is cleaned.** Token names and symbols pass the prompt firewall before they reach any channel.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-rules-engine.md

@@ -0,0 +1,36 @@
+---
+id: docs-configuration-rules-engine
+title: Configuration and files on disk › Rules engine
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Rules engine
+anchor: rules-engine
+url: https://dexterm.xyz/docs/configuration#rules-engine
+tags:
+  - docs
+  - configuration
+  - rules
+  - engine
+  - 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
+---
+
+A rule is one line: `when <cond> [for <n> ticks | <n>s | <n>m] then <action>+ [cooldown <dur>] [max <n>/h] [scope screener | watchlist | newpairs | positions | mint:<addr>] [window <dur>] [name "<s>"]`. Conditions use the filter grammar (https://dexterm.xyz/docs/cli#filter-grammar)'s fields and tags with `and` / `or` / `not` and parentheses, plus two derived signals over a per-coin history the engine keeps itself: `<field>.velocity` (current ÷ the mean of the earlier samples in the window) and `<field>.delta` (current − oldest in the window); both are false until two earlier samples exist, so a rule never fires on a coin's first paint. Actions: `alert(level, "text")`, `ticket(buy | sell, size ≤ 50, sol | usd | pct)`, `ask(skill)`, `popup(chart | token | bubbles | narrative | plans | feeds)`, `tag("label")`, `sound(name)`, `watch`.
+
+```text
+vol5m.velocity > 3 and cluster < 20 and liq > 25K for 2 ticks then alert(up, "surge") ask(token-dossier) popup(chart) cooldown 15m max 6/h name "surge-clean"
+```
+
+- The open token's live holder and rug signals (https://dexterm.xyz/docs/screens#live-holder-and-rug-signals) are rule fields too: `top10`, `dev`, `bundled`, `snipers`, `fresh`, `cluster`, `lplocked`, `bonding`, `mintable`, `freezable`, with `.delta` and `.velocity` (`dexterm rules fields` lists them all).
+- The text is parsed, never evaluated as code. Every rule has a cooldown (default 10 m) and a max per hour (default 12, hard cap 120), so a bad rule is annoying, not dangerous.
+- Rules can **alert**, annotate your own watchlist (`tag`, `watch`), open the read-only windows and ring the bell, or **propose**. `ticket` and `ask` do not act: each fire becomes a proposal card on the rules screen (status proposal, your keypress required, armed by nobody); acting on it opens the PAPER ticket in its editing phase, where you size and confirm, or asks the analyst. Nothing a rule does reaches an order plan, a mandate, the signer or the gate, and a rule argument named like money (`arm`, `auto`, `confirm`, `execute`, `sign`, `send`) is refused at parse time, in text and in JSON.
+- `ctrl+r` opens the RULES screen: the list with enabled / last fired / source, `i` types a new rule with a live "would match N of M rows right now" dry-run, `tab` the proposals pane, `space` toggles, `d` removes. `dexterm rules list | add "<rule>" | remove | enable | disable <id> | check "<rule>" | dry-run "<rule>" | fields`. Rules live in `config.json`, every change through the journal.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-the-analyst-s-launch.md

@@ -0,0 +1,27 @@
+---
+id: docs-configuration-the-analyst-s-launch
+title: Configuration and files on disk › The analyst's launch
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: The analyst's launch
+anchor: the-analyst-s-launch
+url: https://dexterm.xyz/docs/configuration#the-analyst-s-launch
+tags:
+  - docs
+  - configuration
+  - analyst
+  - launch
+  - 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
+---
+
+For the record, the analyst is spawned as `claude -p` with `--output-format stream-json`, `--tools ''` (no built-in tools), `--strict-mcp-config` pointing at the dexterm server only, `--allowedTools mcp__dexterm__*`, `--permission-mode dontAsk`, `--setting-sources ''` (none of your Claude Code settings or other plugins), the dexterm plugin directory for the skills, the analyst system prompt appended, a JSON schema for structured skills, and `--disallowedTools` for the action tools in scan mode. It cannot read files, run commands or reach any other MCP server from inside dexterm.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-the-optional-free-rpc-key.md

@@ -0,0 +1,42 @@
+---
+id: docs-configuration-the-optional-free-rpc-key
+title: Configuration and files on disk › The optional free RPC key
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: The optional free RPC key
+anchor: the-optional-free-rpc-key
+url: https://dexterm.xyz/docs/configuration#the-optional-free-rpc-key
+tags:
+  - docs
+  - configuration
+  - optional
+  - free
+  - rpc
+  - key
+  - 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
+---
+
+Keyless, the holders panel shows the holder count and the top-10 share from Jupiter; the ranked top-20 list with owner wallets needs a free RPC key (a 2-minute signup with no card at Helius, Alchemy, QuickNode or Ankr). Configure one of:
+
+```sh
+$ mkdir -p ~/.dexterm && printf %s "<your-key>" > ~/.dexterm/helius.key && chmod 600 ~/.dexterm/helius.key
+```
+
+```sh any read-only RPC URL; the first wins, extras join the rotation pool
+$ export DEXTERM_RPC_URL="https://<provider>/<path>"
+$ export DEXTERM_RPC_URLS="https://rpc-a/...,https://rpc-b/..."
+```
+
+Resolution order: `DEXTERM_RPC_URL`, else `~/.dexterm/helius.key`, else the public RPC pool. All configured endpoints rotate by health score; a 429 pauses one endpoint (honouring `Retry-After`) and fails over to the next. Every URL in an error, a `--verbose` line or a `--record` file passes a redactor; a recording that still carries a key refuses to save. `dexterm doctor` reports the provider name only, never the key.
+
+> warn: never paste a key into a command line argument, a shell history, a chat or a repository. The file above is the only place dexterm reads it from.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-themes-and-keymaps.md

@@ -0,0 +1,29 @@
+---
+id: docs-configuration-themes-and-keymaps
+title: Configuration and files on disk › Themes and keymaps
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Themes and keymaps
+anchor: themes-and-keymaps
+url: https://dexterm.xyz/docs/configuration#themes-and-keymaps
+tags:
+  - docs
+  - configuration
+  - themes
+  - keymaps
+  - 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
+---
+
+`~/.dexterm/themes/<name>.json` is `{ "extends": "cyberspace", "tokens": { "accent": "#ffb02e", … } }`: a built-in base plus hex overrides. At load every value must be a hex colour, ramps exactly four, unknown tokens are refused, and two semantic checks protect you from a shared theme: a **contrast floor** (text on background, muted on panel, the up / down / warn colours) and an **up / down guard** (`up` must read green/cyan and `down` red/pink by hue, both must carry real colour — an HSL saturation floor — and they must sit a minimum perceptual distance apart, so neither an amber pair nor a near-grey pair can make a loss look like a gain). A theme that fails loads as `paper` with a toast naming the token. `config.theme.overrides` is the same for one-off tokens; `dexterm theme list | show | init <name> | check <name>`.
+
+`config.keymap` re-binds the app's actions: `"global": { "screen.watchlist": ["3", "W"] }` and `"screens": { "screener": { "preset.next": ["]"] } }`, chords as `"ctrl+w s"`. Refused by name, whatever the file says: assigning `ctrl+c`, `esc`, `enter`, `y` / `Y` or `!` to anything; changing the keys of quit, back, the alert confirm / dismiss, arm, panic or the gate; two actions on one key within one scope; a chord prefix bound on its own; more than four keys per action. Any error keeps the defaults (a half-applied keymap is worse than none) and names the path. `dexterm keymap [screen]` prints the effective keys with overrides marked `·`; the `?` overlay marks them the same way.

package/dist/packages/mcp/assets/kb/docs/docs-configuration-themes-and-look.md

@@ -0,0 +1,27 @@
+---
+id: docs-configuration-themes-and-look
+title: Configuration and files on disk › Themes and look
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Themes and look
+anchor: themes-and-look
+url: https://dexterm.xyz/docs/configuration#themes-and-look
+tags:
+  - docs
+  - configuration
+  - themes
+  - look
+  - 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
+---
+
+`--theme cyberspace|midnight|ember|paper` or `t` at runtime. `--intensity off|normal|fever`, `--fps N`, `--no-boot`, `--ascii-rain`, `--tz ZONE` for the header clock (default America/New_York; `local` for the machine zone). Details in the CLI reference (https://dexterm.xyz/docs/cli#flags). User themes join the `t` cycle: see themes and keymaps (https://dexterm.xyz/docs/configuration#themes-and-keymaps).

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

@@ -0,0 +1,31 @@
+---
+id: docs-configuration-widgets
+title: Configuration and files on disk › Widgets
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Widgets
+anchor: widgets
+url: https://dexterm.xyz/docs/configuration#widgets
+tags:
+  - docs
+  - configuration
+  - widgets
+  - 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
+---
+
+A pack widget is an html page the popup host serves in a loopback HUD window, the same window technology as the popup chart (https://dexterm.xyz/docs/popup-chart). It is the only way third-party UI gets into dexterm, and it is small on purpose: a widget can **receive and render**; it cannot fetch, import, run anything in the terminal process, or send anything but close / focus / drag.
+
+- `widgets/<name>/widget.json` declares pages and their topics, a subset of `rows · token · narrative · positions · alerts · theme`: the screener's public columns, the open coin, the narrative board, your positions (symbol, size, PnL), the alert log, the theme. Nothing in a view model names a key, a signer, a cap, a mandate or the gate; pair / source ids and provenance internals are not sent.
+- The window is two documents: the host's own wrapper page (it owns the connection to the terminal, the title strip and the close button) and, inside it, the pack page in a sandboxed frame. The pack page runs under a hash-only CSP: the html is served exactly as installed (nothing is substituted into it, there is no nonce), and every inline `<script>` and `<style>` block runs because its sha256 is in the header — only the text you read before enabling the widget. It has no network of its own at all (no fetch, no socket, no remote scripts, styles, images or fonts), no cookies or storage (an opaque origin), no inline handlers, no eval, no runtime script injection where the engine supports Trusted Types, and no way to navigate anywhere: a document may always navigate itself, which a sandbox alone cannot stop, so the wrapper's `frame-src` names the one document the frame may show and the engine refuses any other before a request exists — the wrapper then closes the widget and logs why. Verified in headless Chromium and WebKit. One kind of connection no content-security directive covers — a `<link rel=preconnect>` built at run time makes WebKit open a bare TCP connection to a host and port the page chose — so the SDK, which runs first in the frame, seals the DOM: the insertion methods, every HTML-parsing entry point (the static `Document.parseHTMLUnsafe` included), `adoptNode` / `importNode`, the element-taking setters and WebRTC are locked on the prototypes before any pack script runs, a click on a link that targets another window (and any form submit) is cancelled before the engine can open a connection for it, a MutationObserver closes the widget if a loader element ever appears anyway, and none of it depends on Trusted Types, which the system WebKit of macOS 14 and 15 lacks (verified inside the real native shell on that WebKit, and in headless Chromium and WebKit with Trusted Types stripped, with a raw TCP sink). Widgets open only in the native popup shell (macOS 14 or newer), whose windows are routed through a loopback sink proxy of the host's as a further backstop for named hosts. A page that carries a loader (`<script src>`, `<link>`, a frame, `<meta http-equiv>`, `@import`, or a `__NONCE__` placeholder) is refused at install, again at open and again when the host issues the window's ticket. A frozen `dexterm` object is injected ahead of the pack markup: `dexterm.on(topic, fn)`, `dexterm.theme` (also CSS variables), `dexterm.close()`, `dexterm.log()`; the frame can say only ready / log / close back, and the terminal's socket accepts nothing but the generic events from a widget.
+- Consent is yours and re-checked: a widget installs disabled; `dexterm pack widget <pack> <name> --enable` after you read the page; at every open the app re-hashes the installed pack and refuses a page edited since. A workspace can list a widget popup (`{ "kind": "widget", "widget": "<pack>/<name>" }`) but cannot enable it.
+- **Beta.** One example widget (`packs/example-widgets`, the MOVERS tiles), a popup window only. The in-process plugin sandbox from the design (terminal columns and panels, host-mediated fetch, per-plugin storage) is not built. API and limits: `packages/popup/WIDGETS.md` in the repo.

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

@@ -0,0 +1,30 @@
+---
+id: docs-configuration-workspaces
+title: Configuration and files on disk › Workspaces
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+heading: Workspaces
+anchor: workspaces
+url: https://dexterm.xyz/docs/configuration#workspaces
+tags:
+  - docs
+  - configuration
+  - workspaces
+  - 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
+---
+
+A workspace is one JSON file, `~/.dexterm/workspaces/<name>.json`: the screen to land on, the theme and intensity, the screener preset / filter / sort, the token-screen panel toggles, optional per-screen pane trees for the layout solver (weights, fixed widths, priorities, what collapses at which width), and the HUD popups to open together. The shipped `default` reproduces the five screens exactly; `morning-hud` is "show me everything": the narrative board, the feeds, order plans and the chart of the selected coin as windows beside the terminal.
+
+- In the app: `ctrl+w` then `w` list · `n` / `N` next / previous · `s` save the current layout under a typed name · `m` the morning HUD · `o` open the active workspace's popups · `d` default · `1`–`9` pick a slot. `--workspace <name>` starts in one. The footer shows the active workspace.
+- On the command line: `dexterm workspace list | show <name> | remove <name> | init` (`init` writes `default` as an editable file with the shipped trees).
+- A switch is a UI action and nothing more. It can navigate, re-theme and open the same read-only windows the keys open; it cannot open a ticket, confirm, arm or sign, and a workspace file has no field for any of that (the schema refuses unknown keys by name). Jarvis proposes workspace switches through the same proposal card as everything else.

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

@@ -0,0 +1,25 @@
+---
+id: docs-configuration
+title: Configuration and files on disk
+kind: docs
+page: configuration
+page_title: Configuration and files on disk
+url: https://dexterm.xyz/docs/configuration
+tags:
+  - docs
+  - configuration
+  - 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
+---
+
+Environment variables, the files dexterm writes, the optional free RPC key, and how to delete everything.
+
+dexterm has no config server, no account and no telemetry. Everything it remembers is in a handful of local files you can read and delete.

package/dist/packages/mcp/assets/kb/docs/docs-copy-trading-stage-1-follow-a-wallet-see-what-it-does.md

@@ -0,0 +1,51 @@
+---
+id: docs-copy-trading-stage-1-follow-a-wallet-see-what-it-does
+title: Copy trading (staged, personal, paper by default) › Stage 1: follow a wallet, see what it does
+kind: docs
+page: copy-trading
+page_title: Copy trading (staged, personal, paper by default)
+heading: Stage 1: follow a wallet, see what it does
+anchor: stage-1-follow-a-wallet-see-what-it-does
+url: https://dexterm.xyz/docs/copy-trading#stage-1-follow-a-wallet-see-what-it-does
+tags:
+  - docs
+  - copy-trading
+  - stage
+  - follow
+  - wallet
+  - does
+  - copy
+  - trading
+  - staged
+  - personal
+  - paper
+  - default
+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/copy-trading.md
+date: 2026-10-16
+---
+
+Press `U` anywhere for the **FOLLOWED WALLETS** screen, or use the shell:
+
+```
+dexterm follow add <addr> --name "my label"
+dexterm follow list | stats <addr> | trades <addr> | remove <addr> | purge --yes
+```
+
+- **Your list, your labels.** A label is whatever you type, passed through the prompt firewall (an instruction-shaped label is refused, control characters are stripped, 24 characters at most). dexterm never infers who a wallet is, never scrapes X or Telegram to attribute one, and never exports the list. `purge` deletes every follow and label; the file is `~/.dexterm/follows.json` (mode 600).
+- **Decoded swaps.** The tracker reads the wallet's own recent history (Helius `getTransactionsForAddress`, 10 credits a call, newest first, through the data layer's limiter and credit meter) and classifies each transaction from the wallet's own balances: tokens up and SOL down is a **buy**, tokens down and SOL up a **sell**, tokens moved without a SOL leg a **transfer** (an airdrop is flagged as cost 0), tokens and SOL moving the *same* way is **lp-like** (an LP add or removal, never a swap), and two mints in one transaction is a **token-swap** with no SOL split, so nothing unpriceable is priced. Wrapped SOL is never a mint. The POPCAT recording from the wallet-intel spike is the regression case for the lp-like rule: its busiest launch signer *receives* tokens and SOL together.
+- **Numbers with their sample.** Realised PnL is FIFO by token amount over the history fetched, in SOL exactly and in USD at today's rate (the rate is printed). Fees and tips are inside the SOL leg. Win rate is wins over closed positions and stays hidden under n = 10 (the row shows `n<10 (2/4)`). The early-entry score needs the token's launch-window buyer ranks (a bubble-map scan) and shows `—` with the reason otherwise; it has no "reached 3×" filter yet and says so. Every figure carries `all N txs` or `last N txs only · older history not fetched`.
+- **Alerts, not news.** The first look at a wallet backfills history silently. Only transactions that appear *after* that raise an alert, as a toast anywhere in the app and on the screen's ALERTS tape with the lag between the block and the moment dexterm saw it. Keyless, the tracker is honestly **unavailable** and says how to get the free Helius key; a failed poll shows on the row and the next poll retries.
+
+- **Hold time.** The median time from first buy to last sell over the wallet's **closed** positions. A position counts only when both of those trades carry a real block time. Otherwise hold time shows `—` with the reason. It appears in `dexterm follow stats` and the detail view.
+- **Buy and sell alerts, pushed if you want.** A new trade by a followed wallet raises the in-app alert as before. If you have enabled a push channel (https://dexterm.xyz/docs/configuration#push-alerts-and-dexterm-watch) (desktop, your own Telegram bot or Discord webhook), the alert is delivered there too, marked buy or sell and "not a recommendation". This happens only while the dexterm terminal is running: `dexterm watch` runs your rules headless but does not follow wallets. Delivery is read-only: an alert cannot open, arm or sign anything.
+- **Per-wallet detail.** `⏎` on a followed wallet opens its detail view: recent decoded trades, positions, realised PnL, win rate with its n, hold time, early-entry score and open positions. Each figure is labelled with its source (Helius history) and data age. `↑`/`↓` scroll, `⏎` or `esc` close.
+
+Nothing on this stage trades. A wallet's past fills say nothing about its next one, and the screen says so.
+
+`H` on this screen makes a PnL card (https://dexterm.xyz/docs/paper-trading#pnl-cards) for the selected wallet's coins, stamped **TRACKED WALLET** (read-only observation), with the wallet address hidden unless you show it. To mark an open position it looks up the coin's public decimals and price (the same keyless lookup the mirror ticket uses).