dexterm-cli 0.1.2 → 0.1.4

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

@@ -14,16 +14,24 @@ import { shellBinaryPath } from '../../popup/src/index.js';
 import { detectColorDepth, protocolFromEnv } from '../../tui/src/index.js';
 import { resolveRpcUrl, defaultDbPath } from '../../data/src/index.js';
 import { XTokenStore } from '../../data/src/index.js';
-import { SayTts, voiceDoctor, resolveVoice, WHISPER_MODEL, resolvePiperBin, pickPlayer, PIPER_MODEL } from '../../voice/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";
 /** 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;
 }
 /**
@@ -42,10 +50,11 @@ export async function defaultVoiceProbe(platform = process.platform, configuredV
     const resolvedStt = swiftcPresent ? 'apple' : (whisperBinPresent && whisperModelPresent && micToolPresent) ? 'whisper' : null;
     // espeak-ng is the baseline portable speech-out engine off macOS.
     const espeakPresent = platform !== 'darwin' && (onPath('espeak-ng') || onPath('espeak'));
-    // Piper is the preferred neural speech-out engine off macOS (task-1408): binary + voice model + a player.
-    const piperPresent = platform !== 'darwin' && resolvePiperBin() !== null;
-    const piperVoicePresent = platform !== 'darwin' && existsSync(PIPER_MODEL);
-    const playerName = platform !== 'darwin' ? pickPlayer() : null;
+    // Piper is the preferred neural speech-out engine EVERYWHERE (task-1408, task-1416): a runtime (the
+    // prebuilt binary off macOS, the managed venv on macOS) + the voice model + a player (afplay on macOS).
+    const piperPresent = resolvePiperRuntime() !== null;
+    const piperVoicePresent = existsSync(PIPER_MODEL);
+    const playerName = pickPlayer();
     // task-1393: show which voice will actually speak, and why — never a silent system/novelty voice.
     const r = sayAvailable ? resolveVoice({ configured: configuredVoice, installed: voices }) : { voice: null, reason: '' };
     return {
@@ -103,7 +112,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;
@@ -236,8 +250,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/follow-cmd.js

@@ -15,8 +15,11 @@
 // Helius key (keyless prints the fix) and reads public history. Secrets never print: the RPC URL stays inside the
 // data layer.
 import { createDataLayer, resolveRpcUrl, HeliusHistory } from '../../data/src/index.js';
-import { FollowStore, WalletTracker, defaultFollowsPath, isWalletAddress, shortAddr, CopyAuto, defaultCopyJournalPath, AUTO_HARD, autoSizeCap } from '../../data/src/trade/copy/index.js';
+import { FollowStore, WalletTracker, defaultFollowsPath, isWalletAddress, shortAddr, fmtHoldMs, CopyAuto, defaultCopyJournalPath, AUTO_HARD, autoSizeCap, buildMirror, leaderSoldSince } from '../../data/src/trade/copy/index.js';
 import { PlanService, defaultPlansJournalPath } from '../../data/src/trade/plans/index.js';
+import { CopyLive } from "./live/copy.js";
+/** Default per-mirror cap for the headless path (same as the TUI's MIRROR_DEFAULT_CAP_USD); overridable with --cap. */
+export const FOLLOW_MIRROR_DEFAULT_CAP_USD = 20;
 function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
 function has(rest, name) { return rest.includes(name); }
 const USAGE = `dexterm follow <command>
@@ -25,6 +28,9 @@ const USAGE = `dexterm follow <command>
   list [--json]
   stats <addr> [--json]            one Helius history fetch: trades, FIFO realised PnL, win rate (hidden under n=10)
   trades <addr> [--limit N]        the decoded swaps behind the stats
+  mirror <addr> [--cap USD] [--k X] [--propose] [--json]
+                                   preview a MIRROR TICKET from this wallet's latest BUY (checks + size);
+                                   --propose writes it as an INERT order plan (arm only in the app, keypress/Phantom gate)
   purge --yes                      delete every follow and label
   auto <addr> [--per-trade USD] [--daily USD] [--max-open N] [--cooldown SEC] [--k X] [--disarm N] [--off]
                                    draft the auto-mirror caps (always OFF here: enabling is a keypress in the app, U then A,
@@ -35,7 +41,9 @@ function fmtStats(s) {
         `${shortAddr(s.wallet)}  ${s.trades} trades (${s.buys} buys · ${s.sells} sells · ${s.transfers} transfers) over ${s.mints} mints · ${s.sample.note}`,
         `realised ${s.realisedSol >= 0 ? '+' : ''}${s.realisedSol.toFixed(4)} SOL${s.realisedUsd !== null ? ` (${s.realisedUsd >= 0 ? '+' : ''}$${s.realisedUsd.toFixed(2)} at $${s.solUsdAt}/SOL now)` : ' (no SOL price: USD not shown)'} · FIFO over fetched history, fees and tips included`,
         `win rate ${s.winRate === null ? '—' : `${(s.winRate * 100).toFixed(0)}%`} · ${s.winRateNote} · open positions ${s.open}`,
+        `hold time ${fmtHoldMs(s.holdMedianMs)} · ${s.holdNote}`,
         `early-entry score ${s.earlyEntry.score === null ? '—' : s.earlyEntry.score.toFixed(2)} · ${s.earlyEntry.note}`,
+        `source ${s.sample.source}${s.sample.asOf ? ` · as of ${new Date(s.sample.asOf).toISOString().replace('T', ' ').slice(0, 19)} (${Math.max(0, Math.round((Date.now() - s.sample.asOf) / 1000))}s ago)` : ' · not fetched yet'}`,
     ];
     for (const p of s.positions.slice(0, 12))
         out.push(`  ${shortAddr(p.mint)}  ${p.closed ? 'closed' : 'open  '}  realised ${p.realisedSol >= 0 ? '+' : ''}${p.realisedSol.toFixed(4)} SOL  ${p.buys}b/${p.sells}s${p.flagged ? '  (cost-0 lot: airdrop/transfer/unpriced leg)' : ''}`);
@@ -209,6 +217,104 @@ export async function runFollow(rest, io, over = {}) {
                 dl?.close();
             }
         }
