multimodel-dev-os 0.8.0 → 1.1.0

package/docs/final-launch.md

@@ -0,0 +1,34 @@
+# Final Launch Guidelines (v1.1.0)
+
+This document details the final launch guidelines and distribution routines for the public releases of MultiModel Dev OS.
+
+> **Use when**: Executing pre-flight local audits, managing release announcements, or verifying package integrity.
+
+---
+
+## 1. Local Pre-flight Verification
+
+Prior to pushing files to the remote repository, ensure that:
+- The exact target version `1.1.0` is configured in `package.json`.
+- The cross-platform verify script completes cleanly:
+  ```bash
+  npm run verify
+  ```
+- The VitePress documentation compiles without warnings or errors:
+  ```bash
+  npm run docs:build
+  ```
+
+---
+
+## 2. Launch Announcement Outlines
+
+When publishing the stable release, communicate the key advantages clearly:
+- **Portability**: Write-once configurations working seamlessly across Cursor, Claude, Gemini, Antigravity, and VS Code.
+- **Context Economy**: Up to 79% reduction in prompt tokens through Caveman Mode configurations.
+- **Zero Dependencies**: A completely self-contained CLI for lightning-fast setups.
+- **AI Discoverability**: Ready-to-ingest discoverability guides (`llms.txt` / `llms-full.txt`) for LLM agents.
+
+Refer to `docs/launch-kit.md` for specific copy blocks ready for distribution on Twitter/X, LinkedIn, Hacker News, and Reddit.
+
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/index.md

@@ -4,7 +4,7 @@ layout: home
 hero:
   name: "MultiModel Dev OS"
   text: "Standardize your AI pair-programmers"
-  tagline: "Portable, vendor-neutral workspace configurations for multi-agent coding loops."
+  tagline: "One portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows."
   image:
     src: /logo.png
     alt: MultiModel Dev OS Logo
@@ -13,14 +13,14 @@ hero:
       text: Get Started Quick
       link: /quickstart
     - theme: alt
-      text: View Case Studies
-      link: /case-studies/
+      text: Stable Protocol Specs
+      link: /stable-protocol
     - theme: alt
-      text: Cost Playbook
-      link: /cost-optimization
+      text: v1.0 Readiness
+      link: /v1-readiness
     - theme: alt
-      text: 5-Day Roadmap
-      link: /5-day-roadmap
+      text: View Case Studies
+      link: /case-studies/
     - theme: alt
       text: View on GitHub
       link: https://github.com/rizvee/multimodel-dev-os
@@ -42,8 +42,125 @@ features:
   --vp-home-hero-name-color: transparent;
   --vp-home-hero-name-background: linear-gradient(135deg, #6366f1 0%, #10b981 100%);
 }
+.grid-container {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  gap: 1.5rem;
+  margin-top: 2rem;
+  margin-bottom: 2rem;
+}
+.card-item {
+  border: 1px solid var(--vp-c-bg-mute);
+  background-color: var(--vp-c-bg-soft);
+  border-radius: 8px;
+  padding: 1.5rem;
+  transition: border-color 0.25s, transform 0.25s;
+  text-decoration: none !important;
+  color: inherit !important;
+}
+.card-item:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-4px);
+}
+.card-title {
+  font-weight: 600;
+  font-size: 1.15rem;
+  margin-bottom: 0.5rem;
+}
+.card-desc {
+  font-size: 0.9rem;
+  color: var(--vp-c-text-2);
+}
+.works-with-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 1rem;
+  margin-top: 1.5rem;
+  margin-bottom: 2.5rem;
+}
+.works-with-item {
+  border: 1px solid var(--vp-c-bg-mute);
+  background-color: var(--vp-c-bg-soft);
+  border-radius: 6px;
+  padding: 1rem;
+  text-align: center;
+  font-weight: 500;
+  font-size: 0.95rem;
+}
 </style>
 
