@mnemahq/cli 0.3.1 → 0.7.0

package/src/login.mjs

@@ -13,7 +13,10 @@
  * then told the login "timed out". They didn't time out. They said no.
  */
 
-import { c, DEFAULT_ORIGIN } from './util.mjs';
+import { c, mark, DEFAULT_ORIGIN } from './util.mjs';
+import { spinner } from './render/wait.mjs';
+import { heading, entries } from './render/layout.mjs';
+import { openInBrowser } from './browser.mjs';
 import {
   backendName, clearState, deleteSecret, getSecret, readState, setSecret, writeState, NoKeychainError,
 } from './keychain.mjs';
@@ -61,52 +64,81 @@ export async function cmdLogin(flags = {}) {
     expires_in, interval,
   } = start.json;
 
+  // ⭐ ACTUALLY OPEN IT. `mnema --help` has promised "opens a browser" since 0.1.0
+  // and the CLI has never once done so — it printed the URL and waited. Opening is
+  // attempted BEFORE printing, so the "we opened it" line is only claimed when it
+  // is true; the URL is printed either way, because a headless box, an SSH session
+  // and a locked-down desktop all legitimately have nothing to open with.
+  const opened = await openInBrowser(verification_uri_complete || verification_uri, origin);
+
   console.log('');
-  console.log(`  Open  ${c.cyan(verification_uri)}`);
-  console.log(`  Code  ${c.bold(user_code)}`);
-  console.log('');
-  console.log(c.dim(`  Or go straight there: ${verification_uri_complete}`));
-  console.log(c.dim(`  The code expires in ${Math.round((expires_in ?? 600) / 60)} minutes.`));
+  heading('Sign in');
+  // ⚠️ MEASURED, NOT HAND-PADDED. Writing `'Open '` with a trailing space to line
+  // up under `Code` is the same hand-counted gutter t-630 removed from status,
+  // doctor and pull — and it silently breaks the moment either word changes.
+  entries([
+    { label: 'code', value: user_code, style: c.bold },
+    { label: opened ? 'opened' : 'open', value: verification_uri, style: c.cyan },
+    ...(opened ? [] : [{ label: '', value: verification_uri_complete, dim: true }]),
+    { label: 'expires', value: `in ${Math.round((expires_in ?? 600) / 60)} minutes`, dim: true },
+  ]);
   console.log('');
-  process.stdout.write(c.dim('  Waiting for approval…'));
 
   const deadline = Date.now() + (expires_in ?? 600) * 1000;
   let waitMs = (interval ?? 5) * 1000;
+  // ⚠️ ONE LINE THAT REDRAWS ITSELF, not a dot per poll. The old version wrote '.'
+  // every interval — up to 120 of them — which wraps and scrolls the user_code off
+  // the top of the screen. The code is the one thing they have to read.
+  const spin = spinner('Waiting for approval in your browser…');
 
