@empirical-gauzza/cli 1.0.9

package/lib/installers/hooks.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log } = require('../ui');
+const { ensureDir, writeFile, readJsonIfExists } = require('../fsUtils');
+
+const CLAUDE_HOOK_SESSION_START_SOURCE = `#!/usr/bin/env node
+'use strict';
+
+var spawnSync = require('child_process').spawnSync;
+
+function commandExists(cmd) {
+  var probe = process.platform === 'win32'
+    ? spawnSync('where', [cmd], { stdio: 'ignore', shell: true })
+    : spawnSync('which', [cmd], { stdio: 'ignore' });
+  return probe.status === 0;
+}
+
+function main() {
+  if (!commandExists('empirical')) {
+    process.exit(0);
+  }
+
+  var result = spawnSync('empirical', [
+    'memory', 'query',
+    '--match', 'project context, conventions, recent decisions, user preferences',
+    '--top-k', '8'
+  ], {
+    encoding: 'utf8',
+    timeout: 10000,
+    shell: process.platform === 'win32'
+  });
+
+  if (!result || result.status !== 0 || !result.stdout) {
+    process.exit(0);
+  }
+
+  var results;
+  try {
+    results = JSON.parse(result.stdout);
+  } catch (e) {
+    process.exit(0);
+  }
+
+  if (!Array.isArray(results) || results.length === 0) {
+    process.exit(0);
+  }
+
+  var lines = results.slice(0, 8).map(function (r) {
+    var category = r && r.category ? r.category : 'memory';
+    var summary = r && r.summary ? r.summary : '';
+    return '- [' + category + '] ' + summary;
+  });
+
+  console.log('Empirical memory context for this session:\\n' + lines.join('\\n'));
+  process.exit(0);
+}
+
+main();
+`;
+
+function getEmpiricalHooksDir() {
+  return path.join(os.homedir(), '.empirical', 'hooks');
+}
+
+function buildHookCommand(scriptPath) {
+  return `"${process.execPath}" "${scriptPath}"`;
+}
+
+function removeEmpiricalHookEntries(entries, scriptPath) {
+  if (!Array.isArray(entries)) return [];
+  return entries
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const filteredHooks = entry.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && h.command.includes(scriptPath))
+      );
+      return { ...entry, hooks: filteredHooks };
+    })
+    .filter((entry) => entry && (!Array.isArray(entry.hooks) || entry.hooks.length > 0));
+}
+
+function installClaudeHooks() {
+  const hooksDir = getEmpiricalHooksDir();
+  ensureDir(hooksDir);
+
+  // Older installs registered a per-turn UserPromptSubmit hook here too. That traded an
+  // unconditional network call on every single prompt for determinism, which is wasteful —
+  // the native empirical-memory plugin now covers ad-hoc reads/writes via
+  // Bash without that per-turn tax. SessionStart remains: one cheap call per session boundary.
+  const userPromptScriptPath = path.join(hooksDir, 'claude-user-prompt-submit.js');
+  const sessionStartScriptPath = path.join(hooksDir, 'claude-session-start.js');
+  writeFile(sessionStartScriptPath, CLAUDE_HOOK_SESSION_START_SOURCE);
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  const settings = readJsonIfExists(settingsPath) || {};
+  if (!settings.hooks || typeof settings.hooks !== 'object') {
+    settings.hooks = {};
+  }
+
+  // Clean up the old per-turn hook entry if a prior install left one behind.
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    settings.hooks.UserPromptSubmit = removeEmpiricalHookEntries(settings.hooks.UserPromptSubmit, userPromptScriptPath);
+    if (settings.hooks.UserPromptSubmit.length === 0) {
+      delete settings.hooks.UserPromptSubmit;
+    }
+  }
+
+  settings.hooks.SessionStart = removeEmpiricalHookEntries(settings.hooks.SessionStart, sessionStartScriptPath);
+  for (const matcher of ['startup', 'resume', 'compact']) {
+    settings.hooks.SessionStart.push({
+      matcher,
+      hooks: [{ type: 'command', command: buildHookCommand(sessionStartScriptPath), timeout: 15 }]
+    });
+  }
+
+  writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+  log('  - Claude SessionStart hook installed for deterministic memory lookups.');
+}
+
+module.exports = {
+  CLAUDE_HOOK_SESSION_START_SOURCE,
+  getEmpiricalHooksDir,
+  buildHookCommand,
+  removeEmpiricalHookEntries,
+  installClaudeHooks
+};

