multimodel-dev-os 2.6.0 → 2.8.1

package/docs/quickstart.md

@@ -1,31 +1,33 @@
-# Quickstart Guide: AI Dev OS Deployment
+# Quickstart Guide
 
-Get the MultiModel Dev OS integrated into your codebase in under 2 minutes to synchronize your multi-agent developer workflows.
+Get MultiModel Dev OS integrated into your codebase in **under 30 seconds** to synchronize your multi-agent developer workflows.
 
-> **Use when**: Setting up a new repository or aligning multiple AI tools (like Cursor, Claude Code, Gemini, Codex, and Antigravity) to prevent instruction drift and prompt token bloat.
+> **Use when**: Setting up a new repository or aligning multiple AI tools (Cursor, Claude Code, Gemini, Codex, Antigravity, VS Code) to prevent instruction drift and prompt token bloat.
 
 ---
 
-## Option A: NPX Scaffolding (Stable Packages)
+## Option A: NPX Scaffolding (Recommended)
 
-Initialize any project instantly using our public npm registry. Note that this pulls the latest stable npm-published release (`v2.0.1`):
+Initialize any project instantly using the public npm registry:
 
 ```bash
-# Standard interactive initialization in the current directory
+# Standard initialization in the current directory
 npx multimodel-dev-os@latest init
 
-# Target specific stack templates and specific tool adapters
+# Pick a stack template and inject specific adapters
 npx multimodel-dev-os@latest init --template nextjs-saas --adapter cursor --adapter claude
 
-# Run a dry-run preview before executing file writes
+# Run a dry-run preview before writing any files
 npx multimodel-dev-os@latest init --dry-run
 ```
 
+**Available templates:** `nextjs-saas` · `wordpress-site` · `ecommerce-store` · `seo-landing-page` · `expo-react-native-android` · `general-app`
+
 ---
 
 ## Option B: Fallback One-Line Scripts
 
-If you choose to run installation scripts directly (fetches stable files):
+If you prefer installation scripts:
 
 **macOS / Linux / WSL (bash):**
 ```bash
@@ -41,17 +43,17 @@ irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/inst
 
 ## Option C: Caveman Mode (Minimal Tokens)
 
-**Best for**: Context optimization for AI coding when using tight API budgets or smaller models. Reduces rules footprint by **~79%**.
+Cut prompt token overhead by **~79%** with compressed shorthand declarations. Best for tight API budgets or smaller models:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --caveman
+npx multimodel-dev-os@latest init --caveman
 ```
 
 ---
 
-## Option D: Scaffold Target Directory (NPX Direct)
+## Option D: Target a Specific Directory
 
