shmakk 1.2.1 → 1.2.3

package/README.md

@@ -170,6 +170,46 @@ The coordinator system enables complex, multi-step task execution with plan-firs
 - Secrets (`.env`, keys, tokens) are never sent to the AI
 - Workspace root is enforced — tools can't access files outside it
 
+## Remote SSH
+
+The agent can run commands and transfer files on remote hosts via SSH. Configure hosts in `.shmakk/hosts.json` (per-project) or `~/.config/shmakk/hosts.json` (global):
+
+```json
+{
+  "hosts": {
+    "devbox": {
+      "host": "marcus@192.168.1.100",
+      "port": 22,
+      "auto_approve": false,
+      "timeout_sec": 30
+    },
+    "staging": {
+      "host": "deploy@10.0.0.5",
+      "port": 2247
+    }
+  },
+  "allow_ssh_config": false,
+  "default_timeout_sec": 30
+}
+```
+
+| Tool | Description |
+|------|-------------|
+| `ssh_run` | Run a shell command on a remote host |
+| `ssh_push` | Copy a local workspace file to a remote host |
+| `ssh_pull` | Copy a remote file into the local workspace |
+
+SSH key auth via `~/.ssh` is assumed. For persistent connections (avoid re-auth on every call), add to `~/.ssh/config`:
+
+```
+Host *
+  ControlMaster auto
+  ControlPath ~/.ssh/controlmasters/%r@%h:%p
+  ControlPersist 600
+```
+
+Then `mkdir -p ~/.ssh/controlmasters` once.
+
 ## How it works
 
 shmakk wraps your shell in a PTY (pseudo-terminal). Every command that fails is checked against a deterministic correction engine (no LLM, no API call). If a correction matches and the fixed command succeeds, shmakk feeds the agent your **original input** (not the fixed command) so the agent can address your full intent — not just the typo. You can also give task instructions in natural language — shmakk uses tools to read files, write code, list directories, and run commands, all constrained to your workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shmakk",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "AI-supervised terminal wrapper — command correction, tool-driven tasks, safety controls",
   "license": "MIT",
   "keywords": [

package/src/agent.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { makeClient, modelFor, isConfigured, getDeepSeekOptions } = require('./llm');
+const { makeClient, modelFor, isConfigured, getDeepSeekOptions, supportsVision } = require('./llm');
 const {
   sanitizeAssistantContent,
   isLeakedToolMarkup,
@@ -87,13 +87,16 @@ function clearTaskJournal(root) {
 const { renderBlock } = require('./markdown');
 
 // Tiny spinner so the user sees "the agent is thinking" while we wait on
-// the model. Erased when stop() is called.
+// the model. Erased when stop() is called. Also updates the terminal tab
+// title so you can see agent activity even when looking at another tab.
 function startSpinner(write, label = 'thinking') {
   const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   let i = 0; let line = '';
   const draw = () => {
     line = `\x1b[2m${frames[i % frames.length]} ${label}…\x1b[0m`;
     write('\r' + line);
+    // Update terminal tab/window title so activity is visible from other tabs
+    write(`\x1b]0;${frames[i % frames.length]} ${label} — shmakk\x07`);
     i++;
   };
   draw();
@@ -101,6 +104,8 @@ function startSpinner(write, label = 'thinking') {
   return () => {
     clearInterval(tm);
     write('\r' + ' '.repeat(line.replace(/\x1b\[[0-9;]*m/g, '').length + 2) + '\r\r');
+    // Clear the terminal title — shell will restore normal title on next prompt
+    write('\x1b]0;\x07');
   };
 }
 
@@ -251,6 +256,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     mcpToolHint,
     userRulesText,
     userMemoryText,
+    supportsVision: supportsVision(),
   });
 
   const boundedHistory = trimForContext(history, runtimeProfile.historyEntries);
@@ -292,14 +298,22 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
   // Tool loop. Streams content as it arrives; prints each tool call.
   let producedAnything = false;
   const runState = { _dsmlLeakRetries: 0 };
+  let taskSpinnerStop = null;
+  const ensureSpinner = () => {
+    if (!taskSpinnerStop) taskSpinnerStop = startSpinner(write, 'thinking');
+  };
+  const stopTaskSpinner = () => {
+    if (taskSpinnerStop) { taskSpinnerStop(); taskSpinnerStop = null; }
+  };
   for (let i = 0; i < dynamicToolBudget; i++) {
-    if (signal && signal.aborted) return messages.slice(1);
+    if (signal && signal.aborted) { stopTaskSpinner(); return messages.slice(1); }
 
     // Stream the response so the user sees text as it generates.
     const cacheKey = promptCacheEnabled ? promptCache.makeKey({ model: modelFor('agent'), messages, toolChoice: 'auto' }) : null;
     if (promptCacheEnabled && cacheKey) {
       const hit = promptCache.get(roots[0], cacheKey);
       if (hit && hit.content) {
+        stopTaskSpinner();
         write(dim('[shmakk] prompt cache hit', colors) + '\n');
         write(highlightCodeBlocks(hit.content, colors));
         if (!hit.content.endsWith('\n')) write('\n');
@@ -309,7 +323,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       }
     }
 
-    const stop = startSpinner(write, i === 0 ? 'thinking' : 'continuing');
+    ensureSpinner();
     const allTools = mcpManager ? [...TOOLS, ...mcpManager.getToolDefinitions()] : TOOLS;
     let stream;
     try {
@@ -324,14 +338,13 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         ...getDeepSeekOptions('tool_loop'),
       }, { signal });
     } catch (e) {
-      stop();
+      stopTaskSpinner();
       throw e;
     }
 
     let content = '';
     let reasoningContent = '';
     const toolCalls = []; // [{id, type:'function', function:{name, arguments}}]
-    let spinnerStopped = false;
     let streamingContentOk = true;  // flipped to false on leak
     try {
       for await (const chunk of stream) {
@@ -370,7 +383,6 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
           reasoningContent += delta.reasoning_content;
         }
         if (delta.tool_calls) {
-          if (!spinnerStopped) { stop(); spinnerStopped = true; }
           for (const tc of delta.tool_calls) {
             const idx = tc.index ?? 0;
             if (!toolCalls[idx]) toolCalls[idx] = { id: tc.id || '', type: 'function', function: { name: '', arguments: '' } };
@@ -382,7 +394,8 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         }
       }
     } finally {
-      if (!spinnerStopped) stop();
+      // Spinner runs continuously from loop start — stopped below when
+      // we're about to show output or dispatch tools that may need input.
     }
 
     // ── DSML leak detection (after stream completes) ────────────────────
@@ -427,6 +440,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       // Max retries exceeded — strip and show what we can.
       content = sanitized.visibleText;
       if (!content) {
+        stopTaskSpinner();
         write(dim('[shmakk] response contained only leaked tool markup — blocked.', colors) + '\n');
         clearTaskJournal(roots[0]);
         return messages.slice(1);
@@ -477,6 +491,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
 
     // No tools → done.
     if (!normalizedToolCalls.length) {
+      stopTaskSpinner();
       if (content) {
         write(renderBlock(content, { enabled: markdown, colors }));
         if (!content.endsWith('\n')) write('\n');
@@ -497,6 +512,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     // Dispatch tool calls.
     // Reads/lists are noisy — collect them silently and show a single dim summary.
     // Writes, edits, runs, and errors always print clearly.
+    stopTaskSpinner();
     const SILENT_TOOLS = new Set(['read_file', 'list_dir', 'web_search', 'fetch_url']);
     let iterProgress = false;
     let silentReads = [];
@@ -534,7 +550,34 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         write(dim(`→ ${c.function.name}(${shortArgs(args)})${summary ? ' — ' + summary : ''}`, colors) + '\n');
       }
 
-      messages.push({ role: 'tool', tool_call_id: c.id, content: JSON.stringify(result).slice(0, 8000) });
+      // Build tool result message. If the result includes images with real
+      // base64 data AND the current endpoint has `vision: true`, send them as
+      // vision content blocks in a follow-up user message. Otherwise just
+      // include image metadata in the text. Keep the tool message text-only.
+      const toolImages = Array.isArray(result.images) ? result.images.filter((img) => img.data) : [];
+      const toolText = result.content || '';
+      const toolMeta = Object.fromEntries(
+        Object.entries(result || {}).filter(([k]) => !['content', 'images', 'error', 'isRetryable'].includes(k)),
+      );
+      let toolContent = (toolText + (Object.keys(toolMeta).length ? ' ' + JSON.stringify(toolMeta) : '')).trim();
+      if (toolImages.length > 0 && !supportsVision()) {
+        // Endpoint doesn't support vision — include image metadata as text
+        const imgDesc = toolImages.map((img, i) => `[Image #${i + 1}: ${img.mimeType}, base64=${img.dataLength} chars${img.truncated ? ', truncated' : ''}]`).join(', ');
+        toolContent = toolContent ? `${toolContent} ${imgDesc}` : imgDesc;
+      }
+      messages.push({ role: 'tool', tool_call_id: c.id, content: toolContent.slice(0, 8000) });
+      if (toolImages.length > 0 && supportsVision()) {
+        messages.push({
+          role: 'user',
+          content: [
+            { type: 'text', text: `[Images returned by ${c.function.name}${toolImages.some((img) => img.truncated) ? ' (some truncated to ~2MB base64)' : ''}]` },
+            ...toolImages.map((img) => ({
+              type: 'image_url',
+              image_url: { url: `data:${img.mimeType};base64,${img.data}`, detail: 'auto' },
+            })),
+          ],
+        });
+      }
       producedAnything = true;
       persistJournal('running');
       if (signal && signal.aborted) return messages.slice(1);
@@ -553,6 +596,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     }
 
     if (repeatedSignatureCount >= runtimeProfile.stallRepeat && noProgressRepeats >= 2) {
+      stopTaskSpinner();
       break;
     }
   }
@@ -589,6 +633,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     }
   } catch {}
 
