@sandrinio/vbounce 1.8.0 → 1.9.0

package/README.md

@@ -1,246 +1,254 @@
-# 🎯 V-Bounce OS
+# V-Bounce Engine
 
-**Turn your AI coding assistant into a full engineering team.**
+**A structured SDLC framework for AI coding agents.**
 
-*Stop letting your AI code in a vacuum. V-Bounce OS is a structured, agentic framework that enforces a strict Software Development Lifecycle (SDLC) on AI agents like Claude Code, Cursor, Copilot, Gemini, and Codex.*
+V-Bounce Engine turns AI assistants — Claude Code, Cursor, Gemini, Copilot, Codex — into disciplined engineering teams. Instead of letting agents code in a vacuum, it enforces a planning-first workflow with automated quality gates, structured handoffs, and a persistent learning loop.
 
-> *Inspired by the work of Cory Hymel*
+> Inspired by the work of Cory Hymel
 
 ---
 
-## 💡 The Hook: Why V-Bounce OS?
+## How It Works
 
-Multi-agent frameworks are everywhere. But simply putting three agents in a chatroom doesn't write scalable software. When left unchecked, AI coding teams still hallucinate requirements, introduce architectural drift, and break existing patterns because they are disconnected from the truth of what they actually built.
+V-Bounce Engine is built around a **Context Loop** — a closed feedback system that makes agents smarter with each sprint.
 
-**The core differentiator of V-Bounce OS is the Context Loop: Requirements → Bounce Reports → Product Documentation.**
+```
+Plan  ──>  Build  ──>  Bounce  ──>  Document  ──>  Learn
+ │                        │             │              │
+ │                    QA + Arch         │          LESSONS.md
+ │                    gate code     Scribe maps        │
+ │                                  the codebase       │
+ └─────────────────────────────────────────────────────┘
+                  Next sprint reads it all
+```
+
+**Plan.** The Team Lead writes requirements using structured templates (Charter, Epic, Story) before any code is written.
 
-Instead of treating your AI as a solo developer, V-Bounce OS forces distinct, specialized roles (Team Lead, Developer, QA, Architect, Scribe) to communicate exclusively through structured artifacts.
+**Build.** The Developer agent implements each Story in an isolated git worktree and submits an Implementation Report.
 
-1. **Requirements (`product_plans/`)**: The Team Lead defines standard, immutable templates (Charter, Epic, Story) before a single line of code is written.
-2. **Bounce Reports (`.bounce/`)**: During implementation, the QA and Architect agents do not edit code. They run deep codebase audits and emit structured "Bounce Reports" summarizing anti-patterns and regressions. The Developer must fix the issues and run the loop again until the code passes validation. 
-3. **Product Documentation (`vdocs/`)**: The Scribe agent explores the *actual* codebase post-merge and uses our integrated `vdoc` tool to update feature-centric documentation and the semantic `_manifest.json` map. 
+**Bounce.** The QA agent validates against acceptance criteria. The Architect agent audits against your architecture rules. If either fails, the work bounces back to the Developer — up to 3 times before escalating to you. Every failure is tagged with a root cause (`missing_tests`, `adr_violation`, `spec_ambiguity`, etc.) for trend analysis.
 
