nodedex 0.1.0

package/tui-dist/api.js

@@ -0,0 +1,197 @@
+// api.ts — read-only REST client for a running NodeDex server.
+// The TUI NEVER touches the DB; it only reads endpoints that already exist
+// (session, reflect/status, session/events, flags, blocks). Every fetch is
+// failure-tolerant: a down/501 endpoint yields null, the rest still render.
+// Force IPv4 for the loopback host. On Windows, "localhost" resolves to IPv6 ::1
+// FIRST; servers bind IPv4 (127.0.0.1), so every localhost request pays a ~200ms
+// ::1-refused → IPv4-retry penalty — the TUI's lag (measured: localhost 0.21s vs
+// 127.0.0.1 0.001s per request). 127.0.0.1 also works when a server binds 0.0.0.0.
+export function prefer127(url) {
+    return url.replace(/\/\/localhost(?=[:/]|$)/i, "//127.0.0.1");
+}
+// The active server. Mutable so the Servers pane can switch which graph the
+// TUI reads at runtime (was a const — multi-server switching needs it live).
+let currentBase = prefer127((process.env.NODEDEX_TUI_API || "http://localhost:3001").replace(/\/$/, ""));
+// Per-server API tokens. A server launched with NODEDEX_API_TOKEN gates its WHOLE REST API,
+// so the TUI must send the token to read it. Keyed by normalized base url; setBase picks the
+// active one up automatically, so every connect path authenticates without extra plumbing.
+const tokenByBase = new Map();
+let currentToken = process.env.NODEDEX_TUI_TOKEN || "";
+export function registerToken(url, token) {
+    const u = prefer127(url.replace(/\/$/, ""));
+    if (token)
+        tokenByBase.set(u, token);
+    else
+        tokenByBase.delete(u);
+}
+function authHeaders(forUrl) {
+    const t = forUrl ? (tokenByBase.get(prefer127(forUrl.replace(/\/$/, ""))) || "") : currentToken;
+    return t ? { "x-nodedex-token": t } : {};
+}
+export function getBase() {
+    return currentBase;
+}
+export function setBase(url) {
+    currentBase = prefer127(url.replace(/\/$/, ""));
+    currentToken = tokenByBase.get(currentBase) || (process.env.NODEDEX_TUI_TOKEN || "");
+}
+async function getJSON(path, timeoutMs = 4000) {
+    try {
+        const r = await fetch(`${currentBase}${path}`, { headers: authHeaders(), signal: AbortSignal.timeout(timeoutMs) });
+        if (!r.ok)
+            return null;
+        return (await r.json());
+    }
+    catch {
+        return null;
+    }
+}
+// Probe an ARBITRARY url (not the active base) for a NodeDex server's identity —
+// used by server discovery. One cheap GET /api/session; short timeout so a dead
+// port fails fast.
+export async function probeServer(url) {
+    const base = prefer127(url.replace(/\/$/, ""));
+    try {
+        const r = await fetch(`${base}/api/session`, { headers: authHeaders(url), signal: AbortSignal.timeout(1200) });
+        if (r.ok) {
+            const j = (await r.json());
+            return { up: true, db: j.db, blocks: j.total_blocks };
+        }
+        // Responded but gated (token required, not supplied) → still confirm liveness via the
+        // always-open /api/health route, so a token-protected server shows UP (without its data).
+        if (r.status === 401 || r.status === 403) {
+            const h = await fetch(`${base}/api/health`, { signal: AbortSignal.timeout(1200) });
+            if (h.ok)
+                return { up: true };
+        }
+        return { up: false };
+    }
+    catch {
+        return { up: false }; // connection refused / timeout = genuinely down
+    }
+}
+// Fast poll — all LOCAL endpoints (no external calls), safe to hit every couple seconds.
+export async function fetchDashboard() {
+    const [session, reflect, eventsRes, agentFlagsRes, flagSummary, reviewRes, relatedRes, budget, passes, alertsRes] = await Promise.all([
+        getJSON("/api/session"),
+        getJSON("/api/reflect/status"),
+        getJSON("/api/session/events"),
+        getJSON("/api/flags/agent-pending"),
+        getJSON("/api/flags/summary"),
+        getJSON("/api/blocks/review-queue"),
+        getJSON("/api/roots/related"),
+        // budget hits OpenRouter only when a credit floor is set, and that fetch is
+        // cached ~60s server-side, so it's safe on the 2s poll.
+        getJSON("/api/usage/budget"),
+        getJSON("/api/usage/passes"),
+        getJSON("/api/alerts"),
+    ]);
+    const reads = Array.isArray(eventsRes?.events)
+        ? eventsRes.events.filter((e) => e?.type === "recall").slice(-8).reverse()
+        : [];
+    return {
+        ok: !!session || !!reflect,
+        base: currentBase,
+        fetchedAt: new Date(),
+        session,
+        reflect,
+        reads,
+        agentFlags: Array.isArray(agentFlagsRes?.flags) ? agentFlagsRes.flags : [],
+        flagSummary,
+        reviewQueue: Array.isArray(reviewRes?.blocks) ? reviewRes.blocks : [],
+        related: relatedRes,
+        budget,
+        passes,
+        alerts: Array.isArray(alertsRes?.alerts) ? alertsRes.alerts.slice(-20).reverse() : [],
+    };
+}
+export async function fetchConfig() {
+    return getJSON("/api/admin/config", 6000);
+}
+/** Persist a config patch (model/fallback/breaker). Applies live + writes .env. */
+export async function postConfig(patch) {
+    try {
+        const r = await fetch(`${currentBase}/api/admin/config`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...authHeaders() },
+            body: JSON.stringify(patch),
+            signal: AbortSignal.timeout(8000),
+        });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pause or resume the reflect pipeline (capture). */
+export async function setReflectPausedRemote(paused) {
+    try {
+        const r = await fetch(`${currentBase}/api/reflect/${paused ? "pause" : "resume"}`, {
+            method: "POST", headers: authHeaders(), signal: AbortSignal.timeout(6000),
+        });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function fetchTree() {
+    const r = await getJSON("/api/tree?depth=1");
+    return Array.isArray(r?.tree) ? r.tree : [];
+}
+export async function fetchProjectBlocks(projectLabel) {
+    const r = await getJSON(`/api/blocks?project=${encodeURIComponent(projectLabel)}&limit=500`);
+    return Array.isArray(r) ? r : [];
+}
+export async function searchMemory(q, limit = 6) {
+    if (!q.trim())
+        return [];
+    const r = await getJSON(`/api/search?q=${encodeURIComponent(q)}&limit=${limit}`);
+    return Array.isArray(r) ? r : [];
+}
+export async function fetchBlockDetail(id) {
+    return getJSON(`/api/blocks/${encodeURIComponent(id)}?detail=relations`);
+}
+// ─── Chains pane ─────────────────────────────────────────────────────────────
+// chain blocks (type:"chain") — content carries unique.arc + unique.conclusion
+export async function fetchChains() {
+    const r = await getJSON(`/api/blocks?type=chain&limit=200`);
+    return Array.isArray(r) ? r : [];
+}
+export async function fetchChainMembers(chainBlockId) {
+    const r = await getJSON(`/api/chains/${encodeURIComponent(chainBlockId)}`);
+    return Array.isArray(r?.blocks) ? r.blocks : [];
+}
+export async function fetchUnreviewedFlags() {
+    const r = await getJSON(`/api/flags?reviewed=false&limit=50`);
+    return Array.isArray(r?.flags) ? r.flags : [];
+}
+export async function fetchFlagDetail(id) {
+    return getJSON(`/api/flags/${encodeURIComponent(id)}`);
+}
+// the ONE write: POST a verdict (merge can execute: archive loser + wire
+// superseded_by). Returns the server's reply verbatim so errors surface in UI.
+export async function postFlagReview(id, body) {
+    try {
+        const r = await fetch(`${currentBase}/api/flags/${encodeURIComponent(id)}/review`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...authHeaders() },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(8000),
+        });
+        return (await r.json());
+    }
+    catch (e) {
+        return { error: String(e) };
+    }
+}
+// Slow poll — balance hits OpenRouter (external), so it runs on its own ~30s cadence.
+export async function fetchBalance() {
+    const b = await getJSON("/api/usage/balance", 8000);
+    if (!b || typeof b.remaining === "undefined")
+        return { remaining: null, available: false };
+    return { remaining: b.remaining, available: true };
+}
+// back-compat: a few callers imported BASE for display. getBase() is the live
+// value; this stays as the INITIAL base only.
+export const BASE = currentBase;

