dsh-claude-move 0.2.1

package/lib/skills-provider.mjs

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/skills-provider.mjs — Claude Code 技能 → DSH SkillProvider（F12，零 DSH 依赖）。
+//
+// DSH 技能名必须是 kebab-case，Claude 技能名不做此保证，这里做归一化
+// （小写、非 [a-z0-9-] 折叠为 '-'、冲突加 -2/-3 后缀）。候选只含名称与描述，
+// 完整正文在 get() 时按需读取（与 DSH 技能契约一致）。发现约定沿用
+// YYTbit/dsh-plugin-claude-bridge（MIT，见 THIRD_PARTY_NOTICES.md）。
+//
+// 对齐当前 DSH 技能契约：list(options)/get(candidate, options) 接收
+// `{ cwd, signal }`；options.cwd 命中项目时把该项目 `<cwd>/.claude/skills`
+// 一并暴露（Claude Code 项目级技能）；candidate 携带 `path` 与 `metadata`
+// 字段；list 尊重 signal 中止。
+
+import { readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { parseFrontmatter } from './frontmatter.mjs'
+
+/** Claude 技能提供者的固定 provider 名（技能目录里可辨识）。 */
+export const CLAUDE_SKILLS_PROVIDER = 'claude-move'
+
+/** 归一化后的技能名必须满足的 DSH kebab-case 模式。 */
+export const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** 全局技能 rank（更低者赢得同名冲突：全局优先于项目级）。 */
+export const GLOBAL_SKILL_RANK = 260
+
+/** 项目级技能 rank（高于全局：同名时全局技能胜出）。 */
+export const PROJECT_SKILL_RANK = 280
+
+/**
+ * 把任意技能名归一化为 kebab-case。
+ * @param raw - 原始名称。
+ * @param fallback - 归一化结果为空时使用。
+ * @returns kebab-case 名称。
+ */
+export function kebabName(raw, fallback = 'skill') {
+  const slug = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+  return slug.length > 0 ? slug : fallback
+}
+
+/**
+ * 读取一个技能文件（SKILL.md 或扁平 .md）。DSH 技能系统要求每个技能必须有
+ * 非空 name 与 description（空 description 会直接抛错并使整个技能目录加载
+ * 失败，见 issue#1）；缺失或为空时跳过该文件（与官方 dsh-skill-filesystem
+ * 的「warn + ignore」行为一致），绝不产出非法候选。
+ * @param file - 绝对路径。
+ * @returns `{ name, description, argumentHint?, level?, content, path, meta }` 或 null。
+ */
+async function readSkillFile(file) {
+  try {
+    const content = await readFile(file, 'utf8')
+    const { meta, body } = parseFrontmatter(content)
+    if (body.trim().length === 0) return null
+    const name = (meta.name ?? path.basename(file).replace(/\.md$/, '')).trim()
+    const description = (meta.description ?? '').trim()
+    if (name.length === 0 || description.length === 0) return null
+    const level = meta.level ? Number.parseInt(meta.level, 10) : undefined
+    return {
+      name,
+      description,
+      ...(meta['argument-hint'] ? { argumentHint: meta['argument-hint'] } : {}),
+      ...(Number.isFinite(level) ? { level } : {}),
+      content: body,
+      path: file,
+      meta,
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 发现一个技能根目录下的全部技能文件：`<root>/<name>/SKILL.md` 与 `<root>/<name>.md`。
+ * 显式排除非技能文档：MEMORY.md 与 README.md（Claude skills 目录惯用的
+ * 索引/说明文件，无 name/description frontmatter，误注册会令 DSH 技能加载
+ * 整体失败，issue#1）。排除文件名匹配大小写不敏感。
+ * @param root - 技能根目录。
+ * @param signal - 可选 AbortSignal；中止时抛出 signal.reason。
+ * @returns 技能文件绝对路径数组；目录缺失返回空数组。
+ */
+async function discoverSkillFiles(root, signal) {
+  let entries
+  try {
+    signal?.throwIfAborted()
+    entries = await readdir(root, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const NON_SKILL_FILES = /^(memory|readme)\.md$/i
+  const files = []
+  for (const entry of entries) {
+    signal?.throwIfAborted()
+    if (entry.isDirectory()) {
+      files.push(path.join(root, entry.name, 'SKILL.md'))
+    } else if (entry.isFile() && entry.name.endsWith('.md') && !NON_SKILL_FILES.test(entry.name)) {
+      files.push(path.join(root, entry.name))
+    }
+  }
+  return files
+}
+
+/**
+ * 构造 Claude 技能 SkillProvider（F12）。
+ *
+ * 归属校验采用候选对象身份（与 dsh-resume-plugin 一致）：list() 为同一路径
+ * 且同一分配名复用同一候选对象，get() 拒绝任何非该身份的 candidate。
+ * 项目级技能（`<cwd>/.claude/skills`）按 options.cwd 动态并入，rank 低于
+ * 全局（同名冲突全局胜出）；跨 cwd 的候选对象身份隔离（切换目录后旧候选
+ * 归属被回收，get 返回 undefined，由注册表按需失效）。
+ * @param options - `{ roots: string[], maxSkills: number }`。
+ * @returns `{ name, list, get }`；candidate.locator 为 `{ path }`。
+ */
+export function makeClaudeSkillsProvider({ roots, maxSkills = 30 }) {
+  // path → { candidate, assignedName, rank }：跨 list() 调用保持候选对象身份稳定。
+  const owned = new Map()
+
+  // 全集上分配 kebab 名：冲突（含字面 dup-2 撞名）追加 -2/-3 后缀。
+  const assignNames = (skills) => {
+    const assigned = new Map()
+    const taken = new Set()
+    for (const skill of skills) {
+      const base = kebabName(skill.name)
+      let finalName = base
+      let n = 2
+      while (taken.has(finalName)) finalName = `${base}-${n++}`
+      taken.add(finalName)
+      assigned.set(skill.path, finalName)
+    }
+    return assigned
+  }
+
+  const provider = {
+    name: CLAUDE_SKILLS_PROVIDER,
+    async list(options = {}) {
+      const signal = options?.signal
+      signal?.throwIfAborted()
+
+      const allRoots = [...roots]
+      let projectRootIndex = -1
+      // 项目级技能：options.cwd 命中项目时并入（Claude Code 项目技能布局）。
+      if (typeof options?.cwd === 'string' && options.cwd.length > 0) {
+        projectRootIndex = allRoots.length
+        allRoots.push(path.join(options.cwd, '.claude', 'skills'))
+      }
+
+      // 按发现来源标记项目级文件（同一文件树里既有目录束也有扁平文件，不能用路径形态判断）。
+      const files = []
+      for (let i = 0; i < allRoots.length; i++) {
+        signal?.throwIfAborted()
+        const discovered = await discoverSkillFiles(allRoots[i], signal)
+        for (const file of discovered) files.push({ file, project: i === projectRootIndex })
+      }
+      const skills = []
+      for (const entry of files) {
+        signal?.throwIfAborted()
+        const skill = await readSkillFile(entry.file)
+        if (skill) skills.push({ ...skill, project: entry.project })
+      }
+      const assigned = assignNames(skills)
+
+      const candidates = []
+      const seen = new Set()
+      for (const skill of skills) {
+        signal?.throwIfAborted()
+        const finalName = assigned.get(skill.path)
+        const rank = skill.project ? PROJECT_SKILL_RANK : GLOBAL_SKILL_RANK
+        const prev = owned.get(skill.path)
+        if (prev && prev.assignedName === finalName && prev.rank === rank) {
+          candidates.push(prev.candidate)
+        } else {
+          const candidate = {
+            name: finalName,
+            description: skill.description,
+            ...(skill.argumentHint ? { whenToUse: `argument hint: ${skill.argumentHint}` } : {}),
+            invocation: { modelInvocable: true, userInvocable: true },
+            provider: provider.name,
+            source: skill.project ? 'claude-project' : 'claude',
+            resourceBase: { kind: 'directory', path: path.dirname(skill.path) },
+            rank,
+            locator: { path: skill.path },
+            path: skill.path,
+            metadata: skill.meta,
+          }
+          owned.set(skill.path, { candidate, assignedName: finalName, rank })
+          candidates.push(candidate)
+        }
+        seen.add(skill.path)
+      }
+      for (const filePath of [...owned.keys()]) {
+        if (!seen.has(filePath)) owned.delete(filePath)
+      }
+      return candidates.sort((a, b) => a.name.localeCompare(b.name)).slice(0, maxSkills)
+    },
+    async get(candidate, options = {}) {
+      options?.signal?.throwIfAborted()
+      const prev = candidate?.locator?.path ? owned.get(candidate.locator.path) : undefined
+      if (!prev || prev.candidate !== candidate) return undefined
+      const skill = await readSkillFile(candidate.locator.path)
+      if (!skill) return undefined
+      return {
+        name: candidate.name,
+        description: candidate.description,
+        ...(candidate.whenToUse ? { whenToUse: candidate.whenToUse } : {}),
+        invocation: { modelInvocable: true, userInvocable: true },
+        provider: provider.name,
+        source: candidate.source,
+        resourceBase: candidate.resourceBase,
+        content: skill.content,
+        path: skill.path,
+        metadata: skill.meta,
+      }
+    },
+  }
+  return provider
+}

package/lib/sources/claude/mapper.mjs

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/sources/claude/mapper.mjs — Claude Code 源映射器（四合一迁移向导，纯函数）。
+//
+// 清单 → 迁移计划：
+//   - sessions → import-session（会话转换与落盘复用一期 convertClaudeJsonl /
+//     persistConverted，provider 'claude-code'；幂等走一期 imports.json，无 digest）。
+//   - skills（一期已过滤为含 name+description）→ copy（目录束整目录复制，扁平
+//     .md 写入 SKILL.md）。
+//   - memories（projects/*/memory/*.md）→ append-section（DSH 全局 AGENTS.md 管理段，
+//     每条一个段；一期 F11 的实时注入同时保留，两者互补：AGENTS.md 落盘可审计，
+//     实时注入按请求刷新）。
+//   - instructions（全局 CLAUDE.md）→ append-section。
+//   - hooks（settings.json）→ unsupported 清单。
+
+import { readFile } from 'node:fs/promises'
+import { planKey } from '../contract.mjs'
+import { defaultAgentsMdPath } from '../../agmd-section.mjs'
+import { skillTargetPath, kebabName } from '../../skill-migrate.mjs'
+import { hookUnsupportedPlan } from '../../commands-migrate.mjs'
+
+/**
+ * 映射 Claude 检测清单为迁移计划。
+ * @param source - 'claude'。
+ * @param detection - claude/parser.mjs 的 detect() 输出。
+ * @param opts - `{ skillsDir, agentsMdPath }`。
+ * @returns `{ plans, errors }`。
+ */
+export async function mapSource(source, detection, opts = {}) {
+  const plans = []
+  const errors = []
+  const agentsMdPath = opts.agentsMdPath ?? defaultAgentsMdPath()
+  const skillsDir = opts.skillsDir
+
+  for (const session of detection.sessions ?? []) {
+    plans.push({
+      key: planKey(source, 'session', session.file),
+      from: source,
+      kind: 'session',
+      action: 'import-session',
+      source: { file: session.file, title: session.title, cwd: session.cwd, importKey: session.file, turns: session.turns },
+      target: {},
+      provider: 'claude-code',
+      title: session.title,
+    })
+  }
+
+  for (const skill of detection.skills ?? []) {
+    plans.push({
+      key: planKey(source, 'skill', skill.id),
+      from: source,
+      kind: 'skill',
+      action: 'copy',
+      source: { file: skill.file, dir: skill.dir, name: skill.name, ...(skill.flat ? { flat: true } : {}) },
+      target: skillsDir ? { path: skillTargetPath(skillsDir, kebabName(skill.name)) } : {},
+      digest: skill.digest,
+    })
+  }
+
+  for (const memory of detection.memories ?? []) {
+    try {
+      const content = await readFile(memory.file, 'utf8')
+      plans.push({
+        key: planKey(source, 'memory', memory.id),
+        from: source,
+        kind: 'memory',
+        action: 'append-section',
+        source: { file: memory.file, kind: memory.kind },
+        target: { path: agentsMdPath },
+        content,
+        digest: memory.digest,
+      })
+    } catch (err) {
+      errors.push(`memory:${memory.file}: ${String((err && err.message) || err)}`)
+    }
+  }
+
+  for (const instruction of detection.instructions ?? []) {
+    try {
+      const content = await readFile(instruction.file, 'utf8')
+      plans.push({
+        key: planKey(source, 'instruction', instruction.id),
+        from: source,
+        kind: 'instruction',
+        action: 'append-section',
+        source: { file: instruction.file, kind: instruction.kind },
+        target: { path: agentsMdPath },
+        content,
+        digest: instruction.digest,
+      })
+    } catch (err) {
+      errors.push(`instruction:${instruction.file}: ${String((err && err.message) || err)}`)
+    }
+  }
+
+  for (const hook of detection.hooks ?? []) {
+    plans.push(hookUnsupportedPlan(
+      source, hook.id, hook.file,
+      'Claude Code settings.json 钩子（PreToolUse 等）在 DSH 无插件级等价 seam（宿主 tools/post-execute 瀑布需 composition 级接入），未自动迁移',
+    ))
+  }
+  return { plans, ...(errors.length > 0 ? { errors } : {}) }
+}

package/lib/sources/claude/parser.mjs

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/sources/claude/parser.mjs — Claude Code 源解析器（四合一迁移向导）。
+//
+// 复用一期 discovery.mjs 的扫描能力（projects/*/*.jsonl、memory、skills、
+// CLAUDE.md、settings.json），输出向导统一的 Detection 形状。只读白名单：
+// projects 目录、skills 目录、CLAUDE.md、settings.json —— 凭据文件
+// （~/.claude.json 等）永不读取。git 探测默认关闭（向导只关心条目，不关心
+// 仓库状态；scanGit 开启会派生 git 子进程）。
+
+import path from 'node:path'
+import { homedir } from 'node:os'
+import { readFile } from 'node:fs/promises'
+import {
+  locateClaudeHome as locateClaudeRoot,
+  scanClaudeHome,
+} from '../../discovery.mjs'
+import { assertAllowedRead, digestText, emptyDetection, errorText, recordError } from '../contract.mjs'
+
+export const source = 'claude'
+
+/** Claude 数据根定位（$CLAUDE_CONFIG_DIR / ~/.claude，与一期一致）。 */
+export function locateHome(env = process.env, home = homedir()) {
+  return locateClaudeRoot(env, home)
+}
+
+/** 只读白名单：仅四类路径（projects/skills/CLAUDE.md/settings.json）。 */
+export function whitelist(home) {
+  return [
+    path.join(home, 'projects'),
+    path.join(home, 'skills'),
+    path.join(home, 'CLAUDE.md'),
+    path.join(home, 'settings.json'),
+  ]
+}
+
+/**
+ * 从 settings.json 提取 hooks（Claude hooks → 不支持清单的输入）。
+ * @param file - settings.json 绝对路径。
+ * @returns HookItem 数组；无 hooks/解析失败返回空数组（失败记 errors）。
+ */
+async function scanHooks(file, detection) {
+  let raw
+  try {
+    raw = await readFile(assertAllowedRead(whitelist(detection.home), file), 'utf8')
+  } catch (err) {
+    recordError(detection, 'settings.json', err)
+    return []
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (err) {
+    recordError(detection, 'settings.json', 'JSON 解析失败：' + errorText(err))
+    return []
+  }
+  const hooks = parsed && typeof parsed === 'object' ? parsed.hooks : undefined
+  if (!hooks || typeof hooks !== 'object') return []
+  const items = []
+  for (const [event, defs] of Object.entries(hooks)) {
+    if (!Array.isArray(defs)) continue
+    for (const def of defs) {
+      const matcher = def && typeof def.matcher === 'string' ? def.matcher : undefined
+      items.push({
+        id: `${event}:${matcher ?? defs.indexOf(def)}`,
+        file,
+        kind: `claude-hook:${event}`,
+        ...(matcher ? { matcher } : {}),
+        bytes: Buffer.byteLength(raw, 'utf8'),
+        digest: digestText(raw),
+      })
+    }
+  }
+  return items
+}
+
+/**
+ * 扫描 Claude 数据根（复用一期 scanClaudeHome，scanGit 默认关闭）。
+ * @param home - 数据根目录。
+ * @param opts - `{ signal, scanGit }`。
+ * @returns 统一 Detection。
+ */
+export async function detect(home, { signal, scanGit = false } = {}) {
+  const detection = emptyDetection(source, home)
+  const { existsSync } = await import('node:fs')
+  detection.homeExists = existsSync(home)
+  if (!detection.homeExists) return detection
+
+  let index
+  try {
+    const result = await scanClaudeHome(home, {
+      scanGit,
+      ...(signal ? { signal } : {}),
+    })
+    index = result.index
+  } catch (err) {
+    if (signal?.aborted) throw err
+    recordError(detection, 'scan', err)
+    return detection
+  }
+
+  // sessions：projects/*/*.jsonl → 统一会话条目；项目级 memories 在项目层收集。
+  for (const project of index.projects ?? []) {
+    for (const session of project.sessions ?? []) {
+      if (session.error) {
+        recordError(detection, 'session:' + session.file, new Error(session.error))
+        continue
+      }
+      detection.sessions.push({
+        id: session.sessionId ?? session.file,
+        file: session.file,
+        ...(session.title ? { title: session.title } : {}),
+        ...(session.cwd ? { cwd: session.cwd } : {}),
+        ...(session.createdAt ? { createdAt: session.createdAt } : {}),
+        ...(session.lastActivity ? { lastActivity: session.lastActivity } : {}),
+        turns: session.turns ?? 0,
+        messages: session.messages ?? 0,
+        toolCalls: session.toolCalls ?? 0,
+        ...(session.malformed ? { malformed: session.malformed } : {}),
+        format: 'claude-jsonl',
+      })
+    }
+    // 项目级 memories（memory/*.md）→ 记忆条目（digest 在此计算，正文映射器再读）。
+    for (const memory of project.memories ?? []) {
+      let content = ''
+      try {
+        content = await readFile(assertAllowedRead(whitelist(home), memory.path), 'utf8')
+      } catch (err) {
+        recordError(detection, 'memory:' + memory.path, err)
+        continue
+      }
+      detection.memories.push({
+        id: memory.path,
+        file: memory.path,
+        kind: `claude-memory:${memory.type ?? 'unknown'}`,
+        bytes: Buffer.byteLength(content, 'utf8'),
+        digest: digestText(content),
+      })
+    }
+  }
+
+  // skills：~/.claude/skills/** → 技能条目（一期 scanSkills 已过滤无描述文件）。
+  for (const skill of index.personal?.skills ?? []) {
+    let content = ''
+    try {
+      content = await readFile(assertAllowedRead(whitelist(home), skill.path), 'utf8')
+    } catch (err) {
+      recordError(detection, 'skill:' + skill.path, err)
+      continue
+    }
+    detection.skills.push({
+      id: skill.path,
+      dir: path.dirname(skill.path),
+      file: skill.path,
+      flat: path.basename(skill.path).toLowerCase() !== 'skill.md',
+      name: skill.name,
+      description: skill.description,
+      compatible: true, // 一期 readSkillFile 已要求 name+description 齐备
+      ...(Number.isFinite(skill.level) ? { level: skill.level } : {}),
+      digest: digestText(content),
+    })
+  }
+
+  // instructions：全局 CLAUDE.md。
+  const globalClaudeMd = index.personal?.globalClaudeMd
+  if (globalClaudeMd) {
+    try {
+      const content = await readFile(assertAllowedRead(whitelist(home), globalClaudeMd.path), 'utf8')
+      detection.instructions.push({
+        id: globalClaudeMd.path,
+        file: globalClaudeMd.path,
+        kind: 'claude-md',
+        bytes: globalClaudeMd.sizeBytes ?? Buffer.byteLength(content, 'utf8'),
+        digest: digestText(content),
+      })
+    } catch (err) {
+      recordError(detection, 'CLAUDE.md', err)
+    }
+  }
+
+  // hooks：全局 + 项目级 settings.json 的 hooks 段 → 不支持清单输入。
+  if (index.personal?.settings) {
+    detection.hooks.push(...await scanHooks(index.personal.settings.path, detection))
+  }
+  for (const project of index.projects ?? []) {
+    if (project.projectSettings) {
+      detection.hooks.push(...await scanHooks(project.projectSettings.path, detection))
+    }
+  }
+  return detection
+}

package/lib/sources/codex/mapper.mjs

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+// lib/sources/codex/mapper.mjs — Codex CLI 源映射器（四合一迁移向导，零 DSH 依赖）。
+//
+// 清单 → 迁移计划：
+//   - sessions → import-session（会话转换与落盘复用一期 convertCodexJsonl /
+//     persistConverted，provider 'codex'；幂等走一期 imports，无 digest）。
+//   - skills → copy（兼容）/ convert-copy（缺 name/description 补合成 frontmatter）。
+//   - memories（memories/*.md）与 instructions（AGENTS.md/CODEX.md）→ append-section
+//     （DSH 全局 AGENTS.md 管理段，每条一个独立段 key）。
+//   - commands（hooks/*/command.md）→ 纯提示词 register-command、含 shell unsupported。
+//   - hooks（hooks/*/prompt.md、config.toml [commands]）→ unsupported 清单。
+// 正文（memories/instructions/commands）在本模块读一次；所有读取经 assertAllowedRead
+// 守卫（复用 parser 的白名单），越界/缺文件跳过并记 errors，绝不越界读隐私文件。
+
+import { readFile } from 'node:fs/promises'
+import { assertAllowedRead, planKey } from '../contract.mjs'
+import { skillTargetPath, kebabName } from '../../skill-migrate.mjs'
+import { commandPlan, hookUnsupportedPlan } from '../../commands-migrate.mjs'
+import { defaultAgentsMdPath } from '../../agmd-section.mjs'
+import { whitelist } from './parser.mjs'
+
+/** 钩子 → 不支持清单的固定文案。 */
+const CODEX_HOOK_REASON = 'Codex 钩子（matched-tool/shell）在 DSH 无插件级等价 seam，未自动迁移'
+
+/**
+ * 映射 Codex 检测清单为迁移计划。
+ * @param source - 'codex'。
+ * @param detection - codex/parser.mjs 的 detect() 输出。
+ * @param opts - `{ skillsDir, agentsMdPath }`；agentsMdPath 缺省 defaultAgentsMdPath()。
+ * @returns `{ plans }`；读取失败时附 `{ errors }`（plans 数组仍返回）。
+ */
+export async function mapSource(source, detection, opts = {}) {
+  const plans = []
+  const errors = []
+  const agentsMdPath = opts.agentsMdPath ?? defaultAgentsMdPath()
+  const skillsDir = opts.skillsDir
+  const roots = whitelist(detection.home)
+
+  const read = async (file, scope) => {
+    try {
+      return await readFile(assertAllowedRead(roots, file), 'utf8')
+    } catch (err) {
+      errors.push(`${scope}:${String((err && err.message) || err)}`)
+      return null
+    }
+  }
+
+  for (const session of detection.sessions ?? []) {
+    plans.push({
+      key: planKey(source, 'session', session.file),
+      from: source,
+      kind: 'session',
+      action: 'import-session',
+      source: { file: session.file, title: session.title, cwd: session.cwd, importKey: session.file, turns: session.turns },
+      target: {},
+      provider: 'codex',
+      title: session.title,
+    })
+  }
+
+  for (const skill of detection.skills ?? []) {
+    plans.push({
+      key: planKey(source, 'skill', skill.id),
+      from: source,
+      kind: 'skill',
+      action: skill.compatible ? 'copy' : 'convert-copy',
+      source: { file: skill.file, dir: skill.dir, name: skill.name },
+      target: skillsDir ? { path: skillTargetPath(skillsDir, kebabName(skill.name)) } : {},
+      digest: skill.digest,
+    })
+  }
+
+  for (const memory of detection.memories ?? []) {
+    const content = await read(memory.file, 'memory:' + memory.file)
+    if (content === null) continue
+    plans.push({
+      key: planKey(source, 'memory', memory.id),
+      from: source,
+      kind: 'memory',
+      action: 'append-section',
+      source: { file: memory.file },
+      target: { path: agentsMdPath },
+      content,
+      digest: memory.digest,
+    })
+  }
+
+  for (const instruction of detection.instructions ?? []) {
+    const content = await read(instruction.file, 'instruction:' + instruction.file)
+    if (content === null) continue
+    plans.push({
+      key: planKey(source, 'instruction', instruction.id),
+      from: source,
+      kind: 'instruction',
+      action: 'append-section',
+      source: { file: instruction.file },
+      target: { path: agentsMdPath },
+      content,
+      digest: instruction.digest,
+    })
+  }
+
+  for (const command of detection.commands ?? []) {
+    const content = await read(command.file, 'command:' + command.file)
+    if (content === null) continue
+    plans.push(commandPlan(source, 'command', command.id, {
+      file: command.file,
+      name: command.name,
+      promptOnly: command.promptOnly,
+      prompt: content,
+      digest: command.digest,
+    }))
+  }
+
+  for (const hook of detection.hooks ?? []) {
+    plans.push(hookUnsupportedPlan(source, hook.id, hook.file, CODEX_HOOK_REASON))
+  }
+
+  return { plans, ...(errors.length > 0 ? { errors } : {}) }
+}