@cspeach/cli 1.1.18 → 1.1.20

package/dist/commands/help.js

@@ -1,5 +1,11 @@
 import chalk from 'chalk';
 import { SKILL_CATALOG } from '../skill-catalog.js';
+import { costCommandDescription } from '../repl/builtin-commands.js';
+import { panelHeading } from '../renderer/panel-rows.js';
+import { paint } from '../renderer/theme.js';
+import { uiWidth, truncateToWidth } from '../renderer/ui-width.js';
+// I2's shortcuts table and note — one source for the `?` sheet and /help.
+import { SHORTCUT_ROWS, SHORTCUTS_NOTE } from '../ui/widgets/shortcuts-sheet.js';
 // Workflow order: plan → understand → modify → build → upgrade → ship.
 const CATEGORY_ORDER = [
     'Pre-Coding',
@@ -9,13 +15,45 @@ const CATEGORY_ORDER = [
     'Upgrade / Migrate',
     'Ship / Release',
 ];
-const NAME_COL_PAD = 28; // padded width of "/skill-name"
-const NAME_GUTTER = 2; // leading 2-space indent
-const DESC_GUTTER = 1; // 1 space between name col and description
-const NAME_COL_WIDTH = NAME_GUTTER + NAME_COL_PAD + DESC_GUTTER; // 31
+const NAME_COL_PAD = 28; // padded width of the command/skill column
+const NAME_COL_WIDTH = 2 + NAME_COL_PAD + 1; // indent + column + gap = 31
 const MAX_DESC_LINES = 2;
-const MIN_DESC_WIDTH = 40;
-const DEFAULT_TERM_WIDTH = 100;
+const MIN_DESC_WIDTH = 20;
+const fixed = (s) => () => s;
+/**
+ * Piece 2 §10 — /help grouped by what you want to do. Every palette command
+ * is listed (a test enforces it), plus /files and /ui look. The /cost text
+ * follows the cost display mode (credits for managed customers).
+ */
+export const HELP_GROUPS = [
+    { title: 'Work on SAP', rows: [
+            { name: '/transport [TR]', description: fixed('View or set the transport for this session') },
+            { name: '/mode [advisory|gated|auto]', description: fixed('Set the write mode (Shift+Tab also cycles)') },
+            { name: '/safety-mode on|off|status', description: fixed('Turn the Forge Rule confirmation cards on or off') },
+            { name: '/rewind', description: fixed('Undo a write from this session (Esc Esc)') },
+            { name: '/reroute <skill>', description: fixed('Re-run your last prompt with a different skill') },
+        ] },
+    { title: 'Local files', rows: [
+            { name: '/files', description: fixed('Pick a saved project file and what to do with it') },
+            { name: '@<file>', description: fixed('Attach a file from this folder to your prompt') },
+            { name: '/export audit [file]', description: fixed('Write the signable session audit record to a file') },
+        ] },
+    { title: 'Session', rows: [
+            { name: '/new', description: fixed('Next prompt picks a skill afresh (also /reset)') },
+            { name: '/recap', description: fixed('Show the recap (last session, open tasks, plan)') },
+            { name: '/cost', description: costCommandDescription },
+            { name: '/context', description: fixed("Show what fills the model's context window") },
+            { name: '/compact', description: fixed('Shrink a long session and keep the facts') },
+            { name: '/help', description: fixed('This screen (also /skills)') },
+            { name: '/exit', description: fixed('Quit CSPeach (also /quit)') },
+        ] },
+    { title: 'Look and settings', rows: [
+            { name: '/ui [auto|ink]', description: fixed('Change the UI mode (applies after a relaunch)') },
+            { name: '/ui look [panels|legacy]', description: fixed('Switch between the panels and legacy looks') },
+        ] },
+];
+/** /help lists the `?` key itself first, then I2's sheet rows in their order. */
+const SHORTCUTS = [['?', 'shortcuts'], ...SHORTCUT_ROWS];
 /**
  * Word-wrap a description into at most `maxLines` lines of `width` chars each.
  * If content overflows, the last line is suffixed with `…`.
@@ -28,7 +66,6 @@ function wrapDescription(desc, width, maxLines) {
     while (i < words.length && lines.length < maxLines) {
         const word = words[i];
         if (current.length === 0) {
-            // Word longer than width — hard-truncate
             current = word.length <= width ? word : word.slice(0, width);
             i++;
         }
@@ -41,65 +78,66 @@ function wrapDescription(desc, width, maxLines) {
             current = '';
         }
     }
-    if (current.length > 0 && lines.length < maxLines) {
+    if (current.length > 0 && lines.length < maxLines)
         lines.push(current);
-    }
-    // Overflow → suffix last line with " …"
     if (i < words.length && lines.length > 0) {
         const last = lines[lines.length - 1];
-        if (last.length + 2 <= width) {
-            lines[lines.length - 1] = last + ' …';
-        }
-        else {
-            lines[lines.length - 1] = last.slice(0, Math.max(0, width - 2)) + ' …';
-        }
+        lines[lines.length - 1] = last.length + 2 <= width ? last + ' …' : last.slice(0, Math.max(0, width - 2)) + ' …';
     }
     return lines;
 }
-/**
- * Prints the flat-list /help screen grouped by category.
- * Cyan category headings, bold skill names, default-color descriptions.
- * Descriptions wrap to MAX_DESC_LINES lines max, aligned to the name column.
- */
+const groupTitle = (t) => paint('sap', chalk.bold(t));
 /**
  * Phase D5 (2026-05-17) — accepts an optional emit callback so Ink mode
  * can route output through chunkEmitter instead of console.log (which
  * corrupts the React frame). Default keeps the classic-mode behaviour.
  */
 export function printHelp(emit = (s) => console.log(s)) {
-    const termWidth = process.stdout.columns ?? DEFAULT_TERM_WIDTH;
-    const descWidth = Math.max(MIN_DESC_WIDTH, termWidth - NAME_COL_WIDTH);
+    const width = uiWidth();
+    const descWidth = Math.max(MIN_DESC_WIDTH, width - NAME_COL_WIDTH);
     const continuationIndent = ' '.repeat(NAME_COL_WIDTH);
+    const row = (name, desc) => `  ${chalk.bold(truncateToWidth(name, NAME_COL_PAD).padEnd(NAME_COL_PAD))} ${paint('dim', truncateToWidth(desc, descWidth))}`;
     emit('');
-    for (const category of CATEGORY_ORDER) {
-        const skills = SKILL_CATALOG.filter((s) => s.category === category);
-        if (skills.length === 0)
-            continue;
-        emit(chalk.cyan.bold(category));
-        for (const skill of skills) {
-            const nameCol = ('/' + skill.name).padEnd(NAME_COL_PAD);
-            const descLines = wrapDescription(skill.description, descWidth, MAX_DESC_LINES);
-            const firstLine = descLines[0] ?? '';
-            emit(`  ${chalk.bold(nameCol)} ${firstLine}`);
-            for (let j = 1; j < descLines.length; j++) {
-                emit(`${continuationIndent}${descLines[j]}`);
+    emit(panelHeading('Commands', 'type / to search'));
+    for (const group of HELP_GROUPS) {
+        emit('');
+        emit(groupTitle(group.title));
+        for (const r of group.rows)
+            emit(row(r.name, r.description()));
+        if (group.title === 'Work on SAP') {
+            // Skills live under "Work on SAP", one dim sub-heading per category.
+            for (const category of CATEGORY_ORDER) {
+                const skills = SKILL_CATALOG.filter((s) => s.category === category);
+                if (skills.length === 0)
+                    continue;
+                emit(`  ${paint('dim', category)}`);
+                for (const skill of skills) {
+                    const descLines = wrapDescription(skill.description, descWidth, MAX_DESC_LINES);
+                    emit(`  ${chalk.bold(('/' + skill.name).padEnd(NAME_COL_PAD))} ${descLines[0] ?? ''}`);
+                    for (let j = 1; j < descLines.length; j++)
+                        emit(`${continuationIndent}${descLines[j]}`);
+                }
             }
         }
-        emit('');
     }
-    emit(chalk.cyan.bold('Shortcuts'));
-    emit(`  ${chalk.bold('/help'.padEnd(NAME_COL_PAD))} This screen`);
-    emit(`  ${chalk.bold('/skills'.padEnd(NAME_COL_PAD))} Same as /help`);
-    emit(`  ${chalk.bold('/ui [auto|ink|classic]'.padEnd(NAME_COL_PAD))} View or change UI rendering mode`);
-    emit(`  ${chalk.bold('/reroute <skill>'.padEnd(NAME_COL_PAD))} Re-run your last prompt with a different skill`);
-    emit(`  ${chalk.bold('/new'.padEnd(NAME_COL_PAD))} End the current Q&A chain — next prompt is classified fresh`);
-    emit(`  ${chalk.bold('/mode [advisory|gated|auto]'.padEnd(NAME_COL_PAD))} Cycle or set the session write mode (Shift+Tab / Alt+M also cycle)`);
-    emit(`  ${chalk.bold('/recap'.padEnd(NAME_COL_PAD))} Show the session recap (last session · open tasks · plan progress)`);
-    emit(`  ${chalk.bold('/rewind'.padEnd(NAME_COL_PAD))} Undo a write from this session — restore an object to a pre-write snapshot (Esc Esc)`);
-    emit(`  ${chalk.bold('/cost'.padEnd(NAME_COL_PAD))} Show this session's API spend so far ($ + token breakdown)`);
-    emit(`  ${chalk.bold('/context'.padEnd(NAME_COL_PAD))} Show what fills the model context window — a composition grid of bars`);
-    emit(`  ${chalk.bold('/export audit [file]'.padEnd(NAME_COL_PAD))} Write the signable session audit record to a markdown file`);
-    emit(`  ${chalk.bold('/compact'.padEnd(NAME_COL_PAD))} Summarise older turns into a compact context block — cuts subsequent turn cost by 80-90%`);
-    emit(`  ${chalk.bold('/exit'.padEnd(NAME_COL_PAD))} Quit CSPeach`);
+    emit('');
+    emit(groupTitle('Shortcuts'));
+    // Pack "key  action" pairs into lines no wider than the UI. The plain
+    // length is tracked alongside the painted line (no ANSI stripping).
+    let line = ' ';
+    let lineLen = 1;
+    for (const [key, action] of SHORTCUTS) {
+        const cellLen = 2 + key.length + 2 + action.length;
+        if (lineLen + cellLen > width && lineLen > 1) {
+            emit(line);
+            line = ' ';
+            lineLen = 1;
+        }
+        line += `  ${chalk.bold(key)}  ${paint('dim', action)}`;
+        lineLen += cellLen;
+    }
+    if (lineLen > 1)
+        emit(line);
+    emit(`  ${paint('dim', truncateToWidth(SHORTCUTS_NOTE, width - 2))}`);
     emit('');
 }

package/dist/commands/login.js

@@ -7,7 +7,7 @@
  *   3) Print user_code prominently so customer can read it
  *   4) Poll /v1/auth/device/poll every interval until verified or maxAttempts
  *   5) Save api_key + customer_id to ~/.cspeach/auth.json
- *   6) Call GET /v1/me — if trial_mode === 'byok', prompt for Anthropic key
+ *   6) Call GET /v1/me — if trial_mode === 'byok', prompt for the user's own API key
  *   7) Re-save auth file with byokAnthropicKey if provided
  *
  * Dependencies (open, print, prompt) are injected so the command is
