@mnemahq/cli 0.3.1 → 0.7.0

package/README.md

@@ -50,7 +50,48 @@ contents. See the [privacy details](https://mnema.theboringpeople.in/docs/connec
 
 `--origin <url>` (or `MNEMA_API_ORIGIN`) points the CLI at a self-hosted instance.
 
-Requires Node 18+ and `git`.
+Requires Node 20+ and `git` — the same floor `@mnemahq/sdk` already declares.
+
+## The interactive briefing
+
+Run `mnema` with no arguments in a terminal and it opens a navigable briefing:
+pulse, then the ranked findings, with `enter` to drill into one.
+
+```
+mnema        the briefing (a terminal, Node 20+)
+mnema tui    the same, explicitly
+mnema --no-tui   print help instead
+```
+
+It never opens when output is piped, under `CI`, on `TERM=dumb`, or where the
+terminal cannot enter raw mode — in all of those `mnema` prints help exactly as it
+always has. `MNEMA_TUI=never` turns it off for good; `MNEMA_TUI=always` forces it.
+
+**Ink is loaded lazily**, so this costs one-shot commands nothing: `mnema --version`
+measures the same before and after (~60ms), because `ink` is only imported once the
+UI is actually opening. Installed size is ~22 MB, most of which is `es-toolkit`
+arriving through Ink.
+
+## Output, piping and colour
+
+Every read command takes `--json`, so the CLI composes:
+
+```bash
+mnema tasks --json | jq '.[] | select(.priority == "high") | .title'
+```
+
+**Colour is emitted only when output is a terminal.** `mnema docs > out.txt` and
+`mnema tasks | grep …` produce plain text with no escape sequences in it.
+
+| variable | effect |
+| --- | --- |
+| `NO_COLOR` | disable colour, any value ([no-color.org](https://no-color.org)) |
+| `FORCE_COLOR=1` | keep colour through a pipe, e.g. `mnema tasks \| less -R` |
+| `COLUMNS` | override the width used for column layout |
+| `MNEMA_WORKSPACE_ID` | default workspace, instead of `--workspace` |
+
+`mnema doc <id>` is built for redirection: the markdown goes to stdout and the title
+and path go to stderr, so `mnema doc <id> > note.md` gets the document alone.
 
 ## `.mnema/` repo artifacts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.3.1",
+  "version": "0.7.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "LICENSE.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mnema",
@@ -22,19 +22,23 @@
     "claude-code",
     "sessions"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "ink-testing-library": "^4.0.0",
     "vitest": "^3.2.7"
   },
   "dependencies": {
+    "htm": "^3.1.1",
+    "ink": "^6.8.0",
+    "react": "^19.2.7",
     "@mnemahq/sdk": "0.3.1"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",
-    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs && node --check src/client.mjs && node --check src/read-commands.mjs && node --check test/version.test.mjs",
+    "typecheck": "find bin src -name '*.mjs' -exec node --check {} +",
     "test": "vitest run"
   }
 }

package/src/browser.mjs

@@ -0,0 +1,93 @@
+/**
+ * Open a URL in the user's browser (t-631).
+ *
+ * ⭐ `mnema --help` HAS CLAIMED THIS SINCE 0.1.0 — "login  Sign in (opens a
+ * browser; tokens go to your OS keychain)" — and the CLI has never once opened a
+ * browser. cmdLogin printed the URL and waited. The help text was describing a
+ * feature that did not exist, which is the same class of untruth as a docs pointer
+ * to a settings page that was never built (t-629): nothing breaks, no test goes
+ * red, the sentence is just not true.
+ *
+ * ⚠️ THE URL COMES FROM A SERVER RESPONSE, so it is INPUT, not a constant. The
+ * device-authorization body hands back `verification_uri_complete` and we are
+ * about to hand it to the operating system's "open this" facility. Two rules
+ * follow, and neither is optional:
+ *
+ *   1. VALIDATE IT. http/https only, and the host must match the API origin we
+ *      chose to talk to. Without the scheme check a `file://` or `javascript:`
+ *      value would be handed straight to the OS; without the host check, an
+ *      origin-confused or tampered response could send the user's browser
+ *      somewhere else entirely while they are in the mood to approve a login.
+ *   2. NEVER THROUGH A SHELL. execFile with the URL as an argv entry, so no amount
+ *      of quoting, backticks or semicolons in it can become a command. `shell:true`
+ *      here would be a straightforward injection.
+ *
+ * And it must never be load-bearing: a headless box, an SSH session and a locked
+ * down desktop all legitimately have nothing to open with. Failure returns false
+ * and the printed URL — which is still printed — remains the real path.
+ */
+
+import { execFile } from 'node:child_process';
+
+/**
+ * Is this URL safe to hand to the OS, given the origin we are talking to?
+ *
+ * Exported for the tests, because the interesting cases are the ones nobody
+ * reaches by hand.
+ */
+export function isSafeToOpen(url, origin) {
+  let target;
+  let base;
+  try {
+    target = new URL(String(url));
+    base = new URL(String(origin));
+  } catch {
+    return false;
+  }
+  // Not a denylist. Anything that is not plainly http(s) is refused, so
+  // `javascript:`, `data:`, `file:` and every scheme nobody has thought of yet
+  // are all covered by the same line.
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') return false;
+  // Same host as the API we are already trusting. `endsWith` would accept
+  // `evil-theboringpeople.in`, so this is an exact comparison.
+  return target.hostname === base.hostname;
+}
+
+/** Platform command + args. Windows' `start` is a cmd builtin, hence the shim. */
+function opener(url) {
+  if (process.platform === 'darwin') return ['open', [url]];
+  if (process.platform === 'win32') return ['cmd', ['/c', 'start', '', url]];
+  return ['xdg-open', [url]];
+}
+
+/**
+ * Try to open `url`. Resolves true only if the opener actually started.
+ *
+ * ⚠️ NEVER THROWS AND NEVER REJECTS. The caller's next line prints the URL for the
+ * user to open themselves; turning a missing xdg-open into a failed login would be
+ * absurd.
+ */
+export function openInBrowser(url, origin) {
+  if (!isSafeToOpen(url, origin)) return Promise.resolve(false);
+  if (process.env.MNEMA_NO_BROWSER) return Promise.resolve(false);
+  // Nothing to open onto, and on a headless box the opener can hang rather than
+  // fail — so do not even start it.
+  if (!process.stdout.isTTY || process.env.CI) return Promise.resolve(false);
+
+  const [cmd, args] = opener(url);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    try {
+      const child = execFile(cmd, args, { windowsHide: true }, (err) => done(!err));
+      child.on('error', () => done(false));
+      // xdg-open on a misconfigured desktop can sit there indefinitely. The login
+      // must not wait on it: give it two seconds, then carry on with the printed
+      // URL either way.
+      const t = setTimeout(() => done(false), 2000);
+      if (typeof t.unref === 'function') t.unref();
+    } catch {
+      done(false);
+    }
+  });
+}

