dexterm-cli 0.1.2 → 0.1.3

package/dist/packages/mcp/assets/kb/app-help/use-presets.md

@@ -0,0 +1,42 @@
+---
+id: use-presets
+title: Use screener presets
+kind: app-help
+screen: screener
+feature: presets
+tags:
+  - app-help
+  - preset
+  - presets
+  - trending
+  - runners
+  - organic
+  - graduating
+  - smart
+keys:
+  - ]
+  - right
+  - l
+  - [
+  - left
+  - h
+actions:
+  - preset.next
+  - preset.prev
+flags:
+  - --preset
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+Press `]` / `[` to step through presets (Trending, Runners, Organic; Graduating ships keyless as an `approx` mcap-band proxy; Smart money needs a key and says so). The analyst can switch the feed too. One-shot at launch: `--preset <name>`.
+
+Keys: `] / → / l` (screener), `[ / ← / h` (screener).

package/dist/packages/mcp/assets/kb/app-help/use-voice-mode.md

@@ -0,0 +1,36 @@
+---
+id: use-voice-mode
+title: Use voice mode (Jarvis, push-to-talk)
+kind: app-help
+screen: all
+feature: jarvis
+tags:
+  - app-help
+  - voice
+  - jarvis
+  - talk
+  - mic
+  - microphone
+  - push
+  - listen
+keys:
+  - v
+actions:
+  - voice.talk
+flags:
+  - --sound
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+Press `v` to start push-to-talk: speak, press `v` again to send (a red ● LISTENING badge shows while the mic is live; it also auto-closes after 15 s). Instant commands ("show the runners", "open bonk", "filter liquidity over 50k") run locally; questions go to `claude`. Voice only PROPOSES trades — it can never confirm, sign, arm or raise a cap. macOS only; every voice action also has a key. `--sound on|off` sets the sound/voice output at launch.
+
+Keys: `v`.

package/dist/packages/mcp/assets/kb/app-help/watch-a-coin.md

@@ -0,0 +1,34 @@
+---
+id: watch-a-coin
+title: Watch (or unwatch) a coin
+kind: app-help
+screen: all
+feature: watchlist
+tags:
+  - app-help
+  - watch
+  - watchlist
+  - follow
+  - track
+  - token
+  - tokens
+  - coins
+keys:
+  - w
+actions:
+  - watch.add
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+Press `w` to watch/unwatch the highlighted coin (screener, new pairs, token screen). The watchlist is persisted and priced live. On the watchlist screen `d` removes a row.
+
+Keys: `w` (screener).

package/dist/packages/mcp/assets/kb/app-help/watch-headless.md

@@ -0,0 +1,35 @@
+---
+id: watch-headless
+title: Run alerts in the background (dexterm watch)
+kind: app-help
+screen: all
+feature: push-alerts
+tags:
+  - app-help
+  - watch
+  - background
+  - headless
+  - push
+  - alerts
+  - notify
+  - daemon
+  - interval
+commands:
+  - watch
+flags:
+  - --interval
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+`dexterm watch [--interval S] [--once|--ticks N] [--replay FILE]` runs the rules engine headless and PUSHES alerts to your enabled channels, so they reach you when the terminal is closed. It has no signer and can never trade. Set channels up first with `dexterm alerts`.
+
+CLI: `dexterm watch`.

package/dist/packages/mcp/assets/kb/app-help/what-dexterm-shows-agents.md

@@ -0,0 +1,31 @@
+---
+id: what-dexterm-shows-agents
+title: See what the user currently sees (app_state)
+kind: app-help
+screen: all
+feature: mcp
+tags:
+  - app-help
+  - state
+  - current
+  - screen
+  - context
+  - selected
+  - agent
+  - see
+tools:
+  - app_state
+  - screen_state
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+An agent can call the read-only `app_state` MCP tool to fit an answer to what the user sees: the current screen, the selected coin, the theme, price mode, voice name/rate, whether scan and calm are on, and which alert channels are configured (YES/NO only — never a token, webhook or key). `screen_state` adds the visible rows and the action allow-list.

package/dist/packages/mcp/assets/kb/app-help/workspaces.md

@@ -0,0 +1,38 @@
+---
+id: workspaces
+title: Save and switch workspaces
+kind: app-help
+screen: all
+feature: workspaces
+tags:
+  - app-help
+  - workspace
+  - workspaces
+  - layout
+  - hud
+  - save
+  - morning
+keys:
+  - ctrl+w s
+actions:
+  - workspace.save
+commands:
+  - workspace
+flags:
+  - --workspace
+  - --screen
+confidence: high
+owner: maintainers
+origin: app-help-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/app keymap + overlay + mcp tools + cli (task-1413)
+sources:
+  - packages/tui/src/keymap.ts
+  - packages/cli/src/main.ts
+  - packages/mcp/src/server.ts
+date: 2026-10-16
+---
+
+A workspace saves a start screen, theme, intensity, screener preset/filter/sort, token panels and the HUD popups to open together. `ctrl+w` then `s` saves as; `w` lists; `n`/`N` cycle. `dexterm workspace list|show|remove|init` manages them. The analyst can open a saved workspace for you.
+
+Keys: `^W S`. CLI: `dexterm workspace`.

package/dist/packages/mcp/src/app-help.js

@@ -0,0 +1,135 @@
+// @dexterm/mcp — the app-help knowledge base (task-1413).
+//
+// A SECOND bundled KB set, separate from the 17 memecoin-risk entries, that teaches an agent how dexterm
+// ITSELF works: what each screen shows, the exact key for a task, the CLI subcommand/flag, and the MCP
+// tools. The entries in `assets/kb/app-help/*.md` are GENERATED from the app's own keymap / help overlay /
+// MCP tool list / CLI by `packages/cli/src/app-help-gen.ts` (committed, run in tests), so they cannot drift
+// from the real app. This module only LOADS and SEARCHES them — it is read-only and dependency-free.
+//
+// It is kept out of the main KB store on purpose: the memecoin KB's "exactly 17 bundled entries" invariant
+// stays true, and a "how do I …" search hits app-help first without the two sets diluting each other.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadBundled } from "./user-content.js";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** The shipped app-help KB directory (read-only; generated). */
+export const APP_HELP_DIR = path.resolve(HERE, '..', 'assets', 'kb', 'app-help');
+function list(v) {
+    return Array.isArray(v) ? v.map(String) : typeof v === 'string' && v ? [v] : [];
+}
+function toAppHelp(e) {
+    return {
+        id: e.id,
+        title: String(e.meta.title ?? e.id),
+        screen: String(e.meta.screen ?? 'all'),
+        tags: list(e.meta.tags),
+        keys: list(e.meta.keys),
+        actions: list(e.meta.actions),
+        commands: list(e.meta.commands),
+        flags: list(e.meta.flags),
+        tools: list(e.meta.tools),
+        feature: String(e.meta.feature ?? ''),
+        body: e.body,
+        bytes: e.bytes,
+    };
+}
+/** Load every app-help entry (bundled-only; deterministic order by id). */
+export function loadAppHelp(dir = APP_HELP_DIR) {
+    const entries = loadBundled([{ dir, layout: 'flat' }]).map(toAppHelp);
+    entries.sort((a, b) => a.id.localeCompare(b.id));
+    return entries;
+}
+// Generic words that carry no retrieval signal in a "how do I …" question — dropped before scoring so a
+// short noise word ('to', 'my') can't substring-match an unrelated entry and outrank the real one.
+const STOP = new Set([
+    'how', 'do', 'does', 'did', 'the', 'a', 'an', 'to', 'my', 'me', 'i', 'is', 'it', 'its', 'of', 'in', 'on',
+    'at', 'by', 'or', 'and', 'for', 'with', 'this', 'that', 'these', 'those', 'your', 'you', 'can', 'what',
+    'which', 'where', 'when', 'who', 'am', 'are', 'be', 'get', 'got', 'use', 'using', 'make', 'want', 'need',
+    'from', 'into', 'show', 'see', 'tell', 'about', 'some', 'any', 'all', 'up', 'out', 'off', 'on',
+    // generic action verbs — they appear in many entry titles ("Change…", "Switch…") and carry no signal.
+    'change', 'switch', 'set', 'setting', 'turn', 'open', 'close', 'enable', 'disable', 'add', 'remove',
+    'start', 'stop', 'run', 'cycle', 'pick', 'choose', 'save', 'view', 'check',
+]);
+function tokenise(s) {
+    return (s.toLowerCase().match(/[a-z0-9][a-z0-9-]+/g) ?? []).filter((t) => !STOP.has(t));
+}
+/** A short, deterministic how-to synonym map so natural phrasings land on the right entry. */
+const QUERY_SYNONYMS = {
+    paste: 'open', ca: 'open', 'contract-address': 'open', address: 'open', link: 'open',
+    screenshot: 'export', save: 'export', png: 'export', report: 'export', share: 'export',
+    speed: 'rate', faster: 'rate', slower: 'rate', wpm: 'rate',
+    speak: 'voice', talk: 'voice', jarvis: 'voice', mic: 'voice', microphone: 'voice',
+    notify: 'alert', notification: 'alerts', telegram: 'alerts', discord: 'alerts',
+    filtering: 'filter', query: 'filter',
+    marketcap: 'mcap', 'market-cap': 'mcap', cap: 'mcap',
+    honeypot: 'rug', safe: 'rug', scam: 'rug',
+    fake: 'larp', legit: 'larp', real: 'larp', website: 'larp', 'rug-pull': 'rug',
+    agent: 'mcp', agents: 'mcp', bot: 'mcp', claude: 'analyst',
+    helius: 'key', rpc: 'key', holders: 'key',
+    layout: 'workspace', workspaces: 'workspace',
+    keybind: 'keymap', keybinding: 'keymap', rebind: 'keymap', shortcut: 'keymap',
+    theme: 'theme', colour: 'theme', color: 'theme',
+    buy: 'paper', sell: 'paper', trade: 'paper', ticket: 'paper',
+    upgrade: 'update',
+    chart: 'popup', candles: 'popup',
+    bubbles: 'bubble', cluster: 'bubble', clusters: 'bubble',
+    scanner: 'scan', watcher: 'scan',
+    copy: 'follow', mirror: 'follow', unfollow: 'follow',
+};
+function expand(terms) {
+    const out = new Set(terms);
+    for (const t of terms) {
+        const s = QUERY_SYNONYMS[t];
+        if (s)
+            out.add(s);
+    }
+    return [...out];
+}
+/** Raw word tokens of a haystack (no stopword filtering), for exact word-boundary matching. */
+function words(s) {
+    return s.toLowerCase().match(/[a-z0-9][a-z0-9-]+/g) ?? [];
+}
+/**
+ * Deterministic keyword retrieval over the app-help set (no model). Matches on WORD BOUNDARIES (not
+ * substrings) so "screener" does not match the tag "dexscreener" and "token" does not match a tool name
+ * like "open_token". title/tags/screen/feature score strongest; the body is the weak tail.
+ */
+export function searchAppHelp(query, limit = 5, entries = loadAppHelp()) {
+    const terms = expand(tokenise(query));
+    // A query whose only meaningful word is a screen name ("what does the screener show") is a request for
+    // that screen's overview, not for a topic that happens to run there.
+    const soleScreen = terms.length === 1 ? terms[0] : null;
+    // An explicit "... screen ..." question ("what does the kol screen show") is a request for that screen's
+    // overview even when other words survive; boost the matching overview so it beats a topic that shares the name.
+    const asksScreen = words(query).includes('screen');
+    const scored = entries.map((e) => {
+        const overview = e.id.startsWith('screen-');
+        // Screen field matches only for an overview entry; on a topic it is just where the action happens.
+        const strong = new Set(words(`${e.title} ${e.tags.join(' ')} ${e.feature}${overview ? ' ' + e.screen : ''}`));
+        // An overview's body is the enumerated key list — it names every action word, so it is NOT scored
+        // (else "sort the screener" would match the screener overview's `s — sort` line over the sort topic).
+        const bodyWords = overview ? [] : words(e.body);
+        let score = 0;
+        for (const t of terms) {
+            if (strong.has(t))
+                score += 4;
+            let n = 0;
+            for (const w of bodyWords)
+                if (w === t)
+                    n++;
+            score += Math.min(n, 3);
+        }
+        if (overview && soleScreen && soleScreen === e.screen)
+            score += 6;
+        if (overview && asksScreen && terms.includes(e.screen))
+            score += 3;
+        return { e, score };
+    }).filter((x) => x.score > 0)
+        .sort((a, b) => (b.score - a.score) || a.e.id.localeCompare(b.e.id))
+        .slice(0, limit);
+    return scored.map(({ e, score }) => ({ ...e, score }));
+}
+/** Fetch one app-help entry by id. */
+export function getAppHelp(id, entries = loadAppHelp()) {
+    return entries.find((e) => e.id === id) ?? null;
+}

package/dist/packages/mcp/src/index.js

@@ -4,6 +4,9 @@
 export { runStdioServer, selfTest, McpTools, TOOLS, READ_ONLY_TOOLS, firewall, listPrompts, getPrompt, resourceList, resourceRead, overlayCounts, userSkillPreamble, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR } from "./server.js";
 export { OverlayStore, mergeOverlay, loadBundled, checkKb, checkSkill, moneyToolMentions, isMoneyToolName, parseFrontmatter, dextermHome, userKbDir, userSkillsDir, userDir, contentJournalPath, journalContent, writeOverlayFile, resetOverlayFile, templateFor, KB_LIMITS, SKILL_LIMITS, KB_ID, SKILL_NAME, KB_RULE, MONEY_TOOLS, } from "./user-content.js";
 export { buildDossier } from "./dossier.js";
+// task-1406: the spectator sink the tool-call path writes to when launched with a spectator channel.
+export { recordForToolCall, maxAgeSec, fileSpectatorSinkFromEnv } from "./spectator-sink.js";
+export { loadAppHelp, searchAppHelp, getAppHelp, APP_HELP_DIR } from "./app-help.js";
 /** Tool names served in v1 (SPEC §5.2 core + the task-1293 KB/case tools + the task-1314 dossier). */
 export const PLANNED_TOOLS = [
     'screen_state',

package/dist/packages/mcp/src/server.js

@@ -21,6 +21,8 @@ import { createDataLayer, resolveRpcUrl, redactSecrets, defaultDbPath, replayTra
 import { buildDossier } from "./dossier.js";
 import { firewall } from "./firewall.js";
 import { OverlayStore, dextermHome, KB_RULE } from "./user-content.js";
+import { fileSpectatorSinkFromEnv, recordForToolCall } from "./spectator-sink.js";
+import { loadAppHelp, searchAppHelp, getAppHelp } from "./app-help.js";
 import { assembleTokenDossier, computeBoard, recentNarrativeRows, loadDefaultLexicon, summaryText, buildDigest, tokenRugScorer, h1Model, runBacktest } from '../../packs/src/index.js';
 import { exportRecorded, openHistoryReadOnly } from '../../recorder/src/index.js';
 // The default rug-probability scorer (task-1356 Tier 4). H1 is the PRE-REGISTERED heuristic; it is the
@@ -94,6 +96,16 @@ function kbSearch(q, limit = 5) {
     return scored.map(({ e, score }) => ({ ...kbView(e, { full: false }), score }));
 }
 // ---------------------------------------------------------------------------
+// app-help KB (task-1413): a separate bundled set generated from the app's own keymap/overlay/tools/CLI
+// (packages/mcp/assets/kb/app-help/*.md). It teaches "how dexterm works" with the exact key/command; it
+// is first-party doc text (not firewalled) and carries structured keys/commands/flags/tools per entry.
+function appHelpView(e) {
+    return {
+        id: e.id, title: e.title, screen: e.screen, feature: e.feature || null, tags: e.tags,
+        keys: e.keys, commands: e.commands, flags: e.flags, tools: e.tools, text: e.body, origin: 'app-help',
+    };
+}
+// ---------------------------------------------------------------------------
 // Case files: assets/cases.json (format in research/claude-layer/cases/FORMAT.md). Read-only.
 const CASES_FILE = path.join(ASSETS, 'cases.json');
 const CASES = fs.existsSync(CASES_FILE)
@@ -203,10 +215,27 @@ export const TOOLS = [
     // tokens currently on screen (screen_state.actions) and applied by the running app, which shows
     // "analyst did X". None can size, confirm, sign, or send a trade.
     { name: 'open_token', description: "Open a token's detail screen in dexterm so the user can see it. `mint` must be one of the mints currently on screen (see screen_state). Use for \"put this/that coin on my screen\", \"show me $X\". Non-financial navigation; it never trades.", inputSchema: { type: 'object', properties: { mint: { type: 'string', description: 'base58 mint, must be on screen' } }, required: ['mint'], additionalProperties: false } },
-    { name: 'show_in_screener', description: 'Show the screener with an optional filter, sort, and a highlighted mint. Use for "rank these by volume", "filter to liq > 50k", "coins under 5M mcap". `filter` is dexterm\'s grammar: space-separated `field op value` clauses ANDed, e.g. `mcap < 5M liq > 100K h24 > 20`. Fields: vol24 vol6h vol1h vol5m liq mcap fdv price age holders buys sells org top10 dev lplocked bundled snipers m5 h1 h6 h24. Ops > >= < <= = !=. Money K/M/B; percents plain; age needs a unit (6h, 30m). Tags: launchpad:pump|dbc|raydium|meteora|bonk, flag:mint|freeze|top10|dev|bundle|lp|clean (negate with !, e.g. !flag:mint), verified:yes, sus:no, chain:solana. Invalid fields are rejected — only use the ones listed. `sort.key` must be one of screen_state.actions.sortKeys; `highlight` must be a mint on screen. When you build a filter from a plain-language request, also return `filter_applied` in your structured output.', inputSchema: { type: 'object', properties: { filter: { type: 'string' }, sort: { type: 'object', properties: { key: { type: 'string' }, dir: { type: 'string', enum: ['asc', 'desc'] } }, required: ['key'], additionalProperties: false }, highlight: { type: 'string' } }, additionalProperties: false } },
+    { name: 'show_in_screener', description: 'Show the screener with an optional filter, sort, and a highlighted mint. Use for "rank these by volume", "filter to liq > 50k", "coins under 5M mcap". `filter` is dexterm\'s grammar: space-separated `field op value` clauses ANDed, e.g. `mcap < 5M liq > 100K h24 > 20`. Fields: vol24 vol6h vol1h vol5m liq mcap fdv price age holders buys sells org top10 dev lplocked bundled snipers m5 h1 h6 h24. Ops > >= < <= = !=. Money K/M/B; percents plain; age needs a unit (6h, 30m). Tags: launchpad:pump|dbc|raydium|meteora|bonk, flag:mint|freeze|top10|dev|bundle|lp|clean (negate with !, e.g. !flag:mint), verified:yes, sus:no, chain:solana. Invalid fields are rejected — only use the ones listed. `sort.key` must be one of screen_state.actions.sortKeys; `highlight` must be a mint on screen. `preset`, when given, must be one of screen_state.actions.feeds. When you build a filter from a plain-language request, also return `filter_applied` in your structured output.', inputSchema: { type: 'object', properties: { filter: { type: 'string' }, sort: { type: 'object', properties: { key: { type: 'string' }, dir: { type: 'string', enum: ['asc', 'desc'] } }, required: ['key'], additionalProperties: false }, highlight: { type: 'string' }, preset: { type: 'string' } }, additionalProperties: false } },
     { name: 'add_to_watchlist', description: 'Add a token to the user\'s watchlist. `mint` must be one of the mints currently on screen. Non-financial.', inputSchema: { type: 'object', properties: { mint: { type: 'string' } }, required: ['mint'], additionalProperties: false } },
     { name: 'switch_feed', description: 'Switch the screener feed/preset. `feed` must be one of screen_state.actions.feeds.', inputSchema: { type: 'object', properties: { feed: { type: 'string' } }, required: ['feed'], additionalProperties: false } },
     { name: 'open_ticket', description: 'Open the PAPER trade ticket pre-filled for a mint and side. It ONLY opens the ticket (editing phase); it never sizes, confirms, signs, or sends — the user confirms every trade themselves. `mint` must be on screen; `side` is "buy" or "sell".', inputSchema: { type: 'object', properties: { mint: { type: 'string' }, side: { type: 'string', enum: ['buy', 'sell'] } }, required: ['mint', 'side'], additionalProperties: false } },
+    // ---- app-help + app-state (task-1413). Read-only: how the app works, and what the user currently sees.
+    { name: 'app_help', description: 'Search the APP-HELP knowledge base: how dexterm itself works (what a screen shows, the exact key for a task, the CLI command, the MCP tools). For any "how do I …", "what key …", "what does this screen show" question, call this FIRST and answer with the exact key or command from the result — NEVER invent a key. If nothing matches, say "I don\'t see that in the app." Pass `query` to search, or `id` to fetch one entry. Each result carries structured `keys`, `commands`, `flags`, `tools` and the screen it is about.', inputSchema: { type: 'object', properties: { query: { type: 'string' }, id: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 10 } }, additionalProperties: false } },
+    { name: 'app_state', description: 'Read-only snapshot of what the user currently sees so an answer fits their screen: current screen, selected coin (mint+symbol), theme, price display mode, voice name/rate, whether scan and calm are on, and which alert channels are CONFIGURED (yes/no only). It never returns a key, token, webhook, secret or any credential. Use it to tailor a "how do I" answer to the user\'s actual state.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    // ---- more UI actions (task-1413). Tiered, non-financial. `view`: applied immediately with an "analyst did X"
+    // note. `config`: a one-line PROPOSAL the user accepts with a keypress, then written to config.json as actor
+    // 'analyst' (undo with ctrl+z). NONE can touch wallets/keys/alerts-secrets/signing/caps/network/software.
+    { name: 'switch_screen', description: 'Switch to a dexterm screen (view-only). `screen` must be one of screen_state.actions.screens.', inputSchema: { type: 'object', properties: { screen: { type: 'string' } }, required: ['screen'], additionalProperties: false } },
+    { name: 'switch_workspace', description: 'Open a saved workspace layout (view-only). `name` must be one of screen_state.actions.workspaces.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false } },
+    { name: 'chart_popup', description: 'Open or close the chart popup window (view-only). `open`: true to open, false to close.', inputSchema: { type: 'object', properties: { open: { type: 'boolean' } }, required: ['open'], additionalProperties: false } },
+    { name: 'toggle_calm', description: 'Turn calm mode (effects off) on or off (view-only). `on`: true for calm, false to restore effects.', inputSchema: { type: 'object', properties: { on: { type: 'boolean' } }, required: ['on'], additionalProperties: false } },
+    { name: 'set_scan', description: 'Turn the observe-only AI scan mode on or off (view-only). `on`: true/false.', inputSchema: { type: 'object', properties: { on: { type: 'boolean' } }, required: ['on'], additionalProperties: false } },
+    { name: 'export_view', description: 'Export the current view to ~/.dexterm/exports (PNG + text report; view-only, nothing uploaded).', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'set_theme', description: 'PROPOSE a theme change the user confirms with a keypress (persisted, undoable). `name` must be one of screen_state.actions.themes.', inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false } },
+    { name: 'set_price_mode', description: 'PROPOSE the price display mode the user confirms with a keypress (persisted, undoable). `mode`: "price" or "mcap".', inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['price', 'mcap'] } }, required: ['mode'], additionalProperties: false } },
+    { name: 'set_intensity', description: 'PROPOSE the visual intensity the user confirms with a keypress (persisted, undoable). `intensity`: "off", "normal" or "fever".', inputSchema: { type: 'object', properties: { intensity: { type: 'string', enum: ['off', 'normal', 'fever'] } }, required: ['intensity'], additionalProperties: false } },
+    // task-1413 r2: voice speed/name are NOT analyst actions. The `/voice` config path is DENIED_FOR_MODELS —
+    // only the keyboard (`<`/`>`, the voice picker) sets it. There is deliberately no set_voice_* tool here.
 ];
 /** The read-only tool surface: every tool except the UI-action ones (task-1313). The only tools a skill may name (task-1377). */
 export const READ_ONLY_TOOLS = TOOLS.map((t) => String(t.name)).filter((n) => !ANALYST_ACTION_TYPES.includes(n));