+  stopTaskSpinner();
   write(dim('[shmakk] paused after several tool rounds. Resume later continues from task journal; try `shmakk --reset` to clear.', colors) + '\n');
   persistJournal('paused');
   return messages.slice(1);

package/src/cli.js

@@ -41,8 +41,10 @@ function parseArgs(argv) {
     voiceSilenceStartSec: null,
     voicePadStartSec: null,
     ttsVoice: null,
-    notify: false,
+    notify: true,
     completion: null,
+    helpCategory: null,
+    shell: null,
     unknown: [],
   };
 
@@ -53,7 +55,13 @@ function parseArgs(argv) {
       case '--yes-files': opts.yesFiles = true; break;
       case '--update-command-glossary': opts.updateGlossary = true; break;
       case '-h':
-      case '--help': opts.help = true; break;
+      case '--help':
+        opts.help = true;
+        // Capture optional category: shmakk --help voice
+        if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+          opts.helpCategory = argv[++i];
+        }
+        break;
       case '--debug': opts.debug = true; break;
       case '--no-ai': opts.noAi = true; break;
       case '--no-correction': opts.noCorrection = true; break;
@@ -102,34 +110,67 @@ function parseArgs(argv) {
       case '--markdown': opts.markdown = argv[++i] || null; break;
       case '--endpoint': opts.endpoint = argv[++i] || null; break;
       case '--model-recommendation': opts.modelRecommendation = true; break;
+      case '--shell':
+        {
+          const v = argv[++i];
+          if (!v || !['fish', 'bash', 'zsh'].includes(v)) {
+            process.stderr.write('[shmakk] invalid --shell. Use: fish|bash|zsh\n');
+            process.exit(2);
+          }
+          opts.shell = v;
+        }
+        break;
       default: opts.unknown.push(a);
     }
   }
   return opts;
 }
 
