@thispointon/kondi-chat 0.1.2

package/src/cli/commands.ts

@@ -0,0 +1,419 @@
+/**
+ * Slash command dispatcher for the TUI backend.
+ *
+ * Split out of backend.ts to shrink the god-object. Every command handler
+ * is a branch of one switch statement; the runtime dependencies it
+ * reaches for are bundled into a single `CommandDeps` param instead of
+ * 20 positional args. Keep this file free of startup wiring and stdin
+ * plumbing — its only job is: given the typed deps and a command
+ * string, return the string to display.
+ *
+ * Two side effects the handlers can produce beyond their return value:
+ *   - Calling `deps.emit(...)` to push a TUI event (used by /use and
+ *     /mode so the model indicator refreshes without a turn).
+ *   - Mutating shared state on `deps.profiles`, `deps.router`,
+ *     `deps.checkpointManager`, etc. — these are live references, not
+ *     snapshots, so changes persist for the rest of the session.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Session, ImageAttachment } from '../types.ts';
+import type { Ledger } from '../audit/ledger.ts';
+import type { ContextManager } from '../context/manager.ts';
+import type { ModelRegistry } from '../router/registry.ts';
+import type { RoutingCollector } from '../router/collector.ts';
+import type { ProfileManager } from '../router/profiles.ts';
+import type { Router as UnifiedRouter } from '../router/index.ts';
+import type { CouncilProfileManager } from '../council/profiles.ts';
+import { executeCouncil } from '../council/tool.ts';
+import type { Analytics } from '../audit/analytics.ts';
+import type { CheckpointManager } from '../engine/checkpoints.ts';
+import type { SessionStore } from '../session/store.ts';
+import type { RateLimiter } from '../providers/rate-limiter.ts';
+import type { TelemetryEmitter } from '../audit/telemetry.ts';
+import type { ToolContext } from '../engine/tools.ts';
+import type { McpClientManager } from '../mcp/client.ts';
+import type { ToolManager } from '../mcp/tool-manager.ts';
+import { saveMcpServer, removeMcpServer } from '../mcp/config.ts';
+import { formatHelp } from './help.ts';
+import { writeActiveProfile } from './wizard.ts';
+import { pickCompressionModel } from './submit-helpers.ts';
+
+export interface CommandDeps {
+  session: Session;
+  contextManager: ContextManager;
+  ledger: Ledger;
+  registry: ModelRegistry;
+  collector: RoutingCollector;
+  toolCtx: ToolContext;
+  mcpClient: McpClientManager;
+  toolManager: ToolManager;
+  workingDir: string;
+  profiles: ProfileManager;
+  router: UnifiedRouter;
+  councilProfiles: CouncilProfileManager;
+  analytics: Analytics;
+  checkpointManager: CheckpointManager;
+  sessionStore: SessionStore;
+  rateLimiter: RateLimiter;
+  pendingImages: ImageAttachment[];
+  telemetry: TelemetryEmitter;
+  /** Push a live event back to the TUI. */
+  emit: (event: Record<string, unknown>) => void;
+}
+
+export async function handleCommand(input: string, deps: CommandDeps): Promise<string> {
+  const {
+    session, contextManager, ledger, registry, collector, toolCtx,
+    mcpClient, toolManager, workingDir,
+    profiles, router, councilProfiles, analytics,
+    checkpointManager, sessionStore, rateLimiter, pendingImages, telemetry, emit,
+  } = deps;
+
+  const parts = input.split(/\s+/);
+  const cmd = parts[0];
+
+  switch (cmd) {
+    case '/mode-details': {
+      // Show full config for a profile. No arg = active profile.
+      const name = parts[1] || profiles.getActive().name;
+      const all = profiles.getAll();
+      const p = all[name];
+      if (!p) return `Unknown profile: ${name}. Available: ${profiles.getNames().join(', ')}`;
+
+      // Build a model roster. If the profile has rolePinning, show those
+      // specific models. If not, show all enabled models (the profile uses
+      // whatever's available via capability preferences).
+      const modelIds = new Set<string>();
+      if (p.rolePinning && Object.keys(p.rolePinning).length > 0) {
+        for (const id of Object.values(p.rolePinning)) modelIds.add(id as string);
+      } else {
+        for (const m of registry.getEnabled()) modelIds.add(m.id);
+      }
+
+      const lines: string[] = [
+        `═══ ${p.name}${p.name === profiles.getActive().name ? ' (active)' : ''} ═══`,
+        p.description,
+        '',
+      ];
+
+      // Models in this profile
+      if (modelIds.size > 0) {
+        lines.push('── Models ────────────────────────────────────────────');
+        for (const id of modelIds) {
+          const m = registry.getById(id);
+          if (m) {
+            const alias = m.alias ? `@${m.alias}` : '';
+            const cost = m.inputCostPer1M === 0 && m.outputCostPer1M === 0
+              ? 'free'
+              : `$${m.inputCostPer1M}/$${m.outputCostPer1M} per 1M`;
+            // Find which phases this model is pinned to
+            const phases: string[] = [];
+            if (p.rolePinning) {
+              for (const [phase, pinId] of Object.entries(p.rolePinning)) {
+                if (pinId === id) phases.push(phase);
+              }
+            }
+            const phaseStr = phases.length > 0 ? ` ← ${phases.join(', ')}` : '';
+            lines.push(`  ${m.name} ${alias} (${m.provider}, ${cost})${phaseStr}`);
+            lines.push(`    capabilities: ${m.capabilities.join(', ')}`);
+          } else {
+            lines.push(`  ${id} (not in registry)`);
+          }
+        }
+        lines.push('');
+      }
+
+      // Role assignments
+      if (p.rolePinning && Object.keys(p.rolePinning).length > 0) {
+        lines.push('── Phase → Model ─────────────────────────────────────');
+        for (const [phase, modelId] of Object.entries(p.rolePinning)) {
+          const m = registry.getById(modelId as string);
+          const label = m ? `${m.name} @${m.alias || m.id}` : modelId;
+          lines.push(`  ${(phase as string).padEnd(14)} → ${label}`);
+        }
+        lines.push('');
+      }
+
+      // Settings
+      lines.push('── Settings ──────────────────────────────────────────');
+      lines.push(`  Context budget:    ${p.contextBudget.toLocaleString()} tokens`);
+      lines.push(`  Loop caps:         ${p.loopIterationCap} iterations, $${p.loopCostCap.toFixed(2)}`);
+      lines.push(`  Max output tokens: ${p.maxOutputTokens.toLocaleString()}`);
+      lines.push(`  Prefer local:      ${p.preferLocal ? 'yes' : 'no'}`);
+      lines.push(`  Reflection:        ${p.includeReflection ? 'yes' : 'no'}`);
+      lines.push(`  Verification:      ${p.includeVerification ? 'yes' : 'no'}`);
+      lines.push(`  Promotion after:   ${p.promotionThreshold} failures`);
+
+      // Capability preferences
+      lines.push('');
+      lines.push('── Capability Preferences ────────────────────────────');
+      lines.push(`  Planning:  [${p.planningPreference.join(', ')}]`);
+      lines.push(`  Execution: [${p.executionPreference.join(', ')}]`);
+      lines.push(`  Review:    [${p.reviewPreference.join(', ')}]`);
+
+      return lines.join('\n');
+    }
+    case '/mode': {
+      const mode = parts[1];
+      if (!mode) return profiles.format();
+      try {
+        profiles.setProfile(mode);
+        router.rules.setProfile(profiles.getActive());
+        // Reapply profile scope to intent router + compression model so
+        // switching to/from zai updates everything in one shot.
+        const p = profiles.getActive();
+        const cheap = pickCompressionModel(registry, p);
+        if (cheap) contextManager.setCompressionModel(cheap.provider, cheap.id);
+        router.setProfileScope({
+          classifier: cheap ? { provider: cheap.provider, model: cheap.id } : undefined,
+          rolePinning: p.rolePinning,
+        });
+        writeActiveProfile(resolve(workingDir, '.kondi-chat'), profiles.getActive().name);
+        // Switching mode clears any /use override — the user wants the
+        // profile's routing, not a stale manual pin.
+        router.rules.setOverride(undefined);
+        emit({ type: 'model_override', label: profiles.getActive().name, pinned: false });
+        return `Mode: ${profiles.getActive().name}`;
+      } catch (e) { return (e as Error).message; }
+    }
+    case '/use': {
+      const alias = parts[1];
+      if (!alias) return router.rules.getOverride()
+        ? `Using: ${router.rules.getOverride()!.alias || router.rules.getOverride()!.id}`
+        : 'Router: auto';
+      if (alias === 'auto') {
+        router.rules.setOverride(undefined);
+        emit({ type: 'model_override', label: profiles.getActive().name, pinned: false });
+        return 'Router: auto';
+      }
+      const model = registry.getByAlias(alias);
+      if (!model) {
+        const candidates: string[] = registry.findAliasCandidates(alias);
+        const hint = candidates.length > 1
+          ? ` — ambiguous, could be: ${candidates.map((a: string) => `@${a}`).join(', ')}`
+          : ` — available: ${registry.getAliases().join(', ')}`;
+        return `Unknown: ${alias}${hint}`;
+      }
+      router.rules.setOverride(model);
+      emit({ type: 'model_override', label: model.alias || model.id, pinned: true });
+      return `Using: ${model.name} (@${model.alias})`;
+    }
+    case '/consultants': {
+      const roster = toolCtx.consultants ?? [];
+      if (roster.length === 0) return 'No consultants configured. Edit .kondi-chat/consultants.json to add some.';
+      const lines: string[] = ['Available consultants:', ''];
+      for (const c of roster) {
+        lines.push(`  ${c.role}`);
+        lines.push(`    ${c.name} (${c.provider}/${c.model})`);
+        lines.push(`    ${c.description}`);
+        lines.push('');
+      }
+      lines.push('Edit .kondi-chat/consultants.json to add, remove, or tune them.');
+      return lines.join('\n');
+    }
+    case '/models': return registry.format();
+    case '/health': { await registry.checkHealth(); return registry.formatHealth(); }
+    case '/routing': return collector.formatStats();
+    case '/status': {
+      const budget = contextManager.getBudgetStatus();
+      return [
+        `Session: ${session.id.slice(0, 8)}`,
+        `Tokens: ${session.totalInputTokens.toLocaleString()}in / ${session.totalOutputTokens.toLocaleString()}out`,
+        `Cost: $${session.totalCostUsd.toFixed(4)}`,
+        `Context: ${budget.currentContextSize.toLocaleString()}/${budget.modelContextWindow.toLocaleString()} (${(budget.contextUtilization * 100).toFixed(0)}%)`,
+      ].join('\n');
+    }
+    case '/cost': {
+      const totals = ledger.getTotals();
+      if (totals.calls === 0) return 'No calls yet.';
+      const lines = [
+        `═══ Session Cost Breakdown ═══`,
+        `Total: ${totals.calls} calls | ${totals.inputTokens.toLocaleString()}in / ${totals.outputTokens.toLocaleString()}out | $${totals.costUsd.toFixed(4)}`,
+        '',
+        'By Model:',
+      ];
+      type ModelTotal = { calls: number; inputTokens: number; outputTokens: number; costUsd: number };
+      const byModel = totals.byModel as Record<string, ModelTotal>;
+      for (const [m, d] of Object.entries(byModel).sort((a, b) => b[1].costUsd - a[1].costUsd)) {
+        lines.push(`  ${m.slice(0, 28).padEnd(30)} ${String(d.calls).padStart(3)} calls  ${d.inputTokens.toLocaleString().padStart(10)}in  ${d.outputTokens.toLocaleString().padStart(8)}out  $${d.costUsd.toFixed(4)}`);
+      }
+      const byPhase = totals.byPhase as Record<string, ModelTotal>;
+      if (Object.keys(byPhase).length > 1) {
+        lines.push('', 'By Phase:');
+        for (const [p, d] of Object.entries(byPhase).sort((a, b) => b[1].costUsd - a[1].costUsd)) {
+          lines.push(`  ${p.padEnd(15)} ${String(d.calls).padStart(3)} calls  ${d.inputTokens.toLocaleString().padStart(10)}in  ${d.outputTokens.toLocaleString().padStart(8)}out  $${d.costUsd.toFixed(4)}`);
+        }
+      }
+      return lines.join('\n');
+    }
+    case '/council': {
+      if (!parts[1] || parts[1] === 'list') return councilProfiles.format();
+      if (parts[1] === 'run' && parts[2]) {
+        const brief = parts.slice(3).join(' ');
+        if (!brief) return 'Usage: /council run <profile> <brief>';
+        const result = await executeCouncil(parts[2], brief, [], workingDir, councilProfiles);
+        return result.content;
+      }
+      return 'Usage: /council [list|run <profile> <brief>]';
+    }
+    case '/analytics': {
+      const days = parts[1] ? parseInt(parts[1]) : 30;
+      if (parts[1] === 'rebuild') { analytics.rebuild(); return 'Analytics rebuilt from all ledger files.'; }
+      if (parts[1] === 'export') { return analytics.exportAll(); }
+      return analytics.format(days);
+    }
+    case '/attach': {
+      const p = parts.slice(1).join(' ');
+      if (!p) return 'Usage: /attach <path to image>';
+      try {
+        const abs = resolve(workingDir, p);
+        const buf = readFileSync(abs);
+        const MAX_BYTES = 10 * 1024 * 1024;
+        if (buf.byteLength > MAX_BYTES) return `Image too large: ${buf.byteLength} > 10MB`;
+        if (pendingImages.length >= 5) return 'Already 5 images queued for next message.';
+        const ext = (p.split('.').pop() || '').toLowerCase();
+        const mime: Record<string, string> = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' };
+        const mimeType = mime[ext];
+        if (!mimeType) return `Unsupported image type: .${ext}`;
+        pendingImages.push({
+          mimeType,
+          base64: buf.toString('base64'),
+          originalPath: p,
+          sizeBytes: buf.byteLength,
+        });
+        return `Attached ${p} (${mimeType}, ${buf.byteLength} bytes). Queued ${pendingImages.length}/5 for next message.`;
+      } catch (e) {
+        return `Attach failed: ${(e as Error).message}`;
+      }
+    }
+    case '/telemetry': {
+      const sub = parts[1] || 'status';
+      if (sub === 'enable') { telemetry.enable(); return 'Telemetry: local-only (no network). Run /telemetry details to see the schema.'; }
+      if (sub === 'disable') { telemetry.disable(); return 'Telemetry: disabled (local events cleared).'; }
+      if (sub === 'delete') { telemetry.deleteAll(); return 'Telemetry: all local events deleted.'; }
+      if (sub === 'export') { return telemetry.export(); }
+      if (sub === 'details') {
+        return [
+          'Telemetry records anonymous counters only. Allowed kinds:',
+          '  feature_used   — enum counter (session_started, undo_invoked, …)',
+          '  tool_called    — counter by category (filesystem_read, git, web, …)',
+          '  error_occurred — counter by class (llm_timeout, permission_denied, …)',
+          'NEVER recorded: prompts, responses, tool args, file paths, URLs, API keys.',
+          'Storage: .kondi-chat/telemetry.json (local only). No network in v1.',
+        ].join('\n');
+      }
+      return telemetry.format();
+    }
+    case '/rate-limits': return rateLimiter.format();
+    case '/sessions': return sessionStore.format(workingDir);
+    case '/resume': {
+      if (!parts[1]) return 'Usage: /resume <session-id>';
+      const p = sessionStore.load(parts[1]);
+      if (!p) return `Session not found: ${parts[1]}`;
+      return `To resume ${p.session.id.slice(0, 8)}, restart with:\n  kondi-chat --resume ${p.session.id}`;
+    }
+    case '/checkpoints': return checkpointManager.format();
+    case '/undo': {
+      const arg = parts[1];
+      try {
+        if (!arg) {
+          const r = checkpointManager.restore(-1);
+          return `Reverted ${r.restored.id} (turn ${r.restored.turnNumber}): ${r.restored.summary}\n  files: ${r.filesRestored.length}${r.errors.length ? `  errors: ${r.errors.join('; ')}` : ''}`;
+        }
+        if (/^\d+$/.test(arg)) {
+          const n = parseInt(arg, 10);
+          const r = checkpointManager.restore(-n);
+          return `Reverted ${n} checkpoint(s) to ${r.restored.id} (turn ${r.restored.turnNumber}). Files: ${r.filesRestored.length}`;
+        }
+        const cp = checkpointManager.get(arg);
+        if (!cp) return `Unknown checkpoint: ${arg}. Run /checkpoints to list.`;
+        const r = checkpointManager.restore(arg);
+        return `Restored ${r.restored.id}. Files: ${r.filesRestored.join(', ') || '(none)'}`;
+      } catch (e) {
+        return `Undo failed: ${(e as Error).message}`;
+      }
+    }
+    case '/mcp': {
+      const sub = parts[1];
+      if (!sub) return mcpClient.format();
+      if (sub === 'add' && parts[2]) {
+        // /mcp add <name> <command> [args...]
+        // /mcp add <name> http <url>
+        const name = parts[2];
+        if (parts[3] === 'http' || parts[3] === 'https') {
+          const url = parts[4];
+          if (!url) return 'Usage: /mcp add <name> http <url>';
+          saveMcpServer(workingDir, name, { type: 'http', url } as any);
+          await mcpClient.connect(name, { type: 'http', url, scope: 'project' } as any);
+          return `Added HTTP MCP server: ${name} → ${url}`;
+        }
+        const command = parts[3];
+        const args = parts.slice(4);
+        if (!command) return 'Usage: /mcp add <name> <command> [args...]';
+        saveMcpServer(workingDir, name, { command, args });
+        await mcpClient.connect(name, { command, args, scope: 'project' } as any);
+        return `Added stdio MCP server: ${name} → ${command} ${args.join(' ')}`;
+      }
+      if (sub === 'remove' && parts[2]) {
+        const name = parts[2];
+        await mcpClient.disconnect(name);
+        const removed = removeMcpServer(workingDir, name) || removeMcpServer(workingDir, name, 'user');
+        return removed ? `Removed MCP server: ${name}` : `Server not found in config: ${name}`;
+      }
+      if (sub === 'reconnect') {
+        const name = parts[2];
+        if (name) {
+          const server = mcpClient.getServer(name);
+          if (!server) return `Unknown server: ${name}`;
+          await mcpClient.disconnect(name);
+          await mcpClient.connect(name, server.config);
+          return `Reconnected: ${name}`;
+        }
+        // Reconnect all
+        const servers = mcpClient.getServers();
+        for (const s of servers) {
+          await mcpClient.disconnect(s.name);
+          await mcpClient.connect(s.name, s.config);
+        }
+        return `Reconnected ${servers.length} server(s)`;
+      }
+      return 'Usage: /mcp [add <name> <command> [args...] | remove <name> | reconnect [name]]';
+    }
+    case '/tools': {
+      const all = toolManager.getTools();
+      const summary = toolManager.getSummary();
+      const lines = [
+        '═══ Slash Commands ═══',
+        '  /mode [name]         Show or set budget profile',
+        '  /mode-details [name] Full config for a profile',
+        '  /use <alias>         Pin to a model (/use auto to unpin)',
+        '  /models              List models and aliases',
+        '  /health              Check model availability',
+        '  /cost                Session cost breakdown by model',
+        '  /analytics [days]    Cross-session cost by model and day',
+        '  /routing             Router stats and tier distribution',
+        '  /tools               This list',
+        '  /consultants         List domain-expert consultants',
+        '  /council             Multi-model deliberation',
+        '  /tasks               List task cards',
+        '  /loop <goal>         Autonomous agent loop',
+        '  /sessions            List recent sessions',
+        '  /checkpoints         List checkpoints',
+        '  /undo [N]            Revert to checkpoint',
+        '  /attach <path>       Queue image for next message',
+        '  /mcp                 List MCP servers and tools',
+        '  /rate-limits         Per-provider RPM/TPM usage',
+        '  /help [topic]        Detailed help on any topic',
+        '  /quit                Exit',
+        '',
+        `═══ Agent Tools (${all.length}: ${summary.builtIn} built-in, ${summary.mcp} MCP) ═══`,
+        ...all.map(t => `  ${t.name.padEnd(22)} ${(t.description || '').slice(0, 55)}`),
+      ];
+      return lines.join('\n');
+    }
+    case '/help': return formatHelp(parts[1]);
+    default: return `Unknown: ${cmd}. Try /help`;
+  }
+}

