mindforge-cc 2.0.0-alpha.4 → 2.0.0-alpha.6

package/bin/installer-core.js

@@ -21,7 +21,7 @@ const RUNTIMES = {
   antigravity: {
     globalDir:      path.join(os.homedir(), '.gemini', 'antigravity'),
     localDir:       'agents',
-    commandsSubdir: 'mindforge',
+    commandsSubdir: 'workflows',
     entryFile:      'CLAUDE.md',
   },
 };
@@ -51,6 +51,31 @@ const fsu = {
   },
 };
 
+// ── Registry Management ────────────────────────────────────────────────────────
+const RegistryManager = {
+  getRegistryPath: () => path.join(os.homedir(), '.mindforge', 'registry.json'),
+
+  registerProject(projectPath) {
+    const regPath = this.getRegistryPath();
+    fsu.ensureDir(path.dirname(regPath));
+
+    let registry = { projects: [] };
+    if (fsu.exists(regPath)) {
+      try {
+        registry = JSON.parse(fsu.read(regPath));
+      } catch (e) {
+        console.error('  ⚠️  Registry file corrupted, recreating...');
+      }
+    }
+
+    if (!registry.projects.includes(projectPath)) {
+      registry.projects.push(projectPath);
+      fsu.write(regPath, JSON.stringify(registry, null, 2));
+      console.log(`  ✅  Registered project in ${regPath}`);
+    }
+  }
+};
+
 // ── Self-install detection ────────────────────────────────────────────────────
 function isSelfInstall() {
   const pkgPath = path.join(process.cwd(), 'package.json');
@@ -125,14 +150,14 @@ function safeCopyClaude(src, dst, options = {}) {
 
 // ── Install verification ──────────────────────────────────────────────────────
 function verifyInstall(baseDir, cmdsDir, runtime, scope) {
-  // Minimum required files for a functional installation
+  const pfx = runtime === 'antigravity' ? 'mindforge:' : '';
   const required = [
-    path.join(baseDir, 'CLAUDE.md'),
-    path.join(cmdsDir, 'help.md'),
-    path.join(cmdsDir, 'init-project.md'),
-    path.join(cmdsDir, 'health.md'),
-    path.join(cmdsDir, 'execute-phase.md'),
-    path.join(cmdsDir, 'security-scan.md'),
+    scope === 'local' ? path.join(process.cwd(), 'CLAUDE.md') : path.join(baseDir, 'CLAUDE.md'),
+    path.join(cmdsDir, `${pfx}help.md`),
+    path.join(cmdsDir, `${pfx}init-project.md`),
+    path.join(cmdsDir, `${pfx}health.md`),
+    path.join(cmdsDir, `${pfx}execute-phase.md`),
+    path.join(cmdsDir, `${pfx}security-scan.md`),
   ];
 
   const missing = required.filter(f => !fsu.exists(f));
@@ -171,14 +196,28 @@ async function install(runtime, scope, options = {}) {
     return;
   }
 
-  // ── 1. Install CLAUDE.md ────────────────────────────────────────────────────
+  // ── 1. Install CLAUDE.md (Root standardization for IDEs) ────────────────────
   const claudeSrc = runtime === 'claude'
     ? src('.claude', 'CLAUDE.md')
     : src('.agent', 'CLAUDE.md');
 
   if (fsu.exists(claudeSrc)) {
+    // Keep legacy location based on runtime config
     safeCopyClaude(claudeSrc, path.join(baseDir, 'CLAUDE.md'), { force, verbose });
-    console.log('  ✅  CLAUDE.md');
+
+    // ✨ STANDARD: Inject into project root and IDE-specific rules files
+    if (scope === 'local' && !selfInstall) {
+      const rootClaude = path.join(process.cwd(), 'CLAUDE.md');
+      const rootCursor = path.join(process.cwd(), '.cursorrules');
+      const rootWindsurf = path.join(process.cwd(), '.windsurfrules');
+      
+      safeCopyClaude(claudeSrc, rootClaude, { force, verbose });
+      safeCopyClaude(claudeSrc, rootCursor, { force, verbose });
+      safeCopyClaude(claudeSrc, rootWindsurf, { force, verbose });
+      console.log('  ✅  CLAUDE.md (Mirrored to project root & .cursorrules)');
+    } else {
+      console.log('  ✅  CLAUDE.md');
+    }
   }
 
   // ── 2. Install commands ─────────────────────────────────────────────────────
@@ -189,8 +228,24 @@ async function install(runtime, scope, options = {}) {
   if (fsu.exists(cmdSrc)) {
     fsu.ensureDir(cmdsDir);
     const files = fsu.listFiles(cmdSrc).filter(f => f.endsWith('.md'));
-    files.forEach(f => fsu.copy(path.join(cmdSrc, f), path.join(cmdsDir, f)));
-    console.log(`  ✅  ${files.length} commands`);
+    
+    // Install for specific runtime
+    files.forEach(f => {
+      const targetName = runtime === 'antigravity' ? `mindforge:${f}` : f;
+      fsu.copy(path.join(cmdSrc, f), path.join(cmdsDir, targetName));
+    });
+
+    // ✨ STANDARD: Mirror to .claude/commands for cross-IDE compatibility (Cursor/Windsurf/Claude Code)
+    if (scope === 'local' && runtime !== 'claude' && !selfInstall) {
+      const standardCmdDir = path.join(process.cwd(), '.claude', 'commands', 'mindforge');
+      fsu.ensureDir(standardCmdDir);
+      files.forEach(f => {
+        fsu.copy(path.join(cmdSrc, f), path.join(standardCmdDir, f));
+      });
+      console.log(`  ✅  ${files.length} commands (Mirrored to .claude/commands/mindforge/)`);
+    } else {
+      console.log(`  ✅  ${files.length} commands`);
+    }
   }
 
   // ── 3. Framework files (local scope only, non-self-install) ─────────────────
@@ -266,6 +321,7 @@ async function install(runtime, scope, options = {}) {
       }
     }
 
+    RegistryManager.registerProject(process.cwd());
   }
 
   // ── 4. Verify installation ──────────────────────────────────────────────────

package/bin/mindforge-cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * MindForge CLI Router — v2.0.0
+ * Standardizes command invocation for GitHub Actions and local development.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const ARGS = process.argv.slice(2);
+const COMMAND = ARGS[0];
+const COMMAND_ARGS = ARGS.slice(1);
+
+const ROOT = path.resolve(__dirname, '..');
+
+const COMMANDS = {
+  'security-scan': {
+    script: 'bin/validate-config.js',
+    description: 'Validate configuration and run security checks',
+    defaultArgs: ['MINDFORGE.md']
+  },
+  'health': {
+    script: 'bin/installer-core.js',
+    description: 'Verify project health and installation integrity',
+    defaultArgs: ['--check']
+  },
+  'headless': {
+    script: 'bin/autonomous/headless.js',
+    description: 'Run MindForge agent in headless mode'
+  },
+  'pr-review': {
+    script: 'bin/review/cross-review-engine.js',
+    description: 'Run standard PR review logic'
+  },
+  'cross-review': {
+    script: 'bin/review/cross-review-engine.js',
+    description: 'Run advanced cross-model review'
+  },
+  'classify': {
+    script: 'bin/change-classifier.js',
+    description: 'Classify changes into governance tiers'
+  },
+  'approve': {
+    script: 'bin/governance/approve.js',
+    description: 'Generate a governance approval signature to unblock Tier 3 gates'
+  }
+};
+
+if (!COMMAND || ARGS.includes('--help') || ARGS.includes('-h')) {
+  printUsage();
+  process.exit(0);
+}
+
+const target = COMMANDS[COMMAND];
+if (!target) {
+  console.error(`❌ Unknown command: ${COMMAND}`);
+  console.error('Available commands: ' + Object.keys(COMMANDS).join(', '));
+  process.exit(1);
+}
+
+const scriptPath = path.join(ROOT, target.script);
+const finalArgs = COMMAND_ARGS.length > 0 ? COMMAND_ARGS : (target.defaultArgs || []);
+
+console.log(`🚀 Executing: ${COMMAND} (${target.description})`);
+
+const result = spawnSync('node', [scriptPath, ...finalArgs], {
+  cwd: ROOT,
+  stdio: 'inherit',
+  env: { ...process.env, MINDFORGE_CLI: 'true' }
+});
+
+process.exit(result.status || 0);
+
+function printUsage() {
+  console.log('\n⚡ MindForge Enterprise CLI\n');
+  console.log('Usage: node bin/mindforge-cli.js <command> [options]\n');
+  console.log('Commands:');
+  for (const [name, cfg] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(15)} ${cfg.description}`);
+  }
+  console.log('\nExamples:');
+  console.log('  node bin/mindforge-cli.js security-scan');
+  console.log('  node bin/mindforge-cli.js headless --phase 1');
+  console.log('\n');
+}

package/bin/wizard/setup-wizard.js

@@ -246,4 +246,8 @@ async function main() {
   }
 }
 
-main();
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/docs/architecture/README.md

@@ -11,6 +11,7 @@ Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
 4. **Intelligence Layer** — Health, difficulty, anti-patterns in `.mindforge/intelligence/`
 5. **Knowledge Layer** — Long-term memory, capture, and sync in `.mindforge/memory/`
 6. **Distribution Layer** — Installer, registry, CI, SDK, plugins
+7. **Observability Layer (v2)** — Real-time dashboard, SSE bridge, metrics aggregator
 
 ## Key data artifacts
 - `.planning/PROJECT.md` — project brief
@@ -24,6 +25,7 @@ Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
 2. `/mindforge:execute-phase` runs plans in waves
 3. `/mindforge:verify-phase` runs automated + human gates
 4. `/mindforge:ship` generates release artifacts and PR metadata
+5. `/mindforge:dashboard` provides real-time observability and governance
 
 ## Installation targets
 - Claude Code: `~/.claude/` or `.claude/`

package/docs/ci-cd.md

@@ -0,0 +1,92 @@
+# 🚀 MindForge 5-Layer Plane Architecture (CI/CD)
+
+MindForge v2.0.0 uses a sophisticated Control + Execution Plane architecture for its GitHub Actions, ensuring enterprise-grade governance and autonomous execution capabilities.
+
+## 🏗️ The 5 Planes
+
+| Plane | Purpose | Trigger |
+| --- | --- | --- |
+| **Control Plane** | Change classification & Routing | `push`, `pull_request` |
+| **Execution Plane** | Headless agent runtime | `workflow_call` |
+| **AI Intelligence** | Multi-model code validation | PRs (reusable) |
+| **Release Plane** | Packaging & Deployment | Tags (`v*`) |
+| **Observability** | Run metrics & Analytics | Post-run |
+
+---
+
+## 🔄 PR Workflow Lifecycle
+
+When you open or update a Pull Request, MindForge triggers the following "Beast" sequence:
+
+1. **🔍 Classify**: Analyzes diffs to assign a **Governance Tier (1, 2, or 3)**.
+2. **⚖️ Govern**:
+    - **Tier 3 Enforcement**: Blocks the PR if sensitive changes are detected without an approval file.
+    - **Security Scan**: Automatically validates `MINDFORGE.md` and project configurations.
+3. **⚡ Execute**:
+    - Runs **Headless Agent** to verify autonomous logic.
+    - Executes full **Test Suite** and **Linter**.
+4. **🤖 Review**:
+    - Triggers **AI Intelligence Layer** (Claude + GPT-4o).
+    - Posts architectural/security findings as a **PR Comment**.
+5. **📊 Observe**: Generates a performance and audit trace report.
+
+---
+
+## 🔍 Control Plane & Tiers
+
+Every change is automatically classified into a governance tier:
+
+- **Tier 1 (Trivial)**: Auto-approves and executes basic verification.
+- **Tier 2 (Logic)**: Executes full test suites and AI review.
+- **Tier 3 (Sensitive)**: Blocks the pipeline unless a manual approval is found in `.planning/approvals/`.
+
+---
+
+## 🛠️ MindForge CLI (`bin/mindforge-cli.js`)
+
+All planes interact with MindForge via a centralized CLI router:
+
+- `health`: Validates project integrity.
+- `security-scan`: Scans for secrets and PII.
+- `headless`: Executes agents in non-interactive mode.
+- `pr-review`: Standard code review.
+- `cross-review`: Multi-model architecture validation.
+
+---
+
+## 🛡️ Governance Enforcement
+
+If a PR touches sensitive components (Auth, Payments, Security):
+1. The **Control Plane** identifies it as **Tier 3**.
+2. The **Governance Gate** fails unless a valid `.planning/approvals/*.json` file exists.
+3. Once approved, the **Execution Plane** resumes the workflow.
+
+
+
+---
+
+## 📦 Automated Releases
+
+Releases are triggered by pushing a semver tag:
+
+```bash
+git tag v2.0.0
+git push origin v2.0.0
+```
+
+This will automatically:
+
+- Run the full test suite.
+- Generate a CHANGELOG.
+- Publish to npm.
+- Create a GitHub Release with build artifacts.
+
+---
+
+## 📊 Observability
+
+MindForge tracks every CI execution:
+
+- **Success Rate**: Phase completion status.
+- **Token Usage**: AI cost monitoring.
+- **Audit Trace**: Full execution history in `AUDIT.jsonl`.

package/docs/commands-reference.md

@@ -8,4 +8,5 @@
 | `/mindforge:execute-phase [N]`  | Execute plans with wave-based parallelism     |
 | `/mindforge:verify-phase [N]`   | Human acceptance testing + automated checks  |
 | `/mindforge:ship [N]`           | Generate changelog, run quality gates, create PR |
+| `/mindforge:dashboard`           | Manage the real-time web observability dashboard |
 

package/docs/feature-dashboard.md

@@ -0,0 +1,52 @@
+# Feature: Real-time Dashboard (v2)
+
+The MindForge Real-time Dashboard provides a high-fidelity, web-based control center for your agentic workflows. It leverages **Server-Sent Events (SSE)** to push live updates from your codebase directly to your browser with zero performance overhead.
+
+## 🚀 Getting Started
+
+To launch the dashboard:
+```bash
+/mindforge:dashboard --start --open
+```
+
+Default access: `http://localhost:7339` (Strictly bound to `127.0.0.1` for security).
+
+## 🛠 Key Features
+
+### 1. Live Audit Stream
+- Real-time rolling feed of all `AUDIT.jsonl` events.
+- Color-coded status indicators (Success, Failure, Security Warning).
+- Detailed JSON inspection for every action.
+
+### 2. Performance Metrics
+- **Token Costs**: Cumulative and session-based cost tracking across all providers.
+- **Quality Score**: Real-time graphing of verify-pass-rates.
+- **Compaction Health**: Monitoring of context management efficiency.
+
+### 3. Web-based Governance
+- **Tier 2/3 Approvals**: Review pending architectural or security changes.
+- **Tier 3 Confirmation**: Mandatory plan ID typing for high-risk approvals is enforced in the UI.
+- **Decision History**: Interactive timeline of past approvals and rejections.
+
+### 4. Team & Agent Activity
+- **Wave Progress**: Track multiple agents executing parallel waves.
+- **Persona Context**: See which agent personas are currently active.
+- **Steerage Feed**: View steering instructions as they are applied.
+
+## 🛡 Hardened Security
+- **Localhost Binding**: The server refuses connections from external IPs.
+- **CORS Lock-down**: Only allows requests from the local control plane.
+- **Integrity First**: Audit logs are written by the backend *before* changes are committed, ensuring a bulletproof trail.
+
+## 📟 Command Reference
+
+| Flag | Action |
+| :--- | :--- |
+| `--start` | Launch the dashboard server process. |
+| `--stop` | Gracefully shut down the server. |
+| `--status` | Check if the dashboard is running and get PID. |
+| `--open` | Open the UI in your default browser. |
+| `--port [N]` | Change the default port (7339). |
+
+---
+*For technical implementation details, see `.mindforge/dashboard/dashboard-spec.md`.*

package/docs/publishing-guide.md

@@ -10,69 +10,34 @@ This guide outlines the standard procedure for publishing a new version of `mind
 
 ## Step-by-Step Workflow
 
-### 1. Versioning Strategy
+### 1. Pre-Flight Verification & Adversarial Review
+Before any release, ensure the following is completed:
 
-MindForge follows [Semantic Versioning (SemVer)](https://semver.org/).
+- **Structural Integrity**: Run `npm test` to verify layout and command mirroring.
+- **Security Check**: Run `/mindforge:security-scan` to ensure no keys or CVEs are present.
+- **Mult-Model Review**: Run `/mindforge:cross-review` to have multiple models (Claude, GPT, Gemini) audit the new features for edge cases.
 
-- **Major (X.0.0)**: Breaking changes or significant architecture shifts.
-- **Minor (0.X.0)**: New features, non-breaking.
-- **Patch (0.0.X)**: Bug fixes, performance improvements.
-- **Prereleases**: Append `-alpha.N`, `-beta.N`, or `-rc.N` (e.g., `2.0.0-alpha.4`).
+### 2. Versioning Strategy
+MindForge follows SemVer. Update `package.json` and `CHANGELOG.md` first.
 
-### 2. Pre-Publish Verification
+### 3. Automated Release Workflow
+MindForge provides a built-in workflow to handle the heavy lifting:
 
-Always run the integrity suite before publishing:
+1. Run the slash command: `/publish-release`
+2. Follow the interactive prompts to execute tests and dry runs.
 
-```bash
-npm test
-```
-
-This verifies that:
-- All required directories and files exist.
-- Commands are mirrored between `.claude/` and `.agent/`.
-- `package.json` metadata is valid.
-- No secrets are leaked.
-
-### 3. Dry Run
-
-Validate the package contents:
+### 4. Manual Publishing (Fallback)
+If the workflow is unavailable:
 
 ```bash
-npm pack --dry-run
+npm publish --tag alpha --access public
 ```
 
-Review the file list in the output to ensure no internal config or temporary files are included.
-
-### 4. Publishing
-
-#### Stable Releases
-For stable versions (e.g., `2.0.0`), use a standard publish:
-
-```bash
-npm publish --access public
-```
-
-#### Prereleases (Alpha/Beta/RC)
-For prerelease versions, you **MUST** specify a tag to avoid them being installed as `@latest`:
-
-```bash
-npm publish --tag [alpha|beta|rc] --access public
-```
-
-### 5. Git Tagging
-
-After a successful publish, tag the commit in Git:
-
+### 5. Git Tagging & Origin Sync
 ```bash
 git tag v[version]
-git push origin v[version]
+git push origin --tags
 ```
 
-## Troubleshooting
-
-- **403 Forbidden**: Usually means the version already exists on npm or you don't have permissions.
-- **Tag Required**: If you get an error about specifying a tag, it's because you are publishing a version with a hyphen (prerelease) without the `--tag` flag.
-- **Integrity Failure**: Fix the structural issues reported by `npm test` before retrying.
-
 ---
 *Last Updated: 2026-03-22*

package/docs/testing-current-version.md

@@ -0,0 +1,130 @@
+# MindForge v2.0.0-alpha.6: In-Depth Testing Guide (Antigravity)
+
+This document provides a step-by-step rigorous testing flow to validate the entire MindForge framework from a blank project state. It is designed to be shared and logged for architectural review.
+
+## 🏁 Phase 0: Isolated Setup
+1. Create a new empty directory (e.g., `Mind-Forge-Test`): `mkdir Mind-Forge-Test && cd Mind-Forge-Test`
+2. **Linked Alpha Testing** (Simulated Live Publish):
+   - Use the **Absolute Binary Path** to bypass shell PATH configuration issues:
+     ```bash
+     /Users/sairamugge/.vite-plus/js_runtime/node/24.14.0/bin/mindforge-cc --antigravity --local
+     ```
+   - *Confirmation*: Run the command with `--version`. It must show `v2.0.0-alpha.6`.
+3. Verify the local binary exists: `ls agents/bin/install.js` (or `.agent/bin/install.js` if legacy)
+
+## 🏗 Phase 1: Registry & Integrity
+**Objective**: Verify that MindForge correctly registers the project and mirrors commands.
+
+**Command**:
+```bash
+./mindforge:init-project
+```
+
+**Post-Init Verification**:
+- Check `.claude/commands/mindforge/` and `.agent/commands/mindforge/`. They should be identical.
+- Verify the project is in the global registry (optional):
+  ```bash
+  cat ~/.mindforge/registry.json
+  ```
+**Prompt to Agent**:
+> "Initialize this project for me. I am building a simple 'Weather Proxy API' in Node.js. Please set up the `.planning/` directory and registry."
+
+**Success Criteria**:
+- `.planning/PROJECT.md` is created with the Weather Proxy brief.
+- `.mindforge/` metadata directory is populated.
+
+## 📝 Phase 2: Workflow & Planning
+**Objective**: Test the planning engine and dependency mapping.
+
+**Prompt to Agent**:
+> "I need a plan to implement the weather service. Phase 1 should handle the API structure, Phase 2 should handle the weather fetching logic, and Phase 3 should add caching. Generate a detailed plan for Phase 1."
+
+**Command**:
+```bash
+/mindforge:plan-phase 1
+```
+
+**Success Criteria**:
+- `.planning/phases/phase-1/PLAN.md` is generated.
+- Plan status is set to `[ ]` in `task.md`.
+
+## 🤖 Phase 3: Autonomous Execution (The "Walk-Away" Test)
+**Objective**: Test the `/mindforge:auto` engine and state management.
+
+**Command**:
+```bash
+/mindforge:auto --phase 1
+```
+
+**Success Criteria**:
+- MindForge iterates through tasks without human intervention.
+- Code is written to the project (e.g., `index.js`, `routes/`).
+- `.planning/AUDIT.jsonl` is logging every execution step.
+
+## 📊 Phase 4: Observability (Dashboard)
+**Objective**: Test the Real-time Dashboard and SSE Bridge.
+
+**Command**:
+```bash
+/mindforge:dashboard --start --open
+```
+
+**Testing Steps**:
+1. Keep the dashboard open at `http://localhost:7339`.
+2. Run another command (e.g., `/mindforge:health`).
+3. Verify that the "Activity Feed" in the browser updates instantly.
+4. Check the "Metrics" tab for token spend data.
+
+## 🧠 Phase 5: Persistent Memory
+**Objective**: Test the Knowledge Graph retrieval.
+
+**Command**:
+```bash
+/mindforge:remember --search "api structure"
+```
+
+**Success Criteria**:
+- MindForge returns findings from the earlier `/mindforge:init-project` or `/mindforge:plan-phase` steps.
+
+## ⚔️ Phase 6: Multi-Model Hardening
+**Objective**: Test the adversarial cross-review system.
+
+**Command**:
+```bash
+/mindforge:cross-review
+```
+
+**Success Criteria**:
+- MindForge invokes secondary models (GPT/Gemini) to critique the code generated in Phase 3.
+- Review results are logged in `review_results.md`.
+
+## 🚢 Phase 7: Verification & Shipping
+**Objective**: Test the quality gates and release automation.
+
+**Commands**:
+```bash
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+**Success Criteria**:
+- `CHANGELOG.md` is updated.
+- A PR-ready diff is generated.
+
+---
+
+## 🛡 Phase 8: Framework Conflict Check
+**Objective**: Ensure MindForge is isolated from other frameworks.
+
+1. **Port Check**: Verify the dashboard is on `7339` and not conflicting with common framework ports (e.g., 8000, 8080).
+2. **Directory Check**: Ensure no other framework is writing to `.planning/` or `.mindforge/`.
+3. **Process Check**: Run `ps aux | grep mindforge` to ensure only one instance of the SSE bridge is active.
+
+## 📂 Logging for Review
+All Antigravity sessions are logged. To share your results for review, zip and send:
+- `.planning/AUDIT.jsonl` (Full execution history)
+- `CHANGELOG.md` (Outcome summary)
+## 💡 Troubleshooting
+- **Command not found**: Ensure you are using `./mindforge:command` or `/mindforge:command` within the agent.
+- **Wrong Version**: Run `/mindforge:health` and check for "v2.0.0-alpha.6". If it shows "v1.0.5", your installation failed or you are using the global `npx` version.
+- **Registry Error**: Check `~/.mindforge/registry.json` exists; it is now automatically created by the v2 installer.

package/docs/user-guide.md

@@ -1,4 +1,4 @@
-# MindForge User Guide (v2.0.0-alpha.4)
+# MindForge User Guide (v2.0.0-alpha.6)
 
 This guide gets you from install to productive, with the minimum needed to run
 MindForge in a real project. It assumes Node.js 18+.
@@ -152,7 +152,29 @@ Relevant memories are automatically loaded at the start of every session, provid
 
 ---
 
-## 10. Update and migration
+## 10. Real-time Dashboard (v2)
+MindForge provides a premium web-based dashboard for real-time observability of your agent waves, metrics, and team activity.
+
+### Start the Dashboard
+```bash
+/mindforge:dashboard --start --open
+```
+This will start the Express-based SSE bridge and open `http://localhost:7339` in your default browser.
+
+### Features
+- **Live Activity**: Real-time stream of audit logs and agent status.
+- **Metrics & Costs**: Live visualization of token spend and session quality.
+- **Browser Governance**: Approve or reject Tier 2/3 changes directly from the UI.
+- **Team Feed**: See what other agents are doing in a multi-agent environment.
+
+### Stop the Dashboard
+```bash
+/mindforge:dashboard --stop
+```
+
+---
+
+## 11. Update and migration
 ### Check for updates
 ```
 /mindforge:update

package/docs/usp-features.md

@@ -1,4 +1,4 @@
-# MindForge v2.0.0 — Unique Selling Points, Features, and Best Practices (v2.0.0-alpha.4)
+# MindForge v2.0.0 — Unique Selling Points, Features, and Best Practices (v2.0.0-alpha.6)
 
 This document summarizes what makes MindForge v2.0.0 distinct, what features
 are included in the latest alpha release, and how to use them effectively.
@@ -43,6 +43,9 @@ are included in the latest alpha release, and how to use them effectively.
 11. **Persistent Knowledge Graph (v2)**
     - Captures and ranks engineering context (decisions, bug patterns, preferences) across project sessions using TF-IDF and confidence reinforcement.
 
+12. **Real-time Observability Dashboard (v2)**
+    - High-fidelity web interface for live audit streams, metrics visualization, and browser-based governance with zero performance overhead.
+
 ---
 
 ## Feature Set (v1.0.0)
@@ -200,6 +203,17 @@ preserving scope (local vs global).
 
 ---
 
+### 16. Real-time Dashboard (v2)
+**What it does:** Web-based control plane for observing agent waves, costs, and quality metrics in real-time.
+
+**How to use:**
+```bash
+/mindforge:dashboard --start --open
+```
+Access at `http://localhost:7339` (Localhost-only for security).
+
+---
+
 ### 15. SDK (TypeScript)
 **What it does:** Programmatic access to health, audit log, event stream, and commands.