zugzbot 1.0.21 → 1.0.23

package/.opencode/oh-my-design/src/cli/install-skills.ts

@@ -1,1116 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import {
-  readFileSync,
-  readdirSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  cpSync,
-} from 'node:fs';
-import { join, dirname, relative } from 'node:path';
-import { homedir } from 'node:os';
-import { createHash } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import { detectInstalledAgents } from '../core/agent-detect.js';
-
-export type SkillTarget = 'claude-code' | 'codex' | 'opencode' | 'cursor';
-
-/** Channels that host SKILL.md trees. Cursor is NOT one — it consumes a
- *  `.cursor/rules` shim + the shared `.claude/data` catalog (issue #20). */
-type SkillChannel = Exclude<SkillTarget, 'cursor'>;
-
-export interface InstallSkillsOptions {
-  dir?: string;
-  agents?: SkillTarget[];
-  force?: boolean;
-  /** Non-interactive: install all skills + all agents without TUI prompt.
-   *  Default false → interactive multiselect when TTY available. */
-  all?: boolean;
-  /** Pre-select specific skill names from CLI flag (`--skills omd-init,omd-apply`).
-   *  Overrides interactive prompt when set. */
-  skillsFilter?: string[];
-  /** Pre-select specific agent names. Overrides interactive prompt when set. */
-  agentsFilter?: string[];
-  /** Minimal install: only the named skill files — skip sub-agents, data files,
-   *  hooks, and settings.json. Ideal for shipping a single standalone skill. */
-  skillsOnly?: boolean;
-  /** Install to the user-level dir (~/.claude/skills) instead of this project.
-   *  Writes skills + sub-agents (+ data); never touches global hooks/settings.
-   *  When unset and interactive, the TUI asks project-vs-global. */
-  global?: boolean;
-}
-
-interface InstallPlan {
-  target: SkillChannel;
-  destDir: string;
-  layout: 'folder' | 'flat';
-}
-
-function findPackageRoot(): string | null {
-  let cur = dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 8; i++) {
-    if (existsSync(join(cur, 'skills'))) return cur;
-    const parent = dirname(cur);
-    if (parent === cur) break;
-    cur = parent;
-  }
-  return null;
-}
-
-function listShippedSkills(packageRoot: string): string[] {
-  const skillsDir = join(packageRoot, 'skills');
-  if (!existsSync(skillsDir)) return [];
-  return readdirSync(skillsDir)
-    .filter((name) => existsSync(join(skillsDir, name, 'SKILL.md')))
-    .sort();
-}
-
-/**
- * Canonical agent definitions live at `agents/<name>.md` (markdown with YAML
- * frontmatter). Channel-specific files (.claude/agents/*.md, .codex/agents/*.toml)
- * are generated artifacts — never the source of truth.
- *
- * The package ships only `agents/` and the generator emits per-channel files
- * into the user's project on `omd install-skills`.
- */
-function listCanonicalAgents(packageRoot: string): string[] {
-  const dir = join(packageRoot, 'agents');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((name) => name.startsWith('omd-') && name.endsWith('.md'))
-    .sort();
-}
-
-interface ParsedAgent {
-  name: string;
-  description: string;
-  tools: string[];
-  model: string;
-  body: string;
-}
-
-/** Parse `agents/<name>.md` YAML frontmatter + body into structured form. */
-function parseCanonicalAgent(packageRoot: string, filename: string): ParsedAgent {
-  const src = readFileSync(join(packageRoot, 'agents', filename), 'utf8');
-  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(src);
-  if (!match) {
-    throw new Error(`agents/${filename}: missing YAML frontmatter`);
-  }
-  const fm = match[1];
-  const body = match[2];
-  const grab = (key: string): string => {
-    const re = new RegExp(`^${key}:\\s*(.+)$`, 'm');
-    const m = re.exec(fm);
-    return m ? m[1].trim().replace(/^["']|["']$/g, '') : '';
-  };
-  return {
-    name: grab('name') || filename.replace(/\.md$/, ''),
-    description: grab('description'),
-    tools: grab('tools')
-      .split(',')
-      .map((t) => t.trim())
-      .filter(Boolean),
-    model: grab('model') || 'sonnet',
-    body,
-  };
-}
-
-/** Map Claude tool names to Codex tool names (best-effort). */
-function claudeToolsToCodex(tools: string[]): string[] {
-  const m: Record<string, string> = {
-    Read: 'read_file',
-    Write: 'write_file',
-    Edit: 'edit_file',
-    Bash: 'shell',
-    Glob: 'search',
-    Grep: 'search',
-    WebFetch: 'web_fetch',
-    WebSearch: 'search',
-    Agent: 'spawn_agent',
-    TaskCreate: 'task',
-    TaskUpdate: 'task',
-    TaskList: 'task',
-  };
-  const out = new Set<string>();
-  for (const t of tools) out.add(m[t] ?? t.toLowerCase());
-  return [...out].sort();
-}
-
-/** Map Claude model alias to Codex/OpenAI model id (best-effort). */
-function claudeModelToCodex(model: string): string {
-  const m: Record<string, string> = {
-    haiku: 'gpt-4.1-mini',
-    sonnet: 'gpt-4.1',
-    opus: 'gpt-4.1',
-  };
-  return m[model.toLowerCase()] ?? 'gpt-4.1';
-}
-
-/** Render a canonical agent as a Claude Code subagent file.
- *  IMPORTANT: Claude Code's subagent parser requires YAML frontmatter (`---`)
- *  as the FIRST line of the file. Any preceding content (HTML comments, blank
- *  lines) breaks discovery. So we encode the managed-by-omd marker as a
- *  custom frontmatter field (`omd_managed: true`) instead of an HTML comment.
- */
-function renderClaudeAgent(a: ParsedAgent): string {
-  const fm = [
-    '---',
-    `name: ${a.name}`,
-    `description: ${a.description}`,
-    `tools: ${a.tools.join(', ')}`,
-    `model: ${a.model}`,
-    `omd_managed: true`,
-    '---',
-    '',
-  ].join('\n');
-  return fm + a.body;
-}
-
-/** Render a canonical agent as a Codex TOML file (declarative pointer). */
-function renderCodexAgent(a: ParsedAgent): string {
-  const tools = claudeToolsToCodex(a.tools);
-  const model = claudeModelToCodex(a.model);
-  const desc = a.description.replace(/"/g, '\\"');
-  return [
-    `[agent]`,
-    `name = "${a.name}"`,
-    `description = "${desc}"`,
-    `model = "${model}"`,
-    `max_threads = 1`,
-    `allowed_tools = [${tools.map((t) => `"${t}"`).join(', ')}]`,
-    '',
-    `instructions = """`,
-    `Source of truth: agents/${a.name}.md (canonical). The full role spec is`,
-    `mirrored to .claude/agents/${a.name}.md when installed for Claude Code.`,
-    `Follow that spec verbatim regardless of channel.`,
-    '',
-    `Codex notes:`,
-    `- Spawn sub-agents via spawn_agent with names matching .codex/agents/<name>.toml`,
-    `- Use shell to invoke CLI helpers (omd init prepare, omd remember, git apply, npx axe-core, npx lighthouse)`,
-    `- All artifacts go inside .omd/runs/run-<latest>/ (or skills/omd-lab-02-design-harness/runs/<lab-version>-...)`,
-    `"""`,
-    '',
-  ].join('\n');
-}
-
-function planForTarget(projectRoot: string, target: SkillChannel): InstallPlan {
-  switch (target) {
-    case 'claude-code':
-      return {
-        target,
-        destDir: join(projectRoot, '.claude', 'skills'),
-        layout: 'folder',
-      };
-    case 'codex':
-      // Official Codex skill discovery path is `.agents/skills/<name>/SKILL.md`
-      // (developers.openai.com/codex/skills) — NOT `.codex/skills`. Folder layout
-      // so multi-file skills (scripts/, references/) install + run.
-      return {
-        target,
-        destDir: join(projectRoot, '.agents', 'skills'),
-        layout: 'folder',
-      };
-    case 'opencode':
-      // OpenCode loads `.opencode/skills/<name>/SKILL.md` (opencode.ai/docs/skills)
-      // as folder skills — the old flat `.opencode/agents/<name>.md` couldn't host
-      // a skill's scripts/references.
-      return {
-        target,
-        destDir: join(projectRoot, '.opencode', 'skills'),
-        layout: 'folder',
-      };
-  }
-}
-
-/**
- * Channel → shared data dir (`<dir>/data/…`) for read-only data assets
- * (catalog JSONs, reference DESIGN.md catalog, ctx-prime helper scripts).
- * Single lookup table replacing the repeated if-else/ternary chains (issue #28).
- * `null` = the channel hosts no data dir of its own:
- *   - opencode ships skills only (no data channel yet);
- *   - cursor reads the SHARED `.claude/data` path (issue #20) — resolved by
- *     `dataDirFor()` below, which also applies the claude-code dedup guard.
- *     (Helper scripts intentionally stay claude-code/codex only — a cursor-only
- *     install gets the catalog + JSONs but no ctx-prime, matching the shim's scope.)
- */
-const CHANNEL_DATA_DIRS: Record<SkillTarget, '.claude' | '.codex' | null> = {
-  'claude-code': '.claude',
-  codex: '.codex',
-  opencode: null,
-  cursor: null,
-};
-
-/**
- * Where a target's data assets (data JSONs + reference catalog) land. Cursor
- * reuses `.claude/data` so the catalog location stays single (issue #20) —
- * but ONLY when claude-code isn't also selected: the claude-code pass already
- * writes there, and a second pass would double-copy the catalog.
- */
-export function dataDirFor(
-  target: SkillTarget,
-  targets: SkillTarget[]
-): '.claude' | '.codex' | null {
-  if (target === 'cursor') {
-    return targets.includes('claude-code') ? null : '.claude';
-  }
-  return CHANNEL_DATA_DIRS[target];
-}
-
-const MANAGED_HEADER =
-  '<!-- omd:installed-skill — managed by `omd install-skills`. Do not edit; rerun the command to refresh. -->';
-
-// Substring shared by old (line 1) and new (after-frontmatter) marker formats.
-// Used for detection so upgrades from pre-v1.7.2 installs still refresh.
-const MANAGED_MARKER_SUBSTR = 'omd:installed-skill';
-
-/**
- * Write the managed marker AFTER the YAML frontmatter block so the very first
- * line of the installed file is `---`. Claude Code's skill loader reads the
- * frontmatter `name`/`description` only when `---` is line 1 — a leading HTML
- * comment makes it register the comment as the description (issue #17).
- *
- * If the source has no frontmatter (shouldn't happen for SKILL.md, but be
- * defensive), fall back to prepending the marker.
- */
-function withManagedMarker(src: string): string {
-  // \r?\n: a CRLF checkout (Windows core.autocrlf) must not miss the
-  // frontmatter and fall back to a line-1 marker — that reintroduces #17.
-  const fm = /^(---\r?\n[\s\S]*?\r?\n---\r?\n)([\s\S]*)$/.exec(src);
-  if (!fm) {
-    return MANAGED_HEADER + '\n\n' + src;
-  }
-  return fm[1] + MANAGED_HEADER + '\n\n' + fm[2];
-}
-
-/**
- * Detect an omd-managed installed-skill file. Matches both the new format
- * (marker after frontmatter) and the legacy format (marker on line 1) by
- * scanning the first ~30 lines for the marker substring. This keeps upgrades
- * working: a pre-v1.7.2 file with the marker at line 1 is still recognized as
- * managed and gets refreshed rather than skipped as user-edited drift.
- */
-function isManagedSkillFile(content: string): boolean {
-  if (!content) return false;
-  const head = content.split('\n', 30).join('\n');
-  return head.includes(MANAGED_MARKER_SUBSTR);
-}
-
-interface InstallResult {
-  target: SkillTarget;
-  skill: string;
-  destPath: string;
-  status: 'created' | 'updated' | 'unchanged' | 'skipped-drift' | 'skipped-incompat';
-}
-
-// Skill-tree entries that must never be installed (runtime state, caches, OS cruft).
-const IGNORED_SKILL_ENTRIES = new Set(['.runtime', '__pycache__', '.DS_Store']);
-
-/**
- * A skill may restrict itself to specific agent channels via a frontmatter line
- * `x-omd-channels: claude-code` (comma/space separated). Returns the allowed
- * channels, or null when channel-agnostic (installs anywhere). Used by skills that
- * depend on a particular agent runtime — e.g. claude-design needs Claude Code's
- * claude-in-chrome MCP + Bash/python/node and is therefore claude-code only.
- */
-function parseSkillChannels(skillMd: string): SkillChannel[] | null {
-  const fm = /^---\n([\s\S]*?)\n---/.exec(skillMd);
-  if (!fm) return null;
-  const m = /^x-omd-channels:\s*(.+)$/m.exec(fm[1]);
-  if (!m) return null;
-  const valid: SkillChannel[] = ['claude-code', 'codex', 'opencode'];
-  const list = m[1]
-    .split(/[,\s]+/)
-    .map((s) => s.trim())
-    .filter((s): s is SkillChannel => (valid as string[]).includes(s));
-  return list.length > 0 ? list : null;
-}
-
-/**
- * The agent channels a skill can install into: its declared `x-omd-channels`
- * (if any), else all channels. All three channels now use folder layout
- * (.claude/skills, .agents/skills, .opencode/skills) so multi-file skills with
- * scripts/references install everywhere — the only restriction is what the skill
- * itself declares (e.g. claude-design needs a browser-driving runtime).
- */
-function skillSupportedChannels(packageRoot: string, skill: string): SkillChannel[] {
-  return (
-    parseSkillChannels(readFileSync(join(packageRoot, 'skills', skill, 'SKILL.md'), 'utf8')) ??
-    (['claude-code', 'codex', 'opencode'] as SkillChannel[])
-  );
-}
-
-function installOne(
-  packageRoot: string,
-  plan: InstallPlan,
-  skill: string,
-  force: boolean
-): InstallResult {
-  const skillDir = join(packageRoot, 'skills', skill);
-  const src = readFileSync(join(skillDir, 'SKILL.md'), 'utf8');
-  // Marker goes AFTER frontmatter so `---` stays line 1 (issue #17).
-  const managed = withManagedMarker(src);
-
-  // Respect a skill's declared channel restriction (frontmatter `x-omd-channels:`).
-  const channels = parseSkillChannels(src);
-  if (channels && !channels.includes(plan.target)) {
-    return {
-      target: plan.target,
-      skill,
-      destPath: join(plan.destDir, skill + '.md'),
-      status: 'skipped-incompat',
-    };
-  }
-
-  // A skill is "multi-file" when it ships more than SKILL.md (scripts/, references/, …).
-  const extras = readdirSync(skillDir).filter(
-    (n) => n !== 'SKILL.md' && !IGNORED_SKILL_ENTRIES.has(n)
-  );
-  const isMultiFile = extras.length > 0;
-
-  // Flat channels (codex/opencode) store a skill as a single <skill>.md and cannot
-  // host a multi-file skill's scripts/references — such skills are claude-code only.
-  if (plan.layout !== 'folder' && isMultiFile) {
-    return {
-      target: plan.target,
-      skill,
-      destPath: join(plan.destDir, skill + '.md'),
-      status: 'skipped-incompat',
-    };
-  }
-
-  const destPath =
-    plan.layout === 'folder'
-      ? join(plan.destDir, skill, 'SKILL.md')
-      : join(plan.destDir, skill + '.md');
-
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-
-  // Drift protection guards the user-editable SKILL.md. Single-file skills can
-  // short-circuit on "unchanged"; multi-file skills always re-sync their tree.
-  if (exists && existing === managed && !isMultiFile) {
-    return { target: plan.target, skill, destPath, status: 'unchanged' };
-  }
-  // Drift = a file we didn't write. Detect the marker anywhere in the head
-  // (new after-frontmatter position OR legacy line-1 position) so pre-v1.7.2
-  // installs are recognized as managed and refreshed, not skipped.
-  if (exists && !isManagedSkillFile(existing) && !force) {
-    return { target: plan.target, skill, destPath, status: 'skipped-drift' };
-  }
-
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, managed, 'utf8');
-
-  // Copy the rest of the skill tree (scripts/, references/, …) for folder layout.
-  if (plan.layout === 'folder' && isMultiFile) {
-    const destSkillDir = join(plan.destDir, skill);
-    for (const entry of extras) {
-      cpSync(join(skillDir, entry), join(destSkillDir, entry), {
-        recursive: true,
-        filter: (s) => !/(\/__pycache__|\/\.runtime|\.pyc$|\.DS_Store$)/.test(s),
-      });
-    }
-  }
-
-  return {
-    target: plan.target,
-    skill,
-    destPath,
-    status: exists ? 'updated' : 'created',
-  };
-}
-
-/** Install a hook script from package's .claude/hooks/ to project. */
-function installHookFile(
-  packageRoot: string,
-  projectRoot: string,
-  filename: string,
-  force: boolean
-): InstallResult {
-  const target: SkillTarget = 'claude-code';
-  const skillLabel = `hook:${filename}`;
-  const srcPath = join(packageRoot, '.claude', 'hooks', filename);
-  const destPath = join(projectRoot, '.claude', 'hooks', filename);
-
-  if (!existsSync(srcPath)) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-  const src = readFileSync(srcPath, 'utf8');
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-  if (exists && existing === src) {
-    return { target, skill: skillLabel, destPath, status: 'unchanged' };
-  }
-  if (exists && !force) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, src);
-  return { target, skill: skillLabel, destPath, status: exists ? 'updated' : 'created' };
-}
-
-/**
- * Install / merge .claude/settings.json. We MERGE hooks (don't clobber user
- * customizations) by checking if the omd-managed `_doc` field is present.
- * Without --force, if a user-edited settings.json exists (no _doc field),
- * we skip with `skipped-drift`.
- */
-function installSettingsJson(
-  packageRoot: string,
-  projectRoot: string,
-  force: boolean
-): InstallResult {
-  const target: SkillTarget = 'claude-code';
-  const skillLabel = 'settings:.claude/settings.json';
-  const srcPath = join(packageRoot, '.claude', 'settings.json');
-  const destPath = join(projectRoot, '.claude', 'settings.json');
-  if (!existsSync(srcPath)) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-  const src = readFileSync(srcPath, 'utf8');
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-  if (exists && existing === src) {
-    return { target, skill: skillLabel, destPath, status: 'unchanged' };
-  }
-  if (exists && !force) {
-    // Check if it's the omd-managed version
-    try {
-      const parsed = JSON.parse(existing);
-      if (typeof parsed._doc === 'string' && parsed._doc.includes('OmD')) {
-        // managed — overwrite
-      } else {
-        return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-      }
-    } catch {
-      return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-    }
-  }
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, src);
-  return { target, skill: skillLabel, destPath, status: exists ? 'updated' : 'created' };
-}
-
-/**
- * Copy a read-only data asset (reference-fingerprints.json, vocabulary.json, …)
- * from the package's `data/` into the project's `.claude/data/` or `.codex/data/`.
- * The skill reads these at runtime — they replace the deprecated `omd init recommend` CLI.
- */
-function installDataFile(
-  packageRoot: string,
-  projectRoot: string,
-  channelDir: string,
-  dataFilename: string,
-  force: boolean,
-  // Cursor reuses the `.claude` data dir (single catalog path) — callers pass
-  // an explicit target so the results table reports the real channel.
-  target: SkillTarget
-): InstallResult {
-  const skillLabel = `data:${dataFilename}`;
-
-  const srcPath = join(packageRoot, 'data', dataFilename);
-  const destPath = join(projectRoot, channelDir, 'data', dataFilename);
-
-  if (!existsSync(srcPath)) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-
-  const src = readFileSync(srcPath, 'utf8');
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-
-  // Data files are pure copies — no managed header (would corrupt JSON).
-  if (exists && existing === src) {
-    return { target, skill: skillLabel, destPath, status: 'unchanged' };
-  }
-  if (exists && !force) {
-    // Honor user customization unless --force
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, src, 'utf8');
-  return {
-    target,
-    skill: skillLabel,
-    destPath,
-    status: exists ? 'updated' : 'created',
-  };
-}
-
-/**
- * Generate a per-channel agent file from the canonical `agents/<name>.md`.
- *
- * Channel = 'claude' → emits `.claude/agents/<name>.md` (markdown w/ frontmatter)
- * Channel = 'codex'  → emits `.codex/agents/<name>.toml` (TOML pointer)
- */
-function installAgentFile(
-  packageRoot: string,
-  projectRoot: string,
-  channel: 'claude' | 'codex',
-  filename: string,
-  force: boolean
-): InstallResult {
-  const target: SkillTarget = channel === 'claude' ? 'claude-code' : 'codex';
-  const skillLabel = `agent:${filename}`;
-
-  const parsed = parseCanonicalAgent(packageRoot, filename);
-  const rendered =
-    channel === 'claude' ? renderClaudeAgent(parsed) : renderCodexAgent(parsed);
-
-  const destFilename =
-    channel === 'claude' ? filename : filename.replace(/\.md$/, '.toml');
-  const destPath = join(
-    projectRoot,
-    channel === 'claude' ? '.claude' : '.codex',
-    'agents',
-    destFilename
-  );
-
-  // For Claude Code: managed marker is encoded as `omd_managed: true` INSIDE the
-  // frontmatter (rendered above) — no HTML comment can precede `---` or the
-  // subagent loader rejects the file.
-  // For Codex: TOML allows leading comments, so `# omd:installed-agent ...` is fine.
-  const managed =
-    channel === 'claude'
-      ? rendered
-      : '# omd:installed-agent — generated from agents/' +
-        filename +
-        ' by `omd install-skills`. Do not edit; rerun the command to refresh.\n\n' +
-        rendered;
-
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-
-  if (exists && existing === managed) {
-    return { target, skill: skillLabel, destPath, status: 'unchanged' };
-  }
-
-  // Drift detection sentinels:
-  //   Claude — look for `omd_managed: true` line inside frontmatter
-  //   Codex  — look for `# omd:installed-agent` comment
-  const isManaged =
-    channel === 'claude'
-      ? /\nomd_managed:\s*true\b/.test(existing)
-      : existing.startsWith('# omd:installed-agent');
-
-  if (exists && !isManaged && !force) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, managed, 'utf8');
-  return {
-    target,
-    skill: skillLabel,
-    destPath,
-    status: exists ? 'updated' : 'created',
-  };
-}
-
-/**
- * Copy the reference catalog (`web/references/<id>/DESIGN.md`) into the project's
- * `.claude/data/references/<id>/DESIGN.md` so it's reachable on clean npx installs
- * — where there is no `node_modules` and no dev `web/references` (issue #16).
- *
- * Only DESIGN.md per id is copied (not _promo.json/_research.md/screenshots) to
- * keep the install lean. Idempotent: skips ids whose DESIGN.md already matches.
- * Returns the number of catalog files written (created or updated).
- */
-function installReferenceCatalog(
-  packageRoot: string,
-  installRoot: string,
-  channelDir: string,
-  force: boolean
-): number {
-  const srcRoot = join(packageRoot, 'web', 'references');
-  if (!existsSync(srcRoot)) return 0;
-  const destRoot = join(installRoot, channelDir, 'data', 'references');
-
-  let written = 0;
-  for (const id of readdirSync(srcRoot)) {
-    const srcDesign = join(srcRoot, id, 'DESIGN.md');
-    if (!existsSync(srcDesign)) continue;
-    const destDesign = join(destRoot, id, 'DESIGN.md');
-    const src = readFileSync(srcDesign, 'utf8');
-    if (existsSync(destDesign)) {
-      const existing = readFileSync(destDesign, 'utf8');
-      if (existing === src) continue;
-      if (!force) continue; // honor user edits unless --force
-    }
-    mkdirSync(dirname(destDesign), { recursive: true });
-    writeFileSync(destDesign, src, 'utf8');
-    written++;
-  }
-  return written;
-}
-
-/**
- * Cursor channel shim — Cursor has no skill/agent surface; it consumes a
- * project rule at `.cursor/rules/omd-design.mdc`. Frontmatter, body, and the
- * body-hash marker below mirror the omd:sync skill's cursor template EXACTLY
- * (skills/omd-sync/SKILL.md, "whole" mode: hash = sha256 of the body text,
- * 12-char hex prefix), so a later omd:sync run reads the installer-written
- * file as `clean` rather than drifted (issue #20).
- */
-const CURSOR_RULE_BODY = [
-  'The authoritative design spec lives at `@DESIGN.md` (repo root). Open and read before generating/modifying UI.',
-  '',
-  'Pending preference corrections: `@.omd/preferences.md`.',
-  '',
-  'Precedence: DESIGN.md > preferences.md > framework defaults.',
-].join('\n');
-
-function renderCursorRule(): string {
-  const hash = createHash('sha256').update(CURSOR_RULE_BODY).digest('hex').slice(0, 12);
-  return [
-    '---',
-    'description: Authoritative brand & UI design system. Read DESIGN.md before UI work.',
-    'globs:',
-    '  - "**/*.tsx"',
-    '  - "**/*.jsx"',
-    '  - "**/*.vue"',
-    '  - "**/*.svelte"',
-    '  - "**/*.css"',
-    '  - "**/*.scss"',
-    '  - "**/tailwind.config.*"',
-    '  - "**/components/**"',
-    '  - "**/app/**/page.*"',
-    'alwaysApply: false',
-    '---',
-    '',
-    `<!-- omd:start v=1 hash=${hash} -->`,
-    CURSOR_RULE_BODY,
-    '<!-- omd:end -->',
-    '',
-  ].join('\n');
-}
-
-function installCursorRule(installRoot: string, force: boolean): InstallResult {
-  const target: SkillTarget = 'cursor';
-  const skillLabel = 'rule:omd-design.mdc';
-  const destPath = join(installRoot, '.cursor', 'rules', 'omd-design.mdc');
-  const rendered = renderCursorRule();
-
-  const exists = existsSync(destPath);
-  const existing = exists ? readFileSync(destPath, 'utf8') : '';
-  if (exists && existing === rendered) {
-    return { target, skill: skillLabel, destPath, status: 'unchanged' };
-  }
-  // The omd marker block doubles as the managed sentinel (matching omd:sync's
-  // whole-mode rules): a file without it is user content → drift unless --force.
-  if (exists && !existing.includes('<!-- omd:start') && !force) {
-    return { target, skill: skillLabel, destPath, status: 'skipped-drift' };
-  }
-  mkdirSync(dirname(destPath), { recursive: true });
-  writeFileSync(destPath, rendered, 'utf8');
-  return { target, skill: skillLabel, destPath, status: exists ? 'updated' : 'created' };
-}
-
-const STATUS_LABEL: Record<InstallResult['status'], string> = {
-  created: pc.green('created'),
-  updated: pc.cyan('updated'),
-  unchanged: pc.dim('unchanged'),
-  'skipped-drift': pc.yellow('skipped'),
-  'skipped-incompat': pc.yellow('skipped (claude-code only)'),
-};
-
-function autoDetectTargets(projectRoot: string): SkillTarget[] {
-  const presence = detectInstalledAgents(projectRoot);
-  const targets: SkillTarget[] = [];
-  if (presence.claudeCode) targets.push('claude-code');
-  if (presence.codex) targets.push('codex');
-  if (presence.opencode) targets.push('opencode');
-  // Cursor hosts no skills — its channel writes the .cursor/rules shim + the
-  // shared .claude/data catalog (issue #20). Only when .cursor is detected;
-  // the no-signal fallback below stays skill-channel-only so we never drop a
-  // .cursor dir into projects that don't use Cursor.
-  if (presence.cursor) targets.push('cursor');
-  if (targets.length === 0) {
-    // Fallback: install for all three skill channels so user gets coverage
-    // even without explicit signal. Idempotent so cost is low.
-    return ['claude-code', 'codex', 'opencode'];
-  }
-  return targets;
-}
-
-export async function runInstallSkills(
-  opts: InstallSkillsOptions = {}
-): Promise<number> {
-  const projectRoot = opts.dir ?? process.cwd();
-  const packageRoot = findPackageRoot();
-  if (!packageRoot) {
-    console.error(pc.red('omd install-skills: package data not found'));
-    return 1;
-  }
-
-  const allSkills = listShippedSkills(packageRoot);
-  if (allSkills.length === 0) {
-    console.error(pc.red('omd install-skills: no skills found in package'));
-    return 1;
-  }
-  const allAgents = listCanonicalAgents(packageRoot);
-
-  const force = opts.force ?? false;
-  const minimal = opts.skillsOnly === true;
-  // Install scope: 'project' (<cwd>/.claude/…) or 'global' (~/.claude/…). --global
-  // forces it; otherwise the interactive TUI asks. Global writes skills + sub-agents
-  // (+ data) to the user-level dir but never touches global hooks/settings.json.
-  let scope: 'project' | 'global' = opts.global ? 'global' : 'project';
-
-  p.intro(
-    pc.bold('omd install-skills') +
-      pc.dim(`  (${relative(process.cwd(), projectRoot) || '.'})`)
-  );
-
-  // Each dimension (scope / skills / sub-agents / channels) is resolved
-  // independently: a CLI flag pins it; otherwise we prompt — but only when stdin
-  // is a TTY and --all wasn't passed. This is the key fix: `--skills X` or
-  // `--skills-only` no longer suppress the *channel* (where to install) prompt —
-  // they only pin the dimension they name.
-  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  const interactive = isTTY && !opts.all;
-
-  const detected = autoDetectTargets(projectRoot);
-  // Real presence (not the all-3 fallback) — used for hint labels + prompt defaults.
-  const presence = detectInstalledAgents(projectRoot);
-  const actuallyDetected: SkillTarget[] = [
-    presence.claudeCode ? 'claude-code' : null,
-    presence.codex ? 'codex' : null,
-    presence.opencode ? 'opencode' : null,
-    presence.cursor ? 'cursor' : null,
-  ].filter((x): x is SkillTarget => x !== null);
-
-  // --- Scope (project vs global) — --global pins it, else ask / default project.
-  if (!opts.global && interactive) {
-    const scopeResult = await p.select({
-      message: 'Install scope · 어디에 설치할까요?',
-      options: [
-        { value: 'project', label: 'Project', hint: `${relative(process.cwd(), projectRoot) || '.'}/.claude/skills · 이 프로젝트만` },
-        { value: 'global', label: 'Global', hint: '~/.claude/skills · 모든 프로젝트 (skills + sub-agents, hooks/settings 제외)' },
-      ],
-      initialValue: 'project',
-    });
-    if (p.isCancel(scopeResult)) { p.cancel('Install cancelled.'); return 130; }
-    scope = scopeResult as 'project' | 'global';
-  }
-
-  // --- Skills — --skills pins it, else ask / default ALL.
-  let skills: string[];
-  if (opts.skillsFilter) {
-    skills = allSkills.filter((s) => opts.skillsFilter!.includes(s));
-  } else if (interactive) {
-    const skillResult = await p.multiselect({
-      message: 'Skills · space = 토글 · a = 전체 · enter = 확인 (default ALL)',
-      options: allSkills.map((s) => ({ value: s, label: s, hint: 'omd skill' })),
-      initialValues: allSkills,
-      required: true,
-    });
-    if (p.isCancel(skillResult)) { p.cancel('Install cancelled.'); return 130; }
-    skills = skillResult as string[];
-  } else {
-    skills = allSkills;
-  }
-
-  // --- Sub-agents — dropped by --skills-only, else --agents pins, else ask / ALL.
-  let canonicalAgents: string[];
-  if (minimal) {
-    canonicalAgents = [];
-  } else if (opts.agentsFilter) {
-    canonicalAgents = allAgents.filter((a) => opts.agentsFilter!.includes(a.replace(/\.md$/, '')));
-  } else if (interactive && allAgents.length > 0) {
-    const agentResult = await p.multiselect({
-      message: 'Sub-agents · space = 토글 · a = 전체 · enter = 확인 (default ALL)',
-      options: allAgents.map((a) => ({ value: a, label: a.replace(/\.md$/, ''), hint: 'subagent' })),
-      initialValues: allAgents,
-      required: false,
-    });
-    if (p.isCancel(agentResult)) { p.cancel('Install cancelled.'); return 130; }
-    canonicalAgents = agentResult as string[];
-  } else {
-    canonicalAgents = allAgents;
-  }
-
-  // --- Channels / targets — the "where do I install" choice.
-  // --agent pins it. Otherwise, in a TTY we ASK — limited to the channels the
-  // selected skills actually support (claude-design is claude-code only, so its
-  // picker shows just Claude Code). Non-TTY / --all falls back to auto-resolution.
-  const supportedTargets = ((): SkillTarget[] => {
-    const set = new Set<SkillTarget>(skills.flatMap((s) => skillSupportedChannels(packageRoot, s)));
-    // Cursor consumes no skills — its channel install (.cursor/rules shim +
-    // shared .claude/data catalog) is skill-independent, so always offer it.
-    set.add('cursor');
-    return (['claude-code', 'codex', 'opencode', 'cursor'] as SkillTarget[]).filter((t) => set.has(t));
-  })();
-  const channelLabel: Record<SkillTarget, string> = {
-    'claude-code': 'Claude Code',
-    codex: 'Codex',
-    opencode: 'OpenCode',
-    cursor: 'Cursor',
-  };
-  const channelDir: Record<SkillTarget, string> = {
-    'claude-code': '.claude',
-    codex: '.codex',
-    opencode: '.opencode',
-    cursor: '.cursor',
-  };
-  let targets: SkillTarget[];
-  if (opts.agents) {
-    targets = opts.agents;
-  } else if (interactive) {
-    const defaults = actuallyDetected.filter((t) => supportedTargets.includes(t));
-    const targetResult = await p.multiselect({
-      message: 'Agent channels · 어디에 설치할까요? · space = 토글 · enter = 확인',
-      options: supportedTargets.map((t) => ({
-        value: t,
-        label: channelLabel[t],
-        hint: actuallyDetected.includes(t) ? `${channelDir[t]}/ detected` : '',
-      })) as { value: SkillTarget; label: string; hint?: string }[],
-      initialValues: defaults.length > 0 ? defaults : supportedTargets,
-      required: true,
-    });
-    if (p.isCancel(targetResult)) { p.cancel('Install cancelled.'); return 130; }
-    targets = targetResult as SkillTarget[];
-  } else {
-    // Non-interactive (CI / piped / --all): resolve from flags + detection,
-    // narrowed to channels the selected skills support.
-    targets = opts.all
-      ? (['claude-code', 'codex', 'opencode'] as SkillTarget[])
-      : minimal
-        ? (actuallyDetected.length > 0 ? actuallyDetected : (['claude-code'] as SkillTarget[]))
-        : detected;
-    const narrowed = targets.filter((t) => supportedTargets.includes(t));
-    if (narrowed.length > 0) targets = narrowed;
-  }
-
-  // Global scope roots everything at the home dir, so plan dirs resolve to
-  // ~/.claude/skills, ~/.claude/agents, etc. Project scope uses cwd (or --dir).
-  const installRoot = scope === 'global' ? homedir() : projectRoot;
-  // Cursor hosts no SKILL.md tree — it's excluded from skill plans and handled
-  // below via the .cursor/rules shim + shared data copies (issue #20).
-  const skillChannelTargets = targets.filter(
-    (t): t is SkillChannel => t !== 'cursor'
-  );
-  const plans = skillChannelTargets.map((t) => planForTarget(installRoot, t));
-
-  p.log.message(
-    pc.bold('Scope: ') +
-      pc.cyan(scope) +
-      pc.dim(scope === 'global' ? '  (~/.claude)' : `  (${relative(process.cwd(), projectRoot) || '.'})`)
-  );
-  p.log.message(
-    pc.bold(`Skills (${skills.length}): `) +
-      skills.map((s) => pc.cyan(s)).join(', ')
-  );
-  if (minimal) {
-    // --skills-only: sub-agents are intentionally skipped (minimal single-skill
-    // install). Clear BEFORE the summary so we never print agents we won't write.
-    canonicalAgents = [];
-    p.log.message(pc.bold('Agents: ') + pc.dim('skipped (--skills-only)'));
-  } else if (canonicalAgents.length > 0) {
-    p.log.message(
-      pc.bold(`Agents (${canonicalAgents.length}): `) +
-        canonicalAgents.map((a) => pc.cyan(a.replace(/\.md$/, ''))).join(', ')
-    );
-  }
-  p.log.message(
-    pc.bold('Targets: ') + targets.map((t) => pc.cyan(t)).join(', ')
-  );
-
-  const results: InstallResult[] = [];
-  // Count of reference-catalog DESIGN.md files copied (issue #16) — surfaced in
-  // the install summary. Declared here so the outro (outside `if (!minimal)`) sees it.
-  let catalogCount = 0;
-  for (const plan of plans) {
-    for (const skill of skills) {
-      results.push(installOne(packageRoot, plan, skill, force));
-    }
-  }
-
-  // Generate per-channel sub-agent definitions from the canonical `agents/`.
-  // This is the v2 portable source-of-truth pattern (oh-my-agent style).
-  // `canonicalAgents` is already resolved above by the TUI / --agents filter.
-  for (const target of targets) {
-    if (target === 'claude-code') {
-      for (const filename of canonicalAgents) {
-        results.push(installAgentFile(packageRoot, installRoot, 'claude', filename, force));
-      }
-    } else if (target === 'codex') {
-      for (const filename of canonicalAgents) {
-        results.push(installAgentFile(packageRoot, installRoot, 'codex', filename, force));
-      }
-    }
-    // OpenCode currently has no agent-definition channel — skills only.
-  }
-
-  if (!minimal) {
-  // Cursor channel: write the `.cursor/rules` shim (the exact content omd:sync
-  // renders for .cursor/rules/omd-design.mdc) so Cursor reads DESIGN.md before
-  // UI work. No skills/agents/hooks — the shim plus the shared .claude/data
-  // copies below are the whole Cursor install (issue #20).
-  if (targets.includes('cursor')) {
-    results.push(installCursorRule(installRoot, force));
-  }
-
-  // Ship the read-only data assets (reference fingerprints, controlled vocab,
-  // human-readable tag matrix, opt-out corpus) so skills + hooks can run entirely
-  // on the host CLI's own model — no external API keys.
-  const dataFiles = [
-    'reference-fingerprints.json',
-    'reference-tags.md',
-    'vocabulary.json',
-    'synonyms.json',
-    'opt-out-corpus.json',
-  ];
-  // Channel→dir resolution (incl. the cursor shared-`.claude/data` dedup guard,
-  // issue #20) lives in dataDirFor — single source for all three copy loops.
-  for (const target of targets) {
-    const dataDir = dataDirFor(target, targets);
-    if (!dataDir) continue;
-    for (const dataFile of dataFiles) {
-      results.push(installDataFile(packageRoot, installRoot, dataDir, dataFile, force, target));
-    }
-  }
-
-  // Ship the reference catalog (DESIGN.md per id) into .claude/data/references
-  // so omd:init can resolve a reference on clean npx installs — no node_modules,
-  // no dev web/references (issue #16). Skipped under --skills-only (handled by the
-  // enclosing `if (!minimal)`). Codex gets the same copy under .codex/data.
-  // Same dataDirFor single-path rule as the data JSONs above — Cursor reads
-  // .claude/data/references, never a second catalog location.
-  for (const target of targets) {
-    const dataDir = dataDirFor(target, targets);
-    if (dataDir) {
-      catalogCount += installReferenceCatalog(packageRoot, installRoot, dataDir, force);
-    }
-  }
-
-  // Copy ctx-prime.cjs (+ its companion context.cjs) into .claude/data/scripts/
-  // so /omd-harness CTX-PRIME works without the package dir on npx installs
-  // (issue #18 / harness OMD_DIR resolution).
-  // Note: base table (no cursor special-case) — helper scripts are
-  // claude-code/codex only; a cursor-only install ships no ctx-prime.
-  for (const target of targets) {
-    const cd = CHANNEL_DATA_DIRS[target];
-    if (!cd) continue;
-    for (const helper of ['ctx-prime.cjs', 'context.cjs']) {
-      const srcHelper = join(packageRoot, 'scripts', helper);
-      if (!existsSync(srcHelper)) continue;
-      const destHelper = join(installRoot, cd, 'data', 'scripts', helper);
-      const srcTxt = readFileSync(srcHelper, 'utf8');
-      if (existsSync(destHelper) && readFileSync(destHelper, 'utf8') === srcTxt) continue;
-      mkdirSync(dirname(destHelper), { recursive: true });
-      writeFileSync(destHelper, srcTxt, 'utf8');
-    }
-  }
-
-  // Hooks + settings.json are PROJECT-SCOPED only — a global install must not
-  // mutate the user's global Claude config / make hooks fire in every project.
-  if (scope === 'project' && targets.includes('claude-code')) {
-    for (const hookFile of [
-      'skill-activation.cjs',
-      'session-state-loader.cjs',
-      'post-edit-watch.cjs',
-      'session-end-foldin.cjs',
-      // Shared modules required by the fold-in / state-loader / watch hooks.
-      // Live in a lib/ subdir; installHookFile preserves the relative path
-      // under .claude/hooks/.
-      join('lib', 'preferences-parser.cjs'),
-      join('lib', 'preferences-writer.cjs'),
-    ]) {
-      results.push(installHookFile(packageRoot, installRoot, hookFile, force));
-    }
-    // settings.json (with merge, never clobber user)
-    results.push(installSettingsJson(packageRoot, installRoot, force));
-  }
-  } // !minimal — skills-only skips data files, hooks, and settings.json
-
-  p.log.message(pc.bold('\nResults:'));
-  for (const r of results) {
-    const rel = relative(installRoot, r.destPath);
-    p.log.message(
-      `  ${STATUS_LABEL[r.status]}  ${pc.dim(r.target.padEnd(12))} ${rel}`
-    );
-  }
-
-  const driftCount = results.filter((r) => r.status === 'skipped-drift').length;
-  const writtenCount = results.filter(
-    (r) => r.status === 'created' || r.status === 'updated'
-  ).length;
-
-  if (driftCount > 0) {
-    p.outro(
-      pc.yellow(
-        `${writtenCount} written, ${driftCount} skipped (existing files lack the omd marker — rerun with --force to overwrite).`
-      )
-    );
-    return 0;
-  }
-
-  // Minimal single-skill install (--skills-only): no omd onboarding, no agents/hooks.
-  // Ideal for shipping a standalone skill (e.g. claude-design) to people who don't
-  // want the rest of the omd toolchain.
-  if (minimal) {
-    for (const r of results.filter((x) => x.status === 'skipped-incompat')) {
-      p.log.warn(
-        `${pc.bold(r.skill)} ${pc.dim('skipped for ')}${pc.cyan(r.target)}${pc.dim(' — declares x-omd-channels (channel not supported).')}`
-      );
-    }
-    const installed = results.filter(
-      (r) => r.status === 'created' || r.status === 'updated'
-    );
-    if (installed.length === 0) {
-      p.outro(pc.yellow('Nothing installed — no compatible skill/channel match.'));
-      return 0;
-    }
-    p.outro(
-      pc.green(
-        `Done. Installed ${skills.map((s) => pc.bold(s)).join(', ')} ${scope === 'global' ? 'globally (~/.claude/skills)' : `for ${targets.join(', ')}`}.`
-      ) +
-        pc.dim('  →  restart your agent, then use the skill (e.g. ') +
-        pc.cyan('/claude-design') +
-        pc.dim(').')
-    );
-    return 0;
-  }
-
-  // Friendly next-step nudge after successful install.
-  // The first prompt is kept identical to the README's "Your first 60 seconds"
-  // block so the README, the terminal, and the postinstall message all teach
-  // the same activation moment. Bilingual (EN + KR) so an English reader is not
-  // handed a Korean-only outro.
-  const nextSteps = [
-    `${pc.bold('Restart your agent, then type your first prompt:')}`,
-    '',
-    `  ${pc.cyan('EN')}  ${pc.dim('Set up our design system — Toss-style, for a family meal-tracking app.')}`,
-    `  ${pc.cyan('KR')}  ${pc.dim('토스 스타일로 가족 식단 공유 앱 디자인 시스템 잡아줘')}`,
-    '',
-    `${pc.dim('Your agent runs omd:init and writes DESIGN.md. Then build against it:')}`,
-    `  ${pc.cyan('EN')}  ${pc.dim('Design the home screen.')}   ${pc.cyan('KR')}  ${pc.dim('홈 화면 디자인해줘')}`,
-    '',
-    `${pc.dim('Full walkthrough → "Your first 60 seconds" in the README. Routing is automatic — no slash command needed.')}`,
-    `${pc.dim('Power user: ')}${pc.cyan('/omd-harness <task>')}${pc.dim(' — jump straight into the pipeline.')}`,
-    '',
-    `${pc.yellow('⚠ Already-running session?')} ${pc.dim('Run `/agents` to reload — or quit (Cmd+Q on macOS) and relaunch. Without reload, hooks/agents do not load.')}`,
-  ].join('\n');
-  p.note(nextSteps, 'Next');
-
-  // Counts derived from what was actually resolved/installed — never hardcoded,
-  // so the outro can't drift from the real skill/agent/hook set (or the README).
-  const hookCount = scope === 'project' && targets.includes('claude-code') ? 4 : 0;
-  if (catalogCount > 0) {
-    p.log.message(
-      pc.bold('Reference catalog: ') +
-        pc.cyan(`${catalogCount}`) +
-        pc.dim(' DESIGN.md copied → .claude/data/references/<id>/DESIGN.md'),
-    );
-  }
-  p.outro(
-    pc.green(
-      `Done. ${skills.length} skills · ${canonicalAgents.length} sub-agents · ${hookCount} hooks · ${catalogCount} catalog refs installed (${writtenCount} files)${scope === 'global' ? ' globally (~/.claude)' : ''}.`,
-    ),
-  );
-  return 0;
-}
-