trellis 1.0.8 → 2.0.5

package/src/cli/index.ts

@@ -0,0 +1,2340 @@
+#!/usr/bin/env bun
+
+/**
+ * TrellisVCS CLI
+ *
+ * Commands:
+ *   init     Initialize a new TrellisVCS repository
+ *   status   Show current repository status
+ *   log      Show operation history
+ *   watch    Start file watcher (foreground)
+ *   files    List tracked files
+ *   import   Import from a Git repository
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { resolve, join } from 'path';
+import { TrellisVcsEngine } from '../engine.js';
+import { importFromGit } from '../git/git-importer.js';
+import { exportToGit } from '../git/git-exporter.js';
+import {
+  createIdentity,
+  saveIdentity,
+  loadIdentity,
+  hasIdentity,
+  toPublicIdentity,
+} from '../identity/index.js';
+
+const program = new Command();
+
+program
+  .name('trellis')
+  .description('TrellisVCS — graph-native, code-first version control')
+  .version('0.1.0');
+
+function requireRepo(rootPath: string): void {
+  if (!TrellisVcsEngine.isRepo(rootPath)) {
+    console.error(
+      chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+    );
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// trellis init
+// ---------------------------------------------------------------------------
+
+program
+  .command('init')
+  .description(
+    'Initialize a new TrellisVCS repository in the current directory',
+  )
+  .option('-p, --path <path>', 'Path to initialize', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+
+    if (TrellisVcsEngine.isRepo(rootPath)) {
+      console.log(chalk.yellow('Already a TrellisVCS repository.'));
+      return;
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    const result = await engine.initRepo();
+
+    console.log(chalk.green('✓ Initialized TrellisVCS repository'));
+    console.log(`  ${chalk.dim('Path:')}     ${rootPath}`);
+    console.log(
+      `  ${chalk.dim('Ops:')}      ${result.opsCreated} initial operations recorded`,
+    );
+    console.log(`  ${chalk.dim('Config:')}   .trellis/config.json`);
+    console.log(`  ${chalk.dim('Op log:')}   .trellis/ops.json`);
+    console.log();
+    console.log(
+      chalk.dim(
+        'The causal stream is now recording. Every file change will be tracked.',
+      ),
+    );
+  });
+
+// ---------------------------------------------------------------------------
+// trellis repair
+// ---------------------------------------------------------------------------
+
+program
+  .command('repair')
+  .description('Attempt to repair a corrupted .trellis/ops.json file')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    console.log(chalk.yellow('Attempting to repair ops.json...'));
+    const result = TrellisVcsEngine.repair(rootPath);
+
+    if (result.lost === -1) {
+      console.log(
+        chalk.red(
+          'Could not recover any ops. A corrupted backup was saved as ops.json.corrupted',
+        ),
+      );
+    } else if (result.recovered > 0) {
+      console.log(chalk.green(`✓ Recovered ${result.recovered} ops.`));
+    } else {
+      console.log(chalk.green('ops.json is already valid. No repair needed.'));
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis status
+// ---------------------------------------------------------------------------
+
+program
+  .command('status')
+  .description('Show current repository status')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.log(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+    const st = engine.status();
+
+    console.log(chalk.bold('TrellisVCS Status'));
+    console.log();
+    console.log(`  ${chalk.dim('Branch:')}        ${chalk.cyan(st.branch)}`);
+    console.log(`  ${chalk.dim('Total ops:')}     ${st.totalOps}`);
+    console.log(`  ${chalk.dim('Tracked files:')} ${st.trackedFiles}`);
+
+    if (st.lastOp) {
+      console.log();
+      console.log(
+        `  ${chalk.dim('Last op:')}      ${chalk.yellow(st.lastOp.kind)}`,
+      );
+      console.log(`  ${chalk.dim('  at:')}          ${st.lastOp.timestamp}`);
+      if (st.lastOp.vcs?.filePath) {
+        console.log(
+          `  ${chalk.dim('  file:')}        ${st.lastOp.vcs.filePath}`,
+        );
+      }
+    }
+
+    if (st.recentOps.length > 0) {
+      console.log();
+      console.log(chalk.dim('  Recent activity:'));
+      // Show last 5 ops (excluding branch create for readability)
+      const display = st.recentOps
+        .filter((op) => op.kind !== 'vcs:branchCreate')
+        .slice(-5);
+      for (const op of display) {
+        const kind = formatOpKind(op.kind);
+        const file = op.vcs?.filePath ?? '';
+        const time = formatRelativeTime(op.timestamp);
+        console.log(`    ${kind} ${chalk.white(file)} ${chalk.dim(time)}`);
+      }
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis log
+// ---------------------------------------------------------------------------
+
+program
+  .command('log')
+  .description('Show operation history')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('-n, --limit <n>', 'Number of ops to show', '20')
+  .option('-f, --file <file>', 'Filter by file path')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.log(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+    const ops = engine.log({
+      limit: parseInt(opts.limit, 10),
+      filePath: opts.file,
+    });
+
+    if (ops.length === 0) {
+      console.log(chalk.dim('No operations found.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Causal Stream — ${ops.length} ops`));
+    console.log();
+
+    for (const op of ops.reverse()) {
+      const kind = formatOpKind(op.kind);
+      const hash = chalk.dim(op.hash.slice(0, 28) + '…');
+      const time = formatRelativeTime(op.timestamp);
+      const file = op.vcs?.filePath ? chalk.white(op.vcs.filePath) : '';
+      const rename = op.vcs?.oldFilePath
+        ? chalk.dim(` (from ${op.vcs.oldFilePath})`)
+        : '';
+
+      console.log(`  ${hash} ${kind} ${file}${rename} ${chalk.dim(time)}`);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis files
+// ---------------------------------------------------------------------------
+
+program
+  .command('files')
+  .description('List all tracked files')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.log(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+    const files = engine.trackedFiles();
+
+    if (files.length === 0) {
+      console.log(chalk.dim('No tracked files.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Tracked Files — ${files.length}`));
+    console.log();
+
+    for (const f of files.sort((a, b) => a.path.localeCompare(b.path))) {
+      const hash = f.contentHash
+        ? chalk.dim(f.contentHash.slice(0, 12))
+        : chalk.dim('(no hash)');
+      console.log(`  ${hash} ${f.path}`);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis watch
+// ---------------------------------------------------------------------------
+
+program
+  .command('watch')
+  .description('Start file watcher (foreground, Ctrl+C to stop)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.log(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    console.log(
+      chalk.green('✓ Watching for changes…') + chalk.dim(' (Ctrl+C to stop)'),
+    );
+    console.log();
+
+    // Override engine's watch to add logging
+    const originalWatch = engine.watch.bind(engine);
+    engine.watch();
+
+    // Keep process alive
+    process.on('SIGINT', () => {
+      engine.stop();
+      console.log();
+      console.log(chalk.dim('Watcher stopped.'));
+      process.exit(0);
+    });
+  });
+
+// ---------------------------------------------------------------------------
+// trellis import
+// ---------------------------------------------------------------------------
+
+program
+  .command('import')
+  .description('Import from an existing Git repository')
+  .requiredOption('--from <path>', 'Path to the Git repository to import from')
+  .option('-p, --path <path>', 'Target TrellisVCS repository path', '.')
+  .action(async (opts) => {
+    const from = resolve(opts.from);
+    const to = resolve(opts.path);
+
+    console.log(chalk.dim(`Importing from Git: ${from}`));
+    console.log(chalk.dim(`Target: ${to}`));
+    console.log();
+
+    try {
+      const result = await importFromGit({
+        from,
+        to,
+        onProgress: (p) => {
+          if (p.phase === 'reading') {
+            process.stdout.write(`\r  ${chalk.dim('Reading…')} ${p.message}`);
+          } else if (p.phase === 'importing') {
+            process.stdout.write(
+              `\r  ${chalk.dim('Importing…')} ${p.current}/${p.total} commits`,
+            );
+          } else {
+            process.stdout.write('\n');
+          }
+        },
+      });
+
+      console.log();
+      console.log(chalk.green('✓ Git import complete'));
+      console.log(`  ${chalk.dim('Commits:')}    ${result.commitsImported}`);
+      console.log(`  ${chalk.dim('Ops:')}        ${result.opsCreated}`);
+      console.log(`  ${chalk.dim('Files:')}      ${result.filesTracked}`);
+      console.log(
+        `  ${chalk.dim('Branches:')}   ${result.branches.join(', ')}`,
+      );
+      console.log(
+        `  ${chalk.dim('Duration:')}   ${(result.duration / 1000).toFixed(1)}s`,
+      );
+      console.log();
+      console.log(
+        chalk.dim(
+          'Run `trellis status` or `trellis log` to explore the imported history.',
+        ),
+      );
+    } catch (err: any) {
+      console.error(chalk.red(`\nImport failed: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis export
+// ---------------------------------------------------------------------------
+
+program
+  .command('export')
+  .description('Export milestones to a Git repository')
+  .requiredOption('--to <path>', 'Path to the target Git repository')
+  .option('-p, --path <path>', 'Source TrellisVCS repository path', '.')
+  .option('--author-name <name>', 'Author name for Git commits')
+  .option('--author-email <email>', 'Author email for Git commits')
+  .action(async (opts) => {
+    const from = resolve(opts.path);
+    const to = resolve(opts.to);
+
+    if (!TrellisVcsEngine.isRepo(from)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    console.log(chalk.dim(`Exporting from: ${from}`));
+    console.log(chalk.dim(`Target Git repo: ${to}`));
+    console.log();
+
+    try {
+      const result = await exportToGit({
+        from,
+        to,
+        authorName: opts.authorName,
+        authorEmail: opts.authorEmail,
+        onProgress: (p) => {
+          if (p.phase === 'preparing') {
+            console.log(`  ${chalk.dim(p.message)}`);
+          } else if (p.phase === 'exporting') {
+            process.stdout.write(
+              `\r  ${chalk.dim('Exporting…')} ${p.current}/${p.total} milestones`,
+            );
+          } else {
+            process.stdout.write('\n');
+          }
+        },
+      });
+
+      console.log();
+      console.log(chalk.green('✓ Git export complete'));
+      console.log(`  ${chalk.dim('Milestones:')} ${result.milestonesExported}`);
+      console.log(`  ${chalk.dim('Commits:')}    ${result.commitsCreated}`);
+      console.log(
+        `  ${chalk.dim('Duration:')}   ${(result.duration / 1000).toFixed(1)}s`,
+      );
+    } catch (err: any) {
+      console.error(chalk.red(`\nExport failed: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis branch
+// ---------------------------------------------------------------------------
+
+program
+  .command('branch')
+  .description('Manage branches')
+  .argument('[name]', 'Branch name to create or switch to')
+  .option('-d, --delete <name>', 'Delete a branch')
+  .option('-l, --list', 'List all branches')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (name, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    // Delete
+    if (opts.delete) {
+      try {
+        await engine.deleteBranch(opts.delete);
+        console.log(chalk.green(`✓ Deleted branch '${opts.delete}'`));
+      } catch (err: any) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Create or switch
+    if (name) {
+      const branches = engine.listBranches();
+      const exists = branches.find((b) => b.name === name);
+
+      if (exists) {
+        // Switch to existing branch
+        try {
+          engine.switchBranch(name);
+          console.log(chalk.green(`✓ Switched to branch '${name}'`));
+        } catch (err: any) {
+          console.error(chalk.red(err.message));
+          process.exit(1);
+        }
+      } else {
+        // Create new branch
+        try {
+          await engine.createBranch(name);
+          engine.switchBranch(name);
+          console.log(
+            chalk.green(`✓ Created and switched to branch '${name}'`),
+          );
+        } catch (err: any) {
+          console.error(chalk.red(err.message));
+          process.exit(1);
+        }
+      }
+      return;
+    }
+
+    // List (default)
+    const branches = engine.listBranches();
+    if (branches.length === 0) {
+      console.log(chalk.dim('No branches'));
+      return;
+    }
+
+    console.log(chalk.bold('Branches\n'));
+    for (const b of branches) {
+      const marker = b.isCurrent ? chalk.green('* ') : '  ';
+      const name = b.isCurrent ? chalk.green(b.name) : b.name;
+      const age = b.createdAt ? chalk.dim(formatRelativeTime(b.createdAt)) : '';
+      console.log(`${marker}${name} ${age}`);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis milestone
+// ---------------------------------------------------------------------------
+
+program
+  .command('milestone')
+  .description('Create or list milestones')
+  .argument('[action]', '"create" or "list" (default: list)')
+  .option('-m, --message <message>', 'Milestone message')
+  .option('--from <hash>', 'Start op hash for the milestone range')
+  .option('--to <hash>', 'End op hash for the milestone range')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (action, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    if (action === 'create') {
+      if (!opts.message) {
+        console.error(
+          chalk.red('Milestone message is required: --message "..."'),
+        );
+        process.exit(1);
+      }
+
+      try {
+        const op = await engine.createMilestone(opts.message, {
+          fromOpHash: opts.from,
+          toOpHash: opts.to,
+        });
+        console.log(chalk.green(`✓ Milestone created`));
+        console.log(`  ${chalk.dim('ID:')}      ${op.vcs?.milestoneId}`);
+        console.log(`  ${chalk.dim('Message:')} ${opts.message}`);
+        console.log(`  ${chalk.dim('Hash:')}    ${op.hash.slice(0, 32)}…`);
+      } catch (err: any) {
+        console.error(chalk.red(`Failed: ${err.message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // List (default)
+    const milestones = engine.listMilestones();
+    if (milestones.length === 0) {
+      console.log(chalk.dim('No milestones'));
+      return;
+    }
+
+    console.log(chalk.bold(`Milestones (${milestones.length})\n`));
+    for (const m of milestones) {
+      const age = m.createdAt ? formatRelativeTime(m.createdAt) : '';
+      console.log(
+        `  ${chalk.cyan('★')} ${chalk.bold(m.message ?? '(no message)')}`,
+      );
+      console.log(`    ${chalk.dim('ID:')} ${m.id}  ${chalk.dim(age)}`);
+      if (m.affectedFiles.length > 0) {
+        console.log(
+          `    ${chalk.dim('Files:')} ${m.affectedFiles.slice(0, 5).join(', ')}${m.affectedFiles.length > 5 ? ` +${m.affectedFiles.length - 5} more` : ''}`,
+        );
+      }
+      console.log();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis checkpoint
+// ---------------------------------------------------------------------------
+
+program
+  .command('checkpoint')
+  .description('Create or list checkpoints')
+  .argument('[action]', '"create" or "list" (default: list)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (action, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    if (action === 'create') {
+      try {
+        const op = await engine.createCheckpoint('manual');
+        console.log(chalk.green(`✓ Checkpoint created`));
+        console.log(`  ${chalk.dim('Hash:')}    ${op.hash.slice(0, 32)}…`);
+        console.log(`  ${chalk.dim('Trigger:')} manual`);
+      } catch (err: any) {
+        console.error(chalk.red(`Failed: ${err.message}`));
+        process.exit(1);
+      }
+      return;
+    }
+
+    // List (default)
+    const checkpoints = engine.listCheckpoints();
+    if (checkpoints.length === 0) {
+      console.log(chalk.dim('No checkpoints'));
+      return;
+    }
+
+    console.log(chalk.bold(`Checkpoints (${checkpoints.length})\n`));
+    for (const cp of checkpoints) {
+      const age = cp.createdAt ? formatRelativeTime(cp.createdAt) : '';
+      console.log(
+        `  ${chalk.dim('●')} ${cp.id.slice(0, 32)}  ${chalk.dim(cp.trigger ?? '')}  ${chalk.dim(age)}`,
+      );
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis diff
+// ---------------------------------------------------------------------------
+
+program
+  .command('diff')
+  .description('Show file-level diff between two points in history')
+  .argument('[from]', 'Starting op hash or milestone ID')
+  .argument('[to]', 'Ending op hash (default: current head)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--stat', 'Show only summary stats')
+  .action((from, to, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    let result;
+    if (from && to) {
+      result = engine.diffOps(from, to);
+    } else if (from) {
+      result = engine.diffFromOp(from);
+    } else {
+      // Diff from the first op to HEAD
+      const ops = engine.getOps();
+      if (ops.length < 2) {
+        console.log(chalk.dim('Not enough history to diff.'));
+        return;
+      }
+      result = engine.diffOps(ops[0].hash, ops[ops.length - 1].hash);
+    }
+
+    if (result.diffs.length === 0) {
+      console.log(chalk.dim('No differences.'));
+      return;
+    }
+
+    // Stats
+    const s = result.stats;
+    console.log(
+      `${chalk.green(`+${s.added} added`)}  ${chalk.yellow(`~${s.modified} modified`)}  ${chalk.red(`-${s.removed} removed`)}${s.renamed ? `  ${chalk.blue(`→${s.renamed} renamed`)}` : ''}`,
+    );
+    console.log();
+
+    if (opts.stat) return;
+
+    // Detailed output
+    for (const diff of result.diffs) {
+      switch (diff.kind) {
+        case 'fileAdded':
+          console.log(`${chalk.green('+ ' + diff.path)}`);
+          break;
+        case 'fileDeleted':
+          console.log(`${chalk.red('- ' + diff.path)}`);
+          break;
+        case 'fileRenamed':
+          console.log(`${chalk.blue(`→ ${diff.oldPath} → ${diff.path}`)}`);
+          break;
+        case 'fileModified':
+          console.log(`${chalk.yellow('~ ' + diff.path)}`);
+          if (diff.unifiedDiff) {
+            for (const line of diff.unifiedDiff.split('\n')) {
+              if (line.startsWith('+')) {
+                console.log(chalk.green(line));
+              } else if (line.startsWith('-')) {
+                console.log(chalk.red(line));
+              } else if (line.startsWith('@@')) {
+                console.log(chalk.cyan(line));
+              } else {
+                console.log(chalk.dim(line));
+              }
+            }
+          }
+          break;
+      }
+      console.log();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis merge
+// ---------------------------------------------------------------------------
+
+program
+  .command('merge')
+  .description('Merge a branch into the current branch')
+  .argument('<branch>', 'Source branch to merge')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--dry-run', 'Preview merge without applying changes')
+  .action((branch, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const result = engine.mergeBranch(branch);
+
+    if (result.clean) {
+      console.log(chalk.green('✓ Merge completed cleanly'));
+    } else {
+      console.log(
+        chalk.yellow(`⚠ Merge has ${result.conflicts.length} conflict(s)`),
+      );
+    }
+
+    const s = result.stats;
+    console.log(`  ${chalk.dim('Modified:')}   ${s.modified}`);
+    console.log(`  ${chalk.dim('Deleted:')}    ${s.deleted}`);
+    console.log(`  ${chalk.dim('Conflicted:')} ${s.conflicted}`);
+
+    if (result.conflicts.length > 0) {
+      console.log();
+      console.log(chalk.bold('Conflicts:'));
+      for (const c of result.conflicts) {
+        console.log(`  ${chalk.red('✗')} ${c.path} (${c.kind})`);
+      }
+    }
+
+    if (opts.dryRun) {
+      console.log();
+      console.log(chalk.dim('(dry run — no changes applied)'));
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis parse
+// ---------------------------------------------------------------------------
+
+program
+  .command('parse')
+  .description('Parse a file into AST-level semantic entities')
+  .argument('<file>', 'File to parse')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((file, opts) => {
+    const rootPath = resolve(opts.path);
+    const engine = new TrellisVcsEngine({ rootPath });
+    if (TrellisVcsEngine.isRepo(rootPath)) engine.open();
+
+    const { readFileSync } = require('fs');
+    const filePath = resolve(file);
+    const content = readFileSync(filePath, 'utf-8');
+    const result = engine.parseFile(content, file);
+
+    if (!result) {
+      console.log(chalk.dim(`No parser available for: ${file}`));
+      return;
+    }
+
+    console.log(chalk.bold(`Parse: ${file}\n`));
+    console.log(`  ${chalk.dim('Language:')}     ${result.language}`);
+    console.log(
+      `  ${chalk.dim('Declarations:')} ${result.declarations.length}`,
+    );
+    console.log(`  ${chalk.dim('Imports:')}      ${result.imports.length}`);
+    console.log(`  ${chalk.dim('Exports:')}      ${result.exports.length}`);
+
+    if (result.declarations.length > 0) {
+      console.log();
+      console.log(chalk.bold('Declarations:'));
+      for (const d of result.declarations) {
+        console.log(
+          `  ${chalk.cyan(d.kind.padEnd(14))} ${chalk.bold(d.name)}${d.children.length ? ` (${d.children.length} members)` : ''}`,
+        );
+        for (const child of d.children) {
+          console.log(`    ${chalk.dim(child.kind.padEnd(14))} ${child.name}`);
+        }
+      }
+    }
+
+    if (result.imports.length > 0) {
+      console.log();
+      console.log(chalk.bold('Imports:'));
+      for (const imp of result.imports) {
+        const specs =
+          imp.specifiers.length > 0 ? ` { ${imp.specifiers.join(', ')} }` : '';
+        console.log(
+          `  ${chalk.dim('from')} ${chalk.yellow(imp.source)}${specs}`,
+        );
+      }
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis sdiff (semantic diff)
+// ---------------------------------------------------------------------------
+
+program
+  .command('sdiff')
+  .description('Show semantic diff between two versions of a file')
+  .argument('<fileA>', 'Old version of the file')
+  .argument('<fileB>', 'New version of the file')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((fileA, fileB, opts) => {
+    const rootPath = resolve(opts.path);
+    const engine = new TrellisVcsEngine({ rootPath });
+    if (TrellisVcsEngine.isRepo(rootPath)) engine.open();
+
+    const { readFileSync } = require('fs');
+    const oldContent = readFileSync(resolve(fileA), 'utf-8');
+    const newContent = readFileSync(resolve(fileB), 'utf-8');
+    const patches = engine.semanticDiff(oldContent, newContent, fileA);
+
+    if (patches.length === 0) {
+      console.log(chalk.dim('No semantic differences.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Semantic diff: ${fileA} → ${fileB}\n`));
+    console.log(`  ${chalk.dim('Patches:')} ${patches.length}\n`);
+
+    for (const patch of patches) {
+      switch (patch.kind) {
+        case 'symbolAdd':
+          console.log(
+            `  ${chalk.green('+')} ${chalk.green(`${patch.entity.kind}: ${patch.entity.name}`)}`,
+          );
+          break;
+        case 'symbolRemove':
+          console.log(
+            `  ${chalk.red('-')} ${chalk.red(`${patch.entityName}`)} (removed)`,
+          );
+          break;
+        case 'symbolModify':
+          console.log(
+            `  ${chalk.yellow('~')} ${chalk.yellow(patch.entityName)} (modified)`,
+          );
+          break;
+        case 'symbolRename':
+          console.log(
+            `  ${chalk.blue('\u2192')} ${chalk.blue(`${patch.oldName} \u2192 ${patch.newName}`)} (renamed)`,
+          );
+          break;
+        case 'importAdd':
+          console.log(
+            `  ${chalk.green('+')} import from ${chalk.yellow(patch.source)}`,
+          );
+          break;
+        case 'importRemove':
+          console.log(
+            `  ${chalk.red('-')} import from ${chalk.yellow(patch.source)}`,
+          );
+          break;
+        case 'importModify':
+          console.log(
+            `  ${chalk.yellow('~')} import from ${chalk.yellow(patch.source)} (specifiers changed)`,
+          );
+          break;
+        case 'exportAdd':
+          console.log(`  ${chalk.green('+')} export ${chalk.bold(patch.name)}`);
+          break;
+        case 'exportRemove':
+          console.log(`  ${chalk.red('-')} export ${chalk.bold(patch.name)}`);
+          break;
+        case 'symbolMove':
+          console.log(
+            `  ${chalk.blue('\u2192')} ${chalk.blue(patch.entityName)} moved ${patch.oldFile} \u2192 ${patch.newFile}`,
+          );
+          break;
+      }
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis sync
+// ---------------------------------------------------------------------------
+
+program
+  .command('sync')
+  .description('Sync operations with another TrellisVCS repository')
+  .argument(
+    '[action]',
+    '"push", "pull", "status", or "reconcile" (default: status)',
+  )
+  .option('-p, --path <path>', 'Local repository path', '.')
+  .option('--remote <remote>', 'Remote repository path')
+  .action((action, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+    const ops = engine.getOps();
+
+    if (action === 'status' || !action) {
+      console.log(chalk.bold('Sync Status\n'));
+      console.log(`  ${chalk.dim('Local ops:')}  ${ops.length}`);
+      console.log(
+        `  ${chalk.dim('Head:')}       ${ops.length > 0 ? ops[ops.length - 1].hash.slice(0, 16) + '\u2026' : '(none)'}`,
+      );
+      console.log(`  ${chalk.dim('Branch:')}     ${engine.getCurrentBranch()}`);
+      return;
+    }
+
+    if (action === 'reconcile' && opts.remote) {
+      const remotePath = resolve(opts.remote);
+      if (!TrellisVcsEngine.isRepo(remotePath)) {
+        console.error(chalk.red(`Not a TrellisVCS repository: ${remotePath}`));
+        process.exit(1);
+      }
+
+      const remoteEngine = new TrellisVcsEngine({ rootPath: remotePath });
+      remoteEngine.open();
+      const remoteOps = remoteEngine.getOps();
+
+      const { reconcile } = require('../sync/reconciler.js');
+      const result = reconcile(ops, remoteOps);
+
+      console.log(chalk.bold('Reconcile Result\n'));
+      console.log(`  ${chalk.dim('Merged ops:')}    ${result.merged.length}`);
+      console.log(`  ${chalk.dim('Unique local:')} ${result.uniqueToA.length}`);
+      console.log(
+        `  ${chalk.dim('Unique remote:')} ${result.uniqueToB.length}`,
+      );
+      console.log(
+        `  ${chalk.dim('Fork point:')}   ${result.forkPoint?.slice(0, 16) ?? '(none)'}`,
+      );
+      console.log(
+        `  ${chalk.dim('Clean:')}        ${result.clean ? chalk.green('yes') : chalk.red('no')}`,
+      );
+
+      if (result.conflicts.length > 0) {
+        console.log();
+        console.log(chalk.bold('Conflicts:'));
+        for (const c of result.conflicts) {
+          console.log(`  ${chalk.red('\u2717')} ${c.filePath}: ${c.reason}`);
+        }
+      }
+      return;
+    }
+
+    console.log(
+      chalk.dim('Use --remote <path> with reconcile to compare repositories.'),
+    );
+    console.log(
+      chalk.dim('Full peer sync requires a transport layer (coming soon).'),
+    );
+  });
+
+// ---------------------------------------------------------------------------
+// trellis garden
+// ---------------------------------------------------------------------------
+
+program
+  .command('garden')
+  .description('Explore the Idea Garden — abandoned work clusters')
+  .argument(
+    '[action]',
+    '"list", "show <id>", "search", "revive <id>", or "stats" (default: list)',
+  )
+  .argument('[id]', 'Cluster ID (for show/revive)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('-f, --file <file>', 'Filter by file path')
+  .option('-k, --keyword <keyword>', 'Filter by keyword')
+  .option('-s, --status <status>', 'Filter by status (abandoned|draft|revived)')
+  .option('-n, --limit <n>', 'Max results', parseInt as any)
+  .action((action, id, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+    const garden = engine.garden();
+
+    if (action === 'stats') {
+      const s = garden.stats();
+      console.log(chalk.bold('Idea Garden Stats\n'));
+      console.log(`  ${chalk.dim('Total clusters:')} ${s.total}`);
+      console.log(`  ${chalk.dim('Abandoned:')}      ${s.abandoned}`);
+      console.log(`  ${chalk.dim('Draft:')}          ${s.draft}`);
+      console.log(`  ${chalk.dim('Revived:')}        ${s.revived}`);
+      console.log(`  ${chalk.dim('Total ops:')}      ${s.totalOps}`);
+      console.log(`  ${chalk.dim('Total files:')}    ${s.totalFiles}`);
+      return;
+    }
+
+    if (action === 'show') {
+      if (!id) {
+        console.error(chalk.red('Usage: trellis garden show <cluster-id>'));
+        process.exit(1);
+      }
+      const cluster = garden.getCluster(id);
+      if (!cluster) {
+        console.error(chalk.red(`Cluster not found: ${id}`));
+        process.exit(1);
+      }
+
+      console.log(chalk.bold(`Cluster: ${cluster.id}\n`));
+      console.log(
+        `  ${chalk.dim('Status:')}     ${formatClusterStatus(cluster.status)}`,
+      );
+      console.log(`  ${chalk.dim('Detected by:')} ${cluster.detectedBy}`);
+      console.log(`  ${chalk.dim('Created:')}    ${cluster.createdAt}`);
+      console.log(`  ${chalk.dim('Abandoned:')}  ${cluster.abandonedAt}`);
+      console.log(`  ${chalk.dim('Ops:')}        ${cluster.ops.length}`);
+      console.log(
+        `  ${chalk.dim('Files:')}      ${cluster.affectedFiles.join(', ')}`,
+      );
+      if (cluster.estimatedIntent) {
+        console.log(`  ${chalk.dim('Intent:')}     ${cluster.estimatedIntent}`);
+      }
+      console.log();
+      console.log(chalk.bold('Operations:'));
+      for (const op of cluster.ops.slice(0, 20)) {
+        console.log(
+          `  ${formatOpKind(op.kind)} ${chalk.dim(op.hash.slice(0, 12))} ${op.vcs?.filePath ?? ''}`,
+        );
+      }
+      if (cluster.ops.length > 20) {
+        console.log(chalk.dim(`  ... +${cluster.ops.length - 20} more`));
+      }
+      return;
+    }
+
+    if (action === 'revive') {
+      if (!id) {
+        console.error(chalk.red('Usage: trellis garden revive <cluster-id>'));
+        process.exit(1);
+      }
+      const ops = garden.revive(id);
+      if (!ops) {
+        console.error(chalk.red(`Cluster not found: ${id}`));
+        process.exit(1);
+      }
+      console.log(chalk.green(`\u2713 Cluster revived: ${id}`));
+      console.log(`  ${chalk.dim('Ops to replay:')} ${ops.length}`);
+      console.log(
+        `  ${chalk.dim('Files:')} ${[...new Set(ops.filter((o) => o.vcs?.filePath).map((o) => o.vcs!.filePath!))].join(', ')}`,
+      );
+      return;
+    }
+
+    if (action === 'search') {
+      const results = garden.search({
+        file: opts.file,
+        keyword: opts.keyword,
+        status: opts.status as any,
+        limit: opts.limit,
+      });
+
+      if (results.length === 0) {
+        console.log(chalk.dim('No matching clusters found.'));
+        return;
+      }
+
+      console.log(chalk.bold(`Search results (${results.length})\n`));
+      for (const c of results) {
+        printClusterSummary(c);
+      }
+      return;
+    }
+
+    // List (default)
+    const clusters = garden.search({
+      file: opts.file,
+      keyword: opts.keyword,
+      status: opts.status as any,
+      limit: opts.limit,
+    });
+
+    if (clusters.length === 0) {
+      console.log(chalk.dim('No idea clusters found. The garden is empty.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Idea Garden (${clusters.length} clusters)\n`));
+    for (const c of clusters) {
+      printClusterSummary(c);
+    }
+  });
+
+function formatClusterStatus(status: string): string {
+  switch (status) {
+    case 'abandoned':
+      return chalk.yellow('abandoned');
+    case 'draft':
+      return chalk.blue('draft');
+    case 'revived':
+      return chalk.green('revived');
+    default:
+      return chalk.dim(status);
+  }
+}
+
+function printClusterSummary(c: {
+  id: string;
+  status: string;
+  detectedBy: string;
+  ops: any[];
+  affectedFiles: string[];
+  createdAt: string;
+  abandonedAt: string;
+}): void {
+  console.log(
+    `  ${chalk.cyan('\u2740')} ${chalk.bold(c.id)}  ${formatClusterStatus(c.status)}  ${chalk.dim(c.detectedBy)}`,
+  );
+  console.log(
+    `    ${chalk.dim('Ops:')} ${c.ops.length}  ${chalk.dim('Files:')} ${c.affectedFiles.slice(0, 3).join(', ')}${c.affectedFiles.length > 3 ? ` +${c.affectedFiles.length - 3}` : ''}`,
+  );
+  console.log(
+    `    ${chalk.dim('Created:')} ${formatRelativeTime(c.createdAt)}  ${chalk.dim('Abandoned:')} ${formatRelativeTime(c.abandonedAt)}`,
+  );
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// trellis issue
+// ---------------------------------------------------------------------------
+
+function formatIssueStatus(status: string | undefined): string {
+  switch (status) {
+    case 'backlog':
+      return chalk.gray('backlog');
+    case 'queue':
+      return chalk.blue('queue');
+    case 'in_progress':
+      return chalk.yellow('in_progress');
+    case 'paused':
+      return chalk.magenta('paused');
+    case 'closed':
+      return chalk.green('closed');
+    default:
+      return chalk.dim(status ?? 'unknown');
+  }
+}
+
+function formatPriority(p: string | undefined): string {
+  switch (p) {
+    case 'critical':
+      return chalk.red('critical');
+    case 'high':
+      return chalk.yellow('high');
+    case 'medium':
+      return chalk.cyan('medium');
+    case 'low':
+      return chalk.dim('low');
+    default:
+      return chalk.dim(p ?? '');
+  }
+}
+
+function formatCriterionStatus(status: string | undefined): string {
+  switch (status) {
+    case 'passed':
+      return chalk.green('✓ passed');
+    case 'failed':
+      return chalk.red('✗ failed');
+    case 'pending':
+      return chalk.dim('○ pending');
+    default:
+      return chalk.dim(status ?? 'pending');
+  }
+}
+
+const issueCmd = program
+  .command('issue')
+  .description('Manage issues (task tracking)');
+
+issueCmd
+  .command('create')
+  .description('Create a new issue')
+  .requiredOption('-t, --title <title>', 'Issue title')
+  .option(
+    '-P, --priority <priority>',
+    'Priority: critical, high, medium, low',
+    'medium',
+  )
+  .option('-l, --labels <labels>', 'Comma-separated labels')
+  .option('--assignee <agentId>', 'Agent to assign')
+  .option('--parent <id>', 'Parent issue ID (for sub-tasks)')
+  .option('-d, --desc <description>', 'Short description')
+  .option(
+    '-S, --status <status>',
+    'Initial status: backlog (default) or queue',
+    'backlog',
+  )
+  .option(
+    '--ac <criteria...>',
+    'Acceptance criteria. Prefix with "test:" for test commands',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const labels = opts.labels
+      ? opts.labels.split(',').map((l: string) => l.trim())
+      : undefined;
+
+    const criteria = opts.ac
+      ? opts.ac.map((ac: string) => {
+          if (ac.startsWith('test:')) {
+            return { description: ac.slice(5), command: ac.slice(5) };
+          }
+          return { description: ac };
+        })
+      : undefined;
+
+    const op = await engine.createIssue(opts.title, {
+      priority: opts.priority,
+      labels,
+      assignee: opts.assignee,
+      parentId: opts.parent,
+      description: opts.desc,
+      status: opts.status,
+      criteria,
+    });
+
+    const issueId = op.vcs?.issueId;
+    console.log(chalk.green(`✓ Issue created: ${chalk.bold(issueId)}`));
+    console.log(`  ${chalk.dim('Title:')}    ${opts.title}`);
+    console.log(`  ${chalk.dim('Priority:')} ${formatPriority(opts.priority)}`);
+    if (labels) {
+      console.log(`  ${chalk.dim('Labels:')}   ${labels.join(', ')}`);
+    }
+    if (opts.parent) {
+      console.log(`  ${chalk.dim('Parent:')}   ${opts.parent}`);
+    }
+    if (criteria) {
+      console.log(
+        `  ${chalk.dim('Criteria:')} ${criteria.length} acceptance criteria`,
+      );
+    }
+  });
+
+issueCmd
+  .command('list')
+  .description('List issues')
+  .option(
+    '--status <status>',
+    'Filter by status: backlog, queue, in_progress, paused, closed',
+  )
+  .option('--label <label>', 'Filter by label')
+  .option('--assignee <agentId>', 'Filter by assignee')
+  .option('--parent <id>', 'Filter by parent issue')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const issues = engine.listIssues({
+      status: opts.status,
+      label: opts.label,
+      assignee: opts.assignee,
+      parentId: opts.parent,
+    });
+
+    if (issues.length === 0) {
+      console.log(chalk.dim('No issues found.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Issues (${issues.length})\n`));
+    for (const issue of issues) {
+      const labels =
+        issue.labels.length > 0
+          ? chalk.dim(` [${issue.labels.join(',')}]`)
+          : '';
+      const assignee = issue.assignee ? chalk.dim(` → ${issue.assignee}`) : '';
+      const parent = issue.parentId ? chalk.dim(` ← ${issue.parentId}`) : '';
+      const blocked = issue.isBlocked ? chalk.yellow(' 🔒 blocked') : '';
+      const criteria =
+        issue.criteria.length > 0
+          ? chalk.dim(
+              ` (${issue.criteria.filter((c) => c.status === 'passed').length}/${issue.criteria.length} AC)`,
+            )
+          : '';
+      console.log(
+        `  ${formatPriority(issue.priority)} ${chalk.bold(issue.id)} ${formatIssueStatus(issue.status)} ${issue.title ?? ''}${labels}${assignee}${parent}${blocked}${criteria}`,
+      );
+    }
+  });
+
+issueCmd
+  .command('show')
+  .description('Show issue details')
+  .argument('<id>', 'Issue ID (e.g. TRL-1)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const issue = engine.getIssue(id);
+    if (!issue) {
+      console.error(chalk.red(`Issue not found: ${id}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.bold(`${issue.id}: ${issue.title ?? '(untitled)'}\n`));
+    if (issue.description) {
+      console.log(`  ${chalk.dim(issue.description)}\n`);
+    }
+    console.log(
+      `  ${chalk.dim('Status:')}    ${formatIssueStatus(issue.status)}`,
+    );
+    console.log(
+      `  ${chalk.dim('Priority:')}  ${formatPriority(issue.priority)}`,
+    );
+    if (issue.labels.length > 0) {
+      console.log(`  ${chalk.dim('Labels:')}    ${issue.labels.join(', ')}`);
+    }
+    if (issue.assignee) {
+      console.log(`  ${chalk.dim('Assignee:')}  ${issue.assignee}`);
+    }
+    if (issue.parentId) {
+      console.log(`  ${chalk.dim('Parent:')}    ${issue.parentId}`);
+    }
+    if (issue.branchName) {
+      console.log(`  ${chalk.dim('Branch:')}    ${issue.branchName}`);
+    }
+    if (issue.blockedBy.length > 0) {
+      console.log(
+        `  ${chalk.dim('Blocked by:')} ${issue.blockedBy.map((b) => chalk.yellow(b)).join(', ')}`,
+      );
+    }
+    if (issue.blocking.length > 0) {
+      console.log(
+        `  ${chalk.dim('Blocking:')}  ${issue.blocking.map((b) => chalk.cyan(b)).join(', ')}`,
+      );
+    }
+    if (issue.createdAt) {
+      console.log(
+        `  ${chalk.dim('Created:')}   ${formatRelativeTime(issue.createdAt)}`,
+      );
+    }
+    if (issue.startedAt) {
+      console.log(
+        `  ${chalk.dim('Started:')}   ${formatRelativeTime(issue.startedAt)}`,
+      );
+    }
+    if (issue.closedAt) {
+      console.log(
+        `  ${chalk.dim('Closed:')}    ${formatRelativeTime(issue.closedAt)}`,
+      );
+    }
+
+    if (issue.criteria.length > 0) {
+      console.log(`\n  ${chalk.bold('Acceptance Criteria:')}`);
+      for (const c of issue.criteria) {
+        const desc = c.description ?? c.id;
+        const cmd = c.command ? chalk.dim(` (${c.command})`) : '';
+        console.log(`    ${formatCriterionStatus(c.status)} ${desc}${cmd}`);
+      }
+    }
+  });
+
+issueCmd
+  .command('start')
+  .description('Start working on an issue (creates branch, auto-assigns)')
+  .argument('<id>', 'Issue ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const op = await engine.startIssue(id);
+    const issue = engine.getIssue(id);
+    console.log(chalk.green(`✓ Started issue ${chalk.bold(id)}`));
+    if (issue?.branchName) {
+      console.log(`  ${chalk.dim('Branch:')}   ${issue.branchName}`);
+    }
+    if (issue?.assignee) {
+      console.log(`  ${chalk.dim('Assignee:')} ${issue.assignee}`);
+    }
+  });
+
+issueCmd
+  .command('pause')
+  .description('Pause an in-progress issue (switches to default branch)')
+  .argument('<id>', 'Issue ID')
+  .requiredOption(
+    '-n, --note <note>',
+    'Why paused and what must happen before resuming',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.pauseIssue(id, opts.note);
+    console.log(chalk.yellow(`⏸ Paused issue ${chalk.bold(id)}`));
+    console.log(`  ${chalk.dim('Note:')} ${opts.note}`);
+    console.log(`  ${chalk.dim('Switched to:')} ${engine.getCurrentBranch()}`);
+  });
+
+issueCmd
+  .command('resume')
+  .description('Resume a paused issue (switches to issue branch)')
+  .argument('<id>', 'Issue ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.resumeIssue(id);
+    const issue = engine.getIssue(id);
+    console.log(chalk.green(`▶ Resumed issue ${chalk.bold(id)}`));
+    if (issue?.branchName) {
+      console.log(`  ${chalk.dim('Branch:')} ${issue.branchName}`);
+    }
+  });
+
+issueCmd
+  .command('triage')
+  .description('Move a backlog issue to queue (ready to start)')
+  .argument('<id>', 'Issue ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.triageIssue(id);
+    console.log(chalk.green(`✓ Triaged ${chalk.bold(id)} → queue`));
+  });
+
+issueCmd
+  .command('update')
+  .description('Update issue metadata')
+  .argument('<id>', 'Issue ID')
+  .option('--title <title>', 'New title')
+  .option('-d, --desc <description>', 'Short description')
+  .option(
+    '--status <status>',
+    'New status: backlog, queue, in_progress, paused, closed',
+  )
+  .option('-P, --priority <priority>', 'Priority: critical, high, medium, low')
+  .option('-l, --labels <labels>', 'Comma-separated labels')
+  .option('--assignee <agentId>', 'Agent to assign')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const updates: Record<string, any> = {};
+    if (opts.title !== undefined) updates.title = opts.title;
+    if (opts.desc !== undefined) updates.description = opts.desc;
+    if (opts.status !== undefined) updates.status = opts.status;
+    if (opts.priority !== undefined) updates.priority = opts.priority;
+    if (opts.labels !== undefined) {
+      updates.labels = opts.labels.split(',').map((l: string) => l.trim());
+    }
+    if (opts.assignee !== undefined) updates.assignee = opts.assignee;
+
+    await engine.updateIssue(id, updates);
+    console.log(chalk.green(`✓ Updated ${chalk.bold(id)}`));
+  });
+
+issueCmd
+  .command('describe')
+  .description('Set an issue description')
+  .argument('<id>', 'Issue ID')
+  .argument('<description>', 'Short description text')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, description, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.updateIssue(id, { description });
+    console.log(chalk.green(`✓ Description set for ${chalk.bold(id)}`));
+  });
+
+issueCmd
+  .command('assign')
+  .description('Assign an issue to an agent')
+  .argument('<id>', 'Issue ID')
+  .requiredOption('--to <agentId>', 'Agent ID to assign')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.assignIssue(id, opts.to);
+    console.log(chalk.green(`✓ Assigned ${chalk.bold(id)} → ${opts.to}`));
+  });
+
+issueCmd
+  .command('ac')
+  .description('Add acceptance criterion to an issue')
+  .argument('<id>', 'Issue ID')
+  .argument('<description>', 'Criterion description')
+  .option('--test <command>', 'Shell command to validate (exit 0 = pass)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, description, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.addCriterion(id, description, opts.test);
+    const cmdNote = opts.test ? chalk.dim(` (test: ${opts.test})`) : '';
+    console.log(
+      chalk.green(
+        `✓ Added criterion to ${chalk.bold(id)}: ${description}${cmdNote}`,
+      ),
+    );
+  });
+
+issueCmd
+  .command('ac-pass')
+  .description('Manually mark an acceptance criterion as passed')
+  .argument('<id>', 'Issue ID')
+  .argument('<index>', 'Criterion number (1-based)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, index, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.setCriterionStatus(id, parseInt(index, 10), 'passed');
+    console.log(
+      chalk.green(
+        `✓ Criterion #${index} on ${chalk.bold(id)} marked as passed`,
+      ),
+    );
+  });
+
+issueCmd
+  .command('ac-fail')
+  .description('Manually mark an acceptance criterion as failed')
+  .argument('<id>', 'Issue ID')
+  .argument('<index>', 'Criterion number (1-based)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, index, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.setCriterionStatus(id, parseInt(index, 10), 'failed');
+    console.log(
+      chalk.red(`✗ Criterion #${index} on ${chalk.bold(id)} marked as failed`),
+    );
+  });
+
+issueCmd
+  .command('check')
+  .description('Run acceptance criteria for an issue')
+  .argument('<id>', 'Issue ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    console.log(chalk.bold(`Running criteria for ${id}...\n`));
+    const results = await engine.runCriteria(id);
+
+    if (results.length === 0) {
+      console.log(chalk.dim('No acceptance criteria defined.'));
+      return;
+    }
+
+    for (const r of results) {
+      const desc = r.description ?? r.id;
+      const statusStr =
+        r.status === 'passed'
+          ? chalk.green('✓ PASSED')
+          : r.status === 'failed'
+            ? chalk.red('✗ FAILED')
+            : chalk.dim('○ SKIPPED');
+      console.log(`  ${statusStr}  ${desc}`);
+      if (r.command) {
+        console.log(`    ${chalk.dim('$')} ${r.command}`);
+      }
+      if (r.output && r.status === 'failed') {
+        const lines = r.output.split('\n').slice(0, 5);
+        for (const line of lines) {
+          console.log(`    ${chalk.dim(line)}`);
+        }
+      }
+    }
+
+    const passed = results.filter((r) => r.status === 'passed').length;
+    const total = results.length;
+    console.log();
+    if (passed === total) {
+      console.log(
+        chalk.green(
+          `All ${total} criteria passed. Close with: trellis issue close ${id} --confirm`,
+        ),
+      );
+    } else {
+      console.log(chalk.yellow(`${passed}/${total} criteria passing.`));
+    }
+  });
+
+issueCmd
+  .command('close')
+  .description('Close an issue (requires all criteria pass + --confirm)')
+  .argument('<id>', 'Issue ID')
+  .option('--confirm', 'Confirm closure after criteria pass')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    try {
+      const result = await engine.closeIssue(id, { confirm: opts.confirm });
+
+      if (!result.op) {
+        // Criteria passed but no --confirm
+        console.log(chalk.bold(`Criteria status for ${id}:\n`));
+        for (const r of result.criteriaResults) {
+          console.log(
+            `  ${formatCriterionStatus(r.status)}  ${r.description ?? r.id}`,
+          );
+        }
+        console.log();
+        console.log(
+          chalk.yellow(
+            `All criteria pass. Re-run with --confirm to close: trellis issue close ${id} --confirm`,
+          ),
+        );
+        return;
+      }
+
+      console.log(chalk.green(`✓ Issue ${chalk.bold(id)} closed`));
+    } catch (err: any) {
+      console.error(chalk.red(err.message));
+      process.exit(1);
+    }
+  });
+
+issueCmd
+  .command('reopen')
+  .description('Reopen a closed issue')
+  .argument('<id>', 'Issue ID')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.reopenIssue(id);
+    console.log(chalk.green(`✓ Issue ${chalk.bold(id)} reopened`));
+  });
+
+issueCmd
+  .command('block')
+  .description('Mark an issue as blocked by another issue')
+  .argument('<id>', 'Issue ID to block')
+  .argument('<blockedBy>', 'Issue ID that blocks it')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, blockedBy, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.blockIssue(id, blockedBy);
+    console.log(
+      chalk.yellow(
+        `🔒 ${chalk.bold(id)} is now blocked by ${chalk.bold(blockedBy)}`,
+      ),
+    );
+  });
+
+issueCmd
+  .command('unblock')
+  .description('Remove a blocking relationship')
+  .argument('<id>', 'Blocked issue ID')
+  .argument('<blockedBy>', 'Blocking issue ID to remove')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (id, blockedBy, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    await engine.unblockIssue(id, blockedBy);
+    console.log(
+      chalk.green(
+        `🔓 ${chalk.bold(id)} is no longer blocked by ${chalk.bold(blockedBy)}`,
+      ),
+    );
+  });
+
+issueCmd
+  .command('active')
+  .description('Show all active (in-progress) issues')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const active = engine.getActiveIssues();
+    if (active.length === 0) {
+      console.log(chalk.dim('No active issues.'));
+      return;
+    }
+
+    console.log(chalk.bold(`Active Issues (${active.length})\n`));
+    for (const issue of active) {
+      const branch = issue.branchName
+        ? chalk.dim(` on ${issue.branchName}`)
+        : '';
+      const assignee = issue.assignee ? chalk.dim(` → ${issue.assignee}`) : '';
+      console.log(
+        `  ${formatPriority(issue.priority)} ${chalk.bold(issue.id)} ${issue.title ?? ''}${branch}${assignee}`,
+      );
+    }
+  });
+
+issueCmd
+  .command('readiness')
+  .description(
+    'Check if all issues are complete (no queue, paused, or in-progress)',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const result = engine.checkCompletionReadiness();
+    console.log(result.summary);
+
+    if (!result.ready) {
+      process.exit(1);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis decision
+// ---------------------------------------------------------------------------
+
+const decisionCmd = program
+  .command('decision')
+  .description('Manage decision traces');
+
+decisionCmd
+  .command('list')
+  .description('List decision traces')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option(
+    '-t, --tool <pattern>',
+    'Filter by tool name pattern (e.g. "trellis_issue_*")',
+  )
+  .option('-e, --entity <id>', 'Filter by related entity ID')
+  .option('-n, --limit <n>', 'Max results', '20')
+  .action((opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const decisions = engine.queryDecisions({
+      toolPattern: opts.tool,
+      entityId: opts.entity,
+      limit: parseInt(opts.limit, 10),
+    });
+
+    if (decisions.length === 0) {
+      console.log(chalk.dim('No decision traces found.'));
+      return;
+    }
+
+    for (const d of decisions) {
+      const ts = d.createdAt ? chalk.dim(d.createdAt) : '';
+      console.log(`${chalk.cyan(d.id)}  ${chalk.white(d.toolName)}  ${ts}`);
+      if (d.rationale) {
+        console.log(`  ${chalk.dim('→')} ${d.rationale}`);
+      }
+    }
+  });
+
+decisionCmd
+  .command('show')
+  .description('Show full details of a decision trace')
+  .argument('<id>', 'Decision ID (e.g. DEC-1)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((id, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const d = engine.getDecision(id);
+    if (!d) {
+      console.error(chalk.red(`Decision ${id} not found.`));
+      process.exit(1);
+    }
+
+    console.log(`${chalk.bold('ID:')}         ${d.id}`);
+    console.log(`${chalk.bold('Tool:')}       ${d.toolName}`);
+    console.log(`${chalk.bold('Created:')}    ${d.createdAt ?? 'unknown'}`);
+    console.log(`${chalk.bold('Agent:')}      ${d.createdBy ?? 'unknown'}`);
+    if (d.context) console.log(`${chalk.bold('Context:')}    ${d.context}`);
+    if (d.rationale) console.log(`${chalk.bold('Rationale:')}  ${d.rationale}`);
+    if (d.alternatives && d.alternatives.length > 0) {
+      console.log(
+        `${chalk.bold('Alternatives:')} ${d.alternatives.join(', ')}`,
+      );
+    }
+    if (d.outputSummary) {
+      console.log(`${chalk.bold('Output:')}    ${d.outputSummary}`);
+    }
+    if (d.relatedEntities.length > 0) {
+      console.log(
+        `${chalk.bold('Related:')}   ${d.relatedEntities.join(', ')}`,
+      );
+    }
+  });
+
+decisionCmd
+  .command('chain')
+  .description('Trace all decisions that affected a given entity')
+  .argument(
+    '<entityId>',
+    'Entity ID (e.g. "issue:TRL-5", "file:src/engine.ts")',
+  )
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action((entityId, opts) => {
+    const rootPath = resolve(opts.path);
+    requireRepo(rootPath);
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const chain = engine.getDecisionChain(entityId);
+    if (chain.length === 0) {
+      console.log(chalk.dim(`No decision traces found for ${entityId}.`));
+      return;
+    }
+
+    console.log(
+      chalk.bold(`Decision chain for ${entityId} (${chain.length} decisions):`),
+    );
+    for (const d of chain) {
+      const ts = d.createdAt ? chalk.dim(d.createdAt) : '';
+      console.log(`  ${chalk.cyan(d.id)}  ${chalk.white(d.toolName)}  ${ts}`);
+      if (d.rationale) {
+        console.log(`    ${chalk.dim('→')} ${d.rationale}`);
+      }
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis identity
+// ---------------------------------------------------------------------------
+
+program
+  .command('identity')
+  .description('Manage local identity (Ed25519 key pair)')
+  .argument('[action]', '"init" or "show" (default: show)')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('--name <name>', 'Display name for new identity')
+  .option('--email <email>', 'Email for new identity')
+  .action((action, opts) => {
+    const rootPath = resolve(opts.path);
+    const trellisDir = join(rootPath, '.trellis');
+
+    if (action === 'init') {
+      if (hasIdentity(trellisDir)) {
+        console.error(
+          chalk.yellow(
+            'Identity already exists. Use `trellis identity` to view it.',
+          ),
+        );
+        process.exit(1);
+      }
+
+      const name = opts.name ?? 'Anonymous';
+      const email = opts.email;
+
+      const identity = createIdentity({ displayName: name, email });
+      saveIdentity(trellisDir, identity);
+
+      console.log(chalk.green('✓ Identity created'));
+      console.log(`  ${chalk.dim('Name:')}  ${identity.displayName}`);
+      if (identity.email) {
+        console.log(`  ${chalk.dim('Email:')} ${identity.email}`);
+      }
+      console.log(`  ${chalk.dim('DID:')}   ${identity.did}`);
+      console.log(`  ${chalk.dim('ID:')}    ${identity.entityId}`);
+      return;
+    }
+
+    // Show (default)
+    const identity = loadIdentity(trellisDir);
+    if (!identity) {
+      console.log(
+        chalk.dim(
+          'No identity configured. Run `trellis identity init --name "Your Name"`.',
+        ),
+      );
+      return;
+    }
+
+    const pub = toPublicIdentity(identity);
+    console.log(chalk.bold('Identity\n'));
+    console.log(`  ${chalk.dim('Name:')}       ${pub.displayName}`);
+    if (pub.email) {
+      console.log(`  ${chalk.dim('Email:')}      ${pub.email}`);
+    }
+    console.log(`  ${chalk.dim('DID:')}        ${pub.did}`);
+    console.log(`  ${chalk.dim('Entity ID:')}  ${pub.entityId}`);
+    console.log(`  ${chalk.dim('Public Key:')} ${pub.publicKey.slice(0, 32)}…`);
+    console.log(`  ${chalk.dim('Created:')}    ${pub.createdAt}`);
+  });
+
+// ---------------------------------------------------------------------------
+// trellis refs
+// ---------------------------------------------------------------------------
+
+program
+  .command('refs')
+  .description('List wiki-link references in files or find backlinks')
+  .argument('[file]', 'File to list outgoing refs for')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option(
+    '--backlinks <entity>',
+    'Show all files referencing an entity (e.g. TRL-5)',
+  )
+  .option('--broken', 'List all broken and stale references')
+  .option('--stats', 'Show reference index statistics')
+  .action((file, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const { readFileSync } = require('fs');
+    const {
+      parseFileRefs,
+      buildRefIndex,
+      getOutgoingRefs,
+      getBacklinks,
+      getIndexStats,
+    } = require('../links/index.js');
+    const {
+      resolveRef,
+      resolveRefs,
+      createResolverContext,
+    } = require('../links/index.js');
+    const { StaleRefRegistry, getDiagnostics } = require('../links/index.js');
+
+    // Build resolver context from engine
+    const resolverCtx = createResolverContext(engine);
+
+    // Scan all tracked .md files and source files to build the index
+    const trackedFiles = engine.trackedFiles();
+    const fileContents: Array<{ path: string; content: string }> = [];
+    for (const f of trackedFiles) {
+      try {
+        const absPath = join(rootPath, f.path);
+        const content = readFileSync(absPath, 'utf-8');
+        fileContents.push({ path: f.path, content });
+      } catch {
+        // File may not exist on disk
+      }
+    }
+
+    const index = buildRefIndex(fileContents, resolverCtx);
+
+    // --stats: show index statistics
+    if (opts.stats) {
+      const stats = getIndexStats(index);
+      console.log(chalk.bold('Reference Index Stats\n'));
+      console.log(`  ${chalk.dim('Files with refs:')} ${stats.totalFiles}`);
+      console.log(`  ${chalk.dim('Total refs:')}      ${stats.totalRefs}`);
+      console.log(`  ${chalk.dim('Unique entities:')} ${stats.totalEntities}`);
+      return;
+    }
+
+    // --backlinks <entity>: show all sources referencing an entity
+    if (opts.backlinks) {
+      const entity = opts.backlinks;
+      // Try common entity ID formats
+      const candidates = [
+        `issue:${entity}`,
+        `file:${entity}`,
+        `symbol:${entity}`,
+        `identity:${entity}`,
+        `milestone:${entity}`,
+        `decision:${entity}`,
+        entity, // raw entity ID
+      ];
+
+      let found = false;
+      for (const eid of candidates) {
+        const sources = getBacklinks(index, eid);
+        if (sources.length > 0) {
+          console.log(
+            chalk.bold(
+              `Backlinks for ${chalk.cyan(eid)} (${sources.length})\n`,
+            ),
+          );
+          for (const s of sources) {
+            console.log(
+              `  ${chalk.dim(s.filePath)}:${s.line}  ${chalk.dim(`(${s.context})`)}`,
+            );
+          }
+          found = true;
+          break;
+        }
+      }
+
+      if (!found) {
+        console.log(chalk.dim(`No references found for: ${entity}`));
+      }
+      return;
+    }
+
+    // --broken: list all broken and stale refs
+    if (opts.broken) {
+      const registry = new StaleRefRegistry();
+      const resolvedIds = new Set<string>();
+
+      // Resolve all refs to build the resolved set
+      for (const [, refs] of index.outgoing) {
+        for (const ref of refs) {
+          const resolved = resolveRef(ref, resolverCtx);
+          if (resolved.state === 'resolved' && resolved.entityId) {
+            resolvedIds.add(resolved.entityId);
+          }
+        }
+      }
+
+      const diags = getDiagnostics(index, registry, resolvedIds);
+
+      if (diags.length === 0) {
+        console.log(chalk.green('✓ No broken or stale references found.'));
+        return;
+      }
+
+      const stale = diags.filter((d: any) => d.state === 'stale');
+      const broken = diags.filter((d: any) => d.state === 'broken');
+
+      if (broken.length > 0) {
+        console.log(
+          chalk.bold(chalk.red(`Broken references (${broken.length})\n`)),
+        );
+        for (const d of broken) {
+          console.log(
+            `  ${chalk.red('✗')} ${d.source.filePath}:${d.source.line}  ${d.message}`,
+          );
+        }
+        console.log();
+      }
+
+      if (stale.length > 0) {
+        console.log(
+          chalk.bold(chalk.yellow(`Stale references (${stale.length})\n`)),
+        );
+        for (const d of stale) {
+          console.log(
+            `  ${chalk.yellow('⚠')} ${d.source.filePath}:${d.source.line}  ${d.message}`,
+          );
+        }
+      }
+      return;
+    }
+
+    // Default: list outgoing refs for a specific file (or all files)
+    if (file) {
+      const refs = getOutgoingRefs(index, file);
+      if (refs.length === 0) {
+        console.log(chalk.dim(`No [[...]] references found in: ${file}`));
+        return;
+      }
+
+      console.log(
+        chalk.bold(`References in ${chalk.cyan(file)} (${refs.length})\n`),
+      );
+      for (const ref of refs) {
+        const resolved = resolveRef(ref, resolverCtx);
+        const stateIcon =
+          resolved.state === 'resolved'
+            ? chalk.green('✓')
+            : resolved.state === 'stale'
+              ? chalk.yellow('⚠')
+              : chalk.red('✗');
+        const display = ref.alias ?? ref.raw;
+        const entityId = resolved.entityId ?? chalk.dim('unresolved');
+        console.log(
+          `  ${stateIcon} [[${display}]]  → ${entityId}  ${chalk.dim(`L${ref.source.line}`)}`,
+        );
+      }
+    } else {
+      // List all files with refs
+      const stats = getIndexStats(index);
+      if (stats.totalRefs === 0) {
+        console.log(
+          chalk.dim('No [[...]] references found in any tracked files.'),
+        );
+        return;
+      }
+
+      console.log(
+        chalk.bold(
+          `References (${stats.totalRefs} across ${stats.totalFiles} files)\n`,
+        ),
+      );
+      for (const [filePath, refs] of index.outgoing) {
+        console.log(`  ${chalk.cyan(filePath)} (${refs.length} refs)`);
+        for (const ref of refs) {
+          const resolved = resolveRef(ref, resolverCtx);
+          const stateIcon =
+            resolved.state === 'resolved'
+              ? chalk.green('✓')
+              : resolved.state === 'stale'
+                ? chalk.yellow('⚠')
+                : chalk.red('✗');
+          console.log(
+            `    ${stateIcon} [[${ref.raw}]]  ${chalk.dim(`L${ref.source.line}`)}`,
+          );
+        }
+      }
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis search
+// ---------------------------------------------------------------------------
+
+program
+  .command('search')
+  .description('Semantic search across all embedded content')
+  .argument('<query>', 'Natural language search query')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .option('-l, --limit <n>', 'Max results', '10')
+  .option(
+    '-t, --type <types>',
+    'Filter by chunk type(s), comma-separated (issue_title,issue_desc,milestone_msg,markdown,code_entity,doc_comment,summary_md)',
+  )
+  .action(async (query, opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const { EmbeddingManager } = require('../embeddings/index.js');
+
+    const dbPath = join(rootPath, '.trellis', 'embeddings.db');
+    const manager = new EmbeddingManager(dbPath);
+
+    try {
+      const searchOpts: any = {
+        limit: parseInt(opts.limit, 10) || 10,
+      };
+      if (opts.type) {
+        searchOpts.types = opts.type.split(',').map((t: string) => t.trim());
+      }
+
+      const results = await manager.search(query, searchOpts);
+
+      if (results.length === 0) {
+        console.log(
+          chalk.dim(
+            'No results found. Try `trellis reindex` to build the index.',
+          ),
+        );
+        return;
+      }
+
+      console.log(
+        chalk.bold(
+          `Search results for ${chalk.cyan(`"${query}"`)} (${results.length})\n`,
+        ),
+      );
+
+      for (const r of results) {
+        const score = (r.score * 100).toFixed(1);
+        const typeTag = chalk.dim(`[${r.chunk.chunkType}]`);
+        const filePart = r.chunk.filePath
+          ? chalk.dim(` ${r.chunk.filePath}`)
+          : '';
+        const preview = r.chunk.content.slice(0, 120).replace(/\n/g, ' ');
+
+        console.log(`  ${chalk.green(`${score}%`)} ${typeTag}${filePart}`);
+        console.log(`    ${chalk.dim(preview)}`);
+        console.log();
+      }
+    } finally {
+      manager.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// trellis reindex
+// ---------------------------------------------------------------------------
+
+program
+  .command('reindex')
+  .description('Rebuild the semantic embedding index')
+  .option('-p, --path <path>', 'Repository path', '.')
+  .action(async (opts) => {
+    const rootPath = resolve(opts.path);
+    if (!TrellisVcsEngine.isRepo(rootPath)) {
+      console.error(
+        chalk.red('Not a TrellisVCS repository. Run `trellis init` first.'),
+      );
+      process.exit(1);
+    }
+
+    const engine = new TrellisVcsEngine({ rootPath });
+    engine.open();
+
+    const { EmbeddingManager } = require('../embeddings/index.js');
+
+    const dbPath = join(rootPath, '.trellis', 'embeddings.db');
+    const manager = new EmbeddingManager(dbPath);
+
+    try {
+      console.log(chalk.dim('Loading embedding model…'));
+      const result = await manager.reindex(engine);
+      console.log(chalk.green(`✓ Indexed ${result.chunks} chunks`));
+
+      const stats = manager.stats();
+      console.log(chalk.dim(`  Types: ${JSON.stringify(stats.byType)}`));
+    } finally {
+      manager.close();
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatOpKind(kind: string): string {
+  const kindMap: Record<string, string> = {
+    'vcs:fileAdd': chalk.green('+add'),
+    'vcs:fileModify': chalk.yellow('~mod'),
+    'vcs:fileDelete': chalk.red('-del'),
+    'vcs:fileRename': chalk.blue('→ren'),
+    'vcs:branchCreate': chalk.magenta('⊕branch'),
+    'vcs:branchAdvance': chalk.magenta('→branch'),
+    'vcs:milestoneCreate': chalk.cyan('★milestone'),
+    'vcs:checkpointCreate': chalk.dim('●checkpoint'),
+  };
+  return kindMap[kind] ?? chalk.dim(kind);
+}
+
+function formatRelativeTime(iso: string): string {
+  const now = Date.now();
+  const then = new Date(iso).getTime();
+  const diff = now - then;
+
+  if (diff < 60_000) return 'just now';
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
+  return `${Math.floor(diff / 86_400_000)}d ago`;
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+program.parse();