multimodel-dev-os 2.6.0 → 2.8.1

package/docs/demos/multi-agent-handoff.md

@@ -0,0 +1,88 @@
+# Demo: Multi-Agent Handoff
+
+> **Who**: Developers switching between AI models (e.g., Claude → Gemini → Cursor) mid-session.
+> **Time**: ~1 minute | **Prerequisites**: Node.js 18+, a MultiModel Dev OS workspace with some history
+
+---
+
+## Starting State
+
+You've been coding with Claude Code for an hour. You want to switch to Gemini for an audit pass, but you don't want to lose the session context.
+
+---
+
+## Workflow
+
+### Step 1: Build the memory index
+
+```bash
+npx multimodel-dev-os@latest memory build
+```
+
+**What happens**: Scans your codebase and writes a hash-compressed index to `.ai/intelligence/memory.hash.json` and a human-readable summary to `.ai/intelligence/memory.summary.md`. Both are gitignored.
+
+### Step 2: Compile the handoff spec
+
+```bash
+npx multimodel-dev-os@latest handoff build
+```
+
+**What happens**: Compiles a token-compressed session context document at `.ai/intelligence/handoff.md`. This includes:
+- Project structure summary
+- Active tasks from `TASKS.md`
+- Recent memory state
+- Feedback log highlights
+- Proposal status
+
+### Step 3: View the handoff
+
+```bash
+npx multimodel-dev-os@latest handoff show
+```
+
+**Expected output**: Prints the handoff document to stdout — ready to paste into your next agent session.
+
+### Step 4: Check workspace status
+
+```bash
+npx multimodel-dev-os@latest status
+```
+
+**What happens**: Shows a compact dashboard of package details, framework signals, memory freshness, feedback counts, proposal states, and audit metrics.
+
+---
+
+## What Gets Created
+
+| File | Purpose | Gitignored? |
+|------|---------|-------------|
+| `.ai/intelligence/memory.hash.json` | Hash-compressed file index | ✅ |
+| `.ai/intelligence/memory.summary.md` | Human-readable memory summary | ✅ |
+| `.ai/intelligence/handoff.md` | Token-compressed session context | ✅ |
+
+---
+
+## Safety Notes
+
+- **All commands are read-only** except `memory build` and `handoff build` which write to gitignored `.ai/intelligence/` paths
+- No project source files are modified
+- Handoff documents are designed to be ephemeral — rebuild before each agent switch
+- Secret-safety exclusions automatically skip `.env`, `.npmrc`, `.keystore` files
+
+---
+
+## Cleanup
+
+```bash
+rm -f .ai/intelligence/memory.hash.json
+rm -f .ai/intelligence/memory.summary.md
+rm -f .ai/intelligence/handoff.md
+```
+
+---
+
+## Next Steps
+
+- **Paste handoff into your next agent** — copy the output of `handoff show` into Claude, Gemini, or Cursor
+- **Run a health workflow**: `npx multimodel-dev-os@latest workflow run repo-health`
+- **Refresh after more work**: `npx multimodel-dev-os@latest memory refresh`

package/docs/demos/release-check.md

