aegiscode 6.0.0 → 6.1.0

package/README.md

@@ -72,42 +72,60 @@ Every command above that talks to AEGIS names a tool from `mcp/tools.js`, and
 the test suite asserts both directions: no command points at a tool that does
 not exist, and no tool is unreachable from the prompt.
 
+Command names, aliases and categories follow `aegiscodex-dev`'s registry, so the
+vocabulary matches the other terminal host: the AEGIS family is spelled
+`/aegis-ask`, `/aegis-status`, `/aegis-recall`, `/aegis-remember`, `/aegis-import`
+(with `/ask`, `/status`, `/recall`, `/remember` kept as aliases), and the session
+and model controls are its `help`/`?`/`h`, `exit`/`quit`, `clear`/`cls`,
+`theme`/`t`, `version`/`v` and `model`/`m`. Commands that need a local agent loop
+this client deliberately does not have — `/login`, `/doctor`, `/permissions`,
+`/mcp`, `/skills`, `/hooks`, `/agents`, `/resume` and a few more — are listed but
+answer honestly with the reason and the nearest working alternative rather than
+pretending to work.
+
 ## What it looks like
 
 ```
-                                     ▄▄▄▄▄▄▄
-                                     ▟███████▙
-                                     ▜███▀███▛
-                                      ▜█████▛
-                                       ▜███▛
-                                        ▜▛
-
-                                     A E G I S  C O D E
-                             Cloud brain in your shell.
-
-┏━ aegiscode ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-┃ version  v6.0.0                                              ┃
-┃ model    nexus-brain                                         ┃
-┃ base     https://aegiscloud.org                              ┃
-┃ key      aegis_••••4f2a                                      ┃
-┃ render   streaming                                           ┃
-┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
- type /help for commands ∙ /quit to exit
-
-┃» you
-┃ summarise what changed in the token accounting
-┃⬢ aegis
-┃ Three things changed, and one of them was costing you money:
-┃
-┃ ∙ the pool merges worker usage instead of overwriting it
-┃ ∙ cache reads and writes are billed, not ignored
-┃ ∙ a zero-token call no longer refunds its reservation
-┃
-┃   merge_usage({input_tokens: 1250}, {output_tokens: 312})
-┃   => 1562 total
-┣─ ∅ nexus-brain ∙ 1,562 tok ∙ 1,250/312 ∙ €0.0007 ∙ 4.2s ∙ 4 calls
-
- ⬢ aegis ∙ nexus-brain ∙ 1,562 tok ∙ €0.0007 ∙ stream          ctrl+c quit
+━────────────────────────────────────────────────────────────────────────────━
+
+            ✦               █████▓▓░      ▓▓▓▓▓▓▓▓▓ ✦       ▒▒▒▒▒▒▒▒▒▒▒▒ 
+                 ✦        ███▓░     ░░    ▓▓▓▓▓▓▓░░░       ▒▒▒▒▒▒▒▒▒▒▒▒▒ 
+             ░░░░         ███▓░           ▓▓▓▓░░░░░░     ██▒▒▒▒▒▒▒▒▒▒▒▒▓▓
+           ░░░░░░░░       ███▓░             ░░░░░░       ██▒▒▒▒▒▒▒▒▒▒▒▒▓ 
+         ░░░░░░░░░░░░     ███▓░           ✦   ·   ·       ▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 
+                  ██▓░░      ▓                             ░░░░░░░░░░░░  
+                  ░▓▓███▓▓░                                              
+     ▐▛███▜▌                                                             
+    ▝▜█████▛▘                                                            
+      ▘▘ ▝▝                                                              
+
+                            Welcome to AEGIS Code
+                     v6.1.0 · Cloud brain in your shell.
+
+───────────────────────────────── aegiscode ──────────────────────────────────
+  version v6.1.0
+  model   nexus-brain
+  base    https://aegiscloud.org
+  key     aegis_••••4f2a
+  render  streaming
+
+ type /help for commands · /quit to exit
+
+❯ summarise what changed in the token accounting
+● Three things changed, and one of them was costing you money:
+
+  - the pool merges worker usage instead of overwriting it
+  - cache reads and writes are billed, not ignored
+  - a zero-token call no longer refunds its reservation
+
+  merge_usage({input_tokens: 1250}, {output_tokens: 312})
+  => 1562 total
+
+Use /balance to see tokens beside € on every row.
+⎿  nexus-brain · 1,562 tok · 1,250/312 · €0.0007 · 4.2s · 4 calls
+
+* Consulting… (2.1s)  esc to interrupt
+ aegis · nexus-brain · 1,562 tok · €0.0007 · stream               ctrl+c quit 
 ```
 
 Render it yourself, with no key and no network:
