multimodel-dev-os 2.0.1 → 2.8.0

package/docs/distribution.md

@@ -0,0 +1,195 @@
+# Distribution & Release Guide
+
+How to distribute, verify, and publish MultiModel Dev OS releases.
+
+---
+
+## Installation Methods
+
+### NPX (Recommended)
+
+```bash
+# Initialize a new workspace
+npx multimodel-dev-os@latest init
+
+# Onboard an existing project
+npx multimodel-dev-os@latest onboard analyze
+```
+
+### Global Install
+
+```bash
+npm install -g multimodel-dev-os
+multimodel-dev-os init
+```
+
+### Fallback Scripts
+
+**macOS / Linux / WSL:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main/scripts/install.ps1 | iex
+```
+
+---
+
+## Pre-Release Checklist
+
+Before every release, run this complete verification sequence:
+
+### 1. Version Bump
+
+Update version strings in all 7 locations:
+
+| File | Field |
+|------|-------|
+| `package.json` | `version` |
+| `package-lock.json` | `version` (2 occurrences) |
+| `scripts/install.sh` | `VERSION` |
+| `scripts/install.ps1` | `$Version` |
+| `docs/.vitepress/config.js` | `softwareVersion` in JSON-LD |
+| `docs/public/llms.txt` | Title version |
+| `docs/public/llms-full.txt` | Title version |
+
+### 2. Changelog Entry
+
+Add a new section to `CHANGELOG.md` following the Keep a Changelog format.
+
+### 3. Verification Suite
+
+```bash
+# Run 214+ structural assertions
+npm run verify
+
+# Build docs to catch broken links
+npm run docs:build
+
+# Dry-run the npm package
+npm pack --dry-run
+
+# Verify CLI version
+node bin/multimodel-dev-os.js --help
+
+# Release doctor
+node bin/multimodel-dev-os.js doctor --release
+```
+
+**Expected results:**
+- `verify`: 213+ pass, 0 fail, 1 expected .npmrc warning
+- `docs:build`: builds without errors
+- `pack --dry-run`: reports correct version in tarball name
+- CLI `--help`: shows correct version
+- `doctor --release`: version alignment passes
+
+### 4. Commit
+
+```bash
+git add .
+git diff --cached --stat
+git commit -m "docs: release vX.Y.Z [description]"
+```
+
+---
+
+## Publishing to npm
+
+> [!WARNING]
+> **Manual publish only.** The `prepublish-guard.js` script blocks accidental publishes. You must explicitly set the environment variable.
+
+```bash
+# Set the publish guard
+export MMDO_ALLOW_PUBLISH=true   # bash
+$env:MMDO_ALLOW_PUBLISH = "true" # PowerShell
+
+# Publish to npm
+npm publish --access public
+```
+
+### Post-Publish Smoke Test
+
+After publishing, verify the package works correctly:
+
+```bash
+# Create a temp directory
+mkdir /tmp/mmdo-smoke && cd /tmp/mmdo-smoke
+
+# Test npx execution
+npx multimodel-dev-os@latest --help
+npx multimodel-dev-os@latest init --dry-run
+
+# Verify version matches
+npx multimodel-dev-os@latest doctor --release
+
+# Cleanup
+cd .. && rm -rf /tmp/mmdo-smoke
+```
+
+---
+
+## Package Hygiene
+
+### What's Included in the Tarball
+
+The `files` field in `package.json` controls what ships:
+
+```
+AGENTS.md, MEMORY.md, TASKS.md, RUNBOOK.md
+.ai/          → Configuration, schemas, registries, templates
+adapters/     → IDE/tool adapter files
+scripts/      → Install scripts, verify scripts
+docs/         → Documentation source (excluding .vitepress/dist/ and cache/)
+examples/     → Template examples
+bin/          → CLI executable
+assets/       → Visual assets
+```
+
+### What's Excluded
+
+- `node_modules/` — dev dependencies only
+- `docs/.vitepress/dist/` — built docs (deployed separately via GitHub Pages)
+- `docs/.vitepress/cache/` — build cache
+- `.ai/intelligence/` runtime files — memory, feedback, proposals
+- `.npmrc` — expected warning in verify suite
+
+### The `.npmrc` Warning
+
+The verify suite reports 1 expected warning about `.npmrc` existing in the package root. This file contains only the registry URL and no credentials. It's flagged as a security best practice reminder. This warning is intentional and does not block publishing.
+
+---
+
+## GitHub Releases
+
+After publishing to npm:
+
+1. Tag the commit: `git tag vX.Y.Z`
+2. Push tags: `git push origin main --tags`
+3. Create a GitHub Release from the tag
+4. Copy the changelog entry as the release body
+5. Verify the GitHub Pages deployment triggered
+
+---
+
+## Prepublish Guard
+
+The [prepublish-guard.js](../scripts/prepublish-guard.js) script runs automatically before `npm publish`. It:
+
+1. Checks for `MMDO_ALLOW_PUBLISH=true` environment variable
+2. If not set, prints a warning and exits with code 1
+3. Prevents accidental publishes from CI or local dev environments
+
+This guard ensures every publish is an intentional, reviewed action.
+
+---
+
+## Version Alignment
+
+The `doctor --release` command verifies version parity across:
+- `package.json`
+- `scripts/install.sh`
+- `scripts/install.ps1`
+
+Any mismatch is reported as a warning. Fix alignment before publishing.

package/docs/faq.md

@@ -1,67 +1,134 @@
-# FAQ: MultiModel Dev OS Questions & Answers
+# FAQ
 
-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.
+Frequently asked questions about MultiModel Dev OS, AI coding agents compatibility, and prompt context optimization.
 
 ---
 
 ## General
 
 **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.
+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. Think of it as `.editorconfig` but for AI assistants.
 
 **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.
+No. It is a workspace configuration standard — standard files (`AGENTS.md`, `MEMORY.md`, `TASKS.md`, `RUNBOOK.md`) and a `.ai/` directory that coordinate multiple tools. There is no background process, no daemon, and no runtime overhead.
 
 **What does "multimodel" mean?**
-Multiple distinct AI coding models/agents (such as Codex, Antigravity, Cursor, and Claude Code) operating sequentially on the exact same workspace branch.
+Multiple distinct AI coding models/agents (like Codex, Cursor, Claude Code, and Gemini) operating on the **same workspace** without context loss or instruction drift.
+
+**How is this different from just writing my own `.cursorrules` or `CLAUDE.md`?**
+Those are tool-specific instruction files. If you use multiple tools, you end up maintaining duplicated rules that quickly drift out of sync. MultiModel Dev OS gives you a **single source of truth** (`AGENTS.md`) and automatically adapts it for each tool. You write rules once, every tool reads them.
+
+---
+
+## Demo Workflows
+
+**How do I run the demo workflows?**
+Our demos are fully self-contained markdown walkthroughs. You can copy the commands directly from the demo pages, run them in your terminal, and observe the output. See the **[Demos Hub](/demos/)** for all available workflows.
+
+**Do the demos make any changes to my system?**
+The demos are designed to run in a safe, isolated, or dry-run configuration. For example, `onboard analyze` is entirely read-only, and onboarding plans and adapter syncs require developer approval before writing files. We also provide clear **Cleanup** sections on every demo page to undo any files created.
 
 ---
 
-## Setup
+## Setup & Installation
 
 **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.
+* **Yes:** If you use the primary `npx multimodel-dev-os@latest init` workflow (recommended).
 * **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 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.
+**Can I use this with an existing project?**
+Yes! The `onboard` command suite is designed specifically for this. It analyzes your project structure, recommends the best template, generates a plan, and applies configs safely with automatic backups:
+```bash
+npx multimodel-dev-os@latest onboard analyze
+npx multimodel-dev-os@latest onboard apply --approved
+```
+
+**Does this overwrite my existing files?**
+Never by default. The CLI audits for conflicts before writing anything. To overwrite existing files, you must explicitly pass `--force`, and the system automatically creates `.bak` backups.
 
 ---
 
-## Adapters
+## Adapters & Tools
 
 **Do I copy adapter files to my project root?**
-Yes, for tools that auto-detect specific files:
-- Cursor → `.cursorrules`
-- Claude Code → `CLAUDE.md`
-- VS Code → `.vscode/settings.json`
+You can do it automatically with the `adapter sync` command:
+```bash
+npx multimodel-dev-os@latest adapter sync all --approved
+```
+Or manually:
+- Cursor → `cp adapters/cursor/.cursorrules .cursorrules`
+- Claude Code → `cp adapters/claude/CLAUDE.md CLAUDE.md`
+- VS Code → `cp -r adapters/vscode/.vscode/ .vscode/`
+
+**Does this work with MCP tools?**
+Yes. MultiModel Dev OS includes a `.ai/registries/tools.yaml` that defines MCP tool integrations (like gcloud, Chrome DevTools). The tool registry maps capabilities dynamically rather than hardcoding tool names.
+
+**What AI models does this support?**
+All of them. The `.ai/models/` directory contains a model registry with capability scores, routing presets, and provider configurations. It supports cloud models (GPT-4, Claude, Gemini), local models (Llama, Ollama), and everything in between. No model is hardcoded — the registry routes tasks based on capability scores.
 
 ---
 
 ## Caveman Mode
 
 **When should I use Caveman Mode?**
-**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.
+Use Caveman Mode when you want to minimize prompt token overhead — ideal for tight API budgets, smaller context windows, or when you want to save money on API calls. It compresses the workspace rules by **~79%** using shorthand declarations.
+
+---
+
+## Intelligence & Safety
+
+**Is this safe? Can it modify my code?**
+MultiModel Dev OS is primarily a **read-only** workspace configuration layer. The only write operations are:
+- `init` / `onboard apply` — creates configuration files (with conflict detection)
+- `memory build` — creates memory index files under `.ai/intelligence/` (gitignored)
+- `improve apply` — applies approved proposals (requires explicit `--approved` flag and passes 12 safety gates)
+
+No command can execute arbitrary shell commands, and destructive operations always require explicit developer approval.
+
+**What are the safety gates?**
+The improvement proposal system enforces 12 strict safety checks including path boundary containment, protected path blocks (`.git/`, `.env`, `node_modules/`), idempotency verification, and mandatory human approval. Every apply action is logged in an append-only audit trail.
+
+---
+
+## TUI & Plugins
+
+**What is the Interactive TUI Dashboard?**
+It is a terminal-based operational menu (`npx multimodel-dev-os dashboard` or `ui`) that allows developers to run diagnostics, sync rules, build memory indexes, and check proposal status in a guided interface. It uses Node.js's native `readline` module for raw-keypress navigation, keeping execution zero-dependency and fast.
+
+**Will the TUI Dashboard hang in CI/CD pipelines?**
+No. The dashboard detects when stdin or stdout is non-interactive. In non-TTY environments, it prints a dry-run list of all options with their equivalent CLI commands and exits immediately, preventing pipelines from stalling.
+
+**How secure is the Declarative Plugin system?**
+Extremely secure. Plugins are strictly configuration-based (YAML manifest files). They cannot run arbitrary bash commands, execute node scripts, download npm packages, or make network calls. File copies are restricted to whitelisted `.ai/` and `adapters/` directories, and blacklists protect files like `.env`, `.git/`, `package.json`, and source code folders. Overwriting existing files requires `--force` and automatically generates backups.
 
 ---
 
 ## Diagnostics & Validation
 
 **What is the difference between `validate` and `doctor`?**
-* **`validate`** is strict and verifies compliance with the directory schema.
-* **`doctor`** is advisory and warns you about large unignored directories or empty placeholders.
+* **`validate`** — Strict compliance gate. Checks if required files exist and adapter configs are structurally correct. Exits with code 1 on failures. Use in CI/CD.
+* **`doctor`** — Advisory audit. Warns about large unignored directories, missing `.gitignore` entries, stale memory indexes, and potential token waste. Non-blocking.
+
+---
+
+## Contributing
+
+**How do I contribute a new adapter?**
+1. Create a directory under `adapters/{tool-name}/`
+2. Add the tool-native instruction files referencing `/AGENTS.md` and `/MEMORY.md`
+3. Add a clear `setup.md` installation guide
+4. Update the adapter registry in `.ai/adapters/registry.yaml`
+5. Submit a PR — see our [Contributing Guidelines](/contributing)
 
 ---
 
 ## 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 codebases prepared using `v1.1.0` or later operate seamlessly inside all `1.x` and `2.x` ecosystems.
+Yes. The core Layer 1 specifications (root contracts and `.ai/` directory structure) are officially frozen and backward-compatible. Codebases prepared using any `v1.x` or `v2.x` release operate seamlessly with the latest version.
+
+**How do I upgrade from an older version?**
+Run `npx multimodel-dev-os@latest init --force` to pull the latest configuration files. Existing files will be backed up automatically. See the [Migration Guide](/migration-guide) for details.
 
-Explore our [Stable Protocol Specification](/stable-protocol) or [Upgrade & Migration Guide](/migration-guide) for details.
+Explore our [Stable Protocol Specification](/stable-protocol) or [CLI Command Reference](/CLI) for more details.

package/docs/feedback-learning.md

@@ -0,0 +1,33 @@
+# Feedback Learning Loop
+
+MultiModel Dev OS implements a feedback learning loop, converting developer edits and instruction overrides into reusable prompt rules.
+
+---
+
+## 1. Learning Flow
+
+When an agent proposes changes and the developer modifies or rejects the code:
+1.  **Directive Compilation**: The developer logs the feedback comment:
+    ```bash
+    npx multimodel-dev-os feedback add "Do not use Tailwind CSS in components under src/components/legacy; use CSS modules." --type preference --tags styling
+    ```
+2.  **Summarization**: The developer compiles the logged guidelines:
+    ```bash
+    npx multimodel-dev-os feedback summarize
+    ```
+3.  **Learnings Update**: The learning rules are compiled and saved to `.ai/intelligence/learning-rules.md`.
+
+---
+
+## 2. Dynamic Context Ingestion
+
+During subsequent task prompts:
+1.  **Pattern Matching**: The routing engine scans `learning-rules.md` for rules matching the current file targets.
+2.  **Constraint Assembly**: Matching rules are compiled and injected directly into the prompt context budget as strict formatting rules.
+3.  **Instruction Drift Prevention**: This guarantees that once a design preference is specified, developer agents immediately align to it without repeating mistakes.
+
+---
+
+## Command Center Integration
+
+The [Repository Command Center](repository-command-center.md) dashboard counts the logged feedback items and tracks whether `learning-rules.md` is present or missing. Running `mmdo status` will advise you when feedback logs exist but have not yet been summarized into active rules.

package/docs/future-proof-architecture.md

@@ -0,0 +1,22 @@
+# Future-Proof Intelligence Architecture
+
+To scale seamlessly with next-generation model classes (such as Claude Fable/Mythos, GPT-5) and emerging developer tool interfaces (such as MCP servers, terminal wrappers, IDE extensions), MultiModel Dev OS decouples cognitive and operational mappings from the core binary into a registry-driven architecture.
+
+---
+
+## Registry-Driven Design
+
+Rather than hardcoding specific model names or adapter rules inside the CLI engine, all behaviors are governed by JSON/YAML schemas under `.ai/registries/` and `.ai/intelligence/`:
+
+1.  **Capabilities Registry** (`.ai/registries/capabilities.yaml`): Scores and matches models using multi-dimensional cognitive capability vectors (e.g. coding depth, context retrieval, local capabilities, agentic duration) instead of string matching.
+2.  **Tools Registry** (`.ai/registries/tools.yaml`): Configures tool connections, interface types (editor, terminal, assistant), and file targets. Supports Model Context Protocol (MCP) server bindings dynamically.
+3.  **Workflows Registry** (`.ai/registries/workflows.yaml`): Coordinates multi-agent development cycles, defining step sequences, capability thresholds, and checklist gates.
+
+---
+
+## Cognitive Mapping Pipeline
+
+When a developer triggers a command (e.g., initializing a stack, validating structure, routing task prompts):
+1.  **Task Analysis**: The OS determines the task complexity category (e.g. reasoning, coding, review).
+2.  **Query Capability**: The engine searches the Capability Registry to select the optimal model matching the task requirements.
+3.  **Context Integration**: The local Memory Engine loads token-bounded repository state summaries and historic developer feedback to build the final optimized prompt context.

package/docs/hash-compressed-memory.md

@@ -0,0 +1,72 @@
+# Hash-Compressed Repository Memory
+
+To prevent context bloat and ensure token-efficient prompting, MultiModel Dev OS leverages a diff-driven, hash-compressed repository memory engine.
+
+---
+
+## Codebase State Index (`memory.hash.json`)
+
+The memory engine compiles the workspace structure into a compact JSON file under `.ai/intelligence/memory.hash.json`:
+*   **Content Fingerprints**: SHA-256 hashes and size metrics of files to detect changes quickly.
+*   **Framework Signals**: Automatically detected project framework and environment indicators.
+*   **Package Manager Signals**: Detected package managers (npm, yarn, pnpm, etc.).
+*   **AI Dev OS Integration**: Mapped list of present MultiModel Dev OS workspace files.
+*   **Risk Profile**: Scans and logs files/patterns that require stricter verification checks.
+*   **Recommended Next Steps**: Tailored integration and stabilization recommendations.
+
+---
+
+## Memory CLI Commands
+
+MultiModel Dev OS provides four commands to scan the codebase and manage the memory index:
+
+### 1. `mmdo scan`
+Scans the codebase target directory, detects package managers, frameworks/languages, MultiModel Dev OS integrations, and lists security or size risks without writing any files.
+
+```bash
+npx multimodel-dev-os@latest scan
+```
+
+### 2. `mmdo memory build`
+Performs a full codebase scan and compiles the index files under `.ai/intelligence/`:
+- `memory.hash.json`: Structural fingerprints and framework signals.
+- `memory.summary.md`: Human-readable codebase status summary.
+
+```bash
+npx multimodel-dev-os@latest memory build
+```
+
+### 3. `mmdo memory refresh`
+Incremental refresh of memory files, comparing current file hashes against `memory.hash.json` to update changed, added, or removed files without re-indexing unchanged assets.
+
+```bash
+npx multimodel-dev-os@latest memory refresh
+```
+
+### 4. `mmdo memory diff`
+Computes the difference between the current workspace state and the existing `memory.hash.json` file. Reports count and paths of added, removed, and changed files without writing any changes to disk.
+
+```bash
+npx multimodel-dev-os@latest memory diff
+```
+
+---
+
+## Memory Refresh Operations
+
+Re-indexing the workspace is optimized to run incrementally:
+1.  **Hash Scanning**: The scanner compares current file hashes against the fingerprints in `memory.hash.json`.
+2.  **Pruning**: Files no longer present in the directory are removed from summaries.
+3.  **Targeted Summarization**: Only modified or new files are summarized, preserving historical decision logs and unchanged summaries to minimize token costs.
+4.  **Ignore Bounds**: Any directory or file path matching patterns inside `.gitignore` or default excludes (like `node_modules`, `.git`, `build`, etc.) is completely excluded from the memory scanning loop.
+5.  **Secret Redaction**: Skips configuration files containing secrets, credential blocks, or keystores (e.g. `.env`, `.npmrc`, `.keystore`).
+
+---
+
+## Command Center Integration
+
+The status of the memory index is monitored in the [Repository Command Center](repository-command-center.md). Running `mmdo status` displays one of three states for your codebase memory:
+*   **`CURRENT`**: The filesystem matches the built memory index exactly.
+*   **`STALE`**: The filesystem has changed since the last build. Run `mmdo memory refresh` to update the index.
+*   **`MISSING`**: No memory index is built yet. Run `mmdo memory build` to generate it.
+

package/docs/improvement-proposals.md

@@ -0,0 +1,70 @@
+# Codebase Improvement Proposals
+
+MultiModel Dev OS supports structured codebase optimization and refactoring proposals via a secure, proposal-based self-improvement pipeline.
+
+---
+
+## 1. Safety Principles
+
+To guarantee repository integrity and prevent unintended changes, all self-improvement operations adhere to three core rules:
+1.  **Write-Protection**: The CLI binary, security guards, workflows, and core policies are read-only and cannot be modified by model proposals.
+2.  **Human-in-the-Loop (HITL)**: Models cannot write code directly to the workspace without explicit user verification.
+3.  **Proposal-Only Modifications**: The proposal engine compiles ideas without applying edits directly.
+
+---
+
+## 2. Proposal-Review Cycle
+
+The workflow follows these stages:
+
+### Stage A: Proposal Generation
+Run the following command to check codebase context and write a proposal:
+```bash
+npx multimodel-dev-os improve propose --title "Fix unignored config files"
+```
+This generates a markdown file under `.ai/proposals/proposal-YYYYMMDD-HHMMSS.md` containing Frontmatter metadata and markdown explanation.
+
+### Stage B: Human Review
+The developer runs the review command to inspect active proposals:
+```bash
+npx multimodel-dev-os improve review
+```
+This prints a summary table of pending, approved, and rejected proposals.
+
+To see aggregates of proposal statuses:
+```bash
+npx multimodel-dev-os improve status
+```
+
+## 3. Proposal Execution
+
+Once a proposal is reviewed, you can execute it in one of two ways:
+
+### A. Automated Application (Recommended)
+Starting in v2.4.1, approved proposals with machine-applicable operation blocks can be executed automatically:
+1. Edit the frontmatter metadata block to set `approval_status` to `approved`.
+2. Validate the proposal and its safety boundaries:
+   ```bash
+   npx multimodel-dev-os improve validate .ai/proposals/proposal-xxxx.md
+   ```
+3. Preview planned changes using the dry-run diff command:
+   ```bash
+   npx multimodel-dev-os improve diff .ai/proposals/proposal-xxxx.md
+   ```
+4. Deterministically apply changes to the repository:
+   ```bash
+   npx multimodel-dev-os improve apply .ai/proposals/proposal-xxxx.md --approved
+   ```
+
+For detailed specifications on safety gates, allowed operations, and audit logs, see the [Approved Proposal Application Guide](/approved-proposal-apply).
+
+### B. Manual Implementation
+For proposals containing vague instructions or complex edits without structured operation blocks:
+1. Manually implement and verify the code edits within your workspace.
+2. Edit the frontmatter metadata block to set `approval_status` to `approved` to archive.
+
+---
+
+## Command Center Integration
+
+The [Repository Command Center](repository-command-center.md) displays active proposal counts (pending, approved, and rejected) and provides a recommended command if pending proposals are waiting for review. You can run `mmdo status` to get a quick overview of your self-improvement status.