multimodel-dev-os 2.0.1 → 2.8.0

package/docs/approved-proposal-apply.md

@@ -0,0 +1,156 @@
+# Approved Proposal Application Engine
+
+MultiModel Dev OS v2.4.1 (Safety & UX Patch) introduces a safe, deterministic, human-approved proposal application layer to automate the execution of approved codebase optimization proposals under strict safety constraints.
+
+---
+
+## 1. Core Workflow
+
+Instead of requiring manual copy-pasting, the CLI can execute machine-applicable operation blocks from proposal files that have been marked as `approved` by a developer.
+
+```mermaid
+graph TD
+    A[improve propose] --> B[Pending Proposal File]
+    B --> C{Developer Review}
+    C -->|Rejects| D[approval_status: rejected]
+    C -->|Approves & edits frontmatter| E[approval_status: approved]
+    E --> F[improve validate]
+    F -->|Validation check passes| G[improve diff]
+    G -->|Dry-run preview passes| H[improve apply --approved]
+    H --> I[Changes written to target & logged in apply-log]
+```
+
+---
+
+## 2. Machine-Applicable Operations
+
+To automate changes, proposal files support an optional, structured JSON block embedded as a `json` code block in the markdown body:
+
+````markdown
+```json
+{
+  "operations": [
+    {
+      "type": "create_file",
+      "path": "docs/example.md",
+      "content": "# Example\n",
+      "overwrite": true
+    },
+    {
+      "type": "append_line",
+      "path": ".gitignore",
+      "line": "node_modules/"
+    },
+    {
+      "type": "replace_text",
+      "path": "README.md",
+      "find": "old text",
+      "replace": "new text",
+      "allow_multiple": false
+    }
+  ]
+}
+```
+````
+
+### Supported Operation Types
+
+| Operation | Parameters | Description |
+|---|---|---|
+| `create_file` | `path`, `content`, `overwrite` (optional) | Creates a file with the given content. Fails if the file exists unless `overwrite: true`. |
+| `append_line` | `path`, `line` | Appends a line to the file. It is idempotent; if the line already exists in the file, it will not be duplicated. |
+| `replace_text` | `path`, `find`, `replace`, `allow_multiple` (optional) | Replaces search string `find` with `replace`. Fails if `find` is not found, or matches multiple times unless `allow_multiple: true`. |
+
+### Disallowed Operations for Safety
+The following actions are strictly prohibited in the v2.4.0 application engine:
+* Deleting or renaming files (`delete_file`, `rename_file`)
+* Running arbitrary shell commands
+* Installing npm packages or editing package dependencies
+* Interacting with Git or version control
+* Performing network calls
+* Modifying binary files or secret files
+* Modifying files outside the target workspace root folder
+
+---
+
+## 3. Strict Safety Gates
+
+The application engine validates every proposal file against a set of strict safety rules before any file is touched:
+
+1. **Existence**: The target proposal markdown file must exist.
+2. **Metadata Frontmatter**: YAML frontmatter must parse successfully.
+3. **Approval Check**: `approval_status` inside the frontmatter must be explicitly set to `approved`.
+4. **CLI Flag**: `improve apply` refuses to execute unless `--approved` is passed by the user.
+5. **Operations block**: A valid JSON code block with `operations` array must be found.
+6. **Command validation**: Every listed operation type must be allowed.
+7. **Directory boundaries**: Every target path must resolve strictly inside the target root directory. Directory traversal using `..` or absolute paths resolves outside target root and fails.
+8. **Protected paths**: No protected files or directories (such as `.git/`, `node_modules/`, `.env`, `.npmrc`, SSL keys/certificates) can be written to or modified.
+9. **`replace_text` match count**: Search text `find` must match exactly once unless `allow_multiple: true` is passed.
+10. **`create_file` overwrites**: If a target file exists, the operation must explicitly specify `overwrite: true`.
+11. **`append_line` idempotency**: Line additions will not duplicate if the exact line already exists.
+12. **Dry-run diff**: Developers can preview all changes using `improve diff` prior to execution.
+
+> [!WARNING]
+> **Workflow Isolation**: The `improve apply` command can only be executed manually by a developer. The MultiModel Dev OS [Workflow Runner](workflow-orchestration.md) runs in a strictly read-only mode and is prohibited from executing `improve apply` or modifying codebase files.
+
+---
+
+## 4. CLI Commands
+
+### validate
+Validates the proposal frontmatter, safety gates, and operation rules. Displays a color-coded Checklist showing the status of each safety gate (pass, fail, skip) and actionable fixes:
+```bash
+npx multimodel-dev-os improve validate <proposal-file> --target <path>
+```
+
+### diff
+Previews the changes grouped by operation type (Create, Append, Replace) in a token-safe truncated format:
+```bash
+npx multimodel-dev-os improve diff <proposal-file> --target <path>
+```
+
+### apply
+Deterministically executes the operations listed in the approved proposal file. Refuses to run without the `--approved` flag. Prints pre-apply summaries and detailed idempotent run indicators.
+```bash
+npx multimodel-dev-os improve apply <proposal-file> --target <path> --approved
+```
+
+### log
+Lists the history of applied proposals from the audit log:
+```bash
+npx multimodel-dev-os improve log --target <path>
+```
+
+---
+
+## 5. Audit Logging
+
+Every execution of `improve apply` writes an entry to the append-only JSON Lines audit log. Hardened in v2.4.1, it also writes records for failed/refused attempts:
+* **Log Location**: `.ai/proposals/apply-log.jsonl`
+* **Log Exclusion**: Automatically ignored by Git via `.gitignore` and excluded from AI scanner runs.
+
+Each record conforms to `.ai/intelligence/apply-log.schema.json` and contains:
+* `id`: Unique execution identifier (`apply-YYYYMMDD-HHMMSS`)
+* `proposal_id`: Proposal file identifier
+* `applied_at`: ISO timestamp of execution
+* `target`: Resolved workspace target path
+* `operations_count`: Total operations performed
+* `files_changed`: List of relative paths modified
+* `before_hashes`: SHA-256 file hashes before execution
+* `after_hashes`: SHA-256 file hashes after execution
+* `status`: `success`, `failed`, or `refused`
+* `refused_reason`: Reason why validation was refused (when applicable)
+* `notes`: Additional run information or failure reasons
+
+---
+
+## 6. Recommended Workflow
+
+To ensure safety, consistency, and clarity, follow this workflow:
+
+1. **validate**: Run `npx multimodel-dev-os improve validate .ai/proposals/proposal-xxxx.md` to run safety gate audits.
+2. **diff**: Run `npx multimodel-dev-os improve diff .ai/proposals/proposal-xxxx.md` to review planned changes.
+3. **manually review**: Verify the proposal contents, target paths, and operation constraints.
+4. **apply**: Run `npx multimodel-dev-os improve apply .ai/proposals/proposal-xxxx.md --approved` to write modifications locally.
+5. **run tests**: Manually run verification tests (e.g., `npm run verify` or custom test runner).
+6. **commit**: Commit the changes manually to version control.