@@ -16,8 +16,16 @@
 import keychain from '../auth/keychain.js';
 import { writeAuthFile } from '../auth/auth-file.js';
 import { fetchOrgAnthropicKey } from '../auth/org-anthropic-key.js';
+import { formatFailure, formatAttention, formatInfo } from '../renderer/notice-shape.js';
+import { panelRow } from '../renderer/panel-rows.js';
+import { paint } from '../renderer/theme.js';
+import { getGlyphs } from '../renderer/glyphs.js';
+import { sanitizeControlChars } from '../renderer/sanitize.js';
 const ANTHROPIC_KEYCHAIN_SERVICE = 'cspeach.anthropic';
 const ANTHROPIC_KEYCHAIN_ACCOUNT = 'api-key';
+/** Server-supplied text (user code, URL, email, plan) is one line with no control characters. */
+const serverText = (v) => sanitizeControlChars(String(v ?? '')).replace(/\s*\r?\n\s*/g, ' ').trim();
+const done = (text) => `${paint('ok', getGlyphs().done)} ${text}`;
 export async function runLoginCommand(deps) {
     const proxy = deps.proxyUrl.replace(/\/$/, '');
     const pollInterval = deps.pollIntervalMs ?? 5000;
@@ -27,26 +35,26 @@ export async function runLoginCommand(deps) {
     try {
         const r = await fetch(`${proxy}/v1/auth/device/start`, { method: 'POST' });
         if (!r.ok) {
-            deps.print(`error: device-start HTTP ${r.status}`);
+            deps.print(formatFailure({ what: 'Could not start sign-in', detail: [`HTTP ${r.status}`], next: 'check your network, then run cspeach login again' }).trimEnd());
             return 2;
         }
         start = await r.json();
     }
     catch (err) {
-        deps.print(`error: device-start network failure — ${err instanceof Error ? err.message : String(err)}`);
+        deps.print(formatFailure({ what: 'Could not start sign-in', detail: [err instanceof Error ? err.message : String(err)], next: 'check your network, then run cspeach login again' }).trimEnd());
         return 2;
     }
     // 2 + 3) Browser + user_code. The next line auto-opens the browser, so
     // there's nothing for the user to do — just print honest "opening" wording.
     deps.print('');
-    deps.print(`Your one-time code:  ${start.user_code}`);
-    deps.print(`Opening browser to:  ${start.verification_url_complete}`);
+    deps.print(panelRow('One-time code', serverText(start.user_code), 14));
+    deps.print(panelRow('Opening', serverText(start.verification_url_complete), 14));
     deps.print('');
     try {
         await deps.open(start.verification_url_complete);
     }
     catch {
-        deps.print(`(browser didn't auto-open — paste this URL manually: ${start.verification_url_complete})`);
+        deps.print(formatAttention({ text: "The browser didn't open", next: `open ${start.verification_url_complete} yourself` }).trimEnd());
     }
     // 4) Poll.
     let polled = null;
@@ -67,19 +75,19 @@ export async function runLoginCommand(deps) {
             if (errBody.error === 'authorization_pending')
                 continue;
             if (errBody.error === 'expired_token') {
-                deps.print('error: device code expired — run `cspeach login` again');
+                deps.print(formatFailure({ what: 'The sign-in code expired', next: 'cspeach login' }).trimEnd());
                 return 3;
             }
-            deps.print(`error: poll HTTP ${r.status} — ${errBody.error ?? 'unknown'}`);
+            deps.print(formatFailure({ what: 'Sign-in failed', detail: [`HTTP ${r.status} · ${errBody.error ?? 'unknown'}`], next: 'cspeach login' }).trimEnd());
             return 4;
         }
         catch (err) {
-            deps.print(`(network blip — retrying — ${err instanceof Error ? err.message : String(err)})`);
+            deps.print(formatInfo(`Network blip, retrying (${err instanceof Error ? err.message : String(err)})`).trimEnd());
             continue;
         }
     }
     if (!polled) {
-        deps.print('error: timed out waiting for browser authorization');
+        deps.print(formatFailure({ what: 'Timed out waiting for the browser sign-in', next: 'cspeach login' }).trimEnd());
         return 5;
     }
     // 5) Save (non-BYOK part).
@@ -88,13 +96,13 @@ export async function runLoginCommand(deps) {
         customerId: polled.customer_id,
         byokAnthropicKey: null,
     });
