mindforge-cc 11.9.1 → 11.9.3

package/changelogs/v11.9.3.md

@@ -0,0 +1,195 @@
+# Changelog
+
+## [11.9.3] — 2026-08-21 — Honesty: gates that can fail, commands that run, a release path that is checked
+
+Patch release. No new features. Twenty-one fixes, and they all turned out to be the
+same defect: **an instrument reported success while doing nothing.** Gates that could
+not fail, tests satisfied by a comment, docs describing capabilities with no code
+behind them, commands printing success while performing no action, and a publish path
+that no check ever touched.
+
+Contains behaviour changes under a patch bump — several of the things being fixed were
+bugs that a consumer could have been relying on. Read BREAKING before upgrading if you
+script against the CLI or the installer.
+
+### BREAKING
+
+Each of these is a bug fix whose correct behaviour differs from the shipped behaviour.
+
+- **Routed CLI commands now act on YOUR project, not MindForge's own checkout.**
+  `bin/mindforge-cli.js` passed `cwd: ROOT` to every routed command, so `mindforge
+  classify` diffed MindForge's repository instead of yours, and `mindforge health`
+  inspected MindForge's `node_modules`. Measured across all 27 routed commands: 7
+  changed behaviour, all in the correct direction, none regressed. If you parsed output
+  that happened to describe MindForge itself, it now describes your project. (#201)
+
+- **`npx mindforge-cc install` — and any other positional argument — now exits 1.**
+  The installer takes flags only and silently ignored stray words, so
+  `npx mindforge-cc install` appeared to work while installing nothing configured.
+  It now refuses with the correct form. `--runtime`'s value token is still accepted.
+  Use `npx mindforge-cc --claude --local`. (#202)
+
+- **`mindforge verify` now SKIPS unavailable stages instead of failing them.** A project
+  with no ESLint config, no test script or no `bin/verify-audit.js` was reported as
+  FAILING those stages rather than as not having them. If your CI relied on a non-zero
+  exit in those cases, it will now pass. A run in which every stage skipped prints a
+  "NOTHING WAS VERIFIED" banner rather than a clean bill of health. (#204)
+
+- **`scripts/sync-version.js` now exits non-zero when the plugin build artifacts are
+  stale.** A bump used to report `✅ every derivable channel is at <version>` and exit 0
+  while leaving `npm test` red. If you script this, handle the new exit code — it means
+  "run the build chain it just printed". (#211)
+
+- **A self-install no longer writes over your tracked files.** Running the installer
+  inside a MindForge checkout printed that it was skipping and then overwrote 149
+  tracked files, including `CLAUDE.md`, `.claude/**`, `.agent/**` and `.mindforge/**`.
+  The skip is now honoured for local scope. (#200)
+
+- **Releases must be tagged on a commit reachable from `main`.** The release workflow
+  now refuses a tag that is not an ancestor of `origin/main`. The documented flow is
+  develop → release → main; tagging elsewhere previously published, with provenance
+  attesting to that tree. (#216)
+
+### Fixed
+
+**Installer**
+
+- A self-install claimed to skip and then overwrote 149 tracked files. The gate is now
+  scope-aware (`isSelfInstall() && scope === 'local'`). (#200)
+- Every `--global` install reported failure on a correct run: `verifyInstall` demanded
+  six `bin/**` paths regardless of scope, so a global install ended
+  `❌ 6 of 12 required file(s) missing` and exit 1, with a `--force` retry that could
+  not help. A global install writes 389 files to `$HOME/.claude` and, deliberately,
+  zero to `bin/`. (#210)
+- 11 of 27 routed CLI verbs died on `MODULE_NOT_FOUND` in a real install: the router
+  shipped but 6 of the scripts it dispatches to did not. `coreFiles` grew from 2 entries
+  to 8. (#210)
+- Two leaks: `/tmp` staging files left behind on abandoned runs, and developer runtime
+  state (`celestial.db`, `.browser-daemon-token`) copied into consumer projects.
+  `SENSITIVE_EXCLUDE` now covers both. (#210)
+- The forge commands overwrote three `mindforge` commands of the same name. (#197)
+- The documented default install did not deliver the CLI it documents. (#196)
+
+**Versioning and release**
+
+- `sync-version.js --fetch-sha` hashed npm's 404 error body. For an unpublished version
+  the registry answers `{"error":"Not found"}` and `curl -sL` exits 0, so the digest
+  written into the Homebrew formula was the SHA-256 of that error text — the same
+  constant for every unpublished version — and `--check` then passed. Now `curl -fsSL`
+  plus a gzip magic-byte check, and it refuses rather than writing a digest no artifact
+  can match. (#203)
+- The Homebrew formula may now LAG canonical but never LEAD it. Requiring equality
+  before publishing required something impossible: the digest is the hash of a tarball
+  that does not exist yet, and `npm test` blocked the publish that would have made it
+  satisfiable. (#208)
+- Semver comparison is numeric per component. Lexicographically, `11.10.0` reads as
+  *behind* `11.9.2` — wrong on exactly the first release past a `.9` minor. (#208)
+- Three version channels had no writer at all, so `npm test` failed on every bump and
+  the documented remedy could not fix it: `mcp-server/server.json` (both keys, matched
+  by identifier), `AGENTS.md`, and `sdk/README.md`'s second shape. (#207, #211)
+- **No channel covered a document a user receives.** `SECURITY.md` — the security policy
+  at the root of the published package — said "Current version: 11.9.0", and
+  getting-started, faq, troubleshooting, user-guide and sdk-reference all titled
+  themselves v11.9.0: three releases stale, while every npm manifest was correct.
+  `--check` was green throughout, because a channel that does not exist cannot drift.
+  Structural markers now track canonical; narrative measurements deliberately do not.
+  (#211)
+- A bump is not finished when `sync-version.js` exits. Two tracked artifacts are gated
+  against `package.json` and only a build can write them —
+  `plugins/mindforge/.claude-plugin/plugin.json` and
+  `plugins/mindforge/mcp/dist/index.js`. They are now reported under
+  `🔨 REQUIRE A BUILD` with the exact three-command chain, which nothing had documented.
+  (#211)
+- `sync-version.js` reported "a channel is AHEAD of canonical" whenever its exit code
+  was non-zero for any reason, so the `--fetch-sha` refusal for an unpublished tarball
+  claimed the formula LEADS canonical in the same run that printed "DEFERRED until after
+  publish (behind, not ahead)". (#211)
+- `changelogs/index.json`, which `bin/updater/changelog-fetcher.js` reads as the
+  authoritative version list, was missing 11.9.2. (#218)
+
+**Publishing**
+
+- **The tag push that publishes was exempt from every gate.** Publishing is triggered by
+  exactly one event — a `v*` tag push — and the repository's only ruleset targets
+  branches, so its six required checks applied to nothing on the path that ships. GitHub
+  cannot attach required status checks to a tag. A `preflight` job now gates it. (#216)
+- The `stable` npm dist-tag was moved by hand, or not at all — it sat four releases
+  behind `latest` (11.8.3 against 11.9.2), so `npm i mindforge-cc@stable` delivered a
+  build with none of the 11.9.x fixes. The release workflow now moves it as its final
+  step: forward-only, prereleases skipped, and verified against npm's uncached dist-tags
+  endpoint rather than the CDN-cached packument. (#216)
+
+**Dashboard**
+
+- `--status` and `--stop` were documented in nine places and implemented in none; both
+  printed nothing and exited 0. Now implemented, before `express` is required, so they
+  work without the dependency installed. (#206)
+- `--stop` identified the target by the SHAPE of its command line, which matched any
+  `node <anything>/dashboard/server.js` — verified against
+  `node /var/www/unrelated_app/dashboard/server.js`. It now resolves the script's
+  realpath and compares it to its own. (#206)
+- `--status` printed a port it could not know: the PID file records only the pid, so it
+  reported whatever port that invocation happened to receive. Measured, `--status` on a
+  server started with `--port 7466` printed "port 7339". (#206)
+
+**Memory**
+
+- Every abandoned exit left a full copy of the database on disk — 1.8 GB of orphaned
+  `.tmp` files. (#199)
+- The SDK's WebSocket client took the caller's process down on a failed reconnect. (#191)
+
+**Verification**
+
+- `mindforge verify`'s lint stage used `--max-warnings=0`, which made it impossible to
+  pass in the repository it ships from: `npx eslint .` reports 199 problems / 0 errors /
+  199 warnings, so `verify` reported a lint FAILURE on a tree that is green by the
+  project's own contract. Aligned with the project's definition; errors still fail. (#204)
+- `temporal cleanup` printed "🧹 Cleaning up old temporal snapshots..." and
+  "✅ Cleanup complete." with no cleanup between them. Now wired to
+  `TemporalHub.gc({maxSnapshots: 50, maxAgeDays: 30})` with `--dry-run` and honest
+  counts, including zero. (#209)
+
+**Documentation that named things that do not exist**
+
+- The protocol files instructed the agent to run `soul-engine.js` and
+  `shard-controller.js`, neither of which exists anywhere in the package. Those steps
+  are reasoning protocols and now say so. (#205)
+- Fifteen phantom `/mindforge:` slash commands in shipped docs. A reader following
+  `docs/user-guide.md` typed `/mindforge:personas --list` and got nothing. They were not
+  typos: `.agent/workflows/` holds 130 tracked files using those exact names — an old
+  target layout, committed and orphaned, shipping zero files. (#209)
+- Four documented CLI invocations could not be run, each verified by running it:
+  `npx mindforge-cc@latest install` (exit 1), `mindforge-cli.js dashboard` (exit 1),
+  `npx mindforge auto` in a shipped engine doc (`auto` is a slash command, never a CLI
+  verb), and `@mindforge <verb>`, a syntax that exists nowhere. (#213)
+- `workflow` is the most-documented CLI verb in the project and works, but appeared in
+  neither `--help` nor the "Available commands" list, so a user who mistyped it was told
+  it does not exist. (#213)
+- Root `CLAUDE.md` named `bin/hooks/mindforge-context-monitor.js`; the file is under
+  `.agent/hooks/`. (#214)
+
+### Added
+
+- **`preflight` job on the release workflow.** Asserts the tagged commit is an ancestor
+  of `origin/main`, then runs the six gates a tag push never saw, with the publish job
+  behind `needs:`. (#216)
+- **Automatic `stable` dist-tag movement**, forward-only and verified. (#216)
+- **`node bin/dashboard/server.js --status` / `--stop`.** Not CLI verbs —
+  `mindforge-cli.js dashboard` does not route. (#206)
+- **`mindforge temporal cleanup --dry-run`.** (#209)
+- New regression gates, each falsified by mutation before being trusted:
+  `tests/protocol-claims.test.js` (no exemption list, deliberately — a name-keyed
+  allowlist was shown to excuse the exact defect it was written for), the shipped-doc
+  phantom-command gate, the CLI-verb gate, the authority-doc `.js` gate, the
+  version-channel round trips, and assertions that the release preflight itself cannot
+  be silently removed.
+
+### Notes for operators
+
+- `npm run version:check` is the offline drift check. A bump is finished only when
+  `sync-version.js` exits 0 — if it prints `🔨 REQUIRE A BUILD`, run the three commands
+  it names and commit both regenerated files.
+- Releases are now gated on being tagged from `main`. One residual, inherent to
+  tag-triggered workflows: a tag push resolves the workflow from the TAGGED ref, so a
+  tag placed on a commit predating this release runs that commit's workflow and is
+  ungated.

package/docs/References/config-reference.md

@@ -4,24 +4,86 @@
 
 ---
 
+## 0. Syntax and required keys
+
+**Read this first.** As of 11.9.2 `node bin/validate-config.js` and
+`mindforge security-scan` can actually fail — before that they reported
+`0 settings configured` and exited 0 on any input, so an invalid registry passed silently.
+
+Two syntaxes are accepted:
+
+```text
+[PLANNER] = claude-opus-4-7      # bracketed — CANONICAL, what the shipped MINDFORGE.md uses
+PLANNER_MODEL=claude-opus-4-7    # plain — legacy, still read, used by examples/starter-project
+```
+
+Prefer the bracketed form. A bracketed key must open the line (leading whitespace is allowed)
+and be followed by `=`. Prose bullets that merely mention `[KEY]` are not parsed as settings.
+
+**These five keys are REQUIRED.** Validation exits 1 if any is missing:
+
+| Key | Example |
+| :--- | :--- |
+| `[VERSION]` | `11.9.2` — must match `^\d+\.\d+\.\d+$` |
+| `[REACTIVE_MODE]` | `true` |
+| `[PLANNER]` | `claude-opus-4-7` |
+| `[EXECUTOR]` | `claude-sonnet-4-6` |
+| `[MIN_SOUL_SCORE]` | `8` (range 0–10) |
+
+Three more are **recommended** — absent ones produce a warning, not an error:
+`[COST_WARN_USD]`, `[COST_HARD_LIMIT_USD]`, `[BLOCK_ON_SECURITY]`.
+
+> `[COST_HARD_LIMIT_USD]` is **enforced from 11.9.3** (it was declared but inert in 11.9.2).
+> `preflight()` refuses the model call once today's ledger spend plus the call estimate reaches
+> the limit. Because the key is *recommended* rather than *required*, an absent key — or an
+> explicit `0` — leaves the cap off; a present-but-unparseable value is a hard error
+> (`COST_LIMIT_MISCONFIGURED`), not a silent bypass.
+
+---
+
 ## 1. Model Configuration
 
 MindForge uses a tiered model routing system. You can specify exact models for different phases of the lifecycle.
 
-| Key | Description | Default |
-| :--- | :--- | :--- |
-| `PLANNER_MODEL` | Model used for task decomposition and planning. | `claude-sonnet-4-5` |
-| `EXECUTOR_MODEL` | Model used for code generation and implementation. | `claude-sonnet-4-5` |
-| `REVIEWER_MODEL` | Model used for code review and PR analysis. | `claude-opus-4-alpha` |
-| `VERIFIER_MODEL` | Model used for testing and UAT verification. | `claude-sonnet-4-5` |
-| `SECURITY_MODEL` | Model used for sensitive security scanning. | `claude-opus-4-alpha` |
-
-**Supported Values:**
-
-- `claude-opus-4-alpha` (High intelligence, slow, expensive)
-- `claude-sonnet-4-5` (Balanced, recommended)
-- `claude-haiku-4-5` (Fast, logical, best for trivial tasks)
-- `inherit` (Use the system-wide default)
+The canonical keys are the short bracketed forms; the `*_MODEL` names are accepted aliases kept
+for older configs.
+
+| Key | Alias | Description | Shipped default |
+| :--- | :--- | :--- | :--- |
+| `[PLANNER]` | `PLANNER_MODEL` | Task decomposition and planning. | `claude-opus-4-7` |
+| `[EXECUTOR]` | `EXECUTOR_MODEL` | Code generation and implementation. | `claude-sonnet-4-6` |
+| `[REVIEWER]` | `REVIEWER_MODEL` | Code review and PR analysis. | `claude-sonnet-4-6` |
+| `[VERIFIER]` | `VERIFIER_MODEL` | Testing and UAT verification. | `claude-sonnet-4-6` |
+| `[SECURITY]` | `SECURITY_MODEL` | Sensitive security scanning. | `claude-opus-4-7` |
+| `[DEBUG]` | — | Debugging and root-cause analysis. | `claude-opus-4-7` |
+
+**Values are free-form strings** — the schema does not constrain them to a list, so a new model
+id works without a framework upgrade. The ids shipped in `MINDFORGE.md` today are
+`claude-opus-4-7`, `claude-sonnet-4-6` and `claude-haiku-4-5`; `inherit` selects the
+system-wide default. Because the values are unconstrained, a typo is NOT caught by validation —
+it falls through to the routing defaults.
+
+---
+
+## 1b. Numeric bounds enforced by validation
+
+Out-of-range values now fail. These were previously documented nowhere a consumer reads.
+
+| Key | Range | Key | Range |
+| :--- | :--- | :--- | :--- |
+| `MIN_SOUL_SCORE` | 0–10 | `MAX_TASKS_PER_PHASE` | 1–50 |
+| `AUTO_SWARM_THRESHOLD` | 0–10 | `MIN_TEST_COVERAGE_PCT` | 0–100 |
+| `DYNAMISM_LEVEL` | 1–5 | `MAX_FUNCTION_LINES` | 10–200 |
+| `ADS_DEBATE_ROUNDS` | 1–10 | `MAX_CYCLOMATIC_COMPLEXITY` | 3–30 |
+| `COMPACTION_THRESHOLD_PCT` | 50–90 | `MAX_FULL_SKILL_INJECTIONS` | 1–10 |
+| `DASHBOARD_PORT` | 1024–65535 | `NEXUS_TRACE_RETENTION_DAYS` | 1–365 |
+| `BROWSER_PORT` | 1024–65535 | `SHARD_RETAIN_DAYS` | 1–365 |
+| `COST_WARN_USD` | 0–10000 | `AI_REVIEW_DAILY_LIMIT` | 0–500 |
+| `COST_HARD_LIMIT_USD` | 0–10000 | `CI_MIN_COVERAGE_PCT` | 0–100 |
+| `VERIFY_PASS_RATE_WARNING_THRESHOLD` | 0–1 | `DISCUSS_PHASE_REQUIRED_ABOVE_DIFFICULTY` | 1–5 |
+
+If one of these rejects a value you consider legitimate, the bound is wrong — report it rather
+than editing your registry to satisfy it.
 
 ---
 

package/docs/References/sdk-api.md

@@ -2,7 +2,7 @@
 
 ## Package
 
-`@mindforge/sdk`
+`mindforge-sdk`
 
 ## Exports
 

package/docs/Templates/Codebase/architecture.md

@@ -146,7 +146,7 @@ Template for `.mindforge/codebase/ARCHITECTURE.md` - captures conceptual code or
 
 **CLI Command Execution:**
 
-1. User runs: `mindforge new-project`
+1. User runs: `mytool new-project`
 2. Commander parses args and flags
 3. Command handler invoked (`src/commands/new-project.ts`)
 4. Handler calls service methods (`src/services/project.ts` → `create()`)

package/docs/commands-reference.md

@@ -131,13 +131,12 @@ High-fidelity behaviors ported from the Superpowers library and hardened for pro
 
 | Command | Description |
 | :--- | :--- |
-| `/mindforge:brainstorming` | Deep exploratory protocol for intent clarification and architectural ideation. |
-| `/mindforge:swarm-execution` | Wave-based implemention for independent, non-conflicting tasks. |
-| `/mindforge:parallel-mesh` | Orchestrates a mesh of agent waves with automated dependency compaction. |
+| *(protocol, not a command)* | Wave-based implementation for independent tasks — see `.mindforge/engine/swarm-controller.md`. |
+| *(protocol, not a command)* | Mesh of agent waves with dependency compaction — see `.mindforge/engine/wave-executor.md`. |
 | `/mindforge:workspace` | Manages isolated development environments via git worktrees with smart safety checks. |
-| `/mindforge:tdd` | Strict Test-Driven Development (Red-Green-Refactor) with automated test generation. |
+| `/mindforge:skill-tdd` | Strict Test-Driven Development (Red-Green-Refactor) with automated test generation. |
 | `/mindforge:debug` | Systematic debugging using persistent state tracking and Root Cause Analysis. |
-| `/mindforge:verify-work` | Multi-level truth verification protocol (substance, existence, wiring). |
+| `/mindforge:verify-phase` | Multi-level truth verification protocol (substance, existence, wiring). |
 | `/mindforge:retrospective` | Facilitates structured team retrospectives with objective telemetry and metrics. |
 
 ---

package/docs/faq.md

@@ -1,4 +1,4 @@
-# MindForge FAQ (v11.9.0)
+# MindForge FAQ (v11.9.3)
 
 ## Is MindForge tied to Claude only?
 No. MindForge supports Claude Code and Antigravity. Install with `--claude`,
@@ -55,13 +55,21 @@ The `deep-research` workflow was removed before the v11.8.0 release (the superpo
 ## Version & Stability
 
 **Q: What version is current?**
-v11.9.0 — verify with `node bin/mindforge-cli.js --version`
+v11.9.3 — 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: What npm dist-tags point to v11.9.0?**
-Both `latest` and `stable`: `npx mindforge-cc@stable` or `npx mindforge-cc@latest`
+**Q: Which npm dist-tag should I install?**
+`latest` is every published release, including patches. `stable` tracks the newest
+non-prerelease and is moved by the release workflow as its final step — forward only, so it
+never regresses to an older version. Prerelease builds keep their own `rc` and `alpha` tags and
+never become `stable`. Use `npx mindforge-cc@latest` unless you specifically want to lag a
+release behind. Check what each points at right now with `npm dist-tag ls mindforge-cc`.
+
+> This answer deliberately names no version. It previously claimed `latest` and `stable` both
+> pointed at v11.9.0; measured, they were 11.9.2 and 11.8.3 — neither. A documented invariant
+> survives releases, a documented value does not.
 
 ## Known Limitations
 
@@ -72,4 +80,16 @@ Spawn dispatch is not yet implemented in v11.9.0. Use `/mindforge:auto` or `/min
 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.
 
 **Q: What is the test coverage?**
-95/97 tests passing (0 failures, 2 permanently env-skipped). Line coverage ~66% — gaps are in `bin/source-loader.js` and `scripts/ci/validate-assets.js`. Target is 80% for v11.9.0.
+133 test files: 131 pass, 0 failures, 2 env-dependent skips (`browser.test.js` needs a Chromium
+daemon, `sre-integration.test.js` needs git worktree support and a clean tree).
+
+The enforced floor is **30% lines**, gated in CI by the `mindforge-quality` job
+(`npx c8 --check-coverage --lines 30 --exclude 'plugins/**' --exclude 'mcp-server/dist/**'`).
+The measured figure is printed by that job and deliberately not restated here. The previous
+answer to this question was wrong in three ways at once — a test count from a much smaller
+suite, a stale coverage figure, and two named coverage gaps that were no longer the gaps — and
+it stayed wrong because none of it was checked by anything. `tests/doc-count-claims.test.js`
+now pins every count this file does state.
+
+Both `--exclude` flags are load-bearing: without them c8 measured the generated `plugins/` tree
+and `mcp-server/dist/` esbuild output, which understated real coverage substantially.

package/docs/getting-started.md

@@ -1,4 +1,4 @@
-# MindForge — Getting Started (v11.9.0)
+# MindForge — Getting Started (v11.9.3)
 
 This guide gets you from zero to a working MindForge project in under five minutes.
 
@@ -108,7 +108,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.0`)
+2. **Check version:** `node bin/mindforge-cli.js --version` (should print `11.9.3`)
 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`
@@ -140,4 +140,4 @@ MindForge operates on a high-velocity 4-pillar lifecycle:
 
 - Explore the [User Guide](user-guide.md) for advanced features.
 - Switch to a specialized [Persona](PERSONAS.md) for target tasks.
-- Join the community: `/mindforge:join-discord`.
+- Join the community: https://github.com/sairam0424/MindForge/issues.

package/docs/sdk-reference.md

@@ -2,8 +2,8 @@
 
 ## Overview
 
-The `@mindforge/sdk` package provides a programmatic TypeScript API for integrating
-MindForge into tools, dashboards, and CI pipelines. Import from `@mindforge/sdk`.
+The `mindforge-sdk` package provides a programmatic TypeScript API for integrating
+MindForge into tools, dashboards, and CI pipelines. Import from `mindforge-sdk`.
 
 ```typescript
 import {
@@ -11,14 +11,14 @@ import {
   MindForgeEventStream,
   MindForgeMemory,
   commands,
-} from '@mindforge/sdk';
+} from 'mindforge-sdk';
 ```
 
-Current SDK version: `11.9.0`
+Current SDK version: `11.9.3`
 
 ---
 
-## SDK Exports (v11.9.0)
+## SDK Exports (v11.9.3)
 
 ```javascript
 const {
@@ -28,7 +28,7 @@ const {
   commands,               // Command registry
   batch,                  // Batch execution
   MindForgeMemory,        // Memory interface
-  VERSION                 // '11.9.0'
+  VERSION                 // '11.9.3'
 } = require('mindforge-sdk');
 // or: import { MindForgeClient, VERSION } from 'mindforge-sdk';
 ```
@@ -417,6 +417,14 @@ cd sdk && npm install && npm run build
 
 ## Installation
 ```bash
-npm install mindforge-sdk@11.8.0
+npm install mindforge-sdk
 # or: npx mindforge-cc@stable  # installs SDK as part of the framework
 ```
+
+> **`mindforge-sdk` is versioned independently of the framework.** The release workflow
+> (`.github/workflows/mindforge-release.yml`) publishes `mindforge-cc` and
+> `mindforge-mcp-server` only — it has no `sdk` steps — so `sdk/package.json`'s version
+> tracks the monorepo while the published package does not. At the time of writing the
+> latest published SDK is **11.8.0** (`npm view mindforge-sdk versions`), even though the
+> in-repo `sdk/package.json` reads 11.9.2. Install it unpinned, as above; pinning it to a
+> framework version yields `E404 No match found for version …`.

package/docs/troubleshooting.md

@@ -1,4 +1,4 @@
-# MindForge Troubleshooting (v11.9.0)
+# MindForge Troubleshooting (v11.9.3)
 
 This page lists common issues and fast fixes. If you get stuck, start with
 `/mindforge:health`.
@@ -117,15 +117,19 @@ rerun migration. See `.mindforge/audit/AUDIT-SCHEMA.md` for expected format.
 
 ### Protocol Step 0 fails to activate
 **Symptom:** Commands proceed without activating `_extended` skills.
-**Fix:** Run `/mindforge:neural-orchestrator --reset`. Ensure all `_extended` skills are present in `.agent/skills/`.
+**Fix:** Ensure all `_extended` skills are present in `.agent/skills/`, then start a fresh session so the
+skill loader re-reads them. There is no orchestrator reset command.
 
 ### Context drift in Parallel Mesh
 **Symptom:** Parallel agents making conflicting decisions.
-**Fix:** Run `/mindforge:parallel-mesh --sync`. This forces a global state re-synchronization across all active worker identities.
+**Fix:** Re-synchronise by re-reading `.planning/HANDOFF.json` and `.planning/auto-state.json` before the
+next wave — the mesh protocol is described in `.mindforge/engine/wave-executor.md`. It is a protocol you
+follow, not a command.
 
 ### Workspace isolation failure
 **Symptom:** Conflicts between feature branches or dirty worktree.
-**Fix:** Run `/mindforge:workspace-isolated --cleanup`. Use `/mindforge:health --repair` if `.git/worktrees/` is corrupt.
+**Fix:** Run `/mindforge:workspace` to inspect worktree state. Use `/mindforge:health --repair` if
+`.git/worktrees/` is corrupt.
 
 ---
 
@@ -133,7 +137,7 @@ rerun migration. See `.mindforge/audit/AUDIT-SCHEMA.md` for expected format.
 If the above doesn’t resolve it:
 - Review `docs/user-guide.md`
 - Check `docs/security/SECURITY.md` for security issues
-- Open a GitHub issue or join the Discord: `/mindforge:join-discord`
+- Open a GitHub issue: https://github.com/sairam0424/MindForge/issues
 - **Architecture**: `docs/architecture/V5-ENTERPRISE.md`
 - **Commands**: `docs/commands-reference.md`
 - **Personas**: `docs/PERSONAS.md`
@@ -203,4 +207,4 @@ All tests must be run from the MindForge project root: `cd /path/to/MindForge &&
 
 **Symptom:** `--version` flag reports "Unknown command" on installs older than v11.9.0.
 
-**Fix:** Upgrade to v11.9.0: `npx mindforge-cc@latest install`
+**Fix:** Upgrade: `npx mindforge-cc@latest --claude --local`

package/docs/user-guide.md

@@ -1,8 +1,8 @@
-# MindForge User Guide (v11.9.0)
+# MindForge User Guide (v11.9.3)
 
 This guide gets you from install to productive, with the minimum needed to run MindForge in a real project.
 
-> **v11.9.0 Stats:** 35 workflows · 221 slash commands · 232 engine skills · 216 personas · 0 CVEs · 258/258 IQ200 checks passing
+> **v11.9.3 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.0) and exit 0
+mindforge --version       # Print installed version (e.g. 11.9.3) 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.
@@ -127,7 +127,7 @@ MindForge features 211 specialized personas. Each persona is optimized for a spe
 To switch personas or see the full list:
 
 ```bash
-/mindforge:personas --list
+ls .mindforge/personas/            # 216 persona briefs; there is no personas command
 ```
 
 ---
@@ -137,7 +137,7 @@ To switch personas or see the full list:
 For complex tasks that require minimal intervention:
 
 ```bash
-/mindforge:autonomous --phase [N]
+/mindforge:auto --phase [N]
 ```
 
 Use the **Steer** command to guide logic without stopping execution:
@@ -153,7 +153,7 @@ Use the **Steer** command to guide logic without stopping execution:
 Observe your agent waves, token spend, and milestone progress in real-time.
 
 ```bash
-/mindforge:dashboard --start --open
+/mindforge:dashboard --open
 ```
 
 The dashboard provides a premium web interface at `http://localhost:7339`.
@@ -179,7 +179,7 @@ Extend MindForge by learning from documentation or authoring custom protocols.
 
 ```bash
 /mindforge:learn https://docs.nextjs.org "nextjs-mastery"
-/mindforge:skill-creation # Author a new high-fidelity protocol
+/mindforge:skills-index   # browse the catalogue; author new skills per the guide in CLAUDE.md
 ```
 
 ---
@@ -189,7 +189,7 @@ Extend MindForge by learning from documentation or authoring custom protocols.
 MindForge features automated PR creation and commit management.
 
 ```bash
-/mindforge:pr-branch "feature/auth-refactor"
+git switch -c feature/auth-refactor   # no pr-branch command; use git, then /mindforge:pr-review
 /mindforge:ship --auto-pr
 ```
 
@@ -202,7 +202,7 @@ MindForge provides mission-critical resilience and sovereign reasoning for enter
 ### Multi-Cloud Arbitrage
 MindForge automatically hedges against provider outages and optimizes for cost/latency.
 ```bash
-/mindforge:settings --cloud-arbitrage on
+# settings live in MINDFORGE.md as [KEY] = value; edit it, then run `mindforge security-scan`
 ```
 
 ### Sovereign Reason Enclaves (SRE)
@@ -214,8 +214,8 @@ Tier 3 (Principal) agents execute reasoning in isolated enclaves to protect sens
 ### Dynamic Human-Agent Handover & Temporal Steering (Pillar VII)
 NEXUS enables sub-second state reconstruction and **Hindsight Injection**. When an agent drifts, roll back its logic via the Dashboard's **Temporal Slider** and inject a steering vector to re-orient the wave.
 ```bash
-/mindforge:temporal status     # View active reasoning snapshots
-/mindforge:temporal inject [ID] # Manual CLI-based hindsight
+mindforge temporal status      # View active reasoning snapshots (a CLI command)
+mindforge temporal inject [ID] # Manual CLI-based hindsight
 ```
 
 ### Agentic Revenue Operations (AgRevOps) (Pillar VIII)
@@ -239,7 +239,7 @@ The **Enterprise Expansion** introduces 14 hardened protocols from the Superpowe
 
 Activate the mesh for any session:
 ```bash
-/mindforge:neural-orchestrator
+# the orchestrator layer is a protocol in .mindforge/engine/, not a command
 ```
 
 ---
@@ -260,7 +260,7 @@ Keep your framework current with the latest personas and library updates:
 
 MindForge allows you to "time-travel" through your agent's reasoning.
 
-1.  **Launch the Dashboard**: `/mindforge:dashboard --start --open`
+1.  **Launch the Dashboard**: `/mindforge:dashboard --open`
 2.  **Navigate to 'Temporal'**: Use the horizontal slider to scrub through reasoning snapshots.
 3.  **Inspect State**: View the exact memory, file diffs, and thought chain at that point in space-time.
 4.  **Inject Hindsight**: If you see a logic error, use the **Hindsight Injector** form to roll back and provide a corrective "Steering Vector."
@@ -283,4 +283,4 @@ Monitor your project's economic performance in real-time via the **RevOps Hub**.
 - **USP & Roadmap**: `docs/usp-features.md`
 - **Commands**: `docs/commands-reference.md`
 - **Troubleshooting**: `docs/troubleshooting.md`
-- **Discord**: `/mindforge:join-discord`
+- **Issues**: https://github.com/sairam0424/MindForge/issues

package/examples/sdk-integration/README.md

@@ -1,6 +1,6 @@
 # SDK Integration Example
 
-Demonstrates basic usage of the `@mindforge/sdk` package.
+Demonstrates basic usage of the `mindforge-sdk` package.
 
 ## Prerequisites