multimodel-dev-os 2.0.1 → 2.8.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.1',
+        'softwareVersion': '2.8.0',
         'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
       })
     ]
@@ -50,11 +50,30 @@ export default {
         text: 'Getting Started',
         items: [
           { text: 'Introduction', link: '/' },
-          { text: 'Interactive CLI Demo', link: '/demo' },
           { text: 'Quickstart', link: '/quickstart' },
+          { text: 'Interactive CLI Demo', link: '/demo' },
           { text: 'FAQ', link: '/faq' }
         ]
       },
+      {
+        text: 'Demo Workflows',
+        items: [
+          { text: 'Demo Hub', link: '/demos/' },
+          { text: 'Existing Repo Onboarding', link: '/demos/existing-repo-onboarding' },
+          { text: 'Adapter Sync', link: '/demos/adapter-sync' },
+          { text: 'Safe Improvement Loop', link: '/demos/safe-improvement-loop' },
+          { text: 'Multi-Agent Handoff', link: '/demos/multi-agent-handoff' },
+          { text: 'Release Check', link: '/demos/release-check' }
+        ]
+      },
+      {
+        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: [
@@ -137,16 +156,36 @@ export default {
         ]
       },
       {
-        text: 'Operations & Publishing',
+        text: 'Self-Improvement Engine',
         items: [
-          { text: 'Public Launch Checklist', link: '/launch-checklist' },
+          { 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: 'Interactive TUI Dashboard', link: '/dashboard' },
+          { text: 'Declarative Plugin Hooks', link: '/plugin-hooks' },
+          { text: 'Plugin Authoring Guide', link: '/plugin-authoring' },
+          { text: 'TUI & Plugin Safety', link: '/tui-safety' }
+        ]
+      },
+      {
+        text: 'Distribution & Release',
+        items: [
+          { text: 'Distribution Guide', link: '/distribution' },
+          { text: 'NPM Publishing Runbook', link: '/npm-publishing' },
           { text: 'Release Playbook Template', link: '/release-template' },
+          { text: 'Public Launch Checklist', link: '/launch-checklist' },
+          { text: 'Launch & Sharing Kit', link: '/launch-kit' },
           { 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: 'v2 Roadmap', link: '/v2-roadmap' },
           { text: 'Release Policy', link: '/release-policy' },
           { text: 'Support Policy', link: '/support-policy' },
+          { text: 'Pre-flight Release Testing', link: '/testing-v0.2' },
           { text: 'Final Launch Guidelines', link: '/final-launch' },
           { text: 'v1.0.0 Release Checklist', link: '/v1-checklist' }
         ]

package/docs/5-day-roadmap.md

@@ -30,8 +30,8 @@ The timeline maps the progress from a fresh install to automated pull request ve
 ### Day 2: Fill Project Memory (Core Workspace Contracts)
 - **Objective:** Author the central single source of truth files.
 - **Tasks:**
-  1. Edit [AGENTS.md](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/AGENTS.md) — detail your project overview, technology stack, build commands, and strict directory boundaries (`no-touch` blocks).
-  2. Edit [MEMORY.md](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/MEMORY.md) — log architectural decisions, third-party credentials rules, and project milestones.
+  1. Edit [AGENTS.md](file:///f:/multimodel-dev-os/AGENTS.md) — detail your project overview, technology stack, build commands, and strict directory boundaries (`no-touch` blocks).
+  2. Edit [MEMORY.md](file:///f:/multimodel-dev-os/MEMORY.md) — log architectural decisions, third-party credentials rules, and project milestones.
   3. Verify file placement is correct inside the root folder.
 
 ---
@@ -39,18 +39,18 @@ The timeline maps the progress from a fresh install to automated pull request ve
 ### Day 3: Configure Skills & Checks (Custom Prompt Packs)
 - **Objective:** Assemble reusable instructions for common development routines.
 - **Tasks:**
-  1. Author specific command workflows inside [.ai/skills/](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/.ai/skills/) (e.g. database setup scripts, feature-specific build guidelines).
-  2. Define validation constraints in [.ai/checks/](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/.ai/checks/) (e.g. regression checks, test coverage parameters).
-  3. Edit [.ai/prompts/](file:///c:/Users/ADMIN/OneDrive/Desktop/multimodel-dev-os/.ai/prompts/) to establish output formatting expectations.
+  1. Author specific command workflows inside [.ai/skills/](file:///f:/multimodel-dev-os/.ai/skills/) (e.g. database setup scripts, feature-specific build guidelines).
+  2. Define validation constraints in [.ai/checks/](file:///f:/multimodel-dev-os/.ai/checks/) (e.g. regression checks, test coverage parameters).
+  3. Edit [.ai/prompts/](file:///f:/multimodel-dev-os/.ai/prompts/) to establish output formatting expectations.
 
 ---
 
 ### Day 4: Mount Adapters & Handoff Logs (Sync Environments)
 - **Objective:** Synchronize the central rules with IDE settings and terminal agents.
 - **Tasks:**
-  1. Map adapters using the CLI command:
+  1. Synchronize all adapters using the sync command:
      ```bash
-     npx multimodel-dev-os@latest init --adapter cursor --adapter claude --adapter vscode
+     npx multimodel-dev-os@latest adapter sync all --approved
      ```
   2. Confirm that `.cursorrules`, `CLAUDE.md`, and `.vscode/settings.json` mirror the central instructions properly.
   3. Execute a local hand-off by creating a session log template inside `.ai/session-logs/` to pass context between agents.
@@ -62,11 +62,11 @@ The timeline maps the progress from a fresh install to automated pull request ve
 - **Tasks:**
   1. Run the local structure verification:
      ```bash
-     npx multimodel-dev-os validate
+     npx multimodel-dev-os@latest validate
      ```
   2. Add validation gates to pre-commit hooks or CI workflows (e.g. `.github/workflows/verify.yml`).
   3. Run diagnostic checkups using the `doctor` command:
      ```bash
-     npx multimodel-dev-os doctor
+     npx multimodel-dev-os@latest doctor
      ```
   4. Educate the engineering team on executing validations before pushing code blocks.

package/docs/CLI.md

@@ -1,50 +1,276 @@
 # CLI Command Reference
 
-`multimodel-dev-os` features a lightweight, dependency-free local CLI utility. It allows standard bootstraps, structural integrity checks, and rule validations natively.
+`multimodel-dev-os` features a lightweight, dependency-free CLI utility with **zero third-party runtime dependencies**. All commands work on Windows, macOS, and Linux.
 
 ## Execution
 
-Execute the CLI globally or inside target folder contexts using `npx`:
-
 ```bash
+# Via npx (recommended — no install needed)
 npx multimodel-dev-os@latest <command> [options]
+
+# Via local clone
+node bin/multimodel-dev-os.js <command> [options]
 ```
 
-Or execute locally within a cloned workspace:
+---
+
+## Commands
+
+### 1. `init` — Scaffold Workspace
+
+Scaffold MultiModel Dev OS files and adapters cleanly.
 
 ```bash
-node bin/multimodel-dev-os.js <command> [options]
+npx multimodel-dev-os@latest init [options]
 ```
 
+| Option | Description |
+|:---|:---|
+| `-t, --target <path>` | Target destination (default: current directory) |
+| `--template <name>` | Stack blueprint: `nextjs-saas`, `wordpress-site`, `ecommerce-store`, `seo-landing-page`, `expo-react-native-android`, `general-app` |
+| `-a, --adapter <name>` | Inject adapter rules: `cursor`, `claude`, `vscode`, `gemini`, `antigravity`, `codex` |
+| `--caveman` | Install ultra-lightweight token-optimized variant |
+| `-d, --dry-run` | Preview actions without writing files |
+| `-f, --force` | Overwrite existing files (creates `.bak` backups) |
+
 ---
 
-## Commands
+### 2. `scan` — Codebase Scanner
+
+Scan codebase structure, frameworks, package managers, and security/exclusion risks.
+
+```bash
+npx multimodel-dev-os@latest scan [--target <path>]
+```
+
+---
+
+### 3. `status` — Intelligence Dashboard
+
+Display a compact project intelligence dashboard summarizing package metadata, framework signals, memory state, feedback counts, proposals, and recommended next steps. Fully read-only.
+
+```bash
+npx multimodel-dev-os@latest status [--target <path>]
+```
+
+---
+
+### 4. `memory` — Hash-Compressed Memory
+
+Manage codebase hash-compressed memory index.
+
+```bash
+npx multimodel-dev-os@latest memory <subcommand> [--target <path>]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `build` | Full codebase scan → writes memory files |
+| `refresh` | Incremental memory update based on file hash diffs |
+| `diff` | Reports modified/added/removed files vs memory index (read-only) |
+
+---
+
+### 5. `feedback` — Developer Feedback Loop
 
-### 1. `init`
-Scaffold `multimodel-dev-os` files and adapters cleanly.
-* **Usage:** `node bin/multimodel-dev-os.js init [options]`
-* **Options:**
-  - `-t, --target <path>`: Specifies target destination (default: current working directory).
-  - `--template <name>`: Stack blueprint: `nextjs-saas`, `wordpress-site`, `ecommerce-store`, `seo-landing-page`, `general-app`.
-  - `-a, --adapter <name>`: Inject rules file directly (`cursor`, `claude`, `vscode`, `gemini`, `antigravity`, `codex`).
-  - `--caveman`: Installs ultra-lightweight variant profiles.
-  - `-d, --dry-run`: Previews actions without mutated files.
-  - `-f, --force`: Overwrites conflicts.
-
-### 2. `validate`
-Strict directory schema compliance gate checks.
-* **Usage:** `node bin/multimodel-dev-os.js validate [options]`
-* **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.
-* **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.
-
-### 4. `templates` / `list-templates`
-Inspection map of all built-in stacks.
-* **Usage:** `node bin/multimodel-dev-os.js templates`
-
-### 5. `show-template <name>`
-Detailed layout specifications and skill blueprints audit.
-* **Usage:** `node bin/multimodel-dev-os.js show-template nextjs-saas`
+Capture developer corrections and compile them into reusable learning rules.
+
+```bash
+npx multimodel-dev-os@latest feedback <subcommand> [options]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `add "<text>"` | Append a structured feedback entry |
+| `list` | View all logged feedback entries |
+| `summarize` | Compile feedback logs into `learning-rules.md` |
+
+**Options:** `--type <type>` (correction, preference, bug) · `--tags <list>` · `--files <list>`
+
+---
+
+### 6. `improve` — Proposal Engine
+
+Manage codebase optimization proposals and deterministic execution.
+
+```bash
+npx multimodel-dev-os@latest improve <subcommand> [options]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `propose` | Generate a codebase improvement proposal |
+| `review` | List active proposals and their statuses |
+| `status` | Show aggregate proposal status counts |
+| `validate <file>` | Validate safety gates and parse operations |
+| `diff <file>` | Preview changes in grouped diff format |
+| `apply <file> --approved` | Apply approved operations to target codebase |
+| `log` | Display Applied Proposals Audit Log history |
+
+**Options:** `--title <text>` (with `propose`) · `--approved` (required for `apply`) · `--target <path>`
+
+---
+
+### 7. `workflow` — Workflow Orchestration
+
+Orchestrate read-only development workflow pipelines.
+
+```bash
+npx multimodel-dev-os@latest workflow <subcommand> [options]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `list` | Print all registered workflows |
+| `show <name>` | Display workflow details, risk level, and steps |
+| `plan <name>` | Dry-run preview of workflow steps |
+| `run <name>` | Execute safe, read-only workflow steps |
+
+**Built-in workflows:** `repo-health` · `memory-refresh` · `feedback-review` · `proposal-review` · `release-check`
+
+---
+
+### 8. `handoff` — Agent Session Handoff
+
+Compile token-compressed agent session handoff context.
+
+```bash
+npx multimodel-dev-os@latest handoff <subcommand>
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `build` | Generate `.ai/intelligence/handoff.md` (gitignored) |
+| `show` | Print handoff contents to console |
+
+---
+
+### 9. `onboard` — Existing Repo Onboarding
+
+Safely onboard an existing repository into MultiModel Dev OS.
+
+```bash
+npx multimodel-dev-os@latest onboard <subcommand> [options]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `analyze` | Scan project structure, frameworks, and risk markers (read-only) |
+| `recommend` | Run diagnostics and recommend templates/adapters (read-only) |
+| `plan` | Generate onboarding plan and report (read-only) |
+| `apply --approved` | Copy configuration templates (creates backups, requires `--force` for overwrites) |
+| `status` | Show onboarding progress and completeness dashboard |
+
+---
+
+### 10. `adapter` — IDE Adapter Sync
+
+Manage and synchronize rule files for IDE and assistant adapters.
+
+```bash
+npx multimodel-dev-os@latest adapter <subcommand> [options]
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `status` | Show rules files status and enable/disable states |
+| `diff <adapter>` | Show diff between bundled template and target root file |
+| `sync <adapter\|all> --approved` | Synchronize rule files (creates backups, requires `--force` for overwrites) |
+
+---
+
+### 11. `validate` — Strict Validation
+
+Strict directory schema compliance gate. Exits with code 1 on failures — safe for CI/CD.
+
+```bash
+npx multimodel-dev-os@latest validate [--target <path>]
+```
+
+---
+
+### 12. `doctor` — Advisory Diagnostics
+
+Advisory checkups for workspace health, gitignores, token-sinks, and intelligence configuration.
+
+```bash
+npx multimodel-dev-os@latest doctor [options]
+```
+
+| Flag | Description |
+|:---|:---|
+| `--release` | Verify version stability, docs build, and dry-run pack |
+| `--intelligence` | Audit memory freshness, feedback logs, proposals, and `.gitignore` safety |
+| `--onboarding` | Verify crucial root files, configs, and git-ignored plan files for onboarding readiness |
+
+---
+
+### 13. `verify` — Release Audit
+
+Full release verification suite with **214+ structural assertions**. Checks all files, registries, YAML syntax, CLI version matching, npm pack hygiene, and security boundaries.
+
+```bash
+npx multimodel-dev-os@latest verify
+# or
+npm run verify
+```
+
+---
+
+### 14. `templates` — Template Gallery
+
+List and inspect all built-in stack templates.
+
+```bash
+npx multimodel-dev-os@latest templates          # List all templates
+npx multimodel-dev-os@latest show-template <name>  # Detailed template inspection
+```
+
+---
+
+### 15. `dashboard` — Interactive TUI Dashboard
+
+Launch the zero-dependency interactive command center to manage all commands.
+
+```bash
+npx multimodel-dev-os@latest dashboard
+# or short alias:
+npx multimodel-dev-os@latest ui
+```
+
+---
+
+### 16. `plugin` — Declarative Plugins Engine
+
+Manage declarative plugins safely within the whitelisted `.ai/` and `adapters/` paths.
+
+```bash
+npx multimodel-dev-os@latest plugin list
+npx multimodel-dev-os@latest plugin show <slug>
+npx multimodel-dev-os@latest plugin validate <path-to-yaml>
+npx multimodel-dev-os@latest plugin install <path-to-yaml> --approved
+npx multimodel-dev-os@latest plugin status
+```
+
+| Subcommand | Description |
+|:---|:---|
+| `list` | Print all installed plugins |
+| `show <slug>` | Inspect detailed plugin capabilities and safety notes |
+| `validate <path>` | Validate a YAML manifest against the plugin JSON schema |
+| `install <path>` | Install plugin configs (creates backups, requires `--approved`) |
+| `status` | Audit workspace to verify plugin asset presence |
+
+---
+
+### 17. Registry Commands
+
+Explore model, adapter, and skill registries.
+
+```bash
+npx multimodel-dev-os@latest models         # View model registry
+npx multimodel-dev-os@latest models --json   # Machine-readable output
+npx multimodel-dev-os@latest show-model <id> # Detailed model info
+npx multimodel-dev-os@latest providers       # View API providers
+npx multimodel-dev-os@latest adapters        # View adapter registry
+npx multimodel-dev-os@latest skills          # View skill registry
+```

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.