Forge Desktop

Forge is an internal Windows desktop workspace for governed AI-assisted development. The native Rust host owns workspace access, credentials, approvals, durable state, file effects, checkpoints, rollback, and evidence. The React/WebView2 renderer is a typed client; it never receives generic filesystem, process, credential, database, or updater authority.

Start with the team documentation hub. For the shortest accurate overview, read product state, architecture and authority, and release readiness.

Forge is useful as a local development prototype, but it is not release- or pilot-ready. Source checks, a local build, an installer, a signed artifact, deployed Azure evidence, and a pilot are separate acceptance gates.

• desktop-app is the sole native composition root.
• Workspace content and model output are data, never authority.
• Every model request requires reviewed context and a fresh, single-use decision.
• Every proposed change re-enters the host-owned review, apply, evidence, and rollback boundary.
• Direct API-key transport is prototype evidence, not production authentication.
• Current development and intended deployment must work without Entra; the production credential and attribution design is incomplete.
• Imported reference sources are never executed by the product toolchain.

See the accepted ADR index for the decisions behind these rules.

Use the pinned toolchain: Node.js 24.18.0, pnpm 11.15.1, Rust 1.97.0, and .NET SDK 10.0.302.

pnpm toolchain:check
pnpm install --frozen-lockfile
pnpm docs:verify

Run deterministic local mode:

pnpm desktop:dev:deterministic

Run the development-only direct-provider mode:

pnpm desktop:dev

Run the local support seam alongside the native host:

pnpm desktop:local
pnpm local:down

Provider credentials are entered in Forge Settings > Providers. The frontend submits the key once over typed IPC and clears the field; the Rust host keeps it only in zeroizing process memory until disconnect or process exit. Connecting does not itself send workspace content.

For prerequisites and PATH troubleshooting, use the local setup guide.

Run the narrowest relevant check first, then the required broader gate. A green documentation gate does not prove product source, and a green source gate does not prove installer, Azure, signing, clean-machine, or pilot readiness.

• apps/desktop-ui — Forge workbench renderer and UI tests.
• crates/desktop-app — native composition root and Tauri application.
• crates/desktop-runtime — governed runtime and BMAD capability adapters.
• crates/desktop-* — native authority services and platform adapters.
• packages/bmad-foundation — sealed BMAD source, ledgers, catalog, and runtime projections.
• packages/contracts — schema source, fixtures, generators, and cross-language boundaries.
• services/desktop-support-api — support-plane scaffold and local contract seam.
• infra — local rehearsal and deployment infrastructure.
• docs — current guidance, ADRs, runbooks, evidence, references, and archives.

bmad-runtime-lib is a compatibility pointer and retained reference-source boundary. It is not current guidance, a workspace package, a build input, a runtime dependency, or a distribution artifact.

• Documentation hub
• Onboarding
• Contribution guide
• Testing and verification
• Roadmap and known gaps

Source, tests, and named gates outrank documentation. Accepted ADRs outrank current summaries; plans, reviews, source analyses, and archives cannot prove implementation. Existing sapphirus.*, @sapphirus/*, and SAPPHIRUS_* names are legacy compatibility identifiers, not the human-facing product name.