multimodel-dev-os 3.1.0 → 3.5.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': '3.1.0',
+        'softwareVersion': '3.5.0',
         'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
       })
     ]
@@ -184,6 +184,7 @@ export default {
           { text: 'Trusted Registries', link: '/trusted-registries' },
           { text: 'Registry Policy Engine', link: '/registry-policy' },
           { text: 'Registry Security Model', link: '/registry-security' },
+          { text: 'Registry Security Threat Model', link: '/security-threat-model' },
           { text: 'Remote Catalog Authoring', link: '/remote-catalog-authoring' }
         ]
       },
@@ -197,6 +198,7 @@ export default {
           { text: 'Launch & Sharing Kit', link: '/launch-kit' },
           { text: 'CLI Roadmap', link: '/cli-roadmap' },
           { text: 'v3 Roadmap', link: '/v3-roadmap' },
+          { text: 'v3.5.0 Release Readiness', link: '/v3.5.0-readiness' },
           { text: 'Release Policy', link: '/release-policy' },
           { text: 'Support Policy', link: '/support-policy' },
           { text: 'Pre-flight Release Testing', link: '/testing' },

package/docs/architecture.md

@@ -38,7 +38,8 @@
 │    Layer 4: Intelligence Layer       │
 │  .ai/intelligence/  (memory, handoff)│
 │  .ai/registries/    (workflows,     │
-│    capabilities, tools, sources)     │
+│    capabilities, tools, sources,    │
+│    trusted-keys)                     │
 │  .ai/registry-cache/ (cached remote) │
 │  .ai/proposals/     (improvements)  │
 │  .ai/policies/      (safety, registry│
@@ -49,6 +50,7 @@
 │  plugin list/show/validate/install   │
 │  catalog list/show/recommend/install │
 │  registry list/add/sync/status/verify│
+│    /keygen/lock/trust                │
 │  onboard / adapter sync              │
 └──────────────────────────────────────┘
 ```

package/docs/index.md

@@ -214,12 +214,12 @@ You use **Cursor** for autocomplete, **Claude Code** for terminal ops, **Gemini*
 
 <div class="highlight-box">
 
-### 🆕 What's New in v2.7
+### 🆕 What's New in v3.5
 
-- 🎬 **Demo Workflow Pages** — 5 copy-paste guided workflows for onboarding, adapter sync, improvement loops, handoffs, and release checks
-- 📖 **Distribution Guide** — comprehensive release, verification, and package hygiene documentation
-- 🖼️ **Visual Flow Diagrams** — SVG assets for onboarding and adapter sync flows
-- 📁 **Docs-First Examples** — 4 new example workflows with commands and expected output
+- 🛡️ **Trusted Registry Signatures** — Asymmetric Ed25519 signatures verify remote publisher identity, preventing man-in-the-middle manifest modifications.
+- 🔑 **Trusted Key Store** — Local keys configuration at `.ai/registries/trusted-keys.yaml` manages active publisher public keys, statuses, and scope permissions.
+- 📝 **Registry Provenance Lockfile** — Records synced catalog/manifest SHA-256 hashes, sync times, and verdicts to detect post-sync local tampering.
+- 📊 **Structured Verdicts** — Generates machine-readable trust verdicts covering registry manifests, catalogs, keys, and signatures for auditability.
 
 </div>
 

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-3.0.2.tgz` in your directory root.
+   This creates a file named like `multimodel-dev-os-3.5.0.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-3.0.2.tgz
+   tar -xzf /path/to/multimodel-dev-os-3.5.0.tgz
    ls -la package/
    ```
 
@@ -78,17 +78,17 @@ Execute these validation actions strictly in sequence before triggering a releas
 ## 4. Prepublish Safety Guard
 
 > [!IMPORTANT]
-> **v3.0.2 is the active stable release.** NPM publishing is live.
+> **v3.5.0 is the active stable release.** NPM publishing is live.
 
 ### Source vs. Registry Strategy
-* **GitHub main branch (Source)**: Contains the current stable `v3.0.2` codebase.
+* **GitHub main branch (Source)**: Contains the current stable `v3.5.0` codebase.
 * **npm latest (Registry)**: Pulled and installed globally or via npx.
 
 ### Prepublish Safety Guard
 To prevent accidental `npm publish` executions on developer environments, a local validation script has been added to package hooks. If you run `npm publish`, it is blocked by default.
 
 To bypass this check during approved release windows:
-1. Ensure the version in `package.json` is a valid stable major version >= 2 (e.g., v3.0.2).
+1. Ensure the version in `package.json` is a valid stable major version >= 2 (e.g., v3.5.0).
 2. Run publication with the override env variable:
    ```powershell
    # PowerShell

package/docs/package-safety.md

@@ -9,6 +9,7 @@ To prevent security compromises, credential exposure, or prompt bloating, the fo
 1. **Local Credentials & API Keys:**
    * `.npmrc` (specifically containing authentication tokens)
    * `.env` / `.env.local`
+   * `.ai/registry-signing-key` (project-scoped HMAC signing key)
 2. **Build and Cache Artifacts:**
    * `node_modules/`
    * `dist/` / `build/`
@@ -35,3 +36,19 @@ A security hotfix has been applied in `v3.0.2` to secure the registry synchroniz
 * **Registry URL Sanitization:** Enforces strict validation of remote registry URLs using Node's `URL` parser. URLs must use HTTPS by default. Control characters, credentials, spaces, quotes, and shell metacharacters are strictly rejected.
 * **Upgrade Guidance:** Users running `v3.0.0` or `v3.0.1` must upgrade to `v3.0.2` immediately.
 * **Safety Boundaries Preserved:** Remote registries remain disabled by default, sync operations are cache-only (never installing or running plugins), and conflict checks on sensitive files (`.env`, `.npmrc`, package configuration files) are strictly enforced.
+
+## Package Governance Policies
+
+1. **Zero Runtime Dependencies:**
+   * The runtime package is strictly zero-dependency to ensure minimal installation footprint and maximum security.
+   * All compilation, testing, and dev tools (e.g., `esbuild`, `vitest`, `vitepress`) are restricted to `devDependencies` only.
+
+2. **Open-Source Transparency:**
+   * The complete modular source files (`src/`) and testing suites (`tests/`) are intentionally included in the published NPM package, allowing for visual auditing, validation, and debugging.
+
+3. **Manual NPM Publishing Only:**
+   * Automated publishing via CI is disabled. NPM publish is performed manually by maintainers using verification guards.
+
+4. **Milestone-Based Releases:**
+   * Patch-level releases are kept internal by default for stabilization sprints (such as `v3.5.0-prep`).
+   * Public updates are batched into stable, fully-audited milestone releases (e.g., `v3.5.0`). Critical security hotfixes are the only exception.

package/docs/public/llms-full.txt

@@ -1,4 +1,4 @@
-# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v3.1.0 Stable Release)
+# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v3.5.0 Stable Release)
 
 MultiModel Dev OS is a repository-level porting specification designed to align context and instructions across diverse developer tools and AI models.
 
@@ -97,6 +97,8 @@ All compliant MultiModel Dev OS CLIs strictly enforce the following command cont
   - `verify <name>`: Verifies SHA256 checksums of cached files against `checksums.json`.
   - `show <name>`: Shows detailed metadata and policies of a specific registry source.
   - `cache clear`: Deletes all files in `.ai/registry-cache/` (requires `--approved`).
+  - `trust list`: Lists trusted publisher keys.
+  - `trust show <key_id>`: Shows details of a specific trusted key.
 - **`verify`**: Automated release script that checks structure integrity.
 - **`templates`**: Lists built-in template profiles (supports overrides via `--registry <path>`).
 - **`validate`**: Strict Quality Gate checking the layout rules on disk (supports `--all-registries`).
@@ -140,3 +142,5 @@ npx multimodel-dev-os@latest init --caveman
 - **Release Policies**: https://rizvee.github.io/multimodel-dev-os/release-policy
 - **Upgrade Playbook**: https://rizvee.github.io/multimodel-dev-os/migration-guide
 - **Model Compatibility**: https://rizvee.github.io/multimodel-dev-os/model-compatibility
+- **Security Threat Model**: https://rizvee.github.io/multimodel-dev-os/security-threat-model
+- **v3.5.0 Release Readiness**: https://rizvee.github.io/multimodel-dev-os/v3.5.0-readiness

package/docs/public/llms.txt

@@ -1,4 +1,4 @@
-# MultiModel Dev OS (v3.1.0 Stable Release)
+# MultiModel Dev OS (v3.5.0 Stable Release)
 
 Portable, vendor-neutral workspace configuration standard for multi-agent AI pair-programming workflows.
 
@@ -33,6 +33,8 @@ npx multimodel-dev-os@latest registry show bundled
 npx multimodel-dev-os@latest registry add official https://example.com/catalog.yaml --approved
 npx multimodel-dev-os@latest registry sync official --approved
 npx multimodel-dev-os@latest registry cache clear --approved
+npx multimodel-dev-os@latest registry trust list
+npx multimodel-dev-os@latest registry trust show <key_id>
 
 # Scan codebase signals & check status
 npx multimodel-dev-os@latest scan
@@ -57,6 +59,7 @@ npx multimodel-dev-os@latest memory refresh
 # Run automated workflow cycles
 npx multimodel-dev-os@latest workflow run repo-health
 npx multimodel-dev-os@latest workflow list
+npx multimodel-dev-os@latest workflow show repo-health
 
 # Compile session handoff spec
 npx multimodel-dev-os@latest handoff build
@@ -94,6 +97,8 @@ npx multimodel-dev-os@latest improve log
 - **Guided Demo Workflows**: https://rizvee.github.io/multimodel-dev-os/demos/
 - **Stable Protocol Specification**: https://rizvee.github.io/multimodel-dev-os/stable-protocol
 - **Model Compatibility & Routing Guide**: https://rizvee.github.io/multimodel-dev-os/model-compatibility
+- **Security Threat Model**: https://rizvee.github.io/multimodel-dev-os/security-threat-model
+- **v3.5.0 Release Readiness**: https://rizvee.github.io/multimodel-dev-os/v3.5.0-readiness
 - **Cost/Context Optimization Playbook**: https://rizvee.github.io/multimodel-dev-os/cost-optimization
 
 ## Standard Templates

package/docs/public/sitemap.xml

@@ -250,4 +250,19 @@
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/release-policy</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/security-threat-model</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/v3.5.0-readiness</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
 </urlset>

package/docs/registry-policy.md

@@ -29,7 +29,35 @@ Here is a list of all fields supported in `.ai/policies/registry-policy.yaml`:
 
 ### `require_signature` (Boolean)
 * **Default:** `false`
-* **Description:** Reserved for future cryptographic signature validation.
+* **Description:** Requires cryptographic signature verification (HMAC-SHA256 or Ed25519) of registry manifests when syncing or verifying.
+
+### `allow_unsigned_local` (Boolean)
+* **Default:** `true`
+* **Description:** Allows unsigned local registries.
+
+### `allow_unsigned_bundled` (Boolean)
+* **Default:** `true`
+* **Description:** Allows unsigned bundled registries.
+
+### `allow_unsigned_remote` (Boolean)
+* **Default:** `false`
+* **Description:** Controls whether unsigned remote registries are permitted.
+
+### `trusted_keys_file` (String)
+* **Default:** `".ai/registries/trusted-keys.yaml"`
+* **Description:** Path to the trusted publisher key store file.
+
+### `allowed_signature_algorithms` (Array of Strings)
+* **Default:** `['ed25519', 'hmac-sha256']`
+* **Description:** List of cryptographic signature algorithms permitted for verification.
+
+### `require_trusted_publisher` (Boolean)
+* **Default:** `false`
+* **Description:** Requires that registry signatures come from a publisher registered in the trust store.
+
+### `provenance_required` (Boolean)
+* **Default:** `true`
+* **Description:** Requires local provenance verification via lockfile entries.
 
 ### `allow_untrusted_install` (Boolean)
 * **Default:** `false`

package/docs/registry-security.md

@@ -8,12 +8,7 @@ This document describes the threat model, safety boundaries, and mitigation stra
 
 ## Threat Model & Mitigations
 
-```
-Threat: Malicious Remote Registry
-   |--> Arbitrary Code Execution (Mitigated: Declarative-only YAML)
-   |--> Path Traversal / Overwrite (Mitigated: Resolve path bounds + Blacklist)
-   |--> Dependency Poisoning (Mitigated: No automated package installation)
-```
+For a comprehensive analysis of threat vectors (including transport compromise, command injection, path traversal, and malicious manifests) along with their corresponding architectural mitigations, please refer to the [Registry Security Threat Model](file:///F:/multimodel-dev-os/docs/security-threat-model.md).
 
 ### 1. Arbitrary Code Execution
 * **Threat:** A remote registry delivers a plugin containing malicious scripts (`shell`, `javascript`, etc.) that execute on the developer's machine.
@@ -72,3 +67,75 @@ For teams deploying MultiModel Dev OS in sensitive environments, we recommend:
 1. Keeping `allow_remote_registries: false` (the default) if no third-party plugins are needed.
 2. If remote plugins are required, set `allow_untrusted_install: false` to only permit plugins from official, signed corporate registries.
 3. Commit `.ai/policies/registry-policy.yaml` to version control to enforce uniform governance across all developer machines.
+
+---
+
+## Trusted Registry Signing & Provenance (v3.5.0-prep)
+
+MultiModel Dev OS supports optional **HMAC-SHA256 signing** of synced registry catalogs, providing tamper-evident provenance records.
+
+### How it works
+
+1. **Key generation** — Generate a project-scoped signing key (32 random bytes):
+   ```sh
+   npx multimodel-dev-os registry keygen --approved
+   ```
+   This writes a 64-char hex key to `.ai/registry-signing-key` with `0o600` permissions. **Add this file to `.gitignore`** — it should never be committed.
+
+2. **Sync with signing** — When you sync a remote registry, the CLI:
+   - Downloads `catalog.yaml` and verifies its SHA-256 checksum
+   - Computes `HMAC-SHA256(key, catalog_sha256)` → `signature`
+   - Writes a lockfile entry to `.ai/registry-lock.json`:
+     ```json
+     {
+       "url": "https://...",
+       "synced_at": "<ISO timestamp>",
+       "catalog_sha256": "<hex>",
+       "manifest_sha256": "<hex or null>",
+       "signature": "<hmac-sha256 hex>",
+       "signature_alg": "hmac-sha256"
+     }
+     ```
+
+3. **Verification** — `registry verify <name>` performs three checks:
+   - SHA-256 file integrity (existing behavior)
+   - Lockfile hash match — re-hashes cached `catalog.yaml` and compares against the lockfile entry
+   - HMAC signature verification — if a signing key and stored signature are present, verifies using `timingSafeEqual` (timing-attack safe)
+
+4. **Lockfile inspection** — `registry lock` shows the current lockfile state and per-registry signature status.
+
+### Signing Algorithm Details
+
+| Property | Value |
+|---|---|
+| Algorithm | HMAC-SHA256 |
+| Key material | 32 random bytes via `crypto.randomBytes` |
+| Signed payload | `catalog_sha256` (hex string) |
+| Comparison | `crypto.timingSafeEqual` |
+| Storage | `.ai/registry-signing-key` (mode 0o600) |
+| Lockfile | `.ai/registry-lock.json` (committed to VCS) |
+| Runtime deps | None — Node.js `crypto` built-in only |
+
+### Policy Controls
+
+The following fields in `.ai/policies/registry-policy.yaml` control signing and trust enforcement:
+
+| Field | Default | Effect |
+|---|---|---|
+| `require_signature` | `false` | When `true`, verify/sync fails if the manifest is unsigned or has an invalid signature. |
+| `require_lockfile_on_verify` | `false` | When `true`, verify fails if no lockfile entry exists for the registry. |
+| `allow_unsigned_local` | `true` | Permits unsigned local registries. |
+| `allow_unsigned_bundled` | `true` | Permits unsigned bundled registries. |
+| `allow_unsigned_remote` | `false` | Restricts unsigned remote registries (enforces signatures). |
+| `require_trusted_publisher` | `false` | Fails verification if signature key_id is not in the trust store. |
+| `allowed_signature_algorithms` | `['ed25519', 'hmac-sha256']` | Restricts allowed cryptographic signature algorithms. |
+| `trusted_keys_file` | `".ai/registries/trusted-keys.yaml"` | Configured location of the trusted key store. |
+
+### Security Notes
+
+- **HMAC Keys** are project-scoped and local. They are stored in `.ai/registry-signing-key` and must never be committed (automatically gitignored).
+- **Ed25519 Public Keys** are registered in `.ai/registries/trusted-keys.yaml` to authorize public publishers.
+- The **lockfile** (`.ai/registry-lock.json`) should be committed to VCS to provide verifiable tamper-evidence for the team.
+- **HTTPS transport security** secures the delivery, but **signatures and trust store** secure publisher identity, protecting against server-side compromises.
+- **Zero-Dependency Cryptography**: All operations rely strictly on Node's built-in `crypto` library.
+

package/docs/registry-signing.md

@@ -0,0 +1,70 @@
+# Registry Signature Verification
+
+MultiModel Dev OS employs cryptographic signatures to verify the authenticity and integrity of remote catalog registries. This document describes the signature formats, payload canonicalization, and verification mechanisms.
+
+---
+
+## Architecture Overview
+
+There are two primary modes of cryptographic integrity and identity checks:
+
+1. **Local/Internal Integrity Mode (HMAC-SHA256)**:
+   - Used for team or project-level locking.
+   - Signs the catalog checksum with a project-scoped key stored locally at `.ai/registry-signing-key`.
+   - Verified offline against `.ai/registry-lock.json` when running `registry verify`.
+
+2. **Public Publisher Trust Mode (Ed25519)**:
+   - Used to verify public registry catalogs using asymmetric public-key cryptography.
+   - The publisher signs the manifest using their Ed25519 private key.
+   - MultiModel Dev OS verifies the signature block against the public keys stored in the trusted key store (`.ai/registries/trusted-keys.yaml`).
+
+---
+
+## Canonical Payload Design
+
+To prevent key insertion order differences from altering signature checks, MultiModel Dev OS constructs a **stable canonical payload** before signing or verifying.
+
+### Canonicalization Algorithm:
+1. Sort the fields specified in `signed_fields` alphabetically.
+2. Extract these fields from the manifest object.
+3. Sort any nested object keys alphabetically recursively.
+4. Serialize the object to a standard minified JSON string (no spaces).
+
+Example code:
+```javascript
+import { createCanonicalPayload } from './src/registry/signing.js';
+
+const manifest = {
+  registry_name: "official",
+  version: "1.0.0",
+  catalog_hash: "sha256:abcd..."
+};
+
+const payload = createCanonicalPayload(manifest, ['registry_name', 'version', 'catalog_hash']);
+// Output: '{"catalog_hash":"sha256:abcd...","registry_name":"official","version":"1.0.0"}'
+```
+
+---
+
+## Key Management
+
+### Project-Scoped HMAC Keys
+To generate a local HMAC key for signing your synced catalog files:
+```bash
+node bin/multimodel-dev-os.js registry keygen --approved
+```
+This generates a random 32-byte key (64 hex characters) and saves it to `.ai/registry-signing-key` with `0o600` permissions. Ensure this file is gitignored.
+
+### Ed25519 Publisher Keys
+For public registries, the publisher generates an Ed25519 keypair. The public key is published in the trust store, while the private key is kept strictly confidential and offline.
+To verify signatures, the corresponding public key must be registered in `.ai/registries/trusted-keys.yaml`.
+
+---
+
+## Verification & Trust Readiness
+
+As of the current internal development sprint, the registry signature verification pipeline is fully tested end-to-end using dedicated offline E2E fixtures:
+- **Valid signatures** pass verification.
+- **Tampered manifests, wrong keys, and revoked keys** are blocked, reporting precise errors and warning verdicts recorded inside the local provenance lockfile (`registry-lock.json`).
+
+For current status and verification audits, see the [v3.5.0 Release Readiness Checklist](file:///F:/multimodel-dev-os/docs/v3.5.0-readiness.md).

package/docs/registry-sync.md

@@ -23,11 +23,14 @@ The `registry` command suite provides the following operations:
 | `registry list` | Read-only | List all configured registry sources |
 | `registry status` | Read-only | View sync status, timestamps, and cache health |
 | `registry show <name>` | Read-only | View configuration details of a specific source |
-| `registry verify <name>` | Read-only | Audit SHA256 checksums of cached registry files |
+| `registry verify <name>` | Read-only | Audit SHA256 checksums, lockfile hash, and signatures |
 | `registry add <name> <url> --approved` | Write | Add a new remote registry source |
-| `registry sync <name> --approved` | Network + Write | Download and cache remote catalog and manifest |
+| `registry sync <name> --approved` | Network + Write | Download and cache remote catalog, manifest, and verify signature |
 | `registry remove <name> --approved` | Write | Remove a registry source and clear its cache |
 | `registry cache clear --approved` | Write | Clear all cached registry files |
+| `registry keygen --approved` | Write | Generate local project-scoped HMAC key |
+| `registry lock` | Read-only | Inspect registry provenance lockfile |
+| `registry trust <subcmd>` | Read/Write | Inspect or verify trusted publisher store (subcmd: list, show, verify) |
 
 ---
 

package/docs/registry-trust-store.md

@@ -0,0 +1,66 @@
+# Trusted Key Store
+
+MultiModel Dev OS uses a trusted key store to authorize public publishers of remote catalog indexes.
+
+---
+
+## Configuration Path
+
+The trusted keys are stored in a YAML file at the path defined by the `trusted_keys_file` policy setting (default: `.ai/registries/trusted-keys.yaml`).
+
+---
+
+## File Format
+
+Each key record in `.ai/registries/trusted-keys.yaml` consists of:
+
+- `key_id`: A unique string identifier for the key.
+- `name`: Human-readable name of the key owner.
+- `algorithm`: The cryptographic algorithm (e.g. `ed25519`).
+- `public_key`: SPKI public key PEM block or raw key string.
+- `scopes`: Allowed operations for the key (e.g. `registry`, `catalog`).
+- `status`: Key status (`active`, `disabled`, or `revoked`).
+
+### Example Configuration:
+```yaml
+trusted_publishers:
+  - key_id: official-maintainer-key
+    name: "MultiModel Dev OS Core Team"
+    algorithm: ed25519
+    public_key: |
+      -----BEGIN PUBLIC KEY-----
+      MCowBQYDK2VwAyEA9vWwyE5+fY0dvEzl9S1UcvtoMkOAIDhDCzZAkP+CVNo=
+      -----END PUBLIC KEY-----
+    scopes:
+      - registry
+      - catalog
+    status: active
+```
+
+---
+
+## Policy Integration
+
+The policy configuration in `.ai/policies/registry-policy.yaml` controls how keys in the trust store are enforced:
+
+- `require_trusted_publisher`: If set to `true`, verification will fail if a signature uses a `key_id` not found in the trust store.
+- `allowed_signature_algorithms`: Restricts the algorithms allowed for verification (e.g. only `ed25519`).
+
+---
+
+## Command Line Interface
+
+You can manage and inspect the trust store using the `registry trust` subcommands:
+
+- **List trusted keys**:
+  ```bash
+  node bin/multimodel-dev-os.js registry trust list
+  ```
+- **Show key details**:
+  ```bash
+  node bin/multimodel-dev-os.js registry trust show <key_id>
+  ```
+- **Verify key formats**:
+  ```bash
+  node bin/multimodel-dev-os.js registry trust verify
+  ```

package/docs/release-policy.md

@@ -34,9 +34,10 @@ No package shall be merged or released without:
 
 ---
 
-## 4. Release Channel & Staging Controls
+## 4. Release Strategy & Staging Controls
 
-MultiModel Dev OS releases new versions directly to the public NPM registry:
-*   **Stable Releases (`npx multimodel-dev-os`)**: Published to the public registry under semantic version categories (e.g. `2.0.0`, `2.0.1`).
-*   **Release Candidates**: Built and validated locally via the automated verification script (`scripts/verify.js`) before tags or packaging runs.
-*   **Staging Verification**: To test new configurations prior to publishing, package the bundle locally (`npm pack`) and run CLI checkups in clean test directories.
+To ensure developer stability and avoid package version fatigue, MultiModel Dev OS enforces the following distribution strategy:
+- **Internal Stabilization Sprints**: Patch-level work (e.g. bug fixes, refactoring, test stability, documentation formatting) is treated as internal by default and committed directly to `main` without bumping versions or publishing to npm.
+- **Batched Milestone Releases**: Public npm and GitHub releases are batched into stable milestone releases (e.g., `v3.5.0`, `v3.6.0`, `v4.0.0`).
+- **Security Hotfix Exceptions**: Critical security hotfixes (e.g., remote execution, command injection remediations) bypass the batching policy and are published immediately as public patch releases.
+- **Staging Verification**: To test new configurations prior to publishing, package the bundle locally (`npm pack`) and run CLI checkups in clean test directories (`C:\mmdo-smoke`).

package/docs/security-threat-model.md

@@ -0,0 +1,96 @@
+# Registry Security Threat Model
+
+This document outlines the security architecture, threat model using the STRIDE framework, mitigation strategies, and design limitations of the registry and catalog trust systems in MultiModel Dev OS (MMDO).
+
+---
+
+## 1. Threat Scenarios & Mitigations
+
+### Threat: Attacker Modifies Remote Registry Manifest
+- **Description**: An attacker compromises the remote host or storage bucket containing the registry manifest file (`manifest.json`) and attempts to alter its contents.
+- **Mitigation**: 
+  - Every sync operation retrieves the manifest. 
+  - The client verifies the manifest's cryptographic signature against the local trust store ([`trusted-keys.yaml`](file:///.ai/registries/trusted-keys.yaml)). 
+  - If the manifest's contents are modified by an attacker, the signature verification check fails, halting verification and refusing cache sync.
+
+### Threat: Attacker Modifies Catalog Contents
+- **Description**: An attacker alters the `catalog.yaml` index to point to malicious plugins or scripts, while leaving the manifest file unchanged.
+- **Mitigation**: 
+  - The `manifest.json` contains a SHA-256 integrity hash of `catalog.yaml` (`catalog_hash`). 
+  - The client calculates the local SHA-256 hash of the downloaded `catalog.yaml` and asserts it matches the manifest's `catalog_hash`. Any discrepancy halts synchronization.
+
+### Threat: Attacker Compromises Transport (Man-in-the-Middle)
+- **Description**: An attacker intercepts the network connection to spoof registry manifests or download files.
+- **Mitigation**: 
+  - Registry URLs are strictly validated to require secure HTTPS connections. HTTP is rejected by default.
+  - Transport integrity is backed by public-key Ed25519 signatures. Even if transport-level security is compromised, the client asserts the signature matches a trusted key.
+
+### Threat: Attacker Submits Malicious Plugin Metadata
+- **Description**: An attacker registers a plugin with malicious parameters, such as directory paths designed to cause directory traversal, or shell scripts designed to run command injection.
+- **Mitigation**: 
+  - Strict path safety validation is performed on plugin installation paths to prevent path traversal outside permitted `.ai/` and `adapters/` directories.
+  - Slugs are validated against strict alphanumeric patterns (`/^[a-z0-9-_]+$/i`).
+  - Catalog synchronization is cache-only and non-executing. Synchronizing remote registries does not run any code or auto-install plugins.
+
+### Threat: Path Traversal
+- **Description**: An attacker crafts registry source configurations or manifest files using relative directory sequences (e.g. `../../etc/passwd`) to read or write sensitive files.
+- **Mitigation**: 
+  - All file path resolutions are strictly bounded and verified using canonical paths (`path.resolve`). Access outside the approved workspace directory is rejected.
+
+### Threat: Command Injection via Registry URLs
+- **Description**: An attacker specifies registry URLs containing shell metacharacters (e.g., quotes, backticks, semicolons) hoping to execute shell commands during sync or fetch operations.
+- **Mitigation**: 
+  - The fetch helper utilizes `execFileSync` instead of shell-based `execSync`, ensuring URL values are treated strictly as literal command arguments.
+  - Strict validation rejects URLs containing whitespace or shell command syntax.
+
+### Threat: Stale/Replay Registry Data
+- **Description**: An attacker serves a valid, signed registry manifest from the past (e.g. version 1.0.0 containing an older, vulnerable plugin) to roll back updates.
+- **Mitigation**: 
+  - The local lockfile ([`registry-lock.json`](file:///.ai/registry-lock.json)) records the last synchronized manifest hash, version, and sync timestamp. 
+  - Replays or attempts to downgrade manifest versions can be detected via local history comparison.
+
+### Threat: Unknown/Revoked Signing Keys
+- **Description**: An attacker signs a malicious manifest using an expired, disabled, revoked, or unconfigured signing key.
+- **Mitigation**: 
+  - Key IDs are verified against active trust store records. If a key is marked `revoked` or `disabled`, verification immediately fails.
+  - Keys lacking the specific `scopes: ["registry"]` or `scopes: ["catalog"]` attribute are rejected.
+
+### Threat: Local Cache Tampering
+- **Description**: An attacker with local access modifies the cache files in `.ai/registry-cache/` to bypass remote verification.
+- **Mitigation**: 
+  - Every `registry verify` run calculates the SHA-256 hashes of all cached files and compares them against the tamper-evident local provenance lockfile (`registry-lock.json`), which is committed to VCS.
+
+---
+
+## 2. Trust Model Layers
+
+MultiModel Dev OS enforces a multi-layer defense-in-depth model:
+
+```mermaid
+graph TD
+    A[1. URL Validation] --> B[2. Cache-Only Sync]
+    B --> C[3. Catalog Hash Verification]
+    C --> D[4. Lockfile Comparison]
+    D --> E[5. Provenance Report]
+    E --> F[6. Public-Key Signature Verification]
+    F --> G[7. Trusted Key Store]
+    G --> H[8. Manual Approval Gates]
+```
+
+1. **URL Validation**: Rejects non-HTTPS, command-injection characters, or malformed URLs.
+2. **Cache-Only Sync**: Downloads files strictly to offline cache folders. No script execution occurs.
+3. **Catalog Hash Verification**: Asserts SHA-256 integrity matches between files and manifest list.
+4. **Lockfile Comparison**: Checks current downloaded hashes against committed VCS registry lockfile.
+5. **Provenance Report**: Computes local and signature status to output detailed trust verdicts.
+6. **Public-Key Signature Verification**: Verifies cryptographic signatures using Ed25519.
+7. **Trusted Key Store**: Verifies that the signing key is configured, active, and scoped.
+8. **Manual Approval Gates**: Plugin installation requires explicit `--approved` confirmation from the operator.
+
+---
+
+## 3. Limits & Constraints
+
+- **Local HMAC Mode Limitations**: HMAC signature mode provides project-scoped integrity verification (proving a registry was synced by a project member with the key). It does *not* prove remote publisher identity to the public.
+- **Asymmetric Signature Boundaries**: Ed25519 signatures verify publisher identity only if the user's local trust store is correct. If the trust store itself is compromised or loaded with untrusted public keys, signatures cannot prevent spoofing.
+- **HTTPS Limitations**: HTTPS secures transit integrity against network-level eavesdroppers. It does not establish publisher identity or code quality.
+- **Operator Overrides**: No security model can protect users who manually execute command overrides (`--approved` or `--force`) without inspecting the manifest and plugins being installed.