multimodel-dev-os 0.8.0 → 1.1.0

package/.ai/schema/adapter.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MultiModel Dev OS Adapter Schema",
+  "description": "JSON schema reference detailing tool/IDE adapter expected boundaries and setup layouts",
+  "type": "OBJECT",
+  "required": ["adapterName", "targetFile", "setupDocs"],
+  "properties": {
+    "adapterName": {
+      "type": "STRING",
+      "description": "Unique identifier of the target programming tool (e.g. cursor, claude)"
+    },
+    "targetFile": {
+      "type": "STRING",
+      "description": "The rule configuration file mapped by the adapter"
+    },
+    "setupDocs": {
+      "type": "STRING",
+      "description": "Relative reference to the adapter setup markdown instructions"
+    },
+    "requiredRootFiles": {
+      "type": "ARRAY",
+      "items": { "type": "STRING" },
+      "description": "Root workspace contracts verified by the adapter schema"
+    }
+  },
+  "additionalProperties": false
+}

package/.ai/schema/config.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MultiModel Dev OS Config Schema",
+  "description": "JSON schema reference validating standard .ai/config.yaml workspace settings",
+  "type": "OBJECT",
+  "required": ["version", "adapters"],
+  "properties": {
+    "version": {
+      "type": "STRING",
+      "description": "The configuration protocol version matching semantic limits"
+    },
+    "adapters": {
+      "type": "OBJECT",
+      "description": "Enabled state of target IDE and terminal programming adapters",
+      "properties": {
+        "codex": { "type": "BOOLEAN" },
+        "antigravity": { "type": "BOOLEAN" },
+        "cursor": { "type": "BOOLEAN" },
+        "claude": { "type": "BOOLEAN" },
+        "gemini": { "type": "BOOLEAN" },
+        "vscode": { "type": "BOOLEAN" }
+      },
+      "additionalProperties": false
+    },
+    "caveman": {
+      "type": "BOOLEAN",
+      "description": "Toggled state of minimal-token prompt rules"
+    },
+    "template": {
+      "type": "STRING",
+      "description": "Selected baseline technology stack template name"
+    }
+  },
+  "additionalProperties": false
+}

package/.ai/schema/template.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MultiModel Dev OS Template Schema",
+  "description": "JSON schema reference defining expectations for pre-configured stack templates",
+  "type": "OBJECT",
+  "required": ["name", "requiredFiles"],
+  "properties": {
+    "name": {
+      "type": "STRING",
+      "description": "The unique identifying template name"
+    },
+    "description": {
+      "type": "STRING",
+      "description": "A description of the technology stack profile"
+    },
+    "requiredFiles": {
+      "type": "ARRAY",
+      "items": { "type": "STRING" },
+      "description": "Baseline contracts and subfolders required to scaffold"
+    },
+    "optionalFiles": {
+      "type": "ARRAY",
+      "items": { "type": "STRING" },
+      "description": "Optional overrides or specific skill prompts files"
+    },
+    "supportedAdapters": {
+      "type": "ARRAY",
+      "items": { "type": "STRING" },
+      "description": "IDE and terminal adapters validated for the template"
+    }
+  },
+  "additionalProperties": false
+}

package/README.md

@@ -1,16 +1,25 @@
 # MultiModel Dev OS
 
-Portable, vendor-neutral workspace configuration layer for multi-agent coding loops.
+<p align="center">
+  <img src="assets/logo.png" alt="MultiModel Dev OS Logo" width="160">
+</p>
 
