Initial TrueGrowth source import

openspec/changes/add-desktop-runtime-readiness/specs/desktop-runtime-readiness/spec.md

@@ -0,0 +1,93 @@
+## ADDED Requirements
+
+### Requirement: Product-Level Runtime Readiness Summary
+The system SHALL expose a product-level local runtime readiness summary for desktop delivery.
+
+#### Scenario: Fresh customer computer opens Model Center
+- **GIVEN** TrueGrowth is running on a desktop computer for the first time
+- **WHEN** the user opens Model Center
+- **THEN** the Local API SHALL report readiness for system prerequisites, network sources, ComfyUI image generation, model downloads, AI clipping, digital-human, voice, and publishing dependencies
+- **AND** every dependency SHALL include status, source, platform support, path or configuration summary, next action, and customer-safe detail text
+- **AND** the UI SHALL not show raw stack traces, raw command output, or developer-only copy
+
+#### Scenario: Runtime uses a writable customer directory
+- **GIVEN** the app is running from a packaged desktop install
+- **WHEN** the readiness summary resolves runtime paths
+- **THEN** managed runtimes, model caches, logs, and downloaded model files SHALL default to a writable per-user TrueGrowth runtime directory
+- **AND** the packaged application directory SHALL not be used as the default write target
+
+### Requirement: Guided Dependency Initialization
+The system SHALL guide or perform dependency initialization for customer machines.
+
+#### Scenario: Dependency can be installed safely by TrueGrowth
+- **GIVEN** a missing dependency can be installed inside the managed runtime directory without administrator privileges
+- **WHEN** the user starts initialization
+- **THEN** the system SHALL create a runtime task
+- **AND** install or prepare the dependency in the managed directory
+- **AND** update readiness and task progress until the dependency is ready or failed
+
+#### Scenario: Dependency requires external action
+- **GIVEN** a missing dependency requires administrator permission, a system installer, GPU driver setup, or another action TrueGrowth cannot safely automate
+- **WHEN** the user views the readiness item
+- **THEN** the system SHALL show OS-specific guidance and a retry/detect action
+- **AND** the system SHALL not silently modify protected system locations
+
+#### Scenario: Git or Python is missing
+- **GIVEN** ComfyUI or another runtime needs Git or Python 3.10+
+- **WHEN** the system checks prerequisites
+- **THEN** the readiness summary SHALL report whether a bundled, managed, configured, or system Git/Python is available
+- **AND** if no valid option exists, the UI SHALL offer automatic managed setup when supported or exact Windows/macOS installation guidance otherwise
+
+### Requirement: Hugging Face Source Selection and Download Progress
+The system SHALL support Hugging Face source selection and realtime model download progress.
+
+#### Scenario: User chooses a download source
+- **GIVEN** the user needs to download a Hugging Face-hosted model
+- **WHEN** the user opens Model Center download settings
+- **THEN** the UI SHALL allow official, configured mirror, or custom endpoint selection
+- **AND** the selected endpoint SHALL be stored in local runtime settings
+- **AND** model download tasks SHALL use that endpoint for Hugging Face downloads
+
+#### Scenario: Single-file model download runs
+- **GIVEN** the user starts a single-file model download such as a ComfyUI checkpoint
+- **WHEN** the download is in progress
+- **THEN** the runtime task SHALL expose downloaded bytes, total bytes when known, percent, speed, ETA, stage text, and target path
+- **AND** Model Center and task center SHALL display the realtime progress
+
+#### Scenario: Snapshot model download runs
+- **GIVEN** the user starts a multi-file Hugging Face snapshot download such as Qwen-Image
+- **WHEN** file or aggregate progress is available
+- **THEN** the runtime task SHALL expose file-level or aggregate progress
+- **AND** when only cache/stage progress is available, the UI SHALL clearly label the progress as stage progress instead of an exact byte percentage
+
+#### Scenario: Download is interrupted
+- **GIVEN** a model download fails or the app exits before completion
+- **WHEN** the user returns to Model Center
+- **THEN** the system SHALL detect partial cache state where possible
+- **AND** offer retry/resume or explicit cache cleanup guidance without deleting data automatically
+
+### Requirement: Model Center Initialization Surface
+Model Center SHALL be the primary discovery and initialization surface for local runtime readiness.
+
+#### Scenario: User prepares a fresh desktop environment
+- **WHEN** the user opens Model Center
+- **THEN** the page SHALL show grouped readiness for system prerequisites, ComfyUI/image models, AI clipping, digital-human/voice, publishing, and network sources
+- **AND** each group SHALL show readiness, progress, primary action, secondary guidance, and whether related product features are usable
+- **AND** actions SHALL create or link to runtime tasks in the existing task center
+
+#### Scenario: A heavy runtime is available but stopped
+- **GIVEN** ComfyUI, FunClip, or another heavy local service is installed but not running
+- **WHEN** Model Center renders the readiness group
+- **THEN** the UI SHALL show it as installed but stopped
+- **AND** the system SHALL not auto-start it on app boot
+- **AND** the start action SHALL perform resource checks before launching
+
+### Requirement: Feature Readiness Degradation
+Feature pages that depend on local runtimes SHALL degrade through the shared readiness model.
+
+#### Scenario: User opens a feature before initialization is complete
+- **GIVEN** a feature depends on an unavailable runtime resource
+- **WHEN** the user opens that feature
+- **THEN** the feature page SHALL show concise setup status and a Model Center action
+- **AND** the feature SHALL preserve usable non-runtime controls where possible
+- **AND** failures SHALL be expressed as setup guidance rather than raw runtime errors