@mnemahq/cli 0.3.0 → 0.4.0

package/README.md

@@ -52,6 +52,27 @@ contents. See the [privacy details](https://mnema.theboringpeople.in/docs/connec
 
 Requires Node 18+ and `git`.
 
+## 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
 
 `mnema init` scaffolds a committed `.mnema/` directory and `mnema pull` fills it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -22,7 +22,7 @@
     "claude-code",
     "sessions"
   ],
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "SEE LICENSE IN LICENSE.md",
   "publishConfig": {
     "access": "public"
   },
@@ -34,7 +34,7 @@
   },
   "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",
+    "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 src/render/theme.mjs",
     "test": "vitest run"
   }
 }

package/src/cli.mjs

@@ -10,14 +10,14 @@
  *   mnema uninstall  cleanly reverse everything
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
-import { makeClient, canAuthenticate, renderError } from './client.mjs';
+import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 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,
+  DEFAULT_ORIGIN, DEFAULT_APP_URL, c, truncate, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
   apiFetch, prompt, promptHidden, localSessionsForRepo,
 } from './util.mjs';
 import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from './secrets.mjs';
@@ -27,17 +27,59 @@ import {
 import { applyContext, scaffold } from './artifacts.mjs';
 import { execFileSync } from 'node:child_process';
 
-const VERSION = '0.1.0';
+/**
+ * ⚠️ READ FROM package.json, NEVER HAND-WRITTEN. This was `const VERSION =
+ * '0.1.0'` and stayed that way through 0.1.1 and 0.3.0 — so every release of
+ * this CLI reported the same wrong number, and `mnema --version` was useless for
+ * the one job it has.
+ *
+ * The cost was not cosmetic. After 0.3.0 shipped with eight new commands,
+ * `mnema --help` printed "mnema 0.1.0" and the old command list, because the
+ * global install was stale and npm does not upgrade an installed global when you
+ * publish. The right fix was one line — `npm i -g @mnemahq/cli@latest` — but a
+ * binary that misreports itself makes that undiagnosable, and the honest reading
+ * of the evidence was "you shipped nothing".
+ *
+ * Resolved relative to import.meta.url, not cwd: the CLI runs from whatever
+ * directory the user happens to be in. package.json is always in the tarball.
+ */
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+
+/**
+ * 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']);
 
-function parseFlags(argv) {
+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 };
 }
@@ -105,6 +147,26 @@ async function cmdInit(flags) {
   if (!workspaceId) { console.error(c.red('A workspace id is required.')); process.exit(1); }
 
   let hookToken = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+
+  // ⚠️ ONLY MINT WHEN THERE IS NOTHING STORED. Minting ROTATES — the server keeps
+  // a hash, so `regenerate` is the only way to obtain a token and it invalidates
+  // the previous one. Re-running `init` on a second machine must not silently
+  // kill capture on the first.
+  if (!hookToken) {
+    process.stdout.write('Getting a hook token… ');
+    const minted = await mintHookToken({ origin, workspaceId });
+    if (minted) {
+      hookToken = minted;
+      console.log(c.green('done'));
+      console.log(c.dim('  A new token was issued. Any OTHER machine set up for this workspace'));
+      console.log(c.dim('  must re-run `mnema init` — the previous token no longer works.'));
+    } else {
+      // Not logged in, not the owner (the endpoint is owner-only), or offline.
+      // Fall through to asking, with the right pointer.
+      console.log(c.dim('not available — enter one manually'));
+    }
+  }
+
   if (!hookToken) {
     // ⚠️ NOT "Settings → Developer". That page does not exist and never did in
     // this shape — the hook token moved to the Access page when tokens were
@@ -215,9 +277,8 @@ async function cmdSessions(flags) {
   const repo = canonicalRepo(git.remote);
   let rows = [];
   try {
-    rows = await makeClient({ origin, workspaceId })
-      .sessions.list({ limit, ...(repo ? { repo } : {}) })
-      .all();
+    rows = await call({ origin, workspaceId }, (m) =>
+      m.sessions.list({ limit, ...(repo ? { repo } : {}) }).all());
   } 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
@@ -260,13 +321,21 @@ async function cmdSearch(flags, rest) {
 
   let results = [];
   try {
-    results = await makeClient({ origin, workspaceId }).docs.search(query);
-  } catch (e) { renderError(e, { context: 'search' }); }
+    results = await call({ origin, workspaceId }, (m) => m.docs.search(query));
+  } catch (e) { renderError(e, { context: 'search', usedApiKey: hasApiKey(workspaceId) }); }
+
+  // ⚠️ `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; }
+
   if (!results.length) { console.log(c.dim('No results.')); return; }
   console.log(c.bold(`${results.length} result(s) for "${query}"`));
   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, ' '), 140))}`);
   }
 }
 
@@ -285,8 +354,8 @@ async function cmdPull(flags) {
   try {
     // `.context`, not the whole result — `.repo` is the URL the server matched.
     // Reading the wrong one of these two is the bug this rewire found in the SDK.
-    docs = (await makeClient({ origin, workspaceId }).repos.context(repo)).context ?? [];
-  } catch (e) { renderError(e, { context: 'pull' }); }
+    docs = (await call({ origin, workspaceId }, (m) => m.repos.context(repo))).context ?? [];
+  } catch (e) { renderError(e, { context: 'pull', usedApiKey: hasApiKey(workspaceId) }); }
 
   scaffold(root);
   const s = applyContext(root, docs);
@@ -329,6 +398,9 @@ async function cmdDoctor(flags) {
   const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
   if (apiKey) {
     let keyOk = false;
+    // Probes the KEY specifically — no fallback — because that is the thing
+    // doctor is reporting on. Using call() here would mask a dead key behind a
+    // working login and print a green tick for a credential that does not work.
     try { await makeClient({ origin, workspaceId }).docs.list({ limit: 1 }).pages().next(); keyOk = true; } catch { /* */ }
     ok('API key valid', keyOk);
   } else {
@@ -400,6 +472,15 @@ Options:
   --yes              Non-interactive; skip optional prompts
   --purge            uninstall: also delete .mnema/config.json
   --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_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.
 `);
 }
 

package/src/client.mjs

@@ -28,8 +28,8 @@ import { c, DEFAULT_APP_URL } from './util.mjs';
  * request — that is what makes a refresh mid-command work instead of failing on
  * a token that expired thirty seconds ago.
  */
-export function makeClient({ origin, workspaceId }) {
-  const apiKey = (workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null;
+export function makeClient({ origin, workspaceId, forceLogin = false }) {
+  const apiKey = forceLogin ? null : ((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null);
   return new Mnema(
     apiKey
       ? { apiKey, baseUrl: origin }
@@ -37,6 +37,45 @@ export function makeClient({ origin, workspaceId }) {
   );
 }
 
+/**
+ * Run an SDK call, and if a STORED API KEY is rejected, retry once with the login.
+ *
+ * ⭐ THE TRAP THIS REMOVES. makeClient prefers an explicit API key, which is right
+ * — a key is scoped and deliberate. But a DEAD key then shadows a perfectly good
+ * login forever, and the failure told the user to do the one thing that could not
+ * help:
+ *
+ *     $ mnema docs      -> not authenticated. Run `mnema login`.
+ *     $ mnema login     -> ✓ Logged in.
+ *     $ mnema docs      -> not authenticated. Run `mnema login`.
+ *
+ * The login was never the credential in play. An instruction that cannot work is
+ * worse than none: it spends the reader's remaining trust in the tool.
+ *
+ * ⚠️ THE SDK CANNOT DO THIS FOR US. packages/core resolves `Bearer apiKey`
+ * whenever apiKey is set and never consults getToken, so `onUnauthorized` can
+ * ask for a retry but cannot change which credential the retry uses. The swap has
+ * to happen out here, by building a second client.
+ *
+ * ⚠️ AND IT IS ANNOUNCED, not silent. Quietly using a different identity than the
+ * one configured is its own confusion — the next question would be "which
+ * credential ran this?", and the answer should not require reading source.
+ */
+export async function call(ctx, fn) {
+  try {
+    return await fn(makeClient(ctx));
+  } catch (e) {
+    const isAuth = e?.constructor?.name === 'AuthError';
+    if (!isAuth || ctx.forceLogin || !hasApiKey(ctx.workspaceId)) throw e;
+    let loggedIn = false;
+    try { loggedIn = Boolean(await accessToken()); } catch { /* no login */ }
+    if (!loggedIn) throw e;
+    console.error(c.yellow('  stored API key was rejected — using your login instead.'));
+    console.error(c.dim('  Run `mnema init` to replace the key, or ignore this if you meant to use the login.'));
+    return await fn(makeClient({ ...ctx, forceLogin: true }));
+  }
+}
+
 /** True when an explicit API key is configured. Cheap; no network. */
 export function hasApiKey(workspaceId) {
   return Boolean((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY);
@@ -73,14 +112,24 @@ export async function canAuthenticate(workspaceId) {
  * branch — turning a good message back into a bad one for the exact reason this
  * function exists.
  */
-export function renderError(e, { context = '' } = {}) {
+export function renderError(e, { context = '', usedApiKey = false } = {}) {
+  const opts = { usedApiKey };
   const name = e?.constructor?.name ?? '';
   const where = context ? `${context}: ` : '';
 
   switch (name) {
     case 'AuthError':
       console.error(c.red(`${where}not authenticated.`));
-      console.error(`  ${e.fix ?? 'Run `mnema login`.'}`);
+      // ⚠️ NAME THE CREDENTIAL THAT FAILED. The SDK's generic fix is "Run `mnema
+      // login`", which is exactly wrong when the thing that was rejected is a
+      // stored API KEY and a valid login already exists — the user runs it,
+      // succeeds, and nothing changes.
+      if (opts.usedApiKey) {
+        console.error('  The stored API key was rejected.');
+        console.error('  Run `mnema init` to replace it, or `mnema login` to use a login instead.');
+      } else {
+        console.error(`  ${e.fix ?? 'Run `mnema login`.'}`);
+      }
       break;
 
     case 'PlanRequiredError':
@@ -126,3 +175,43 @@ export function renderError(e, { context = '' } = {}) {
   }
   process.exit(1);
 }