-The next time an agent writes code, it reads the `_manifest.json` and the `LESSONS.md` file from previous sprints. The context loop closes. Your AI writes better code because it finally understands the reality of your evolving system.
+**Document.** After merge, the Scribe agent maps the actual codebase into semantic product documentation using [vdoc](https://github.com/sandrinio/vdoc) (optional).
+
+**Learn.** Sprint mistakes are recorded in `LESSONS.md`. All agents read it before writing future code. The framework also tracks its own performance — bounce rates, correction tax, recurring failure patterns — and suggests improvements to its own templates and skills.
 
 ---
 
-## 📂 State-Based Folder Structure
+## Quick Start
 
-V-Bounce OS organizes planning documents (`product_plans/`) through a strict state machine based on folder location:
+```bash
+npx @sandrinio/vbounce install claude    # Claude Code
+npx @sandrinio/vbounce install cursor    # Cursor
+npx @sandrinio/vbounce install gemini    # Gemini CLI
+npx @sandrinio/vbounce install codex     # OpenAI Codex
+npx @sandrinio/vbounce install vscode    # GitHub Copilot
+```
 
-- **`strategy/`**: High-level context (Charter, Roadmap, Risk Registry, Release Plans). Frozen during active sprints.
-- **`backlog/`**: Where unassigned work lives. Epics and their child Stories are refined here until selected for a sprint.
-- **`sprints/`**: The active execution workspace. A physical `sprint-XX/` boundary is created and Stories are moved in. Only one sprint is "Active" at a time.
-- **`hotfixes/`**: Trivial, emergency tasks that bypass sprint cycles.
-- **`archive/`**: Immutable history. Finished sprint folders and fully completed Epics are permanently moved here.
+Then verify your setup:
 
----
+```bash
+npx vbounce doctor
+```
 
-## 🛠️ The Tech Stack
+### What gets installed
 
-V-Bounce OS is built to be **local-first, privacy-conscious, and dependency-light**.
+Here's what lands in your repo (example: Claude Code):
 
-- **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.
+```
+your-project/
+├── CLAUDE.md                    # Brain file — teaches the agent the V-Bounce process
+├── .claude/agents/              # Subagent instructions (Claude Code only)
+│   ├── developer.md
+│   ├── qa.md
+│   ├── architect.md
+│   ├── devops.md
+│   └── scribe.md
+├── templates/                   # 9 Markdown + YAML frontmatter templates
+│   ├── charter.md
+│   ├── roadmap.md
+│   ├── epic.md
+│   ├── story.md
+│   ├── sprint.md
+│   ├── delivery_plan.md
+│   ├── sprint_report.md
+│   ├── hotfix.md
+│   └── risk_registry.md
+├── skills/                      # 7 modular skill files (see Skills below)
+│   ├── agent-team/
+│   ├── doc-manager/
+│   ├── lesson/
+│   ├── vibe-code-review/
+│   ├── write-skill/
+│   ├── improve/
+│   └── react-best-practices/   # Example — customize for your stack
+├── scripts/                     # 23 automation scripts (validation, context prep, state)
+└── package.json                 # 3 deps: js-yaml, marked, commander. Nothing else.
+```
+
+Other platforms install the same `templates/`, `skills/`, and `scripts/` — only the brain file differs (`.cursor/rules/`, `GEMINI.md`, `AGENTS.md`, or `.github/copilot-instructions.md`).
+
+Everything is plain Markdown and Node.js. No vector DBs, no embedding models, no background services.
 
 ---
 
-## 🚀 Quick Start
+## Supported Tools
 
-One command to install the entire methodology directly into your AI assistant.
+V-Bounce Engine adapts to each tool's capabilities:
 
-```bash
-# For Claude Code
-npx @sandrinio/vbounce install claude
+| Tier | Tool | How it works |
+|------|------|-------------|
+| 1 | Claude Code | Full orchestration — spawns subagents for each role, manages state, runs all CLI commands |
+| 2 | Gemini CLI, Codex | Single-agent mode — follows the bounce loop sequentially, full CLI access |
+| 3 | Cursor | Role-specific context injection via `.cursor/rules/` MDC files |
+| 4 | Copilot, Windsurf | Awareness mode — checklist-driven, reads state, safe CLI operations |
 
-# For Cursor
-npx @sandrinio/vbounce install cursor
+---
 
-# For Gemini / Antigravity
-npx @sandrinio/vbounce install gemini
+## The Bounce Loop
 
-# For Copilot / VS Code
-npx @sandrinio/vbounce install vscode
+This is the core execution cycle for every Story:
 
-# For OpenAI Codex
-npx @sandrinio/vbounce install codex
+```
+         Developer                QA                 Architect            DevOps
+            │                     │                      │                  │
+  Writes code in worktree         │                      │                  │
+  Submits Implementation  ──────> │                      │                  │
+  Report                   Validates against       (waits for QA)          │
+                           acceptance criteria           │                  │
+                                  │                      │                  │
+                           PASS ──────────────────────>  │                  │
+                           FAIL ──> bounces back    Audits against          │
+                                    to Developer    ADRs + safe zone        │
+                                                         │                  │
+                                                  PASS ──────────────────>  │
+                                                  FAIL ──> bounces back  Merges worktree
+                                                           to Developer  into main branch
 ```
 
-### 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, 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 3 failed bounces on either gate, the Story escalates to you for intervention.
 
-After installing, run `vbounce doctor` to verify your setup is complete.
+Each FAIL report includes a `root_cause` tag that feeds into cross-sprint trend analysis via `vbounce trends`.
 
 ---
 
-## 🛠️ The `vbounce` CLI
+## Skills
 
-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.
+Skills are modular markdown instructions the Team Lead invokes automatically during the SDLC:
 
-```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
-```
+| Skill | Purpose |
+|-------|---------|
+| `agent-team` | Spawns temporary sub-agents (Dev, QA, Architect, DevOps, Scribe) to parallelize work |
+| `doc-manager` | Enforces the document hierarchy for Epics and Stories |
+| `lesson` | Extracts mistakes from sprints into `LESSONS.md` |
+| `vibe-code-review` | Runs Quick Scan or Deep Audit against acceptance criteria and architecture rules |
+| `write-skill` | Allows the Team Lead to author new skills when the team encounters a recurring problem |
+| `improve` | Self-improvement loop — reads agent friction signals across sprints and proposes framework changes (with your approval) |
+| `react-best-practices` | Example tech-stack skill — customize this for your own stack |
 
 ---
 
-## 🔄 State Management & Crash Recovery
+## State Management
 
-V-Bounce OS tracks sprint state in `.bounce/state.json` — a machine-readable snapshot that survives context resets and session interruptions.
+Sprint state lives 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"
+      "worktree": ".worktrees/STORY-001-01-login"
     }
   }
 }
 ```
 
-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.
+When a session starts, the Team Lead reads `state.json` to resume exactly where the sprint left off.
 
 ---
 
-## 📊 Self-Improvement Loop
+## CLI Reference
 
-V-Bounce OS tracks its own performance and suggests improvements automatically.
+```bash
+# Sprint lifecycle
+vbounce sprint init S-01 D-01         # Initialize sprint
+vbounce sprint close S-01             # Validate, archive, close
 
-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.
+# Story lifecycle
+vbounce story complete STORY-ID       # Mark story done, update state
 
----
+# State management
+vbounce state show                    # Print current state
+vbounce state update STORY-ID STATE   # Update story state
 
-## 🔧 Tool Tier Model
+# Context preparation
+vbounce prep sprint S-01              # Sprint context pack
+vbounce prep qa STORY-ID              # QA context pack
+vbounce prep arch STORY-ID            # Architect context pack
 
-V-Bounce OS supports four tiers of AI tools with dedicated brain files for each.
+# Validation
+vbounce validate report <file>        # Validate report YAML
+vbounce validate state                # Validate state.json schema
+vbounce validate sprint S-01          # Validate sprint plan
+vbounce validate ready STORY-ID       # Pre-bounce readiness gate
 
-| 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 |
+# Self-improvement
+vbounce trends                        # Cross-sprint trend analysis
+vbounce suggest S-01                  # Generate improvement suggestions
 
-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
+# Health check
+vbounce doctor                        # Verify setup
 ```
 
 ---
 
-### 🧰 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:
+## Runtime Structure
 
-| Skill | Role | Purpose |
-|-------|------|---------|
-| `agent-team` | Lead | Spawns temporary sub-agents (Dev, QA, DevOps) to parallelize complex tasks without losing context. |
-| `doc-manager` | All | Enforces the strict hierarchy for managing Epic and Story documents *(Charter is optional, used only for new projects or brainstorming)*. |
-| `lesson` | Lead | Extracts mistakes made during Sprints and updates `LESSONS.md` to prevent future regressions. |
-| `react-best-practices` | Developer | A strict set of frontend execution rules the Developer must follow during implementation. <mark>*(Note: This skill serves as a template and must be customized by the human according to the specific tech stack being used.)*</mark> |
-| `vibe-code-review` | QA/Architect | Runs distinct review modes (Quick Scan, Deep Audit) to validate code against Acceptance Criteria and Architecture rules. |
-| `write-skill` | Lead | Allows the Team Lead to autonomously write and deploy entirely *new* skills if the team repeatedly encounters a novel problem. |
-| `improve` | Lead | The framework's self-improvement loop. Reads agent friction signals from sprint retros and proposes targeted changes to templates, skills, brain files, and scripts — with human approval. |
+As you use V-Bounce Engine, the framework creates these directories to manage your sprints:
 
----
-
-## ⚙️ A Skill-Driven Methodology
-
-V-Bounce OS enforces a strict hierarchy. No code is written without a plan, and no task is executed without invoking the proper skills.
-
-### 1. Planning Layer
-You use the bundled templates to define the work.
-`Charter ➔ Roadmap ➔ Epic ➔ Story`
+```
+product_plans/                   # Created when you start planning
+  strategy/                      #   Charter, Roadmap, Risk Registry (frozen during sprints)
+  backlog/                       #   Epics and Stories awaiting sprint assignment
+  sprints/                       #   Active sprint workspace (one active at a time)
+  hotfixes/                      #   Emergency fixes that bypass sprint cycles
+  archive/                       #   Completed sprints and Epics (immutable history)
 
-### 2. The Bounce Loop (Implementation)
-Once a Story is ready, you kick off the AI sprint.
-1. The **Developer** AI writes the code and submits an Implementation Report.
-2. The **QA** AI reads the report and tests it against the Story's requirements. If it fails, it bounces back. (Max 3 attempts before escalating to you).
-3. The **Architect** AI audits the successful QA build against your Safe Zone and Architecture Decision Records (ADRs).
-4. Only when both gates pass does the **DevOps** AI merge the isolated worktree into your main branch.
+.bounce/                         # Created on first sprint init
+  state.json                     #   Machine-readable sprint state (crash recovery)
+  reports/                       #   QA and Architect bounce reports
+  improvement-log.md             #   Tracked improvement suggestions
 
-### 3. End of Sprint Reports
-When a sprint concludes, V-Bounce OS generates structured reports so human reviewers can audit the work without reading every line of code:
-- **Sprint Report**: A comprehensive summary by the Team Lead detailing what was delivered, execution metrics, story results, and a retro of what went wrong.
-- **Sprint Release Report**: The DevOps agent's log of the merge process to the main branch, environment changes, and post-merge test validations.
-- **Scribe Report**: The Scribe agent's complete audit of which product documentation files were generated, updated, or removed (using `vdoc`) to map the new codebase reality.
+.worktrees/                      # Git worktrees for isolated story branches
 
-### 4. Progressive Learning (`LESSONS.md`)
-Every time the AI makes a mistake during the Bounce Loop, it flags the issue. During the sprint retrospective, these mistakes are recorded in `LESSONS.md`—a permanent project memory that all agents read *before* writing any future code. **Your AI gets smarter about your specific codebase with every single sprint.**
+LESSONS.md                       # Accumulated mistakes — agents read this before coding
+```
 
-### 5. Self-Improving Framework (`improve` skill)
-V-Bounce OS doesn't just improve your code — it improves *itself*. Every agent report includes a **Process Feedback** section where agents flag friction with the framework: a template missing a critical field, a handoff that lost context, a RAG query that returned irrelevant results, or a skill instruction that was unclear.
+---
 
-These signals are aggregated into the Sprint Report's **Framework Self-Assessment** — categorized by area (Templates, Handoffs, RAG Pipeline, Skills, Process Flow, Tooling) with severity ratings and suggested fixes.
+## End-of-Sprint Reports
 
-After every 2-3 sprints, the Team Lead runs the `improve` skill which:
-1. Reads accumulated friction signals across sprints
-2. Identifies recurring patterns (same complaint from multiple agents = real problem)
-3. Proposes specific, targeted changes to templates, skills, brain files, or scripts
-4. **Applies nothing without your approval** — you review every proposed change
+When a sprint concludes, V-Bounce Engine generates three structured reports:
 
-The result: templates get sharper, handoffs get cleaner, skills get more precise, and the bounce loop gets tighter — all driven by the agents who actually use the framework every day.
+- **Sprint Report** — what was delivered, execution metrics (tokens, cost, bounce rates), story results, lessons learned, and a retrospective.
+- **Release Report** — the DevOps agent's merge log, environment changes, and post-merge validations.
+- **Scribe Report** — which product documentation was created, updated, or flagged as stale.
 
 ---
 
-## 🔍 Keywords for Searchability
-`ai coding agent` `claude code` `cursor` `github copilot` `gemini` `openai codex` `software development lifecycle` `sdlc` `ai software engineer` `autonomous coding` `agentic framework` `software architecture` `ai team` `vdoc` `ai documentation` `prompt engineering`
+## Documentation
 
----
+- [Epic template and structure](templates/epic.md)
+- [Hotfix edge cases](docs/HOTFIX_EDGE_CASES.md)
+- [vdoc integration](https://github.com/sandrinio/vdoc)
+
+## Contributing
 
-## 📖 Documentation
-- [How to structure an Epic](templates/epic.md)
-- [How the Bounce Loop handles Hotfixes](docs/HOTFIX_EDGE_CASES.md)
-- [Integrating with vdoc](https://github.com/sandrinio/vdoc)
+Contributions, issues, and feature requests are welcome. Check the [issues page](https://github.com/sandrinio/v-bounce-engine/issues).
 
-## 🤝 Contributing
-Contributions, issues, and feature requests are welcome! Feel free to check the [issues page]().
+## License
 
-## 📝 License
-This project is [MIT](LICENSE) licensed.
+[MIT](LICENSE)

package/bin/vbounce.mjs

@@ -2,6 +2,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import crypto from 'crypto';
 import { fileURLToPath } from 'url';
 import readline from 'readline';
 
@@ -65,10 +66,10 @@ const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve
 
 function displayHelp() {
   console.log(`
-V-Bounce OS CLI
+V-Bounce Engine CLI
 
 Usage:
-  vbounce install <platform>           Install V-Bounce OS into a project
+  vbounce install <platform>           Install V-Bounce Engine 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,...]
@@ -227,6 +228,7 @@ if (command === 'install') {
   }
 
   const CWD = process.cwd();
+  const pkgVersion = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
 
   // Map vbounce platform names to vdoc platform names
   const vdocPlatformMap = {
@@ -287,34 +289,208 @@ if (command === 'install') {
     displayHelp();
   }
 
-  console.log(`\n🚀 Preparing to install V-Bounce OS for \x1b[36m${targetPlatform}\x1b[0m...\n`);
+  // ---------------------------------------------------------------------------
+  // Upgrade-safe install helpers
+  // ---------------------------------------------------------------------------
 
-  const toCopy = [];
-  const toOverwrite = [];
+  const META_PATH = path.join(CWD, '.bounce', 'install-meta.json');
+  const BACKUPS_DIR = path.join(CWD, '.bounce', 'backups');
 
-  mapping.forEach(rule => {
-    const sourcePath = path.join(pkgRoot, rule.src);
-    const destPath = path.join(CWD, rule.dest);
+  /** Compute MD5 hash of a single file's contents. */
+  function computeFileHash(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('md5').update(content).digest('hex');
+  }
 
-    if (!fs.existsSync(sourcePath)) {
-      return; // Source does not exist internally, skip
+  /** Compute a combined hash for a directory by hashing all files sorted by relative path. */
+  function computeDirHash(dirPath) {
+    const hash = crypto.createHash('md5');
+    const entries = [];
+
+    function walk(dir, rel) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        const relPath = path.join(rel, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath, relPath);
+        } else {
+          entries.push({ relPath, fullPath });
+        }
+      }
     }
 
-    if (fs.existsSync(destPath)) {
-      toOverwrite.push(rule.dest);
-    } else {
-      toCopy.push(rule.dest);
+    walk(dirPath, '');
+    entries.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    for (const e of entries) {
+      hash.update(e.relPath);
+      hash.update(fs.readFileSync(e.fullPath));
     }
-  });
+    return hash.digest('hex');
+  }
+
+  /** Compute hash for a path (file or directory). */
+  function computeHash(p) {
+    const stats = fs.statSync(p);
+    return stats.isDirectory() ? computeDirHash(p) : computeFileHash(p);
+  }
+
+  /** Count files in a path (1 for a file, recursive count for a directory). */
+  function countFiles(p) {
+    const stats = fs.statSync(p);
+    if (!stats.isDirectory()) return 1;
+    let count = 0;
+    function walk(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) walk(path.join(dir, entry.name));
+        else count++;
+      }
+    }
+    walk(p);
+    return count;
+  }
+
+  /** Read install-meta.json, returns null if missing. */
+  function readInstallMeta() {
+    if (!fs.existsSync(META_PATH)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(META_PATH, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  /** Write install-meta.json. */
+  function writeInstallMeta(version, platform, files, hashes) {
+    const meta = {
+      version,
+      platform,
+      installed_at: new Date().toISOString(),
+      files,
+      hashes
+    };
+    fs.mkdirSync(path.dirname(META_PATH), { recursive: true });
+    fs.writeFileSync(META_PATH, JSON.stringify(meta, null, 2) + '\n');
+  }
+
+  /** Backup files to .bounce/backups/<version>/. Removes previous backup first. */
+  function backupFiles(version, paths) {
+    // Remove previous backup (keep only one)
+    if (fs.existsSync(BACKUPS_DIR)) {
+      for (const entry of fs.readdirSync(BACKUPS_DIR, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          fs.rmSync(path.join(BACKUPS_DIR, entry.name), { recursive: true, force: true });
+        }
+      }
+    }
+
+    const backupDir = path.join(BACKUPS_DIR, version);
+    fs.mkdirSync(backupDir, { recursive: true });
+
+    for (const relPath of paths) {
+      const src = path.join(CWD, relPath);
+      const dest = path.join(backupDir, relPath);
+
+      if (!fs.existsSync(src)) continue;
+
+      const stats = fs.statSync(src);
+      if (stats.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        fs.cpSync(src, dest, { recursive: true });
+      } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+      }
+    }
+
+    return backupDir;
+  }
+
+  /**
+   * Classify files into unchanged, modified, and newFiles.
+   * - unchanged: dest exists and matches what was installed (safe to overwrite)
+   * - modified: dest exists but differs from what was installed (user changed it)
+   * - newFiles: dest does not exist
+   */
+  function classifyFiles(mappingRules, meta) {
+    const unchanged = [];
+    const modified = [];
+    const newFiles = [];
+
+    for (const rule of mappingRules) {
+      const sourcePath = path.join(pkgRoot, rule.src);
+      const destPath = path.join(CWD, rule.dest);
+
+      if (!fs.existsSync(sourcePath)) continue;
 
-  if (toCopy.length > 0) {
-    console.log('The following will be \x1b[32mCREATED\x1b[0m:');
-    toCopy.forEach(f => console.log(`  + ${f}`));
+      if (!fs.existsSync(destPath)) {
+        newFiles.push(rule);
+        continue;
+      }
+
+      // Dest exists — classify as unchanged or modified
+      if (!meta || !meta.hashes || !meta.hashes[rule.dest]) {
+        // No metadata (first upgrade) — treat as modified to be safe
+        modified.push(rule);
+        continue;
+      }
+
+      const currentHash = computeHash(destPath);
+      const installedHash = meta.hashes[rule.dest];
+
+      if (currentHash === installedHash) {
+        unchanged.push(rule);
+      } else {
+        modified.push(rule);
+      }
+    }
+
+    return { unchanged, modified, newFiles };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Begin install flow
+  // ---------------------------------------------------------------------------
+
+  const meta = readInstallMeta();
+  const isUpgrade = meta !== null;
+
+  if (isUpgrade) {
+    console.log(`\n🚀 V-Bounce Engine \x1b[36m${pkgVersion}\x1b[0m (upgrading from \x1b[33m${meta.version}\x1b[0m)\n`);
+  } else {
+    console.log(`\n🚀 Preparing to install V-Bounce Engine \x1b[36m${pkgVersion}\x1b[0m for \x1b[36m${targetPlatform}\x1b[0m...\n`);
+  }
+
+  const { unchanged, modified, newFiles } = classifyFiles(mapping, meta);
+
+  if (unchanged.length > 0) {
+    console.log('Will update (unchanged by you):');
+    for (const rule of unchanged) {
+      const destPath = path.join(CWD, rule.dest);
+      const n = countFiles(destPath);
+      const label = n > 1 ? `(${n} files)` : '';
+      console.log(`  \x1b[32m✓\x1b[0m ${rule.dest} ${label}`);
+    }
   }
 
-  if (toOverwrite.length > 0) {
-    console.log('\nThe following will be \x1b[33mOVERWRITTEN\x1b[0m:');
-    toOverwrite.forEach(f => console.log(`  ! ${f}`));
+  if (modified.length > 0) {
+    const backupLabel = isUpgrade ? `.bounce/backups/${meta.version}/` : '.bounce/backups/pre-install/';
+    console.log(`\nModified by you (backed up to ${backupLabel}):`);
+    for (const rule of modified) {
+      console.log(`  \x1b[33m⚠\x1b[0m ${rule.dest}`);
+    }
+  }
+
+  if (newFiles.length > 0) {
+    console.log('\nNew in this version:');
+    for (const rule of newFiles) {
+      console.log(`  \x1b[32m+\x1b[0m ${rule.dest}`);
+    }
+  }
+
+  if (unchanged.length === 0 && modified.length === 0 && newFiles.length === 0) {
+    rl.close();
+    console.log('Nothing to install — all source files are missing from the package.');
+    process.exit(0);
   }
 
   console.log('');
@@ -328,13 +504,23 @@ if (command === 'install') {
       process.exit(0);
     }
 
+    // Backup modified files before overwriting
+    if (modified.length > 0) {
+      const backupVersion = isUpgrade ? meta.version : 'pre-install';
+      const backupDir = backupFiles(backupVersion, modified.map(r => r.dest));
+      console.log(`\n📂 Backed up modified files to ${path.relative(CWD, backupDir)}/`);
+    }
+
     console.log('\n📦 Installing files...');
 
-    mapping.forEach(rule => {
+    const installedFiles = [];
+    const hashes = {};
+
+    for (const rule of [...unchanged, ...modified, ...newFiles]) {
       const sourcePath = path.join(pkgRoot, rule.src);
       const destPath = path.join(CWD, rule.dest);
 
-      if (!fs.existsSync(sourcePath)) return;
+      if (!fs.existsSync(sourcePath)) continue;
 
       const stats = fs.statSync(sourcePath);
       if (stats.isDirectory()) {
@@ -347,8 +533,16 @@ if (command === 'install') {
         }
         fs.copyFileSync(sourcePath, destPath);
       }
+
+      // Record hash of what we just installed (from source)
+      hashes[rule.dest] = computeHash(sourcePath);
+      installedFiles.push(rule.dest);
       console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
-    });
+    }
+
+    // Write install metadata
+    writeInstallMeta(pkgVersion, targetPlatform, installedFiles, hashes);
+    console.log(`  \x1b[32m✓\x1b[0m .bounce/install-meta.json`);
 
     console.log('\n⚙️  Installing dependencies...');
     try {
@@ -380,7 +574,22 @@ if (command === 'install') {
       }
     }
 
-    console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
+    // Auto-run doctor to verify installation
+    console.log('\n🩺 Running doctor to verify installation...');
+    const doctorPath = path.join(CWD, 'scripts', 'doctor.mjs');
+    if (fs.existsSync(doctorPath)) {
+      const result = spawnSync(process.execPath, [doctorPath], {
+        stdio: 'inherit',
+        cwd: CWD
+      });
+      if (result.status !== 0) {
+        console.error('\n  \x1b[33m⚠\x1b[0m Doctor reported issues. Review the output above.');
+      }
+    } else {
+      console.log('  \x1b[33m⚠\x1b[0m Doctor script not found — skipping verification.');
+    }
+
+    console.log('\n✅ V-Bounce Engine successfully installed! Welcome to the team.\n');
   });
 
 } else {

package/brains/AGENTS.md

@@ -1,10 +1,10 @@
-# V-Bounce OS — Agent Brain (Codex CLI)
+# V-Bounce Engine — Agent Brain (Codex CLI)
 
-> This file configures OpenAI Codex CLI to operate within the V-Bounce OS framework.
+> This file configures OpenAI Codex CLI to operate within the V-Bounce Engine framework.
 
 ## Identity
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+You are an AI coding agent operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
 
 You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
 
@@ -106,7 +106,7 @@ Bouncing → Escalated (3+ failures)
 ## Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files (this file)
 ├── templates/       — Document templates (immutable)
 ├── skills/          — Agent skills (SKILL.md files)

package/brains/CHANGELOG.md

@@ -1,4 +1,4 @@
-# V-Bounce OS Brains & Skills Changelog
+# V-Bounce Engine Brains & Skills Changelog
 
 This log tracks modifications to the core agentic framework (e.g., `brains/`, `skills/`). 
 Per **Rule 13: Framework Integrity**, anytime an entry is made here, all tool-specific brain files must be reviewed for consistency.
@@ -21,7 +21,7 @@ Per **Rule 13: Framework Integrity**, anytime an entry is made here, all tool-sp
 - **Modified**: `.gitignore` — Removed `.bounce/.lancedb/` entry.
 - **Rationale**: Modern LLMs have 200K+ token context windows. The prep scripts (`vbounce prep sprint/qa/arch`) + LESSONS.md graduation provide targeted, deterministic context without embedding models, sync steps, or heavy dependencies. Removes ~50MB of node_modules and eliminates the most common setup failure point.
 
-## [2026-03-12] — V-Bounce OS Optimization Plan (12-Change Batch)
+## [2026-03-12] — V-Bounce Engine Optimization Plan (12-Change Batch)
 
 ### State Management (Change #1)
 - **Added**: `.bounce/state.json` — machine-readable sprint state snapshot for crash recovery. Tracks sprint_id, delivery_id, current_phase, last_action, and per-story state (V-Bounce state, bounce counts, worktree path, updated_at).

package/brains/CLAUDE.md

@@ -1,10 +1,10 @@
-# V-Bounce OS — Agent Brain
+# V-Bounce Engine — Agent Brain
 
-> This file configures Claude Code to operate within the V-Bounce OS framework.
+> This file configures Claude Code to operate within the V-Bounce Engine framework.
 
 ## Identity
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+You are an AI coding agent operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
 
 You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
 
@@ -127,7 +127,7 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ## Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files (this file)
 ├── templates/       — Document templates (immutable)
 ├── skills/          — Agent skills (SKILL.md files)

package/brains/GEMINI.md

@@ -1,11 +1,11 @@
-# V-Bounce OS — Agent Brain
+# V-Bounce Engine — Agent Brain
 
-> This file configures Gemini CLI and Antigravity to operate within the V-Bounce OS framework.
+> This file configures Gemini CLI and Antigravity to operate within the V-Bounce Engine framework.
 > Place at project root for Gemini CLI. For Antigravity, also copy skills to `.agents/skills/`.
 
 ## Identity
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+You are an AI coding agent operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
 
 You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
 
@@ -27,7 +27,7 @@ For Antigravity: copy skills to `.agents/skills/` for workspace-scoped discovery
 
 ## CLI Commands
 
-V-Bounce OS ships a CLI. Use these commands for state management instead of editing files manually:
+V-Bounce Engine ships a CLI. Use these commands for state management instead of editing files manually:
 
 ```bash
 # Sprint management
@@ -149,7 +149,7 @@ Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architec
 ## Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files (this file)
 ├── templates/       — Document templates (immutable)
 ├── skills/          — Agent skills (SKILL.md files)

package/brains/SETUP.md

@@ -1,13 +1,13 @@
-# Adding V-Bounce OS to Any Repo
+# Adding V-Bounce Engine to Any Repo
 
-Step-by-step guide to set up V-Bounce OS in an existing or new project.
+Step-by-step guide to set up V-Bounce Engine in an existing or new project.
 
 ## Prerequisites
 
-- A git repository (V-Bounce OS uses branches and worktrees)
+- A git repository (V-Bounce Engine uses branches and worktrees)
 - Node.js installed (for validation and semantic search scripts)
 - At least one supported AI coding tool installed
-- The V-Bounce OS folder (this repo)
+- The V-Bounce Engine folder (this repo)
 
 ## Step 1: Copy the Framework
 
@@ -15,11 +15,11 @@ Copy the `skills/` and `templates/` directories into your project root:
 
 ```bash
 # From your project root
-cp -r /path/to/V-Bounce-OS/skills/ ./skills/
-cp -r /path/to/V-Bounce-OS/templates/ ./templates/
+cp -r /path/to/V-Bounce-Engine/skills/ ./skills/
+cp -r /path/to/V-Bounce-Engine/templates/ ./templates/
 ```
 
-These are the core of V-Bounce OS — skills define agent behavior, templates define document structure.
+These are the core of V-Bounce Engine — skills define agent behavior, templates define document structure.
 
 ## Step 2: Deploy Brain File for Your AI Tool
 
@@ -27,32 +27,32 @@ Pick the tool you're using and deploy the corresponding brain file:
 
 ### Claude Code
 ```bash
-cp /path/to/V-Bounce-OS/brains/CLAUDE.md ./CLAUDE.md
+cp /path/to/V-Bounce-Engine/brains/CLAUDE.md ./CLAUDE.md
 
 # Deploy subagent configs
 mkdir -p .claude/agents
-cp /path/to/V-Bounce-OS/brains/claude-agents/*.md .claude/agents/
+cp /path/to/V-Bounce-Engine/brains/claude-agents/*.md .claude/agents/
 ```
 
 ### Codex CLI (OpenAI)
 ```bash
-cp /path/to/V-Bounce-OS/brains/AGENTS.md ./AGENTS.md
+cp /path/to/V-Bounce-Engine/brains/AGENTS.md ./AGENTS.md
 ```
 
 ### Cursor
 ```bash
 mkdir -p .cursor/rules
-cp /path/to/V-Bounce-OS/brains/cursor-rules/*.mdc .cursor/rules/
+cp /path/to/V-Bounce-Engine/brains/cursor-rules/*.mdc .cursor/rules/
 ```
 
 ### Gemini CLI
 ```bash
-cp /path/to/V-Bounce-OS/brains/GEMINI.md ./GEMINI.md
+cp /path/to/V-Bounce-Engine/brains/GEMINI.md ./GEMINI.md
 ```
 
 ### Antigravity
 ```bash
-cp /path/to/V-Bounce-OS/brains/GEMINI.md ./GEMINI.md
+cp /path/to/V-Bounce-Engine/brains/GEMINI.md ./GEMINI.md
 cp -r skills/ .agents/skills/
 ```
 
@@ -141,7 +141,7 @@ your-project/
 ├── CLAUDE.md                  ← brain file (or AGENTS.md / GEMINI.md)
 ├── LESSONS.md                 ← project-specific rules (grows over time)
 ├── .claude/agents/            ← subagent configs (Claude Code only)
-├── skills/                    ← V-Bounce OS skills
+├── skills/                    ← V-Bounce Engine skills
 │   ├── agent-team/
 │   ├── doc-manager/
 │   ├── lesson/
@@ -192,4 +192,4 @@ brains/
     └── vbounce-docs.mdc
 ```
 
-Each brain file is self-contained and authoritative for its tool. When updating V-Bounce OS rules, update each brain file directly and keep them in sync.
+Each brain file is self-contained and authoritative for its tool. When updating V-Bounce Engine rules, update each brain file directly and keep them in sync.

package/brains/claude-agents/architect.md

@@ -5,7 +5,7 @@ tools: Read, Glob, Grep, Bash
 disallowedTools: Edit, Write
 ---
 
-You are the **Architect Agent** in the V-Bounce OS framework.
+You are the **Architect Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Audit the codebase for structural integrity, standards compliance, and long-term sustainability. You review — you do not implement. You are the last gate before human review.

package/brains/claude-agents/developer.md

@@ -5,7 +5,7 @@ tools: Read, Edit, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **Developer Agent** in the V-Bounce OS framework.
+You are the **Developer Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Implement features and fix bugs as specified in Story documents. You write code — nothing more, nothing less.

package/brains/claude-agents/devops.md

@@ -5,7 +5,7 @@ tools: Read, Edit, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **DevOps Agent** in the V-Bounce OS framework.
+You are the **DevOps Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 

package/brains/claude-agents/qa.md

@@ -5,7 +5,7 @@ tools: Read, Bash, Glob, Grep
 disallowedTools: Edit, Write
 ---
 
-You are the **QA Agent** in the V-Bounce OS framework.
+You are the **QA Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 Validate that the Developer's implementation meets the Story's acceptance criteria. You test — you do not fix. If something fails, you write a detailed bug report and send it back.

package/brains/claude-agents/scribe.md

@@ -5,7 +5,7 @@ tools: Read, Write, Bash, Glob, Grep
 model: sonnet
 ---
 
-You are the **Scribe Agent** in the V-Bounce OS framework.
+You are the **Scribe Agent** in the V-Bounce Engine framework.
 
 ## Your Role
 

package/brains/copilot/copilot-instructions.md

@@ -1,10 +1,10 @@
-# V-Bounce OS — GitHub Copilot Instructions
+# V-Bounce Engine — GitHub Copilot Instructions
 
-This project uses **V-Bounce OS** — a structured AI-agent development framework.
+This project uses **V-Bounce Engine** — a structured AI-agent development framework.
 
 ## What This Means for You
 
-You are operating in Tier 4 (Awareness) mode. You understand the project uses V-Bounce OS but you do not orchestrate agents.
+You are operating in Tier 4 (Awareness) mode. You understand the project uses V-Bounce Engine but you do not orchestrate agents.
 
 ## Key Behaviors
 

package/brains/cursor-rules/vbounce-docs.mdc

@@ -1,10 +1,10 @@
 ---
-description: V-Bounce OS document hierarchy — templates, locations, and report formats
+description: V-Bounce Engine document hierarchy — templates, locations, and report formats
 globs:
 alwaysApply: false
 ---
 
-# V-Bounce OS — Document & Report Reference
+# V-Bounce Engine — Document & Report Reference
 
 ## Document Locations
 

package/brains/cursor-rules/vbounce-process.mdc

@@ -1,12 +1,12 @@
 ---
-description: V-Bounce OS process rules — the core framework for AI-assisted software development
+description: V-Bounce Engine process rules — the core framework for AI-assisted software development
 globs:
 alwaysApply: true
 ---
 
-# V-Bounce OS — Process Rules
+# V-Bounce Engine — Process Rules
 
-You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents.
+You are an AI coding agent operating within **V-Bounce Engine** — a structured system for planning, implementing, and validating software using AI agents.
 
 ## The V-Bounce Process
 

package/brains/cursor-rules/vbounce-rules.mdc

@@ -1,10 +1,10 @@
 ---
-description: V-Bounce OS critical rules — mandatory constraints for all implementation work
+description: V-Bounce Engine critical rules — mandatory constraints for all implementation work
 globs:
 alwaysApply: true
 ---
 
-# V-Bounce OS — Critical Rules
+# V-Bounce Engine — Critical Rules
 
 ## Before Writing Code
 1. **Read LESSONS.md** at the project root. Every time. No exceptions.

package/brains/windsurf/.windsurfrules

@@ -1,6 +1,6 @@
-# V-Bounce OS — Windsurf Rules
+# V-Bounce Engine — Windsurf Rules
 
-This project uses V-Bounce OS. You are operating in Tier 4 (Awareness) mode.
+This project uses V-Bounce Engine. You are operating in Tier 4 (Awareness) mode.
 
 ## Before Writing Code
 

package/docs/HOTFIX_EDGE_CASES.md

@@ -1,6 +1,6 @@
 # Hotfix Workflow: Edge Cases & Mitigations
 
-This document outlines the critical edge cases, failure modes, and required mitigations for the **V-Bounce OS Hotfix (L1 Trivial)** workflow.
+This document outlines the critical edge cases, failure modes, and required mitigations for the **V-Bounce Engine Hotfix (L1 Trivial)** workflow.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.8.0",
-  "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
+  "version": "1.9.0",
+  "description": "V-Bounce Engine: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {
     "vbounce": "./bin/vbounce.mjs"
@@ -11,7 +11,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sandrinio/v-bounce-os.git"
+    "url": "git+https://github.com/sandrinio/v-bounce-engine.git"
   },
   "keywords": [
     "ai",
@@ -28,9 +28,9 @@
   "author": "sandrinio",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/sandrinio/v-bounce-os/issues"
+    "url": "https://github.com/sandrinio/v-bounce-engine/issues"
   },
-  "homepage": "https://github.com/sandrinio/v-bounce-os#readme",
+  "homepage": "https://github.com/sandrinio/v-bounce-engine#readme",
   "files": [
     "bin",
     "brains",

package/scripts/doctor.mjs

@@ -2,7 +2,7 @@
 
 /**
  * doctor.mjs
- * V-Bounce OS Health Check — validates all configs, templates, state files
+ * V-Bounce Engine Health Check — validates all configs, templates, state files
  * Usage: vbounce doctor
  */
 
@@ -42,7 +42,7 @@ const templatesDir = path.join(ROOT, 'templates');
 let templateCount = 0;
 for (const t of requiredTemplates) {
   if (fs.existsSync(path.join(templatesDir, t))) templateCount++;
-  else fail(`templates/${t} missing`, `Create from V-Bounce OS template`);
+  else fail(`templates/${t} missing`, `Create from V-Bounce Engine template`);
 }
 if (templateCount === requiredTemplates.length) pass(`templates/ complete (${templateCount}/${requiredTemplates.length})`);
 
@@ -130,7 +130,7 @@ if (fs.existsSync(path.join(ROOT, 'vbounce.config.json'))) {
 }
 
 // Print results
-console.log('\nV-Bounce OS Health Check');
+console.log('\nV-Bounce Engine Health Check');
 console.log('========================');
 checks.forEach(c => console.log(c));
 console.log('');

package/scripts/hotfix_manager.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# V-Bounce OS: Hotfix Manager
+# V-Bounce Engine: Hotfix Manager
 # Handles edge cases for L1 Trivial tasks to save tokens and ensure framework integrity.
 
 set -euo pipefail
@@ -14,7 +14,7 @@ REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
 COMMAND="${1:-}"
 
 function show_help {
-    echo "V-Bounce OS — Hotfix Manager"
+    echo "V-Bounce Engine — Hotfix Manager"
     echo ""
     echo "Usage: ./scripts/hotfix_manager.sh <command> [args]"
     echo ""

package/scripts/init_gate_config.sh

@@ -17,7 +17,7 @@ YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 
-echo -e "${CYAN}V-Bounce OS Gate Config Initializer${NC}"
+echo -e "${CYAN}V-Bounce Engine Gate Config Initializer${NC}"
 echo -e "Project: ${PROJECT_PATH}"
 echo ""
 

package/scripts/pre_gate_common.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# pre_gate_common.sh — Shared gate check functions for V-Bounce OS
+# pre_gate_common.sh — Shared gate check functions for V-Bounce Engine
 # Sourced by pre_gate_runner.sh. Never run directly.
 
 set -euo pipefail

package/scripts/pre_gate_runner.sh

@@ -31,7 +31,7 @@ fi
 # Resolve to absolute path
 WORKTREE_PATH="$(cd "$WORKTREE_PATH" && pwd)"
 
-echo -e "${CYAN}V-Bounce OS Pre-Gate Scanner${NC}"
+echo -e "${CYAN}V-Bounce Engine Pre-Gate Scanner${NC}"
 echo -e "Gate: ${YELLOW}${GATE_TYPE}${NC}"
 echo -e "Target: ${WORKTREE_PATH}"
 echo ""

package/scripts/suggest_improvements.mjs

@@ -159,7 +159,7 @@ suggestions.push({
   num: itemNum++,
   category: 'Health',
   title: 'Run vbounce doctor',
-  detail: 'Verify the V-Bounce OS installation is healthy after this sprint.',
+  detail: 'Verify the V-Bounce Engine installation is healthy after this sprint.',
   recommendation: 'Run: `vbounce doctor` — checks brain files, templates, scripts, state.json validity.',
   target: 'scripts/doctor.mjs',
   effort: 'Trivial',

package/scripts/validate_report.mjs

@@ -3,7 +3,7 @@
 /**
  * validate_report.mjs
  * 
- * Strict YAML Frontmatter validation for V-Bounce OS Agent Reports.
+ * Strict YAML Frontmatter validation for V-Bounce Engine Agent Reports.
  * Fails loudly if an agent hallucinates formatting or omits required fields,
  * so the orchestrator can bounce the prompt back.
  */

package/scripts/verify_framework.mjs

@@ -63,7 +63,7 @@ const EXPECTED_PROMPT_SIGNATURES = {
 
 function main() {
     console.log("===========================================");
-    console.log(" V-Bounce OS: Framework Integrity Check");
+    console.log(" V-Bounce Engine: Framework Integrity Check");
     console.log("===========================================\n");
 
     let hasErrors = false;

package/skills/doc-manager/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: doc-manager
-description: "Use when creating, modifying, or navigating V-Bounce OS planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when an agent needs to know which template to use, where a document fits in the hierarchy, or what upstream/downstream documents to read before writing. This skill manages the full document lifecycle from Charter through Sprint execution."
+description: "Use when creating, modifying, or navigating V-Bounce Engine planning documents. Trigger on any request to create a charter, roadmap, epic, story, delivery plan, or risk registry — or when the user asks to update, refine, decompose, or transition documents between phases. Also trigger when an agent needs to know which template to use, where a document fits in the hierarchy, or what upstream/downstream documents to read before writing. This skill manages the full document lifecycle from Charter through Sprint execution."
 ---
 
 # Document Hierarchy Manager
 
 ## Purpose
 
-This skill is the navigation system for V-Bounce OS planning documents. It knows the full document hierarchy, what each template contains, where to find templates, and the rules for creating, modifying, and transitioning documents between phases.
+This skill is the navigation system for V-Bounce Engine planning documents. It knows the full document hierarchy, what each template contains, where to find templates, and the rules for creating, modifying, and transitioning documents between phases.
 
 **Core principle:** No document exists in isolation. Every document inherits context from upstream and feeds downstream consumers. YOU MUST read upstream documents before creating any new document.
 
@@ -120,10 +120,10 @@ product_plans/
 - `sprints/` contains active 1-week execution boundaries. A Story file physically moves here when a sprint begins.
 - `archive/` is where finished Sprints and finished Epics are moved for permanent record keeping.
 
-### V-Bounce OS Framework Structure
+### V-Bounce Engine Framework Structure
 
 ```
-V-Bounce OS/
+V-Bounce Engine/
 ├── brains/          — Agent brain files for each AI coding tool
 │   ├── CLAUDE.md        — Claude Code brain
 │   ├── AGENTS.md        — Codex CLI brain
@@ -148,7 +148,7 @@ When initializing a new project, deploy the correct brain file for the AI coding
 | Gemini CLI | `brains/GEMINI.md` | Project root as `GEMINI.md` |
 | Antigravity | `brains/GEMINI.md` | Project root + copy `skills/` to `.agents/skills/` |
 
-Brain files contain the V-Bounce process, critical rules, and skill references. Each tool's brain file is self-contained and authoritative. When updating V-Bounce OS rules, update each brain file directly and keep them in sync.
+Brain files contain the V-Bounce process, critical rules, and skill references. Each tool's brain file is self-contained and authoritative. When updating V-Bounce Engine rules, update each brain file directly and keep them in sync.
 
 ## Document Operations
 

package/skills/improve/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: improve
-description: "Use when the V-Bounce OS framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
+description: "Use when the V-Bounce Engine framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
 ---
 
 # Framework Self-Improvement
 
 ## Purpose
 
-V-Bounce OS is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
+V-Bounce Engine is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
 
 **Core principle:** No framework change happens without human approval. The system suggests — the human decides.