multimodel-dev-os 2.0.1 → 2.8.0

package/docs/index.md

@@ -3,38 +3,44 @@ layout: home
 
 hero:
   name: "MultiModel Dev OS"
-  text: "Standardize your AI pair-programmers"
-  tagline: "One portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows."
+  text: "One config. Every AI tool. Zero lock-in."
+  tagline: "Stop copy-pasting rules between Cursor, Claude, Gemini, Codex, and VS Code. Standardize your AI pair-programmers with a single portable workspace."
   image:
     src: /logo.png
     alt: MultiModel Dev OS Logo
   actions:
     - theme: brand
-      text: Get Started Quick
+      text: Get Started in 30 Seconds
       link: /quickstart
     - theme: alt
-      text: Stable Protocol Specs
-      link: /stable-protocol
+      text: See It in Action
+      link: /demos/
     - theme: alt
-      text: v2 Release Checklist
-      link: /v2-release-checklist
-    - theme: alt
-      text: View Case Studies
-      link: /case-studies/
+      text: vs Alternatives
+      link: /comparison
     - theme: alt
       text: View on GitHub
       link: https://github.com/rizvee/multimodel-dev-os
 
 features:
+  - icon: 📁
+    title: Instant Repo Onboarding
+    details: Analyze existing projects, get template recommendations, and bootstrap AI Dev OS configs without breaking anything.
+  - icon: 🔄
+    title: Universal Adapter Sync
+    details: Write rules once in AGENTS.md — auto-syncs to .cursorrules, CLAUDE.md, .vscode/, .gemini/, and 10+ more tools.
   - icon: 🧠
-    title: Universal Portability
-    details: Supports Codex, Antigravity, Cursor, Claude Code, Gemini, and VS Code with dynamic adapters sync.
+    title: Self-Improving Intelligence
+    details: Hash-compressed memory, developer feedback loops, and structured improvement proposals with human-in-the-loop safety gates.
   - icon: ⚡
-    title: Ultra-Low Token Footprint
-    details: Includes Caveman Mode to slash model context footprint by ~79%, saving massive API bill budgets.
+    title: Caveman Mode (−79% Tokens)
+    details: Slash model context footprint by ~79% with compressed shorthand declarations. Save massively on API bills.
   - icon: 🛡️
-    title: Local Quality Gates
-    details: Built-in zero-dependency validate and doctor checkups ensure pristine workspace rules layout.
+    title: 214+ Quality Gates
+    details: Built-in validate, doctor, and verify commands enforce workspace health with strict structural assertions.
+  - icon: 🔧
+    title: Zero Dependencies
+    details: Pure Node.js CLI — no runtime, no build step, no package manager lock-in. Works on Windows, macOS, and Linux.
 ---
 
 <style>
@@ -42,17 +48,27 @@ features:
   --vp-home-hero-name-color: transparent;
   --vp-home-hero-name-background: linear-gradient(135deg, #6366f1 0%, #10b981 100%);
 }
+.section-title {
+  font-size: 1.6rem;
+  font-weight: 800;
+  margin-bottom: 0.5rem;
+}
+.section-sub {
+  color: var(--vp-c-text-2);
+  font-size: 1rem;
+  margin-bottom: 1.5rem;
+}
 .grid-container {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-  gap: 1.5rem;
-  margin-top: 2rem;
+  gap: 1.25rem;
+  margin-top: 1.5rem;
   margin-bottom: 2rem;
 }
 .card-item {
   border: 1px solid var(--vp-c-bg-mute);
   background-color: var(--vp-c-bg-soft);
-  border-radius: 8px;
+  border-radius: 10px;
   padding: 1.5rem;
   transition: border-color 0.25s, transform 0.25s;
   text-decoration: none !important;
@@ -60,48 +76,91 @@ features:
 }
 .card-item:hover {
   border-color: var(--vp-c-brand-1);
-  transform: translateY(-4px);
+  transform: translateY(-3px);
 }
 .card-title {
-  font-weight: 600;
-  font-size: 1.15rem;
-  margin-bottom: 0.5rem;
+  font-weight: 700;
+  font-size: 1.1rem;
+  margin-bottom: 0.4rem;
 }
 .card-desc {
   font-size: 0.9rem;
   color: var(--vp-c-text-2);
 }
