@mnemahq/cli 0.4.0 → 0.9.0

package/src/render/mark-art.mjs

@@ -0,0 +1,160 @@
+/**
+ * The Mnema mark, drawn in a terminal (t-636).
+ *
+ * ⭐ THE TRICK IS '▀'. One character cell carries TWO vertical pixels: the
+ * foreground colour paints the upper half, the background colour the lower half.
+ * That doubles vertical resolution, which matters enormously because a terminal
+ * cell is roughly twice as tall as it is wide — without it, any mark comes out
+ * squashed to half height and reads as a smudge.
+ *
+ * ⚠️ RASTERISED FROM THE REAL GEOMETRY, NOT EYEBALLED. The mark is
+ * apps/web/public/favicon.svg and it is three shapes on a 100×100 field:
+ *
+ *     left stem   rect x=24 y=13 w=11 h=74     (full height, has the descender)
+ *     right stem  rect x=65 y=13 w=11 h=47     (stops where the arch meets it)
+ *     arch        M24,60 C24,80 76,80 76,60 L65,60 C65,73 35,73 35,60 Z
+ *
+ * Hand-drawing an ASCII approximation would drift from the brand the first time
+ * either changed, and nothing would catch it. Evaluating the actual geometry means
+ * the terminal mark IS the mark — and it costs about forty lines, no dependency,
+ * and no SVG parser.
+ */
+
+const BLACK = [0x00, 0x00, 0x00];
+const CREAM = [0xed, 0xe8, 0xdc];
+
+// ── the geometry, straight from favicon.svg ──────────────────────────────────
+
+/** Cubic Bézier, flattened to points. */
+function cubic(p0, p1, p2, p3, steps = 24) {
+  const out = [];
+  for (let i = 0; i <= steps; i += 1) {
+    const t = i / steps;
+    const u = 1 - t;
+    out.push([
+      u * u * u * p0[0] + 3 * u * u * t * p1[0] + 3 * u * t * t * p2[0] + t * t * t * p3[0],
+      u * u * u * p0[1] + 3 * u * u * t * p1[1] + 3 * u * t * t * p2[1] + t * t * t * p3[1],
+    ]);
+  }
+  return out;
+}
+
+/**
+ * The arch as one closed polygon: the outer curve, across, then the inner curve
+ * back. It is a single subpath in the SVG and does not self-intersect, so
+ * even-odd and nonzero agree and a plain point-in-polygon test is exact.
+ */
+const ARCH = [
+  ...cubic([24, 60], [24, 80], [76, 80], [76, 60]),
+  [65, 60],
+  ...cubic([65, 60], [65, 73], [35, 73], [35, 60]),
+];
+
+function inPolygon(x, y, poly) {
+  let inside = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i, i += 1) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if ((yi > y) !== (yj > y) && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+const inRect = (x, y, rx, ry, w, h) => x >= rx && x < rx + w && y >= ry && y < ry + h;
+
+/** Is this point on the cream part of the mark? */
+function inMark(x, y) {
+  return inRect(x, y, 24, 13, 11, 74)      // left stem
+    || inRect(x, y, 65, 13, 11, 47)        // right stem
+    || inPolygon(x, y, ARCH);              // arch
+}
+
+// ── rasterising ──────────────────────────────────────────────────────────────
+
+/**
+ * Coverage of one output pixel, 0..1, by supersampling.
+ *
+ * Antialiasing is not decoration here: at ~14 pixels across, a hard threshold
+ * turns the arch's curve into a staircase, and the two stems end up different
+ * widths depending on where the sample grid happens to land.
+ */
+function coverage(px, py, cols, pxRows, viewW, viewH, samples = 4) {
+  // ⚠️ CROPPED TO THE GLYPH, NOT THE ARTBOARD. The SVG's 100×100 field carries
+  // generous margins (the mark itself only occupies x 24..76, y 13..87), so
+  // rasterising the whole artboard spends a third of a small tile on emptiness
+  // and leaves the stems under a pixel wide. `view` is a square window centred on
+  // the glyph, which is what lets it stay legible at header size.
+  let hit = 0;
+  for (let sy = 0; sy < samples; sy += 1) {
+    for (let sx = 0; sx < samples; sx += 1) {
+      const x = 50 - viewW / 2 + ((px + (sx + 0.5) / samples) / cols) * viewW;
+      const y = 50 - viewH / 2 + ((py + (sy + 0.5) / samples) / pxRows) * viewH;
+      if (inMark(x, y)) hit += 1;
+    }
+  }
+  return hit / (samples * samples);
+}
+
+// The glyph's own bounding box, plus a little air. Cropping to THIS rather than to
+// a square is what makes the tile compact: the mark is 52 wide and 74 tall, so a
+// square tile would spend a third of its width on nothing.
+const GLYPH_W = 52 + 10;
+const GLYPH_H = 74 + 10;
+
+const mix = (a, b, t) => a.map((v, i) => Math.round(v + (b[i] - v) * t));
+
+/** Nearest xterm-256 index, for terminals without truecolour. */
+function to256([r, g, b]) {
+  const q = (v) => (v < 48 ? 0 : v < 114 ? 1 : Math.min(5, Math.round((v - 35) / 40)));
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+/**
+ * How much colour this terminal can actually show.
+ *
+ * ⚠️ TRUECOLOUR IS NOT IMPLIED BY 256-COLOUR SUPPORT and there is no query for it
+ * that works everywhere — COLORTERM is the convention. Guessing wrong does not
+ * degrade gracefully: a 24-bit sequence on a terminal that cannot read it prints
+ * the escape as literal text across the screen.
+ */
+export function colourDepth(env = process.env) {
+  const ct = String(env.COLORTERM ?? '').toLowerCase();
+  if (ct.includes('truecolor') || ct.includes('24bit')) return 24;
+  if (/-256(color)?$/.test(String(env.TERM ?? ''))) return 8;
+  return 4;
+}
+
+/**
+ * The mark, as an array of lines ready to print.
+ *
+ * @param size  pixels across; the output is `size` columns and `size/2` rows.
+ */
+export function markLines({ rows: wantRows = 5, depth = colourDepth(), tile = BLACK, ink = CREAM } = {}) {
+  // Below 24-bit there is no honest way to draw a two-tone antialiased mark, and a
+  // banded approximation looks like a rendering fault rather than a logo. The
+  // caller falls back to a wordmark.
+  if (depth < 8) return null;
+
+  // Half-blocks give SQUARE pixels — one cell is one column wide and two pixel
+  // rows tall — so the aspect ratio is preserved by matching the pixel grid to the
+  // glyph's box rather than by fudging either dimension.
+  const pxRows = wantRows * 2;
+  const cols = Math.max(3, Math.round(pxRows * (GLYPH_W / GLYPH_H)));
+
+  const rows = [];
+  for (let y = 0; y < pxRows; y += 2) {
+    let line = '';
+    for (let x = 0; x < cols; x += 1) {
+      const top = mix(tile, ink, coverage(x, y, cols, pxRows, GLYPH_W, GLYPH_H));
+      const bot = mix(tile, ink, coverage(x, y + 1, cols, pxRows, GLYPH_W, GLYPH_H));
+      line += depth >= 24
+        ? `\x1b[38;2;${top.join(';')}m\x1b[48;2;${bot.join(';')}m▀`
+        : `\x1b[38;5;${to256(top)}m\x1b[48;5;${to256(bot)}m▀`;
+    }
+    rows.push(`${line}\x1b[0m`);
+  }
+  return rows;
+}
+
+/** Plain-text identity for terminals that cannot draw, and for pipes. */
+export const WORDMARK = 'mnema';

package/src/render/pick.mjs

@@ -0,0 +1,131 @@
+/**
+ * Choose from a list without copying an id (t-631).
+ *
+ * ⭐ THE CLI KEPT ASKING FOR THINGS IT COULD OFFER. `mnema doc` with no argument
+ * printed "Usage: mnema doc <id>" — so the actual workflow was: run `mnema docs`,
+ * read a truncated title, select eight hex characters with the mouse, paste. Every
+ * id in this CLI is a UUID prefix that nobody can hold in their head, and the list
+ * command already knows all of them.
+ *
+ * ⚠️ RAW MODE IS THE DANGEROUS PART, and the danger is entirely in the exits. A
+ * process that leaves the terminal in raw mode with the cursor hidden hands back a
+ * shell where typing shows nothing and Ctrl-C does not work — the user's next move
+ * is to close the window. So there is exactly ONE restore path here, every exit
+ * goes through it, and it is also wired to SIGINT and to process exit. This is the
+ * single most damaging thing a terminal UI can get wrong, and it is worth more care
+ * than the feature itself.
+ */
+
+import { c, truncate, width } from './theme.mjs';
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+const CLEAR = '\x1b[K';
+
+/** How many rows to show at once. Longer lists scroll within this window. */
+const WINDOW = 10;
+
+/**
+ * @param items  [{ label, hint }]
+ * @returns the chosen index, or null if cancelled / not interactive
+ */
+export function pick(items, { title = 'Select', stream = process.stderr, input = process.stdin } = {}) {
+  // Not interactive: there is nothing to drive the selection with. Returning null
+  // rather than hanging on a stdin that will never produce a keypress.
+  if (!items.length || !input.isTTY || !stream.isTTY || typeof input.setRawMode !== 'function') {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let top = 0;
+    let drawn = 0;
+    let finished = false;
+
+    const paint = () => {
+      // Move back over what we drew last time, clearing as we go.
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      const w = width();
+      const lines = [];
+      lines.push(`${c.bold(title)}  ${c.dim('↑↓ move · enter select · esc cancel')}`);
+      const view = items.slice(top, top + WINDOW);
+      for (let i = 0; i < view.length; i += 1) {
+        const idx = top + i;
+        const on = idx === cursor;
+        const label = truncate(view[i].label ?? '', w - 6);
+        // ⚠️ Colour AFTER truncation — the ordering rule from t-628. Truncating a
+        // coloured string cuts inside the escape and leaves the terminal stuck in
+        // whatever attribute was open.
+        lines.push(on ? `${c.cyan('❯')} ${c.bold(label)}` : `  ${c.dim(label)}`);
+      }
+      if (items.length > WINDOW) {
+        lines.push(c.dim(`  ${cursor + 1}/${items.length}`));
+      }
+      stream.write(lines.map((l) => `${CLEAR}${l}`).join('\n') + '\n');
+      drawn = lines.length;
+    };
+
+    // ⭐ ONE restore path. Every exit — enter, esc, Ctrl-C, an unexpected throw,
+    // the process dying — comes through here, and it is idempotent.
+    const restore = () => {
+      if (finished) return;
+      finished = true;
+      try { input.setRawMode(false); } catch { /* already closed */ }
+      input.pause();
+      input.removeListener('data', onData);
+      process.removeListener('SIGINT', onSigint);
+      process.removeListener('exit', restore);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      for (let i = 0; i < drawn; i += 1) stream.write(`${CLEAR}\n`);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      stream.write(SHOW);
+    };
+
+    function onSigint() {
+      restore();
+      // Exit the way an unhandled Ctrl-C would, so shells see the right status.
+      process.exit(130);
+    }
+
+    // Named constants, because a literal control byte pasted into source is
+    // invisible in a diff and unreadable in a comparison.
+    const CTRL_C = '\u0003';
+    const CTRL_D = '\u0004';
+    const ESC = '\u001b';
+    const UP = '\u001b[A';
+    const DOWN = '\u001b[B';
+    const PGUP = '\u001b[5~';
+    const PGDN = '\u001b[6~';
+
+    function onData(buf) {
+      const s = buf.toString('utf8');
+      // ⚠️ In raw mode Ctrl-C is DATA, not a signal — nothing else handles it.
+      if (s === CTRL_C) { onSigint(); return; }
+      if (s === CTRL_D || s === ESC || s === 'q') { restore(); resolve(null); return; }
+      if (s === '\r' || s === '\n') { restore(); resolve(cursor); return; }
+
+      let moved = 0;
+      if (s === UP || s === 'k') moved = -1;
+      else if (s === DOWN || s === 'j') moved = 1;
+      else if (s === PGUP) moved = -WINDOW;
+      else if (s === PGDN) moved = WINDOW;
+      else if (s === 'g') { cursor = 0; top = 0; paint(); return; }
+      else if (s === 'G') { cursor = items.length - 1; top = Math.max(0, items.length - WINDOW); paint(); return; }
+      if (!moved) return;
+
+      cursor = Math.min(items.length - 1, Math.max(0, cursor + moved));
+      if (cursor < top) top = cursor;
+      if (cursor >= top + WINDOW) top = cursor - WINDOW + 1;
+      paint();
+    }
+
+    stream.write(HIDE);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding('utf8');
+    input.on('data', onData);
+    process.on('SIGINT', onSigint);
+    process.on('exit', restore);
+    paint();
+  });
+}

package/src/render/theme.mjs

@@ -123,9 +123,19 @@ function isWide(cp) {
  * document that ended there. Everywhere that shortens text must say it did.
  */
 export function truncate(s, n) {
-  const plain = strip(s ?? '');
+  const raw = String(s ?? '');
+  const plain = strip(raw);
   if (n <= 0) return '';
-  if (displayWidth(plain) <= n) return plain;
+  // ⭐ IF IT FITS, HAND BACK WHAT WE WERE GIVEN — escapes and all. Unconditionally
+  // returning the stripped string is why `c.bold(user_code)` rendered plain in the
+  // login block and `c.red('not linked')` renders plain in `status`: the caller
+  // coloured it, this measured it, and the colour was silently thrown away.
+  //
+  // ⚠️ WHEN IT MUST CUT, THE COLOUR STILL GOES. Slicing inside an SGR run leaves
+  // the terminal stuck in whatever attribute was open, which is worse than a plain
+  // string. So: preserved when whole, dropped when cut — and the fix for a long
+  // coloured value is to pass plain text plus a style function, as table() wants.
+  if (displayWidth(plain) <= n) return raw;
   let out = '';
   let w = 0;
   for (const { segment } of segmenter.segment(plain)) {
@@ -137,12 +147,19 @@ export function truncate(s, n) {
   return `${out}…`;
 }
 
-/** Pad to `n` columns. Plain text in, plain text out — colour afterwards. */
+/**
+ * Pad to `n` columns.
+ *
+ * Measures with escapes stripped and pads the ORIGINAL, so a pre-coloured cell
+ * keeps its colour and still lands in the right column. Padding is whitespace
+ * outside the SGR run, so there is nothing unsafe about it — unlike truncation,
+ * which has to cut and therefore cannot preserve an open attribute.
+ */
 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);
+  const raw = String(s ?? '');
+  const gap = n - displayWidth(raw);
+  if (gap <= 0) return raw;
+  return align === 'right' ? ' '.repeat(gap) + raw : raw + ' '.repeat(gap);
 }
 
 /**
@@ -218,10 +235,21 @@ export function link(label, url) {
   return `\x1b]8;;${url}\x1b\\${label}\x1b]8;;\x1b\\`;
 }
 
-/** Status glyphs, used consistently rather than ad hoc per command. */
+/**
+ * Status glyphs, used consistently rather than ad hoc per command.
+ *
+ * ⚠️ TWO FORMS ON PURPOSE. `mark.*` returns a COLOURED glyph for direct printing;
+ * `glyph.*` is the plain character, for anything that will be measured or padded.
+ * Passing `mark.ok()` into table() silently loses the colour — pad() strips escapes
+ * to measure, exactly as the ordering rule at the top of this file requires — so a
+ * table wants the plain glyph plus a style function, not a pre-coloured cell.
+ * I hit this myself the first time I wrote the doctor list.
+ */
+export const glyph = { ok: '✓', bad: '✗', warn: '!', dot: '·' };
+
 export const mark = {
-  ok: () => c.green('✓'),
-  bad: () => c.red('✗'),
-  warn: () => c.yellow('!'),
-  dot: () => c.dim('·'),
+  ok: () => c.green(glyph.ok),
+  bad: () => c.red(glyph.bad),
+  warn: () => c.yellow(glyph.warn),
+  dot: () => c.dim(glyph.dot),
 };

package/src/render/wait.mjs

@@ -0,0 +1,96 @@
+/**
+ * Showing that something is still happening (t-631).
+ *
+ * ⭐ THE LOGIN GREW A DOT PER POLL. `mnema login` wrote one '.' every `interval`
+ * seconds — 5s by default against a code that lives 10 minutes, so up to 120 dots.
+ * They wrap. On an 80-column terminal the second line of dots pushes the
+ * `user_code` off the top, and the code is THE ONE THING the user has to read. A
+ * progress indicator that destroys the information it is decorating is worse than
+ * no progress indicator.
+ *
+ * ⚠️ AND IT COULD NOT CLEAN UP AFTER ITSELF. Success did:
+ *
+ *     process.stdout.write('\r' + ' '.repeat(40) + '\r')
+ *
+ * Forty spaces, against a line that is 23 characters plus every dot written since.
+ * Past the fortieth character the residue simply stayed on screen. `\x1b[K` clears
+ * from the cursor to the end of the line and cannot be off by a count.
+ *
+ * A spinner redraws ONE line in place, so the code above it stays put however long
+ * the wait runs.
+ */
+
+import { c } from './theme.mjs';
+
+const BRAILLE = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const ASCII = ['-', '\\', '|', '/'];
+
+/**
+ * ⚠️ NOT EVERY TERMINAL HAS THE BRAILLE BLOCK. Where it is missing the frame
+ * renders as a replacement box that flickers once a tick, which looks broken
+ * rather than busy. Locale is the only signal available without querying the
+ * terminal, so an ASCII fallback is the honest default when it is not UTF-8.
+ */
+function frames() {
+  const enc = `${process.env.LC_ALL ?? ''}${process.env.LC_CTYPE ?? ''}${process.env.LANG ?? ''}`;
+  return /UTF-?8/i.test(enc) ? BRAILLE : ASCII;
+}
+
+const CLEAR_LINE = '\r\x1b[K';
+
+/**
+ * A single self-redrawing line.
+ *
+ * `stream` defaults to stderr so a spinner never lands in piped DATA — the same
+ * rule `doctor` needed in t-630, where "… checking connectivity" was being
+ * captured into `report.txt` as though it were part of the report.
+ *
+ * ⚠️ NO-OP ON A NON-TTY, and that is not merely tidy. Writing \r frames into a log
+ * file produces one enormous unreadable line, and into a CI transcript, thousands.
+ */
+export function spinner(label, { stream = process.stderr, interval = 100 } = {}) {
+  const live = Boolean(stream.isTTY);
+  const startedAt = Date.now();
+  let i = 0;
+  let timer = null;
+  let text = label;
+  const f = frames();
+
+  const elapsed = () => {
+    const s = Math.round((Date.now() - startedAt) / 1000);
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
+  };
+
+  const draw = () => {
+    stream.write(`${CLEAR_LINE}  ${c.cyan(f[i % f.length])} ${text} ${c.dim(elapsed())}`);
+    i += 1;
+  };
+
+  if (live) {
+    draw();
+    timer = setInterval(draw, interval);
+    // Do not hold the process open just to animate.
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  return {
+    /** Change the message without losing the line or the elapsed clock. */
+    update(next) {
+      text = next;
+      if (live) draw();
+    },
+    /**
+     * Erase the line and optionally print something in its place.
+     *
+     * ⚠️ ALWAYS ERASES, even when it was never drawn, because a caller that has to
+     * remember whether the terminal was live will eventually forget.
+     */
+    stop(finalLine) {
+      if (timer) clearInterval(timer);
+      if (live) stream.write(CLEAR_LINE);
+      if (finalLine) stream.write(`${finalLine}\n`);
+    },
+    elapsed,
+    live,
+  };
+}

package/src/tui/app.mjs

@@ -0,0 +1,127 @@
+/**
+ * The shell: header, screen stack, key map, error panel (t-632).
+ *
+ * ⚠️ A STACK, NOT A ROUTER, and `esc` pops it. But the top-level screen keys
+ * REPLACE the root rather than pushing, so mashing keys cannot build a
+ * forty-deep stack that takes forty escapes to unwind.
+ *
+ * ⚠️ AUTH IS A TAKEOVER, NOT A PANEL. Every screen needs a credential, so an
+ * AuthError leaves nothing usable behind it. And the device flow deliberately does
+ * NOT run inside Ink: it needs its own stdout and a browser, and it would fight
+ * the render loop for the terminal. Pressing `l` quits cleanly and prints the
+ * command to run — which is honest about what is about to happen, rather than
+ * appearing to log in and then redrawing over the code the user has to read.
+ */
+
+import { useState, useMemo } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { html } from './h.mjs';
+import { Briefing } from './screens/briefing.mjs';
+import { Finding } from './screens/finding.mjs';
+import { NodeScreen } from './screens/node.mjs';
+import { Header } from './components/header.mjs';
+
+const HOME = { name: 'briefing' };
+
+export function App({ ctx }) {
+  const { exit } = useApp();
+  const [stack, setStack] = useState([HOME]);
+  const [fatal, setFatal] = useState(null);
+
+  // ⭐ THE AUTH TAKEOVER HAS TO BE WIRED, not merely rendered. Every screen fetches
+  // through this wrapper, so an AuthError anywhere flips the whole app to the
+  // signed-out state instead of each screen showing its own red line for the same
+  // single cause. Matched on constructor NAME: the SDK's errors can cross a module
+  // realm here (the TUI is loaded by a dynamic import) and instanceof is unreliable
+  // across realms.
+  const wrapped = useMemo(() => ({
+    ...ctx,
+    call: async (fn) => {
+      try {
+        return await ctx.call(fn);
+      } catch (e) {
+        if (e?.constructor?.name === 'AuthError' || e?.code === 'unauthorized') {
+          setFatal({ kind: 'auth', message: e.message ?? 'That credential is not valid.' });
+        }
+        throw e;
+      }
+    },
+  }), [ctx]);
+
+  const top = stack[stack.length - 1];
+  const push = (screen) => setStack((s) => [...s, screen]);
+  const pop = () => setStack((s) => (s.length > 1 ? s.slice(0, -1) : s));
+
+  useInput((input, key) => {
+    if (input === 'q' || (key.ctrl && input === 'c')) { exit(); return; }
+    if (key.escape) { pop(); return; }
+    if (fatal?.kind === 'auth' && input === 'l') { exit(); return; }
+  });
+
+  if (fatal?.kind === 'auth') {
+    return html`
+      <${Box} flexDirection="column" paddingX=${1}>
+        <${Text} color="red" bold>Not signed in<//>
+        <${Text} dimColor>${fatal.message}<//>
+        <${Box} marginTop=${1}><${Text}>Press <${Text} bold>l<//> to quit and run <${Text} bold>mnema login<//><//><//>
+      <//>`;
+  }
+
+  // The trail is the stack's node screens, so the breadcrumb is derived rather
+  // than tracked separately — one source of truth for "where am I".
+  const trail = stack.filter((s) => s.name === 'node').map((s) => s.target.label ?? s.target.id);
+
+  let body;
+  if (top.name === 'briefing') {
+    body = html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`;
+  } else if (top.name === 'node') {
+    body = html`<${NodeScreen}
+      ctx=${wrapped}
+      target=${top.target}
+      trail=${trail}
+      focused=${true}
+      onOpen=${(n) => push({ name: 'node', target: n })}
+    />`;
+  } else {
+    // ⭐ A FINDING IS NO LONGER A DEAD END. Most carry subjectNodeId, so `enter`
+    // walks from "276 merged PRs have no task" into the actual node it is about —
+    // which is the difference between a report and something you can investigate.
+    body = html`<${Finding}
+      finding=${top.finding}
+      focused=${true}
+      onOpenSubject=${(t) => push({ name: 'node', target: t })}
+    />`;
+  }
+
+  return html`
+    <${Box} flexDirection="column">
+      <${Header}
+        version=${ctx.version ?? ''}
+        workspace=${ctx.workspaceName ?? ctx.workspaceId ?? ''}
+        plan=${ctx.plan}
+        edition=${ctx.edition}
+        cwd=${ctx.root}
+      />
+      ${body}
+      <${Box} paddingX=${1} marginTop=${1}>
+        <${Text} dimColor>${footerFor(top)}<//>
+      <//>
+    <//>`;
+}
+
+/** The keys that actually do something on THIS screen — never a generic legend. */
+function footerFor(top) {
+  if (top.name === 'briefing') return '↑↓ move · enter open · r refresh · q quit';
+  if (top.name === 'node') return '↑↓ move · enter walk in · esc back · r refresh · q quit';
+  if (top.name === 'finding') {
+    // Only offer the key that works. A grouped finding has members to open; a
+    // single one is an aggregate with nothing beneath it, and advertising `enter`
+    // there teaches people the UI is unresponsive.
+    return top.finding?.members?.length
+      ? '↑↓ move · enter open in graph · esc back · q quit'
+      : 'esc back · q quit';
+  }
+  return 'esc back · q quit';
+}
+
+export { HOME };

package/src/tui/components/header.mjs

@@ -0,0 +1,66 @@
+/**
+ * The identity block (t-636).
+ *
+ * ⭐ WHAT MAKES A TERMINAL APP LOOK LIKE A PRODUCT rather than a shell prompt is
+ * this exact thing: a mark, then who you are and where you are, before anything
+ * else. The old header was one line of text and read as output; this reads as an
+ * application you have opened.
+ *
+ *     ░█░···░█░   Mnema  0.8.0
+ *     ░█░···░█░   Mnema · team · a67e6584
+ *     ░█▓░░░▓▓    ~/Projects/project-x
+ *     ░█▓▓▓▓░
+ *     ░█░
+ *
+ * ⚠️ THE MARK IS NOT ALWAYS DRAWABLE, and the failure is ugly rather than subtle:
+ * a 24-bit escape on a terminal that cannot read it prints as literal text across
+ * the screen. markLines() returns null below 256 colours and the header falls back
+ * to the wordmark, which is a real state and not a theoretical one — TERM=xterm
+ * over a plain ssh hits it.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { markLines, WORDMARK } from '../../render/mark-art.mjs';
+
+/** Shorten a home-relative path the way a shell prompt would. */
+function shortPath(cwd, home = process.env.HOME) {
+  if (!cwd) return '';
+  return home && cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
+}
+
+export function Header({ version, workspace, plan, edition, cwd, rows = 6 }) {
+  const art = markLines({ rows });
+
+  const facts = [workspace, plan, edition === 'core' ? 'core' : null].filter(Boolean).join(' · ');
+
+  const info = html`
+    <${Box} flexDirection="column">
+      <${Box}>
+        <${Text} bold>Mnema<//>
+        <${Text} dimColor>  ${version}<//>
+      <//>
+      ${facts ? html`<${Text} dimColor>${facts}<//>` : null}
+      ${cwd ? html`<${Text} dimColor>${shortPath(cwd)}<//>` : null}
+    <//>`;
+
+  if (!art) {
+    // No mark: keep the same shape, just without the tile. Dropping the block
+    // entirely would make the app look different on different machines for a
+    // reason the user cannot see.
+    return html`
+      <${Box} paddingX=${1} paddingY=${0}>
+        <${Text} bold color="cyan">${WORDMARK}<//>
+        <${Text}>  <//>
+        ${info}
+      <//>`;
+  }
+
+  return html`
+    <${Box} paddingX=${1}>
+      <${Box} flexDirection="column" marginRight=${2}>
+        ${art.map((line, i) => html`<${Text} key=${i}>${line}<//>`)}
+      <//>
+      ${info}
+    <//>`;
+}