apero-kit-cli 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apero-kit-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI tool to scaffold AI agent projects with pre-configured kits (Claude, OpenCode, Codex)",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -15,30 +15,64 @@ import {
   promptCommands,
   promptIncludeRouter,
   promptIncludeHooks,
-  promptConfirm
+  promptConfirm,
+  promptExistingTarget
 } from '../utils/prompts.js';
 
 export async function initCommand(projectName, options) {
   console.log('');
 
-  // 1. Get project name
-  if (!projectName) {
-    projectName = await promptProjectName();
+  // 1. Get project name (support current directory with "." or empty)
+  let projectDir;
+  let isCurrentDir = false;
+
+  if (!projectName || projectName === '.') {
+    // Use current directory
+    projectDir = process.cwd();
+    projectName = '.';
+    isCurrentDir = true;
+    console.log(chalk.gray(`Initializing in current directory: ${projectDir}`));
+  } else {
+    projectDir = resolve(process.cwd(), projectName);
   }
 
-  const projectDir = resolve(process.cwd(), projectName);
+  // 2. Get target early to check existing
+  let target = options.target || 'claude';
+  if (!TARGETS[target]) {
+    console.log(chalk.yellow(`Unknown target "${target}", using "claude"`));
+    target = 'claude';
+  }
+
+  const targetDir = getTargetDir(projectDir, target);
+  let existingAction = null;
+
+  // Check if target directory (.claude, .opencode, etc.) already exists
+  if (fs.existsSync(targetDir) && !options.force) {
+    if (!process.stdin.isTTY) {
+      // Non-interactive mode - skip
+      console.log(chalk.yellow(`${TARGETS[target]} already exists. Use --force to override.`));
+      return;
+    }
+
+    existingAction = await promptExistingTarget(TARGETS[target]);
+
+    if (existingAction === 'skip') {
+      console.log(chalk.yellow('Skipped. No changes made.'));
+      return;
+    }
+  }
 
-  // Check if directory exists
-  if (fs.existsSync(projectDir) && !options.force) {
+  // For new project directory, check if it exists
+  if (!isCurrentDir && fs.existsSync(projectDir) && !options.force) {
     const files = fs.readdirSync(projectDir);
-    if (files.length > 0) {
+    if (files.length > 0 && !existingAction) {
       console.log(chalk.red(`Directory "${projectName}" already exists and is not empty.`));
       console.log(chalk.gray('Use --force to overwrite.'));
       return;
     }
   }
 
-  // 2. Resolve source
+  // 3. Resolve source
   const source = resolveSource(options.source);
   if (source.error) {
     console.log(chalk.red(`Error: ${source.error}`));
@@ -47,20 +81,18 @@ export async function initCommand(projectName, options) {
 
   console.log(chalk.gray(`Source: ${source.path}`));
 
-  // 3. Get kit
+  // 4. Get kit
   let kitName = options.kit;
-  if (!kitName) {
+  if (!kitName && !options.force) {
     kitName = await promptKit();
+  } else if (!kitName) {
+    kitName = 'engineer'; // Default kit for --force mode
   }
 
-  // 4. Get target
-  let target = options.target || 'claude';
-  if (!TARGETS[target]) {
-    console.log(chalk.yellow(`Unknown target "${target}", using "claude"`));
-    target = 'claude';
-  }
+  // 5. Set merge mode based on existing action
+  const mergeMode = existingAction === 'merge';
 
-  // 5. Prepare what to install
+  // 6. Prepare what to install
   let toInstall = {
     agents: [],
     commands: [],
@@ -134,56 +166,56 @@ export async function initCommand(projectName, options) {
     await fs.ensureDir(targetDir);
 
     // Copy agents
-    spinner.text = 'Copying agents...';
+    spinner.text = mergeMode ? 'Merging agents...' : 'Copying agents...';
     if (toInstall.agents === 'all') {
-      await copyAllOfType('agents', source.claudeDir, targetDir);
+      await copyAllOfType('agents', source.claudeDir, targetDir, mergeMode);
     } else if (toInstall.agents.length > 0) {
-      await copyItems(toInstall.agents, 'agents', source.claudeDir, targetDir);
+      await copyItems(toInstall.agents, 'agents', source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy skills
-    spinner.text = 'Copying skills...';
+    spinner.text = mergeMode ? 'Merging skills...' : 'Copying skills...';
     if (toInstall.skills === 'all') {
-      await copyAllOfType('skills', source.claudeDir, targetDir);
+      await copyAllOfType('skills', source.claudeDir, targetDir, mergeMode);
     } else if (toInstall.skills.length > 0) {
-      await copyItems(toInstall.skills, 'skills', source.claudeDir, targetDir);
+      await copyItems(toInstall.skills, 'skills', source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy commands
-    spinner.text = 'Copying commands...';
+    spinner.text = mergeMode ? 'Merging commands...' : 'Copying commands...';
     if (toInstall.commands === 'all') {
-      await copyAllOfType('commands', source.claudeDir, targetDir);
+      await copyAllOfType('commands', source.claudeDir, targetDir, mergeMode);
     } else if (toInstall.commands.length > 0) {
-      await copyItems(toInstall.commands, 'commands', source.claudeDir, targetDir);
+      await copyItems(toInstall.commands, 'commands', source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy workflows
-    spinner.text = 'Copying workflows...';
+    spinner.text = mergeMode ? 'Merging workflows...' : 'Copying workflows...';
     if (toInstall.workflows === 'all') {
-      await copyAllOfType('workflows', source.claudeDir, targetDir);
+      await copyAllOfType('workflows', source.claudeDir, targetDir, mergeMode);
     } else if (toInstall.workflows && toInstall.workflows.length > 0) {
-      await copyItems(toInstall.workflows, 'workflows', source.claudeDir, targetDir);
+      await copyItems(toInstall.workflows, 'workflows', source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy router
     if (toInstall.includeRouter) {
-      spinner.text = 'Copying router...';
-      await copyRouter(source.claudeDir, targetDir);
+      spinner.text = mergeMode ? 'Merging router...' : 'Copying router...';
+      await copyRouter(source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy hooks
     if (toInstall.includeHooks) {
-      spinner.text = 'Copying hooks...';
-      await copyHooks(source.claudeDir, targetDir);
+      spinner.text = mergeMode ? 'Merging hooks...' : 'Copying hooks...';
+      await copyHooks(source.claudeDir, targetDir, mergeMode);
     }
 
     // Copy base files
-    spinner.text = 'Copying base files...';
-    await copyBaseFiles(source.claudeDir, targetDir);
+    spinner.text = mergeMode ? 'Merging base files...' : 'Copying base files...';
+    await copyBaseFiles(source.claudeDir, targetDir, mergeMode);
 
     // Copy AGENTS.md
     if (source.agentsMd) {
-      await copyAgentsMd(source.agentsMd, projectDir);
+      await copyAgentsMd(source.agentsMd, projectDir, mergeMode);
     }
 
     // Create state file
@@ -202,13 +234,18 @@ export async function initCommand(projectName, options) {
       }
     });
 
-    spinner.succeed(chalk.green('Project created successfully!'));
+    const actionWord = mergeMode ? 'merged' : (existingAction === 'override' ? 'overridden' : 'created');
+    spinner.succeed(chalk.green(`Project ${actionWord} successfully!`));
 
     // Print next steps
     console.log('');
-    console.log(chalk.cyan('Next steps:'));
-    console.log(chalk.white(`  cd ${projectName}`));
-    console.log(chalk.white('  # Start coding with Claude Code'));
+    if (!isCurrentDir) {
+      console.log(chalk.cyan('Next steps:'));
+      console.log(chalk.white(`  cd ${projectName}`));
+      console.log(chalk.white('  # Start coding with Claude Code'));
+    } else {
+      console.log(chalk.cyan('Ready to code with Claude Code!'));
+    }
     console.log('');
     console.log(chalk.gray('Useful commands:'));
     console.log(chalk.gray('  ak status     - Check file status'));

package/src/utils/copy.js

@@ -3,8 +3,9 @@ import { join, basename } from 'path';
 
 /**
  * Copy specific items from source to destination
+ * @param {boolean} mergeMode - If true, skip existing files
  */
-export async function copyItems(items, type, sourceDir, destDir) {
+export async function copyItems(items, type, sourceDir, destDir, mergeMode = false) {
   const typeDir = join(sourceDir, type);
   const destTypeDir = join(destDir, type);
 
@@ -37,14 +38,14 @@ export async function copyItems(items, type, sourceDir, destDir) {
       // Determine destination path
       const stat = fs.statSync(srcPath);
       if (stat.isDirectory()) {
-        await fs.copy(srcPath, join(destTypeDir, item), { overwrite: true });
+        await fs.copy(srcPath, join(destTypeDir, item), { overwrite: !mergeMode });
       } else {
         // Preserve directory structure for nested items
         const destPath = srcPath.endsWith('.md')
           ? join(destTypeDir, item + '.md')
           : join(destTypeDir, item);
         await fs.ensureDir(join(destTypeDir, item.split('/').slice(0, -1).join('/')));
-        await fs.copy(srcPath, destPath, { overwrite: true });
+        await fs.copy(srcPath, destPath, { overwrite: !mergeMode });
       }
 
       copied.push(item);
@@ -58,8 +59,9 @@ export async function copyItems(items, type, sourceDir, destDir) {
 
 /**
  * Copy all items of a type
+ * @param {boolean} mergeMode - If true, skip existing files
  */
-export async function copyAllOfType(type, sourceDir, destDir) {
+export async function copyAllOfType(type, sourceDir, destDir, mergeMode = false) {
   const typeDir = join(sourceDir, type);
   const destTypeDir = join(destDir, type);
 
@@ -68,7 +70,7 @@ export async function copyAllOfType(type, sourceDir, destDir) {
   }
 
   try {
-    await fs.copy(typeDir, destTypeDir, { overwrite: true });
+    await fs.copy(typeDir, destTypeDir, { overwrite: !mergeMode });
     return { success: true };
   } catch (err) {
     return { success: false, error: err.message };
@@ -77,8 +79,9 @@ export async function copyAllOfType(type, sourceDir, destDir) {
 
 /**
  * Copy router directory
+ * @param {boolean} mergeMode - If true, skip existing files
  */
-export async function copyRouter(sourceDir, destDir) {
+export async function copyRouter(sourceDir, destDir, mergeMode = false) {
   const routerDir = join(sourceDir, 'router');
 
   if (!fs.existsSync(routerDir)) {
@@ -86,7 +89,7 @@ export async function copyRouter(sourceDir, destDir) {
   }
 
   try {
-    await fs.copy(routerDir, join(destDir, 'router'), { overwrite: true });
+    await fs.copy(routerDir, join(destDir, 'router'), { overwrite: !mergeMode });
     return { success: true };
   } catch (err) {
     return { success: false, error: err.message };
@@ -95,8 +98,9 @@ export async function copyRouter(sourceDir, destDir) {
 
 /**
  * Copy hooks directory
+ * @param {boolean} mergeMode - If true, skip existing files
  */
-export async function copyHooks(sourceDir, destDir) {
+export async function copyHooks(sourceDir, destDir, mergeMode = false) {
   const hooksDir = join(sourceDir, 'hooks');
 
   if (!fs.existsSync(hooksDir)) {
@@ -104,7 +108,7 @@ export async function copyHooks(sourceDir, destDir) {
   }
 
   try {
-    await fs.copy(hooksDir, join(destDir, 'hooks'), { overwrite: true });
+    await fs.copy(hooksDir, join(destDir, 'hooks'), { overwrite: !mergeMode });
     return { success: true };
   } catch (err) {
     return { success: false, error: err.message };
@@ -123,15 +127,23 @@ export async function copyWorkflows(items, sourceDir, destDir) {
 
 /**
  * Copy base files (README, settings, etc.)
+ * @param {boolean} mergeMode - If true, skip existing files
  */
-export async function copyBaseFiles(sourceDir, destDir) {
+export async function copyBaseFiles(sourceDir, destDir, mergeMode = false) {
   const baseFiles = ['README.md', 'settings.json', '.env.example'];
   const copied = [];
 
   for (const file of baseFiles) {
     const srcPath = join(sourceDir, file);
+    const destPath = join(destDir, file);
+
+    // Skip if merge mode and file exists
+    if (mergeMode && fs.existsSync(destPath)) {
+      continue;
+    }
+
     if (fs.existsSync(srcPath)) {
-      await fs.copy(srcPath, join(destDir, file), { overwrite: true });
+      await fs.copy(srcPath, destPath, { overwrite: !mergeMode });
       copied.push(file);
     }
   }
@@ -141,13 +153,21 @@ export async function copyBaseFiles(sourceDir, destDir) {
 
 /**
  * Copy AGENTS.md to project root
+ * @param {boolean} mergeMode - If true, skip if file exists
  */
-export async function copyAgentsMd(agentsMdPath, projectDir) {
+export async function copyAgentsMd(agentsMdPath, projectDir, mergeMode = false) {
   if (!agentsMdPath || !fs.existsSync(agentsMdPath)) {
     return false;
   }
 
-  await fs.copy(agentsMdPath, join(projectDir, 'AGENTS.md'), { overwrite: true });
+  const destPath = join(projectDir, 'AGENTS.md');
+
+  // Skip if merge mode and file exists
+  if (mergeMode && fs.existsSync(destPath)) {
+    return false;
+  }
+
+  await fs.copy(agentsMdPath, destPath, { overwrite: !mergeMode });
   return true;
 }
 

package/src/utils/prompts.js

@@ -207,6 +207,25 @@ export async function promptConfirm(message, defaultValue = true) {
   return confirmed;
 }
 
+/**
+ * Prompt for existing target directory action
+ */
+export async function promptExistingTarget(targetPath) {
+  const { action } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: `${targetPath} already exists. What do you want to do?`,
+      choices: [
+        { name: '🔄 Override - Replace all files', value: 'override' },
+        { name: '📦 Merge - Only add missing files', value: 'merge' },
+        { name: '⏭️  Skip - Do nothing', value: 'skip' }
+      ]
+    }
+  ]);
+  return action;
+}
+
 /**
  * Prompt for update confirmation with file list
  */

package/templates/commands/plan/fast.md

@@ -66,6 +66,15 @@ Use `planner` subagent to:
 - Save the overview access point at `{plan-dir}/plan.md`. Keep it generic, under 80 lines, and list each implementation phase with status and progress plus links to phase files.
 - For each phase, create `{plan-dir}/phase-XX-phase-name-here.md` containing the following sections in order: Context links (reference parent plan, dependencies, docs), Overview (date, description, priority, implementation status, review status), Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps.
 
+## Post-Plan Preview (Optional)
+
+After plan creation, offer to open in browser for easier reading.
+
+Use `AskUserQuestion` tool:
+- "Open plan in browser for easier reading?" → Yes (Recommended) / No
+
+**If user chooses Yes:** Run `/plan:preview {plan-path}` SlashCommand.
+
 ## Important Notes
 
 - **IMPORTANT:** Ensure token consumption efficiency while maintaining high quality.

package/templates/commands/plan/hard.md

@@ -45,6 +45,15 @@ After plan creation, offer validation interview to confirm decisions before impl
 **If mode is `prompt`:** Use `AskUserQuestion` tool with options above.
 **If user chooses validation or mode is `auto`:** Execute `/plan:validate {plan-path}` SlashCommand.
 
+## Post-Plan Preview (Optional)
+
+After plan creation, offer to open in browser for easier reading.
+
+Use `AskUserQuestion` tool:
+- "Open plan in browser for easier reading?" → Yes (Recommended) / No
+
+**If user chooses Yes:** Run `/plan:preview {plan-path}` SlashCommand.
+
 ## Output Requirements
 
 **Plan Directory Structure** (use `Plan dir:` from `## Naming` section)

package/templates/commands/plan/parallel.md

@@ -131,6 +131,15 @@ Phase 04: Integration Tests (depends on 01, 02, 03)
 - Execution strategy (e.g., "Phases 1-3 parallel, then Phase 4")
 - File ownership matrix (which phase owns which files)
 
+## Post-Plan Preview (Optional)
+
+After plan creation, offer to open in browser for easier reading.
+
+Use `AskUserQuestion` tool:
+- "Open plan in browser for easier reading?" → Yes (Recommended) / No
+
+**If user chooses Yes:** Run `/plan:preview {plan-path}` SlashCommand.
+
 ## Important Notes
 
 **IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/templates/commands/plan/preview.md

@@ -0,0 +1,40 @@
+---
+description: 👁️ Open plan in browser for easy reading
+argument-hint: [plan-path]
+---
+
+## Your mission
+
+Open the plan preview server to view the plan in a nicely formatted web page.
+
+## Workflow
+
+1. **Determine plan path:**
+   - If `$ARGUMENTS` provided → Use that path
+   - If active plan exists in `## Plan Context` → Use that path
+   - If neither → Ask user to specify a plan path
+
+2. **Start preview server:**
+
+   ```bash
+   node .claude/scripts/plan-preview.cjs {plan-path}
+   ```
+
+3. **Inform user:**
+   - Browser will open automatically
+   - Server runs on `http://localhost:3456`
+   - Press `Ctrl+C` in terminal to stop
+
+## Example Usage
+
+```
+/plan:preview plans/250116-feature-auth
+/plan:preview  # Uses active plan from context
+```
+
+## Notes
+
+- The preview server renders markdown with syntax highlighting
+- Navigation sidebar shows all plan files (plan.md, phases, reports)
+- Server auto-detects plan structure (research/, reports/, scout/ subdirs)
+- Refresh the page to see updated content

package/templates/scripts/plan-preview.cjs

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+/**
+ * Plan Preview Server
+ *
+ * Usage: node .claude/scripts/plan-preview.cjs <plan-path> [--port=3456]
+ *
+ * Opens a local web server to preview plans with:
+ * - Rendered markdown with syntax highlighting
+ * - Navigation sidebar for phases
+ * - Auto-refresh on file changes
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { exec } = require('child_process');
+
+const planPath = process.argv[2];
+const portArg = process.argv.find(arg => arg.startsWith('--port='));
+const PORT = portArg ? parseInt(portArg.split('=')[1]) : 3456;
+
+if (!planPath) {
+  console.error('Error: Plan path required');
+  console.log('Usage: node .claude/scripts/plan-preview.cjs <plan-path>');
+  console.log('Example: node .claude/scripts/plan-preview.cjs plans/251207-feature');
+  process.exit(1);
+}
+
+const fullPlanPath = path.resolve(process.cwd(), planPath);
+if (!fs.existsSync(fullPlanPath)) {
+  console.error(`Error: Plan directory not found: ${fullPlanPath}`);
+  process.exit(1);
+}
+
+// Simple markdown to HTML converter
+function markdownToHtml(md) {
+  return md
+    // Code blocks with language
+    .replace(/```(\w+)?\n([\s\S]*?)```/g, (_, lang, code) => {
+      const langClass = lang ? `language-${lang}` : '';
+      return `<pre class="${langClass}"><code>${escapeHtml(code.trim())}</code></pre>`;
+    })
+    // Inline code
+    .replace(/`([^`]+)`/g, '<code class="inline">$1</code>')
+    // Headers
+    .replace(/^### (.*$)/gm, '<h3>$1</h3>')
+    .replace(/^## (.*$)/gm, '<h2>$1</h2>')
+    .replace(/^# (.*$)/gm, '<h1>$1</h1>')
+    // Bold and italic
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*([^*]+)\*/g, '<em>$1</em>')
+    // Links
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" target="_blank">$1</a>')
+    // Lists
+    .replace(/^\s*[-*] (.*$)/gm, '<li>$1</li>')
+    .replace(/(<li>.*<\/li>)\n(?!<li>)/g, '$1</ul>\n')
+    .replace(/(?<!<\/li>\n)(<li>)/g, '<ul>$1')
+    // Numbered lists
+    .replace(/^\s*\d+\. (.*$)/gm, '<li class="numbered">$1</li>')
+    // Blockquotes
+    .replace(/^> (.*$)/gm, '<blockquote>$1</blockquote>')
+    // Horizontal rules
+    .replace(/^---+$/gm, '<hr>')
+    // Paragraphs
+    .replace(/\n\n/g, '</p><p>')
+    // Tables (simple)
+    .replace(/\|(.+)\|/g, (match) => {
+      const cells = match.split('|').filter(c => c.trim());
+      if (cells.every(c => /^[-:]+$/.test(c.trim()))) return ''; // Skip separator
+      const tag = 'td';
+      return '<tr>' + cells.map(c => `<${tag}>${c.trim()}</${tag}>`).join('') + '</tr>';
+    });
+}
+
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// Get all markdown files in plan directory
+function getPlanFiles(dir) {
+  const files = [];
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    if (item.isFile() && item.name.endsWith('.md')) {
+      files.push({
+        name: item.name,
+        path: path.join(dir, item.name),
+        isMain: item.name === 'plan.md',
+        isPhase: item.name.startsWith('phase-')
+      });
+    } else if (item.isDirectory()) {
+      // Include reports, research, scout subdirs
+      const subFiles = getPlanFiles(path.join(dir, item.name));
+      files.push(...subFiles.map(f => ({
+        ...f,
+        name: `${item.name}/${f.name}`,
+        category: item.name
+      })));
+    }
+  }
+
+  return files.sort((a, b) => {
+    if (a.isMain) return -1;
+    if (b.isMain) return 1;
+    if (a.isPhase && !b.isPhase) return -1;
+    if (!a.isPhase && b.isPhase) return 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+// Generate HTML page
+function generatePage(files, currentFile) {
+  const file = files.find(f => f.name === currentFile) || files[0];
+  const content = file ? fs.readFileSync(file.path, 'utf-8') : '# No plan found';
+  const htmlContent = markdownToHtml(content);
+
+  const nav = files.map(f => {
+    const isActive = f.name === (currentFile || files[0]?.name);
+    const icon = f.isMain ? '📋' : f.isPhase ? '📌' : f.category === 'research' ? '🔬' : f.category === 'reports' ? '📄' : '📝';
+    return `<a href="?file=${encodeURIComponent(f.name)}" class="${isActive ? 'active' : ''}">${icon} ${f.name}</a>`;
+  }).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Plan Preview - ${path.basename(fullPlanPath)}</title>
+  <style>
+    :root {
+      --bg: #0d1117;
+      --bg-secondary: #161b22;
+      --text: #c9d1d9;
+      --text-muted: #8b949e;
+      --accent: #58a6ff;
+      --border: #30363d;
+      --code-bg: #1f2428;
+      --success: #3fb950;
+      --warning: #d29922;
+    }
+
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      line-height: 1.6;
+      display: flex;
+      min-height: 100vh;
+    }
+
+    /* Sidebar */
+    .sidebar {
+      width: 280px;
+      background: var(--bg-secondary);
+      border-right: 1px solid var(--border);
+      padding: 20px;
+      position: fixed;
+      height: 100vh;
+      overflow-y: auto;
+    }
+
+    .sidebar h2 {
+      color: var(--text);
+      font-size: 14px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      margin-bottom: 16px;
+      padding-bottom: 8px;
+      border-bottom: 1px solid var(--border);
+    }
+
+    .sidebar a {
+      display: block;
+      color: var(--text-muted);
+      text-decoration: none;
+      padding: 8px 12px;
+      border-radius: 6px;
+      font-size: 13px;
+      margin-bottom: 4px;
+      transition: all 0.2s;
+    }
+
+    .sidebar a:hover {
+      background: var(--border);
+      color: var(--text);
+    }
+
+    .sidebar a.active {
+      background: rgba(88, 166, 255, 0.15);
+      color: var(--accent);
+    }
+
+    /* Main content */
+    .main {
+      flex: 1;
+      margin-left: 280px;
+      padding: 40px 60px;
+      max-width: 900px;
+    }
+
+    .main h1 {
+      font-size: 32px;
+      margin-bottom: 24px;
+      padding-bottom: 16px;
+      border-bottom: 1px solid var(--border);
+    }
+
+    .main h2 {
+      font-size: 24px;
+      margin: 32px 0 16px;
+      color: var(--text);
+    }
+
+    .main h3 {
+      font-size: 18px;
+      margin: 24px 0 12px;
+      color: var(--text);
+    }
+
+    .main p {
+      margin-bottom: 16px;
+    }
+
+    .main ul, .main ol {
+      margin: 16px 0;
+      padding-left: 24px;
+    }
+
+    .main li {
+      margin-bottom: 8px;
+    }
+
+    .main a {
+      color: var(--accent);
+    }
+
+    .main blockquote {
+      border-left: 4px solid var(--accent);
+      padding-left: 16px;
+      margin: 16px 0;
+      color: var(--text-muted);
+    }
+
+    .main hr {
+      border: none;
+      border-top: 1px solid var(--border);
+      margin: 32px 0;
+    }
+
+    /* Code */
+    pre {
+      background: var(--code-bg);
+      padding: 16px;
+      border-radius: 8px;
+      overflow-x: auto;
+      margin: 16px 0;
+      border: 1px solid var(--border);
+    }
+
+    code {
+      font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+      font-size: 13px;
+    }
+
+    code.inline {
+      background: var(--code-bg);
+      padding: 2px 6px;
+      border-radius: 4px;
+      color: var(--accent);
+    }
+
+    /* Tables */
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 16px 0;
+    }
+
+    th, td {
+      padding: 12px;
+      border: 1px solid var(--border);
+      text-align: left;
+    }
+
+    th {
+      background: var(--bg-secondary);
+    }
+
+    /* Status badges */
+    .status-pending { color: var(--warning); }
+    .status-completed { color: var(--success); }
+
+    /* Footer */
+    .footer {
+      margin-top: 48px;
+      padding-top: 24px;
+      border-top: 1px solid var(--border);
+      color: var(--text-muted);
+      font-size: 12px;
+    }
+
+    /* Responsive */
+    @media (max-width: 768px) {
+      .sidebar { width: 100%; height: auto; position: relative; }
+      .main { margin-left: 0; padding: 20px; }
+      body { flex-direction: column; }
+    }
+  </style>
+</head>
+<body>
+  <nav class="sidebar">
+    <h2>📁 ${path.basename(fullPlanPath)}</h2>
+    ${nav}
+  </nav>
+  <main class="main">
+    <article>
+      ${htmlContent}
+    </article>
+    <footer class="footer">
+      <p>Plan Preview Server • <a href="javascript:location.reload()">↻ Refresh</a></p>
+    </footer>
+  </main>
+  <script>
+    // Auto-refresh every 5 seconds (optional)
+    // setTimeout(() => location.reload(), 5000);
+  </script>
+</body>
+</html>`;
+}
+
+// Create HTTP server
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+  const currentFile = url.searchParams.get('file');
+
+  const files = getPlanFiles(fullPlanPath);
+  const html = generatePage(files, currentFile);
+
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+  res.end(html);
+});
+
+server.listen(PORT, () => {
+  const url = `http://localhost:${PORT}`;
+  console.log(`\n📋 Plan Preview Server`);
+  console.log(`   Plan: ${planPath}`);
+  console.log(`   URL:  ${url}`);
+  console.log(`\n   Press Ctrl+C to stop\n`);
+
+  // Open browser
+  const openCommand = process.platform === 'darwin' ? 'open' :
+                      process.platform === 'win32' ? 'start' : 'xdg-open';
+  exec(`${openCommand} ${url}`);
+});
+
+// Handle shutdown
+process.on('SIGINT', () => {
+  console.log('\n👋 Server stopped');
+  process.exit(0);
+});