+.card-time {
+  font-size: 0.8rem;
+  color: var(--vp-c-brand-1);
+  font-weight: 600;
+  margin-top: 0.4rem;
+}
 .works-with-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
-  gap: 1rem;
-  margin-top: 1.5rem;
-  margin-bottom: 2.5rem;
+  grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
+  gap: 0.75rem;
+  margin-top: 1rem;
+  margin-bottom: 2rem;
 }
 .works-with-item {
   border: 1px solid var(--vp-c-bg-mute);
   background-color: var(--vp-c-bg-soft);
   border-radius: 6px;
-  padding: 1rem;
+  padding: 0.75rem;
   text-align: center;
   font-weight: 500;
-  font-size: 0.95rem;
+  font-size: 0.9rem;
+}
+.highlight-box {
+  background: linear-gradient(135deg, rgba(99, 102, 241, 0.08), rgba(16, 185, 129, 0.08));
+  border: 1px solid rgba(99, 102, 241, 0.2);
+  border-radius: 12px;
+  padding: 1.5rem 2rem;
+  margin: 2rem 0;
+}
+.highlight-box h3 { margin-top: 0; }
+.safety-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 1rem;
+  margin: 1.5rem 0;
 }
+.safety-item {
+  text-align: center;
+  padding: 1rem;
+}
+.safety-icon { font-size: 2rem; margin-bottom: 0.3rem; }
+.safety-label { font-weight: 700; font-size: 1.1rem; }
+.safety-desc { font-size: 0.85rem; color: var(--vp-c-text-2); }
 </style>
 
-## Quick Start Setup
-
-Scaffold a tool-neutral workspace instantly:
+## Install in 30 Seconds
 
 ```bash
 npx multimodel-dev-os@latest init
 ```
 
+Already have a project? Onboard it safely:
+
+```bash
+npx multimodel-dev-os@latest onboard analyze
+npx multimodel-dev-os@latest onboard recommend
+npx multimodel-dev-os@latest onboard apply --approved
+```
+
 ---
 
-## Works With
+## Why Not Just `.cursorrules` or `CLAUDE.md`?
+
+You use **Cursor** for autocomplete, **Claude Code** for terminal ops, **Gemini** for audits. Every tool switch:
+
+1. **Drops context** — the next tool doesn't know what the previous one decided
+2. **Drifts rules** — you update `.cursorrules` but forget `CLAUDE.md`, causing confusing failures
+3. **Wastes tokens** — every prompt resends your full ruleset, and API bills spike
 
-MultiModel Dev OS maps repository context directly to all major developer tools and coding agents:
+**MultiModel Dev OS** gives you a **single source of truth** (`AGENTS.md`) that auto-syncs to every tool. Change once, every tool updates.
+
+---
+
+## Works With
 
 <div class="works-with-grid">
   <div class="works-with-item">🤖 Codex</div>
@@ -110,81 +169,133 @@ MultiModel Dev OS maps repository context directly to all major developer tools
   <div class="works-with-item">⚡ Claude Code</div>
   <div class="works-with-item">🧠 Gemini</div>
   <div class="works-with-item">💻 VS Code</div>
+  <div class="works-with-item">🔌 Cline / Roo</div>
+  <div class="works-with-item">🔌 Aider</div>
 </div>
 
 ---
 
-## Core Specifications & Playbooks
+## See It in Action
 
 <div class="grid-container">
-  <a href="/quickstart" class="card-item">
-    <div class="card-title">🚀 Quickstart Guide</div>
-    <div class="card-desc">Deploy adapters and root contracts in under 2 minutes.</div>
+  <a href="/demos/existing-repo-onboarding" class="card-item">
+    <div class="card-title">📁 Repo Onboarding</div>
+    <div class="card-desc">Analyze your project, get recommendations, and bootstrap configs safely.</div>
+    <div class="card-time">~2 min</div>
   </a>
