multimodel-dev-os 2.6.0 → 2.8.1

package/docs/comparison.md

@@ -1,34 +1,81 @@
-# Comparison Guide: multimodel-dev-os vs. Alternatives
+# Comparison Guide: MultiModel Dev OS vs. Alternatives
 
-Selecting how to manage AI instructions inside a codebase significantly impacts developer speed, token consumption, and context drift. This document contrasts `multimodel-dev-os` with standard configurations.
+Selecting how to manage AI instructions inside a codebase impacts developer speed, token consumption, and context drift. This document contrasts `multimodel-dev-os` with common alternatives.
 
-## The Strategy Matrix
+---
+
+## Quick Decision Matrix
 
-| Feature | AGENTS.md Only (DIY) | Tool-Specific Prompt Packs | MultiModel Dev OS (`.ai/` + CLI) |
-| :--- | :--- | :--- | :--- |
-| **Tool Portability** | Manual copying when changing tools | Zero portability (highly vendor-locked) | **Portable & Vendor-Neutral** (Single source of truth) |
-| **Instruction Synchronization** | Manually synchronizing `.cursorrules`, `CLAUDE.md`, etc. | No synchronization (rules drift quickly) | **Automated** (Adapters mirror root rules instantly) |
-| **Token Optimization** | No budgeting (full rules read every time) | Vague, static rules | **Caveman Mode** (slashes token footprints by **~79%**) |
-| **Structural Segregation** | Flat single-file instructions (easily cluttered) | Disorganized configs | **Concise modular directories** (Context, Skills, Prompts, Checks) |
-| **CI/CD Quality Gates** | None (no structural safety checks) | None | **Verify subcommand** (`npm run verify` protects standard formats) |
-| **Standardized Hand-offs** | Manual human explanations | Manual human explanations | **Sequential hand-off protocol** with structured session logs |
-| **Cost Playbook Alignment** | None | None | **12 Playbook mappings** (RAG scoping, batching, caching) |
+| Feature | AGENTS.md Only (DIY) | .cursorrules / CLAUDE.md | Prompt Packs | **MultiModel Dev OS** |
+| :--- | :--- | :--- | :--- | :--- |
+| **Multi-tool support** | ❌ Manual duplication | ❌ Single tool only | ❌ Vendor-locked | ✅ **6+ tools from one source** |
+| **Instruction sync** | ❌ Copy-paste drift | ❌ No sync possible | ❌ No sync | ✅ **Auto adapter sync** |
+| **Token optimization** | ❌ Full rules every time | ❌ No budgeting | ❌ Static rules | ✅ **Caveman Mode (−79%)** |
+| **Structural validation** | ❌ None | ❌ None | ❌ None | ✅ **validate + doctor + verify** |
+| **Templates** | ❌ Start from scratch | ❌ Start from scratch | ⚠️ Generic starters | ✅ **6 production-ready templates** |
+| **Memory & learning** | ❌ None | ❌ None | ❌ None | ✅ **Hash-compressed memory + feedback loops** |
+| **CI/CD integration** | ❌ None | ❌ None | ❌ None | ✅ **214+ assertion verification suite** |
+| **Onboarding existing repos** | ❌ Manual setup | ❌ Manual setup | ❌ Manual setup | ✅ **`onboard analyze` workflow** |
+| **Interactive TUI Dashboard** | ❌ None | ❌ None | ❌ None | ✅ **Zero-dependency TUI Menu** |
+| **Declarative Plugins** | ❌ None | ❌ None | ❌ None | ✅ **Safe whitelist YAML plugins** |
+| **Cost** | Free | Free | Free–Paid | ✅ **Free & open source** |
 
 ---
 
-## Detailed Evaluation
+## Detailed Comparison
+
+### 1. The DIY Approach (Single AGENTS.md)
+
+Many developers start by dropping a single `AGENTS.md` in their project root. This is better than nothing, but it breaks down fast:
+
+- **Drift:** You update a build command in `AGENTS.md`, but forget to update Cursor's `.cursorrules`. Cursor keeps running the old build script.
+- **Clutter:** The file bloats with styling rules, deployment procedures, and troubleshooting steps. The AI spends 10,000+ tokens reading instructions every turn.
+- **No validation:** There's no way to check if your instructions are well-formed or complete.
+
+### 2. Tool-Specific Rules (`.cursorrules`, `CLAUDE.md`, etc.)
+
+Each tool has its own configuration format. Using only one locks you into that vendor:
+
+- **No portability:** If your team uses Cursor for coding and Claude Code for debugging, you must manually translate and duplicate rules for both.
+- **No collaboration:** Co-workers using different IDEs or agents can't benefit from the same context.
+- **No onboarding:** New team members must discover and configure each tool manually.
+
+### 3. Community Prompt Packs
 