package/tui-dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+// cli.tsx — entry point. `npm run dev` (tsx) renders the app.
+import { useState } from "react";
+import { render } from "ink";
+import { App } from "./App.js";
+import { Onboarding } from "./onboarding.js";
+import { needsOnboarding } from "./config.js";
+// Own the terminal via the ALTERNATE SCREEN BUFFER (like vim / htop / less): the TUI
+// renders into a dedicated buffer with NO scrollback, so a frame taller than the
+// window — or a tab switch — can't push a copy of the UI up into shell history (the
+// "duplicate TUI on tab switch" bug). Pair with the height-pinned root in App.tsx so
+// every frame is the same height and ink repaints in place.
+//
+// CRITICAL: restore the user's normal screen on EVERY exit path. A process that exits
+// while still in the alt buffer leaves the shell looking broken. `process.on("exit")`
+// is the catch-all — it fires on normal unmount, on process.exit() (App's signal
+// handlers), and after ink's own Ctrl-C exit. It must be synchronous (a raw write is).
+const enterAltScreen = () => process.stdout.write("\x1b[?1049h\x1b[2J\x1b[H");
+const leaveAltScreen = () => process.stdout.write("\x1b[?1049l");
+enterAltScreen();
+process.on("exit", leaveAltScreen);
+// A crash (a render throw or an unhandled promise rejection) while the terminal is in
+// RAW MODE + the alt-screen buffer would otherwise leave it FROZEN — no input handler, so
+// q / Ctrl-C / esc all do nothing and you can't close it. Restore raw mode + the screen and
+// exit hard, so the user always gets their shell (and the error) back instead of a dead TUI.
+const crashOut = (label) => (err) => {
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode?.(false);
+    }
+    catch { /* */ }
+    try {
+        leaveAltScreen();
+    }
+    catch { /* */ }
+    try {
+        process.stderr.write(`\nNodedex TUI ${label}: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    }
+    catch { /* */ }
+    process.exit(1);
+};
+process.on("uncaughtException", crashOut("crashed"));
+process.on("unhandledRejection", crashOut("unhandled rejection"));
+// First run (no model configured yet) → the setup wizard, which starts a server and
+// hands off to the TUI. Otherwise, straight into the app. `--onboard` (npm run onboard)
+// FORCES the wizard even when already set up — to switch provider/model/db or re-run setup.
+const forceOnboard = process.argv.includes("--onboard");
+function Root() {
+    const [done, setDone] = useState(() => !forceOnboard && !needsOnboarding());
+    return done ? _jsx(App, {}) : _jsx(Onboarding, { onDone: () => setDone(true) });
+}
+render(_jsx(Root, {}));

package/tui-dist/components.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import Gradient from "ink-gradient";
+import { theme, glyph, fmtNum, fmtMoney } from "./theme.js";
+const WORDMARK = [
+    " ███╗   ██╗ ██████╗ ██████╗ ███████╗██████╗ ███████╗██╗  ██╗",
+    " ████╗  ██║██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝╚██╗██╔╝",
+    " ██╔██╗ ██║██║   ██║██║  ██║█████╗  ██║  ██║█████╗   ╚███╔╝ ",
+    " ██║╚██╗██║██║   ██║██║  ██║██╔══╝  ██║  ██║██╔══╝   ██╔██╗ ",
+    " ██║ ╚████║╚██████╔╝██████╔╝███████╗██████╔╝███████╗██╔╝ ██╗",
+    " ╚═╝  ╚═══╝ ╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚══════╝╚═╝  ╚═╝",
+].join("\n");
+const TAGLINE = "the memory your agent lives in";
+// Wordmark gradient — already the cool family (teal→sky→indigo).
+const MARK_COLORS = ["#5eead4", "#38bdf8", "#818cf8"];
+// Full logo — onboarding's welcome only. The running app uses <Brand/>.
+export function Logo() {
+    return (_jsxs(Box, { flexDirection: "column", alignItems: "center", children: [_jsx(Gradient, { colors: MARK_COLORS, children: _jsx(Text, { children: WORDMARK }) }), _jsx(Text, { color: theme.dim, italic: true, children: `◇  ${TAGLINE}  ◇` })] }));
+}
+// One-line brand for the app shell: wordmark-as-word, nothing shouting.
+export function Brand() {
+    return (_jsx(Box, { children: _jsx(Gradient, { colors: MARK_COLORS, children: _jsx(Text, { bold: true, children: " nodedex" }) }) }));
+}
+// The view switcher — plain text, the active view carries the accent.
+export function ViewBar({ views, active }) {
+    return (_jsx(Box, { children: views.map((v, i) => (_jsxs(Box, { marginRight: 1, children: [_jsx(Text, { color: i === active ? theme.accent : theme.dim, bold: i === active, children: `${i + 1} ${v}` }), i < views.length - 1 ? _jsx(Text, { color: theme.dim, children: "  ·" }) : null] }, v))) }));
+}
+// Caps section header — replaces bordered panels for in-flow content.
+export function Section({ title, hot, right, children }) {
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { color: hot ? theme.accent : theme.title, bold: true, children: title.toUpperCase() }), right ?? null] }), children] }));
+}
+// A selectable row: focused = accent cursor + bright text; blurred list keeps a
+// quiet cursor so pane focus is always legible.
+export function Row({ selected, focused = true, children }) {
+    return (_jsxs(Box, { children: [_jsx(Text, { color: selected ? (focused ? theme.accent : theme.dim) : undefined, children: selected ? "▸ " : "  " }), children] }));
+}
+// Bordered panel — kept for overlays (search, review) that float over a view.
+export function Panel({ title, children, hot, width, flexGrow, minHeight }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: hot ? theme.borderHot : theme.border, flexDirection: "column", paddingX: 1, width: width, flexGrow: flexGrow, minHeight: minHeight, children: [_jsx(Box, { marginTop: -1, children: _jsx(Text, { color: theme.title, children: ` ${title} ` }) }), children] }));
+}
+// The ONE home for connection / graph / pipeline / spend state — bottom line,
+// every view. Views must not repeat these numbers (one value, one home).
+export function StatusLine({ dash, balance, captureDots }) {
+    const ok = !!dash?.ok;
+    const s = dash?.session;
+    const r = dash?.reflect;
+    const spend24 = dash?.budget?.observed?.spend24h;
+    return (_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { color: ok ? theme.ok : theme.danger, children: `${glyph.up} ` }), _jsx(Text, { color: theme.value, children: s?.db ?? "no server" }), _jsx(Text, { color: theme.dim, children: `  ${fmtNum(s?.total_blocks)} blocks` }), r ? (_jsx(Text, { color: r.paused || r.spend_paused ? theme.warn : theme.dim, children: r.paused ? "  ‖ capture paused" : r.spend_paused ? "  ‖ spend paused" : r.queue_depth > 0 ? `  ⟳ extracting (${r.queue_depth})` : "" })) : null] }), _jsxs(Box, { marginLeft: 2, children: [captureDots.map((c) => (_jsxs(Box, { marginRight: 1, children: [_jsx(Text, { color: c.on ? theme.ok : theme.dim, children: glyph.up }), _jsx(Text, { color: theme.dim, children: ` ${c.name}` })] }, c.name))), typeof spend24 === "number" ? _jsx(Text, { color: theme.dim, children: ` ${fmtMoney(spend24)}/24h` }) : null, balance.available ? _jsx(Text, { color: theme.dim, children: `  bal ${fmtMoney(balance.remaining)}` }) : null] })] }));
+}
+// Viewport windowing for selectable lists: slides a cap-sized window so the
+// cursor stays visible (the fix for "cursor moves past the fold but the list
+// doesn't scroll"). Centers the selection where possible; callers render
+// `↑ N more / ↓ N more` from above/below.
+export function windowSlice(items, sel, cap) {
+    if (items.length <= cap)
+        return { visible: items, start: 0, above: 0, below: 0 };
+    const start = Math.min(Math.max(0, sel - Math.floor(cap / 2)), items.length - cap);
+    return { visible: items.slice(start, start + cap), start, above: start, below: items.length - start - cap };
+}
+// Bottom-of-view key hints. Quiet; the keycap carries the accent.
+export function Keys({ items }) {
+    return (_jsx(Box, { children: items.map(([k, label], i) => (_jsxs(Box, { marginRight: 2, children: [_jsx(Text, { color: theme.accent, children: `[${k}]` }), _jsx(Text, { color: theme.dim, children: ` ${label}` })] }, `${k}-${i}`))) }));
+}

package/tui-dist/config.js

@@ -0,0 +1,242 @@
+// config.ts — the onboarding config home (~/.nodedex/config.json).
+//
+// The TUI owns onboarding config here (user's decision); it is injected into any
+// server the TUI launches as env overrides (see servers.ts), so the secret never
+// lives in the git repo. This is also the natural seat for the forward-compat
+// auth/identity config later.
+//
+// Provider: OpenRouter (BYO key) — one platform for every model, spoken via the
+// server's openai-compatible path.
+import { homedir } from "os";
+import { resolve } from "path";
+import { mkdirSync, readFileSync, writeFileSync, readdirSync } from "fs";
+const NODEDEX_HOME = resolve(homedir(), ".nodedex");
+const CONFIG_FILE = resolve(NODEDEX_HOME, "config.json");
+export const DEFAULT_PORT = 3001;
+export const DEFAULT_DB = resolve(NODEDEX_HOME, "workspace.db");
+export const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+export const OPENROUTER_DEFAULT_MODEL = "google/gemini-2.5-flash";
+// Local / self-hosted default (Ollama). LM Studio = :1234/v1, vLLM = your host. Used by the
+// "Local / self-hosted" onboarding path — no API key, fully offline, $0.
+export const DEFAULT_LOCAL_BASE_URL = "http://localhost:11434/v1";
+export const RECOMMENDED_MODELS = [
+    { id: "google/gemini-2.5-flash-lite", label: "Gemini 2.5 Flash Lite", note: "recommended — cheapest, 1M ctx" },
+    { id: "google/gemini-2.5-flash", label: "Gemini 2.5 Flash", note: "cheap + capable" },
+    { id: "openai/gpt-4o-mini", label: "GPT-4o mini", note: "cheap, reliable" },
+];
+// Models that train on submitted prompts — used to warn the user that their inputs may
+// be used to improve the model. Matched case-insensitively as a substring so
+// provider-prefixed and bare ids both hit. ":free" catches OpenRouter free variants,
+// whose provider data policies generally allow prompt training.
+const TRAINS_ON_PROMPTS = ["owl-alpha", ":free"];
+export function isTrainsOnPrompts(model) {
+    const m = (model || "").toLowerCase();
+    return TRAINS_ON_PROMPTS.some((needle) => m.includes(needle));
+}
+/** Verify an OpenRouter key before saving — a typo fails here, not at first
+ *  extraction. GET /key returns the key's usage/limit for a valid key.
+ *  Shared by onboarding and the Health provider picker. */
+export async function validateOpenRouterKey(key) {
+    try {
+        const r = await fetch(`${OPENROUTER_BASE_URL}/key`, {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (r.ok)
+            return { ok: true };
+        if (r.status === 401)
+            return { ok: false, error: "Key rejected (401) — check it and try again." };
+        return { ok: false, error: `OpenRouter returned ${r.status}.` };
+    }
+    catch (e) {
+        return { ok: false, error: `Couldn't reach OpenRouter (${e?.message ?? e}).` };
+    }
+}
+export const DEFAULT_HERMES_SOURCES = ["tui"];
+/** Existing Nodedex DBs in ~/.nodedex (so the user can reuse one instead of a new graph). */
+export function listDbs() {
+    try {
+        return readdirSync(NODEDEX_HOME)
+            .filter((f) => f.endsWith(".db"))
+            .map((f) => ({ name: f.replace(/\.db$/, ""), path: resolve(NODEDEX_HOME, f) }));
+    }
+    catch {
+        return []; // home not created yet / unreadable → no existing DBs
+    }
+}
+/** Resolve a user-typed DB name to a ~/.nodedex/<name>.db path (sanitized). */
+export function dbPathForName(name) {
+    const safe = (name || "workspace").trim().replace(/[^a-z0-9_-]/gi, "-").replace(/^-+|-+$/g, "") || "workspace";
+    return resolve(NODEDEX_HOME, `${safe}.db`);
+}
+export function loadConfig() {
+    try {
+        return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(patch) {
+    const cfg = { ...loadConfig(), ...patch };
+    try {
+        mkdirSync(NODEDEX_HOME, { recursive: true });
+        writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+    }
+    catch {
+        /* read-only home → no persistence; the in-session launch env still works */
+    }
+}
+/** The current Hermes-capture config, with defaults filled in. */
+export function loadHermesCapture() {
+    const h = loadConfig().hermesCapture ?? {};
+    const sources = Array.isArray(h.sources) && h.sources.length ? h.sources.map(String) : [...DEFAULT_HERMES_SOURCES];
+    return {
+        // Default ON: capture should "just work" for a normal user. The watcher idles harmlessly
+        // when no Hermes state.db exists, and the user can turn it off in Settings (sets enabled:false).
+        enabled: h.enabled !== false,
+        sources,
+        pollMs: Number.isFinite(h.pollMs) && h.pollMs >= 500 ? h.pollMs : 4000,
+        stateDbPath: h.stateDbPath ?? "",
+    };
+}
+/** Patch the Hermes-capture block (nested merge — saveConfig is a shallow merge, so do it here). */
+export function setHermesCapture(patch) {
+    const current = loadConfig().hermesCapture ?? {};
+    saveConfig({ hermesCapture: { ...current, ...patch } });
+}
+/** The current Claude Code-capture config, with defaults filled in. */
+export function loadClaudeCapture() {
+    const c = loadConfig().claudeCapture ?? {};
+    const projects = Array.isArray(c.projects) && c.projects.length ? c.projects.map(String) : ["*"];
+    return {
+        // Default ON, same rationale as Hermes: the watcher idles harmlessly when no
+        // ~/.claude/projects exists; the onboarding capture step + Settings are the off switch.
+        enabled: c.enabled !== false,
+        projects,
+        pollMs: Number.isFinite(c.pollMs) && c.pollMs >= 1000 ? c.pollMs : 5000,
+        idleFlushMs: Number.isFinite(c.idleFlushMs) && c.idleFlushMs >= 15000 ? c.idleFlushMs : 120000,
+        projectsDir: c.projectsDir ?? "",
+    };
+}
+/** Patch the Claude Code-capture block (nested merge). */
+export function setClaudeCapture(patch) {
+    const current = loadConfig().claudeCapture ?? {};
+    saveConfig({ claudeCapture: { ...current, ...patch } });
+}
+export function scanCaptureHosts() {
+    const out = [];
+    // Hermes: the state.db the watcher reads.
+    const hermesDb = process.platform === "win32" && process.env.LOCALAPPDATA
+        ? resolve(process.env.LOCALAPPDATA, "hermes", "state.db")
+        : resolve(homedir(), ".local", "share", "hermes", "state.db");
+    let hermesFound = false;
+    try {
+        hermesFound = readdirSync(resolve(hermesDb, "..")).includes("state.db");
+    }
+    catch { /* absent */ }
+    out.push({ host: "hermes", label: "Hermes / Owl", found: hermesFound, detail: hermesFound ? "state.db present" : "not installed" });
+    // Claude Code: the transcripts dir.
+    const ccDir = resolve(homedir(), ".claude", "projects");
+    let projects = 0, sessions = 0;
+    try {
+        for (const d of readdirSync(ccDir, { withFileTypes: true })) {
+            if (!d.isDirectory())
+                continue;
+            let n = 0;
+            try {
+                n = readdirSync(resolve(ccDir, d.name)).filter((f) => f.endsWith(".jsonl")).length;
+            }
+            catch { /* skip */ }
+            if (n > 0) {
+                projects++;
+                sessions += n;
+            }
+        }
+    }
+    catch { /* absent */ }
+    out.push({
+        host: "claude-code", label: "Claude Code", found: projects > 0,
+        detail: projects > 0 ? `${sessions} session${sessions === 1 ? "" : "s"} across ${projects} project${projects === 1 ? "" : "s"}` : "not installed",
+    });
+    return out;
+}
+/** Parse a user-typed source list ("tui, telegram" or "*") into a clean array. */
+export function parseSources(input) {
+    const parts = (input || "").split(",").map((s) => s.trim()).filter(Boolean);
+    if (parts.includes("*"))
+        return ["*"];
+    return parts.length ? Array.from(new Set(parts)) : [...DEFAULT_HERMES_SOURCES];
+}
+/** First run = not yet onboarded, or the chosen provider isn't usable yet. */
+export function needsOnboarding() {
+    const c = loadConfig();
+    if (!c.onboarded)
+        return true;
+    if (c.provider === "openrouter")
+        return !c.openrouter_key;
+    if (c.provider === "local")
+        return !c.base_url || !c.model; // local needs an endpoint + model, no key
+    return true;
+}
+/** The provider env a TUI-launched server needs. Both paths speak the openai-compatible API:
+ *  OpenRouter (cloud, BYO key) or a local/self-hosted endpoint (Ollama/LM Studio/vLLM, no key).
+ *  Empty when un-configured (so launchServer stays a no-op for un-onboarded use). These WIN over
+ *  the server's .env because node --env-file won't override set vars. */
+export function providerEnv() {
+    const c = loadConfig();
+    if (c.provider === "openrouter" && c.openrouter_key) {
+        return {
+            AI_PROVIDER: "openai-compatible",
+            OPENAI_BASE_URL: OPENROUTER_BASE_URL,
+            OPENAI_API_KEY: c.openrouter_key,
+            AI_MODEL: c.model || OPENROUTER_DEFAULT_MODEL,
+        };
+    }
+    if (c.provider === "local" && c.base_url && c.model) {
+        return {
+            AI_PROVIDER: "openai-compatible",
+            OPENAI_BASE_URL: c.base_url,
+            OPENAI_API_KEY: "local", // local servers ignore the key; a non-empty value keeps clients happy
+            AI_MODEL: c.model,
+        };
+    }
+    return {};
+}
+/** Probe the usual local LLM servers (Ollama, LM Studio, vLLM) and list the models they serve,
+ *  so onboarding can show a pick-list instead of asking for a URL + model id. Each server that
+ *  isn't running just fails fast and is skipped. Returns [] if nothing local is up. */
+export async function scanLocalModels() {
+    const out = [];
+    const seen = new Set();
+    const add = (baseUrl, model, server) => {
+        const m = (model || "").trim();
+        const key = `${baseUrl}::${m}`;
+        if (m && !seen.has(key)) {
+            seen.add(key);
+            out.push({ label: `${m}  ·  ${server}`, baseUrl, model: m });
+        }
+    };
+    const get = async (url) => {
+        try {
+            const r = await fetch(url, { signal: AbortSignal.timeout(1500) });
+            return r.ok ? await r.json() : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Ollama's native tags API (richest model list).
+    const tags = await get("http://localhost:11434/api/tags");
+    for (const m of tags?.models ?? [])
+        add("http://localhost:11434/v1", m?.name ?? m?.model, "Ollama");
+    // OpenAI-compatible /v1/models on the common local ports.
+    for (const [port, server] of [[1234, "LM Studio"], [8000, "vLLM"], [11434, "Ollama"]]) {
+        const base = `http://localhost:${port}/v1`;
+        const j = await get(`${base}/models`);
+        for (const m of j?.data ?? [])
+            add(base, m?.id, server);
+    }
+    return out;
+}
+export { NODEDEX_HOME, CONFIG_FILE };

package/tui-dist/connect-snippets.js

@@ -0,0 +1,98 @@
+// connect-snippets.ts — ready-to-paste "connect your agent" config, per host.
+//
+// The wizard's last screen can only show one-liners (a TUI frame is a bad place to
+// copy multi-line JSON from), so the full snippets are WRITTEN TO A FILE the user
+// can open and paste from: ~/.nodedex/connect-snippets.md. Regenerated on every
+// server start from the wizard, so the port/token in it always match the live server.
+//
+// Two wires per host (the model users must internalize): READ = the MCP endpoint
+// below; CAPTURE = how finished turns reach the pipeline (without it the graph
+// stays empty). Hermes capture is automatic (the state.db watcher); other hosts
+// point at the README's capture section.
+import { homedir } from "os";
+import { resolve } from "path";
+import { mkdirSync, writeFileSync } from "fs";
+const NODEDEX_HOME = resolve(homedir(), ".nodedex");
+export const SNIPPETS_FILE = resolve(NODEDEX_HOME, "connect-snippets.md");
+export function buildConnectSnippets(p) {
+    const auth = p.token ? ` --header "Authorization: Bearer ${p.token}"` : "";
+    const authJsonLine = p.token ? `\n      "headers": { "Authorization": "Bearer ${p.token}" },` : "";
+    return `# Connect your agent to NodeDex
+
+MCP endpoint (Streamable HTTP): ${p.mcpUrl}
+${p.token ? `Auth header: Authorization: Bearer ${p.token}\n` : ""}
+The ONE token rule: connections from THIS machine never need the token; Docker/remote
+connections always do. Lost? \`nodedex connect\` prints the right URL + test command
+for every client location.
+
+Two wires, set up separately:
+1. **READ** — connect your agent to the MCP endpoint below (gives it the memory tools).
+2. **CAPTURE** — wire finished turns into the pipeline (without this the graph stays EMPTY).
+   Hermes: automatic (the state.db watcher, on by default in the TUI).
+   Everything else: see ${p.readmeUrl}
+
+---
+
+## Claude Code
+
+\`\`\`bash
+claude mcp add --transport http nodedex ${p.mcpUrl}${auth}
+\`\`\`
+
+Then in any session the workspace_* read tools are available. Capture: Claude Code's
+own transcripts can feed NodeDex — see the README's capture section.
+
+Note: Claude Code's built-in auto-memory is per-project notes for Claude Code alone.
+NodeDex complements it: one structured, self-maintaining graph that EVERY agent you
+run (Claude Code, Hermes, Codex, custom) reads and feeds — your experience follows
+you across tools instead of living in one.
+
+## Hermes
+
+Add to Hermes's MCP config (Settings → MCP servers):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "nodedex": {
+      "url": "${p.mcpUrl}"${authJsonLine}
+    }
+  }
+}
+\`\`\`
+
+Use 127.0.0.1, not localhost (localhost can resolve to IPv6 ::1 and fail).
+Capture is automatic — the NodeDex TUI watches Hermes's state.db (Settings → hermes capture).
+
+## Codex CLI
+
+In \`~/.codex/config.toml\` (needs a Codex version with HTTP MCP support):
+
+\`\`\`toml
+[mcp_servers.nodedex]
+url = "${p.mcpUrl}"
+${p.token ? `http_headers = { "Authorization" = "Bearer ${p.token}" }\n` : ""}\`\`\`
+
+## Any other MCP host
+
+Point it at the Streamable-HTTP endpoint: ${p.mcpUrl}
+${p.token ? `Send header: Authorization: Bearer ${p.token}` : "(no auth needed on localhost)"}
+
+Docker'd agent on this machine? Use http://host.docker.internal:<port>/mcp instead.
+
+---
+
+Full connect + capture reference: ${p.readmeUrl}
+`;
+}
+/** Write the snippets file; returns its path. Never throws (best-effort). */
+export function writeConnectSnippets(p) {
+    try {
+        mkdirSync(NODEDEX_HOME, { recursive: true });
+        writeFileSync(SNIPPETS_FILE, buildConnectSnippets(p), "utf8");
+        return SNIPPETS_FILE;
+    }
+    catch {
+        return null;
+    }
+}