multimodel-dev-os 2.0.0 → 2.6.0

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': '2.0.0',
+        'softwareVersion': '2.6.0',
         'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
       })
     ]
@@ -55,6 +55,14 @@ export default {
           { text: 'FAQ', link: '/faq' }
         ]
       },
+      {
+        text: 'Repo Onboarding & Adapters',
+        items: [
+          { text: 'Real Repo Onboarding', link: '/real-repo-onboarding' },
+          { text: 'IDE Adapter Sync', link: '/adapter-sync' },
+          { text: 'Template Recommendation', link: '/template-recommendation' }
+        ]
+      },
       {
         text: 'Protocol & QA Specifications',
         items: [
@@ -136,6 +144,20 @@ export default {
           { text: 'Templates Architecture', link: '/templates-guide' }
         ]
       },
+      {
+        text: 'Self-Improvement Engine',
+        items: [
+          { text: 'Self-Improving Codebase', link: '/self-improving-codebase' },
+          { text: 'Improvement Proposals', link: '/improvement-proposals' },
+          { text: 'Feedback Learning Loop', link: '/feedback-learning' },
+          { text: 'Hash-Compressed Memory', link: '/hash-compressed-memory' },
+          { text: 'Learning Rules', link: '/learning-rules' },
+          { text: 'Approved Proposal Application', link: '/approved-proposal-apply' },
+          { text: 'Repository Command Center', link: '/repository-command-center' },
+          { text: 'Workflow Orchestration', link: '/workflow-orchestration' },
+          { text: 'Agent Handoff Spec', link: '/agent-handoff' }
+        ]
+      },
       {
         text: 'Operations & Publishing',
         items: [

package/docs/CLI.md

@@ -37,9 +37,12 @@ Strict directory schema compliance gate checks.
 * **Assertions:** Checks for the presence of crucial root files and enabled adapters' rule targets. If assertions fail, exits with status 1.
 
 ### 3. `doctor`
-Advisory checkups for gitignores and large token-sinks.
+Advisory checkups for gitignores, large token-sinks, and intelligence configuration.
 * **Usage:** `node bin/multimodel-dev-os.js doctor [options]`
-* **Audits:** Missing `.env` gates in gitignores, missing build steps inside `AGENTS.md`, and large unignored directories (e.g. `node_modules`, `.next`). Reports warnings without blocking execution.
+* **Audits:** Missing `.env` gates in gitignores, missing build steps inside `AGENTS.md`, and large unignored directories.
+* **Options:**
+  - `--release`: Verifies version stability, verifies Vitepress docs build, checks dry-run pack.
+  - `--intelligence`: Runs advisory audits verifying memory index freshness, feedback log presence, learning rules compilation, proposals status, and `.gitignore` safety boundaries.
 
 ### 4. `templates` / `list-templates`
 Inspection map of all built-in stacks.
@@ -48,3 +51,87 @@ Inspection map of all built-in stacks.
 ### 5. `show-template <name>`
 Detailed layout specifications and skill blueprints audit.
 * **Usage:** `node bin/multimodel-dev-os.js show-template nextjs-saas`
+
+### 6. `scan`
+Scan codebase structure, frameworks, package managers, and security/exclusion risks.
+* **Usage:** `node bin/multimodel-dev-os.js scan [options]`
+* **Options:**
+  - `-t, --target <path>`: Specifies target destination (default: current working directory).
+
+### 7. `memory`
+Manage codebase hash-compressed memory index.
+* **Usage:** `node bin/multimodel-dev-os.js memory <subcommand> [options]`
+* **Subcommands:**
+  - `build`: Performs full codebase scan and writes memory files.
+  - `refresh`: Performs incremental memory updates based on file hash diffs.
+  - `diff`: Reports files modified, added, or removed compared to memory index without writing any changes.
+* **Options:**
+  - `-t, --target <path>`: Specifies target destination (default: current working directory).
+
+### 8. `feedback`
+Manage developer feedback loop and compile rules.
+* **Usage:** `node bin/multimodel-dev-os.js feedback <subcommand> [options]`
+* **Subcommands:**
+  - `add "<text>"`: Append a structured feedback object.
+  - `list`: View logged feedback entries.
+  - `summarize`: Compile raw feedback logs into `learning-rules.md`.
+* **Options:**
+  - `--type <type>`: Classification type (`correction`, `preference`, `bug`, etc.)
+  - `--tags <list>`: Comma-separated list of tags.
+  - `--files <list>`: Comma-separated list of related files.
+
+### 9. `improve`
+Manage codebase optimization proposals and deterministic execution.
+* **Usage:** `node bin/multimodel-dev-os.js improve <subcommand> [options]`
+* **Subcommands:**
+  - `propose`: Generate a codebase improvement proposal markdown file.
+  - `review`: List active proposals and their statuses.
+  - `status`: Show aggregate counts of proposal statuses.
+  - `validate <proposal-file>`: Validate safety gates and parse operations. Prints a structured safety checklist (Frontmatter, Approval, JSON, Types, Boundaries, Permissions, Constraints) with actionable fixes on refusal.
+  - `diff <proposal-file>`: Preview proposed changes grouped by type in a token-safe truncated diff format.
+  - `apply <proposal-file> --approved`: Apply approved operations to target, printing compact summaries, clear idempotent statuses, and writing success/refusal audit logs.
+  - `log`: Display Applied Proposals Audit Log execution history (`apply-log.jsonl`).
+* **Options:**
+  - `--title <text>`: Title of the proposal (used with `propose`).
+  - `--approved`: Explicitly authorize apply command execution (required for `apply`).
+  - `-t, --target <path>`: Specifies target destination (default: current working directory).
+
+### 10. `status`
+Display a compact project intelligence dashboard.
+* **Usage:** `node bin/multimodel-dev-os.js status [options]`
+* **Overview:** Summarizes package metadata, framework signals, memory state (`MISSING`/`STALE`/`CURRENT`), feedback counts, proposal statuses, apply log audits, and the recommended next command. Fully read-only.
+
+### 11. `workflow`
+Orchestrate read-only development workflow pipelines.
+* **Usage:** `node bin/multimodel-dev-os.js workflow <subcommand> [options]`
+* **Subcommands:**
+  - `list`: Print all registered workflows in `.ai/registries/workflows.yaml`.
+  - `show <workflow>`: Display details, risk level, memory write capability, code modification capability, and logical steps of target workflow.
+  - `plan <workflow>`: Print steps and commands of target workflow without executing them (dry-run).
+  - `run <workflow>`: Sequentially execute safe, read-only and metadata-write steps (e.g. scan, doctor, memory refresh, feedback summarize). Any step requiring source code modification will halt and output manual instructions.
+
+### 12. `handoff`
+Compile token-compressed agent session handoff context.
+* **Usage:** `node bin/multimodel-dev-os.js handoff <subcommand> [options]`
+* **Subcommands:**
+  - `build`: Scans project signals and intelligence state and generates `.ai/intelligence/handoff.md` (which is git-ignored by default).
+  - `show`: Prints handoff contents to console (building them first if not present).
+
+### 13. `onboard`
+Safely onboard an existing repository into MultiModel Dev OS.
+* **Usage:** `node bin/multimodel-dev-os.js onboard <subcommand> [options]`
+* **Subcommands:**
+  - `analyze`: Scans repository structure, frameworks, languages, and risk markers. Read-only.
+  - `recommend`: Runs scanner diagnostics and recommendations for templates and adapters. Read-only.
+  - `plan`: Generates onboarding plan `.ai/intelligence/onboarding.plan.json` and report `.ai/intelligence/onboarding.report.md`. Read-only.
+  - `apply --approved`: Copies configuration templates to target directory. Overwrites require `--force` and automatically generate backups.
+  - `status`: Show progress and completeness percentage dashboard.
+
+### 14. `adapter`
+Manage and synchronize rule files for IDE and assistant adapters.
+* **Usage:** `node bin/multimodel-dev-os.js adapter <subcommand> [options]`
+* **Subcommands:**
+  - `status`: Show rules files status and enable/disable states from config.
+  - `diff <adapter>`: Show rules diff between bundled template and target root file.
+  - `sync <adapter|all> --approved`: Synchronizes rule files. Overwrites require `--force` and automatically generate backups.
+

package/docs/adapter-sync.md

@@ -0,0 +1,27 @@
+# IDE & Coding Agent Adapter Sync
+
+The `adapter` command system synchronizes target IDE configurations and coding agent rule files (e.g. `.cursorrules`, `CLAUDE.md`, `.vscode/settings.json`) from bundled templates based on enabled states in `.ai/config.yaml`.
+
+## Adapter Commands
+
+```bash
+# 1. Show the synchronization status of all adapters
+npx multimodel-dev-os adapter status --target .
+
+# 2. Preview rules to write for a specific adapter
+npx multimodel-dev-os adapter diff cursor --target .
+
+# 3. Synchronize rule files for a specific adapter
+npx multimodel-dev-os adapter sync cursor --target . --approved
+
+# 4. Synchronize all enabled adapters
+npx multimodel-dev-os adapter sync all --target . --approved
+```
+
+## Overwriting Existing Files
+
+By default, the synchronizer skips existing rules files to prevent overwriting user customizations. Use the `--force` option to overwrite, which automatically creates a backup with a `.bak` suffix.
+
+```bash
+npx multimodel-dev-os adapter sync all --target . --approved --force
+```

package/docs/adapters.md

@@ -77,3 +77,19 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md).
 3. **Include only** tool-specific overrides or behavior notes
 4. **Test with the actual tool** — don't guess at file detection behavior
 5. **Document quirks** — if a tool has unusual behavior, note it in `setup.md`
+
+## Synchronizing Adapters
+
+Use the `adapter` command to automatically synchronize native rule and settings files from the bundled adapter registry templates into your workspace root:
+
+```bash
+# Check status of installed rule files
+npx multimodel-dev-os adapter status
+
+# Preview diffs between template and local rule files
+npx multimodel-dev-os adapter diff cursor
+
+# Write rule files to target (forces backup if files exist and --force is passed)
+npx multimodel-dev-os adapter sync cursor --approved --force
+npx multimodel-dev-os adapter sync all --approved
+```

package/docs/agent-handoff.md

@@ -0,0 +1,40 @@
+# Agent Handoff Specification
+
+The `handoff` command parses repository context to build a token-compressed summary document designed to transfer codebase state to a new agent or model session.
+
+---
+
+## 1. CLI Commands
+
+### Build Handoff Spec
+Generates the summary document at `.ai/intelligence/handoff.md`:
+```bash
+npx multimodel-dev-os handoff build
+```
+
+### Show Handoff Spec
+Prints the handoff content directly to the console (building it first if missing):
+```bash
+npx multimodel-dev-os handoff show
+```
+
+---
+
+## 2. Handoff Structure
+
+The compiled `.ai/intelligence/handoff.md` file contains the following key sections:
+
+1.  **Project Context**: Package name, version, detected frameworks, and package dependencies.
+2.  **Intelligence Core State**: Tells the incoming agent if the memory is `CURRENT` or `STALE`, feedback loop counts, rules status, proposals status, and last applied proposal run ID.
+3.  **Core Learning Summaries**: Provides a snippet of active learning rules from `learning-rules.md`.
+4.  **Safety Constraints**: Outlines session boundaries, indicating that workflows are read-only and modifications require explicit user approval.
+5.  **Recommended Next Steps**: Provides 2-3 logical starting points for the incoming agent.
+
+---
+
+## 3. Safety Controls
+
+*   **No Source Dumps**: Full source code is never appended.
+*   **No Secrets**: Scans target folders and excludes sensitive files, `.env` configs, credentials, or private keys.
+*   **Excluded in VCS**: `.ai/intelligence/handoff.md` is ignored by Git, ensuring local state doesn't pollute repository history.
+*   **Onboarding Guard**: If the target repository has not been initialized with MultiModel Dev OS, the handoff builder warns the developer/agent and details the onboarding steps in the generated handoff.

package/docs/approved-proposal-apply.md

@@ -0,0 +1,156 @@
+# Approved Proposal Application Engine
+
+MultiModel Dev OS v2.4.1 (Safety & UX Patch) introduces a safe, deterministic, human-approved proposal application layer to automate the execution of approved codebase optimization proposals under strict safety constraints.
+
+---
+
+## 1. Core Workflow
+
+Instead of requiring manual copy-pasting, the CLI can execute machine-applicable operation blocks from proposal files that have been marked as `approved` by a developer.
+
+```mermaid
+graph TD
+    A[improve propose] --> B[Pending Proposal File]
+    B --> C{Developer Review}
+    C -->|Rejects| D[approval_status: rejected]
+    C -->|Approves & edits frontmatter| E[approval_status: approved]
+    E --> F[improve validate]
+    F -->|Validation check passes| G[improve diff]
+    G -->|Dry-run preview passes| H[improve apply --approved]
+    H --> I[Changes written to target & logged in apply-log]
+```
+
+---
+
+## 2. Machine-Applicable Operations
+
+To automate changes, proposal files support an optional, structured JSON block embedded as a `json` code block in the markdown body:
+
+````markdown
+```json
+{
+  "operations": [
+    {
+      "type": "create_file",
+      "path": "docs/example.md",
+      "content": "# Example\n",
+      "overwrite": true
+    },
+    {
+      "type": "append_line",
+      "path": ".gitignore",
+      "line": "node_modules/"
+    },
+    {
+      "type": "replace_text",
+      "path": "README.md",
+      "find": "old text",
+      "replace": "new text",
+      "allow_multiple": false
+    }
+  ]
+}
+```
+````
+
+### Supported Operation Types
+
+| Operation | Parameters | Description |
+|---|---|---|
+| `create_file` | `path`, `content`, `overwrite` (optional) | Creates a file with the given content. Fails if the file exists unless `overwrite: true`. |
+| `append_line` | `path`, `line` | Appends a line to the file. It is idempotent; if the line already exists in the file, it will not be duplicated. |
+| `replace_text` | `path`, `find`, `replace`, `allow_multiple` (optional) | Replaces search string `find` with `replace`. Fails if `find` is not found, or matches multiple times unless `allow_multiple: true`. |
+
+### Disallowed Operations for Safety
+The following actions are strictly prohibited in the v2.4.0 application engine:
+* Deleting or renaming files (`delete_file`, `rename_file`)
+* Running arbitrary shell commands
+* Installing npm packages or editing package dependencies
+* Interacting with Git or version control
+* Performing network calls
+* Modifying binary files or secret files
+* Modifying files outside the target workspace root folder
+
+---
+
+## 3. Strict Safety Gates
+
+The application engine validates every proposal file against a set of strict safety rules before any file is touched:
+
+1. **Existence**: The target proposal markdown file must exist.
+2. **Metadata Frontmatter**: YAML frontmatter must parse successfully.
+3. **Approval Check**: `approval_status` inside the frontmatter must be explicitly set to `approved`.
+4. **CLI Flag**: `improve apply` refuses to execute unless `--approved` is passed by the user.
+5. **Operations block**: A valid JSON code block with `operations` array must be found.
+6. **Command validation**: Every listed operation type must be allowed.
+7. **Directory boundaries**: Every target path must resolve strictly inside the target root directory. Directory traversal using `..` or absolute paths resolves outside target root and fails.
+8. **Protected paths**: No protected files or directories (such as `.git/`, `node_modules/`, `.env`, `.npmrc`, SSL keys/certificates) can be written to or modified.
+9. **`replace_text` match count**: Search text `find` must match exactly once unless `allow_multiple: true` is passed.
+10. **`create_file` overwrites**: If a target file exists, the operation must explicitly specify `overwrite: true`.
+11. **`append_line` idempotency**: Line additions will not duplicate if the exact line already exists.
+12. **Dry-run diff**: Developers can preview all changes using `improve diff` prior to execution.
+
+> [!WARNING]
+> **Workflow Isolation**: The `improve apply` command can only be executed manually by a developer. The MultiModel Dev OS [Workflow Runner](workflow-orchestration.md) runs in a strictly read-only mode and is prohibited from executing `improve apply` or modifying codebase files.
+
+---
+
+## 4. CLI Commands
+
+### validate
+Validates the proposal frontmatter, safety gates, and operation rules. Displays a color-coded Checklist showing the status of each safety gate (pass, fail, skip) and actionable fixes:
+```bash
+npx multimodel-dev-os improve validate <proposal-file> --target <path>
+```
+
+### diff
+Previews the changes grouped by operation type (Create, Append, Replace) in a token-safe truncated format:
+```bash
+npx multimodel-dev-os improve diff <proposal-file> --target <path>
+```
+
+### apply
+Deterministically executes the operations listed in the approved proposal file. Refuses to run without the `--approved` flag. Prints pre-apply summaries and detailed idempotent run indicators.
+```bash
+npx multimodel-dev-os improve apply <proposal-file> --target <path> --approved
+```
+
+### log
+Lists the history of applied proposals from the audit log:
+```bash
+npx multimodel-dev-os improve log --target <path>
+```
+
+---
+
+## 5. Audit Logging
+
+Every execution of `improve apply` writes an entry to the append-only JSON Lines audit log. Hardened in v2.4.1, it also writes records for failed/refused attempts:
+* **Log Location**: `.ai/proposals/apply-log.jsonl`
+* **Log Exclusion**: Automatically ignored by Git via `.gitignore` and excluded from AI scanner runs.
+
+Each record conforms to `.ai/intelligence/apply-log.schema.json` and contains:
+* `id`: Unique execution identifier (`apply-YYYYMMDD-HHMMSS`)
+* `proposal_id`: Proposal file identifier
+* `applied_at`: ISO timestamp of execution
+* `target`: Resolved workspace target path
+* `operations_count`: Total operations performed
+* `files_changed`: List of relative paths modified
+* `before_hashes`: SHA-256 file hashes before execution
+* `after_hashes`: SHA-256 file hashes after execution
+* `status`: `success`, `failed`, or `refused`
+* `refused_reason`: Reason why validation was refused (when applicable)
+* `notes`: Additional run information or failure reasons
+
+---
+
+## 6. Recommended Workflow
+
+To ensure safety, consistency, and clarity, follow this workflow:
+
+1. **validate**: Run `npx multimodel-dev-os improve validate .ai/proposals/proposal-xxxx.md` to run safety gate audits.
+2. **diff**: Run `npx multimodel-dev-os improve diff .ai/proposals/proposal-xxxx.md` to review planned changes.
+3. **manually review**: Verify the proposal contents, target paths, and operation constraints.
+4. **apply**: Run `npx multimodel-dev-os improve apply .ai/proposals/proposal-xxxx.md --approved` to write modifications locally.
+5. **run tests**: Manually run verification tests (e.g., `npm run verify` or custom test runner).
+6. **commit**: Commit the changes manually to version control.

package/docs/capability-registry.md

@@ -0,0 +1,24 @@
+# Model Capability Registry
+
+The **Capability Registry** manages and scores AI models across cognitive, speed, and cost vectors, eliminating hardcoded model routing logic.
+
+---
+
+## 1. Capabilities Score Matrix
+
+Models are scored in `.ai/registries/capabilities.yaml` across six primary vectors:
+*   `coding` — Syntax accuracy, language compliance, and refactoring competence.
+*   `reasoning` — Multi-file plan generation and logical constraint auditing.
+*   `repo-scan` — Needle-in-a-haystack retrieval accuracy at massive context scales.
+*   `agentic-duration` — Ability to execute long-running task loops without losing parameters.
+*   `mcp-compliance` — Native Model Context Protocol (MCP) tool bindings.
+*   `local-offline` — Suitability for local resources (e.g. running via Ollama/Llama.cpp).
+
+---
+
+## 2. Dynamic Routing Engine
+
+When executing workflow steps:
+1.  **Workflows Query**: The workflow profile specifies the minimum capability scores required for each step (e.g., `planning` requires `reasoning: 0.85`, while `coding` requires `coding: 0.80`).
+2.  **Capabilities Filter**: The router filters active models that meet or exceed these score thresholds.
+3.  **Cost-Speed Trade-off**: From the matching models, the engine selects the candidate that optimizes cost, latency, or user-selected flags (e.g. `--local` or `--low-cost`).

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,25 +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 | v1.2.0 | Source Only |
-| `show-model` | Inspect settings for a model registry entry | v1.2.0 | Source Only |
-| `providers` | List configured model registry providers | v1.2.0 | Source Only |
-| `route-model`| Route a target prompt based on presets | v1.2.0 | Source Only |
-| `adapters` | List configured adapter registry entries | v1.2.0 | Source Only |
-| `show-adapter`| Inspect settings for an adapter registry entry | v1.2.0 | Source Only |
-| `skills` | List configured skill registry entries | v1.2.0 | Source Only |
-| `show-skill` | Inspect settings for a skill registry entry | v1.2.0 | Source Only |
-
-> [!NOTE]
-> All new `v1.2.0` subcommands listed as **Source Only** are fully implemented in the source code but are unreleased on the npm package registry. To run them, execute from a clone of the GitHub repository. They will be packaged officially in the `v2.0.0` stable release.
-
-## CLI v2.0.0 Stabilization Goal
-
-Ahead of the `v2.0.0` release, we will run a comprehensive compatibility pass:
-* **Backward Compatibility**: Ensure that all new registries configurations and subcommand syntax do not break the stable `v1.0.0` and `v1.1.0` CLI behaviors.
-* **Unified Quality Gates**: Integrate model registry and adapter configuration validation parameters directly into the standard `validate` and `doctor` command pipelines.
-* **Cross-Platform Hardening**: Audit all commands on Windows (PowerShell/CMD), macOS, and Linux bash environments before resuming npm package publishing.
+| `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 |
+
+## CLI v2.0.0 Stabilization & Beyond
+
+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.
 
 

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/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.
+