-If you prefer to initialize a target project path directly:
+Initialize a target project path directly:
 
 ```bash
 npx multimodel-dev-os@latest init --target /path/to/your-project --template nextjs-saas --adapter cursor
@@ -59,34 +61,86 @@ npx multimodel-dev-os@latest init --target /path/to/your-project --template next
 
 ---
 
+## Option E: Onboard an Existing Repository
+
+Already have a project with code in it? Use the onboarding system to safely analyze your repo and bootstrap configs without breaking anything:
+
+```bash
+# Step 1: Analyze your project structure
+npx multimodel-dev-os@latest onboard analyze
+
+# Step 2: Get template and adapter recommendations
+npx multimodel-dev-os@latest onboard recommend
+
+# Step 3: Generate an onboarding plan
+npx multimodel-dev-os@latest onboard plan
+
+# Step 4: Apply the plan (creates backups automatically)
+npx multimodel-dev-os@latest onboard apply --approved
+
+# Step 5: Check onboarding status
+npx multimodel-dev-os@latest onboard status
+```
+
+---
+
+## Option F: Launch the Interactive Dashboard
+
+Launch the TUI command center to manage onboarding, adapter sync, memory building, feedback collection, proposals, and quality checks in an interactive menu:
+
+```bash
+npx multimodel-dev-os@latest dashboard
+```
+
+---
+
 ## After Install
 
-1. **Edit `AGENTS.md`** — fill in your project name, stack, and build commands (portable AI project context).
+1. **Edit `AGENTS.md`** — fill in your project name, stack, and build commands.
 2. **Edit `.ai/config.yaml`** — enable adapters for your tools.
-3. **Copy adapter files** to your project root (e.g., Cursor project rules, Claude Code project instructions):
+3. **Sync adapter rule files** to your project root automatically:
+   ```bash
+   npx multimodel-dev-os@latest adapter sync all --approved
+   ```
+   Or copy manually if you prefer:
    - Cursor: `cp adapters/cursor/.cursorrules .cursorrules`
    - Claude: `cp adapters/claude/CLAUDE.md CLAUDE.md`
    - VS Code: `cp -r adapters/vscode/.vscode/ .vscode/`
-4. **Start coding** — your AI coding agents will read the shared configuration instantly.
+4. **Build your codebase memory index:**
+   ```bash
+   npx multimodel-dev-os@latest memory build
+   ```
+5. **Start coding** — your AI coding agents will read the shared configuration instantly.
 
 ---
 
-## Verify & Diagnose
+## Try the Demo Workflows
+
+To see MultiModel Dev OS in action in under 2 minutes, try one of our guided, copy-paste demo workflows:
+- 🚀 **[Safe Repo Onboarding](/demos/existing-repo-onboarding)** — Safely onboard an existing project without breaking changes.
+- 🔄 **[Universal Adapter Sync](/demos/adapter-sync)** — Write rules once in `AGENTS.md` and sync Cursor, Claude, and Gemini.
+- 🤝 **[Multi-Agent Handoff](/demos/multi-agent-handoff)** — Smoothly hand off session context between terminal and editor agents.
+- 🔁 **[Safe Improvement Loop](/demos/safe-improvement-loop)** — Capture user feedback and run safe, audited codebase upgrades.
+- 🩺 **[Release Verification](/demos/release-check)** — Run the final pre-flight checks before releasing a package.
+
+Or browse them all on the [Demos Hub](/demos/).
 
-Validate structural health, run codebase scans, and build hash-compressed memory:
+---
+
+## Verify & Diagnose
 
 ```bash
 # Strict directory schema validation
-npx multimodel-dev-os validate
+npx multimodel-dev-os@latest validate
 
-# Advisory doctor workspace compatibility audit
-npx multimodel-dev-os doctor
+# Advisory workspace compatibility audit
+npx multimodel-dev-os@latest doctor
 
-# Advisory codebase scanner
-npx multimodel-dev-os scan
+# Codebase structure scanner
+npx multimodel-dev-os@latest scan
 
-# Build codebase memory index
-npx multimodel-dev-os memory build
+# Compact status dashboard
+npx multimodel-dev-os@latest status
 ```
 
-Explore our canonical [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.
+Explore the full **[CLI Command Reference](/CLI)**, **[Stable Protocol Specification](/stable-protocol)**, or **[Upgrade & Migration Guide](/migration-guide)** for details.

package/docs/repository-command-center.md

@@ -50,3 +50,19 @@ npx multimodel-dev-os onboard status
 ```
 
 This prints a checklist of crucial MultiModel Dev OS files and an overall completeness percentage score.
