## Context
The repository has a React/Vite web renderer, an Electron shell, a Local API started from the Electron main process, and a Model Center readiness flow for customer runtime initialization. Development launch currently loads `http://127.0.0.1:7200`; commercial packages need to load built static renderer files and run from a read-only application directory.

## Goals
- Produce branded macOS and Windows desktop packages without developer setup on the customer machine.
- Bundle the Electron main/preload files, web build output, Local API script, lightweight assets, and package metadata needed at runtime.
- Preserve managed per-user runtime directories for writable state, downloaded models, logs, caches, and optional runtimes.
- Make missing heavy dependencies actionable in Model Center instead of requiring technical installation during app install.
- Provide one documented build flow that the product owner can repeat.

## Non-Goals
- Shipping GPU drivers, CUDA, system Python, Git, or every local AI model inside the installer.
- Silent administrator-level system mutation.
- Code signing certificates, Apple notarization credentials, or Windows EV/OV certificate procurement.
- Guaranteeing that macOS can produce a fully signed Windows installer locally.

## Packaging Strategy
- Use Electron Builder as the desktop packager because the project already uses Electron and needs macOS/Windows installer targets, app metadata, files staging, and signing hooks.
- Stage a production Electron app directory under `dist/desktop/app` containing:
  - `apps/electron/main.mjs`
  - `apps/electron/preload.cjs`
  - `apps/electron/assets/*`
  - `dist/apps/web/**`
  - `scripts/truegrowth-local-api.mjs`
  - runtime helper scripts that are required by Local API in packaged mode
  - a minimal package manifest used by Electron Builder
- Electron main resolves `VITE_DEV_SERVER_URL` in development and `dist/apps/web/index.html` in packaged production.
- The Local API receives packaged-mode environment variables so it can default writable runtime state to Electron `userData` instead of project-local paths.

## Runtime Boundary
- Built-in app shell functionality must work after install with no terminal, Node.js, pnpm, Vite, or developer environment on the customer computer.
- Heavy optional features rely on the existing Model Center readiness model:
  - If a managed runtime is bundled or can be installed into the per-user runtime directory, the app may start a guided install task.
  - If a dependency requires system permissions or external setup, Model Center must show customer-safe OS-specific guidance.
  - Large models are downloaded after install into the managed runtime/model directories.

## Release Artifacts
- macOS:
  - local developer artifact: `.dmg` or `.zip`
  - commercial artifact: signed and notarized `.dmg`
- Windows:
  - local/CI artifact: `.exe` NSIS installer and optional portable build
  - commercial artifact: Authenticode-signed installer
- Unsigned artifacts are acceptable for internal testing only and must be labeled as such in docs/output.

## Verification
- Build web renderer successfully.
- Build desktop package target successfully on the host platform.
- Inspect packaged artifact metadata for TrueGrowth name, app id, version, and icon presence.
- Launch the packaged app where the host allows it and verify:
  - renderer loads from file assets, not dev server
  - Local API responds on `127.0.0.1:48177/local-api/health`
  - Model Center shows runtime readiness/setup guidance
- For Windows packages, verify on Windows or CI rather than relying only on macOS cross-build output.