feat: implement API-first settings management and description history tracking

- Migrated settings persistence from localStorage to an API-first approach, ensuring consistency between Electron and web modes.
- Introduced `useSettingsSync` hook for automatic synchronization of settings to the server with debouncing.
- Enhanced feature update logic to track description changes with a history, allowing for better management of feature descriptions.
- Updated various components and services to utilize the new settings structure and description history functionality.
- Removed persist middleware from Zustand store, streamlining state management and improving performance.

apps/ui/src/components/dialogs/file-browser-dialog.tsx

@@ -11,10 +11,10 @@ import {
 import { Button } from '@/components/ui/button';
 import { PathInput } from '@/components/ui/path-input';
 import { Kbd, KbdGroup } from '@/components/ui/kbd';
-import { getJSON, setJSON } from '@/lib/storage';
 import { getDefaultWorkspaceDirectory, saveLastProjectDirectory } from '@/lib/workspace-config';
 import { useOSDetection } from '@/hooks';
 import { apiPost } from '@/lib/api-fetch';
+import { useAppStore } from '@/store/app-store';
 
 interface DirectoryEntry {
   name: string;
@@ -40,28 +40,8 @@ interface FileBrowserDialogProps {
   initialPath?: string;
 }
 
-const RECENT_FOLDERS_KEY = 'file-browser-recent-folders';
 const MAX_RECENT_FOLDERS = 5;
 
-function getRecentFolders(): string[] {
-  return getJSON<string[]>(RECENT_FOLDERS_KEY) ?? [];
-}
-
-function addRecentFolder(path: string): void {
-  const recent = getRecentFolders();
-  // Remove if already exists, then add to front
-  const filtered = recent.filter((p) => p !== path);
-  const updated = [path, ...filtered].slice(0, MAX_RECENT_FOLDERS);
-  setJSON(RECENT_FOLDERS_KEY, updated);
-}
-
-function removeRecentFolder(path: string): string[] {
-  const recent = getRecentFolders();
-  const updated = recent.filter((p) => p !== path);
-  setJSON(RECENT_FOLDERS_KEY, updated);
-  return updated;
-}
-
 export function FileBrowserDialog({
   open,
   onOpenChange,
@@ -78,20 +58,20 @@ export function FileBrowserDialog({
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState('');
   const [warning, setWarning] = useState('');
-  const [recentFolders, setRecentFolders] = useState<string[]>([]);
 
-  // Load recent folders when dialog opens
-  useEffect(() => {
-    if (open) {
-      setRecentFolders(getRecentFolders());
-    }
-  }, [open]);
+  // Use recent folders from app store (synced via API)
+  const recentFolders = useAppStore((s) => s.recentFolders);
+  const setRecentFolders = useAppStore((s) => s.setRecentFolders);
+  const addRecentFolder = useAppStore((s) => s.addRecentFolder);
 
-  const handleRemoveRecent = useCallback((e: React.MouseEvent, path: string) => {
-    e.stopPropagation();
-    const updated = removeRecentFolder(path);
-    setRecentFolders(updated);
-  }, []);
+  const handleRemoveRecent = useCallback(
+    (e: React.MouseEvent, path: string) => {
+      e.stopPropagation();
+      const updated = recentFolders.filter((p) => p !== path);
+      setRecentFolders(updated);
+    },
+    [recentFolders, setRecentFolders]
+  );
 
   const browseDirectory = useCallback(async (dirPath?: string) => {
     setLoading(true);

apps/ui/src/components/views/board-view/dialogs/edit-feature-dialog.tsx

@@ -27,6 +27,7 @@ import {
   Sparkles,
   ChevronDown,
   GitBranch,
+  History,
 } from 'lucide-react';
 import { toast } from 'sonner';
 import { getElectronAPI } from '@/lib/electron';
@@ -55,6 +56,8 @@ import {
   DropdownMenuItem,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import type { DescriptionHistoryEntry } from '@automaker/types';
 import { DependencyTreeDialog } from './dependency-tree-dialog';
 import { isCursorModel, PROVIDER_PREFIXES } from '@automaker/types';
 
@@ -78,7 +81,9 @@ interface EditFeatureDialogProps {
       priority: number;
       planningMode: PlanningMode;
       requirePlanApproval: boolean;
-    }
+    },
+    descriptionHistorySource?: 'enhance' | 'edit',
+    enhancementMode?: 'improve' | 'technical' | 'simplify' | 'acceptance'
   ) => void;
   categorySuggestions: string[];
   branchSuggestions: string[];
@@ -121,6 +126,14 @@ export function EditFeatureDialog({
   const [requirePlanApproval, setRequirePlanApproval] = useState(
     feature?.requirePlanApproval ?? false
   );
+  // Track the source of description changes for history
+  const [descriptionChangeSource, setDescriptionChangeSource] = useState<
+    { source: 'enhance'; mode: 'improve' | 'technical' | 'simplify' | 'acceptance' } | 'edit' | null
+  >(null);
+  // Track the original description when the dialog opened for comparison
+  const [originalDescription, setOriginalDescription] = useState(feature?.description ?? '');
+  // Track if history dropdown is open
+  const [showHistory, setShowHistory] = useState(false);
 
   // Get worktrees setting from store
   const { useWorktrees } = useAppStore();
@@ -135,9 +148,15 @@ export function EditFeatureDialog({
       setRequirePlanApproval(feature.requirePlanApproval ?? false);
       // If feature has no branchName, default to using current branch
       setUseCurrentBranch(!feature.branchName);
+      // Reset history tracking state
+      setOriginalDescription(feature.description ?? '');
+      setDescriptionChangeSource(null);
+      setShowHistory(false);
     } else {
       setEditFeaturePreviewMap(new Map());
       setShowEditAdvancedOptions(false);
+      setDescriptionChangeSource(null);
+      setShowHistory(false);
     }
   }, [feature]);
 
@@ -183,7 +202,21 @@ export function EditFeatureDialog({
       requirePlanApproval,
     };
 
-    onUpdate(editingFeature.id, updates);
+    // Determine if description changed and what source to use
+    const descriptionChanged = editingFeature.description !== originalDescription;
+    let historySource: 'enhance' | 'edit' | undefined;
+    let historyEnhancementMode: 'improve' | 'technical' | 'simplify' | 'acceptance' | undefined;
+
+    if (descriptionChanged && descriptionChangeSource) {
+      if (descriptionChangeSource === 'edit') {
+        historySource = 'edit';
+      } else {
+        historySource = 'enhance';
+        historyEnhancementMode = descriptionChangeSource.mode;
+      }
+    }
+
+    onUpdate(editingFeature.id, updates, historySource, historyEnhancementMode);
     setEditFeaturePreviewMap(new Map());
     setShowEditAdvancedOptions(false);
     onClose();
@@ -247,6 +280,8 @@ export function EditFeatureDialog({
       if (result?.success && result.enhancedText) {
         const enhancedText = result.enhancedText;
         setEditingFeature((prev) => (prev ? { ...prev, description: enhancedText } : prev));
+        // Track that this change was from enhancement
+        setDescriptionChangeSource({ source: 'enhance', mode: enhancementMode });
         toast.success('Description enhanced!');
       } else {
         toast.error(result?.error || 'Failed to enhance description');
@@ -312,12 +347,16 @@ export function EditFeatureDialog({
               <Label htmlFor="edit-description">Description</Label>
               <DescriptionImageDropZone
                 value={editingFeature.description}
-                onChange={(value) =>
+                onChange={(value) => {
                   setEditingFeature({
                     ...editingFeature,
                     description: value,
-                  })
-                }
+                  });
+                  // Track that this change was a manual edit (unless already enhanced)
+                  if (!descriptionChangeSource || descriptionChangeSource === 'edit') {
+                    setDescriptionChangeSource('edit');
+                  }
+                }}
                 images={editingFeature.imagePaths ?? []}
                 onImagesChange={(images) =>
                   setEditingFeature({
@@ -400,6 +439,80 @@ export function EditFeatureDialog({
                 size="sm"
                 variant="icon"
               />
+
+              {/* Version History Button */}
+              {feature?.descriptionHistory && feature.descriptionHistory.length > 0 && (
+                <Popover open={showHistory} onOpenChange={setShowHistory}>
+                  <PopoverTrigger asChild>
+                    <Button type="button" variant="outline" size="sm" className="gap-2">
+                      <History className="w-4 h-4" />
+                      History ({feature.descriptionHistory.length})
+                    </Button>
+                  </PopoverTrigger>
+                  <PopoverContent className="w-80 p-0" align="start">
+                    <div className="p-3 border-b">
+                      <h4 className="font-medium text-sm">Version History</h4>
+                      <p className="text-xs text-muted-foreground mt-1">
+                        Click a version to restore it
+                      </p>
+                    </div>
+                    <div className="max-h-64 overflow-y-auto p-2 space-y-1">
+                      {[...(feature.descriptionHistory || [])]
+                        .reverse()
+                        .map((entry: DescriptionHistoryEntry, index: number) => {
+                          const isCurrentVersion = entry.description === editingFeature.description;
+                          const date = new Date(entry.timestamp);
+                          const formattedDate = date.toLocaleDateString(undefined, {
+                            month: 'short',
+                            day: 'numeric',
+                            hour: '2-digit',
+                            minute: '2-digit',
+                          });
+                          const sourceLabel =
+                            entry.source === 'initial'
+                              ? 'Original'
+                              : entry.source === 'enhance'
+                                ? `Enhanced (${entry.enhancementMode || 'improve'})`
+                                : 'Edited';
+
+                          return (
+                            <button
+                              key={`${entry.timestamp}-${index}`}
+                              onClick={() => {
+                                setEditingFeature((prev) =>
+                                  prev ? { ...prev, description: entry.description } : prev
+                                );
+                                // Mark as edit since user is restoring from history
+                                setDescriptionChangeSource('edit');
+                                setShowHistory(false);
+                                toast.success('Description restored from history');
+                              }}
+                              className={`w-full text-left p-2 rounded-md hover:bg-muted transition-colors ${
+                                isCurrentVersion ? 'bg-muted/50 border border-primary/20' : ''
+                              }`}
+                            >
+                              <div className="flex items-center justify-between gap-2">
+                                <span className="text-xs font-medium">{sourceLabel}</span>
+                                <span className="text-xs text-muted-foreground">
+                                  {formattedDate}
+                                </span>
+                              </div>
+                              <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
+                                {entry.description.slice(0, 100)}
+                                {entry.description.length > 100 ? '...' : ''}
+                              </p>
+                              {isCurrentVersion && (
+                                <span className="text-xs text-primary font-medium mt-1 block">
+                                  Current version
+                                </span>
+                              )}
+                            </button>
+                          );
+                        })}
+                    </div>
+                  </PopoverContent>
+                </Popover>
+              )}
             </div>
             <div className="space-y-2">
               <Label htmlFor="edit-category">Category (optional)</Label>

apps/ui/src/components/views/board-view/hooks/use-board-actions.ts

@@ -23,7 +23,12 @@ interface UseBoardActionsProps {
   runningAutoTasks: string[];
   loadFeatures: () => Promise<void>;
   persistFeatureCreate: (feature: Feature) => Promise<void>;
-  persistFeatureUpdate: (featureId: string, updates: Partial<Feature>) => Promise<void>;
+  persistFeatureUpdate: (
+    featureId: string,
+    updates: Partial<Feature>,
+    descriptionHistorySource?: 'enhance' | 'edit',
+    enhancementMode?: 'improve' | 'technical' | 'simplify' | 'acceptance'
+  ) => Promise<void>;
   persistFeatureDelete: (featureId: string) => Promise<void>;
   saveCategory: (category: string) => Promise<void>;
   setEditingFeature: (feature: Feature | null) => void;
@@ -221,7 +226,9 @@ export function useBoardActions({
         priority: number;
         planningMode?: PlanningMode;
         requirePlanApproval?: boolean;
-      }
+      },
+      descriptionHistorySource?: 'enhance' | 'edit',
+      enhancementMode?: 'improve' | 'technical' | 'simplify' | 'acceptance'
     ) => {
       const finalBranchName = updates.branchName || undefined;
 
@@ -265,7 +272,7 @@ export function useBoardActions({
       };
 
       updateFeature(featureId, finalUpdates);
-      persistFeatureUpdate(featureId, finalUpdates);
+      persistFeatureUpdate(featureId, finalUpdates, descriptionHistorySource, enhancementMode);
       if (updates.category) {
         saveCategory(updates.category);
       }

apps/ui/src/components/views/board-view/hooks/use-board-persistence.ts

@@ -15,7 +15,12 @@ export function useBoardPersistence({ currentProject }: UseBoardPersistenceProps
 
   // Persist feature update to API (replaces saveFeatures)
   const persistFeatureUpdate = useCallback(
-    async (featureId: string, updates: Partial<Feature>) => {
+    async (
+      featureId: string,
+      updates: Partial<Feature>,
+      descriptionHistorySource?: 'enhance' | 'edit',
+      enhancementMode?: 'improve' | 'technical' | 'simplify' | 'acceptance'
+    ) => {
       if (!currentProject) return;
 
       try {
@@ -25,7 +30,13 @@ export function useBoardPersistence({ currentProject }: UseBoardPersistenceProps
           return;
         }
 
-        const result = await api.features.update(currentProject.path, featureId, updates);
+        const result = await api.features.update(
+          currentProject.path,
+          featureId,
+          updates,
+          descriptionHistorySource,
+          enhancementMode
+        );
         if (result.success && result.feature) {
           updateFeature(result.feature.id, result.feature);
         }

apps/ui/src/components/views/board-view/worktree-panel/worktree-panel.tsx

@@ -1,8 +1,8 @@
-import { useState, useEffect, useRef } from 'react';
+import { useEffect, useRef } from 'react';
 import { Button } from '@/components/ui/button';
 import { GitBranch, Plus, RefreshCw, PanelLeftOpen, PanelLeftClose } from 'lucide-react';
 import { cn, pathsEqual } from '@/lib/utils';
-import { getItem, setItem } from '@/lib/storage';
+import { useAppStore } from '@/store/app-store';
 import type { WorktreePanelProps, WorktreeInfo } from './types';
 import {
   useWorktrees,
@@ -14,8 +14,6 @@ import {
 } from './hooks';
 import { WorktreeTab } from './components';
 
-const WORKTREE_PANEL_COLLAPSED_KEY = 'worktree-panel-collapsed';
-
 export function WorktreePanel({
   projectPath,
   onCreateWorktree,
@@ -85,17 +83,11 @@ export function WorktreePanel({
     features,
   });
 
-  // Collapse state with localStorage persistence
-  const [isCollapsed, setIsCollapsed] = useState(() => {
-    const saved = getItem(WORKTREE_PANEL_COLLAPSED_KEY);
-    return saved === 'true';
-  });
+  // Collapse state from store (synced via API)
+  const isCollapsed = useAppStore((s) => s.worktreePanelCollapsed);
+  const setWorktreePanelCollapsed = useAppStore((s) => s.setWorktreePanelCollapsed);
 
-  useEffect(() => {
-    setItem(WORKTREE_PANEL_COLLAPSED_KEY, String(isCollapsed));
-  }, [isCollapsed]);
-
-  const toggleCollapsed = () => setIsCollapsed((prev) => !prev);
+  const toggleCollapsed = () => setWorktreePanelCollapsed(!isCollapsed);
 
   // Periodic interval check (5 seconds) to detect branch changes on disk
   // Reduced from 1s to 5s to minimize GPU/CPU usage from frequent re-renders

apps/ui/src/components/views/settings-view/model-defaults/phase-model-selector.tsx

@@ -358,10 +358,10 @@ export function PhaseModelSelector({
           </PopoverTrigger>
           <PopoverContent
             side="right"
-            align="center"
-            avoidCollisions={false}
+            align="start"
             className="w-[220px] p-1"
             sideOffset={8}
+            collisionPadding={16}
             onCloseAutoFocus={(e) => e.preventDefault()}
           >
             <div className="space-y-1">
@@ -474,10 +474,10 @@ export function PhaseModelSelector({
           </PopoverTrigger>
           <PopoverContent
             side="right"
-            align="center"
-            avoidCollisions={false}
+            align="start"
             className="w-[220px] p-1"
             sideOffset={8}
+            collisionPadding={16}
             onCloseAutoFocus={(e) => e.preventDefault()}
           >
             <div className="space-y-1">