Sync latest TrueGrowth updates

openspec/changes/unify-local-data-persistence/specs/desktop-local-persistence/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Canonical Desktop Data Root
+TrueGrowth SHALL use a single writable per-user desktop data root as the canonical location for business persistence.
+
+#### Scenario: Local API starts outside Electron
+- **WHEN** the Local API starts without explicit runtime path environment variables
+- **THEN** it resolves the same platform user data root that Electron uses
+- **AND** it stores canonical data under a `data` directory and runtime outputs under a `runtime` directory.
+
+#### Scenario: Electron starts the Local API
+- **WHEN** Electron launches or imports the Local API
+- **THEN** it provides the canonical `TRUEGROWTH_ELECTRON_USER_DATA` and `TRUEGROWTH_RUNTIME_STATE_DIR`
+- **AND** repeated desktop launches use the same persisted data root.
+
+### Requirement: SQLite Business Ledger
+TrueGrowth SHALL store desktop business records in a canonical SQLite ledger.
+
+#### Scenario: Runtime task is created
+- **WHEN** a local runtime task is queued, updated, completed, failed, or cleared
+- **THEN** the task and clear marker are written to the ledger
+- **AND** restarting the Local API restores the latest task state from the ledger.
+
+#### Scenario: Runtime asset is imported or generated
+- **WHEN** a media asset is imported or generated
+- **THEN** its metadata is written to the ledger with local file path and URL identity
+- **AND** the media file remains in the managed runtime output directory or its indexed legacy path.
+
+#### Scenario: Workflow or publishing state changes
+- **WHEN** workflows, schedules, runs, events, accounts, campaigns, or jobs change
+- **THEN** the aggregate state is saved to the ledger
+- **AND** JSON shadow files remain compatible during migration.
+
+### Requirement: Storage Diagnostics And Migration
+TrueGrowth SHALL expose local storage diagnostics and safe migration controls.
+
+#### Scenario: User checks storage health
+- **WHEN** a client requests storage diagnostics
+- **THEN** the response includes canonical paths, active runtime path, SQLite availability, ledger path, legacy source status, and warnings for split roots.
+
+#### Scenario: Legacy project runtime exists
+- **WHEN** migration runs and `.truegrowth-runtime` contains previous records or outputs
+- **THEN** TrueGrowth imports metadata and indexes file paths without deleting or copying large files by default
+- **AND** records the migration result in the ledger.
+
+#### Scenario: User exports or imports local data
+- **WHEN** export or import is requested
+- **THEN** TrueGrowth serializes or restores ledger-managed business data through the Local API
+- **AND** invalid import payloads are rejected without clearing existing data.