@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/ui/cli/activity.js

@@ -2,10 +2,60 @@ import pc from 'picocolors';
 
 const CLEAR_LINE = '\x1b[2K';
 const SPINNER = ['◐', '◓', '◑', '◒'];
+export const INTERRUPT_HINT = 'ctrl-c to cancel';
 
 function elapsed(ms) {
   if (ms < 1000) return `${Math.max(0, Math.round(ms))}ms`;
-  return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(ms < 10_000 ? 1 : 0)}s`;
+  const m = Math.floor(ms / 60_000);
+  const s = Math.floor((ms % 60_000) / 1000);
+  return `${m}m ${String(s).padStart(2, '0')}s`;
+}
+
+function count(value) {
+  const n = Number(value || 0);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n >= 10_000_000 ? 0 : 1)}m`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(n >= 100_000 ? 0 : 1)}k`;
+  return String(Math.round(n));
+}
+
+export function colorAllowed(env = process.env) {
+  if (!env || Object.hasOwn(env, 'NO_COLOR')) return false;
+  if (String(env.FORCE_COLOR || '') === '0') return false;
+  return true;
+}
+
+export function colorDepth(env = process.env) {
+  if (!colorAllowed(env)) return 0;
+  const colorterm = String(env.COLORTERM || '').toLowerCase();
+  if (colorterm.includes('truecolor') || colorterm.includes('24bit')) return 24;
+  if (String(env.TERM || '').includes('direct')) return 24;
+  return 8;
+}
+
+export function renderShimmer(text, tick = 0, options = {}) {
+  const env = options.env || process.env;
+  const source = String(text ?? '');
+  if (!source) return '';
+  const depth = colorDepth(env);
+  if (depth === 0) return source;
+  const chars = [...source];
+  const highlight = Math.max(3, Math.min(6, chars.length));
+  const origin = ((Number(tick) || 0) % (chars.length + highlight)) - highlight;
+  const painted = chars.map((ch, index) => {
+    const dist = index - origin;
+    const t = dist < 0 || dist > highlight ? 0 : 1 - Math.abs((dist / highlight) - 0.5) * 2;
+    if (depth >= 24) {
+      const r = Math.round(34 + t * 180);
+      const g = Math.round(180 + t * 75);
+      const b = Math.round(220 + t * 35);
+      return `\x1b[38;2;${r};${g};${b}m${ch}\x1b[39m`;
+    }
+    const code = t > 0.6 ? 159 : t > 0.2 ? 87 : 37;
+    return `\x1b[38;5;${code}m${ch}\x1b[39m`;
+  }).join('');
+  return `${painted}\x1b[0m`;
 }
 
 export function createInlineActivity(options = {}) {
@@ -15,17 +65,33 @@ export function createInlineActivity(options = {}) {
   const setTimer = options.setInterval || globalThis.setInterval;
   const clearTimer = options.clearInterval || globalThis.clearInterval;
   const intervalMs = Math.max(80, Number(options.intervalMs) || 120);
+  const interruptible = options.interruptible !== false;
+  const env = options.env || process.env;
 
-  let label = String(options.label || 'Thinking');
+  let label = String(options.label || 'Running');
   let startedAt = 0;
   let tick = 0;
   let timer = null;
   let active = false;
+  let tokenTotal = Number(options.tokenTotal) || 0;
+
+  function paint(kind, value) {
+    if (!colorAllowed(env)) return value;
+    if (kind === 'cyan') return pc.cyan(value);
+    if (kind === 'red') return pc.red(value);
+    if (kind === 'green') return pc.green(value);
+    return pc.dim(value);
+  }
 
   function frame() {
     if (!active || !interactive) return;
-    const icon = pc.cyan(SPINNER[tick % SPINNER.length]);
-    write(`\r${CLEAR_LINE}  ${icon} ${label} ${pc.dim('· ' + elapsed(now() - startedAt))}`);
+    const icon = paint('cyan', SPINNER[tick % SPINNER.length]);
+    const parts = [elapsed(now() - startedAt)];
+    const tokens = count(tokenTotal);
+    if (tokens) parts.unshift(`${tokens} tokens`);
+    if (interruptible) parts.push(INTERRUPT_HINT);
+    const paintedLabel = renderShimmer(label, tick, { env });
+    write(`\r${CLEAR_LINE}  ${icon} ${paintedLabel} ${paint('dim', '· ' + parts.join(' · '))}`);
     tick += 1;
   }
 
@@ -43,8 +109,9 @@ export function createInlineActivity(options = {}) {
     }
   }
 
-  function update(nextLabel) {
+  function update(nextLabel, nextTokens) {
     if (nextLabel) label = String(nextLabel);
+    if (Number.isFinite(Number(nextTokens))) tokenTotal = Number(nextTokens);
     if (!active) start(label);
     else frame();
   }
@@ -55,8 +122,9 @@ export function createInlineActivity(options = {}) {
     timer = null;
     const duration = elapsed(now() - startedAt);
     if (interactive) write(`\r${CLEAR_LINE}`);
-    const icon = status === 'error' ? pc.red('✗') : pc.green('✓');
-    write(`  ${icon} ${finalLabel} ${pc.dim('· ' + duration)}\n`);
+    const icon = status === 'error' ? paint('red', '✗') : paint('green', '✓');
+    const tokens = count(tokenTotal);
+    write(`  ${icon} ${finalLabel} ${paint('dim', '· ' + [tokens ? `${tokens} tokens` : null, duration].filter(Boolean).join(' · '))}\n`);
     active = false;
   }
 
@@ -64,6 +132,7 @@ export function createInlineActivity(options = {}) {
     get active() { return active; },
     start,
     update,
+    setTokens(value) { update(null, value); },
     succeed(labelText) { finish('success', labelText || label); },
     fail(labelText) { finish('error', labelText || 'Failed'); },
     clear() {

package/src/ui/cli/footer.js

@@ -21,19 +21,120 @@ function ctxLabel(usage) {
   return `ctx ${Math.min(999, Math.round((active / window) * 100))}%`;
 }
 
+function money(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return null;
+  return `$${n.toFixed(n >= 1 ? 2 : 3)}`;
+}
+
+export const FOOTER_HINTS = '/ commands · @ files · ! shell · ctrl-c to cancel';
+
 export function renderCliFooter(value = {}) {
   const usage = value.usage || value.usageSnapshot || {};
   const cumulative = usage.cumulative || {};
   const model = String(value.model || value.modelLabel || 'model');
+  const provider = String(value.provider || '').trim();
+  const effort = String(value.effort || value.reasoning || '').trim();
   const tier = String(value.tier || '').trim();
+  const projectName = String(value.projectName || value.identity || (value.cwd ? value.project : '') || '').trim();
+  const branch = String(value.branch || value.gitBranch || '').trim();
+  const cwd = String(value.cwd || (!value.projectName && !value.identity ? value.project : '') || '').trim();
+  const action = String(value.action || value.statusLabel || '').trim();
+  const filesEdited = Number(value.filesEdited || value.files_edited || 0);
   const elapsedMs = Number(value.elapsedMs);
-  const parts = [
-    model,
-    ctxLabel(usage),
-    `↑${count(cumulative.input_tokens)} ↓${count(cumulative.output_tokens)}`,
-  ];
-  if (Number(cumulative.cached_input_tokens) > 0) parts.push(`cache ${count(cumulative.cached_input_tokens)}`);
-  if (tier && tier !== 'default') parts.push(tier);
-  if (Number.isFinite(elapsedMs) && elapsedMs >= 0) parts.push(elapsedMs < 60_000 ? `${(elapsedMs / 1000).toFixed(1)}s` : `${Math.floor(elapsedMs / 60_000)}m${Math.floor((elapsedMs % 60_000) / 1000)}s`);
-  return pc.dim('  ' + parts.join(' · '));
+  const cost = money(value.cost ?? cumulative.cost_usd ?? usage.cost_usd);
+
+  const primary = [];
+  if (projectName) primary.push(projectName);
+  if (branch) primary.push(branch);
+  if (cwd) primary.push(cwd.replace(String(process.env.HOME || ''), '~'));
+  if (action) primary.push(action);
+  primary.push([provider, model, effort].filter(Boolean).join(' ') || model);
+  primary.push(ctxLabel(usage));
+  primary.push(`↑${count(cumulative.input_tokens)} ↓${count(cumulative.output_tokens)}`);
+  if (Number(cumulative.cached_input_tokens) > 0) primary.push(`cache ${count(cumulative.cached_input_tokens)}`);
+  if (filesEdited > 0) primary.push(`${filesEdited} files edited`);
+  if (cost) primary.push(cost);
+  if (tier && tier !== 'default') primary.push(tier);
+  if (Number.isFinite(elapsedMs) && elapsedMs >= 0) {
+    primary.push(elapsedMs < 60_000 ? `${(elapsedMs / 1000).toFixed(1)}s` : `${Math.floor(elapsedMs / 60_000)}m${Math.floor((elapsedMs % 60_000) / 1000)}s`);
+  }
+
+  const hints = String(value.hints || FOOTER_HINTS);
+  return [
+    pc.dim('  ' + primary.join(' · ')),
+    pc.dim('  ' + hints),
+  ].join('\n');
+}
+
+export function renderDiffPreview(diffText, options = {}) {
+  const source = String(diffText || '');
+  const color = options.color ?? !Object.hasOwn(process.env, 'NO_COLOR');
+  const paint = (text, style) => {
+    if (!color) return text;
+    const code = style === 'add' ? '32' : style === 'del' ? '31' : style === 'hunk' ? '36' : style === 'meta' ? '1' : '2';
+    return `\x1b[${code}m${text}\x1b[0m`;
+  };
+  if (!source.trim()) return `  ${paint('no changes', 'dim')}\n`;
+  const maxLines = Math.max(20, Number(options.maxLines) || 200);
+  const lines = source.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+  const truncated = lines.length > maxLines;
+  const shown = truncated ? lines.slice(0, maxLines) : lines;
+  const out = shown.map((line) => {
+    if (line.startsWith('diff ') || line.startsWith('index ') || line.startsWith('+++') || line.startsWith('---')) {
+      return `  ${paint(line, 'meta')}`;
+    }
+    if (line.startsWith('@@')) return `  ${paint(line, 'hunk')}`;
+    if (line.startsWith('+')) return `  ${paint(line, 'add')}`;
+    if (line.startsWith('-')) return `  ${paint(line, 'del')}`;
+    return `  ${line}`;
+  });
+  if (truncated) out.push(`  ${paint(`… ${lines.length - maxLines} more lines`, 'dim')}`);
+  return `${out.join('\n')}\n`;
+}
+
+export function renderUsagePanel(value = {}) {
+  const session = value.session || {};
+  const usage = value.usage || value.usageSnapshot || session.usage_snapshot || {};
+  const cumulative = usage.cumulative || session.cumulative_usage || {};
+  const current = usage.current_context || {};
+  const lines = [];
+  const push = (label, text) => lines.push(`  ${pc.dim(label.padEnd(12))} ${text}`);
+
+  lines.push('');
+  lines.push(`  ${pc.bold('AgentSam · Usage')}`);
+  lines.push('');
+  push('session', session.id || session.session_id || 'unknown');
+  push('provider', value.provider || session.provider || (String(session.model_key || '').split(':')[0]) || 'unknown');
+  push('model', value.model || session.model || session.model_key || 'unknown');
+  push('reasoning', value.effort || session.reasoning_effort || 'unknown/unavailable');
+  push('tier', value.tier || session.service_tier || 'unknown/unavailable');
+  lines.push('');
+  const window = Number(current.window_tokens || 0);
+  const active = Number(current.input_tokens || 0);
+  push(
+    'context',
+    window > 0
+      ? `${count(active)} / ${count(window)} · ${Math.round((active / window) * 1000) / 10}%`
+      : active > 0
+        ? `${count(active)} / unknown`
+        : 'unknown/unavailable',
+  );
+  push('input', count(cumulative.input_tokens));
+  push('output', count(cumulative.output_tokens));
+  push('cached', Number(cumulative.cached_input_tokens) > 0 ? count(cumulative.cached_input_tokens) : 'unknown/unavailable');
+  lines.push('');
+  push('cost', money(value.cost ?? cumulative.cost_usd ?? session.total_cost_usd) || 'unknown/unavailable');
+  push('elapsed', value.elapsedLabel || (Number.isFinite(Number(value.elapsedMs)) ? `${Math.round(Number(value.elapsedMs) / 1000)}s` : 'unknown/unavailable'));
+  push('tool calls', value.toolCalls != null ? String(value.toolCalls) : 'unknown/unavailable');
+  push('shell', value.shellCommands != null ? String(value.shellCommands) : 'unknown/unavailable');
+  push('files', value.filesEdited != null ? `${value.filesEdited} edited` : 'unknown/unavailable');
+  push('compactions', value.compactions != null ? String(value.compactions) : 'unknown/unavailable');
+  lines.push('');
+  push('accounting', usage.estimate_kind || value.estimateKind || 'unknown/unavailable');
+  if (session.id || session.session_id) {
+    push('resume', `agentsam resume ${session.id || session.session_id}`);
+  }
+  lines.push('');
+  return lines.join('\n');
 }

package/src/ui/cli/help.js

@@ -1,82 +1,21 @@
 import pc from 'picocolors';
 import { isCancel, select } from '@clack/prompts';
 import pkg from '../../../package.json' with { type: 'json' };
-
-const HELP_TOPICS = Object.freeze([
-  {
-    id: 'start',
-    label: 'Start / resume',
-    summary: 'Enter Agent Sam, resume work, inspect identity, and choose a model.',
-    rows: [
-      ['agentsam', 'Enter the interactive Agent Sam experience'],
-      ['agentsam resume [session]', 'Resume a saved Agent Sam session'],
-      ['agentsam whoami', 'Show authenticated account and credential status'],
-      ['agentsam models', 'Probe account-visible hosted/local models'],
-      ['agentsam providers', 'Configure and verify machine provider credentials'],
-      ['agentsam env init <provider>', 'Low-level provider profile compatibility command'],
-    ],
-  },
-  {
-    id: 'work',
-    label: 'Build / inspect',
-    summary: 'Repository intelligence and normal project work.',
-    rows: [
-      ['agentsam inspect', 'Bounded repository index / authority view'],
-      ['agentsam index', 'Incremental AST and optional embeddings'],
-      ['agentsam search "query"', 'Search indexed code/text'],
-      ['agentsam repo snapshot', 'Git composition/churn snapshot'],
-      ['agentsam security', 'Dependency and trust-boundary scan'],
-      ['agentsam merkle', 'Integrity snapshots and comparisons'],
-    ],
-  },
-  {
-    id: 'runtime',
-    label: 'Runtime / terminal',
-    summary: 'Local, remote, sandbox, and deployment controls.',
-    rows: [
-      ['agentsam status', 'Project, Git, DB, API, and PTY status'],
-      ['agentsam start-local', 'Start the local PTY service'],
-      ['agentsam connections', 'Inspect available execution connections'],
-      ['agentsam tunnel', 'Expose local PTY only when remote access is wanted'],
-      ['agentsam deploy', 'Graduate intentionally to cloud infrastructure'],
-      ['agentsam cloudflare', 'Wrangler and Cloudflare runtime diagnostics'],
-    ],
-  },
-  {
-    id: 'inside',
-    label: 'Inside Agent Sam',
-    summary: 'Commands available while the interactive session is running.',
-    rows: [
-      ['/', 'Open the keyboard command picker'],
-      ['/model', 'Choose model, reasoning, and processing tier'],
-      ['/providers', 'Configure and verify machine provider credentials'],
-      ['/context', 'Show live context economics'],
-      ['/usage', 'Show token/cost/session receipt'],
-      ['/settings', 'Change runtime, terminal, and model policy'],
-      ['/status', 'Show project/runtime health'],
-      ['/help [topic]', 'Show in-session help'],
-      ['/exit', 'Return to the host shell'],
-    ],
-  },
-  {
-    id: 'create',
-    label: 'Create / extend',
-    summary: 'Scaffold and add reusable capabilities.',
-    rows: [
-      ['agentsam create <name> --preset <preset>', 'Create a new AgentSam project'],
-      ['agentsam add <capability>', 'Add a supported capability'],
-      ['agentsam capabilities [id]', 'Inspect capability contracts'],
-      ['agentsam skills [id]', 'Inspect packaged skills'],
-      ['agentsam identity init', 'Add reusable identity surfaces'],
-      ['agentsam dockerize', 'Build supported container targets'],
-    ],
-  },
-]);
+import {
+  CLI_COMMAND_CATALOG,
+  CLI_HELP_TOPICS,
+  getCliCommand,
+  listCliCommands,
+  printAssistTip,
+} from '../../cli/command-catalog.js';
+import { SLASH_COMMANDS } from '../../lib/slash-commands.js';
 
 const TOPIC_ALIASES = new Map([
   ['models', 'start'], ['model', 'start'], ['provider', 'start'], ['providers', 'start'], ['resume', 'start'],
   ['repo', 'work'], ['repository', 'work'], ['inspect', 'work'], ['index', 'work'], ['security', 'work'],
+  ['ingest', 'work'], ['codebaseindex', 'work'], ['codebase-index', 'work'],
   ['terminal', 'runtime'], ['connections', 'runtime'], ['remote', 'runtime'], ['sandbox', 'runtime'], ['deploy', 'runtime'],
+  ['mcp', 'runtime'], ['eval', 'runtime'],
   ['slash', 'inside'], ['commands', 'inside'], ['session', 'inside'], ['usage', 'inside'], ['context', 'inside'],
   ['create', 'create'], ['scaffold', 'create'], ['capabilities', 'create'], ['skills', 'create'],
 ]);
@@ -85,44 +24,66 @@ function clean(value) {
   return value == null ? '' : String(value).trim().toLowerCase();
 }
 
+function commandsForTopic(topicId) {
+  return listCliCommands({ topic: topicId }).map((entry) => {
+    const aliases = (entry.aliases || []).filter((a) => !a.startsWith('-')).slice(0, 2);
+    const name = aliases.length ? `agentsam ${entry.id}|${aliases.join('|')}` : `agentsam ${entry.id}`;
+    const tip = entry.skill ? ` · skill ${entry.skill}` : '';
+    return [name, `${entry.summary}${tip}`];
+  });
+}
+
 function padRows(rows) {
-  const width = Math.min(42, Math.max(...rows.map(([command]) => command.length), 0));
+  const width = Math.min(52, Math.max(...rows.map(([command]) => command.length), 0));
   return rows.map(([command, description]) => '    ' + pc.cyan(command.padEnd(width)) + '  ' + pc.dim(description));
 }
 
 export function resolveHelpTopic(value) {
   const query = clean(value);
   if (!query) return null;
-  const direct = HELP_TOPICS.find((topic) => topic.id === query || clean(topic.label) === query);
-  if (direct) return direct;
+  const direct = CLI_HELP_TOPICS.find((topic) => topic.id === query || clean(topic.label) === query);
+  if (direct) {
+    return { ...direct, rows: commandsForTopic(direct.id) };
+  }
   const alias = TOPIC_ALIASES.get(query);
-  if (alias) return HELP_TOPICS.find((topic) => topic.id === alias) || null;
-  return HELP_TOPICS.find((topic) =>
-    topic.rows.some(([command, description]) => clean(command).includes(query) || clean(description).includes(query))) || null;
+  if (alias) {
+    const topic = CLI_HELP_TOPICS.find((t) => t.id === alias);
+    return topic ? { ...topic, rows: commandsForTopic(topic.id) } : null;
+  }
+  const command = getCliCommand(query);
+  if (command) {
+    const topic = CLI_HELP_TOPICS.find((t) => t.id === command.topic);
+    return topic ? { ...topic, rows: commandsForTopic(topic.id) } : null;
+  }
+  return CLI_HELP_TOPICS.map((topic) => ({ ...topic, rows: commandsForTopic(topic.id) }))
+    .find((topic) => topic.rows.some(([cmd, description]) => clean(cmd).includes(query) || clean(description).includes(query))) || null;
 }
 
 export function renderHelpOverview(version, options = {}) {
+  const common = listCliCommands({ common: true });
   const lines = [
     '',
     '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version),
-    '  ' + pc.dim('Type normally to work with Agent Sam. Use help only when you need the map.'),
+    '  ' + pc.dim('SAM = Systematic Autonomous Machinery · help is generated from the command catalog.'),
     '',
     '  ' + pc.bold('Start'),
     '    ' + pc.cyan('agentsam') + '                         ' + pc.dim('enter the interactive experience'),
     '    ' + pc.cyan('agentsam resume') + '                  ' + pc.dim('continue saved work'),
-    '    ' + pc.cyan('agentsam help <topic>') + '            ' + pc.dim('focused help'),
+    '    ' + pc.cyan('agentsam help <topic>') + '            ' + pc.dim('focused help from catalog'),
+    '    ' + pc.cyan('agentsam skills <id>') + '             ' + pc.dim('load how-to skill instructions'),
     '',
     '  ' + pc.bold('Common'),
-    '    ' + pc.cyan('agentsam inspect') + '                 ' + pc.dim('understand this repository'),
-    '    ' + pc.cyan('agentsam models') + '                  ' + pc.dim('see account-visible models'),
-    '    ' + pc.cyan('agentsam status') + '                  ' + pc.dim('check project/runtime health'),
-    '    ' + pc.cyan('agentsam security') + '                ' + pc.dim('scan dependency + trust boundaries'),
-    '    ' + pc.cyan('agentsam deploy') + '                  ' + pc.dim('graduate intentionally'),
-    '',
-    '  ' + pc.dim('Inside Agent Sam: press / for the command picker. Ask the selected model for natural-language help at any time.'),
   ];
+  for (const entry of common) {
+    lines.push('    ' + pc.cyan(('agentsam ' + entry.id).padEnd(34)) + '  ' + pc.dim(entry.summary));
+  }
+  lines.push(
+    '',
+    '  ' + pc.dim('Every command prints: tip: use skill <id>  — machine baseline for in-CLI guidance.'),
+    '  ' + pc.dim('Inside Agent Sam: press / for the command picker.'),
+  );
   if (options.showTopics !== false) {
-    lines.push('', '  ' + pc.dim('Topics: ' + HELP_TOPICS.map((topic) => topic.id).join(' · ') + ' · all'));
+    lines.push('', '  ' + pc.dim('Topics: ' + CLI_HELP_TOPICS.map((topic) => topic.id).join(' · ') + ' · all · skills'));
   }
   lines.push('');
   return lines.join('\n');
@@ -130,21 +91,37 @@ export function renderHelpOverview(version, options = {}) {
 
 export function renderHelpTopic(topic, version) {
   if (!topic) return renderHelpOverview(version);
+  const skillHint = topic.rows?.[0]?.[1]?.includes('skill')
+    ? ''
+    : '';
   return [
     '',
     '  ' + pc.bold('Agent Sam') + ' ' + pc.dim('v' + version) + ' ' + pc.dim('·') + ' ' + pc.bold(topic.label),
     '  ' + pc.dim(topic.summary),
     '',
-    ...padRows(topic.rows),
+    ...padRows(topic.rows || []),
     '',
-    '  ' + pc.dim('Tip: run agentsam help for the map, or agentsam to return to the interactive experience.'),
+    '  ' + pc.dim('Tip: agentsam skills <id> loads how-to instructions for that command’s skill.'),
+    skillHint,
     '',
   ].join('\n');
 }
 
 export function renderAllHelp(version) {
   const lines = [renderHelpOverview(version, { showTopics: false })];
-  for (const topic of HELP_TOPICS) lines.push(renderHelpTopic(topic, version));
+  for (const topic of CLI_HELP_TOPICS) {
+    lines.push(renderHelpTopic({ ...topic, rows: commandsForTopic(topic.id) }, version));
+  }
+  lines.push(
+    '',
+    '  ' + pc.bold('Inside shell (slash)'),
+    ...padRows(SLASH_COMMANDS.slice(0, 16).map((row) => [row.cmd, row.description])),
+    '    ' + pc.dim(`… ${SLASH_COMMANDS.length} slash commands total · /help inside the shell`),
+    '',
+    '  ' + pc.bold('Catalog'),
+    '    ' + pc.dim(`${CLI_COMMAND_CATALOG.length} top-level commands · source: src/cli/command-catalog.js`),
+    '',
+  );
   return lines.join('');
 }
 
@@ -153,11 +130,27 @@ export async function runHelp(argv = [], options = {}) {
   const write = options.write || ((value) => process.stdout.write(value));
   const args = argv.filter((arg) => arg !== '--interactive');
 
-  if (args.includes('--all')) {
+  printAssistTip('help', { write: (s) => process.stderr.write(s) });
+
+  if (args.includes('--all') || args.some((arg) => clean(arg) === 'all')) {
     write(renderAllHelp(version));
     return;
   }
 
+  if (args.some((arg) => clean(arg) === 'skills' || clean(arg) === 'skill')) {
+    write([
+      '',
+      '  ' + pc.bold('Skills') + ' ' + pc.dim('· how-to instructions per surface'),
+      '    ' + pc.cyan('agentsam skills') + '                      ' + pc.dim('list portable skills'),
+      '    ' + pc.cyan('agentsam skills <id>') + '               ' + pc.dim('print skill instructions'),
+      '    ' + pc.cyan('agentsam skills <id> --references') + '  ' + pc.dim('include reference docs'),
+      '',
+      '  ' + pc.dim('Every CLI command tip points at a skill id — that is the machine baseline.'),
+      '',
+    ].join('\n'));
+    return;
+  }
+
   const topicArg = args.find((arg) => !arg.startsWith('-'));
   if (topicArg) {
     const topic = resolveHelpTopic(topicArg);
@@ -177,18 +170,25 @@ export async function runHelp(argv = [], options = {}) {
   }
 
   const choice = await select({
-    message: 'Agent Sam help',
+    message: 'Agent Sam help (catalog-driven)',
     options: [
-      ...HELP_TOPICS.map((topic) => ({ value: topic.id, label: topic.label, hint: topic.summary })),
-      { value: 'all', label: 'All commands', hint: 'Print the complete deterministic help map' },
+      ...CLI_HELP_TOPICS.map((topic) => ({ value: topic.id, label: topic.label, hint: topic.summary })),
+      { value: 'skills', label: 'Skills', hint: 'How-to instructions loaded via agentsam skills' },
+      { value: 'all', label: 'All commands', hint: 'Print the complete catalog map' },
       { value: 'exit', label: 'Back', hint: 'Return without printing more help' },
     ],
   });
   if (isCancel(choice) || choice === 'exit') return;
   if (choice === 'all') write(renderAllHelp(version));
-  else write(renderHelpTopic(resolveHelpTopic(choice), version));
+  else if (choice === 'skills') {
+    write([
+      '',
+      '  Run ' + pc.cyan('agentsam skills') + ' to list, or ' + pc.cyan('agentsam skills agentsam-codebaseindex') + ' for ingest how-to.',
+      '',
+    ].join('\n'));
+  } else write(renderHelpTopic(resolveHelpTopic(choice), version));
 }
 
 export function listHelpTopics() {
-  return HELP_TOPICS.map((topic) => ({ id: topic.id, label: topic.label, summary: topic.summary }));
+  return CLI_HELP_TOPICS.map((topic) => ({ id: topic.id, label: topic.label, summary: topic.summary }));
 }