----
+<p align="center">
+  <b>One portable AI Dev OS for multimodel coding workflows.</b>
+</p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/assets/social-preview.svg" alt="MultiModel Dev OS Banner" width="100%">
+  [![NPM Version](https://img.shields.io/npm/v/multimodel-dev-os.svg?color=blue&style=flat-square)](https://www.npmjs.com/package/multimodel-dev-os)
+  [![NPM Package](https://img.shields.io/badge/npm-package-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/multimodel-dev-os)
+  [![License](https://img.shields.io/npm/l/multimodel-dev-os.svg?color=green&style=flat-square)](https://github.com/rizvee/multimodel-dev-os/blob/main/LICENSE)
+  [![GitHub Release](https://img.shields.io/github/v/release/rizvee/multimodel-dev-os?color=indigo&style=flat-square)](https://github.com/rizvee/multimodel-dev-os/releases)
+  [![Build Verification](https://img.shields.io/github/actions/workflow/status/rizvee/multimodel-dev-os/verify.yml?branch=main&style=flat-square&label=verification)](https://github.com/rizvee/multimodel-dev-os/actions)
+  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-emerald.svg?style=flat-square)](https://github.com/rizvee/multimodel-dev-os/blob/main/CONTRIBUTING.md)
 </p>
 
 ---
 
-## Quickstart
+## One portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows.
 
 Initialize a unified, tool-neutral AI developer workspace instantly:
 
@@ -18,29 +27,112 @@ Initialize a unified, tool-neutral AI developer workspace instantly:
 npx multimodel-dev-os@latest init
 ```
 
+> **Give Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and other AI coding agents the same project brain.**
+
+---
+
+<p align="center">
+  <img src="assets/social-preview.svg" alt="MultiModel Dev OS Banner" width="100%">
+</p>
+
+---
+
+## Why This Exists
+
+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.
+
+`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.
+
 ---
 
-## See It in Action
+## What You Get
+
+A standard installation scaffolds a lightweight, zero-runtime-dependency workspace hierarchy:
 
-`multimodel-dev-os` runs completely on native Node.js libraries, keeping execution speeds lightning-fast with **zero third-party NPM runtime dependencies**. Here is the clean interactive terminal sequence executing `init`, `validate`, and `doctor` commands:
+```
+┌────────────────────────────────────────────────────────┐
+│ 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/        │
+└────────────────────────────────────────────────────────┘
+```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/assets/terminal-demo.svg" alt="Terminal Demo Sequence" width="100%">
+  <img src="assets/architecture-preview.svg" alt="Architecture Diagram" width="100%">
 </p>
 
 ---
 
-## Before vs. After
+## 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?
 
-### Before: Chaotic Prompting & Instruction Drift
-- Switching between agents (like Cursor, Claude Code, Gemini, Codex, Antigravity) requires maintaining duplicate instruction files (`.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, etc.).
-- Modifying guidelines in one place results in immediate **Instruction Drift**, where one agent operates on outdated conventions, causing compile crashes.
-- Duplicate instructions bloat prompts, wasting **1,500+ tokens** of model context budget on every single turn.
+While you can write a raw markdown file manually, `multimodel-dev-os` offers a standardized development workflow:
 
-### After: Standardized Zero-Drift Sync
-- Rules are defined once in a central root document (`AGENTS.md` and `.ai/`).
-- MultiModel Dev OS dynamically routes the root contract directly to Cursor, Claude Code, Gemini, and VS Code. All agents operate on matching build specifications instantly.
-- Toggling **Caveman Mode** dynamically strips descriptions and examples, saving **~79% of token context** per chat turn.
+| 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 |
+
+---
+
+## Interactive Command Line Interface (CLI)
+
+MultiModel Dev OS is powered by a pure Node.js CLI with **zero runtime external npm dependencies**.
+
+<p align="center">
+  <img src="assets/terminal-demo.svg" alt="Terminal Demo Sequence" width="100%">
+</p>
+
+### 1. Scaffolding Templates
+Initialize customized stack specifications:
+- **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`
+
+### 2. Adapter Linking
+Inject rules specifically for a developer tool:
+```bash
+npx multimodel-dev-os@latest init --adapter cursor
+npx multimodel-dev-os@latest init --adapter claude
+```
+
+### 3. Caveman Mode (Token Optimizer)
+Cuts prompt rules overhead down by **~79%** using highly optimized short-hand declarations:
+```bash
+npx multimodel-dev-os@latest init --caveman
+```
+
+### 4. Quality Gates
+Run assertions and diagnostic checkups:
+- **`validate`** (Strict schema checkup): `npx multimodel-dev-os validate`
+- **`doctor`** (Advisory compatibility warning): `npx multimodel-dev-os doctor`
 
 ---
 
@@ -49,13 +141,9 @@ npx multimodel-dev-os@latest init
 Minimize prompt overhead and API billing by mapping key context-reduction techniques to MultiModel Dev OS features:
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/assets/cost-optimization.svg" alt="Cost Optimization Funnel" width="100%">
+  <img src="assets/cost-optimization.svg" alt="Cost Optimization Funnel" width="100%">
 </p>
 
-- 🧠 **Choose Right Model:** Configured in `model-map.md`.
-- ⚡ **Caveman Mode:** Cuts rule context sizes down by **~79%**.
-- 📦 **RAG Scoping:** Modular context files in `.ai/context/` prevent token waste.
-
 For a full deep dive, see our [Cost Optimization Playbook](https://rizvee.github.io/multimodel-dev-os/cost-optimization).
 
 ---
@@ -65,7 +153,7 @@ For a full deep dive, see our [Cost Optimization Playbook](https://rizvee.github
 Deploying MultiModel Dev OS across your team is straightforward and tool-neutral:
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/assets/ai-dev-os-roadmap.svg" alt="5-Day Adoption Roadmap" width="100%">
+  <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).
@@ -83,15 +171,33 @@ Discover how engineering teams deploy MultiModel Dev OS:
 
 ---
 
-## Core Navigation Guides
+## Stable Protocol Specification
+
+MultiModel Dev OS version `v1.1.0` officially freezes the Layer 1, Layer 2, and Layer 3 specifications:
+- 🛡️ [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)
+
+---
+
+## Contributing
+
+We love contributions! Propose new adapters, request built-in templates, or report issues safely.
+Read our [Contributing Onboarding Guidelines](CONTRIBUTING.md) to get started.
+
+---
+
+## Docs & Staging Links
 
-Explore our detailed manuals directly:
-- 📖 [CLI Terminal Demo Guide](https://rizvee.github.io/multimodel-dev-os/demo)
-- 💡 [Before/After Workflow Case Studies](https://rizvee.github.io/multimodel-dev-os/workflow-examples)
-- 🛡️ [Public Release & Staging Checklist](https://rizvee.github.io/multimodel-dev-os/launch-checklist)
+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)**
 
 ---
 
 ## License
 
-MIT License.
+MIT License. Copyright (c) 2026-present MultiModel Dev OS team.

package/bin/multimodel-dev-os.js

@@ -202,6 +202,7 @@ function handleInit(options) {
   // Source path mapping for core files
   let templateDir = join(sourceRoot, 'examples', options.template);
   if (!existsSync(templateDir)) {
+    console.warn(`  \x1b[33m[WARNING] Template '${options.template}' not found. Falling back to 'general-app' profile.\x1b[0m`);
     templateDir = join(sourceRoot, 'examples', 'general-app');
   }
 

package/docs/.vitepress/config.js

@@ -3,6 +3,40 @@ export default {
   title: 'MultiModel Dev OS',
   description: 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.',
   ignoreDeadLinks: true,
+  head: [
+    ['link', { rel: 'icon', href: '/multimodel-dev-os/favicon.png', type: 'image/png' }],
+    ['link', { rel: 'canonical', href: 'https://rizvee.github.io/multimodel-dev-os/' }],
+    ['meta', { name: 'theme-color', content: '#6366f1' }],
+    ['meta', { name: 'robots', content: 'index, follow' }],
+    ['meta', { name: 'application-name', content: 'MultiModel Dev OS' }],
+    ['meta', { name: 'apple-mobile-web-app-title', content: 'MultiModel Dev OS' }],
+    ['meta', { property: 'og:title', content: 'MultiModel Dev OS' }],
+    ['meta', { property: 'og:description', content: 'Portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows.' }],
+    ['meta', { property: 'og:image', content: 'https://rizvee.github.io/multimodel-dev-os/assets/social-preview.svg' }],
+    ['meta', { property: 'og:url', content: 'https://rizvee.github.io/multimodel-dev-os/' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:title', content: 'MultiModel Dev OS' }],
+    ['meta', { name: 'twitter:description', content: 'Portable AI Dev OS for Codex, Antigravity, Cursor, Claude, Gemini, VS Code, and multimodel coding workflows.' }],
+    ['meta', { name: 'twitter:image', content: 'https://rizvee.github.io/multimodel-dev-os/assets/social-preview.svg' }],
+    [
+      'script',
+      { type: 'application/ld+json' },
+      JSON.stringify({
+        '@context': 'https://schema.org',
+        '@type': 'SoftwareApplication',
+        'name': 'MultiModel Dev OS',
+        'applicationCategory': 'DeveloperApplication',
+        'operatingSystem': 'Windows, macOS, Linux',
+        'programmingLanguage': 'JavaScript',
+        'license': 'https://opensource.org/licenses/MIT',
+        'url': 'https://github.com/rizvee/multimodel-dev-os',
+        'downloadUrl': 'https://www.npmjs.com/package/multimodel-dev-os',
+        'softwareVersion': '1.1.0',
+        'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
+      })
+    ]
+  ],
   themeConfig: {
     logo: '/logo.png',
     nav: [
@@ -21,6 +55,17 @@ export default {
           { text: 'FAQ', link: '/faq' }
         ]
       },
+      {
+        text: 'Protocol & QA Specifications',
+        items: [
+          { text: 'Protocol Specification', link: '/protocol' },
+          { text: 'Stable Protocol Specification', link: '/stable-protocol' },
+          { text: 'Adapter Compatibility', link: '/compatibility' },
+          { text: 'Upgrades & Migration', link: '/migration-guide' },
+          { text: 'Templates QA Blueprint', link: '/template-qa' },
+          { text: 'v1.0.0 Readiness Checklist', link: '/v1-readiness' }
+        ]
+      },
       {
         text: 'Case Studies & Playbooks',
         items: [
@@ -64,7 +109,11 @@ export default {
           { text: 'Release Playbook Template', link: '/release-template' },
           { text: 'CLI Roadmap', link: '/cli-roadmap' },
           { text: 'NPM Publishing Runbook', link: '/npm-publishing' },
-          { text: 'Pre-flight Release Testing', link: '/testing-v0.2' }
+          { text: 'Pre-flight Release Testing', link: '/testing-v0.2' },
+          { text: 'Release Policy', link: '/release-policy' },
+          { text: 'Support Policy', link: '/support-policy' },
+          { text: 'Final Launch Guidelines', link: '/final-launch' },
+          { text: 'v1.0.0 Release Checklist', link: '/v1-checklist' }
         ]
       }
     ],

package/docs/case-studies/index.md

@@ -1,6 +1,8 @@
-# Real-World Case Studies
+# Real-World Case Studies: AI Dev OS Integrations
 
-Explore how engineering teams and developers leverage `multimodel-dev-os` to prevent instruction drift, secure workspace boundaries, and save significant LLM token context budgets.
+Explore how engineering teams and developers leverage MultiModel Dev OS to prevent instruction drift, secure workspace boundaries, and save significant LLM token context budgets.
+
+> **Use when**: Designing a workflow for a specific tech stack (like Next.js SaaS schema synchronization, WordPress themes, headless checkout loops, or multi-model handoffs).
 
 ---
 
@@ -9,16 +11,18 @@ Explore how engineering teams and developers leverage `multimodel-dev-os` to pre
 Select a case study to see specific problems, setups, commands, outcomes, and reusable design patterns:
 
 ### 1. [Full-Stack Next.js SaaS](nextjs-saas.md)
-*Solving schema sync and inline autocompletion shifts across full-stack applications.*
+*Solving schema sync and inline autocompletion shifts across full-stack applications (Nextjs SaaS template / database schema synchronization).*
 
 ### 2. [WordPress Theme & Plugin Development](wordpress-site.md)
-*Securing PHP coding style conventions and folder overrides during local scaffolding.*
+*Securing PHP coding style conventions and folder overrides during local scaffolding (WordPress theme folder boundaries).*
 
 ### 3. [E-Commerce Webhooks & State Tracking](ecommerce-store.md)
-*Keeping payment routes and database event states strictly aligned between terminal-based models and editors.*
+*Keeping payment routes and database event states strictly aligned between terminal-based models and editors (e-commerce state webhooks).*
 
 ### 4. [SEO Landing Page Audits](seo-landing-page.md)
-*Managing multiple automated performance linter audits and SEO checkups.*
+*Managing multiple automated performance linter audits and SEO checkups (SEO landing page performance Core Web Vitals).*
 
 ### 5. [Multi-Model Handoff Protocols](multimodel-handoff.md)
-*Structuring sequential session logs to pass context between Claude Code and Gemini with zero token drops.*
+*Structuring sequential session logs to pass context between Claude Code and Gemini with zero token drops (Claude Gemini handoff logs).*
+
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/cli-roadmap.md

@@ -54,3 +54,11 @@ node bin/multimodel-dev-os.js verify
 * **Adapter Autoregeneration (`sync`):** Parse custom override boundaries inside adapters and automatically synchronize them with updates in the root markdown source of truth.
 * **Interactive Mode:** Provide step-by-step CLI options if run without arguments.
 
+## Protocol Stabilization & v1.0.0 Freeze (v0.9.0)
+
+In version **v0.9.0**, we pivot the roadmap to focus on **stabilization and hardening** ahead of the official `v1.0.0` freeze:
+- **API Freeze:** The CLI syntax, standard command names (`init`, `verify`, `validate`, `doctor`, `templates`), and dynamic flags are frozen to ensure zero breaking changes in future minor patches.
+- **Robust JSON Schemas:** Added standard validators inside `.ai/schema/` to define config and template formats.
+- **Continuous Integration Gates:** Transitioning `validate` to serve as a strict build blocker for pulling and publishing code.
+- **Enhanced Warning Paths:** Hardened CLI error messaging when directory write conflicts occur, mapping absolute paths cleanly.
+

package/docs/compatibility.md

@@ -0,0 +1,46 @@
+# Compatibility & Customization Guide
+
+This document maps how MultiModel Dev OS integrates across diverse IDEs and terminal utilities, detailing what parameters developers can customize without breaking the protocol.
+
+> **Use when**: Setting up tool configurations (like Cursor project rules or Claude Code project instructions) or configuring the active adapter mappings in `.ai/config.yaml`.
+
+---
+
+## 1. Supported Tool Matrix
+
+The CLI routes centralized specifications directly to the following target adapters:
+
+| Tool / Agent | Target Adapter File | Setup Instructions | Behavior Setup |
+| :--- | :--- | :--- | :--- |
+| **Cursor** | `.cursorrules` | `adapters/cursor/setup.md` | Inline autocomplete guidelines |
+| **Claude Code** | `CLAUDE.md` | `adapters/claude/setup.md` | Terminal build and run controls |
+| **VS Code** | `.vscode/settings.json` | `adapters/vscode/setup.md` | Editor layout and search limits |
+| **Gemini** | `GEMINI.md` | `adapters/gemini/setup.md` | Prompt system context logs |
+| **Antigravity** | `.gemini/settings.json` | `adapters/antigravity/setup.md` | Security and audit parameters |
+| **Codex** | `adapters/codex/AGENTS.md` | `adapters/codex/setup.md` | Automated code scaffolding |
+
+---
+
+## 2. Safe Customizations
+
+Developers can customize the following configurations inside the `.ai/` directory without breaking linter checkups:
+- **Skills and Prompts:** Adding custom task files under `.ai/skills/` (e.g., custom database migrations, API setups).
+- **Core Memory Notes:** Expanding milestones or architectural notes in `MEMORY.md` and `RUNBOOK.md`.
+- **Model Routings:** Adjusting provider selections and endpoint targets inside `.ai/context/model-map.md`.
+
+---
+
+## 3. Strict Rules (Do Not Rename)
+
+To guarantee validation compliance:
+- **Do Not Rename Root Documents:** The core contract files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) must reside exactly at the repository root and use capital letters.
+- **Do Not Modify Schema Subfolders:** Subdirectories under `.ai/` (context, skills, prompts, checks, session-logs) must maintain lower-case names.
+- **Do Not Interfere with CLI Flags:** Compliance checks expect `init`, `validate`, and `doctor` to accept `--target` and `--adapter` variables consistently.
+
+---
+
+## 4. v1.1.0 Compatibility Guarantee
+
+The supported tool matrix and custom specifications listed here represent the officially frozen contracts of MultiModel Dev OS `v1.1.0`. Any backward-compatible extensions introduced in subsequent `1.x` releases will build on top of these mappings without breaking current project integrations.
+
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/cost-optimization.md

@@ -1,6 +1,8 @@
-# LLM Cost & Context Optimization Playbook
+# LLM Cost & Context Optimization Playbook (v1.1.0)
 
-Maximizing developer velocity while minimizing LLM prompt overhead and API billing budgets is a critical priority for engineering teams. This playbook maps 12 industry cost-reduction techniques directly to native `multimodel-dev-os` features.
+Maximizing developer velocity while minimizing LLM prompt overhead and API billing budgets is a critical priority for engineering teams. This playbook maps 12 industry cost-reduction techniques directly to native MultiModel Dev OS features.
+
+> **Use when**: Optimizing API token usage, configuring Caveman Mode settings, or designing modular prompt caching strategies.
 
 ---
 
@@ -59,3 +61,5 @@ Below is how the 12 core context optimization strategies are implemented inside
 ### 12. Embedding Hygiene
 - **The Strategy:** Ensure semantic search indexes only relevant source files instead of temporary distributions.
 - **Dev OS Implementation:** Strict routing specifications mapped inside `context-routing.md` and pre-configured `.gitignore` definitions protect search databases from index pollution.
+
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/faq.md

@@ -1,83 +1,67 @@
-# FAQ
+# FAQ: MultiModel Dev OS Questions & Answers
+
+Frequently asked questions regarding MultiModel Dev OS, AI coding agents compatibility, and prompt context optimization.
+
+> **Use when**: Resolving setup ambiguities, understanding comparative advantages over simple rules files, or auditing CLI validations.
+
+---
 
 ## General
 
-**What is multimodel-dev-os?**
-A set of markdown files and conventions that let multiple AI coding tools
-(Codex, Cursor, Claude, Gemini, Antigravity, VS Code) share the same
-project context. Not a runtime. Not an AI agent. Think `.editorconfig`
-but for AI tools.
+**What is MultiModel Dev OS?**
+A set of markdown templates and directory structures that allow multiple AI coding tools (Codex, Cursor, Claude Code, Gemini, Antigravity, VS Code) to share a single portable AI project context. It acts like `.editorconfig` but for AI assistants.
 
-**Is this an operating system?**
-No. "Dev OS" is a metaphor for the shared operating layer between tools.
-It's just markdown files in your repo.
+**Is this a runtime operating system?**
+No. It is a metaphorical "OS" providing standard files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) to coordinate multiple tools.
 
 **What does "multimodel" mean?**
-Multiple AI models/tools working on the same project.
-Not "multimodal" (multiple input types like text + image).
+Multiple distinct AI coding models/agents (such as Codex, Antigravity, Cursor, and Claude Code) operating sequentially on the exact same workspace branch.
+
+---
 
 ## Setup
 
 **Do I need Node.js?**
 It depends on your installation path:
-* **Yes:** If you run the primary, recommended `npx multimodel-dev-os@latest init` workflow, Node.js is required.
-* **No:** If you run the fallback automated shell installer scripts (`install.sh` or `install.ps1`), they run purely on native bash or PowerShell and download resources directly.
+* **Yes:** If you run the primary, recommended `npx multimodel-dev-os@latest init` workflow.
+* **No:** If you run the fallback bash (`install.sh`) or PowerShell (`install.ps1`) one-liners.
 
 **Why not just write a single manual AGENTS.md myself?**
-While you can write a raw markdown instruction file manually, `multimodel-dev-os` offers a standardized development environment:
-1. **Automated Bridging:** Rather than copying and pasting rules into `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, and `.gemini/settings.json`, our adapters dynamically references your root source of truth.
-2. **Standardized Context Segregation:** Separates concerns cleanly (`MEMORY.md` for architectural context, `TASKS.md` for task state tracking, `RUNBOOK.md` for incident response, and `.ai/` for skills and prompts).
-3. **Structured Verification:** Pre-packaged CLI and verification scripts test and assert the structural completeness of your rules.
-4. **Token Savings:** Seamlessly switches into Caveman Mode to slash token footprints by **~79%** for smaller models.
-
-**Can I use just one AI tool?**
-Yes. Use a single adapter. The multi-agent features are optional.
+While you can write a raw markdown file, MultiModel Dev OS offers:
+1. **Automated Bridging:** Adapters dynamically map your root source to Cursor, Claude, and Gemini native rules.
+2. **Context Budgets:** Toggle **Caveman Mode** to slash prompt rules overhead by **~79%**.
+3. **Structured Verification:** Built-in CLI commands validate workspace specifications instantly.
 
-**Which files are required?**
-At minimum: `AGENTS.md`. Everything else is optional.
-The installer creates the full structure, but you can delete what you don't need.
+---
 
 ## Adapters
 
 **Do I copy adapter files to my project root?**
 Yes, for tools that auto-detect specific files:
-- Cursor → copy `.cursorrules` to root
-- Claude → copy `CLAUDE.md` to root
-- VS Code → copy `.vscode/` to root
-
-**My tool isn't listed. Can I add one?**
-Yes. See [docs/adapters.md](adapters.md) for the guide. PRs welcome.
+- Cursor → `.cursorrules`
+- Claude Code → `CLAUDE.md`
+- VS Code → `.vscode/settings.json`
 
-**Will adapters break if a tool changes its config format?**
-Possibly. Adapters are community-maintained. File an issue if you
-notice an adapter is outdated.
+---
 
 ## Caveman Mode
 
 **When should I use Caveman Mode?**
-When your context window is tight, your model is small, or you're
-optimizing for API cost. It cuts ~79% of tokens.
+**Best for**: Context optimization for AI coding when you are using compact context budget windows, smaller models, or want to save money on API bill parameters.
 
-**Can I mix standard and caveman files?**
-Yes. Each file is independent. You could have a standard `AGENTS.md`
-and a caveman `TASKS.md`.
-
-## Orchestrator
-
-**Does the orchestrator run agents automatically?**
-No, not in v0.1. It's a protocol spec — conventions for how agents
-should coordinate. Runtime orchestration is planned for v0.2+.
-
-**Do I need the orchestrator for single-agent workflows?**
-No. The orchestrator is only relevant when multiple agents work
-on the same codebase.
+---
 
 ## Diagnostics & Validation
 
 **What is the difference between `validate` and `doctor`?**
-* **`validate`** is strict and verifies that your workspace strictly complies with the multimodel-dev-os directory schema. It checks for the existence of core files/directories and ensures enabled adapter rule references are not broken. If any checks fail, it exits with an error status (exit code 1).
-* **`doctor`** is advisory. It inspects compatibility constraints, warning you about potential context bloat (e.g. missing `.gitignore` files or non-ignored build directories) or active rules missing matching files. It reports warnings without blocking execution.
+* **`validate`** is strict and verifies compliance with the directory schema.
+* **`doctor`** is advisory and warns you about large unignored directories or empty placeholders.
+
+---
+
+## Protocol & Migration
 
-**How do I view available scaffolding templates?**
-You can use `node bin/multimodel-dev-os.js templates` (or `list-templates`) to view all available tech stacks and detailed blueprints, or `show-template <name>` to inspect a specific template's specifications.
+**Is the MultiModel Dev OS protocol stable?**
+Yes. As of version `v1.1.0`, the core specifications are officially frozen and backward-compatible. This ensures that any codebase prepared using `v1.1.0` will operate seamlessly inside future `1.x` ecosystems.
 
+Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.