multimodel-dev-os 2.0.1 → 2.8.0

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>

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)