+## Quick Start Setup
+
+Scaffold a tool-neutral workspace instantly:
+
+```bash
+npx multimodel-dev-os@latest init
+```
+
+---
+
+## Works With
+
+MultiModel Dev OS maps repository context directly to all major developer tools and coding agents:
+
+<div class="works-with-grid">
+  <div class="works-with-item">🤖 Codex</div>
+  <div class="works-with-item">🪐 Antigravity</div>
+  <div class="works-with-item">🎯 Cursor</div>
+  <div class="works-with-item">⚡ Claude Code</div>
+  <div class="works-with-item">🧠 Gemini</div>
+  <div class="works-with-item">💻 VS Code</div>
+</div>
+
+---
+
+## Core Specifications & Playbooks
+
+<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>
+  <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>
+  <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>
+  <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>
+  <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>
+  <a href="/v1-checklist" class="card-item">
+    <div class="card-title">🏁 Release Checklist</div>
+    <div class="card-desc">Audit repository compliance with the strict 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>
+</div>
+
+---
+
+## For AI Assistants and Coding Agents
+
+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.
+
+---
+
 ## Cost & Context Optimization
 
 Minimize prompt overhead and API billing by mapping key context-reduction techniques to MultiModel Dev OS features:

package/docs/migration-guide.md

@@ -0,0 +1,54 @@
+# Migration Guide: Upgrading MultiModel Dev OS
+
+This guide assists engineering teams in upgrading their MultiModel Dev OS configurations across releases, preparing repositories for v1.0.0 compliance.
+
+---
+
+## 1. Upgrading from v0.1 to v0.5
+
+The `v0.5` release introduced the pure-Node local CLI and template scaffolding directories.
+
+### Upgrade Steps:
+1. **Directory Scaffolding:** Create the Lower-case subfolders under `.ai/` if they do not exist:
+   ```bash
+   mkdir -p .ai/context .ai/skills .ai/session-logs
+   ```
+2. **Move Custom Rules:** Scrape old system prompt snippets from `.cursorrules` and modularize them into isolated files inside `.ai/context/` (e.g. `project-brief.md`, `architecture.md`).
+3. **Configure Adapters Settings:** Create [.ai/config.yaml](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/.ai/config.yaml) and configure adapter mappings:
+   ```yaml
+   version: "0.5.0"
+   adapters:
+     cursor: true
+     claude: true
+   ```
+
+---
+
+## 2. Upgrading from v0.5 to v0.8
+
+The `v0.8` release focused on cost/context optimizations, adding the 12 playbook techniques and visual timelines.
+
+### Upgrade Steps:
+1. **Enable Caveman Mode:** Set up Caveman minimal-token files inside `.ai/templates/` to allow rapid chat turns under tight budgets.
+2. **Deploy Session Logs:** Confirm a `session-log-template.md` exists in `.ai/templates/` and create [.ai/session-logs/README.md](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/.ai/session-logs/README.md) to manage sequential handoffs.
+3. **Audit Workspace compliance:** Run the linter to diagnostic environment issues:
+   ```bash
+   npx multimodel-dev-os doctor
+   ```
+
+---
+
+## 3. Upgrading from v0.9.0 to v1.0.0 Stable
+
+The `v1.0.0` release completely freezes the public protocol and schemas.
+
+### Upgrade Steps:
+1. **Mount JSON Schemas:** Verify that config schemas under `.ai/schema/` are linked in your local configuration files.
+2. **Execute Strict Validations:** Enforce strict assertions inside your pull requests or pre-commit hooks:
+   ```bash
+   npx multimodel-dev-os validate
+   ```
+3. **Run Diagnostics Suite:** Execute the full verification and doctor suite to ensure absolute compliance:
+   ```bash
+   npx multimodel-dev-os doctor
+   ```

package/docs/protocol.md

@@ -0,0 +1,58 @@
+# MultiModel Dev OS Protocol Specification (v1.1.0)
+
+This document defines the official, stable architectural protocol and design contracts for MultiModel Dev OS, establishing portable AI project context conventions.
+
+> **Use when**: Implementing a custom CLI client, creating private adapters, or auditing Layer 1-3 protocol compliance.
+
+---
+
+## 1. Protocol Architecture Layers
+
+The protocol is divided into three distinct decoupled layers to guarantee portability:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 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/        │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Stability Matrix (v1.1.0 Freeze)
+
+To prevent breaking changes, protocol definitions are designated as **Stable** or **Experimental**:
+
+### A. Stable Protocol Components
+These features are fully frozen. No breaking changes or renaming will occur in `v1.x`:
+- **Core Workspace Contracts:** The names and root directories of `AGENTS.md`, `MEMORY.md`, `TASKS.md`, and `RUNBOOK.md` are completely frozen.
+- **Scaffolding Subfolders:** Target folders `.ai/context/`, `.ai/skills/`, and `.ai/session-logs/` are strictly required by the sync CLI.
+- **Adapters Interface:** Mappings to Cursor (`.cursorrules`), Claude (`CLAUDE.md`), VS Code (`.vscode/settings.json`), and Gemini (`GEMINI.md`) are guaranteed.
+- **Core Commands:** Subcommands `init`, `verify`, `validate`, `doctor`, and `templates` will retain their signatures.
+
+### B. Experimental Components
+These components represent early specs and may undergo minor tweaks in future minor releases:
+- **Caveman Mode Custom Overrides:** Custom manual template modifications under `.ai/templates/`.
+- **Dynamic Context Routing:** Pre-implementation check validations inside `.ai/checks/context-budget.md`.
+
+---
+
+## 3. CLI Command Contracts
+
+All compliant MultiModel Dev OS CLIs must strictly support the following execution contracts:
+- **`init` Scaffolding:** Recursively writes root documents and links requested adapters.
+- **`validate` Quality Gate:** Asserts that required folders and enabled adapter rules exist on disk.
+- **`doctor` Diagnostic:** Advisory audit of `.gitignore` setups and folder compatibility.
+- **`templates` Inspector:** Displays available stack configurations.
+
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/public/humans.txt

