multimodel-dev-os 2.0.1 → 2.6.0

package/.ai/registries/workflows.yaml

@@ -0,0 +1,217 @@
+# MultiModel Dev OS - Workflow Registry
+# Defines logical steps, cognitive thresholds, and checklist validation gates for coding cycles
+
+workflows:
+  repo-health:
+    name: "Repository Health Check"
+    description: "Evaluates project hygiene, directory schema, and structural integrity."
+    risk_level: "low"
+    allowed_to_write_memory: false
+    allowed_to_modify_source: false
+    steps:
+      - name: "framework-scanning"
+        command: "scan"
+        expected_output: "Framework detection signals"
+        next_action: "doctor"
+      - name: "advisory-checkup"
+        command: "doctor"
+        expected_output: "Project compatibility alerts"
+        next_action: "verify"
+      - name: "schema-verification"
+        command: "verify"
+        expected_output: "Structural file verification"
+        next_action: "done"
+    commands:
+      - "scan"
+      - "doctor"
+      - "verify"
+    expected_outputs:
+      - "Framework detection signals"
+      - "Project compatibility alerts"
+      - "Structural file verification"
+    next_action: "Resolve warnings shown in doctor checkup"
+
+  memory-refresh:
+    name: "Memory Refresh Cycle"
+    description: "Inspects workspace changes and increments memory."
+    risk_level: "medium"
+    allowed_to_write_memory: true
+    allowed_to_modify_source: false
+    steps:
+      - name: "diff-assessment"
+        command: "memory diff"
+        expected_output: "Memory delta"
+        next_action: "memory refresh"
+      - name: "index-refresh"
+        command: "memory refresh"
+        expected_output: "Updated memory files"
+        next_action: "done"
+    commands:
+      - "memory diff"
+      - "memory refresh"
+    expected_outputs:
+      - "Memory delta"
+      - "Updated memory files"
+    next_action: "Commit updated intelligence files"
+
+  feedback-review:
+    name: "Feedback Review Loop"
+    description: "Inspects developer loop feedback and compiles learning rules."
+    risk_level: "low"
+    allowed_to_write_memory: false
+    allowed_to_modify_source: false
+    steps:
+      - name: "feedback-listing"
+        command: "feedback list"
+        expected_output: "Logged feedback items"
+        next_action: "feedback summarize"
+      - name: "rules-summarization"
+        command: "feedback summarize"
+        expected_output: "Compiled learning-rules.md"
+        next_action: "done"
+    commands:
+      - "feedback list"
+      - "feedback summarize"
+    expected_outputs:
+      - "Logged feedback items"
+      - "Compiled learning rules file"
+    next_action: "Review rules and share with the team"
+
+  proposal-review:
+    name: "Improvement Proposal Review"
+    description: "Inspects codebase optimization proposals and execution histories."
+    risk_level: "low"
+    allowed_to_write_memory: false
+    allowed_to_modify_source: false
+    steps:
+      - name: "proposals-list"
+        command: "improve review"
+        expected_output: "Proposals list"
+        next_action: "improve status"
+      - name: "proposals-status"
+        command: "improve status"
+        expected_output: "Pending, approved counts"
+        next_action: "improve log"
+      - name: "apply-history"
+        command: "improve log"
+        expected_output: "Audit apply history"
+        next_action: "done"
+    commands:
+      - "improve review"
+      - "improve status"
+      - "improve log"
+    expected_outputs:
+      - "Proposals list"
+      - "Pending, approved counts"
+      - "Audit apply history"
+    next_action: "Apply approved proposals manually"
+
+  release-check:
+    name: "Pre-Release Verification"
+    description: "Verifies package readiness and install script alignment prior to publish."
+    risk_level: "low"
+    allowed_to_write_memory: false
+    allowed_to_modify_source: false
+    steps:
+      - name: "code-hygiene"
+        command: "verify"
+        expected_output: "Release verification passed"
+        next_action: "doctor --release"
+      - name: "doctor-checks"
+        command: "doctor --release"
+        expected_output: "Release audit doctor complete"
+        next_action: "npm pack --dry-run"
+      - name: "tarball-check"
+        command: "npm pack --dry-run"
+        expected_output: "Dry-run tarball details"
+        next_action: "done"
+    commands:
+      - "verify"
+      - "doctor --release"
+      - "npm pack --dry-run"
+    expected_outputs:
+      - "Release verification passed"
+      - "Release audit doctor complete"
+      - "Dry-run tarball details"
+    next_action: "Proceed to manual package publish"
+
+  feature-implementation:
+    name: "Feature Implementation"
+    description: "Standard workflow to design, write, and verify new codebase features."
+    risk_level: "high"
+    allowed_to_write_memory: true
+    allowed_to_modify_source: true
+    steps:
+      - name: planning
+        command: "propose"
+        expected_output: "Design plan proposal"
+        next_action: "coding"
+      - name: coding
+        command: "implement"
+        expected_output: "Code modifications"
+        next_action: "verification"
+      - name: verification
+        command: "verify"
+        expected_output: "Checks passing"
+        next_action: "done"
+    commands:
+      - "propose"
+      - "implement"
+      - "verify"
+    expected_outputs:
+      - "Design plan proposal"
+      - "Code modifications"
+      - "Checks passing"
+    next_action: "Submit for approval"
+
+  bug-fixing:
+    name: "Bug Fixing"
+    description: "Workflow to reproduce, resolve, and run regression tests on defects."
+    risk_level: "medium"
+    allowed_to_write_memory: true
+    allowed_to_modify_source: true
+    steps:
+      - name: reproduction
+        command: "verify"
+        expected_output: "Reproduction cases"
+        next_action: "resolution"
+      - name: resolution
+        command: "implement"
+        expected_output: "Fix applied"
+        next_action: "regression-testing"
+      - name: regression-testing
+        command: "verify"
+        expected_output: "Regression tests passing"
+        next_action: "done"
+    commands:
+      - "verify"
+      - "implement"
+      - "verify"
+    expected_outputs:
+      - "Reproduction cases"
+      - "Fix applied"
+      - "Regression tests passing"
+    next_action: "Verify fixed state is fully clean"
+
+  security-audit:
+    name: "Security Audit"
+    description: "Workflow to audit files against security guidelines and vulnerability checks."
+    risk_level: "high"
+    allowed_to_write_memory: false
+    allowed_to_modify_source: false
+    steps:
+      - name: scanning
+        command: "scan"
+        expected_output: "Security scanning results"
+        next_action: "reporting"
+      - name: reporting
+        command: "doctor"
+        expected_output: "Vulnerabilities summary report"
+        next_action: "done"
+    commands:
+      - "scan"
+      - "doctor"
+    expected_outputs:
+      - "Security scanning results"
+      - "Vulnerabilities summary report"
+    next_action: "Mitigate warnings reported by scanner"