-  for (;;) {
-    if (Date.now() > deadline) {
-      console.log('');
-      throw new Error('The code expired before it was approved. Run `mnema login` again.');
-    }
-    await sleep(waitMs);
-
-    const poll = await post(origin, '/oauth/token', {
-      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-      device_code,
-      client_id: CLIENT_ID,
-    });
-
-    if (poll.status === 200 && poll.json?.access_token) {
-      process.stdout.write('\r' + ' '.repeat(40) + '\r');
-      return finish(origin, poll.json, store);
-    }
-
-    const err = poll.json?.error;
-
-    if (err === 'authorization_pending') { process.stdout.write(c.dim('.')); continue; }
-
-    if (err === 'slow_down') {
-      // The server raised the interval and told us the new one. Honour it —
-      // ignoring slow_down is how a CLI gets a client id rate-limited.
-      waitMs = ((poll.json.interval ?? (waitMs / 1000) + 5)) * 1000;
-      continue;
+  try {
+    for (;;) {
+      if (Date.now() > deadline) {
+        spin.stop();
+        throw new Error('The code expired before it was approved. Run `mnema login` again.');
+      }
+
+      const poll = await post(origin, '/oauth/token', {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code,
+        client_id: CLIENT_ID,
+      });
+
+      if (poll.status === 200 && poll.json?.access_token) {
+        spin.stop();
+        return finish(origin, poll.json, store);
+      }
+
+      const err = poll.json?.error;
+
+      if (err === 'authorization_pending') {
+        // ⚠️ SLEEP AFTER THE CHECK, not before it. The old loop slept first, so
+        // someone who approved instantly still sat through a full interval
+        // watching nothing happen.
+        await sleep(waitMs);
+        continue;
+      }
+
+      if (err === 'slow_down') {
+        // The server raised the interval and told us the new one. Honour it —
+        // ignoring slow_down is how a CLI gets a client id rate-limited — but SAY
+        // so, because obeying it silently just makes the wait mysteriously longer.
+        waitMs = ((poll.json.interval ?? (waitMs / 1000) + 5)) * 1000;
+        spin.update(`Waiting for approval — the server asked us to slow to ${Math.round(waitMs / 1000)}s…`);
+        await sleep(waitMs);
+        continue;
+      }
+
+      // ⭐ Everything below is terminal, and each says what actually happened.
+      spin.stop();
+      if (err === 'access_denied') throw new Error('The login was denied in the browser.');
+      if (err === 'expired_token') throw new Error('The code expired before it was approved. Run `mnema login` again.');
+      throw new Error(`Login failed: ${poll.json?.error_description || err || `HTTP ${poll.status}`}`);
     }
-
-    // ⭐ Everything below is terminal, and each says what actually happened.
-    console.log('');
-    if (err === 'access_denied') throw new Error('The login was denied in the browser.');
-    if (err === 'expired_token') throw new Error('The code expired before it was approved. Run `mnema login` again.');
-    throw new Error(`Login failed: ${poll.json?.error_description || err || `HTTP ${poll.status}`}`);
+  } finally {
+    // Belt and braces: a throw from post() must not leave a timer running and the
+    // user's cursor parked mid-line.
+    spin.stop();
   }
 }
 
@@ -134,11 +166,15 @@ async function finish(origin, tokens, store) {
     logged_in_at: new Date().toISOString(),
   });
 
-  console.log(c.green('✓ Logged in.'));
-  if (who?.email) console.log(`  Account   : ${who.email}`);
-  if (who?.workspace_id) console.log(`  Workspace : ${who.workspace_id}`);
-  if (who?.plan) console.log(`  Plan      : ${who.plan}`);
-  console.log(`  Tokens    : ${c.dim(store)}`);
+  // Hand-counted gutters ('Account   :' is 10, 'Workspace :' is 10, 'Plan      :'
+  // is 11) were the same defect t-630 removed everywhere else. One table.
+  heading('Signed in');
+  entries([
+    ...(who?.email ? [{ label: 'account', value: who.email }] : []),
+    ...(who?.workspace_id ? [{ label: 'workspace', value: who.workspace_id }] : []),
+    ...(who?.plan ? [{ label: 'plan', value: who.plan }] : []),
+    { label: 'tokens', value: store, dim: true },
+  ]);
   console.log('');
   return 0;
 }
@@ -185,6 +221,6 @@ export async function cmdLogout() {
   deleteSecret(`${ACCOUNT}:access`);
   deleteSecret(`${ACCOUNT}:refresh`);
   clearState();
-  console.log(c.green('✓ Logged out.') + c.dim(' Tokens removed from ' + backendName() + '.'));
+  console.log(`${mark.ok()} ${c.green('Logged out.')}${c.dim(` Tokens removed from ${backendName()}.`)}`);
   return 0;
 }

package/src/paging.mjs