package/lib/installers/nativePlugin.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const { runResolvedCommand, summarizeProcessOutput } = require('../fsUtils');
+
+const EMPIRICAL_PLUGIN_SOURCE = process.env.EMPIRICAL_PLUGIN_SOURCE || 'mattgauzza/empirical-memory-plugin';
+const CORE_PLUGIN_NAME = 'empirical-memory';
+const OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo'];
+
+function runPluginCommand(command, args, options = {}) {
+  return runResolvedCommand(command, args, { stdio: 'inherit', ...options });
+}
+
+function assertPluginInstallSucceeded(agentId, result) {
+  if (result && result.status === 0) return;
+  const detail = result ? summarizeProcessOutput(result) : 'no process result';
+  throw new Error(`${agentId} plugin installation failed.${detail ? ` Details: ${detail}` : ''}`);
+}
+
+function updateOrInstall(agentId, command, updateArgs, installArgs) {
+  const updateResult = runPluginCommand(command, updateArgs);
+  if (updateResult && updateResult.status === 0) return updateResult;
+
+  const installResult = runPluginCommand(command, installArgs);
+  assertPluginInstallSucceeded(agentId, installResult);
+  return installResult;
+}
+
+function normalizePluginNames(pluginNames = [CORE_PLUGIN_NAME]) {
+  const names = Array.isArray(pluginNames) ? pluginNames : [pluginNames];
+  const normalized = [...new Set(names.map(String))];
+  if (!normalized.includes(CORE_PLUGIN_NAME)) normalized.unshift(CORE_PLUGIN_NAME);
+  const invalid = normalized.filter((name) => name !== CORE_PLUGIN_NAME && !OPTIONAL_PLUGIN_NAMES.includes(name));
+  if (invalid.length) throw new Error(`Unsupported Empirical plugin(s): ${invalid.join(', ')}`);
+  return normalized;
+}
+
+function installNativePlugin(agentId, pluginNames = [CORE_PLUGIN_NAME]) {
+  const names = normalizePluginNames(pluginNames);
+  if (agentId === 'claude') {
+    // Marketplace registration is intentionally best-effort: native Claude returns non-zero
+    // when the same Git marketplace is already registered, but the install command is still
+    // authoritative and idempotent.
+    runPluginCommand('claude', ['plugin', 'marketplace', 'add', EMPIRICAL_PLUGIN_SOURCE], { stdio: 'pipe' });
+    for (const name of names) {
+      updateOrInstall(
+        agentId,
+        'claude',
+        ['plugin', 'update', `${name}@empirical-memory`, '--scope', 'user'],
+        ['plugin', 'install', name, '--scope', 'user']
+      );
+    }
+    return;
+  }
+
+  if (agentId === 'codex') {
+    runPluginCommand('codex', ['plugin', 'marketplace', 'add', EMPIRICAL_PLUGIN_SOURCE], { stdio: 'pipe' });
+    // Refresh the Git marketplace snapshot before reinstalling an existing plugin.
+    runPluginCommand('codex', ['plugin', 'marketplace', 'upgrade', 'empirical-memory'], { stdio: 'pipe' });
+    for (const name of names) {
+      const result = runPluginCommand('codex', ['plugin', 'add', `${name}@empirical-memory`]);
+      assertPluginInstallSucceeded(agentId, result);
+    }
+    return;
+  }
+
+  if (agentId === 'copilot') {
+    // Copilot is deprecating direct repository installs. Register the GitHub
+    // marketplace first, then use the marketplace-qualified plugin name.
+    runPluginCommand('copilot', ['plugin', 'marketplace', 'add', EMPIRICAL_PLUGIN_SOURCE], { stdio: 'pipe' });
+    runPluginCommand('copilot', ['plugin', 'marketplace', 'update', 'empirical-memory'], { stdio: 'pipe' });
+    for (const name of names) {
+      const result = runPluginCommand('copilot', ['plugin', 'install', `${name}@empirical-memory`]);
+      assertPluginInstallSucceeded(agentId, result);
+    }
+    return;
+  }
+
+  throw new Error(`Unsupported plugin target: ${agentId}`);
+}
+
+module.exports = {
+  EMPIRICAL_PLUGIN_SOURCE,
+  CORE_PLUGIN_NAME,
+  OPTIONAL_PLUGIN_NAMES,
+  normalizePluginNames,
+  installNativePlugin
+};

