multimodel-dev-os 1.1.0 → 2.0.1

package/docs/.vitepress/config.js

@@ -32,7 +32,7 @@ export default {
         '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',
+        'softwareVersion': '2.0.1',
         'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
       })
     ]
@@ -62,10 +62,44 @@ export default {
           { text: 'Stable Protocol Specification', link: '/stable-protocol' },
           { text: 'Adapter Compatibility', link: '/compatibility' },
           { text: 'Upgrades & Migration', link: '/migration-guide' },
+          { text: 'v2 Migration Guide', link: '/v2-migration' },
+          { text: 'v2 Release Checklist', link: '/v2-release-checklist' },
+          { text: 'Package Safety', link: '/package-safety' },
           { text: 'Templates QA Blueprint', link: '/template-qa' },
           { text: 'v1.0.0 Readiness Checklist', link: '/v1-readiness' }
         ]
       },
+      {
+        text: 'Model Compatibility Layer',
+        items: [
+          { text: 'Model Capabilities Registry', link: '/model-compatibility' },
+          { text: 'Model Routing & Presets', link: '/model-routing' },
+          { text: 'Local & Offline Models', link: '/local-models' },
+          { text: 'API Provider Strategy', link: '/provider-strategy' }
+        ]
+      },
+      {
+        text: 'Agent & IDE Extensions',
+        items: [
+          { text: 'Agent Compatibility Mappings', link: '/agent-compatibility' },
+          { text: 'Custom Adapters Guide', link: '/adapter-authoring' },
+          { text: 'Template Authoring Guide', link: '/template-authoring' },
+          { text: 'Skill Authoring Guide', link: '/skill-authoring' },
+          { text: 'Registry Contribution Guide', link: '/registry-contribution' }
+        ]
+      },
+      {
+        text: 'Mobile Integration & Delivery',
+        items: [
+          { text: 'Expo Android Delivery', link: '/mobile-android' }
+        ]
+      },
+      {
+        text: 'Token Cost Optimization',
+        items: [
+          { text: 'Token Budgets & Optimization', link: '/token-optimization' }
+        ]
+      },
       {
         text: 'Case Studies & Playbooks',
         items: [
@@ -108,6 +142,7 @@ export default {
           { text: 'Public Launch Checklist', link: '/launch-checklist' },
           { text: 'Release Playbook Template', link: '/release-template' },
           { text: 'CLI Roadmap', link: '/cli-roadmap' },
+          { text: 'v2.0.0 Roadmap', link: '/v2-roadmap' },
           { text: 'NPM Publishing Runbook', link: '/npm-publishing' },
           { text: 'Pre-flight Release Testing', link: '/testing-v0.2' },
           { text: 'Release Policy', link: '/release-policy' },

package/docs/adapter-authoring.md

@@ -0,0 +1,46 @@
+# Custom IDE Adapter Authoring Guide
+
+MultiModel Dev OS is fully extensible. Developers and teams can build custom adapters to route protocol directives to new IDE interfaces, command-line coding agents, or company-proprietary AI environments.
+
+---
+
+## Authoring Workflow
+
+To construct a new adapter:
+
+### 1. Register the Adapter Metadata
+Open [.ai/adapters/registry.yaml](file:///F:/multimodel-dev-os/.ai/adapters/registry.yaml) and declare the adapter properties:
+```yaml
+adapters:
+  my-custom-agent:
+    name: "My Custom Agent"
+    config_file: ".mycustomrules"
+    type: "coding-agent"
+    docs: "docs/adapters/my-custom-agent.md"
+```
+
+### 2. Scaffold the Adapter Assets
+Create the adapter assets directory under `adapters/my-custom-agent/`:
+* **`adapters/my-custom-agent/setup.md`**: Guide for developers enabling this adapter.
+* **`adapters/my-custom-agent/.mycustomrules`**: Rule boilerplate template which contains variables (e.g. system prompts or build scripts references) to be copied to project root during CLI initialization.
+
+### 3. Register in CLI
+Open `bin/multimodel-dev-os.js` and extend the `handleInit` mapping:
+```javascript
+} else if (adapter === 'my-custom-agent') {
+  const srcFile = join(sourceRoot, 'adapters/my-custom-agent/.mycustomrules');
+  const destFile = join(options.target, '.mycustomrules');
+  if (existsSync(srcFile)) {
+    writeFileSync(destFile, readFileSync(srcFile));
+  }
+}
+```
+
+### 4. Verify Compliance
+Extend `scripts/verify.js` to ensure the new files are verified:
+```javascript
+checkFile('adapters/my-custom-agent/setup.md');
+checkFile('adapters/my-custom-agent/.mycustomrules');
+```
+
+Run `npm run verify` to confirm all assertions pass cleanly.

package/docs/agent-compatibility.md

@@ -0,0 +1,51 @@
+# Coding Agent & IDE Adapter Compatibility
+
+MultiModel Dev OS acts as an interoperability layer across modern developer agents, terminal assistants, and IDE extensions.
+
+---
+
+## Agent Registry Mapping
+Compatible configurations and destination files are detailed in [.ai/adapters/registry.yaml](file:///F:/multimodel-dev-os/.ai/adapters/registry.yaml):
+
+```yaml
+adapters:
+  continue:
+    name: "Continue"
+    config_file: ".continue/config.json"
+    type: "editor-extension"
+    docs: "docs/adapters.md"
+  cline:
+    name: "Cline"
+    config_file: ".clinerules"
+    type: "coding-agent"
+    docs: "docs/agent-compatibility.md"
+  roo-code:
+    name: "Roo Code"
+    config_file: ".clinerules"
+    type: "coding-agent"
+    docs: "docs/agent-compatibility.md"
+```
+
+---
+
+## Supported Agent Configurations
+
+### 1. Continue
+* **File Target**: `.continue/config.json`
+* **Workflow**: Integrates custom system prompts and routing matrices into the VS Code / JetBrains sidebar panel.
+
+### 2. Cline / Roo Code
+* **File Target**: `.clinerules`
+* **Workflow**: Feeds strict directory layout schemas and role assignments directly to agent context loops during project scans.
+
+### 3. Aider
+* **File Target**: `.aider.conf.yml`
+* **Workflow**: Centralizes exclude filters, auto-commit actions, and CLI test verification shortcuts.
+
+### 4. Windsurf
+* **File Target**: `.windsurfrules`
+* **Workflow**: Injects development constraints and build commands into the IDE context window.
+
+### 5. OpenHands / Terminal Agents
+* **File Target**: `CLAUDE.md` / `adapters/codex/AGENTS.md`
+* **Workflow**: Standardize shell execution targets and error-handling steps for autonomous agents.

package/docs/cli-roadmap.md

@@ -1,6 +1,6 @@
 # CLI Roadmap
 
-> The zero-dependency CLI utility is fully integrated with `npm` and `npx` in v0.3.0!
+> The zero-dependency CLI utility is fully integrated with `npm` and `npx` in v2.0.0!
 
 ## Current CLI Usage
 
@@ -23,7 +23,7 @@ npx multimodel-dev-os@latest init --force
 npx multimodel-dev-os@latest verify
 ```
 
-Alternatively, you can run the CLI locally within a cloned workspace:
+Alternatively, you can run the CLI directly from cloned source during development:
 ```bash
 node bin/multimodel-dev-os.js init
 node bin/multimodel-dev-os.js verify
@@ -37,28 +37,17 @@ node bin/multimodel-dev-os.js verify
 | `show-template` | Inspect stack specifications of a template | v0.5.0 | ✅ Completed |
 | `doctor` | Advisory checkup of workspace compatibility | v0.5.0 | ✅ Completed |
 | `validate` | Strict directory schema compliance checks | v0.5.0 | ✅ Completed |
-| `sync` | Regenerate adapter files from root AGENTS.md | v0.6.0 | 📋 Planned |
-| `add-adapter` | Add a new adapter to the project | v0.6.0 | 📋 Planned |
+| `models` | List configured model registry entries | v2.0.0 | ✅ Completed |
+| `show-model` | Inspect settings for a model registry entry | v2.0.0 | ✅ Completed |
+| `providers` | List configured model registry providers | v2.0.0 | ✅ Completed |
+| `route-model`| Route a target prompt based on presets | v2.0.0 | ✅ Completed |
+| `adapters` | List configured adapter registry entries | v2.0.0 | ✅ Completed |
+| `show-adapter`| Inspect settings for an adapter registry entry | v2.0.0 | ✅ Completed |
+| `skills` | List configured skill registry entries | v2.0.0 | ✅ Completed |
+| `show-skill` | Inspect settings for a skill registry entry | v2.0.0 | ✅ Completed |
 
-## Requirements Completed in v0.5.0
+## CLI v2.0.0 Stabilization & Beyond
 
-- [x] Implemented strict `validate` CLI command for structural directory validation.
-- [x] Implemented advisory `doctor` command for project compatibility warnings.
-- [x] Implemented `templates` and `show-template` commands for built-in profiles inspection.
-- [x] Upgraded all 5 built-in template profiles with practical real-world contents.
-- [x] Implemented dynamic context budgetary constraints and skills validation.
-- [x] Preserved zero-dependency pure Node CLI implementations.
+The `v2.0.0` stabilization milestone was completed successfully, hardening registries configurations, custom skill checking tools, and token size overrides. Any future subcommands or adapter sync mechanisms will follow SemVer guidelines to ensure full backward compatibility.
 
-## Future Releases (v0.6.0+)
-
-* **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/faq.md

@@ -62,6 +62,6 @@ Yes, for tools that auto-detect specific files:
 ## Protocol & Migration
 
 **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.
+Yes. As of version `v1.1.0`, the core specifications are officially frozen and backward-compatible. This ensures that codebases prepared using `v1.1.0` or later operate seamlessly inside all `1.x` and `2.x` ecosystems.
 
 Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.

package/docs/final-launch.md

@@ -1,15 +1,16 @@
-# Final Launch Guidelines (v1.1.0)
+# Final Launch Guidelines (v2.0.0 Target)
 
 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.
+> [!IMPORTANT]
+> **v2.0.0 is the active stable release.** NPM publishing is no longer paused. All Template Galaxy and Model Compatibility features are now available on the public registry.
 
 ---
 
 ## 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`.
+Prior to pushing files or preparing a release, ensure that:
+- The exact target version starts with `2.` (e.g. `2.0.0`) in `package.json` for publishing, or remains at `1.2.0` for local development.
 - The cross-platform verify script completes cleanly:
   ```bash
   npm run verify

package/docs/index.md

@@ -16,8 +16,8 @@ hero:
       text: Stable Protocol Specs
       link: /stable-protocol
     - theme: alt
-      text: v1.0 Readiness
-      link: /v1-readiness
+      text: v2 Release Checklist
+      link: /v2-release-checklist
     - theme: alt
       text: View Case Studies
       link: /case-studies/
@@ -141,9 +141,9 @@ MultiModel Dev OS maps repository context directly to all major developer tools
     <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 href="/v2-release-checklist" class="card-item">
+    <div class="card-title">🏁 v2 Release Checklist</div>
+    <div class="card-desc">Audit repository compliance with the strict v2 release quality gates.</div>
   </a>
   <a href="/llms.txt" class="card-item" target="_blank">
     <div class="card-title">🤖 AI Discovery (llms.txt)</div>

package/docs/local-models.md

@@ -0,0 +1,48 @@
+# Local & Open-Weight Offline Models Guide
+
+MultiModel Dev OS supports offline development workflows utilizing open-weight models running on local developer hardware (via Ollama, Llama.cpp, or vLLM).
+
+---
+
+## Local Models Configuration
+Local model bindings are defined in [.ai/models/local-models.yaml](file:///F:/multimodel-dev-os/.ai/models/local-models.yaml):
+
+```yaml
+local_engines:
+  ollama:
+    base_url: "http://localhost:11434/v1"
+    models:
+      - alias: local-coder-model
+        official_id: qwen2.5-coder:7b
+      - alias: open-weight-reasoner
+        official_id: deepseek-r1:8b
+```
+
+---
+
+## Local Setup Instructions
+
+### 1. Using Ollama
+To spin up a local model runner and pull target coding weights:
+```bash
+# Install Ollama and run server
+ollama run qwen2.5-coder:7b
+
+# In another terminal tab, run MultiModel Dev OS verify
+node bin/multimodel-dev-os.js verify
+```
+
+### 2. Local fallback routing
+To configure local fallback when remote APIs are unavailable, set your primary model map to point to the local coder model:
+```yaml
+# .ai/context/model-map.md
+Planning: open-weight-reasoner
+Execution: local-coder-model
+```
+
+---
+
+## Benefits & Optimization
+* **Zero API Cost**: Local model queries carry no token charges.
+* **Privacy Compliance**: No code snippets or workspace context files leave the local host machine.
+* **Offline-Ready**: Develop and build applications on flights or remote zones with zero internet dependencies.

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

@@ -12,13 +12,13 @@ Before publishing, always test the built package locally by compiling a compress
    ```bash
    npm pack
    ```
-   This creates a file named like `multimodel-dev-os-0.3.0.tgz` in your directory root.
+   This creates a file named like `multimodel-dev-os-2.0.1.tgz` in your directory root.
 
 2. **Verify bundle contents:**
    Create an empty temporary workspace, extract the tarball, and confirm that only required scaffold folders are included (no `.github/`, test configurations, or local system files):
    ```bash
    mkdir -p /tmp/package-test && cd /tmp/package-test
-   tar -xzf /path/to/multimodel-dev-os-0.3.0.tgz
+   tar -xzf /path/to/multimodel-dev-os-2.0.1.tgz
    ls -la package/
    ```
 
@@ -61,14 +61,41 @@ Execute these validation actions strictly in sequence before triggering a releas
 ## 3. Versioning & Rollback Strategy
 
 * **Semantic Versioning (SemVer) Discipline:**
-  * **Patch Release (e.g. 0.3.1):** Backward-compatible bug fixes or documentation updates.
-  * **Minor Release (e.g. 0.4.0):** Backward-compatible new features (like new adapter sync mechanisms).
-  * **Major Release (e.g. 1.0.0):** Breaking changes to core specification files.
+   * **Patch Release (e.g. 2.0.1):** Backward-compatible bug fixes or documentation updates.
+   * **Minor Release (e.g. 2.1.0):** Backward-compatible new features (like new adapter sync mechanisms).
+   * **Major Release (e.g. 3.0.0):** Breaking changes to core specification files.
 
 * **Rollback & Deprecation Guidelines:**
-  * Since published versions cannot be republished or overwritten, **never unpublish** unless absolutely necessary.
-  * If a critical bug is discovered, immediately publish a new patch version (e.g. `v0.3.1`).
-  * If a version is broken, flag it as deprecated to inform downstream installers:
-    ```bash
-    npm deprecate multimodel-dev-os@0.3.0 "Critical bug found, please use v0.3.1 instead."
-    ```
+   * Since published versions cannot be republished or overwritten, **never unpublish** unless absolutely necessary.
+   * If a critical bug is discovered, immediately publish a new patch version (e.g. `v2.0.1`).
+   * If a version is broken, flag it as deprecated to inform downstream installers:
+     ```bash
+     npm deprecate multimodel-dev-os@2.0.0 "Critical bug found, please use v2.0.1 instead."
+     ```
+
+---
+
+## 4. Prepublish Safety Guard (v2.0.1 Stable)
+
+> [!IMPORTANT]
+> **v2.0.1 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.1` 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 approved release windows:
+1. Ensure the version in `package.json` starts with `2.` (e.g. `2.0.1`).
+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/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.