-  <a href="/templates/" class="card-item">
-    <div class="card-title">📦 Template Gallery</div>
-    <div class="card-desc">5 premium, production-ready stack configurations for developers.</div>
-  </a>
-  <a href="/stable-protocol" class="card-item">
-    <div class="card-title">🛡️ Stable Protocol</div>
-    <div class="card-desc">Explore the officially frozen Layer 1-3 directory and file contracts.</div>
+  <a href="/demos/adapter-sync" class="card-item">
+    <div class="card-title">🔄 Adapter Sync</div>
+    <div class="card-desc">Mirror rules across Cursor, Claude, VS Code, and Gemini automatically.</div>
+    <div class="card-time">~1 min</div>
   </a>
-  <a href="/cost-optimization" class="card-item">
-    <div class="card-title">⚡ Cost Optimization</div>
-    <div class="card-desc">Cuts your prompting token bills by up to 79% using Caveman shortcuts.</div>
+  <a href="/demos/safe-improvement-loop" class="card-item">
+    <div class="card-title">🧠 Improvement Loop</div>
+    <div class="card-desc">Feedback → proposals → validate → apply with audit trails.</div>
+    <div class="card-time">~2 min</div>
   </a>
-  <a href="/case-studies/" class="card-item">
-    <div class="card-title">💼 Case Studies Gallery</div>
-    <div class="card-desc">5 real-world integration guides mapping SaaS schemas and sequential handoffs.</div>
+  <a href="/demos/multi-agent-handoff" class="card-item">
+    <div class="card-title">🤝 Agent Handoff</div>
+    <div class="card-desc">Compile session context and hand off between models.</div>
+    <div class="card-time">~1 min</div>
   </a>
-  <a href="/migration-guide" class="card-item">
-    <div class="card-title">📈 Migration Playbook</div>
-    <div class="card-desc">Upgrade older workspaces to v1.1.0 standards cleanly.</div>
+  <a href="/demos/release-check" class="card-item">
+    <div class="card-title">🚀 Release Check</div>
+    <div class="card-desc">Run 214+ verification assertions and package hygiene checks.</div>
+    <div class="card-time">~1 min</div>
   </a>
-  <a href="/v2-release-checklist" class="card-item">
-    <div class="card-title">🏁 v2 Release Checklist</div>
-    <div class="card-desc">Audit repository compliance with the strict v2 release quality gates.</div>
-  </a>
-  <a href="/llms.txt" class="card-item" target="_blank">
-    <div class="card-title">🤖 AI Discovery (llms.txt)</div>
-    <div class="card-desc">A highly concise, structured overview formatted specifically for AI context ingestion.</div>
+  <a href="/comparison" class="card-item">
+    <div class="card-title">⚔️ vs Alternatives</div>
+    <div class="card-desc">See how MMDO compares to manual rules, prompt packs, and tool-specific configs.</div>
+    <div class="card-time"></div>
   </a>
 </div>
 
 ---
 
-## For AI Assistants and Coding Agents
+<div class="highlight-box">
 
-To support modern AI search, GEO discovery, and developer agents:
-- We provide [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) at the root of the hosted documentation to allow Large Language Models and AEO utilities to read full workspace specs in single, token-optimized files.
-- The officially frozen protocol guarantees that agents can read and write workspace rules without manual supervision or instruction drift.
+### 🆕 What's New in v2.7
 
----
+- 🎬 **Demo Workflow Pages** — 5 copy-paste guided workflows for onboarding, adapter sync, improvement loops, handoffs, and release checks
+- 📖 **Distribution Guide** — comprehensive release, verification, and package hygiene documentation
+- 🖼️ **Visual Flow Diagrams** — SVG assets for onboarding and adapter sync flows
+- 📁 **Docs-First Examples** — 4 new example workflows with commands and expected output
 
-## Cost & Context Optimization
+</div>
 
-Minimize prompt overhead and API billing by mapping key context-reduction techniques to MultiModel Dev OS features:
+---
 
