wtf-p 0.4.0 → 0.5.0

package/bin/commands/install-logic.js

@@ -2,16 +2,43 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const MANIFEST = require('../lib/manifest');
-const { 
-  isValidPath, 
-  getClaudeDir, // Legacy support, will refactor
-  getPathLabel, 
-  getBackupPath, 
-  writeVersionFile, 
-  createRL, 
-  prompt 
+const {
+  isValidPath,
+  expandTilde,
+  getPathLabel,
+  getBackupPath,
+  writeVersionFile,
+  detectInstallation,
+  createRL,
+  prompt
 } = require('../lib/utils');
 
+/**
+ * Get vendor-specific config directory
+ */
+function getVendorDir(runtime, explicitConfigDir) {
+  // Handle 'claude-local' special case
+  if (runtime === 'claude-local') {
+    return path.join(process.cwd(), '.claude');
+  }
+
+  const vendorConfig = MANIFEST[runtime];
+  if (!vendorConfig) {
+    throw new Error(`Unknown runtime: ${runtime}`);
+  }
+
+  if (explicitConfigDir) {
+    return expandTilde(explicitConfigDir);
+  }
+
+  const envDir = process.env[vendorConfig.configDirEnv];
+  if (envDir) {
+    return expandTilde(envDir);
+  }
+
+  return path.join(os.homedir(), vendorConfig.defaultDir);
+}
+
 /**
  * Process file content with path replacement
  */
@@ -68,15 +95,15 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
 
   if (existingFiles.length > 0 && !hasForce && !hasBackupAll && isInteractive) {
     const relPath = getPathLabel(targetDir, true);
-    out.log(`  ${c.yellow(`Found ${existingFiles.length} existing WTF-P file(s) in ${relPath}`)}
+    out.log(`  ${c.yellow(`Found ${existingFiles.length} existing file(s) in ${relPath}`)}
 `);
 
     if (showExplanations) {
       out.log(`  ${c.dim('For each file, choose:')}`);
-      out.log(`  ${c.dim('[o]verwrite - Replace with new version')}`);
-      out.log(`  ${c.dim('[s]kip      - Keep your existing file')}`);
-      out.log(`  ${c.dim('[b]ackup    - Save existing, then install new')}`);
-      out.log(`  ${c.dim('[a]ll       - Apply same choice to remaining')}\n`);
+      out.log(`  ${c.dim('[o]verwrite  Replace with new version')}`);
+      out.log(`  ${c.dim('[s]kip       Keep your existing file')}`);
+      out.log(`  ${c.dim('[b]ackup     Save existing, then install new')}`);
+      out.log(`  ${c.dim('[a]ll        Apply same choice to all remaining')}\n`);
     }
   }
 
@@ -132,6 +159,18 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
       stats.backed++;
     }
 
+    // Safety: never overwrite a non-WTF-P plugin.json
+    if (file.name === 'plugin.json' && file.componentId === 'plugin' && exists) {
+      try {
+        const existing = JSON.parse(fs.readFileSync(file.dest, 'utf8'));
+        if (existing.name && existing.name !== 'wtf-p' && existing.name !== 'write-the-f-paper') {
+          out.verbose(`  ${c.yellow('!')} ${c.dim(relDest)} belongs to another plugin — skipped`);
+          stats.skipped++;
+          continue;
+        }
+      } catch { /* corrupt JSON — safe to overwrite */ }
+    }
+
     const content = processContent(file.src, pathPrefix);
     if (content !== null) {
       fs.writeFileSync(file.dest, content);
@@ -153,17 +192,27 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
 
 /**
  * Main install logic
+ * @param {string} runtime - 'claude' | 'gemini' | 'claude-local'
+ * @param {boolean} isUpdate - Whether this is an update operation
+ * @param {object} options - CLI options
+ * @param {object} pkg - Package.json contents
  */
-async function install(isGlobal, isUpdate, options, pkg) {
+async function install(runtime, isUpdate, options, pkg) {
   const { out, explicitConfigDir, hasQuiet, onlyInstall, showExplanations } = options;
   const c = out.colors;
 
-  // Use Claude vendor by default for now (can be passed as arg later)
-  const vendorConfig = MANIFEST.claude;
-  
+  // Handle 'claude-local' by mapping to 'claude' vendor config
+  const vendorKey = runtime === 'claude-local' ? 'claude' : runtime;
+  const vendorConfig = MANIFEST[vendorKey];
+
+  if (!vendorConfig) {
+    out.error(`Unknown runtime: ${runtime}`);
+    process.exit(1);
+  }
+
   // Resolve Target Directory using the Vendor Strategy
-  // TODO: Use getVendorDir generic
-  const targetDir = getClaudeDir(explicitConfigDir, isGlobal);
+  const targetDir = getVendorDir(runtime, explicitConfigDir);
+  const isGlobal = runtime !== 'claude-local';
   const locationLabel = getPathLabel(targetDir, isGlobal);
 
   // Validate path
@@ -174,7 +223,53 @@ async function install(isGlobal, isUpdate, options, pkg) {
 
   const pathPrefix = isGlobal
     ? (explicitConfigDir ? `${targetDir}/` : `~/${vendorConfig.defaultDir}/`)
-    : `./${vendorConfig.defaultDir}/`;
+    : `./.claude/`;
+
+  // ---- Cross-installation conflict detection ----
+  // If installing locally, warn if a global install already exists (and vice versa).
+  // Claude Code loads commands from BOTH ~/.claude/ and ./.claude/, causing duplicates.
+  if (vendorKey === 'claude' && !explicitConfigDir) {
+    const globalDir = path.join(os.homedir(), '.claude');
+    const localDir = path.join(process.cwd(), '.claude');
+
+    if (runtime === 'claude-local') {
+      // Installing local — check if global exists
+      const globalInstall = detectInstallation(globalDir);
+      if (globalInstall.hasCommands) {
+        out.log(`  ${c.yellow('⚠ WTF-P is already installed globally')} ${c.dim('(' + getPathLabel(globalDir, true) + ')')}`);
+        out.log(`    Installing locally too will cause every command to appear twice.`);
+        out.log('');
+        out.log(`    ${c.cyan('Options:')}`);
+        out.log(`      • Use your global install as-is (recommended)`);
+        out.log(`      • Remove global first: ${c.dim('npx wtf-p uninstall --global')}`);
+        out.log(`      • Continue anyway (commands will be duplicated)`);
+        out.log('');
+
+        if (options.isInteractive && !options.hasForce) {
+          const rl = createRL();
+          const answer = await prompt(rl, `  Continue with local install? [y/N]: `);
+          rl.close();
+          if (answer !== 'y' && answer !== 'yes') {
+            out.log(`\n  ${c.yellow('Aborted.')} Using global install.\n`);
+            return;
+          }
+          out.log('');
+        } else if (!options.hasForce) {
+          out.log(`  ${c.yellow('Aborted.')} Use --force to install anyway.\n`);
+          return;
+        }
+      }
+    } else if (runtime === 'claude') {
+      // Installing global — check if local exists in cwd
+      const localInstall = detectInstallation(localDir);
+      if (localInstall.hasCommands && globalDir !== localDir) {
+        out.log(`  ${c.yellow('⚠ WTF-P is also installed locally')} ${c.dim('(' + getPathLabel(localDir, false) + ')')}`);
+        out.log(`    Commands may appear twice in this directory.`);
+        out.log(`    To fix: ${c.dim('npx wtf-p uninstall --local')}`);
+        out.log('');
+      }
+    }
+  }
 
   if (!hasQuiet) {
     out.log(`  Installing to ${c.cyan(locationLabel)}
@@ -214,16 +309,16 @@ async function install(isGlobal, isUpdate, options, pkg) {
   // Summary
   if (!hasQuiet) {
     out.log(`
-  ${c.green('Done!')} Installed: ${stats.installed}, Skipped: ${stats.skipped}, Backed up: ${stats.backed}
+  ${c.green('Done!')} ${c.dim(`[${vendorConfig.name}]`)} Installed: ${stats.installed}, Skipped: ${stats.skipped}, Backed up: ${stats.backed}
 
-  Run ${c.cyan('/wtfp:help')} in Claude Code to get started.
+  Run ${c.cyan('/wtfp:help')} in ${vendorConfig.name} to get started.
 `);
 
     if (showExplanations && !isUpdate) {
-      out.log(`  ${c.yellow('Quick Start:')}`);
-      out.log(`    ${c.cyan('/wtfp:new-paper')}      Start a new academic paper`);
-      out.log(`    ${c.cyan('/wtfp:progress')}       Check your writing status`);
-      out.log(`    ${c.cyan('/wtfp:help')}           Show all commands\n`);
+      out.log(`  ${c.yellow('Get started:')}`);
+      out.log(`    ${c.cyan('/wtfp:new-paper')}      Define your paper's vision and structure`);
+      out.log(`    ${c.cyan('/wtfp:progress')}       See where you are and what's next`);
+      out.log(`    ${c.cyan('/wtfp:help')}           Browse all available commands\n`);
     }
   }
 }

package/bin/commands/status.js

@@ -57,6 +57,7 @@ async function showStatus(options, pkg) {
     if (loc.hasCommands) components.push(`commands (${loc.commandFiles.length} files)`);
     if (loc.hasWorkflows) components.push(`workflows (${loc.workflowFiles.length} files)`);
     if (loc.hasSkills) components.push(`skills (${loc.skillFiles.length} files)`);
+    if (loc.hasAgents) components.push(`agents (${loc.agentFiles.length} files)`);
     out.log(`    Installed: ${components.join(', ')}`);
 
     // Warnings
@@ -70,12 +71,29 @@ async function showStatus(options, pkg) {
     out.log('');
   }
 
-  // Check for updates
+  // Check for dual-install conflict (global + local both present)
+  const bothInstalled = locations.filter(l =>
+    l.hasCommands || l.hasWorkflows || l.hasSkills
+  );
+  if (bothInstalled.length > 1) {
+    out.log(`  ${c.red('⚠ Duplicate installation detected!')}`);
+    out.log(`    WTF-P is installed in both locations. This causes every command to appear twice.`);
+    out.log(`    Remove one to fix:`);
+    out.log(`      ${c.cyan('npx wtf-p uninstall --local')}   Remove local copy`);
+    out.log(`      ${c.cyan('npx wtf-p uninstall --global')}  Remove global copy\n`);
+  }
+
+  // Check for updates (only suggest if registry version is actually newer)
   try {
     const latest = execSync('npm view wtf-p version 2>/dev/null', { encoding: 'utf8' }).trim();
-    if (latest && latest !== pkg.version) {
-      out.log(`  ${c.yellow('Update available:')} ${pkg.version} → ${c.green(latest)}`);
-      out.log(`  Run: ${c.cyan('npx wtf-p update --global')}\n`);
+    const isNewer = (a, b) => {
+      const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+      for (let i = 0; i < 3; i++) { if ((pa[i] || 0) > (pb[i] || 0)) return true; if ((pa[i] || 0) < (pb[i] || 0)) return false; }
+      return false;
+    };
+    if (latest && isNewer(latest, pkg.version)) {
+      out.log(`  ${c.yellow('Update available:')} ${pkg.version} -> ${c.green(latest)}`);
+      out.log(`  Run: ${c.cyan('npx wtf-p update')}\n`);
     }
   } catch {
     // Ignore

package/bin/commands/update.js

@@ -25,8 +25,8 @@ async function runUpdate(options, pkg, installFunc) {
   }
 
   if (!targetDir) {
-    out.log(`  ${c.yellow('No existing installation found.')}`);
-    out.log(`  Run ${c.cyan('npx wtf-p --global')} to install.\n`);
+    out.log(`  ${c.yellow('No WTF-P installation found.')}`);
+    out.log(`  Install with: ${c.cyan('npx wtf-p')}\n`);
     return;
   }
 
@@ -43,8 +43,9 @@ async function runUpdate(options, pkg, installFunc) {
 
   out.log(`\n  ${c.cyan('Updating...')}\n`);
 
-  // Run install with backup
-  await installFunc(isGlobal, true);
+  // Run install with backup (convert isGlobal to runtime string)
+  const runtime = isGlobal ? 'claude' : 'claude-local';
+  await installFunc(runtime, true, options, pkg);
 }
 
 module.exports = runUpdate;

package/bin/install.js

@@ -22,7 +22,7 @@ const showList = require('./commands/list');
 const args = process.argv.slice(2);
 
 // Detect subcommand
-const subcommands = ['status', 'doctor', 'update'];
+const subcommands = ['status', 'doctor', 'update', 'uninstall'];
 const subcommand = args.find(arg => !arg.startsWith('-') && subcommands.includes(arg));
 const subcommandIndex = args.indexOf(subcommand);
 if (subcommandIndex !== -1) {
@@ -32,6 +32,9 @@ if (subcommandIndex !== -1) {
 // Parse flags
 const hasGlobal = args.includes('--global') || args.includes('-g');
 const hasLocal = args.includes('--local') || args.includes('-l');
+const hasGemini = args.includes('--gemini');
+const hasOpenCode = args.includes('--opencode');
+const hasAll = args.includes('--all');
 const hasForce = args.includes('--force') || args.includes('-f');
 const hasBackupAll = args.includes('--backup-all') || args.includes('-b');
 const hasHelp = args.includes('--help') || args.includes('-h');
@@ -90,7 +93,7 @@ ${out.colors.magenta('╚███╔███╔╝   ██║   ██║
 ${out.colors.magenta(' ╚══╝╚══╝    ╚═╝   ╚═╝           ╚═╝')}
 
   ${out.colors.cyan('Write The F***ing Paper')} ${out.colors.dim(`v${pkg.version}`)}
-  Context engineering for academic writing.
+  Academic writing commands for your AI coding assistant.
 `;
 
 // ============ Help Text ============ 
@@ -101,16 +104,20 @@ function showHelp() {
   console.log(`  ${c.yellow('Usage:')} npx wtf-p [command] [options] 
 
   ${c.yellow('Commands:')}
-    ${c.cyan('status')}                    Show current installation state
-    ${c.cyan('doctor')}                    Diagnose installation issues
-    ${c.cyan('update')}                    Update existing installation
+    ${c.cyan('status')}                    Show installation status
+    ${c.cyan('doctor')}                    Check for installation problems
+    ${c.cyan('update')}                    Update to latest version
+    ${c.cyan('uninstall')}                 Remove WTF-P
 
   ${c.yellow('Install Options:')}
-    ${c.cyan('-g, --global')}              Install globally (to Claude config directory)
-    ${c.cyan('-l, --local')}               Install locally (to ./.claude in current directory)
-    ${c.cyan('-c, --config-dir <path>')}   Specify custom Claude config directory
-    ${c.cyan('-f, --force')}               Overwrite all existing files without prompting
-    ${c.cyan('-b, --backup-all')}          Backup all existing files before overwriting
+    ${c.cyan('-g, --global')}              Install to your home directory (recommended)
+    ${c.cyan('-l, --local')}               Install to current project only
+    ${c.cyan('--gemini')}                  Install for Gemini CLI
+    ${c.cyan('--opencode')}                Install for OpenCode
+    ${c.cyan('--all')}                     Install for all supported tools
+    ${c.cyan('-c, --config-dir <path>')}   Install to a custom directory
+    ${c.cyan('-f, --force')}               Overwrite existing files without asking
+    ${c.cyan('-b, --backup-all')}          Backup existing files before overwriting
     ${c.cyan('--only=<type>')}             Install only: commands, workflows, or all
 
   ${c.yellow('Output Options:')}
@@ -121,18 +128,18 @@ function showHelp() {
     ${c.cyan('--verbose')}                 Show detailed progress
 
   ${c.yellow('Other:')}
-    ${c.cyan('-v, --version')}             Show version information
-    ${c.cyan('-h, --help')}                Show this help message
+    ${c.cyan('-v, --version')}             Show version
+    ${c.cyan('-h, --help')}                Show this help
 
   ${c.yellow('Examples:')}
-    ${c.dim('# Interactive install with prompts')}
+    ${c.dim('# Install with interactive prompts')}
     npx wtf-p
 
-    ${c.dim('# Quick global install')}
+    ${c.dim('# Quick global install (no prompts)')}
     npx wtf-p --global --advanced
 
-  ${c.yellow('After installation:')}
-    Run ${c.cyan('/wtfp:help')} in Claude Code to get started.
+  ${c.yellow('After installing:')}
+    Open your AI assistant and run ${c.cyan('/wtfp:help')} to see all commands.
 `);
 }
 
@@ -174,28 +181,61 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'uninstall') {
+    // Delegate to uninstall script with remaining args
+    const { execFileSync } = require('child_process');
+    const uninstallArgs = process.argv.slice(2).filter(a => a !== 'uninstall');
+    try {
+      execFileSync(process.execPath, [path.join(__dirname, 'uninstall.js'), ...uninstallArgs], { stdio: 'inherit' });
+    } catch (e) {
+      process.exit(e.status || 1);
+    }
+    return;
+  }
+
   // Default: Install
   if (!hasQuiet) console.log(banner);
 
-  if (hasGlobal) {
-    await install(true, false, options, pkg);
+  if (hasAll) {
+    // Install for all supported runtimes
+    await install('claude', false, options, pkg);
+    await install('gemini', false, options, pkg);
+    await install('opencode', false, options, pkg);
+  } else if (hasGemini) {
+    await install('gemini', false, options, pkg);
+  } else if (hasOpenCode) {
+    await install('opencode', false, options, pkg);
+  } else if (hasGlobal) {
+    await install('claude', false, options, pkg);
   } else if (hasLocal) {
-    await install(false, false, options, pkg);
+    await install('claude-local', false, options, pkg);
   } else if (options.isInteractive) {
     const rl = createRL();
-    out.log(`  ${out.colors.yellow('Where would you like to install?')} 
+    out.log(`  ${out.colors.yellow('Which tool do you use for AI-assisted coding?')}
 `);
-    out.log(`  ${out.colors.cyan('1)')} Global (~/.claude) - available in all projects`);
-    out.log(`  ${out.colors.cyan('2)')} Local  (./.claude) - this project only
+    out.log(`  ${out.colors.cyan('1)')} Claude Code ${out.colors.dim('(~/.claude)')}`);
+    out.log(`  ${out.colors.cyan('2)')} Gemini CLI ${out.colors.dim('(~/.config/gemini)')}`);
+    out.log(`  ${out.colors.cyan('3)')} OpenCode ${out.colors.dim('(~/.opencode)')}`);
+    out.log(`  ${out.colors.cyan('4)')} All of the above
 `);
-    
+
     const answer = await prompt(rl, `  Choice ${out.colors.dim('[1]')}: `);
     rl.close();
-    
+
     const choice = answer || '1';
-    await install(choice !== '2', false, options, pkg);
+    if (choice === '4') {
+      await install('claude', false, options, pkg);
+      await install('gemini', false, options, pkg);
+      await install('opencode', false, options, pkg);
+    } else if (choice === '3') {
+      await install('opencode', false, options, pkg);
+    } else if (choice === '2') {
+      await install('gemini', false, options, pkg);
+    } else {
+      await install('claude', false, options, pkg);
+    }
   } else {
-    await install(true, false, options, pkg);
+    await install('claude', false, options, pkg);
   }
 }
 

package/bin/lib/checkpoint.js

@@ -0,0 +1,183 @@
+/**
+ * Checkpoint - Save and restore paper state bundles
+ *
+ * Captures complete .planning/ state as a git-tagged checkpoint
+ * that can be restored in a new session for full context recovery.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Create a checkpoint of current paper state
+ * @param {Object} options
+ * @param {string} options.planningDir - Path to .planning/
+ * @param {string} options.label - Checkpoint label (e.g., "pre-discussion", "draft-1")
+ * @param {string} [options.note] - Optional note about checkpoint context
+ * @returns {Object} - { tag, files, timestamp }
+ */
+function createCheckpoint({ planningDir, label, note }) {
+  if (!fs.existsSync(planningDir)) {
+    throw new Error('.planning/ directory not found');
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const tag = `wtfp-checkpoint/${label}-${timestamp}`;
+
+  // Collect all state files
+  const files = collectFiles(planningDir);
+
+  // Stage all planning files
+  try {
+    execSync(`git add ${planningDir}`, { stdio: 'pipe' });
+  } catch (e) {
+    // May fail if no changes — that's OK
+  }
+
+  // Check if there are staged changes
+  const status = execSync('git status --porcelain', { encoding: 'utf8' });
+  const hasChanges = status.trim().length > 0;
+
+  if (hasChanges) {
+    const commitMsg = `checkpoint: ${label}${note ? `\n\n${note}` : ''}`;
+    execSync(`git commit -m "${commitMsg.replace(/"/g, '\\"')}"`, { stdio: 'pipe' });
+  }
+
+  // Create annotated tag
+  const tagMsg = [
+    `WTF-P Checkpoint: ${label}`,
+    `Timestamp: ${timestamp}`,
+    `Files: ${files.length}`,
+    note ? `Note: ${note}` : '',
+  ].filter(Boolean).join('\n');
+
+  execSync(`git tag -a "${tag}" -m "${tagMsg.replace(/"/g, '\\"')}"`, { stdio: 'pipe' });
+
+  return { tag, files: files.length, timestamp };
+}
+
+/**
+ * Restore a checkpoint by tag name
+ * @param {string} tag - Git tag to restore from
+ * @returns {Object} - { restored, files }
+ */
+function restoreCheckpoint(tag) {
+  // Verify tag exists
+  try {
+    execSync(`git tag -l "${tag}"`, { encoding: 'utf8', stdio: 'pipe' });
+  } catch (e) {
+    throw new Error(`Checkpoint tag not found: ${tag}`);
+  }
+
+  // Restore .planning/ from the tagged commit
+  try {
+    execSync(`git checkout "${tag}" -- .planning/`, { stdio: 'pipe' });
+    return { restored: true, tag };
+  } catch (e) {
+    throw new Error(`Failed to restore checkpoint: ${e.message}`);
+  }
+}
+
+/**
+ * List available checkpoints
+ * @returns {Array} - List of { tag, date, label, message }
+ */
+function listCheckpoints() {
+  try {
+    const tags = execSync('git tag -l "wtfp-checkpoint/*" --sort=-creatordate', {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    }).trim();
+
+    if (!tags) return [];
+
+    return tags.split('\n').map(tag => {
+      let message = '';
+      try {
+        message = execSync(`git tag -l "${tag}" -n1`, {
+          encoding: 'utf8',
+          stdio: 'pipe',
+        }).trim();
+      } catch (e) { /* ignore */ }
+
+      const parts = tag.replace('wtfp-checkpoint/', '').split('-');
+      const label = parts.slice(0, -6).join('-'); // Remove timestamp portion
+
+      return { tag, label, message };
+    });
+  } catch (e) {
+    return [];
+  }
+}
+
+/**
+ * Generate a handoff document for session continuity
+ * @param {string} planningDir - Path to .planning/
+ * @returns {string} - Markdown content for HANDOFF.md
+ */
+function generateHandoff(planningDir) {
+  const statePath = path.join(planningDir, 'STATE.md');
+  const configPath = path.join(planningDir, 'config.json');
+
+  const state = fs.existsSync(statePath) ? fs.readFileSync(statePath, 'utf8') : '';
+  let config = {};
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) { /* ignore */ }
+
+  // Extract position from STATE.md
+  const positionMatch = state.match(/Section:\s*(\d+)\s*of\s*(\d+)/i);
+  const wordsMatch = state.match(/Words?:\s*(\d+)\s*\/\s*(\d+)/i);
+
+  const sections = [];
+  sections.push('# Session Handoff');
+  sections.push(`\nGenerated: ${new Date().toISOString()}`);
+  sections.push(`\n## Position`);
+
+  if (positionMatch) {
+    sections.push(`- Section: ${positionMatch[1]} of ${positionMatch[2]}`);
+  }
+  if (wordsMatch) {
+    sections.push(`- Words: ${wordsMatch[1]} / ${wordsMatch[2]}`);
+  }
+  if (config.model_profile) {
+    sections.push(`- Profile: ${config.model_profile}`);
+  }
+
+  sections.push(`\n## Resume With`);
+  sections.push('```');
+  sections.push('/wtfp:resume-writing');
+  sections.push('```');
+
+  return sections.join('\n');
+}
+
+// --- Helpers ---
+
+function collectFiles(dir) {
+  const files = [];
+
+  function walk(d) {
+    if (!fs.existsSync(d)) return;
+    const entries = fs.readdirSync(d, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(d, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else {
+        files.push(full);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+module.exports = {
+  createCheckpoint,
+  restoreCheckpoint,
+  listCheckpoints,
+  generateHandoff,
+};