@@ -0,0 +1,109 @@
+# Demo: Release Check
+
+> **Who**: Maintainers preparing a release or contributors validating their PR.
+> **Time**: ~1 minute | **Prerequisites**: Node.js 18+, a MultiModel Dev OS workspace
+
+---
+
+## Starting State
+
+You've made changes to your MultiModel Dev OS workspace and want to verify everything is healthy before committing or publishing.
+
+---
+
+## Workflow
+
+### Step 1: Run the verification suite
+
+```bash
+npx multimodel-dev-os@latest verify
+```
+
+**What happens**: Runs 214+ structural assertions checking:
+- All required files exist (root contracts, adapters, templates, schemas, docs)
+- YAML registries parse correctly with expected root keys
+- Package.json version matches CLI output
+- npm pack dry-run reports correct version
+- No runtime files (memory, feedback, proposals) are committed
+
+**Expected output**:
+```
+  ✓ AGENTS.md
+  ✓ MEMORY.md
+  ...
+  ✓ package.json version is valid: 2.7.0
+  ✓ CLI help displays v2.7.0
+  ✓ npm pack --dry-run reports version 2.7.0
+  ✓ No runtime proposals committed
+
+  Pass: 213  Fail: 0  Warn: 0  Total: 213
+```
+
+### Step 2: Run the release doctor
+
+```bash
+npx multimodel-dev-os@latest doctor --release
+```
+
+**What happens**: Checks version alignment across `package.json`, `install.sh`, and `install.ps1`. Warns about blacklisted files (like `.npmrc`) in the package root.
+
+**Expected output**:
+```
+🩺 Running release audit doctor
+  ✓ package.json version: 2.7.0
+  ✓ scripts/install.sh version aligns: 2.7.0
+  ✓ scripts/install.ps1 version aligns: 2.7.0
+```
+
+### Step 3: Build the docs
+
+```bash
+npm run docs:build
+```
+
+**What happens**: Compiles the VitePress documentation site. Catches broken links, missing assets, and template errors.
+
+### Step 4: Dry-run the npm package
+
+```bash
+npm pack --dry-run
+```
+
+**What happens**: Shows exactly what files would be included in the npm tarball without actually creating it. Verify no secrets, caches, or development artifacts are included.
+
+### Step 5: Test CLI commands
+
+```bash
+npx multimodel-dev-os@latest --help
+npx multimodel-dev-os@latest doctor --onboarding
+npx multimodel-dev-os@latest doctor --intelligence
+```
+
+---
+
+## What Gets Created
+
+Nothing — all commands in this demo are read-only diagnostic checks.
+
+---
+
+## Safety Notes
+
+- **Every command is read-only** — no files are created, modified, or deleted
+- The verification suite has a non-zero exit code on failure, making it CI-compatible
+- `npm pack --dry-run` does not create a tarball file
+- `docs:build` outputs to `docs/.vitepress/dist/` which is gitignored
+
+---
+
+## Cleanup
+
+No cleanup needed — this demo creates no files.
+
+---
+
+## Next Steps
+
+- **Commit your changes**: `git add . && git commit -m "your message"`
+- **Create a release**: Follow the [Distribution Guide](/distribution)
+- **Publish to npm**: Follow the [NPM Publishing Runbook](/npm-publishing)

package/docs/demos/safe-improvement-loop.md