-<p align="center">
-  <img src="/assets/cost-optimization.svg" alt="Cost Optimization Funnel" width="100%">
-</p>
+## Safety & Trust
+
+<div class="safety-grid">
+  <div class="safety-item">
+    <div class="safety-icon">🛡️</div>
+    <div class="safety-label">214+ Quality Gates</div>
+    <div class="safety-desc">Strict structural verification on every release</div>
+  </div>
+  <div class="safety-item">
+    <div class="safety-icon">👤</div>
+    <div class="safety-label">Human-in-the-Loop</div>
+    <div class="safety-desc">All writes require explicit --approved flag</div>
+  </div>
+  <div class="safety-item">
+    <div class="safety-icon">🔒</div>
+    <div class="safety-label">12 Safety Gates</div>
+    <div class="safety-desc">Proposal validation with path boundary checks</div>
+  </div>
+  <div class="safety-item">
+    <div class="safety-icon">📝</div>
+    <div class="safety-label">Full Audit Trail</div>
+    <div class="safety-desc">SHA-256 hashed apply log for every change</div>
+  </div>
+</div>
 
 ---
 
-## 5-Day Adoption Roadmap
+## Explore
+
+<div class="grid-container">
+  <a href="/quickstart" class="card-item">
+    <div class="card-title">🚀 Quickstart Guide</div>
+    <div class="card-desc">Deploy adapters and root contracts in under 30 seconds.</div>
+  </a>
+  <a href="/CLI" class="card-item">
+    <div class="card-title">⌨️ CLI Reference</div>
+    <div class="card-desc">Full command reference for init, scan, status, memory, workflow, and more.</div>
+  </a>
+  <a href="/templates/" class="card-item">
+    <div class="card-title">📦 Template Gallery</div>
+    <div class="card-desc">6 production-ready stack configurations for Next.js, WordPress, e-commerce, and more.</div>
+  </a>
+  <a href="/architecture" class="card-item">
+    <div class="card-title">🏗️ Architecture</div>
+    <div class="card-desc">4-layer protocol from root contracts through intelligence engine.</div>
+  </a>
+  <a href="/cost-optimization" class="card-item">
+    <div class="card-title">⚡ Cost Optimization</div>
+    <div class="card-desc">Cut your prompting token bills by up to 79% using Caveman shortcuts.</div>
+  </a>
+  <a href="/distribution" class="card-item">
+    <div class="card-title">📦 Distribution Guide</div>
+    <div class="card-desc">Release checklists, npm publishing, and package hygiene.</div>
+  </a>
+</div>
+
+---
 
-Deploying MultiModel Dev OS across your team is straightforward and tool-neutral:
+## For AI Assistants and Coding Agents
 
-<p align="center">
-  <img src="/assets/ai-dev-os-roadmap.svg" alt="5-Day Adoption Roadmap" width="100%">
-</p>
+To support modern AI search, GEO discovery, and developer agents:
+- We provide [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) at the root of the hosted documentation to allow Large Language Models and AEO utilities to read full workspace specs in single, token-optimized files.
+- The officially frozen protocol guarantees that agents can read and write workspace rules without manual supervision or instruction drift.
 
 ---
 
-## Why MultiModel Dev OS?
+## Contributing & Community
 
