mouaif 0.3.0

package/src/agentFeatures.js

@@ -0,0 +1,294 @@
+'use strict';
+
+// Agent features — dynamic system context that tells the model which
+// mouaif features are enabled/disabled for the current project and
+// chat session. The model receives a terse summary injected into the
+// upstream message array. A companion tool (`list_features`) lets the
+// model query the full structured feature state at any time, which is
+// especially useful in `very-small` prompt mode.
+//
+// Public surface:
+//   buildFeatureSummary({ chat, projectDir, project, authz, mcpServers })
+//     -> string (system-message content) | null
+//   LIST_FEATURES_SPEC                : tool spec for the list_features tool
+//   dispatchListFeatures(...)         : execute the tool call
+
+const path = require('path');
+
+const TOOL_NAME = 'list_features';
+
+const LIST_FEATURES_SPEC = {
+  type: 'function',
+  function: {
+    name: TOOL_NAME,
+    description: 'Describe every mouaif feature available in this project and their current on/off/ask state. Returns a JSON object with one key per feature family; each value contains the enable state, authorization mode, and a short description.',
+    parameters: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    }
+  }
+};
+
+// buildFeatureSummary({ chat, projectDir, project, authz, mcpServers })
+//
+// Compose a short system message describing which features are
+// available, enabled, and authorized. Returns null when no features
+// are relevant (to avoid injecting an empty message).
+function buildFeatureSummary(opts) {
+  const { chat, projectDir, project, authz, mcpServers } = opts || {};
+  const lines = [];
+  const feat = [];
+
+  // --- Built-in tools ---
+  // shell
+  if (authz && authz.tools && authz.tools.shell) {
+    const s = authz.tools.shell;
+    if (s.mode !== 'off') {
+      feat.push('[shell](off|ask|allow) → ' + s.mode + (s.mode === 'allowlist' ? ' (' + (Array.isArray(s.allowlist) ? s.allowlist.length : 0) + ' patterns)' : ''));
+      // Let the model know which shell dialect runs its commands
+      // (cmd.exe vs a POSIX sh) so it picks the right syntax.
+      try {
+        const shellMod = require('./tools/shell.js');
+        if (typeof shellMod.shellDialectHint === 'function') {
+          feat.push('[shell] ' + shellMod.shellDialectHint());
+        }
+      } catch { /* label is best-effort */ }
+    }
+  }
+  // subagent
+  if (authz && authz.tools && authz.tools.subagent) {
+    const s = authz.tools.subagent;
+    if (s.mode !== 'off') {
+      feat.push('[subagent](off|ask|allow) → ' + s.mode);
+    }
+  }
+  // progress updates
+  if (authz && authz.tools && authz.tools.report_progress) {
+    const s = authz.tools.report_progress;
+    if (s.mode !== 'off') {
+      feat.push('[report_progress](off|ask|allow) → ' + s.mode);
+    }
+  }
+  // ask_user
+  if (authz && authz.tools && authz.tools.ask_user) {
+    const s = authz.tools.ask_user;
+    if (s.mode !== 'off') {
+      feat.push('[ask_user](off|ask) → ' + s.mode);
+    }
+  }
+  // task tool
+  if (authz && authz.tools && authz.tools.task) {
+    const s = authz.tools.task;
+    if (s.mode !== 'off') {
+      feat.push('[task](off|ask|allow) → ' + s.mode);
+    }
+  }
+  // file tools
+  if (authz && authz.tools && authz.tools.file) {
+    const s = authz.tools.file;
+    if (s.mode !== 'off') {
+      feat.push('[file tools](off|ask|allow) → ' + s.mode + (s.mode === 'allowlist' ? ' (' + (Array.isArray(s.allowlist) ? s.allowlist.length : 0) + ' patterns)' : ''));
+    }
+  }
+
+  // app restart
+if (authz && authz.tools && authz.tools.restart_app) {
+const s = authz.tools.restart_app;
+if (s.mode !== 'off') feat.push('[restart app](off|ask|allow) → ' + s.mode + ' — graceful supervisor relaunch from chat');
+}
+// --- MCP servers ---
+if (Array.isArray(mcpServers) && mcpServers.length) {
+
+    // NOTE: the MCP line deliberately carries ONLY the configured server
+    // count — never the live running/stopped status. The feature summary
+    // rides inside the cached system block of Anthropic prompt caching;
+    // a status flip (on-demand start, error, restart) mid-conversation
+    // would change that block and invalidate the entire warm cache for
+    // the rest of the chat. The model can query live status via
+    // list_features / the MCP tools if it actually needs it.
+    feat.push('[MCP] ' + mcpServers.length + ' configured');
+  }
+
+  // --- Agent files ---
+  // Resolve whether agent files are enabled (per-chat -> project -> profile default)
+  let agentFilesEnabled = false;
+  try {
+    const agentFiles = require('./agentFiles.js');
+    agentFilesEnabled = agentFiles.resolveEnabled({ chat, projectDir });
+  } catch { /* safe default */ }
+  if (agentFilesEnabled) {
+    feat.push('[agent files] enabled — AGENTS.md / CLAUDE.md / .github/copilot-instructions.md');
+  }
+
+  // --- Project agents (subagent delegation targets) ---
+  try {
+    const agents = require('./agents.js');
+    const list = agents.list(projectDir);
+    if (list.length) {
+      feat.push('[agents] ' + list.length + ' available — subagent delegation targets');
+    }
+  } catch { /* safe default */ }
+
+  // --- File tagging ---
+  // Tagged files are always injected when the project has tag entries.
+  // We check if any tags are configured.
+  let tagsExist = false;
+  try {
+    const tags = require('./tags.js');
+    const tagList = tags.getTags(projectDir);
+    tagsExist = tagList && typeof tagList === 'object' && Object.keys(tagList).length > 0;
+  } catch { /* safe default */ }
+  if (tagsExist) {
+    feat.push('[file tagging] active — tags found in project');
+  }
+
+  // --- Trace ---
+  const traceOn = chat && chat.trace === true;
+  if (traceOn) {
+    feat.push('[trace] on — events written to .mouaif/traces/');
+  }
+
+  // --- Prompt profile ---
+  let profileId = 'average';
+  try {
+    const promptProfiles = require('./promptProfiles.js');
+    const profile = promptProfiles.resolveProfile({ chat, projectDir });
+    if (profile && profile.id) profileId = profile.id;
+  } catch { /* safe default */ }
+  feat.push('[prompt profile] ' + profileId);
+
+  if (!feat.length) return null;
+
+  lines.push('This mouaif project has these features:');
+  lines.push('');
+  for (const f of feat) lines.push('- ' + f);
+  lines.push('');
+  lines.push('You also have a `list_features` tool available — call it to get the complete structured feature state with every detail.');
+
+  return lines.join('\n');
+}
+
+// dispatchListFeatures(args, opts)
+//
+// Handler for the `list_features` tool call. Returns the full structured
+// feature state as a JSON object so the model can inspect details.
+async function dispatchListFeatures(args, opts) {
+  const chatId = opts && opts.chatId;
+  const projectDir = opts && opts.projectDir;
+  // Load the chat record to inspect trace, agentFiles, promptSize, etc.
+  let chat = opts && opts.chat;
+  if (!chat && projectDir && chatId) {
+    try {
+      const chats = require('./chats.js');
+      chat = chats.getChat(projectDir, chatId);
+    } catch { /* safe default */ }
+  }
+  const result = { ok: true, content: '', result: null };
+
+  const state = {};
+
+  // Built-in tool authorization
+  try {
+    const authz = require('./tools/authorization.js');
+    const authState = authz.getAuthorization(projectDir);
+    const tools = (authState && authState.tools) || {};
+    state.tools = {};
+    for (const name of ['shell', 'subagent', 'file', 'ask_user', 'report_progress', 'task', 'webpreview', 'restart_app']) {
+      const cfg = tools[name] || { mode: 'ask' };
+      state.tools[name] = {
+        mode: cfg.mode || 'ask',
+        allowlist: cfg.allowlist || [],
+        defaultTimeoutMs: cfg.defaultTimeoutMs,
+        maxTimeoutMs: cfg.maxTimeoutMs
+      };
+    }
+    // Surface the interpreter the shell tool runs under, so the model
+    // can pick the right syntax from the structured state too.
+    try {
+      const shellMod = require('./tools/shell.js');
+      const hint = typeof shellMod.shellDialectHint === 'function' ? shellMod.shellDialectHint() : '';
+      if (hint) {
+        state.tools.shell = Object.assign({}, state.tools.shell, {
+          dialect: hint,
+          exe: process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : (process.env.SHELL || '/bin/sh')
+        });
+      }
+    } catch { /* shell module unavailable; keep auth state only */ }
+  } catch (e) {
+    state.tools = { _error: e.message };
+  }
+
+  // MCP servers
+  try {
+    const mcpMod = require('./mcp.js');
+    const serverList = typeof mcpMod.listServers === 'function' ? mcpMod.listServers(projectDir) : [];
+    if (Array.isArray(serverList)) {
+      state.mcp = [];
+      for (const s of serverList) {
+        const entry = { name: s.name, slug: s.slug, status: s.status, tools: s.tools || [] };
+        if (s.authorization) entry.authorization = s.authorization;
+        state.mcp.push(entry);
+      }
+    }
+  } catch (e) {
+    state.mcp = { _error: e.message };
+  }
+
+  // Agent files
+  try {
+    const agentFiles = require('./agentFiles.js');
+    state.agentFiles = {
+      enabled: agentFiles.resolveEnabled({ chat, projectDir }),
+      fileNames: agentFiles.resolveFileNames({ chat, projectDir }),
+      discovered: agentFiles.discover(projectDir).map(f => ({ name: f.name, size: f.size }))
+    };
+  } catch (e) {
+    state.agentFiles = { _error: e.message };
+  }
+
+  // Project agents (subagent delegation targets)
+  try {
+    const agents = require('./agents.js');
+    state.agents = {
+      discovered: agents.list(projectDir).map(a => ({ name: a.name }))
+    };
+  } catch (e) {
+    state.agents = { _error: e.message };
+  }
+
+  // File tagging
+  try {
+    const tags = require('./tags.js');
+    const tagList = tags.getTags(projectDir);
+    state.fileTagging = {
+      active: tagList && typeof tagList === 'object' && Object.keys(tagList).length > 0,
+      count: tagList && typeof tagList === 'object' ? Object.keys(tagList).length : 0
+    };
+  } catch (e) {
+    state.fileTagging = { _error: e.message };
+  }
+
+  // Trace
+  state.trace = chat && chat.trace === true;
+
+  // Prompt profile
+  try {
+    const promptProfiles = require('./promptProfiles.js');
+    const profile = promptProfiles.resolveProfile({ chat, projectDir });
+    state.promptProfile = profile ? { id: profile.id, label: profile.label } : null;
+  } catch (e) {
+    state.promptProfile = null;
+  }
+
+  result.content = JSON.stringify(state, null, 2);
+  result.result = state;
+  return result;
+}
+
+module.exports = {
+  TOOL_NAME,
+  LIST_FEATURES_SPEC,
+  buildFeatureSummary,
+  dispatchListFeatures
+};

