@sandrinio/vbounce 1.5.0 → 1.7.0

package/README.md

@@ -38,22 +38,12 @@ V-Bounce OS organizes planning documents (`product_plans/`) through a strict sta
 
 ## 🛠️ The Tech Stack
 
-V-Bounce OS is built to be **local-first, privacy-conscious, and blazing fast**.
+V-Bounce OS is built to be **local-first, privacy-conscious, and dependency-light**.
 
-- **Vector Database**: [LanceDB](https://lancedb.com/) — A serverless, local vector DB used to store and query project context.
-- **Embeddings**: [Xenova Transformers](https://github.com/xenova/transformers.js) — Local execution of `all-MiniLM-L6-v2`. **No private code is ever sent to external embedding APIs for RAG.**
-- **Runtime**: Node.js — Powering the validation pipeline and semantic search engine.
-- **Data Contract**: YAML Frontmatter + Markdown — Ensures human-readable agent handoffs that are also strictly machine-parsable.
-
----
-
-## 🧠 Semantic Context (Local RAG)
-
-V-Bounce OS doesn't just dump your entire codebase into a prompt. It uses **Retrieval-Augmented Generation (RAG)** to find only the rules that matter right now.
-
-1. **Indexing**: The `pre_bounce_sync.sh` script crawls your `product_plans/`, `LESSONS.md`, and `Roadmap ADRs`, converting them into searchable vectors.
-2. **Querying**: Agents use the built-in `./scripts/vbounce_ask.mjs` tool to ask questions like *"What are the architectural constraints for auth?"* or *"What mistakes did we make with the last React component?"*.
-3. **Targeted Context**: The agent receives only the most relevant 3-5 snippets of project history, preventing context-window bloat and improving instruction following.
+- **Runtime**: Node.js — Powering the validation pipeline, context preparation, and CLI.
+- **Data Contract**: YAML Frontmatter + Markdown — Human-readable agent handoffs that are also strictly machine-parsable.
+- **State Management**: `.bounce/state.json` — Machine-readable sprint state for instant crash recovery without re-reading documents.
+- **Context Budget**: On-demand prep scripts (`vbounce prep sprint/qa/arch`) generate capped context packs — no embedding or vector DB required.
 
 ---
 
@@ -80,11 +70,111 @@ npx @sandrinio/vbounce install codex
 
 ### What gets installed?
 - **Agent Instructions:** The "Brain" file (e.g., `CLAUDE.md`, `.cursor/rules/`) that teaches your AI how to follow the V-Bounce process.
-- **Templates:** Markdown templates for your Charter, Roadmap, Epics, and Stories.
-- **Bundled Scripts:** Our validation pipeline (`validate_report.mjs`) and RAG synchronization engine (`pre_bounce_sync.sh`).
-- **Autonomous RAG Setup:** The installer automatically runs `npm install` for required libraries and initializes your local LanceDB knowledge base (`.bounce/.lancedb/`).
+- **Templates:** Markdown templates for your Charter, Roadmap, Epics, Stories, Sprint Plans, and Delivery Plans.
+- **Bundled Scripts:** 16+ automation scripts — validation pipeline, context preparation, state management, sprint lifecycle, and the self-improvement loop.
+- **Lightweight Dependencies:** The installer runs `npm install` for `js-yaml`, `marked`, and `commander` — nothing else. No vector DBs, no embedding models.
 - **vdoc Integration:** The installer offers to install [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) for your platform — enabling automatic semantic product documentation generation via the Scribe agent.
 
+After installing, run `vbounce doctor` to verify your setup is complete.
+
+---
+
+## 🛠️ The `vbounce` CLI
+
+All V-Bounce OS operations route through a unified CLI. Every command is designed to be run by the Team Lead agent — not just humans.
+
+```bash
+# Sprint lifecycle
+vbounce sprint init S-01 D-01   # Initialize sprint state.json + plan dir
+vbounce sprint close S-01        # Validate terminal states, archive, close
+
+# Story lifecycle
+vbounce story complete STORY-001-01-login   # Update state.json + sprint plan §4
+
+# State management (crash recovery)
+vbounce state show                               # Print current state.json
+vbounce state update STORY-001-01-login "QA Passed"  # Update story state
+vbounce state update STORY-001-01-login "Bouncing" --qa-bounce  # Increment QA bounce
+
+# Context preparation (context budget management)
+vbounce prep sprint S-01          # Generate sprint-context-S-01.md (≤200 lines)
+vbounce prep qa STORY-001-01-login    # Generate qa-context-STORY-ID.md (≤300 lines)
+vbounce prep arch STORY-001-01-login  # Generate arch-context with truncated diff
+
+# Validation gates
+vbounce validate report .bounce/reports/STORY-001-01-login-qa.md
+vbounce validate state            # Validate state.json schema
+vbounce validate sprint S-01      # Validate sprint plan structure + cross-refs
+vbounce validate ready STORY-001-01-login  # Pre-bounce readiness gate
+
+# Self-improvement loop
+vbounce trends                    # Compute sprint metrics → .bounce/trends.md
+vbounce suggest S-01              # Generate improvement suggestions
+
+# Framework health
+vbounce doctor                    # Check all required files, scripts, templates
+```
+
+---
+
+## 🔄 State Management & Crash Recovery
+
+V-Bounce OS tracks sprint state in `.bounce/state.json` — a machine-readable snapshot that survives context resets and session interruptions.
+
+```json
+{
+  "sprint_id": "S-01",
+  "delivery_id": "D-01",
+  "current_phase": "bouncing",
+  "last_action": "QA failed STORY-001-01-login — bounce 1",
+  "stories": {
+    "STORY-001-01-login": {
+      "state": "Bouncing",
+      "qa_bounces": 1,
+      "arch_bounces": 0,
+      "worktree": ".worktrees/STORY-001-01-login",
+      "updated_at": "2026-03-12T10:00:00Z"
+    }
+  }
+}
+```
+
+When a new session starts, the Team Lead reads `state.json` in under 5 seconds to know exactly where the sprint left off — no re-reading 10 markdown files.
+
+---
+
+## 📊 Self-Improvement Loop
+
+V-Bounce OS tracks its own performance and suggests improvements automatically.
+
+1. **Root Cause Tagging**: Every QA and Architect FAIL report includes a `root_cause:` field (e.g., `missing_tests`, `adr_violation`, `spec_ambiguity`) that feeds into trend analysis.
+2. **Sprint Trends**: `vbounce trends` scans all archived reports to compute first-pass rate, average bounce count, correction tax, and root cause breakdown per sprint.
+3. **Improvement Suggestions**: `vbounce suggest S-{XX}` reads trends, LESSONS.md, and the improvement log to flag stale lessons, recurring failure patterns, and graduation candidates.
+4. **Improvement Log**: `.bounce/improvement-log.md` tracks every suggestion with Applied/Rejected/Deferred status — so nothing falls through the cracks.
+
+---
+
+## 🔧 Tool Tier Model
+
+V-Bounce OS supports four tiers of AI tools with dedicated brain files for each.
+
+| Tier | Tools | Brain File | Capabilities |
+|------|-------|------------|--------------|
+| **Tier 1** | Claude Code | `brains/CLAUDE.md` | Full orchestration — spawns subagents, manages state, runs all CLI commands |
+| **Tier 2** | Gemini CLI, OpenAI Codex | `brains/GEMINI.md`, `brains/codex/` | Single-agent — follows bounce loop, reads state.json, all CLI commands |
+| **Tier 3** | Cursor | `brains/cursor-rules/` | Role-specific context injection via `.cursor/rules/` MDC files |
+| **Tier 4** | GitHub Copilot, Windsurf | `brains/copilot/`, `brains/windsurf/` | Awareness mode — checklist-driven, reads state.json, CLI commands for safe operations |
+
+Install the appropriate brain for your tool:
+```bash
+npx @sandrinio/vbounce install claude   # Tier 1
+npx @sandrinio/vbounce install gemini   # Tier 2
+npx @sandrinio/vbounce install cursor   # Tier 3
+npx @sandrinio/vbounce install vscode   # Tier 4
+```
+
+---
+
 ### 🧰 The Bundled Skills
 V-Bounce OS installs a powerful suite of specialized markdown `skills/` directly into your workspace. These act as modular capabilities you can invoke dynamically or that the Team Lead agent will invoke automatically during the SDLC process:
 

package/bin/vbounce.mjs

@@ -5,7 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 
-import { execSync } from 'child_process';
+import { execSync, spawnSync } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -13,7 +13,7 @@ const pkgRoot = path.join(__dirname, '..');
 
 const args = process.argv.slice(2);
 const command = args[0];
-const targetPlatform = args[1]?.toLowerCase();
+const sub = args[1];
 
 if (command === '-v' || command === '--version') {
   const pkgPath = path.join(pkgRoot, 'package.json');
@@ -26,7 +26,32 @@ if (command === '-v' || command === '--version') {
   process.exit(0);
 }
 
-// Utility for interactive prompt
+// ---------------------------------------------------------------------------
+// Script runner helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a Node.js script from the scripts/ directory with forwarded args.
+ * @param {string} scriptName - filename inside scripts/ (e.g. 'doctor.mjs')
+ * @param {string[]} scriptArgs - additional CLI arguments
+ */
+function runScript(scriptName, scriptArgs = []) {
+  const scriptPath = path.join(pkgRoot, 'scripts', scriptName);
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`Error: Script not found: scripts/${scriptName}`);
+    console.error('Run `vbounce doctor` to check which scripts are missing.');
+    process.exit(1);
+  }
+  const result = spawnSync(process.execPath, [scriptPath, ...scriptArgs], {
+    stdio: 'inherit',
+    cwd: process.cwd()
+  });
+  process.exit(result.status ?? 0);
+}
+
+// ---------------------------------------------------------------------------
+// Utility for interactive prompt (used by install)
+// ---------------------------------------------------------------------------
 const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout
@@ -34,14 +59,33 @@ const rl = readline.createInterface({
 
 const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve));
 
+// ---------------------------------------------------------------------------
+// Help text
+// ---------------------------------------------------------------------------
+
 function displayHelp() {
   console.log(`
-🎯 V-Bounce OS Installer
+V-Bounce OS CLI
 
 Usage:
-  npx vbounce install <platform>
-
-Supported Platforms:
+  vbounce install <platform>           Install V-Bounce OS into a project
+  vbounce state show                   Show current sprint state
+  vbounce state update <storyId> <state|--qa-bounce>
+  vbounce sprint init <sprintId> <deliveryId> [--stories STORY-001,...]
+  vbounce sprint close <sprintId>
+  vbounce story complete <storyId> [options]
+  vbounce validate report <file>       Validate agent report YAML
+  vbounce validate state               Validate state.json
+  vbounce validate sprint [file]       Validate Sprint Plan
+  vbounce validate ready <storyId>     Pre-bounce gate check
+  vbounce prep qa <storyId>            Generate QA context pack
+  vbounce prep arch <storyId>          Generate Architect context pack
+  vbounce prep sprint <sprintId>       Generate Sprint context pack
+  vbounce trends                       Cross-sprint trend analysis
+  vbounce suggest <sprintId>           Generate improvement suggestions
+  vbounce doctor                       Validate all configs and state files
+
+Install Platforms:
   claude  : Installs CLAUDE.md and Claude Code subagents
   cursor  : Installs modular .cursor/rules/
   gemini  : Installs GEMINI.md and Antigravity skills
@@ -52,179 +96,280 @@ Supported Platforms:
   process.exit(0);
 }
 
-if (!command || command !== 'install' || !targetPlatform) {
-  displayHelp();
-}
+// ---------------------------------------------------------------------------
+// Route commands
+// ---------------------------------------------------------------------------
 
-const CWD = process.cwd();
-
-// Map vbounce platform names to vdoc platform names
-const vdocPlatformMap = {
-  claude: 'claude',
-  cursor: 'cursor',
-  gemini: 'gemini',
-  codex: 'agents',
-  vscode: 'vscode',
-  copilot: 'vscode'
-};
-
-const platformMappings = {
-  claude: [
-    { src: 'brains/CLAUDE.md', dest: 'CLAUDE.md' },
-    { src: 'brains/claude-agents', dest: '.claude/agents' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ],
-  cursor: [
-    { src: 'brains/cursor-rules', dest: '.cursor/rules' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ],
-  gemini: [
-    { src: 'brains/GEMINI.md', dest: 'GEMINI.md' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'skills', dest: '.agents/skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ],
-  codex: [
-    { src: 'brains/AGENTS.md', dest: 'AGENTS.md' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ],
-  vscode: [
-    { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ],
-  copilot: [
-    { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
-    { src: 'templates', dest: 'templates' },
-    { src: 'skills', dest: 'skills' },
-    { src: 'scripts', dest: 'scripts' }
-  ]
-};
-
-const mapping = platformMappings[targetPlatform];
-
-if (!mapping) {
-  console.error(`Error: Unsupported platform '${targetPlatform}'.\n`);
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  rl.close();
   displayHelp();
 }
 
-console.log(`\n🚀 Preparing to install V-Bounce OS for \x1b[36m${targetPlatform}\x1b[0m...\n`);
-
-const toCopy = [];
-const toOverwrite = [];
+// -- state --
+if (command === 'state') {
+  rl.close();
+  if (sub === 'show') {
+    runScript('update_state.mjs', ['--show']);
+  } else if (sub === 'update') {
+    // vbounce state update <storyId> <newState|--qa-bounce>
+    runScript('update_state.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown state subcommand: ${sub}`);
+    console.error('Usage: vbounce state show | vbounce state update <storyId> <state|--qa-bounce>');
+    process.exit(1);
+  }
+}
 
-mapping.forEach(rule => {
-  const sourcePath = path.join(pkgRoot, rule.src);
-  const destPath = path.join(CWD, rule.dest);
+// -- sprint --
+if (command === 'sprint') {
+  rl.close();
+  if (sub === 'init') {
+    runScript('init_sprint.mjs', args.slice(2));
+  } else if (sub === 'close') {
+    runScript('close_sprint.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown sprint subcommand: ${sub}`);
+    console.error('Usage: vbounce sprint init <sprintId> <deliveryId> | vbounce sprint close <sprintId>');
+    process.exit(1);
+  }
+}
 
-  if (!fs.existsSync(sourcePath)) {
-    return; // Source does not exist internally, skip
+// -- story --
+if (command === 'story') {
+  rl.close();
+  if (sub === 'complete') {
+    runScript('complete_story.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown story subcommand: ${sub}`);
+    console.error('Usage: vbounce story complete <storyId> [options]');
+    process.exit(1);
   }
+}
 
-  if (fs.existsSync(destPath)) {
-    toOverwrite.push(rule.dest);
+// -- validate --
+if (command === 'validate') {
+  rl.close();
+  if (sub === 'report') {
+    runScript('validate_report.mjs', args.slice(2));
+  } else if (sub === 'state') {
+    runScript('validate_state.mjs', args.slice(2));
+  } else if (sub === 'sprint') {
+    runScript('validate_sprint_plan.mjs', args.slice(2));
+  } else if (sub === 'ready') {
+    runScript('validate_bounce_readiness.mjs', args.slice(2));
   } else {
-    toCopy.push(rule.dest);
+    console.error(`Unknown validate subcommand: ${sub}`);
+    console.error('Usage: vbounce validate report <file> | state | sprint [file] | ready <storyId>');
+    process.exit(1);
   }
-});
+}
 
-if (toCopy.length > 0) {
-  console.log('The following will be \x1b[32mCREATED\x1b[0m:');
-  toCopy.forEach(f => console.log(`  + ${f}`));
+// -- prep --
+if (command === 'prep') {
+  rl.close();
+  if (sub === 'qa') {
+    runScript('prep_qa_context.mjs', args.slice(2));
+  } else if (sub === 'arch') {
+    runScript('prep_arch_context.mjs', args.slice(2));
+  } else if (sub === 'sprint') {
+    runScript('prep_sprint_context.mjs', args.slice(2));
+  } else {
+    console.error(`Unknown prep subcommand: ${sub}`);
+    console.error('Usage: vbounce prep qa <storyId> | arch <storyId> | sprint <sprintId>');
+    process.exit(1);
+  }
 }
 
-if (toOverwrite.length > 0) {
-  console.log('\nThe following will be \x1b[33mOVERWRITTEN\x1b[0m:');
-  toOverwrite.forEach(f => console.log(`  ! ${f}`));
+// -- trends --
+if (command === 'trends') {
+  rl.close();
+  runScript('sprint_trends.mjs', args.slice(1));
 }
 
-console.log('');
+// -- suggest --
+if (command === 'suggest') {
+  rl.close();
+  runScript('suggest_improvements.mjs', args.slice(1));
+}
 
-askQuestion('Proceed with installation? [y/N] ').then(async answer => {
+// -- doctor --
+if (command === 'doctor') {
   rl.close();
-  const confirmation = answer.trim().toLowerCase();
+  runScript('doctor.mjs', args.slice(1));
+}
+
+// ---------------------------------------------------------------------------
+// install command (original functionality)
+// ---------------------------------------------------------------------------
+
+if (command === 'install') {
+  const targetPlatform = sub?.toLowerCase();
 
-  if (confirmation !== 'y' && confirmation !== 'yes') {
-    console.log('\n❌ Installation cancelled.\n');
-    process.exit(0);
+  if (!targetPlatform) {
+    rl.close();
+    displayHelp();
   }
 
-  console.log('\n📦 Installing files...');
+  const CWD = process.cwd();
+
+  // Map vbounce platform names to vdoc platform names
+  const vdocPlatformMap = {
+    claude: 'claude',
+    cursor: 'cursor',
+    gemini: 'gemini',
+    codex: 'agents',
+    vscode: 'vscode',
+    copilot: 'vscode'
+  };
+
+  const platformMappings = {
+    claude: [
+      { src: 'brains/CLAUDE.md', dest: 'CLAUDE.md' },
+      { src: 'brains/claude-agents', dest: '.claude/agents' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ],
+    cursor: [
+      { src: 'brains/cursor-rules', dest: '.cursor/rules' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ],
+    gemini: [
+      { src: 'brains/GEMINI.md', dest: 'GEMINI.md' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'skills', dest: '.agents/skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ],
+    codex: [
+      { src: 'brains/AGENTS.md', dest: 'AGENTS.md' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ],
+    vscode: [
+      { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ],
+    copilot: [
+      { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
+      { src: 'templates', dest: 'templates' },
+      { src: 'skills', dest: 'skills' },
+      { src: 'scripts', dest: 'scripts' }
+    ]
+  };
+
+  const mapping = platformMappings[targetPlatform];
+
+  if (!mapping) {
+    rl.close();
+    console.error(`Error: Unsupported platform '${targetPlatform}'.\n`);
+    displayHelp();
+  }
+
+  console.log(`\n🚀 Preparing to install V-Bounce OS for \x1b[36m${targetPlatform}\x1b[0m...\n`);
+
+  const toCopy = [];
+  const toOverwrite = [];
 
   mapping.forEach(rule => {
     const sourcePath = path.join(pkgRoot, rule.src);
     const destPath = path.join(CWD, rule.dest);
 
-    if (!fs.existsSync(sourcePath)) return;
+    if (!fs.existsSync(sourcePath)) {
+      return; // Source does not exist internally, skip
+    }
 
-    const stats = fs.statSync(sourcePath);
-    if (stats.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      fs.cpSync(sourcePath, destPath, { recursive: true, force: true });
+    if (fs.existsSync(destPath)) {
+      toOverwrite.push(rule.dest);
     } else {
-      const destDir = path.dirname(destPath);
-      if (!fs.existsSync(destDir)) {
-        fs.mkdirSync(destDir, { recursive: true });
-      }
-      fs.copyFileSync(sourcePath, destPath);
+      toCopy.push(rule.dest);
     }
-    console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
   });
 
-  console.log('\n⚙️  Installing RAG dependencies...');
-  try {
-    const deps = [
-      '@lancedb/lancedb',
-      '@xenova/transformers',
-      'js-yaml',
-      'marked',
-      'commander'
-    ];
-    console.log(`  Running: npm install ${deps.join(' ')}`);
-    execSync(`npm install ${deps.join(' ')}`, { stdio: 'inherit', cwd: CWD });
-    console.log('  \x1b[32m✓\x1b[0m Dependencies installed.');
-  } catch (err) {
-    console.error('  \x1b[31m✖\x1b[0m Failed to install dependencies. You may need to run it manually.');
+  if (toCopy.length > 0) {
+    console.log('The following will be \x1b[32mCREATED\x1b[0m:');
+    toCopy.forEach(f => console.log(`  + ${f}`));
   }
 
-  console.log('\n🧠 Initializing RAG Knowledge Base...');
-  try {
-    const syncScript = path.join(CWD, 'scripts', 'pre_bounce_sync.sh');
-    if (fs.existsSync(syncScript)) {
-      execSync(`chmod +x "${syncScript}" && "${syncScript}"`, { stdio: 'inherit', cwd: CWD });
-      console.log('  \x1b[32m✓\x1b[0m Knowledge base initialized.');
-    }
-  } catch (err) {
-    console.error('  \x1b[31m✖\x1b[0m Failed to initialize knowledge base. Run ./scripts/pre_bounce_sync.sh manually.');
+  if (toOverwrite.length > 0) {
+    console.log('\nThe following will be \x1b[33mOVERWRITTEN\x1b[0m:');
+    toOverwrite.forEach(f => console.log(`  ! ${f}`));
   }
 
-  // vdoc integration
-  const vdocPlatform = vdocPlatformMap[targetPlatform];
-  if (vdocPlatform) {
-    const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const vdocAnswer = await new Promise(resolve => rl2.question('\n📝 Install vdoc (AI-powered documentation generator)? [y/N] ', resolve));
-    rl2.close();
-
-    if (vdocAnswer.trim().toLowerCase() === 'y' || vdocAnswer.trim().toLowerCase() === 'yes') {
-      console.log(`\n📝 Installing vdoc for ${vdocPlatform}...`);
-      try {
-        execSync(`npx @sandrinio/vdoc install ${vdocPlatform}`, { stdio: 'inherit', cwd: CWD });
-        console.log('  \x1b[32m✓\x1b[0m vdoc installed.');
-      } catch (err) {
-        console.error(`  \x1b[31m✖\x1b[0m Failed to install vdoc. Run manually: npx @sandrinio/vdoc install ${vdocPlatform}`);
+  console.log('');
+
+  askQuestion('Proceed with installation? [y/N] ').then(async answer => {
+    rl.close();
+    const confirmation = answer.trim().toLowerCase();
+
+    if (confirmation !== 'y' && confirmation !== 'yes') {
+      console.log('\n❌ Installation cancelled.\n');
+      process.exit(0);
+    }
+
+    console.log('\n📦 Installing files...');
+
+    mapping.forEach(rule => {
+      const sourcePath = path.join(pkgRoot, rule.src);
+      const destPath = path.join(CWD, rule.dest);
+
+      if (!fs.existsSync(sourcePath)) return;
+
+      const stats = fs.statSync(sourcePath);
+      if (stats.isDirectory()) {
+        fs.mkdirSync(destPath, { recursive: true });
+        fs.cpSync(sourcePath, destPath, { recursive: true, force: true });
+      } else {
+        const destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir)) {
+          fs.mkdirSync(destDir, { recursive: true });
+        }
+        fs.copyFileSync(sourcePath, destPath);
       }
-    } else {
-      console.log(`\n  Skipped. You can install later: npx @sandrinio/vdoc install ${vdocPlatform}`);
+      console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
+    });
+
+    console.log('\n⚙️  Installing dependencies...');
+    try {
+      const deps = ['js-yaml', 'marked', 'commander'];
+      console.log(`  Running: npm install ${deps.join(' ')}`);
+      execSync(`npm install ${deps.join(' ')}`, { stdio: 'inherit', cwd: CWD });
+      console.log('  \x1b[32m✓\x1b[0m Dependencies installed.');
+    } catch (err) {
+      console.error('  \x1b[31m✖\x1b[0m Failed to install dependencies. You may need to run it manually.');
     }
-  }
 
-  console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
-});
+    // vdoc integration
+    const vdocPlatform = vdocPlatformMap[targetPlatform];
+    if (vdocPlatform) {
+      const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const vdocAnswer = await new Promise(resolve => rl2.question('\n📝 Install vdoc (AI-powered documentation generator)? [y/N] ', resolve));
+      rl2.close();
+
+      if (vdocAnswer.trim().toLowerCase() === 'y' || vdocAnswer.trim().toLowerCase() === 'yes') {
+        console.log(`\n📝 Installing vdoc for ${vdocPlatform}...`);
+        try {
+          execSync(`npx @sandrinio/vdoc install ${vdocPlatform}`, { stdio: 'inherit', cwd: CWD });
+          console.log('  \x1b[32m✓\x1b[0m vdoc installed.');
+        } catch (err) {
+          console.error(`  \x1b[31m✖\x1b[0m Failed to install vdoc. Run manually: npx @sandrinio/vdoc install ${vdocPlatform}`);
+        }
+      } else {
+        console.log(`\n  Skipped. You can install later: npx @sandrinio/vdoc install ${vdocPlatform}`);
+      }
+    }
+
+    console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
+  });
+
+} else {
+  // Unknown command fallthrough
+  rl.close();
+  console.error(`Unknown command: ${command}`);
+  displayHelp();
+}