@@ -0,0 +1,119 @@
+# Demo: Safe Improvement Loop
+
+> **Who**: Teams who want their AI agents to propose codebase improvements with human-in-the-loop safety.
+> **Time**: ~2 minutes | **Prerequisites**: Node.js 18+, a MultiModel Dev OS workspace
+
+---
+
+## Starting State
+
+You have a project with MultiModel Dev OS initialized and at least one coding session completed. You've noticed patterns you want the system to learn.
+
+---
+
+## Workflow
+
+### Step 1: Record developer feedback
+
+```bash
+npx multimodel-dev-os@latest feedback add "Always use TypeScript strict mode" --type preference
+npx multimodel-dev-os@latest feedback add "Avoid Tailwind CSS in this project" --type override
+```
+
+**What happens**: Logs feedback entries to `.ai/intelligence/feedback-log.jsonl` (gitignored). Each entry is timestamped and typed.
+
+### Step 2: Compile feedback into learning rules
+
+```bash
+npx multimodel-dev-os@latest feedback summarize
+```
+
+**What happens**: Reads all feedback entries and compiles them into `.ai/intelligence/learning-rules.md` — a human-readable file that AI agents can reference. Gitignored.
+
+### Step 3: Propose an improvement
+
+```bash
+npx multimodel-dev-os@latest improve propose --title "Add TypeScript strict config"
+```
+
+**What happens**: Creates a structured proposal file under `.ai/proposals/` with frontmatter, description, and optionally a deterministic operations JSON block.
+
+### Step 4: Review proposals
+
+```bash
+npx multimodel-dev-os@latest improve review
+npx multimodel-dev-os@latest improve status
+```
+
+**What happens**: Lists all proposals and their statuses (draft, approved, applied, refused). Read-only.
+
+### Step 5: Validate safety gates
+
+```bash
+npx multimodel-dev-os@latest improve validate .ai/proposals/proposal-XXXX.md
+```
+
+**What happens**: Runs 12 safety gates including path boundary checks, protected path blocks, approval status, and operation type validation. Read-only.
+
+### Step 6: Preview changes
+
+```bash
+npx multimodel-dev-os@latest improve diff .ai/proposals/proposal-XXXX.md
+```
+
+**What happens**: Shows a unified diff of what the proposal would change. No files are modified.
+
+### Step 7: Apply the approved proposal
+
+```bash
+npx multimodel-dev-os@latest improve apply .ai/proposals/proposal-XXXX.md --approved
+```
+
+**What happens**: Executes the deterministic operations (`create_file`, `append_line`, `replace_text`). Records execution in `.ai/proposals/apply-log.jsonl` with SHA-256 hashes.
+
+### Step 8: Check the audit log
+
+```bash
+npx multimodel-dev-os@latest improve log
+```
+
+---
+
+## What Gets Created
+
+| File | Purpose | Gitignored? |
+|------|---------|-------------|
+| `.ai/intelligence/feedback-log.jsonl` | Raw feedback entries | ✅ |
+| `.ai/intelligence/learning-rules.md` | Compiled learning rules | ✅ |
+| `.ai/proposals/proposal-XXXX.md` | Improvement proposal | ❌ (reviewable) |
+| `.ai/proposals/apply-log.jsonl` | Execution audit log | ✅ |
+
+---
+
+## Safety Notes
+
+- **Steps 1-6 are non-destructive** — feedback logging, proposal drafting, review, and diff are all safe
+- **Step 7 modifies files** but only through validated deterministic operations
+- 12 safety gates must pass before any apply can execute
+- Proposals require explicit `--approved` flag
+- All applied changes are audited with pre/post SHA-256 file hashes
+- Protected paths (`.git/`, `.env`, `node_modules/`, `apply-log.jsonl`) are blocked
+
+---
+
+## Cleanup
+
+```bash
+# Remove feedback and proposals (gitignored files stay local)
+rm -f .ai/intelligence/feedback-log.jsonl
+rm -f .ai/intelligence/learning-rules.md
+rm -rf .ai/proposals/
+```
+
+---
+
+## Next Steps
+
+- **Build memory index**: `npx multimodel-dev-os@latest memory build`
+- **Run a workflow cycle**: `npx multimodel-dev-os@latest workflow run feedback-review`
+- **Hand off to next agent**: [Multi-Agent Handoff Demo](/demos/multi-agent-handoff)

package/docs/distribution.md