-const HELP = `shmakk - AI-supervised terminal wrapper
+// ── Help: category-based navigation ──────────────────────────────────────────
+
+const HELP_SUMMARY = `shmakk - AI-supervised terminal wrapper
 
   Launch shmakk, then type commands as usual. shmakk watches the shell, catches
   failures, and calls an LLM to fix them, plan tasks, and edit files.
 
-  You can also type natural-language self-commands directly into the session
-  (e.g. "list skills", "agent overview", "compact"). See SELF-COMMANDS below.
-
   Type "help" inside a session to see this same text.
 
+  Usage: shmakk [--flag ...]
+         shmakk --help [category]
+
+Categories (shmakk --help <name> for details):
+
+  launch       Startup modes, profiles, tuning flags
+  session      Status, stats, restart, exit, control signals
+  skills       Skill discovery, loading, listing, management
+  models       Provider configuration, endpoint presets
+  voice        Speech-to-Text / Text-to-Speech options
+  env          Environment variable reference
+  mcp          MCP servers and browser automation
+  ssh          Remote host execution
+  self         Natural-language self-commands (inside a session)
+
+`;
+
+const HELP_SECTIONS = {};
+
+HELP_SECTIONS.launch = `═══════════════════════════════════════════════════════════════════════════
+  LAUNCH OPTIONS  (shmakk --flag  from outside a session)
 ═══════════════════════════════════════════════════════════════════════════
