## Context
TrueGrowth desktop already has a local API boundary, task center, Model Center, ComfyUI integration, FunClip-related readiness, social publishing bridge, and local persistence split between Electron `userData` and `.truegrowth-runtime`. Commercial delivery needs a first-run experience that treats these as one runtime estate instead of feature-by-feature setup fragments.

## Goals
- Provide one product-level runtime readiness summary in Model Center.
- Make first-run setup safe for Windows and macOS customers.
- Download Hugging Face model assets with realtime progress and resumable status.
- Prefer bundled or per-user managed dependencies over asking users to install developer tools manually.
- Keep heavy runtimes stopped until the user starts or initializes the feature, avoiding machine-wide freezes.
- Give manual guidance when automation cannot legally or safely complete the step.

## Non-Goals
- Silent administrator-level system modification.
- Guaranteed GPU support on every machine.
- Bundling every model in the desktop installer.
- Replacing ComfyUI, FunClip, social-auto-upload, or Agent-Reach internals.
- Exposing raw install logs, stack traces, command lines, or foreign-brand setup pages to customers.

## Runtime Directory Strategy
- The packaged application directory is treated as read-only.
- Customer runtime state defaults to a per-user TrueGrowth directory:
  - macOS: Electron `app.getPath('userData')` or `~/Library/Application Support/TrueGrowth`
  - Windows: `%APPDATA%/TrueGrowth`
- Runtime installs live under this directory, for example:
  - `runtimes/ComfyUI`
  - `runtimes/python`
  - `runtimes/ffmpeg`
  - `models/comfyui`
  - `cache/huggingface`
  - `logs/runtime`
- Development builds may keep using project-local paths, but the setup summary must explicitly report whether it is using development paths or customer runtime paths.

## Dependency Resolution Strategy
Each dependency is represented as a readiness resource with:
- `id`, `label`, `category`, `platforms`
- `status`: `ready`, `missing`, `needs_action`, `installing`, `downloading`, `failed`, `external`, `unsupported`
- `source`: `bundled`, `managed`, `system`, `configured`, `download`, `manual`, `development`
- `canAutoInstall`, `requiresAdmin`, `requiresRestart`, `requiresNetwork`, `licenseRequired`
- `version`, `path`, `sizeBytes`, `requiredBytes`, `availableBytes`
- `progress` with bytes, percent, speed, ETA, stage, and task id when applicable
- `actions` such as `install`, `download`, `openGuide`, `chooseMirror`, `configurePath`, `retry`, `clearPartial`

Safe automation:
- Install or update dependencies only inside the managed runtime directory.
- Install Python packages into a managed venv or embedded Python when present.
- Clone or update ComfyUI only inside the managed ComfyUI directory.
- Download model files into ComfyUI model directories or managed model cache.
- Use bundled ffmpeg when present; otherwise guide the user or install managed ffmpeg only if the package is available in the app bundle or approved download source.

Manual guidance:
- If Git or Python is absent and no bundled/managed installer is available, show OS-specific install steps.
- If Windows requires Visual C++ runtime, long path support, or GPU driver/CUDA setup, report it as a guided prerequisite.
- If macOS blocks unsigned binaries or quarantine attributes, show customer-safe recovery steps and only remove quarantine for app-managed runtime files when allowed.

## Mirror and Network Strategy
- Provide a runtime source selector with options such as:
  - Hugging Face official
  - configured mirror endpoint
  - custom endpoint
- Store the selected endpoint in local runtime settings.
- Apply the endpoint to Hugging Face CLI/API downloads through `HF_ENDPOINT`.
- Disable Xet by default when it improves compatibility for large downloads, while keeping the setting visible in diagnostics.
- Preflight network access to GitHub, Hugging Face endpoint, and selected mirror with customer-facing status.

## Hugging Face Download Progress
- Single-file downloads should stream response bytes and patch the runtime task with:
  - downloaded bytes
  - total bytes when known
  - percent
  - speed
  - ETA
  - target path
- Snapshot downloads should prefer a controllable download helper over opaque child-process output when possible. The helper should emit structured progress events for files and total bytes.
- If the Hugging Face CLI is used as a fallback, parse progress output when possible; otherwise report stage progress and cache status.
- Incomplete downloads must be resumable when the underlying cache supports it, and the UI must show whether cache cleanup or retry is recommended.

## Model Center UX
- Add a first-run environment panel in Model Center before model cards.
- Group readiness by:
  - System prerequisites
  - Local image / ComfyUI
  - AI clipping / FunClip / ASR
  - Digital human / voice
  - Publishing / browser automation
  - Network and mirrors
- Every group shows readiness, progress, next action, and whether other features can still be used.
- Primary actions use TrueGrowth orange and feed into task center.
- The lower-left global task status remains the global progress entry; no fixed topbar is introduced.

## Safety and Resource Controls
- Do not auto-start heavy services at app boot.
- Before starting ComfyUI/FunClip/ASR, check memory/disk/GPU basics and show expected resource use.
- Allow one runtime initialization task per dependency group at a time.
- Cancellation should stop downloads where possible and leave resumable cache state.
- Logs stay available in diagnostics but are summarized before being shown to users.

## Risks
- Cross-platform dependency installation is fragile. Mitigation: prefer managed/bundled dependencies and degrade to exact guidance.
- Hugging Face snapshot progress is harder than single-file progress. Mitigation: implement a structured helper for official downloads, with CLI parsing as fallback.
- Large local models can exhaust customer disks. Mitigation: preflight every model, show target path and required space, and keep partial-cache cleanup explicit.
- Heavy AI runtimes can freeze weak machines. Mitigation: no automatic heavy service start on boot, readiness/resource checks before launch, and clear unsupported states.