Initial ForgeLM import

.planning/research/SUMMARY.md

@@ -0,0 +1,168 @@
+# Project Research Summary
+
+**Project:** AI Backend Studio
+**Domain:** Brownfield runtime workspace UX and state-flow hardening for a local-first Tauri desktop app
+**Researched:** 2026-03-28
+**Confidence:** HIGH
+
+## Executive Summary
+
+AI Backend Studio is already a functioning local-first desktop app for operating local LLM runtimes, selecting models, and chatting against the active backend. The research is consistent on the real problem: this is not a platform rewrite or net-new product architecture effort, it is a trust-and-ownership fix inside the runtime workspace. Experts solve this class of issue by separating live polled runtime state from persisted settings and from unsaved draft form state, then making one runtime workspace the clear control center for status, actions, and configuration.
+
+The recommended approach is conservative and brownfield-friendly: keep React 18, Tauri 2, and TypeScript, add TanStack Query for live runtime polling and command invalidation, use React Hook Form for draft ownership and dirty tracking, and use Zod at the frontend boundary for runtime-safe parsing and validation. Roadmap order matters: first fix the state model, then orchestrate save/start/stop behavior explicitly, then consolidate the UI around that stable ownership model. Doing UI cleanup before state separation would only relocate the same bug.
+
+The main risks are draft loss from polling, race conditions across save/start/stop and async model-discovery flows, and ambiguous operator feedback when validation, runtime health, and command errors share one surface. These are mitigated by explicit state boundaries, explicit command sequencing, request guards for async lookups, clearer error ownership, and regression tests that simulate timer-driven interleavings instead of only happy-path flows.
+
+## Key Findings
+
+### Recommended Stack
+
+The stack recommendation is intentionally narrow: preserve the existing Rust + Tauri + React/TypeScript architecture and add only the feature-scoped libraries needed to fix state ownership and reliability. The problem is not missing framework capability; it is incorrect coupling between polling and editing.
+
+**Core technologies:**
+- `React 18.x`: keep the current desktop UI surface stable and avoid upgrade churn unrelated to the bug.
+- `Tauri 2.x`: keep commands as the authoritative runtime mutation boundary; optionally add events later only for status nudges.
+- `TypeScript 5.5+`: enforce explicit contracts between live snapshot, persisted baseline, and editable draft.
+- `@tanstack/react-query` `5.x`: own polled runtime snapshot state, caching, invalidation, and post-mutation refetch behavior.
+- `react-hook-form` `7.x`: own editable settings draft, dirty tracking, reset semantics, and safe save/cancel flows.
+- `zod` `4.x` plus `@hookform/resolvers` `3.x`: validate and normalize Tauri payloads and form submissions at the boundary.
+
+Critical version guidance is straightforward: keep current framework majors and add current stable Query/RHF/Zod packages, avoiding larger shifts like Redux, Zustand, XState, TanStack Form, or an event-stream rewrite.
+
+### Expected Features
+
+The MVP is defined by trust and operator clarity, not breadth. Users expect one runtime control center where they can safely edit settings, understand what is live versus unsaved, control lifecycle actions with clear feedback, and recover from failure without losing work.
+
+**Must have (table stakes):**
+- Draft-safe settings editing with no background overwrite of dirty fields.
+- Explicit save, cancel, revert, and dirty-state behavior.
+- Unified runtime control center for status, effective config, and lifecycle actions.
+- Clear lifecycle controls with transitional feedback, disablement, and recovery.
+- Effective-versus-draft visibility so operators know what is running versus what is merely edited.
+- Model source/model selection with validation and safe path editing.
+- Restart-required/apply-now signaling and non-destructive error recovery.
+
+**Should have (competitive):**
+- Side-by-side live snapshot and editable draft.
+- Per-setting change impact preview.
+- Inline diagnostics with guided repair actions.
+- Explainable automation around model loading and runtime lifecycle.
+
+**Defer (v2+):**
+- Source-specific preserved drafts across local/remote switching until single-runtime draft safety is solid.
+- Session-safe draft persistence/recovery across reloads after in-session overwrite bugs are fixed.
+- Optimistic model browser and richer compatibility hints after save/apply semantics are stable.
+
+### Architecture Approach
+
+The architecture research is opinionated: use a feature-scoped runtime workspace controller with three explicit state domains - `live runtime state`, `persisted settings baseline`, and `draft settings state`. Status components consume live query state; forms consume only draft state; saves update the baseline and invalidate/refetch the live query. Runtime actions use persisted config unless the user explicitly chooses a composed action like save-then-start.
+
+**Major components:**
+1. `RuntimeWorkspaceProvider` - feature root that composes queries, mutations, and draft ownership.
+2. `useRuntimeWorkspaceQuery` / `useRuntimeCommands` - explicit read/write orchestration for polling and start/stop/save actions.
+3. `RuntimeSettingsDraftProvider` / `RuntimeSettingsForm` - local draft control, dirty tracking, reset/cancel, and safe editing.
+4. `RuntimeStatusPanel` / read-only summary surfaces - live health, readiness, endpoint, last error, and restart-required status.
+5. `RuntimeModelLibraryPanel` / auxiliary queries - model discovery, scans, GPU info, and search isolated from core runtime readiness.
+
+### Critical Pitfalls
+
+1. **Polling clobbers dirty drafts** - prevent by splitting live snapshot, saved baseline, and draft state; never rehydrate dirty form inputs from poll results.
+2. **Save/start/stop are effect-driven instead of command-driven** - prevent by modeling explicit commands and per-operation status instead of chaining effects off render updates.
+3. **Async lookups write back stale intent** - prevent with request IDs, abort/cancel semantics, and checks that a result still matches the current draft context.
+4. **One surface mixes validation, save, health, and operation errors** - prevent by separating error channels and attaching specific remediation copy to each class.
+5. **Polling ignores editing and transition context** - prevent with state-aware refresh policy and explicit revalidation after operations rather than blind fixed-interval refresh everywhere.
+
+## Implications for Roadmap
+
+Based on the combined research, the roadmap should be organized around state ownership boundaries first, then command orchestration, then UI consolidation, then secondary hardening.
+
+### Phase 1: State Split Foundation
+**Rationale:** This is the root dependency for every other improvement and the direct fix for the primary product constraint in `PROJECT.md`.
+**Delivers:** Explicit `live`, `persisted baseline`, and `draft` models; query-backed runtime snapshot; form state no longer reset by polling; regression tests for edit-during-polling flows.
+**Addresses:** Draft-safe editing, explicit save/cancel foundations, effective-vs-draft visibility.
+**Avoids:** Polling overwrites dirty state; happy-path-only test coverage.
+
+### Phase 2: Runtime Command Orchestration
+**Rationale:** Once state ownership is correct, runtime actions can become explicit and predictable instead of effect-coupled.
+**Delivers:** Dedicated save/start/stop/save-then-start mutations, per-operation status, disablement rules, and post-mutation refetch/cache update behavior.
+**Uses:** Tauri commands, TanStack Query mutations, typed payloads, and persisted baseline semantics.
+**Implements:** `useRuntimeCommands`, action bar logic, clearer runtime control semantics.
+**Avoids:** Double-fire races, stop/save confusion, ambiguous busy state.
+
+### Phase 3: Unified Runtime Control Center
+**Rationale:** UI consolidation should happen only after ownership and action semantics are stable.
+**Delivers:** One authoritative runtime workspace that combines status, effective config, draft editing, lifecycle controls, and clear restart/apply messaging while reducing duplication between status card and drawer.
+**Addresses:** Unified runtime control center, lifecycle feedback, diagnostics visibility, reduced split-brain behavior.
+**Avoids:** Split-brain control surfaces and UI rearrangement that preserves the same underlying overwrite bug.
+
+### Phase 4: Async Data-Source and Error-Model Hardening
+**Rationale:** Model scans, search, GPU metadata, path selection, and error messaging are the next reliability bottlenecks after core ownership is stable.
+**Delivers:** Separate auxiliary queries, stale-response guards, mode-aware draft handling, validation/save/health/operation error channels, and operator guidance CTAs.
+**Addresses:** Model selection validation, actionable diagnostics, safe path editing, error recovery without losing work.
+**Avoids:** Stale async writes, hidden-mode leakage, one-banner ambiguity.
+
+### Phase 5: Context-Aware Refresh and Differentiators
+**Rationale:** After the MVP is trustworthy, the team can improve polish and higher-leverage differentiators without destabilizing the core workspace.
+**Delivers:** Adaptive polling or event-assisted refresh, side-by-side live vs draft comparison, impact previews, and selective draft persistence/recovery.
+**Addresses:** Early differentiators and operator confidence improvements.
+**Avoids:** Polling jitter during transitions and premature investment in lower-priority enhancements.
+
+### Phase Ordering Rationale
+
+- State ownership comes first because both the architecture and pitfalls research identify draft overwrite as the highest-severity issue and as the prerequisite for reliable UI changes.
+- Action orchestration comes second because start/stop/save semantics depend on a stable persisted-baseline-versus-draft contract.
+- UI consolidation comes third because the product requirement is one trustworthy control center, but that surface only works if the first two phases are already correct.
+- Async hardening and refresh-policy tuning follow because they refine reliability around model discovery, diagnostics, and transition states rather than defining the core ownership model.
+
+### Research Flags
+
+Phases likely needing deeper research during planning:
+- **Phase 4:** Model discovery/search/GPU flows have more async edge cases, mode interactions, and stale-response risks than the core state split.
+- **Phase 5:** Adaptive polling versus optional Tauri event nudges may need targeted research if the team decides to optimize beyond the current polling model.
+
+Phases with standard patterns (can likely skip research-phase):
+- **Phase 1:** Query-state versus local draft-state separation is well-established and strongly supported by official React and TanStack guidance.
+- **Phase 2:** Explicit query/mutation orchestration over Tauri commands is a standard, well-documented pattern.
+- **Phase 3:** Control-center consolidation is mostly an information-architecture and implementation exercise once state ownership is sound.
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | HIGH | Strongly grounded in local codebase evidence plus official React Hook Form, TanStack Query, Zod, and Tauri documentation. |
+| Features | HIGH | Table stakes align closely with official desktop-tool patterns and the explicit trust constraint in `PROJECT.md`. |
+| Architecture | HIGH | Recommended split is directly supported by repo evidence and official React/TanStack guidance on controlled state and server-state ownership. |
+| Pitfalls | HIGH | Critical failure modes are visible in current code paths and reinforced by official React guidance plus ecosystem examples of the same class of bugs. |
+
+**Overall confidence:** HIGH
+
+### Gaps to Address
+
+- Backend contract clarity: confirm whether Tauri can return a monotonic config `revision` or `updated_at`; if not, plan deep-equality fallback and add revision later.
+- Mode-switch semantics: local/remote switching behavior likely needs explicit product decisions during planning to avoid hidden-value confusion.
+- Refresh policy thresholds: decide when to pause/downshift polling during editing, dialogs, and in-flight operations based on actual UX testing.
+- Differentiator scope: confirm whether side-by-side live-vs-draft comparison enters MVP or remains a post-foundation enhancement.
+
+## Sources
+
+### Primary (HIGH confidence)
+- `.planning/research/STACK.md` - recommended libraries, boundaries, and brownfield implementation guidance.
+- `.planning/research/FEATURES.md` - table stakes, differentiators, anti-features, and MVP priorities.
+- `.planning/research/ARCHITECTURE.md` - state-domain split, component boundaries, query/mutation orchestration, and build order.
+- `.planning/research/PITFALLS.md` - critical failure modes, prevention strategies, and phase warnings.
+- `.planning/PROJECT.md` - product scope, active requirements, constraints, and core value.
+- React official docs via Context7 and react.dev - controlled inputs, preserving/resetting state, and avoiding effect-driven event logic.
+- TanStack Query official docs via Context7 - polling, invalidation, and mutation cache update patterns.
+- React Hook Form official docs - async defaults, reset semantics, and dirty-field-safe form handling.
+- Tauri 2 official docs - command/event communication guidance.
+
+### Secondary (MEDIUM confidence)
+- Docker Desktop, LM Studio, VS Code, and Ollama docs - expectation setting for desktop runtime controls, diagnostics, settings flows, and restart/apply semantics.
+- Ecosystem issue and PR examples cited in the research files - recurring evidence for unsaved-change and stale-async race bugs.
+
+### Tertiary (LOW confidence)
+- None required for the core recommendation; the main conclusions do not depend on single-source speculation.
+
+---
+*Research completed: 2026-03-28*
+*Ready for roadmap: yes*