-  LAUNCH OPTIONS
-═══════════════════════════════════════════════════════════════════════════
+
+  These flags only apply when starting a new shmakk session. They are
+  ignored if you are already inside shmakk (SHMAKK=1).
 
   shmakk                           Launch in auto mode (AI acts on failures)
   shmakk --review                  Launch in review mode (confirm every AI action)
   shmakk --yes-files               Auto-accept file writes, edits, mkdir
 
-  shmakk --help                    Show this help
+  shmakk --help                    Show overview (this text)
+  shmakk --help <category>         Show detailed help for a category
   shmakk --build-history [files]   Parse shell history for better corrections
   shmakk --update-command-glossary Scan PATH and build local command glossary
 
+  --shell <fish|bash|zsh>          Use a specific shell (default: current $SHELL)
   --no-ai                          Disable AI entirely (pure passthrough)
   --no-correction                  Disable command correction
   --debug                          Verbose logging to stderr
@@ -140,8 +181,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   --colors <true|false>            Enable or disable ANSI colors
   --markdown <true|false>          Enable or disable markdown rendering
   --notify                         Desktop notifications for Y/n prompts
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.models = `═══════════════════════════════════════════════════════════════════════════
   MODEL PROVIDERS
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -159,8 +201,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
                           "model":"qwen/qwen3.5-9b" }
       }
     }
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.session = `═══════════════════════════════════════════════════════════════════════════
   SESSION CONTROL  (shmakk --flag  from another terminal)
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -176,6 +219,11 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   shmakk --exit                    Cleanly exit the parent shmakk
 
   shmakk --profile-set <name>      Switch profile and restart
+`;
+
+HELP_SECTIONS.skills = `═══════════════════════════════════════════════════════════════════════════
+  SKILLS
+═══════════════════════════════════════════════════════════════════════════
 
   shmakk --load-skill <name>       Load a skill into workspace state
   shmakk --install-skill <url>     Download skill markdown from URL, validate, load
@@ -183,71 +231,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   shmakk --list-skills             List all registered skills (workspace + global)
   shmakk --skill-status            Active skill and registry status
   shmakk --unload-skill <name>     Remove skill from whichever registry has it
