archymedes-cli 2.2.0 → 2.5.0

package/dist/{archymedes-npcrm9a0.mjs → archymedes-d3azqkay.mjs}

@@ -1,4 +1,20 @@
-// packages/archymedes-cli/src/viewport.ts
+import {
+  GUTTER,
+  clip,
+  note,
+  panel,
+  rule
+} from "./archymedes-bmtdqqwt.mjs";
+import {
+  BOLD,
+  DIM,
+  UNICODE_GLYPHS,
+  paint,
+  paintAll,
+  visibleWidth
+} from "./archymedes-130jt0wr.mjs";
+
+// packages/archymedes-cli/src/terminal/viewport.ts
 function newViewport(lines, height) {
   return clamp({ lines, height: Math.max(1, Math.floor(height)), top: 0 });
 }
@@ -40,12 +56,18 @@ function applyViewport(state, action) {
 function visibleLines(state) {
   return state.lines.slice(state.top, state.top + state.height);
 }
+function atTop(state) {
+  return state.top <= 0;
+}
+function atBottom(state) {
+  return state.top >= maxTop(state);
+}
 function scrollFraction(state) {
   const furthest = maxTop(state);
   return furthest === 0 ? 1 : state.top / furthest;
 }
 
-// packages/archymedes-cli/src/i18n.ts
+// packages/archymedes-cli/src/platform/i18n.ts
 var CONTROL_LANGUAGES = {
   en: "English",
   zh: "中文 (Mandarin)",
@@ -532,7 +554,7 @@ function t(language, key) {
   return MESSAGES[key][language] ?? MESSAGES[key].en;
 }
 
-// packages/archymedes-cli/src/commands.ts
+// packages/archymedes-cli/src/catalog/commands.ts
 function defineCommands(table) {
   return Object.entries(table).map(([name, command]) => ({ name, ...command }));
 }
@@ -555,19 +577,22 @@ var COMMANDS2 = defineCommands({
   "/route": { args: "[all|summary|plan]", description: "The hosted exchange's routing decision: chosen model, alternatives, policy, est vs actual cost. `plan` forecasts the next turn before spending" },
   "/clear": { description: "Start a fresh thread" },
   "/memory": { args: "[add|replace|recall|forget]", description: "Bounded, relevant memory across sessions — # <fact> remembers for this project" },
-  "/history": { args: "[<id> | search <text> | resume | status]", description: "Browse, search or pick up durable conversation history" },
+  "/history": { args: "[list | <id> | search <text> | delete <id>|--all | status]", description: "Go back to an earlier conversation — opens a picker (Del deletes one); list prints them, search finds one" },
+  "/resume": { args: "[<id> | latest]", description: "Continue an earlier conversation in this folder (picker, or straight to one)" },
   "/export": { args: "[markdown|json|support]", description: "Write a redacted session transcript or compact support artifact" },
   "/expand": { args: "[N | all | list]", description: "Show a folded block — written code, a test run, a long result — in full" },
   "/slow": { args: "[on|strict|off]", description: "Spend at a slower pace: fewer model rounds, smaller replies, a pause between turns" },
   "/workspace": { description: "Open the control panel: every tab and watched job, live, on one screen" },
   "/watch": { args: "[id|show <id>|stop <id>]", description: "Follow a background job's output without giving up the prompt" },
-  "/theme": { args: "[name|list|where]", description: "Change the colours — blueprint, parchment, chalkboard, high-contrast, rainbow, or a .tss file of your own" },
+  "/theme": { args: "[name|list|where]", description: "Pick the colours from a list, or name one — blueprint, parchment, chalkboard, high-contrast, rainbow, or a .tss file of your own" },
   "/tab": { args: "[new|next|prev|close|rename|N]", description: "Several pieces of work, one at a time — only the tab in front runs (/detach for parallel)" },
   "/pull": { args: "[dir]", description: "Copy sandbox files here" },
   "/where": { description: "Show the current workspace" },
+  "/diagnostics": { args: "[glob]", description: "Language server diagnostics for the workspace — errors, warnings, info from installed language servers" },
   "/tools": { description: "What the agent can call, and which skills, plugins, MCP servers or hooks a project added" },
   "/providers": { description: "Which model providers are configured" },
-  "/settings": { description: "Configure API keys, URLs, models and voice input" },
+  "/settings": { description: "Theme, code colours, simple mode, startup, free-mode savings, keys and models" },
+  "/upgrade": { description: "Use your own OpenRouter API key instead of the shared free gateway" },
   "/update": { args: "[auto|check|off]", description: "Update Archymedes now, or choose whether it updates itself" },
   "/voice": { args: "[audio-file]", description: "Record or transcribe an editable voice prompt" },
   "/wander": { args: "[topic|random|daily|weekly]", description: "Run a bounded research lab and grade what it finds" },
@@ -577,15 +602,518 @@ var COMMANDS2 = defineCommands({
   "/cost": { description: "Token and cost breakdown for this session" },
   "/balance": { args: "[amount] [currency] | clear", description: "Your Archymedes credit balance on the exchange, or a locally tracked spend limit on a direct provider" },
   "/scan": { args: "[glob]", description: "Deterministic secret scan of the workspace, worst severity first — no model turn needed" },
-  "/sessions": { description: "List sessions in this project (an alias for /history)" },
+  "/sessions": { description: "Pick an earlier conversation in this project (an alias for /history)" },
   "/palette": { description: "Search every command by name or by what it does" },
   "/keys": { description: "Every shortcut in full, plus line-editing keys and which chords this terminal may not deliver — /help lists them inline, next to each command" },
   "/guide": { args: "[topic|search <text>|all]", description: "The user guide, as a screen you can browse — or print one topic with /guide <topic>" },
   "/files": { description: "Browse the project tree — expand folders, preview a file, pick one to @mention" },
   "/edit": { args: "<path>", description: "Open a file in the built-in editor — through the workspace, so it works in a sandbox too" },
-  "/cat": { args: "<path>", description: "Print a file into the transcript — markdown rendered like a document, code numbered and highlighted" },
+  "/cat": { args: "<path>", description: "Print a file into the transcript — markdown rendered like a document, code numbered and highlighted, PNG images drawn" },
+  "/find": { args: "<text> | next | prev | off", description: "Search this tab's transcript in the fixed workspace; repeat /find for the next match" },
+  "/pager": { description: "Open this tab's transcript in $PAGER (less -R) to search, select and save it" },
   "/help": { args: "[all|work|review|steer|parallel|learn|setup]", description: "Commands grouped by purpose" },
   "/exit": { description: "Leave" }
 });
+function renderCommandHelp(language = "en", shortcuts = new Map, options = {}) {
+  const width = Math.max(...COMMANDS2.map((command) => command.name.length + (command.args ? command.args.length + 1 : 0)));
+  const shortcutWidth = Math.max(0, ...[...shortcuts.values()].map((label) => label.length));
+  const mark = options.mark ?? (() => "  ");
+  return COMMANDS2.map((command) => {
+    const head = command.args ? `${command.name} ${command.args}` : command.name;
+    const shortcut = shortcuts.get(command.name) ?? "";
+    const shortcutColumn = shortcutWidth > 0 ? shortcut.padEnd(shortcutWidth + 2) : "";
+    return `${mark(command.name)}${head.padEnd(width + 2)}${shortcutColumn}${commandDescription(language, command.name, command.description)}`;
+  }).join(`
+`);
+}
+function suggestionsFor(line, models = []) {
+  const model = /^\/models?\s+(\S*)$/.exec(line);
+  if (model) {
+    const fragment = model[1].toLowerCase();
+    const matched = models.filter((id) => id.toLowerCase().includes(fragment));
+    return matched.length === 1 && matched[0].toLowerCase() === fragment ? [] : matched.map((id) => ({ command: id, description: "" }));
+  }
+  if (!/^\/\S*$/.test(line))
+    return [];
+  const matches = COMMANDS2.filter((command) => command.name.startsWith(line));
+  if (matches.length === 1 && matches[0].name === line)
+    return [];
+  return matches.map((command) => ({ command: command.name, ...command.args ? { args: command.args } : {}, description: command.description }));
+}
+function inlineCompletion(line, models = []) {
+  const none = { suffix: "", alternatives: 0 };
+  const model = /^(\/models?\s+)(\S+)$/.exec(line);
+  if (model) {
+    const fragment = model[2].toLowerCase();
+    const matched2 = models.filter((id) => id.toLowerCase().startsWith(fragment)).sort((a, b) => a.length - b.length);
+    if (matched2.length === 0 || matched2[0].length === fragment.length)
+      return none;
+    return { suffix: matched2[0].slice(model[2].length), alternatives: matched2.length - 1 };
+  }
+  if (!/^\/\S*$/.test(line) || line === "/")
+    return none;
+  const matched = COMMANDS2.map((command) => command.name).filter((name) => name.startsWith(line)).sort((left, right) => left.length - right.length);
+  if (matched.length === 0 || matched[0] === line)
+    return none;
+  return { suffix: matched[0].slice(line.length), alternatives: matched.length - 1 };
+}
+function isKnownCommand(name) {
+  return COMMANDS2.some((command) => command.name === name);
+}
+var MODE_NAMES = ["plan", "build", "auto", "defender"];
+function isModeName(value) {
+  return MODE_NAMES.includes(value);
+}
+function parseModeCommand(input) {
+  const bareModeCommand = input.startsWith("/") ? input.slice(1) : "";
+  if (isModeName(bareModeCommand))
+    return { type: "switch", mode: bareModeCommand };
+  const match = /^\/mode(?:\s+(\S+))?$/.exec(input);
+  if (!match)
+    return null;
+  if (!match[1])
+    return { type: "show" };
+  return isModeName(match[1]) ? { type: "switch", mode: match[1] } : { type: "invalid" };
+}
+function editDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_unused, index) => index);
+  for (let row = 1;row <= left.length; row += 1) {
+    let diagonal = previous[0];
+    previous[0] = row;
+    for (let column = 1;column <= right.length; column += 1) {
+      const candidate = Math.min(previous[column] + 1, previous[column - 1] + 1, diagonal + (left[row - 1] === right[column - 1] ? 0 : 1));
+      diagonal = previous[column];
+      previous[column] = candidate;
+    }
+  }
+  return previous[right.length];
+}
+function suggestCommand(name) {
+  const ranked = COMMANDS2.map((command) => ({ name: command.name, distance: editDistance(name, command.name) })).sort((left, right) => left.distance - right.distance);
+  const best = ranked[0];
+  return best && best.distance <= 2 ? best.name : undefined;
+}
+var KEYBOARD_SHORTCUTS = [
+  ["menu-move", "↑ / ↓", "Move through any menu — settings, models, the palette"],
+  ["menu-number", "1-9", "Jump straight to a numbered row in a menu"],
+  ["menu-take", "Enter / Esc", "Take the highlighted row / leave the menu"],
+  ["complete-command", "Tab", "Complete a slash command"],
+  ["complete-path", "@ + path", "Complete a project file mention"],
+  ["history", "Up / Down", "Search persistent prompt history"],
+  ["line-ends", "Home / End", "Move to the start / end of the input"],
+  ["delete", "Alt-Backspace / Ctrl-U", "Delete the previous word / whole input"],
+  ["clear", "Ctrl-L", "Clear and redraw the terminal"],
+  ["interrupt", "Ctrl-C", "Interrupt the current turn"],
+  ["voice", "/voice", "Record a prompt from the microphone"],
+  ["expand", "Ctrl-O", "Unfold the most recent folded block"],
+  ["memory", "# fact", "Remember a fact for every future session in this project"]
+];
+function renderKeyboardShortcuts(language = "en") {
+  const width = Math.max(...KEYBOARD_SHORTCUTS.map(([, key]) => key.length));
+  return KEYBOARD_SHORTCUTS.map(([id, key, description]) => `  ${key.padEnd(width + 2)}${keyboardDescription(language, id, description)}`).join(`
+`);
+}
+
+// packages/archymedes-cli/src/render/guide.ts
+var GUIDE_TOPICS = [
+  {
+    id: "start",
+    title: "Getting started",
+    summary: "What Archymedes is, and the first thing to type.",
+    body: [
+      "Archymedes is a coding agent that works in a scrolling terminal transcript. You type what you want in plain language; it reads files, runs commands and edits code, and shows you what it did as it goes.",
+      "Everything it prints stays in your terminal's scrollback, so you can scroll up, select text and pipe a session to a file the way you would with any other command.",
+      "Type a request and press Enter. Slash commands do everything else — press / to see them, or open the searchable list.",
+      "One rule everywhere: Esc takes you back. Out of a menu, the guide, the file browser, the pager or the editor, Esc returns you to the chat prompt. A lone ? on the prompt shows the short help.",
+      "Archymedes starts in simple mode — one line of help and nothing else to learn. Turn ARCHYMEDES_SIMPLE off in /settings for the full banner, starter ideas and the grouped /help."
+    ],
+    examples: [
+      { input: "fix the failing test in cart.ts", effect: "an ordinary request; Archymedes reads, edits and runs the tests" },
+      { input: "?", effect: "the short help: the handful of commands worth knowing first" },
+      { input: "/help all", effect: "every command, with one line each" },
+      { input: "/palette", effect: "search commands by name or by what they do" },
+      { input: "/guide", effect: "open this guide as a screen — arrows to move, / to search, Esc to come back" },
+      { input: "/guide tabs", effect: "print one topic into the transcript, to keep or to copy" },
+      { input: "/exit", effect: "leave; the session is saved and can be resumed" }
+    ],
+    covers: ["/help", "/palette", "/exit", "/keys", "/guide"]
+  },
+  {
+    id: "modes",
+    title: "Permission modes",
+    summary: "How much Archymedes may do without asking.",
+    body: [
+      "Four modes, and you can change them at any time. Plan reads and reasons but cannot write or run commands. Build is the default: edits are proposed and you approve them. Auto applies ordinary workspace edits without asking, while anything sensitive or reaching outside the workspace still stops for you. Defender turns Archymedes into a security reviewer — full tool access to actually scan and fix, but never auto-approved, the same posture as Build.",
+      "Defender also looks outward: when web search is configured it checks current advisories against what the project actually depends on, remembers durable findings in project memory so the next review builds on this one, and closes out with concrete, costed remediation resources fitted to how the project actually hosts and deploys — not a generic checklist.",
+      "/scan runs the deterministic half of defender's own secrets playbook directly — no model turn, no mode switch needed. It is the same pattern-matching scan_secrets uses, worst severity first: a private key or a live cloud credential ahead of a merely credential-shaped variable name.",
+      "The mode is per tab, so one piece of work can be on a short leash while another runs freely."
+    ],
+    examples: [
+      { input: "/plan", effect: "read-only: no writes, no commands" },
+      { input: "/build", effect: "edits ask first (the default)" },
+      { input: "/auto", effect: "ordinary edits apply; sensitive actions still ask" },
+      { input: "/defender", effect: "security review — find and fix real issues; every change still asks" },
+      { input: "/mode", effect: "show which mode you are in" },
+      { input: "/scan", effect: "pattern-based secret scan, worst severity first, no model call" },
+      { input: "/scan src/**", effect: "same scan, limited to files matching the glob" }
+    ],
+    covers: ["/mode", "/plan", "/build", "/auto", "/defender", "/scan"]
+  },
+  {
+    id: "tabs",
+    title: "Tabs: several pieces of work, one at a time",
+    summary: "Each tab keeps its own conversation, model, cost and machine — the tab in front is the one that runs.",
+    body: [
+      "A tab is a separate piece of work with its own conversation, its own running total, its own mode — and its own model and location. One tab can be on a large model against your checkout while another runs a cheaper or open model inside a throwaway remote sandbox.",
+      "Only the tab in front runs. Switching away does not leave a turn working in the background — it pauses that piece of work and hands the terminal to another one. That is a deliberate limit rather than a missing feature: a terminal transcript has one bottom, and two agents printing into it at once would interleave into something neither of them said. (Archymedes's desktop window is different — it has a transcript per tab, so its tabs really do run at the same time.)",
+      "When you want work running while you do something else, that is what /detach and /jobs are for: a detached job keeps going after you close the terminal, and /watch streams it into the session without taking the prompt.",
+      "Tabs keep what they printed. Leave one and come back and the last lines reappear, so you can pick up where you were instead of facing a bare prompt.",
+      "The strip above the prompt shows every tab with its model and a mark for where it runs. Closing a tab that started its own sandbox stops that sandbox — and only that one."
+    ],
+    examples: [
+      { input: "/tab new review", effect: "a second tab, same model, same machine" },
+      { input: "/tab new fast --model claude-haiku-4-5-20251001", effect: "a tab on a different model" },
+      { input: "/tab new risky --sandbox e2b", effect: "a tab whose edits land in a remote sandbox, not on your disk" },
+      { input: "/tab 2", effect: "switch to tab 2 and replay where you left off" },
+      { input: "/tab close 2", effect: "close it, stopping its sandbox if it started one" },
+      { input: "/detach run the full test suite", effect: "work that runs while you use another tab" }
+    ],
+    covers: ["/tab"]
+  },
+  {
+    id: "models",
+    title: "Models and providers",
+    summary: "Choosing what runs, and what it costs.",
+    body: [
+      "Archymedes talks to several providers. The picker lists what you can use, with prices, and offers to save a key for anything you cannot use yet. Switching model keeps the conversation — you are changing who answers, not starting over.",
+      "The list is the union of what this build knows the prices of and what each provider says it has today, so a model released last week is still offerable — it is simply shown without a price rather than hidden. The live half is cached for six hours; /models refresh asks again.",
+      "A model switch applies to the tab you are in. Opening a tab with --model is how you compare two models on the same problem.",
+      "Type in /model to narrow a long list; Esc clears the search before it leaves.",
+      "archymedes --free needs no key: it runs zero-priced tool models (openrouter/free or an exact model:free ID) through the Archymedes free gateway, which holds the shared OpenRouter key server-side and enforces a daily allowance — 100,000 tokens and 300 requests per UTC day, 20 a minute; tokens are the budget that usually runs out first. Until that gateway is live, free mode uses your own free OpenRouter key (50 free-model requests a day, 1,000 once the account has bought 10 credits). Every request carries a zero price cap and never falls back to a paid provider. When the allowance runs out, it says so and when it resets.",
+      "Type /upgrade (or /upgrades) to use your own OpenRouter API key instead: free-mode limits stop applying and requests go straight to OpenRouter. With your own key, --free talks to OpenRouter directly.",
+      "For any other OpenRouter model — paid or free — use --provider openrouter with the same key (e.g. --provider openrouter --model openrouter/auto). That path has no price cap and needs no Archymedes Cloud account.",
+      "Paste a TYPESAFE_API_KEY in archymedes settings for a Jev second opinion: it annotates approvals with a tool-fit reading and prints a post-turn verdict with probabilities. Advisory only — it never approves, denies, or blocks."
+    ],
+    examples: [
+      { input: "/models", effect: "the list, with prices" },
+      { input: "/models refresh", effect: "ask every provider what it has right now" },
+      { input: "/model", effect: "the picker" },
+      { input: "/model claude-sonnet-5", effect: "switch straight to one, keeping the transcript" },
+      { input: "/fallback openai:gpt-5.4-mini", effect: "retry transient provider failures on this model, only before any output or tool action" },
+      { input: "/providers", effect: "which providers are configured" }
+    ],
+    covers: ["/models", "/model", "/fallback", "/providers", "/settings", "/upgrade"]
+  },
+  {
+    id: "where",
+    title: "Where the work happens",
+    summary: "This machine, a container, or a remote sandbox.",
+    body: [
+      "By default Archymedes edits the directory you started it in. Started with --sandbox e2b it works inside a throwaway remote machine instead, and --sandbox docker uses a local container. Files written there never touch your disk unless you ask for them.",
+      "Sandboxes are per tab, so 'try this somewhere I don't mind breaking' is one command rather than a second terminal.",
+      "One thing worth knowing: background jobs always run on your machine, even when the session that started them is sandboxed. Archymedes says so each time you start one."
+    ],
+    examples: [
+      { input: "archymedes --sandbox e2b", effect: "the whole session runs in a remote sandbox" },
+      { input: "/tab new spike --sandbox docker", effect: "one tab in a local container" },
+      { input: "/where", effect: "which machine the current tab is using" },
+      { input: "/pull", effect: "copy files out of a sandbox and onto your disk" }
+    ],
+    covers: ["/where", "/pull"]
+  },
+  {
+    id: "reading",
+    title: "Reading what Archymedes did",
+    summary: "Code, diffs, test results, and folded detail.",
+    body: [
+      "When Archymedes writes or edits a file it shows the code, numbered, under the tool line. When it runs tests it re-lays the output into sections with the failures pulled out. When output is long it is folded rather than truncated, and the whole of it is one command away.",
+      "The diff shows the actual patch since the last checkpoint — the lines, not a count of them.",
+      "/diagnostics asks the language servers installed on this machine what they make of the code: errors, warnings and hints, file by file. It runs no model and changes nothing. A language whose server is not installed is listed as unavailable rather than passed over in silence."
+    ],
+    examples: [
+      { input: "/diff", effect: "the real patch, file by file" },
+      { input: "/diff stat", effect: "just the summary of how much changed" },
+      { input: "/expand", effect: "unfold the last folded block" },
+      { input: "/expand list", effect: "everything that has been folded this session" },
+      { input: "/undo", effect: "revert the last turn — files, conversation, or both" },
+      { input: "/retry", effect: "repeat a failed request when nothing had run or changed" },
+      { input: "/continue", effect: "finish an interrupted task without repeating completed work" },
+      { input: "/todos", effect: "the agent's current plan" },
+      { input: "/task", effect: "the whole task at a glance: request, plan, changes, verification, blockers" },
+      { input: "/route", effect: "the hosted exchange's routing decision for the last turn — chosen model, alternatives, cost vs estimate" },
+      { input: "/diagnostics", effect: "errors and warnings from installed language servers, no model call" },
+      { input: "/diagnostics src/**", effect: "the same, limited to files matching the glob" }
+    ],
+    covers: ["/diff", "/expand", "/undo", "/retry", "/continue", "/todos", "/task", "/route", "/diagnostics"]
+  },
+  {
+    id: "memory",
+    title: "Memory",
+    summary: "Facts worth keeping between sessions.",
+    body: [
+      "Telling Archymedes the same thing every session costs you tokens and patience. A remembered fact is prepended to the conversation instead.",
+      "Memory is a plain markdown file you can open, edit, commit or delete. Project memory belongs to the repository; personal memory follows you across projects. Nothing is remembered unless you say so."
+    ],
+    examples: [
+      { input: "# we use bun, not npm", effect: "remember a fact about this project" },
+      { input: "/memory", effect: "list what is remembered" },
+      { input: "/memory add --user I prefer terse explanations", effect: "remember something about you, everywhere" },
+      { input: "/memory forget 2", effect: "drop one" }
+    ],
+    covers: ["/memory"]
+  },
+  {
+    id: "history",
+    title: "History",
+    summary: "Past conversations, searchable and resumable.",
+    body: [
+      "Every session is saved, so you can always go back to a normal conversation. /history (or /resume) opens a list of your earlier chats in this folder — arrows to choose, Enter to continue it with its whole context, Esc to stay where you are.",
+      "When you start Archymedes in a folder with a recent chat, it offers to continue it: press Enter on the empty prompt to pick it up, or just type to start fresh. ARCHYMEDES_RESUME in /settings changes that to always or never.",
+      "Chats belong to the folder they were started in: the list only ever shows this project's chats. In the picker, Del (or Ctrl+D) deletes the highlighted chat after asking — the chat you are in can't be deleted while it is open."
+    ],
+    examples: [
+      { input: "/history", effect: "pick an earlier chat and continue it" },
+      { input: "/resume latest", effect: "continue the most recent one straight away" },
+      { input: "/history list", effect: "print recent sessions, newest first" },
+      { input: "/history search failing tests", effect: "find one by what you typed" },
+      { input: "/history delete --all", effect: "delete every other chat in this folder, after a yes (Del in the picker deletes one)" },
+      { input: "archymedes --resume", effect: "start Archymedes on the picker" },
+      { input: "/export support", effect: "write a compact redacted artifact safe to attach to a support request" },
+      { input: "/clear", effect: "start a fresh thread in this tab" }
+    ],
+    covers: ["/history", "/sessions", "/resume", "/export", "/clear"]
+  },
+  {
+    id: "cost",
+    title: "Cost and pace",
+    summary: "Knowing what you are spending, and spending it slower.",
+    body: [
+      "Every turn is priced in your own currency, and the running total is always on screen. Start with --budget N to approve a cap that is then enforced rather than merely reported.",
+      "Slow mode is the other half: it limits how many model rounds and tool calls a turn may use, shortens replies, and pauses between turns. It caps the rate, not the total, and asks before an unusually expensive turn."
+    ],
+    examples: [
+      { input: "/cost", effect: "the breakdown for this session" },
+      { input: "archymedes --budget 20", effect: "approve and enforce a cap" },
+      { input: "/slow", effect: "spend at a gentler pace" },
+      { input: "/slow strict", effect: "slower still, with a pause between turns" },
+      { input: "/slow off", effect: "back to full speed" }
+    ],
+    covers: ["/cost", "/slow"]
+  },
+  {
+    id: "balance",
+    title: "Tracking a spend balance",
+    summary: "A local budget the prompt draws down as you work.",
+    body: [
+      "Archymedes has no hosted wallet. /balance sets a figure — the amount you have decided this project can spend — and after every completed turn Archymedes subtracts that turn's measured cost from it. It is an estimate you own, not a provider statement.",
+      "The balance is kept in whatever currency your session shows costs in. /balance 5000 uses that currency; /balance 50 usd or /balance 5000 inr sets it explicitly. /balance on its own shows what remains and what this session has used so far. /balance clear stops tracking.",
+      "Once a balance is being tracked, Archymedes warns calmly when it gets low, drops below the critical threshold, or falls unusually fast between turns. Before a demanding task it compares its token-based estimate with the balance and stops before contacting the model when even the conservative estimate cannot fit.",
+      "The thresholds default to small USD amounts converted to your currency; ARCHYMEDES_LOW_BALANCE and ARCHYMEDES_CRITICAL_BALANCE override them in /settings."
+    ],
+    examples: [
+      { input: "/balance 5000", effect: "track a 5,000 balance in the display currency" },
+      { input: "/balance 50 usd", effect: "track a balance in a specific currency" },
+      { input: "/balance", effect: "what remains, and what this session has used" },
+      { input: "/balance clear", effect: "stop tracking a balance" }
+    ],
+    covers: ["/balance", "/cost"]
+  },
+  {
+    id: "updating",
+    title: "Keeping Archymedes current",
+    summary: "Automatic updates by default, with explicit check-only and off controls.",
+    body: [
+      "Archymedes looks for a new version once a day, at the moment a session starts and never in the middle of one. The check is bounded at three seconds and its failure is silent: an unreachable registry costs one attempt a day, not a slow prompt.",
+      "By default Archymedes installs a newer release automatically through whichever package manager installed it; it does not wait for another acceptance prompt. /update check changes that to notification-only behavior, and /update off stops it looking at all.",
+      "Automatic installs never happen in a piped or headless run, or in CI, because automation may depend on an exact installed version. A version that fails to install is remembered and not retried, because an update mechanism that fails loudly every launch is one people uninstall.",
+      "An install replaces the program on disk; the session you are in keeps running the version it started with until you restart it."
+    ],
+    examples: [
+      { input: "/update", effect: "install the newest version now" },
+      { input: "/update check", effect: "tell you about updates without installing" },
+      { input: "/update off", effect: "stop looking for updates" }
+    ],
+    covers: ["/update"]
+  },
+  {
+    id: "background",
+    title: "Background work",
+    summary: "Jobs that outlive the prompt, and research that runs itself.",
+    body: [
+      "Work can be sent to the background and keeps running after you close the terminal. A watched job streams its output into the session without taking the prompt, so you can read it when you want to and carry on meanwhile.",
+      "This — not tabs — is how two things run at once in the terminal. A tab you switch away from is paused; a detached job keeps working.",
+      "Wander runs a bounded research lab on a topic, gathers evidence first, and grades its own claims. It can run once or on a schedule.",
+      "A job that needs approval says so and waits — attach to it to answer."
+    ],
+    examples: [
+      { input: "/detach update the changelog", effect: "start it in the background" },
+      { input: "/jobs", effect: "what is running, queued or finished" },
+      { input: "/watch 20260814T0132Z-ab12cd", effect: "follow its output without giving up the prompt" },
+      { input: "/watch show <id>", effect: "read what it has said so far" },
+      { input: "/attach <id>", effect: "take the prompt to answer an approval" },
+      { input: "/wander daily coral reefs", effect: "a research lab, every day" }
+    ],
+    covers: ["/detach", "/jobs", "/attach", "/watch", "/wander"]
+  },
+  {
+    id: "panel",
+    title: "The control panel",
+    summary: "Every tab and job, live, on one screen.",
+    body: [
+      "The workspace is a full-screen view of everything at once: each tab as a pane showing its live output, what model it is running and where, and each watched job alongside them.",
+      "It is a view — it reads the session and changes nothing — so leaving it puts you back exactly where you were.",
+      "Inside it: 1-9 select a pane, arrows or Tab move between them, arrows or j/k scroll, g and G jump to the ends, Esc comes back to the chat."
+    ],
+    examples: [
+      { input: "/workspace", effect: "open the panel" },
+      { input: "q", effect: "leave it and return to the prompt" }
+    ],
+    covers: ["/workspace"]
+  },
+  {
+    id: "look",
+    title: "How it looks",
+    summary: "Themes, symbols, the fixed workspace, and terminals that need help.",
+    body: [
+      "Archymedes ships a blueprint theme and three others, and reads themes you write yourself as .tss files in .archymedes/themes — the same format TermUI apps use, so a palette written once works in both. /theme <name> also saves the choice, so it is still your theme tomorrow.",
+      "Code is coloured like VS Code — Dark+ on a dark theme, Light+ on a light one — with numbered lines in code blocks and green and red bands on changed lines in diffs. In /settings, Code colours set to theme paints code in the theme's own palette instead, and Line numbers in code blocks turns the numbers off.",
+      "Sessions open in the fixed workspace: a mode rail and composer stay anchored while the transcript scrolls underneath. Read history with the mouse wheel or Page Up / Page Down, move a line at a time with Alt+Up / Alt+Down, jump to the top with Ctrl+Home, and press Escape to return to live output. Menus open inside the transcript area so the composer never jumps. Prefer the plain terminal log? Use --layout scrollback, ARCHYMEDES_LAYOUT=scrollback, or /layout. ARCHYMEDES_MOUSE=0 keeps the terminal's own text selection instead of wheel scrolling.",
+      "If your terminal draws question marks instead of symbols, --ascii switches to characters every terminal has. If you would rather have a status line pinned to the bottom row, --pin does that, at the cost of your terminal's scrollback. ARCHYMEDES_NO_MOTION=1 keeps the opening geometry and menu focus still."
+    ],
+    examples: [
+      { input: "/theme list", effect: "every theme available, including your own" },
+      { input: "/theme chalkboard", effect: "change the colours immediately" },
+      { input: "/theme where", effect: "where to put a theme file of your own" },
+      { input: "/layout fixed", effect: "mode rail, anchored composer, menus in the transcript" },
+      { input: "/find TypeError", effect: "search this tab's history; /find again for the next match, Esc to return" },
+      { input: "/pager", effect: "open the whole transcript to scroll and search — in less, or the built-in pager on Windows (Esc back)" },
+      { input: "/settings", effect: "theme, code colours, line numbers, simple mode, startup and free-mode savings" },
+      { input: "/layout scrollback", effect: "return to the ordinary terminal log" },
+      { input: "archymedes --ascii", effect: "plain characters for terminals that mangle symbols" }
+    ],
+    covers: ["/theme", "/layout", "/find", "/pager", "/settings"]
+  },
+  {
+    id: "extend",
+    title: "Tools and voice",
+    summary: "What the agent can call, and talking to it.",
+    body: [
+      "Archymedes has a fixed set of built-in tools, and a project can add more through skills, plugins, MCP servers and hooks. The tools command shows exactly what is available in this project.",
+      "A prompt you type often can be saved as a command: `.archymedes/commands/review.md` becomes `/review`, shared with everyone on the project, and the same file in your config directory's `commands` folder is yours alone. `$ARGUMENTS` in the file is replaced by whatever you type after the name. Built-in commands cannot be replaced.",
+      "Voice input records or transcribes a prompt you can edit before sending.",
+      "The file picker is the project as a tree rather than a flat completion list: expand a folder, preview a file's contents, and pick one to drop an @mention into the line you're writing.",
+      "Mentioning an image — `what is wrong in @screenshots/bug.png?` — sends the picture itself with that request (PNG, JPEG, GIF or WebP, up to four, 5 MB each, from a local workspace). The model must accept images; the saved conversation keeps a note of the attachment rather than the image.",
+      "`/edit <path>` opens a file in the built-in editor. It reads and writes through the workspace like every tool does, so it edits the sandbox's copy in a sandboxed session rather than a same-named file on this machine, and it only writes when you save — quitting really is a discard."
+    ],
+    examples: [
+      { input: "/tools", effect: "every tool, skill, plugin, MCP server and hook" },
+      { input: "/review src/auth.ts", effect: "run .archymedes/commands/review.md with src/auth.ts as $ARGUMENTS" },
+      { input: "/voice", effect: "record a prompt, then edit it before sending" },
+      { input: "/cat README.md", effect: "read a file in the transcript, with markdown formatting or numbered code" },
+      { input: "/cat docs/diagram.png", effect: "draw a PNG in the transcript (ARCHYMEDES_IMAGES=kitty for real pixels in scrollback)" },
+      { input: "/files", effect: "browse the project tree and @mention a file" },
+      { input: "/edit src/app.ts", effect: "open a file in the built-in editor" }
+    ],
+    covers: ["/tools", "/voice", "/files", "/edit", "/cat"]
+  }
+];
+function findTopic(id) {
+  const wanted = id.trim().toLowerCase();
+  return GUIDE_TOPICS.find((topic) => topic.id === wanted) ?? GUIDE_TOPICS.find((topic) => topic.title.toLowerCase().includes(wanted));
+}
+function searchTopics(query) {
+  const needle = query.trim().toLowerCase();
+  if (!needle)
+    return GUIDE_TOPICS;
+  return GUIDE_TOPICS.filter((topic) => [topic.title, topic.summary, ...topic.body, ...(topic.examples ?? []).flatMap((example) => [example.input, example.effect])].some((text) => text.toLowerCase().includes(needle)));
+}
+function wrapText(text, width) {
+  const measure = Math.max(1, width);
+  const lines = [];
+  let current = "";
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    if (current === "") {
+      current = word;
+      continue;
+    }
+    if (visibleWidth(current) + 1 + visibleWidth(word) <= measure)
+      current = `${current} ${word}`;
+    else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current !== "")
+    lines.push(current);
+  return lines;
+}
+function renderGuideIndex(style) {
+  const glyphs = style.glyphs ?? UNICODE_GLYPHS;
+  const available = Math.max(8, style.width - GUTTER.length);
+  const longest = Math.max(...GUIDE_TOPICS.map((topic) => topic.id.length));
+  const rows = GUIDE_TOPICS.map((topic) => {
+    const id = paint(topic.id.padEnd(longest + 2), style.depth === "none" ? "" : DIM, style.depth);
+    return `${GUTTER}${id}${clip(topic.title, Math.max(0, available - longest - 2), glyphs)}`;
+  });
+  return [
+    rule(style, { label: "archymedes guide", tone: "accent" }),
+    ...rows,
+    "",
+    note(clip("/guide <topic> · /guide search <text> · /guide all", Math.max(0, style.width - GUTTER.length * 2), glyphs), style)
+  ].join(`
+`);
+}
+function renderGuideTopic(topic, style) {
+  const glyphs = style.glyphs ?? UNICODE_GLYPHS;
+  const measure = Math.max(20, style.width - GUTTER.length * 2);
+  const parts = [
+    rule(style, { label: topic.title, tone: "accent" }),
+    ""
+  ];
+  for (const paragraph of topic.body) {
+    for (const line of wrapText(paragraph, measure))
+      parts.push(`${GUTTER}${line}`);
+    parts.push("");
+  }
+  if (topic.examples && topic.examples.length > 0) {
+    const inner = Math.max(8, style.width - GUTTER.length - 4);
+    const longest = Math.max(...topic.examples.map((example) => visibleWidth(example.input)));
+    const bold = (text) => paintAll(text, [style.depth === "none" ? "" : BOLD], style.depth);
+    const dim = (text) => paint(text, style.depth === "none" ? "" : DIM, style.depth);
+    const stacked = longest > Math.floor(inner / 2);
+    const rows = topic.examples.flatMap((example) => stacked ? [bold(example.input), `  ${dim(clip(example.effect, inner - 2, glyphs))}`] : [`${bold(example.input.padEnd(longest + 2))}${dim(clip(example.effect, inner - longest - 2, glyphs))}`]);
+    parts.push(panel(rows, style, { title: "try", tone: "accent" }));
+  }
+  const next = GUIDE_TOPICS[GUIDE_TOPICS.indexOf(topic) + 1];
+  if (next) {
+    parts.push(note(clip(`next: /guide ${next.id} ${glyphs.middot} ${next.title}`, Math.max(0, style.width - GUTTER.length * 2), glyphs), style));
+  }
+  return parts.join(`
+`);
+}
+function renderWholeGuide(style) {
+  return [
+    renderGuideIndex(style),
+    "",
+    ...GUIDE_TOPICS.map((topic) => renderGuideTopic(topic, style))
+  ].join(`
+`);
+}
+function parseGuideCommand(input) {
+  const match = /^\/(?:guide|tutorial)(?:\s+([\s\S]*))?$/.exec(input.trim());
+  if (!match)
+    return null;
+  const rest = (match[1] ?? "").trim().replace(/\s+/g, " ");
+  if (!rest)
+    return { kind: "index" };
+  const [verb, ...words] = rest.split(" ");
+  if (verb.toLowerCase() === "all")
+    return { kind: "all" };
+  if (verb.toLowerCase() === "search") {
+    const query = words.join(" ").trim();
+    return query ? { kind: "search", query } : { kind: "index" };
+  }
+  return findTopic(rest) ? { kind: "topic", id: findTopic(rest).id } : { kind: "unknown", id: rest };
+}
 
-export { newViewport, applyViewport, visibleLines, scrollFraction, CONTROL_LANGUAGES, resolveControlLanguage, controlLabel, commandDescription, keyboardDescription, t, COMMANDS2 as COMMANDS };
+export { newViewport, maxTop, applyViewport, visibleLines, atTop, atBottom, scrollFraction, CONTROL_LANGUAGES, resolveControlLanguage, controlLabel, t, COMMANDS2 as COMMANDS, renderCommandHelp, suggestionsFor, inlineCompletion, isKnownCommand, parseModeCommand, suggestCommand, renderKeyboardShortcuts, GUIDE_TOPICS, findTopic, searchTopics, wrapText, renderGuideIndex, renderGuideTopic, renderWholeGuide, parseGuideCommand };