ts-procedures 10.2.0 → 10.2.2

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## 10.2.2 — 2026-06-29
+
+### Fixed
+
+- **Export `ProcedureResult` from the package root.** The shape every creator returns (`Create`/`CreateStream`/`CreateHttp`/`CreateHttpStream`) appears in the inferred return type of `Procedures(...)`, but the type itself was only reachable via an internal deep path. Downstream apps that assign a factory or creator result to an exported binding under declaration emit (e.g. `export const api = Procedures<Ctx>(...)`) hit `TS2742`/`TS2883` — _"The inferred type of '…' cannot be named without a reference to 'ProcedureResult' from '…/node_modules/ts-procedures/build/core/types.js'. This is likely not portable."_ Re-exporting `ProcedureResult` lets TypeScript name the type via the portable `ts-procedures` specifier. No runtime change.
+
+## 10.2.1 — 2026-06-26
+
+### Changed
+
+- **AI agent config is now a single spec-compliant [Agent Skill](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills).** Replaced the per-tool config directories (`claude-code/`, `cursor/`, `copilot/`) with one source of truth at `agent_config/skills/ts-procedures/`. `npx ts-procedures-setup` now installs that one skill into the standard agent roots — `.agents/skills/ts-procedures/` (read by Codex, Cursor, GitHub Copilot, Gemini CLI, and 30+ tools) and `.claude/skills/ts-procedures/` (Claude Code native) — eliminating the hand-synced duplicate `.cursorrules` / `.github/copilot-instructions.md` files and their marker-merge machinery.
+- `ts-procedures-setup` CLI simplified to `--dry-run` / `--check` / `--help` (per-tool `targets` and `--force` removed; the install is a force-overwrite copy). The postinstall auto-update remains opt-in (only refreshes once the skill is already installed).
+
+### Removed
+
+- The Claude-only `ts-procedures-architect` agent and the Claude Code plugin manifest (`.claude-plugin/plugin.json`). The unified `ts-procedures` skill covers reference, scaffold, and review modes.
+- Downstream cleanup note: a previously installed `.claude/agents/ts-procedures-architect.md` is now orphaned and can be deleted manually.
+
 ## 10.2.0 — 2026-06-25
 
 ### Added

package/README.md

@@ -191,17 +191,20 @@ implementation.
 
 ## AI assistant setup
 