@@ -0,0 +1,13 @@
+/* TEAM */
+Maintainer: rizvee
+GitHub: https://github.com/rizvee
+
+/* THANKS */
+Special thanks to: All Open Source contributors, AI agents, and early adoptions teams!
+
+/* SITE */
+Canonical: https://rizvee.github.io/multimodel-dev-os/
+Codebase: https://github.com/rizvee/multimodel-dev-os
+License: MIT License
+Language: JavaScript
+Framework: VitePress

package/docs/public/llms-full.txt

@@ -0,0 +1,73 @@
+# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide
+
+MultiModel Dev OS is a repository-level porting specification designed to align context and instructions across diverse developer tools and AI models.
+
+---
+
+## 1. Core Architecture Layers
+
+The protocol decouples the centralized workspace context from the individual tool rules:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ 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 Documents
+- **`AGENTS.md`**: Defines teams, capabilities, boundaries, and model instructions.
+- **`MEMORY.md`**: Holds architectural decisions, repository milestones, and tech stacks.
+- **`TASKS.md`**: Active backlog tracking items.
+- **`RUNBOOK.md`**: Operational verification commands and post-deployment routines.
+
+---
+
+## 2. CLI Command specifications
+
+All compliant MultiModel Dev OS CLIs strictly enforce the following command contracts:
+- **`init`**: Scaffolds the standard `.ai/` context configuration directories.
+- **`verify`**: Automated release script that checks structure integrity.
+- **`templates`**: Lists built-in stack specifications (`nextjs-saas`, `wordpress-site`, `ecommerce-store`, `seo-landing-page`, `general-app`).
+- **`validate`**: Strict Quality Gate checking the layout rules on disk.
+- **`doctor`**: Advisory checkup warning you about unignored compiler caches or large folder directories.
+
+---
+
+## 3. Adapters & Mappings
+
+Adapters read context directly from `AGENTS.md` and translate them into native configs:
+- **Cursor** targets root `.cursorrules`
+- **Claude Code** targets root `CLAUDE.md`
+- **VS Code** targets `.vscode/settings.json`
+- **Gemini** targets root `GEMINI.md`
+- **Antigravity** targets `.gemini/settings.json`
+
+---
+
+## 4. Key Context Optimization (Caveman Mode)
+
+Toggling **Caveman Mode** dynamically reduces system prompt instructions to highly-optimized shorthand symbols, reducing rule tokens footprint by **~79%** for low-cost token execution budgets:
+
+```bash
+npx multimodel-dev-os@latest init --caveman
+```
+
+---
+
+## 5. Canonical Links
+- **Documentation site**: https://rizvee.github.io/multimodel-dev-os/
+- **GitHub Codebase**: https://github.com/rizvee/multimodel-dev-os
+- **Release Policies**: https://rizvee.github.io/multimodel-dev-os/release-policy
+- **LTS Support Policies**: https://rizvee.github.io/multimodel-dev-os/support-policy
+- **Upgrade Playbook**: https://rizvee.github.io/multimodel-dev-os/migration-guide

package/docs/public/llms.txt