package/src/cli.mjs

@@ -17,9 +17,14 @@ import {
   cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
 } from './read-commands.mjs';
 import {
-  DEFAULT_ORIGIN, DEFAULT_APP_URL, c, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
-  apiFetch, prompt, promptHidden, localSessionsForRepo,
+  DEFAULT_ORIGIN, DEFAULT_APP_URL, c, truncate, width, mark, gitInfo, canonicalRepo, readConfig, writeConfig,
+  removeConfigDir, apiFetch, prompt, promptHidden, localSessionsForRepo,
 } from './util.mjs';
+// `checks` is aliased because cmdDoctor already has a local of that name — the
+// collision is worth keeping visible rather than renaming the well-named local.
+import { heading, entries, checks as checkList, rows, empty, more } from './render/layout.mjs';
+import { take } from './paging.mjs';
+import { tuiEligibility, explainUnavailable } from './tui-gate.mjs';
 import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from './secrets.mjs';
 import {
   installHook, uninstallHook, hookInstalled, hookConfigPath, defaultDeveloperId, sweepScriptPath,
@@ -47,15 +52,39 @@ const VERSION = JSON.parse(
   readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 ).version;
 
-function parseFlags(argv) {
+/**
+ * Flags that take a value. Everything else is boolean.
+ *
+ * ⭐ THIS LIST IS THE FIX. The parser used to treat ANY flag as value-taking if
+ * the next argv entry did not start with `--`, so a boolean flag silently ate the
+ * following positional:
+ *
+ *     mnema doc --json <id>   ->  flags.json = '<id>',  rest = []
+ *                             ->  "Usage: mnema doc <id>"
+ *
+ * `--json` only worked in trailing position, and the same trap hit `ask`,
+ * `search` and `graph`. Guessing from argv shape cannot distinguish "a boolean
+ * flag followed by an argument" from "a flag and its value" — the parser has to
+ * be told which is which, so it is.
+ */
+const VALUE_FLAGS = new Set(['workspace', 'origin', 'limit', 'status', 'project', 'repo', 'budget']);
+
+export function parseFlags(argv) {
   const flags = {}; const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) {
-      const key = a.slice(2);
-      if (argv[i + 1] && !argv[i + 1].startsWith('--')) { flags[key] = argv[++i]; }
-      else flags[key] = true;
-    } else rest.push(a);
+    if (!a.startsWith('--')) { rest.push(a); continue; }
+
+    // `--limit=5` as well as `--limit 5`; the former is unambiguous and common.
+    const eq = a.indexOf('=');
+    if (eq > 2) { flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+
+    const key = a.slice(2);
+    if (VALUE_FLAGS.has(key) && argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) {
+      flags[key] = argv[++i];
+    } else {
+      flags[key] = true;
+    }
   }
   return { flags, rest };
 }
@@ -211,24 +240,36 @@ async function cmdInit(flags) {
 
 async function cmdStatus(flags) {
   const { git, root, cfg, origin, workspaceId } = resolveContext(flags);
-  console.log(c.bold('Mnema status'));
-  console.log(`  Workspace : ${workspaceId || c.red('not linked — run `mnema init`')}`);
-  console.log(`  Origin    : ${origin}`);
-  console.log(`  Repo      : ${canonicalRepo(git.remote) || c.dim('(no git remote)')}`);
-  console.log(`  Hook      : ${hookInstalled() ? c.green('installed') : c.red('not installed')}`);
 
-  process.stdout.write('  API       : ');
+  // ⚠️ THE API PROBE RUNS BEFORE ANYTHING PRINTS, and that is the fix for the
+  // broken gutter. The old version wrote a hand-padded '  API       : ' with
+  // process.stdout.write, awaited the network, then console.log'd the result —
+  // so the label column was aligned by counting spaces against four other lines,
+  // and any change to a label name silently knocked one row out of true. Gathering
+  // first means one table() measures every row against every other.
+  let api;
   try {
     const r = await apiFetch(origin, '/install/mnema-hook.mjs');
-    console.log(r.ok ? c.green('reachable') : c.yellow(`HTTP ${r.status}`));
-  } catch { console.log(c.red('unreachable')); }
+    api = r.ok ? { pass: true, note: 'reachable' } : { pass: false, note: `HTTP ${r.status}` };
+  } catch { api = { pass: false, note: 'unreachable' }; }
 
   const local = localSessionsForRepo(git.root, 1);
-  if (local.length) {
-    console.log(`  Last local session: ${local[0].sessionId.slice(0, 8)}… ${c.dim(fmtAge(local[0].mtimeMs))}`);
-  } else {
-    console.log(`  Last local session: ${c.dim('none found')}`);
-  }
+
+  // ⚠️ ONE entries() CALL, not one per group — the label column only lines up if
+  // every row is measured against every other row. Three calls printed three
+  // different label widths, which is this PR's own bug in miniature.
+  heading('Status', workspaceId ? undefined : 'not linked');
+  entries([
+    { label: 'workspace', value: workspaceId || c.red('not linked — run `mnema init`') },
+    { label: 'origin', value: origin },
+    { label: 'repo', value: canonicalRepo(git.remote) || c.dim('(no git remote)') },
+    { label: 'capture hook', value: hookInstalled() ? 'installed' : 'run `mnema init`', state: hookInstalled() },
+    { label: 'api', value: api.note, state: api.pass },
+    {
+      label: 'last session',
+      value: local.length ? `${local[0].sessionId.slice(0, 8)}… ${c.dim(fmtAge(local[0].mtimeMs))}` : c.dim('none found'),
+    },
+  ]);
   void cfg;
 }
 
@@ -239,34 +280,49 @@ async function cmdSessions(flags) {
   const limit = Number(flags.limit) || 10;
 
   const local = localSessionsForRepo(git.root, limit);
-  console.log(c.bold(`Local sessions for this repo (${local.length})`));
-  if (!local.length) console.log(c.dim('  none found under ~/.claude/projects'));
-  for (const s of local) {
-    console.log(`  ${s.sessionId.slice(0, 8)}…  ${fmtAge(s.mtimeMs).padStart(8)}  ${c.dim((s.sizeBytes / 1024).toFixed(0) + ' KB')}`);
+  heading('Local sessions', local.length);
+  if (!local.length) {
+    empty('None found under ~/.claude/projects.', 'Start a Claude Code session in this repo.');
+  } else {
+    rows(local.map((s) => ({
+      cells: [`${s.sessionId.slice(0, 8)}…`, fmtAge(s.mtimeMs), `${(s.sizeBytes / 1024).toFixed(0)} KB`],
+      style: [undefined, undefined, c.dim],
+    })));
   }
 
   if (!(await canAuthenticate(workspaceId))) {
-    console.log(c.dim('\n  (run `mnema login` — or add an API key — to see server-side cost + status)'));
+    console.log(c.dim('\n  Run `mnema login` to see server-side cost and status.'));
     return;
   }
 
   const repo = canonicalRepo(git.remote);
-  let rows = [];
+  let page;
   try {
-    rows = await call({ origin, workspaceId }, (m) =>
-      m.sessions.list({ limit, ...(repo ? { repo } : {}) }).all());
+    page = await call({ origin, workspaceId }, (m) =>
+      take(m.sessions.list({ limit, ...(repo ? { repo } : {}) }), limit));
   } catch (e) {
     // Non-fatal by design: the LOCAL list above is the useful half and has
     // already printed. Degrading here is deliberate, and it says which wall it
     // hit rather than a bare HTTP number.
-    console.log(c.yellow(`\n  server sessions unavailable — ${e?.message ?? e}`));
+    console.log(c.yellow(`\n  Server sessions unavailable — ${e?.message ?? e}`));
     return;
   }
-  console.log(c.bold(`\nServer sessions (${rows.length})`));
-  for (const s of rows) {
-    const cost = typeof s.totalCostUsd === 'number' ? `$${s.totalCostUsd.toFixed(4)}` : '$0';
-    console.log(`  ${(s.developerId || '?').padEnd(16)} ${String(s.status).padEnd(10)} ${cost.padStart(10)}  ${c.dim(s.model || '')}`);
+  console.log('');
+  heading('Server sessions', page.rows.length);
+  if (!page.rows.length) {
+    empty('None recorded for this repo yet.');
+    return;
   }
+  rows(page.rows.map((s) => ({
+    cells: [
+      s.developerId || '?',
+      String(s.status),
+      typeof s.totalCostUsd === 'number' ? `$${s.totalCostUsd.toFixed(4)}` : '$0',
+      s.model || '',
+    ],
+    style: [undefined, undefined, undefined, c.dim],
+  })));
+  more(page.more, `mnema sessions --limit ${limit * 2}`);
 }
 
 // ── sweep ───────────────────────────────────────────────────────────────────────
@@ -299,11 +355,19 @@ async function cmdSearch(flags, rest) {
   try {
     results = await call({ origin, workspaceId }, (m) => m.docs.search(query));
   } catch (e) { renderError(e, { context: 'search', usedApiKey: hasApiKey(workspaceId) }); }
-  if (!results.length) { console.log(c.dim('No results.')); return; }
-  console.log(c.bold(`${results.length} result(s) for "${query}"`));
+
+  // ⚠️ `search` DID NOT HONOUR --json, though help advertised it for "every read
+  // command". It sits in cli.mjs rather than read-commands.mjs, so it never got
+  // the shared emit() — a filing accident, not a decision.
+  if (flags.json) { console.log(JSON.stringify(results, null, 2)); return; }
+
+  heading('Results', results.length);
+  if (!results.length) { empty(`Nothing matched "${query}".`, 'Try fewer words, or a phrase from the document body.'); return; }
   for (const d of results) {
     console.log(`  ${c.bold(d.title || d.path || d.id)}`);
-    if (d.preview) console.log(`    ${c.dim(String(d.preview).replace(/\s+/g, ' ').slice(0, 140))}`);
+    // truncate() adds an ellipsis; the old slice(0,140) cut mid-sentence with no
+    // marker, so a clipped preview looked like a document that simply ended.
+    if (d.preview) console.log(`    ${c.dim(truncate(String(d.preview).replace(/\s+/g, ' '), width() - 6))}`);
   }
 }
 
@@ -328,16 +392,30 @@ async function cmdPull(flags) {
   scaffold(root);
   const s = applyContext(root, docs);
 
-  const line = (label, arr, color) => { if (arr.length) console.log(`  ${color(label)} ${arr.length}`); };
-  console.log(c.bold(`Synced .mnema/context from ${repo}`));
-  if (!docs.length) console.log(c.dim('  no docs are bound to this repo yet (add a project with this repo URL).'));
-  line('written  ', s.written, c.green);
-  line('updated  ', s.updated, c.green);
-  line('up-to-date', s.upToDate, c.dim);
-  line('kept local', s.kept, c.yellow);
-  line('orphaned ', s.orphaned, c.dim);
+  heading('Synced', repo);
+  if (!docs.length) {
+    empty('No docs are bound to this repo yet.', 'Add a project in the app with this repo URL.');
+  }
+  // ⚠️ THE LABELS USED TO BE PADDED BY HAND — 'written  ' is 9 characters and
+  // 'up-to-date' is 10, so the count column stepped one place to the right on two
+  // of the five rows. Nobody notices reading it once; it is exactly the sort of
+  // thing that makes output feel unmade. table() measures them against each other.
+  const tally = [
+    ['written', s.written, c.green],
+    ['updated', s.updated, c.green],
+    ['up-to-date', s.upToDate, c.dim],
+    ['kept local', s.kept, c.yellow],
+    ['orphaned', s.orphaned, c.dim],
+  ].filter(([, arr]) => arr.length);
+  if (tally.length) {
+    rows(tally.map(([label, arr, colour]) => ({
+      cells: [label, String(arr.length)],
+      style: [colour, undefined],
+    })));
+  }
   if (s.conflicts.length) {
-    console.log(c.red(`  conflicts ${s.conflicts.length} — server version written beside your file as *.remote.md:`));
+    console.log(`\n  ${mark.warn()} ${c.red(`${s.conflicts.length} conflict(s) — the server version is beside yours as *.remote.md`)}`);
+    // Paths are printed plain: these are the files the user is about to open.
     for (const rel of s.conflicts) console.log(`    ${rel}  ${c.dim('vs')}  ${rel.replace(/\.md$/, '.remote.md')}`);
   }
   console.log(c.dim('\n  .mnema/context is committed and readable offline. Edit NOTABILITY.md to tune capture.'));
@@ -359,7 +437,11 @@ async function cmdDoctor(flags) {
   ok('hook token stored', !!(workspaceId && getSecret(workspaceId, 'hook-token')), `store: ${backendName()}`);
   ok('capture hook installed', hookInstalled());
 
-  process.stdout.write('  … checking connectivity\r');
+  // ⚠️ ONLY ON A TTY. This wrote unconditionally, so `mnema doctor > report.txt`
+  // and `mnema doctor | grep` both captured the progress text as if it were part
+  // of the report. A spinner is for a human watching; it is noise in a pipe.
+  const live = process.stdout.isTTY;
+  if (live) process.stdout.write('  … checking connectivity\r');
   let apiReach = false; try { apiReach = (await apiFetch(origin, '/install/mnema-hook.mjs')).ok; } catch { /* */ }
   ok('API reachable', apiReach, origin);
 
@@ -375,14 +457,19 @@ async function cmdDoctor(flags) {
     ok('API key stored', false, 'optional — needed for search/sessions');
   }
 
-  console.log(c.bold('Mnema doctor            '));
-  for (const ch of checks) {
-    const mark = ch.pass ? c.green('✓') : c.red('✗');
-    console.log(`  ${mark} ${ch.label.padEnd(26)} ${ch.note ? c.dim(ch.note) : ''}`);
-  }
+  // ⚠️ The old heading was the literal string 'Mnema doctor            ' — twelve
+  // trailing spaces, left over from overwriting the '… checking connectivity\r'
+  // progress line by hand. It is invisible until you select the line, or diff the
+  // output, or pipe it. \x1b[K clears to end of line and cannot be off by a space.
+  if (live) process.stdout.write('\x1b[K');
+  heading('Doctor', origin);
+  checkList(checks);
   const failed = checks.filter((ch) => !ch.pass && ch.label !== 'API key stored');
-  if (failed.length) { console.log(c.yellow(`\n  ${failed.length} issue(s). Run \`mnema init\` to (re)connect.`)); process.exit(1); }
-  console.log(c.green('\n  All good.'));
+  if (failed.length) {
+    console.log(`\n  ${mark.warn()} ${c.yellow(`${failed.length} issue(s). Run \`mnema init\` to (re)connect.`)}`);
+    process.exit(1);
+  }
+  console.log(`\n  ${mark.ok()} ${c.green('All good.')}`);
   void root;
 }
 
@@ -419,6 +506,7 @@ Commands:
   search "q"   Search your workspace from the terminal
   doctor       Diagnose install, hooks, auth, connectivity
   uninstall    Remove hooks and stored secrets
+  tui          Open the interactive briefing explicitly (Node 20+, a terminal)
 
 Read your workspace:
   tasks        List tasks            [--status --project --limit]
@@ -439,13 +527,63 @@ Options:
   --json             Machine-readable output (every read command)
   --yes              Non-interactive; skip optional prompts
   --purge            uninstall: also delete .mnema/config.json
+  --no-tui           Print help instead of opening the interactive UI
   --version, --help
+
+Environment:
+  NO_COLOR           Disable colour (any value)
+  FORCE_COLOR=1      Keep colour when piping, e.g. into \`less -R\`
+  COLUMNS            Override the terminal width used for layout
+  MNEMA_TUI          never | always — force the interactive UI off or on
+  MNEMA_WORKSPACE_ID Default workspace, instead of --workspace
+
+Colour is off automatically when output is not a terminal, so \`mnema tasks > f.txt\`
+writes plain text.
 `);
 }
 
+/**
+ * Open the interactive briefing, or explain why not and print help.
+ *
+ * ⭐ THE ONLY DYNAMIC IMPORT OF THE TUI IN THE WHOLE PACKAGE. Everything under
+ * src/tui/ is reached exclusively through this line, which is why modules in there
+ * can use ordinary static imports. `import('ink')` measures 136–141ms against a
+ * 59–65ms `mnema --version`, and mnema runs from capture hooks and shell prompts —
+ * so this must stay the single seam. test/no-ink-in-oneshot.test.mjs enforces it,
+ * because `node --check` parses without resolving and would never notice a stray
+ * `import { Box } from 'ink'` in read-commands.mjs.
+ */
+async function openTuiOrHelp(flags) {
+  const gate = tuiEligibility(flags);
+  if (gate.ok) {
+    const { startTui } = await import('./tui/launch.mjs');
+    const ctx = resolveContext(flags);
+    return startTui({
+      ...ctx,
+      call: (fn) => call(ctx, fn),
+    });
+  }
+  // ⚠️ TO STDERR, so `mnema | cat` still gets clean help on stdout. And nothing at
+  // all for `not-a-tty`: piping mnema to read its help is legitimate, and a nag
+  // there is noise in someone's data.
+  for (const line of explainUnavailable(gate.reason, gate.detail)) console.error(c.dim(line));
+  help();
+  // Exit 0: bare `mnema` has printed help and exited 0 since 0.1.0, and turning
+  // that into a failure for a runtime we still support is a regression wearing a
+  // feature's clothes.
+  return 0;
+}
+
 export async function run(argv) {
   const { flags, rest } = parseFlags(argv);
   if (flags.version) { console.log(VERSION); return; }
+  // ⭐ BEFORE THE GATE, AND THIS ORDER IS THE WHOLE POINT. `mnema --help` leaves
+  // rest empty, so cmd === undefined — the SAME branch that opens the TUI. Worse,
+  // version.test.mjs runs the binary through execFileSync, where stdout is not a
+  // TTY, so the gate would fall through to help() and THE TEST WOULD PASS while
+  // every real user on a terminal got a UI instead of the help they asked for.
+  // That is this repo's characteristic bug aimed at its own test suite.
+  if (flags.help || flags.h) { help(); return; }
   const cmd = rest.shift();
   switch (cmd) {
     case 'login':     return cmdLogin(flags);
@@ -469,7 +607,21 @@ export async function run(argv) {
     case 'ask':       return cmdAsk(flags, resolveContext(flags), rest);
     case 'graph':     return cmdGraph(flags, resolveContext(flags), rest);
     case 'briefing':  return cmdBriefing(flags, resolveContext(flags));
-    case undefined:
+    case 'tui':
+      // An EXPLICIT request that cannot be honoured fails loudly (exit 1); the
+      // implicit one below degrades to help and exits 0. That asymmetry is
+      // CLAUDE.md's no-silent-returns rule: `mnema tui` on Node 18 must not
+      // quietly print help as though that were what was asked for.
+      {
+        const gate = tuiEligibility(flags);
+        if (gate.ok) return openTuiOrHelp(flags);
+        const why = explainUnavailable(gate.reason, gate.detail);
+        console.error(c.red(why[0] ?? `The interactive UI is unavailable here (${gate.reason}).`));
+        for (const line of why.slice(1)) console.error(c.dim(line));
+        process.exit(1);
+      }
+      break;
+    case undefined:   return openTuiOrHelp(flags);
     case 'help':      return help();
     default:
       console.error(c.red(`Unknown command: ${cmd}`));