@@ -119,12 +137,15 @@ node cli/scripts/demo.mjs            # from a source checkout
 
 ## Design notes
 
-**It is not a Claude Code look-alike.** Violet-and-cyan on ink; a hexagonal
-shield sigil rather than a mascot; a `»` prompt and a `┃` transcript rail rather
-than `❯` and `✻`; heavy box corners rather than rounded ones. This is a
-deliberate divergence, not an accident of taste: `test/cli-identity.test.mjs`
-fails if any of Claude Code's exact RGB triples, glyphs, spinner frames or art
-rows appear in this host.
+**It looks like `aegiscodex-dev` on purpose.** The gold/coral/lavender palette,
+the `✦`-studded welcome mark (mascot, crescent moon and diving whale), the `❯`
+prompt, the `⎿` hook rows and the `✻` spinner line are the `aegiscodex-dev`
+design system, adopted wholesale rather than approximated: the palette, glyphs,
+welcome art, working verbs and command vocabulary all come from it, and
+`test/cli-conformance.test.mjs` pins every RGB triple, glyph, spinner frame, verb
+and art row to that source so the two hosts cannot drift apart. (An earlier
+revision of this CLI was a deliberate divergence — a violet/cyan "Signal" theme
+with a test asserting it. That direction is gone.)
 
 **A linear transcript, not a full-screen TUI.** Finished turns are written once
 to the scrollback; only the one live line (spinner, elapsed time) is redrawn.
