mindforge-cc 11.9.7 → 11.9.8

package/.agent/skills/mindforge-join-discord/SKILL.md

@@ -1,19 +1,22 @@
 ---
 name: "mindforge-join-discord"
-description: "Join the MindForge Discord community"
+description: "Find the current MindForge community/support channel"
 ---
 
 
 <objective>
-Display the Discord invite link for the MindForge community server.
+Display the current, working channel for MindForge community discussion and support.
 </objective>
 
 <output>
-# Join the MindForge Discord
+# MindForge community & support
 
-Connect with other MindForge users, get help, share what you're building, and stay updated.
+The `discord.gg/mindforge` invite that used to be linked here is no longer valid (verified
+against Discord's own invite API, not just an HTTP redirect check). GitHub Discussions is the
+current, working channel:
 
-**Invite link:** https://discord.gg/mindforge
+**https://github.com/sairam0424/MindForge/discussions**
 
-Click the link or paste it into your browser to join.
+For a specific bug or feature request, use the issue templates instead:
+https://github.com/sairam0424/MindForge/issues/new/choose
 </output>

package/.mindforge/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "11.9.7",
+  "version": "11.9.8",
   "environment": "development",
   "governance": {
     "drift_threshold": 0.75,

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [11.9.8] — 2026-09-21 — What the README claims, verified line by line
+
+Patch release. v11.9.7's README rewrite got a literal, end-to-end audit: every command it
+documents actually run — real `npx` installs, a real Homebrew install/uninstall cycle, a
+real `npm i mindforge-sdk`, live registry checks — instead of re-reading the prose. 113
+claims checked: 98 held up, 14 didn't, 1 couldn't be verified either way. All 14 confirmed
+failures are fixed here.
+
+### Fixed
+
+**Two real bugs, not just docs**
+
+- `--runtime claude,cursor` (or any comma-separated runtime list) crashed the installer
+  outright ("Cannot read properties of undefined (reading 'localDir')"). `--all` already
+  expanded into a real multi-runtime loop; a comma-separated `--runtime` value was never
+  split into it, so it was looked up as the literal key `RUNTIMES['claude,cursor']`, which
+  doesn't exist. Fixed, plus a graceful "Unknown runtime(s)" exit for typos instead of a raw
+  crash.
+- `--minimal` claimed "no persona library" but shipped all 216 personas anyway — the
+  `minimalEntries` allowlist in `bin/installer-core.js` explicitly included `'personas'`.
+  Removed.
+
+**Twelve documentation inaccuracies**
+
+- Removed a `[--ads]` flag hint on `/mindforge:plan-phase` that was never wired into the
+  live command spec — it only exists in a much larger, never-ported legacy workflow file.
+- Reworded the bare `npx mindforge-cc@latest` "auto-detects your runtime" claim: real
+  detection only runs inside the interactive TTY wizard (and even there it's a pre-selected
+  default you still confirm); every non-interactive invocation (CI, piped stdin, scripted)
+  hardcodes `--claude`.
+- Disclosed that `/mindforge:health --repair` is documented in the command spec but not
+  wired into the CLI backing path — the flag is silently dropped, output is byte-identical
+  to plain `health`.
+- Fixed `/mindforge:tokens --profile` — that flag doesn't exist; swapped in a real one
+  (`--optimise`) and listed the actual flag set.
+- Disclosed that `node bin/mindforge-cli.js spawn <persona>` is a v1.0 stub that exits 1
+  with "NOT IMPLEMENTED", not a working scripted path.
+- Corrected the License section's copyright holder to match `LICENSE` exactly.
+- Fixed the architecture diagram's skill count: only 232 of the 355 skills live under
+  `.mindforge/` (engine tier); the other 123 are under `.agent/skills/` (extended tier).
+- Corrected `bin/`'s "~22K LOC" claim to the measured ~32K raw / ~25K stripped-of-comments.
+- Narrowed the Config reference doc-table row — that doc never mentions
+  `.mindforge/config.json`.
+- Reworded the Threat model doc-table row — that file is explicitly historical (v1.0.0-era),
+  not re-reviewed against v11.x, and redirects to `SECURITY.md`.
+- Reworded the USP-features doc-table row — that file has zero competitor comparison
+  content; it's the same honesty pass applied to MindForge's own features.
+- Disclosed that the `mindforge-plugin-*` namespace has zero packages published under it
+  today.
+
 ## [11.9.7] — 2026-09-20 — The install banner stops contradicting itself
 
 Patch release. Found by actually running the documented install command

package/MINDFORGE.md

@@ -1,9 +1,9 @@
-# MINDFORGE.md — Parameter Registry (v11.9.7)
+# MINDFORGE.md — Parameter Registry (v11.9.8)
 
 ## 1. IDENTITY & VERSIONING
 
 [NAME]    = MindForge
-[VERSION] = 11.9.7
+[VERSION] = 11.9.8
 [STABLE]  = true
 [MODE]    = "Platform Sovereign"
 [REQUIRED_CORE_VERSION] = 11.9.1

package/README.md

@@ -4,47 +4,208 @@
 [![npm downloads](https://img.shields.io/npm/dm/mindforge-cc.svg)](https://www.npmjs.com/package/mindforge-cc)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
+[![CI](https://github.com/sairam0424/MindForge/actions/workflows/mindforge-ci.yml/badge.svg)](https://github.com/sairam0424/MindForge/actions/workflows/mindforge-ci.yml)
 
-**An agentic intelligence framework for Claude Code** — orchestrates multi-agent workflows with governance, memory, and autonomous execution. Production-hardened with true parallelism, streaming SDK, and zero-trust security. Install once, get structured AI-driven development with built-in quality gates.
+**A governance and orchestration layer for Claude Code.**
 
-**At a glance:** 221 slash commands · 355 skills (232 auto-triggered + 123 explicit) · 216 personas · 164 installable subagents · 35 pre-built multi-agent dynamic workflows · a tamper-evident audit hash-chain · cost-aware routing across Anthropic/OpenAI/Gemini/Bedrock/Ollama · a local-first knowledge graph on zero-native-dependency SQLite (sql.js) · a live Express+SSE dashboard. Ships as an npm package, a Claude Code plugin, and an MCP server.
+Claude Code alone runs one agent in one context. MindForge adds the parts that don't fit in a
+single context window: skills that auto-load by trigger, personas you can call by name, a
+wave-based executor that fans work out to fresh-context subagents and commits per task, a
+tamper-evident audit chain, and cost-aware routing across providers. Install it once and get
+`/mindforge:plan-phase` → `/mindforge:execute-phase` → `/mindforge:verify-phase` → `/mindforge:ship`
+as your actual working loop, not a slogan.
 
-**Jump to:** [Latest release](#latest-release) · [What is actually enforced](#what-is-actually-enforced) · [Install](#install) · [Quick start](#quick-start-new-project) · [Documentation](#documentation) · [Core workflow](#core-workflow) · [Dynamic workflows](#dynamic-workflow-library)
+<!-- TODO: record a ~30s terminal cast of one real /mindforge:plan-phase -> /mindforge:execute-phase
+     run (asciinema or GIF) and embed it here. Every comparable README in this space leads with a
+     visual in the first 15 lines; this is currently the single biggest gap. -->
+
+**Jump to:** [Latest release](#latest-release) · [What you get](#what-you-get) · [What is actually enforced](#what-is-actually-enforced) · [Install](#install) · [Quick start](#quick-start-new-project) · [Documentation](#documentation) · [Core workflow](#core-workflow) · [Dynamic workflows](#dynamic-workflow-library)
+
+---
+
+## What you get
+
+| | Capability | Detail |
+|---|---|---|
+| 🧩 | **221 slash commands** | `/mindforge:plan-phase`, `/mindforge:execute-phase`, `/mindforge:ship`, and 218 more — [full reference](docs/commands-reference.md) |
+| 🛠️ | **355 skills** | 232 auto-triggered by keyword match (engine tier) + 123 explicit, invoked by name (extended tier) |
+| 🎭 | **216 personas** | In-session role overlays via `/mindforge:agent <name>` — same context, different behavioral spec |
+| 🤖 | **164 subagents** | Genuine isolated-context Claude-Code-native subagent definitions — a separate mechanism from personas, see [docs/PERSONAS.md](docs/PERSONAS.md) |
+| 🔀 | **35 dynamic workflows** | Multi-agent fan-out scripts across 5 tiers (Research, Dev, Ops, Intelligence, Beast) — [workflow atlas](docs/workflow-atlas.md) |
+| 🔒 | **Tamper-evident audit chain** | SHA-256 hash-linked `.planning/AUDIT.jsonl`; verify independently with `node bin/verify-audit.js` |
+| 💸 | **Cost-aware model routing** | Anthropic / OpenAI / Gemini / Bedrock / Ollama, routed by task difficulty tier |
+| 🧠 | **Local-first knowledge graph** | Zero-native-dependency SQLite (`sql.js` / WASM) — no native build step |
+| 📊 | **Live dashboard** | Express + SSE at `localhost:7339` |
+
+Ships three ways: an npm package (`npx mindforge-cc@latest`), a Claude Code plugin marketplace
+entry, and an MCP server.
+
+---
+
+## Install
+
+Pick whichever matches how you work — all of these are real, live channels.
+
+### `npx` (recommended)
+
+Writes `.mindforge/` governance, memory, and planning into your project:
+
+```bash
+npx mindforge-cc@latest --claude --local      # Claude Code, this project only
+npx mindforge-cc@latest --antigravity --local # Antigravity, this project only
+npx mindforge-cc@latest                       # interactive wizard, pre-selects a detected runtime
+```
+
+The bare form only detects anything inside an interactive TTY wizard session, where it pre-selects
+— you still confirm — whichever runtime it finds. Run it non-interactively (CI, piped, scripted,
+or anywhere `stdin` isn't a TTY) and it skips the wizard entirely and installs `--claude` by
+default, regardless of what's actually on the machine.
+
+**Global** (system-wide, for your primary AI coding runtime):
+
+```bash
+npx mindforge-cc@latest --claude --global
+```
+
+(`npm install -g mindforge-cc@latest` only puts the `mindforge-cc`/`mindforge` binaries on your
+PATH — it doesn't select a runtime or write anything. Run the command above, or the equivalent
+`mindforge-cc --claude --global` once installed, to actually scaffold a global setup.)
+
+**Other runtimes** — same flag pattern, swap `--global`/`--local`:
+
+| Runtime | Flag |
+|---|---|
+| Claude Code | `--claude` |
+| Antigravity | `--antigravity` |
+| Cursor | `--cursor` |
+| GitHub Copilot | `--copilot` |
+| Gemini CLI | `--gemini` |
+
+**Advanced:** `--runtime claude,cursor` (combined runtimes) · `--with-utils` (installs local `bin/` utilities) · `--minimal` (essential scaffolding only, no persona library) · `--force` (rewrite an existing `.mindforge/MINDFORGE-SCHEMA.json` with the current, stricter schema)
+
+### Claude Code plugin marketplace
+
+No project files written — the plugin's hooks fire, see [What is actually enforced](#what-is-actually-enforced) for what that does and does not cover.
+
+```bash
+/plugin marketplace add sairam0424/MindForge
+/plugin install mindforge@mindforge
+```
+
+Prefer just a slice (e.g. Python agents)? `mindforge-lang@mindforge` and 9 other focused packs exist — see [docs/plugin-installation.md](docs/plugin-installation.md) for all 10, token-budget guidance, and team setup.
+
+### Standalone MCP server
+
+```bash
+claude mcp add mindforge -- npx -y mindforge-mcp-server
+```
+
+Exposes 8 tools over stdio (6 read-only, 1 guarded write, 1 guarded browse proxy). Also listed on
+the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.sairam0424/mindforge`
+— that entry is republished manually and can lag; check what it actually serves before relying on
+it, or install `mindforge-mcp-server` from npm directly to pin a version.
+
+### Homebrew
+
+```bash
+brew install sairam0424/tap/mindforge
+```
+
+### SDK
+
+Build on MindForge programmatically:
+
+```bash
+npm i mindforge-sdk
+```
+
+**Upgrading from 11.9.x?** The installer does not overwrite an existing
+`.mindforge/MINDFORGE-SCHEMA.json`, so 11.9.2's armed config validator keeps the older
+permissive schema on a plain upgrade — run with `--force` for the stricter gate. The daily cost
+cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in 11.9.2 (11.9.3
+arms it), and an upgrade never rewrites an existing `MINDFORGE.md` — add
+`[COST_HARD_LIMIT_USD] = 25.00` yourself if yours predates the key.
+
+Full install matrix, plugin packs, and team-setup guidance: [docs/getting-started.md](docs/getting-started.md).
+
+---
+
+## Verify
+
+These `/mindforge:*` commands require the Claude Code plugin or an `npx`/Homebrew framework
+install — the standalone MCP server exposes MCP tools instead, and `mindforge-sdk` exposes a
+programmatic API; neither installs these slash commands.
+
+```bash
+/mindforge:health              # framework + installation health check
+/mindforge:health --repair     # documented in the command spec, but NOT wired into the CLI
+                                # backing path — silently ignored, output is byte-identical to plain health
+/mindforge:status              # project status snapshot
+/mindforge:next                # auto-discover your first task
+```
+
+Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
+
+---
+
+## Quick start (new project)
+
+```bash
+/mindforge:init-project
+/mindforge:plan-phase 1
+/mindforge:execute-phase 1
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+## Quick start (existing codebase)
+
+```bash
+/mindforge:map-codebase
+/mindforge:do I want to plan the next phase
+/mindforge:plan-phase 1
+```
 
 ---
 
 ## Latest release
 
-**v11.9.7** (2026-09-20) — The install banner stops contradicting itself. Found by
-actually running v11.9.6's own documented install command in a clean project instead of
-stopping at `--version`: the top banner claimed `SOVEREIGN INTELLIGENCE v8.1.1` while the
-install activation line two screens later said `v8.2.0` for the same subsystem, and claimed
-`PQAS ... Enabled` right before accurately disclosing it's simulated and off by default a
-few lines down. Both fixed, plus a dead `docs.mindforge.cc` link and a persona-count doc
-regression (218 → back to the correct 216) introduced by v11.9.6's own honesty pass. No
-new features. See [RELEASENOTES.md](./RELEASENOTES.md) or [CHANGELOG.md](./CHANGELOG.md).
-
-The previous release, **v11.9.6**, was the release-readiness pass before pointing real,
-external users at the project for the first time: fixed a crash in `/mindforge:learn`, a
-token-leak in the browser daemon, three dashboard panels that silently rendered nothing, a
-stale Homebrew formula, and docs describing PQAS/ZTAI/"Pillar"-numbered subsystems as live
-guarantees when the code already self-labels them simulated. **v11.9.5** fixed a release
-pipeline that could strand itself mid-publish and shipped `mindforge-sdk` for the first
-time since 11.8.0, with provenance. **v11.9.4**, before that, is where the hook gates
-started actually registering: 11.9.3
-shipped the code and then declined to run it on essentially every project. Measured against
-the published tarballs — 11.9.3: **11 hook scripts installed, 0 registered**; 11.9.4:
-**8 registered, 3 deny-class verified blocking**. That **behaviour change under a patch
-bump** still applies — the installer writes `.claude/settings.json` where it previously
-declined, merging append-only and backing up first. See the BREAKING section in
-[CHANGELOG.md](./CHANGELOG.md).
+**v11.9.8** (2026-09-21) — What the README claims, verified line by line. v11.9.7's README
+rewrite got a literal, end-to-end audit: every command it documents actually run — real
+`npx` installs, a real Homebrew install/uninstall cycle, a real `npm i mindforge-sdk`, live
+registry checks — instead of re-read for plausibility. 113 claims checked, 98 held up, 14
+didn't, 1 couldn't be verified either way. Two of the 14 were real bugs:
+`--runtime claude,cursor` crashed the installer outright, and `--minimal` claimed "no
+persona library" but shipped all 216 anyway. Both fixed. The other twelve were
+documentation catching up to what the code actually does — a removed `[--ads]` hint that
+was never real, the auto-detect claim, `--repair`, `--profile`, the CLI `spawn` stub, the
+License holder, the skill-tier split, the `bin/` line count, three Documentation-table rows
+that overstated their linked docs, and the `mindforge-plugin-*` namespace's empty catalog.
+See [RELEASENOTES.md](./RELEASENOTES.md) or [CHANGELOG.md](./CHANGELOG.md).
+
+The previous release, **v11.9.7**, fixed a version self-contradiction and a false "Enabled"
+claim in the install banner, a dead `docs.mindforge.cc` link, and a persona-count doc
+regression (218 → back to the correct 216) introduced by v11.9.6's own honesty pass.
+**v11.9.6** was the release-readiness pass before pointing real, external users at the
+project for the first time: fixed a crash in `/mindforge:learn`, a token-leak in the
+browser daemon, three dashboard panels that silently rendered nothing, a stale Homebrew
+formula, and docs describing PQAS/ZTAI/"Pillar"-numbered subsystems as live guarantees when
+the code already self-labels them simulated. **v11.9.5** fixed a release pipeline that
+could strand itself mid-publish and shipped `mindforge-sdk` for the first time since
+11.8.0, with provenance. **v11.9.4**, before that, is where the hook gates started actually
+registering: 11.9.3 shipped the code and then declined to run it on essentially every
+project. Measured against the published tarballs — 11.9.3: **11 hook scripts installed, 0
+registered**; 11.9.4: **8 registered, 3 deny-class verified blocking**. That **behaviour
+change under a patch bump** still applies — the installer writes `.claude/settings.json`
+where it previously declined, merging append-only and backing up first. See the BREAKING
+section in [CHANGELOG.md](./CHANGELOG.md).
 
 ---
 
 ## What is actually enforced
 
-Read this before the install instructions. MindForge ships a large corpus of agent
-instructions — commands, skills, personas, protocols — and those are advisory: they work by
+Read this before you rely on anything below blocking a bad command. MindForge ships a large
+corpus of agent instructions — commands, skills, personas, protocols — and those are advisory: they work by
 being in the model's context, and a model can decline them. The parts that would *block* an
 action are hooks. Through 11.9.2 **no channel registered them.** 11.9.3 added the registration code
 but it declined to run on almost every project, so in practice nothing was enforced there either.
@@ -94,91 +255,64 @@ instructions — review what you install. The audit chain is verifiable today
 
 ---
 
-## Install
-
-Claude Code plugin marketplace (no project files written). The plugin's hooks now fire — see
-*What is actually enforced* above for what that does and does not cover.
-
-```bash
-/plugin marketplace add sairam0424/MindForge
-/plugin install mindforge@mindforge
-```
-
-Or the full framework engine via `npx` (writes `.mindforge/` governance, memory, and planning into your project):
-
-```bash
-npx mindforge-cc@latest --claude --local
-```
-
-All install channels (global, local, Antigravity, Cursor, Copilot, Gemini CLI, MCP server, combined runtimes, `--minimal`): see [docs/getting-started.md](docs/getting-started.md).
-
-**Upgrading from 11.9.x?** The installer does not overwrite an existing
-`.mindforge/MINDFORGE-SCHEMA.json`, so 11.9.2's armed config validator keeps the older
-permissive schema on a plain upgrade. Run with `--force` if you want the stricter gate. The
-daily cost cap declared as `[COST_HARD_LIMIT_USD]` in `MINDFORGE.md` was **not enforced** in
-11.9.2; 11.9.3 arms it. An upgrade never rewrites an existing `MINDFORGE.md`, so if yours
-predates the key the cap stays off — add `[COST_HARD_LIMIT_USD] = 25.00` to turn it on.
-
----
-
-## Verify
+## How it fits together
 
-```bash
-/mindforge:health              # framework + installation health check
-/mindforge:health --repair     # fix anything the health check flags
-/mindforge:status              # project status snapshot
-/mindforge:next                # auto-discover your first task
 ```
-
-Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
-
----
-
-## Quick start (new project)
-
-```bash
-/mindforge:init-project
-/mindforge:plan-phase 1
-/mindforge:execute-phase 1
-/mindforge:verify-phase 1
-/mindforge:ship 1
+                     /mindforge:plan-phase N
+                              |
+                              v
+   Skill Loader (trigger-match, tier: Project > Org > Core)
+                              |
+                              v
+        Context Injector (<=60K tokens)  --> Cost Router
+                              |             (Haiku / Sonnet / Opus / Gemini,
+                              v              by task difficulty)
+      Fresh-context Subagent (implement -> self-verify -> commit)
+                              |
+                              v
+   Verification (build / typecheck / lint / test / security / diff)
+                              |
+                              v
+        Handoff (.planning/HANDOFF.json + AUDIT.jsonl)
 ```
 
-## Quick start (existing codebase)
-
-```bash
-/mindforge:map-codebase
-/mindforge:do I want to plan the next phase
-/mindforge:plan-phase 1
-```
+Four layers underlie this, top to bottom: **Interface** (`.claude/`, `.agent/` — the 221 slash
+commands and hooks), **Engine specs** (`.mindforge/` — 232 of the 355 skills plus 216 personas and
+`config.json` runtime knobs; the other 123 skills are extended-tier, under `.agent/skills/`),
+**Execution** (`bin/`, ~32K raw / ~25K stripped-of-comments LOC — the wave executor, governance,
+memory, and dashboard code that actually runs), and **Persistence** (`.planning/` — `STATE.md`,
+the audit chain, resumable `HANDOFF.json`). Edit behavior in layer 2 where possible; layer 3 is
+the only place with real enforcement, per *What is actually enforced* above.
 
 ---
 
 ## Documentation
 
-- **User Guide:** [docs/user-guide.md](docs/user-guide.md)
-- **Getting started:** [docs/getting-started.md](docs/getting-started.md)
-- **Quick verify:** [docs/quick-verify.md](docs/quick-verify.md)
-- **Troubleshooting:** [docs/troubleshooting.md](docs/troubleshooting.md)
-- **FAQ:** [docs/faq.md](docs/faq.md)
-- **Full tutorial:** [docs/tutorial.md](docs/tutorial.md)
-- **Commands reference (full):** [docs/commands-reference.md](docs/commands-reference.md)
-- **Commands (quick):** [docs/References/commands.md](docs/References/commands.md)
-- **Config reference:** [docs/References/config-reference.md](docs/References/config-reference.md)
-- **SDK:** [docs/References/sdk-api.md](docs/References/sdk-api.md)
-- **Skills:** [docs/References/skills-api.md](docs/References/skills-api.md)
-- **Audit events:** [docs/References/audit-events.md](docs/References/audit-events.md)
-- **Upgrade guide:** [docs/upgrade.md](docs/upgrade.md)
-- **Workflow atlas:** [docs/workflow-atlas.md](docs/workflow-atlas.md)
-- **Security:** [SECURITY.md](SECURITY.md) (credentials are read from env vars and never committed to the repository)
-- **Threat model:** [docs/security/threat-model.md](docs/security/threat-model.md)
-- **Architecture:** [docs/architecture/README.md](docs/architecture/README.md)
-- **Contributing:** [docs/contributing/CONTRIBUTING.md](docs/contributing/CONTRIBUTING.md)
-- **Release notes:** [RELEASENOTES.md](RELEASENOTES.md)
-- **CI quickstart:** [docs/ci-quickstart.md](docs/ci-quickstart.md)
-- **Requirements:** [docs/requirements.md](docs/requirements.md)
-- **Release checklist guide:** [docs/release-checklist-guide.md](docs/release-checklist-guide.md)
-- **USPs and features:** [docs/usp-features.md](docs/usp-features.md)
+Six categories, read in this order the first time:
+
+| Category | Doc | Read this when |
+|---|---|---|
+| Start here | [Getting started](docs/getting-started.md) | Installing for the first time |
+| Start here | [Quick verify](docs/quick-verify.md) | Right after install — confirm it actually works |
+| Start here | [User guide](docs/user-guide.md) | Learning the day-to-day command loop |
+| Start here | [Full tutorial](docs/tutorial.md) | Want a guided walkthrough instead of reference docs |
+| Reference | [Commands (full)](docs/commands-reference.md) / [Commands (quick)](docs/References/commands.md) | Looking up a specific `/mindforge:*` command |
+| Reference | [Config reference](docs/References/config-reference.md) | Editing `MINDFORGE.md` — this doc doesn't cover `.mindforge/config.json` |
+| Reference | [SDK API](docs/References/sdk-api.md) / [Skills API](docs/References/skills-api.md) | Building on `mindforge-sdk` or authoring a new skill |
+| Reference | [Audit events](docs/References/audit-events.md) | Parsing `.planning/AUDIT.jsonl` |
+| Reference | [Workflow atlas](docs/workflow-atlas.md) | Choosing one of the 35 dynamic workflows |
+| Reference | [Requirements](docs/requirements.md) | Checking supported Node/OS versions before install |
+| When something's wrong | [Troubleshooting](docs/troubleshooting.md) | A command or hook isn't behaving as documented |
+| When something's wrong | [FAQ](docs/faq.md) | Common questions before filing an issue |
+| When something's wrong | [Upgrade guide](docs/upgrade.md) | Moving between major/minor versions |
+| Security | [SECURITY.md](SECURITY.md) | Reporting a vulnerability; credentials are read from env vars and never committed |
+| Security | [Threat model](docs/security/threat-model.md) | Historical only — scoped to the v1.0.0 predecessor, not re-reviewed against v11.x; see [SECURITY.md](SECURITY.md) for what's actually enforced today |
+| Contributing | [Architecture](docs/architecture/README.md) | Understanding the codebase before sending a PR |
+| Contributing | [Contributing guide](docs/contributing/CONTRIBUTING.md) | Sending a PR |
+| Contributing | [CI quickstart](docs/ci-quickstart.md) | Understanding what CI checks before you push |
+| Contributing | [Release checklist](docs/release-checklist-guide.md) | Cutting a release |
+| Reference | [USPs and features](docs/usp-features.md) | The same "measured, not asserted" honesty pass applied to what's actually shipped — no competitor comparison |
+| Release notes | [RELEASENOTES.md](RELEASENOTES.md) | What changed, in prose, per version |
 
 ---
 
@@ -187,7 +321,7 @@ Full verification walkthrough: [docs/quick-verify.md](docs/quick-verify.md).
 | Command | What it does |
 | :--- | :--- |
 | `/mindforge:init-project` | Requirements interview → creates `PROJECT.md`, `REQUIREMENTS.md`, `STATE.md` |
-| `/mindforge:plan-phase 1 [--ads]` | Discuss scope, research the domain in parallel, create atomic XML task plans |
+| `/mindforge:plan-phase 1` | Discuss scope, research the domain in parallel, create atomic XML task plans |
 | `/mindforge:execute-phase 1` | Wave-based parallel execution, one commit per task, automated verification |
 | `/mindforge:verify-phase 1` | Human acceptance testing, debug agent on failures, UAT sign-off |
 | `/mindforge:ship 1` | Changelog generation, final quality gates, PR creation |
@@ -207,13 +341,18 @@ Full, verified 35-workflow table by tier: [docs/workflow-atlas.md](docs/workflow
 
 ---
 
-## Execution Modes
+<details>
+<summary><strong>Execution modes</strong></summary>
 
 MindForge supports multiple interaction models to fit your engineering workflow:
 
 - **In-IDE Orchestration**: Use `/mindforge:agent <persona>` for real-time delegation.
 - **Enterprise Workflows**: Specialized commands like `/mindforge:wf-tdd-sprint` and `/mindforge:plan-phase`.
-- **CLI Automation**: Run `node bin/mindforge-cli.js spawn <persona>` for scripted tasks.
+- **CLI Automation**: `node bin/mindforge-cli.js spawn <persona>` exists but is a v1.0 stub — it
+  prints "NOT IMPLEMENTED in v1.0" and exits 1, redirecting you to `/mindforge:auto` or
+  `/mindforge:next` instead.
+
+</details>
 
 ---
 
@@ -223,27 +362,32 @@ Run `/mindforge:update` (add `--apply` to install) — see [docs/upgrade.md](doc
 
 ---
 
-## Plugin system (v1.0.0)
+<details>
+<summary><strong>Plugin system (v1.0.0)</strong></summary>
 
-Plugins extend MindForge via the `mindforge-plugin-*` namespace.
+Plugins extend MindForge via the `mindforge-plugin-*` namespace. No packages are currently
+published under it — this is the mechanism, not a catalog.
 
-```
+```bash
 /mindforge:plugins list
 /mindforge:plugins install mindforge-plugin-<name>
 /mindforge:plugins validate
 ```
 
+</details>
+
 ---
 
 ## Token usage profiling
 
 ```
-/mindforge:tokens --profile
+/mindforge:tokens --optimise
 ```
-See `.mindforge/production/token-optimiser.md`.
+(`--profile` doesn't exist; real flags are `--phase N`, `--session ID`, `--window short|medium|long`,
+and `--optimise`.) See `.mindforge/production/token-optimiser.md`.
 
 ---
 
 ## License
 
-MIT © 2026 MindForge Team
+MIT © 2026 Sairam Ugge (GitHub: Sairam0000)

package/RELEASENOTES.md

@@ -1,5 +1,34 @@
 # Release Notes
 
+## v11.9.8 — 2026-09-21 — What the README claims, verified line by line
+
+### Why this release exists
+
+v11.9.7 shipped a full README rewrite. This release is what happened when that rewrite got
+a literal, end-to-end audit — every command it documents actually run in a real environment
+(real `npx` installs, a real Homebrew install/uninstall cycle, a real `npm i mindforge-sdk`,
+live registry checks) rather than re-read for plausibility. Of 113 claims checked, 98 held
+up, 14 didn't, and 1 couldn't be verified either way.
+
+### The user-visible part
+
+**Two of the 14 were real bugs, not just wording.** `--runtime claude,cursor` — or any
+comma-separated runtime list — crashed the installer outright; it's fixed, and an unknown
+runtime name now exits cleanly with a clear message instead of a raw crash. `--minimal`
+claimed "no persona library" but silently installed all 216 personas anyway; it now
+installs none, as documented.
+
+**The other twelve are documentation catching up to what the code actually does:** the
+bare `npx mindforge-cc@latest` "auto-detects your runtime" claim (real detection only
+happens inside the interactive wizard, and even there you still confirm it — every
+non-interactive run defaults to `--claude`), an `--ads` flag on `/mindforge:plan-phase`
+that was never real, `/mindforge:health --repair` silently doing nothing, a `--profile`
+flag on `/mindforge:tokens` that doesn't exist, a CLI `spawn` command that's a v1.0 stub,
+the License section's copyright holder, the skill-tier split in the architecture diagram,
+the `bin/` line-count figure, three Documentation-table rows that overstated what their
+linked docs actually cover, and the `mindforge-plugin-*` namespace, which has zero
+packages published under it today.
+
 ## v11.9.7 — 2026-09-20 — The install banner stops contradicting itself
 
 ### Why this release exists

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-> **Current version:** 11.9.7 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
+> **Current version:** 11.9.8 | **npm audit:** 0 vulnerabilities across root, sdk, mcp-server
 
 ## Supported Versions
 
@@ -90,7 +90,8 @@ We follow responsible disclosure practices. We will credit reporters in the rele
 ### Supply Chain
 
 - **Zero native dependencies** — The removal of `better-sqlite3` eliminates the entire native compilation toolchain (node-gyp, Python, C++ compiler) from the install process, reducing the attack surface.
-- **Dependabot enabled** — Automated weekly scans for vulnerable npm dependencies and monthly GitHub Actions version updates.
+- **Dependabot enabled** — Automated weekly scans for vulnerable npm dependencies (root, `sdk/`, and `mcp-server/` each tracked independently) and monthly GitHub Actions version updates.
+- **SBOM available** — GitHub generates a full SPDX software bill of materials from the dependency graph; export it from the repo's Insights tab, or via the API: `gh api repos/sairam0424/MindForge/dependency-graph/sbom/generate-report` returns an `sbom_url`, poll it until it 302s to a download. (The older single-call `.../dependency-graph/sbom` endpoint still works today but GitHub is retiring it on 2026-11-13 — use the generate/fetch flow above for anything meant to keep working past that date.)
 - **CODEOWNERS enforcement** — Changes to `bin/governance/`, `bin/engine/`, and the SDK require review from designated security owners.
 - **.npmignore** — Prevents accidental publication of secrets, test fixtures, planning state, and intelligence logs.
 

package/bin/installer-core.js

@@ -882,7 +882,10 @@ async function install(runtime, scope, options = {}) {
       if (minimal) {
         const minimalEntries = new Set([
           'MINDFORGE-SCHEMA.json',
-          'engine', 'org', 'governance', 'integrations', 'personas', 'skills', 'team'
+          // 'personas' deliberately excluded: --minimal's whole point is "no persona library"
+          // (README.md, docs/getting-started.md). It was accidentally left in this allowlist,
+          // so a --minimal install shipped the full 216-persona set anyway.
+          'engine', 'org', 'governance', 'integrations', 'skills', 'team'
         ]);
         fsu.ensureDir(forgeDst);
         for (const entry of fs.readdirSync(forgeSrc, { withFileTypes: true })) {
@@ -1338,7 +1341,17 @@ async function run(args) {
     return;
   }
 
-  const runtimes = runtime === 'all' ? Object.keys(RUNTIMES) : [runtime];
+  const runtimes = runtime === 'all'
+    ? Object.keys(RUNTIMES)
+    : runtime.split(',').map((r) => r.trim()).filter(Boolean);
+
+  const unknownRuntimes = runtimes.filter((rt) => !RUNTIMES[rt]);
+  if (unknownRuntimes.length) {
+    console.error(
+      `Unknown runtime(s): ${unknownRuntimes.join(', ')}. Valid: ${Object.keys(RUNTIMES).join(', ')}, all`
+    );
+    process.exit(1);
+  }
 
   for (const rt of runtimes) {
     if (isUninstall)  await uninstall(rt, scope, options);

package/bin/wizard/theme.js

@@ -76,7 +76,7 @@ const Theme = {
     console.log(`  ${this.colors.dim('│')}`);
     console.log(`  ${this.colors.dim('│')}  ${this.colors.cyan('⭐ HELP US GROW:')}`);
     console.log(`  ${this.colors.dim('│')}    - GitHub:  ${this.colors.dim('https://github.com/sairam0424/MindForge')}`);
-    console.log(`  ${this.colors.dim('│')}    - Discord: ${this.colors.dim('https://discord.gg/mindforge')}`);
+    console.log(`  ${this.colors.dim('│')}    - Discussions: ${this.colors.dim('https://github.com/sairam0424/MindForge/discussions')}`);
     console.log(`  ${this.colors.dim('│')}    - Docs:    ${this.colors.dim('https://github.com/sairam0424/MindForge#documentation')}`);
     console.log(`  ${this.colors.dim('│')}`);
     console.log(`  ${this.colors.dim('—'.repeat(80))}\n`);

package/changelogs/v11.9.8.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## [11.9.8] — 2026-09-21 — What the README claims, verified line by line
+
+Patch release. v11.9.7's README rewrite got a literal, end-to-end audit: every command it
+documents actually run — real `npx` installs, a real Homebrew install/uninstall cycle, a
+real `npm i mindforge-sdk`, live registry checks — instead of re-reading the prose. 113
+claims checked: 98 held up, 14 didn't, 1 couldn't be verified either way. All 14 confirmed
+failures are fixed here.
+
+### Fixed
+
+**Two real bugs, not just docs**
+
+- `--runtime claude,cursor` (or any comma-separated runtime list) crashed the installer
+  outright ("Cannot read properties of undefined (reading 'localDir')"). `--all` already
+  expanded into a real multi-runtime loop; a comma-separated `--runtime` value was never
+  split into it, so it was looked up as the literal key `RUNTIMES['claude,cursor']`, which
+  doesn't exist. Fixed, plus a graceful "Unknown runtime(s)" exit for typos instead of a raw
+  crash.
+- `--minimal` claimed "no persona library" but shipped all 216 personas anyway — the
+  `minimalEntries` allowlist in `bin/installer-core.js` explicitly included `'personas'`.
+  Removed.
+
+**Twelve documentation inaccuracies**
+
+- Removed a `[--ads]` flag hint on `/mindforge:plan-phase` that was never wired into the
+  live command spec — it only exists in a much larger, never-ported legacy workflow file.
+- Reworded the bare `npx mindforge-cc@latest` "auto-detects your runtime" claim: real
+  detection only runs inside the interactive TTY wizard (and even there it's a pre-selected
+  default you still confirm); every non-interactive invocation (CI, piped stdin, scripted)
+  hardcodes `--claude`.
+- Disclosed that `/mindforge:health --repair` is documented in the command spec but not
+  wired into the CLI backing path — the flag is silently dropped, output is byte-identical
+  to plain `health`.
+- Fixed `/mindforge:tokens --profile` — that flag doesn't exist; swapped in a real one
+  (`--optimise`) and listed the actual flag set.
+- Disclosed that `node bin/mindforge-cli.js spawn <persona>` is a v1.0 stub that exits 1
+  with "NOT IMPLEMENTED", not a working scripted path.
+- Corrected the License section's copyright holder to match `LICENSE` exactly.
+- Fixed the architecture diagram's skill count: only 232 of the 355 skills live under
+  `.mindforge/` (engine tier); the other 123 are under `.agent/skills/` (extended tier).
+- Corrected `bin/`'s "~22K LOC" claim to the measured ~32K raw / ~25K stripped-of-comments.
+- Narrowed the Config reference doc-table row — that doc never mentions
+  `.mindforge/config.json`.
+- Reworded the Threat model doc-table row — that file is explicitly historical (v1.0.0-era),
+  not re-reviewed against v11.x, and redirects to `SECURITY.md`.
+- Reworded the USP-features doc-table row — that file has zero competitor comparison
+  content; it's the same honesty pass applied to MindForge's own features.
+- Disclosed that the `mindforge-plugin-*` namespace has zero packages published under it
+  today.

package/docs/faq.md

@@ -1,4 +1,4 @@
-# MindForge FAQ (v11.9.7)
+# MindForge FAQ (v11.9.8)
 
 ## Is MindForge tied to Claude only?
 No. MindForge supports Claude Code and Antigravity. Install with `--claude`,
@@ -39,7 +39,7 @@ Plugins are preferred for sharing and versioning.
 
 ## Dynamic Workflows
 
-**Q: How many workflows does MindForge v11.9.0 include?**
+**Q: How many workflows does MindForge include?**
 35 pre-built multi-agent workflows across 5 tiers: Research (5), Dev (14), Ops (6), Intelligence (7), Beast (3).
 
 **Q: How do I run a workflow?**
@@ -55,10 +55,13 @@ The `deep-research` workflow was removed before the v11.8.0 release (the superpo
 ## Version & Stability
 
 **Q: What version is current?**
-v11.9.7 — verify with `node bin/mindforge-cli.js --version`
+v11.9.8 — verify with `node bin/mindforge-cli.js --version`
 
-**Q: Is v11.9.0 production-stable?**
-Yes. The IQ200 deep-audit (258 discrete checks across 14 dimensions) shows 258/258 passing. 0 CVEs, 0 test failures, 0 ESLint errors, 0 TypeScript errors.
+**Q: Was v11.9.0 production-stable?**
+At that release: yes, by the IQ200 deep-audit (258 discrete checks across 14 dimensions),
+258/258 passing, 0 CVEs, 0 test failures, 0 ESLint errors, 0 TypeScript errors. That was a
+one-time, point-in-time audit rather than a repeated gate, so it is not re-run per release —
+see "What is the test coverage?" below for the number that is.
 
 **Q: Which npm dist-tag should I install?**
 `latest` is every published release, including patches. `stable` tracks the newest
@@ -74,10 +77,10 @@ release behind. Check what each points at right now with `npm dist-tag ls mindfo
 ## Known Limitations
 
 **Q: Why does `spawn architect` exit with an error?**
-Spawn dispatch is not yet implemented in v11.9.0. Use `/mindforge:auto` or `/mindforge:next` from Claude Code instead.
+Spawn dispatch is a v1.0 stub — still not implemented as of v11.9.8. Use `/mindforge:auto` or `/mindforge:next` from Claude Code instead.
 
 **Q: Why does ZTAI show a Tier-3 warning?**
-Tier-3 trust uses in-process key simulation in v11.9.0 — this is intentional and safe. `SECURITY_TIER_3_SIMULATED = true` is the documented v11.x behavior. Hardware TPM/HSM is planned for v12.x.
+Tier-3 trust uses in-process key simulation in v11.x. `bin/governance/ztai-manager.js` warns on this itself: key material resides in the Node.js heap, not hardware-isolated — do not use Tier-3 trust for production credential workflows. `SECURITY_TIER_3_SIMULATED = true` is the documented v11.x behavior. Hardware TPM/HSM is planned for v12.x.
 
 **Q: What is the test coverage?**
 140 test files: 137 pass, 0 failures, 3 env-dependent skips (`browser.test.js` and

package/docs/getting-started.md

@@ -1,4 +1,4 @@
-# MindForge — Getting Started (v11.9.7)
+# MindForge — Getting Started (v11.9.8)
 
 This guide gets you from zero to a working MindForge project in under five minutes.
 
@@ -106,7 +106,7 @@ MindForge adapts to your existing engineering environment via runtime flags:
 
 **Run any workflow:**
 ```bash
-node bin/mindforge-cli.js workflow list              # browse all 32
+node bin/mindforge-cli.js workflow list              # browse all 35
 node bin/mindforge-cli.js workflow info code-audit   # details + phases
 ```
 Or use slash commands: `/mindforge:wf-code-audit`
@@ -114,7 +114,7 @@ Or use slash commands: `/mindforge:wf-code-audit`
 ## Your First 5 Minutes with MindForge
 
 1. **Verify install:** `node bin/mindforge-cli.js health`
-2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.7`)
+2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.8`)
 3. **List workflows:** `node bin/mindforge-cli.js workflow list`
 4. **Run first slash command:** Open Claude Code → `/mindforge:status`
 5. **Onboard your codebase:** Open Claude Code → `/mindforge:wf-onboard-codebase`

package/docs/sdk-reference.md

@@ -14,11 +14,11 @@ import {
 } from 'mindforge-sdk';
 ```
 
-Current SDK version: `11.9.7`
+Current SDK version: `11.9.8`
 
 ---
 
-## SDK Exports (v11.9.7)
+## SDK Exports (v11.9.8)
 
 ```javascript
 const {
@@ -28,7 +28,7 @@ const {
   commands,               // Command registry
   batch,                  // Batch execution
   MindForgeMemory,        // Memory interface
-  VERSION                 // '11.9.7'
+  VERSION                 // '11.9.8'
 } = require('mindforge-sdk');
 // or: import { MindForgeClient, VERSION } from 'mindforge-sdk';
 ```

package/docs/troubleshooting.md

@@ -1,4 +1,4 @@
-# MindForge Troubleshooting (v11.9.7)
+# MindForge Troubleshooting (v11.9.8)
 
 This page lists common issues and fast fixes. If you get stuck, start with
 `/mindforge:health`.

package/docs/user-guide.md

@@ -1,8 +1,8 @@
-# MindForge User Guide (v11.9.7)
+# MindForge User Guide (v11.9.8)
 
 This guide gets you from install to productive, with the minimum needed to run MindForge in a real project.
 
-> **v11.9.7 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
+> **v11.9.8 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
 
 ## Prerequisites
 
@@ -44,7 +44,7 @@ mindforge health          # Verify project integrity
 mindforge security-scan   # Run security checks
 mindforge headless        # Run agent in non-interactive mode
 mindforge --verbose ...   # Enable verbose output for debugging
-mindforge --version       # Print installed version (e.g. 11.9.7) and exit 0
+mindforge --version       # Print installed version (e.g. 11.9.8) and exit 0
 ```
 
 Use `--verbose` (or `-v`) on any command for detailed diagnostic output. Use `--version` (or `-V`) to print the installed version and exit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "11.9.7",
+  "version": "11.9.8",
   "description": "Agentic intelligence framework for Claude Code and Antigravity: slash commands, subagents, skills, hooks, governance, memory, and cost-aware model routing for AI-driven development.",
   "bin": {
     "mindforge-cc": "bin/install.js",