TrueGrowth/openspec/changes/add-desktop-runtime-readiness/proposal.md

Change: Add commercial desktop runtime onboarding

Why

TrueGrowth desktop delivery must work on a fresh customer computer without exposing raw developer setup work. Local AI features currently depend on Git, Python, ffmpeg, ComfyUI, Hugging Face downloads, model caches, and feature-specific sidecars, but the product only exposes partial readiness and coarse task progress. Customers need a single Model Center surface that can diagnose, initialize, download, and recover local runtime dependencies with clear guidance.

What Changes

• Expand the desktop runtime readiness contract into a product-wide onboarding and initialization layer surfaced in Model Center.
• Add Windows/macOS first-run checks for OS, architecture, writable runtime directories, disk space, network reachability, Git, Python 3.10+, ffmpeg, ComfyUI, Hugging Face tooling/cache, local model assets, FunClip/ASR, digital-human, voice, and publishing dependencies.
• Add guided dependency resolution: use bundled/runtime-managed dependencies where available, offer safe automatic installers when supported, and provide clear manual steps when administrator permission or external installers are required.
• Add Hugging Face mirror/source selection and realtime model download progress with bytes, percent, speed, ETA, resumable cache awareness, and failure recovery.
• Move customer runtime installs and model caches out of the packaged app directory into a writable per-user TrueGrowth runtime directory by default.
• Surface all initialization tasks through the existing task center and Model Center readiness panels with customer-facing copy, not raw command output.

Impact

• Affected specs:
  • desktop-runtime-readiness
  • runtime-model-discovery
• Affected code:
  • scripts/truegrowth-local-api.mjs
  • apps/web/src/workbench/local-runtime-client.ts
  • apps/web/src/workbench/WorkbenchShell.tsx
  • apps/web/src/workbench/workbench.scss
  • desktop packaging config under apps/electron/
  • future runtime bootstrap/download helper modules under scripts/

Notes

• This change does not promise every customer computer can run every local model. It promises that TrueGrowth will detect constraints, initialize what is safely automatable, and guide unresolved prerequisites in a commercial-grade flow.
• Destructive cleanup of caches, system package installation, and administrator-level changes require explicit user action.