@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/bin/lib/context.js

@@ -27,6 +27,9 @@ function validateManifestV2(manifest) {
   if (!manifest || manifest.version !== 2) return false;
   if (!manifest.runtime?.files || !Array.isArray(manifest.runtime.files)) return false;
   if (!manifest.settings?.template) return false;
+  if (!Array.isArray(manifest.skills?.required)) return false;
+  if (!Array.isArray(manifest.skills?.bundles?.documentSkills)) return false;
+  if (!Array.isArray(manifest.obsolete?.skills)) return false;
   return true;
 }
 
@@ -205,6 +208,8 @@ function parseInstallerArgs(argv) {
     yes: false,
     withSkillsDeps: false,
     withRtk: false,
+    withDocumentSkills: false,
+    withoutDocumentSkills: false,
     platforms: []
   };
 
@@ -221,6 +226,10 @@ function parseInstallerArgs(argv) {
       args.withSkillsDeps = true;
     } else if (arg === '--with-rtk') {
       args.withRtk = true;
+    } else if (arg === '--with-document-skills') {
+      args.withDocumentSkills = true;
+    } else if (arg === '--without-document-skills') {
+      args.withoutDocumentSkills = true;
     } else if (arg === '--platform') {
       args.platforms.push(...String(argv[++i] || '').split(',').filter(Boolean));
     } else if (arg.startsWith('--platform=')) {
@@ -232,6 +241,10 @@ function parseInstallerArgs(argv) {
     }
   }
 
+  if (args.withDocumentSkills && args.withoutDocumentSkills) {
+    throw new Error('--with-document-skills and --without-document-skills cannot be used together');
+  }
+
   // Back-compat alias used throughout the phases.
   args.upgrade = args.forceOverwrite;
   return args;
@@ -298,6 +311,7 @@ function buildContext(argv, runId) {
     results: createResults(),
     trackers: {},    // platformKey → ownership tracker, set per platform
     ownership: {},   // platformFolder → ownership manifest read at run start
+    documentSkills: {}, // platformKey → persisted optional-bundle selection
     cancelled: false
   };
 }

package/bin/lib/i18n.js