+
+/**
+ * Mint a hook token for this workspace, using the login (t-627).
+ *
+ * ⭐ WHY THIS EXISTS. Setting up a repo meant fetching three things from two
+ * settings pages. The workspace id now comes from /api/me and the API key is
+ * optional — this was the last piece of copy-paste, and it never needed to be one:
+ * the endpoint has existed all along and has accepted a bearer token since t-613.
+ *
+ * ⚠️ THE HOOK TOKEN CANNOT SIMPLY BE THE LOGIN, and that is deliberate rather than
+ * unfinished. installHook writes it in PLAINTEXT to ~/.claude/mnema-hook.json,
+ * where an unattended process reads it after every session. A narrow,
+ * single-purpose token belongs in a file like that; an OAuth refresh token — which
+ * can mint access tokens for the whole account — does not.
+ *
+ * ⚠️ AND MINTING ROTATES. The server keeps only a HASH, so there is no way to read
+ * an existing token back; `regenerate` is the only path and it invalidates the old
+ * one. Callers MUST check for a stored token first — minting unconditionally would
+ * silently break capture on every other machine the user has set up. That check
+ * lives in cmdInit, not here, because this function's job is to mint and it should
+ * not pretend otherwise.
+ *
+ * Returns null rather than throwing: not logged in, not the owner (the endpoint is
+ * owner-only), or offline are all ordinary, and the caller falls back to asking.
+ */
+export async function mintHookToken({ origin, workspaceId }) {
+  try {
+    const token = await accessToken();
+    if (!token) return null;
+    const res = await fetch(`${origin}/api/workspaces/${workspaceId}/regenerate-hook-token`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body?.hookToken ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/read-commands.mjs

@@ -20,8 +20,8 @@
  * returns the shape worth emitting, so it costs one line each.
  */
 
-import { makeClient, canAuthenticate, renderError } from './client.mjs';
-import { c } from './util.mjs';
+import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
+import { c, truncate } from './util.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
 function emit(flags, value, render) {
@@ -35,18 +35,21 @@ async function guard(workspaceId) {
   process.exit(1);
 }
 
-const trunc = (s, n) => (s && s.length > n ? `${s.slice(0, n - 1)}…` : (s ?? ''));
+// ⚠️ The old local helper measured `.length` — UTF-16 code units — so a CJK title
+// or an emoji made the column visibly ragged. truncate() from the theme measures
+// terminal columns instead.
+const trunc = (s, n) => truncate(s ?? '', n);
 
 // ── tasks ─────────────────────────────────────────────────────────────────────
 export async function cmdTasks(flags, ctx) {
   await guard(ctx.workspaceId);
   const limit = Number(flags.limit) || 20;
   try {
-    const rows = await makeClient(ctx).tasks.list({
+    const rows = await call(ctx, (m) => m.tasks.list({
       limit,
       ...(flags.status ? { status: flags.status } : {}),
       ...(flags.project ? { project: flags.project } : {}),
-    }).all();
+    }).all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No tasks match.'));
       console.log(c.bold(`${rows.length} task(s)`));
@@ -55,13 +58,13 @@ export async function cmdTasks(flags, ctx) {
         console.log(`  ${c.cyan(id)} ${String(t.status).padEnd(12)} ${c.dim(String(t.priority).padEnd(8))} ${trunc(t.title, 70)}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'tasks' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'tasks' }); }
 }
 
 export async function cmdNext(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const t = await makeClient(ctx).tasks.next();
+    const t = await call(ctx, (m) => m.tasks.next());
     emit(flags, t, () => {
       if (!t) return console.log(c.dim('Nothing queued — the board is clear.'));
       console.log(`${c.bold(t.publicId || t.id)}  ${t.title}`);
@@ -73,7 +76,7 @@ export async function cmdNext(flags, ctx) {
         console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'next' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'next' }); }
 }
 
 // ── docs ──────────────────────────────────────────────────────────────────────
@@ -81,7 +84,7 @@ export async function cmdDocs(flags, ctx) {
   await guard(ctx.workspaceId);
   const limit = Number(flags.limit) || 20;
   try {
-    const rows = await makeClient(ctx).docs.list({ limit }).all();
+    const rows = await call(ctx, (m) => m.docs.list({ limit }).all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No docs.'));
       console.log(c.bold(`${rows.length} doc(s)`));
@@ -89,7 +92,7 @@ export async function cmdDocs(flags, ctx) {
         console.log(`  ${c.dim(d.id.slice(0, 8))}  ${trunc(d.title, 60).padEnd(60)} ${c.dim(String(d.updatedAt).slice(0, 10))}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'docs' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'docs' }); }
 }
 
 export async function cmdDoc(flags, ctx, rest) {
@@ -97,7 +100,7 @@ export async function cmdDoc(flags, ctx, rest) {
   const id = rest[0];
   if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
   try {
-    const d = await makeClient(ctx).docs.get(id);
+    const d = await call(ctx, (m) => m.docs.get(id));
     // Markdown goes to stdout unadorned so `mnema doc <id> > file.md` works and
     // the heading is not silently baked into the file.
     emit(flags, d, () => {
@@ -105,20 +108,20 @@ export async function cmdDoc(flags, ctx, rest) {
       console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
       if (d.markdown) console.log(d.markdown);
     });
-  } catch (e) { renderError(e, { context: 'doc' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'doc' }); }
 }
 
 // ── projects ──────────────────────────────────────────────────────────────────
 export async function cmdProjects(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const rows = await makeClient(ctx).projects.list().all();
+    const rows = await call(ctx, (m) => m.projects.list().all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No projects.'));
       console.log(c.bold(`${rows.length} project(s)`));
       for (const p of rows) console.log(`  ${c.dim(p.id.slice(0, 8))}  ${trunc(p.name, 50)}`);
     });
-  } catch (e) { renderError(e, { context: 'projects' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'projects' }); }
 }
 
 // ── graph: ask + traverse ─────────────────────────────────────────────────────
@@ -127,7 +130,7 @@ export async function cmdAsk(flags, ctx, rest) {
   const q = rest.join(' ').trim();
   if (!q) { console.error(c.red('Usage: mnema ask "<question>"')); process.exit(1); }
   try {
-    const a = await makeClient(ctx).graph.ask(q, { ...(flags.budget ? { budgetMs: Number(flags.budget) } : {}) });
+    const a = await call(ctx, (m) => m.graph.ask(q, { ...(flags.budget ? { budgetMs: Number(flags.budget) } : {}) }));
     emit(flags, a, () => {
       console.log(a.answer);
       // ⚠️ NEVER WITHOUT THE CONFIDENCE. The interpreter deliberately hedges
@@ -138,11 +141,19 @@ export async function cmdAsk(flags, ctx, rest) {
       const line = `confidence ${pct}%${why} · tier ${a.tier}${a.usedFallback ? ' · fallback' : ''}`;
       console.log(pct >= 60 ? c.dim(`\n${line}`) : c.yellow(`\n${line} — treat as a lead, not a fact`));
       if (a.sources?.length) {
+        // ⚠️ THE HEADER USED TO LIE. It printed "sources (7):" and then listed
+        // five, silently. Either show them all or say how many are hidden —
+        // a count that does not match the rows under it teaches the reader to
+        // distrust every other number in the output.
+        const SHOWN = 5;
+        const shown = a.sources.slice(0, SHOWN);
+        const hidden = a.sources.length - shown.length;
         console.log(c.dim(`\nsources (${a.sources.length}):`));
-        for (const s of a.sources.slice(0, 5)) console.log(c.dim(`  ${trunc(s.title, 70)}`));
+        for (const s of shown) console.log(c.dim(`  ${trunc(s.title, 70)}`));
+        if (hidden > 0) console.log(c.dim(`  … ${hidden} more — --json for all`));
       }
     });
-  } catch (e) { renderError(e, { context: 'ask' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'ask' }); }
 }
 
 export async function cmdGraph(flags, ctx, rest) {
@@ -150,7 +161,7 @@ export async function cmdGraph(flags, ctx, rest) {
   const [from, to] = rest;
   if (!from) { console.error(c.red('Usage: mnema graph <from> [to]')); process.exit(1); }
   try {
-    const g = await makeClient(ctx).graph.traverse(from, to);
+    const g = await call(ctx, (m) => m.graph.traverse(from, to));
     emit(flags, g, () => {
       if (to) {
         // connected:false is an ANSWER, not a failure — say so plainly rather
@@ -164,16 +175,20 @@ export async function cmdGraph(flags, ctx, rest) {
         return;
       }
       console.log(c.bold(`${g.nodes.length} node(s), ${g.edges.length} edge(s) around "${from}"`));
-      for (const n of g.nodes.slice(0, 25)) console.log(`  ${trunc(n.label, 60).padEnd(60)} ${c.dim(n.type ?? '')}`);
+      // ⚠️ SAME LIE AS `ask`: the header reported the true count and the body
+      // stopped at 25 without a word.
+      const CAP = 25;
+      for (const n of g.nodes.slice(0, CAP)) console.log(`  ${trunc(n.label, 60).padEnd(60)} ${c.dim(n.type ?? '')}`);
+      if (g.nodes.length > CAP) console.log(c.dim(`  … ${g.nodes.length - CAP} more — --json for all`));
     });
-  } catch (e) { renderError(e, { context: 'graph' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'graph' }); }
 }
 
 // ── briefing ──────────────────────────────────────────────────────────────────
 export async function cmdBriefing(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const b = await makeClient(ctx).findings.briefing();
+    const b = await call(ctx, (m) => m.findings.briefing());
     emit(flags, b, () => {
       const p = b.pulse;
       console.log(c.bold('Pulse'));
@@ -192,5 +207,5 @@ export async function cmdBriefing(flags, ctx) {
         console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'briefing' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }

package/src/render/theme.mjs

@@ -0,0 +1,227 @@
+/**
+ * The CLI's presentation primitives (t-628).
+ *
+ * ⭐ COLOUR WAS UNCONDITIONAL, WHICH IS THE BUG UNDER THE BUG. util.mjs's `c`
+ * helper emitted `\x1b[Nm…\x1b[0m` with no isTTY check, no NO_COLOR, no
+ * FORCE_COLOR anywhere in the package — so `mnema tasks | less` and
+ * `mnema docs > out.txt` both contained raw escape bytes, and nothing in the CLI
+ * had any idea how wide the terminal was. Eleven separate hard-coded `padEnd`
+ * widths disagreed with each other because there was nothing to agree with.
+ *
+ * This is the one module that knows about the terminal. Everything above it asks
+ * questions ("how wide?", "truncate this") instead of writing escapes.
+ *
+ * ⚠️ THE ORDERING RULE THAT MUST NOT BREAK: pad and truncate the PLAIN string,
+ * then colour it. Alignment is correct in the current CLI only because every call
+ * site happens to do this by hand — `id.padEnd(8)` before `c.cyan(...)`. An
+ * escape sequence is zero columns wide but many characters long, so padding a
+ * coloured string pads by the wrong amount and the column silently drifts. Every
+ * helper here takes plain text and returns coloured text; none of them accepts
+ * pre-coloured input.
+ */
+
+/**
+ * ⚠️ THREE SIGNALS, IN THIS ORDER, and the order is the convention every other
+ * CLI follows: an explicit FORCE_COLOR wins, then NO_COLOR (https://no-color.org
+ * — presence alone counts, whatever the value), then whether stdout is a real
+ * terminal. Reading isTTY first would make FORCE_COLOR useless in exactly the
+ * case people set it: piping into something that renders colour itself.
+ */
+function detectColour() {
+  const env = process.env;
+  // ⚠️ AN EMPTY STRING IS "UNSET", NOT "ON". `FORCE_COLOR=` in a shell sets the
+  // variable to '' — and reading that as force-on made `NO_COLOR=1 FORCE_COLOR= …`
+  // emit colour anyway, which is precisely the combination someone types when
+  // they are trying hard to turn it off. Caught by the verification run, not by
+  // reading the code.
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '') {
+    return force !== '0' && force !== 'false';
+  }
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false;
+  if (env.TERM === 'dumb') return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+let colourEnabled = detectColour();
+
+/** Test seam. Production code never calls this. */
+export function setColour(on) { colourEnabled = on; }
+export function colourOn() { return colourEnabled; }
+
+const wrap = (open) => (s) => (colourEnabled ? `\x1b[${open}m${s}\x1b[0m` : String(s));
+
+/**
+ * Same six names the old `c` helper had, so the migration is a rename rather
+ * than a rewrite, plus the two the redesign needs.
+ */
+export const c = {
+  dim: wrap(2),
+  bold: wrap(1),
+  red: wrap(31),
+  green: wrap(32),
+  yellow: wrap(33),
+  cyan: wrap(36),
+  blue: wrap(34),
+  magenta: wrap(35),
+};
+
+/** Strip escapes — needed to measure anything that may already be coloured. */
+export function strip(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/**
+ * How many terminal columns a string occupies.
+ *
+ * ⚠️ NOT `.length`. The old `trunc()` measured UTF-16 code units, which is wrong
+ * three separate ways: a CJK ideograph is one unit but two columns, an emoji is
+ * two units and two columns, and a combining accent is one unit and zero columns.
+ * A list of Japanese doc titles came out visibly ragged.
+ *
+ * Uses Intl.Segmenter to walk graphemes so a family emoji or a flag counts once.
+ * It has been in Node since 16, and this package requires 18.
+ */
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+
+export function displayWidth(s) {
+  const plain = strip(s);
+  let w = 0;
+  for (const { segment } of segmenter.segment(plain)) {
+    const cp = segment.codePointAt(0);
+    if (cp === undefined) continue;
+    // Zero-width: combining marks, ZWJ, variation selectors, control chars.
+    if (cp === 0x200d || (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x0300 && cp <= 0x036f)) continue;
+    if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0)) continue;
+    w += isWide(cp) ? 2 : 1;
+  }
+  return w;
+}
+
+/** East Asian Wide + Fullwidth ranges, plus the emoji blocks that render double. */
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f)     // Hangul Jamo
+    || (cp >= 0x2e80 && cp <= 0xa4cf)  // CJK radicals … Yi
+    || (cp >= 0xac00 && cp <= 0xd7a3)  // Hangul syllables
+    || (cp >= 0xf900 && cp <= 0xfaff)  // CJK compatibility ideographs
+    || (cp >= 0xfe30 && cp <= 0xfe6f)  // CJK compatibility forms
+    || (cp >= 0xff00 && cp <= 0xff60)  // Fullwidth forms
+    || (cp >= 0xffe0 && cp <= 0xffe6)
+    || (cp >= 0x1f300 && cp <= 0x1f64f) // emoji
+    || (cp >= 0x1f900 && cp <= 0x1f9ff)
+    || (cp >= 0x20000 && cp <= 0x3fffd) // CJK ext B+
+  );
+}
+
+/**
+ * Truncate to `n` COLUMNS, with an ellipsis when it actually cut something.
+ *
+ * ⚠️ THE ELLIPSIS IS NOT DECORATION. `search` used to `slice(0, 140)` with no
+ * marker, so a preview that stopped mid-sentence was indistinguishable from a
+ * document that ended there. Everywhere that shortens text must say it did.
+ */
+export function truncate(s, n) {
+  const plain = strip(s ?? '');
+  if (n <= 0) return '';
+  if (displayWidth(plain) <= n) return plain;
+  let out = '';
+  let w = 0;
+  for (const { segment } of segmenter.segment(plain)) {
+    const sw = displayWidth(segment);
+    if (w + sw > n - 1) break;
+    out += segment;
+    w += sw;
+  }
+  return `${out}…`;
+}
+
+/** Pad to `n` columns. Plain text in, plain text out — colour afterwards. */
+export function pad(s, n, align = 'left') {
+  const plain = strip(s ?? '');
+  const gap = n - displayWidth(plain);
+  if (gap <= 0) return plain;
+  return align === 'right' ? ' '.repeat(gap) + plain : plain + ' '.repeat(gap);
+}
+
+/**
+ * Usable terminal width.
+ *
+ * COLUMNS is honoured because that is how a user (and every test) says "pretend
+ * the terminal is this wide" for something that is not a TTY. Clamped low so a
+ * 20-column terminal degrades rather than producing negative padding, and high so
+ * a maximised 4K window does not stretch a two-column list across 400 characters.
+ */
+export function width() {
+  const raw = Number(process.env.COLUMNS) || process.stdout.columns || 80;
+  return Math.max(40, Math.min(raw, 120));
+}
+
+/**
+ * Render aligned rows from `[{ cells: [...], style?: [...] }]`.
+ *
+ * ⭐ REPLACES ELEVEN HAND-PICKED padEnd WIDTHS. Column widths are measured from
+ * the content, then the LAST column absorbs whatever is left so a long title
+ * truncates instead of wrapping and destroying the alignment of every row under
+ * it. `style` is applied per cell AFTER padding, preserving the ordering rule at
+ * the top of this file.
+ */
+export function table(rows, { indent = 2, gap = 2, max = width() } = {}) {
+  if (!rows.length) return [];
+  const cols = Math.max(...rows.map((r) => r.cells.length));
+  const widths = [];
+  for (let i = 0; i < cols; i += 1) {
+    widths[i] = Math.max(...rows.map((r) => displayWidth(r.cells[i] ?? '')));
+  }
+  // Everything except the final column is fixed; the final column gets the rest.
+  const fixed = indent + widths.slice(0, -1).reduce((a, b) => a + b + gap, 0);
+  widths[cols - 1] = Math.max(8, max - fixed);
+
+  return rows.map((r) => {
+    const parts = r.cells.map((cell, i) => {
+      const isLast = i === cols - 1;
+      const text = isLast ? truncate(cell ?? '', widths[i]) : pad(cell ?? '', widths[i]);
+      const style = r.style?.[i];
+      // Trailing cell is not padded — a padded last column leaves invisible
+      // whitespace that shows up when someone copies a row out of the terminal.
+      const sized = isLast ? text : text;
+      return style ? style(sized) : sized;
+    });
+    return ' '.repeat(indent) + parts.join(' '.repeat(gap)).replace(/\s+$/, '');
+  });
+}
+
+/**
+ * One heading grammar.
+ *
+ * ⚠️ THE OLD CLI HAD FOUR: product-prefixed ("Mnema status"), noun + count
+ * ("Server sessions (7)"), count-first ("12 task(s)"), and bare noun ("Pulse").
+ * Nothing was wrong with any one of them; having four made the output read as
+ * four different programs.
+ */
+export function section(title, meta) {
+  const left = c.bold(title);
+  if (!meta) return left;
+  const room = width() - displayWidth(title) - displayWidth(meta) - 2;
+  return room > 0 ? `${left}${' '.repeat(room)}${c.dim(meta)}` : `${left}  ${c.dim(meta)}`;
+}
+
+/**
+ * A terminal hyperlink (OSC 8), degrading to plain text where unsupported.
+ *
+ * ⚠️ NOT EMITTED WHEN COLOUR IS OFF. The same detection covers both: if stdout is
+ * a pipe, an OSC 8 sequence is corruption in the consumer's data, not a link.
+ */
+export function link(label, url) {
+  if (!colourEnabled) return `${label} (${url})`;
+  return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
+
+/** Status glyphs, used consistently rather than ad hoc per command. */
+export const mark = {
+  ok: () => c.green('✓'),
+  bad: () => c.red('✗'),
+  warn: () => c.yellow('!'),
+  dot: () => c.dim('·'),
+};

package/src/util.mjs

@@ -28,14 +28,16 @@ export const DEFAULT_ORIGIN = process.env.MNEMA_API_ORIGIN || 'https://api.thebo
  */
 export const DEFAULT_APP_URL = process.env.MNEMA_APP_URL || 'https://mnema.theboringpeople.in';
 
-export const c = {
-  dim: (s) => `\x1b[2m${s}\x1b[0m`,
-  green: (s) => `\x1b[32m${s}\x1b[0m`,
-  red: (s) => `\x1b[31m${s}\x1b[0m`,
-  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
-  bold: (s) => `\x1b[1m${s}\x1b[0m`,
-  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
-};
+/**
+ * ⭐ RE-EXPORTED, NOT REDEFINED. `c` used to live here and emitted escapes
+ * unconditionally — no isTTY, no NO_COLOR — so `mnema tasks | less` was full of
+ * escape bytes and `mnema docs > out.txt` wrote them to disk.
+ *
+ * Re-exporting from render/theme.mjs means every existing
+ * `import { c } from './util.mjs'` picks up the TTY-aware version without a
+ * single call site changing. One line, whole-CLI effect.
+ */
+export { c, truncate, pad, table, section, width, link, mark, strip, displayWidth } from './render/theme.mjs';
 
 // ── git ──────────────────────────────────────────────────────────────────────
 
@@ -118,35 +120,92 @@ export async function apiFetch(origin, path, { token, method = 'GET', body } = {
 
 // ── prompts ────────────────────────────────────────────────────────────────────
 
+/**
+ * Ask a question and read one line.
+ *
+ * ⚠️ CTRL-D USED TO VANISH. There was no `close` handler, so EOF never resolved
+ * the promise — the process simply ran out of work and exited 0, halfway through
+ * `init`, with no message. A setup that stops silently and claims success is
+ * worse than one that fails, so EOF now rejects and the caller reports it.
+ */
 export function prompt(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+  return new Promise((resolve, reject) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answered = false;
+    rl.question(question, (a) => { answered = true; rl.close(); resolve(a.trim()); });
+    rl.on('close', () => {
+      if (!answered) reject(new Error('Cancelled.'));
+    });
+  });
 }
 
-/** Prompt without echoing (for secrets). Falls back to visible if not a TTY. */
+/**
+ * Prompt for a secret without echoing it.
+ *
+ * ⚠️ THREE THINGS WERE WRONG HERE, and two of them were security-adjacent.
+ *
+ * 1. NOTHING WAS ECHOED AT ALL — not even a mask. Pasting a 106-character API key
+ *    looked exactly like pressing nothing, so the only way to find out whether it
+ *    had registered was to hit Enter and see what happened. A dot per grapheme
+ *    fixes that without revealing length-sensitive content any more than the
+ *    cursor position already does.
+ *
+ * 2. CTRL-C EXITED WITHOUT RESTORING RAW MODE. Node usually repairs the tty on
+ *    exit, so it *usually* looked fine — which is exactly what makes it the kind
+ *    of bug that surfaces on someone else's terminal months later.
+ *
+ * 3. ESCAPE SEQUENCES WERE APPENDED VERBATIM. An arrow key is `\x1b[A`; that went
+ *    straight into the secret, as did Ctrl-U, Ctrl-W and bracketed-paste markers.
+ *    The user saw nothing (see 1) and got an authentication failure with no clue.
+ *    Control bytes are now filtered rather than stored.
+ *
+ * Falls back to a visible readline when stdin is not a TTY — deliberate, so
+ * `echo $TOKEN | mnema init` still works in CI.
+ */
 export function promptHidden(question) {
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     const { stdin, stdout } = process;
     if (!stdin.isTTY) {
-      // Non-interactive: read one line plainly.
       const rl = createInterface({ input: stdin, output: stdout });
-      rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+      let answered = false;
+      rl.question(question, (a) => { answered = true; rl.close(); resolve(a.trim()); });
+      rl.on('close', () => { if (!answered) reject(new Error('Cancelled.')); });
       return;
     }
+
     stdout.write(question);
     stdin.setRawMode(true);
     stdin.resume();
     let buf = '';
+
+    // One restore path for every exit, so raw mode cannot leak.
+    const restore = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+    };
+
     const onData = (ch) => {
       const s = ch.toString('utf8');
-      if (s === '\r' || s === '\n') {
-        stdin.setRawMode(false); stdin.pause(); stdin.removeListener('data', onData);
-        stdout.write('\n'); resolve(buf.trim()); return;
+
+      if (s === '\r' || s === '\n') { restore(); stdout.write('\n'); resolve(buf.trim()); return; }
+      if (s === '\u0003') { restore(); stdout.write('\n'); reject(new Error('Cancelled.')); return; }  // Ctrl-C
+      if (s === '\u0004') { restore(); stdout.write('\n'); reject(new Error('Cancelled.')); return; }  // Ctrl-D
+      if (s === '\u0015') { stdout.write(`\r${question}${' '.repeat(buf.length)}\r${question}`); buf = ''; return; } // Ctrl-U
+
+      if (s === '\u007f' || s === '\b') {
+        if (buf.length) { buf = buf.slice(0, -1); stdout.write('\b \b'); }
+        return;
       }
-      if (s === '') { stdout.write('\n'); process.exit(1); }        // Ctrl-C
-      if (s === '' || s === '\b') { buf = buf.slice(0, -1); return; } // backspace
+
+      // ⚠️ Drop anything with a control byte in it — arrow keys, function keys,
+      // bracketed-paste markers. Storing these was silent corruption of a secret.
+      if (/[\u0000-\u001f\u007f]/.test(s)) return;
+
       buf += s;
+      stdout.write('•'.repeat([...s].length));
     };
+
     stdin.on('data', onData);
   });
 }