+`;
 
-═══════════════════════════════════════════════════════════════════════════
-  SELF-COMMANDS  (type inside an shmakk session)
-═══════════════════════════════════════════════════════════════════════════
-
-  ── Skills ──
-  list skills                      List all registered skills
-  list skills <category>           List skills in a specific category
-  list skill categories            Show available skill categories
-  find skills <query>              Search skills by name/description
-  load skill <name>                Load a skill into the active workspace
-  unload skill <name>              Remove a skill from its registry
-  skill status                     Show active skill and registry state
-
-  ── Agents & Team ──
-  agent overview                   Show all agents and their specialisms
-  agent skills                     List all agent skills
-  agent <name>                     Show detail for a specific agent
-  list agents                      Alias for agent overview
-
-  ── Context & Session ──
-  status                           Show session status
-  stats                            Show session/task statistics
-  resume status                    Show task journal for resume continuity
-  show plan                        Display current plan and progress
-  compact                          Clear conversation + task journal
-  reset                            Clear AI conversation history
-
-  ── Memory & Search ──
-  recall <query>                   Search past sessions by content
-  find session <query>             Find a session by topic
-  last sessions                    Show recent sessions
-  search db status                 Display session search DB info
-  show memory                      List stored memories
-  forget <query>                   Remove matching memories
-
-  ── Configuration ──
-  show config                      Print resolved configuration
-  mcp status                       Show MCP servers and tools
-  show rules                       Display active workspace rules
-  list endpoints                   List configured model endpoints
-  use endpoint <name>              Switch to a named model endpoint
-  set model to <name>              Change the active model
-  set url to <url>                 Change the base URL
-  set api key to <key>             Change the API key
-
-  ── Toggles ──
-  enable review  |  disable review
-  enable correction  |  disable correction
-  enable yes-files  |  disable yes-files
-  enable colors  |  disable colors
-  enable debug  |  disable debug
-
-  ── Workflows ──
-  list workflows                   Show available automation workflows
-  run workflow <name>              Execute a named workflow
-
-  ── Edits ──
-  review edits                     Step through pending file changes
-
-  ── Meta ──
-  sidebar <query>                  Out-of-band agent query (not added to history)
-  help                             Show this help
-
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.voice = `═══════════════════════════════════════════════════════════════════════════
   VOICE  (Speech-to-Text / Text-to-Speech)
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -266,8 +252,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   STT: Whisper-base ONNX in-process. No Python, no server, no API key.
   TTS: kokoro-js (Kokoro-82M ONNX, ~334MB fp16). Auto-download on first use.
   Requires aplay, paplay, or afplay for audio. 28 voices, rotated daily.
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.env = `═══════════════════════════════════════════════════════════════════════════
   ENVIRONMENT
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -287,8 +274,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   SHMAKK_VOICE_SILENCE_SEC         VAD silence threshold seconds
   SHMAKK_VOICE_SILENCE_THRESHOLD   VAD amplitude threshold
   SHMAKK_VOICE_PAD_START_SEC       Start-of-recording padding
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.mcp = `═══════════════════════════════════════════════════════════════════════════
   MCP & BROWSER
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -299,7 +287,134 @@ const HELP = `shmakk - AI-supervised terminal wrapper
     npm install playwright && npx playwright install chromium
   Tools: navigate, click, type, read_page, screenshot, evaluate, select,
   wait, scroll, close.
+`;
+
+HELP_SECTIONS.ssh = `═══════════════════════════════════════════════════════════════════════════
+  REMOTE HOSTS (SSH)
+═══════════════════════════════════════════════════════════════════════════
+
+  The agent can run commands on remote hosts and transfer files via SSH.
+  Configure hosts in .shmakk/hosts.json or ~/.config/shmakk/hosts.json:
+
+    {
+      "hosts": {
+        "devbox": {
+          "host": "user@192.168.1.100",
+          "port": 22,
+          "auto_approve": false,
+          "timeout_sec": 30
+        }
+      },
+      "allow_ssh_config": false,
+      "default_timeout_sec": 30
+    }
+
+  Agent tools: ssh_run (run command), ssh_push (upload), ssh_pull (download).
+  For persistent connections, use ControlMaster in ~/.ssh/config:
+    Host *
+      ControlMaster auto
+      ControlPath ~/.ssh/controlmasters/%r@%h:%p
+      ControlPersist 600
+`;
+
+HELP_SECTIONS.self = `═══════════════════════════════════════════════════════════════════════════
+  SELF-COMMANDS  (type inside an shmakk session)
+═══════════════════════════════════════════════════════════════════════════
+
+  Self-commands work with a prefix — /cmd or shmakk cmd.
+  Bare words like "status" or "stats" go to the shell, not shmakk.
+
+  -- Session --
+  /status  |  shmakk status         Show session status
+  /stats   |  shmakk stats          Show session/task statistics
+  /sessions  |  shmakk sessions     Show recent sessions
+  show sessions  |  last sessions   (same as /sessions)
+  resume status                     Show task journal for resume continuity
+  show plan                         Display current plan and progress
+  /compact  |  shmakk compact       Clear conversation + task journal
+  /reset  |  shmakk reset           Clear AI conversation history
+
+  -- Skills --
+  list skills                       List all registered skills
+  list skills <category>            List skills in a specific category
+  list skill categories             Show available skill categories
+  find skills <query>               Search skills by name/description
+  load skill <name>                 Load a skill into the active workspace
+  unload skill <name>               Remove a skill from its registry
+  skill status                      Show active skill and registry state
+
+  -- Agents & Team --
+  agent overview                    Show all agents and their specialisms
+  agent skills                      List all agent skills
+  agent <name>                      Show detail for a specific agent
+  list agents                       Alias for agent overview
+
+  -- Memory & Search --
+  recall <query>                    Search past sessions by content
+  find session <query>              Find a session by topic
+  search db status                  Display session search DB info
+  show memory                       List stored memories
+  forget <query>                    Remove matching memories
+
+  -- Configuration --
+  show config                       Print resolved configuration
+  mcp status                        Show MCP servers and tools
+  show rules                        Display active workspace rules
+  list endpoints                    List configured model endpoints
+  use endpoint <name>               Switch to a named model endpoint
+  set model to <name>               Change the active model
+  set url to <url>                  Change the base URL
+  set api key to <key>              Change the API key
+
+  -- Toggles --
+  enable review  |  disable review
+  enable correction  |  disable correction
+  enable yes-files  |  disable yes-files
+  enable colors  |  disable colors
+  enable debug  |  disable debug
+
+  -- Workflows --
+  list workflows                    Show available automation workflows
+  run workflow <name>               Execute a named workflow
+
+  -- Edits --
+  review edits                      Step through pending file changes
+
+  -- Meta --
+  sidebar <query>                   Out-of-band agent query (not added to history)
+  help                              Show this help
+`;
+
+// Resolve: returns the full old HELP string for backward compat, or the category
+// text, or the summary.
+function resolveHelp(category) {
+  if (category) {
+    const key = category.toLowerCase();
+    if (HELP_SECTIONS[key]) return HELP_SECTIONS[key];
+    // Unknown category: show summary + available categories
+    const available = Object.keys(HELP_SECTIONS).join(', ');
+    return HELP_SUMMARY + `Unknown category "${category}". Available: ${available}\n`;
+  }
+  return HELP_SUMMARY;
+}
+
+// Help text shown INSIDE a session (no launch flags — you're already running)
+const HELP_SESSION_SUMMARY = `shmakk — inside a session
+
+  Type commands as usual. shmakk watches the shell, catches failures, and
+  calls an LLM to fix them, plan tasks, and edit files.
+
+  Self-commands use a prefix: /cmd  or  shmakk cmd
+  Examples:  /status   /sessions   shmakk status   shmakk show sessions
+
+  Multi-word natural language also works:  "show help"  "list skills"
+
+  For the full reference: shmakk --help self (from outside the session)
+  For launch flags:        shmakk --help launch
 
 `;
 