@@ -58,6 +58,8 @@ const MESSAGES = {
 
     // Skills / deps setup
     skillDepsConfirm:      'Install skill dependencies? (Python venv, pip, npm, Chromium — takes a few minutes)',
+    documentSkillsConfirm: 'Install optional document skills? (docs, DOCX, PDF, PPTX, XLSX, multimodal)',
+    documentSkillsMetadataRecovery: 'Could not read {path}; preserving document skills to avoid destructive cleanup.',
     skillsSkipped:         'Skill dependencies skipped.\n  Run later: npx @haposoft/cafekit --with-skills-deps',
 
     // rtk token-saver setup
@@ -106,8 +108,8 @@ const MESSAGES = {
 
     // Next steps
     nextStepsTitle:  'Next steps',
-    nsClaude:        'Start coding: /hapo:specs <feature>',
-    nsCodex:         'Start with `$hapo-specs <feature>`; review and trust project hooks with `/hooks`',
+    nsClaude:        'Start coding: /cf:specs <feature>',
+    nsCodex:         'Start with `$cf-specs <feature>`; review and trust project hooks with `/hooks`',
     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.',
@@ -180,6 +182,8 @@ const MESSAGES = {
     changeAddressingOption:'別の名前に変更',
 
     skillDepsConfirm:      'スキルの依存関係をインストールしますか？（Python venv、pip、npm、Chromium — 数分かかります）',
+    documentSkillsConfirm: '任意のドキュメントスキルをインストールしますか？（docs、DOCX、PDF、PPTX、XLSX、multimodal）',
+    documentSkillsMetadataRecovery: '{path} を読み取れないため、破壊的な削除を避けて document skills を保持します。',
     skillsSkipped:         'スキルの依存関係をスキップしました。\n  後で実行: npx @haposoft/cafekit --with-skills-deps',
 
     // rtk token-saver setup
@@ -226,8 +230,8 @@ const MESSAGES = {
     preservedNote:   '編集済みファイル {n} 件はそのままにしました。\n  --force-overwrite で再実行するとリセットできます（.cafekit-backup/ にバックアップ保存）。',
 
     nextStepsTitle:  '次のステップ',
-    nsClaude:        'コーディング開始: /hapo:specs <機能名>',
-    nsCodex:         '`$hapo-specs <機能名>` で開始し、`/hooks` でプロジェクトフックを確認・信頼',
+    nsClaude:        'コーディング開始: /cf:specs <機能名>',
+    nsCodex:         '`$cf-specs <機能名>` で開始し、`/hooks` でプロジェクトフックを確認・信頼',
     nsKeys:          '一部のスキルに API キーが必要です: {skills}\n  <skill>/.env.example を .env にコピーし、値を入力してください',
     nsForce:         '管理ファイルを強制更新: npx @haposoft/cafekit --force-overwrite',
     dryRunOnly:      'ドライラン完了 — ファイルへの変更はありませんでした。\n  変更を適用するには --dry-run なしで再実行してください。',
@@ -299,6 +303,8 @@ const MESSAGES = {
     changeAddressingOption:'Đổi tên khác',
 
     skillDepsConfirm:      'Cài dependencies cho skill ngay? (Python venv, pip, npm, Chromium — mất vài phút)',
+    documentSkillsConfirm: 'Cài thêm nhóm skill tài liệu? (docs, DOCX, PDF, PPTX, XLSX, multimodal)',
+    documentSkillsMetadataRecovery: 'Không đọc được {path}; giữ nguyên skill tài liệu để tránh dọn nhầm dữ liệu.',
     skillsSkipped:         'Đã bỏ qua dependencies skill.\n  Cài sau bằng lệnh: npx @haposoft/cafekit --with-skills-deps',
 
     // rtk token-saver setup
@@ -345,8 +351,8 @@ const MESSAGES = {
     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>',
-    nsCodex:         'Bắt đầu bằng `$hapo-specs <tính-năng>`; kiểm tra và trust project hooks bằng `/hooks`',
+    nsClaude:        'Bắt đầu code: /cf:specs <mô-tả-tính-năng>',
+    nsCodex:         'Bắt đầu bằng `$cf-specs <tính-năng>`; kiểm tra và trust project hooks bằng `/hooks`',
     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.',

package/bin/lib/skill-deps.js

@@ -271,15 +271,15 @@ function collectSkillPackages(skillsDir) {
 
 /** External binaries some skills shell out to — detected, never auto-installed. */
 const SYSTEM_TOOLS = [
-  { cmd: 'ffmpeg', why: 'ai-multimodal (audio/video)', brew: 'brew install ffmpeg', apt: 'sudo apt install ffmpeg', win: 'winget install ffmpeg' },
-  { cmd: 'pdftotext', why: 'pdf (text extraction, poppler)', brew: 'brew install poppler', apt: 'sudo apt install poppler-utils', win: 'choco install poppler' },
-  { cmd: 'rsvg-convert', why: 'generate-graph (PNG export, librsvg)', brew: 'brew install librsvg', apt: 'sudo apt install librsvg2-bin', win: 'choco install rsvg-convert' },
-  { cmd: 'tesseract', why: 'pdf/ai-multimodal (OCR)', brew: 'brew install tesseract', apt: 'sudo apt install tesseract-ocr', win: 'choco install tesseract' }
+  { cmd: 'ffmpeg', skills: ['ai-multimodal'], why: 'ai-multimodal (audio/video)', brew: 'brew install ffmpeg', apt: 'sudo apt install ffmpeg', win: 'winget install ffmpeg' },
+  { cmd: 'pdftotext', skills: ['pdf'], why: 'pdf (text extraction, poppler)', brew: 'brew install poppler', apt: 'sudo apt install poppler-utils', win: 'choco install poppler' },
+  { cmd: 'rsvg-convert', skills: ['generate-graph'], why: 'generate-graph (PNG export, librsvg)', brew: 'brew install librsvg', apt: 'sudo apt install librsvg2-bin', win: 'choco install rsvg-convert' },
+  { cmd: 'tesseract', skills: ['pdf', 'ai-multimodal'], why: 'pdf/ai-multimodal (OCR)', brew: 'brew install tesseract', apt: 'sudo apt install tesseract-ocr', win: 'choco install tesseract' }
 ];
 
 /** Global npm CLIs some skills expect — detected, never auto-installed. */
 const GLOBAL_NPM = [
-  { cmd: 'agent-browser', pkg: 'agent-browser', why: 'agent-browser skill' }
+  { cmd: 'agent-browser', pkg: 'agent-browser', skills: ['agent-browser'], why: 'agent-browser skill' }
 ];
 
 /** Per-OS install hint for a SYSTEM_TOOLS entry. */

package/bin/phases/claude-runtime.js

@@ -276,8 +276,31 @@ function copyRulesDirectory(ctx, platformKey) {
   report(ctx, treeAction(agg), 'rules/ directory');
 }
 
+/**
+ * Copy the output-styles/ tree from the one canonical source. Claude Code discovers
+ * these natively under `.claude/`; Codex CLI has no output-style feature, so its rules
+ * hook reads the selected file and injects it once per session instead.
+ */
+function copyOutputStylesDirectory(ctx, platformKey) {
+
+  const src = path.join(SRC, 'claude/output-styles');
+  const dest = getRuntimeSupportTargetDir(platformKey, 'output-styles');
+  if (!fs.existsSync(src)) {
+    ctx.ui.warn('output-styles/ directory not found');
+    ctx.results.missingDependencies++;
+    return;
+  }
+
+  const transform = getCopyOptions(platformKey, {}).transform;
+  const agg = copyManagedTree({
+    src, dest, platformFolder: PLATFORMS[platformKey].folder, ctx, tracker: ctx.trackers[platformKey], transform
+  });
+  report(ctx, treeAction(agg), 'output-styles/ directory');
+}
+
 module.exports = {
   copyRoutingFile,
+  copyOutputStylesDirectory,
   copyClaudeRuntimeFiles,
   removeObsoleteClaudeRuntimeFiles,
   copyClaudeMdFile,

package/bin/phases/claude-settings.js

@@ -109,6 +109,14 @@ function mergeClaudeSettings(ctx, platformKey) {
     }
   }
 
+  // outputStyle: a reader preference, not CafeKit functionality. Seed it once when
+  // the user has none, and never replace a choice they made — not even under
+  // --force-overwrite, which exists to repair managed files, not to reset taste.
+  if (managedSettings.outputStyle && !existingSettings.outputStyle) {
+    mergedSettings.outputStyle = managedSettings.outputStyle;
+    ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: outputStyle seeded (${managedSettings.outputStyle})`);
+  }
+
   // hooks: merge managed hooks per command (not per entry). An entry is keyed
   // by its matcher; commands missing from the matching entry are appended, so
   // a new command added to an existing matcher entry is not swallowed on

package/bin/phases/codex-hooks.js

@@ -0,0 +1,156 @@
+/**
+ * Phase helper: Codex hooks.json merge.
+ *
+ * `.codex/hooks.json` is a shared configuration file, not a CafeKit payload. It was
+ * previously copied verbatim, which made a single user-added hook turn the whole file
+ * into a user-modified artifact: a normal install then preserved CafeKit's stale hooks,
+ * and `--force-overwrite` destroyed the user's. Merging per command removes that choice.
+ *
+ * This mirrors how `.claude/settings.json` is handled, so hooks.json likewise stays
+ * outside the ownership model: CafeKit owns its own entries, the user owns theirs, and
+ * neither erases the other. Honors dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+
+const CODEX_SRC = path.join(__dirname, '../../src/codex');
+const WINDOWS_HOOK_COMMAND = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
+
+/** The hook script a command runs, which is stable across installs and platforms. */
+function hookScript(command) {
+  if (typeof command !== 'string') return null;
+  const match = command.match(/[/\\]hooks[/\\]([a-z0-9-]+\.cjs)/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Rewrite a managed `commandWindows` into a path-encoded invocation. Absolute Windows
+ * paths cannot be quoted safely inside the Codex command string, so the path travels
+ * base64url and is decoded by the launcher.
+ */
+function materializeWindowsCommand(handler, projectRoot) {
+  if (typeof handler.commandWindows !== 'string') return handler;
+  const match = handler.commandWindows.match(WINDOWS_HOOK_COMMAND);
+  if (!match) throw new Error(`Unsupported Codex Windows hook command: ${handler.commandWindows}`);
+  const hookPath = path.join(fs.realpathSync(projectRoot), '.codex', 'hooks', match[1]);
+  const encoded = Buffer.from(hookPath, 'utf8').toString('base64url');
+  return {
+    ...handler,
+    commandWindows: 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' + encoded,
+  };
+}
+
+/** Drop CafeKit hooks the manifest has retired, leaving foreign entries untouched. */
+function pruneObsoleteCodexHooks(config, ctx) {
+  const obsolete = ctx.manifest?.obsolete?.settingsHookCommandSubstrings || [];
+  if (!config.hooks || obsolete.length === 0) return { config, removed: 0 };
+
+  let removed = 0;
+  const pruned = {};
+  for (const [eventName, groups] of Object.entries(config.hooks)) {
+    if (!Array.isArray(groups)) { pruned[eventName] = groups; continue; }
+    const keptGroups = [];
+    for (const group of groups) {
+      if (!Array.isArray(group?.hooks)) { keptGroups.push(group); continue; }
+      const keptHooks = group.hooks.filter((handler) => {
+        const command = handler?.command || '';
+        const isObsolete = obsolete.some((substring) => command.includes(substring));
+        if (isObsolete) removed += 1;
+        return !isObsolete;
+      });
+      if (keptHooks.length > 0) keptGroups.push({ ...group, hooks: keptHooks });
+    }
+    if (keptGroups.length > 0) pruned[eventName] = keptGroups;
+  }
+  return { config: removed > 0 ? { ...config, hooks: pruned } : config, removed };
+}
+
+/**
+ * Merge CafeKit-managed Codex hooks into the project's hooks.json, preserving every
+ * entry CafeKit did not author. Codex only.
+ */
+function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
+  if (platformKey !== 'codex') return;
+
+  const templatePath = path.join(CODEX_SRC, 'hooks.json');
+  if (!fs.existsSync(templatePath)) {
+    ctx.ui.warn('Codex hooks template not found: src/codex/hooks.json');
+    return;
+  }
+  const managed = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  const targetPath = path.join(PLATFORMS.codex.folder, 'hooks.json');
+
+  let existing = {};
+  if (fs.existsSync(targetPath)) {
+    // A malformed hooks.json must not abort the install and must never be
+    // overwritten blind: skip the merge and say why.
+    try {
+      existing = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    } catch (error) {
+      ctx.ui.warn(`Codex hooks: ${targetPath} is not valid JSON (${error.message}). `
+        + 'Skipping the hooks merge — fix the file and re-run the installer.');
+      ctx.results.errors++;
+      return;
+    }
+  }
+
+  const { config: base, removed } = pruneObsoleteCodexHooks({ ...existing }, ctx);
+  if (removed > 0) {
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: removed ${removed} obsolete hook(s)`);
+    ctx.results.updated++;
+  }
+
+  const merged = { ...base };
+  if (typeof managed.description === 'string' && typeof merged.description !== 'string') {
+    merged.description = managed.description;
+  }
+  merged.hooks = { ...(base.hooks || {}) };
+
+  let added = 0;
+  for (const [eventName, managedGroups] of Object.entries(managed.hooks || {})) {
+    const groups = Array.isArray(merged.hooks[eventName]) ? [...merged.hooks[eventName]] : [];
+    // A script already registered anywhere under this event stays where the user put
+    // it. Matching on the script rather than the whole command survives the path
+    // differences between installs and platforms.
+    const registered = new Set(
+      groups.flatMap((group) => (group?.hooks || []).map((handler) => hookScript(handler?.command))).filter(Boolean),
+    );
+
+    for (const managedGroup of managedGroups) {
+      const wanted = (managedGroup.hooks || [])
+        .filter((handler) => {
+          const script = hookScript(handler?.command);
+          return script && !registered.has(script);
+        })
+        .map((handler) => materializeWindowsCommand(handler, projectRoot));
+      if (wanted.length === 0) continue;
+
+      const matcher = managedGroup.matcher || '';
+      const target = groups.find((group) => (group?.matcher || '') === matcher && Array.isArray(group?.hooks));
+      if (target) {
+        target.hooks = [...target.hooks, ...wanted];
+      } else {
+        groups.push({ ...managedGroup, hooks: wanted });
+      }
+      for (const handler of wanted) registered.add(hookScript(handler.command));
+      added += wanted.length;
+      ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: ${eventName} merged (+${wanted.length})`);
+    }
+
+    merged.hooks[eventName] = groups;
+  }
+
+  if (added === 0 && removed === 0) {
+    ctx.ui.detail(`  → ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: already registered`);
+    ctx.results.unchanged++;
+  }
+
+  if (!ctx.dryRun) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
+  }
+}
+
+module.exports = { mergeCodexHooks, pruneObsoleteCodexHooks, hookScript };

package/bin/phases/codex-runtime.js

@@ -5,57 +5,32 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
-const { copyRulesDirectory } = require('./claude-runtime');
+const { copyRulesDirectory, copyOutputStylesDirectory } = require('./claude-runtime');
 const {
   managedRange,
   upsertManagedCodexBlock
 } = require('../lib/codex-install');
+const { mergeCodexHooks } = require('./codex-hooks');
 
 const SRC = path.join(__dirname, '../../src');
 const CODEX_SRC = path.join(SRC, 'codex');
 
+// hooks.json is merged by `codex-hooks.js`, not copied: it is a shared config file
+// the user also writes to, so a verbatim copy would either preserve CafeKit's stale
+// hooks or destroy the user's.
 const CODEX_OWN_RUNTIME = [
   ['gitignore', '.gitignore'],
-  ['runtime.json', 'runtime.json'],
-  ['hooks.json', 'hooks.json']
+  ['runtime.json', 'runtime.json']
 ];
 
-const WINDOWS_HOOK_COMMAND = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
-
-function materializeWindowsHookCommands(content, projectRoot = process.cwd()) {
-  const config = JSON.parse(content);
-  const canonicalRoot = fs.realpathSync(projectRoot);
-
-  for (const groups of Object.values(config.hooks || {})) {
-    for (const group of groups) {
-      for (const handler of group.hooks || []) {
-        if (typeof handler.commandWindows !== 'string') continue;
-        const match = handler.commandWindows.match(WINDOWS_HOOK_COMMAND);
-        if (!match) {
-          throw new Error(`Unsupported Codex Windows hook command: ${handler.commandWindows}`);
-        }
-        const hookPath = path.join(canonicalRoot, '.codex', 'hooks', match[1]);
-        const encodedPath = Buffer.from(hookPath, 'utf8').toString('base64url');
-        handler.commandWindows = (
-          'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' +
-          encodedPath
-        );
-      }
-    }
-  }
-
-  return `${JSON.stringify(config, null, 2)}\n`;
-}
-
-function writeSourceFile(ctx, platformKey, src, dest, label, transform) {
+function writeSourceFile(ctx, platformKey, src, dest, label) {
   const platform = PLATFORMS[platformKey];
   const { action } = writeManagedFile({
     src,
     dest,
     platformFolder: platform.folder,
     ctx,
-    tracker: ctx.trackers[platformKey],
-    transform
+    tracker: ctx.trackers[platformKey]
   });
   report(ctx, action, label);
 }
@@ -68,10 +43,7 @@ function installRuntimeFiles(ctx, platformKey) {
       platformKey,
       path.join(CODEX_SRC, sourceRel),
       path.join(platform.folder, targetRel),
-      `Codex runtime: ${targetRel}`,
-      sourceRel === 'hooks.json'
-        ? (content) => materializeWindowsHookCommands(content, process.cwd())
-        : undefined
+      `Codex runtime: ${targetRel}`
     );
   }
   writeSourceFile(
@@ -82,6 +54,8 @@ function installRuntimeFiles(ctx, platformKey) {
     'Codex skills: .agents/.gitignore'
   );
 
+  mergeCodexHooks(ctx, platformKey);
+
   const agg = copyManagedTree({
     src: path.join(CODEX_SRC, 'hooks'),
     dest: path.join(platform.folder, 'hooks'),
@@ -92,6 +66,15 @@ function installRuntimeFiles(ctx, platformKey) {
   report(ctx, treeAction(agg), 'Codex native hooks');
   // Keep one canonical command analyzer in the Claude source tree, then
   // materialize the same bytes into the installed Codex runtime.
+  // One canonical runtime schema lives in the Claude source tree; both installed
+  // runtimes reference it as ./runtime.schema.json beside their runtime.json.
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'runtime.schema.json'),
+    path.join(platform.folder, 'runtime.schema.json'),
+    'Codex runtime schema'
+  );
   writeSourceFile(
     ctx,
     platformKey,
@@ -99,6 +82,13 @@ function installRuntimeFiles(ctx, platformKey) {
     path.join(platform.folder, 'hooks', 'lib', 'privacy-command-analysis.cjs'),
     'Codex privacy command analyzer'
   );
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'hooks', 'lib', 'secret-keywords.cjs'),
+    path.join(platform.folder, 'hooks', 'lib', 'secret-keywords.cjs'),
+    'Codex secret keyword matcher'
+  );
   writeSourceFile(
     ctx,
     platformKey,
@@ -154,9 +144,10 @@ function installCodexRuntime(ctx, platformKey) {
   if (platformKey !== 'codex') return ctx;
   installRuntimeFiles(ctx, platformKey);
   copyRulesDirectory(ctx, platformKey);
+  copyOutputStylesDirectory(ctx, platformKey);
   installNativeRuleOverrides(ctx, platformKey);
   installManagedAgentsMd(ctx);
   return ctx;
 }
 
-module.exports = { installCodexRuntime, materializeWindowsHookCommands };
+module.exports = { installCodexRuntime };

package/bin/phases/copy-payload.js

@@ -127,12 +127,18 @@ function copyPlatformFiles(ctx, platformKey) {
       });
     }
 
-    // Additional required skills.
+    // Core skills plus the optional document bundle selected for this runtime.
     let requiredSkills = [];
     if (hasPlatformCapability(platformKey, 'skills')) {
       requiredSkills = ctx.manifest?.skills?.required || [];
+      if (ctx.documentSkills?.[platformKey]?.enabled) {
+        requiredSkills = [
+          ...requiredSkills,
+          ...(ctx.manifest?.skills?.bundles?.documentSkills || [])
+        ];
+      }
     }
-    requiredSkills
+    [...new Set(requiredSkills)]
       .filter((skillName) => skillName !== 'specs')
       .forEach((skillName) => {
         const skillSource = path.join(skillsSourceDir, skillName);

package/bin/phases/select-skill-bundles.js

@@ -0,0 +1,96 @@
+/** Resolve the optional document-skills bundle for each selected runtime. */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+
+function readMetadata(platformKey) {
+  const target = path.join(PLATFORMS[platformKey].folder, 'cafekit.json');
+  if (!fs.existsSync(target)) return { state: 'absent', target, metadata: null };
+  try {
+    const metadata = JSON.parse(fs.readFileSync(target, 'utf8'));
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+      return { state: 'invalid', target, metadata: null, reason: 'expected a JSON object' };
+    }
+    return { state: 'valid', target, metadata };
+  } catch (error) {
+    return { state: 'invalid', target, metadata: null, reason: error.message };
+  }
+}
+
+function explicitSelection(options) {
+  if (options.withDocumentSkills) {
+    return { enabled: true, selectionSource: 'cli-opt-in' };
+  }
+  if (options.withoutDocumentSkills) {
+    return { enabled: false, selectionSource: 'cli-opt-out' };
+  }
+  return null;
+}
+
+async function selectDocumentSkills(ctx) {
+  const explicit = explicitSelection(ctx.options);
+  const unresolvedFresh = [];
+
+  for (const platformKey of ctx.platforms) {
+    if (explicit) {
+      ctx.documentSkills[platformKey] = { ...explicit };
+      continue;
+    }
+
+    const metadataResult = readMetadata(platformKey);
+    const metadata = metadataResult.metadata;
+    if (metadata?.schemaVersion >= 2 && typeof metadata.documentSkills?.enabled === 'boolean') {
+      ctx.documentSkills[platformKey] = {
+        enabled: metadata.documentSkills.enabled,
+        selectionSource: metadata.documentSkills.selectionSource || 'persisted'
+      };
+    } else if (metadataResult.state === 'valid') {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'legacy-upgrade'
+      };
+    } else if (metadataResult.state === 'invalid') {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'metadata-recovery'
+      };
+      ctx.ui.warn(ctx.t('documentSkillsMetadataRecovery', {
+        path: metadataResult.target
+      }));
+    } else if (fs.existsSync(path.join(PLATFORMS[platformKey].folder, 'cafekit-manifest.json'))) {
+      ctx.documentSkills[platformKey] = {
+        enabled: true,
+        selectionSource: 'legacy-upgrade'
+      };
+    } else {
+      unresolvedFresh.push(platformKey);
+    }
+  }
+
+  let freshEnabled = false;
+  let source = 'default-fresh';
+  if (unresolvedFresh.length > 0 && ctx.interactive) {
+    const answer = await ctx.ui.confirm(
+      { message: ctx.t('documentSkillsConfirm'), initialValue: false },
+      false
+    );
+    if (ctx.ui.isCancel(answer)) {
+      ctx.cancelled = true;
+      return ctx;
+    }
+    freshEnabled = Boolean(answer);
+    source = 'interactive';
+  }
+
+  for (const platformKey of unresolvedFresh) {
+    ctx.documentSkills[platformKey] = {
+      enabled: freshEnabled,
+      selectionSource: source
+    };
+  }
+
+  return ctx;
+}
+
+module.exports = { readMetadata, explicitSelection, selectDocumentSkills };

package/bin/phases/skill-inventory.js

@@ -0,0 +1,71 @@
+/** Ownership-aware removal for retired and deselected skill directories. */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { hashFile } = require('../lib/manifest');
+
+function listTreeEntries(root) {
+  const entries = [];
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      entries.push({ target, entry });
+      if (entry.isDirectory() && !entry.isSymbolicLink()) visit(target);
+    }
+  };
+  visit(root);
+  return entries;
+}
+
+function classifySkillTree(ctx, platformKey, skillName) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const target = path.join(platform.skillsDir, skillName);
+  if (!fs.existsSync(target)) return { target, removable: false, absent: true };
+  if (!fs.lstatSync(target).isDirectory()) {
+    return { target, removable: false, absent: false };
+  }
+
+  const entries = listTreeEntries(target);
+  const ownership = ctx.ownership?.[platform.folder]?.files || {};
+  const unsafe = entries.some(({ target: item, entry }) => {
+    if (!entry.isFile() || entry.isSymbolicLink()) return !entry.isDirectory();
+    const key = tracker.keyFor(item);
+    return ownership[key]?.sha256 !== hashFile(item);
+  });
+  return { target, removable: entries.length > 0 && !unsafe, absent: false };
+}
+
+function removeSkill(ctx, platformKey, skillName) {
+  const tracker = ctx.trackers[platformKey];
+  const classified = classifySkillTree(ctx, platformKey, skillName);
+  if (classified.absent) return;
+
+  if (!classified.removable) {
+    ctx.ui.warn(`Preserved user-owned skill: ${classified.target}`);
+    ctx.results.preserved++;
+    ctx.results.preservedFiles.push(classified.target);
+    return;
+  }
+
+  const prefix = `${tracker.keyFor(classified.target).replace(/\/$/, '')}/`;
+  if (!ctx.dryRun) {
+    fs.rmSync(classified.target, { recursive: true, force: true });
+    tracker.prunePrefix(prefix);
+  }
+  ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed skill: ${classified.target}`);
+  ctx.results.updated++;
+}
+
+function reconcileSkillInventory(ctx, platformKey) {
+  const retired = ctx.manifest?.obsolete?.skills || [];
+  for (const skillName of retired) removeSkill(ctx, platformKey, skillName);
+
+  if (!ctx.documentSkills?.[platformKey]?.enabled) {
+    const optional = ctx.manifest?.skills?.bundles?.documentSkills || [];
+    for (const skillName of optional) removeSkill(ctx, platformKey, skillName);
+  }
+}
+
+module.exports = { listTreeEntries, classifySkillTree, removeSkill, reconcileSkillInventory };

package/bin/phases/skills-setup.js

@@ -115,8 +115,15 @@ async function setupNode(ctx, skillsDir) {
 
 /** 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 installed = new Set();
+  for (const key of ctx.platforms) {
+    const skillsDir = PLATFORMS[key].skillsDir;
+    if (!fs.existsSync(skillsDir)) continue;
+    for (const name of fs.readdirSync(skillsDir)) installed.add(name);
+  }
+  const applies = (item) => (item.skills || []).some((skill) => installed.has(skill));
+  const missingTools = dep.SYSTEM_TOOLS.filter((t) => applies(t) && !dep.hasCmd(t.cmd));
+  const missingNpm   = dep.GLOBAL_NPM.filter((g) => applies(g) && !dep.hasCmd(g.cmd));
   if (missingTools.length === 0 && missingNpm.length === 0) return;
 
   const lines = [];