-### 1. The DIY Approach (AGENTS.md Only)
-Many developers start by dropping a single `AGENTS.md` file in their root. While better than nothing, this approach quickly breaks down:
-- **Drift:** You modify a build command in `AGENTS.md`, but forget to update Cursor's `.cursorrules`. Cursor continues running the old build script, causing confusing errors.
-- **Clutter:** A single markdown file gets bloated with styling guidelines, deployment procedures, and troubleshooting steps. Soon, the AI spends 10,000 tokens just reading instructions on every turn.
+Various community projects offer pre-built instruction sets for specific tools:
+
+- **Vendor lock:** Prompt packs are built for one tool — switching means starting over.
+- **Generic rules:** Community packs optimize for broad use, not your specific project architecture.
+- **No intelligence:** No memory, no feedback loops, no self-improvement capabilities.
+
+### 4. MultiModel Dev OS
+
+`multimodel-dev-os` creates a lightweight, vendor-neutral layer that decouples your project's rules from specific tools:
+
+- **Write once, read everywhere:** Define build parameters once in `AGENTS.md`. Adapters expose these configurations cleanly to Cursor, Claude, Antigravity, VS Code, Codex, and more.
+- **Continuous integration:** Add `multimodel-dev-os verify` to your CI pipeline or pre-commit hooks to guarantee all developers share healthy, correctly-formatted AI configurations.
+- **Self-improving:** The feedback loop compiles developer corrections into reusable rules. The proposal engine suggests codebase improvements with strict safety gates.
+- **Instant onboarding:** The `onboard analyze` command scans existing projects and recommends the optimal template and adapter configuration.
+
+### 5. Agentic CLIs & Extensions (Aider, Roo Code, Continue, Cline)
+
+While advanced AI coding assistants like **Aider**, **Roo Code (Cline)**, and **Continue** provide powerful code generation and agentic capabilities, they serve a different layer of the stack than MultiModel Dev OS:
+
+- **Complementary, Not Competitive:** MultiModel Dev OS is not a chatbot or code generator. It is a **configuration and governance layer**. It formats and syncs workspace context so that tools like Aider, Roo Code, and Continue can read the exact same project boundaries.
+- **Rules Portability:** Roo Code or Continue read custom instructions, but they are stored in tool-specific config formats. If you switch to Aider in the CLI, you have to recreate those instructions. MultiModel Dev OS bridges this gap by auto-generating target configurations from `AGENTS.md`.
+- **Quality Gates & Backups:** MultiModel Dev OS provides built-in `validate`, `doctor`, and `onboard` commands, plus structured proposal safety gates. This prevents external agents from making unchecked, destructive changes directly to your main branch.
+
+---
 
-### 2. Tool-Specific Prompt Packs
-Using tools like `Cursorrules` websites or Claude Code presets locks your project configuration into one vendor's ecosystem:
-- **Vendor Lock:** If your team uses Cursor for coding and Claude Code for debugging, you must duplicate and manually translate the syntax for both tools.
-- **No Collaboration:** Co-workers using different IDEs or terminal utilities cannot benefit from the unified context.
+## When to Use What
 
-### 3. MultiModel Dev OS
-`multimodel-dev-os` establishes a lightweight, vendor-neutral layer that decouples your project's rules from specific tools:
-- **Translate once, read everywhere:** You write build parameters once in the root. The CLI and adapters expose these configurations cleanly to Cursor, Claude, Antigravity, VS Code, and Codex.
-- **Continuous Integration:** You can add `multimodel-dev-os verify` to your CI pipeline or pre-commit hooks to guarantee that all developers share healthy, correctly-formatted AI configurations.
+```
+Do you use only one AI coding tool?
+├── Yes → Tool-specific rules (e.g., .cursorrules) might be enough
+│         But consider MMDO if you want templates, validation, or memory
+│
+└── No → Do you switch between 2+ tools?
+    ├── Yes → MultiModel Dev OS is built for this
+    └── Maybe later → Start with MMDO anyway — it's backward-compatible
+        and takes 30 seconds to set up
+```

