dexterm-cli 0.1.3 → 0.1.5

package/dist/packages/cli/src/app-help-gen.js

@@ -85,7 +85,7 @@ export function appTools() {
 const SCREENS = [
     { screen: 'screener', title: 'The screener screen', feature: 'screener', tools: ['screener_query'],
         blurb: 'The live table of Solana tokens (DexScreener + Jupiter, refreshed every ~10 s): price, 5m/1h/6h/24h change, volume, liquidity, market cap, age, holders, organic score, flags and a sparkline, with a p(rug) column. Cells whose source is down show a dash and the caption says why — never a fabricated number.' },
-    { screen: 'token', title: 'The token screen', feature: 'token-intel', tools: ['get_dossier', 'get_token', 'get_holders', 'get_trades', 'get_candles', 'get_dev_history', 'rugcheck'],
+    { screen: 'token', title: 'The token screen', feature: 'token-intel', tools: ['get_dossier', 'get_token', 'get_holders', 'get_trades', 'get_candles', 'get_dev_history', 'dev_history', 'rugcheck'],
         blurb: 'One coin in depth: market stats, a candle chart, the trades tape, mint/freeze authority, top holders with their class (pool/dev/linked/…), RugCheck + GoPlus, snipers/bundled from the wallet-intel scan, and the ANALYST panel. Open it with ⏎ on any live row or `--mint <CA|link>`.' },
     { screen: 'newpairs', title: 'The new pairs screen', feature: 'new-pairs', tools: ['screener_query'],
         blurb: 'A live feed of just-launched tokens (PumpPortal new-token + migration push, plus Jupiter/RugCheck/DexScreener polls). Bonding progress is a create-time estimate and says so; SNIPE/BUNDLE columns fill in from the wallet-intel scan of the row the cursor rests on (Helius-keyed).' },
@@ -93,8 +93,8 @@ const SCREENS = [
         blurb: 'The coins you watch, persisted in SQLite, priced live every ~10 s with a LIVE/POLL badge. Add with `w` on any coin; remove with `d`.' },
     { screen: 'analyst', title: 'The analyst screen', feature: 'analyst', tools: ['get_dossier', 'kb_search', 'app_help'],
         blurb: 'Your own `claude` CLI as the dexterm analyst: it reads the read-only dexterm MCP tools, grounds every fact in a tool result, and answers in a few terse lines. ⏎ on a coin runs a full dossier; `a` runs a rug-check. Facts never come from model memory; token text passes the prompt firewall.' },
-    { screen: 'positions', title: 'The paper positions screen', feature: 'positions', tools: [],
-        blurb: 'Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow.' },
+    { screen: 'positions', title: 'The paper positions screen', feature: 'positions', tools: ['paper_positions', 'paper_pnl'],
+        blurb: 'Your simulated (PAPER) positions and their P&L. dexterm holds no keys and signs nothing; paper trading is a simulation for learning the flow. An agent you enabled can read these over MCP with the read-only paper_positions and paper_pnl tools.' },
     { screen: 'trending', title: 'The trending screen', feature: 'trending-board', tools: ['narrative_board'],
         blurb: 'What is trending in the space — narratives and movers aggregated from the feed.' },
     { screen: 'kol', title: 'The KOL lists screen', feature: 'kol-lists', tools: [],
@@ -179,10 +179,16 @@ const TOPICS = [
     { id: 'ask-the-analyst', title: 'Ask the analyst a question', screen: 'analyst', tags: ['analyst', 'ask', 'claude', 'ai', 'question', 'dossier', 'chat'],
         actions: [{ action: 'analyst.toggle' }, { action: 'open', screen: 'screener' }], tools: ['get_dossier', 'kb_search', 'app_help', 'case_lookup'], feature: 'analyst',
         flags: ['--no-ai'],
-        body: 'The analyst is your own `claude` login. ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.' },
+        body: 'The analyst is your own `claude` login (or your own `codex` login: `/engine codex`, see "Run the analyst on Codex"). ⏎ on a coin runs a full dossier; `a` runs a rug-check (or a trench-scan of the screener when nothing is selected). Type a follow-up and ⏎ to send. If `claude` is missing or logged out the panel shows the one-line fix and the rest of dexterm keeps working. Start without AI using `--no-ai`.' },
     { id: 'connect-an-agent', title: 'Connect your own agent (MCP)', screen: 'all', tags: ['mcp', 'agent', 'agents', 'connect', 'claude', 'tool', 'server', 'bot'],
         commands: ['mcp'], tools: ['screen_state', 'get_dossier', 'kb_search', 'app_help', 'app_state'], feature: 'mcp',
-        body: '`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.' },
+        body: '`dexterm mcp` is a plain stdio MCP server exposing the same read-only tools the analyst uses. Add it to any Claude Code with `claude mcp add dexterm -- node packages/mcp/bin/dexterm-mcp.mjs`, or set up Claude Code, Claude Desktop, Cursor or Codex in one command with `dexterm mcp install <client>`. Agents are untrusted: every tool is read-only and an agent can never sign, arm, raise a cap or touch keys. Use `app_help` for "how do I" questions and `app_state` to see what the user sees.' },
+    { id: 'use-codex-analyst', title: 'Run the analyst on Codex instead of Claude', screen: 'all', tags: ['codex', 'openai', 'chatgpt', 'engine', 'analyst', 'claude', 'switch', 'backend'],
+        flags: ['--analyst-engine'], feature: 'analyst',
+        body: 'The analyst can run on your own Codex CLI login instead of Claude (0.1.5). Pick it with `--analyst-engine codex`, `DEXTERM_ANALYST_ENGINE=codex`, `"analyst": {"engine": "codex"}` in `~/.dexterm/config.json`, or type `/engine codex` in the chat box (new conversations; `/engine` alone shows the engine and what is installed). The default `auto` uses claude when it is installed, else codex. dexterm stores no credentials: your `codex login` does the work. The Codex run is locked read-only: only the read-only dexterm tools (plus the UI actions the session allows, none in scan mode), no shell, no file edits, no web search, no other MCP server; a turn that tries anything else is stopped. `dexterm doctor` shows a Codex CLI line (installed, version, logged in). Codex is also supported as an MCP client: `dexterm mcp install codex`.' },
+    { id: 'dev-history', title: 'Check if a coin\'s creator rugged before (dev history)', screen: 'token', tags: ['dev', 'deployer', 'creator', 'serial', 'rugger', 'rugged', 'history', 'launches'],
+        tools: ['dev_history', 'get_dev_history'], feature: 'token-intel',
+        body: 'The token screen\'s ON-CHAIN panel shows the creator\'s recorded track record (0.1.5): `Dev rugs (recorded)` (rugs out of labelled prior launches, with the sample n), `Dev launches seen`, `Dev sold its bag` (median minutes to the dev\'s exit) and `Dev linked` (funder or cluster from the wallet-intel scan). It comes from dexterm\'s own local history recorder (keyless creator links + code-only outcome labels), so it says `unknown` when there is no record; it is a risk flag from observed history, never a certificate. Alert on it with the rule field `devrugs`, e.g. `when devrugs >= 2 then alert(warn, "new coin from a wallet that rugged before") scope newpairs`. Agents and the analyst use the `dev_history` MCP tool.' },
     { id: 'configure-rpc-key', title: 'Configure a Helius / RPC key for holders', screen: 'all', tags: ['helius', 'rpc', 'key', 'holders', 'free', 'api', 'ranked'],
         feature: 'keyless',
         body: 'dexterm is free-forever and keyless by default. The one real keyless gap is the ranked top-holder list: add a free RPC key for it. Save a Helius key ONLY at `~/.dexterm/helius.key` (mode 600, never a repo or command line), or set `DEXTERM_RPC_URL` to any read-only RPC. `dexterm doctor` prints the exact command. Without a key the holders panel shows count + top-10% via Jupiter.' },
@@ -194,7 +200,10 @@ const TOPICS = [
         body: '`config.keymap` in `~/.dexterm/config.json` re-binds actions to keys; `dexterm keymap [screen]` shows the effective bindings including your overrides. Reserved keys (ctrl+c, esc, enter, y, !) and the confirm/dismiss/panic/quit actions cannot be rebound, and collisions refuse the whole keymap.' },
     { id: 'paper-trade', title: 'Paper trade a coin', screen: 'token', tags: ['paper', 'trade', 'buy', 'sell', 'ticket', 'simulate', 'practice'],
         actions: [{ action: 'trade.buy', screen: 'token' }, { action: 'trade.sell', screen: 'token' }], feature: 'paper-ticket',
-        body: 'Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The analyst can open a PAPER ticket but can never size, confirm or send it.' },
+        body: 'Press `B` / `S` on the token screen to open a PAPER buy/sell ticket in its editing phase. dexterm holds no keys and signs nothing — paper trading is a simulation. Confirming a ticket needs your explicit keypress (the gate); a stray key never confirms. The in-app analyst can open a PAPER ticket but can never size, confirm or send it. If you separately arm a mandate and enable agent paper trading, a connected agent can open, size, confirm and close PAPER trades inside your caps (never raising them, never signing) — see "Let an agent paper trade".' },
+    { id: 'agent-paper-trade', title: 'Let an agent paper trade', screen: 'all', tags: ['agent', 'mcp', 'paper', 'autonomous', 'experimental', 'confirm', 'close', 'simulated'],
+        flags: ['--agent-paper'], tools: ['paper_open_ticket', 'paper_size_ticket', 'paper_confirm', 'paper_close', 'paper_positions', 'paper_pnl'], feature: 'mcp',
+        body: 'Experimental, paper only, off by default. Arm a mandate yourself (its caps, by keypress), then start `dexterm --spectate-mcp --agent-paper <mandate-id>`: an agent connected through `dexterm mcp` can then open, size, confirm and close SIMULATED (paper) trades inside those caps with paper_open_ticket / paper_size_ticket / paper_confirm / paper_close, and read paper_positions / paper_pnl. The agent is untrusted: it can never sign, send a real transaction, touch keys, or raise a cap; its per-trade cap is a quarter of the mandate\'s, and a size over any cap is refused. Caps are re-read from your armed mandate on every call, so revoking it or the panic key stops the agent. Every call is journaled and shows in this terminal\'s agent activity; Ctrl+P pauses, Ctrl+K stops for the rest of the run, any key takes over, and quitting turns it off. Figures are simulated and are not a result.' },
     { id: 'run-doctor', title: 'Diagnose problems with doctor', screen: 'all', tags: ['doctor', 'diagnose', 'check', 'troubleshoot', 'broken', 'fix', 'problem'],
         commands: ['doctor'], feature: 'doctor',
         body: '`dexterm doctor` is the first stop for any problem: non-interactive, never touches your keys, exits 0 when dexterm will run and 1 when something must be fixed. Every non-pass line prints the exact fix. `dexterm doctor --offline` skips the network probes.' },
@@ -223,9 +232,9 @@ const TOPICS = [
     { id: 'connect-an-agent-registry', title: 'Manage connected agents (dexterm agent)', screen: 'all', tags: ['agent', 'agents', 'registry', 'tier', 'pause', 'resume', 'kick', 'audit', 'bus', 'serve'],
         commands: ['agent'], feature: 'mcp',
         body: '`dexterm agent add|list|rotate|remove|tier|pause|resume|kick|audit|packs` manages your bring-your-own-agent registry and the loopback bus; `dexterm agent serve` runs a standalone bus on fixtures and `connect` attaches one. Every agent is untrusted and read-only: it can never sign, arm, raise a cap, touch keys or change network settings.' },
-    { id: 'spectate-an-agent', title: 'Watch an agent drive dexterm (dexterm spectate)', screen: 'all', tags: ['spectate', 'spectator', 'watch', 'agent', 'cook', 'observe', 'replay', 'stream', 'record'],
-        commands: ['spectate'], flags: ['--replay'], feature: 'spectator',
-        body: '`dexterm spectate --replay FILE` replays a saved agent session so you can watch what an agent did step by step; `dexterm spectate --info` shows the live read-only, token-gated, loopback spectator stream. The stream is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act.' },
+    { id: 'spectate-an-agent', title: 'Watch an agent drive dexterm (dexterm spectate)', screen: 'all', tags: ['spectate', 'spectator', 'watch', 'agent', 'cook', 'observe', 'replay', 'stream', 'record', 'mcp', 'follow'],
+        commands: ['spectate'], flags: ['--replay', '--spectate-mcp'], feature: 'spectator',
+        body: 'Watch an agent work. For an agent on the loopback bus, `dexterm agent serve --spectator-popup` opens the AGENT ACTIVITY window, `--spectate` starts the read-only, token-gated, loopback stream, and `--record FILE` saves a redacted session. For an agent connected over MCP (`dexterm mcp install`), run the app with `dexterm --spectate-mcp`: the running terminal then follows the agent — a navigation call moves the screen, a status line shows `agent <name>: opened <coin>`, ctrl+p pauses, ctrl+k stops and any key you press takes control. `dexterm spectate --replay FILE` replays a saved session step by step and `dexterm spectate --info` shows the live stream endpoint. Every shared copy is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act. Full docs: https://dexterm.xyz/docs/spectator/' },
     { id: 'recorder-history', title: 'Work with the history recorder (dexterm recorder)', screen: 'all', tags: ['recorder', 'record', 'history', 'stats', 'label', 'prune', 'outcomes', 'database', 'session', 'capture', 'data'],
         commands: ['recorder'], flags: ['--record', '--no-recorder'], feature: 'recorder',
         body: '`dexterm recorder stats|label|prune|export` works with the local history recorder\'s tables (the outcome-labelled data the rug model and backtests learn from). No network. Recording is on by default; `--no-recorder` disables it for a run and `--record FILE` captures a data session to a file for replay.' },

package/dist/packages/cli/src/docs-kb-gen.js

@@ -0,0 +1,228 @@
+// dexterm — generator for the docs knowledge base (task-1420).
+//
+// Builds the `@dexterm/mcp` docs KB entries (assets/kb/docs/*.md) from EVERY page of the site's docs
+// (dexterm/site/content/docs/*.md), chunked by heading, so the analyst can answer from the docs and cite the
+// exact page section (https://dexterm.xyz/docs/<slug>#<anchor>). The app-help KB (app-help-gen.ts) stays the
+// authority for an exact key or command; these entries carry the docs' explanations and never a structured
+// key/command/flag/tool list (docs text is data: nothing in it becomes a key, a command or an action).
+//
+// The site is a sibling checkout (../site from the app root) that a public checkout does not have: `haveSite`
+// is false there, the drift test skips, and the committed entries still ship.
+//
+// Deterministic by construction: files in name order, no clock, no network, no writes here (the script does
+// that). The site's `{{placeholders}}` are filled from the app at site build time; they are NOT expanded here
+// (that would tie the KB to the app's current commit). `{{minNode}}` comes from site.json; the commit stamp
+// sentences are dropped; every other placeholder becomes a pointer to the docs page section.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** App root: packages/cli/src → up three. */
+const ROOT = path.resolve(HERE, '..', '..', '..');
+/** The site checkout next to the app (absent in a public checkout). `DEXTERM_SITE_DIR` overrides it. */
+export const SITE_DIR = process.env.DEXTERM_SITE_DIR || path.resolve(ROOT, '..', 'site');
+export const haveSite = fs.existsSync(path.join(SITE_DIR, 'content', 'docs'));
+/** Stamped into every generated entry; bump on a deliberate regenerate. */
+export const DOCS_GENERATED_DATE = '2026-10-16';
+export const DOCS_BASE_URL = 'https://dexterm.xyz';
+const SLUG_FILE = /^[a-z0-9][a-z0-9-]*\.md$/;
+const MAX_ID = 64;
+/** The site's heading slug (site/lib/html.mjs `slug`), applied to heading text without backticks. */
+export function siteSlug(s) {
+    return String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/** The site's frontmatter split (site/lib/pages/docs.mjs `frontMatter`): flat `key: value` lines. */
+function siteFrontMatter(src) {
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(src.replace(/\r/g, ''));
+    if (!m)
+        return { meta: {}, body: src };
+    const meta = {};
+    for (const line of m[1].split('\n')) {
+        const i = line.indexOf(':');
+        if (i > 0)
+            meta[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    return { meta, body: m[2] };
+}
+/** One frontmatter value on one line: no newlines, no leading/trailing quote the KB parser would strip. */
+function oneLine(s) {
+    return s.replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim().replace(/^"+|"+$/g, '');
+}
+/** Absolute URL for a docs link: `/docs/x/#a` → https://dexterm.xyz/docs/x#a, `#a` → this page. */
+export function docsUrl(href, pageUrl) {
+    if (/^https?:\/\//i.test(href))
+        return href;
+    if (href.startsWith('#'))
+        return `${pageUrl}${href}`;
+    if (!href.startsWith('/'))
+        return href;
+    const d = /^\/docs\/([a-z0-9-]+)\/?(#[a-z0-9-]+)?$/.exec(href);
+    if (d)
+        return `${DOCS_BASE_URL}/docs/${d[1]}${d[2] ?? ''}`;
+    return `${DOCS_BASE_URL}${href}`;
+}
+const HTML_TAG = /<\/?(?:kbd|code|a|em|strong|b|i|br|span|div|p|details|summary|table|thead|tbody|tr|td|th|img|ul|ol|li|sup|sub|small|figure|figcaption|hr)\b[^>]*>/gi;
+const TAG_STOP = new Set(['the', 'and', 'for', 'with', 'what', 'how', 'you', 'your', 'its', 'not', 'one', 'see', 'also', 'from', 'into', 'when', 'it', 'is', 'of', 'to', 'in', 'on', 'a', 'an', 'vs', 'by', 'or']);
+/** Prose → KB body: placeholders resolved, links made absolute, inline HTML tags dropped (code fences kept as-is). */
+function cleanBody(lines, ctx) {
+    const out = [];
+    let fence = false;
+    for (const raw of lines) {
+        let line = raw;
+        if (/^```/.test(line)) {
+            fence = !fence;
+            out.push(line);
+            continue;
+        }
+        if (!fence) {
+            // The commit-stamp sentences ("Generated against … at commit {{head}}.") describe the site build, not the app.
+            line = line.replace(/(^|(?<=[.!?]\s))[^.!?\n]*\{\{head(?:Date)?\}\}[^\n]*?[.!?](?=\s|$)\s*/g, '');
+            line = line.replace(/\[\[([^\]]+)\]\]/g, '`$1`'); // the site's [[key]] → <kbd> shorthand
+            line = line.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1');
+            line = line.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, text, href) => `${text} (${docsUrl(href, ctx.pageUrl)})`);
+            line = line.replace(HTML_TAG, '');
+        }
+        line = line.replace(/\{\{minNode\}\}/g, ctx.nodeMin ?? `(see ${ctx.sectionUrl})`);
+        line = line.replace(/\{\{[^}]*\}\}/g, `(generated from the app: see ${ctx.sectionUrl}; app-help has the exact keys and commands)`);
+        out.push(line.replace(/\s+$/, ''));
+    }
+    return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+function tagsFor(...texts) {
+    const out = [];
+    for (const t of texts) {
+        for (const w of t.replace(/`/g, '').toLowerCase().match(/[a-z0-9][a-z0-9-]+/g) ?? []) {
+            if (w.length < 3 || TAG_STOP.has(w) || out.includes(w))
+                continue;
+            out.push(w);
+        }
+    }
+    return out.slice(0, 12);
+}
+/** A KB id ≤ 64 chars (cut at a dash), unique within this run. */
+function uniqueId(base, used) {
+    let id = base;
+    if (id.length > MAX_ID) {
+        id = id.slice(0, MAX_ID);
+        const d = id.lastIndexOf('-');
+        if (d > 20)
+            id = id.slice(0, d);
+    }
+    let out = id, n = 2;
+    while (used.has(out)) {
+        const suf = `-${n++}`;
+        out = id.slice(0, MAX_ID - suf.length) + suf;
+    }
+    used.add(out);
+    return out;
+}
+/** Split a page into its intro + one section per h2/h3, with anchors exactly as the site renders them. */
+export function splitPage(body) {
+    const ids = new Set();
+    const uid = (text) => { const base = siteSlug(text.replace(/`/g, '')); let id = base, n = 2; while (ids.has(id))
+        id = `${base}-${n++}`; ids.add(id); return id; };
+    const lines = body.replace(/\r/g, '').split('\n');
+    const intro = [];
+    const sections = [];
+    let cur = intro;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^```/.test(line)) {
+            // a fenced block: copied whole, never scanned for headings (mirrors the site renderer)
+            cur.push(line);
+            for (i++; i < lines.length && !/^```/.test(lines[i]); i++)
+                cur.push(lines[i]);
+            if (i < lines.length)
+                cur.push(lines[i]);
+            continue;
+        }
+        if (/^<(?!kbd|code|a |em|strong)[a-z!]/.test(line)) {
+            // a raw HTML block (until a blank line): the site does not read headings inside it either
+            for (; i < lines.length && lines[i].trim(); i++)
+                cur.push(lines[i]);
+            i--;
+            continue;
+        }
+        const h = /^(#{1,4})\s+(.+?)\s*(?:\{#([a-z0-9-]+)\})?$/.exec(line);
+        if (h) {
+            const level = h[1].length;
+            const anchor = h[3] ? (ids.add(h[3]), h[3]) : uid(h[2]);
+            if (level === 2 || level === 3) {
+                const s = { level, heading: h[2].replace(/`/g, ''), anchor, lines: [] };
+                sections.push(s);
+                cur = s.lines;
+                continue;
+            }
+            cur.push(line); // h1/h4 stay inside their section as text
+            continue;
+        }
+        cur.push(line);
+    }
+    return { intro, sections };
+}
+/** Every docs page file (name order), or [] when the site is absent. */
+export function docsPages(siteDir = SITE_DIR) {
+    const dir = path.join(siteDir, 'content', 'docs');
+    try {
+        return fs.readdirSync(dir).filter((f) => SLUG_FILE.test(f)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Build every docs KB entry from the site's docs pages. Throws when the site has no docs directory. */
+export function buildDocsEntries(siteDir = SITE_DIR) {
+    const dir = path.join(siteDir, 'content', 'docs');
+    if (!fs.existsSync(dir))
+        throw new Error(`no site docs at ${dir} (the site checkout is not next to the app)`);
+    let nodeMin = null;
+    try {
+        nodeMin = String(JSON.parse(fs.readFileSync(path.join(siteDir, 'site.json'), 'utf8')).nodeMin ?? '') || null;
+    }
+    catch { /* no site.json */ }
+    const out = [];
+    const used = new Set();
+    for (const file of docsPages(siteDir)) {
+        const slug = file.slice(0, -3);
+        const { meta, body } = siteFrontMatter(fs.readFileSync(path.join(dir, file), 'utf8'));
+        const pageTitle = oneLine(meta.title || slug);
+        const description = oneLine(meta.description || '');
+        const pageUrl = `${DOCS_BASE_URL}/docs/${slug}`;
+        const { intro, sections } = splitPage(body);
+        const entry = (heading, anchor, lines, parent) => {
+            const url = anchor ? `${pageUrl}#${anchor}` : pageUrl;
+            let text = cleanBody(lines, { pageUrl, sectionUrl: url, nodeMin });
+            if (!anchor && description)
+                text = text ? `${description}\n\n${text}` : description;
+            if (!text)
+                return;
+            const head = oneLine(heading);
+            const title = head ? `${pageTitle} › ${parent ? `${oneLine(parent)} › ` : ''}${head}` : pageTitle;
+            const id = uniqueId(anchor ? `docs-${slug}-${anchor}` : `docs-${slug}`, used);
+            const fmo = [
+                ['id', id], ['title', title], ['kind', 'docs'], ['page', slug], ['page_title', pageTitle],
+                ['heading', head], ['anchor', anchor], ['url', url],
+                ['tags', ['docs', slug, ...tagsFor(head, parent ?? '', pageTitle).filter((t) => t !== slug && t !== 'docs')]],
+                ['confidence', 'high'], ['owner', 'maintainers'], ['origin', 'docs-generated'],
+                ['reviewed_by', `generated@${DOCS_GENERATED_DATE}`],
+                ['generated_from', 'dexterm/site content/docs (task-1420)'],
+                ['sources', [`site/content/docs/${file}`]],
+                ['date', DOCS_GENERATED_DATE],
+            ];
+            const frontmatter = {};
+            for (const [k, v] of fmo)
+                if (v !== '' && !(Array.isArray(v) && v.length === 0))
+                    frontmatter[k] = v;
+            out.push({ id, frontmatter, body: text });
+        };
+        entry('', '', intro, null);
+        let h2 = null;
+        for (const s of sections) {
+            if (s.level === 2)
+                h2 = s.heading;
+            entry(s.heading, s.anchor, s.lines, s.level === 3 ? h2 : null);
+        }
+    }
+    out.sort((a, b) => a.id.localeCompare(b.id));
+    return out;
+}

package/dist/packages/cli/src/doctor.js

@@ -17,13 +17,22 @@ import { XTokenStore } from '../../data/src/index.js';
 import { SayTts, voiceDoctor, resolveVoice, WHISPER_MODEL, resolvePiperRuntime, pickPlayer, PIPER_MODEL } from '../../voice/src/index.js';
 import { loadConfig, dextermHome } from '../../custom/src/index.js';
 import { kbStore, skillStore } from "./kb-skill-cmd.js";
+import { analystCliOnPath, CODEX_MIN_VERSION, parseEngineChoice, resolveEngine, versionAtLeast } from "./analyst/codex.js";
 /** The minimum Node that runs dexterm (type-stripping of the .ts entry needs 22.18). */
 export const MIN_NODE = [22, 18, 0];
-/** Cheap PATH lookup (no spawn) for the voice probe. */
-function onPath(bin) {
-    for (const p of (process.env.PATH ?? '').split(':'))
-        if (p && existsSync(join(p, bin)))
-            return true;
+/** Cheap PATH lookup (no spawn). Windows (task-1423): PATH is `;`-separated and commands carry an extension
+ *  (`claude.cmd` from npm, `claude.exe` from the native installer), so try the PATHEXT list there. */
+export function onPath(bin, env = process.env, platform = process.platform) {
+    const win = platform === 'win32';
+    // Windows file names are case-insensitive; lower-case keeps the lookup exact on the case-sensitive test hosts
+    const exts = win ? ['', ...(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').toLowerCase().split(';').filter(Boolean)] : [''];
+    for (const p of (env.PATH ?? env.Path ?? '').split(win ? ';' : ':')) {
+        if (!p)
+            continue;
+        for (const ext of exts)
+            if (existsSync(join(p, bin + ext)))
+                return true;
+    }
     return false;
 }
 /**
@@ -104,7 +113,12 @@ export async function livingProbe(url, timeoutMs = 4000) {
     }
 }
 /** Default claude probe: spawn `claude --version` with a timeout. Presence only (login is not asserted here). */
-export async function claudeProbe(timeoutMs = 4000) {
+export async function claudeProbe(timeoutMs = 4000, platform = process.platform, env = process.env) {
+    // Windows (task-1423): answer from PATH without a spawn, and count only what the analyst's shell-less spawn can
+    // start: `claude.exe` / `.com` (the native installer). An npm `claude.cmd` alone is 'missing', because the
+    // analyst cannot run it, so "found on PATH" would be a false pass.
+    if (platform === 'win32')
+        return onPath('claude', { ...env, PATHEXT: '.EXE;.COM' }, platform) ? 'present' : 'missing';
     const { execFile } = await import('node:child_process');
     return new Promise((resolve) => {
         let done = false;
@@ -128,6 +142,32 @@ export async function claudeProbe(timeoutMs = 4000) {
         }
     });
 }
+/**
+ * Default codex probe (0.1.5): PATH (spawnable form only), then `codex --version` and `codex login status`. The
+ * status command is the user's own CLI reporting on its own login; dexterm never reads the credential itself.
+ */
+export async function codexProbe(timeoutMs = 4000, env = process.env) {
+    if (!analystCliOnPath('codex', env))
+        return { state: 'missing' };
+    const { execFile } = await import('node:child_process');
+    const run = (args) => new Promise((resolve) => {
+        try {
+            const child = execFile('codex', args, { timeout: timeoutMs, env }, (err, stdout, stderr) => {
+                const code = err ? (typeof err.code === 'number' ? err.code : null) : 0;
+                resolve({ code, out: `${stdout ?? ''}${stderr ?? ''}` });
+            });
+            child.on('error', () => resolve({ code: null, out: '' }));
+        }
+        catch {
+            resolve({ code: null, out: '' });
+        }
+    });
+    const v = await run(['--version']);
+    const version = /(\d+\.\d+\.\d+[\w.-]*)/.exec(v.out)?.[1] ?? null;
+    const st = await run(['login', 'status']);
+    const loggedIn = st.code === 0 ? !/not logged in/i.test(st.out) : st.code === null ? null : false;
+    return { state: 'present', version, loggedIn };
+}
 /** Default writable check: create the directory, write and remove a temp file. Returns an error message or null. */
 export function writableProbe(dir) {
     try {
@@ -149,6 +189,8 @@ export function defaultDeps(env = process.env, isTTY = process.stdout.isTTY ===
         nodeVersion: process.versions.node,
         platform: process.platform,
         claude: () => claudeProbe(),
+        codex: () => codexProbe(4000, env),
+        analystEngine: env.DEXTERM_ANALYST_ENGINE ?? loadConfig(dextermHome(env)).config.analyst?.engine ?? null,
         probe: (url) => livingProbe(url),
         checkWritable: writableProbe,
         offline: env.DEXTERM_OFFLINE === '1' || env.DEXTERM_OFFLINE === 'true',
@@ -217,11 +259,20 @@ export async function runDoctor(deps) {
     }
     // 3. Claude CLI (the analyst). Not required to browse; required for the `a` analyst.
     const claude = await deps.claude();
-    if (claude === 'missing') {
+    // 0.1.5: codex is the optional second engine; a missing claude is fine when codex can run the analyst.
+    const codex = deps.codex ? await deps.codex() : null;
+    const codexUsable = codex?.state === 'present';
+    if (claude === 'missing' && codexUsable) {
+        checks.push({
+            name: 'Claude CLI', status: 'pass',
+            detail: 'not found on PATH (optional now): the analyst runs on your codex CLI instead',
+        });
+    }
+    else if (claude === 'missing') {
         checks.push({
             name: 'Claude CLI', status: 'warn',
             detail: 'not found on PATH; the analyst (a) is disabled, the rest of dexterm works',
-            fix: 'Install Claude Code (https://claude.com/claude-code) and run `claude` once to log in.',
+            fix: 'Install Claude Code (https://claude.com/claude-code) and run `claude` once to log in, or use Codex: `npm i -g @openai/codex && codex login`.',
         });
     }
     else {
@@ -230,6 +281,24 @@ export async function runDoctor(deps) {
             detail: 'found on PATH (the analyst runs your local `claude`; log in once with `claude` if the analyst errors)',
         });
     }
+    // 3b. Codex CLI (0.1.5): optional second analyst engine, the user's own codex login. Read-only lock needs >= CODEX_MIN_VERSION.
+    if (codex) {
+        const choice = parseEngineChoice(deps.analystEngine) ?? 'auto';
+        const engine = resolveEngine(choice, (b) => b === 'claude' ? claude !== 'missing' : codexUsable);
+        const eng = `analyst engine: ${engine}${choice === 'auto' ? ' (auto)' : ''}`;
+        if (codex.state === 'missing') {
+            checks.push({ name: 'Codex CLI', status: engine === 'codex' ? 'warn' : 'pass', detail: `not installed (optional second analyst engine) · ${eng}`, ...(engine === 'codex' ? { fix: 'npm i -g @openai/codex && codex login, or set analyst.engine to claude' } : {}) });
+        }
+        else if (codex.version && !versionAtLeast(codex.version, CODEX_MIN_VERSION)) {
+            checks.push({ name: 'Codex CLI', status: 'warn', detail: `codex-cli ${codex.version} is older than ${CODEX_MIN_VERSION}; the read-only analyst lock needs ${CODEX_MIN_VERSION}+ · ${eng}`, fix: 'npm i -g @openai/codex@latest' });
+        }
+        else if (codex.loggedIn === false) {
+            checks.push({ name: 'Codex CLI', status: 'warn', detail: `found${codex.version ? ` (codex-cli ${codex.version})` : ''}, not logged in · ${eng}`, fix: 'codex login' });
+        }
+        else {
+            checks.push({ name: 'Codex CLI', status: 'pass', detail: `found${codex.version ? ` (codex-cli ${codex.version})` : ''}${codex.loggedIn ? ', logged in' : ''}; runs the analyst read-only on your own codex login (/engine codex) · ${eng}` });
+        }
+    }
     // 4b. Login with X (optional, task-1357): the user's own X app + login unlock X posts in the SOCIAL panel / TRENDING.
     {
         const xs = new XTokenStore({ env: deps.env });
@@ -237,8 +306,10 @@ export async function runDoctor(deps) {
         const modes = xs.modes();
         const clientId = xs.clientId(deps.env);
         if (meta.loggedIn) {
+            const windows = deps.platform === 'win32';
             const loose = (modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700);
-            checks.push({ name: 'Login with X', status: loose ? 'warn' : 'pass', detail: `logged in${meta.user ? ` as @${meta.user.username}` : ''} · scopes ${meta.scopes.join(' ') || '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no'}${loose ? ' · token file permissions are looser than 0600' : ''}`, ...(loose ? { fix: `chmod 700 ${xs.dir} && chmod 600 ${xs.tokensPath}` } : {}) });
+            const warning = windows ? ' · Windows ACL isolation is not verified' : loose ? ' · token file permissions are looser than 0600' : '';
+            checks.push({ name: 'Login with X', status: windows || loose ? 'warn' : 'pass', detail: `logged in${meta.user ? ` as @${meta.user.username}` : ''} · scopes ${meta.scopes.join(' ') || '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no'}${warning}`, ...(windows ? { fix: 'Review the token directory Security permissions in Windows; chmod does not enforce owner-only ACLs.' } : loose ? { fix: `chmod 700 ${xs.dir} && chmod 600 ${xs.tokensPath}` } : {}) });
         }
         else if (clientId) {
             checks.push({ name: 'Login with X', status: 'warn', detail: 'client id stored, not logged in — X posts stay off (keyless venues, news and on-chain rows still work)', fix: 'dexterm x login' });

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

@@ -1,7 +1,7 @@
 // dexterm — library surface of the CLI package (used by tests and tools).
 export * from "./state.js";
 export * from "./fixtures.js";
-export { parseArgs, stateFromArgs, applyScreenerArgs, applyEffectArgs, applyAction, applyAnalystAction, applyKey, colorDepthFor, intensityFor, asciiRainFor, fpsFor, demoEvent, main, interactive, terminalGuard, describeError, buildScreenState, HELP, LIVE_REFRESH_MS, FPS_BY_INTENSITY, MAX_FPS, DEMO_KEYS, } from "./main.js";
+export { parseArgs, stateFromArgs, applyScreenerArgs, applyEffectArgs, applyAction, applyAnalystAction, applyFollowNav, applyKey, colorDepthFor, intensityFor, asciiRainFor, fpsFor, demoEvent, main, interactive, terminalGuard, describeError, buildScreenState, HELP, LIVE_REFRESH_MS, FPS_BY_INTENSITY, MAX_FPS, DEMO_KEYS, } from "./main.js";
 export { AnalystSession, parseResults, parseFilterApplied } from "./analyst/session.js";
 export { resolveAnalystResults } from "./analyst/results.js";
 export { runAnalyst, buildArgv, turnPrompt, analystContextBlock, untrusted, ASSETS as ANALYST_ASSETS, MCP_BIN } from "./analyst/backend.js";

package/dist/packages/cli/src/kb-skill-cmd.js

@@ -66,6 +66,9 @@ function openEditor(io, file) {
     const ed = (io.env.VISUAL || io.env.EDITOR || '').trim();
     if (!ed || io.isTTY === false)
         return 'no-editor';
+    // task-1423: Windows has no /bin/sh, so the spawn below always failed there; print the path to edit instead
+    if ((io.platform ?? process.platform) === 'win32')
+        return 'no-editor';
     // `sh -c '$EDITOR "$1"'` so an EDITOR with arguments ("code -w") works; the path is passed as $1, never interpolated.
     const r = spawnSync('/bin/sh', ['-c', `${ed} "$1"`, 'sh', file], { stdio: 'inherit', env: io.env });
     return r.status === 0 ? 'edited' : 'failed';