@@ -0,0 +1,50 @@
+/**
+ * Stop reading when the caller has enough (t-630).
+ *
+ * ⭐ `--limit` DID NOT LIMIT ANYTHING. Every read command called `.all()`, and
+ * `paginate()` follows `next_cursor` to exhaustion — `limit` is only the page-SIZE
+ * query parameter. So a smaller `--limit` made the CLI do strictly more work:
+ *
+ *     mnema docs --limit 5
+ *       /api/public/v1/docs?limit=5
+ *       /api/public/v1/docs?limit=5&cursor=59e921a0-…
+ *       /api/public/v1/docs?limit=5&cursor=92360dfa-…
+ *       …and on, and on
+ *
+ * Measured against prod: it blew past a 10-request cap and was still walking the
+ * cursor chain. `mnema docs --limit 5` never returned — it was the command that
+ * hung this branch's own baseline capture — and had it finished it would have
+ * printed EVERY document, because the header counts the rows it collected.
+ *
+ * ⚠️ SO THE PRINTED COUNT CHANGES with this fix, and that is the point: it used to
+ * be "everything you have", now it is "what you asked for".
+ *
+ * `Paginated<T>` is an AsyncIterable, so stopping is simply a `break` — the
+ * generator is closed and the next page is never requested.
+ */
+
+/**
+ * Read at most `limit` items.
+ *
+ * Returns `more` so callers can say that the list was cut. A row count that
+ * silently means "there might be others" is the same lie `ask` and `graph` used to
+ * tell with their headers, and it is worth exactly as little.
+ */
+export async function take(paginated, limit) {
+  // ⚠️ `>= 0`, NOT `> 0`. With `> 0` a limit of ZERO fell through to Infinity and
+  // fetched the entire workspace — the exact bug this module exists to fix, hiding
+  // inside the fix, and it made the `max === 0` guard below unreachable. An
+  // explicit 0 means zero rows; only undefined, NaN or a negative is "unbounded".
+  const max = Number.isFinite(limit) && limit >= 0 ? Math.floor(limit) : Infinity;
+  const rows = [];
+  if (max === 0) return { rows, more: false };
+
+  for await (const item of paginated) {
+    rows.push(item);
+    // Read ONE past the limit rather than stopping exactly on it: that extra item
+    // is the only way to distinguish "exactly this many exist" from "there are
+    // more", and getting it wrong means the footer either lies or never appears.
+    if (rows.length > max) return { rows: rows.slice(0, max), more: true };
+  }
+  return { rows, more: false };
+}

package/src/read-commands.mjs

@@ -1,5 +1,5 @@
 /**
- * The read commands — tasks, docs, projects, ask, graph, briefing (t-624).
+ * The read commands — tasks, docs, projects, ask, graph, briefing (t-624, t-630).
  *
  * ⭐ EVERY ONE OF THESE IS A WRAPPER, NOT A CLIENT. They exist because t-623 put
  * the CLI on @mnemahq/sdk; each is four lines of SDK call plus formatting, and
@@ -16,12 +16,19 @@
  *             news. On a core build six of seven finding families cannot produce
  *             anything at all, and `coverage.notice` is the only thing that says so.
  *
+ * t-630 moved every heading, row and empty state onto render/layout.mjs so the
+ * grammar is one module's job rather than eleven call sites', and put `--limit`
+ * through take() so it stops the pagination instead of decorating it.
+ *
  * --json everywhere: a CLI you cannot pipe is half a CLI, and the SDK already
  * returns the shape worth emitting, so it costs one line each.
  */
 
 import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