-AI coding tools are incredibly fast, but switching between them introduces context fragmentation:
-1. **Context Loss:** You use **Cursor** for quick code completions, **Claude Code** for command-line implementations, and **Gemini/Antigravity** for auditing large code volumes. Every context switch drops your operational parameters.
-2. **Instruction Drift:** Different tools look for different files (`.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, `.gemini/settings.json`). If you modify build scripts or styling rules in one place, they quickly drift across others, causing confusing compile failures.
+⭐ **[Star us on GitHub](https://github.com/rizvee/multimodel-dev-os)** — it helps developers discover this project
 
-`multimodel-dev-os` establishes a single source of truth inside your repository using a standardized root structure (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) and a `.ai/` context configuration directory.
+- 📖 **[Contributing Guidelines](https://github.com/rizvee/multimodel-dev-os/blob/main/CONTRIBUTING.md)**
+- 🐛 **[Report a Bug](https://github.com/rizvee/multimodel-dev-os/issues/new)**
+- 💡 **[Request a Feature](https://github.com/rizvee/multimodel-dev-os/issues/new)**
+- 📦 **[NPM Package](https://www.npmjs.com/package/multimodel-dev-os)**

package/docs/installers.md

@@ -1,10 +1,24 @@
-# Installers
+# Installers & NPX Setup
 
-## Overview
+## NPX (Recommended Primary Method)
 
-While `npx multimodel-dev-os@latest init` is the primary and recommended route to bootstrap your project, we provide cross-platform automated shell script installers as robust, dependency-free fallbacks for environments without Node.js. These are located in `scripts/`.
+For environments with Node.js 18+ installed, use our zero-install scaffolding runner. This is the fastest, most reliable, and standard way to initialize and manage workspaces:
 
-## Usage
+```bash
+# Initialize a new workspace in the current directory
+npx multimodel-dev-os@latest init
+
+# Or onboard an existing repository safely
+npx multimodel-dev-os@latest onboard analyze
+```
+
+For more details, see the **[Quickstart Guide](/quickstart)**.
+
+---
+
+## Offline & Dependency-Free Installers
+
+While `npx` is the primary route, we provide cross-platform automated shell script installers as robust, dependency-free fallbacks for environments without Node.js. These are located in `scripts/`.
 
 ### macOS / Linux / WSL (`install.sh`)
 

package/docs/launch-kit.md

@@ -1,81 +1,129 @@
 # Public Launch & Social Sharing Kit
 
-A curated collection of ready-to-use sharing outlines focused on LLM cost savings, multi-agent context synchronization, and configuration reuse inside development teams.
+Ready-to-use promotional copy for sharing MultiModel Dev OS on social platforms, forums, and communities.
 
 ---
 
-## 1. Product Hunt Launch (Milestone v0.8.0)
-- **Product Tagline:** Portable workspace configuration layer and playbooks to sync AI coding agents.
-- **Pitch Focus:** Slash LLM API billing and context overhead by up to **~79%** with our native Caveman Mode. Enforce strict coding styles and boundaries across Cursor, Claude, Antigravity, and VS Code automatically using a singular root contract.
+## 1. Product Hunt / Show HN Pitch
+
+**Tagline:** One workspace config for every AI coding tool — zero lock-in, zero dependencies.
+
+**Pitch:**
+> If you use 2+ AI coding tools (Cursor, Claude Code, Gemini, Codex, VS Code Copilot), you know the pain: rules drift between tools, every switch drops context, and tokens waste on duplicate instructions.
+>
+> MultiModel Dev OS solves this with a single `AGENTS.md` that auto-syncs to every tool. One command sets it up: `npx multimodel-dev-os@latest init`
+>
+> v2.7 includes guided demo workflows, safe repo onboarding for existing projects, adapter sync across 10+ tools, a self-improvement engine with 12 safety gates, and 214+ quality assertions.
+>
+> Free, MIT licensed, zero dependencies. Works on Windows, macOS, and Linux.
+>
+> 👉 https://github.com/rizvee/multimodel-dev-os
 
 ---
 
-## 2. X / Twitter Campaign (The Focus: Token Cost Savings)
+## 2. X / Twitter Campaign
 
 ```text
-AI coding is fast, but prompt token bills scale faster. 💸
+I use Cursor for autocomplete, Claude for terminal ops, and Gemini for audits.
 
-Duplicating instructions in .cursorrules, CLAUDE.md, and system prompts drains your API token budget on every message turn.
+The problem? Every tool switch drops context. Rules drift. Tokens waste.
 
-Say hello to MultiModel Dev OS v0.8.0! 🧠
+MultiModel Dev OS fixes this:
 
 npx multimodel-dev-os@latest init
 
-👉 Decoupled adapters sync Cursor, Claude, VS Code, and Gemini instantly
-👉 Slash rule overhead by up to ~79% with Caveman Mode
-👉 12 Cost Optimization plays mapped to Dev OS features
-👉 5-Day tool-neutral Adoption Roadmap for teams
+→ One config syncs to .cursorrules, CLAUDE.md, .vscode/, .gemini/
+→ Onboard existing repos safely
+→ Self-improvement engine with safety gates
+→ Slash token overhead by ~79%
 
-Stop wasting context. Sync and reuse your workspace memory! 🚀
+Free, MIT, zero dependencies.
 👉 https://github.com/rizvee/multimodel-dev-os
-#AIDev #OpenSource #SoftwareEngineering #AItools
 ```
 
 ---
 
-## 3. LinkedIn Campaign (The Focus: Enterprise Adoption)
+## 3. LinkedIn Campaign
 
 ```text
-The hidden tax of scaling AI inside development teams: Context Fragmentation. 💸
+The hidden cost of using multiple AI coding tools: Context Fragmentation.
 
-When switching between tools:
-- Claude Code scaffolds terminal builds
-- Cursor suggests local autocompletions
-- Gemini/Antigravity performs codebase audits
+When your team switches between Cursor, Claude Code, and Gemini:
+• Rules in .cursorrules go stale when you update CLAUDE.md
+• Every model switch loses your operational context
+• Token bills spike from duplicate instructions
 
-If each developer maintains distinct, custom configurations, your rules drift immediately. Models break, and you waste thousands of tokens repeating basic instructions.
+MultiModel Dev OS creates a single source of truth that auto-syncs to every tool:
 
-To solve this, we are releasing MultiModel Dev OS v0.8.0:
-1. One central brain (AGENTS.md and .ai/) routes instructions dynamically.
-2. Slashes API prompt overhead by ~79% via Caveman Mode.
-3. Maps 12 context optimization techniques ( RAG scoping, prompt caching, batching).
-4. Includes a 5-Day tool-neutral Adoption Roadmap to align your team in a business week.
+1. npx multimodel-dev-os@latest init
+2. Edit AGENTS.md with your project rules
+3. Run adapter sync to push to all your tools
 
-Fully open-source, MIT licensed, and zero-dependency.
+v2.7 includes 5 guided demo workflows, safe repo onboarding, a self-improvement engine with 12 safety gates, and 214+ quality assertions.
 
-Read the Case Studies Gallery & Playbook:
-👉 https://github.com/rizvee/multimodel-dev-os
-Let me know how your team manages prompt consistency in the comments! 👇
+Zero dependencies. MIT licensed. Works everywhere.
+
+Demo workflows: https://rizvee.github.io/multimodel-dev-os/demos/
+GitHub: https://github.com/rizvee/multimodel-dev-os
 ```
 
 ---
 
-## 4. Reddit-Style Pitch (/r/LocalLLaMA, /r/webdev)
-
-- **Title:** Show HN / Show Reddit: MultiModel Dev OS v0.8.0 — Prevent AI instruction drift and save ~79% token budget.
-- **Content:**
-  Hey everyone,
-  
-  If your team pair programs with multiple LLM agents, you know how fast rules drift. You edit a command in your terminal prompts, but Cursor's autocompletes are still reading outdated caching guidelines, causing compile crashes.
-  
-  I built **multimodel-dev-os** to solve this. It's a lightweight, zero-dependency Node.js CLI that scaffolds a single repository brain and uses automated adapters to route a single source of truth to all your tools.
-  
-  ### v0.8.0 Feature Highlights:
-  * **Cost Optimization Playbook:** Maps 12 techniques (prompt caching, RAG scoping, batching) directly to Dev OS directory modules.
-  * **Caveman Mode:** Strips out descriptions and examples to save **~79% of tokens** per prompt turn.
-  * **5-Day Adoption Timeline:** A tool-neutral business week adoption playbook.
-  * **Real-World Case Studies:** 5 generic but realistic guides covering full-stack SaaS schema synchronization, WordPress directory boundaries, and Claude/Gemini hand-off session logs.
-  
-  Open-source and MIT licensed. I'd love to hear your feedback on the layout structure!
-  
-  GitHub: https://github.com/rizvee/multimodel-dev-os
+## 4. Reddit / Hacker News
+
+**Title:** MultiModel Dev OS v2.7 — One config for Cursor, Claude, Gemini, Codex, and VS Code
+
+**Content:**
+```text
+Hey everyone,
+
+If you use more than one AI coding tool, you've probably hit these problems:
+- Update .cursorrules → forget to update CLAUDE.md → Claude generates wrong code
+- Switch from Claude to Gemini → lose all session context
+- Every prompt resends your full ruleset → token bills spike
+
+I built multimodel-dev-os to fix this. It's a lightweight CLI that creates a single
+AGENTS.md and auto-syncs it to every tool via adapters.
+
+v2.7 adds:
+• 5 copy-paste demo workflows (onboarding, adapter sync, improvement loops, handoffs, release checks)
+• Safe repo onboarding — analyze, recommend, plan, apply with auto-backups
+• Distribution guide with release checklists and package hygiene
+• Visual SVG flow diagrams
+
+It's zero-dependency, MIT licensed, and works on Windows/macOS/Linux.
+
+Try it: npx multimodel-dev-os@latest init
+Demos: https://rizvee.github.io/multimodel-dev-os/demos/
+GitHub: https://github.com/rizvee/multimodel-dev-os
+
+Happy to answer questions about the architecture or safety model.
+```
+
+---
+
+## 5. Key Talking Points
+
+Use these when writing about MultiModel Dev OS:
+
+| Point | Detail |
+|-------|--------|
+| **Problem** | Switching between AI coding tools causes rule drift, context loss, and token waste |
+| **Solution** | Single `AGENTS.md` → auto-syncs to `.cursorrules`, `CLAUDE.md`, `.vscode/`, `.gemini/`, and more |
+| **Onboarding** | Safely onboard existing repos: `onboard analyze → recommend → plan → apply` |
+| **Safety** | 12 proposal safety gates, `--approved` flags, auto-backups, SHA-256 audit trails |
+| **Token Savings** | Caveman Mode cuts ~79% token overhead |
+| **Quality** | 214+ verification assertions, `doctor --release` alignment checks |
+| **Trust** | Zero dependencies, MIT license, no runtime, no network calls |
+| **Tools** | Codex, Antigravity, Cursor, Claude Code, Gemini, VS Code, Cline, Aider, Windsurf |
+
+---
+
+## 6. Links
+
+- **GitHub**: https://github.com/rizvee/multimodel-dev-os
+- **NPM**: https://www.npmjs.com/package/multimodel-dev-os
+- **Docs**: https://rizvee.github.io/multimodel-dev-os/
+- **Demos**: https://rizvee.github.io/multimodel-dev-os/demos/
+- **Quickstart**: https://rizvee.github.io/multimodel-dev-os/quickstart
+- **Comparison**: https://rizvee.github.io/multimodel-dev-os/comparison

package/docs/learning-rules.md

@@ -0,0 +1,36 @@
+# Learning Rules and Feedback Loop
+
+MultiModel Dev OS captures developer corrections and instruction overrides to compile reusable system rules that refine subsequent agent proposal generations.
+
+---
+
+## 1. Feedback Loop Commands
+
+### 1. Log Feedback
+To log a design preference or instruction override, run:
+```bash
+npx multimodel-dev-os feedback add "Prefer vanilla CSS or CSS Modules in legacy components" --type preference --tags styling --files "src/components/legacy/*"
+```
+This logs a structured JSON entry to `.ai/intelligence/feedback-log.jsonl`.
+
+### 2. List Logged Feedback
+To view all feedback entries in a formatted list:
+```bash
+npx multimodel-dev-os feedback list
+```
+
+### 3. Summarize Feedback
+To compile the raw feedback log into instructions that agents read:
+```bash
+npx multimodel-dev-os feedback summarize
+```
+This aggregates the logs by type and writes `.ai/intelligence/learning-rules.md`.
+
+---
+
+## 2. Context Ingestion by Agents
+
+Prior to generating proposals or refactoring components:
+1. Model agents read `.ai/intelligence/learning-rules.md` as context.
+2. The rules act as prompt constraints matching specific file target patterns.
+3. This prevents agents from repeating previously corrected mistakes.