-    deps.print(`✓ Saved API key to ~/.cspeach/auth.json`);
+    deps.print(done('Saved your CSPeach key to ~/.cspeach/auth.json'));
     // 6) /v1/me — figure out if BYOK is required.
     try {
         const r = await fetch(`${proxy}/v1/me`, { headers: { Authorization: `Bearer ${polled.api_key}` } });
         if (r.ok) {
             const me = await r.json();
-            deps.print(`✓ Signed in as ${me.email} (${me.plan})`);
+            deps.print(done(`Signed in as ${serverText(me.email)} · ${serverText(me.plan)}`));
             if (me.trial_mode === 'byok' || me.plan === 'byo-key') {
                 // Try to fetch the org's Anthropic key first — non-fatal if unavailable.
                 const orgKey = await fetchOrgAnthropicKey(proxy, polled.api_key, {
@@ -104,14 +112,14 @@ export async function runLoginCommand(deps) {
                     ((svc, acct, k) => keychain.setPassword(svc, acct, k));
                 if (orgKey !== null) {
                     await setKey(ANTHROPIC_KEYCHAIN_SERVICE, ANTHROPIC_KEYCHAIN_ACCOUNT, orgKey);
-                    deps.print('Using your organization\'s Anthropic key.');
+                    deps.print(done("Using your organization's API key"));
                 }
                 else {
                     // Fall back to the manual paste prompt — behaviour unchanged.
                     deps.print('');
-                    deps.print('This account is BYOK — you provide your own Anthropic API key.');
-                    deps.print('Get one at https://console.anthropic.com/settings/keys');
-                    const ak = (await deps.prompt('Paste your Anthropic API key (sk-ant-...): ')).trim();
+                    deps.print(formatInfo('This account is BYOK: you provide your own API key').trimEnd());
+                    // The key-entry row — the one place the vendor and its key page are named.
+                    const ak = (await deps.prompt('Paste your Anthropic API key (sk-ant-..., from https://console.anthropic.com/settings/keys): ')).trim();
                     if (ak.startsWith('sk-ant-') && ak.length > 20) {
                         // The non-BYOK save above just persisted these exact values,
                         // so reading them back from disk would be redundant.
@@ -120,18 +128,19 @@ export async function runLoginCommand(deps) {
                             customerId: polled.customer_id,
                             byokAnthropicKey: ak,
                         });
-                        deps.print('✓ Anthropic key saved');
+                        deps.print(done('API key saved'));
                     }
                     else {
-                        deps.print('error: Anthropic key looks malformed (must start with sk-ant-). Skipped — run `cspeach login` again later.');
+                        deps.print(formatFailure({ what: 'That does not look like your own API key', detail: ['it must start with sk-ant-', 'skipped'], next: 'run cspeach login again later' }).trimEnd());
                     }
                 }
             }
         }
     }
     catch (err) {
-        deps.print(`(could not fetch /v1/me — login still succeeded — ${err instanceof Error ? err.message : String(err)})`);
+        deps.print(formatInfo(`Could not read your account details (${err instanceof Error ? err.message : String(err)}) · sign-in still worked`).trimEnd());
     }
+    deps.print(`  ${paint('dim', 'Next:')} run cspeach to start`);
     return 0;
 }
 function sleep(ms) {

package/dist/commands/logout.js

@@ -3,15 +3,19 @@
  * will fall back to the keytar-stored API key if one is present.
  */
 import { deleteAuthFile, readAuthFile } from '../auth/auth-file.js';
+import { formatInfo } from '../renderer/notice-shape.js';
+import { paint } from '../renderer/theme.js';
+import { getGlyphs } from '../renderer/glyphs.js';
 export async function runLogoutCommand(deps) {
     const before = await readAuthFile();
     await deleteAuthFile();
     if (before) {
-        deps.print('✓ Signed out — removed ~/.cspeach/auth.json');
-        deps.print('  (the REPL will use the keychain-stored key if you have one)');
+        deps.print(`${paint('ok', getGlyphs().done)} Signed out · removed ~/.cspeach/auth.json`);
+        deps.print(`  ${paint('dim', 'The REPL uses the keychain-stored key if you have one.')}`);
+        deps.print(`  ${paint('dim', 'Next:')} cspeach login   (to sign in again)`);
     }
     else {
-        deps.print('Already signed out — no auth.json present.');
+        deps.print(formatInfo('Already signed out · no auth.json present').trimEnd());
     }
     return 0;
 }

package/dist/commands/plan-audit.js

@@ -635,6 +635,7 @@ export async function runPhaseAudit(args) {
                 // read-only filter (which still exposes file_read/grep/glob).
                 toolFilter: () => false,
                 modelOverride: auditModel,
+                modelRole: 'audit',
                 suppressSaveHook: true,
                 signal: controller.signal,
             });