@@ -0,0 +1,195 @@
+# Distribution & Release Guide
+
+How to distribute, verify, and publish MultiModel Dev OS releases.
+
+---
+
+## Installation Methods
+
+### NPX (Recommended)
+
+```bash
+# Initialize a new workspace
+npx multimodel-dev-os@latest init
+
+# Onboard an existing project
+npx multimodel-dev-os@latest onboard analyze
+```
+
+### Global Install
+
+```bash
+npm install -g multimodel-dev-os
+multimodel-dev-os init
+```
+
+### Fallback Scripts
+
+**macOS / Linux / WSL:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1 | iex
+```
+
+---
+
+## Pre-Release Checklist
+
+Before every release, run this complete verification sequence:
+
+### 1. Version Bump
+
+Update version strings in all 7 locations:
+
+| File | Field |
+|------|-------|
+| `package.json` | `version` |
+| `package-lock.json` | `version` (2 occurrences) |
+| `scripts/install.sh` | `VERSION` |
+| `scripts/install.ps1` | `$Version` |
+| `docs/.vitepress/config.js` | `softwareVersion` in JSON-LD |
+| `docs/public/llms.txt` | Title version |
+| `docs/public/llms-full.txt` | Title version |
+
+### 2. Changelog Entry
+
+Add a new section to `CHANGELOG.md` following the Keep a Changelog format.
+
+### 3. Verification Suite
+
+```bash
+# Run 214+ structural assertions
+npm run verify
+
+# Build docs to catch broken links
+npm run docs:build
+
+# Dry-run the npm package
+npm pack --dry-run
+
+# Verify CLI version
+node bin/multimodel-dev-os.js --help
+
+# Release doctor
+node bin/multimodel-dev-os.js doctor --release
+```
+
+**Expected results:**
+- `verify`: 213+ pass, 0 fail, 1 expected .npmrc warning
+- `docs:build`: builds without errors
+- `pack --dry-run`: reports correct version in tarball name
+- CLI `--help`: shows correct version
+- `doctor --release`: version alignment passes
+
+### 4. Commit
+
+```bash
+git add .
+git diff --cached --stat
+git commit -m "docs: release vX.Y.Z [description]"
+```
+
+---
+
+## Publishing to npm
+
+> [!WARNING]
+> **Manual publish only.** The `prepublish-guard.js` script blocks accidental publishes. You must explicitly set the environment variable.
+
+```bash
+# Set the publish guard
+export MMDO_ALLOW_PUBLISH=true   # bash
+$env:MMDO_ALLOW_PUBLISH = "true" # PowerShell
+
+# Publish to npm
+npm publish --access public
+```
+
+### Post-Publish Smoke Test
+
+After publishing, verify the package works correctly:
+
+```bash
+# Create a temp directory
+mkdir /tmp/mmdo-smoke && cd /tmp/mmdo-smoke
+
+# Test npx execution
+npx multimodel-dev-os@latest --help
+npx multimodel-dev-os@latest init --dry-run
+
+# Verify version matches
+npx multimodel-dev-os@latest doctor --release
+
+# Cleanup
+cd .. && rm -rf /tmp/mmdo-smoke
+```
+
+---
+
+## Package Hygiene
+
+### What's Included in the Tarball
+
+The `files` field in `package.json` controls what ships:
+
+```
+AGENTS.md, MEMORY.md, TASKS.md, RUNBOOK.md
+.ai/          → Configuration, schemas, registries, templates
+adapters/     → IDE/tool adapter files
+scripts/      → Install scripts, verify scripts
+docs/         → Documentation source (excluding .vitepress/dist/ and cache/)
+examples/     → Template examples
+bin/          → CLI executable
+assets/       → Visual assets
+```
+
+### What's Excluded
+
+- `node_modules/` — dev dependencies only
+- `docs/.vitepress/dist/` — built docs (deployed separately via GitHub Pages)
+- `docs/.vitepress/cache/` — build cache
+- `.ai/intelligence/` runtime files — memory, feedback, proposals
+- `.npmrc` — expected warning in verify suite
+
+### The `.npmrc` Warning
+
+The verify suite reports 1 expected warning about `.npmrc` existing in the package root. This file contains only the registry URL and no credentials. It's flagged as a security best practice reminder. This warning is intentional and does not block publishing.
+
+---
+
+## GitHub Releases
+
+After publishing to npm:
+
+1. Tag the commit: `git tag vX.Y.Z`
+2. Push tags: `git push origin main --tags`
+3. Create a GitHub Release from the tag
+4. Copy the changelog entry as the release body
+5. Verify the GitHub Pages deployment triggered
+
+---
+
+## Prepublish Guard
+
+The [prepublish-guard.js](../scripts/prepublish-guard.js) script runs automatically before `npm publish`. It:
+
+1. Checks for `MMDO_ALLOW_PUBLISH=true` environment variable
+2. If not set, prints a warning and exits with code 1
+3. Prevents accidental publishes from CI or local dev environments
+
+This guard ensures every publish is an intentional, reviewed action.
+
+---
+
+## Version Alignment
+
+The `doctor --release` command verifies version parity across:
+- `package.json`
+- `scripts/install.sh`
+- `scripts/install.ps1`
+
+Any mismatch is reported as a warning. Fix alignment before publishing.

package/docs/faq.md

@@ -1,67 +1,134 @@
-# FAQ: MultiModel Dev OS Questions & Answers
+# FAQ
 
-Frequently asked questions regarding MultiModel Dev OS, AI coding agents compatibility, and prompt context optimization.
-
-> **Use when**: Resolving setup ambiguities, understanding comparative advantages over simple rules files, or auditing CLI validations.
+Frequently asked questions about MultiModel Dev OS, AI coding agents compatibility, and prompt context optimization.
 
 ---
 
 ## General
 
 **What is MultiModel Dev OS?**
-A set of markdown templates and directory structures that allow multiple AI coding tools (Codex, Cursor, Claude Code, Gemini, Antigravity, VS Code) to share a single portable AI project context. It acts like `.editorconfig` but for AI assistants.
+A set of markdown templates and directory structures that allow multiple AI coding tools (Codex, Cursor, Claude Code, Gemini, Antigravity, VS Code) to share a single portable AI project context. Think of it as `.editorconfig` but for AI assistants.
 
 **Is this a runtime operating system?**
-No. It is a metaphorical "OS" providing standard files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) to coordinate multiple tools.
+No. It is a workspace configuration standard — standard files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) and a `.ai/` directory that coordinate multiple tools. There is no background process, no daemon, and no runtime overhead.
 
 **What does "multimodel" mean?**
-Multiple distinct AI coding models/agents (such as Codex, Antigravity, Cursor, and Claude Code) operating sequentially on the exact same workspace branch.
+Multiple distinct AI coding models/agents (like Codex, Cursor, Claude Code, and Gemini) operating on the **same workspace** without context loss or instruction drift.
+
+**How is this different from just writing my own `.cursorrules` or `CLAUDE.md`?**
+Those are tool-specific instruction files. If you use multiple tools, you end up maintaining duplicated rules that quickly drift out of sync. MultiModel Dev OS gives you a **single source of truth** (`AGENTS.md`) and automatically adapts it for each tool. You write rules once, every tool reads them.
+
+---
+
+## Demo Workflows
+
+**How do I run the demo workflows?**
+Our demos are fully self-contained markdown walkthroughs. You can copy the commands directly from the demo pages, run them in your terminal, and observe the output. See the **[Demos Hub](/demos/)** for all available workflows.
+
+**Do the demos make any changes to my system?**
+The demos are designed to run in a safe, isolated, or dry-run configuration. For example, `onboard analyze` is entirely read-only, and onboarding plans and adapter syncs require developer approval before writing files. We also provide clear **Cleanup** sections on every demo page to undo any files created.
 
 ---
 
-## Setup
+## Setup & Installation
 
 **Do I need Node.js?**
 It depends on your installation path:
-* **Yes:** If you run the primary, recommended `npx multimodel-dev-os@latest init` workflow.
+* **Yes:** If you use the primary `npx multimodel-dev-os@latest init` workflow (recommended).
 * **No:** If you run the fallback bash (`install.sh`) or PowerShell (`install.ps1`) one-liners.
 
-**Why not just write a single manual AGENTS.md myself?**
-While you can write a raw markdown file, MultiModel Dev OS offers:
-1. **Automated Bridging:** Adapters dynamically map your root source to Cursor, Claude, and Gemini native rules.
-2. **Context Budgets:** Toggle **Caveman Mode** to slash prompt rules overhead by **~79%**.
-3. **Structured Verification:** Built-in CLI commands validate workspace specifications instantly.
+**Can I use this with an existing project?**
+Yes! The `onboard` command suite is designed specifically for this. It analyzes your project structure, recommends the best template, generates a plan, and applies configs safely with automatic backups:
+```bash
+npx multimodel-dev-os@latest onboard analyze
+npx multimodel-dev-os@latest onboard apply --approved
+```
+
+**Does this overwrite my existing files?**
+Never by default. The CLI audits for conflicts before writing anything. To overwrite existing files, you must explicitly pass `--force`, and the system automatically creates `.bak` backups.
 
 ---
 
-## Adapters
+## Adapters & Tools
 
 **Do I copy adapter files to my project root?**
-Yes, for tools that auto-detect specific files:
-- Cursor → `.cursorrules`
-- Claude Code → `CLAUDE.md`
-- VS Code → `.vscode/settings.json`
+You can do it automatically with the `adapter sync` command:
+```bash
+npx multimodel-dev-os@latest adapter sync all --approved
+```
+Or manually:
+- Cursor → `cp adapters/cursor/.cursorrules .cursorrules`
+- Claude Code → `cp adapters/claude/CLAUDE.md CLAUDE.md`
+- VS Code → `cp -r adapters/vscode/.vscode/ .vscode/`
+
+**Does this work with MCP tools?**
+Yes. MultiModel Dev OS includes a `.ai/registries/tools.yaml` that defines MCP tool integrations (like gcloud, Chrome DevTools). The tool registry maps capabilities dynamically rather than hardcoding tool names.
+
+**What AI models does this support?**
+All of them. The `.ai/models/` directory contains a model registry with capability scores, routing presets, and provider configurations. It supports cloud models (GPT-4, Claude, Gemini), local models (Llama, Ollama), and everything in between. No model is hardcoded — the registry routes tasks based on capability scores.
 
 ---
 
 ## Caveman Mode
 
 **When should I use Caveman Mode?**
-**Best for**: Context optimization for AI coding when you are using compact context budget windows, smaller models, or want to save money on API bill parameters.
+Use Caveman Mode when you want to minimize prompt token overhead — ideal for tight API budgets, smaller context windows, or when you want to save money on API calls. It compresses the workspace rules by **~79%** using shorthand declarations.
+
+---
+
+## Intelligence & Safety
+
+**Is this safe? Can it modify my code?**
+MultiModel Dev OS is primarily a **read-only** workspace configuration layer. The only write operations are:
+- `init` / `onboard apply` — creates configuration files (with conflict detection)
+- `memory build` — creates memory index files under `.ai/intelligence/` (gitignored)
+- `improve apply` — applies approved proposals (requires explicit `--approved` flag and passes 12 safety gates)
+
+No command can execute arbitrary shell commands, and destructive operations always require explicit developer approval.
+
+**What are the safety gates?**
+The improvement proposal system enforces 12 strict safety checks including path boundary containment, protected path blocks (`.git/`, `.env`, `node_modules/`), idempotency verification, and mandatory human approval. Every apply action is logged in an append-only audit trail.
+
+---
+
+## TUI & Plugins
+
+**What is the Interactive TUI Dashboard?**
+It is a terminal-based operational menu (`npx multimodel-dev-os dashboard` or `ui`) that allows developers to run diagnostics, sync rules, build memory indexes, and check proposal status in a guided interface. It uses Node.js's native `readline` module for raw-keypress navigation, keeping execution zero-dependency and fast.
+
+**Will the TUI Dashboard hang in CI/CD pipelines?**
+No. The dashboard detects when stdin or stdout is non-interactive. In non-TTY environments, or when `--dry-run` or `--list-actions` is passed, it prints a grouped preview of all options with their equivalent CLI commands and exits immediately, preventing pipelines from stalling.
+
+**How secure is the Declarative Plugin system?**
+Extremely secure. Plugins are strictly configuration-based (YAML manifest files). They cannot run arbitrary bash commands, execute node scripts, download npm packages, or make network calls. File copies are restricted to whitelisted `.ai/` and `adapters/` directories, and blacklists protect files like `.env`, `.git/`, `package.json`, and source code folders. Overwriting existing files requires `--force` and automatically generates backups.
 
 ---
 
 ## Diagnostics & Validation
 
 **What is the difference between `validate` and `doctor`?**
-* **`validate`** is strict and verifies compliance with the directory schema.
-* **`doctor`** is advisory and warns you about large unignored directories or empty placeholders.
+* **`validate`** — Strict compliance gate. Checks if required files exist and adapter configs are structurally correct. Exits with code 1 on failures. Use in CI/CD.
+* **`doctor`** — Advisory audit. Warns about large unignored directories, missing `.gitignore` entries, stale memory indexes, and potential token waste. Non-blocking.
+
+---
+
+## Contributing
+
+**How do I contribute a new adapter?**
+1. Create a directory under `adapters/{tool-name}/`
+2. Add the tool-native instruction files referencing `/AGENTS.md` and `/MEMORY.md`
+3. Add a clear `setup.md` installation guide
+4. Update the adapter registry in `.ai/adapters/registry.yaml`
+5. Submit a PR — see our [Contributing Guidelines](/contributing)
 
 ---
 
 ## Protocol & Migration
 
 **Is the MultiModel Dev OS protocol stable?**
-Yes. As of version `v1.1.0`, the core specifications are officially frozen and backward-compatible. This ensures that codebases prepared using `v1.1.0` or later operate seamlessly inside all `1.x` and `2.x` ecosystems.
+Yes. The core Layer 1 specifications (root contracts and `.ai/` directory structure) are officially frozen and backward-compatible. Codebases prepared using any `v1.x` or `v2.x` release operate seamlessly with the latest version.
+
+**How do I upgrade from an older version?**
+Run `npx multimodel-dev-os@latest init --force` to pull the latest configuration files. Existing files will be backed up automatically. See the [Migration Guide](/migration-guide) for details.
 
-Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.
+Explore our [Stable Protocol Specification](/stable-protocol) or [CLI Command Reference](/CLI) for more details.