@@ -0,0 +1,34 @@
+# MultiModel Dev OS (v1.1.0)
+
+Portable, vendor-neutral workspace configuration standard for multi-agent AI pair-programming workflows. 
+
+## What It Does
+Provides a unified repository-level specification using root markdown files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) and bridges them dynamically to multiple developer tools, ensuring zero instruction drift and up to 79% token context savings.
+
+## Fast Setup
+```bash
+npx multimodel-dev-os@latest init
+```
+
+## Supported Tools
+- **Cursor** (`.cursorrules`)
+- **Claude Code** (`CLAUDE.md`)
+- **VS Code** (`.vscode/settings.json`)
+- **Gemini** (`GEMINI.md`)
+- **Antigravity** (`.gemini/settings.json`)
+- **Codex** (`adapters/codex/AGENTS.md`)
+
+## Core Resources
+- **Canonical Website**: https://rizvee.github.io/multimodel-dev-os/
+- **GitHub Repository**: https://github.com/rizvee/multimodel-dev-os
+- **NPM Registry Package**: https://www.npmjs.com/package/multimodel-dev-os
+- **Stable Protocol Specification**: https://rizvee.github.io/multimodel-dev-os/stable-protocol
+- **Cost/Context Optimization Playbook**: https://rizvee.github.io/multimodel-dev-os/cost-optimization
+- **5-Day Adoption Roadmap**: https://rizvee.github.io/multimodel-dev-os/5-day-roadmap
+
+## Standard Templates
+- `nextjs-saas` (App Router, Prisma ORM, Stripe)
+- `wordpress-site` (Custom Block Themes, secure PHP guidelines)
+- `ecommerce-store` (PCI checkout, Webhooks, card state)
+- `seo-landing-page` (Astro static builds, JSON-LD, optimal LCP)
+- `general-app` (Universal baseline configurations)

package/docs/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://rizvee.github.io/multimodel-dev-os/sitemap.xml

package/docs/public/sitemap.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/</loc>
+    <changefreq>daily</changefreq>
+    <priority>1.0</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/quickstart</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/templates/</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/protocol</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/stable-protocol</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.9</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/compatibility</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/migration-guide</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/cost-optimization</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/5-day-roadmap</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.6</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/case-studies/</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/demo</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/faq</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.6</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/v1-checklist</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.6</priority>
+  </url>
+</urlset>

package/docs/quickstart.md

@@ -1,6 +1,8 @@
-# Quickstart
+# Quickstart Guide: AI Dev OS Deployment
 
-Get `multimodel-dev-os` integrated into your codebase in under 2 minutes.
+Get the MultiModel Dev OS integrated into your codebase in under 2 minutes to synchronize your multi-agent developer workflows.
+
+> **Use when**: Setting up a new repository or aligning multiple AI tools (like Cursor, Claude Code, Gemini, Codex, and Antigravity) to prevent instruction drift and prompt token bloat.
 
 ---
 
@@ -39,7 +41,7 @@ irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/inst
 
 ## Option C: Caveman Mode (Minimal Tokens)
 
-Reduce token footprint by **~79%** with our lightweight variants:
+**Best for**: Context optimization for AI coding when using tight API budgets or smaller models. Reduces rules footprint by **~79%**.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash -s -- --caveman
@@ -63,13 +65,13 @@ For offline execution or customized packaging within a cloned workspace:
 
 ## After Install
 
-1. **Edit `AGENTS.md`** — fill in your project name, stack, and build commands.
+1. **Edit `AGENTS.md`** — fill in your project name, stack, and build commands (portable AI project context).
 2. **Edit `.ai/config.yaml`** — enable adapters for your tools.
-3. **Copy adapter files** to your project root:
+3. **Copy adapter files** to your project root (e.g., Cursor project rules, Claude Code project instructions):
    - Cursor: `cp adapters/cursor/.cursorrules .cursorrules`
    - Claude: `cp adapters/claude/CLAUDE.md CLAUDE.md`
    - VS Code: `cp -r adapters/vscode/.vscode/ .vscode/`
-4. **Start coding** — your AI tools will read the shared configuration instantly.
+4. **Start coding** — your AI coding agents will read the shared configuration instantly.
 
 ---
 