-The package ships rules and skills for Claude Code, Cursor, and GitHub
-Copilot so your AI tooling knows the framework's patterns and footguns:
+The package ships a single spec-compliant [Agent Skill](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
+so your AI tooling knows the framework's patterns and footguns. One skill is
+installed into the standard agent directories (`.agents/skills/` — read by
+Codex, Cursor, Copilot, Gemini CLI and 30+ others — plus `.claude/skills/` for
+Claude Code):
 
 ```bash
-npx ts-procedures-setup            # all targets
-npx ts-procedures-setup claude     # Claude Code only
+npx ts-procedures-setup            # install the skill
 npx ts-procedures-setup --dry-run  # preview
+npx ts-procedures-setup --check    # CI gate: fail if outdated
 ```
 
-Installed files auto-update on subsequent `npm install` via the package's
-postinstall hook.
+The installed skill auto-updates on subsequent `npm install` via the package's
+postinstall hook. See [docs/ai-agent-setup.md](docs/ai-agent-setup.md).
 
 ## Migrating from v8
 

package/agent_config/bin/postinstall.mjs

@@ -1,105 +1,36 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { resolve, join, dirname } from 'node:path';
+import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { installSkills, isInstalled } from '../lib/install-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const AGENT_CONFIG_DIR = resolve(__dirname, '..');
 
-const MARKER_BEGIN = '<!-- BEGIN ts-procedures -->';
-const MARKER_END = '<!-- END ts-procedures -->';
+// ─── Per-project config (keep in sync with bin/setup.mjs) ────────────────────
+const CONFIG = {
+  packageName: 'ts-procedures',
+  sourceDir: resolve(__dirname, '..', 'skills'),
+  skills: ['ts-procedures'],
+  targetRoots: ['.agents/skills', '.claude/skills'],
+};
 
-// INIT_CWD is set by npm/yarn/pnpm during lifecycle scripts — points to the project root
+// INIT_CWD is set by npm/yarn/pnpm during lifecycle scripts — the project root.
 const projectRoot = process.env.INIT_CWD;
+if (!projectRoot) process.exit(0);
 
-if (!projectRoot) {
-  process.exit(0);
-}
-
-// Detect self-install (developing ts-procedures itself) — skip
-const ownPackageRoot = resolve(__dirname, '../..');
-if (resolve(projectRoot) === ownPackageRoot) {
-  process.exit(0);
-}
-
-// ─── Helpers ──────────────────────────────────────────────
-
-function readSourceFile(relativePath) {
-  return readFileSync(join(AGENT_CONFIG_DIR, relativePath), 'utf-8');
-}
-
-function wrapWithMarkers(content) {
-  return `${MARKER_BEGIN}\n${content.trim()}\n${MARKER_END}`;
-}
-
-function replaceMarkerSection(existingContent, newContent) {
-  const beginIdx = existingContent.indexOf(MARKER_BEGIN);
-  const endIdx = existingContent.indexOf(MARKER_END);
-
-  if (beginIdx !== -1 && endIdx !== -1) {
-    const before = existingContent.slice(0, beginIdx);
-    const after = existingContent.slice(endIdx + MARKER_END.length);
-    return before + wrapWithMarkers(newContent) + after;
-  }
-
-  return null; // No existing markers — don't modify
-}
+// Skip when developing this package itself.
+if (resolve(projectRoot) === resolve(__dirname, '..', '..')) process.exit(0);
 
-function updateMarkedFile(targetPath, sourceRelativePath) {
-  if (!existsSync(targetPath)) return false;
+const cfg = { ...CONFIG, projectRoot };
 
-  const existing = readFileSync(targetPath, 'utf-8');
-  if (!existing.includes(MARKER_BEGIN)) return false;
-
-  const sourceContent = readSourceFile(sourceRelativePath);
-  const updated = replaceMarkerSection(existing, sourceContent);
-  if (updated) {
-    writeFileSync(targetPath, updated, 'utf-8');
-    return true;
-  }
-  return false;
-}
-
-// ─── Auto-update ──────────────────────────────────────────
-
-const claudeSkillDir = join(projectRoot, '.claude', 'skills', 'ts-procedures');
-const cursorFile = join(projectRoot, '.cursorrules');
-const copilotFile = join(projectRoot, '.github', 'copilot-instructions.md');
-
-// Check if any target was previously set up
-const hasAnySetup = existsSync(claudeSkillDir) || existsSync(cursorFile) || existsSync(copilotFile);
-
-if (hasAnySetup) {
+// Opt-in only: refresh skills the user has already installed; never create on
+// first install (rely on README / `npx <pkg>-setup`).
+if (isInstalled(cfg)) {
   try {
-    const updated = [];
-
-    // Auto-update Claude Code files
-    if (existsSync(claudeSkillDir)) {
-      const { installClaude } = await import('../lib/install-claude.mjs');
-      installClaude(projectRoot);
-      updated.push('Claude Code');
-    }
-
-    // Auto-update Cursor rules (only if markers present)
-    if (updateMarkedFile(cursorFile, 'cursor/cursorrules')) {
-      updated.push('Cursor');
-    }
-
-    // Auto-update Copilot instructions (only if markers present)
-    if (updateMarkedFile(copilotFile, 'copilot/copilot-instructions.md')) {
-      updated.push('Copilot');
-    }
-
-    if (updated.length > 0) {
-      console.log('');
-      console.log(`  ts-procedures — AI agent rules updated (${updated.join(', ')})`);
-      console.log('');
-    }
+    installSkills(cfg);
+    console.log(`\n  ${CONFIG.packageName} — Agent Skill updated\n`);
   } catch {
-    // Never break npm install
+    // Never break npm install.
   }
 }
-
-// No invitation message if not opted in — rely on README / npx ts-procedures-setup --help

package/agent_config/bin/setup.mjs

@@ -1,297 +1,84 @@
 #!/usr/bin/env node
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline';
-import { installClaude } from '../lib/install-claude.mjs';
+import { installSkills, planSkills, outdatedSkillFiles } from '../lib/install-skills.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const AGENT_CONFIG_DIR = resolve(__dirname, '..');
-const PROJECT_DIR = process.cwd();
-
-const MARKER_BEGIN = '<!-- BEGIN ts-procedures -->';
-const MARKER_END = '<!-- END ts-procedures -->';
 
-const VALID_TARGETS = ['claude', 'cursor', 'copilot', 'all'];
+// ─── Per-project config (the only thing a consuming library customizes) ──────
+const CONFIG = {
+  packageName: 'ts-procedures',
+  sourceDir: resolve(__dirname, '..', 'skills'),
+  skills: ['ts-procedures'],
+  // `.agents/skills` is read by 30+ agent tools (Codex, Cursor, Copilot,
+  // Gemini CLI, …); `.claude/skills` is Claude Code's native project location.
+  // One source, fanned out to both.
+  targetRoots: ['.agents/skills', '.claude/skills'],
+};
 
-// ─── Helpers ──────────────────────────────────────────────
+const PROJECT_DIR = process.cwd();
 
 function printUsage() {
   console.log(`
-Usage: npx ts-procedures-setup [targets...] [options]
+Usage: npx ${CONFIG.packageName}-setup [options]
 
-Targets:
-  claude     Install Claude Code skills and architect agent into .claude/
-  cursor     Copy ts-procedures rules to .cursorrules
-  copilot    Copy ts-procedures instructions to .github/copilot-instructions.md
-  all        Set up all targets (default)
+Installs the ${CONFIG.packageName} Agent Skill into the standard agent
+directories so any compatible AI coding tool picks it up automatically:
+
+  ${CONFIG.targetRoots.map((r) => `${r}/${CONFIG.skills.join(', ')}`).join('\n  ')}
 
 Options:
   --help      Show this help message
-  --force     Overwrite existing files without prompting
   --dry-run   Show what would be created/updated without writing files
-  --check     Exit with code 1 if any files are outdated (useful in CI)
+  --check     Exit with code 1 if any installed files are outdated (CI gate)
 
-Examples:
-  npx ts-procedures-setup              # Set up all targets
-  npx ts-procedures-setup cursor       # Set up Cursor only
-  npx ts-procedures-setup cursor copilot  # Set up Cursor and Copilot
-  npx ts-procedures-setup --force      # Overwrite without prompting
-  npx ts-procedures-setup --dry-run    # Preview changes
-  npx ts-procedures-setup --check      # Verify files are up to date
+The files auto-update on every \`npm install\` once installed.
 `);
 }
 
-function readSourceFile(relativePath) {
-  const fullPath = join(AGENT_CONFIG_DIR, relativePath);
-  return readFileSync(fullPath, 'utf-8');
-}
-
-function wrapWithMarkers(content) {
-  return `${MARKER_BEGIN}\n${content.trim()}\n${MARKER_END}`;
-}
-
-function replaceMarkerSection(existingContent, newContent) {
-  const beginIdx = existingContent.indexOf(MARKER_BEGIN);
-  const endIdx = existingContent.indexOf(MARKER_END);
-
-  if (beginIdx !== -1 && endIdx !== -1) {
-    const before = existingContent.slice(0, beginIdx);
-    const after = existingContent.slice(endIdx + MARKER_END.length);
-    return before + wrapWithMarkers(newContent) + after;
-  }
-
-  const separator = existingContent.trim() ? '\n\n' : '';
-  return existingContent.trim() + separator + wrapWithMarkers(newContent) + '\n';
-}
-
-async function confirm(message) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(`${message} (y/N) `, (answer) => {
-      rl.close();
-      resolve(answer.toLowerCase() === 'y');
-    });
-  });
-}
-
-// ─── Check Mode ───────────────────────────────────────────
-
-function isFileOutdated(targetPath, expectedContent) {
-  if (!existsSync(targetPath)) return true;
-  const current = readFileSync(targetPath, 'utf-8');
-  return current !== expectedContent;
-}
-
-// ─── Target Handlers ──────────────────────────────────────
-
-function setupClaude({ dryRun, check } = {}) {
-  if (dryRun) {
-    // Mirror install-claude.mjs: copy every file under each source skill dir, plus the agent.
-    const claudeFiles = [];
-    const skillsSrc = join(AGENT_CONFIG_DIR, 'claude-code', 'skills');
-    for (const skill of ['ts-procedures']) {
-      const walk = (dir, prefix) => {
-        for (const entry of readdirSync(dir)) {
-          const full = join(dir, entry);
-          if (statSync(full).isDirectory()) {
-            walk(full, `${prefix}/${entry}`);
-          } else {
-            claudeFiles.push(`${prefix}/${entry}`);
-          }
-        }
-      };
-      walk(join(skillsSrc, skill), `.claude/skills/${skill}`);
-    }
-    claudeFiles.push('.claude/agents/ts-procedures-architect.md');
-
-    console.log('\n  Claude Code (dry run)');
-    console.log('  ─────────────────────');
-    for (const f of claudeFiles) {
-      const status = existsSync(join(PROJECT_DIR, f)) ? 'update' : 'create';
-      console.log(`    [${status}] ${f}`);
-    }
-    console.log('');
-    return false;
-  }
-
-  const { files } = installClaude(PROJECT_DIR);
-
-  if (check) return false; // installClaude always writes — check mode handled at main level
-
-  console.log('\n  Claude Code');
-  console.log('  ───────────');
-  console.log('  Installed (updates automatically on npm install/update):\n');
-  for (const f of files) {
-    console.log(`    ${f}`);
-  }
-  console.log('');
-  console.log('  Skills:  ts-procedures (use `/ts-procedures review <path>` and `/ts-procedures scaffold <type> <Name>`; Kotlin/Swift codegen reference included)');
-  console.log('  Agent:   ts-procedures-architect (architecture planning)\n');
-  return false;
-}
-
-async function setupCursor(force, { dryRun, check } = {}) {
-  const targetPath = join(PROJECT_DIR, '.cursorrules');
-  const sourceContent = readSourceFile('cursor/cursorrules');
-
-  if (dryRun || check) {
-    const exists = existsSync(targetPath);
-    const hasMarkers = exists && readFileSync(targetPath, 'utf-8').includes(MARKER_BEGIN);
-    const label = dryRun ? 'dry run' : 'check';
-    const status = !exists ? 'create' : hasMarkers ? 'update' : 'append';
-    console.log(`\n  Cursor (${label})`);
-    console.log(`  ──────`);
-    console.log(`    [${status}] .cursorrules\n`);
-    return check && (status === 'create' || status === 'update');
-  }
-
-  console.log('\n  Cursor');
-  console.log('  ──────');
-
-  if (existsSync(targetPath)) {
-    const existing = readFileSync(targetPath, 'utf-8');
-
-    if (existing.includes(MARKER_BEGIN)) {
-      const updated = replaceMarkerSection(existing, sourceContent);
-      writeFileSync(targetPath, updated, 'utf-8');
-      console.log('  Updated ts-procedures section in .cursorrules\n');
-      return false;
-    }
-
-    if (!force) {
-      const ok = await confirm('  .cursorrules already exists. Append ts-procedures rules?');
-      if (!ok) {
-        console.log('  Skipped.\n');
-        return false;
-      }
-    }
-
-    const updated = replaceMarkerSection(existing, sourceContent);
-    writeFileSync(targetPath, updated, 'utf-8');
-    console.log('  Appended ts-procedures rules to .cursorrules\n');
-  } else {
-    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
-    console.log('  Created .cursorrules\n');
-  }
-  return false;
-}
-
-async function setupCopilot(force, { dryRun, check } = {}) {
-  const githubDir = join(PROJECT_DIR, '.github');
-  const targetPath = join(githubDir, 'copilot-instructions.md');
-  const sourceContent = readSourceFile('copilot/copilot-instructions.md');
-
-  if (dryRun || check) {
-    const exists = existsSync(targetPath);
-    const hasMarkers = exists && readFileSync(targetPath, 'utf-8').includes(MARKER_BEGIN);
-    const label = dryRun ? 'dry run' : 'check';
-    const status = !exists ? 'create' : hasMarkers ? 'update' : 'append';
-    console.log(`\n  GitHub Copilot (${label})`);
-    console.log(`  ──────────────`);
-    console.log(`    [${status}] .github/copilot-instructions.md\n`);
-    return check && (status === 'create' || status === 'update');
-  }
-
-  console.log('\n  GitHub Copilot');
-  console.log('  ──────────────');
-
-  if (!existsSync(githubDir)) {
-    mkdirSync(githubDir, { recursive: true });
-  }
-
-  if (existsSync(targetPath)) {
-    const existing = readFileSync(targetPath, 'utf-8');
-
-    if (existing.includes(MARKER_BEGIN)) {
-      const updated = replaceMarkerSection(existing, sourceContent);
-      writeFileSync(targetPath, updated, 'utf-8');
-      console.log('  Updated ts-procedures section in .github/copilot-instructions.md\n');
-      return false;
-    }
-
-    if (!force) {
-      const ok = await confirm('  .github/copilot-instructions.md already exists. Append ts-procedures instructions?');
-      if (!ok) {
-        console.log('  Skipped.\n');
-        return false;
-      }
-    }
-
-    const updated = replaceMarkerSection(existing, sourceContent);
-    writeFileSync(targetPath, updated, 'utf-8');
-    console.log('  Appended ts-procedures instructions to .github/copilot-instructions.md\n');
-  } else {
-    writeFileSync(targetPath, wrapWithMarkers(sourceContent) + '\n', 'utf-8');
-    console.log('  Created .github/copilot-instructions.md\n');
-  }
-  return false;
-}
-
-// ─── Main ─────────────────────────────────────────────────
-
-async function main() {
+function main() {
   const args = process.argv.slice(2);
-  const force = args.includes('--force');
-  const dryRun = args.includes('--dry-run');
-  const check = args.includes('--check');
-  const help = args.includes('--help') || args.includes('-h');
-  const targets = args.filter(a => !a.startsWith('--') && !a.startsWith('-'));
-
-  if (help) {
+  if (args.includes('--help') || args.includes('-h')) {
     printUsage();
     process.exit(0);
   }
-
-  for (const t of targets) {
-    if (!VALID_TARGETS.includes(t)) {
-      console.error(`Unknown target: "${t}". Valid targets: ${VALID_TARGETS.join(', ')}`);
-      process.exit(1);
-    }
-  }
-
-  const selectedTargets = targets.length === 0 || targets.includes('all')
-    ? ['claude', 'cursor', 'copilot']
-    : targets;
+  const dryRun = args.includes('--dry-run');
+  const check = args.includes('--check');
+  const cfg = { ...CONFIG, projectRoot: PROJECT_DIR };
 
   const mode = dryRun ? ' (dry run)' : check ? ' (check)' : '';
-  console.log(`\nts-procedures AI Agent Setup${mode}`);
-  console.log('════════════════════════════');
-
-  const opts = { dryRun, check };
-  let outdated = false;
-
-  if (selectedTargets.includes('claude')) {
-    outdated = setupClaude(opts) || outdated;
-  }
-
-  if (selectedTargets.includes('cursor')) {
-    outdated = (await setupCursor(force, opts)) || outdated;
-  }
-
-  if (selectedTargets.includes('copilot')) {
-    outdated = (await setupCopilot(force, opts)) || outdated;
-  }
+  console.log(`\n${CONFIG.packageName} — Agent Skill setup${mode}`);
+  console.log('═'.repeat(40));
 
   if (check) {
-    if (outdated) {
-      console.log('  Files are outdated. Run: npx ts-procedures-setup\n');
+    const outdated = outdatedSkillFiles(cfg);
+    if (outdated.length) {
+      console.log('\n  Outdated or missing:');
+      for (const f of outdated) console.log(`    ${f}`);
+      console.log(`\n  Run: npx ${CONFIG.packageName}-setup\n`);
       process.exit(1);
-    } else {
-      console.log('  All files are up to date.\n');
     }
-  } else if (dryRun) {
-    console.log('  No files were modified (dry run).\n');
-  } else {
-    console.log('  Tip: Auto-generated .claude/ files can be added to .gitignore');
-    console.log('  (they are regenerated on npm install).\n');
-    console.log('Done!\n');
+    console.log('\n  All files are up to date.\n');
+    return;
+  }
+
+  if (dryRun) {
+    console.log('');
+    for (const { rel, dest } of planSkills(cfg)) {
+      console.log(`    [${existsSync(dest) ? 'update' : 'create'}] ${rel}`);
+    }
+    console.log('\n  No files were modified (dry run).\n');
+    return;
   }
+
+  const { files } = installSkills(cfg);
+  console.log('\n  Installed (auto-updates on npm install):\n');
+  for (const f of files) console.log(`    ${f}`);
+  console.log('\n  Tip: these are generated — you may add the install roots to .gitignore.\n');
+  console.log('Done!\n');
 }
 
-main().catch((err) => {
-  console.error('Error:', err.message);
-  process.exit(1);
-});
+main();

package/agent_config/lib/install-skills.mjs

@@ -0,0 +1,108 @@
+import { cpSync, mkdirSync, readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic, project-agnostic skill installer.
+//
+// This file is intentionally free of any ts-procedures specifics so it can be
+// dropped verbatim into any library that ships Agent Skills. The only
+// per-project surface is the config object the caller passes in (see
+// bin/setup.mjs / bin/postinstall.mjs).
+//
+// A "skill" is a spec-compliant directory containing a SKILL.md (name +
+// description frontmatter) plus optional references/templates. The same
+// directory is read by 30+ agent tools from `.agents/skills/<name>/` and by
+// Claude Code from `.claude/skills/<name>/`, so we fan the one source out to
+// every configured target root.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Recursively list file paths under `dir`, relative to `dir`. */
+export function listFilesRecursive(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      for (const nested of listFilesRecursive(full)) out.push(join(entry, nested));
+    } else {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Enumerate the install plan without touching the filesystem.
+ *
+ * @param {object} cfg
+ * @param {string}   cfg.projectRoot — consuming project root (absolute)
+ * @param {string}   cfg.sourceDir   — dir containing the source skill folders (absolute)
+ * @param {string[]} cfg.skills      — skill folder names under sourceDir
+ * @param {string[]} cfg.targetRoots — install roots relative to projectRoot
+ *                                      (e.g. ['.agents/skills', '.claude/skills'])
+ * @returns {Array<{ skill: string, root: string, rel: string, src: string, dest: string }>}
+ */
+export function planSkills({ projectRoot, sourceDir, skills, targetRoots }) {
+  const plan = [];
+  for (const skill of skills) {
+    const skillSrc = join(sourceDir, skill);
+    for (const rel of listFilesRecursive(skillSrc)) {
+      for (const root of targetRoots) {
+        plan.push({
+          skill,
+          root,
+          rel: join(root, skill, rel),
+          src: join(skillSrc, rel),
+          dest: join(projectRoot, root, skill, rel),
+        });
+      }
+    }
+  }
+  return plan;
+}
+
+/**
+ * Copy each source skill into every target root (force-overwrite).
+ *
+ * @param {object} cfg — same shape as planSkills
+ * @returns {{ files: string[] }} — installed paths relative to projectRoot
+ */
+export function installSkills({ projectRoot, sourceDir, skills, targetRoots }) {
+  const files = [];
+  for (const root of targetRoots) {
+    const rootDest = join(projectRoot, root);
+    mkdirSync(rootDest, { recursive: true });
+    for (const skill of skills) {
+      cpSync(join(sourceDir, skill), join(rootDest, skill), { recursive: true, force: true });
+    }
+  }
+  for (const { rel } of planSkills({ projectRoot, sourceDir, skills, targetRoots })) {
+    files.push(rel);
+  }
+  return { files };
+}
+
+/**
+ * Report which planned files are missing or differ from source (for --check).
+ *
+ * @param {object} cfg — same shape as planSkills
+ * @returns {string[]} — relative paths that are outdated (empty == up to date)
+ */
+export function outdatedSkillFiles(cfg) {
+  const outdated = [];
+  for (const { rel, src, dest } of planSkills(cfg)) {
+    if (!existsSync(dest) || readFileSync(dest, 'utf-8') !== readFileSync(src, 'utf-8')) {
+      outdated.push(rel);
+    }
+  }
+  return outdated;
+}
+
+/** True if any skill was previously installed into any target root. */
+export function isInstalled({ projectRoot, skills, targetRoots }) {
+  for (const root of targetRoots) {
+    for (const skill of skills) {
+      if (existsSync(join(projectRoot, root, skill))) return true;
+    }
+  }
+  return false;
+}

package/build/codegen/bin/cli.js

@@ -21,7 +21,7 @@ export async function loadConfigFile(configPath) {
     catch (err) {
         if (configPath !== undefined) {
             // Explicit path — always throw
-            throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`);
+            throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`, { cause: err });
         }
         // Default path — silently ignore if not found
         return undefined;