package/src/cli/help.ts

@@ -0,0 +1,182 @@
+/**
+ * In-app help. Hand-authored topic database keyed by slash command or feature
+ * name. `/help` lists topics; `/help <topic>` shows a single entry; if the
+ * topic is unknown, the closest-match suggestion is returned.
+ */
+
+export interface HelpTopic {
+  syntax?: string;
+  description: string;
+  examples?: string[];
+  related?: string[];
+}
+
+const TOPICS: Record<string, HelpTopic> = {
+  '/mode': {
+    syntax: '/mode [quality|balanced|cheap|zai|<custom>]',
+    description: 'Show or set the active budget profile. Profiles control loop caps, cost caps, model priorities, and optional provider allow-lists. Persisted across restarts via .kondi-chat/config.json.',
+    examples: ['/mode', '/mode quality', '/mode zai'],
+    related: ['/use', '/cost', '/routing'],
+  },
+  '/use': {
+    syntax: '/use <alias> | /use auto',
+    description: 'Pin the agent to a specific model for every subsequent turn, or return to auto-routing. Aliases resolve on an unambiguous prefix (`/use gemi` → gemini). Ambiguous prefixes list the candidates. The bottom-of-viewport model indicator updates immediately when this runs — no turn required.',
+    examples: ['/use claude', '/use gemini', '/use glm', '/use auto'],
+    related: ['/models', '/mode', 'mentions'],
+  },
+  '/models': {
+    description: 'List all registered models with their aliases and health status.',
+    related: ['/use', '/health'],
+  },
+  '/status': {
+    description: 'Show session cost, token usage, and context window utilization.',
+    related: ['/cost', '/analytics'],
+  },
+  '/cost': {
+    description: 'Breakdown of LLM cost by model and phase for the current session.',
+    related: ['/status', '/analytics'],
+  },
+  '/attach': {
+    syntax: '/attach <path>',
+    description: 'Queue an image (PNG/JPG/GIF/WebP, ≤10MB) to send with the next message. Up to 5 images per turn.',
+    examples: ['/attach ./screenshot.png'],
+    related: [],
+  },
+  '/sessions': {
+    description: 'List recent sessions (id, message count, cost).',
+    related: ['/resume'],
+  },
+  '/resume': {
+    syntax: '/resume <id>',
+    description: 'Print the exact restart command to resume a session. v1 does not hot-swap; relaunch with --resume <id>.',
+    related: ['/sessions'],
+  },
+  '/checkpoints': {
+    description: 'List checkpoints created before mutating tool calls.',
+    related: ['/undo'],
+  },
+  '/undo': {
+    syntax: '/undo [N | <id>]',
+    description: 'Revert to a previous checkpoint. No argument restores the latest; N reverts that many checkpoints back; an id restores a specific one.',
+    examples: ['/undo', '/undo 2', '/undo cp-1712438400-abcd'],
+    related: ['/checkpoints'],
+  },
+  '/routing': {
+    description: 'Routing dashboard: tier distribution (intent/nn/rules), per-model success rates and cost, model×tier matrix, quality scores, NN training readiness, and by-phase breakdown. The intent tier is the primary — if it is dominant you know the router is picking models with full model descriptions instead of falling back to hardcoded rules.',
+    related: ['/models', '/cost', '/analytics'],
+  },
+  '/rate-limits': {
+    description: 'Show per-provider RPM/TPM usage and any queued requests.',
+  },
+  '/telemetry': {
+    syntax: '/telemetry [enable|disable|status|details|export|delete]',
+    description: 'Control opt-in local telemetry. Nothing is sent to any server in v1.',
+  },
+  '/consultants': {
+    description:
+      'List the domain-expert consultants configured for this project. Each consultant is a (model, system-prompt) pair stored in .kondi-chat/consultants.json. The agent can call them via the `consult` tool when it decides a problem has a clear domain angle — aerospace safety, security, database, etc. Edit the JSON to add, remove, or tune experts without touching code.',
+    related: ['consultants', '/models'],
+  },
+  'consultants': {
+    description:
+      'Consultants are domain-expert personas the agent calls on demand via the `consult` tool. Each is a triple of (role id, provider/model, system prompt) stored in .kondi-chat/consultants.json. Consultants are pure text-in/text-out — they cannot read files, run commands, or see the main conversation. They exist to give the agent a specialized opinion without setting up a full sub-agent. Defaults include aerospace-engineer, security-auditor, and database-architect. To add one, append an entry to the JSON: {"role": "ml-researcher", "name": "...", "description": "...", "provider": "anthropic", "model": "claude-sonnet-4-5-20250929", "system": "You are a machine-learning researcher..."}. Consultations are logged to the ledger as phase: consult so /routing and /cost can attribute the spend.',
+    related: ['/consultants', '/loop'],
+  },
+  '/loop': {
+    syntax: '/loop <goal>',
+    description: 'Run an autonomous agent loop toward a stated goal. Each iteration the model may call tools, produce partial output, and decide whether the goal is met. If the model returns final text without calling any tool but has not emitted DONE or STUCK, the backend synthesizes a "continue" follow-up and keeps iterating — LoopGuard still enforces the profile\'s iteration and cost caps. The model signals termination with DONE (success) or STUCK: <reason> (blocked) on its own line. The `/loop` command streams tool_call and activity events in real time like a normal submit, not a silent command.',
+    examples: ['/loop fix all the failing tests and commit when green', '/loop find every TODO in src/ and resolve them'],
+    related: ['/mode', 'type-ahead', '/undo'],
+  },
+  '/council': {
+    syntax: '/council [list | run <profile> <brief>]',
+    description: 'Run multi-model deliberation via the council tool. Councils are expensive (fan out across frontier models for multiple rounds) and blocking (synchronous subprocess) — the agent CANNOT invoke them automatically; only explicit /council runs them. Not available from inside the agent toolset.',
+  },
+  '/help': {
+    syntax: '/help [topic]',
+    description: 'Show general help or a specific topic.',
+    examples: ['/help', '/help /undo', '/help memory'],
+  },
+  // Feature topics
+  'memory': {
+    description: 'KONDI.md and AGENTS.md files provide persistent project conventions injected into the system prompt. AGENTS.md is an open cross-tool convention (Claude Code, Cursor, Copilot, Aider, Zed, etc.); KONDI.md is kondi-chat-specific. Both are searched at three levels: user (~/.kondi-chat/), project (<workingDir>/), and nearest-ancestor subdirectory. If both exist at the same level, both are loaded. Agent writes (update_memory tool) go to KONDI.md only — AGENTS.md is hand-authored.',
+    related: ['/help update_memory'],
+  },
+  'permissions': {
+    description: 'Tools run through a permission gate (auto-approve/confirm/always-confirm). Dangerous shell commands (rm -rf, sudo, git push --force) are always-confirm regardless of config.',
+  },
+  'checkpoints': {
+    description: 'Every turn that mutates files snapshots state first. Git repos use git stash; non-git dirs copy files. /undo restores the latest.',
+    related: ['/undo', '/checkpoints'],
+  },
+  'hooks': {
+    description: 'Shell or tool-call hooks run before or after agent tools. Configured in .kondi-chat/hooks.json. See docs/hooks.md.',
+  },
+  'non-interactive': {
+    description: 'Flags: --prompt "<text>", --pipe, --json, --sessions. Exit codes: 0 ok, 1 error, 2 max-iter, 3 max-cost, 5 permission-denied.',
+  },
+  'shortcuts': {
+    description: 'TUI keybindings. Ctrl+C quit · Enter send OR queue if a turn is running (see `type-ahead`) · Ctrl+N newline in input · Ctrl+O toggle tool-call detail view · Ctrl+T toggle stats detail view · Ctrl+R toggle reasoning detail view (chain-of-thought for reasoning models) · Ctrl+Y copy last assistant response to clipboard · Ctrl+A toggle activity log · Left/Right/Home/End move input cursor · Up/Down recall input history · Esc cascades: close detail view → clear input → clear queued submits. Permission dialogs: y/Enter approve · n/Esc deny · a approve this exact command for session · t yolo-approve everything for this turn.',
+    related: ['permissions', 'type-ahead', 'mentions'],
+  },
+  'type-ahead': {
+    description: 'Enter during an in-flight turn queues the new message instead of dispatching it. A dim "⧗ queued: …" line drops into scrollback and the status bar shows "⧗ queued: N (Esc to clear)". When the current turn finishes, the oldest queued entry fires automatically. Guarantees at most one handleSubmit is ever in flight on the backend, so concurrent turns cannot race over session state, tool attribution, or permissions. Esc on an empty input clears the queue.',
+    related: ['shortcuts'],
+  },
+  'mentions': {
+    description: '@<alias> at the start of a message forces one specific model for that single turn without changing the router state. Typing `@` alone triggers an autocomplete list of every enabled alias, filterable as you keep typing. Aliases resolve on unambiguous prefix (`@gemi` → @gemini). Ambiguous prefixes report candidates. For a persistent pin use /use <alias> instead.',
+    related: ['/use', '/models', 'shortcuts'],
+  },
+  'zai': {
+    description: 'Z.AI (GLM) is supported as an OpenAI-compatible provider. Set ZAI_API_KEY in .env. The Coding Plan endpoint (https://api.z.ai/api/coding/paas/v4) is used — NOT the pay-as-you-go /api/paas/v4. Use /mode zai to route everything through the tiered zai profile: glm-5.1 (reasoning) for planning/review, glm-4.6 for execution/coding, glm-4.5-flash (free!) for compression and summarization. Profile restricts routing via allowedProviders so nothing leaks to other providers.',
+    related: ['/mode', 'reasoning-models', 'compression'],
+  },
+  'reasoning-models': {
+    description: 'Reasoning models (GLM-5.x, OpenAI o-series, DeepSeek-R1, Anthropic extended-thinking) emit hidden chain-of-thought that is billed as OUTPUT tokens at full rate but not shown inline. A single 20-char reply can cost 500+ output tokens of unseen reasoning — the "80× reasoning tax." Ctrl+R opens the reasoning panel so you can see what the model was actually thinking. Keep reasoning models off the hot path if quota matters; use them only where the depth pays for itself (planning, code review). Cache discount still applies to cached input tokens.',
+    related: ['shortcuts', 'zai'],
+  },
+  'compression': {
+    description: 'Context is capped at the active profile contextBudget. Inside a single agent-loop turn, old tool_result payloads are stubbed in place across three escalation passes (keep 2 turns at 300 chars, keep 1 turn at 100 chars, keep 1 turn at 50 chars) — no LLM calls, just string rewriting. Between turns, ContextManager.compact() summarizes older messages via the active profile compression model (glm-4.5-flash in zai mode, claude-haiku-4-5 otherwise) and writes a COMPACT_BOUNDARY marker. Compaction triggers at contextBudget × 1.2, not at the model context window.',
+    related: ['/mode', 'zai'],
+  },
+  'intent-router': {
+    description: 'The LLM-based intent router is the primary model-selection tier. It reads every model declared in the profile (via rolePinning values, not all enabled models), sees what happened in prior pipeline phases ("Gemini just wrote the code, tests passed"), understands what each phase needs (dispatch = planning, execute = coding, reflect = review), and picks the best model for the current step. When comparable models are available (e.g. Opus and GPT-5.4 for planning), the classifier weighs capabilities against cost per turn. Profile pins serve as fallback if the intent tier fails — the router gets first shot at an intelligent pick. Classifier LLM is profile-scoped (zai uses glm-4.5-flash — free). /routing shows the per-tier distribution.',
+    related: ['/routing', '/mode'],
+  },
+  'caching': {
+    description: 'Prompt cache hits are tracked on both Anthropic (cache_read_input_tokens) and OpenAI-compatible (prompt_tokens_details.cached_tokens) responses. Cached tokens are recorded separately on the ledger entry and discounted in cost estimates (10% of input rate on Anthropic, 50% on OpenAI/Z.AI). See cachedInputTokens in the ledger and /routing for live totals.',
+    related: ['/routing', '/cost'],
+  },
+};
+
+export function formatHelp(topic?: string): string {
+  if (!topic) {
+    const keys = Object.keys(TOPICS).sort();
+    return [
+      'Topics (use /help <topic> for details):',
+      ...keys.map(k => `  ${k}  —  ${TOPICS[k].description.slice(0, 60)}`),
+    ].join('\n');
+  }
+  const entry = TOPICS[topic] || TOPICS[topic.startsWith('/') ? topic : `/${topic}`];
+  if (!entry) {
+    const suggestion = closestMatch(topic, Object.keys(TOPICS));
+    return suggestion ? `No help for ${topic}. Did you mean ${suggestion}?` : `No help for ${topic}.`;
+  }
+  const parts: string[] = [];
+  if (entry.syntax) parts.push(`Syntax:  ${entry.syntax}`);
+  parts.push(entry.description);
+  if (entry.examples?.length) parts.push('\nExamples:\n  ' + entry.examples.join('\n  '));
+  if (entry.related?.length) parts.push(`\nRelated: ${entry.related.join(', ')}`);
+  return parts.join('\n');
+}
+
+function closestMatch(query: string, candidates: string[]): string | null {
+  let best: { k: string; score: number } | null = null;
+  for (const c of candidates) {
+    if (c.includes(query) || query.includes(c)) {
+      const score = Math.abs(c.length - query.length);
+      if (!best || score < best.score) best = { k: c, score };
+    }
+  }
+  return best?.k || null;
+}