@@ -139,12 +160,15 @@ free usage next to a token count.
 ## Tests
 
 ```bash
-node ../../test/cli-identity.test.mjs   # the divergence guard
-node ../../test/cli-render.test.mjs     # width safety, accounting, live region
-node ../../test/cli-tools.test.mjs      # registry parity with the MCP host + dispatch
-node ../../test/cli-run.test.mjs        # the real binary against a real backend
-node ../../test/cli-package.test.mjs    # the published layout, isolated from the repo
-npm test                                # all of the above
+node ../../test/cli-conformance.test.mjs # the design guard: palette, glyphs, art, verbs
+node ../../test/cli-render.test.mjs      # width safety, accounting, live region
+node ../../test/cli-overlays.test.mjs    # the / palette, model + effort pickers, resume list
+node ../../test/cli-fuzzy.test.mjs       # palette ranking and match positions
+node ../../test/cli-markdown.test.mjs    # span-line markdown, cell widths
+node ../../test/cli-tools.test.mjs       # registry parity with the MCP host + dispatch
+node ../../test/cli-run.test.mjs         # the real binary against a real backend
+node ../../test/cli-package.test.mjs     # the published layout, isolated from the repo
+npm test                                 # all of the above
 ```
 
 `npm run predist` stages `client/`, `mcp/tools.js` and the desktop's `usage.js`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegiscode",
   "productName": "AEGIS Code",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "aegiscode — the command-line version of AEGIS Desktop. The shared tool surface in your shell, over the same thin transport and tool registry as the MCP plugin and the desktop app. Ships transport + UI only; no brain.",
   "author": {
     "name": "AEGIS Code",
@@ -31,7 +31,7 @@
     "start": "node bin/aegiscode.js",
     "predist": "node scripts/predist.mjs",
     "prepublishOnly": "npm run predist",
-    "check": "node --check bin/aegiscode.js && node --check src/theme.js && node --check src/art.js && node --check src/screen.js && node --check src/format.js && node --check src/render.js && node --check src/commands.js && node --check src/deps.js && node --check src/app.js && node --check scripts/predist.mjs",
+    "check": "node --check bin/aegiscode.js && node --check src/theme.js && node --check src/art.js && node --check src/screen.js && node --check src/format.js && node --check src/fuzzy.js && node --check src/markdown.js && node --check src/render.js && node --check src/overlays.js && node --check src/commands.js && node --check src/deps.js && node --check src/app.js && node --check scripts/predist.mjs",
     "test": "for f in ../../test/cli-*.test.mjs; do node \"$f\" || exit 1; done"
   },
   "keywords": [

package/scripts/demo.mjs

@@ -87,6 +87,6 @@ push(render.renderStatus(ctx, { model: 'nexus-brain', tokens: 1562, spend: 0.000
 process.stdout.write((plain ? out.map(stripAnsi) : out).join('\n') + '\n\n');
 if (!plain) {
   process.stdout.write(
-    stripAnsi(`${art.WORDMARK} — ${out.length} lines rendered at ${width} cols${ctx.light ? ' (light)' : ''}\n`)
+    stripAnsi(`${art.WELCOME_TITLE} — ${out.length} lines rendered at ${width} cols${ctx.light ? ' (light)' : ''}\n`)
   );
 }

package/src/app.js

@@ -13,7 +13,7 @@
 
 const readline = require('node:readline');
 const { createTools, createClient, usageTokens } = require('./deps.js');
-const { GLYPH, VERBS, themeOf, RESET } = require('./theme.js');
+const { GLYPH, VERBS, themeOf, RESET, BOLD } = require('./theme.js');
 const { LiveRegion, termWidth, EC, w } = require('./screen.js');
 const { parseLine, findCommand, COMMANDS } = require('./commands.js');
 const render = require('./render.js');
@@ -289,21 +289,67 @@ function createApp(options = {}) {
     emit(render.renderToolResult(ctx(), name, text, width()));
   }
 
+  // Category order and labels, matching aegiscodex-dev's palette.
+  const CATEGORY_ORDER = ['aegis', 'model', 'session', 'data', 'auth', 'support', 'workspace'];
+  const CATEGORY_LABEL = {
+    aegis: 'Aegis plugin',
+    model: 'Model & behavior',
+    session: 'Session & context',
+    data: 'Data',
+    auth: 'Auth',
+    support: 'Support',
+    workspace: 'Workspace',
+  };
+
+  /**
+   * The nearest routable name to a mistyped one: a prefix of it, or a name it
+   * is a prefix of. Deliberately simple — `cli/src/fuzzy.js` is a separate
+   * workstream and may not exist, so this must not depend on it.
+   */
+  function nearest(name) {
+    const n = String(name || '').toLowerCase();
+    if (!n) return null;
+    let best = null;
+    for (const c of COMMANDS) {
+      for (const cand of [c.name, ...(c.aliases || [])]) {
+        if (cand === n) continue;
+        if (cand.startsWith(n) || n.startsWith(cand)) {
+          if (best == null || Math.abs(cand.length - n.length) < Math.abs(best.length - n.length)) {
+            best = cand;
+          }
+        }
+      }
+    }
+    return best;
+  }
+
   function printHelp() {
+    const t = themeOf(ctx());
     emit([render.renderHeading(ctx(), 'commands', width())]);
-    const rows = COMMANDS.map((c) => {
-      const usage = `/${c.name}${c.args ? ' ' + c.args : ''}`;
-      return { usage, help: c.help, aliases: (c.aliases || []).map((a) => `/${a}`).join(' ') };
-    });
+    const rows = COMMANDS.filter((c) => !c.unavailable).map((c) => ({
+      cat: c.category || 'other',
+      usage: `/${c.name}${c.args ? ' ' + c.args : ''}`,
+      desc: c.desc,
+      aliases: (c.aliases || []).map((a) => `/${a}`).join(' '),
+    }));
     const widest = rows.reduce((m, r) => Math.max(m, r.usage.length), 0);
-    const t = themeOf(ctx());
-    for (const r of rows) {
-      const alias = r.aliases ? render.fg(t, t.dim) + `  (${r.aliases})` + RESET : '';
-      emit([`  ${render.fg(t, t.plasma)}${'/' + r.usage.slice(1)}` +
-        ' '.repeat(Math.max(1, widest - r.usage.length + 2)) +
-        render.fg(t, t.text) + r.help + RESET + alias]);
+    for (const cat of CATEGORY_ORDER) {
+      const group = rows.filter((r) => r.cat === cat);
+      if (!group.length) continue;
+      emit(['', `${t.dim}${BOLD}${CATEGORY_LABEL[cat] || cat}${RESET}`]);
+      for (const r of group) {
+        const alias = r.aliases ? `${t.dim}  (${r.aliases})${RESET}` : '';
+        emit([
+          `  ${t.gold}${r.usage}${RESET}${' '.repeat(Math.max(1, widest - r.usage.length + 2))}` +
+            `${t.white}${r.desc}${RESET}${alias}`,
+        ]);
+      }
+    }
+    const unavail = COMMANDS.filter((c) => c.unavailable).map((c) => `/${c.name}`);
+    if (unavail.length) {
+      emit(['', `${t.dim}not available in this client: ${unavail.join(' ')}${RESET}`]);
     }
-    emit(['', render.renderNotice(ctx(), 'info', `plain text is a prompt ${GLYPH.bullet} /quit exits`)]);
+    emit(['', render.renderNotice(ctx(), 'info', `plain text is a prompt ${GLYPH.bullet} /exit exits`)]);
   }
 
   /** Handle one line of input. Returns false when the session should end. */
@@ -316,7 +362,24 @@ function createApp(options = {}) {
       return true;
     }
     if (parsed.kind === 'unknown') {
-      emit(render.renderNotice(ctx(), 'error', `unknown command: /${parsed.name} — try /help`));
+      const alt = nearest(parsed.name);
+      emit(
+        render.renderNotice(
+          ctx(),
+          'error',
+          `unknown command: /${parsed.name}${alt ? ` — did you mean /${alt}?` : ` — try /help`}`
+        )
+      );
+      return true;
+    }
+    if (parsed.kind === 'unavailable') {
+      const c = parsed.command;
+      emit(render.renderNotice(ctx(), 'warn', `/${c.name} is not available in aegiscode — ${c.why}`));
+      if (c.alt) emit(render.renderNotice(ctx(), 'info', `try ${c.alt} instead`));
+      else {
+        const alt = nearest(c.name);
+        if (alt) emit(render.renderNotice(ctx(), 'info', `try /${alt} instead`));
+      }
       return true;
     }
 
@@ -325,15 +388,27 @@ function createApp(options = {}) {
 
     if (cmd.local) {
       switch (cmd.local) {
-        case 'quit':
+        case 'exit':
           return false;
         case 'clear':
           out.write(EC.clearScreen);
+          // aegiscodex-dev's /clear starts a new session with empty context, so
+          // the session tallies reset too (the transcript is not persisted here).
+          session.turns = 0;
+          session.calls = 0;
+          session.tokens = 0;
+          session.inputTokens = 0;
+          session.outputTokens = 0;
+          session.cost = 0;
+          session.startedAt = Date.now();
           emit(bannerLines());
           return true;
         case 'help':
           printHelp();
           return true;
+        case 'version':
+          emit(render.renderNotice(ctx(), 'info', `aegiscode v${VERSION}`));
+          return true;
         case 'model':
           if (!arg) {
             emit(render.renderNotice(ctx(), 'info', `model: ${opts.model || 'server default'}`));
@@ -353,13 +428,14 @@ function createApp(options = {}) {
           opts.light = arg ? /^light/i.test(arg) : !opts.light;
           emit(render.renderNotice(ctx(), 'ok', `theme: ${opts.light ? 'light' : 'dark'}`));
           return true;
-        case 'cost': {
+        case 'cost':
+        case 'tokens': {
           const t = themeOf(ctx());
           emit([render.renderHeading(ctx(), 'session', width())]);
           emit([
-            `  tokens   ${render.fg(t, t.text)}${fmtTokens(session.tokens)}${RESET}  ` +
-              render.fg(t, t.muted) + `(${fmtTokens(session.inputTokens)} in / ${fmtTokens(session.outputTokens)} out)` + RESET,
-            `  spend    ${render.fg(t, t.pulse)}${fmtEur(session.cost)}${RESET}`,
+            `  tokens   ${t.white}${fmtTokens(session.tokens)}${RESET}  ` +
+              t.gray + `(${fmtTokens(session.inputTokens)} in / ${fmtTokens(session.outputTokens)} out)` + RESET,
+            `  spend    ${t.green}${fmtEur(session.cost)}${RESET}`,
             `  calls    ${session.calls}`,
             `  balance  ${session.balance == null ? 'unknown' : fmtEur(session.balance)}`,
             `  elapsed  ${fmtElapsed(Date.now() - session.startedAt)}`,
@@ -397,7 +473,7 @@ function createApp(options = {}) {
         }
         args = { ...args, api_key: key };
       }
-      if (cmd.name === 'ask') return await runPrompt(args.prompt);
+      if (cmd.tool === 'aegis_ask') return await runPrompt(args.prompt);
       await runTool(cmd.tool, args);
     } catch (e) {
       emit(render.renderNotice(ctx(), 'error', e.message));
@@ -412,7 +488,7 @@ function createApp(options = {}) {
     }
     return new Promise((resolve) => {
       const t = themeOf(ctx());
-      out.write(render.fg(t, t.muted) + promptText + RESET);
+      out.write(t.gray + promptText + RESET);
       const stdin = process.stdin;
       let buf = '';
       stdin.setRawMode(true);
@@ -477,9 +553,9 @@ function createApp(options = {}) {
       if (tokens != null) {
         const t = themeOf(ctx());
         out.write(
-          render.fg(t, t.dim) + GLYPH.spend + ' ' + render.fg(t, t.beam) + (res.model || 'aegis') + RESET +
-            render.fg(t, t.dim) + ' ' + GLYPH.bullet + ' ' + RESET +
-            render.fg(t, t.text) + `${fmtTokens(tokens)} tok` + RESET + '\n'
+          t.dim + GLYPH.spend + ' ' + t.blue + (res.model || 'aegis') + RESET +
+            t.dim + ' ' + GLYPH.bullet + ' ' + RESET +
+            t.white + `${fmtTokens(tokens)} tok` + RESET + '\n'
         );
       }
     }
@@ -493,7 +569,7 @@ function createApp(options = {}) {
     out.write('\n');
 
     const rl = options.readline || readline.createInterface({ input: process.stdin, output: out, terminal: true });
-    const promptStr = render.fg(themeOf(ctx()), themeOf(ctx()).plasma) + GLYPH.prompt + ' ' + RESET;
+    const promptStr = themeOf(ctx()).gold + GLYPH.prompt + ' ' + RESET;
     rl.setPrompt(promptStr);
     rl.prompt();
 

package/src/art.js

@@ -1,45 +1,235 @@
 'use strict';
 
 /**
- * AEGIS brand art.
+ * Welcome art — the aegiscodex-dev mark, adopted wholesale.
  *
- * A hexagonal shield with a signal core — the mark that replaces the mascot
- * art every Claude Code derivative (including this repo's sibling project
- * aegiscodex-dev) ships. Same job, different iconography on purpose:
- * `test/cli-identity.test.mjs` asserts Claude Code's own art never appears here.
+ * The composition is copied from `aegiscodex-dev/src/art.js`, which took the
+ * glyph rows from the shipped Claude Code binary: a feather plume (░), a top hat
+ * (█ ▓ ▒), the spark face (▐▛███▜▌ / ▝▜█████▛▘ / ▘▘ ▝▝), plus a crescent moon and
+ * a diving whale for the second brain. Side-by-side when the terminal is wide
+ * enough, stacked when it isn't.
  *
- * Every row is the same display width (9 cells) so it can be centred or stacked
- * without drift; `tests` assert that rather than trusting it.
- *
- * The wordmark spells the whole product name (`aegiscode`) with the same letter
- * spacing the shorter `AEGIS` mark used, now that the host and the CLI have been
- * folded onto one name. `test/cli-identity.test.mjs` strips the spacing and
- * asserts the mark still names the product.
+ * Every row of a block is the same display width, so `center()` and
+ * `joinSideBySide()` stay exact. `test/cli-conformance.test.mjs` asserts both
+ * that property and that these rows still match aegiscodex-dev's source, so the
+ * mark can't drift.
  */
 
-const SIGIL = [
-  ' ▄▄▄▄▄▄▄ ',
-  '▟███████▙',
-  '▜███▀███▛',
-  ' ▜█████▛ ',
-  '  ▜███▛  ',
-  '   ▜▛    ',
+// The mascot face — exact glyphs from the binary (msS template).
+const FACE = [' ▐▛███▜▌', '▝▜█████▛▘', '  ▘▘ ▝▝'];
+
+// Top hat + feather plume, composed from the extracted row glyphs.
+const HAT = [
+  '  ✦         ░░░░░░░░░░      ✦',
+  '           ░░░░░░░░░░░░░░░░',
+  '                 █████▓▓░',
+  '                 ███▓░',
+  '                 ███▓░',
+  '                 ███▓░',
+  '               ░▓▓███▓▓░',
+  '          ▒▒░░▒▒     ▒ ▒▒',
+];
+
+// Plume + hat + face: the left half of the welcome mark.
+const MASCOT_ART = [
+  '        ✦               █████▓▓░',
+  '             ✦        ███▓░     ░░',
+  '         ░░░░         ███▓░',
+  '       ░░░░░░░░       ███▓░',
+  '     ░░░░░░░░░░░░     ███▓░',
+  '              ██▓░░      ▓',
+  '              ░▓▓███▓▓░',
+  ...FACE,
+];
+
+// Crescent moon in a starry night sky — lit rim (▓) with a faint earthshine
+// body (░). Rows are equal code-point length (13).
+const MOON = [
+  '  ✦   ▓▓▓  ✦ ',
+  '    ▓▓▓▓▓   ✦',
+  '  ▓▓▓▓▓▓▓▓▓ ✦',
+  '  ▓▓▓▓▓▓▓░░░ ',
+  '  ▓▓▓▓░░░░░░ ',
+  '    ░░░░░░   ',
+  '  ✦   ·   ·  ',
 ];
 
-/** Cell offsets (row, col) of the core, painted in the secondary colour. */
-const CORE = [{ row: 2, col: 4 }];
+// The diving whale: spout (░), eye (██) on the rounded head, body (▒) sweeping
+// right to a small forked fluke (▓), water line (░) beneath. Rows are equal
+// code-point length (18).
+const WHALE = [
+  '   ✦   ░ ░ ░      ',
+  '    ✦ ░░░░░       ',
+  '     ▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '    ▒▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '  ██▒▒▒▒▒▒▒▒▒▒▒▒▓▓',
+  '  ██▒▒▒▒▒▒▒▒▒▒▒▒▓ ',
+  '   ▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '    ░░░░░░░░░░░░  ',
+];
+
+// Moon above the whale — the right half of the mark, 2-col gutter. The moon is
+// padded with a trailing blank row so joinSideBySide keeps both blocks aligned.
+const MOON_WHALE = joinSideBySide([...MOON, ''], WHALE, 2);
+
+/** Full welcome mark: mascot + (moon + whale) side by side, bottom-aligned. */
+const WELCOME_ART = joinSideBySide(MASCOT_ART, MOON_WHALE, 2);
 
-const WORDMARK = 'A E G I S  C O D E';
+/** Narrow-terminal fallback: mascot stacked above (moon + whale). */
+const WELCOME_ART_STACKED = stackVertical(MASCOT_ART, MOON_WHALE, 1);
+
+/** Welcome copy, in aegiscode-dev's frame: coral title over the mark. */
+const WELCOME_TITLE = 'Welcome to AEGIS Code';
+const WELCOME_BACK = 'Welcome back!';
 const TAGLINE = 'Cloud brain in your shell.';
 
+// ── Terminal portability ─────────────────────────────────────────────────────
+// The block-glyph palette and ✦ stars are single-width on Linux terminals, but
+// not everywhere: Windows fonts often lack the U+259B..U+259F face edges and
+// mangle █▓▒░ entirely; on macOS ✦ renders as a double-width emoji. Each pass
+// swaps offending code points 1:1 (same character count per row) so the width
+// maths stays exact and the mark keeps its shape.
+const ASCII_STENCIL = new Map([
+  ['█', '#'],
+  ['▓', '@'],
+  ['▒', '='],
+  ['░', '.'],
+  ['▐', '#'],
+  ['▛', '#'],
+  ['▜', '#'],
+  ['▌', '#'],
+  ['▝', '#'],
+  ['▘', '#'],
+  ['✦', '*'],
+  ['·', '.'],
+]);
+
+const DARWIN_STENCIL = new Map([
+  ['▐', '#'],
+  ['▛', '#'],
+  ['▜', '#'],
+  ['▌', '#'],
+  ['▝', '#'],
+  ['▘', '#'],
+  ['✦', '*'],
+]);
+
+/** One platform pass over an art block. */
+function portability(rows) {
+  if (process.platform === 'win32') {
+    return rows.map((r) => [...r].map((ch) => ASCII_STENCIL.get(ch) ?? ch).join(''));
+  }
+  if (process.platform === 'darwin') {
+    return rows.map((r) => [...r].map((ch) => DARWIN_STENCIL.get(ch) ?? ch).join(''));
+  }
+  return rows;
+}
+
+/** The mark that fits the current terminal: side-by-side when there's room. */
+function welcomeArtFor(cols) {
+  const wide = portability(WELCOME_ART);
+  const stacked = portability(WELCOME_ART_STACKED);
+  const W = Math.max(...wide.map((r) => [...r].length));
+  return cols >= W + 4 ? wide : stacked;
+}
+
 /**
- * Left-pad every row of `art` so it sits centred inside `width`.
- * @returns {string[]}
+ * Split the mark into its two halves so each can carry its own theme ink.
+ * @returns {{rows: Array<[string,string]>, width: number, gutter: number}}
  */
-function center(art, width) {
-  const w = art.reduce((m, r) => Math.max(m, [...r].length), 0);
-  const pad = Math.max(0, Math.floor((width - w) / 2));
-  return art.map((r) => ' '.repeat(pad) + r);
+function welcomeArtParts(cols) {
+  const mascot = portability(MASCOT_ART);
+  const moonWhale = portability(MOON_WHALE);
+  const L = Math.max(...mascot.map((r) => [...r].length));
+  const R = Math.max(...moonWhale.map((r) => [...r].length));
+  const wide = cols >= L + R + 2 + 4;
+  const gutter = wide ? 2 : 1;
+  if (wide) {
+    // The right half carries the moon *and* the whale. Using WHALE alone here —
+    // which the reference does, because it only wants the per-mascot ink split —
+    // would silently drop the crescent from the welcome screen this CLI renders.
+    const n = Math.max(mascot.length, moonWhale.length);
+    const rows = [];
+    for (let i = 0; i < n; i++) {
+      const li = i + (n - mascot.length);
+      const ri = i + (n - moonWhale.length);
+      rows.push([(mascot[li] ?? '').padEnd(L), (moonWhale[ri] ?? '').padEnd(R)]);
+    }
+    return { rows, width: L + gutter + R, gutter };
+  }
+  const w = Math.max(L, R);
+  const centerBlock = (rows) =>
+    rows.map((r) => ' '.repeat(Math.max(0, Math.floor((w - [...r].length) / 2))) + r);
+  return {
+    rows: [
+      ...centerBlock(mascot).map((c) => [c, '']),
+      ['', ''],
+      ...centerBlock(moonWhale).map((r) => ['', r]),
+    ],
+    width: w,
+    gutter,
+  };
+}
+
+/** Stack two art blocks vertically, each centred, separated by `gap` rows. */
+function stackVertical(top, bottom, gap = 1) {
+  const w = Math.max(...[...top, ...bottom].map((r) => [...r].length));
+  const centerBlock = (rows) =>
+    rows.map((r) => {
+      const pad = Math.max(0, Math.floor((w - [...r].length) / 2));
+      return ' '.repeat(pad) + r;
+    });
+  return [...centerBlock(top), ...Array(gap).fill(''), ...centerBlock(bottom)];
+}
+
+/** Join two art stacks row-aligned (bottom-aligned by default). */
+function joinSideBySide(left, right, gutter = 2, align = 'bottom') {
+  const L = Math.max(...left.map((r) => [...r].length));
+  const R = Math.max(...right.map((r) => [...r].length));
+  const n = Math.max(left.length, right.length);
+  return Array.from({ length: n }, (_, i) => {
+    const li = align === 'bottom' ? i + (n - left.length) : i;
+    const ri = align === 'bottom' ? i + (n - right.length) : i;
+    const l = (left[li] ?? '').padEnd(L);
+    const r = (right[ri] ?? '').padEnd(R);
+    return l + ' '.repeat(gutter) + r;
+  });
+}
+
+/** Centre every row of an art block inside `width` (left pad + right fill). */
+function center(rows, width) {
+  return rows.map((r) => {
+    const pad = Math.max(0, Math.floor((width - [...r].length) / 2));
+    return ' '.repeat(pad) + r + ' '.repeat(Math.max(0, width - [...r].length - pad));
+  });
+}
+
+/** Centre each row against the block's own max width (no trailing fill). */
+function padBoth(rows, width) {
+  const w = Math.max(...rows.map((r) => [...r].length));
+  return rows.map((r) => {
+    const pad = Math.floor((width - w) / 2);
+    return ' '.repeat(Math.max(0, pad)) + r;
+  });
 }
 
-module.exports = { SIGIL, CORE, WORDMARK, TAGLINE, center, SIGIL_WIDTH: 9 };
+module.exports = {
+  FACE,
+  HAT,
+  MASCOT_ART,
+  MOON,
+  WHALE,
+  MOON_WHALE,
+  WELCOME_ART,
+  WELCOME_ART_STACKED,
+  WELCOME_TITLE,
+  WELCOME_BACK,
+  TAGLINE,
+  portability,
+  welcomeArtFor,
+  welcomeArtParts,
+  stackVertical,
+  joinSideBySide,
+  center,
+  padBoth,
+};