multimodel-dev-os 1.0.0 → 2.0.0

package/docs/mobile-android.md

@@ -0,0 +1,75 @@
+# Production Mobile Android Setup (Expo + React Native)
+
+MultiModel Dev OS v1.2.0 adds a dedicated production-ready template for mobile Android clients under [examples/expo-react-native-android/](file:///F:/multimodel-dev-os/examples/expo-react-native-android/).
+
+This guide describes how to customize and deploy this template using Expo EAS Build pipelines.
+
+---
+
+## 1. Directory Structure
+
+The `expo-react-native-android` template structures standard mobile files:
+
+* **`app.json`**: Global metadata mapping package namespaces (`com.multimodel.devos`), app icons, orientation constraints, and runtime permissions.
+* **`eas.json`**: Configuration profile mapping for Expo EAS Build pipelines.
+* **`app.config.ts`**: TypeScript config dynamically mapping environment profiles.
+* **`src/services/api-client.ts`**: Standardized fetch client with connection timeout limits.
+* **`src/lib/secure-storage.ts`**: Storage wrapper interface utilizing `expo-secure-store`.
+* **`src/app/_layout.tsx`**: Expo Router root Layout component displaying loading/offline network states.
+* **`jest.config.js`**: Jest configuration setting up native Expo mocks and test suites.
+
+---
+
+## 2. Environment Configurations
+
+EAS Build uses the `APP_ENV` environment variable to direct endpoint paths:
+
+| Profile / APP_ENV | Target API BaseUrl | Distribution Method |
+| :--- | :--- | :--- |
+| `development` | `http://10.0.2.2:3000/api` | Expo Go Dev Client |
+| `staging` | `https://staging-api.multimodel.dev` | Internal testing APK |
+| `production` | `https://api.multimodel.dev` | Play Store AAB Bundle |
+
+---
+
+## 3. Build & Submission Command Lines
+
+To trigger builds on EAS servers:
+```bash
+# Build development client APK
+eas build --profile development --platform android
+
+# Build staging preview APK
+eas build --profile preview --platform android
+
+# Build production bundle AAB
+eas build --profile production --platform android
+```
+
+---
+
+## 4. Mobile Quality Assurance (QA) Checklist
+
+To verify app compliance before distribution:
+1. **No committed secrets**: Do not write keys inside `app.config.ts` or `app.json`. Use EAS secrets vault.
+2. **Offline Handlers**: Verify layout redirects properly to connection failure views when network states drop.
+3. **Session Encryptions**: Confirm tokens are stored exclusively inside `secure-storage.ts` (`expo-secure-store`), not `AsyncStorage`.
+
+---
+
+## 5. Android & Expo Template FAQ
+
+### Q: Why does the API call fail in the Android Emulator when using localhost?
+In Android emulators, `localhost` or `127.0.0.1` refers to the emulator's loopback interface itself, not your host computer. The host computer's loopback interface is mapped to the special IP address `10.0.2.2`. The `api-client` automatically resolves this default when `APP_ENV` is set to `development`.
+
+### Q: How do I handle EAS credentials errors during eas build?
+EAS credentials errors usually occur when the `projectId` or `owner` in `app.config.ts` does not match your Expo Developer account. To resolve this:
+1. Log in to your Expo account via command line: `npx eas login`.
+2. Configure your own Expo username in `app.config.ts` under `owner`.
+3. Generate a project ID on your Expo dashboard and update the `projectId` placeholder in `app.config.ts`.
+
+### Q: How do I test the API client's retry mechanism locally?
+You can toggle offline mock responses by setting `useMockData: true` inside [api-client.ts](file:///f:/multimodel-dev-os/examples/expo-react-native-android/src/services/api-client.ts) constructor, or you can temporarily disconnect your development server to watch the console log warning attempts:
+`[ApiClient] Attempt 1 failed: fetch failed. Retrying...`
+The client will automatically retry up to 3 times before returning a `Max retries exceeded` error.
+

package/docs/model-compatibility.md

@@ -0,0 +1,65 @@
+# Model Compatibility & Capabilities Registry
+
+MultiModel Dev OS v1.2.0 introduces a centralized, registry-driven configuration layer to specify target AI model behaviors, token windows, cost metrics, and specialized capabilities.
+
+This ensures that agentic coding workflows are future-proof, allowing developers to route prompts to optimal engines without updating core codebase packages.
+
+---
+
+## Central Registry File
+The core system registry resides in [.ai/models/registry.yaml](file:///F:/multimodel-dev-os/.ai/models/registry.yaml):
+
+```yaml
+models:
+  claude-sonnet-latest:
+    provider: anthropic
+    alias: claude-3-5-sonnet
+    official_id: claude-3-5-sonnet-20241022
+    context_window: 200000
+    tiers:
+      cost: high
+      speed: medium
+      reasoning: premium
+      coding: premium
+    capabilities:
+      vision: true
+      tool_use: true
+
+  gemini-flash-latest:
+    provider: google
+    alias: gemini-1.5-flash
+    official_id: gemini-1.5-flash-001
+    context_window: 1048576
+    tiers:
+      cost: low
+      speed: fast
+      reasoning: medium
+      coding: medium
+    capabilities:
+      vision: true
+      tool_use: true
+```
+
+---
+
+## Schema Attributes Reference
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `provider` | String | Matches identifier in [providers.yaml](file:///F:/multimodel-dev-os/.ai/models/providers.yaml). |
+| `alias` | String | Common developer name or shortcut (e.g. `gpt-4o`). |
+| `official_id` | String | Precise API endpoint identifier string. |
+| `context_window` | Integer | Maximum token capacity of the model. |
+| `tiers` | Object | Speed, cost, reasoning, and coding classifications (low/medium/high/premium). |
+| `capabilities` | Object | Toggles indicating `vision` or `tool_use` (function calling) support. |
+
+---
+
+## Dynamic Placeholders
+If a model name is future-facing or unverified, it is registered as a configurable placeholder or alias:
+* `gpt-coding-latest`
+* `deepseek-coder-latest`
+* `local-coder-model`
+* `open-weight-reasoner`
+
+This strategy prevents hardcoding unverified API configurations and allows instant mapping via localized parameters.

package/docs/model-routing.md

@@ -0,0 +1,45 @@
+# Multi-Model Routing & Presets Guide
+
+To optimize context budgets and API costs, MultiModel Dev OS separates agent roles and routes tasks to specialized model families based on their complexity.
+
+---
+
+## Central Routing Configuration
+Routing policies and presets reside in [.ai/models/routing-presets.yaml](file:///F:/multimodel-dev-os/.ai/models/routing-presets.yaml):
+
+```yaml
+presets:
+  planning:
+    primary: claude-sonnet-latest
+    fallback: gemini-pro-latest
+  debugging:
+    primary: deepseek-coder-latest
+    fallback: gemini-flash-latest
+```
+
+---
+
+## Standard Presets Matrix
+
+### 1. Planning (`planning` Preset)
+* **Goal**: Architect implementation files, outline tasks checklists, and coordinate directory hierarchies.
+* **Primary Target**: Premium reasoning models (e.g. `claude-sonnet-latest`, `gemini-pro-latest`).
+* **Requirements**: Comprehensive context processing, high structured-output obedience.
+
+### 2. Code Writing (`coding` Preset)
+* **Goal**: Generate precise diffs and write modular, functional scripts.
+* **Primary Target**: Fast, high-accuracy coding models (e.g. `deepseek-coder-latest`, `claude-sonnet-latest`).
+* **Requirements**: Coding tier premium classification.
+
+### 3. Quick Fixes & Verification (`verification` Preset)
+* **Goal**: Run unit tests, verify CLI diagnostic outputs, and perform style compliance checks.
+* **Primary Target**: Low-cost, fast inference models (e.g. `gemini-flash-latest`).
+* **Requirements**: Speed tier fast classification, tool calling support.
+
+---
+
+## Fallback Routing Logic
+When executing commands via terminal agents or local adapters:
+1. Verify target provider key exists (e.g. `GEMINI_API_KEY`).
+2. If primary model endpoint fails, check `capabilities.fallback` mapping in `registry.yaml`.
+3. Route queries automatically to fallback options or fallback to `local-coder-model`.

package/docs/npm-publishing.md

@@ -72,3 +72,30 @@ Execute these validation actions strictly in sequence before triggering a releas
     ```bash
     npm deprecate multimodel-dev-os@0.3.0 "Critical bug found, please use v0.3.1 instead."
     ```
+
+---
+
+## 4. Prepublish Safety Guard (v2.0.0 Stable)
+
+> [!IMPORTANT]
+> **v2.0.0 is the active stable release.** NPM publishing is no longer paused.
+
+### Source vs. Registry Strategy
+* **GitHub main branch (Source)**: Contains the current stable `v2.0.0` codebase.
+* **npm latest (Registry)**: Pulled and installed globally or via npx.
+
+### Prepublish Safety Guard
+To prevent accidental `npm publish` executions on developer environments, a local validation script has been added to package hooks. If you run `npm publish`, it is blocked by default.
+
+To bypass this check during the approved `v2.0.0` release window:
+1. Ensure the version in `package.json` starts with `2.` (e.g. `2.0.0`).
+2. Run publication with the override env variable:
+   ```powershell
+   # PowerShell
+   $env:MMDO_ALLOW_PUBLISH="true"
+   npm publish --access public
+   ```
+   ```bash
+   # Bash
+   MMDO_ALLOW_PUBLISH=true npm publish --access public
+   ```

package/docs/package-safety.md

@@ -0,0 +1,29 @@
+# Package Safety and Security Hygiene
+
+This document defines strict safety guidelines for the MultiModel Dev OS workspace.
+
+## Excluded Items List
+
+To prevent security compromises, credential exposure, or prompt bloating, the following files must **never** be included in git pushes or packaged in NPM releases:
+
+1. **Local Credentials & API Keys:**
+   * `.npmrc` (specifically containing authentication tokens)
+   * `.env` / `.env.local`
+2. **Build and Cache Artifacts:**
+   * `node_modules/`
+   * `dist/` / `build/`
+   * `docs/.vitepress/dist/`
+   * `docs/.vitepress/cache/`
+3. **Mobile & Android Signing Artifacts:**
+   * `*.keystore` / `*.jks` files
+   * `google-services.json`
+   * `GoogleService-Info.plist`
+   * Signing configuration credentials
+
+## Enforcement
+
+The project release audit scripts strictly enforce these checks:
+```bash
+npm run verify
+```
+Any violation will cause verification and build pipelines to fail immediately.

package/docs/protocol.md

@@ -1,6 +1,8 @@
-# MultiModel Dev OS Protocol Specification
+# MultiModel Dev OS Protocol Specification (v1.1.0)
 
-This document defines the official, stable architectural protocol and design contracts for `multimodel-dev-os`, preparing the codebase for the v1.0.0 freeze.
+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.
 
 ---
 
@@ -27,12 +29,12 @@ The protocol is divided into three distinct decoupled layers to guarantee portab
 
 ---
 
-## 2. Stability Matrix (v1.0.0 Freeze)
+## 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.0:
+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.
@@ -52,3 +54,5 @@ All compliant MultiModel Dev OS CLIs must strictly support the following executi
 - **`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/provider-strategy.md

@@ -0,0 +1,44 @@
+# Provider Strategy & API Keys Reference
+
+MultiModel Dev OS supports multi-vendor API routing by centralizing provider properties, endpoints, and credentials reference schemas.
+
+---
+
+## Provider Registry Configuration
+Configure base URLs and API environment variables in [.ai/models/providers.yaml](file:///F:/multimodel-dev-os/.ai/models/providers.yaml):
+
+```yaml
+providers:
+  anthropic:
+    name: "Anthropic"
+    api_endpoint: "https://api.anthropic.com/v1"
+    env_key: "ANTHROPIC_API_KEY"
+    default_headers:
+      "anthropic-version": "2023-06-01"
+
+  google:
+    name: "Google Gemini"
+    api_endpoint: "https://generativelanguage.googleapis.com/v1beta"
+    env_key: "GEMINI_API_KEY"
+
+  openai:
+    name: "OpenAI"
+    api_endpoint: "https://api.openai.com/v1"
+    env_key: "OPENAI_API_KEY"
+```
+
+---
+
+## API Key Security Rules
+
+To guarantee credential safety during agentic loops:
+1. **Never commit raw keys**: Add `.env` and `.env.local` files to `.gitignore` to prevent committing secrets to version control.
+2. **Centralized Environment Variables**: Centralize keys inside local shell environments or local `.env` configs.
+3. **No hardcoded defaults**: The default `providers.yaml` refers only to standard environment variable keys (e.g. `ANTHROPIC_API_KEY`), never API secrets.
+
+---
+
+## custom endpoint routing (e.g. proxy/gateways)
+For companies routing traffic through centralized proxy interfaces (such as OpenRouter, Cloudflare AI Gateway, or local mocks):
+* Edit `.ai/models/providers.yaml` and update the `api_endpoint` parameter of the targeted provider.
+* Update `default_headers` to inject custom authentication tokens or routing parameters required by the gateway.

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,82 @@
+# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v2.0.0 Stable Release)
+
+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          │
+│ (And central registries under .ai/models/ & .ai/adps/) │
+└──────────────────────────┬─────────────────────────────┘
+                           │ 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/ • etc.  │
+└────────────────────────────────────────────────────────┘
+```
+
+### 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. Supports `--template`, `--caveman`, `--adapter`, and dynamic registries mapping.
+- **`verify`**: Automated release script that checks structure integrity.
+- **`templates`**: Lists built-in template profiles (supports overrides via `--registry <path>`).
+- **`validate`**: Strict Quality Gate checking the layout rules on disk (supports `--all-registries`).
+- **`validate-template`**: Scans a template registry entry and source directory structure for completeness.
+- **`validate-adapter`**: Audits an adapter config file and directory setup compliance.
+- **`validate-skill`**: Checks a custom skill file against standard Markdown headers.
+- **`doctor`**: Advisory checkup auditing ignored folders and token footprint (supports `--tokens` and `--release`).
+
+---
+
+## 3. Registries & Mappings
+
+### Model Compatibility Registry
+Central registry configuration resides in `.ai/models/`:
+* `registry.yaml`: Maps model aliases to official provider IDs, context windows, and tiers.
+* `providers.yaml`: API base urls and environment variables keys.
+* `routing-presets.yaml`: Multi-model presets for task-oriented routing.
+* `local-models.yaml`: Endpoint mappings for offline model engines (Ollama, Llama.cpp).
+
+### IDE/Agent Adapters Registry
+Central adapter rules mapped under `.ai/adapters/registry.yaml`:
+* Targets files like `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`, `.clinerules`, `.aider.conf.yml`, `.windsurfrules`, `.continue/config.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
+- **v2.0.0 Roadmap**: https://rizvee.github.io/multimodel-dev-os/v2-roadmap
+- **Release Policies**: https://rizvee.github.io/multimodel-dev-os/release-policy
+- **Upgrade Playbook**: https://rizvee.github.io/multimodel-dev-os/migration-guide
+- **Model Compatibility**: https://rizvee.github.io/multimodel-dev-os/model-compatibility

package/docs/public/llms.txt

@@ -0,0 +1,36 @@
+# MultiModel Dev OS (v2.0.0 Stable Release)
+
+Portable, vendor-neutral workspace configuration standard for multi-agent AI pair-programming workflows.
+
+## Fast Setup (Stable npm @latest)
+```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`)
+- **Continue** (`.continue/config.json`)
+- **Cline / Roo Code** (`.clinerules`)
+- **Aider** (`.aider.conf.yml`)
+- **Windsurf** (`.windsurfrules`)
+- **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 Package**: https://www.npmjs.com/package/multimodel-dev-os
+- **Stable Protocol Specification**: https://rizvee.github.io/multimodel-dev-os/stable-protocol
+- **Model Compatibility & Routing Guide**: https://rizvee.github.io/multimodel-dev-os/model-compatibility
+- **Cost/Context Optimization Playbook**: https://rizvee.github.io/multimodel-dev-os/cost-optimization
+
+## 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)
+- `expo-react-native-android` (Production Android delivery with EAS Build)
+- `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,12 +1,14 @@
-# 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.
 
 ---
 
-## Option A: NPX Scaffolding (Recommended)
+## Option A: NPX Scaffolding (Stable Packages)
 
-Initialize any project immediately without local clones using our public npm registry:
+Initialize any project instantly using our public npm registry. Note that this pulls the latest stable npm-published release (`v2.0.0`):
 
 ```bash
 # Standard interactive initialization in the current directory
@@ -23,7 +25,7 @@ npx multimodel-dev-os@latest init --dry-run
 
 ## Option B: Fallback One-Line Scripts
 
-If you choose to run installation scripts directly:
+If you choose to run installation scripts directly (fetches stable files):
 
 **macOS / Linux / WSL (bash):**
 ```bash
@@ -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
@@ -47,14 +49,15 @@ curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scrip
 
 ---
 
-## Option D: Node.js Local Scaffolding CLI
+## Option D: Node.js Local Scaffolding CLI (Direct Run)
+
+If you prefer to run directly from cloned source without global installation:
 
-For offline execution or customized packaging within a cloned workspace:
 1. Clone this repository locally:
    ```bash
    git clone https://github.com/rizvee/multimodel-dev-os.git
    ```
-2. Run the CLI directly using the absolute target path:
+2. Run the CLI directly from the cloned repository source:
    ```bash
    node bin/multimodel-dev-os.js init --target /path/to/your-project --template nextjs-saas --adapter cursor
    ```
@@ -63,13 +66,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 +90,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/registry-contribution.md

@@ -0,0 +1,20 @@
+# Registry Contribution Workflow
+
+This document describes how to propose and contribute new models, adapters, and templates.
+
+## Contribution Flow
+
+1. **Local Authoring:** Follow the respective authoring guides:
+   * [Custom IDE Adapter Authoring](adapter-authoring.md)
+   * [Custom Template Authoring](template-authoring.md)
+   * [Skill Authoring](skill-authoring.md)
+2. **Local Validation:** Use validation CLI commands to ensure structural compliance:
+   * `node bin/multimodel-dev-os.js validate-template <name>`
+   * `node bin/multimodel-dev-os.js validate-adapter <name>`
+   * `node bin/multimodel-dev-os.js validate-skill <name>`
+3. **Registry Addition:** Insert your metadata records into:
+   * `.ai/templates/registry.yaml` for templates.
+   * `.ai/adapters/registry.yaml` for adapters.
+   * `.ai/models/registry.yaml` for models.
+4. **Verification suite:** Run `npm run verify` to ensure the release audit checks pass cleanly.
+5. **Submit PR:** Submit your changes via a GitHub Pull Request to `https://github.com/rizvee/multimodel-dev-os`.