vividkit · thieung · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026
diff --git a/docs/code-standards.md b/docs/code-standards.md
@@ -64,11 +64,12 @@ export function useMyFeature() {
 ```
 
 **Rules:**
-- No async logic in stores — hooks own async + error handling
+- Prefer hooks for UI orchestration and cross-store flows
+- Domain stores may expose async CRUD actions when they call typed Tauri wrappers and own state updates
 - Always catch and log errors (never silent failures)
 - Memoize expensive deps with `useMemo` / `useCallback` if needed
 
-### Tauri IPC Wrapper (src/lib/tauri.ts)
+### Tauri IPC Wrappers (`src/lib/tauri-*.ts` + `src/lib/tauri.ts` barrel)
 
 ```ts
 // Typed wrappers, not raw invoke()
@@ -82,9 +83,10 @@ export async function spawnCcs(args: {
 ```
 
 **Rules:**
+- Group wrappers by domain (`tauri-project`, `tauri-task`, `tauri-settings`, etc.) and re-export via `src/lib/tauri.ts`
 - Every wrapper has typed args + return
 - Always `Promise<T>` return type
-- Error handling at call site (try/catch in component/hook)
+- Error handling at call site (try/catch in component/hook/store action)
 - No `any` argument types
 
 ---
@@ -110,9 +112,10 @@ export const useProjectStore = create<ProjectStore>((set) => ({
 **Rules:**
 - One store per domain (project, task, brainstorm, worktree, etc.)
 - All actions defined inside `create()` callback
-- No async logic — stores hold state only
+- Keep stores focused on state + domain actions; avoid cross-domain orchestration inside store actions
+- Async CRUD actions are allowed in domain stores when backed by typed Tauri wrappers
 - No circular dependencies between stores
-- Custom hooks subscribe and invoke actions
+- Custom hooks subscribe and orchestrate multi-store flows
 
 ---
 

diff --git a/docs/development-roadmap.md b/docs/development-roadmap.md
@@ -15,19 +15,31 @@ Core mechanic: Rust spawns PTY `ccs [profile]`, streamed via xterm.js. UI hides
 
 | Route | Module | Status |
 |-------|--------|--------|
-| `/onboarding` | Onboarding | ⬜ Planned |
-| `/` | Dashboard | ⬜ Planned |
-| `/decks` | Project Deck | ⬜ Planned |
-| `/brainstorm` | Brainstorm | ⬜ Planned |
-| `/brainstorm/:id` | Brainstorm Report | ⬜ Planned |
-| `/generate-plan` | Generate Plan | ⬜ Planned |
-| `/plans` | Plans | ⬜ Planned |
-| `/plans/:id` | Plan Review | ⬜ Planned |
-| `/tasks` | Tasks | ⬜ Planned |
-| `/cook/:taskId` | Cook Standalone | ⬜ Planned |
-| `/worktrees` | Worktrees | ⬜ Planned |
-| `/settings` | Settings | ⬜ Planned |
-| `/new-project` | New Project | ⬜ Planned |
+| `/onboarding` | Onboarding | 🟡 UI prototype |
+| `/` | Dashboard | 🟡 UI prototype |
+| `/decks` | Project Deck | 🟡 UI prototype |
+| `/brainstorm` | Brainstorm | 🟡 UI prototype |
+| `/brainstorm/:id` | Brainstorm Report | 🟡 UI prototype |
+| `/generate-plan` | Generate Plan | 🟡 UI prototype |
+| `/plans` | Plans | 🟡 UI prototype |
+| `/plans/:id` | Plan Review | 🟡 UI prototype |
+| `/tasks` | Tasks | 🟡 UI prototype |
+| `/cook/:taskId` | Cook Standalone | 🟡 UI prototype |
+| `/worktrees` | Worktrees | 🟡 UI prototype |
+| `/settings` | Settings | 🟡 UI prototype |
+| `/new-project` | New Project | 🟡 UI prototype |
+
+### Completion Status
+
+| Layer | Status |
+|-------|--------|
+| UI Components | 🟡 ~80% (routes/components largely present; some flows still prototype/hardcoded) |
+| CCS PTY Integration | ✅ Production-ready (ai.rs) |
+| SQLite Persistence | ✅ M1 foundation implemented (r2d2 pool + v1 migration + SQLite schema) |
+| Git Operations (git2) | ❌ Stubs only |
+| Worktree CRUD | 🟡 Persistence CRUD implemented (`worktree_cmd`); git lifecycle wiring still partial |
+| Store → IPC Integration | 🟡 Core stores wired to Tauri IPC (project/deck/task/plan/brainstorm/worktree/settings); some UI consumers still prototype |
+| i18n Keys | 🟡 Structure ready, keys incomplete |
 
 ---
 
@@ -54,118 +66,53 @@ Core mechanic: Rust spawns PTY `ccs [profile]`, streamed via xterm.js. UI hides
 
 ---
 
-## Phase 1 — Foundation
+## Milestones
 
-**Goal:** App shell, routing, shared layout, SQLite schema, CCS detection.
+### M1 — Data Foundation ✅ Complete (Wave 5 gate passed)
+**Goal:** SQLite persistence + Rust CRUD commands + stores wired to IPC.
+**Ref:** `plans/260224-1104-m1-data-foundation/plan.md`
 
-- [ ] AppLayout: sidebar (collapsible) + header + outlet
-- [ ] AppSidebar: project switcher, main nav, bottom nav, collapsed mode
-- [ ] AppHeader: AI status indicator, theme toggle, notifications
-- [ ] Routing: all 13 routes wired
-- [ ] SQLite schema: all models migrated
-- [ ] CCS detection: `ccs detect` → parse accounts, save to DB
-- [ ] i18n setup: `react-i18next`, `en.json` + `vi.json` base keys
-- [ ] Zustand stores: project, deck, task, worktree, settings
+- [x] SQLite schema: versioned migration for all 9 models (v1 migration + schema_version)
+- [x] Rust CRUD commands: project, deck, task, plan, phase, brainstorm, worktree, key-insight, settings
+- [x] Tauri IPC wrappers: typed invoke functions for all CRUD ops
+- [x] Zustand stores refactor: replace mock data with IPC calls
+- [x] App initialization: DB setup on first launch, load active project
 
----
-
-## Phase 2 — Onboarding
-
-**Goal:** First-run wizard. User exits with git repo + CCS detected + first project created.
-
-- [ ] 4-step wizard UI (progress sidebar)
-- [ ] Step 1: Welcome screen
-- [ ] Step 2: Git setup — local repo picker (Browse) or clone from GitHub URL
-- [ ] Step 3: AI Tools detection — `ccs detect` with spinner → accounts display
-- [ ] Step 4: Project setup — name + description + summary
-- [ ] Navigate to `/` on completion
-
----
-
-## Phase 3 — Dashboard & Decks
-
-**Goal:** Project overview + deck management.
-
-- [ ] Dashboard: stats cards (tasks by status, worktree count)
-- [ ] Dashboard: quick actions grid → all major routes
-- [ ] Decks: deck list with active state toggle
-- [ ] Decks: Create Deck dialog (name, description, based-on insight)
-- [ ] New Project: `/new-project` form (git local/clone + name)
-
----
-
-## Phase 4 — Brainstorm
-
-**Goal:** AI ideation via CCS PTY terminal, save insights, generate plan.
-
-- [ ] Brainstorm: deck context bar + key insights dialog
-- [ ] Brainstorm: PTY terminal panel (idle → running → completed states)
-- [ ] Brainstorm: input area (Enter triggers session)
-- [ ] Brainstorm: post-completion actions (View Report, Create Plan, Save Insight)
-- [ ] Report Preview Dialog: article layout, prose typography
-- [ ] Brainstorm Report page (`/brainstorm/:id`): key insights grid + action items
-- [ ] Key Insights Dialog: list, continue session, delete
-
----
+**Wave 5 quality gates:** Test gate PASS (`cargo check`, `npm run build`), review gate PASS (no release blocker).
+**Post-gate follow-up:** High-priority settings lost-update race was fixed in Task #17 (`settings-store` mutation queue + safer patch merge).
 
-## Phase 5 — Plans
+### M2 — Core Workflows ⬜ Not Started
+**Goal:** Wire real CCS PTY into brainstorm/cook. Plan generation + phase tracking.
+**Depends on:** M1
 
-**Goal:** Plan generation from brainstorm output, phase tracking, markdown preview.
+- [ ] Brainstorm terminal → real CCS session → save report to disk + DB
+- [ ] Plan generation via CCS → parse phases → persist to DB
+- [ ] Task auto-generation from plan phases
+- [ ] Cook terminal → real CCS execution per task
+- [ ] Cook progress: real output streaming (replace mock progress)
 
-- [ ] Generate Plan (`/generate-plan`): phase indicator + xterm.js terminal simulation
-- [ ] Plans list (`/plans`): plan cards with phase progress bar
-- [ ] Plan Review (`/plans/:id`): phases checklist + markdown preview toggle
-- [ ] Plan Review: related tasks section (`?new=true` loading state)
-- [ ] Cook Sheet (right panel): xterm.js terminal executing plan via `ccs [profile]`
+### M3 — Git & Worktree Integration ⬜ Not Started
+**Goal:** git2 operations: status, commit, diff, worktree lifecycle.
+**Depends on:** M1, partially M2
 
----
-
-## Phase 6 — Tasks
-
-**Goal:** Task CRUD, list + kanban views, cook integration.
-
-- [ ] Tasks: toolbar (view toggle, search, status filters, add task)
-- [ ] Tasks: list view with status/priority badges + Cook button
-- [ ] Tasks: kanban view (4 columns: Backlog, Todo, In Progress, Done)
-- [ ] Add Task dialog: name, description, priority
-- [ ] Cook Sheet (right panel): PTY terminal, changed files summary, Merge/Discard
-- [ ] Cook standalone (`/cook/:taskId`): progress bar, status steps, preview changes dialog
-
----
-
-## Phase 7 — Worktrees
-
-**Goal:** Git worktree lifecycle management via UI.
-
-- [ ] Worktrees: list grouped by status (Active, Ready to Merge, Merged)
-- [ ] Worktrees: Active card actions (View Files, Pause, Stop)
-- [ ] Merge Dialog: strategy selector (merge/squash/rebase) + options (run tests, delete after)
-- [ ] Rust: `worktree_create`, `worktree_list`, `worktree_merge`, `worktree_cleanup` commands
-
----
-
-## Phase 8 — Settings
-
-**Goal:** App config — language, CCS provider mapping, git defaults, editor prefs.
-
-- [ ] Settings: 4 tabs (General, AI & Commands, Git, Editor)
-- [ ] General: language selector (en/vi)
-- [ ] AI & Commands: CCS accounts list + command→provider mapping table
-- [ ] Git: default branch + worktrees directory inputs
-- [ ] Editor: theme, auto-save toggle, font size
-
----
+- [ ] git2: `git_status`, `git_diff`, `git_commit`
+- [ ] git2: `worktree_create`, `worktree_list`, `worktree_remove`
+- [ ] git2: `worktree_merge` (merge/squash/rebase strategies)
+- [ ] Wire worktree UI to real git2 commands
+- [ ] Cook flow: create worktree → execute → show diff → merge
 
-## Phase 9 — Polish & Release
+### M4 — Onboarding + Settings + Polish ⬜ Not Started
+**Goal:** First-run wizard, settings persistence, error handling, release prep.
+**Depends on:** M1-M3
 
+- [ ] Onboarding wizard: real CCS detect + git repo picker + project creation
+- [ ] Settings: persist to DB, load on app start
 - [ ] Error boundaries on all routes
 - [ ] Empty states for all list views
 - [ ] Toast notifications system-wide
-- [ ] Offline resilience (CCS not installed, git not configured)
-- [ ] CCS not installed → install guide deep-link
+- [ ] Offline resilience (CCS/git not installed → guide)
 - [ ] Cross-platform testing (macOS, Windows, Linux)
-- [ ] App icon + metadata (Tauri `tauri.conf.json`)
-- [ ] Build pipeline (GitHub Actions)
+- [ ] App icon + metadata + build pipeline
 
 ---
 

diff --git a/docs/project-changelog.md b/docs/project-changelog.md
@@ -0,0 +1,30 @@
+# Project Changelog — VividKit Desktop
+
+## 2026-02-24
+
+### Added
+- M1 Data Foundation backend persistence layer:
+  - SQLite DB bootstrap on app startup via `db::init_db(app_data_dir)`.
+  - Connection pool with PRAGMA initialization (`foreign_keys=ON`, `journal_mode=WAL`).
+  - Versioned migration baseline (`schema_version`, v1 schema, seed row for `app_settings`).
+- New Rust command modules for M1 data domains:
+  - `project`, `deck`, `task`, `plan`, `brainstorm`, `worktree_cmd`, `settings`, `ccs_profile`.
+- Dynamic CCS profile listing command registration:
+  - `list_ccs_profiles` backend command is available in invoke handler.
+- TypeScript domain IPC wrapper split under `src/lib/tauri-*.ts` and barrel export via `src/lib/tauri.ts`.
+
+### Changed
+- Zustand stores were refactored from mock/in-memory flows to real IPC-backed CRUD for core M1 domains:
+  - `project-store`, `deck-store`, `task-store`, `plan-store`, `brainstorm-store`, `worktree-store`, `settings-store`.
+- App initialization now loads persisted settings/projects and restores `lastActiveProjectId` when available.
+- Follow-up hardening after Wave 5 review: `settings-store` now serializes settings writes with a mutation queue and applies safer patch merge logic to avoid lost updates under concurrent writes (Task #17 completed).
+- Settings CCS Test Console now loads profile options from backend `list_ccs_profiles` instead of a hardcoded profile list, with fallback to `default` when discovery is unavailable.
+
+### Quality Gates
+- Wave 5 test gate: PASS (`cargo check`, `npm run build`).
+- Wave 5 code review gate: PASS (no release blocker for M1 Data Foundation).
+- Review follow-up closure: High settings lost-update finding resolved in Task #17.
+
+### Known Issues / Follow-up
+- **M4 scope (prototype):** Onboarding AI Tools detection still uses simulated/hardcoded UI states and account badges.
+- **M4 follow-up (partial):** Onboarding Git Setup Browse now uses Tauri dialog plugin API; broader onboarding real detect/clone workflow is still prototype.
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
@@ -73,6 +73,18 @@ CookView component
 | Tasks | Task CRUD, Kanban state | project context |
 | Cook | PTY terminal sessions, file tree | project path, worktrees |
 
+## M1 Data Foundation Snapshot (2026-02-24)
+
+- SQLite foundation is now initialized at app startup via `db::init_db(app_data_dir)` in `src-tauri/src/lib.rs`.
+- DB runtime uses `r2d2_sqlite` pool with per-connection PRAGMA (`foreign_keys=ON`, `journal_mode=WAL`) in `src-tauri/src/db/mod.rs`.
+- Versioned migration baseline exists (`schema_version` + v1 schema for projects, decks, plans/phases, tasks, brainstorm, worktrees, settings) in `src-tauri/src/db/migrations.rs`.
+- CRUD command surface is registered for M1 domains in `src-tauri/src/lib.rs` (`project`, `deck`, `task`, `plan`, `brainstorm`, `worktree_cmd`, `settings`).
+- Frontend now consumes domain IPC wrappers (`src/lib/tauri-*.ts`) and persists state via Zustand domain stores (`src/stores/*-store.ts`) instead of purely mock/in-memory data.
+
+### Known Non-Blocking Follow-up
+
+- Wave 5 review identified a high-priority settings lost-update race under concurrent writes. Follow-up Task #17 fixed the frontend side in `src/stores/settings-store.ts` using a mutation queue + safer patch merge. M1 remains non-blocked and docs now reflect the resolved follow-up.
+
 ## Key Technology Choices
 
 | Decision | Rationale |

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -17,6 +17,7 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@monaco-editor/react": "^4.7.0",
     "@tauri-apps/api": "^2",
+    "@tauri-apps/plugin-dialog": "^2.6.0",
     "@tauri-apps/plugin-opener": "^2",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",