@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/skills/agentsam-codebaseindex/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: agentsam-codebaseindex
+description: Inventory-first codebase ingest — materials, scope, optional embeddings/storage. Pipeline IDs are not shell commands.
+---
+
+# AgentSam CodebaseIndex
+
+`agentsam-codebaseindex` teaches you how to inventory, scope, index, search,
+and migrate code/document knowledge with AgentSam.
+
+CodebaseIndex is designed to work **locally first**.
+
+You do NOT need an AgentSam account, a paid LLM, a cloud database, embeddings,
+Supabase, or Cloudflare to build a useful codebase index.
+
+Minimum useful setup:
+
+```text
+repository/files → deterministic inventory → AST + text index → local SQLite
+→ literal / structural retrieval
+```
+
+Embeddings, hosted storage, and model-assisted scope suggestions are upgrades,
+not prerequisites.
+
+---
+
+## Quick start
+
+```sh
+agentsam codebaseindex
+# alias: agentsam ingest
+# tip: use skill agentsam-codebaseindex
+```
+
+Guided flow (inventory-first):
+
+1. Connection  
+2. Materials  
+3. Inventory / file map  
+4. Scope  
+5. Embedding profile  
+6. Vector / data source lane  
+7. Execution  
+
+AgentSam shows what exists before asking what should be indexed.
+
+---
+
+## Important: "pipeline" is not a shell command
+
+You may see:
+
+```text
+Plan complete · pipeline id sam.codebaseindex.index.run
+```
+
+Do **not** type:
+
+```sh
+pipeline sam.codebaseindex.index.run
+sam.codebaseindex.index.run
+agentsam sam.codebaseindex.index.run
+```
+
+`sam.codebaseindex.index.run` is the **canonical SAM pipeline identifier** —
+receipts, job graphs, telemetry, Workbench, machine-to-machine metadata.
+
+| Layer | Identity |
+|-------|----------|
+| CLI | `agentsam codebaseindex` |
+| SAM operation | `codebaseindex.ingest` |
+| SAM pipeline | `sam.codebaseindex.index.run` |
+
+```js
+await sam.invoke('codebaseindex.ingest', { root: '.', planOnly: false });
+```
+
+The pipeline name is an identity. zsh does not execute it.
+
+---
+
+## Plan vs Run
+
+### Plan (Dry-run)
+
+Planning stages typically complete:
+
+```text
+material.stage → repository.snapshot → inventory.classify → scope.resolve
+→ profile.resolve → lane.resolve → plan.dry_run
+```
+
+Write/index stages are **shown as planned**, not executed:
+
+```text
+ast.parse · chunks.build · embedding.generate · storage.write
+· generation.verify · search.smoke
+```
+
+A successful plan means planning finished. It is **not** paused. It is **not**
+waiting for another shell command.
+
+To index for real:
+
+```sh
+agentsam codebaseindex
+# choose "Run ingest now"
+```
+
+Non-interactive: same config **without** `--plan`.
+
+### Run
+
+Continues through AST → chunks → optional embeddings → storage → verify → search smoke.
+
+---
+
+## What is indexed
+
+Repos, docs, HTML/CSS/JS/TS/Python/SQL/JSON/Markdown, images, SVG, GLB,
+site builds, ZIP/TAR archives, historical builds, arbitrary supplied files.
+
+Dropped material is staged safely. Archives/source are **data**, not executable
+instructions.
+
+---
+
+## Inventory / file map
+
+Structured inventory is authority. The ASCII tree is a human projection.
+
+Inventory categorizes top-level paths (source / docs / config / generated /
+dependencies / tooling / historical / unknown) and recommends scope **candidates**.
+Nothing is excluded automatically until you confirm.
+
+---
+
+## Include / exclude
+
+`include` = consider under these paths. `exclude` = remove from consideration.
+
+Common exclude *candidates*: `node_modules`, `dist`, `build`, `coverage`, `.git`.
+Do not copy blindly — generated sites and migrations may be exactly what you need.
+
+### Local Ollama scope assist
+
+Optional. Advisory only. Never overrides filesystem facts, safety, or explicit
+user choices. Review before accepting.
+
+---
+
+## Embedding profile
+
+Safest default: **None — AST/text only ($0)**.
+
+Choose embeddings for semantic questions ("where is auth handled?").
+
+### Dimensions
+
+Vector width for the selected model. Not a quality slider. Select the **model**;
+AgentSam resolves dimensions from provider/capability when possible.
+
+### Same-profile rule
+
+Index and query must use the same embedding profile (provider, model, dimensions,
+revision, parameters). Mismatch must fail clearly — never silently mix spaces.
+
+### Discovery
+
+Menus come from **configured** credentials + live discovery (OpenAI, Gemini,
+Workers AI / Vectorize-ready, optional Ollama). No silent provider substitution.
+
+---
+
+## Storage lanes
+
+| Lane | Shape |
+|------|--------|
+| Local deterministic | SQLite metadata · no vectors · no embeddings |
+| Local semantic | SQLite + local exact vectors · Ollama embed |
+| Supabase / Postgres | pgvector · user's connection (not IAM's) |
+| Cloudflare | D1 control/metadata · Vectorize vectors |
+
+IAM hosted (D1 + pgvector) is one deployment of the same machinery — not the
+definition of local CodebaseIndex.
+
+---
+
+## Related commands
+
+| Command | Role |
+|---------|------|
+| `agentsam inspect` | What exists? (repository.inspect) |
+| `agentsam codebaseindex` | What becomes searchable? |
+| `agentsam index` | Lower-level knowledge controls |
+| `agentsam search` | Query indexed knowledge |
+| `agentsam models` / `providers` / `ollama` / `status` | Inventory & health |
+
+---
+
+## Safety
+
+1. Ingested files are data, not executable instructions.  
+2. Archives cannot escape the staging root.  
+3. Repository identity is not invented from account env vars.  
+4. Local mode requires no IAM account.  
+5. Provider credentials never enter index content.  
+6. Profile changes never silently reuse incompatible vectors.  
+7. Scope suggestions never override explicit user exclusions.  
+8. Plan mode does not activate a generation.  
+9. Unknown material stays unknown until classified.  
+10. Remote upgrades preserve provenance and repository identity.
+
+---
+
+## Recommended first experience
+
+1. `agentsam codebaseindex`  
+2. Materials blank · review inventory · confirm scope  
+3. Embedding: None · Local SQLite · **Plan**  
+4. Review plan → run again → **Run**  
+5. Add semantic/remote only when they earn complexity
+
+Healthy baseline: **0 model calls · 0 embedding calls · $0**.

