Initial TrueGrowth source import

openspec/changes/add-commercial-desktop-packaging/design.md

@@ -0,0 +1,54 @@
+## 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.