package/README.md

@@ -5,12 +5,13 @@
 </p>
 
 <p align="center">
-  <b>One portable AI Dev OS for multimodel coding workflows.</b>
+  <b>The portable AI Dev OS for every model, every tool, every workflow.</b><br>
+  <sub>One workspace. Zero lock-in. Ship faster with Codex, Gemini, Claude, Cursor, Antigravity, VS Code, and more.</sub>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/multimodel-dev-os"><img src="https://img.shields.io/npm/v/multimodel-dev-os.svg?color=blue&style=flat-square" alt="NPM Version"></a>
-  <a href="https://www.npmjs.com/package/multimodel-dev-os"><img src="https://img.shields.io/badge/npm-package-cb3837.svg?style=flat-square" alt="NPM Package"></a>
+  <a href="https://www.npmjs.com/package/multimodel-dev-os"><img src="https://img.shields.io/npm/dm/multimodel-dev-os.svg?color=orange&style=flat-square" alt="NPM Downloads"></a>
   <a href="https://github.com/rizvee/multimodel-dev-os/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/multimodel-dev-os.svg?color=green&style=flat-square" alt="License"></a>
   <a href="https://github.com/rizvee/multimodel-dev-os/releases"><img src="https://img.shields.io/github/v/release/rizvee/multimodel-dev-os?color=indigo&style=flat-square" alt="GitHub Release"></a>
   <a href="https://github.com/rizvee/multimodel-dev-os/actions"><img src="https://img.shields.io/github/actions/workflow/status/rizvee/multimodel-dev-os/verify.yml?branch=main&style=flat-square&label=verification" alt="Build Verification"></a>