@@ -215,7 +244,11 @@ const SKILL_STORE = new OverlayStore({ kind: 'skill', bundled: [{ dir: SKILLS_DI
 function allowFrom(screenState) {
     const a = (screenState.actions ?? {});
     const list = (x) => Array.isArray(x) ? x.filter((v) => typeof v === 'string') : [];
-    const allow = { mints: list(a.mints), feeds: list(a.feeds), sortKeys: list(a.sortKeys) };
+    const allow = {
+        mints: list(a.mints), feeds: list(a.feeds), sortKeys: list(a.sortKeys),
+        // task-1413: screens/workspaces/themes an action may reference (empty/absent fails closed).
+        screens: list(a.screens), workspaces: list(a.workspaces), themes: list(a.themes),
+    };
     // task-1324: a session-level action-type list (AI scan mode sends []) narrows what this server will
     // write to the channel. Present-but-malformed fails closed (no types allowed).
     if (a.types !== undefined)
@@ -279,6 +312,39 @@ export class McpTools {
         }
         return { ok: true, requested: res.label, note: 'The app applies this and shows "analyst did X". You cannot confirm, size, or send a trade.' };
     }
+    /**
+     * task-1413: a read-only view of what the user currently sees. It only reflects the fields the CLI put in
+     * screen_state (screen, selected coin, and the `app` block of theme/priceMode/voice/scan/calm/alerts). The
+     * `alerts` map is booleans (configured yes/no); by construction this method never reads or returns a token,
+     * webhook, key or any secret. Degrades to `available:false` when there is no running app.
+     */
+    appState() {
+        const s = this.screenState();
+        const app = (s.app && typeof s.app === 'object') ? s.app : null;
+        const sel = (s.selected && typeof s.selected === 'object') ? s.selected : null;
+        // task-1413 residual: the selected symbol is an attacker-chosen token string (a coin can be named
+        // anything), so it is firewalled before it leaves in the snapshot an agent reads — exactly like the
+        // Jupiter symbol at tokenView(). The mint is a base58 address and is safe verbatim.
+        const selected = sel && typeof sel.mint === 'string'
+            ? { mint: sel.mint, symbol: typeof sel.symbol === 'string' ? (firewall(sel.symbol, 'app:selected:symbol', 'symbol', { keepAddresses: false }) ?? '') : '' }
+            : null;
+        if (!app) {
+            return { available: false, screen: s.screen ?? 'unknown', selected, note: 'no running dexterm app; launch it for live state. Never returns any secret.' };
+        }
+        return {
+            available: true,
+            screen: s.screen ?? 'unknown',
+            selected,
+            theme: app.theme ?? null,
+            priceMode: app.priceMode ?? null,
+            intensity: app.intensity ?? null,
+            calm: typeof app.calm === 'boolean' ? app.calm : null,
+            voice: app.voice ?? null,
+            scan: app.scan ?? null,
+            alerts: app.alerts ?? null, // { toast, desktop, telegram, discord } — booleans only, never a secret
+            note: 'Read-only. alerts shows whether each channel is configured (yes/no); it never reveals a token, webhook or key.',
+        };
+    }
     /** Resolve a mint or symbol to one enriched row, or return candidates/error. */
     async resolve(ref) {
         if (!ref || typeof ref !== 'string')
@@ -649,6 +715,20 @@ export class McpTools {
                 const c = CASES.find((x) => x.id === args.id);
                 return c ?? { error: 'no such case' };
             }
+            case 'app_help': {
+                // task-1413: how dexterm itself works. Generated from the keymap/overlay/tools/CLI — the exact key
+                // or command for a task. Fetch one by id, or search; never a fact about a live token.
+                if (args.id) {
+                    const e = getAppHelp(String(args.id));
+                    if (!e)
+                        return { error: `no app-help entry ${String(args.id).slice(0, 64)}`, available: loadAppHelp().map((x) => x.id) };
+                    return { ...appHelpView(e), rule: 'app-help explains how dexterm works. Answer with its exact key/command; never invent one.' };
+                }
+                const results = searchAppHelp(String(args.query ?? ''), Number(args.limit ?? 5)).map((e) => ({ ...appHelpView(e), score: e.score }));
+                return { query: String(args.query ?? '').slice(0, 200), results, rule: 'If nothing matches, tell the user "I don\'t see that in the app." Never invent a key or command.' };
+            }
+            case 'app_state':
+                return this.appState();
             case 'get_links': {
                 const r = await this.linksFor(args.mint ?? args.symbol);
                 if ('error' in r)
@@ -837,6 +917,10 @@ export async function runStdioServer(opts = {}) {
         ? { token: channelToken, append: (line) => fs.appendFileSync(channelFile, line, { mode: 0o600 }) }
         : null;
     const tools = new McpTools(data, screenStateFromEnv, channel, dbPathForHistory);
+    // task-1406: when the running dexterm launched us with a spectator channel, every tool call is emitted
+    // as a SpectatorEvent-shaped JSONL line the TUI tails into its hub (where redaction + the stream live).
+    const spectator = fileSpectatorSinkFromEnv(process.env);
+    let specSeq = 0;
     function appendTrace(rec) {
         if (TRACE) {
             try {
@@ -867,7 +951,10 @@ export async function runStdioServer(opts = {}) {
                     result = { error: err(e) };
                 }
                 const text = JSON.stringify(result);
-                appendTrace({ t: Date.now(), tool: name, args, ms: Date.now() - t0, bytes: Buffer.byteLength(text), isError: Boolean(result.error) });
+                const ms = Date.now() - t0;
+                appendTrace({ t: Date.now(), tool: name, args, ms, bytes: Buffer.byteLength(text), isError: Boolean(result.error) });
+                if (spectator)
+                    spectator.sink.record(recordForToolCall({ seq: ++specSeq, agent: spectator.agent, tool: name, args, result, ms, token: spectator.token }));
                 return reply({ content: [{ type: 'text', text }], isError: false });
             }
             case 'resources/list': return reply({ resources: resourceList() });

package/dist/packages/mcp/src/spectator-sink.js

@@ -0,0 +1,72 @@
+// @dexterm/mcp — spectator sink for the MCP tool-call path (task-1406, "watch the agent cook").
+//
+// The MCP server runs as a separate stdio process spawned by the user's agent. When the running dexterm
+// launches it with DEXTERM_SPECTATOR_FILE (an append-only local channel, 0600, like the task-1313 action
+// channel) it instruments every tools/call: one JSONL record in the @dexterm/agents SpectatorEvent v1
+// shape is appended, which the TUI tails into its SpectatorHub (where redaction + the stream happen).
+// The record carries NOTHING an agent could act on — it only describes a read/navigation call that
+// already completed. The file is local and token-marked; raw addresses live only on this loopback channel
+// and are redacted before anything leaves the machine.
+import { appendFileSync } from 'node:fs';
+/** The UI-action tools that move the screen (so follow mode can visibly perform them). */
+const NAV_TOOLS = new Set(['open_token', 'show_in_screener', 'switch_feed', 'add_to_watchlist', 'open_ticket']);
+function navFor(tool, args) {
+    const s = (v) => (typeof v === 'string' ? v : undefined);
+    if (tool === 'open_token')
+        return { screen: 'token', mint: s(args.mint) };
+    if (tool === 'switch_feed')
+        return { screen: 'screener', feed: s(args.feed) };
+    if (tool === 'show_in_screener')
+        return { screen: 'screener', filter: s(args.filter), highlight: s(args.highlight) };
+    if (tool === 'add_to_watchlist')
+        return { screen: 'watchlist', mint: s(args.mint) };
+    if (tool === 'open_ticket')
+        return { screen: 'ticket', mint: s(args.mint), side: s(args.side) };
+    return null;
+}
+/** Largest `ageSec` anywhere in a tool result (the data freshness the activity panel shows). */
+export function maxAgeSec(result, depth = 0) {
+    if (depth > 6 || !result || typeof result !== 'object')
+        return null;
+    let max = null;
+    for (const [k, v] of Object.entries(result)) {
+        if (k === 'ageSec' && typeof v === 'number' && Number.isFinite(v) && v >= 0)
+            max = max === null ? v : Math.max(max, v);
+        else {
+            const inner = maxAgeSec(v, depth + 1);
+            if (inner !== null)
+                max = max === null ? inner : Math.max(max, inner);
+        }
+    }
+    return max;
+}
+function shortMint(args) {
+    const m = typeof args.mint === 'string' ? args.mint : typeof args.symbol === 'string' ? args.symbol : '';
+    return m ? ` ${m.length > 10 ? m.slice(0, 6) + '…' : m}` : '';
+}
+/** Build one spectator record for a completed MCP tool call. */
+export function recordForToolCall(opts) {
+    const isErr = typeof opts.result.error === 'string';
+    const nav = navFor(opts.tool, opts.args);
+    return {
+        v: 1, seq: opts.seq, t: (opts.now ?? Date.now)(), phase: nav ? 'nav' : 'result',
+        agent: opts.agent, transport: 'mcp', tool: opts.tool,
+        summary: isErr ? `error: ${String(opts.result.error).slice(0, 80)}` : `${opts.tool}${shortMint(opts.args)}`,
+        ms: opts.ms, dataAgeSec: isErr ? null : maxAgeSec(opts.result), nav, ok: !isErr,
+        ...(opts.token ? { token: opts.token } : {}),
+    };
+}
+export function fileSpectatorSinkFromEnv(env) {
+    const file = env.DEXTERM_SPECTATOR_FILE;
+    if (!file)
+        return null;
+    const token = env.DEXTERM_SPECTATOR_TOKEN || undefined;
+    const agent = env.DEXTERM_SPECTATOR_AGENT || 'mcp-agent';
+    const sink = {
+        record(rec) { try {
+            appendFileSync(file, JSON.stringify(rec) + '\n', { mode: 0o600 });
+        }
+        catch { /* best-effort local channel */ } },
+    };
+    return { sink, agent, token };
+}

package/dist/packages/packs/src/index.js

@@ -18,3 +18,5 @@ export * from "./backtest.js";
 // task-1359: LARP eval (recorded product verdicts vs outcome labels; counts only below n = 50).
 export * from "./larp-eval.js";
 export * from "./skill-backtest.js";
+// task-1414: skill care — rolling split, the proposal gate (new-coins + interval-noise + frozen canary), trend.
+export * from "./skill-care.js";