Sync latest TrueGrowth updates

openspec/changes/unify-local-data-persistence/design.md

@@ -0,0 +1,25 @@
+## Context
+The desktop shell already pins Electron `userData`, but development Local API runs can still default to `.truegrowth-runtime`, while packaged or Electron-launched runs use `Application Support/TrueGrowth/runtime`. Browser `localStorage` and `IndexedDB` are origin scoped, so `127.0.0.1:7200` and preview ports cannot share data directly.
+
+## Goals / Non-Goals
+- Goals: make desktop business data survive restarts and port changes, expose storage health, migrate legacy runtime records, and avoid duplicating large media files.
+- Non-Goals: rewrite every browser IndexedDB cache in one step, delete legacy runtime folders, or bundle a new native database dependency.
+
+## Decisions
+- Use `~/Library/Application Support/TrueGrowth/data/truegrowth.sqlite` (platform equivalent on Windows/Linux) as the canonical ledger.
+- Continue using the existing `sqlite3` CLI integration pattern to avoid adding native npm dependencies.
+- Store structured business records as JSON payloads in typed ledger tables, with a `kv` table for aggregate state and migration markers.
+- Keep JSON shadows during migration for compatibility, but prefer SQLite reads whenever available.
+- Index legacy large files by absolute path and local media URL; do not copy the 35GB `.truegrowth-runtime` tree by default.
+
+## Risks / Trade-offs
+- SQLite CLI may be missing on a fresh machine. Mitigation: diagnostics report unavailable status and Local API falls back to existing JSON behavior until the runtime readiness flow installs or bundles SQLite.
+- Browser-only IndexedDB data cannot be read by Node without Chromium internals. Mitigation: make the desktop Local API the authoritative source going forward and keep browser storage as a transitional source.
+- Migration may discover stale or deleted files. Mitigation: diagnostics report missing targets and preserve legacy source metadata.
+
+## Migration Plan
+1. Create canonical data/runtime directories under desktop user data.
+2. Initialize ledger schema and record current storage roots.
+3. Import legacy runtime tasks, cleared task IDs, business workflow JSON/SQLite state, AIGCPanel state, social publishing state, and media file indexes.
+4. Keep legacy files untouched and record migration versions in `storage_migrations`.
+5. Expose diagnostics so support can see which roots are active and which legacy sources were imported.