@haposoft/cafekit 0.9.6 → 0.10.0

package/bin/phases/copy-payload.js

@@ -0,0 +1,220 @@
+/**
+ * Phase: copy payload (skills, agents, references, scripts, commands).
+ *
+ * Ported from the original copyPlatformFiles(), but every write goes through
+ * the ownership-aware writer so re-runs update pristine files and preserve
+ * user-modified ones instead of blindly skipping/overwriting.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  PLATFORMS,
+  DEPENDENCY_TEMPLATES,
+  isClaudeCompatibleRuntime,
+  getRuntimeSupportTargetDir,
+  getCopyOptions
+} = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const {
+  convertOpenCodeAgentContent,
+  convertOpenCodeCommandContent
+} = require('../lib/opencode-install');
+
+const SRC = path.join(__dirname, '../../src');
+
+/**
+ * Spec command files installed for a platform. Claude ships spec-* commands;
+ * OpenCode generates its own command wrappers elsewhere.
+ */
+function getPlatformSpecFiles(platformKey, ctx) {
+  if (platformKey === 'claude') {
+    const manifestCommands = ctx.manifest?.commands?.core;
+    if (Array.isArray(manifestCommands)) {
+      return manifestCommands;
+    }
+    return [
+      'spec-init.md',
+      'spec-requirements.md',
+      'spec-design.md',
+      'spec-validate.md',
+      'spec-tasks.md',
+      'spec-status.md',
+      'code.md',
+      'test.md',
+      'docs.md'
+    ];
+  }
+  return [];
+}
+
+/** DEPENDENCY_TEMPLATES is empty by default; kept for parity/extensibility. */
+function ensureWorkflowDependencies(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const commandTemplates = DEPENDENCY_TEMPLATES.commands[platformKey] || {};
+  Object.entries(commandTemplates).forEach(([fileName, content]) => {
+    if (!content) return;
+    const dest = path.join(platform.commandsDir, fileName);
+    if (!ctx.dryRun) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, content, 'utf8');
+      tracker.record(dest);
+    }
+    report(ctx, 'created', `dependency: ${fileName}`);
+  });
+}
+
+function copyPlatformFiles(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const platformFolder = platform.folder;
+
+  // For OpenCode, text bodies are path-normalized (.claude → .opencode, etc.).
+  const bodyTransform = platformKey === 'opencode'
+    ? getCopyOptions('opencode', {}).transform
+    : undefined;
+
+  const skillsSourceDir = path.join(SRC, 'claude/skills');
+  const agentsSourceDir = path.join(SRC, platform.sourceDir, 'agents');
+
+  if (!ctx.dryRun) {
+    fs.mkdirSync(platform.skillsDir, { recursive: true });
+    fs.mkdirSync(platform.agentsDir, { recursive: true });
+  }
+
+  // ── Skills ──────────────────────────────────────────────
+  if (fs.existsSync(skillsSourceDir)) {
+    const specSkillSource = path.join(skillsSourceDir, 'specs');
+    const specSkillDest = path.join(platform.skillsDir, 'specs');
+
+    if (fs.existsSync(specSkillSource)) {
+      const agg = copyManagedTree({
+        src: specSkillSource, dest: specSkillDest, platformFolder, ctx, tracker, transform: bodyTransform
+      });
+      ctx.results.installedSkills++;
+      report(ctx, treeAction(agg), 'Skill: specs');
+    }
+
+    // Keep spec templates in sync (Claude command runtime reads these).
+    if (platformKey === 'claude') {
+      const legacyInitTemplate = path.join(platform.skillsDir, 'specs', 'templates', 'init.json');
+      if (fs.existsSync(legacyInitTemplate)) {
+        if (!ctx.dryRun) fs.rmSync(legacyInitTemplate, { force: true });
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed legacy template: ${legacyInitTemplate}`);
+        ctx.results.updated++;
+      }
+
+      const specTemplates = [
+        'spec-state.json',
+        'requirements-init.md',
+        'requirements.md',
+        'design.md',
+        'research.md',
+        'task.md'
+      ];
+
+      specTemplates.forEach((fileName) => {
+        const src = path.join(specSkillSource, 'templates', fileName);
+        const dest = path.join(platform.skillsDir, 'specs', 'templates', fileName);
+        const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker });
+        report(ctx, action, `template: ${fileName}`);
+      });
+    }
+
+    // Additional required skills.
+    let requiredSkills = [];
+    if (isClaudeCompatibleRuntime(platformKey)) {
+      requiredSkills = ctx.manifest?.skills?.required || [];
+    }
+    requiredSkills
+      .filter((skillName) => skillName !== 'specs')
+      .forEach((skillName) => {
+        const skillSource = path.join(skillsSourceDir, skillName);
+        const skillDest = path.join(platform.skillsDir, skillName);
+        if (fs.existsSync(skillSource)) {
+          const agg = copyManagedTree({
+            src: skillSource, dest: skillDest, platformFolder, ctx, tracker, transform: bodyTransform
+          });
+          ctx.results.installedSkills++;
+          report(ctx, treeAction(agg), `Skill: ${skillName}`);
+        } else {
+          report(ctx, 'missing', `skill: ${skillName}`);
+        }
+      });
+  }
+
+  // ── Agents + references + scripts ───────────────────────
+  if (isClaudeCompatibleRuntime(platformKey)) {
+    if (fs.existsSync(agentsSourceDir)) {
+      const requiredAgents = ctx.manifest?.agents?.required || [
+        'tester.md', 'code-reviewer.md', 'fullstack-developer.md', 'debugger.md'
+      ];
+      const agentTransform = platformKey === 'opencode'
+        ? (content, src) => convertOpenCodeAgentContent(content, path.basename(src))
+        : undefined;
+
+      requiredAgents.forEach((fileName) => {
+        const src = path.join(agentsSourceDir, fileName);
+        const dest = path.join(platform.agentsDir, fileName);
+        const { action } = writeManagedFile({
+          src, dest, platformFolder, ctx, tracker, transform: agentTransform
+        });
+        report(ctx, action, `agent: ${fileName}`);
+      });
+
+      const refsSource = path.join(SRC, platform.sourceDir, 'references');
+      if (fs.existsSync(refsSource)) {
+        const refsDest = getRuntimeSupportTargetDir(platformKey, 'references');
+        const agg = copyManagedTree({
+          src: refsSource, dest: refsDest, platformFolder, ctx, tracker, transform: bodyTransform
+        });
+        report(ctx, treeAction(agg), 'Agent reference manuals');
+      }
+    } else {
+      report(ctx, 'missing', `agents: ${platform.agentsDir}`);
+    }
+
+    const scriptsSourceDir = path.join(SRC, 'claude/scripts');
+    if (fs.existsSync(scriptsSourceDir)) {
+      const scriptsDest = getRuntimeSupportTargetDir(platformKey, 'scripts');
+      const agg = copyManagedTree({
+        src: scriptsSourceDir, dest: scriptsDest, platformFolder, ctx, tracker, transform: bodyTransform
+      });
+      report(ctx, treeAction(agg), 'Native scripts');
+    }
+  }
+
+  ensureWorkflowDependencies(ctx, platformKey);
+
+  // ── Commands ────────────────────────────────────────────
+  const sourceSubdir = platform.sourceSubdir || 'commands';
+  const commandsSourceDir = path.join(SRC, platform.sourceDir, sourceSubdir);
+  const specFiles = getPlatformSpecFiles(platformKey, ctx);
+
+  specFiles.forEach((file) => {
+    const src = path.join(commandsSourceDir, file);
+    const dest = path.join(platform.commandsDir, file);
+    if (!fs.existsSync(src)) {
+      ctx.ui.error(`Source file not found: ${file}`);
+      ctx.results.errors++;
+      return;
+    }
+    const cmdTransform = (content, s) => {
+      let c = content.replace(/\{\{SKILLS_DIR\}\}/g, platform.skillsRef);
+      if (platformKey === 'opencode') {
+        c = convertOpenCodeCommandContent(c, path.basename(s));
+      }
+      return c;
+    };
+    const { action } = writeManagedFile({
+      src, dest, platformFolder, ctx, tracker, transform: cmdTransform
+    });
+    report(ctx, action, file);
+  });
+
+  return ctx;
+}
+
+module.exports = { copyPlatformFiles, getPlatformSpecFiles };

package/bin/phases/opencode-runtime.js

@@ -0,0 +1,38 @@
+/**
+ * Phase: OpenCode runtime installation.
+ *
+ * Delegates to the existing opencode-install.js module (kept as-is) in the
+ * exact original order. These writers manage their own files (plugins, command
+ * templates, AGENTS.md, opencode.json) and honor the legacy `upgrade` option.
+ * In dry-run we skip them and report intent, since they are not dry-run aware.
+ */
+
+const {
+  copyOpenCodeSharedRuntimeFiles,
+  copyOpenCodePlugins,
+  copyOpenCodeCommandTemplates,
+  copyOpenCodeAgentsMdFile,
+  mergeOpenCodeConfig
+} = require('../lib/opencode-install');
+const { copyRulesDirectory } = require('./claude-runtime');
+
+function installOpenCodeRuntime(ctx, platformKey) {
+  if (platformKey !== 'opencode') return;
+
+  if (ctx.dryRun) {
+    ctx.ui.detail('  → [dry-run] OpenCode runtime (plugins, command templates, AGENTS.md, opencode.json) would be installed');
+    // rules/ is dry-run aware; still preview it.
+    copyRulesDirectory(ctx, platformKey);
+    return;
+  }
+
+  const { results, options } = ctx;
+  copyOpenCodeSharedRuntimeFiles(platformKey, results, options);
+  copyOpenCodePlugins(platformKey, results, options);
+  copyOpenCodeCommandTemplates(platformKey, results, options);
+  copyOpenCodeAgentsMdFile(platformKey, results, options);
+  copyRulesDirectory(ctx, platformKey);
+  mergeOpenCodeConfig(platformKey, results);
+}
+
+module.exports = { installOpenCodeRuntime };

package/bin/phases/post-install.js

@@ -0,0 +1,141 @@
+/**
+ * Phase: post-install runtime configuration.
+ *
+ * OpenCode model, optional Gemini CLI install + API key, and addressing config.
+ * Interactive prompts use ctx.ui (clack); in non-interactive/dry-run they are
+ * skipped via fallbacks so spawned/CI runs never hang. Writes (.env, CLAUDE.md,
+ * opencode.json) happen only when a value is actually provided.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { PLATFORMS } = require('../lib/context');
+const { setupOpenCodeModel } = require('../lib/opencode-install');
+
+function checkGeminiCLI() {
+  try {
+    execSync('which gemini', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function installGeminiCLI(ctx) {
+  ctx.ui.startSpinner('Installing gemini-cli...');
+  try {
+    execSync('npm install -g @google/gemini-cli', { stdio: 'ignore' });
+    ctx.ui.stopSpinner('gemini-cli installed');
+    return true;
+  } catch {
+    ctx.ui.stopSpinner('Could not install gemini-cli automatically');
+    ctx.ui.warn('Run manually: npm install -g @google/gemini-cli');
+    return false;
+  }
+}
+
+function configureGeminiKey(ctx, apiKey, platforms) {
+  const envBody = `GEMINI_API_KEY=${apiKey}\nVISUAL_MODEL=gemma-4-31b-it\nSEARCH_MODEL=gemini-2.5-pro\n`;
+  const targets = platforms.filter((key) => PLATFORMS[key]).map((key) => PLATFORMS[key].folder);
+  if (targets.length === 0) targets.push('.claude');
+
+  for (const folder of targets) {
+    try {
+      const targetDir = path.join(process.cwd(), folder);
+      if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+      fs.writeFileSync(path.join(targetDir, '.env'), envBody, { mode: 0o600 });
+      ctx.ui.success(`Gemini API key stored in ${folder}/.env (0600)`);
+    } catch (error) {
+      ctx.ui.error(`Failed to configure Gemini API key: ${error.message}`);
+    }
+  }
+}
+
+async function setupGemini(ctx) {
+  if (checkGeminiCLI()) {
+    ctx.ui.info('gemini-cli already installed');
+  } else if (ctx.interactive) {
+    const yes = await ctx.ui.confirm(
+      { message: 'Install gemini-cli? (enables hapo:inspect ext mode)', initialValue: false },
+      false
+    );
+    if (yes === true) installGeminiCLI(ctx);
+  }
+
+  const apiKey = await ctx.ui.text(
+    { message: 'Gemini API key (Enter to skip)', placeholder: 'aistudio.google.com/apikey' },
+    ''
+  );
+  if (apiKey && typeof apiKey === 'string' && apiKey.trim()) {
+    configureGeminiKey(ctx, apiKey.trim(), ctx.platforms);
+  }
+}
+
+function configureAddressing(ctx, userAddress) {
+  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdFile)) {
+    ctx.ui.warn('CLAUDE.md not found at project root; skipped addressing');
+    return;
+  }
+
+  let content = fs.readFileSync(claudeMdFile, 'utf8');
+  const addressingSection = `## Addressing (Context Overflow Indicator)
+
+The AI always addresses the user as "${userAddress}" throughout the conversation. If the AI stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider \`/clear\`.`;
+
+  // Idempotent: replace existing section (shared marker) or append.
+  const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
+  content = regex.test(content)
+    ? content.replace(regex, addressingSection)
+    : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
+
+  fs.writeFileSync(claudeMdFile, content, 'utf8');
+  ctx.ui.success(`Addressing set: AI will call you "${userAddress}"`);
+}
+
+async function setupAddressing(ctx) {
+  if (!ctx.platforms.includes('claude')) return;
+
+  const answer = await ctx.ui.text(
+    { message: 'How should the AI address you? (e.g. boss, sir — Enter to skip)', placeholder: 'Enter to skip' },
+    ''
+  );
+  if (ctx.ui.isCancel(answer)) return;
+  const userAddress = (answer || '').trim();
+  if (!userAddress) return;
+
+  if (/[^a-zA-ZÀ-ỹ\s]/.test(userAddress)) {
+    ctx.ui.warn('Invalid input (letters only); skipped addressing');
+    return;
+  }
+  configureAddressing(ctx, userAddress);
+}
+
+/** Run the post-install configuration sequence. */
+async function runPostInstall(ctx) {
+  if (ctx.dryRun) {
+    ctx.ui.info('[dry-run] Skipping OpenCode model / Gemini / addressing setup');
+    return ctx;
+  }
+
+  // OpenCode model uses its own readline; only run it when it won't block:
+  // interactive, or an env override is present (which it reads without prompting).
+  const hasModelEnv = Boolean(process.env.OPENCODE_MODEL || process.env.OPENCODE_DEFAULT_MODEL);
+  if (ctx.platforms.includes('opencode') && (ctx.interactive || hasModelEnv)) {
+    await setupOpenCodeModel(ctx.platforms, ctx.results);
+  }
+
+  await setupGemini(ctx);
+  await setupAddressing(ctx);
+
+  // Re-record CLAUDE.md baseline so the installer-managed file (template +
+  // addressing) stays "pristine" and keeps receiving upstream updates.
+  if (ctx.platforms.includes('claude') && ctx.trackers.claude && fs.existsSync('CLAUDE.md')) {
+    ctx.trackers.claude.record('CLAUDE.md');
+    ctx.trackers.claude.write();
+  }
+  return ctx;
+}
+
+module.exports = { checkGeminiCLI, configureGeminiKey, configureAddressing, runPostInstall };

package/bin/phases/report.js

@@ -0,0 +1,66 @@
+/**
+ * Shared reporting helper for install phases.
+ *
+ * Maps an ownership-writer action to a UI update + results counter so every
+ * phase reports outcomes consistently. Routine create/update lines go to
+ * ctx.ui.detail (ephemeral spinner progress when interactive; plain log when
+ * not). Preserved/missing are surfaced more prominently.
+ */
+
+const SYMBOL = {
+  created: '✓',
+  updated: '↻',
+  unchanged: '→',
+  preserved: '⊘',
+  missing: '⚠'
+};
+
+/**
+ * Report a single file/group outcome.
+ *
+ * @param {object} ctx     run context (ui + results + dryRun)
+ * @param {string} action  'created'|'updated'|'unchanged'|'preserved'|'missing'
+ * @param {string} label   human label, e.g. "Skill: specs"
+ */
+function report(ctx, action, label) {
+  const prefix = ctx.dryRun ? '[dry-run] ' : '';
+  const sym = SYMBOL[action] || ' ';
+  const r = ctx.results;
+
+  switch (action) {
+    case 'created':
+      ctx.ui.detail(`  ${sym} ${prefix}${label}`);
+      r.copied++;
+      break;
+    case 'updated':
+      ctx.ui.detail(`  ${sym} ${prefix}${label}`);
+      r.updated++;
+      break;
+    case 'unchanged':
+      r.unchanged++;
+      break;
+    case 'preserved':
+      ctx.ui.detail(`  ${sym} ${prefix}preserved (user-modified): ${label}`);
+      r.preserved++;
+      break;
+    case 'missing':
+      ctx.ui.warn(`${prefix}Missing: ${label}`);
+      r.missingDependencies++;
+      break;
+    default:
+      break;
+  }
+}
+
+/**
+ * Pick the dominant action for a tree-copy aggregate, for a single summary line.
+ * created wins over updated wins over preserved wins over unchanged.
+ */
+function treeAction(agg) {
+  if (agg.created > 0) return 'created';
+  if (agg.updated > 0) return 'updated';
+  if (agg.preserved > 0) return 'preserved';
+  return 'unchanged';
+}
+
+module.exports = { SYMBOL, report, treeAction };

package/bin/phases/root-config.js

@@ -0,0 +1,49 @@
+/**
+ * Phase: root project configuration (.gitignore).
+ *
+ * Ensures the root .gitignore carries CafeKit-managed patterns, including the
+ * new install backup dir and lock file so they never get committed. Honors dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureGitignore(ctx) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const header = '# CafeKit / Ecosystem';
+  const patterns = [
+    'specs/_shared/',
+    'plans/',
+    '!plans/templates/',
+    '.cafekit-backup/',
+    '.cafekit.lock'
+  ];
+  const prefix = ctx.dryRun ? '[dry-run] ' : '';
+
+  if (!fs.existsSync(gitignorePath)) {
+    const content = ['# Git Ignore', '', header, ...patterns, ''].join('\n');
+    if (!ctx.dryRun) fs.writeFileSync(gitignorePath, content, 'utf8');
+    ctx.ui.detail(`  ✓ ${prefix}.gitignore created at root`);
+    ctx.results.copied++;
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n').map((l) => l.trim());
+  const missing = patterns.filter((p) => !lines.includes(p));
+
+  if (missing.length > 0) {
+    let newContent = content;
+    if (!newContent.endsWith('\n')) newContent += '\n';
+    if (!content.includes(header)) newContent += `\n${header}\n`;
+    newContent += missing.join('\n') + '\n';
+    if (!ctx.dryRun) fs.writeFileSync(gitignorePath, newContent, 'utf8');
+    ctx.ui.detail(`  ↻ ${prefix}.gitignore updated: added ${missing.join(', ')}`);
+    ctx.results.updated++;
+  } else {
+    ctx.ui.detail(`  → ${prefix}.gitignore already up to date`);
+    ctx.results.skipped++;
+  }
+}
+
+module.exports = { ensureGitignore };

package/bin/phases/select-platform.js

@@ -0,0 +1,94 @@
+/**
+ * Phase: platform detection + selection.
+ *
+ * Resolves which platforms to install for: auto-detect existing folders, or
+ * prompt (clack) when interactive. In non-interactive mode it uses detection
+ * only and defaults to Claude when nothing is found — never blocks on input.
+ * Sets ctx.platforms, or ctx.cancelled if the user backs out.
+ */
+
+const {
+  PLATFORMS,
+  detectPlatforms,
+  getPlatformKeys,
+  warnLegacyClaudeFolder
+} = require('../lib/context');
+
+/** clack select: which platform(s) to install for. */
+async function promptPlatformSelection(ctx) {
+  const options = [
+    ...getPlatformKeys().map((key) => ({
+      value: [key],
+      label: PLATFORMS[key].name,
+      hint: `${PLATFORMS[key].folder}/`
+    })),
+    { value: getPlatformKeys(), label: 'All platforms' }
+  ];
+  const r = await ctx.ui.select(
+    { message: 'Select which platform(s) to install for', options },
+    []
+  );
+  if (ctx.ui.isCancel(r)) return [];
+  return r;
+}
+
+/** clack confirm: install for all detected platforms? */
+async function confirmAllDetected(ctx, detected) {
+  const names = detected.map((key) => PLATFORMS[key].name).join(', ');
+  const r = await ctx.ui.confirm(
+    { message: `Install for all detected platforms? (${names})`, initialValue: true },
+    true
+  );
+  if (ctx.ui.isCancel(r)) return false;
+  return r;
+}
+
+/**
+ * Resolve ctx.platforms via detection + prompts. Sets ctx.cancelled on backout.
+ */
+async function resolvePlatforms(ctx) {
+  let platforms = detectPlatforms();
+
+  if (platforms.length === 0) {
+    if (ctx.interactive) {
+      platforms = await promptPlatformSelection(ctx);
+      if (platforms.length === 0) {
+        ctx.ui.outro('Installation cancelled.');
+        ctx.cancelled = true;
+        return ctx;
+      }
+    } else {
+      // Non-interactive with nothing detected → sensible default, never block.
+      platforms = ['claude'];
+      ctx.ui.info('No platform detected; defaulting to Claude Code (.claude/).');
+    }
+  } else if (platforms.length > 1 && ctx.interactive) {
+    const proceed = await confirmAllDetected(ctx, platforms);
+    if (!proceed) {
+      platforms = await promptPlatformSelection(ctx);
+      if (platforms.length === 0) {
+        ctx.ui.outro('Installation cancelled.');
+        ctx.cancelled = true;
+        return ctx;
+      }
+    }
+  }
+
+  ctx.platforms = platforms;
+
+  const platformNames = platforms.map((key) => PLATFORMS[key].name).join(', ');
+  ctx.ui.info(`Installing for: ${platformNames}`);
+  warnLegacyClaudeFolder(platforms);
+
+  if (ctx.options.forceOverwrite) {
+    ctx.ui.info('Mode: force-overwrite (replace user-modified files; backup kept)');
+  } else if (ctx.dryRun) {
+    ctx.ui.info('Mode: dry-run (preview only, no changes written)');
+  } else {
+    ctx.ui.info('Mode: install/update (selective; preserves user-modified files)');
+  }
+
+  return ctx;
+}
+
+module.exports = { promptPlatformSelection, resolvePlatforms };

package/bin/phases/summary.js

@@ -0,0 +1,54 @@
+/**
+ * Phase: final summary report.
+ *
+ * Renders install stats (incl. selective-merge counters) + next steps through
+ * ctx.ui, so it appears as a framed clack note/outro when interactive and as
+ * plain text otherwise.
+ */
+
+const { PLATFORMS, packageJson } = require('../lib/context');
+
+function printSummary(ctx) {
+  const { results, platforms, options, ui } = ctx;
+
+  const stats = [
+    `Copied:      ${results.copied}`,
+    `Updated:     ${results.updated}`,
+    `Unchanged:   ${results.unchanged}`,
+    `Preserved:   ${results.preserved}`,
+    `Skills:      ${results.installedSkills > 0 ? 'yes' : 'no'}`,
+    `CafeKit Version: ${packageJson.version}`,
+    results.missingDependencies > 0 ? `Missing:     ${results.missingDependencies}` : null,
+    results.errors > 0 ? `Errors:      ${results.errors}` : null
+  ].filter(Boolean).join('\n');
+
+  ui.note(stats, ctx.dryRun ? 'Dry-run preview' : 'Installation complete');
+
+  if (results.preserved > 0) {
+    const list = results.preservedFiles.slice(0, 8).map((f) => `  ⊘ ${f}`).join('\n');
+    const more = results.preservedFiles.length > 8 ? `\n  ... and ${results.preservedFiles.length - 8} more` : '';
+    ui.warn(`${results.preserved} user-modified file(s) preserved:\n${list}${more}\n`
+      + 'Re-run with --force-overwrite to replace them (a backup is kept under .cafekit-backup/).');
+  }
+
+  if (ctx.dryRun) {
+    ui.outro('Dry-run only — re-run without --dry-run to apply.');
+    return;
+  }
+
+  const lines = [];
+  for (const key of platforms) {
+    if (key === 'claude') lines.push('Claude: use /hapo:specs <feature-description>');
+    else lines.push('OpenCode: ask the agent to start a feature or brainstorm');
+  }
+  const envHosts = platforms.map((key) => `${PLATFORMS[key].folder}/.env`).join(' and ');
+  lines.push(`API keys isolated in ${envHosts}`);
+  if (!options.forceOverwrite) {
+    lines.push('Use --force-overwrite to refresh user-modified files');
+  }
+  ui.note(lines.join('\n'), 'Next steps');
+
+  ui.outro(`Done — docs: https://github.com/haposoft/cafekit`);
+}
+
+module.exports = { printSummary };