+        // task-1400 Tier 2 (headless): the one-key MIRROR TICKET from a shell. Reuses the exact TUI path — poll the
+        // tracker, take the wallet's latest BUY alert, resolve its market, run buildMirror. --propose writes the result
+        // as an INERT `proposed` order plan through PlanService; it is armable ONLY through the app's keypress / Phantom
+        // gate. There is no arm/sign/execute path in this command (the plan engine refuses to arm without a gesture and
+        // an armed mandate), so a pipe or an agent calling `follow mirror --propose` can never trade.
+        case 'mirror': {
+            const addr = rest[1];
+            if (!isWalletAddress(addr)) {
+                errOut('usage: dexterm follow mirror <addr> [--cap USD] [--k X] [--propose] [--json]');
+                return 2;
+            }
+            if (!store.has(addr)) {
+                errOut(`dexterm follow mirror: ${shortAddr(addr)} is not followed (dexterm follow add <addr> first)`);
+                return 1;
+            }
+            const capUsd = flag(rest, '--cap') ? Number(flag(rest, '--cap')) : FOLLOW_MIRROR_DEFAULT_CAP_USD;
+            if (!(capUsd > 0)) {
+                errOut('dexterm follow mirror: --cap needs a USD number > 0');
+                return 2;
+            }
+            const kRaw = flag(rest, '--k');
+            const k = kRaw ? Number(kRaw) : undefined;
+            if (kRaw !== undefined && !(k > 0)) {
+                errOut('dexterm follow mirror: --k needs a number > 0');
+                return 2;
+            }
+            let dl = null;
+            let history;
+            if (over.history !== undefined)
+                history = over.history;
+            else {
+                const rpc = resolveRpcUrl({ env: io.env });
+                if (rpc.provider !== 'helius')
+                    history = null;
+                else {
+                    dl = createDataLayer({ rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
+                    history = dl.rpcPool.heliusUrl ? new HeliusHistory(dl.http, dl.rpcPool.heliusUrl) : null;
+                }
+            }
+            try {
+                const copy = new CopyLive(dl, { followsPath: null, history, solUsd: () => over.solUsd ?? null, ...(over.clock ? { clock: over.clock } : {}) });
+                copy.store.add(addr);
+                if (copy.status().state === 'unavailable') {
+                    errOut(`dexterm follow mirror: ${copy.status().why}`);
+                    return 1;
+                }
+                await copy.tracker.pollOnce();
+                const after = copy.status();
+                if (after.state === 'degraded') {
+                    errOut(`dexterm follow mirror: ${after.why}`);
+                    return 1;
+                }
+                // Prefer a live "news" buy alert (a buy the tracker saw AFTER priming). A one-shot shell call primes and
+                // sees the history in a single poll, so there is usually no news alert yet; fall back to the latest BUY in
+                // the fetched history, synthesising the same CopyAlert shape and captioning it as history, not live news.
+                let alert = copy.alerts(200).find((a) => a.wallet === addr && a.trade.side === 'buy');
+                let fromHistory = false;
+                if (!alert) {
+                    const lastBuy = copy.trades(addr).filter((t) => t.side === 'buy').sort((a, b) => b.slot - a.slot || b.sig.localeCompare(a.sig))[0];
+                    if (!lastBuy) {
+                        out(`no BUY from ${shortAddr(addr)} in the fetched history (nothing to mirror)`);
+                        return 0;
+                    }
+                    alert = { id: `copy_hist_${lastBuy.sig.slice(0, 12)}`, t: copy.now(), wallet: addr, name: store.get(addr)?.name ?? null, trade: lastBuy, lagMs: lastBuy.tKnown ? Math.max(0, copy.now() - lastBuy.t) : null };
+                    fromHistory = true;
+                }
+                const market = over.mirrorMarket ? await over.mirrorMarket(alert.trade.mint) : await copy.mirrorMarket(alert.trade.mint);
+                const soldSince = leaderSoldSince(alert, copy.trades(addr));
+                // No wallet-intel scan from a shell: the leader's dev-cluster / holdings stay unknown (shown as such).
+                const result = buildMirror(alert, { now: copy.now(), capUsd, k, market, leaderSoldSince: soldSince, leaderIntel: null });
+                if (has(rest, '--json')) {
+                    out(JSON.stringify(result));
+                    return result.ok ? 0 : 1;
+                }
+                out(`mirror of ${shortAddr(addr)}'s latest BUY — ${shortAddr(alert.trade.mint)}${market.symbol ? ` (${market.symbol})` : ''}${fromHistory ? ' · from fetched history (not a live alert)' : ' · live alert'}`);
+                for (const c of result.checks)
+                    out(`  ${c.ok === true ? 'ok ' : c.ok === false ? 'NO ' : '?  '} ${c.name.padEnd(12)} ${c.detail}`);
+                if (!result.ok) {
+                    errOut(`refused: ${result.reason} — ${result.message}`);
+                    return 1;
+                }
+                out(`  size $${result.sizeUsd.toFixed(2)} = ${result.sizeWhy}`);
+                if (!has(rest, '--propose')) {
+                    out('preview only · add --propose to write the inert plan (then arm it in the app: O screen, hold a — keypress/Phantom gate)');
+                    out('not a recommendation · a wallet\'s past fills say nothing about its next one');
+                    return 0;
+                }
+                const plans = new PlanService({ journalPath: over.plansJournalPath === undefined ? defaultPlansJournalPath(io.env) : over.plansJournalPath });
+                const plan = plans.propose(result.input, { supply: result.supply, by: 'copy', ref: result.ref });
+                out(`proposed ${plan.id} · ${plan.status.toUpperCase()} (${plan.side} ${plan.symbol} ≈ $${plan.sizeUsd.toFixed(2)}) · INERT — nothing is armed`);
+                out('arm it in the app: U → O (the plans screen), select it, hold a (keypress) or approve in Phantom · the gate stays on');
+                out('not a recommendation · a wallet\'s past fills say nothing about its next one');
+                return 0;
+            }
+            finally {
+                dl?.close();
+            }
+        }
         default:
             if (cmd) {
                 errOut(`dexterm follow: unknown subcommand ${JSON.stringify(cmd)}`);

package/dist/packages/cli/src/help-cmd.js

@@ -0,0 +1,48 @@
+// `dexterm help [topic]` (task-1413) — the app-help knowledge base from the command line, backed by the
+// same generated entries as the analyst's `app_help` MCP tool. No network, no model.
+//   dexterm help                 list the topics
+//   dexterm help export          show the best-matching topic (exact key/command + how-to)
+//   dexterm help screen token    multi-word query
+import { loadAppHelp, searchAppHelp, getAppHelp } from '../../mcp/src/index.js';
+function show(e, io) {
+    io.stdout.write(`\n${e.title}  (${e.id})\n`);
+    io.stdout.write(`${'─'.repeat(Math.min(60, e.title.length + e.id.length + 4))}\n`);
+    if (e.keys.length)
+        io.stdout.write(`Keys:     ${e.keys.join('  ')}\n`);
+    if (e.commands.length)
+        io.stdout.write(`Commands: ${e.commands.map((c) => `dexterm ${c}`).join('  ')}\n`);
+    if (e.flags.length)
+        io.stdout.write(`Flags:    ${e.flags.join('  ')}\n`);
+    io.stdout.write(`\n${e.body}\n`);
+}
+export function helpCommand(argv, io) {
+    const entries = loadAppHelp();
+    if (!entries.length) {
+        io.stderr.write('no app-help entries found\n');
+        return 1;
+    }
+    const query = argv.join(' ').trim();
+    if (!query) {
+        io.stdout.write('dexterm help <topic> — how the app works. Topics:\n\n');
+        for (const e of entries)
+            io.stdout.write(`  ${e.id.padEnd(26)} ${e.title}\n`);
+        io.stdout.write('\nExamples: dexterm help export · dexterm help voice speed · dexterm help screener\n');
+        return 0;
+    }
+    // Exact id wins; otherwise the best retrieval match, with near-misses listed.
+    const exact = getAppHelp(query.replace(/\s+/g, '-'), entries) ?? getAppHelp(query, entries);
+    if (exact) {
+        show(exact, io);
+        return 0;
+    }
+    const results = searchAppHelp(query, 5, entries);
+    if (!results.length) {
+        io.stdout.write(`No app-help topic matches "${query}". Run \`dexterm help\` to list topics.\n`);
+        return 1;
+    }
+    show(results[0], io);
+    if (results.length > 1) {
+        io.stdout.write(`\nRelated: ${results.slice(1).map((r) => r.id).join(', ')}\n`);
+    }
+    return 0;
+}

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';