package/docs/compatibility.md

@@ -39,8 +39,8 @@ To guarantee validation compliance:
 
 ---
 
-## 4. v1.1.0 Compatibility Guarantee
+## 4. Compatibility Guarantee
 
-The supported tool matrix and custom specifications listed here represent the officially frozen contracts of MultiModel Dev OS `v1.1.0`. Any backward-compatible extensions introduced in subsequent `1.x` releases will build on top of these mappings without breaking current project integrations.
+The supported tool matrix and custom specifications listed here represent the officially frozen contracts of MultiModel Dev OS. The core Layer 1 protocol has been stable since `v1.0.0` and all subsequent `v1.x` and `v2.x` releases maintain full backward compatibility.
 
 Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/dashboard.md

@@ -0,0 +1,107 @@
+# Interactive TUI Dashboard
+
+MultiModel Dev OS provides an interactive, terminal-based command center to manage all repository operations, adapter syncs, memory builds, proposals, and diagnostics from a single interface.
+
+## Launching the Dashboard
+
+Run either of the following commands to launch the TUI:
+
+```bash
+npx multimodel-dev-os@latest dashboard
+# or the short alias
+npx multimodel-dev-os@latest ui
+```
+
+---
+
+## Controls
+
+The dashboard is built using Node.js's native `readline` module. It does not load external UI frameworks or npm prompt dependencies, keeping the execution extremely fast and light.
+
+* **Up / Down Arrows**: Navigate through the menu options.
+* **Return (Enter)**: Select and run the highlighted command or enter a submenu.
+* **Escape / Ctrl+C**: Exit the dashboard or return to the shell.
+
+---
+
+## Dashboard Structure
+
+The dashboard contains a hierarchical structure mapping to all MMDO CLI actions:
+
+```mermaid
+graph TD
+    Dashboard[TUI Command Center]
+    Dashboard --> Status[Active Workspace Status]
+    Dashboard --> Scan[Codebase Scan Analysis]
+    Dashboard --> Onboard[Onboarding Operations...]
+    Dashboard --> Adapter[Adapter Synchronization...]
+    Dashboard --> Memory[Memory & Intelligence...]
+    Dashboard --> Feedback[Developer Feedback Loops...]
+    Dashboard --> Quality[Quality Gates & Diagnostics...]
+    Dashboard --> Plugins[Plugins Status Overview]
+```
+
+### Main Sections
+
+1. **Active Workspace Status**: Runs the equivalent of `status` to print the current state of packages, active workspace structure, and recommendations.
+2. **Codebase Scan Analysis**: Runs the equivalent of `scan` to analyze framework signals and potential token sink risks.
+3. **Onboarding Operations**:
+   * Analyze Repository (`onboard analyze`)
+   * Recommendation Summary (`onboard recommend`)
+   * Generate Integration Plan (`onboard plan`)
+   * Apply Configs in Dry Run (`onboard apply --dry-run`)
+   * View Status Heuristics (`onboard status`)
+4. **Adapter Synchronization**:
+   * Check Sync Status (`adapter status`)
+   * Sync All rule files in Dry Run (`adapter sync all --dry-run`)
+   * Diff Cursor Rules (`adapter diff cursor`)
+   * Diff Claude Rules (`adapter diff claude`)
+5. **Memory & Intelligence**:
+   * Memory Build Index (`memory build`)
+   * Memory Refresh Changes (`memory refresh`)
+   * Memory Diff Index (`memory diff`)
+   * Handoff Build Session Summary (`handoff build`)
+   * Print Session Summary to Console (`handoff show`)
+6. **Developer Feedback Loops & Proposals**:
+   * List developer corrections (`feedback list`)
+   * Summarize feedback logs (`feedback summarize`)
+   * Propose improvement proposal (`improve propose`)
+   * Review active proposals list (`improve review`)
+7. **Quality Gates & Diagnostics**:
+   * Run Advisory Diagnostics (`doctor`)
+   * Strict Schema Compliance (`validate`)
+   * Run Release verification tests (`verify`)
+8. **Plugins Status Overview**: Checks the status of all installed declarative plugins (`plugin status`).
+
+---
+
+## Zero-Hanging CI Fallback (Non-Interactive Mode)
+
+In automated environments (CI/CD pipelines, GitHub Actions) or when piped, the terminal does not have interactive stdin capabilities. 
+
+To prevent execution from hanging indefinitely, the TUI automatically detects non-TTY environments:
+* **Interactive Mode**: Triggered when both `process.stdout.isTTY` and `process.stdin.isTTY` are true.
+* **Headless Fallback**: Triggered when run in non-interactive shells, or if `--dry-run` or `--list-actions` is passed. The dashboard immediately prints a structured, grouped list of all menu options along with their corresponding CLI execution strings (including active target flags) and exits cleanly.
+
+Example headless output:
+
+```txt
+📊 MultiModel Dev OS Command Center (Headless/CI Preview)
+Target Workspace: /workspace
+==================================================
+  • Active Workspace Status        → npx multimodel-dev-os status
+  • Codebase Scan Analysis         → npx multimodel-dev-os scan
+
+  [Onboarding Operations]
+    └─ Onboard: Analyze Repository        → npx multimodel-dev-os onboard analyze
+    └─ Onboard: Recommendation Summary    → npx multimodel-dev-os onboard recommend
+...
+```
+
+---
+
+## Safety Controls
+
+1. **No Destructive Operations**: Subcommands that modify files (such as `adapter sync`, `onboard apply`, or `improve apply`) are run in **dry-run** mode by default inside the dashboard menu. 
+2. **Bold Command Printing**: Before executing any command from the menu, the dashboard prints the exact command it is running (e.g. `npx multimodel-dev-os memory build`). This ensures that developers can learn the underlying CLI commands and transition to direct CLI operations when scripting.
+3. **Subprocess Isolation**: When running subprocess actions, the TUI temporarily detaches keyboard listeners and raw mode, allowing the command to render its output and handle prompts cleanly before restoring TUI control.