-module.exports = { parseArgs, HELP };
+// Full legacy HELP for backward compat
+const HELP = HELP_SUMMARY + Object.values(HELP_SECTIONS).join('\n');
+
+module.exports = { parseArgs, HELP, resolveHelp, HELP_SUMMARY, HELP_SESSION_SUMMARY };

package/src/correction.js

@@ -115,6 +115,12 @@ function preserveCase(original, corrected) {
 }
 
 async function correct({ input, glossary, signal: _unused }) {
+  // /-prefixed and "shmakk ..." commands are shmakk self-commands.
+  // They should never reach the correction engine — bail out immediately.
+  if (/^\//.test(input) || /^shmakk\s/i.test(input)) {
+    return { category: 'not_a_correction', proposed: null, safety: 'uncertain', reason: 'shmakk self-command prefix — not a shell command' };
+  }
+
   // Pre-filter natural language
   if (looksLikeNaturalLanguage(input)) {
     return { category: 'not_a_correction', proposed: null, safety: 'uncertain', reason: 'looks like natural language' };

package/src/endpoints.js

@@ -73,6 +73,7 @@ function normalizeModelConfig(name, cfg) {
     headers: cfg.headers || cfg.headears || null,
     registry: cfg.registry || null,
     main: !!cfg.main,
+    vision: !!cfg.vision,
   };
 }
 
@@ -143,6 +144,10 @@ function getCurrentEndpointName() {
   return currentEndpointName;
 }
 
+function supportsVision() {
+  return !!(currentEndpointConfig && currentEndpointConfig.vision);
+}
+
 function listEndpoints(cwd) {
   return Object.keys(loadModelRegistry(cwd).models);
 }
@@ -160,5 +165,6 @@ module.exports = {
   listEndpoints,
   getCurrentEndpoint,
   getCurrentEndpointName,
+  supportsVision,
   getModelRegistry,
 };