@@ -19,15 +20,13 @@
 
 ---
 
-## One portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows.
-
-Initialize a stable workspace instantly:
+## Get started in 30 seconds
 
 ```bash
 npx multimodel-dev-os@latest init
 ```
 
----
+That's it. Your workspace now has a unified AI context layer that works across **every major AI coding tool** — no config duplication, no context loss, no vendor lock-in.
 
 <p align="center">
   <img src="assets/social-preview.svg" alt="MultiModel Dev OS Banner" width="100%">
@@ -35,35 +34,37 @@ npx multimodel-dev-os@latest init
 
 ---
 
-## Why This Exists
+## The Problem
 
-AI pair programmers are lightning-fast, but switching between them introduces context fragmentation:
-1. **Context Loss:** You use **Cursor** for autocomplete, **Claude Code** for command execution, and **Gemini/Antigravity** for deep audits. Every switch forces you to rebuild context.
-2. **Instruction Drift:** Different tools look for different config files (`.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, `.gemini/settings.json`). Modifying style rules or build parameters in one place leaves the others outdated.
+AI pair programmers are powerful individually, but switching between them creates real friction:
 
-`multimodel-dev-os` solves this by establishing a single source of truth in your repository: four root contracts (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) and a `.ai/` directory that bridges them to all major tools dynamically.
-
----
+| Pain Point | What Happens |
+|:---|:---|
+| **Context Fragmentation** | You use Cursor for autocomplete, Claude Code for terminal ops, Gemini for deep audits. Every switch forces a full context rebuild. |
+| **Instruction Drift** | `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, `.gemini/settings.json` — change one, the rest go stale. |
+| **Token Waste** | Without context budgets, prompts bloat and API bills spike. |
+| **Onboarding Friction** | New team members start from scratch with every tool. |
 
-## What You Get
+## The Solution
 
-A standard installation scaffolds a lightweight, zero-runtime-dependency workspace hierarchy:
+**MultiModel Dev OS** creates a single source of truth — four root contracts and a `.ai/` directory that bridges every tool dynamically:
 
 ```
-┌────────────────────────────────────────────────────────┐
-│ LAYER 1: Root Contracts (Single Source of Truth)       │
-│ AGENTS.md • MEMORY.md • TASKS.md • RUNBOOK.md          │
-└──────────────────────────┬─────────────────────────────┘
-                           │ Centralizes project context
-┌──────────────────────────▼─────────────────────────────┐
-│ LAYER 2: Configuration & Modules (.ai/)                │
-│ context/ • agents/ • skills/ • prompts/ • checks/      │
-└──────────────────────────┬─────────────────────────────┘
-                           │ Routes files dynamically
-┌──────────────────────────▼─────────────────────────────┐
-│ LAYER 3: Tool & IDE Adapters                           │
-│ .cursorrules • CLAUDE.md • .vscode/ • .gemini/        │
-└────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│  LAYER 1: Root Contracts (Single Source of Truth)           │
+│  AGENTS.md  •  MEMORY.md  •  TASKS.md  •  RUNBOOK.md      │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│  LAYER 2: Configuration Engine (.ai/)                       │
+│  context/  agents/  skills/  prompts/  checks/  models/    │
+│  registries/  intelligence/  policies/                      │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│  LAYER 3: Tool & IDE Adapters                               │
+│  .cursorrules  CLAUDE.md  .vscode/  .gemini/  GEMINI.md    │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 <p align="center">
@@ -72,108 +73,191 @@ A standard installation scaffolds a lightweight, zero-runtime-dependency workspa
 
 ---
 
-## Supported Tools
-
-| Tool / Agent | Target Adapter File | Setup Instructions | Behavior Setup |
-| :--- | :--- | :--- | :--- |
-| **Codex** | `adapters/codex/AGENTS.md` | `adapters/codex/setup.md` | Automated code scaffolding |
-| **Antigravity** | `.gemini/settings.json` | `adapters/antigravity/setup.md` | Security and audit parameters |
-| **Cursor** | `.cursorrules` | `adapters/cursor/setup.md` | Inline autocomplete guidelines |
-| **Claude Code** | `CLAUDE.md` | `adapters/claude/setup.md` | Terminal build and run controls |
-| **Gemini** | `GEMINI.md` | `adapters/gemini/setup.md` | Prompt system context logs |
-| **VS Code** | `.vscode/settings.json` | `adapters/vscode/setup.md` | Editor layout and search limits |
-
----
-
-## Why Not Just a Manual AGENTS.md?
+## Supported Tools & Agents
 
-While you can write a raw markdown file manually, `multimodel-dev-os` offers a standardized development workflow:
+| Tool / Agent | Adapter File | Status |
+|:---|:---|:---|
+| **Codex** (OpenAI) | `adapters/codex/AGENTS.md` | ✅ Full support |
+| **Antigravity** (Google DeepMind) | `.gemini/settings.json` | ✅ Full support |
+| **Cursor** | `.cursorrules` | ✅ Full support |
+| **Claude Code** (Anthropic) | `CLAUDE.md` | ✅ Full support |
+| **Gemini** (Google) | `GEMINI.md` | ✅ Full support |
+| **VS Code** (Copilot) | `.vscode/settings.json` | ✅ Full support |
+| **Cline / Continue / Roo Code** | Via adapter registry | 🔌 Adapter-ready |
+| **Aider / Windsurf** | Via adapter registry | 🔌 Adapter-ready |
+| **MCP Tools** (gcloud, Chrome DevTools) | Via tool registry | 🔌 Registry-ready |
 
-| Feature | Manual Rules File | MultiModel Dev OS |
-| :--- | :--- | :--- |
-| **Tool Synchronization** | Manual copy-paste across tools | Automated dynamic adapters |
-| **Context Budgets** | Bloats prompts, wasting cost | **Caveman Mode** slashes tokens by **~79%** |
-| **Standards Enforcement**| Easy to drift and corrupt | Built-in CLI `validate` and `doctor` checks |
-| **Onboarding baseline**  | Start from scratch | 5 production-ready real-world templates |
+> **Zero lock-in.** Switch tools freely — your context, rules, and memory travel with you.
 
 ---
 
-## Interactive Command Line Interface (CLI)
+## CLI Commands
 
-MultiModel Dev OS is powered by a pure Node.js CLI with **zero runtime external npm dependencies**.
+MultiModel Dev OS ships a pure Node.js CLI with **zero runtime dependencies**.
 
 <p align="center">
   <img src="assets/terminal-demo.svg" alt="Terminal Demo Sequence" width="100%">
 </p>
 
-### 1. Scaffolding Templates (Stable npm @latest)
-Initialize customized stack specifications for stable releases:
-- **Next.js SaaS:** `npx multimodel-dev-os@latest init --template nextjs-saas`
-- **WordPress Theme/Plugin:** `npx multimodel-dev-os@latest init --template wordpress-site`
-- **E-Commerce Store:** `npx multimodel-dev-os@latest init --template ecommerce-store`
-- **SEO Landing Page:** `npx multimodel-dev-os@latest init --template seo-landing-page`
-- **General Fallback:** `npx multimodel-dev-os@latest init --template general-app`
+### Initialize a Workspace
 
-### 2. Adapter Linking (Stable npm @latest)
-Inject rules specifically for a developer tool:
 ```bash
+# Default workspace
+npx multimodel-dev-os@latest init
+
+# Pick a template
+npx multimodel-dev-os@latest init --template nextjs-saas
+npx multimodel-dev-os@latest init --template wordpress-site
+npx multimodel-dev-os@latest init --template ecommerce-store
+npx multimodel-dev-os@latest init --template seo-landing-page
+npx multimodel-dev-os@latest init --template expo-react-native-android
+npx multimodel-dev-os@latest init --template general-app
+
+# Inject a specific adapter
 npx multimodel-dev-os@latest init --adapter cursor
 npx multimodel-dev-os@latest init --adapter claude
 ```
 
-### 3. Caveman Mode (Stable npm @latest)
-Cuts prompt rules overhead down by **~79%** using highly optimized short-hand declarations:
+### Codebase Scanning & Memory
+
 ```bash
-npx multimodel-dev-os@latest init --caveman
+# Scan target repository structure and framework signals
+npx multimodel-dev-os@latest scan
+
+# Show compact repository intelligence state status
+npx multimodel-dev-os@latest status
+
+# Compile hash-compressed codebase state memory
+npx multimodel-dev-os@latest memory build
+
+# Incremental update of codebase state memory
+npx multimodel-dev-os@latest memory refresh
+
+# Diff current codebase state against memory files
+npx multimodel-dev-os@latest memory diff
 ```
 
-### 4. Registry & Model Commands (v2.0.0 Stable Release)
-Run model capabilities registries, adapter registers, and scaffold mobile templates directly:
+### Feedback Learning & Proposals
+
 ```bash
-# List model or adapter registries
-npx multimodel-dev-os@latest models
-npx multimodel-dev-os@latest adapters
+# Log developer preference or instruction feedback
+npx multimodel-dev-os@latest feedback add "Avoid Tailwind CSS" --type preference
 
-# Scaffold the Android Expo template
-npx multimodel-dev-os@latest init --template expo-react-native-android
+# View logged feedback entries
+npx multimodel-dev-os@latest feedback list
+
+# Compile raw feedback logs into active rules
+npx multimodel-dev-os@latest feedback summarize
+
+# Generate structured codebase improvement proposal
+npx multimodel-dev-os@latest improve propose --title "Fix config issues"
+
+# Review active proposals and statuses
+npx multimodel-dev-os@latest improve review
+
+# View improvement engine status
+npx multimodel-dev-os@latest improve status
+
+# Validate proposal safety gates and operations
+npx multimodel-dev-os@latest improve validate .ai/proposals/proposal-xxxx.md
+
+# Preview proposed changes in unified diff format
+npx multimodel-dev-os@latest improve diff .ai/proposals/proposal-xxxx.md
+
+# Apply deterministic approved operations to codebase
+npx multimodel-dev-os@latest improve apply .ai/proposals/proposal-xxxx.md --approved
+
+# View applied proposals execution history audit log
+npx multimodel-dev-os@latest improve log
+
+# Orchestrate development workflow pipelines
+npx multimodel-dev-os@latest workflow run repo-health
+npx multimodel-dev-os@latest workflow list
+
+# Compile or print token-compressed agent session handoff summaries
+npx multimodel-dev-os@latest handoff build
+npx multimodel-dev-os@latest handoff show
+
+# Onboard existing repositories safely
+npx multimodel-dev-os@latest onboard analyze
+npx multimodel-dev-os@latest onboard recommend
+npx multimodel-dev-os@latest onboard plan
+npx multimodel-dev-os@latest onboard apply --approved
+npx multimodel-dev-os@latest onboard status
+
+# Manage and sync IDE adapter configuration files
+npx multimodel-dev-os@latest adapter status
+npx multimodel-dev-os@latest adapter diff cursor
+npx multimodel-dev-os@latest adapter sync cursor --approved
+npx multimodel-dev-os@latest adapter sync all --approved
+```
+
+### Explore Registries
+
+```bash
+npx multimodel-dev-os@latest templates     # List all templates
+npx multimodel-dev-os@latest models        # View model registry
+npx multimodel-dev-os@latest adapters      # View adapter registry
+npx multimodel-dev-os@latest models --json # Machine-readable output
+```
+
+### Quality Gates
+
+```bash
+npx multimodel-dev-os@latest validate      # Strict schema validation
+npx multimodel-dev-os@latest doctor        # Advisory compatibility checks
+npx multimodel-dev-os@latest verify        # Full release audit
+```
+
+### Caveman Mode
+
+Cut prompt token overhead by **~79%** with compressed shorthand declarations:
+
+```bash
+npx multimodel-dev-os@latest init --caveman
 ```
 
-For more details, see the [Model Capabilities Registry Guide](https://rizvee.github.io/multimodel-dev-os/model-compatibility).
+---
+
+## Why Not Just a Manual AGENTS.md?
 
-### 5. Quality Gates
-Run assertions and diagnostic checkups:
-- **`validate`** (Strict schema checkup): `npx multimodel-dev-os@latest validate`
-- **`doctor`** (Advisory compatibility warning): `npx multimodel-dev-os@latest doctor`
+| Capability | Manual Rules File | MultiModel Dev OS |
+|:---|:---|:---|
+| **Tool Sync** | Manual copy-paste across tools | Automated dynamic adapters |
+| **Context Budgets** | Bloats prompts, wastes tokens | Caveman Mode cuts **~79%** token overhead |
+| **Standards** | Easy to drift and corrupt | CLI `validate` + `doctor` + 193-assertion `verify` |
+| **Templates** | Start from scratch | 6 production-ready real-world templates |
+| **Model Registry** | Hardcoded model names | Dynamic capability-scored registry with routing presets |
+| **Safety** | No guardrails | Prepublish guards, schema validation, hygiene checks |
 
 ---
 
 ## Cost & Context Optimization
 
-Minimize prompt overhead and API billing by mapping key context-reduction techniques to MultiModel Dev OS features:
+Minimize prompt overhead and API billing with built-in context-reduction techniques:
 
 <p align="center">
   <img src="assets/cost-optimization.svg" alt="Cost Optimization Funnel" width="100%">
 </p>
 
-For a full deep dive, see our [Cost Optimization Playbook](https://rizvee.github.io/multimodel-dev-os/cost-optimization).
+Read the full playbook: **[Cost Optimization Guide](https://rizvee.github.io/multimodel-dev-os/cost-optimization)**
 
 ---
 
 ## 5-Day Adoption Roadmap
 
-Deploying MultiModel Dev OS across your team is straightforward and tool-neutral:
+Deploy MultiModel Dev OS across your team in under a week:
 
 <p align="center">
   <img src="assets/ai-dev-os-roadmap.svg" alt="5-Day Adoption Roadmap" width="100%">
 </p>
 
-See our step-by-step timeline: [5-Day Adoption Roadmap Playbook](https://rizvee.github.io/multimodel-dev-os/5-day-roadmap).
+Step-by-step timeline: **[5-Day Adoption Playbook](https://rizvee.github.io/multimodel-dev-os/5-day-roadmap)**
 
 ---
 
 ## Real-World Case Studies
 
-Discover how engineering teams deploy MultiModel Dev OS:
 - 📦 [Full-Stack Next.js SaaS: Database Schema Synchronization](https://rizvee.github.io/multimodel-dev-os/case-studies/nextjs-saas)
 - 🔌 [WordPress Theme Scaffolding: Folder Boundary Protections](https://rizvee.github.io/multimodel-dev-os/case-studies/wordpress-site)
 - 🛒 [E-Commerce Webhooks: State Verification Alignment](https://rizvee.github.io/multimodel-dev-os/case-studies/ecommerce-store)
@@ -182,31 +266,68 @@ Discover how engineering teams deploy MultiModel Dev OS:
 
 ---
 
-## Stable Protocol Specification & Roadmap
+## Intelligence Layer (v2.1.0 — Coming Next)
 
-MultiModel Dev OS v2.x packages the stable Layer 1, Layer 2, and Layer 3 specifications alongside the Model Compatibility and Template Galaxy registries.
-- 🏁 [v2 Release Checklist](/docs/v2-release-checklist.md) (Release quality checklist)
-- 🛡️ [Stable Protocol Specification](https://rizvee.github.io/multimodel-dev-os/stable-protocol)
-- 🔌 [Multi-Agent Compatibility Guides](https://rizvee.github.io/multimodel-dev-os/compatibility)
-- 📈 [Upgrade & Migration Guide](https://rizvee.github.io/multimodel-dev-os/migration-guide)
-- 🏁 [v1.0.0 Release Quality Checklist](https://rizvee.github.io/multimodel-dev-os/v1-checklist)
+The next major milestone introduces a **future-proof intelligence layer** — registry-driven, feedback-enabled, with strict human-in-the-loop safety gates:
+
+| Component | Description |
+|:---|:---|
+| **Capability Registry** | Score models across coding, reasoning, repo-scan, agentic-duration, MCP compliance — no hardcoded names |
+| **Tool Registry** | Define IDE, terminal, and MCP tool integrations dynamically |
+| **Hash-Compressed Memory** | Token-efficient codebase fingerprints, summaries, and dependency maps |
+| **Feedback Learning** | Convert developer corrections into reusable system rules |
+| **Self-Improvement Engine** | Proposal → Review → Apply cycles with mandatory HITL approval and automatic rollback |
+
+> [!NOTE]
+> The v2.1.0 schemas, registries, and policies are already committed and verified (193/193 assertions pass). CLI implementation is the next phase.
+
+Learn more:
+- [Future-Proof Architecture](https://rizvee.github.io/multimodel-dev-os/future-proof-architecture)
+- [Hash-Compressed Memory](https://rizvee.github.io/multimodel-dev-os/hash-compressed-memory)
+- [Feedback Learning](https://rizvee.github.io/multimodel-dev-os/feedback-learning)
+- [Capability Registry Guide](https://rizvee.github.io/multimodel-dev-os/capability-registry)
+- [v2 Roadmap (v2.1 → v3.0)](https://rizvee.github.io/multimodel-dev-os/v2-roadmap)
 
 ---
 
-## Contributing
+## Roadmap
 
-We love contributions! Propose new adapters, request built-in templates, or report issues safely.
-Read our [Contributing Onboarding Guidelines](CONTRIBUTING.md) to get started.
+| Version | Focus | Status |
+|:---|:---|:---|
+| **v2.0.0** | Template Galaxy, Model Registry, Stable Protocol | ✅ Released |
+| **v2.0.1** | Post-release polish, docs cleanup, 193 verify assertions | ✅ Released |
+| **v2.1.0** | Intelligence Core — Registries, Memory Engine, Capability Routing | ✅ Released |
+| **v2.2.0** | Feedback Loops & MCP Tool Integrations | ✅ Released |
+| **v2.3.0** | Proposal Engine & Safety Controls | ✅ Released |
+| **v2.4.0** | Approved Proposal Application Engine | ✅ Released |
+| **v2.4.1** | Proposal Apply UX + Safety Patch | ✅ Released |
+| **v2.5.0** | Repository Intelligence Command Center | ✅ Released |
+| **v3.0.0** | Unified Autonomous Co-Pilot Ecosystem | 🔮 Future |
+
+Full details: **[v2 Roadmap](https://rizvee.github.io/multimodel-dev-os/v2-roadmap)**
 
 ---
 
-## Docs & Staging Links
+## Documentation & Resources
+
+| Resource | Link |
+|:---|:---|
+| 📖 Documentation Portal | **[rizvee.github.io/multimodel-dev-os](https://rizvee.github.io/multimodel-dev-os/)** |
+| 🐙 GitHub Repository | **[github.com/rizvee/multimodel-dev-os](https://github.com/rizvee/multimodel-dev-os)** |
+| 📦 NPM Registry | **[npmjs.com/package/multimodel-dev-os](https://www.npmjs.com/package/multimodel-dev-os)** |
+| 🤖 AI Discoverability | **[llms.txt](https://rizvee.github.io/multimodel-dev-os/llms.txt)** |
+| 🚀 Quick Start | **[Quickstart Guide](https://rizvee.github.io/multimodel-dev-os/quickstart)** |
+| 🏗️ Architecture | **[Architecture Deep Dive](https://rizvee.github.io/multimodel-dev-os/architecture)** |
+| 🔄 Migration Guide | **[Upgrade from v1.x](https://rizvee.github.io/multimodel-dev-os/migration-guide)** |
+| 🛡️ Stable Protocol | **[Protocol Specification](https://rizvee.github.io/multimodel-dev-os/stable-protocol)** |
+
+---
+
+## Contributing
+
+We welcome contributions! Propose new adapters, request templates, improve docs, or report issues.
 
-Explore detailed specifications, guides, and playbooks at the official docs portal:
-👉 **[Documentation site](https://rizvee.github.io/multimodel-dev-os/)**
-👉 **[GitHub repository](https://github.com/rizvee/multimodel-dev-os)**
-👉 **[NPM registry](https://www.npmjs.com/package/multimodel-dev-os)**
-👉 **[llms.txt discoverability guide](https://rizvee.github.io/multimodel-dev-os/llms.txt)**
+Read our **[Contributing Guidelines](CONTRIBUTING.md)** to get started.
 
 ---