package/lib/installers/promptBlocks.js

@@ -0,0 +1,403 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const { log, warn, uiHeader, uiSuccess, uiDim, ask, askYesNo, askWorkflowMultiSelect } = require('../ui');
+const INSTALL_PROMPT_OPTIONS_DEFAULTS = Object.freeze({
+  queryBeforeCodingTask: false,
+  requireMemoryInWorkflows: true,
+  requiredWorkflows: [
+    'research',
+    'debugging',
+    'spec_prd',
+    'status',
+    'handoff',
+    'personal_health',
+    'lead_management',
+    'assistant_ops'
+  ],
+  allowDiscretionaryMemoryUsage: true,
+  stopOnMemoryToolFailure: true,
+  rememberCodingStyle: true,
+  rememberArchitectureDecisions: true,
+  recordWorkHistory: true,
+  recordScarTissue: true,
+  recordTodos: false,
+  storeInstructionArtifacts: false,
+  checkMemoryBeforeAskingContext: true,
+  durableWritesOnly: true
+});
+
+const WORKFLOW_POLICY_OPTIONS = Object.freeze([
+  { id: 'research', label: 'research' },
+  { id: 'debugging', label: 'debugging' },
+  { id: 'spec_prd', label: 'spec/prd' },
+  { id: 'status', label: 'status' },
+  { id: 'handoff', label: 'handoff' },
+  { id: 'personal_health', label: 'personal health' },
+  { id: 'lead_management', label: 'lead management' },
+  { id: 'assistant_ops', label: 'assistant ops' }
+]);
+
+function normalizeRequiredWorkflows(value) {
+  const valid = new Set(WORKFLOW_POLICY_OPTIONS.map((option) => option.id));
+  if (!Array.isArray(value)) {
+    return [...INSTALL_PROMPT_OPTIONS_DEFAULTS.requiredWorkflows];
+  }
+  const normalized = value.filter((entry) => valid.has(entry));
+  return normalized.length ? normalized : [...INSTALL_PROMPT_OPTIONS_DEFAULTS.requiredWorkflows];
+}
+
+function workflowIdsToLabels(workflowIds = []) {
+  const byId = new Map(WORKFLOW_POLICY_OPTIONS.map((option) => [option.id, option.label]));
+  return workflowIds.map((id) => byId.get(id) || id);
+}
+
+function normalizeInstallPromptOptions(options = {}) {
+  return {
+    queryBeforeCodingTask:
+      options.queryBeforeCodingTask !== false,
+    requireMemoryInWorkflows:
+      options.requireMemoryInWorkflows !== false,
+    requiredWorkflows:
+      normalizeRequiredWorkflows(options.requiredWorkflows),
+    allowDiscretionaryMemoryUsage:
+      options.allowDiscretionaryMemoryUsage !== false,
+    stopOnMemoryToolFailure:
+      options.stopOnMemoryToolFailure !== false,
+    rememberCodingStyle:
+      options.rememberCodingStyle !== false,
+    rememberArchitectureDecisions:
+      options.rememberArchitectureDecisions !== false,
+    recordWorkHistory:
+      options.recordWorkHistory !== false,
+    recordScarTissue:
+      options.recordScarTissue !== false,
+    recordTodos:
+      options.recordTodos === true,
+    storeInstructionArtifacts:
+      options.storeInstructionArtifacts === true,
+    checkMemoryBeforeAskingContext:
+      options.checkMemoryBeforeAskingContext !== false,
+    durableWritesOnly:
+      options.durableWritesOnly !== false
+  };
+}
+
+function buildSharedEmpiricalPolicyLines(options = {}) {
+  const policy = normalizeInstallPromptOptions(options);
+  const lines = [];
+
+  if (policy.queryBeforeCodingTask) {
+    lines.push('- Before coding, call `query_memories` once for relevant repo/user context.');
+  }
+  if (policy.requireMemoryInWorkflows) {
+    const workflowLabels = workflowIdsToLabels(policy.requiredWorkflows);
+    lines.push(`- For these workflows (${workflowLabels.join(', ')}), call \`query_memories\` before substantive response.`);
+  }
+  if (policy.allowDiscretionaryMemoryUsage) {
+    lines.push('- Outside required workflows, use Empirical proactively when prior context is likely useful.');
+  } else {
+    lines.push('- Outside required workflows, use Empirical only when explicitly requested by the user.');
+  }
+  if (policy.stopOnMemoryToolFailure) {
+    lines.push('- If Empirical tools fail, stop and report the failure before making code changes.');
+  }
+  lines.push('- If a memory call returns auth/session errors (`Auth required`, `invalid_token`, `Authentication required`, `Transport send error`), treat it as expired MCP auth.');
+  lines.push('- Retry the same MCP tool call once before taking any other action.');
+  lines.push('- If retry fails, refresh Empirical MCP auth for the active client before continuing memory-dependent work:');
+  lines.push('- Codex CLI: run `codex mcp logout empirical` then `codex mcp login empirical`.');
+  lines.push('- Claude Code: run `/mcp`, reconnect/re-authenticate the Empirical server, then retry the failed tool call.');
+  lines.push('- Copilot CLI: complete the MCP OAuth reconnect/sign-in flow for Empirical in Copilot, then retry the failed tool call.');
+  lines.push('- After re-authentication, retry the original tool call once; if it still fails, stop and ask the user to repair MCP auth/connectivity.');
+  lines.push('- If memory conflicts with the latest repo/user instruction, follow repo/user instruction.');
+  if (policy.rememberCodingStyle) {
+    lines.push('- Persist durable coding style preferences and conventions when they are established.');
+  }
+  if (policy.rememberArchitectureDecisions) {
+    lines.push('- Persist durable architecture/design decisions for future sessions.');
+  }
+  if (policy.recordWorkHistory) {
+    lines.push('- After meaningful completed work, record a concise timestamped work-history summary with what changed, why, verification, and any next action.');
+  }
+  if (policy.recordScarTissue) {
+    lines.push('- When a recurring failure, sharp edge, or corrected misconception is discovered, record concise scar-tissue guidance with the symptom, cause, prevention, and verification.');
+  } else {
+    lines.push('- Do not create scar-tissue guidance unless the user explicitly asks for it.');
+  }
+  if (policy.storeInstructionArtifacts) {
+    lines.push('- Query Empirical first for relevant instruction artifacts (AGENTS.md/CLAUDE.md/skills-style guidance).');
+    lines.push('- If task needs exact syntax or implementation details, open the source file directly.');
+    lines.push('- Persist this type of durable instruction context to Empirical for recall: concise rules, conventions, decision summaries, source path, and optional version/hash pointer.');
+    lines.push('- Use update-first writes: when an artifact/topic already exists, update it instead of creating a new memory.');
+    lines.push('- Create a new memory only when materially new (new decision, new version/hash, or new scope).');
+    lines.push('- Apply a soft cap of 1-2 instruction-artifact writes per task; prefer merge/update over additional creates.');
+    lines.push('- Do not store full raw file dumps by default; store concise, durable extracts that are easy to query.');
+  }
+  if (policy.checkMemoryBeforeAskingContext) {
+    lines.push('- Check memory before asking the user to restate prior context.');
+  }
+  lines.push('- Use available Empirical MCP tools when appropriate: record_graph_memory, get_memory, list_memories, query_memories, add_note_by_query, update_memory_by_query, delete_memory_by_query, get_user.');
+  if (policy.durableWritesOnly) {
+    lines.push('- Persist only durable context; never store secrets, tokens, or one-off transient values.');
+  }
+  lines.push('- Keep writes concise, factual, and easy to query.');
+
+  return lines;
+}
+
+function workflowLabelsSummary(options = {}) {
+  const policy = normalizeInstallPromptOptions(options);
+  if (!policy.requireMemoryInWorkflows) {
+    return 'research, debugging, spec/PRD work, status updates, and handoffs';
+  }
+  return workflowIdsToLabels(policy.requiredWorkflows).join(', ');
+}
+
+function buildEmpiricalSkillFrontmatter(options = {}) {
+  return {
+    name: 'empirical-memory',
+    // Keep frontmatter deliberately simple: Copilot's YAML parser rejects an
+    // unquoted colon in a plain scalar, and does not support when_to_use.
+    description: 'Use Empirical CLI and MCP to recall and save durable project context across sessions and projects.'
+  };
+}
+
+function buildEmpiricalSkillBody(options = {}) {
+  const policyLines = buildSharedEmpiricalPolicyLines(options);
+  const workflows = workflowLabelsSummary(options);
+  return `## Empirical Memory - Use It Like grep/view
+
+Use this skill for ${workflows}, whenever prior context may matter, and whenever the user asks to remember, recall, update, or forget information.
+
+Prefer calling the \`empirical\` CLI directly via the available shell over the MCP tools when both are
+available: \`empirical memory query|get|list|record|note|update|delete\`. The CLI doesn't require an
+extra tool-discovery step the way the deferred Empirical MCP tools do. The MCP tools
+(\`get_memory\`, \`list_memories\`, \`query_memories\`, \`record_graph_memory\`, \`add_note_by_query\`, \`update_memory_by_query\`,
+\`delete_memory_by_query\`, \`get_user\`) remain available as a fallback or for structured/graph
+queries the CLI doesn't cover.
+
+### Policy
+${policyLines.join('\n')}
+
+### Authored Skills - push what you write
+- If you author a new \`SKILL.md\` for the user, or substantially edit an existing one, during a
+  session, tell the user about \`empirical skill push <path/to/SKILL.md>\` afterward so the skill
+  can follow them across machines/projects instead of staying local to this one.
+- Offer, don't auto-push: surface the option (or offer to run it) and get the user's
+  confirmation before running \`empirical skill push\`. Do not run it unprompted the moment a new
+  or edited \`SKILL.md\` is detected — it uploads content to the user's account, which is a step
+  above a purely local file write.
+- Run \`empirical doc\` or \`empirical skill push --help\` via the available shell for exact flags/usage.
+
+### Command reference
+Run \`empirical doc memory\` via the available shell for exact flags/usage before guessing syntax.
+`;
+}
+
+function buildEmpiricalSkillMarkdown(options = {}) {
+  const frontmatter = buildEmpiricalSkillFrontmatter(options);
+  const body = buildEmpiricalSkillBody(options);
+  return `---
+name: ${frontmatter.name}
+description: ${frontmatter.description}
+---
+
+${body}`;
+}
+
+function formatPromptOptionSummary(promptOptions) {
+  const entries = [
+    ['Require memory in selected workflows', promptOptions.requireMemoryInWorkflows],
+    ['Allow discretionary memory usage', promptOptions.allowDiscretionaryMemoryUsage],
+    ['Stop on Empirical tool failure', promptOptions.stopOnMemoryToolFailure],
+    ['Store coding style preferences', promptOptions.rememberCodingStyle],
+    ['Store architecture decisions', promptOptions.rememberArchitectureDecisions],
+    ['Record timestamped work history', promptOptions.recordWorkHistory],
+    ['Record scar-tissue guidance', promptOptions.recordScarTissue],
+    ['Enable project-based Todo skill', promptOptions.recordTodos],
+    ['Store/recall instruction artifacts', promptOptions.storeInstructionArtifacts],
+    ['Check memory before asking for context', promptOptions.checkMemoryBeforeAskingContext],
+    ['Store durable context only', promptOptions.durableWritesOnly]
+  ];
+  const lines = entries
+    .map(([label, enabled]) => `  ${enabled ? '[x]' : '[ ]'} ${label}`)
+    .join('\n');
+  const workflowLine = `  [${promptOptions.requireMemoryInWorkflows ? 'x' : ' '}] Required workflows: ${workflowIdsToLabels(promptOptions.requiredWorkflows).join(', ')}`;
+  return `${lines}\n${workflowLine}`;
+}
+
+async function collectInstallerPromptOptions() {
+  if (!process.stdin.isTTY) {
+    return {
+      savePolicy: true,
+      promptOptions: { ...INSTALL_PROMPT_OPTIONS_DEFAULTS }
+    };
+  }
+
+  const home = os.homedir();
+  log(uiHeader('Global instruction files'));
+  log(`  - Copilot: ${path.join(home, '.copilot', 'copilot-instructions.md')}`);
+  log(`  - Codex: ${path.join(home, '.codex', 'AGENTS.md')}`);
+  log(`  - Claude: ${path.join(home, '.claude', 'CLAUDE.md')}`);
+  log('');
+
+  const savePolicy = await askYesNo(
+    'Save these personalized Empirical behavior preferences for native skills?',
+    true
+  );
+  log('');
+  if (!savePolicy) {
+    log(uiSuccess('Personalized behavior policy not saved; native skills will use safe defaults.'));
+    log('');
+    return {
+      savePolicy: false,
+      promptOptions: { ...INSTALL_PROMPT_OPTIONS_DEFAULTS }
+    };
+  }
+
+  log(uiHeader('Empirical policy setup'));
+  log(uiDim('Answer a few questions to configure native Empirical skills.'));
+  log('');
+
+  const requireMemoryInWorkflows = await askYesNo(
+    'Require Empirical memory-first behavior in specific workflows?',
+    true
+  );
+  let requiredWorkflows = [...INSTALL_PROMPT_OPTIONS_DEFAULTS.requiredWorkflows];
+  if (requireMemoryInWorkflows) {
+    log('');
+    requiredWorkflows = await askWorkflowMultiSelect(
+      'Which workflows should require memory-first behavior? (all preselected)',
+      WORKFLOW_POLICY_OPTIONS,
+      INSTALL_PROMPT_OPTIONS_DEFAULTS.requiredWorkflows
+    );
+  }
+  const allowDiscretionaryMemoryUsage = await askYesNo(
+    'Allow discretionary Empirical use outside required workflows?',
+    true
+  );
+  const stopOnMemoryToolFailure = await askYesNo(
+    'If Empirical tools fail, should the agent stop before code changes?',
+    true
+  );
+  const rememberCodingStyle = await askYesNo(
+    'Do you want Empirical to store coding style preferences?',
+    true
+  );
+  const rememberArchitectureDecisions = await askYesNo(
+    'Do you want Empirical to store architecture/design decisions?',
+    true
+  );
+  const recordWorkHistory = await askYesNo(
+    'Should Empirical record concise timestamped summaries of completed work for future agents?',
+    true
+  );
+  const recordScarTissue = await askYesNo(
+    'Should Empirical record recurring failure patterns and prevention guidance (scar tissue) for future agents?',
+    true
+  );
+  const recordTodos = await askYesNo(
+    'Install the project-based Todo skill for actionable follow-ups?',
+    false
+  );
+  const storeInstructionArtifacts = await askYesNo(
+    'Store and recall instruction artifacts (AGENTS.md/CLAUDE.md/skills-style rules) in Empirical?',
+    false
+  );
+  const checkMemoryBeforeAskingContext = await askYesNo(
+    'Should agents check memory before asking you to restate context?',
+    true
+  );
+  const durableWritesOnly = await askYesNo(
+    'Restrict writes to durable context only (never secrets/tokens/transient values)?',
+    true
+  );
+
+  const promptOptions = normalizeInstallPromptOptions({
+    queryBeforeCodingTask: false,
+    requireMemoryInWorkflows,
+    requiredWorkflows,
+    allowDiscretionaryMemoryUsage,
+    stopOnMemoryToolFailure,
+    rememberCodingStyle,
+    rememberArchitectureDecisions,
+    recordWorkHistory,
+    recordScarTissue,
+    recordTodos,
+    storeInstructionArtifacts,
+    checkMemoryBeforeAskingContext,
+    durableWritesOnly
+  });
+
+  log('');
+  log(uiSuccess('Policy profile captured.'));
+  log(formatPromptOptionSummary(promptOptions));
+  log('');
+
+  return {
+    savePolicy: true,
+    promptOptions
+  };
+}
+
+function buildSkillFileContent({ mcpEnabled = false } = {}) {
+  if (mcpEnabled) {
+    return `# Empirical Memory Skill
+
+Empirical memory is installed via MCP. Use MCP tools as the primary interface.
+
+## MCP tools (primary)
+
+- \`query_memories\` — search memories by natural language
+- \`record_graph_memory\` — save a new memory
+- \`add_note_by_query\` — append a note to an existing memory
+- \`update_memory_by_query\` — update fields on an existing memory
+- \`delete_memory_by_query\` — delete a memory by query
+- \`get_user\` — get current user identity and workspace
+
+## CLI fallback (when MCP is unavailable)
+
+    empirical doc                  List all available topics
+    empirical doc <topic>          Load full CLI instructions for that topic
+    empirical doctor               Verify connectivity and token status
+`;
+  }
+
+  return `# Empirical Memory Skill
+
+Empirical memory is installed in this environment.
+
+## Discover available commands
+
+    empirical doc                  List all available topics
+    empirical doc <topic>          Load full instructions for that topic
+    empirical doctor               Verify connectivity and token status
+
+## Topics
+
+    memory      Query, record, update, and delete memories
+    user        Get current user identity
+    workspace   List and switch workspaces
+    auth        Token types, bootstrap, and refresh
+    agents      Integration modes and SKILL file paths
+    install     Install Empirical for Codex / Copilot / Claude Code
+
+Load any topic on demand — for example: \`empirical doc memory\` or \`empirical doc user\`.
+`;
+}
+
+module.exports = {
+  INSTALL_PROMPT_OPTIONS_DEFAULTS,
+  WORKFLOW_POLICY_OPTIONS,
+  normalizeRequiredWorkflows,
+  workflowIdsToLabels,
+  normalizeInstallPromptOptions,
+  buildSharedEmpiricalPolicyLines,
+  workflowLabelsSummary,
+  buildEmpiricalSkillFrontmatter,
+  buildEmpiricalSkillBody,
+  buildEmpiricalSkillMarkdown,
+  formatPromptOptionSummary,
+  collectInstallerPromptOptions
+};