package/src/agentFiles.js

@@ -0,0 +1,164 @@
+'use strict';
+
+// Agent files — well-known instruction files at the project root that
+// coding assistants read (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md).
+//
+// When enabled for a chat, the content of every agent file found at the
+// project root is injected into the upstream system context, after the
+// prompt-size profile and before the custom prompt. Each file rides as
+// its own `system` message so the model can see the file boundary.
+//
+// Discovery is read-only: we never create, modify, or delete these files.
+// Missing files are silently skipped. Files larger than MAX_BYTES are
+// truncated so a huge AGENTS.md does not blow the context budget.
+//
+// Public surface:
+//   DEFAULT_AGENT_FILE_NAMES         : ordered list of basenames we look for
+//   MAX_BYTES                        : per-file size cap (default 64 KiB)
+//   discover(projectDir)             -> [{ name, absPath, size }]
+//   load(projectDir)                 -> [{ name, role, content }]
+//   isEnabledForChat(chat)           -> boolean
+//   resolveEnabled({chat, projectDir}) -> boolean
+//   resolveFileNames({chat, projectDir}) -> string[]
+
+const fs = require('fs');
+const path = require('path');
+const settings = require('./settings.js');
+
+// Basenames we look for, in priority order. First match wins per slot;
+// all matches are injected (they are complementary, not exclusive).
+// The project-level `agentFileNames` setting can override this list.
+const DEFAULT_AGENT_FILE_NAMES = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.github/copilot-instructions.md'
+];
+
+// Per-file size cap. Files larger than this are truncated to the cap
+// with a trailing note so the model knows it is not the whole file.
+const MAX_BYTES = 64 * 1024;
+
+// resolveFileNames({ chat, projectDir }) -> string[]
+//
+// Return the list of basenames to look for. Resolution order:
+//   1. project.agentFileNames (array of strings) — explicit override
+//   2. DEFAULT_AGENT_FILE_NAMES
+// The chat record does not carry its own file list; the per-chat toggle
+// is a boolean on/off, not a per-file picker.
+function resolveFileNames({ chat, projectDir }) {
+  void chat; // reserved for future per-chat file lists
+  if (projectDir) {
+    try {
+      const project = settings.getProject(projectDir);
+      if (project && Array.isArray(project.agentFileNames) && project.agentFileNames.length) {
+        return project.agentFileNames.map(String).filter(Boolean);
+      }
+    } catch { /* fall through to default */ }
+  }
+  return DEFAULT_AGENT_FILE_NAMES.slice();
+}
+
+// discover(projectDir, names?) -> [{ name, absPath, size }]
+//
+// Return the agent files that exist at the project root. Missing files
+// are skipped silently. The result is ordered by the names list so the
+// most specific file (AGENTS.md) is first. If no names are given the
+// project-level/default list is used.
+function discover(projectDir, names) {
+  if (!projectDir || typeof projectDir !== 'string') return [];
+  const list = Array.isArray(names) && names.length ? names : resolveFileNames({ projectDir });
+  const out = [];
+  for (const name of list) {
+    const absPath = path.join(projectDir, name);
+    try {
+      const st = fs.statSync(absPath);
+      if (st.isFile()) out.push({ name, absPath, size: st.size });
+    } catch { /* missing or unreadable — skip */ }
+  }
+  return out;
+}
+
+// load(projectDir, names?) -> [{ name, role, content }]
+//
+// Read every discovered agent file and return it as a system-message
+// payload. Files larger than MAX_BYTES are truncated. Unreadable files
+// are skipped. The content is wrapped in a small header so the model
+// knows which file it came from. If no names are given the
+// project-level/default list is used.
+function load(projectDir, names) {
+  const files = discover(projectDir, names);
+  const out = [];
+  for (const f of files) {
+    let text;
+    try {
+      const buf = fs.readFileSync(f.absPath);
+      if (buf.length > MAX_BYTES) {
+        text = buf.slice(0, MAX_BYTES).toString('utf8')
+          + '\n\n[... truncated at ' + MAX_BYTES + ' bytes ...]';
+      } else {
+        text = buf.toString('utf8');
+      }
+    } catch { continue; }
+    if (!text.trim()) continue;
+    out.push({
+      name: f.name,
+      role: 'system',
+      content: 'Project agent instructions from ' + f.name + ':\n\n' + text
+    });
+  }
+  return out;
+}
+
+// isEnabledForChat(chat) -> boolean
+//
+// Per-chat toggle. The chat record carries an `agentFiles` field:
+//   true  -> inject agent files
+//   false -> do not inject
+//   undefined / null -> fall through to the profile default
+// The profile default is: very-small = OFF, average/extensive = ON.
+function isEnabledForChat(chat) {
+  if (!chat || typeof chat !== 'object') return true;
+  if (chat.agentFiles === false) return false;
+  if (chat.agentFiles === true) return true;
+  // No explicit per-chat choice: fall back to the prompt-size profile.
+  // very-small is meant to be the tightest context, so agent files are
+  // off there. average and extensive get them by default.
+  const size = chat.promptSize || 'average';
+  return size !== 'very-small';
+}
+
+// resolveEnabled({ chat, projectDir }) -> boolean
+//
+// Full resolution: project-level gate -> per-chat override -> profile default.
+// The project-level setting is the master switch: if it is explicitly `false`
+// agent files are disabled regardless of the per-chat toggle. The per-chat
+// toggle can only *disable* (set to false) when the project has it on.
+// If neither is explicitly set the profile default applies.
+function resolveEnabled({ chat, projectDir }) {
+  // 1. Project-level master switch
+  if (projectDir) {
+    try {
+      const project = settings.getProject(projectDir);
+      if (project && typeof project.agentFiles === 'boolean') {
+        if (project.agentFiles === false) return false;       // locked off
+        // project is true — per-chat can still override to false
+        if (chat && chat.agentFiles === false) return false;
+        return true;
+      }
+    } catch { /* fall through */ }
+  }
+  // 2. Per-chat explicit (no project-level setting)
+  if (chat && typeof chat.agentFiles === 'boolean') return chat.agentFiles;
+  // 3. Profile default
+  return isEnabledForChat(chat);
+}
+
+module.exports = {
+  DEFAULT_AGENT_FILE_NAMES,
+  MAX_BYTES,
+  discover,
+  load,
+  isEnabledForChat,
+  resolveEnabled,
+  resolveFileNames
+};