-import { c } from './util.mjs';
+import { take } from './paging.mjs';
+import { c, truncate, link, mark } from './util.mjs';
+import { heading, empty, rows, more, copyable } from './render/layout.mjs';
+import { pick } from './render/pick.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
 function emit(flags, value, render) {
@@ -35,25 +42,34 @@ async function guard(workspaceId) {
   process.exit(1);
 }
 
-const trunc = (s, n) => (s && s.length > n ? `${s.slice(0, n - 1)}…` : (s ?? ''));
+const limitOf = (flags, fallback) => Number(flags.limit) || fallback;
+
+/** The short id a human actually reads back to you. */
+const shortId = (row) => row.publicId || String(row.id).slice(0, 8);
 
 // ── tasks ─────────────────────────────────────────────────────────────────────
 export async function cmdTasks(flags, ctx) {
   await guard(ctx.workspaceId);
-  const limit = Number(flags.limit) || 20;
+  const limit = limitOf(flags, 20);
   try {
-    const rows = await call(ctx, (m) => m.tasks.list({
+    const page = await call(ctx, (m) => take(m.tasks.list({
       limit,
       ...(flags.status ? { status: flags.status } : {}),
       ...(flags.project ? { project: flags.project } : {}),
-    }).all());
-    emit(flags, rows, () => {
-      if (!rows.length) return console.log(c.dim('No tasks match.'));
-      console.log(c.bold(`${rows.length} task(s)`));
-      for (const t of rows) {
-        const id = (t.publicId || t.id.slice(0, 8)).padEnd(8);
-        console.log(`  ${c.cyan(id)} ${String(t.status).padEnd(12)} ${c.dim(String(t.priority).padEnd(8))} ${trunc(t.title, 70)}`);
+    }), limit));
+    emit(flags, page.rows, () => {
+      heading('Tasks', page.rows.length);
+      if (!page.rows.length) {
+        return empty(
+          flags.status || flags.project ? 'No tasks match those filters.' : 'No tasks yet.',
+          flags.status || flags.project ? 'Drop the filters to see the whole board.' : undefined,
+        );
       }
+      rows(page.rows.map((t) => ({
+        cells: [shortId(t), String(t.status), String(t.priority), t.title ?? ''],
+        style: [c.cyan, undefined, c.dim, undefined],
+      })));
+      more(page.more, `mnema tasks --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'tasks' }); }
 }
@@ -63,14 +79,26 @@ export async function cmdNext(flags, ctx) {
   try {
     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}`);
-      if (t.description) console.log(c.dim(trunc(t.description.replace(/\s+/g, ' '), 300)));
-      // The branch name is the load-bearing part of this project's dev loop, so
-      // the CLI hands it over ready to paste rather than making it be derived.
+      heading('Next');
+      if (!t) return empty('Nothing queued — the board is clear.');
+      rows([{ cells: [shortId(t), t.title ?? ''], style: [c.cyan, undefined] }]);
+      if (t.description) {
+        console.log(c.dim(`  ${truncate(t.description.replace(/\s+/g, ' '), 300)}`));
+      }
+      // A real URL, so make it clickable where the terminal supports it. link()
+      // degrades to "label (url)" when colour is off, rather than emitting an OSC 8
+      // sequence into someone's pipe.
+      if (t.githubPrUrl) console.log(`  ${c.dim('pr:')} ${link(t.githubPrUrl, t.githubPrUrl)}`);
+      // ⚠️ THE BRANCH NAME IS THE LOAD-BEARING PART OF THIS PROJECT'S DEV LOOP —
+      // it is the only signal that needs no cooperation from anything else, and
+      // from it the hook links the session, the PR links the task and the board
+      // moves on its own. So it is printed PLAIN: no colour, no padding, no
+      // truncation, because a padded string carries invisible trailing whitespace
+      // into the clipboard and an escape sequence carries worse.
       if (t.publicId) {
-        const slug = t.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
-        console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
+        const slug = String(t.title ?? '').toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+        copyable('branch:', `git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
       }
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'next' }); }
@@ -79,30 +107,59 @@ export async function cmdNext(flags, ctx) {
 // ── docs ──────────────────────────────────────────────────────────────────────
 export async function cmdDocs(flags, ctx) {
   await guard(ctx.workspaceId);
-  const limit = Number(flags.limit) || 20;
+  const limit = limitOf(flags, 20);
   try {
-    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)`));
-      for (const d of rows) {
-        console.log(`  ${c.dim(d.id.slice(0, 8))}  ${trunc(d.title, 60).padEnd(60)} ${c.dim(String(d.updatedAt).slice(0, 10))}`);
-      }
+    const page = await call(ctx, (m) => take(m.docs.list({ limit }), limit));
+    emit(flags, page.rows, () => {
+      heading('Documents', page.rows.length);
+      if (!page.rows.length) return empty('No documents yet.', 'Docs you write in the app show up here.');
+      rows(page.rows.map((d) => ({
+        cells: [String(d.id).slice(0, 8), String(d.updatedAt).slice(0, 10), d.title ?? ''],
+        style: [c.dim, c.dim, undefined],
+      })));
+      more(page.more, `mnema docs --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'docs' }); }
 }
 
 export async function cmdDoc(flags, ctx, rest) {
   await guard(ctx.workspaceId);
-  const id = rest[0];
-  if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
+  let id = rest[0];
+  // ⭐ OFFER, DO NOT DEMAND. With no id this printed a usage line, so the real
+  // workflow was: run `mnema docs`, read a truncated title, select eight hex
+  // characters with the mouse, paste them back. The list command already knows
+  // every id; asking the user to ferry one across is work the tool can do.
+  //
+  // ⚠️ Only when a human is actually there. pick() returns null on a non-TTY (and
+  // --json means a script is reading), so the usage error remains the answer for
+  // every non-interactive caller — no hanging on a stdin that will never speak.
+  // ⚠️ CHECK THE TERMINAL BEFORE THE NETWORK. Testing interactivity only inside
+  // pick() meant a piped `mnema doc` fetched fifty documents and then threw them
+  // away — a round trip, and a rate-limit slot, spent on a picker nobody can see.
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  if (!id && !flags.json && interactive) {
+    const page = await call(ctx, (m) => take(m.docs.list({ limit: 50 }), 50)).catch(() => null);
+    if (page?.rows.length) {
+      const chosen = await pick(
+        page.rows.map((d) => ({ label: `${d.title ?? '(untitled)'}  ${String(d.updatedAt).slice(0, 10)}` })),
+        { title: 'Which document?' },
+      );
+      if (chosen === null) return;
+      id = page.rows[chosen].id;
+    }
+  }
+  if (!id) {
+    console.error(c.red('Usage: mnema doc <id>'));
+    console.error(c.dim('  Run it without an id in a terminal to pick from a list.'));
+    process.exit(1);
+  }
   try {
     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.
+    // ⚠️ MARKDOWN TO STDOUT, EVERYTHING ELSE TO STDERR, so `mnema doc <id> > f.md`
+    // gets the document alone and the heading is not silently baked into the file.
     emit(flags, d, () => {
-      console.error(c.bold(d.title));
-      console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
+      console.error(c.bold(d.title ?? '(untitled)'));
+      console.error(c.dim(`${d.path ?? ''} · updated ${String(d.updatedAt).slice(0, 10)}`));
       if (d.markdown) console.log(d.markdown);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'doc' }); }
@@ -111,12 +168,17 @@ export async function cmdDoc(flags, ctx, rest) {
 // ── projects ──────────────────────────────────────────────────────────────────
 export async function cmdProjects(flags, ctx) {
   await guard(ctx.workspaceId);
+  const limit = limitOf(flags, 50);
   try {
-    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)}`);
+    const page = await call(ctx, (m) => take(m.projects.list(), limit));
+    emit(flags, page.rows, () => {
+      heading('Projects', page.rows.length);
+      if (!page.rows.length) return empty('No projects yet.');
+      rows(page.rows.map((p) => ({
+        cells: [String(p.id).slice(0, 8), p.name ?? ''],
+        style: [c.dim, undefined],
+      })));
+      more(page.more, `mnema projects --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'projects' }); }
 }
@@ -138,8 +200,12 @@ 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) {
-        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)}`));
+        const SHOWN = 5;
+        const shown = a.sources.slice(0, SHOWN);
+        console.log('');
+        heading('Sources', a.sources.length);
+        rows(shown.map((s) => ({ cells: [truncate(s.title ?? '', 70)], style: [c.dim] })));
+        more(a.sources.length - shown.length, 'mnema ask --json "…"');
       }
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'ask' }); }
@@ -153,18 +219,27 @@ export async function cmdGraph(flags, ctx, rest) {
     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
+        // ⚠️ connected:false IS AN ANSWER, not a failure — say so plainly rather
         // than printing an empty list and letting it read as an error.
-        if (!g.connected) return console.log(c.yellow(`No route between "${from}" and "${to}".`));
-        console.log(c.bold(`${g.hopCount} hop(s) from "${from}" to "${to}"`));
-        for (const id of g.path) {
-          const n = g.nodes.find((x) => x.id === id);
-          console.log(`  ${n ? trunc(n.label, 60) : id}${n?.type ? c.dim(`  [${n.type}]`) : ''}`);
+        if (!g.connected) {
+          heading('Path');
+          return empty(`No route between "${from}" and "${to}".`, 'They are in the graph but nothing links them.');
         }
+        heading('Path', `${g.hopCount} hop${g.hopCount === 1 ? '' : 's'}`);
+        rows(g.path.map((id) => {
+          const n = g.nodes.find((x) => x.id === id);
+          return { cells: [n?.type ?? '', n ? truncate(n.label, 60) : id], style: [c.dim, undefined] };
+        }));
         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 ?? '')}`);
+      const CAP = 25;
+      heading(`Around "${from}"`, `${g.nodes.length} node${g.nodes.length === 1 ? '' : 's'} · ${g.edges.length} edge${g.edges.length === 1 ? '' : 's'}`);
+      if (!g.nodes.length) return empty(`Nothing is connected to "${from}" yet.`);
+      rows(g.nodes.slice(0, CAP).map((n) => ({
+        cells: [n.type ?? '', truncate(n.label, 60)],
+        style: [c.dim, undefined],
+      })));
+      more(g.nodes.length - CAP, `mnema graph --json "${from}"`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'graph' }); }
 }
@@ -176,21 +251,26 @@ export async function cmdBriefing(flags, ctx) {
     const b = await call(ctx, (m) => m.findings.briefing());
     emit(flags, b, () => {
       const p = b.pulse;
-      console.log(c.bold('Pulse'));
-      console.log(`  ${p.activeProjects} active project(s) · ${p.problemsInActiveProjects} problem(s) · $${p.cost7dUsd} last 7d`);
+      heading('Pulse');
+      rows([
+        { cells: ['projects', String(p.activeProjects)], style: [c.dim, undefined] },
+        { cells: ['problems', String(p.problemsInActiveProjects)], style: [c.dim, p.problemsInActiveProjects > 0 ? c.yellow : undefined] },
+        { cells: ['spend 7d', `$${p.cost7dUsd}`], style: [c.dim, undefined] },
+      ]);
 
       // ⚠️ THE CAVEATS COME BEFORE THE LIST, on purpose. A short list has three
       // causes and only one is good news; printing the findings first invites the
       // reader to conclude "all clear" before reaching the reason it is short.
-      if (b.neverComputed) console.log(c.yellow('\n  The findings engine has never run for this workspace.'));
-      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${b.coverage.notice}`));
+      if (b.neverComputed) console.log(c.yellow(`\n  ${mark.warn()} The findings engine has never run for this workspace.`));
+      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${mark.warn()} ${b.coverage.notice}`));
 
-      console.log(c.bold(`\nFindings (${b.findings.length})`));
-      if (!b.findings.length) console.log(c.dim('  nothing surfaced'));
-      for (const f of b.findings) {
-        const count = f.grouped ? c.dim(` ×${f.count}`) : '';
-        console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
-      }
+      console.log('');
+      heading('Findings', b.findings.length);
+      if (!b.findings.length) return empty('Nothing surfaced.');
+      rows(b.findings.map((f) => ({
+        cells: [String(f.kind), `${truncate(f.headline, 90)}${f.grouped ? ` ×${f.count}` : ''}`],
+        style: [c.dim, undefined],
+      })));
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }

package/src/render/layout.mjs

@@ -0,0 +1,117 @@
+/**
+ * One output grammar for the whole CLI (t-630).
+ *
+ * ⭐ THE CLI READ AS FOUR DIFFERENT PROGRAMS. Not because any one line was wrong,
+ * but because there were four heading grammars in eleven call sites:
+ *
+ *     Mnema status                     product-prefixed
+ *     Server sessions (7)              noun + parenthesised count
+ *     12 task(s)                       count-first, with the "(s)" tell
+ *     Pulse                            bare noun
+ *
+ * and three empty-state voices ("No docs.", "none found", "nothing surfaced"), and
+ * eleven hand-picked padEnd widths that had nothing to agree with. t-628 built the
+ * primitives; this module spends them, and it exists so the grammar is enforced by
+ * a function signature rather than by everyone remembering.
+ *
+ * The grammar, in one line each:
+ *
+ *     heading    Title Case noun, left. Count or context, dim, right.
+ *     rows       a table. Columns measured from content, last column absorbs.
+ *     empty      one dim sentence saying what is absent, then what to do.
+ *     footer     never a bare number. If something was cut, the command to see it.
+ *
+ * ⚠️ AND ONE RULE THAT IS NOT COSMETIC: anything the user is meant to COPY —
+ * the branch name from `next`, a conflict path from `pull` — is printed plain.
+ * No colour, no padding, no truncation. A padded string carries invisible trailing
+ * whitespace into their clipboard and an escape sequence carries worse.
+ */
+
+import { c, section, table, truncate, width, mark, glyph } from './theme.mjs';
+
+/** `Tasks                                        12` */
+export function heading(title, meta) {
+  console.log(section(title, meta == null ? undefined : String(meta)));
+}
+
+/**
+ * The one empty state.
+ *
+ * `hint` is where the CLI earns its keep: "No documents yet." is a dead end,
+ * "No documents yet. / Docs you create in the app appear here." is an answer.
+ */
+export function empty(sentence, hint) {
+  console.log(c.dim(`  ${sentence}`));
+  if (hint) console.log(c.dim(`  ${hint}`));
+}
+
+/** Aligned rows. `rows` is `[{ cells, style? }]` — see theme.table. */
+export function rows(list, opts) {
+  for (const line of table(list, opts)) console.log(line);
+}
+
+/**
+ * What was left out, and the exact command that shows it.
+ *
+ * ⚠️ THIS IS THE ANTI-LIE. Three places used to print a header count and then a
+ * shorter body with no word about it: `ask` said "sources (7)" and listed five,
+ * `graph` capped at 25 silently, `search` cut previews mid-sentence. A count that
+ * disagrees with the rows beneath it teaches the reader to distrust every other
+ * number in the output.
+ */
+export function more(hiddenOrTrue, command) {
+  if (!hiddenOrTrue) return;
+  const what = typeof hiddenOrTrue === 'number' ? `${hiddenOrTrue} more` : 'more available';
+  console.log(c.dim(`  … ${what} — ${command}`));
+}
+
+/** A line the user is expected to copy. Plain, always. */
+export function copyable(label, text) {
+  console.log(`\n  ${c.dim(label)} ${text}`);
+}
+
+/**
+ * `[glyph] label   value` — ONE primitive for every label/value block.
+ *
+ * ⚠️ ONE CALL, ONE TABLE, and that matters more than it looks. My first pass at
+ * `status` used three separate helpers, so the three groups measured their label
+ * columns independently and printed at three different widths — reproducing, in
+ * miniature, the exact defect this PR exists to remove. Anything meant to line up
+ * has to be measured together, which means it has to be ONE call.
+ *
+ * `state` is: true → ✓, false → ✗, 'warn' → !, null/undefined → no glyph at all.
+ * A blank glyph rather than a dot, because a bullet in front of "workspace" is
+ * decoration pretending to be information.
+ *
+ * ⚠️ PLAIN GLYPH + STYLE FUNCTION, never mark.ok(). table() strips escapes in
+ * order to measure a cell, so a pre-coloured glyph goes in coloured and comes out
+ * plain — which is what happened the first time I wrote the doctor list, and it
+ * rendered with colourless ticks. Pad first, colour last, always.
+ */
+export function entries(list) {
+  const g = (state) => {
+    if (state === true) return [glyph.ok, c.green];
+    if (state === false) return [glyph.bad, c.red];
+    if (state === 'warn') return [glyph.warn, c.yellow];
+    return ['', undefined];
+  };
+  rows(list.map((e) => {
+    const [mk, mkStyle] = g(e.state);
+    return {
+      cells: [mk, e.label, e.value ?? ''],
+      style: [mkStyle, c.dim, e.dim ? c.dim : e.style],
+    };
+  }));
+}
+
+/** Check list — every row carries a pass/fail glyph. */
+export function checks(list) {
+  entries(list.map((ch) => ({ label: ch.label, value: ch.note ?? '', state: ch.pass ?? false, dim: true })));
+}
+
+/** Plain `label   value` rows, no glyph column content. */
+export function fields(pairs) {
+  entries(pairs.map(([label, value, style]) => ({ label, value, state: null, style })));
+}
+
+export { c, truncate, width, mark };