package/docs/architecture.md

@@ -7,6 +7,7 @@
 3. **Zero dependencies** — no runtime, no package manager, no build step
 4. **Non-destructive** — installers never overwrite, adapters never conflict
 5. **Progressive complexity** — start with `AGENTS.md`, add orchestrator later
+6. **Safety-first** — all write operations require explicit developer approval
 
 ## Layer Architecture
 
@@ -15,24 +16,36 @@
 │          Human Layer                 │
 │   README.md  CONTRIBUTING.md  docs/  │
 ├──────────────────────────────────────┤
-│        Source of Truth Layer         │
+│    Layer 1: Source of Truth          │
 │  AGENTS.md  MEMORY.md  TASKS.md     │
 │  RUNBOOK.md                         │
 ├──────────────────────────────────────┤
-│        AI Operating Layer            │
+│    Layer 2: AI Operating Layer       │
 │  .ai/config.yaml                    │
-│  .ai/agents/multimodel-orchestrator.md│
-│  .ai/context/  .ai/prompts/          │
-│  .ai/skills/  .ai/checks/           │
-│  .ai/session-logs/  .ai/templates/  │
+│  .ai/agents/  .ai/context/          │
+│  .ai/prompts/ .ai/skills/           │
+│  .ai/checks/  .ai/templates/        │
+│  .ai/models/  .ai/schema/           │
 ├──────────────────────────────────────┤
-│         Adapter Layer                │
+│    Layer 3: Adapter Layer            │
 │  adapters/codex/                    │
 │  adapters/antigravity/              │
 │  adapters/cursor/                   │
 │  adapters/claude/                   │
 │  adapters/gemini/                   │
 │  adapters/vscode/                   │
