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

1. Runtime Contract

• 1.1 Define a shared readiness resource schema for system prerequisites, network sources, runtime installs, model assets, services, and feature groups.
• 1.2 Add Local API endpoints for product-level readiness summary, dependency actions, mirror settings, and runtime diagnostics.
• 1.3 Persist runtime settings for managed directory, ComfyUI path, Hugging Face endpoint, mirror choice, and dependency resolution state.
• 1.4 Detect packaged desktop vs local development paths and default production runtime writes to the per-user TrueGrowth directory.
• 1.5 Add platform/architecture detection for Windows, macOS Intel, macOS Apple Silicon, and unsupported environments.

2. Dependency Detection and Initialization

• 2.1 Detect Git, Python 3.10+, ffmpeg, Hugging Face tooling, ComfyUI, ComfyUI custom nodes, FunClip/ASR requirements, digital-human/voice model packages, and publishing runtime dependencies.
• 2.2 Implement managed installation actions where safe: managed runtime directories, Python venv/package setup, ComfyUI clone/update, app-managed custom nodes, and bundled ffmpeg detection.
• 2.3 Add external-action guidance for prerequisites that cannot be safely installed automatically, including Windows/macOS Git/Python, GPU driver/CUDA/MPS notes, and permission issues.
• 2.4 Add resource preflight for disk, memory, network reachability, writable directories, and heavy-runtime start eligibility.
• 2.5 Prevent app boot from auto-starting heavy runtimes; start only from explicit user action with readiness checks.

3. Hugging Face Downloads

• 3.1 Add Hugging Face endpoint/mirror selection and preflight checks in the Local API.
• 3.2 Replace single-file model downloads with streaming byte progress updates.
• 3.3 Add snapshot download helper or structured wrapper that reports file/aggregate progress where possible.
• 3.4 Persist download progress, target paths, cache status, partial/incomplete state, retry/resume information, and errors.
• 3.5 Update ComfyUI model download preflight to include selected endpoint, target directory, disk requirements, and resumable cache state.

4. Model Center UI

• 4.1 Add a Model Center environment panel grouped by system prerequisites, network/mirrors, ComfyUI/image models, AI clipping, digital-human/voice, and publishing.
• 4.2 Display readiness state, source, version/path, progress, next action, and safe guidance for each group.
• 4.3 Add mirror/source selection UI with official/mirror/custom endpoint options.
• 4.4 Show realtime model download progress in Model Center and ensure tasks link to the existing global task center.
• 4.5 Keep feature-specific setup callouts aligned with shared readiness and route unresolved setup actions back to Model Center.
• 4.6 Preserve the /image golden page visual standard, light/dark themes, orange primary actions, compact desktop density, and no topbar reintroduction.

5. Runtime Model Discovery and Feature Integration

• 5.1 Include local model download/readiness metadata in model assets and runtime-discovered local image entries.
• 5.2 Ensure downloaded-but-stopped local image models are discoverable but clearly marked as requiring runtime start.
• 5.3 Ensure downloading or incomplete models do not appear as runnable final selector choices.
• 5.4 Update AI clipping, digital-human, voice, publishing, and ComfyUI feature pages to consume shared readiness status instead of local one-off error copy.

6. Verification

• 6.1 Add unit tests for readiness normalization, platform detection, mirror setting persistence, and download progress math.
• 6.2 Add Local API verifier coverage for fresh-machine simulations: missing Git/Python, managed runtime path, mirror selection, model download progress, interrupted download, and installed-but-stopped ComfyUI.
• 6.3 Add frontend tests or focused component checks for Model Center readiness rendering and progress states.
• 6.4 Run node --check scripts/truegrowth-local-api.mjs.
• 6.5 Run pnpm exec tsc -p apps/web/tsconfig.app.json --noEmit or the closest available project typecheck.
• 6.6 Browser-verify Model Center against the /image golden UI standard with screenshots, console checks, and one primary readiness/download interaction.