+
+---
+
+## 4. Interactive TUI Command Center
+
+Starting in `v2.8.0`, MultiModel Dev OS introduces a full interactive terminal user interface (TUI) command center that wraps all system diagnostics, sync tools, and memory engines.
+
+To launch the interactive dashboard, run:
+
+```bash
+npx multimodel-dev-os dashboard
+# or:
+npx multimodel-dev-os ui
+```
+
+For detailed controls, menu hierarchies, and automated CI safety fallbacks, refer to the [Interactive TUI Dashboard Guide](file:///f:/multimodel-dev-os/docs/dashboard.md).

package/docs/tui-safety.md

@@ -0,0 +1,59 @@
+# TUI & Plugin Safety Model
+
+MultiModel Dev OS enforces a sandboxed, low-risk execution model for both the Interactive TUI Dashboard and the Declarative Plugin System. This document outlines the security architecture and constraints that protect your development environment.
+
+---
+
+## Interactive Dashboard Safety
+
+The `dashboard`/`ui` command acts as a wrapper around the existing CLI commands. 
+
+### 1. Zero Arbitrary Code Execution
+The TUI engine is written entirely using Node.js's native `readline` module. It does not pull in any external third-party interactive libraries or prompt managers at runtime. This guarantees that no untrusted node package codes are executed during dashboard rendering.
+
+### 2. Explicit Approval Gates
+Any operation that alters the workspace directory (such as adapter synchronization or onboarding template setup) is configured to run in **Dry-Run mode** by default. To apply modifications, the underlying command must be run directly from the shell with the explicit `--approved` and `--force` flags.
+
+### 3. Equivalent Command Visibility
+Before executing any action from the menu, the dashboard prints the exact CLI command in bold text. This removes hidden actions and teaches the developer the underlying tooling mechanics.
+
+---
+
+## Declarative Plugin Sandboxing
+
+The plugin system allows community-contributed extensions while ensuring that they cannot infect the host machine or repository code.
+
+### 1. Strictly Config-Based (YAML)
+Plugins in MMDO cannot declare execution steps, binaries, or javascript files. They contain only metadata, workflow steps (mapping to pre-approved MMDO commands), and file paths to copy.
+
+### 2. Path Whitelisting (Write Containment)
+The installer restricts all plugin file copies to specific directories inside the workspace. The whitelisted paths are:
+* `.ai/plugins/`
+* `.ai/registries/`
+* `.ai/templates/`
+* `.ai/skills/`
+* `.ai/checks/`
+* `.ai/prompts/`
+* `.ai/adapters/`
+
+If a plugin manifest attempts to write to paths outside of these folders (such as `src/`, `lib/`, or `tests/`), the validator immediately throws an error and aborts the installation. To guarantee safety, the validation phase restricts plugin `slug` parameters to alphanumeric characters with dashes and underscores only (`/^[a-z0-9-_]+$/i`), hard-blocking directory traversal patterns (`..`, `/`, `\`) to prevent manifest write escapes.
+
+### 3. Blacklist Enforcement
+The system hard-blocks write operations to critical files or directories to prevent credentials exposure or project hijack:
+* `.env` and `.env.*` (secrets containment)
+* `.git/` (git history protection)
+* `.npmrc` (npm authentication protection)
+* `node_modules/` (dependency safety)
+* `package.json` and `package-lock.json` (preventing unauthorized package installations)
+
+### 4. Overwrite & Conflict Backups
+If a plugin attempts to copy files over existing workspace files:
+* Without `--force`, the installation aborts with conflict warnings.
+* With `--force`, the installer automatically creates backup copies (`<filename>.bak`) of the target files before overwriting them.
+
+---
+
+## Network & Package Quarantine
+
+* **No Network Calls**: Neither the dashboard nor the plugin engine executes network queries (e.g. `curl`, `fetch`, or remote API calls). All plugin checks and file copy actions are performed 100% offline.
+* **No Package Downloads**: Plugins cannot run `npm install` or call other package managers.

package/docs/use-cases.md

@@ -36,4 +36,25 @@ The universal fallback layout for Python, Go, Rust, or general backend setups.
 
 ---
 
+## Workflow-Focused Use Cases
+
+Beyond specific technology stacks, MultiModel Dev OS addresses operational friction in modern development environments:
+
+### A. Onboarding Legacy Repositories
+- **The Challenge:** Joining a massive legacy project with sparse docs. Developers spend days learning layout conventions, and AI assistants generate hallucinated file structures.
+- **The Solution:** Run `onboard analyze` to automatically map stack layers, followed by `init` to bootstrap structured rules. Developers instantly get a baseline `AGENTS.md` and `.ai/` directory that teaches incoming models exactly where files belong and how the project compiles.
+- **Demo:** Check out the **[Safe Onboarding Workflow](/demos/existing-repo-onboarding)**.
+
+### B. Cross-Tool Collaboration
+- **The Challenge:** Using Cursor for quick autocomplete while using Claude Code in the terminal to execute builds. Updates to rules in one tool aren't picked up by the other, leading to conflicting edits.
+- **The Solution:** Standardize rules in `AGENTS.md` and use `adapter sync` to write rules to all tool configurations in a single run. Both terminal agents and editor assistants stay aligned.
+- **Demo:** Check out the **[Universal Adapter Sync Workflow](/demos/adapter-sync)**.
+
+### C. Audited Self-Improvement Loops
+- **The Challenge:** Allowing autonomous agents to apply codebase improvements without a solid verification pipeline can lead to broken builds or silent data loss.
+- **The Solution:** Establish a feedback loop where models propose modifications as patch proposals. MultiModel Dev OS enforces Human-In-The-Loop (HITL) approval flags alongside automated `validate` and `doctor` checks before applying edits.
+- **Demo:** Check out the **[Safe Improvement Loop Workflow](/demos/safe-improvement-loop)**.
+
+---
+
 For a complete breakdown of all files, scaffolding structures, and custom developer skills included in each profile, refer to the [Templates Guide](templates-guide.md).

package/docs/v2-roadmap.md

@@ -1,115 +1,107 @@
-# MultiModel Dev OS — v2.0.0 Roadmap
+# MultiModel Dev OS — Roadmap: v2.x → v3.0
 
-This document outlines the development path, stabilization targets, and migration roadmap leading to the `v2.0.0` stable release of MultiModel Dev OS.
+This document outlines the development path, completed milestones, and future plans for MultiModel Dev OS.
 
 ---
 
-## 1. Release Objective
-
-The primary goal of the **v2.0.0 release** is to promote the experimental features introduced in `v1.2.0` (Template Galaxy, Model Compatibility Layer, and Android Expo template) into officially frozen, production-grade core components, and resume stable package publication to the public npm registry.
+## 1. Current Status
 
 > [!IMPORTANT]
-> **v2.0.1 is the active stable release.** NPM publishing is resumed, consolidating the Template Galaxy and Model registries.
+> **v2.8.1 is the active stable release** on the public npm registry. All features below marked ✅ are shipped and production-ready.
 
 ---
 
-## 2. Key Stabilization Targets
-
-### A. Template Galaxy Stabilization
-* Standardize the schema for template configurations under `.ai/schema/template.schema.json`.
-* Harden the built-in templates (`nextjs-saas`, `wordpress-site`, `ecommerce-store`, `seo-landing-page`, `expo-react-native-android`, `general-app`) to ensure they pass validation checks across diverse OS environments.
-
-### B. Model Registry Stabilization
-* Freeze the `.ai/models/` structure:
-  * `registry.yaml` — Core provider mappings and model metadata.
-  * `providers.yaml` — API endpoint declarations.
-  * `routing-presets.yaml` — Optimized task routing configurations.
-  * `local-models.yaml` — Offline execution definitions.
-* Standardize validation rules inside `validate` and `doctor` commands to verify YAML configuration syntax and compatibility.
-
-### C. Adapter Registry Stabilization
-* Freeze `.ai/adapters/registry.yaml`.
-* Extend support mapping for emerging developer tools (e.g. Continue, Cline, Roo Code, Aider, Windsurf).
-* Ensure cross-linking logic maintains strict custom boundaries so that updates in `AGENTS.md` synchronize with adapter targets without wiping user overrides.
-
-### D. Android Expo Template Stabilization
-* Hardening the `examples/expo-react-native-android/` foundation.
-* Verify clean execution of EAS Build and environment configurations on local developer machines and CI runner platforms.
-
-### E. CLI Compatibility Pass
-* Ensure the new subcommands introduced in `v1.2.0` are fully backward-compatible with `v1.0.0` and `v1.1.0` CLI patterns:
-  * `models` / `show-model`
-  * `providers`
-  * `route-model`
-  * `adapters` / `show-adapter`
-  * `skills` / `show-skill`
-  * `doctor --tokens`
-  * `validate --template`
+## 2. Completed Milestones
+
+### v2.0.0 — Template Galaxy & Model Registry ✅
+- Standardized model registries under `.ai/models/` (registry, providers, routing presets, local models)
+- Adapter registry expansion under `.ai/adapters/registry.yaml`
+- Android Expo mobile template (`examples/expo-react-native-android/`)
+- CLI registry subcommands: `models`, `show-model`, `providers`, `route-model`, `adapters`, `show-adapter`, `skills`, `show-skill`
+- Stable npm publication resumed
+
+### v2.2.0 — Codebase Scanner & Memory Engine ✅
+- `scan` command to inspect frameworks, package managers, and AI Dev OS files
+- `memory build`, `memory refresh`, and `memory diff` commands
+- Hash-compressed memory indexing to `.ai/intelligence/memory.hash.json`
+- Secret-safety exclusions for `.env`, `.npmrc`, `.keystore` files
+
+### v2.3.0 — Feedback Learning & Proposal Engine ✅
+- `feedback add`, `feedback list`, `feedback summarize` commands
+- `improve propose`, `improve review`, `improve status` commands
+- Read-only proposal drafting with safety gates
+- Feedback logs and learning rules compilation
+
+### v2.4.0 — Approved Proposal Application Engine ✅
+- `improve validate`, `improve diff`, `improve apply` subcommands
+- 12 strict safety gates including path boundary, protected paths, idempotency
+- Applied Proposals Audit Log (`apply-log.jsonl`) with SHA-256 hashing
+- Deterministic operations: `create_file`, `append_line`, `replace_text`
+
+### v2.5.0 — Repository Intelligence Command Center ✅
+- `status` command — compact operational dashboard
+- `workflow list`, `show`, `plan`, `run` — multi-agent workflow orchestration
+- `handoff build`, `handoff show` — token-compressed session context
+- Safe execution boundaries — no destructive operations from workflows
+
+### v2.6.0 — Real-Repo Onboarding & Adapter Sync ✅
+- `onboard analyze`, `recommend`, `plan`, `apply`, `status` — existing repo onboarding
+- `adapter status`, `diff`, `sync` — IDE adapter rule file synchronization
+- Template recommendation heuristics with confidence scores
+- Safety overwrites with automatic `.bak` backups
+- `doctor --onboarding` diagnostics
+
+### v2.7.0 — Website, Demo & Distribution System ✅
+- Restructured homepage as a product conversion funnel
+- Created 5 structured, copy-paste interactive demo workflow pages
+- Documented comprehensive distribution and release workflows
+- Added new SVG visual assets for onboarding and adapter sync flows
+- Created docs-first examples for key developer workflows
+- Updated sitemaps, model registries, and search indices
+
+### v2.8.0 / v2.8.1 — Interactive TUI Dashboard & Plugin Hooks ✅
+- **Interactive TUI Dashboard**: Added `dashboard`/`ui` command launching a zero-dependency keyboard-interactive command center built with Node's native `readline` module.
+- **Declarative Plugin Hooks**: Added `plugin` command suite (`list`, `show`, `validate`, `install`, `status`) and JSON schema to securely extend workspace templates, workflows, and skills.
+- **Secure Plugin Installer**: Supports `--approved` execution gate, path whitelisting to `.ai/` and `adapters/` directories, and automatic conflict `.bak` backups.
+- **Headless Fallback & CI Polish**: Polish dry-run outputs and added `--list-actions` parameter to prevent TUI hangs in CI.
+- **Path Traversal Hardening**: Enforce alphanumeric slug checks (`/^[a-z0-9-_]+$/i`) and pattern validation bounds to block traversal vectors.
 
 ---
 
-## 3. Package Publishing Checklist
+## 3. Publishing Workflow
 
-Before executing the `v2.0.0` release on the npm registry, the following steps must be completed:
+All releases follow this strict publishing checklist:
 
-1. [x] Set version to `2.0.0` in `package.json`.
-2. [x] Ensure `scripts/prepublish-guard.js` allows the publish (since version starts with `2.`).
-3. [x] Run all verification suites:
-   ```bash
-   npm run verify
-   ```
-4. [x] Build documentation static bundles cleanly:
-   ```bash
-   npm run docs:build
-   ```
-5. [x] Perform a dry-run publish to review package hygiene:
-   ```bash
-   npm publish --dry-run
-   ```
-6. [x] Set the required publication environment variable:
-   * **PowerShell:** `$env:MMDO_ALLOW_PUBLISH="true"`
-   * **Bash:** `export MMDO_ALLOW_PUBLISH=true`
-7. [x] Publish the package to the public registry:
+1. Bump version in `package.json`
+2. Run `npm run verify` (220+ assertions must pass)
+3. Run `npm run docs:build` to verify documentation
+4. Run `npm publish --dry-run` to review package hygiene
+5. Set `MMDO_ALLOW_PUBLISH=true` and publish:
    ```bash
-   npm publish --access public
+   MMDO_ALLOW_PUBLISH=true npm publish --access public
    ```
 
 ---
 
-## 4. Migration Notes: npm latest to v2.0.0
+## 4. Upcoming: v2.9.0 — Auto-Detection & Custom Adaptors
 
-* **Direct Upgrades**: Projects running the last stable npm package (e.g., `1.1.0` / `1.0.0`) can migrate to `2.0.0` by executing `npx multimodel-dev-os@latest init --force` or installing the package locally.
-* **Registry Release**: Now that v2.0.0 is released, cloning the repository is no longer required to access Layer 1 templates or model registries. Simply run:
-  ```bash
-  npx multimodel-dev-os@latest init
-  ```
-* **Configuration Upgrades**: Existing `.ai/` folders can be upgraded by running `init --force` to pull the new centralized registries (`.ai/models/` and `.ai/adapters/`) into the workspace.
+*   **Adapter Auto-Detection**: Detect installed tools and automatically recommend adapter setup.
+*   **Custom Adapter Hookups**: Programmatic hooks allowing plugins to register physical adapter configurations dynamically.
 
 ---
 
-## 5. Final Release Gate
+## 5. Future: v3.0.0 — Unified Autonomous Co-Pilot Ecosystem
 
-The `v2.0.0` release requires:
-1. 100% pass rate on all automated linter and verifier checks.
-2. Complete documentation updates across all guides and discovery indices.
-3. Explicit maintainer sign-off on local testing of the Android Expo template.
+*   **Full Multi-Agent Orchestration**: Dynamic task handoffs between specialized agents
+*   **Distributed Registry Syncing**: Team-wide configuration synchronization
+*   **Cryptographic Proposal Signing**: Tamper-proof improvement proposals
+*   **Real-Time Collaboration**: Live workspace state sharing between agents and developers
+*   **Cloud-Native Intelligence**: Optional cloud-backed memory and feedback aggregation
 
 ---
 
-## 6. Future Stages: v2.1.0 to v3.0.0
-
-*   **v2.1.0 — Intelligence Core & Registries Foundation**
-    *   Design and document schemas (`memory.schema.json`, `feedback.schema.json`).
-    *   Introduce `.ai/registries/` configuration databases.
-    *   Implement CLI routing helper `mmdo capability route` and `mmdo memory build/refresh`.
-*   **v2.2.0 — Feedback Loops & Tool Integrations**
-    *   Add `mmdo learn` capability to append feedback metrics.
-    *   Define `.ai/registries/tools.yaml` with MCP protocol interfaces.
-*   **v2.3.0 — Proposal Engine & Safety Controls**
-    *   Deploy proposal structures under `.ai/proposals/`.
-    *   Implement CLI pipeline `mmdo improve propose/review/apply`.
-*   **v2.4.0 — Local/Offline Operations**
-    *   Integrate local model scoring (Llama.cpp, Ollama) and offline schema checks.
-*   **v3.0.0 — Unified Autonomous Co-Pilot Ecosystem**
-    *   Full multi-agent orchestration workflows with dynamic task handoffs.
-    *   Distributed registry syncing and cryptographically signed self-improvement proposals.
+## 6. Migration Notes
+
+* **From any v2.x**: Run `npx multimodel-dev-os@latest init --force` to pull latest configuration files. Existing files are backed up automatically.
+* **From v1.x**: See the [Migration Guide](/migration-guide) for the upgrade path.
+* **Fresh install**: Simply run `npx multimodel-dev-os@latest init` — no prior setup required.

package/docs/workflow-orchestration.md

@@ -32,6 +32,9 @@ Executes the workflow steps sequentially:
 npx multimodel-dev-os workflow run repo-health
 ```
 
+> [!TIP]
+> You can also run, plan, and list workflows interactively through the [TUI Dashboard](file:///f:/multimodel-dev-os/docs/dashboard.md) under the **Quality Gates & Diagnostics** or **Memory & Intelligence** menus.
+
 ---
 
 ## 2. Standard Built-in Workflows

package/examples/adapter-sync/README.md

@@ -0,0 +1,45 @@
+# Example: Adapter Sync
+
+Sync your AGENTS.md rules to `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, and more — automatically.
+
+## Prerequisites
+
+- Node.js 18+
+- A MultiModel Dev OS workspace (`npx multimodel-dev-os@latest init`)
+
+## Commands
+
+```bash
+# Check which adapters are enabled/disabled
+npx multimodel-dev-os@latest adapter status
+
+# Preview diff for a specific adapter
+npx multimodel-dev-os@latest adapter diff cursor
+
+# Sync all enabled adapters (requires approval)
+npx multimodel-dev-os@latest adapter sync all --approved
+
+# Verify workspace health
+npx multimodel-dev-os@latest validate
+```
+
+## Expected Result
+
+```
+🔄 Syncing adapters...
+  CREATE .cursorrules
+  CREATE CLAUDE.md
+  CREATE .vscode/settings.json
+✅ 3 adapters synced.
+```
+
+## Safety
+
+- `adapter status` and `adapter diff` are read-only
+- `adapter sync` requires `--approved` flag
+- Existing files need `--force` to overwrite
+- All overwrites create `.bak` backups
+
+## Full Demo
+
+See the [complete walkthrough](/demos/adapter-sync) for step-by-step instructions.

package/examples/command-center/README.md

@@ -0,0 +1,59 @@
+# Example: Command Center
+
+Use the repository command center to get a compact operational dashboard and run automated workflows.
+
+## Prerequisites
+
+- Node.js 18+
+- A MultiModel Dev OS workspace (`npx multimodel-dev-os@latest init`)
+
+## Commands
+
+```bash
+# View compact project dashboard
+npx multimodel-dev-os@latest status
+
+# List available workflows
+npx multimodel-dev-os@latest workflow list
+
+# Dry-run a workflow to see what would execute
+npx multimodel-dev-os@latest workflow plan repo-health
+
+# Run a workflow (read-only, safe execution boundaries)
+npx multimodel-dev-os@latest workflow run repo-health
+
+# Build and view session handoff
+npx multimodel-dev-os@latest handoff build
+npx multimodel-dev-os@latest handoff show
+```
+
+## Expected Result
+
+```
+📊 Repository Status: my-project
+  Version: 1.0.0
+  Frameworks: nextjs, typescript
+  Memory: fresh (updated 2 min ago)
+  Feedback entries: 3
+  Proposals: 1 draft, 0 applied
+```
+
+## Available Workflows
+
+| Workflow | Purpose |
+|----------|---------|
+| `repo-health` | Run validate, doctor, and scan checks |
+| `memory-refresh` | Update hash-compressed memory index |
+| `feedback-review` | Summarize pending feedback entries |
+| `proposal-review` | Review and display proposal statuses |
+| `release-check` | Pre-flight release verification |
+
+## Safety
+
+- `status`, `workflow list`, and `workflow plan` are read-only
+- `workflow run` is restricted to safe, non-destructive CLI functions
+- No proposals are applied, no shell commands are executed destructively
+
+## Full Demo
+
+See the [release check walkthrough](/demos/release-check) for the verification workflow.

package/examples/real-repo-onboarding/README.md

@@ -0,0 +1,53 @@
+# Example: Real Repo Onboarding
+
+Onboard an existing codebase into MultiModel Dev OS safely — no breaking changes, automatic backups.
+
+## Prerequisites
+
+- Node.js 18+
+- An existing project directory with source code
+
+## Commands
+
+```bash
+# Step 1: Analyze your project (read-only)
+npx multimodel-dev-os@latest onboard analyze
+
+# Step 2: Get template recommendations (read-only)
+npx multimodel-dev-os@latest onboard recommend
+
+# Step 3: Generate onboarding plan (writes to .ai/intelligence/, gitignored)
+npx multimodel-dev-os@latest onboard plan
+
+# Step 4: Apply configs (creates files, requires approval)
+npx multimodel-dev-os@latest onboard apply --approved
+
+# Step 5: Verify completeness
+npx multimodel-dev-os@latest onboard status
+```
+
+## Expected Result
+
+```
+📊 Onboarding Status
+  Completeness: 100%
+  Root files: AGENTS.md ✓ MEMORY.md ✓ TASKS.md ✓ RUNBOOK.md ✓
+  Config: .ai/config.yaml ✓
+```
+
+## Files Created
+
+- `AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`
+- `.ai/config.yaml` and `.ai/context/` directory
+- `.ai/intelligence/onboarding.plan.json` (gitignored)
+- `.ai/intelligence/onboarding.report.md` (gitignored)
+
+## Safety
+
+- Steps 1-3 are fully read-only
+- Step 4 never overwrites existing files without `--force`
+- All overwrites create `.bak` backups automatically
+
+## Full Demo
+
+See the [complete walkthrough](/demos/existing-repo-onboarding) for expected terminal output and detailed explanations.