+├──────────────────────────────────────┤
+│    Layer 4: Intelligence Layer       │
+│  .ai/intelligence/  (memory, handoff)│
+│  .ai/registries/    (workflows,     │
+│    capabilities, tools)              │
+│  .ai/proposals/     (improvements)  │
+│  .ai/policies/      (safety gates)  │
+├──────────────────────────────────────┤
+│    Layer 5: CLI Dashboard & Plugins  │
+│  dashboard / ui (TUI Command Center) │
+│  plugin list/show/validate/install   │
+│  onboard / adapter sync              │
 └──────────────────────────────────────┘
 ```
 
@@ -43,6 +56,10 @@
 3. **AI agents** read their adapter file + root files
 4. **Agents write** results back to `TASKS.md`, `MEMORY.md`, and session logs
 5. **Orchestrator** coordinates multi-agent workflows via session logs
+6. **Memory engine** indexes codebase state into hash-compressed summaries
+7. **Feedback loop** captures developer corrections and compiles learning rules
+8. **Proposal engine** drafts improvements, validates safety gates, and applies approved changes
+9. **Handoff compiler** generates token-compressed session context for agent transfers
 
 ## File Ownership
 
@@ -54,6 +71,11 @@
 | `RUNBOOK.md` | Human | All agents | Human |
 | `.ai/config.yaml` | Human | System | Human |
 | `.ai/session-logs/*.md` | Agents | Next agent | Current agent |
+| `.ai/intelligence/memory.*` | System | All agents | CLI (`memory build`) |
+| `.ai/intelligence/handoff.md` | System | Next agent | CLI (`handoff build`) |
+| `.ai/intelligence/feedback-log.jsonl` | System | CLI | CLI (`feedback add`) |
+| `.ai/proposals/*.md` | System | Human + CLI | CLI (`improve propose`) |
+| `.ai/registries/*.yaml` | System | CLI | CLI (`init`) |
 | `adapters/*/` | Community | Specific tool | Maintainers |
 
 ## Security Considerations
@@ -62,3 +84,5 @@
 - Handoff logs may contain sensitive context — gitignored by default
 - Adapter config files should not contain API keys or tokens
 - Use `.env` files (gitignored) for secrets, referenced in `RUNBOOK.md`
+- Memory indexes, feedback logs, and proposals are gitignored by default
+- The proposal `apply` command enforces 12 safety gates including path boundary checks

package/docs/capability-registry.md

@@ -0,0 +1,24 @@
+# Model Capability Registry
+
+The **Capability Registry** manages and scores AI models across cognitive, speed, and cost vectors, eliminating hardcoded model routing logic.
+
+---
+
+## 1. Capabilities Score Matrix
+
+Models are scored in `.ai/registries/capabilities.yaml` across six primary vectors:
+*   `coding` — Syntax accuracy, language compliance, and refactoring competence.
+*   `reasoning` — Multi-file plan generation and logical constraint auditing.
+*   `repo-scan` — Needle-in-a-haystack retrieval accuracy at massive context scales.
+*   `agentic-duration` — Ability to execute long-running task loops without losing parameters.
+*   `mcp-compliance` — Native Model Context Protocol (MCP) tool bindings.
+*   `local-offline` — Suitability for local resources (e.g. running via Ollama/Llama.cpp).
+
+---
+
+## 2. Dynamic Routing Engine
+
+When executing workflow steps:
+1.  **Workflows Query**: The workflow profile specifies the minimum capability scores required for each step (e.g., `planning` requires `reasoning: 0.85`, while `coding` requires `coding: 0.80`).
+2.  **Capabilities Filter**: The router filters active models that meet or exceed these score thresholds.
+3.  **Cost-Speed Trade-off**: From the matching models, the engine selects the candidate that optimizes cost, latency, or user-selected flags (e.g. `--local` or `--low-cost`).

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,105 @@
+# 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` is passed. The dashboard immediately prints a structured list of all menu options along with their corresponding CLI execution strings and exits cleanly.
+
+Example headless output:
+
+```txt
+🧠 MultiModel Dev OS Command Center (Headless mode)
+==================================================
+  - Active Workspace Status: equivalent command: "npx multimodel-dev-os status"
+  - Codebase Scan Analysis: equivalent command: "npx multimodel-dev-os scan"
+  - Onboarding Operations...
+    └─ Onboard: Analyze Repository: equivalent command: "npx multimodel-dev-os onboard analyze"
+    └─ Onboard: Recommendation Summary: equivalent command: "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)**.