@@ -87,3 +89,5 @@ node bin/multimodel-dev-os.js doctor
 # Verify repository structure checks
 npm run verify
 ```
+
+Explore our canonical [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/release-policy.md

@@ -0,0 +1,33 @@
+# Release Policy
+
+This document defines the versioning guidelines and standard practices for public releases of the MultiModel Dev OS protocol and CLI tool.
+
+---
+
+## 1. Semantic Versioning Commitments
+
+MultiModel Dev OS strictly adheres to **Semantic Versioning 2.0.0 (SemVer)**:
+- **Major Releases (X.y.z)**: Incremented when backward-incompatible changes are made to the Layer 1-3 protocol or CLI signatures.
+- **Minor Releases (x.Y.z)**: Incremented when new features, optional templates, or backward-compatible adapters are added.
+- **Patch Releases (x.y.Z)**: Incremented for backward-compatible bug fixes, docs corrections, or verification improvements.
+
+---
+
+## 2. Breaking Changes Definition
+
+A modification is defined as a **breaking change** if it:
+1. Renames or deletes any of the frozen Layer 1 root contracts (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`).
+2. Alters standard directory structures (`.ai/context/`, `.ai/skills/`).
+3. Breaks existing CLI command signatures or required inputs.
+
+Any such changes are prohibited outside of new major version releases (e.g., `2.0.0`).
+
+---
+
+## 3. Pre-Flight Verification Gates
+
+No package shall be merged or released without:
+- Passing all checks inside the `scripts/verify.js` release verification suite.
+- Building the documentation site without dead links (`npm run docs:build`).
+- Running packaging validation (`npm pack --dry-run`).
+- Executing smoke tests on all templates.

package/docs/stable-protocol.md

@@ -0,0 +1,70 @@
+# Stable Protocol Specification (v1.1.0 Freeze)
+
+This document formalizes the official, frozen architectural layers and design contracts for the MultiModel Dev OS protocol, guaranteeing portability and long-term stability across diverse AI coding agents.
+
+> **Best for**: Third-party client integrations, tool adapter developers, and engineering teams establishing robust AI coding guidelines.
+
+---
+
+## 1. Frozen Layers Architecture
+
+MultiModel Dev OS enforces a three-tier design to decouple core workspace context from individual IDE adapters:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ LAYER 1: Root Contracts (Single Source of Truth)       │
+│ AGENTS.md • MEMORY.md • TASKS.md • RUNBOOK.md          │
+│ Status: FROZEN                                         │
+└──────────────────────────┬─────────────────────────────┘
+                           │ Centralizes project context
+┌──────────────────────────▼─────────────────────────────┐
+│ LAYER 2: Configuration & Modules (.ai/)                │
+│ context/ • agents/ • skills/ • prompts/ • checks/      │
+│ Status: FROZEN                                         │
+└──────────────────────────┬─────────────────────────────┘
+                           │ Routes files dynamically
+┌──────────────────────────▼─────────────────────────────┐
+│ LAYER 3: Tool & IDE Adapters                           │
+│ .cursorrules • CLAUDE.md • .vscode/ • .gemini/        │
+│ Status: FROZEN                                         │
+└────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Layer 1: Root Contracts
+
+The following root files serve as the workspace single source of truth and are completely frozen:
+- **`AGENTS.md`**: Defines team structures, boundaries, and model configurations (Codex project memory / Antigravity AI workflow).
+- **`MEMORY.md`**: Preserves key context decisions, codebase state, and repository milestones.
+- **`TASKS.md`**: Tracks current active goals and backlog.
+- **`RUNBOOK.md`**: Operational scripts and workspace verify procedures.
+
+---
+
+## 3. Layer 2: Scaffolding Layout
+
+The following directories and files under `.ai/` are strictly locked:
+- **`.ai/config.yaml`**: Standard configuration file mapping templates and active adapters.
+- **`.ai/context/`**: Standard markdown files containing architecture guidelines, briefs, and SEO rules.
+- **`.ai/skills/`**: High-frequency modular instructions for agent workflows.
+- **`.ai/session-logs/`**: Standard directory for tracking agent workspace operations.
+
+---
+
+## 4. Layer 3: Adapters Setup
+
+IDE adapters translate centralized rules to tool-specific paths (Cursor project rules / Claude Code project instructions):
+- **Cursor**: Linked via root `.cursorrules`
+- **Claude**: Linked via root `CLAUDE.md`
+- **Gemini**: Linked via `.gemini/settings.json`
+- **VS Code**: Linked via `.vscode/settings.json`
+
+---
+
+## 5. Experimental vs. Stable Scope
+
+- **Stable**: Root files, scaffolding directories, CLI subcommand signatures, and standard config structures.
+- **Experimental**: Custom check overrides under `.ai/checks/` and stack-specific context routing.
+
+Explore our [Upgrades & Migration Guide](/migration-guide) or [Release Quality Checklist](/v1-checklist) for staging controls.