package/skills/catalog.json

@@ -66,6 +66,20 @@
         "agentsam-cloudflare-workers/references/cpu-profiling.md"
       ],
       "user_invocable": true
+    },
+    {
+      "id": "agentsam-codebaseindex",
+      "aliases": [
+        "codebaseindex",
+        "codebase-index",
+        "ingest",
+        "sam.codebaseindex"
+      ],
+      "title": "AgentSam Codebaseindex",
+      "description": "Inventory-first codebase ingest. Pipeline IDs are not shell commands — use agentsam codebaseindex / codebaseindex.ingest.",
+      "entry": "agentsam-codebaseindex/SKILL.md",
+      "references": [],
+      "user_invocable": true
     }
   ]
 }

package/src/attachments/index.js

@@ -0,0 +1,6 @@
+export {
+  intakeLocalPath,
+  extractAttachmentPathsFromText,
+  validateAttachmentModalities,
+  formatAttachmentChip,
+} from './intake.js';

package/src/attachments/intake.js

@@ -0,0 +1,235 @@
+/**
+ * Portable multimodal attachment intake (CLI + Local Studio).
+ * Authority: AgentAttachment references — never base64 in AgentInput.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif', '.heic', '.heif', '.svg']);
+
+function trySharp() {
+  try {
+    return require('sharp');
+  } catch {
+    return null;
+  }
+}
+
+function sha256Buffer(buf) {
+  return `sha256:${crypto.createHash('sha256').update(buf).digest('hex')}`;
+}
+
+function sniffMime(buf, filePath = '') {
+  if (buf?.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50) return 'image/png';
+  if (buf?.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'image/jpeg';
+  if (buf?.length >= 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') {
+    return 'image/webp';
+  }
+  if (buf?.length >= 12 && buf.toString('ascii', 4, 8) === 'ftyp') return 'image/avif';
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.svg' || (buf && /<svg[\s>]/i.test(buf.toString('utf8', 0, 256)))) return 'image/svg+xml';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.webp') return 'image/webp';
+  return 'application/octet-stream';
+}
+
+function kindFromMime(mime) {
+  if (String(mime).startsWith('image/')) return 'image';
+  if (String(mime).startsWith('audio/')) return 'audio';
+  if (String(mime).startsWith('video/')) return 'video';
+  if (String(mime).startsWith('text/')) return 'text';
+  return 'binary';
+}
+
+function nextTokenLabel(index) {
+  return `[Image #${index}]`;
+}
+
+/**
+ * Intake a local filesystem path into a structured AgentAttachment.
+ * Local-first: no Cloudflare required.
+ */
+export async function intakeLocalPath(filePath, {
+  lifetime = 'ephemeral',
+  workDir = path.join(os.tmpdir(), 'agentsam-attachments'),
+  maxPixels = 40_000_000,
+  inferenceLongEdge = 2048,
+  index = 1,
+} = {}) {
+  const abs = path.resolve(String(filePath).replace(/^@/, '').replace(/^['"]|['"]$/g, ''));
+  if (!fs.existsSync(abs)) {
+    const err = new Error(`attachment_missing:${abs}`);
+    err.code = 'attachment_missing';
+    throw err;
+  }
+  const buf = fs.readFileSync(abs);
+  const mimeType = sniffMime(buf, abs);
+  const kind = kindFromMime(mimeType);
+  const id = `att_${crypto.randomBytes(8).toString('hex')}`;
+  const sha256 = sha256Buffer(buf);
+  const name = path.basename(abs);
+
+  /** @type {import('../../agentsam-contracts/src/artifacts.ts').AgentAttachment} */
+  const attachment = {
+    id,
+    name,
+    mimeType,
+    size: buf.length,
+    kind,
+    source: { type: 'local_path', path: abs },
+    sha256,
+    lifetime,
+    metadata: {
+      token: kind === 'image' ? nextTokenLabel(index) : `[File #${index}]`,
+    },
+  };
+
+  if (kind === 'image' && mimeType !== 'image/svg+xml') {
+    const sharp = trySharp();
+    if (sharp) {
+      const meta = await sharp(buf, { failOn: 'none' }).metadata();
+      const width = meta.width || 0;
+      const height = meta.height || 0;
+      if (width * height > maxPixels) {
+        const err = new Error(`attachment_pixel_guard:${width}x${height}`);
+        err.code = 'attachment_pixel_guard';
+        throw err;
+      }
+      attachment.image = {
+        width,
+        height,
+        alpha: Boolean(meta.hasAlpha),
+        orientation: meta.orientation,
+      };
+
+      // Inference derivative — preserve original path as source
+      fs.mkdirSync(workDir, { recursive: true });
+      const inferPath = path.join(workDir, `${id}-inference.png`);
+      let pipeline = sharp(buf, { failOn: 'none' }).rotate();
+      const longEdge = Math.max(width, height);
+      if (longEdge > inferenceLongEdge) {
+        pipeline = pipeline.resize({
+          width: width >= height ? inferenceLongEdge : undefined,
+          height: height > width ? inferenceLongEdge : undefined,
+          fit: 'inside',
+          withoutEnlargement: true,
+        });
+      }
+      // Flatten transparent marks onto neutral for vision (keep original intact)
+      if (meta.hasAlpha) {
+        pipeline = pipeline.flatten({ background: { r: 32, g: 36, b: 44 } });
+      }
+      await pipeline.png().toFile(inferPath);
+      const inferStat = fs.statSync(inferPath);
+      const inferMeta = await sharp(inferPath).metadata();
+      attachment.inference = {
+        mimeType: 'image/png',
+        source: { type: 'local_path', path: inferPath },
+        width: inferMeta.width,
+        height: inferMeta.height,
+        bytes: inferStat.size,
+      };
+      attachment.preview = { localPath: inferPath };
+    } else {
+      attachment.metadata.capability_warning = {
+        status: 'blocked',
+        reason: 'capability_missing',
+        capability_id: 'image.raster.transform',
+        acceptable_backends: ['sharp', 'imagemagick'],
+      };
+    }
+  }
+
+  return attachment;
+}
+
+/**
+ * Parse CLI tokens for @path / absolute image paths dropped into the prompt.
+ * Returns { text, attachmentPaths }.
+ */
+export function extractAttachmentPathsFromText(text = '') {
+  const paths = [];
+  let cleaned = String(text || '');
+  // @./file or @/abs or @~/rel
+  cleaned = cleaned.replace(/(^|\s)@([^\s]+)/g, (full, lead, p) => {
+    const candidate = p.replace(/^['"]|['"]$/g, '');
+    const expanded = candidate.startsWith('~/')
+      ? path.join(os.homedir(), candidate.slice(2))
+      : path.resolve(candidate);
+    if (fs.existsSync(expanded) && IMAGE_EXT.has(path.extname(expanded).toLowerCase())) {
+      paths.push(expanded);
+      return `${lead}`;
+    }
+    return full;
+  });
+  // bare absolute/relative image path as sole token
+  cleaned = cleaned.replace(/(^|\s)(\/?[^\s]+\.(?:png|jpe?g|webp|gif|avif|heic|svg))\b/gi, (full, lead, p) => {
+    const expanded = p.startsWith('~/')
+      ? path.join(os.homedir(), p.slice(2))
+      : path.isAbsolute(p)
+        ? p
+        : path.resolve(p);
+    if (fs.existsSync(expanded)) {
+      paths.push(expanded);
+      return lead;
+    }
+    return full;
+  });
+  return {
+    text: cleaned.replace(/\s+/g, ' ').trim(),
+    attachmentPaths: [...new Set(paths)],
+  };
+}
+
+/**
+ * Validate selected model modalities against attachments.
+ * Fail closed — never silently swap models.
+ */
+export function validateAttachmentModalities({ attachments = [], model = {} } = {}) {
+  const modalities = new Set(model.input_modalities || model.inputModalities || ['text']);
+  const accepted = new Set(
+    model.attachment_policy?.accepted_mime_types
+      || model.acceptedMimeTypes
+      || (modalities.has('image') ? ['image/png', 'image/jpeg', 'image/webp', 'image/gif'] : []),
+  );
+  const images = attachments.filter((a) => a.kind === 'image' || String(a.mimeType || '').startsWith('image/'));
+  if (!images.length) return { ok: true, images: [] };
+  if (!modalities.has('image')) {
+    return {
+      ok: false,
+      code: 'model_rejects_image',
+      message: `${model.id || model.name || 'Selected model'} does not accept image input.`,
+      images,
+    };
+  }
+  for (const img of images) {
+    const mime = String(img.inference?.mimeType || img.mimeType || '');
+    if (accepted.size && mime && !accepted.has(mime) && !accepted.has(img.mimeType)) {
+      return {
+        ok: false,
+        code: 'mime_not_accepted',
+        message: `${model.id || 'Model'} does not accept ${mime || img.mimeType}.`,
+        images,
+      };
+    }
+  }
+  return { ok: true, images };
+}
+
+export function formatAttachmentChip(attachment) {
+  const token = attachment.metadata?.token || attachment.name;
+  const dims = attachment.image
+    ? `${attachment.image.width}×${attachment.image.height}`
+    : '—';
+  const kb = attachment.size < 1024
+    ? `${attachment.size} B`
+    : `${(attachment.size / 1024).toFixed(attachment.size >= 10240 ? 0 : 1)} KB`;
+  return `${token}  ${attachment.mimeType || 'unknown'} · ${dims} · ${kb}`;
+}

package/src/capabilities/repository-snapshot.js

@@ -4,7 +4,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
-import { resolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
+import { tryResolveGitContext } from '../../packages/agentsam-repository/src/git-context.js';
 import { getRepositoryId, tryReadProjectConfig } from '../lib/project-config.js';
 import { buildMerkleTree } from '../../packages/agentsam-repository/src/merkle/index.js';
 import { gitIgnoredPaths } from '../../packages/agentsam-repository/src/merkle/git-ignore.js';
@@ -111,7 +111,23 @@ export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 }
   if (!Number.isInteger(churnDays) || churnDays < 1 || churnDays > 3650) {
     throw new RangeError('churnDays must be an integer from 1..3650');
   }
-  const git = resolveGitContext({ cwd });
+  const requestedRoot = path.resolve(cwd);
+  if (!fs.existsSync(requestedRoot) || !fs.statSync(requestedRoot).isDirectory()) {
+    throw new Error(`repository_root_not_found:${requestedRoot}`);
+  }
+  const resolvedGit = tryResolveGitContext({ cwd: requestedRoot });
+  const git = resolvedGit || {
+    root: requestedRoot,
+    remoteUrl: '',
+    remoteHost: null,
+    repoFullName: null,
+    owner: null,
+    repo: null,
+    revisionSha: null,
+    branch: null,
+    detached: false,
+    dirty: null,
+  };
   const root = git.root;
   const ignored = await gitIgnoredPaths(root);
   const projectConfig = tryReadProjectConfig(root);
@@ -137,6 +153,7 @@ export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 }
     repository: {
       repository_id: repositoryId,
       identity_source: projectRepositoryId ? 'project-config' : knowledge.repository_id ? 'knowledge-config' : portableRepositoryId ? 'git-remote' : 'unresolved',
+      source_kind: resolvedGit ? 'git' : 'filesystem',
       provider,
       full_name: git.repoFullName,
       remote_url: git.remoteUrl || null,

package/src/cli/command-catalog.js

@@ -0,0 +1,138 @@
+/**
+ * CLI command catalog — machine-readable authority for help, assist tips, and dispatch hints.
+ * Alias ≠ authority: skill tips and SAM operation ids live here so help is not a prose-only dump.
+ */
+
+/** @typedef {{ id: string, aliases?: string[], summary: string, topic: string, skill?: string, operation?: string, common?: boolean }} CliCommandEntry */
+
+/** @type {CliCommandEntry[]} */
+export const CLI_COMMAND_CATALOG = Object.freeze([
+  { id: 'help', aliases: ['-h', '--help'], summary: 'Interactive or topic help from this catalog', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'create', summary: 'Scaffold a new AgentSam project from a preset', topic: 'create', skill: 'agentsam-app-fundamentals', common: false },
+  { id: 'add', summary: 'Add an explicit feature/capability selection', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'plugins', summary: 'Install and manage AgentSam plugins', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'dev', summary: 'Run this project’s npm dev script', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'inspect', summary: 'Bounded repository inspect / authority view', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect', common: true },
+  { id: 'capabilities', summary: 'Inspect capability contracts', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'setup', summary: 'Discover → plan → approve → install capabilities (Homebrew-style)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'skills', aliases: ['skill'], summary: 'List or load portable skill instructions', topic: 'create', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'context', summary: 'Git + bridge context from any repo', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'status', summary: 'Account, models, terminal, and live deploy awareness', topic: 'runtime', skill: 'agentsam-progression-guard', common: true },
+  { id: 'db', summary: 'Project-local SQLite status/init', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'models', summary: 'Probe hosted/local model availability', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'providers', summary: 'Configure machine provider credentials', topic: 'start', skill: 'agentsam-app-fundamentals' },
+  { id: 'credentials', aliases: ['credential'], summary: 'Audit credentials, drift, and failure remediation (never prints secrets)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'cheat-sheet', aliases: ['cheatsheet'], summary: 'Organized command groups (gcloud-like)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'env', summary: 'Provider profile / shell loader helpers', topic: 'start', skill: 'agentsam-app-fundamentals' },
+  { id: 'api-key', aliases: ['apikey', 'api-keys'], summary: 'Create/list/rotate AgentSam API keys (aak_*)', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'login', summary: 'Sign in and persist machine-local session', topic: 'start', skill: 'agentsam-app-fundamentals' },
+  { id: 'logout', summary: 'Sign out locally', topic: 'start', skill: 'agentsam-app-fundamentals' },
+  { id: 'whoami', summary: 'Authenticated account + tokenPermissions', topic: 'start', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'resume', summary: 'Resume a saved AgentSam session', topic: 'start', skill: 'agentsam-app-fundamentals' },
+  { id: 'shell', summary: 'Interactive slash-command shell', topic: 'inside', skill: 'agentsam-app-fundamentals' },
+  { id: 'start-local', summary: 'Local PTY WebSocket service', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'ollama', summary: 'Local Ollama setup/status/models', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'tunnel', summary: 'Cloudflare Tunnel via Wrangler', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'connections', aliases: ['connection'], summary: 'Inspect execution connections', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'compute', summary: 'Alias for google-cloud compute/iam helpers', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'google-cloud', aliases: ['gcp', 'gcloud'], summary: 'Google Cloud auth, projects, compute, IAM SAs, billing, doctor', topic: 'runtime', skill: 'agentsam-app-fundamentals', common: true },
+  { id: 'billing', aliases: ['costs'], summary: 'Billing account relationships (not --billing-project)', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'update', summary: 'Component update preview (gcloud-like)', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'deploy', summary: 'Graduate intentionally to cloud', topic: 'runtime', skill: 'agentsam-progression-guard', common: true },
+  { id: 'deploy-receipt', summary: 'Merkle deploy/checkpoint receipts', topic: 'runtime', skill: 'agentsam-progression-guard' },
+  { id: 'cloudflare', aliases: ['cf'], summary: 'Wrangler reads + Worker CPU profiles', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'go', summary: 'Go product discover/build/deploy', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'rust', aliases: ['wasm', 'rapid-rust'], summary: 'Rust/Wasm scaffold, doctor, check, build, dev, explicit deploy', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'mcp', summary: 'MCP server catalog and client adapters', topic: 'runtime', skill: 'agentsam-cloudflare-workers' },
+  { id: 'eval', summary: 'Context fixtures and live eval telemetry', topic: 'runtime', skill: 'agentsam-app-fundamentals' },
+  { id: 'index', summary: 'Plan/run incremental AST (+ optional embeddings)', topic: 'work', skill: 'agentsam-codebaseindex', operation: 'codebaseindex.ingest' },
+  { id: 'search', summary: 'Retrieve indexed code/text', topic: 'work', skill: 'agentsam-codebaseindex' },
+  { id: 'repo', summary: 'Repository snapshot / observations', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'repository.inspect' },
+  { id: 'init', summary: 'Knowledge setup or local scaffold', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'codebaseindex', aliases: ['ingest', 'codebase-index'], summary: 'Guided codebase ingest: materials, allowlist, embeddings, storage', topic: 'work', skill: 'agentsam-codebaseindex', operation: 'codebaseindex.ingest', common: true },
+  { id: 'brand', summary: 'Deterministic brand intelligence', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'brand.scan' },
+  { id: 'plan', summary: 'Composable plans (e.g. brand)', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'security', aliases: ['sca'], summary: 'Dependency + trust-boundary scan', topic: 'work', skill: 'agentsam-progression-guard', operation: 'security.scan', common: true },
+  { id: 'merkle', summary: 'File integrity snapshots and explorer', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'cad', summary: 'Blender/OpenSCAD/FreeCAD CAD tools', topic: 'work', skill: 'agentsam-app-fundamentals', operation: 'cad.blender.inspect' },
+  { id: 'dockerize', summary: 'Build/run supported containers', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'mini', summary: 'Create a small local gadget', topic: 'create', skill: 'agentsam-jr-dev' },
+  { id: 'recon', summary: 'Bounded-worker packets + finding reports', topic: 'work', skill: 'agentsam-app-fundamentals' },
+  { id: 'autorag', summary: 'AutoRAG configure/probe helpers', topic: 'work', skill: 'agentsam-codebaseindex' },
+  { id: 'identity', summary: 'Identity portal, providers, protocol surfaces', topic: 'create', skill: 'agentsam-app-fundamentals' },
+  { id: 'scaffold', summary: 'Generate CMS or worker-api starter', topic: 'create', skill: 'agentsam-jr-dev' },
+  { id: 'goap', summary: 'GOAP blackboard status/plan', topic: 'inside', skill: 'agentsam-app-fundamentals' },
+  { id: 'app', aliases: ['apps'], summary: 'Bundled AgentSam apps launcher', topic: 'create', skill: 'agentsam-app-fundamentals' },
+]);
+
+const byId = new Map();
+for (const entry of CLI_COMMAND_CATALOG) {
+  byId.set(entry.id, entry);
+  for (const alias of entry.aliases || []) byId.set(alias, entry);
+}
+
+/**
+ * @param {string} name
+ * @returns {CliCommandEntry|null}
+ */
+export function getCliCommand(name) {
+  const key = String(name || '').trim().toLowerCase();
+  if (!key) return null;
+  return byId.get(key) || null;
+}
+
+export function listCliCommands(options = {}) {
+  let rows = [...CLI_COMMAND_CATALOG];
+  if (options.topic) rows = rows.filter((r) => r.topic === options.topic);
+  if (options.common) rows = rows.filter((r) => r.common);
+  return rows;
+}
+
+/**
+ * Machine baseline: every command surfaces how to load its skill from inside the CLI.
+ * @param {CliCommandEntry|string} entryOrId
+ * @param {{ write?: (s: string) => void, quiet?: boolean }} [options]
+ */
+export function printAssistTip(entryOrId, options = {}) {
+  if (options.quiet) return;
+  // Never contaminate machine JSON streams.
+  if (options.json || process.argv.includes('--json') || process.argv.includes('--format=json')) return;
+  const entry = typeof entryOrId === 'string' ? getCliCommand(entryOrId) : entryOrId;
+  if (!entry?.skill) return;
+  const write = options.write || ((s) => process.stderr.write(s));
+  const op = entry.operation ? ` · sam.invoke("${entry.operation}")` : '';
+  write(`  tip: use skill ${entry.skill}   (agentsam skills ${entry.skill})${op}\n`);
+}
+
+/**
+ * Suggest close command ids for unknown input.
+ * @param {string} name
+ * @param {number} [limit]
+ */
+export function suggestCliCommands(name, limit = 5) {
+  const q = String(name || '').toLowerCase();
+  if (!q) return listCliCommands({ common: true }).slice(0, limit);
+  return CLI_COMMAND_CATALOG
+    .map((entry) => {
+      const hay = [entry.id, ...(entry.aliases || []), entry.summary].join(' ').toLowerCase();
+      let score = 0;
+      if (entry.id.startsWith(q) || (entry.aliases || []).some((a) => a.startsWith(q))) score += 3;
+      if (hay.includes(q)) score += 1;
+      for (const t of q.split(/[^a-z0-9]+/).filter(Boolean)) {
+        if (hay.includes(t)) score += 1;
+      }
+      return { entry, score };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score || a.entry.id.localeCompare(b.entry.id))
+    .slice(0, limit)
+    .map((x) => x.entry);
+}
+
+export const CLI_HELP_TOPICS = Object.freeze([
+  { id: 'start', label: 'Start / resume', summary: 'Enter AgentSam, resume work, identity, models.' },
+  { id: 'work', label: 'Build / inspect', summary: 'Repository intelligence, ingest, security, brand.' },
+  { id: 'runtime', label: 'Runtime / terminal', summary: 'Local, remote, sandbox, and deployment controls.' },
+  { id: 'inside', label: 'Inside AgentSam', summary: 'Shell and GOAP surfaces.' },
+  { id: 'create', label: 'Create / extend', summary: 'Scaffold, add capabilities, identity, skills.' },
+]);