package/docs/demo.md

@@ -1,79 +1,42 @@
-# Interactive CLI & Terminal Demo
+# Guided Demo Workflows
 
-Experience the clean scaffolding pipeline and zero-dependency commands of `multimodel-dev-os` right from your terminal.
+Experience MultiModel Dev OS in action. We provide structured, interactive demo workflows that you can copy-paste and run in under 2 minutes.
 
 ---
 
-## Visual Initialization Pipeline
+## Interactive Mockup
 
-Here is how the automatic bootstrapping pipeline looks when initializing a project with a template:
+Here is the automatic onboarding, scaffolding, and sync pipeline in action:
 
 ![Terminal Scaffold Mockup](/assets/terminal-demo.svg)
 
 ---
 
-## Under the Hood: CLI Commands
+## 5 Guided Workflows
 
-`multimodel-dev-os` is built entirely on native Node.js libraries, keeping execution lightning-fast with **zero third-party runtime dependencies**.
+Select a workflow to get started:
 
-### 1. The `init` Scaffolding Engine
-
-Bootstraps the shared workspace contract files and target directory setups.
-
-```bash
-# Global zero-install setup
-npx multimodel-dev-os@latest init
-
-# Scaffold a specific technology stack template and set up adapter status automatically
-npx multimodel-dev-os@latest init --template nextjs-saas --adapter cursor --adapter claude
-
-# Run a dry-run preview to verify planned file actions without modifying the disk
-npx multimodel-dev-os@latest init --dry-run
-```
-
-#### Core Scaffolding Activities:
-- **Directory Guarantee:** Assures target paths (`.ai/context`, `.ai/skills`, `.ai/session-logs`) exist.
-- **Contract Scaffold:** Creates the root source-of-truth instructions (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`).
-- **Adapter Linking:** Translates and copies rule files (like `.cursorrules`, `CLAUDE.md`, or `.vscode/`) directly to your workspace root.
-
----
-
-### 2. The `templates` Gallery Inspector
-
-Allows developers to view, inspect, and choose real-world configuration templates.
-
-```bash
-# List all pre-configured stack templates
-npx multimodel-dev-os templates
-
-# Display detailed configuration rules and files of a specific template
-npx multimodel-dev-os show-template nextjs-saas
-```
+| Workflow Demo | Description | Duration |
+|---|---|---|
+| 🚀 **[Safe Repo Onboarding](/demos/existing-repo-onboarding)** | Safely analyze and bootstrap a real, existing project. | ~2 mins |
+| 🔄 **[Universal Adapter Sync](/demos/adapter-sync)** | Write rules once in `AGENTS.md` and sync Cursor, Claude, and Gemini. | ~1 min |
+| 🤝 **[Multi-Agent Handoff](/demos/multi-agent-handoff)** | Seamlessly pass session context between terminal and editor agents. | ~2 mins |
+| 🔁 **[Safe Improvement Loop](/demos/safe-improvement-loop)** | Capture user feedback, propose upgrades, and apply with safety gates. | ~3 mins |
+| 🩺 **[Release Verification](/demos/release-check)** | Run pre-flight checks and verify version alignment before npm publishing. | ~1 min |
 
 ---
 
-### 3. The `validate` Quality Gate
-
-Enforce strict formatting conventions inside your repository before checking in code:
-
-```bash
-# Strict directory schema and file validation checkup
-npx multimodel-dev-os validate
-```
-
-If any core agent file (`AGENTS.md`, `MEMORY.md`) is missing or is structurally invalid, the CLI exits with non-zero exit codes to fail pull requests or pre-commit hooks, guarding workspace health.
-
----
+## Under the Hood: Core CLI Commands
 
-### 4. The `doctor` Advisory Inspector
+MultiModel Dev OS is a zero-dependency CLI. Here are the main commands that power these workflows:
 
-An advisory checkup to diagnose environment compatibility issues:
+### 1. Scaffolding & Setup
+- `init`: Bootstraps shared workspace contract files and enables target adapters.
+- `onboard analyze`: Safely scans an existing repository to suggest the best template fit.
 
-```bash
-# Diagnostic audit of gitignore rules and IDE adapter overrides
-npx multimodel-dev-os doctor
-```
+### 2. Synchronization & Verification
+- `adapter sync`: Pushes rules in `AGENTS.md` out to `.cursorrules`, `CLAUDE.md`, `.gemini/settings`, and more.
+- `validate`: Enforces structural compliance, perfect for pre-commit hooks and CI.
+- `doctor`: Audits `.gitignore` hygiene and active adapter status.
 
-The doctor warns you if:
-- IDE cache directories (like `node_modules` or `.vitepress/dist`) are not listed in your `.gitignore` file.
-- Enabled adapter configurations inside `.ai/config.yaml` lack corresponding physical rule files on the disk.
+For the full CLI command reference, see the **[CLI Documentation](/CLI)**.

package/docs/demos/adapter-sync.md

@@ -0,0 +1,103 @@
+# Demo: Adapter Sync
+
+> **Who**: Developers using 2+ AI coding tools who want rules synced automatically.
+> **Time**: ~1 minute | **Prerequisites**: Node.js 18+, a MultiModel Dev OS workspace (run `init` first)
+
+---
+
+## Starting State
+
+You have a project with MultiModel Dev OS initialized. Your `AGENTS.md` has been customized with your project's build commands and coding conventions. Now you want those rules pushed to `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, etc.
+
+---
+
+## Workflow
+
+### Step 1: Check adapter status
+
+```bash
+npx multimodel-dev-os@latest adapter status
+```
+
+**Expected output**:
+```
+🔌 Adapter Status:
+  cursor:       enabled  → .cursorrules (missing from root)
+  claude:       enabled  → CLAUDE.md (missing from root)
+  vscode:       enabled  → .vscode/settings.json (missing from root)
+  gemini:       disabled
+  antigravity:  disabled
+```
+
+### Step 2: Preview differences
+
+```bash
+npx multimodel-dev-os@latest adapter diff cursor
+```
+
+**What happens**: Shows the diff between the bundled adapter template and your current root file (if it exists). Read-only.
+
+### Step 3: Sync all enabled adapters
+
+```bash
+npx multimodel-dev-os@latest adapter sync all --approved
+```
+
+**What happens**: Copies rule files from `adapters/*/` to your project root. Existing files require `--force` to overwrite, and `.bak` backups are created automatically.
+
+**Expected output**:
+```
+🔄 Syncing adapters...
+  CREATE .cursorrules
+  CREATE CLAUDE.md
+  CREATE .vscode/settings.json
+✅ 3 adapters synced.
+```
+
+### Step 4: Verify
+
+```bash
+npx multimodel-dev-os@latest validate
+```
+
+---
+
+## What Gets Created
+
+| File | Source Adapter |
+|------|--------------|
+| `.cursorrules` | `adapters/cursor/.cursorrules` |
+| `CLAUDE.md` | `adapters/claude/CLAUDE.md` |
+| `.vscode/settings.json` | `adapters/vscode/.vscode/settings.json` |
+| `.gemini/settings.json` | `adapters/antigravity/.gemini/settings.json` |
+| `GEMINI.md` | `adapters/gemini/GEMINI.md` |
+
+Only enabled adapters are synced.
+
+---
+
+## Safety Notes
+
+- **Step 1-2 are read-only** — no files are modified
+- **Step 3 writes files** but never overwrites without `--force`
+- All overwrites create `.bak` backup files
+- Adapter enable/disable is controlled by `.ai/config.yaml`
+
+---
+
+## Cleanup
+
+Remove synced adapter files:
+
+```bash
+rm -f .cursorrules CLAUDE.md GEMINI.md
+rm -rf .vscode/ .gemini/
+```
+
+---
+
+## Next Steps
+
+- **Edit your rules**: Customize `AGENTS.md` → re-run `adapter sync all --approved` to propagate
+- **Build memory**: `npx multimodel-dev-os@latest memory build` → [Multi-Agent Handoff Demo](/demos/multi-agent-handoff)
+- **Run health check**: `npx multimodel-dev-os@latest workflow run repo-health`

package/docs/demos/existing-repo-onboarding.md

@@ -0,0 +1,125 @@
+# Demo: Existing Repo Onboarding
+
+> **Who**: Developers with an existing codebase who want to add AI Dev OS configs without breaking anything.
+> **Time**: ~2 minutes | **Prerequisites**: Node.js 18+, an existing project directory
+
+---
+
+## Starting State
+
+You have a project directory with source code — for example a Next.js app, a Python API, or a WordPress site. No MultiModel Dev OS files exist yet.
+
+```bash
+cd /path/to/your-project
+```
+
+---
+
+## Workflow
+
+### Step 1: Analyze your project
+
+```bash
+npx multimodel-dev-os@latest onboard analyze
+```
+
+**What happens**: Scans your directory for frameworks, languages, package managers, and existing AI config files. Read-only — no files are created or modified.
+
+**Expected output**:
+```
+🔍 Analyzing repository: /path/to/your-project
+  Detected: package.json (Node.js)
+  Detected: next.config.js (Next.js)
+  Detected: tsconfig.json (TypeScript)
+  Frameworks: nextjs, typescript
+  Adapters found: none
+  Risk markers: 0
+```
+
+### Step 2: Get recommendations
+
+```bash
+npx multimodel-dev-os@latest onboard recommend
+```
+
+**What happens**: Based on the analysis, recommends the best template and adapter configuration. Read-only.
+
+**Expected output**:
+```
+📋 Recommendations for /path/to/your-project
+  Template: nextjs-saas (confidence: 85%)
+  Adapters: cursor, claude (detected IDE signals)
+```
+
+### Step 3: Generate an onboarding plan
+
+```bash
+npx multimodel-dev-os@latest onboard plan
+```
+
+**What happens**: Creates a structured plan file at `.ai/intelligence/onboarding.plan.json` and a human-readable report at `.ai/intelligence/onboarding.report.md`. These are gitignored by default.
+
+### Step 4: Apply the plan
+
+```bash
+npx multimodel-dev-os@latest onboard apply --approved
+```
+
+**What happens**: Copies configuration templates to your project. Existing files are **never overwritten** unless you pass `--force`, and automatic `.bak` backups are created.
+
+### Step 5: Check status
+
+```bash
+npx multimodel-dev-os@latest onboard status
+```
+
+**Expected output**:
+```
+📊 Onboarding Status: /path/to/your-project
+  Completeness: 100%
+  Root files: AGENTS.md ✓ MEMORY.md ✓ TASKS.md ✓ RUNBOOK.md ✓
+  Config: .ai/config.yaml ✓
+  Adapters: cursor ✓ claude ✓
+```
+
+---
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Project instructions for all AI tools |
+| `MEMORY.md` | Architectural decisions and milestones |
+| `TASKS.md` | Active task backlog |
+| `RUNBOOK.md` | Operational verification commands |
+| `.ai/config.yaml` | Central configuration |
+| `.ai/context/` | Project context files |
+| `.ai/intelligence/onboarding.plan.json` | Onboarding plan (gitignored) |
+| `.ai/intelligence/onboarding.report.md` | Human-readable report (gitignored) |
+
+---
+
+## Safety Notes
+
+- **Steps 1-3 are fully read-only** — no files are written to your project
+- **Step 4 writes files** but never overwrites existing files without `--force`
+- All overwrites create `.bak` backup files automatically
+- Plan and report files are placed under `.ai/intelligence/` which is gitignored
+
+---
+
+## Cleanup
+
+To remove all MultiModel Dev OS files from your project:
+
+```bash
+rm -rf .ai/ AGENTS.md MEMORY.md TASKS.md RUNBOOK.md
+```
+
+---
+
+## Next Steps
+
+- **Sync IDE adapters**: `npx multimodel-dev-os@latest adapter sync all --approved` → [Adapter Sync Demo](/demos/adapter-sync)
+- **Build memory index**: `npx multimodel-dev-os@latest memory build`
+- **Run workspace health check**: `npx multimodel-dev-os@latest workflow run repo-health`

package/docs/demos/index.md

@@ -0,0 +1,91 @@
+# Demo Workflows
+
+Hands-on, copy-paste workflows that show MultiModel Dev OS in action. Each demo takes **under 2 minutes** and requires only `npx` — no global install, no dependencies.
+
+---
+
+## Choose a Demo
+
+<div class="demo-grid">
+  <a href="/demos/existing-repo-onboarding" class="demo-card">
+    <div class="demo-icon">📁</div>
+    <div class="demo-title">Existing Repo Onboarding</div>
+    <div class="demo-desc">Analyze a real project, get template recommendations, and safely bootstrap AI Dev OS configs.</div>
+    <div class="demo-time">~2 min</div>
+  </a>
+  <a href="/demos/adapter-sync" class="demo-card">
+    <div class="demo-icon">🔄</div>
+    <div class="demo-title">Adapter Sync</div>
+    <div class="demo-desc">Mirror rule files across Cursor, Claude, VS Code, and Gemini automatically.</div>
+    <div class="demo-time">~1 min</div>
+  </a>
+  <a href="/demos/safe-improvement-loop" class="demo-card">
+    <div class="demo-icon">🧠</div>
+    <div class="demo-title">Safe Improvement Loop</div>
+    <div class="demo-desc">Capture feedback, propose improvements, validate safety, and apply changes with audit trails.</div>
+    <div class="demo-time">~2 min</div>
+  </a>
+  <a href="/demos/multi-agent-handoff" class="demo-card">
+    <div class="demo-icon">🤝</div>
+    <div class="demo-title">Multi-Agent Handoff</div>
+    <div class="demo-desc">Compile token-compressed session context and hand off state between agents or models.</div>
+    <div class="demo-time">~1 min</div>
+  </a>
+  <a href="/demos/release-check" class="demo-card">
+    <div class="demo-icon">🚀</div>
+    <div class="demo-title">Release Check</div>
+    <div class="demo-desc">Run the full pre-flight verification suite, doctor audit, and package hygiene check.</div>
+    <div class="demo-time">~1 min</div>
+  </a>
+</div>
+
+---
+
+## Prerequisites
+
+All demos require:
+- **Node.js 18+** installed
+- A terminal (bash, zsh, PowerShell, or cmd)
+- An existing project directory (or create a temp one)
+
+No global install needed — every command uses `npx multimodel-dev-os@latest`.
+
+---
+
+## Demo Philosophy
+
+Every demo follows the same structure:
+
+1. **Starting State** — what you need before running
+2. **Workflow** — step-by-step commands with expected output
+3. **What Gets Created** — files and directories produced
+4. **Safety Notes** — what is read-only vs. what writes
+5. **Cleanup** — how to undo
+6. **Next Steps** — where to go after
+
+<style>
+.demo-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 1.25rem;
+  margin: 2rem 0;
+}
+.demo-card {
+  border: 1px solid var(--vp-c-bg-mute);
+  background: var(--vp-c-bg-soft);
+  border-radius: 10px;
+  padding: 1.5rem;
+  text-decoration: none !important;
+  color: inherit !important;
+  transition: border-color 0.25s, transform 0.25s;
+  display: block;
+}
+.demo-card:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-3px);
+}
+.demo-icon { font-size: 2rem; margin-bottom: 0.5rem; }
+.demo-title { font-weight: 700; font-size: 1.1rem; margin-bottom: 0.4rem; }
+.demo-desc { font-size: 0.9rem; color: var(--vp-c-text-2); margin-bottom: 0.5rem; }
+.demo-time { font-size: 0.8rem; color: var(--vp-c-brand-1); font-weight: 600; }
+</style>