@haposoft/cafekit 0.10.3 → 0.11.0

package/bin/install.js

@@ -20,7 +20,7 @@ const lock = require('./lib/lock');
 const backup = require('./lib/backup');
 const manifestLib = require('./lib/manifest');
 
-const { resolvePlatforms } = require('./phases/select-platform');
+const { selectLanguage, resolvePlatforms } = require('./phases/select-platform');
 const { copyPlatformFiles } = require('./phases/copy-payload');
 const {
   copyRoutingFile,
@@ -32,6 +32,7 @@ const {
 const { mergeClaudeSettings } = require('./phases/claude-settings');
 const { installOpenCodeRuntime } = require('./phases/opencode-runtime');
 const { writePlatformVersionMetadata } = require('./phases/write-metadata');
+const { checkVersions } = require('./lib/version-check');
 const { ensureGitignore } = require('./phases/root-config');
 const { runPostInstall } = require('./phases/post-install');
 const { setupSkillDeps } = require('./phases/skills-setup');
@@ -46,7 +47,7 @@ function installPlatform(ctx, platformKey) {
   ctx.trackers[platformKey] = manifestLib.createTracker(platform.folder, packageJson.version);
 
   const before = { copied: ctx.results.copied, updated: ctx.results.updated, skills: ctx.results.installedSkills };
-  ctx.ui.startSpinner(`Installing ${platform.name} (${platform.folder}/)`);
+  ctx.ui.startSpinner(ctx.t('installingPlatform', { name: platform.name }));
 
   copyPlatformFiles(ctx, platformKey);
 
@@ -66,13 +67,48 @@ function installPlatform(ctx, platformKey) {
   writePlatformVersionMetadata(ctx, platformKey);
 
   const wrote = (ctx.results.copied - before.copied) + (ctx.results.updated - before.updated);
-  const verb = ctx.dryRun ? 'would install' : 'installed';
-  ctx.ui.stopSpinner(`${platform.name} ${verb} — ${wrote} file(s), ${ctx.results.installedSkills - before.skills} skill(s)`);
+  const skills = ctx.results.installedSkills - before.skills;
+  ctx.ui.stopSpinner(ctx.t(ctx.dryRun ? 'platformDryInstalled' : 'platformInstalled', {
+    name: platform.name, files: wrote, skills
+  }));
 
   ctx.results.targets.push(platform.commandsDir);
 }
 
+function printHelp() {
+  console.log(`CafeKit installer (cafekit) v${packageJson.version}
+
+Usage: npx @haposoft/cafekit [options]
+
+Installs CafeKit skills, agents, rules and runtime into the current project
+(.claude/ and/or .opencode/). Re-runs are selective: managed files are updated,
+your edits are preserved.
+
+Options:
+  --dry-run            Preview changes; write nothing
+  --force-overwrite    Overwrite user-modified managed files (backup kept)
+  -u, --upgrade, -f, --force   Alias of --force-overwrite
+  --with-skills-deps   Install skill dependencies (Python venv + pip, npm,
+                       Chromium/Playwright). Otherwise prompted interactively.
+  -y, --yes            Non-interactive: skip prompts, use defaults (CI)
+  -h, --help           Show this help
+  -v, --version        Print version
+
+Docs: https://github.com/haposoft/cafekit`);
+}
+
 async function main() {
+  // Info flags short-circuit before any side effects.
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    console.log(packageJson.version);
+    process.exit(0);
+  }
+
   // ── Concurrency guard (before context; plain output) ────
   const got = lock.acquire();
   if (!got.acquired) {
@@ -87,13 +123,15 @@ async function main() {
   try {
     ctx = buildContext(process.argv, `${Date.now()}`);
     ctx.ui.intro(`${ctx.ui.pc.bgCyan(ctx.ui.pc.black(' CafeKit '))}Installer v${packageJson.version} · Multi-platform SDD`);
-    if (got.reclaimed) ctx.ui.info('Reclaimed a stale install lock from a dead process.');
+    if (got.reclaimed) ctx.ui.info(ctx.t('reclaimed'));
 
+    await selectLanguage(ctx);
     await resolvePlatforms(ctx);
-    if (ctx.cancelled) {
-      lock.release();
-      process.exit(0);
-    }
+    if (ctx.cancelled) { lock.release(); process.exit(0); }
+
+    // Version check: same → exit, downgrade → confirm
+    await checkVersions(ctx);
+    if (ctx.cancelled) { lock.release(); process.exit(0); }
 
     // ── Pre-run snapshot for rollback ─────────────────────
     // Capture platform folders AND the root files the pipeline mutates
@@ -117,14 +155,14 @@ async function main() {
     exitCode = ctx.results.errors > 0 ? 1 : 0;
   } catch (error) {
     const log = ctx && ctx.ui ? ctx.ui : { error: (m) => console.error(m) };
-    log.error(`Installation failed: ${error.message}`);
+    const t = ctx ? ctx.t : (k) => k;
+    log.error(t('installFailed', { reason: error.message }));
     if (ctx && ctx.backupDir && !ctx.dryRun) {
       try {
         backup.restore(ctx.backupDir);
-        log.error('Rolled back to the pre-install state from snapshot.');
+        log.error(t('rolledBack'));
       } catch (restoreError) {
-        log.error(`Rollback failed: ${restoreError.message}`);
-        log.error(`Manual restore available at: ${ctx.backupDir}`);
+        log.error(t('rollbackFailed', { reason: restoreError.message, dir: ctx.backupDir }));
       }
     }
     exitCode = 1;

package/bin/lib/context.js

@@ -15,6 +15,7 @@ const path = require('path');
 const packageJson = require('../../package.json');
 const { getOpenCodeCopyOptions } = require('./opencode-install');
 const { isInteractive, createUI } = require('./ui');
+const { resolveLang, createTranslator } = require('./i18n');
 
 const INSTALL_COMMAND = `npx ${packageJson.name}@${packageJson.version}`;
 
@@ -198,6 +199,10 @@ function parseInstallerArgs(argv) {
       args.yes = true;
     } else if (arg === '--with-skills-deps') {
       args.withSkillsDeps = true;
+    } else if (arg === '--lang') {
+      args.lang = argv[++i];
+    } else if (arg.startsWith('--lang=')) {
+      args.lang = arg.slice('--lang='.length);
     }
   }
 
@@ -240,6 +245,8 @@ function buildContext(argv, runId) {
   const options = parseInstallerArgs(argv);
   // Interactive only on a real TTY and not when --yes/CI forces non-interactive.
   const interactive = isInteractive() && !options.yes;
+  // Language: --lang wins; otherwise English (an interactive prompt may change it).
+  const lang = options.lang ? resolveLang(options.lang) : 'en';
   return {
     argv,
     runId,
@@ -247,6 +254,13 @@ function buildContext(argv, runId) {
     dryRun: options.dryRun,
     interactive,
     ui: createUI(interactive),
+    lang,
+    t: createTranslator(lang),
+    /** Update the active language + translator (used by the language prompt). */
+    setLang(code) {
+      this.lang = resolveLang(code);
+      this.t = createTranslator(this.lang);
+    },
     manifest: loadClaudeMigrationManifest(),  // migration manifest (skills/agents/runtime lists)
     platforms: [],
     results: createResults(),

package/bin/lib/i18n.js

@@ -0,0 +1,267 @@
+/**
+ * Installer i18n — English / 日本語 / Tiếng Việt.
+ *
+ * Covers every user-visible string: prompts, spinners, warnings, summary and
+ * next steps. High-frequency internal debug logs stay English.
+ *
+ * Tone: concise, friendly, action-oriented. No ellipsis abuse (…); imperative
+ * verbs; consistent capitalisation per language norms.
+ */
+
+const SUPPORTED = ['en', 'ja', 'vi'];
+
+const LANGUAGE_LABELS = { en: 'English', ja: '日本語', vi: 'Tiếng Việt' };
+
+const MESSAGES = {
+  // ─── English ───────────────────────────────────────────────────────────────
+  en: {
+    // Banner / lock / rollback
+    reclaimed:       'Stale install lock reclaimed (previous process was gone).',
+    lockHeld:        'Another install is already running (pid {pid}, started {since}).\n  If that process has ended, delete .cafekit.lock and try again.',
+    installFailed:   'Installation failed: {reason}',
+    rolledBack:      'Changes rolled back to the pre-install state.',
+    rollbackFailed:  'Rollback failed: {reason}\n  Manual restore available at: {dir}',
+    dryRunBanner:    'Dry-run — no files will be written.',
+
+    // Language / platform selection
+    selectLanguage:      'Select language',
+    selectPlatform:      'Select platform(s) to install',
+    allPlatforms:        'All platforms',
+    confirmAllDetected:  'Found existing configs: {names}. Install for all?',
+    defaultedToClaude:   'No existing config detected — defaulting to Claude Code.',
+    cancelled:           'Installation cancelled.',
+
+    // Mode banner
+    modeForce:    'Mode: force-overwrite  •  user-modified files will be replaced (backup kept)',
+    modeDryRun:   'Mode: dry-run  •  no changes will be written',
+    modeInstall:  'Mode: install / update  •  your customisations are preserved',
+
+    // Platform install spinner
+    installingPlatform:    'Installing {name}',
+    platformInstalled:     '{name} — {files} file(s), {skills} skill(s)',
+    platformDryInstalled:  '{name} — {files} file(s), {skills} skill(s)  [dry-run]',
+
+    // Addressing
+    addressingQuestion:    'What should the AI call you?',
+    addressingPlaceholder: 'e.g. boss, friend — Enter to skip',
+    addressingSet:         '{name} will address you as "{addr}"',
+    addressingInvalid:     'Letters only please — addressing skipped.',
+
+    // Skills / deps setup
+    skillDepsConfirm:      'Install skill dependencies? (Python venv, pip, npm, Chromium — takes a few minutes)',
+    skillsSkipped:         'Skill dependencies skipped.\n  Run later: npx @haposoft/cafekit --with-skills-deps',
+    venvCreating:          'Setting up Python environment',
+    venvReady:             'Python environment ready',
+    venvFailed:            'Could not create Python environment — check your Python 3 installation.',
+    venvNoHost:            'Python 3 not found. Install it, then re-run with --with-skills-deps.',
+    pipInstalling:         'Installing Python packages: {skill}',
+    pipInstalled:          '{skill} — Python packages ready',
+    pipFailed:             '{skill} — some packages failed. Retry:\n  {cmd}',
+    npmInstalling:         'Installing Node packages: {skill}',
+    npmInstalled:          '{skill} — Node packages ready',
+    npmFailed:             '{skill} — npm install failed. Check the log and retry in: {dir}',
+    playwrightInstalling:  'Downloading Playwright browser for {skill}',
+    playwrightReady:       '{skill} — Playwright browser ready',
+    playwrightSkipped:     '{skill} — Playwright browser download skipped',
+    chromiumInstalling:    'Downloading Chromium for chrome-devtools',
+    chromiumReady:         'Chromium ready',
+    chromiumSkipped:       'Chromium download skipped — chrome-devtools will prompt on first use.',
+    optionalToolsTitle:    'Optional tools to install manually',
+
+    // Summary stats
+    summaryTitle:    'Installation complete',
+    summaryDryTitle: 'Dry-run preview',
+    labelCopied:     'Installed',
+    labelUpdated:    'Updated',
+    labelUnchanged:  'Unchanged',
+    labelPreserved:  'Preserved',
+    labelSkills:     'Skills',
+    labelVersion:    'CafeKit Version',
+    labelMissing:    'Missing',
+    labelErrors:     'Errors',
+    yes:             'yes',
+    no:              'no',
+    preservedNote:   '{n} file(s) you edited were kept as-is.\n  Re-run with --force-overwrite to reset them (a backup is saved to .cafekit-backup/).',
+
+    // Next steps
+    nextStepsTitle:  'Next steps',
+    nsClaude:        'Start coding: /hapo:specs <feature>',
+    nsOpencode:      'Start coding: ask the agent to begin a new feature or brainstorm',
+    nsKeys:          'Some skills need API keys: {skills}\n  Copy <skill>/.env.example → .env and fill in the values',
+    nsForce:         'To force-refresh managed files: npx @haposoft/cafekit --force-overwrite',
+    dryRunOnly:      'Dry-run complete — no files were changed.\n  Re-run without --dry-run to apply.',
+    outroDone:       'Done!  docs: https://github.com/haposoft/cafekit',
+
+    // Version check
+    versionUpToDate:  'Already up to date ({v}). Use --force-overwrite to reinstall.',
+    versionDowngrade: 'Downgrading {from} → {to}. Features may be removed. Continue?'
+  },
+
+  // ─── 日本語 ─────────────────────────────────────────────────────────────────
+  ja: {
+    reclaimed:       '前のプロセスが終了したため、ロックを解除しました。',
+    lockHeld:        '別のインストールが実行中です（pid {pid}、開始: {since}）。\n  そのプロセスが終了している場合は .cafekit.lock を削除して再試行してください。',
+    installFailed:   'インストールに失敗しました: {reason}',
+    rolledBack:      'インストール前の状態に戻しました。',
+    rollbackFailed:  'ロールバックに失敗しました: {reason}\n  手動復元可能: {dir}',
+    dryRunBanner:    'ドライラン — ファイルへの書き込みは行いません。',
+
+    selectLanguage:      '言語を選択してください',
+    selectPlatform:      'インストールするプラットフォームを選択',
+    allPlatforms:        'すべてのプラットフォーム',
+    confirmAllDetected:  '既存の設定が見つかりました: {names}。すべてにインストールしますか？',
+    defaultedToClaude:   '既存の設定が見つかりません — Claude Code をデフォルトで使用します。',
+    cancelled:           'インストールをキャンセルしました。',
+
+    modeForce:    'モード: 強制上書き  •  編集済みファイルを置換します（バックアップあり）',
+    modeDryRun:   'モード: ドライラン  •  ファイルへの変更はありません',
+    modeInstall:  'モード: インストール / 更新  •  カスタマイズは保持されます',
+
+    installingPlatform:    '{name} をインストール中',
+    platformInstalled:     '{name} — {files} ファイル、{skills} スキル',
+    platformDryInstalled:  '{name} — {files} ファイル、{skills} スキル  [ドライラン]',
+
+    addressingQuestion:    'AI にどう呼ばれたいですか？',
+    addressingPlaceholder: '例: さん、くん — Enter でスキップ',
+    addressingSet:         '{name} はあなたを「{addr}」とお呼びします',
+    addressingInvalid:     '文字のみ入力できます — 呼称の設定をスキップしました。',
+
+    skillDepsConfirm:      'スキルの依存関係をインストールしますか？（Python venv、pip、npm、Chromium — 数分かかります）',
+    skillsSkipped:         'スキルの依存関係をスキップしました。\n  後で実行: npx @haposoft/cafekit --with-skills-deps',
+    venvCreating:          'Python 環境を準備しています',
+    venvReady:             'Python 環境の準備ができました',
+    venvFailed:            'Python 環境を作成できませんでした — Python 3 のインストールを確認してください。',
+    venvNoHost:            'Python 3 が見つかりません。インストール後、--with-skills-deps で再実行してください。',
+    pipInstalling:         'Python パッケージをインストール中: {skill}',
+    pipInstalled:          '{skill} — Python パッケージの準備ができました',
+    pipFailed:             '{skill} — 一部のパッケージが失敗しました。再試行:\n  {cmd}',
+    npmInstalling:         'Node パッケージをインストール中: {skill}',
+    npmInstalled:          '{skill} — Node パッケージの準備ができました',
+    npmFailed:             '{skill} — npm install に失敗しました。{dir} で手動再試行してください。',
+    playwrightInstalling:  '{skill} 用の Playwright ブラウザをダウンロード中',
+    playwrightReady:       '{skill} — Playwright ブラウザの準備ができました',
+    playwrightSkipped:     '{skill} — Playwright ブラウザのダウンロードをスキップしました',
+    chromiumInstalling:    'chrome-devtools 用 Chromium をダウンロード中',
+    chromiumReady:         'Chromium の準備ができました',
+    chromiumSkipped:       'Chromium のダウンロードをスキップ — 初回使用時に chrome-devtools が自動取得します。',
+    optionalToolsTitle:    '手動でインストールが必要なオプションツール',
+
+    summaryTitle:    'インストール完了',
+    summaryDryTitle: 'ドライラン プレビュー',
+    labelCopied:     'インストール',
+    labelUpdated:    '更新',
+    labelUnchanged:  '変更なし',
+    labelPreserved:  '保持',
+    labelSkills:     'スキル',
+    labelVersion:    'CafeKit Version',
+    labelMissing:    '不足',
+    labelErrors:     'エラー',
+    yes:             'はい',
+    no:              'いいえ',
+    preservedNote:   '編集済みファイル {n} 件はそのままにしました。\n  --force-overwrite で再実行するとリセットできます（.cafekit-backup/ にバックアップ保存）。',
+
+    nextStepsTitle:  '次のステップ',
+    nsClaude:        'コーディング開始: /hapo:specs <機能名>',
+    nsOpencode:      'コーディング開始: エージェントに新機能の開始またはブレストを依頼',
+    nsKeys:          '一部のスキルに API キーが必要です: {skills}\n  <skill>/.env.example を .env にコピーし、値を入力してください',
+    nsForce:         '管理ファイルを強制更新: npx @haposoft/cafekit --force-overwrite',
+    dryRunOnly:      'ドライラン完了 — ファイルへの変更はありませんでした。\n  変更を適用するには --dry-run なしで再実行してください。',
+    outroDone:       '完了！  ドキュメント: https://github.com/haposoft/cafekit',
+
+    versionUpToDate:  '最新バージョンです（{v}）。再インストールするには --force-overwrite を使用してください。',
+    versionDowngrade: '{from} → {to} へのダウングレードです。機能が削除される可能性があります。続けますか？'
+  },
+
+  // ─── Tiếng Việt ─────────────────────────────────────────────────────────────
+  vi: {
+    reclaimed:       'Khóa cài đặt cũ đã được thu hồi (tiến trình trước đã kết thúc).',
+    lockHeld:        'Có một phiên cài đặt khác đang chạy (pid {pid}, bắt đầu: {since}).\n  Nếu tiến trình đó đã kết thúc, hãy xóa .cafekit.lock rồi thử lại.',
+    installFailed:   'Cài đặt thất bại: {reason}',
+    rolledBack:      'Đã hoàn tác về trạng thái trước khi cài đặt.',
+    rollbackFailed:  'Hoàn tác thất bại: {reason}\n  Bản sao lưu thủ công: {dir}',
+    dryRunBanner:    'Dry-run — sẽ không có tệp nào được ghi.',
+
+    selectLanguage:      'Chọn ngôn ngữ',
+    selectPlatform:      'Chọn (các) nền tảng cần cài',
+    allPlatforms:        'Tất cả nền tảng',
+    confirmAllDetected:  'Phát hiện cấu hình sẵn: {names}. Cài cho tất cả?',
+    defaultedToClaude:   'Không tìm thấy cấu hình sẵn — mặc định dùng Claude Code.',
+    cancelled:           'Đã hủy cài đặt.',
+
+    modeForce:    'Chế độ: ghi đè  •  file bạn đã sửa sẽ bị thay (có bản sao lưu)',
+    modeDryRun:   'Chế độ: dry-run  •  sẽ không thay đổi bất kỳ tệp nào',
+    modeInstall:  'Chế độ: cài / cập nhật  •  nội dung bạn tuỳ chỉnh được giữ nguyên',
+
+    installingPlatform:    'Đang cài {name}',
+    platformInstalled:     '{name} — {files} tệp, {skills} skill',
+    platformDryInstalled:  '{name} — {files} tệp, {skills} skill  [dry-run]',
+
+    addressingQuestion:    'Bạn muốn AI gọi bạn là gì?',
+    addressingPlaceholder: 'vd: sếp, đại ca — Enter để bỏ qua',
+    addressingSet:         '{name} sẽ gọi bạn là "{addr}"',
+    addressingInvalid:     'Chỉ nhập chữ cái — bỏ qua thiết lập xưng hô.',
+
+    skillDepsConfirm:      'Cài dependencies cho skill ngay? (Python venv, pip, npm, Chromium — mất vài phút)',
+    skillsSkipped:         'Đã bỏ qua dependencies skill.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-skills-deps',
+    venvCreating:          'Đang thiết lập môi trường Python',
+    venvReady:             'Môi trường Python đã sẵn sàng',
+    venvFailed:            'Không thể tạo môi trường Python — hãy kiểm tra cài đặt Python 3.',
+    venvNoHost:            'Không tìm thấy Python 3. Hãy cài Python 3 rồi chạy lại với --with-skills-deps.',
+    pipInstalling:         'Đang cài gói Python: {skill}',
+    pipInstalled:          '{skill} — gói Python đã sẵn sàng',
+    pipFailed:             '{skill} — một số gói cài thất bại. Chạy lại thủ công:\n  {cmd}',
+    npmInstalling:         'Đang cài gói Node: {skill}',
+    npmInstalled:          '{skill} — gói Node đã sẵn sàng',
+    npmFailed:             '{skill} — npm install thất bại. Hãy thử lại trong: {dir}',
+    playwrightInstalling:  'Đang tải Playwright browser cho {skill}',
+    playwrightReady:       '{skill} — Playwright browser đã sẵn sàng',
+    playwrightSkipped:     '{skill} — đã bỏ qua tải Playwright browser',
+    chromiumInstalling:    'Đang tải Chromium cho chrome-devtools',
+    chromiumReady:         'Chromium đã sẵn sàng',
+    chromiumSkipped:       'Bỏ qua tải Chromium — chrome-devtools sẽ tự tải khi dùng lần đầu.',
+    optionalToolsTitle:    'Công cụ tuỳ chọn cần cài thủ công',
+
+    summaryTitle:    'Cài đặt hoàn tất',
+    summaryDryTitle: 'Xem trước dry-run',
+    labelCopied:     'Đã cài',
+    labelUpdated:    'Đã cập nhật',
+    labelUnchanged:  'Không đổi',
+    labelPreserved:  'Đã giữ',
+    labelSkills:     'Skill',
+    labelVersion:    'CafeKit Version',
+    labelMissing:    'Thiếu',
+    labelErrors:     'Lỗi',
+    yes:             'có',
+    no:              'không',
+    preservedNote:   '{n} tệp bạn đã chỉnh sửa được giữ nguyên.\n  Chạy lại với --force-overwrite để cài đè (bản sao lưu ở .cafekit-backup/).',
+
+    nextStepsTitle:  'Bước tiếp theo',
+    nsClaude:        'Bắt đầu code: /hapo:specs <mô-tả-tính-năng>',
+    nsOpencode:      'Bắt đầu code: yêu cầu agent khởi động tính năng mới hoặc brainstorm',
+    nsKeys:          'Một số skill cần API key: {skills}\n  Sao chép <skill>/.env.example → .env rồi điền giá trị',
+    nsForce:         'Làm mới file được quản lý: npx @haposoft/cafekit --force-overwrite',
+    dryRunOnly:      'Dry-run hoàn tất — không có tệp nào thay đổi.\n  Chạy lại không có --dry-run để áp dụng.',
+    outroDone:       'Xong!  Tài liệu: https://github.com/haposoft/cafekit',
+
+    versionUpToDate:  'Đã là phiên bản mới nhất ({v}). Dùng --force-overwrite để cài lại.',
+    versionDowngrade: 'Đang hạ cấp {from} → {to}. Một số tính năng có thể bị xoá. Tiếp tục?'
+  }
+};
+
+/** Normalize a language code to a supported one; unknown → 'ja'. */
+function resolveLang(code) {
+  if (!code) return 'en';
+  const lc = String(code).toLowerCase().slice(0, 2);
+  return SUPPORTED.includes(lc) ? lc : 'ja';
+}
+
+/** Build a translator. Falls back to English per-key, then the key itself. */
+function createTranslator(lang) {
+  const resolved = resolveLang(lang);
+  return function t(key, vars = {}) {
+    const template = (MESSAGES[resolved] && MESSAGES[resolved][key]) || MESSAGES.en[key] || key;
+    return template.replace(/\{(\w+)\}/g, (_, name) => (vars[name] !== undefined ? String(vars[name]) : `{${name}}`));
+  };
+}
+
+module.exports = { SUPPORTED, LANGUAGE_LABELS, MESSAGES, resolveLang, createTranslator };

package/bin/lib/manifest.js

@@ -95,6 +95,16 @@ function createTracker(platformFolder, version) {
       return Object.keys(files).length;
     },
 
+    /** Keys explicitly pruned this run — must not survive the merge into the prior manifest. */
+    _pruned: new Set(),
+
+    /** Remove a relPath from this run's tracked files (e.g. after obsolete removal). */
+    prune(rel) {
+      const key = rel.replace(/\\/g, '/');
+      delete files[key];
+      this._pruned.add(key);
+    },
+
     /** Recorded hash for a relPath written earlier this run, or null. */
     recorded(rel) {
       const key = rel.replace(/\\/g, '/');
@@ -107,7 +117,10 @@ function createTracker(platformFolder, version) {
      */
     write() {
       const prior = read(platformFolder);
-      const merged = { ...prior.files, ...files };
+      // Start from prior, delete pruned entries, then overlay this run's files.
+      const merged = { ...prior.files };
+      for (const key of this._pruned) delete merged[key];
+      Object.assign(merged, files);
       const out = {
         schemaVersion: SCHEMA_VERSION,
         version,

package/bin/lib/skill-deps.js

@@ -69,16 +69,17 @@ function pipUpgrade(skillsDir) {
   return run(venvPython(skillsDir), ['-m', 'pip', 'install', '--upgrade', 'pip', '--prefer-binary']).ok;
 }
 
-/** Install a requirements.txt into the venv (wheels first). Returns true on success. */
-function pipInstall(skillsDir, requirementsPath) {
-  return run(venvPython(skillsDir), [
-    '-m', 'pip', 'install', '-r', requirementsPath, '--prefer-binary'
-  ]).ok;
+/** Install or upgrade pip requirements in the venv. */
+function pipInstall(skillsDir, requirementsPath, upgrade = false) {
+  const args = ['-m', 'pip', 'install', '-r', requirementsPath, '--prefer-binary'];
+  if (upgrade) args.push('--upgrade');
+  return run(venvPython(skillsDir), args).ok;
 }
 
-/** `npm install` in a skill scripts dir. Returns true on success. */
-function npmInstall(dir) {
-  return run('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir }).ok;
+/** `npm install` (fresh) or `npm update` (existing) in a skill scripts dir. */
+function npmInstall(dir, upgrade = false) {
+  const args = upgrade ? ['update', '--no-audit', '--no-fund'] : ['install', '--no-audit', '--no-fund'];
+  return run('npm', args, { cwd: dir }).ok;
 }
 
 /**
@@ -115,6 +116,7 @@ function installPlaywrightBrowser(scriptsDir) {
 /**
  * List installed skills that ship a runnable scripts/requirements.txt
  * (excludes the tests/ requirements). Returns [{ skill, file }].
+ * Always returned regardless of whether venv already exists (caller decides upgrade vs fresh).
  */
 function collectRequirements(skillsDir) {
   const out = [];
@@ -127,16 +129,16 @@ function collectRequirements(skillsDir) {
 }
 
 /**
- * List installed skills with a scripts/package.json that still needs installing
- * (no node_modules present). Returns [{ skill, dir }].
+ * List installed skills with a scripts/package.json.
+ * Returns [{ skill, dir, hasNodeModules }] — always, so caller can upgrade existing installs.
  */
 function collectSkillPackages(skillsDir) {
   const out = [];
   if (!fs.existsSync(skillsDir)) return out;
   for (const skill of fs.readdirSync(skillsDir)) {
     const dir = path.join(skillsDir, skill, 'scripts');
-    if (fs.existsSync(path.join(dir, 'package.json')) && !fs.existsSync(path.join(dir, 'node_modules'))) {
-      out.push({ skill, dir });
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      out.push({ skill, dir, hasNodeModules: fs.existsSync(path.join(dir, 'node_modules')) });
     }
   }
   return out;

package/bin/lib/version-check.js

@@ -0,0 +1,91 @@
+/**
+ * Version check before install.
+ *
+ * Reads each platform's cafekit.json to compare the installed version with the
+ * incoming one and decides whether to proceed:
+ *
+ *   same    → info + exit 0 (unless --force-overwrite)
+ *   newer   → normal update
+ *   older   → downgrade warning + confirm (interactive) or abort (non-interactive)
+ *   missing → fresh install, no check needed
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS, packageJson } = require('./context');
+
+/** Simple semver-ish comparison. Returns -1 | 0 | 1. */
+function cmpVersion(a, b) {
+  const toNum = (v) => String(v).split('.').map((n) => parseInt(n, 10) || 0);
+  const [aN, bN] = [toNum(a), toNum(b)];
+  for (let i = 0; i < 3; i++) {
+    const diff = (aN[i] || 0) - (bN[i] || 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Read the currently installed version for a platform.
+ * Returns null if cafekit.json doesn't exist yet (fresh install).
+ */
+function getInstalledVersion(platformKey) {
+  const p = path.join(PLATFORMS[platformKey].folder, 'cafekit.json');
+  try {
+    if (!fs.existsSync(p)) return null;
+    const meta = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return typeof meta.version === 'string' ? meta.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check versions for all selected platforms and decide whether to proceed.
+ * Sets ctx.cancelled on same-version (without --force) or unconfirmed downgrade.
+ */
+async function checkVersions(ctx) {
+  if (ctx.dryRun) return ctx;
+
+  const incoming = packageJson.version;
+
+  for (const key of ctx.platforms) {
+    const installed = getInstalledVersion(key);
+    if (!installed) continue; // fresh install — no check needed
+
+    const cmp = cmpVersion(installed, incoming);
+
+    // ── Same version ─────────────────────────────────────────────────────────
+    if (cmp === 0) {
+      if (ctx.options.forceOverwrite) continue; // --force-overwrite overrides
+      ctx.ui.info(ctx.t ? ctx.t('versionUpToDate', { v: installed }) : `Already up to date (${installed}). Use --force-overwrite to reinstall.`);
+      ctx.cancelled = true;
+      return ctx;
+    }
+
+    // ── Downgrade ─────────────────────────────────────────────────────────────
+    if (cmp > 0) {
+      const msg = ctx.t
+        ? ctx.t('versionDowngrade', { from: installed, to: incoming })
+        : `Downgrading ${installed} → ${incoming}. This may remove features. Continue?`;
+
+      if (!ctx.interactive) {
+        ctx.ui.warn ? ctx.ui.warn(`Downgrade detected (${installed} → ${incoming}). Aborted in non-interactive mode. Use --force-overwrite to proceed.`) : console.warn(msg);
+        ctx.cancelled = true;
+        return ctx;
+      }
+
+      const yes = await ctx.ui.confirm({ message: msg, initialValue: false }, false);
+      if (!yes || ctx.ui.isCancel(yes)) {
+        ctx.cancelled = true;
+        return ctx;
+      }
+    }
+
+    // cmp < 0 → upgrade, proceed normally
+  }
+
+  return ctx;
+}
+
+module.exports = { getInstalledVersion, cmpVersion, checkVersions };

package/bin/phases/claude-runtime.js

@@ -78,7 +78,13 @@ function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
     const targetPath = path.join(targetBase, relPath);
     if (!fs.existsSync(targetPath)) return;
 
-    if (!ctx.dryRun) fs.rmSync(targetPath, { force: true });
+    if (!ctx.dryRun) {
+      fs.rmSync(targetPath, { force: true });
+      // Remove the entry from the manifest so it doesn't linger as a zombie.
+      if (ctx.trackers && ctx.trackers.claude) {
+        ctx.trackers.claude.prune(relPath);
+      }
+    }
     ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete runtime: ${relPath}`);
     ctx.results.updated++;
   });

package/bin/phases/post-install.js

@@ -13,8 +13,86 @@
 
 const fs = require('fs');
 const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { LANGUAGE_LABELS } = require('../lib/i18n');
 const { setupOpenCodeModel } = require('../lib/opencode-install');
 
+/** Write `"language"` field into .claude/settings.json so it's visible at a glance. */
+function patchSettingsLanguage(ctx) {
+  if (!ctx.platforms.includes('claude')) return;
+  const settingsPath = path.join(process.cwd(), '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) return;
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const label = LANGUAGE_LABELS[ctx.lang] || ctx.lang;
+  if (settings.language === label) return; // already up to date
+  settings.language = label;
+  fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * Patch the "## Language Consistency" section in CLAUDE.md with the chosen
+ * language so every AI session knows which language to respond in — without
+ * relying on hooks reading runtime.json.
+ *
+ * The section is identified by a stable marker comment so subsequent installs
+ * can update it idempotently.
+ */
+function patchLanguageSection(ctx) {
+  if (!ctx.platforms.includes('claude')) return;
+  if (ctx.lang === 'en') return; // English is the default — no override needed.
+
+  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdFile)) return;
+
+  const LANG_LABEL = { vi: 'Vietnamese', ja: 'Japanese', en: 'English' };
+  const label = LANG_LABEL[ctx.lang] || ctx.lang;
+
+  const newSection = `## Language Consistency <!-- cafekit:lang -->
+
+Always respond in **${label}**. Technical terms, code identifiers, and file paths may remain in English, but all explanations, comments directed at the user, and structured output (specs, docs, reports) must be in ${label}.
+
+`;
+
+  let content = fs.readFileSync(claudeMdFile, 'utf8');
+  // Replace if marker present, else replace the generic section.
+  const markerRe = /## Language Consistency <!-- cafekit:lang -->[\s\S]*?(?=\n##|\n*$)/;
+  const genericRe = /## Language Consistency\n[\s\S]*?(?=\n##|\n*$)/;
+
+  if (markerRe.test(content)) {
+    content = content.replace(markerRe, newSection);
+  } else if (genericRe.test(content)) {
+    content = content.replace(genericRe, newSection);
+  } else {
+    content += `\n${newSection}\n`;
+  }
+
+  fs.writeFileSync(claudeMdFile, content, 'utf8');
+}
+function patchRuntimeLocale(ctx) {
+  for (const key of ctx.platforms) {
+    const rtPath = path.join(PLATFORMS[key].folder, 'runtime.json');
+    if (!fs.existsSync(rtPath)) continue;
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(rtPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    data.locale = data.locale || {};
+    if (data.locale.responseLanguage === ctx.lang) continue;
+    data.locale.responseLanguage = ctx.lang;
+    fs.writeFileSync(rtPath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    if (ctx.trackers[key]) ctx.trackers[key].record(rtPath);
+  }
+}
+
 /** Human assistant name for the active platform(s). */
 function assistantName(ctx) {
   return ctx.platforms.includes('claude') ? 'Claude Code' : 'OpenCode';
@@ -40,22 +118,23 @@ ${name} always addresses the user as "${userAddress}" throughout the conversatio
     : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
 
   fs.writeFileSync(claudeMdFile, content, 'utf8');
-  ctx.ui.success(`${name} will call you "${userAddress}"`);
+  ctx.ui.success(ctx.t('addressingSet', { name, addr: userAddress }));
 }
 
 async function setupAddressing(ctx) {
   if (!ctx.platforms.includes('claude')) return;
 
   const answer = await ctx.ui.text(
-    { message: 'How should the AI address you?', placeholder: 'e.g. boss, sir — Enter to skip' },
+    { message: ctx.t('addressingQuestion'), placeholder: ctx.t('addressingPlaceholder') },
     ''
   );
   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');
+  // Allow letters from any script (incl. Japanese) + spaces; reject digits/symbols.
+  if (/[^\p{L}\s]/u.test(userAddress)) {
+    ctx.ui.warn(ctx.t('addressingInvalid'));
     return;
   }
   configureAddressing(ctx, userAddress);
@@ -77,11 +156,22 @@ async function runPostInstall(ctx) {
 
   await setupAddressing(ctx);
 
-  // Re-record CLAUDE.md baseline so the installer-managed file (template +
-  // addressing) stays "pristine" and keeps receiving upstream updates.
+  // Patch Language Consistency section in CLAUDE.md so AI responds in the chosen language.
+  patchLanguageSection(ctx);
+
+  // Persist chosen language into each platform's runtime.json (records in tracker).
+  patchRuntimeLocale(ctx);
+
+  // Write "language" field into .claude/settings.json for visibility.
+  patchSettingsLanguage(ctx);
+
+  // Re-record post-write baselines so installer-managed files stay "pristine",
+  // then flush each touched platform tracker.
   if (ctx.platforms.includes('claude') && ctx.trackers.claude && fs.existsSync('CLAUDE.md')) {
     ctx.trackers.claude.record('CLAUDE.md');
-    ctx.trackers.claude.write();
+  }
+  for (const key of ctx.platforms) {
+    if (ctx.trackers[key]) ctx.trackers[key].write();
   }
   return ctx;
 }

package/bin/phases/select-platform.js

@@ -1,10 +1,9 @@
 /**
- * Phase: platform detection + selection.
+ * Phase: language + platform 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.
+ * Language is chosen first (interactive) so the rest of the installer renders in
+ * it; non-interactive uses --lang or English. Then platforms are auto-detected
+ * or prompted. Sets ctx.platforms, or ctx.cancelled if the user backs out.
  */
 
 const {
@@ -13,6 +12,23 @@ const {
   getPlatformKeys,
   warnLegacyClaudeFolder
 } = require('../lib/context');
+const { SUPPORTED, LANGUAGE_LABELS } = require('../lib/i18n');
+
+/** First step: pick the installer/UI language (interactive only). */
+async function selectLanguage(ctx) {
+  // Honor an explicit --lang or non-interactive default (English) without prompting.
+  if (!ctx.interactive || ctx.options.lang) return ctx;
+
+  const r = await ctx.ui.select(
+    {
+      message: 'Select language · 言語を選択 · Chọn ngôn ngữ',
+      options: SUPPORTED.map((code) => ({ value: code, label: LANGUAGE_LABELS[code] }))
+    },
+    ctx.lang
+  );
+  if (!ctx.ui.isCancel(r)) ctx.setLang(r);
+  return ctx;
+}
 
 /** clack select: which platform(s) to install for. */
 async function promptPlatformSelection(ctx) {
@@ -22,12 +38,9 @@ async function promptPlatformSelection(ctx) {
       label: PLATFORMS[key].name,
       hint: `${PLATFORMS[key].folder}/`
     })),
-    { value: getPlatformKeys(), label: 'All platforms' }
+    { value: getPlatformKeys(), label: ctx.t('allPlatforms') }
   ];
-  const r = await ctx.ui.select(
-    { message: 'Select which platform(s) to install for', options },
-    []
-  );
+  const r = await ctx.ui.select({ message: ctx.t('selectPlatform'), options }, []);
   if (ctx.ui.isCancel(r)) return [];
   return r;
 }
@@ -36,7 +49,7 @@ async function promptPlatformSelection(ctx) {
 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 },
+    { message: ctx.t('confirmAllDetected', { names }), initialValue: true },
     true
   );
   if (ctx.ui.isCancel(r)) return false;
@@ -53,12 +66,11 @@ async function resolvePlatforms(ctx) {
     if (ctx.interactive) {
       platforms = await promptPlatformSelection(ctx);
       if (platforms.length === 0) {
-        ctx.ui.outro('Installation cancelled.');
+        ctx.ui.outro(ctx.t('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/).');
     }
@@ -67,7 +79,7 @@ async function resolvePlatforms(ctx) {
     if (!proceed) {
       platforms = await promptPlatformSelection(ctx);
       if (platforms.length === 0) {
-        ctx.ui.outro('Installation cancelled.');
+        ctx.ui.outro(ctx.t('cancelled'));
         ctx.cancelled = true;
         return ctx;
       }
@@ -77,18 +89,18 @@ async function resolvePlatforms(ctx) {
   ctx.platforms = platforms;
 
   const platformNames = platforms.map((key) => PLATFORMS[key].name).join(', ');
-  ctx.ui.info(`Installing for: ${platformNames}`);
+  ctx.ui.info(ctx.t('installingFor', { names: platformNames }));
   warnLegacyClaudeFolder(platforms);
 
   if (ctx.options.forceOverwrite) {
-    ctx.ui.info('Mode: force-overwrite (replace user-modified files; backup kept)');
+    ctx.ui.info(ctx.t('modeForce'));
   } else if (ctx.dryRun) {
-    ctx.ui.info('Mode: dry-run (preview only, no changes written)');
+    ctx.ui.info(ctx.t('modeDryRun'));
   } else {
-    ctx.ui.info('Mode: install/update (selective; preserves user-modified files)');
+    ctx.ui.info(ctx.t('modeInstall'));
   }
 
   return ctx;
 }
 
-module.exports = { promptPlatformSelection, resolvePlatforms };
+module.exports = { selectLanguage, promptPlatformSelection, resolvePlatforms };

package/bin/phases/skills-setup.js

@@ -5,6 +5,7 @@
  *  - Python venv at <skillsDir>/.venv + pip install each skill's requirements
  *  - skill-local `npm install` (scripts/package.json without node_modules)
  *  - Puppeteer Chromium binary (chrome-devtools)
+ *  - Playwright browser binary (pptx html2pptx)
  *
  * System binaries (ffmpeg, poppler, librsvg, tesseract) and global npm CLIs are
  * NOT auto-installed — they are detected and printed as guidance. All steps are
@@ -23,93 +24,96 @@ async function shouldRun(ctx) {
   if (ctx.options.withSkillsDeps) return true;
   if (!ctx.interactive) return false;
   const yes = await ctx.ui.confirm(
-    { message: 'Install skill dependencies now? (Python venv + pip + Chromium — slower)', initialValue: false },
+    { message: ctx.t('skillDepsConfirm'), initialValue: false },
     false
   );
   return yes === true;
 }
 
-/** Provision Python venv + pip requirements for a platform's skills. */
+/** Provision or upgrade Python venv + pip requirements for a platform's skills. */
 function setupPython(ctx, skillsDir) {
   const reqs = dep.collectRequirements(skillsDir);
   if (reqs.length === 0) return;
 
   const py = dep.findPython();
   if (!py) {
-    ctx.ui.warn('Python 3 not found — skipped venv. Install Python 3, then re-run with --with-skills-deps.');
+    ctx.ui.warn(ctx.t('venvNoHost'));
     return;
   }
 
-  ctx.ui.startSpinner('Creating Python venv...');
+  const alreadyExists = dep.venvValid(skillsDir);
+  ctx.ui.startSpinner(ctx.t('venvCreating'));
   if (!dep.createVenv(skillsDir, py)) {
-    ctx.ui.stopSpinner('Could not create Python venv');
-    ctx.ui.warn(`venv creation failed at ${dep.venvDir(skillsDir)} — check your Python install.`);
+    ctx.ui.stopSpinner(ctx.t('venvFailed'));
+    ctx.ui.warn(ctx.t('venvFailed'));
     return;
   }
   dep.pipUpgrade(skillsDir);
-  ctx.ui.stopSpinner(`Python venv ready (${dep.venvDir(skillsDir)})`);
+  ctx.ui.stopSpinner(`${ctx.t('venvReady')} (${dep.venvDir(skillsDir)})`);
 
+  // Upgrade packages if venv already existed (update run), install fresh otherwise.
+  const upgrade = alreadyExists;
   for (const { skill, file } of reqs) {
-    ctx.ui.startSpinner(`Installing Python deps: ${skill}...`);
-    const ok = dep.pipInstall(skillsDir, file);
-    ctx.ui.stopSpinner(ok ? `${skill}: Python deps installed` : `${skill}: some Python deps failed`);
-    if (!ok) {
-      ctx.ui.warn(`pip failed for ${skill}. Retry: "${dep.venvPython(skillsDir)}" -m pip install -r "${file}"`);
+    ctx.ui.startSpinner(ctx.t(upgrade ? 'pipInstalling' : 'pipInstalling', { skill }));
+    const ok = dep.pipInstall(skillsDir, file, upgrade);
+    if (ok) {
+      ctx.ui.stopSpinner(ctx.t('pipInstalled', { skill }));
+    } else {
+      ctx.ui.stopSpinner(ctx.t('pipFailed', { skill, cmd: `"${dep.venvPython(skillsDir)}" -m pip install -r "${file}"` }));
     }
   }
 }
 
-/** Run skill-local npm installs + Chromium for a platform's skills. */
+/** Run skill-local npm installs/upgrades + browser binaries for a platform's skills. */
 function setupNode(ctx, skillsDir) {
-  for (const { skill, dir } of dep.collectSkillPackages(skillsDir)) {
-    ctx.ui.startSpinner(`Installing npm deps: ${skill}...`);
-    const ok = dep.npmInstall(dir);
-    ctx.ui.stopSpinner(ok ? `${skill}: npm deps installed` : `${skill}: npm install failed`);
-    if (!ok) {
-      ctx.ui.warn(`npm install failed in ${dir} — retry manually.`);
+  for (const { skill, dir, hasNodeModules } of dep.collectSkillPackages(skillsDir)) {
+    ctx.ui.startSpinner(ctx.t('npmInstalling', { skill }));
+    const ok = dep.npmInstall(dir, hasNodeModules); // upgrade if node_modules exists
+    if (ok) {
+      ctx.ui.stopSpinner(ctx.t('npmInstalled', { skill }));
+    } else {
+      ctx.ui.stopSpinner(ctx.t('npmFailed', { skill, dir }));
       continue;
     }
-    // Skills using Playwright (e.g. pptx html2pptx) need a browser binary too.
+
+    // Skills using Playwright (e.g. pptx) also need a browser binary.
     if (dep.pkgHasDep(dir, 'playwright')) {
-      ctx.ui.startSpinner(`Downloading Playwright browser for ${skill}...`);
+      ctx.ui.startSpinner(ctx.t('playwrightInstalling', { skill }));
       const pw = dep.installPlaywrightBrowser(dir);
-      ctx.ui.stopSpinner(pw ? `${skill}: Playwright browser ready` : `${skill}: Playwright browser skipped`);
+      ctx.ui.stopSpinner(pw ? ctx.t('playwrightReady', { skill }) : ctx.t('playwrightSkipped', { skill }));
     }
   }
 
+  // Chromium for chrome-devtools (puppeteer-based).
   const chromeScripts = path.join(skillsDir, 'chrome-devtools', 'scripts');
   if (fs.existsSync(path.join(chromeScripts, 'package.json'))) {
-    ctx.ui.startSpinner('Downloading Chromium for chrome-devtools...');
+    ctx.ui.startSpinner(ctx.t('chromiumInstalling'));
     const ok = dep.installChromium(chromeScripts);
-    ctx.ui.stopSpinner(ok ? 'Chromium ready' : 'Chromium download skipped/failed');
-    if (!ok) ctx.ui.warn('Chromium not downloaded — chrome-devtools may prompt on first use.');
+    ctx.ui.stopSpinner(ok ? ctx.t('chromiumReady') : ctx.t('chromiumSkipped'));
   }
 }
 
 /** Detect (don't install) system binaries + global npm CLIs and print guidance. */
 function guideManual(ctx) {
   const missingTools = dep.SYSTEM_TOOLS.filter((t) => !dep.hasCmd(t.cmd));
-  const missingNpm = dep.GLOBAL_NPM.filter((g) => !dep.hasCmd(g.cmd));
+  const missingNpm   = dep.GLOBAL_NPM.filter((g) => !dep.hasCmd(g.cmd));
   if (missingTools.length === 0 && missingNpm.length === 0) return;
 
   const lines = [];
   for (const t of missingTools) lines.push(`${t.cmd}  — ${t.why}\n   ${dep.systemHint(t)}`);
-  for (const g of missingNpm) lines.push(`${g.cmd}  — ${g.why}\n   npm install -g ${g.pkg}`);
-  ctx.ui.note(lines.join('\n'), 'Optional tools to install manually');
+  for (const g of missingNpm)   lines.push(`${g.cmd}  — ${g.why}\n   npm install -g ${g.pkg}`);
+  ctx.ui.note(lines.join('\n'), ctx.t('optionalToolsTitle'));
 }
 
 async function setupSkillDeps(ctx) {
   if (!(await shouldRun(ctx))) {
-    if (!ctx.dryRun) {
-      ctx.ui.info('Skill dependencies skipped — run later with: npx @haposoft/cafekit --with-skills-deps');
-    }
+    if (!ctx.dryRun) ctx.ui.info(ctx.t('skillsSkipped'));
     return ctx;
   }
 
   for (const key of ctx.platforms) {
-    const skillsDir = PLATFORMS[key].skillsDir;
-    setupPython(ctx, skillsDir);
-    setupNode(ctx, skillsDir);
+    setupPython(ctx, PLATFORMS[key].skillsDir);
+    setupNode(ctx, PLATFORMS[key].skillsDir);
   }
 
   guideManual(ctx);

package/bin/phases/summary.js

@@ -6,49 +6,65 @@
  * plain text otherwise.
  */
 
+const fs = require('fs');
+const path = require('path');
 const { PLATFORMS, packageJson } = require('../lib/context');
 
+/** Installed skills that ship a .env.example (i.e. need API keys configured). */
+function skillsNeedingKeys(platforms) {
+  const found = new Set();
+  for (const key of platforms) {
+    const skillsDir = PLATFORMS[key].skillsDir;
+    if (!fs.existsSync(skillsDir)) continue;
+    for (const skill of fs.readdirSync(skillsDir)) {
+      if (fs.existsSync(path.join(skillsDir, skill, '.env.example'))) found.add(skill);
+    }
+  }
+  return [...found].sort();
+}
+
 function printSummary(ctx) {
-  const { results, platforms, options, ui } = ctx;
+  const { results, platforms, options, ui, t } = ctx;
+  const pad = (s) => `${s}:`.padEnd(16, ' ');
 
   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
+    `${pad(t('labelCopied'))}${results.copied}`,
+    `${pad(t('labelUpdated'))}${results.updated}`,
+    `${pad(t('labelUnchanged'))}${results.unchanged}`,
+    `${pad(t('labelPreserved'))}${results.preserved}`,
+    `${pad(t('labelSkills'))}${results.installedSkills > 0 ? t('yes') : t('no')}`,
+    `${pad(t('labelVersion'))}${packageJson.version}`,
+    results.missingDependencies > 0 ? `${pad(t('labelMissing'))}${results.missingDependencies}` : null,
+    results.errors > 0 ? `${pad(t('labelErrors'))}${results.errors}` : null
   ].filter(Boolean).join('\n');
 
-  ui.note(stats, ctx.dryRun ? 'Dry-run preview' : 'Installation complete');
+  ui.note(stats, ctx.dryRun ? t('summaryDryTitle') : t('summaryTitle'));
 
   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/).');
+    const more = results.preservedFiles.length > 8 ? `\n  ... +${results.preservedFiles.length - 8}` : '';
+    ui.warn(`${t('preservedNote', { n: results.preserved })}\n${list}${more}`);
   }
 
   if (ctx.dryRun) {
-    ui.outro('Dry-run only — re-run without --dry-run to apply.');
+    ui.outro(t('dryRunOnly'));
     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');
+    lines.push(key === 'claude' ? t('nsClaude') : t('nsOpencode'));
+  }
+  const keySkills = skillsNeedingKeys(platforms);
+  if (keySkills.length > 0) {
+    lines.push(t('nsKeys', { skills: keySkills.join(', ') }));
   }
-  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');
+    lines.push(t('nsForce'));
   }
-  ui.note(lines.join('\n'), 'Next steps');
+  ui.note(lines.join('\n'), t('nextStepsTitle'));
 
-  ui.outro(`Done — docs: https://github.com/haposoft/cafekit`);
+  ui.outro(t('outroDone'));
 }
 
 module.exports = { printSummary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",