package/src/agentSkills.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// Agent Skills-compatible discovery and progressive activation.
+// Format: https://agentskills.io/specification
+
+const fs = require('fs');
+const path = require('path');
+const settings = require('./settings.js');
+const MAX_BYTES = 512 * 1024;
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function parseScalar(raw) {
+  const s = String(raw || '').trim();
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) return s.slice(1, -1);
+  return s;
+}
+
+// Parse the spec's shallow frontmatter fields without adding a YAML runtime.
+// metadata is retained as string pairs; malformed/unsupported YAML is diagnosed.
+function parseSkillFile(text, directoryName) {
+  const diagnostics = [];
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) return { valid: false, diagnostics: ['missing YAML frontmatter'] };
+  const lines = text.split(/\r?\n/);
+  const close = lines.indexOf('---', 1);
+  if (close < 0) return { valid: false, diagnostics: ['unterminated YAML frontmatter'] };
+  const metadata = {};
+  let map = null;
+  for (const line of lines.slice(1, close)) {
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const nested = line.match(/^\s+([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (nested && map) { map[nested[1]] = parseScalar(nested[2]); continue; }
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!m) { diagnostics.push('unsupported YAML line: ' + line.trim()); continue; }
+    if (m[1] === 'metadata' && !m[2]) { metadata.metadata = {}; map = metadata.metadata; continue; }
+    map = null;
+    metadata[m[1]] = parseScalar(m[2]);
+  }
+  const name = metadata.name || '';
+  const description = metadata.description || '';
+  if (!name) diagnostics.push('name is required');
+  if (!description) diagnostics.push('description is required');
+  if (name && (!NAME_RE.test(name) || name.length > 64 || name !== directoryName)) diagnostics.push('name must match its directory and use 1-64 lowercase letters, numbers, or single hyphens');
+  if (description.length > 1024) diagnostics.push('description exceeds 1024 characters');
+  if (metadata.compatibility && metadata.compatibility.length > 500) diagnostics.push('compatibility exceeds 500 characters');
+  const validName = !!name && NAME_RE.test(name) && name.length <= 64 && name === directoryName;
+  const validDescription = !!description && description.length <= 1024;
+  const validCompatibility = !metadata.compatibility || metadata.compatibility.length <= 500;
+  return { valid: validName && validDescription && validCompatibility, name, description, metadata, body: lines.slice(close + 1).join('\n').trim(), diagnostics };
+}
+
+function safeSkillFile(projectDir, root, entry) {
+  const file = path.join(root, entry.name, 'SKILL.md');
+  try {
+    const realRoot = fs.realpathSync(projectDir);
+    const realFile = fs.realpathSync(file);
+    if (realFile !== realRoot && !realFile.startsWith(realRoot + path.sep)) return null;
+    const stat = fs.statSync(realFile);
+    if (!stat.isFile() || stat.size > MAX_BYTES) return null;
+    const text = fs.readFileSync(realFile, 'utf8');
+    const parsed = parseSkillFile(text, entry.name);
+    if (!parsed.valid) return null;
+    return Object.assign({ id: parsed.name, path: path.relative(projectDir, realFile).replace(/\\/g, '/'), absPath: realFile, root: path.dirname(realFile), size: stat.size }, parsed);
+  } catch { return null; }
+}
+
+function discover(projectDir) {
+  if (!projectDir || typeof projectDir !== 'string') return [];
+  const root = path.join(projectDir, '.agents', 'skills');
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  return entries.filter((e) => e.isDirectory()).map((e) => safeSkillFile(projectDir, root, e)).filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// normalizeDisabledSkills(raw) -> Set<string>
+//
+// Both the project and the chat carry a `disabledSkills` list of skill
+// ids/names. Anything that is not a string list is treated as empty so a
+// hand-edited `.mouaif.json` (or a legacy row) can never take discovery down.
+function normalizeDisabledSkills(raw) {
+  if (!Array.isArray(raw)) return new Set();
+  return new Set(raw.map((n) => String(n)).filter(Boolean));
+}
+
+// resolve({ chat, projectDir }) -> {
+//   enabled, projectEnabled, disabled, projectDisabled, chatDisabled, skills
+// }
+//
+// `disabled` is the union used for filtering (catalog + activate_skill).
+// The two halves are kept separate so the chat UI can tell a skill the
+// project switched off (locked, with a reason) from one the user
+// unchecked in this chat (a plain per-chat opt-out).
+function resolve({ chat, projectDir }) {
+let project = {};
+try { project = settings.getProject(projectDir) || {}; } catch { /* defaults */ }
+const projectEnabled = project.skills !== false;
+const enabled = projectEnabled && !(chat && chat.skills === false);
+const projectDisabled = normalizeDisabledSkills(project.disabledSkills);
+const chatDisabled = normalizeDisabledSkills(chat && chat.disabledSkills);
+const disabled = new Set([...projectDisabled, ...chatDisabled]);
+return { enabled, projectEnabled, disabled, projectDisabled, chatDisabled, skills: discover(projectDir) };
+}
+
+function available(projectDir, chat) {
+  const state = resolve({ chat, projectDir });
+  return state.enabled ? state.skills.filter((s) => !state.disabled.has(s.name)) : [];
+}
+
+function catalogMessage(projectDir, chat) {
+  const skills = available(projectDir, chat);
+  if (!skills.length) return '';
+  return 'Available Agent Skills (metadata only):\n' + skills.map((s) => '- ' + s.name + ': ' + s.description).join('\n')
+    + '\nWhen a task matches a skill, call activate_skill with its name before proceeding. Load referenced resources only as needed, relative to the returned skill directory.';
+}
+
+function buildSpec(projectDir, chat) {
+  const names = available(projectDir, chat).map((s) => s.name);
+  if (!names.length) return null;
+  return { type: 'function', function: { name: 'activate_skill', description: 'Load one available Agent Skill when its description matches the task.', parameters: { type: 'object', properties: { name: { type: 'string', enum: names, description: 'Skill name from the available skills catalog.' } }, required: ['name'], additionalProperties: false } } };
+}
+
+function listResources(skill) {
+  const out = [];
+  function walk(dir, depth) {
+    if (depth > 3 || out.length >= 200) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (out.length >= 200) break;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs, depth + 1);
+      else if (entry.isFile() && abs !== skill.absPath) out.push(path.relative(skill.root, abs).replace(/\\/g, '/'));
+    }
+  }
+  walk(skill.root, 0);
+  return out;
+}
+
+function activate(projectDir, chat, name) {
+  const skill = available(projectDir, chat).find((s) => s.name === name);
+  if (!skill) { const e = new Error('skill is unavailable: ' + name); e.code = 'ENO_SKILL'; throw e; }
+  const resources = listResources(skill);
+  const content = '<skill_content name="' + skill.name + '">\n' + skill.body + '\n\nSkill directory: ' + skill.root
+    + '\nRelative paths are relative to this directory.' + (resources.length ? '\nResources (load only when needed):\n' + resources.map((r) => '- ' + r).join('\n') : '') + '\n</skill_content>';
+  return { ok: true, content, result: { name: skill.name, description: skill.description, directory: skill.root, resources, content } };
+}
+
+module.exports = { MAX_BYTES, NAME_RE, parseSkillFile, discover, resolve, available, catalogMessage, buildSpec, activate };