Reorganize documentation: move all docs to /docs subdirectories

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>

docs/api/COMPLETE_HOOK_LIBRARY.md

@@ -0,0 +1,392 @@
+# Complete Hook Library Reference
+
+## Overview
+
+The CodeForge hook library provides comprehensive, reusable React hooks organized by domain. All hooks are under 150 LOC, fully typed, and designed for composition.
+
+## Organization
+
+```
+src/hooks/
+├── data/              # Data management hooks
+├── ui/                # UI state management hooks
+├── forms/             # Form and validation hooks
+├── feature-ideas/     # Feature-specific hooks
+├── core/              # Core utility hooks
+├── ai/                # AI integration hooks
+└── orchestration/     # JSON orchestration hooks
+```
+
+## Data Management Hooks
+
+### `useArray<T>(key, defaultValue)`
+
+Enhanced array management with persistence.
+
+**Features:**
+- Add/remove items
+- Update items with predicates
+- Find and filter operations
+- Auto-persists to KV store
+
+**Example:**
+```typescript
+import { useArray } from '@/hooks/data'
+
+const { items, add, remove, update, find, count } = useArray<Todo>('todos', [])
+
+add({ id: '1', text: 'Learn hooks', done: false })
+update(
+  (todo) => todo.id === '1',
+  (todo) => ({ ...todo, done: true })
+)
+remove((todo) => todo.done)
+```
+
+### `useCRUD<T>(items, setItems)`
+
+Complete CRUD operations for entity management.
+
+**Features:**
+- Create, read, update, delete operations
+- Selection management
+- Duplicate functionality
+- Type-safe operations
+
+**Example:**
+```typescript
+import { useCRUD } from '@/hooks/data'
+import { useKV } from '@github/spark/hooks'
+
+const [tasks, setTasks] = useKV('tasks', [])
+const {
+  create,
+  update,
+  remove,
+  selected,
+  setSelectedId
+} = useCRUD(tasks, setTasks)
+
+create({ id: '1', name: 'New Task', status: 'pending' })
+update('1', { status: 'completed' })
+setSelectedId('1')
+```
+
+### `useSearch<T>(items, searchKeys, debounceMs)`
+
+Debounced search across multiple fields.
+
+**Features:**
+- Multi-field search
+- Debounced input
+- Type-safe key selection
+- Performance optimized
+
+**Example:**
+```typescript
+import { useSearch } from '@/hooks/data'
+
+const { query, setQuery, results, isSearching } = useSearch(
+  users,
+  ['name', 'email', 'role'],
+  300
+)
+
+// In your component
+<Input value={query} onChange={(e) => setQuery(e.target.value)} />
+{results.map(user => <UserCard key={user.id} user={user} />)}
+```
+
+### `useDebounce<T>(value, delay)`
+
+Debounce any value changes.
+
+**Example:**
+```typescript
+import { useDebounce } from '@/hooks/data'
+
+const [input, setInput] = useState('')
+const debouncedInput = useDebounce(input, 500)
+
+useEffect(() => {
+  // API call with debounced value
+  fetchResults(debouncedInput)
+}, [debouncedInput])
+```
+
+### `useSort<T>(items, defaultKey)`
+
+Sort items by any key with direction toggle.
+
+**Features:**
+- String, number, and generic comparison
+- Toggle ascending/descending
+- Type-safe sort keys
+
+**Example:**
+```typescript
+import { useSort } from '@/hooks/data'
+
+const { sortedItems, sortKey, sortDirection, toggleSort } = useSort(
+  products,
+  'name'
+)
+
+<Button onClick={() => toggleSort('price')}>
+  Sort by Price {sortKey === 'price' && (sortDirection === 'asc' ? '↑' : '↓')}
+</Button>
+```
+
+### `usePagination<T>(items, initialPageSize)`
+
+Client-side pagination with full controls.
+
+**Features:**
+- Page navigation
+- Dynamic page size
+- Has next/prev indicators
+- Total page calculation
+
+**Example:**
+```typescript
+import { usePagination } from '@/hooks/data'
+
+const {
+  items,
+  page,
+  totalPages,
+  nextPage,
+  prevPage,
+  goToPage,
+  hasNext,
+  hasPrev
+} = usePagination(allItems, 20)
+
+<Button onClick={prevPage} disabled={!hasPrev}>Previous</Button>
+<span>Page {page} of {totalPages}</span>
+<Button onClick={nextPage} disabled={!hasNext}>Next</Button>
+```
+
+## UI State Hooks
+
+### `useDialog(initialOpen)`
+
+Simple dialog/modal state management.
+
+**Example:**
+```typescript
+import { useDialog } from '@/hooks/ui'
+
+const { isOpen, open, close, toggle } = useDialog()
+
+<Button onClick={open}>Open Dialog</Button>
+<Dialog open={isOpen} onOpenChange={(open) => open ? open() : close()}>
+  ...
+</Dialog>
+```
+
+### `useTabs<T>(defaultTab)`
+
+Type-safe tab navigation.
+
+**Example:**
+```typescript
+import { useTabs } from '@/hooks/ui'
+
+const { activeTab, switchTab, isActive } = useTabs<'overview' | 'details' | 'settings'>('overview')
+
+<Tabs value={activeTab} onValueChange={switchTab}>
+  <TabsList>
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="details">Details</TabsTrigger>
+  </TabsList>
+</Tabs>
+```
+
+### `useSelection<T>()`
+
+Multi-select state management.
+
+**Features:**
+- Select/deselect individual items
+- Select all/deselect all
+- Toggle selection
+- Selection count
+
+**Example:**
+```typescript
+import { useSelection } from '@/hooks/ui'
+
+const {
+  selectedIds,
+  toggle,
+  selectAll,
+  deselectAll,
+  isSelected,
+  count
+} = useSelection()
+
+<Checkbox
+  checked={isSelected(item.id)}
+  onCheckedChange={() => toggle(item.id)}
+/>
+{count > 0 && <Badge>{count} selected</Badge>}
+```
+
+### `useClipboard(successMessage)`
+
+Copy to clipboard with feedback.
+
+**Example:**
+```typescript
+import { useClipboard } from '@/hooks/ui'
+
+const { copied, copy } = useClipboard('Copied to clipboard!')
+
+<Button onClick={() => copy(codeSnippet)}>
+  {copied ? 'Copied!' : 'Copy'}
+</Button>
+```
+
+## Form Hooks
+
+### `useFormField<T>(initialValue, rules)`
+
+Single form field with validation.
+
+**Features:**
+- Validation rules
+- Touch state
+- Error messages
+- Reset functionality
+
+**Example:**
+```typescript
+import { useFormField } from '@/hooks/forms'
+
+const email = useFormField('', [
+  {
+    validate: (v) => v.includes('@'),
+    message: 'Invalid email'
+  },
+  {
+    validate: (v) => v.length > 0,
+    message: 'Email required'
+  }
+])
+
+<Input
+  value={email.value}
+  onChange={(e) => email.onChange(e.target.value)}
+  onBlur={email.onBlur}
+/>
+{email.touched && email.error && <span>{email.error}</span>}
+```
+
+### `useForm<T>(config)`
+
+Complete form management with validation.
+
+**Features:**
+- Multi-field state
+- Validation schema
+- Async submit handling
+- Touch tracking per field
+
+**Example:**
+```typescript
+import { useForm } from '@/hooks/forms'
+
+const form = useForm({
+  initialValues: {
+    name: '',
+    email: '',
+    message: ''
+  },
+  validate: (values) => {
+    const errors: Record<string, string> = {}
+    if (!values.email.includes('@')) {
+      errors.email = 'Invalid email'
+    }
+    return errors
+  },
+  onSubmit: async (values) => {
+    await api.submitForm(values)
+    toast.success('Form submitted!')
+  }
+})
+
+<form onSubmit={form.handleSubmit}>
+  <Input
+    value={form.values.email}
+    onChange={(e) => form.setValue('email', e.target.value)}
+  />
+  {form.errors.email && <span>{form.errors.email}</span>}
+  <Button type="submit" disabled={form.isSubmitting}>
+    {form.isSubmitting ? 'Submitting...' : 'Submit'}
+  </Button>
+</form>
+```
+
+## Hook Composition
+
+Hooks are designed to be composed together:
+
+```typescript
+import { useArray, useSearch, useSort, usePagination } from '@/hooks/data'
+import { useSelection } from '@/hooks/ui'
+
+function useProductList() {
+  const { items, add, remove, update } = useArray<Product>('products', [])
+  const { results, query, setQuery } = useSearch(items, ['name', 'category'])
+  const { sortedItems, toggleSort } = useSort(results, 'name')
+  const { items: pagedItems, ...pagination } = usePagination(sortedItems, 10)
+  const selection = useSelection<Product>()
+
+  return {
+    products: pagedItems,
+    add,
+    remove,
+    update,
+    search: { query, setQuery },
+    sort: { toggleSort },
+    pagination,
+    selection,
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep hooks focused**: One responsibility per hook
+2. **Use composition**: Combine simple hooks for complex behavior
+3. **Type everything**: Leverage TypeScript for safety
+4. **Handle loading/error**: Always consider async states
+5. **Memoize callbacks**: Use `useCallback` for stable references
+6. **Document dependencies**: Clear about what causes re-renders
+
+## Performance Tips
+
+- Use `useCallback` and `useMemo` where appropriate
+- Avoid creating new objects/arrays in render
+- Leverage the functional update pattern for `setState`
+- Consider `useTransition` for non-urgent updates
+- Profile with React DevTools
+
+## Testing Hooks
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+import { useArray } from '@/hooks/data'
+
+test('useArray adds items correctly', () => {
+  const { result } = renderHook(() => useArray('test-key', []))
+  
+  act(() => {
+    result.current.add({ id: '1', name: 'Test' })
+  })
+  
+  expect(result.current.items).toHaveLength(1)
+  expect(result.current.items[0].name).toBe('Test')
+})
+```

docs/api/HOOK_LIBRARY_DOCS.md

@@ -0,0 +1,411 @@
+# Hook Library Documentation
+
+## Overview
+
+The CodeForge hook library provides a comprehensive set of reusable React hooks organized by purpose. All business logic should be extracted into hooks, keeping components under 150 LOC and focused purely on presentation.
+
+## Directory Structure
+
+```
+src/hooks/
+├── core/               # Core utility hooks
+├── ui/                 # UI state management hooks
+├── config/             # Configuration and page management hooks
+├── features/           # Feature-specific business logic hooks
+├── ai/                 # AI-powered functionality hooks
+└── validation/         # Validation and error checking hooks
+```
+
+## Core Hooks
+
+### `use-kv-state.ts`
+
+Enhanced wrapper around Spark's `useKV` with Zod validation support.
+
+**Usage:**
+```typescript
+import { useKVState } from '@/hooks/core/use-kv-state'
+import { z } from 'zod'
+
+const UserSchema = z.object({
+  name: z.string(),
+  age: z.number().min(0),
+})
+
+const [user, setUser] = useKVState(
+  'user-data',
+  { name: '', age: 0 },
+  UserSchema
+)
+
+// Invalid data is rejected automatically
+setUser({ name: 'John', age: -5 }) // Logs error, keeps previous value
+setUser({ name: 'John', age: 25 })  // Valid, updates state
+```
+
+### `use-debounced-save.ts`
+
+Automatically debounces and saves values after a delay.
+
+**Usage:**
+```typescript
+import { useDebouncedSave } from '@/hooks/core/use-debounced-save'
+import { useKV } from '@github/spark/hooks'
+
+const [code, setCode] = useState('')
+const [, saveCode] = useKV('code-content', '')
+
+useDebouncedSave(code, saveCode, 1000) // Saves 1s after last change
+```
+
+### `use-clipboard.ts`
+
+Copy/paste operations with user feedback.
+
+**Usage:**
+```typescript
+import { useClipboard } from '@/hooks/core/use-clipboard'
+
+const { copy, paste, copied } = useClipboard()
+
+<Button 
+  onClick={() => copy(codeContent, 'Code copied!')}
+  disabled={copied}
+>
+  {copied ? 'Copied!' : 'Copy Code'}
+</Button>
+```
+
+## UI Hooks
+
+### `use-dialog.ts`
+
+Manage dialog open/closed state.
+
+**Usage:**
+```typescript
+import { useDialog } from '@/hooks/ui/use-dialog'
+
+const { open, openDialog, closeDialog, toggleDialog } = useDialog()
+
+<Button onClick={openDialog}>Open Settings</Button>
+<Dialog open={open} onOpenChange={closeDialog}>
+  {/* Dialog content */}
+</Dialog>
+```
+
+### `use-selection.ts`
+
+Multi-select state management.
+
+**Usage:**
+```typescript
+import { useSelection } from '@/hooks/ui/use-selection'
+
+const { 
+  selected, 
+  toggle, 
+  selectAll, 
+  clear, 
+  isSelected,
+  count 
+} = useSelection<string>()
+
+files.map(file => (
+  <Checkbox
+    checked={isSelected(file.id)}
+    onCheckedChange={() => toggle(file.id)}
+  />
+))
+
+<Button onClick={() => selectAll(files.map(f => f.id))}>
+  Select All ({count} selected)
+</Button>
+```
+
+### `use-confirmation.ts`
+
+Confirmation dialog state and actions.
+
+**Usage:**
+```typescript
+import { useConfirmation } from '@/hooks/ui/use-confirmation'
+import { AlertDialog } from '@/components/ui/alert-dialog'
+
+const { state, confirm, handleConfirm, handleCancel } = useConfirmation()
+
+const deleteFile = (fileId: string) => {
+  confirm(
+    'Delete File?',
+    'This action cannot be undone.',
+    () => {
+      // Perform deletion
+      setFiles(files.filter(f => f.id !== fileId))
+    }
+  )
+}
+
+<AlertDialog open={state.open} onOpenChange={handleCancel}>
+  <AlertDialogContent>
+    <AlertDialogTitle>{state.title}</AlertDialogTitle>
+    <AlertDialogDescription>{state.description}</AlertDialogDescription>
+    <AlertDialogFooter>
+      <AlertDialogCancel onClick={handleCancel}>Cancel</AlertDialogCancel>
+      <AlertDialogAction onClick={handleConfirm}>Confirm</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Config Hooks
+
+### `use-page-config.ts`
+
+Load and manage page configurations from KV store.
+
+**Usage:**
+```typescript
+import { usePageConfig, usePageRegistry } from '@/hooks/config/use-page-config'
+
+// Get specific page config
+const { pageConfig } = usePageConfig('code-editor')
+console.log(pageConfig.title) // "Code Editor"
+
+// Get all pages
+const { pages, getPage } = usePageRegistry()
+const dashboardPage = getPage('dashboard')
+```
+
+### `use-layout-state.ts`
+
+Persist layout state (panel sizes, collapsed state) per page.
+
+**Usage:**
+```typescript
+import { useLayoutState } from '@/hooks/config/use-layout-state'
+
+const { layoutState, setPanelSizes, setCollapsed, setActivePanel } = 
+  useLayoutState('code-editor')
+
+<ResizablePanelGroup 
+  onLayout={setPanelSizes}
+  defaultLayout={layoutState.panelSizes}
+>
+  {/* Panels */}
+</ResizablePanelGroup>
+```
+
+### `use-feature-flags.ts`
+
+Runtime feature flag management.
+
+**Usage:**
+```typescript
+import { useFeatureFlags } from '@/hooks/config/use-feature-flags'
+
+const { isEnabled, enable, disable, toggle } = useFeatureFlags()
+
+{isEnabled('ai-improve') && (
+  <Button onClick={handleAIImprove}>
+    AI Improve Code
+  </Button>
+)}
+
+<Switch
+  checked={isEnabled('dark-mode')}
+  onCheckedChange={() => toggle('dark-mode')}
+/>
+```
+
+## Component Size Guidelines
+
+### Rules
+1. **Maximum 150 LOC** per component file
+2. **Extract all business logic** into hooks
+3. **Pure presentation** in components
+4. **Compose smaller components** instead of conditional rendering
+
+### Example: Breaking Down a Large Component
+
+**Before (300+ LOC):**
+```typescript
+// ModelDesigner.tsx - 350 LOC
+export function ModelDesigner() {
+  const [models, setModels] = useKV('models', [])
+  const [selectedModel, setSelectedModel] = useState(null)
+  const [showDialog, setShowDialog] = useState(false)
+  
+  const handleAddModel = async () => {
+    // 50 lines of logic
+  }
+  
+  const handleGenerateWithAI = async () => {
+    // 50 lines of AI logic
+  }
+  
+  return (
+    <div>
+      {/* 200 lines of JSX */}
+    </div>
+  )
+}
+```
+
+**After (<150 LOC each):**
+```typescript
+// hooks/features/use-model-manager.ts - 80 LOC
+export function useModelManager() {
+  const [models, setModels] = useKV('models', [])
+  const [selectedModel, setSelectedModel] = useState(null)
+  
+  const addModel = useCallback(async (model) => {
+    // Business logic
+  }, [])
+  
+  const generateWithAI = useCallback(async (description) => {
+    // AI logic
+  }, [])
+  
+  return { models, selectedModel, setSelectedModel, addModel, generateWithAI }
+}
+
+// components/ModelList.tsx - 80 LOC
+export function ModelList({ models, onSelect, selected }) {
+  return (
+    <ScrollArea>
+      {models.map(model => (
+        <ModelCard 
+          key={model.id}
+          model={model}
+          selected={selected?.id === model.id}
+          onClick={() => onSelect(model)}
+        />
+      ))}
+    </ScrollArea>
+  )
+}
+
+// components/ModelEditor.tsx - 120 LOC
+export function ModelEditor({ model, onChange }) {
+  return (
+    <Card>
+      {/* Editing UI */}
+    </Card>
+  )
+}
+
+// ModelDesigner.tsx - 90 LOC
+export function ModelDesigner() {
+  const { models, selectedModel, setSelectedModel, addModel, generateWithAI } = 
+    useModelManager()
+  const { open, openDialog, closeDialog } = useDialog()
+  
+  return (
+    <div className="flex gap-4">
+      <ModelList 
+        models={models}
+        selected={selectedModel}
+        onSelect={setSelectedModel}
+      />
+      {selectedModel && (
+        <ModelEditor 
+          model={selectedModel}
+          onChange={handleChange}
+        />
+      )}
+      <Dialog open={open} onOpenChange={closeDialog}>
+        {/* AI Dialog */}
+      </Dialog>
+    </div>
+  )
+}
+```
+
+## JSON-Based Page Orchestration
+
+### Page Config Schema
+
+Pages can be defined in JSON and stored in the KV database:
+
+```json
+{
+  "id": "code-editor",
+  "title": "Code Editor",
+  "description": "Edit project files with AI assistance",
+  "icon": "Code",
+  "component": "CodeEditorPage",
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "defaultSizes": [20, 80],
+    "panels": [
+      {
+        "id": "file-tree",
+        "component": "FileExplorer",
+        "minSize": 15,
+        "maxSize": 40
+      },
+      {
+        "id": "editor",
+        "component": "CodeEditor",
+        "minSize": 60
+      }
+    ]
+  },
+  "features": [
+    { "id": "ai-improve", "enabled": true },
+    { "id": "ai-explain", "enabled": true }
+  ],
+  "shortcuts": [
+    { "key": "2", "ctrl": true, "action": "navigate" }
+  ]
+}
+```
+
+### Benefits
+
+1. **Runtime Configuration**: Change page layouts without code changes
+2. **User Customization**: Users can configure their own layouts
+3. **Feature Flags**: Enable/disable features per page
+4. **A/B Testing**: Test different layouts easily
+5. **Persistence**: Layouts save automatically to KV store
+
+## Migration Checklist
+
+When refactoring a large component:
+
+- [ ] Identify business logic vs presentation
+- [ ] Extract business logic into hooks (`/hooks/features/`)
+- [ ] Break JSX into smaller components (<150 LOC each)
+- [ ] Create atomic components where applicable
+- [ ] Add component to page config JSON
+- [ ] Update component registry
+- [ ] Test isolated components
+- [ ] Update documentation
+
+## Best Practices
+
+1. **One Hook, One Responsibility**: Each hook should manage one concern
+2. **Hooks Return Objects**: Return `{ value, actions }` for clarity
+3. **Memoize Callbacks**: Use `useCallback` for functions passed as props
+4. **Type Everything**: Full TypeScript types for all hooks
+5. **Test Hooks**: Write unit tests for hook logic
+6. **Document Hooks**: Add JSDoc comments explaining purpose and usage
+7. **Validate with Zod**: Use schemas for complex data structures
+8. **Handle Loading/Error States**: Return `{ data, loading, error }` pattern
+
+## Next Steps
+
+1. Extract business logic from top 5 largest components
+2. Break down FeatureIdeaCloud (829 LOC) into 6 smaller components
+3. Create remaining feature hooks (file-manager, workflow-manager, etc.)
+4. Build PageOrchestrator component to render from JSON configs
+5. Add UI for editing page layouts
+6. Migrate all pages to JSON configuration system
+
+## Resources
+
+- [REFACTOR_PHASE2.md](./REFACTOR_PHASE2.md) - Complete refactoring plan
+- [React Hooks Documentation](https://react.dev/reference/react/hooks)
+- [Zod Documentation](https://zod.dev/)
+- [Atomic Design Methodology](https://bradfrost.com/blog/post/atomic-web-design/)

docs/api/HOOK_LIBRARY_REFERENCE.md

@@ -0,0 +1,760 @@
+# Hook Library Reference
+
+## Overview
+
+The CodeForge hook library provides a comprehensive set of reusable hooks for managing application state, UI interactions, and business logic. All hooks follow React best practices and are fully typed with TypeScript.
+
+## Table of Contents
+
+1. [Data Management Hooks](#data-management-hooks)
+2. [Core Utility Hooks](#core-utility-hooks)
+3. [UI State Hooks](#ui-state-hooks)
+4. [Form Hooks](#form-hooks)
+5. [Canvas Hooks](#canvas-hooks)
+6. [AI Hooks](#ai-hooks)
+7. [Orchestration Hooks](#orchestration-hooks)
+
+## Data Management Hooks
+
+### useFiles
+
+Manage project files with full CRUD operations.
+
+```typescript
+import { useFiles } from '@/hooks/data/use-files'
+
+function MyComponent() {
+  const {
+    files,           // ProjectFile[]
+    addFile,         // (file: ProjectFile) => void
+    updateFile,      // (id: string, updates: Partial<ProjectFile>) => void
+    deleteFile,      // (id: string) => void
+    getFile,         // (id: string) => ProjectFile | undefined
+    updateFileContent // (id: string, content: string) => void
+  } = useFiles()
+  
+  // Usage
+  addFile({
+    id: 'new-file',
+    name: 'App.tsx',
+    path: '/src/App.tsx',
+    content: 'export default function App() {}',
+    language: 'typescript'
+  })
+}
+```
+
+### useModels
+
+Manage Prisma models.
+
+```typescript
+import { useModels } from '@/hooks/data/use-models'
+
+function ModelDesigner() {
+  const {
+    models,       // PrismaModel[]
+    addModel,     // (model: PrismaModel) => void
+    updateModel,  // (id: string, updates: Partial<PrismaModel>) => void
+    deleteModel,  // (id: string) => void
+    getModel      // (id: string) => PrismaModel | undefined
+  } = useModels()
+  
+  // Add a new model
+  addModel({
+    id: 'user-model',
+    name: 'User',
+    fields: [
+      { name: 'id', type: 'String', isId: true },
+      { name: 'email', type: 'String', isUnique: true }
+    ],
+    relations: []
+  })
+}
+```
+
+### useComponents
+
+Manage React components.
+
+```typescript
+import { useComponents } from '@/hooks/data/use-components'
+
+function ComponentBuilder() {
+  const {
+    components,      // ComponentNode[]
+    addComponent,    // (component: ComponentNode) => void
+    updateComponent, // (id: string, updates: Partial<ComponentNode>) => void
+    deleteComponent, // (id: string) => void
+    getComponent     // (id: string) => ComponentNode | undefined
+  } = useComponents()
+}
+```
+
+### useWorkflows
+
+Manage n8n-style workflows.
+
+```typescript
+import { useWorkflows } from '@/hooks/data/use-workflows'
+
+function WorkflowDesigner() {
+  const {
+    workflows,       // Workflow[]
+    addWorkflow,     // (workflow: Workflow) => void
+    updateWorkflow,  // (id: string, updates: Partial<Workflow>) => void
+    deleteWorkflow,  // (id: string) => void
+    getWorkflow      // (id: string) => Workflow | undefined
+  } = useWorkflows()
+}
+```
+
+### useLambdas
+
+Manage serverless functions.
+
+```typescript
+import { useLambdas } from '@/hooks/data/use-lambdas'
+
+function LambdaDesigner() {
+  const {
+    lambdas,       // Lambda[]
+    addLambda,     // (lambda: Lambda) => void
+    updateLambda,  // (id: string, updates: Partial<Lambda>) => void
+    deleteLambda,  // (id: string) => void
+    getLambda      // (id: string) => Lambda | undefined
+  } = useLambdas()
+}
+```
+
+## Core Utility Hooks
+
+### useKVState
+
+Enhanced KV storage with validation and transformations.
+
+```typescript
+import { useKVState } from '@/hooks/core/use-kv-state'
+
+function MyComponent() {
+  const [value, setValue] = useKVState({
+    key: 'my-data',
+    defaultValue: { count: 0 },
+    validate: (data) => data.count >= 0,
+    transform: (data) => ({ ...data, lastUpdated: Date.now() })
+  })
+}
+```
+
+### useClipboard
+
+Copy to clipboard with feedback.
+
+```typescript
+import { useClipboard } from '@/hooks/core/use-clipboard'
+
+function CopyButton({ text }: { text: string }) {
+  const { copy, copied } = useClipboard()
+  
+  return (
+    <button onClick={() => copy(text)}>
+      {copied ? 'Copied!' : 'Copy'}
+    </button>
+  )
+}
+```
+
+### useDebouncedSave
+
+Auto-save with debouncing.
+
+```typescript
+import { useDebouncedSave } from '@/hooks/core/use-debounced-save'
+
+function Editor() {
+  const [content, setContent] = useState('')
+  
+  useDebouncedSave(content, async (value) => {
+    await saveToServer(value)
+  }, 1000) // 1 second delay
+  
+  return <textarea value={content} onChange={e => setContent(e.target.value)} />
+}
+```
+
+## UI State Hooks
+
+### useDialog
+
+Manage dialog/modal state.
+
+```typescript
+import { useDialog } from '@/hooks/ui/use-dialog'
+
+function MyComponent() {
+  const { isOpen, open, close, toggle } = useDialog()
+  
+  return (
+    <>
+      <button onClick={open}>Open Dialog</button>
+      <Dialog open={isOpen} onOpenChange={close}>
+        {/* Dialog content */}
+      </Dialog>
+    </>
+  )
+}
+```
+
+### useConfirmation
+
+Confirm dangerous actions.
+
+```typescript
+import { useConfirmation } from '@/hooks/ui/use-confirmation'
+
+function DeleteButton({ onDelete }: { onDelete: () => void }) {
+  const { confirm, ConfirmDialog } = useConfirmation({
+    title: 'Delete Item',
+    description: 'Are you sure? This cannot be undone.',
+    confirmText: 'Delete',
+    variant: 'destructive'
+  })
+  
+  const handleDelete = async () => {
+    if (await confirm()) {
+      onDelete()
+    }
+  }
+  
+  return (
+    <>
+      <button onClick={handleDelete}>Delete</button>
+      <ConfirmDialog />
+    </>
+  )
+}
+```
+
+### useSelection
+
+Manage item selection (single or multiple).
+
+```typescript
+import { useSelection } from '@/hooks/ui/use-selection'
+
+function ItemList({ items }: { items: Item[] }) {
+  const {
+    selected,      // Set<string>
+    isSelected,    // (id: string) => boolean
+    toggle,        // (id: string) => void
+    selectAll,     // () => void
+    deselectAll,   // () => void
+    selectedCount  // number
+  } = useSelection({ multi: true })
+  
+  return (
+    <div>
+      {items.map(item => (
+        <div
+          key={item.id}
+          onClick={() => toggle(item.id)}
+          className={isSelected(item.id) ? 'selected' : ''}
+        >
+          {item.name}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### useModal
+
+Enhanced modal with data passing.
+
+```typescript
+import { useModal } from '@/hooks/ui/use-modal'
+
+function App() {
+  const { isOpen, data, open, close } = useModal<{ userId: string }>()
+  
+  return (
+    <>
+      <button onClick={() => open({ userId: '123' })}>
+        Edit User
+      </button>
+      {isOpen && <UserModal userId={data?.userId} onClose={close} />}
+    </>
+  )
+}
+```
+
+### useTabs
+
+Manage tab state with URL sync.
+
+```typescript
+import { useTabs } from '@/hooks/ui/use-tabs'
+
+function TabbedInterface() {
+  const { activeTab, setTab, tabs } = useTabs({
+    tabs: ['overview', 'details', 'settings'],
+    defaultTab: 'overview',
+    syncWithUrl: true
+  })
+  
+  return (
+    <Tabs value={activeTab} onValueChange={setTab}>
+      {/* Tab content */}
+    </Tabs>
+  )
+}
+```
+
+### usePanels
+
+Manage resizable panel state.
+
+```typescript
+import { usePanels } from '@/hooks/ui/use-panels'
+
+function SplitView() {
+  const { sizes, setSizes, collapsed, togglePanel } = usePanels({
+    defaultSizes: [30, 70],
+    minSizes: [20, 50]
+  })
+  
+  return (
+    <ResizablePanelGroup sizes={sizes} onResize={setSizes}>
+      {/* Panels */}
+    </ResizablePanelGroup>
+  )
+}
+```
+
+## Form Hooks
+
+### useFormState
+
+Comprehensive form state management.
+
+```typescript
+import { useFormState } from '@/hooks/forms/use-form-state'
+
+function UserForm() {
+  const {
+    values,         // Current form values
+    errors,         // Validation errors
+    touched,        // Touched fields
+    isValid,        // Form validity
+    isDirty,        // Form has changes
+    isSubmitting,   // Submission state
+    setValue,       // Set single field
+    setValues,      // Set multiple fields
+    setError,       // Set error
+    handleSubmit,   // Submit handler
+    reset           // Reset form
+  } = useFormState({
+    initialValues: {
+      name: '',
+      email: ''
+    },
+    validate: (values) => {
+      const errors: any = {}
+      if (!values.email) errors.email = 'Required'
+      return errors
+    },
+    onSubmit: async (values) => {
+      await saveUser(values)
+    }
+  })
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={values.name}
+        onChange={e => setValue('name', e.target.value)}
+      />
+      {errors.name && <span>{errors.name}</span>}
+    </form>
+  )
+}
+```
+
+### useValidation
+
+Reusable validation logic.
+
+```typescript
+import { useValidation } from '@/hooks/forms/use-validation'
+
+function PasswordField() {
+  const { validate, errors, isValid } = useValidation({
+    rules: {
+      minLength: 8,
+      hasNumber: true,
+      hasSpecialChar: true
+    }
+  })
+  
+  const handleChange = (value: string) => {
+    validate(value)
+  }
+}
+```
+
+### useFieldArray
+
+Manage dynamic form arrays.
+
+```typescript
+import { useFieldArray } from '@/hooks/forms/use-field-array'
+
+function ContactsForm() {
+  const {
+    fields,    // Array of field values
+    append,    // Add new field
+    remove,    // Remove field
+    move,      // Reorder fields
+    update     // Update specific field
+  } = useFieldArray({
+    name: 'contacts',
+    defaultValue: []
+  })
+  
+  return (
+    <div>
+      {fields.map((field, index) => (
+        <div key={index}>
+          <input value={field.email} />
+          <button onClick={() => remove(index)}>Remove</button>
+        </div>
+      ))}
+      <button onClick={() => append({ email: '' })}>
+        Add Contact
+      </button>
+    </div>
+  )
+}
+```
+
+## Canvas Hooks
+
+### useCanvas
+
+Canvas drawing utilities.
+
+```typescript
+import { useCanvas } from '@/hooks/canvas/use-canvas'
+
+function DrawingCanvas() {
+  const {
+    canvasRef,
+    ctx,
+    clear,
+    drawLine,
+    drawRect,
+    drawCircle,
+    getImageData,
+    setImageData
+  } = useCanvas({
+    width: 800,
+    height: 600
+  })
+  
+  return <canvas ref={canvasRef} />
+}
+```
+
+### useDragDrop
+
+Drag and drop for canvas elements.
+
+```typescript
+import { useDragDrop } from '@/hooks/canvas/use-drag-drop'
+
+function DraggableElements() {
+  const {
+    elements,        // Array of positioned elements
+    draggedId,       // Currently dragged element
+    handleMouseDown, // Start drag
+    handleMouseMove, // During drag
+    handleMouseUp,   // End drag
+    updatePosition,  // Programmatic position update
+  } = useDragDrop({
+    initialElements: [
+      { id: '1', x: 100, y: 100, width: 50, height: 50 }
+    ]
+  })
+}
+```
+
+### useZoomPan
+
+Zoom and pan for canvas views.
+
+```typescript
+import { useZoomPan } from '@/hooks/canvas/use-zoom-pan'
+
+function ZoomableCanvas() {
+  const {
+    zoom,           // Current zoom level
+    pan,            // Pan offset { x, y }
+    zoomIn,         // Increase zoom
+    zoomOut,        // Decrease zoom
+    resetZoom,      // Reset to default
+    setPan,         // Set pan position
+    transform       // CSS transform string
+  } = useZoomPan({
+    minZoom: 0.1,
+    maxZoom: 5,
+    defaultZoom: 1
+  })
+  
+  return (
+    <div style={{ transform }}>
+      {/* Canvas content */}
+    </div>
+  )
+}
+```
+
+### useConnections
+
+Manage node connections (for diagrams/workflows).
+
+```typescript
+import { useConnections } from '@/hooks/canvas/use-connections'
+
+function FlowDiagram() {
+  const {
+    connections,      // Array of connections
+    addConnection,    // Add new connection
+    removeConnection, // Remove connection
+    updateConnection, // Update connection
+    getConnections    // Get connections for node
+  } = useConnections({
+    validate: (from, to) => from !== to // No self-connections
+  })
+}
+```
+
+## AI Hooks
+
+### useAIGenerate
+
+Generate content with AI.
+
+```typescript
+import { useAIGenerate } from '@/hooks/ai/use-ai-generate'
+
+function AIAssistant() {
+  const {
+    generate,      // (prompt: string) => Promise<string>
+    isGenerating,  // boolean
+    result,        // Generated content
+    error          // Error if any
+  } = useAIGenerate()
+  
+  const handleGenerate = async () => {
+    const code = await generate('Create a React login form')
+    console.log(code)
+  }
+}
+```
+
+### useAIComplete
+
+AI code completion.
+
+```typescript
+import { useAIComplete } from '@/hooks/ai/use-ai-complete'
+
+function CodeEditor() {
+  const {
+    complete,        // (prefix: string) => Promise<string>
+    suggestions,     // string[]
+    isCompleting,    // boolean
+    acceptSuggestion // (index: number) => void
+  } = useAIComplete({
+    debounce: 300
+  })
+}
+```
+
+### useAISuggestions
+
+Get AI suggestions for improvements.
+
+```typescript
+import { useAISuggestions } from '@/hooks/ai/use-ai-suggestions'
+
+function CodeReview() {
+  const {
+    getSuggestions,   // (code: string) => Promise<Suggestion[]>
+    suggestions,      // Suggestion[]
+    applySuggestion,  // (id: string) => void
+    dismissSuggestion // (id: string) => void
+  } = useAISuggestions()
+}
+```
+
+## Orchestration Hooks
+
+### usePage
+
+Execute a page schema.
+
+```typescript
+import { usePage } from '@/hooks/orchestration/use-page'
+import pageSchema from '@/config/pages/my-page.json'
+
+function DynamicPage() {
+  const {
+    context,     // Data context
+    execute,     // Execute action by ID
+    isExecuting, // boolean
+    handlers,    // Action handlers map
+    schema       // Page schema
+  } = usePage(pageSchema)
+  
+  return <PageRenderer schema={schema} />
+}
+```
+
+### useActions
+
+Execute page actions.
+
+```typescript
+import { useActions } from '@/hooks/orchestration/use-actions'
+
+function ActionButtons() {
+  const { execute, isExecuting, handlers } = useActions(
+    [
+      {
+        id: 'save',
+        type: 'update',
+        params: { target: 'Files' }
+      }
+    ],
+    { files: [], setFiles: () => {} }
+  )
+  
+  return (
+    <button onClick={() => execute('save')} disabled={isExecuting}>
+      Save
+    </button>
+  )
+}
+```
+
+## Hook Composition Patterns
+
+### Combining Multiple Hooks
+
+```typescript
+function FeaturePage() {
+  const files = useFiles()
+  const models = useModels()
+  const { isOpen, open, close } = useDialog()
+  const { selected, toggle } = useSelection()
+  
+  // Combine hooks to build complex features
+  const handleCreateModel = () => {
+    const model = createModelFromFiles(files.files)
+    models.addModel(model)
+    close()
+  }
+}
+```
+
+### Custom Hook Composition
+
+```typescript
+function useProjectEditor() {
+  const files = useFiles()
+  const { isOpen, open, close } = useDialog()
+  const [activeFileId, setActiveFileId] = useState<string | null>(null)
+  
+  const openFile = (id: string) => {
+    setActiveFileId(id)
+    open()
+  }
+  
+  const saveFile = (content: string) => {
+    if (activeFileId) {
+      files.updateFileContent(activeFileId, content)
+    }
+  }
+  
+  return {
+    files: files.files,
+    activeFile: files.getFile(activeFileId),
+    openFile,
+    saveFile,
+    isEditing: isOpen,
+    closeEditor: close
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Use Functional Updates
+
+```typescript
+// ❌ Bad - May cause data loss
+setFiles([...files, newFile])
+
+// ✅ Good - Always gets current state
+setFiles(current => [...current, newFile])
+```
+
+### 2. Memoize Expensive Computations
+
+```typescript
+const filteredFiles = useMemo(() => {
+  return files.filter(f => f.name.includes(search))
+}, [files, search])
+```
+
+### 3. Clean Up Side Effects
+
+```typescript
+useEffect(() => {
+  const subscription = subscribe()
+  return () => subscription.unsubscribe()
+}, [])
+```
+
+### 4. Type Your Hooks
+
+```typescript
+function useTypedData<T>(key: string, defaultValue: T) {
+  const [data, setData] = useKV<T>(key, defaultValue)
+  return { data, setData }
+}
+```
+
+### 5. Extract Reusable Logic
+
+```typescript
+// Extract common patterns into custom hooks
+function useResource<T>(resourceName: string) {
+  const [items, setItems] = useKV<T[]>(`${resourceName}-items`, [])
+  
+  const add = useCallback((item: T) => {
+    setItems(current => [...current, item])
+  }, [setItems])
+  
+  return { items, add }
+}
+```
+
+## Next Steps
+
+- Explore `/src/hooks/` directory for implementations
+- Check `../architecture/JSON_ORCHESTRATION_GUIDE.md` for page schemas
+- See `REFACTOR_PHASE3.md` for architecture overview
+- Read individual hook files for detailed implementation notes

docs/architecture/ARCHITECTURE_VISUAL_GUIDE.md

@@ -0,0 +1,372 @@
+# Architecture Visual Guide
+
+## System Architecture Diagram
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│                         CODEFORGE APPLICATION                          │
+│                                                                        │
+│  ┌──────────────────────────────────────────────────────────────────┐ │
+│  │                    PRESENTATION LAYER                            │ │
+│  │                                                                  │ │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │ │
+│  │  │  React       │  │  Existing    │  │  JSON-Driven │         │ │
+│  │  │  Components  │  │  Components  │  │  Pages       │         │ │
+│  │  │  (<150 LOC)  │  │  (Migrating) │  │  (New)       │         │ │
+│  │  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘         │ │
+│  └─────────┼──────────────────┼──────────────────┼────────────────┘ │
+│            │                  │                  │                   │
+│  ┌─────────▼──────────────────▼──────────────────▼────────────────┐ │
+│  │                   ORCHESTRATION LAYER                          │ │
+│  │                                                                │ │
+│  │  ┌──────────────────┐         ┌─────────────────────────┐    │ │
+│  │  │  PageRenderer    │◄────────┤  JSON Page Schemas      │    │ │
+│  │  │  - Interprets    │         │  - Structure            │    │ │
+│  │  │    schemas       │         │  - Data sources         │    │ │
+│  │  │  - Renders       │         │  - Actions              │    │ │
+│  │  │    components    │         │  - Components           │    │ │
+│  │  └────────┬─────────┘         └─────────────────────────┘    │ │
+│  │           │                                                   │ │
+│  │  ┌────────▼──────────┐  ┌───────────────┐  ┌─────────────┐  │ │
+│  │  │  Component        │  │  Action       │  │  Data Source│  │ │
+│  │  │  Registry         │  │  Executor     │  │  Manager    │  │ │
+│  │  │  - Lookup         │  │  - Execute    │  │  - KV store │  │ │
+│  │  │  - Resolution     │  │  - Navigate   │  │  - API calls│  │ │
+│  │  └───────────────────┘  └───────────────┘  └─────────────┘  │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│            │                  │                  │                │
+│  ┌─────────▼──────────────────▼──────────────────▼─────────────┐ │
+│  │                      BUSINESS LOGIC LAYER                    │ │
+│  │                     (Hook Library)                           │ │
+│  │                                                              │ │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │ │
+│  │  │  Data Hooks  │  │  UI Hooks    │  │  Form Hooks  │     │ │
+│  │  ├──────────────┤  ├──────────────┤  ├──────────────┤     │ │
+│  │  │ useArray     │  │ useDialog    │  │ useForm      │     │ │
+│  │  │ useCRUD      │  │ useTabs      │  │ useFormField │     │ │
+│  │  │ useSearch    │  │ useSelection │  │              │     │ │
+│  │  │ useSort      │  │ useClipboard │  │              │     │ │
+│  │  │ usePagination│  │              │  │              │     │ │
+│  │  │ useDebounce  │  │              │  │              │     │ │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘     │ │
+│  │                                                              │ │
+│  │  ┌──────────────────────────────────────────────────────┐  │ │
+│  │  │           Feature-Specific Hooks                     │  │ │
+│  │  ├──────────────────────────────────────────────────────┤  │ │
+│  │  │  use-feature-ideas, use-idea-groups,                │  │ │
+│  │  │  use-idea-connections, use-node-positions, etc.     │  │ │
+│  │  └──────────────────────────────────────────────────────┘  │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│            │                                                     │
+│  ┌─────────▼─────────────────────────────────────────────────┐ │
+│  │                  RUNTIME/PLATFORM LAYER                   │ │
+│  │                                                           │ │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │ │
+│  │  │  Spark KV    │  │  Spark LLM   │  │  Spark User  │   │ │
+│  │  │  Storage     │  │  API         │  │  API         │   │ │
+│  │  └──────────────┘  └──────────────┘  └──────────────┘   │ │
+│  └───────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow Diagram
+
+### Traditional React Component Flow
+```
+User Action
+    │
+    ▼
+Component State
+    │
+    ▼
+Inline Logic
+    │
+    ▼
+Direct KV Access
+    │
+    ▼
+UI Update
+```
+
+### New Hook-Based Flow
+```
+User Action
+    │
+    ▼
+Component (Presentation Only)
+    │
+    ▼
+Custom Hook
+    │
+    ├──► Business Logic
+    ├──► Data Management
+    ├──► State Updates
+    └──► Side Effects
+    │
+    ▼
+Spark KV/API
+    │
+    ▼
+UI Update
+```
+
+### JSON-Orchestrated Flow
+```
+JSON Schema Definition
+    │
+    ├──► Data Sources
+    │       │
+    │       ▼
+    │   KV Store / API
+    │
+    ├──► Component Tree
+    │       │
+    │       ▼
+    │   Component Registry
+    │       │
+    │       ▼
+    │   React Components
+    │
+    ├──► Actions
+    │       │
+    │       ▼
+    │   Action Executor
+    │       │
+    │       ▼
+    │   Data Updates
+    │
+    └──► PageRenderer
+            │
+            ▼
+        Final UI
+```
+
+## Component Lifecycle
+
+### Before Refactoring
+```
+┌─────────────────────────────────────┐
+│      Large Component (500+ LOC)     │
+│                                     │
+│  • Business Logic                   │
+│  • State Management                 │
+│  • Data Fetching                    │
+│  • Validation                       │
+│  • UI Rendering                     │
+│  • Event Handlers                   │
+│  • Side Effects                     │
+│                                     │
+│  ❌ Hard to test                    │
+│  ❌ Hard to reuse                   │
+│  ❌ Hard to maintain                │
+└─────────────────────────────────────┘
+```
+
+### After Refactoring
+```
+┌─────────────────────┐     ┌─────────────────────┐
+│  Custom Hook        │     │  Small Component    │
+│  (Business Logic)   │────►│  (Presentation)     │
+│                     │     │                     │
+│  • Data Management  │     │  • UI Only          │
+│  • State Logic      │     │  • Props/Events     │
+│  • API Calls        │     │  • Styling          │
+│  • Validation       │     │  • < 150 LOC        │
+│  • < 150 LOC        │     │                     │
+│                     │     │  ✅ Easy to test    │
+│  ✅ Reusable        │     │  ✅ Readable        │
+│  ✅ Testable        │     │  ✅ Maintainable    │
+└─────────────────────┘     └─────────────────────┘
+```
+
+## Hook Composition Pattern
+
+```
+┌──────────────────────────────────────────────────┐
+│              useProductManager()                 │
+│                                                  │
+│  ┌──────────────┐  ┌──────────────┐            │
+│  │  useArray    │  │  useSearch   │            │
+│  │  (products)  │──┤  (by name)   │            │
+│  └──────┬───────┘  └──────┬───────┘            │
+│         │                 │                     │
+│         ▼                 ▼                     │
+│  ┌─────────────────────────────┐               │
+│  │       useSort               │               │
+│  │    (by price/name)          │               │
+│  └──────────────┬──────────────┘               │
+│                 │                               │
+│                 ▼                               │
+│  ┌─────────────────────────────┐               │
+│  │     usePagination           │               │
+│  │    (10 items/page)          │               │
+│  └─────────────┬───────────────┘               │
+│                │                                │
+│                ▼                                │
+│         Final Result Set                       │
+└──────────────────────────────────────────────────┘
+```
+
+## JSON Page Rendering Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  JSON Page Schema                       │
+│  {                                                      │
+│    id, name, description,                              │
+│    layout, components, dataSources, actions            │
+│  }                                                      │
+└───────────────────┬─────────────────────────────────────┘
+                    │
+                    ▼
+        ┌───────────────────────┐
+        │    Schema Validator   │
+        │    (Zod validation)   │
+        └───────────┬───────────┘
+                    │
+                    ▼
+        ┌───────────────────────┐
+        │    PageRenderer       │
+        │    (Orchestrator)     │
+        └───────────┬───────────┘
+                    │
+        ┌───────────┼───────────┐
+        │           │           │
+        ▼           ▼           ▼
+  ┌─────────┐ ┌─────────┐ ┌─────────┐
+  │ Data    │ │ Actions │ │ Comps   │
+  │ Sources │ │ Setup   │ │ Render  │
+  └────┬────┘ └────┬────┘ └────┬────┘
+       │           │           │
+       ▼           ▼           ▼
+  ┌─────────┐ ┌─────────┐ ┌─────────┐
+  │ Load    │ │ Bind    │ │ Registry│
+  │ from KV │ │ Handlers│ │ Lookup  │
+  └────┬────┘ └────┬────┘ └────┬────┘
+       │           │           │
+       └───────────┼───────────┘
+                   │
+                   ▼
+        ┌──────────────────────┐
+        │   React Component    │
+        │        Tree          │
+        └──────────┬───────────┘
+                   │
+                   ▼
+              Final DOM
+```
+
+## Code Organization
+
+```
+src/
+├── hooks/                      # Business Logic Layer
+│   ├── data/                   # Data management
+│   │   ├── use-array.ts
+│   │   ├── use-crud.ts
+│   │   ├── use-search.ts
+│   │   ├── use-sort.ts
+│   │   ├── use-pagination.ts
+│   │   └── use-debounce.ts
+│   ├── ui/                     # UI state
+│   │   ├── use-dialog.ts
+│   │   ├── use-tabs.ts
+│   │   ├── use-selection.ts
+│   │   └── use-clipboard.ts
+│   ├── forms/                  # Form handling
+│   │   ├── use-form.ts
+│   │   └── use-form-field.ts
+│   └── feature-ideas/          # Feature-specific
+│       ├── use-feature-ideas.ts
+│       └── use-idea-groups.ts
+│
+├── config/                     # Configuration Layer
+│   ├── orchestration/          # Engine
+│   │   ├── schema.ts
+│   │   ├── action-executor.ts
+│   │   ├── data-source-manager.ts
+│   │   ├── component-registry.ts
+│   │   └── PageRenderer.tsx
+│   └── pages/                  # Page definitions
+│       ├── dashboard.json
+│       └── simple-form.json
+│
+└── components/                 # Presentation Layer
+    ├── ui/                     # Shadcn components
+    ├── atoms/                  # Small, focused (<50 LOC)
+    ├── molecules/              # Medium (<100 LOC)
+    └── organisms/              # Complex (<150 LOC)
+```
+
+## Migration Strategy
+
+```
+┌─────────────────────────────────────────────────────┐
+│              Current State                          │
+│  Large monolithic components (500+ LOC)             │
+└─────────────────┬───────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────┐
+│              Step 1: Extract Hooks                  │
+│  Move business logic to custom hooks               │
+└─────────────────┬───────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────┐
+│              Step 2: Split Components               │
+│  Break into smaller presentation components        │
+└─────────────────┬───────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────┐
+│              Step 3: Create JSON Schema             │
+│  Define page structure in JSON                     │
+└─────────────────┬───────────────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────────────┐
+│              Final State                            │
+│  • Reusable hooks                                  │
+│  • Small components (<150 LOC)                     │
+│  • JSON-driven pages                               │
+│  • Fully testable                                  │
+└─────────────────────────────────────────────────────┘
+```
+
+## Benefits Visualization
+
+```
+Code Maintainability
+Before: ████████░░ 80%
+After:  ██████████ 100% ✓
+
+Code Reusability
+Before: █████░░░░░ 50%
+After:  ██████████ 100% ✓
+
+Testability
+Before: ██████░░░░ 60%
+After:  ██████████ 100% ✓
+
+Development Speed
+Before: ███████░░░ 70%
+After:  ██████████ 100% ✓
+
+Type Safety
+Before: ████████░░ 80%
+After:  ██████████ 100% ✓
+
+Component Size
+Before: ██████████ 500+ LOC
+After:  ██░░░░░░░░ <150 LOC ✓
+```
+
+---
+
+**Legend:**
+- ✓ = Achieved
+- ⚡ = Performance optimized
+- 🔒 = Type safe
+- ♻️ = Reusable
+- 🧪 = Testable

docs/architecture/CONFIG_ARCHITECTURE.md

@@ -0,0 +1,436 @@
+# Declarative Page Configuration System
+
+## Overview
+
+CodeForge uses a **declarative, JSON-driven configuration system** to manage pages, components, props, and layouts. This architecture enables rapid development without modifying core application logic.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        App.tsx                               │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  Uses page-loader to:                                 │   │
+│  │  • Get enabled pages                                  │   │
+│  │  • Resolve component props dynamically                │   │
+│  │  • Render pages with correct configuration            │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                            ▲
+                            │
+                            │ imports & uses
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│              page-loader.ts (Resolution Logic)               │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  • getPageConfig()                                    │   │
+│  │  • getEnabledPages(featureToggles)                    │   │
+│  │  • resolveProps(propConfig, state, actions)           │   │
+│  │  • getPageShortcuts()                                 │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                            ▲
+                            │
+                            │ reads
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│            pages.json (Declarative Config)                   │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  {                                                    │   │
+│  │    "pages": [                                         │   │
+│  │      {                                                │   │
+│  │        "id": "models",                                │   │
+│  │        "component": "ModelDesigner",                  │   │
+│  │        "props": {                                     │   │
+│  │          "state": ["models"],                         │   │
+│  │          "actions": ["onModelsChange:setModels"]     │   │
+│  │        }                                              │   │
+│  │      }                                                │   │
+│  │    ]                                                  │   │
+│  │  }                                                    │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                            ▲
+                            │
+                            │ validates
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│         validate-config.ts (Validation Logic)                │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  • validatePageConfig()                               │   │
+│  │  • Checks for duplicate IDs/shortcuts                 │   │
+│  │  • Validates state/action keys exist                  │   │
+│  │  • Validates resizable configurations                 │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+                            ▲
+                            │
+                            │ uses schemas
+                            │
+┌─────────────────────────────────────────────────────────────┐
+│          page-schema.ts (Type Definitions)                   │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  • PropConfigSchema                                   │   │
+│  │  • ResizableConfigSchema                              │   │
+│  │  • SimplePageConfigSchema                             │   │
+│  │  • Zod schemas for runtime validation                 │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Files
+
+### 1. `pages.json` - Source of Truth
+
+The declarative configuration file that defines all pages, their components, and props.
+
+**Location**: `/src/config/pages.json`
+
+**Purpose**: 
+- Define all application pages
+- Configure component props mapping
+- Set keyboard shortcuts
+- Configure resizable layouts
+- Enable/disable features
+
+### 2. `page-loader.ts` - Resolution Engine
+
+The TypeScript module that reads and processes the JSON configuration.
+
+**Location**: `/src/config/page-loader.ts`
+
+**Key Functions**:
+- `getPageConfig()` - Returns full page configuration
+- `getEnabledPages(featureToggles)` - Filters pages based on toggles
+- `resolveProps(propConfig, stateContext, actionContext)` - Maps JSON config to actual props
+- `getPageShortcuts(featureToggles)` - Extracts keyboard shortcuts
+
+### 3. `validate-config.ts` - Configuration Validator
+
+Validates the pages.json configuration for errors and warnings.
+
+**Location**: `/src/config/validate-config.ts`
+
+**Validates**:
+- Required fields (id, title, component)
+- Duplicate IDs, shortcuts, or order numbers
+- Valid state and action keys
+- Resizable configuration correctness
+- Feature toggle key validity
+
+### 4. `page-schema.ts` - Type Definitions
+
+Zod schemas and TypeScript types for type-safe configuration.
+
+**Location**: `/src/config/page-schema.ts`
+
+**Exports**:
+- `PropConfigSchema` - Props configuration structure
+- `ResizableConfigSchema` - Resizable layout structure
+- `SimplePageConfigSchema` - Individual page structure
+- TypeScript types inferred from schemas
+
+## Data Flow
+
+### Adding a New Page
+
+```mermaid
+graph LR
+    A[Edit pages.json] --> B[Add page config with props]
+    B --> C[page-loader reads config]
+    C --> D[App.tsx calls resolveProps]
+    D --> E[Props mapped from state/actions]
+    E --> F[Component rendered with props]
+```
+
+### Prop Resolution Flow
+
+```
+1. Component needs props
+   ↓
+2. App.tsx calls getPropsForComponent(pageId)
+   ↓
+3. getPropsForComponent finds page config
+   ↓
+4. Calls resolveProps(page.props, stateContext, actionContext)
+   ↓
+5. resolveProps iterates over state/action arrays
+   ↓
+6. Maps JSON keys to actual values from contexts
+   ↓
+7. Returns resolved props object
+   ↓
+8. Props passed to component
+```
+
+## Configuration Examples
+
+### Simple Page (Dashboard)
+
+```json
+{
+  "id": "dashboard",
+  "title": "Dashboard",
+  "icon": "ChartBar",
+  "component": "ProjectDashboard",
+  "enabled": true,
+  "shortcut": "ctrl+1",
+  "order": 1,
+  "props": {
+    "state": ["files", "models", "components"]
+  }
+}
+```
+
+### Page with Actions (Model Designer)
+
+```json
+{
+  "id": "models",
+  "title": "Models",
+  "component": "ModelDesigner",
+  "props": {
+    "state": ["models"],
+    "actions": ["onModelsChange:setModels"]
+  }
+}
+```
+
+### Page with Renamed Props (Flask Designer)
+
+```json
+{
+  "id": "flask",
+  "component": "FlaskDesigner",
+  "props": {
+    "state": ["config:flaskConfig"],
+    "actions": ["onConfigChange:setFlaskConfig"]
+  }
+}
+```
+
+### Resizable Split-Panel Page (Code Editor)
+
+```json
+{
+  "id": "code",
+  "component": "CodeEditor",
+  "requiresResizable": true,
+  "props": {
+    "state": ["files", "activeFileId"],
+    "actions": ["onFileChange:handleFileChange"]
+  },
+  "resizableConfig": {
+    "leftComponent": "FileExplorer",
+    "leftProps": {
+      "state": ["files"],
+      "actions": ["onFileSelect:setActiveFileId"]
+    },
+    "leftPanel": {
+      "defaultSize": 20,
+      "minSize": 15,
+      "maxSize": 30
+    },
+    "rightPanel": {
+      "defaultSize": 80
+    }
+  }
+}
+```
+
+## State Context Keys
+
+Available state variables that can be referenced in `props.state`:
+
+- `files` - Project files
+- `models` - Data models
+- `components` - Component definitions
+- `componentTrees` - Component tree structures
+- `workflows` - Workflow definitions
+- `lambdas` - Lambda functions
+- `theme` - Theme configuration
+- `playwrightTests` - Playwright tests
+- `storybookStories` - Storybook stories
+- `unitTests` - Unit tests
+- `flaskConfig` - Flask configuration
+- `nextjsConfig` - Next.js configuration
+- `npmSettings` - NPM settings
+- `featureToggles` - Feature toggles
+- `activeFileId` - Active file ID
+
+## Action Context Keys
+
+Available action functions that can be referenced in `props.actions`:
+
+- `handleFileChange` - Update file content
+- `setActiveFileId` - Set active file
+- `handleFileClose` - Close file
+- `handleFileAdd` - Add new file
+- `setModels` - Update models
+- `setComponents` - Update components
+- `setComponentTrees` - Update component trees
+- `setWorkflows` - Update workflows
+- `setLambdas` - Update lambdas
+- `setTheme` - Update theme
+- `setPlaywrightTests` - Update Playwright tests
+- `setStorybookStories` - Update Storybook stories
+- `setUnitTests` - Update unit tests
+- `setFlaskConfig` - Update Flask config
+- `setNextjsConfig` - Update Next.js config
+- `setNpmSettings` - Update NPM settings
+- `setFeatureToggles` - Update feature toggles
+
+## Benefits of This Architecture
+
+### 1. **Declarative Configuration**
+- All pages defined in one place
+- Easy to understand at a glance
+- No need to read through TypeScript code
+
+### 2. **Separation of Concerns**
+- Configuration separate from logic
+- Props resolution handled systematically
+- Business logic stays in components
+
+### 3. **Type Safety**
+- Zod schemas validate runtime data
+- TypeScript types ensure compile-time safety
+- Catch errors early in development
+
+### 4. **Maintainability**
+- Add pages without touching App.tsx logic
+- Modify props without code changes
+- Clear validation error messages
+
+### 5. **Scalability**
+- Easy to add new pages
+- Simple to extend prop mappings
+- Can add more configuration options
+
+### 6. **Testability**
+- Validate configuration independently
+- Test prop resolution in isolation
+- Mock configurations for testing
+
+## Validation
+
+Run configuration validation:
+
+```bash
+# Via TypeScript (if configured)
+npm run validate-config
+
+# Or manually import and run
+import { validatePageConfig, printValidationErrors } from '@/config/validate-config'
+const errors = validatePageConfig()
+printValidationErrors(errors)
+```
+
+Validation checks:
+- ✅ Required fields present
+- ✅ No duplicate IDs or shortcuts
+- ✅ Valid state/action keys
+- ✅ Correct resizable config format
+- ✅ Panel sizes sum to 100
+- ⚠️ Warnings for missing icons or duplicate orders
+
+## Extending the System
+
+### Adding New State Keys
+
+1. Add state to `useProjectState` hook
+2. Add to `stateContext` in `App.tsx`
+3. Add to validation in `validate-config.ts`
+4. Document in this README
+
+### Adding New Action Keys
+
+1. Create action function in `App.tsx` or hook
+2. Add to `actionContext` in `App.tsx`
+3. Add to validation in `validate-config.ts`
+4. Document in this README
+
+### Adding New Configuration Options
+
+1. Update `pages.json` with new field
+2. Update `PageConfig` interface in `page-loader.ts`
+3. Update Zod schema in `page-schema.ts`
+4. Add validation in `validate-config.ts`
+5. Implement logic in `App.tsx`
+
+## Migration Guide
+
+### From Hardcoded Props to JSON Config
+
+**Before** (Hardcoded in App.tsx):
+```typescript
+const getPropsForComponent = (pageId: string) => {
+  const propsMap: Record<string, any> = {
+    'ModelDesigner': {
+      models,
+      onModelsChange: setModels,
+    },
+  }
+  return propsMap[pageId] || {}
+}
+```
+
+**After** (Declarative in pages.json):
+```json
+{
+  "id": "models",
+  "component": "ModelDesigner",
+  "props": {
+    "state": ["models"],
+    "actions": ["onModelsChange:setModels"]
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep props minimal** - Only pass what the component needs
+2. **Use descriptive prop names** - Clear intent over brevity
+3. **Validate configurations** - Run validation before deployment
+4. **Document new features** - Update this README when extending
+5. **Consistent naming** - Follow existing patterns for state/actions
+6. **Group related props** - Keep state and actions organized
+
+## Troubleshooting
+
+### Props not reaching component?
+- Check state/action key spelling in pages.json
+- Verify key exists in stateContext/actionContext
+- Run validation to catch errors
+
+### Component not rendering?
+- Ensure component added to componentMap in App.tsx
+- Check component name matches exactly (case-sensitive)
+- Verify component has default export
+
+### Resizable panel issues?
+- Ensure defaultSize values sum to 100
+- Check leftComponent exists in componentMap
+- Verify resizableConfig structure is complete
+
+## Related Documentation
+
+- [PROPS_CONFIG_GUIDE.md](./PROPS_CONFIG_GUIDE.md) - Detailed props configuration guide
+- [src/config/pages.json](./src/config/pages.json) - Current page configurations
+- [src/config/page-loader.ts](./src/config/page-loader.ts) - Resolution logic
+- [src/config/validate-config.ts](./src/config/validate-config.ts) - Validation utilities
+
+## Future Enhancements
+
+Potential improvements to the configuration system:
+
+- [ ] Hot-reload configuration changes in development
+- [ ] Visual configuration editor UI
+- [ ] Import/export page configurations
+- [ ] Configuration presets/templates
+- [ ] Computed/derived props from state
+- [ ] Conditional prop mappings
+- [ ] Hook injection via configuration
+- [ ] Layout templates beyond resizable panels
+- [ ] Permission-based page visibility
+- [ ] Analytics tracking configuration

docs/architecture/DECLARATIVE_SYSTEM.md

@@ -0,0 +1,399 @@
+# Declarative System Documentation
+
+## Overview
+
+CodeForge now uses a **declarative, JSON-driven architecture** that makes it easy to add, modify, and configure pages without touching core application code. This system reduces complexity, improves maintainability, and makes the codebase more scalable.
+
+## Key Benefits
+
+✅ **Add new pages by editing a JSON file** - no need to modify App.tsx  
+✅ **Dynamic component loading** - components are lazy-loaded based on configuration  
+✅ **Automatic keyboard shortcuts** - defined in JSON, automatically wired up  
+✅ **Feature toggle integration** - pages automatically show/hide based on feature flags  
+✅ **Consistent page structure** - all pages follow the same rendering pattern  
+✅ **Easy to test and maintain** - configuration is separate from implementation  
+
+## Architecture
+
+### Configuration Files
+
+#### `/src/config/pages.json`
+The main configuration file that defines all pages in the application.
+
+```json
+{
+  "pages": [
+    {
+      "id": "dashboard",
+      "title": "Dashboard",
+      "icon": "ChartBar",
+      "component": "ProjectDashboard",
+      "enabled": true,
+      "shortcut": "ctrl+1",
+      "order": 1
+    },
+    {
+      "id": "code",
+      "title": "Code Editor",
+      "icon": "Code",
+      "component": "CodeEditor",
+      "enabled": true,
+      "toggleKey": "codeEditor",
+      "shortcut": "ctrl+2",
+      "order": 2,
+      "requiresResizable": true
+    }
+  ]
+}
+```
+
+#### Page Configuration Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✅ | Unique identifier for the page (used in routing) |
+| `title` | string | ✅ | Display name for the page |
+| `icon` | string | ✅ | Phosphor icon name |
+| `component` | string | ✅ | Component name (must exist in componentMap) |
+| `enabled` | boolean | ✅ | Whether the page is available |
+| `toggleKey` | string | ❌ | Feature toggle key (from FeatureToggles type) |
+| `shortcut` | string | ❌ | Keyboard shortcut (e.g., "ctrl+1", "ctrl+shift+e") |
+| `order` | number | ✅ | Display order in navigation |
+| `requiresResizable` | boolean | ❌ | Special flag for split-pane layouts |
+
+### Core Functions
+
+#### `getPageConfig()`
+Returns the complete page configuration.
+
+```typescript
+import { getPageConfig } from '@/config/page-loader'
+
+const config = getPageConfig()
+// Returns: { pages: PageConfig[] }
+```
+
+#### `getEnabledPages(featureToggles)`
+Returns only pages that are enabled and pass feature toggle checks.
+
+```typescript
+import { getEnabledPages } from '@/config/page-loader'
+
+const enabledPages = getEnabledPages(featureToggles)
+// Returns: PageConfig[]
+```
+
+#### `getPageShortcuts(featureToggles)`
+Returns keyboard shortcuts for enabled pages.
+
+```typescript
+import { getPageShortcuts } from '@/config/page-loader'
+
+const shortcuts = getPageShortcuts(featureToggles)
+// Returns: Array<{ key: string, ctrl?: boolean, shift?: boolean, description: string, action: string }>
+```
+
+## How to Add a New Page
+
+### Step 1: Create Your Component
+
+```typescript
+// src/components/MyNewDesigner.tsx
+export function MyNewDesigner() {
+  return (
+    <div className="p-6">
+      <h1>My New Designer</h1>
+    </div>
+  )
+}
+```
+
+### Step 2: Add to Component Map
+
+In `src/App.tsx`, add your component to the `componentMap`:
+
+```typescript
+const componentMap: Record<string, React.LazyExoticComponent<any>> = {
+  // ... existing components
+  MyNewDesigner: lazy(() => import('@/components/MyNewDesigner').then(m => ({ default: m.MyNewDesigner }))),
+}
+```
+
+### Step 3: Add to pages.json
+
+Add your page configuration to `/src/config/pages.json`:
+
+```json
+{
+  "id": "my-new-page",
+  "title": "My New Designer",
+  "icon": "Sparkle",
+  "component": "MyNewDesigner",
+  "enabled": true,
+  "toggleKey": "myNewFeature",
+  "shortcut": "ctrl+shift+n",
+  "order": 21
+}
+```
+
+### Step 4: (Optional) Add Feature Toggle
+
+If using a feature toggle, add it to the `FeatureToggles` type in `/src/types/project.ts`:
+
+```typescript
+export interface FeatureToggles {
+  // ... existing toggles
+  myNewFeature: boolean
+}
+```
+
+And update the default in `/src/hooks/use-project-state.ts`:
+
+```typescript
+const DEFAULT_FEATURE_TOGGLES: FeatureToggles = {
+  // ... existing toggles
+  myNewFeature: true,
+}
+```
+
+### Step 5: (Optional) Add Props Mapping
+
+If your component needs props, add it to `getPropsForComponent` in `App.tsx`:
+
+```typescript
+const getPropsForComponent = (pageId: string) => {
+  const propsMap: Record<string, any> = {
+    // ... existing mappings
+    'MyNewDesigner': {
+      data: someData,
+      onDataChange: setSomeData,
+    },
+  }
+  return propsMap[pageId] || {}
+}
+```
+
+That's it! Your new page will now:
+- ✅ Appear in the navigation menu
+- ✅ Be accessible via the keyboard shortcut
+- ✅ Show/hide based on the feature toggle
+- ✅ Be searchable in global search
+- ✅ Follow the same rendering pattern as other pages
+
+## Component Map
+
+The `componentMap` in `App.tsx` is the registry of all available components:
+
+```typescript
+const componentMap: Record<string, React.LazyExoticComponent<any>> = {
+  ProjectDashboard: lazy(() => import('@/components/ProjectDashboard').then(m => ({ default: m.ProjectDashboard }))),
+  CodeEditor: lazy(() => import('@/components/CodeEditor').then(m => ({ default: m.CodeEditor }))),
+  // ... more components
+}
+```
+
+All components are **lazy-loaded** for optimal performance. They only load when the user navigates to that page.
+
+## Special Layouts
+
+### Split-Pane Layout (Code Editor)
+
+The code editor uses a special resizable split-pane layout. This is handled by the `requiresResizable` flag:
+
+```json
+{
+  "id": "code",
+  "component": "CodeEditor",
+  "requiresResizable": true
+}
+```
+
+The rendering logic in `App.tsx` checks for this flag and renders the appropriate layout.
+
+## Feature Toggles Integration
+
+Pages can be conditionally enabled based on feature toggles:
+
+```json
+{
+  "id": "playwright",
+  "toggleKey": "playwright",
+  "enabled": true
+}
+```
+
+The page will only appear if:
+1. `enabled` is `true` in the JSON
+2. `featureToggles.playwright` is `true` (or undefined)
+
+Users can toggle features on/off in the **Features** page.
+
+## Keyboard Shortcuts
+
+Shortcuts are automatically parsed from the configuration:
+
+```json
+{
+  "shortcut": "ctrl+1"
+}
+```
+
+Supported modifiers:
+- `ctrl` - Control key
+- `shift` - Shift key
+- `alt` - Alt key (not implemented yet, but easy to add)
+
+Format: `[modifier+]key` (e.g., "ctrl+1", "ctrl+shift+e", "f")
+
+## Future Enhancements
+
+The declarative system can be extended to support:
+
+### 1. Dynamic Props from JSON
+```json
+{
+  "component": "MyComponent",
+  "props": {
+    "title": "Dynamic Title",
+    "showToolbar": true
+  }
+}
+```
+
+### 2. Layout Configuration
+```json
+{
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "panels": [
+      { "component": "Sidebar", "size": 20 },
+      { "component": "MainContent", "size": 80 }
+    ]
+  }
+}
+```
+
+### 3. Permission-Based Access
+```json
+{
+  "permissions": ["admin", "editor"]
+}
+```
+
+### 4. Page Groups/Categories
+```json
+{
+  "category": "Design Tools",
+  "group": "styling"
+}
+```
+
+### 5. Page Metadata
+```json
+{
+  "description": "Design and test Playwright e2e tests",
+  "tags": ["testing", "automation"],
+  "beta": true
+}
+```
+
+## Advanced: Page Schema System
+
+For even more advanced use cases, check out:
+- `/src/config/page-schema.ts` - TypeScript types for page schemas
+- `/src/components/orchestration/PageRenderer.tsx` - Generic page renderer
+- `/src/config/default-pages.json` - Alternative page configuration format
+
+These files provide a more sophisticated schema-based system that can define:
+- Complex layouts (split, tabs, grid)
+- Component hierarchies
+- Action handlers
+- Context management
+
+## Migration Guide
+
+If you have an existing page that's hardcoded in App.tsx:
+
+### Before (Hardcoded):
+```typescript
+<TabsContent value="my-page" className="h-full m-0">
+  <Suspense fallback={<LoadingFallback message="Loading..." />}>
+    <MyComponent prop1={data} prop2={handler} />
+  </Suspense>
+</TabsContent>
+```
+
+### After (Declarative):
+1. Add to `pages.json`:
+```json
+{
+  "id": "my-page",
+  "title": "My Page",
+  "icon": "Star",
+  "component": "MyComponent",
+  "enabled": true,
+  "order": 10
+}
+```
+
+2. Add to `componentMap`:
+```typescript
+MyComponent: lazy(() => import('@/components/MyComponent').then(m => ({ default: m.MyComponent }))),
+```
+
+3. Add props mapping if needed:
+```typescript
+'MyComponent': {
+  prop1: data,
+  prop2: handler,
+}
+```
+
+4. Remove the hardcoded TabsContent - the system handles it automatically!
+
+## Troubleshooting
+
+### Page doesn't appear in navigation
+- ✅ Check `enabled: true` in pages.json
+- ✅ Check feature toggle is enabled (if using `toggleKey`)
+- ✅ Verify component exists in `componentMap`
+- ✅ Check console for errors
+
+### Component not loading
+- ✅ Verify import path in `componentMap`
+- ✅ Check component has a default export
+- ✅ Look for TypeScript errors in component file
+
+### Keyboard shortcut not working
+- ✅ Verify shortcut format (e.g., "ctrl+1")
+- ✅ Check for conflicts with browser shortcuts
+- ✅ Make sure page is enabled
+
+### Props not being passed
+- ✅ Add mapping in `getPropsForComponent`
+- ✅ Verify component name matches `pages.json`
+- ✅ Check prop types match component interface
+
+## Best Practices
+
+1. **Keep pages.json organized** - Group related pages together, use consistent ordering
+2. **Use meaningful IDs** - Use kebab-case, descriptive IDs (e.g., "code-editor", not "ce")
+3. **Choose appropriate icons** - Use Phosphor icons that match the page purpose
+4. **Document feature toggles** - Add comments to FeatureToggles type
+5. **Test shortcuts** - Verify shortcuts don't conflict with browser/OS shortcuts
+6. **Lazy load everything** - Keep components in the lazy componentMap
+7. **Type your props** - Use TypeScript interfaces for component props
+8. **Keep components small** - Follow the <150 LOC guideline from refactoring
+
+## Summary
+
+The declarative system transforms CodeForge from a monolithic React app into a flexible, configuration-driven platform. By moving page definitions to JSON, we gain:
+
+- 🚀 **Faster development** - Add pages in minutes, not hours
+- 🔧 **Easier maintenance** - Configuration is centralized and versioned
+- 📦 **Better performance** - Lazy loading reduces initial bundle size
+- 🎯 **Cleaner code** - Business logic separated from configuration
+- 🧪 **Simpler testing** - Mock configuration instead of mocking components
+
+The system is designed to grow with your needs - start simple with basic page definitions, then add advanced features like layout configuration, permissions, and dynamic props as needed.

docs/architecture/JSON_ORCHESTRATION_COMPLETE.md

@@ -0,0 +1,680 @@
+# JSON Orchestration System - Complete Guide
+
+## Overview
+
+The JSON Orchestration System allows you to define entire pages, components, data sources, and actions using JSON schemas. This enables:
+
+- **Zero-code page creation**: Build pages without writing React components
+- **Dynamic configuration**: Change page structure without rebuilding
+- **Type safety**: Full TypeScript validation of schemas
+- **Testability**: JSON schemas are easy to validate and test
+- **Rapid prototyping**: Create new pages by editing JSON files
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              JSON Page Schema                    │
+│  (Structure, Data Sources, Actions, Components) │
+└───────────────┬─────────────────────────────────┘
+                │
+        ┌───────▼──────┐
+        │ PageRenderer │
+        └───────┬──────┘
+                │
+    ┌───────────┼───────────┐
+    │           │           │
+┌───▼────┐ ┌───▼─────┐ ┌──▼────────┐
+│ Data   │ │ Action  │ │ Component │
+│ Source │ │ Executor│ │ Registry  │
+│ Manager│ │         │ │           │
+└────────┘ └─────────┘ └───────────┘
+```
+
+## Core Concepts
+
+### 1. Page Schema
+
+A complete page definition:
+
+```typescript
+interface PageSchema {
+  id: string                    // Unique identifier
+  name: string                  // Display name
+  description?: string          // Optional description
+  icon?: string                 // Icon name
+  layout: Layout                // Layout configuration
+  components: ComponentDef[]    // Component tree
+  dataSources?: DataSource[]    // Data sources
+  actions?: Action[]            // Available actions
+  hooks?: HookConfig[]          // Custom hooks
+  seedData?: Record<string, any> // Initial data
+}
+```
+
+### 2. Data Sources
+
+Define where data comes from and how it's managed:
+
+```typescript
+interface DataSource {
+  id: string                              // Unique ID for referencing
+  type: 'kv' | 'api' | 'computed' | 'static'
+  key?: string                            // KV store key
+  endpoint?: string                       // API endpoint
+  transform?: string                      // Transform function name
+  defaultValue?: any                      // Default/fallback value
+  dependencies?: string[]                 // Other data sources needed
+}
+```
+
+**Example:**
+```json
+{
+  "dataSources": [
+    {
+      "id": "todos",
+      "type": "kv",
+      "key": "user-todos",
+      "defaultValue": []
+    },
+    {
+      "id": "user",
+      "type": "api",
+      "endpoint": "/api/user",
+      "defaultValue": null
+    },
+    {
+      "id": "stats",
+      "type": "computed",
+      "dependencies": ["todos"],
+      "transform": "calculateStats"
+    }
+  ]
+}
+```
+
+### 3. Actions
+
+Define what happens when users interact:
+
+```typescript
+interface Action {
+  id: string                                           // Action identifier
+  type: 'create' | 'update' | 'delete' | 'navigate'
+       | 'api' | 'transform' | 'custom'
+  target?: string                                      // Target data source
+  payload?: Record<string, any>                        // Action payload
+  handler?: string                                     // Custom handler name
+}
+```
+
+**Action Types:**
+
+- **`create`**: Add new item to data source
+- **`update`**: Modify existing item
+- **`delete`**: Remove item
+- **`navigate`**: Change route/tab
+- **`api`**: Make HTTP request
+- **`transform`**: Transform data using custom function
+- **`custom`**: Execute custom handler
+
+**Example:**
+```json
+{
+  "actions": [
+    {
+      "id": "add-todo",
+      "type": "create",
+      "target": "todos"
+    },
+    {
+      "id": "complete-todo",
+      "type": "update",
+      "target": "todos"
+    },
+    {
+      "id": "delete-todo",
+      "type": "delete",
+      "target": "todos"
+    },
+    {
+      "id": "refresh-data",
+      "type": "api",
+      "target": "todos",
+      "payload": {
+        "endpoint": "/api/todos",
+        "method": "GET"
+      }
+    },
+    {
+      "id": "export",
+      "type": "custom",
+      "handler": "handleExport"
+    }
+  ]
+}
+```
+
+### 4. Components
+
+Define the component tree structure:
+
+```typescript
+interface ComponentDef {
+  id: string                                // Unique component ID
+  type: string                              // Component name (from registry)
+  props?: Record<string, any>               // Component props
+  children?: ComponentDef[]                 // Child components
+  dataBinding?: string                      // Bind to data source
+  eventHandlers?: Record<string, string>    // Event → Action mapping
+}
+```
+
+**Example:**
+```json
+{
+  "components": [
+    {
+      "id": "todo-list",
+      "type": "Card",
+      "props": {
+        "className": "max-w-2xl mx-auto"
+      },
+      "children": [
+        {
+          "id": "header",
+          "type": "CardHeader",
+          "children": [
+            {
+              "id": "title",
+              "type": "CardTitle",
+              "props": {
+                "children": "My Todos"
+              }
+            }
+          ]
+        },
+        {
+          "id": "content",
+          "type": "CardContent",
+          "dataBinding": "todos",
+          "children": [
+            {
+              "id": "add-button",
+              "type": "Button",
+              "props": {
+                "children": "Add Todo"
+              },
+              "eventHandlers": {
+                "onClick": "add-todo"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 5. Layout
+
+Define how components are arranged:
+
+```typescript
+interface Layout {
+  type: 'single' | 'split' | 'grid' | 'tabs' | 'flex'
+  direction?: 'horizontal' | 'vertical' | 'row' | 'column'
+  panels?: PanelConfig[]
+}
+
+interface PanelConfig {
+  id: string
+  minSize?: number
+  maxSize?: number
+  defaultSize?: number
+}
+```
+
+**Example:**
+```json
+{
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "panels": [
+      {
+        "id": "sidebar",
+        "minSize": 15,
+        "maxSize": 30,
+        "defaultSize": 20
+      },
+      {
+        "id": "main",
+        "defaultSize": 80
+      }
+    ]
+  }
+}
+```
+
+## Complete Examples
+
+### Example 1: Simple Todo List Page
+
+```json
+{
+  "id": "todo-list",
+  "name": "Todo List",
+  "description": "Simple todo list application",
+  "icon": "CheckSquare",
+  "layout": {
+    "type": "single"
+  },
+  "dataSources": [
+    {
+      "id": "todos",
+      "type": "kv",
+      "key": "user-todos",
+      "defaultValue": []
+    }
+  ],
+  "components": [
+    {
+      "id": "root",
+      "type": "Card",
+      "props": {
+        "className": "max-w-2xl mx-auto mt-8"
+      },
+      "children": [
+        {
+          "id": "header",
+          "type": "CardHeader",
+          "children": [
+            {
+              "id": "title",
+              "type": "CardTitle",
+              "props": {
+                "children": "My Tasks"
+              }
+            }
+          ]
+        },
+        {
+          "id": "content",
+          "type": "CardContent",
+          "props": {
+            "className": "space-y-4"
+          },
+          "children": [
+            {
+              "id": "input",
+              "type": "Input",
+              "props": {
+                "placeholder": "What needs to be done?",
+                "id": "todo-input"
+              },
+              "eventHandlers": {
+                "onKeyDown": "add-on-enter"
+              }
+            },
+            {
+              "id": "add-button",
+              "type": "Button",
+              "props": {
+                "children": "Add Task",
+                "className": "w-full"
+              },
+              "eventHandlers": {
+                "onClick": "add-todo"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "id": "add-todo",
+      "type": "create",
+      "target": "todos"
+    },
+    {
+      "id": "toggle-todo",
+      "type": "update",
+      "target": "todos"
+    },
+    {
+      "id": "delete-todo",
+      "type": "delete",
+      "target": "todos"
+    },
+    {
+      "id": "add-on-enter",
+      "type": "custom",
+      "handler": "handleEnterKey"
+    }
+  ],
+  "seedData": {
+    "todos": [
+      {
+        "id": "1",
+        "text": "Welcome to JSON-driven pages!",
+        "completed": false
+      }
+    ]
+  }
+}
+```
+
+### Example 2: Dashboard with Multiple Data Sources
+
+```json
+{
+  "id": "dashboard",
+  "name": "Project Dashboard",
+  "description": "Overview of project metrics",
+  "icon": "ChartBar",
+  "layout": {
+    "type": "grid"
+  },
+  "dataSources": [
+    {
+      "id": "files",
+      "type": "kv",
+      "key": "project-files",
+      "defaultValue": []
+    },
+    {
+      "id": "models",
+      "type": "kv",
+      "key": "project-models",
+      "defaultValue": []
+    },
+    {
+      "id": "components",
+      "type": "kv",
+      "key": "project-components",
+      "defaultValue": []
+    },
+    {
+      "id": "stats",
+      "type": "computed",
+      "dependencies": ["files", "models", "components"],
+      "transform": "calculateProjectStats"
+    }
+  ],
+  "components": [
+    {
+      "id": "stats-grid",
+      "type": "div",
+      "props": {
+        "className": "grid grid-cols-3 gap-4 p-4"
+      },
+      "children": [
+        {
+          "id": "files-card",
+          "type": "Card",
+          "children": [
+            {
+              "id": "files-content",
+              "type": "CardContent",
+              "props": {
+                "className": "pt-6"
+              },
+              "dataBinding": "files",
+              "children": [
+                {
+                  "id": "files-count",
+                  "type": "div",
+                  "props": {
+                    "className": "text-2xl font-bold"
+                  }
+                },
+                {
+                  "id": "files-label",
+                  "type": "div",
+                  "props": {
+                    "children": "Files",
+                    "className": "text-muted-foreground"
+                  }
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "id": "models-card",
+          "type": "Card",
+          "children": [
+            {
+              "id": "models-content",
+              "type": "CardContent",
+              "props": {
+                "className": "pt-6"
+              },
+              "dataBinding": "models"
+            }
+          ]
+        },
+        {
+          "id": "components-card",
+          "type": "Card",
+          "children": [
+            {
+              "id": "components-content",
+              "type": "CardContent",
+              "props": {
+                "className": "pt-6"
+              },
+              "dataBinding": "components"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "id": "navigate-to-files",
+      "type": "navigate",
+      "target": "code"
+    },
+    {
+      "id": "navigate-to-models",
+      "type": "navigate",
+      "target": "models"
+    }
+  ]
+}
+```
+
+## Using the PageRenderer
+
+In your application:
+
+```typescript
+import { PageRenderer } from '@/config/orchestration'
+import dashboardSchema from '@/config/pages/dashboard.json'
+
+function DashboardPage() {
+  const handleNavigate = (path: string) => {
+    // Your navigation logic
+    router.push(path)
+  }
+
+  const customHandlers = {
+    handleExport: async () => {
+      // Custom export logic
+      const data = await exportData()
+      downloadFile(data)
+    },
+    calculateStats: (todos: any[]) => {
+      return {
+        total: todos.length,
+        completed: todos.filter(t => t.completed).length
+      }
+    }
+  }
+
+  return (
+    <PageRenderer
+      schema={dashboardSchema}
+      onNavigate={handleNavigate}
+      customHandlers={customHandlers}
+    />
+  )
+}
+```
+
+## Component Registry
+
+Register all components that can be used in JSON schemas:
+
+```typescript
+// src/config/orchestration/component-registry.ts
+import { ComponentType } from 'react'
+import { Button } from '@/components/ui/button'
+import { MyCustomComponent } from '@/components/MyCustomComponent'
+
+export const ComponentRegistry: Record<string, ComponentType<any>> = {
+  Button,
+  Input,
+  Card,
+  // ... shadcn components
+  
+  // Custom components
+  MyCustomComponent,
+  TodoList,
+  Dashboard,
+}
+```
+
+## Advanced Patterns
+
+### Conditional Rendering
+
+Use computed data sources:
+
+```json
+{
+  "dataSources": [
+    {
+      "id": "user",
+      "type": "kv",
+      "key": "current-user"
+    },
+    {
+      "id": "isAdmin",
+      "type": "computed",
+      "dependencies": ["user"],
+      "transform": "checkIsAdmin"
+    }
+  ]
+}
+```
+
+### Nested Data Binding
+
+Bind to nested properties:
+
+```json
+{
+  "id": "email-input",
+  "type": "Input",
+  "dataBinding": "user.profile.email"
+}
+```
+
+### Batch Actions
+
+Execute multiple actions:
+
+```json
+{
+  "id": "save-all",
+  "type": "custom",
+  "handler": "saveAllChanges",
+  "payload": {
+    "actions": ["save-files", "save-models", "save-components"]
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep schemas focused**: One page = one schema
+2. **Use meaningful IDs**: Makes debugging easier
+3. **Leverage seed data**: For examples and testing
+4. **Document custom handlers**: In the schema description
+5. **Validate schemas**: Use Zod validation before runtime
+6. **Version your schemas**: Track changes over time
+7. **Test with different data**: Ensure schemas work with various inputs
+
+## Migration Strategy
+
+To migrate existing components to JSON:
+
+1. **Identify static structure**: What doesn't change?
+2. **Extract data dependencies**: What data does it need?
+3. **Map actions**: What can users do?
+4. **Create JSON schema**: Follow the structure
+5. **Test with PageRenderer**: Verify functionality
+6. **Add custom handlers**: For complex logic
+7. **Remove old component**: Once verified
+
+## Performance Considerations
+
+- JSON schemas are parsed once
+- Component registry lookups are O(1)
+- Data sources use React hooks (memoized)
+- Actions are executed asynchronously
+- Large schemas can be code-split
+
+## Debugging
+
+Enable debug mode:
+
+```typescript
+<PageRenderer
+  schema={schema}
+  debug={true} // Logs all actions and data changes
+/>
+```
+
+## TypeScript Support
+
+All schemas are fully typed:
+
+```typescript
+import { PageSchema } from '@/config/orchestration'
+
+const mySchema: PageSchema = {
+  // Full type checking and autocomplete
+}
+```
+
+## Testing
+
+Test schemas independently:
+
+```typescript
+import { PageSchemaDefinition } from '@/config/orchestration/schema'
+import dashboardSchema from '@/config/pages/dashboard.json'
+
+test('dashboard schema is valid', () => {
+  const result = PageSchemaDefinition.safeParse(dashboardSchema)
+  expect(result.success).toBe(true)
+})
+```
+
+## Future Enhancements
+
+- Visual schema editor
+- Schema hot-reloading
+- A/B testing support
+- Schema versioning
+- Analytics integration
+- Performance profiling

docs/architecture/JSON_ORCHESTRATION_GUIDE.md

@@ -0,0 +1,664 @@
+# JSON-Driven Page Orchestration Guide
+
+## Overview
+
+The JSON orchestration system allows you to define entire pages using JSON schemas, eliminating the need for writing React components for common patterns. This approach:
+
+- **Reduces code complexity**: Components stay under 150 LOC
+- **Improves maintainability**: Changes to page structure don't require code changes
+- **Enables rapid prototyping**: New pages can be created by editing JSON
+- **Provides type safety**: Full TypeScript validation of schemas
+- **Facilitates testing**: JSON schemas are easy to validate and test
+
+## Table of Contents
+
+1. [Core Concepts](#core-concepts)
+2. [Page Schema Structure](#page-schema-structure)
+3. [Component Tree](#component-tree)
+4. [Data Sources](#data-sources)
+5. [Actions](#actions)
+6. [Bindings](#bindings)
+7. [Events](#events)
+8. [Hooks](#hooks)
+9. [Examples](#examples)
+10. [Best Practices](#best-practices)
+
+## Core Concepts
+
+### Page Schema
+
+A page schema is a JSON object that completely describes a page's structure, data, and behavior:
+
+```typescript
+interface PageSchema {
+  id: string                      // Unique page identifier
+  name: string                    // Display name
+  description?: string            // Optional description
+  layout: LayoutConfig            // How components are arranged
+  components: ComponentSchema[]   // Tree of components
+  data?: DataSource[]            // Data sources
+  actions?: ActionConfig[]        // Available actions
+  hooks?: HookConfig[]           // Custom hooks to use
+  seedData?: Record<string, any> // Initial/example data
+}
+```
+
+### Component Schema
+
+Each component in the tree is described by:
+
+```typescript
+interface ComponentSchema {
+  id: string                     // Unique component ID
+  type: string                   // Component type (Button, Card, etc.)
+  props?: Record<string, any>    // Component props
+  children?: ComponentSchema[]   // Nested components
+  bindings?: DataBinding[]       // Data bindings
+  events?: EventHandler[]        // Event handlers
+  condition?: string             // Conditional rendering
+}
+```
+
+## Page Schema Structure
+
+### Basic Structure
+
+```json
+{
+  "id": "my-page",
+  "name": "My Page",
+  "layout": {
+    "type": "single"
+  },
+  "components": [
+    {
+      "id": "main",
+      "type": "div",
+      "props": {
+        "className": "p-6"
+      }
+    }
+  ]
+}
+```
+
+### Layout Types
+
+#### Single Layout
+
+All components in a single container:
+
+```json
+{
+  "layout": {
+    "type": "single"
+  }
+}
+```
+
+#### Split Layout
+
+Resizable panels:
+
+```json
+{
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "sizes": [30, 70]
+  }
+}
+```
+
+#### Tabs Layout
+
+Tabbed interface:
+
+```json
+{
+  "layout": {
+    "type": "tabs"
+  },
+  "components": [
+    {
+      "id": "tab1",
+      "props": {
+        "label": "Tab 1"
+      }
+    }
+  ]
+}
+```
+
+#### Grid Layout
+
+CSS Grid:
+
+```json
+{
+  "layout": {
+    "type": "grid",
+    "gap": 16
+  }
+}
+```
+
+## Component Tree
+
+### Available Components
+
+- **UI Components**: `Button`, `Card`, `Input`, `Badge`, `Textarea`
+- **HTML Elements**: `div`, `span`, `h1`, `h2`, `h3`, `p`
+- **Custom**: Register more in `ComponentRenderer.tsx`
+
+### Component Example
+
+```json
+{
+  "id": "submit-button",
+  "type": "Button",
+  "props": {
+    "variant": "default",
+    "size": "lg",
+    "className": "w-full"
+  },
+  "children": [
+    {
+      "id": "button-text",
+      "type": "span",
+      "props": {
+        "children": "Submit"
+      }
+    }
+  ]
+}
+```
+
+### Nesting Components
+
+```json
+{
+  "id": "card",
+  "type": "Card",
+  "props": {
+    "className": "p-4"
+  },
+  "children": [
+    {
+      "id": "title",
+      "type": "h2",
+      "props": {
+        "children": "Title"
+      }
+    },
+    {
+      "id": "content",
+      "type": "p",
+      "props": {
+        "children": "Content goes here"
+      }
+    }
+  ]
+}
+```
+
+## Data Sources
+
+Data sources define where data comes from:
+
+### KV Store
+
+```json
+{
+  "id": "files",
+  "type": "kv",
+  "key": "project-files",
+  "defaultValue": []
+}
+```
+
+### Computed Data
+
+```json
+{
+  "id": "activeFile",
+  "type": "computed",
+  "dependencies": ["files", "activeFileId"],
+  "compute": "context.files.find(f => f.id === context.activeFileId)"
+}
+```
+
+### Static Data
+
+```json
+{
+  "id": "greeting",
+  "type": "static",
+  "defaultValue": "Hello, World!"
+}
+```
+
+### AI-Generated Data
+
+```json
+{
+  "id": "suggestions",
+  "type": "ai",
+  "dependencies": ["userInput"],
+  "compute": "Generate 3 suggestions based on: ${context.userInput}"
+}
+```
+
+## Actions
+
+Actions define what happens when events occur:
+
+### Create Action
+
+```json
+{
+  "id": "add-model",
+  "type": "create",
+  "trigger": "button-click",
+  "params": {
+    "target": "Models",
+    "data": {
+      "id": "${Date.now()}",
+      "name": "NewModel"
+    }
+  },
+  "onSuccess": "show-success-toast"
+}
+```
+
+### Update Action
+
+```json
+{
+  "id": "update-file",
+  "type": "update",
+  "trigger": "input-change",
+  "params": {
+    "target": "Files",
+    "id": "${context.activeFileId}",
+    "data": {
+      "content": "${event.value}"
+    }
+  }
+}
+```
+
+### Delete Action
+
+```json
+{
+  "id": "delete-item",
+  "type": "delete",
+  "trigger": "button-click",
+  "params": {
+    "target": "Models",
+    "id": "${context.selectedId}"
+  }
+}
+```
+
+### Navigate Action
+
+```json
+{
+  "id": "go-to-dashboard",
+  "type": "navigate",
+  "trigger": "button-click",
+  "params": {
+    "tab": "dashboard"
+  }
+}
+```
+
+### AI Generate Action
+
+```json
+{
+  "id": "ai-generate",
+  "type": "ai-generate",
+  "trigger": "button-click",
+  "params": {
+    "prompt": "Generate a user registration form with validation",
+    "target": "Components"
+  }
+}
+```
+
+### Custom Action
+
+```json
+{
+  "id": "custom-logic",
+  "type": "custom",
+  "trigger": "button-click",
+  "params": {
+    "customParam": "value"
+  },
+  "handler": "myCustomHandler"
+}
+```
+
+## Bindings
+
+Bindings connect data to component props:
+
+### Simple Binding
+
+```json
+{
+  "bindings": [
+    {
+      "source": "user.name",
+      "target": "children"
+    }
+  ]
+}
+```
+
+### Transformed Binding
+
+```json
+{
+  "bindings": [
+    {
+      "source": "files",
+      "target": "children",
+      "transform": "value.length + ' files'"
+    }
+  ]
+}
+```
+
+### Multiple Bindings
+
+```json
+{
+  "bindings": [
+    {
+      "source": "user.name",
+      "target": "value"
+    },
+    {
+      "source": "user.isActive",
+      "target": "disabled",
+      "transform": "!value"
+    }
+  ]
+}
+```
+
+## Events
+
+Events connect user interactions to actions:
+
+### Button Click
+
+```json
+{
+  "events": [
+    {
+      "event": "onClick",
+      "action": "add-model"
+    }
+  ]
+}
+```
+
+### Input Change
+
+```json
+{
+  "events": [
+    {
+      "event": "onChange",
+      "action": "update-content",
+      "params": {
+        "field": "name"
+      }
+    }
+  ]
+}
+```
+
+### Multiple Events
+
+```json
+{
+  "events": [
+    {
+      "event": "onClick",
+      "action": "select-item"
+    },
+    {
+      "event": "onDoubleClick",
+      "action": "edit-item"
+    }
+  ]
+}
+```
+
+## Hooks
+
+Custom hooks can be included:
+
+```json
+{
+  "hooks": [
+    {
+      "id": "files-hook",
+      "name": "useFiles",
+      "exports": ["files", "addFile", "updateFile"]
+    },
+    {
+      "id": "modal-hook",
+      "name": "useModal",
+      "params": {
+        "defaultOpen": false
+      },
+      "exports": ["isOpen", "open", "close"]
+    }
+  ]
+}
+```
+
+## Examples
+
+### Simple List Page
+
+```json
+{
+  "id": "todo-list",
+  "name": "Todo List",
+  "layout": {
+    "type": "single"
+  },
+  "components": [
+    {
+      "id": "container",
+      "type": "div",
+      "props": {
+        "className": "p-6"
+      },
+      "children": [
+        {
+          "id": "header",
+          "type": "div",
+          "props": {
+            "className": "flex justify-between mb-4"
+          },
+          "children": [
+            {
+              "id": "title",
+              "type": "h1",
+              "props": {
+                "children": "My Todos"
+              }
+            },
+            {
+              "id": "add-button",
+              "type": "Button",
+              "events": [
+                {
+                  "event": "onClick",
+                  "action": "add-todo"
+                }
+              ],
+              "children": [
+                {
+                  "id": "button-text",
+                  "type": "span",
+                  "props": {
+                    "children": "Add Todo"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "id": "add-todo",
+      "type": "create",
+      "params": {
+        "target": "Todos",
+        "data": {
+          "id": "${Date.now()}",
+          "text": "New todo",
+          "completed": false
+        }
+      }
+    }
+  ]
+}
+```
+
+### Master-Detail Page
+
+```json
+{
+  "id": "user-detail",
+  "name": "User Detail",
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "sizes": [30, 70]
+  },
+  "components": [
+    {
+      "id": "user-list",
+      "type": "Card",
+      "props": {
+        "className": "h-full p-4"
+      }
+    },
+    {
+      "id": "user-details",
+      "type": "Card",
+      "props": {
+        "className": "h-full p-4"
+      },
+      "condition": "context.selectedUser !== null"
+    }
+  ],
+  "data": [
+    {
+      "id": "selectedUser",
+      "type": "computed",
+      "dependencies": ["users", "selectedUserId"],
+      "compute": "context.users.find(u => u.id === context.selectedUserId)"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### 1. Use Descriptive IDs
+
+```json
+{
+  "id": "submit-form-button"
+}
+```
+
+### 2. Keep Components Focused
+
+Break down complex UIs into smaller components.
+
+### 3. Use Computed Data
+
+Don't repeat logic - compute derived data:
+
+```json
+{
+  "id": "incomplete-count",
+  "type": "computed",
+  "compute": "context.todos.filter(t => !t.completed).length"
+}
+```
+
+### 4. Handle Edge Cases
+
+Use conditions for empty states:
+
+```json
+{
+  "condition": "context.items.length === 0"
+}
+```
+
+### 5. Provide Seed Data
+
+Include example data for testing:
+
+```json
+{
+  "seedData": {
+    "exampleUser": {
+      "id": "1",
+      "name": "John Doe"
+    }
+  }
+}
+```
+
+### 6. Use Action Chains
+
+Link actions with onSuccess:
+
+```json
+{
+  "id": "create-and-navigate",
+  "type": "create",
+  "onSuccess": "navigate-to-detail"
+}
+```
+
+### 7. Keep Transforms Simple
+
+Complex logic should be in hooks, not transforms.
+
+### 8. Document Your Schemas
+
+Add descriptions to clarify intent:
+
+```json
+{
+  "description": "Main dashboard showing project stats"
+}
+```
+
+## Next Steps
+
+- See `/src/config/pages/` for more examples
+- Check `/src/hooks/orchestration/` for hook implementation
+- Refer to `/src/types/page-schema.ts` for full type definitions
+- Read `REFACTOR_PHASE3.md` for architecture details

docs/architecture/atomic/ATOMIC_COMPONENTS.md

@@ -0,0 +1,348 @@
+# Atomic Component Library
+
+This codebase follows the **Atomic Design** methodology to organize UI components into a scalable, maintainable structure.
+
+## Structure Overview
+
+```
+src/components/
+├── atoms/           # Basic building blocks (smallest components)
+├── molecules/       # Simple combinations of atoms
+├── organisms/       # Complex components built from molecules and atoms
+├── ui/             # shadcn base components
+└── [features]/     # Feature-specific complex components
+```
+
+## Hierarchy Explained
+
+### 🧪 Atoms (`/atoms`)
+**Purpose**: The smallest, most fundamental UI elements that cannot be broken down further.
+
+**Characteristics**:
+- Single-purpose components
+- No business logic
+- Highly reusable
+- Accept minimal props
+- No dependencies on other custom components (may use shadcn)
+
+**Examples**:
+- `AppLogo` - The application logo icon
+- `TabIcon` - Icon wrapper with styling variants
+- `StatusIcon` - Status indicator icons (saved, synced)
+- `ErrorBadge` - Badge showing error count
+
+**When to create an atom**:
+- You have a single UI element used in multiple places
+- The component has no complex logic or state
+- It's a styled wrapper around a basic HTML element or icon
+
+---
+
+### 🔬 Molecules (`/molecules`)
+**Purpose**: Simple combinations of atoms that work together as a unit.
+
+**Characteristics**:
+- Composed of 2-5 atoms
+- Single responsibility
+- Minimal state management
+- Reusable across multiple contexts
+- May include simple interactions
+
+**Examples**:
+- `SaveIndicator` - Combines StatusIcon + text to show save status
+- `AppBranding` - Combines AppLogo + title + subtitle
+- `PageHeaderContent` - Combines TabIcon + title + description
+- `ToolbarButton` - Button + Tooltip wrapper
+- `NavigationItem` - Icon + label + badge navigation button
+- `NavigationGroupHeader` - Collapsible group header with count
+
+**When to create a molecule**:
+- You're combining atoms to create a meaningful UI pattern
+- The combination is reused in multiple organisms
+- It represents a single functional unit (like "branding" or "save status")
+
+---
+
+### 🧬 Organisms (`/organisms`)
+**Purpose**: Complex, feature-rich components that combine molecules and atoms.
+
+**Characteristics**:
+- Complex composition (5+ child components)
+- May manage state
+- Business logic allowed
+- Feature-specific functionality
+- Can include API calls or data fetching
+
+**Examples**:
+- `NavigationMenu` - Full sidebar navigation with groups, items, search
+- `PageHeader` - Complete page header with icon and description
+- `ToolbarActions` - Toolbar with multiple action buttons
+- `AppHeader` - Complete application header with nav, branding, save indicator, and actions
+
+**When to create an organism**:
+- You're building a major UI section (header, navigation, toolbar)
+- The component manages complex state or user interactions
+- It coordinates multiple molecules and atoms
+- It's feature-specific rather than generic
+
+---
+
+### 🏗️ Feature Components (`/components/[FeatureName].tsx`)
+**Purpose**: Full-featured, domain-specific components that implement complete features.
+
+**Characteristics**:
+- High-level business components
+- Complete feature implementations
+- May use multiple organisms, molecules, and atoms
+- Include complex state management
+- Feature-specific (not reusable across features)
+
+**Examples**:
+- `CodeEditor` - Full Monaco code editor with file management
+- `ModelDesigner` - Complete Prisma model design interface
+- `ComponentTreeBuilder` - React component hierarchy builder
+- `WorkflowDesigner` - Visual workflow design canvas
+- `ProjectDashboard` - Complete dashboard view
+
+**When to create a feature component**:
+- You're implementing a complete feature or page
+- The component is not reusable outside its feature domain
+- It requires significant state management and business logic
+
+---
+
+## Component Organization Rules
+
+### 1. Import Hierarchy
+Components should only import from their level or below:
+- ✅ Organisms can import molecules and atoms
+- ✅ Molecules can import atoms
+- ❌ Atoms should NOT import molecules or organisms
+- ❌ Molecules should NOT import organisms
+
+### 2. Naming Conventions
+- **Atoms**: Simple nouns (`AppLogo`, `StatusIcon`, `ErrorBadge`)
+- **Molecules**: Descriptive combinations (`SaveIndicator`, `ToolbarButton`, `NavigationItem`)
+- **Organisms**: Feature-descriptive (`NavigationMenu`, `AppHeader`, `ToolbarActions`)
+- **Features**: Feature names (`CodeEditor`, `ModelDesigner`, `ProjectDashboard`)
+
+### 3. File Structure
+Each atomic level has:
+```
+atoms/
+├── AppLogo.tsx
+├── TabIcon.tsx
+├── StatusIcon.tsx
+├── ErrorBadge.tsx
+└── index.ts    # Exports all atoms
+```
+
+### 4. Index Files
+Each directory should have an `index.ts` for clean imports:
+```typescript
+// atoms/index.ts
+export { AppLogo } from './AppLogo'
+export { TabIcon } from './TabIcon'
+export { StatusIcon } from './StatusIcon'
+export { ErrorBadge } from './ErrorBadge'
+```
+
+This allows:
+```typescript
+// Good ✅
+import { AppLogo, StatusIcon } from '@/components/atoms'
+
+// Instead of ❌
+import { AppLogo } from '@/components/atoms/AppLogo'
+import { StatusIcon } from '@/components/atoms/StatusIcon'
+```
+
+---
+
+## Configuration Files
+
+### `lib/navigation-config.tsx`
+Centralized configuration for navigation structure:
+- **`tabInfo`**: Maps tab IDs to their display information
+- **`navigationGroups`**: Defines navigation hierarchy and groupings
+- **`NavigationItemData`**: TypeScript interfaces for type safety
+
+**Benefits**:
+- Single source of truth for navigation
+- Easy to add/remove navigation items
+- Type-safe navigation configuration
+- Separates data from presentation logic
+
+---
+
+## Migration Guide
+
+When refactoring existing components:
+
+1. **Identify the component's level**
+   - Does it contain business logic? → Feature component
+   - Does it combine many elements? → Organism
+   - Does it combine a few atoms? → Molecule
+   - Is it a single UI element? → Atom
+
+2. **Check dependencies**
+   - What does it import?
+   - Can it be broken into smaller pieces?
+   - Are parts reusable elsewhere?
+
+3. **Extract reusable parts**
+   ```typescript
+   // Before: Monolithic component
+   function Header() {
+     return (
+       <header>
+         <div className="logo">...</div>
+         <div className="save">...</div>
+         <div className="actions">...</div>
+       </header>
+     )
+   }
+
+   // After: Atomic structure
+   // atoms/AppLogo.tsx
+   export function AppLogo() { ... }
+
+   // molecules/SaveIndicator.tsx
+   export function SaveIndicator() { ... }
+
+   // organisms/AppHeader.tsx
+   export function AppHeader() {
+     return (
+       <header>
+         <AppLogo />
+         <SaveIndicator />
+         <ToolbarActions />
+       </header>
+     )
+   }
+   ```
+
+4. **Move to appropriate directory**
+   - Create the component file in its level directory
+   - Update the level's `index.ts`
+   - Update imports in consuming components
+
+---
+
+## Best Practices
+
+### 1. Keep Atoms Pure
+```typescript
+// Good ✅ - Pure, reusable atom
+export function StatusIcon({ type, size = 14 }: StatusIconProps) {
+  return type === 'saved' 
+    ? <CheckCircle size={size} className="text-accent" />
+    : <CloudCheck size={size} />
+}
+
+// Bad ❌ - Too much logic for an atom
+export function StatusIcon({ lastSaved }: { lastSaved: number }) {
+  const [time, setTime] = useState(Date.now())
+  useEffect(() => { /* complex logic */ }, [lastSaved])
+  return <CheckCircle />
+}
+```
+
+### 2. Compose in Molecules
+```typescript
+// Good ✅ - Molecule combines atoms with simple logic
+export function SaveIndicator({ lastSaved }: SaveIndicatorProps) {
+  const isRecent = Date.now() - lastSaved < 3000
+  return (
+    <div>
+      <StatusIcon type={isRecent ? 'saved' : 'synced'} />
+      <span>{isRecent ? 'Saved' : timeAgo}</span>
+    </div>
+  )
+}
+```
+
+### 3. Coordinate in Organisms
+```typescript
+// Good ✅ - Organism manages complex state and coordinates molecules
+export function AppHeader({ onSave, onSearch }: AppHeaderProps) {
+  const [lastSaved, setLastSaved] = useState<number | null>(null)
+  
+  return (
+    <header>
+      <AppBranding />
+      <SaveIndicator lastSaved={lastSaved} />
+      <ToolbarActions onSave={onSave} onSearch={onSearch} />
+    </header>
+  )
+}
+```
+
+### 4. Single Responsibility
+Each component should do one thing well:
+- `AppLogo` → Show the logo
+- `SaveIndicator` → Show save status
+- `AppHeader` → Compose the complete header
+
+### 5. Props Over Children (Usually)
+Prefer explicit props for better type safety:
+```typescript
+// Good ✅
+<ToolbarButton icon={<Search />} label="Search" onClick={onSearch} />
+
+// Less ideal (but sometimes necessary)
+<ToolbarButton onClick={onSearch}>
+  <Search />
+  Search
+</ToolbarButton>
+```
+
+---
+
+## Benefits of Atomic Design
+
+1. **Reusability**: Atoms and molecules can be used across features
+2. **Consistency**: Shared atoms ensure consistent UI
+3. **Testability**: Small components are easier to test
+4. **Maintainability**: Changes propagate naturally through composition
+5. **Collaboration**: Clear boundaries make teamwork easier
+6. **Documentation**: Structure itself documents component relationships
+7. **Performance**: Smaller components are easier to optimize
+8. **Refactoring**: Easy to identify and extract reusable patterns
+
+---
+
+## Quick Reference
+
+| Level | Size | State | Logic | Reusability | Examples |
+|-------|------|-------|-------|-------------|----------|
+| **Atom** | 1 element | None | None | Very High | Logo, Icon, Badge |
+| **Molecule** | 2-5 atoms | Minimal | Simple | High | SaveIndicator, ToolbarButton |
+| **Organism** | 5+ components | Moderate | Complex | Medium | Navigation, Header, Toolbar |
+| **Feature** | Full feature | Complex | Business | Low | CodeEditor, Dashboard |
+
+---
+
+## Future Improvements
+
+Potential enhancements to the atomic structure:
+
+1. **Storybook Integration**: Document all atoms and molecules in Storybook
+2. **Visual Regression Testing**: Test component appearance automatically
+3. **Component Playground**: Interactive component explorer
+4. **Design Tokens**: Move colors/spacing to design token system
+5. **Component Generator**: CLI tool to scaffold new components
+6. **Dependency Graphs**: Visualize component relationships
+
+---
+
+## Getting Help
+
+When deciding where a component belongs, ask:
+
+1. **Can it be broken down?** → If yes, it's not an atom
+2. **Does it combine atoms?** → It's at least a molecule
+3. **Does it have complex state?** → Probably an organism
+4. **Is it feature-specific?** → Keep it as a feature component
+
+**Still unsure?** Start with a higher level (organism or feature) and refactor down as patterns emerge.

docs/architecture/atomic/ATOMIC_DOCS_INDEX.md

@@ -0,0 +1,296 @@
+# Atomic Component Library - Documentation Index
+
+## 📚 Complete Documentation Suite
+
+This refactor includes comprehensive documentation to help you understand and work with the new atomic component structure.
+
+## 🎯 Where to Start
+
+### New to Atomic Design?
+**Start here:** [ATOMIC_README.md](./ATOMIC_README.md)
+- Quick overview of concepts
+- Component level explanations
+- Common usage patterns
+- Quick reference guide
+
+### Need Visual Understanding?
+**Check out:** [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md)
+- Component hierarchy diagrams
+- Data flow visualizations
+- File structure trees
+- Testing pyramids
+
+### Want to Understand the Changes?
+**Read:** [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)
+- What changed and why
+- Before/after comparisons
+- Migration summary
+- Benefits overview
+
+## 📖 Complete Documentation List
+
+### 1. Quick Start & Overview
+- **[ATOMIC_README.md](./ATOMIC_README.md)** ⭐ **START HERE**
+  - Quick start guide
+  - Component level reference
+  - Usage patterns
+  - Best practices summary
+
+### 2. Visual Guides
+- **[ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md)**
+  - ASCII art diagrams
+  - Component flow charts
+  - Import dependency graphs
+  - Performance visualizations
+
+### 3. Complete Architecture Guide
+- **[ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md)**
+  - Full atomic design methodology
+  - Detailed component rules
+  - Naming conventions
+  - Migration strategies
+  - Future improvements
+
+### 4. Practical Examples
+- **[ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)**
+  - 10+ real-world examples
+  - Code templates
+  - Testing patterns
+  - TypeScript patterns
+  - Performance tips
+
+### 5. Component Dependencies
+- **[COMPONENT_MAP.md](./COMPONENT_MAP.md)**
+  - Component composition diagrams
+  - Import graphs
+  - Data flow examples
+  - Styling patterns
+  - Accessibility guidelines
+
+### 6. Refactor Summary
+- **[ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)**
+  - What changed
+  - Component inventory
+  - Benefits analysis
+  - Next steps
+  - Migration status
+
+## 🗂️ Documentation by Purpose
+
+### Learning Atomic Design
+1. [ATOMIC_README.md](./ATOMIC_README.md) - Core concepts
+2. [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Deep dive
+3. [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md) - Visual understanding
+
+### Implementing Components
+1. [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) - Code examples
+2. [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Composition patterns
+3. [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Rules and guidelines
+
+### Understanding the Refactor
+1. [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md) - Change overview
+2. [COMPONENT_MAP.md](./COMPONENT_MAP.md) - New structure
+3. [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md) - Visual comparison
+
+### Testing & Maintenance
+1. [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) - Testing patterns
+2. [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Maintenance guidelines
+3. [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Testing strategy
+
+## 📊 Documentation Coverage
+
+### Topics Covered
+
+✅ **Concepts & Methodology**
+- Atomic design principles
+- Component hierarchy
+- Composition patterns
+
+✅ **Implementation**
+- Code examples (10+)
+- Usage patterns
+- TypeScript integration
+
+✅ **Architecture**
+- File structure
+- Import patterns
+- Dependency rules
+
+✅ **Best Practices**
+- Naming conventions
+- Testing strategies
+- Performance tips
+
+✅ **Migration**
+- Refactor guide
+- Before/after examples
+- Step-by-step checklist
+
+✅ **Visual Aids**
+- Component diagrams
+- Data flow charts
+- Dependency graphs
+
+✅ **Reference**
+- Component inventory
+- Quick reference tables
+- API documentation
+
+## 🎓 Learning Path
+
+### Beginner (0-1 hour)
+1. Read [ATOMIC_README.md](./ATOMIC_README.md) (15 min)
+2. Review [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md) (15 min)
+3. Try examples from [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) (30 min)
+
+### Intermediate (1-2 hours)
+1. Study [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) (45 min)
+2. Review [COMPONENT_MAP.md](./COMPONENT_MAP.md) (30 min)
+3. Implement a molecule (15 min)
+
+### Advanced (2+ hours)
+1. Read [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md) (30 min)
+2. Refactor an existing component (60 min)
+3. Create an organism (30 min)
+4. Document patterns (30 min)
+
+## 🔍 Quick Reference by Question
+
+### "How do I create a new component?"
+→ [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) - Example 8 & Quick Start Template
+
+### "Which component level should I use?"
+→ [ATOMIC_README.md](./ATOMIC_README.md) - Component Levels table
+→ [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - When to create section
+
+### "How do imports work?"
+→ [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Component Import Graph
+→ [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md) - Import Dependency Graph
+
+### "What changed in the refactor?"
+→ [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md) - What Changed section
+
+### "How do I test atomic components?"
+→ [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) - Testing section
+→ [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Testing Strategy
+
+### "What are the component composition rules?"
+→ [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Component Organization Rules
+
+### "How do I migrate an existing component?"
+→ [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Migration Guide
+→ [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md) - Migration Summary
+
+### "What are the naming conventions?"
+→ [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md) - Naming Conventions
+
+### "How do I optimize performance?"
+→ [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Performance Considerations
+→ [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) - Performance Tips
+
+### "Where can I see visual diagrams?"
+→ [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md) - All diagrams
+→ [COMPONENT_MAP.md](./COMPONENT_MAP.md) - Composition diagrams
+
+## 📏 Documentation Metrics
+
+### Files Created
+- 6 markdown documentation files
+- ~45 KB total documentation
+- 21 component files created
+- 3 index files for exports
+
+### Topics Covered
+- 15 major sections
+- 40+ code examples
+- 10+ diagrams
+- 100+ best practices
+
+### Component Documentation
+- 7 atoms documented
+- 10 molecules documented
+- 4 organisms documented
+- All with usage examples
+
+## 🔄 Keeping Documentation Updated
+
+### When Creating New Components
+1. Add to appropriate level's index.ts
+2. Update [COMPONENT_MAP.md](./COMPONENT_MAP.md) with dependency info
+3. Add usage example to [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)
+4. Update component inventory in [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)
+
+### When Refactoring
+1. Document in [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)
+2. Update patterns in [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md)
+3. Add visual diagrams to [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md)
+
+### When Adding Examples
+1. Add to [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)
+2. Reference in [ATOMIC_README.md](./ATOMIC_README.md) if fundamental
+
+## 🎯 Documentation Goals Achieved
+
+✅ **Clarity** - Multiple formats (text, code, diagrams)
+✅ **Completeness** - Covers all aspects of atomic design
+✅ **Accessibility** - Quick start for beginners, depth for advanced
+✅ **Practicality** - Real examples and templates
+✅ **Maintainability** - Clear structure for updates
+✅ **Searchability** - Index and cross-references
+
+## 🚀 Next Steps
+
+### For New Team Members
+1. Start with [ATOMIC_README.md](./ATOMIC_README.md)
+2. Review visual diagrams
+3. Try creating a molecule
+4. Ask questions in code reviews
+
+### For Existing Team Members
+1. Review [ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)
+2. Study [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)
+3. Refactor a component
+4. Share learnings
+
+### For the Project
+1. Add Storybook for visual component docs
+2. Create automated tests for all atoms/molecules
+3. Build component usage analytics
+4. Gather feedback and improve
+
+## 📞 Getting Help
+
+### Documentation Not Clear?
+- Check the visual diagrams in [ATOMIC_VISUAL_OVERVIEW.md](./ATOMIC_VISUAL_OVERVIEW.md)
+- Look for examples in [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)
+- Review the FAQ in [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md)
+
+### Need More Examples?
+- See [ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md) for 10+ examples
+- Check [COMPONENT_MAP.md](./COMPONENT_MAP.md) for composition patterns
+- Look at existing components in the codebase
+
+### Stuck on Implementation?
+- Review the rules in [ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md)
+- Check the quick reference in [ATOMIC_README.md](./ATOMIC_README.md)
+- See if there's a similar component already implemented
+
+## 🎉 Success!
+
+You now have access to comprehensive documentation covering:
+- ✅ Atomic design concepts
+- ✅ Component architecture
+- ✅ Implementation examples
+- ✅ Testing strategies
+- ✅ Migration guides
+- ✅ Visual references
+- ✅ Best practices
+- ✅ Quick starts
+
+**Happy coding with atomic components!** 🚀
+
+---
+
+**Last Updated:** January 2025
+**Version:** 1.0
+**Status:** ✅ Complete and ready to use

docs/architecture/atomic/ATOMIC_README.md

@@ -0,0 +1,335 @@
+# Atomic Component Library - Quick Start
+
+## 📚 Documentation Overview
+
+This project now uses an **Atomic Design** component architecture. Here's how to navigate the documentation:
+
+### Essential Reading (Start Here!)
+
+1. **[ATOMIC_REFACTOR_SUMMARY.md](./ATOMIC_REFACTOR_SUMMARY.md)** - Overview of changes
+   - What changed and why
+   - Component inventory
+   - Benefits and usage patterns
+   - Next steps
+
+2. **[ATOMIC_COMPONENTS.md](./ATOMIC_COMPONENTS.md)** - Complete guide
+   - Atomic design methodology explained
+   - Component hierarchy rules
+   - When to create each type
+   - Best practices and patterns
+   - Migration guide
+
+3. **[ATOMIC_USAGE_EXAMPLES.md](./ATOMIC_USAGE_EXAMPLES.md)** - Practical examples
+   - 10+ real-world usage examples
+   - Code templates
+   - Testing patterns
+   - Quick start guide
+
+4. **[COMPONENT_MAP.md](./COMPONENT_MAP.md)** - Visual reference
+   - Component composition diagrams
+   - Dependency maps
+   - Data flow examples
+   - Performance tips
+
+## 🎯 Quick Reference
+
+### Component Levels
+
+| Level | Purpose | Example | Import From |
+|-------|---------|---------|-------------|
+| **Atom** | Single UI element | `AppLogo`, `StatusIcon` | `@/components/atoms` |
+| **Molecule** | 2-5 atoms combined | `SaveIndicator`, `ToolbarButton` | `@/components/molecules` |
+| **Organism** | Complex composition | `AppHeader`, `NavigationMenu` | `@/components/organisms` |
+| **Feature** | Domain-specific | `CodeEditor`, `ModelDesigner` | `@/components/[Name]` |
+
+### Directory Structure
+
+```
+src/components/
+├── atoms/              # 7 building blocks
+├── molecules/          # 10 simple combinations
+├── organisms/          # 4 complex components
+├── ui/                 # shadcn base components
+└── [features]/        # Feature components
+```
+
+## 🚀 Usage Examples
+
+### Using Atoms
+```tsx
+import { AppLogo, StatusIcon, ErrorBadge } from '@/components/atoms'
+
+<AppLogo />
+<StatusIcon type="saved" animate />
+<ErrorBadge count={5} />
+```
+
+### Using Molecules
+```tsx
+import { SaveIndicator, ToolbarButton, EmptyState } from '@/components/molecules'
+
+<SaveIndicator lastSaved={Date.now()} />
+<ToolbarButton icon={<Plus />} label="Add" onClick={handleAdd} />
+<EmptyState icon={<Code />} title="No files" description="Get started" />
+```
+
+### Using Organisms
+```tsx
+import { AppHeader, PageHeader, NavigationMenu } from '@/components/organisms'
+
+<AppHeader
+  activeTab={activeTab}
+  onTabChange={setActiveTab}
+  lastSaved={lastSaved}
+  onExport={handleExport}
+  {...props}
+/>
+```
+
+## 📋 Component Inventory
+
+### Atoms (7)
+- `AppLogo` - Application logo
+- `TabIcon` - Icon with variants
+- `StatusIcon` - Save/sync status
+- `ErrorBadge` - Error counter
+- `IconWrapper` - Icon container
+- `LoadingSpinner` - Loading animation
+- `EmptyStateIcon` - Empty state icon
+
+### Molecules (10)
+- `SaveIndicator` - Save status display
+- `AppBranding` - Logo + title
+- `PageHeaderContent` - Page title section
+- `ToolbarButton` - Button with tooltip
+- `NavigationItem` - Nav link
+- `NavigationGroupHeader` - Group header
+- `EmptyState` - Empty state view
+- `LoadingState` - Loading view
+- `StatCard` - Statistics card
+- `LabelWithBadge` - Label + badge
+
+### Organisms (4)
+- `NavigationMenu` - Sidebar navigation
+- `PageHeader` - Page header
+- `ToolbarActions` - Action toolbar
+- `AppHeader` - Application header
+
+## 🛠️ Creating New Components
+
+### 1. Determine Component Level
+
+Ask yourself:
+- Can it be broken down? → Not an atom
+- Does it combine atoms? → At least a molecule
+- Does it have complex state? → Probably an organism
+- Is it feature-specific? → Feature component
+
+### 2. Create the Component
+
+```tsx
+// src/components/atoms/MyAtom.tsx
+interface MyAtomProps {
+  value: string
+  variant?: 'default' | 'primary'
+}
+
+export function MyAtom({ value, variant = 'default' }: MyAtomProps) {
+  return <span className={variant}>{value}</span>
+}
+```
+
+### 3. Update Index File
+
+```tsx
+// src/components/atoms/index.ts
+export { MyAtom } from './MyAtom'
+```
+
+### 4. Use in Your Code
+
+```tsx
+import { MyAtom } from '@/components/atoms'
+
+<MyAtom value="Hello" variant="primary" />
+```
+
+## ✅ Best Practices
+
+### DO:
+- ✅ Use atoms for single-purpose elements
+- ✅ Compose molecules from atoms
+- ✅ Build organisms from molecules/atoms
+- ✅ Keep feature logic in feature components
+- ✅ Export from index files
+- ✅ Use TypeScript types
+- ✅ Follow naming conventions
+
+### DON'T:
+- ❌ Import organisms in atoms
+- ❌ Import molecules in atoms
+- ❌ Duplicate atom functionality
+- ❌ Mix business logic in atoms/molecules
+- ❌ Skip TypeScript types
+- ❌ Create "god components"
+
+## 📊 Import Hierarchy
+
+```
+Feature Components
+       ↓ can import
+    Organisms
+       ↓ can import
+    Molecules
+       ↓ can import
+      Atoms
+       ↓ can import
+   shadcn UI
+```
+
+## 🔧 Common Patterns
+
+### Pattern 1: Status Display
+```tsx
+const isRecent = Date.now() - lastSaved < 3000
+<StatusIcon type={isRecent ? 'saved' : 'synced'} />
+```
+
+### Pattern 2: Empty State
+```tsx
+<EmptyState
+  icon={<FileCode size={32} />}
+  title="No files yet"
+  description="Create your first file"
+  action={<Button onClick={onCreate}>Create File</Button>}
+/>
+```
+
+### Pattern 3: Loading State
+```tsx
+{isLoading ? (
+  <LoadingState message="Loading files..." />
+) : (
+  <FileList files={files} />
+)}
+```
+
+### Pattern 4: Stat Cards
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  <StatCard icon={<Code />} label="Files" value={fileCount} />
+  <StatCard icon={<Database />} label="Models" value={modelCount} />
+  <StatCard icon={<Tree />} label="Components" value={compCount} />
+</div>
+```
+
+## 🧪 Testing
+
+### Atoms (Unit Tests)
+```tsx
+describe('StatusIcon', () => {
+  it('shows CheckCircle when saved', () => {
+    render(<StatusIcon type="saved" />)
+    expect(screen.getByTestId('check-circle')).toBeInTheDocument()
+  })
+})
+```
+
+### Molecules (Integration Tests)
+```tsx
+describe('SaveIndicator', () => {
+  it('shows saved text when recent', () => {
+    render(<SaveIndicator lastSaved={Date.now() - 1000} />)
+    expect(screen.getByText('Saved')).toBeInTheDocument()
+  })
+})
+```
+
+### Organisms (E2E Tests)
+```tsx
+describe('NavigationMenu', () => {
+  it('navigates when item clicked', () => {
+    render(<NavigationMenu {...props} />)
+    userEvent.click(screen.getByText('Code Editor'))
+    expect(onTabChange).toHaveBeenCalledWith('code')
+  })
+})
+```
+
+## 🎨 Styling
+
+All components use:
+- **Tailwind** for utility classes
+- **CSS variables** for theming
+- **Responsive** design patterns
+- **Accessible** markup
+
+Example:
+```tsx
+<div className="flex items-center gap-2 sm:gap-3 text-sm sm:text-base">
+  {/* Responsive spacing and text sizing */}
+</div>
+```
+
+## 📝 TypeScript
+
+All components are fully typed:
+```tsx
+interface ComponentProps {
+  required: string
+  optional?: number
+  callback?: () => void
+  variant?: 'default' | 'primary'
+}
+
+export function Component({ required, optional = 0 }: ComponentProps) {
+  // Implementation
+}
+```
+
+## 🚦 Next Steps
+
+1. **Read the docs** - Start with ATOMIC_REFACTOR_SUMMARY.md
+2. **Review examples** - Check ATOMIC_USAGE_EXAMPLES.md
+3. **Study the maps** - See COMPONENT_MAP.md for visual guides
+4. **Try it out** - Create a new molecule or atom
+5. **Refactor** - Identify components to atomize
+
+## 💡 Tips
+
+- Start with molecules for most use cases
+- Extract atoms when you see duplication
+- Build organisms for major UI sections
+- Keep feature components for domain logic
+- Use index files for clean imports
+- Follow the existing patterns
+
+## 🤝 Contributing
+
+When adding new atomic components:
+
+1. Choose the appropriate level
+2. Create the component file
+3. Add TypeScript types
+4. Update the index.ts
+5. Add to COMPONENT_MAP.md
+6. Create usage examples
+7. Write tests
+
+## 📞 Need Help?
+
+1. Check the documentation files
+2. Look at existing component examples
+3. Review the component map
+4. Follow established patterns
+5. Ask questions in code reviews
+
+## 🔗 Resources
+
+- **Atomic Design**: https://atomicdesign.bradfrost.com/
+- **Component-Driven**: https://www.componentdriven.org/
+- **React Patterns**: https://reactpatterns.com/
+
+---
+
+**Remember**: The atomic structure makes components more reusable, testable, and maintainable. When in doubt, start small (atom/molecule) and grow as needed!

docs/architecture/atomic/ATOMIC_REFACTOR_SUMMARY.md

@@ -0,0 +1,431 @@
+# Atomic Component Library Refactor - Summary
+
+## Overview
+
+The codebase has been refactored into an **Atomic Design** component library structure for improved maintainability, reusability, and scalability.
+
+## What Changed
+
+### New Directory Structure
+
+```
+src/components/
+├── atoms/              # NEW: 7 atomic components
+│   ├── AppLogo.tsx
+│   ├── TabIcon.tsx
+│   ├── StatusIcon.tsx
+│   ├── ErrorBadge.tsx
+│   ├── IconWrapper.tsx
+│   ├── LoadingSpinner.tsx
+│   ├── EmptyStateIcon.tsx
+│   └── index.ts
+├── molecules/          # NEW: 10 molecular components
+│   ├── SaveIndicator.tsx
+│   ├── AppBranding.tsx
+│   ├── PageHeaderContent.tsx
+│   ├── ToolbarButton.tsx
+│   ├── NavigationItem.tsx
+│   ├── NavigationGroupHeader.tsx
+│   ├── EmptyState.tsx
+│   ├── LoadingState.tsx
+│   ├── StatCard.tsx
+│   ├── LabelWithBadge.tsx
+│   └── index.ts
+├── organisms/          # NEW: 4 complex components
+│   ├── NavigationMenu.tsx
+│   ├── PageHeader.tsx
+│   ├── ToolbarActions.tsx
+│   ├── AppHeader.tsx
+│   └── index.ts
+├── ui/                 # Existing shadcn components
+└── [features]/        # Existing feature components
+```
+
+### New Configuration Files
+
+```
+src/lib/
+└── navigation-config.tsx    # NEW: Centralized navigation data
+```
+
+### New Documentation
+
+```
+├── ATOMIC_COMPONENTS.md         # Complete guide to atomic design
+├── COMPONENT_MAP.md             # Visual component dependency maps
+├── ATOMIC_USAGE_EXAMPLES.md    # Practical usage examples
+└── ATOMIC_REFACTOR_SUMMARY.md  # This file
+```
+
+## Component Inventory
+
+### Atoms (7)
+Building blocks - smallest reusable UI elements:
+1. **AppLogo** - Application logo with gradient background
+2. **TabIcon** - Icon wrapper with variant support
+3. **StatusIcon** - Save/sync status indicators
+4. **ErrorBadge** - Error count badge
+5. **IconWrapper** - General icon wrapper with sizing
+6. **LoadingSpinner** - Animated loading indicator
+7. **EmptyStateIcon** - Large icon for empty states
+
+### Molecules (10)
+Simple combinations of atoms:
+1. **SaveIndicator** - Save status with timestamp
+2. **AppBranding** - Logo + app name + subtitle
+3. **PageHeaderContent** - Page title with icon
+4. **ToolbarButton** - Button with tooltip
+5. **NavigationItem** - Nav link with badge
+6. **NavigationGroupHeader** - Collapsible group header
+7. **EmptyState** - Empty state display
+8. **LoadingState** - Loading indicator with message
+9. **StatCard** - Statistic card with icon
+10. **LabelWithBadge** - Label with optional badge
+
+### Organisms (4)
+Complex, feature-rich components:
+1. **NavigationMenu** - Complete sidebar navigation
+2. **PageHeader** - Page header with context
+3. **ToolbarActions** - Multi-button toolbar
+4. **AppHeader** - Complete application header
+
+## Key Benefits
+
+### 1. Reusability
+- Atoms and molecules can be used across any feature
+- Consistent UI elements throughout the app
+- Reduced code duplication
+
+### 2. Maintainability
+- Changes to atoms automatically propagate
+- Clear component boundaries
+- Easy to locate and update components
+
+### 3. Testability
+- Small, focused components are easier to test
+- Test atoms in isolation, then molecules, then organisms
+- Better test coverage with less code
+
+### 4. Scalability
+- Adding new features is faster with existing components
+- Pattern is clear for new developers
+- Component library grows organically
+
+### 5. Consistency
+- Design system enforced through atoms
+- Standardized spacing, sizing, colors
+- Predictable behavior across the app
+
+### 6. Documentation
+- Self-documenting component structure
+- Clear naming conventions
+- Easy to onboard new developers
+
+## Migration Summary
+
+### Refactored Components
+
+#### From Monolithic to Atomic:
+- **SaveIndicator.tsx** → Split into `StatusIcon` (atom) + `SaveIndicator` (molecule)
+- **NavigationMenu.tsx** → Split into `NavigationItem`, `NavigationGroupHeader` (molecules) + `NavigationMenu` (organism)
+- **PageHeader.tsx** → Split into `TabIcon` (atom), `PageHeaderContent` (molecule), `PageHeader` (organism)
+- **App header section** → Extracted into `AppLogo`, `AppBranding`, `ToolbarButton`, `ToolbarActions`, `AppHeader`
+
+### New Centralized Configuration:
+- **navigation-config.tsx** - Single source of truth for navigation structure
+  - `tabInfo` - Tab display information
+  - `navigationGroups` - Navigation hierarchy
+  - TypeScript interfaces for type safety
+
+### Updated Files:
+- **App.tsx** - Now uses atomic components via `AppHeader` and `PageHeader`
+- **index.css** - Unchanged (existing theme system)
+- **PRD.md** - Updated with atomic architecture section
+
+## Usage Pattern
+
+### Before (Monolithic):
+```tsx
+// Inline, non-reusable header
+<header>
+  <div className="logo">
+    <Code /> CodeForge
+  </div>
+  <div>{lastSaved ? 'Saved' : 'Unsaved'}</div>
+  <Button>Export</Button>
+</header>
+```
+
+### After (Atomic):
+```tsx
+// Composable, reusable components
+<AppHeader
+  activeTab={activeTab}
+  onTabChange={setActiveTab}
+  lastSaved={lastSaved}
+  onExport={handleExport}
+  // ... more props
+/>
+```
+
+## Import Pattern
+
+### Before:
+```tsx
+import { NavigationMenu } from '@/components/NavigationMenu'
+import { PageHeader } from '@/components/PageHeader'
+import { SaveIndicator } from '@/components/SaveIndicator'
+```
+
+### After:
+```tsx
+// Import from level (atoms, molecules, organisms)
+import { AppLogo, StatusIcon } from '@/components/atoms'
+import { SaveIndicator, ToolbarButton } from '@/components/molecules'
+import { AppHeader, PageHeader } from '@/components/organisms'
+
+// Or import from root index
+import { AppLogo, SaveIndicator, AppHeader } from '@/components'
+```
+
+## Component Hierarchy Example
+
+How `AppHeader` is composed:
+
+```
+AppHeader (organism)
+├── NavigationMenu (organism)
+│   ├── NavigationGroupHeader (molecule)
+│   └── NavigationItem (molecule)
+│       └── ErrorBadge (atom)
+├── AppBranding (molecule)
+│   └── AppLogo (atom)
+├── SaveIndicator (molecule)
+│   └── StatusIcon (atom)
+└── ToolbarActions (organism)
+    └── ToolbarButton (molecule)
+        └── IconWrapper (atom)
+```
+
+## Next Steps
+
+### Recommended Actions:
+
+1. **Familiarize with Structure**
+   - Read `ATOMIC_COMPONENTS.md` for detailed guidelines
+   - Review `COMPONENT_MAP.md` for visual structure
+   - Study `ATOMIC_USAGE_EXAMPLES.md` for patterns
+
+2. **Continue Refactoring**
+   - Identify more monolithic components
+   - Extract reusable patterns into atoms/molecules
+   - Build new features using atomic components
+
+3. **Add Documentation**
+   - Create Storybook stories for atoms and molecules
+   - Add JSDoc comments to component props
+   - Document common patterns
+
+4. **Improve Testing**
+   - Add unit tests for atoms
+   - Add integration tests for molecules
+   - Add E2E tests for organisms
+
+5. **Enhance Components**
+   - Add more variants to existing atoms
+   - Create additional utility molecules
+   - Build domain-specific organisms
+
+### Potential New Components:
+
+**Atoms:**
+- `StatusDot` - Colored status indicator
+- `AvatarInitials` - User initials display
+- `KeyboardKey` - Styled keyboard key
+
+**Molecules:**
+- `SearchInput` - Search with icon and clear
+- `FileIcon` - File type icons
+- `Breadcrumbs` - Navigation breadcrumbs
+
+**Organisms:**
+- `CommandPalette` - Keyboard command interface
+- `NotificationCenter` - Notification management
+- `QuickAccessToolbar` - Customizable toolbar
+
+## Breaking Changes
+
+### None!
+
+All existing feature components continue to work. The refactor:
+- ✅ Maintains backward compatibility
+- ✅ Preserves all functionality
+- ✅ Keeps existing APIs stable
+- ✅ Does not require migration of feature components
+
+Only the internal structure of `App.tsx` header changed, and it uses the same props/behavior.
+
+## Performance Impact
+
+### Positive:
+- Smaller bundle sizes through better tree-shaking
+- Faster re-renders with memoized organisms
+- Better code splitting opportunities
+
+### Neutral:
+- No performance degradation
+- Same number of total components rendered
+- Equivalent runtime behavior
+
+## TypeScript Support
+
+All atomic components are fully typed:
+- ✅ Strict prop interfaces
+- ✅ Exported type definitions
+- ✅ Generic support where appropriate
+- ✅ IntelliSense friendly
+
+Example:
+```tsx
+interface SaveIndicatorProps {
+  lastSaved: number | null
+}
+
+export function SaveIndicator({ lastSaved }: SaveIndicatorProps) {
+  // Type-safe implementation
+}
+```
+
+## Accessibility
+
+All atomic components follow accessibility best practices:
+- ✅ Semantic HTML
+- ✅ ARIA labels where needed
+- ✅ Keyboard navigation support
+- ✅ Screen reader friendly
+- ✅ Focus management
+
+## Browser Support
+
+No changes to browser support:
+- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
+- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+- ✅ Same compatibility as before
+
+## File Size Impact
+
+### Added Files:
+- 7 atoms (~2KB total)
+- 10 molecules (~8KB total)
+- 4 organisms (~12KB total)
+- 1 config (~7KB)
+- **Total new code: ~29KB**
+
+### Removed Duplication:
+- Extracted inline components (~10KB)
+- Centralized navigation config (~5KB saved)
+- **Net impact: +14KB** (acceptable for improved structure)
+
+## Testing Strategy
+
+### Recommended Testing Pyramid:
+
+```
+        /\
+       /  \
+      / E2E \          (Organisms - 10 tests)
+     /--------\
+    / Integr.  \       (Molecules - 30 tests)
+   /-----------\
+  /   Unit      \      (Atoms - 70 tests)
+ /---------------\
+```
+
+1. **Atoms (70%)**: Unit test each atom thoroughly
+2. **Molecules (20%)**: Integration test compositions
+3. **Organisms (10%)**: E2E test user flows
+
+## Rollout Plan
+
+### Phase 1: ✅ Complete
+- Created atomic structure
+- Built initial atoms, molecules, organisms
+- Refactored App.tsx header
+- Added comprehensive documentation
+
+### Phase 2: Suggested Next
+- Add Storybook for component library
+- Create unit tests for all atoms
+- Add integration tests for molecules
+- Document additional patterns
+
+### Phase 3: Future
+- Migrate feature components to atomic patterns
+- Build comprehensive component playground
+- Add visual regression testing
+- Create component usage analytics
+
+## Resources
+
+### Documentation Files:
+1. **ATOMIC_COMPONENTS.md** - Complete atomic design guide
+   - Concept explanation
+   - Component hierarchy rules
+   - Naming conventions
+   - Best practices
+   - Migration guide
+
+2. **COMPONENT_MAP.md** - Visual dependency maps
+   - Component composition diagrams
+   - Import graphs
+   - Data flow examples
+   - Styling patterns
+
+3. **ATOMIC_USAGE_EXAMPLES.md** - Practical examples
+   - 10+ usage examples
+   - Code templates
+   - Testing patterns
+   - Migration checklists
+
+### Quick Links:
+- Atomic Design Methodology: https://atomicdesign.bradfrost.com/
+- Component-Driven Development: https://www.componentdriven.org/
+- React Component Patterns: https://reactpatterns.com/
+
+## Questions?
+
+### How do I know which level to use?
+- Can't be broken down? → Atom
+- Combines 2-5 atoms? → Molecule
+- Complex with state? → Organism
+- Feature-specific? → Feature component
+
+### Can I mix levels?
+- ✅ Organisms can use molecules and atoms
+- ✅ Molecules can use atoms
+- ❌ Atoms should not use molecules/organisms
+
+### What about shared utilities?
+- Put in `/lib` or `/hooks` as before
+- Not part of atomic hierarchy
+- Focus atomic structure on UI components
+
+### How do I add a new component?
+1. Determine appropriate level
+2. Create component file
+3. Add to level's `index.ts`
+4. Import and use
+
+## Feedback
+
+For questions, suggestions, or issues with the atomic structure:
+1. Check documentation files
+2. Review existing component examples
+3. Consult component map for patterns
+4. Follow established conventions
+
+---
+
+**Status**: ✅ Initial refactor complete
+**Last Updated**: January 2025
+**Next Review**: After Phase 2 completion

docs/architecture/atomic/ATOMIC_USAGE_EXAMPLES.md

@@ -0,0 +1,462 @@
+# Atomic Component Usage Examples
+
+This document provides practical examples of using the atomic component library.
+
+## Example 1: Creating a New Feature Header
+
+```tsx
+import { PageHeaderContent } from '@/components/molecules'
+import { Code } from '@phosphor-icons/react'
+
+export function MyFeatureHeader() {
+  return (
+    <div className="border-b border-border bg-card px-4 sm:px-6 py-3 sm:py-4">
+      <PageHeaderContent
+        title="My Feature"
+        icon={<Code size={24} weight="duotone" />}
+        description="Feature description here"
+      />
+    </div>
+  )
+}
+```
+
+## Example 2: Creating a Toolbar with Actions
+
+```tsx
+import { ToolbarButton } from '@/components/molecules'
+import { Plus, Download, Sparkle } from '@phosphor-icons/react'
+
+export function MyToolbar() {
+  return (
+    <div className="flex gap-2">
+      <ToolbarButton
+        icon={<Plus size={18} />}
+        label="Add Item"
+        onClick={() => console.log('Add')}
+      />
+      <ToolbarButton
+        icon={<Download size={18} />}
+        label="Export"
+        onClick={() => console.log('Export')}
+        variant="default"
+      />
+      <ToolbarButton
+        icon={<Sparkle size={18} weight="duotone" />}
+        label="AI Generate"
+        onClick={() => console.log('AI')}
+      />
+    </div>
+  )
+}
+```
+
+## Example 3: Empty State with Action
+
+```tsx
+import { EmptyState } from '@/components/molecules'
+import { Button } from '@/components/ui/button'
+import { FileCode } from '@phosphor-icons/react'
+
+export function NoFilesView() {
+  return (
+    <EmptyState
+      icon={<FileCode size={32} />}
+      title="No files yet"
+      description="Create your first file to get started with your project"
+      action={
+        <Button onClick={() => console.log('Create')}>
+          <Plus size={16} className="mr-2" />
+          Create File
+        </Button>
+      }
+    />
+  )
+}
+```
+
+## Example 4: Loading State
+
+```tsx
+import { LoadingState } from '@/components/molecules'
+
+export function LoadingFiles() {
+  return <LoadingState message="Loading files..." size="lg" />
+}
+```
+
+## Example 5: Statistics Dashboard
+
+```tsx
+import { StatCard } from '@/components/molecules'
+import { Code, Database, Tree } from '@phosphor-icons/react'
+
+export function ProjectStats({ fileCount, modelCount, componentCount }) {
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+      <StatCard
+        icon={<Code size={24} />}
+        label="Files"
+        value={fileCount}
+      />
+      <StatCard
+        icon={<Database size={24} />}
+        label="Models"
+        value={modelCount}
+        variant="primary"
+      />
+      <StatCard
+        icon={<Tree size={24} />}
+        label="Components"
+        value={componentCount}
+      />
+    </div>
+  )
+}
+```
+
+## Example 6: Custom Navigation Group
+
+```tsx
+import { NavigationItem } from '@/components/molecules'
+import { Code, Database, Tree } from '@phosphor-icons/react'
+
+export function MyNavigationSection({ activeTab, onNavigate }) {
+  const items = [
+    { id: 'code', label: 'Code', icon: <Code size={18} />, value: 'code' },
+    { id: 'models', label: 'Models', icon: <Database size={18} />, value: 'models', badge: 5 },
+    { id: 'components', label: 'Components', icon: <Tree size={18} />, value: 'components' },
+  ]
+
+  return (
+    <div className="space-y-1">
+      {items.map((item) => (
+        <NavigationItem
+          key={item.id}
+          icon={item.icon}
+          label={item.label}
+          isActive={activeTab === item.value}
+          badge={item.badge}
+          onClick={() => onNavigate(item.value)}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+## Example 7: Using Atoms Directly
+
+```tsx
+import { StatusIcon, ErrorBadge, LoadingSpinner } from '@/components/atoms'
+
+export function StatusIndicators({ isSaved, errorCount, isLoading }) {
+  return (
+    <div className="flex items-center gap-3">
+      {isLoading && <LoadingSpinner size="sm" />}
+      {isSaved && <StatusIcon type="saved" animate />}
+      {errorCount > 0 && (
+        <div className="relative">
+          <span>Errors</span>
+          <ErrorBadge count={errorCount} />
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+## Example 8: Building a Custom Molecule
+
+```tsx
+// Create: src/components/molecules/FeatureCard.tsx
+import { Card } from '@/components/ui/card'
+import { IconWrapper } from '@/components/atoms'
+import { Button } from '@/components/ui/button'
+
+interface FeatureCardProps {
+  icon: React.ReactNode
+  title: string
+  description: string
+  enabled: boolean
+  onToggle: () => void
+}
+
+export function FeatureCard({
+  icon,
+  title,
+  description,
+  enabled,
+  onToggle,
+}: FeatureCardProps) {
+  return (
+    <Card className="p-4">
+      <div className="flex items-start gap-3">
+        <IconWrapper icon={icon} size="lg" variant="primary" />
+        <div className="flex-1">
+          <h3 className="font-semibold">{title}</h3>
+          <p className="text-sm text-muted-foreground mt-1">{description}</p>
+          <Button
+            size="sm"
+            variant={enabled ? 'outline' : 'default'}
+            onClick={onToggle}
+            className="mt-3"
+          >
+            {enabled ? 'Disable' : 'Enable'}
+          </Button>
+        </div>
+      </div>
+    </Card>
+  )
+}
+```
+
+## Example 9: Building a Custom Organism
+
+```tsx
+// Create: src/components/organisms/FeatureGrid.tsx
+import { FeatureCard } from '@/components/molecules/FeatureCard'
+import { ScrollArea } from '@/components/ui/scroll-area'
+
+interface Feature {
+  id: string
+  icon: React.ReactNode
+  title: string
+  description: string
+  enabled: boolean
+}
+
+interface FeatureGridProps {
+  features: Feature[]
+  onToggle: (featureId: string) => void
+}
+
+export function FeatureGrid({ features, onToggle }: FeatureGridProps) {
+  return (
+    <ScrollArea className="h-full">
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 p-6">
+        {features.map((feature) => (
+          <FeatureCard
+            key={feature.id}
+            icon={feature.icon}
+            title={feature.title}
+            description={feature.description}
+            enabled={feature.enabled}
+            onToggle={() => onToggle(feature.id)}
+          />
+        ))}
+      </div>
+    </ScrollArea>
+  )
+}
+```
+
+## Example 10: Responsive Component Pattern
+
+```tsx
+import { AppBranding, SaveIndicator } from '@/components/molecules'
+import { ToolbarButton } from '@/components/molecules'
+import { useIsMobile } from '@/hooks/use-mobile'
+import { Menu, Search } from '@phosphor-icons/react'
+
+export function ResponsiveHeader({ lastSaved, onSearch, onMenu }) {
+  const isMobile = useIsMobile()
+
+  return (
+    <header className="border-b border-border bg-card px-4 py-3">
+      <div className="flex items-center justify-between gap-3">
+        {isMobile ? (
+          <>
+            <ToolbarButton
+              icon={<Menu size={20} />}
+              label="Menu"
+              onClick={onMenu}
+            />
+            <AppBranding title="CodeForge" />
+            <ToolbarButton
+              icon={<Search size={18} />}
+              label="Search"
+              onClick={onSearch}
+            />
+          </>
+        ) : (
+          <>
+            <AppBranding title="CodeForge" subtitle="Low-Code Builder" />
+            <SaveIndicator lastSaved={lastSaved} />
+            <ToolbarButton
+              icon={<Search size={18} />}
+              label="Search (Ctrl+K)"
+              onClick={onSearch}
+            />
+          </>
+        )}
+      </div>
+    </header>
+  )
+}
+```
+
+## Best Practices Summary
+
+### ✅ DO:
+- Use atoms for single-purpose UI elements
+- Compose molecules from atoms
+- Build organisms from molecules and atoms
+- Keep feature components for complex, domain-specific logic
+- Export all components from index files
+- Use TypeScript interfaces for all props
+- Add descriptive comments to complex compositions
+
+### ❌ DON'T:
+- Import organisms in atoms
+- Import molecules in atoms
+- Duplicate atom functionality
+- Mix business logic into atoms or molecules
+- Skip TypeScript types
+- Create "god components" that do everything
+
+## Migration Checklist
+
+When refactoring an existing component:
+
+1. ☐ Identify reusable parts
+2. ☐ Extract atoms (icons, badges, wrappers)
+3. ☐ Create molecules (combinations of atoms)
+4. ☐ Build organisms (complex compositions)
+5. ☐ Update imports in parent components
+6. ☐ Add to appropriate index.ts file
+7. ☐ Update documentation
+8. ☐ Test thoroughly
+
+## Quick Start Template
+
+```tsx
+// 1. Create your atom
+// src/components/atoms/MyAtom.tsx
+export function MyAtom({ value }: { value: string }) {
+  return <span>{value}</span>
+}
+
+// 2. Update atoms/index.ts
+export { MyAtom } from './MyAtom'
+
+// 3. Create your molecule
+// src/components/molecules/MyMolecule.tsx
+import { MyAtom } from '@/components/atoms'
+
+export function MyMolecule({ label, value }) {
+  return (
+    <div>
+      <MyAtom value={label} />
+      <MyAtom value={value} />
+    </div>
+  )
+}
+
+// 4. Update molecules/index.ts
+export { MyMolecule } from './MyMolecule'
+
+// 5. Use in your feature
+import { MyMolecule } from '@/components/molecules'
+
+export function MyFeature() {
+  return <MyMolecule label="Count" value="42" />
+}
+```
+
+## Component Storybook Template
+
+```tsx
+// Create: src/components/atoms/MyAtom.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { MyAtom } from './MyAtom'
+
+const meta: Meta<typeof MyAtom> = {
+  title: 'Atoms/MyAtom',
+  component: MyAtom,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof MyAtom>
+
+export const Default: Story = {
+  args: {
+    value: 'Hello World',
+  },
+}
+
+export const LongText: Story = {
+  args: {
+    value: 'This is a much longer piece of text to test wrapping',
+  },
+}
+```
+
+## Testing Template
+
+```tsx
+// Create: src/components/atoms/__tests__/MyAtom.test.tsx
+import { render, screen } from '@testing-library/react'
+import { MyAtom } from '../MyAtom'
+
+describe('MyAtom', () => {
+  it('renders the value', () => {
+    render(<MyAtom value="test" />)
+    expect(screen.getByText('test')).toBeInTheDocument()
+  })
+
+  it('handles empty value', () => {
+    render(<MyAtom value="" />)
+    expect(screen.queryByText(/./)).not.toBeInTheDocument()
+  })
+})
+```
+
+## TypeScript Patterns
+
+```tsx
+// Atom props - simple and focused
+interface AtomProps {
+  value: string
+  variant?: 'default' | 'primary'
+  size?: 'sm' | 'md' | 'lg'
+}
+
+// Molecule props - combination of atoms
+interface MoleculeProps {
+  icon: React.ReactNode
+  label: string
+  value: string | number
+  onClick?: () => void
+}
+
+// Organism props - complex with callbacks
+interface OrganismProps {
+  items: Item[]
+  activeId: string | null
+  onItemSelect: (id: string) => void
+  onItemDelete: (id: string) => void
+  onItemCreate: () => void
+}
+```
+
+## Performance Tips
+
+```tsx
+// Memoize expensive computations in molecules/organisms
+const sortedItems = useMemo(
+  () => items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+)
+
+// Memoize callback functions
+const handleClick = useCallback(() => {
+  onItemSelect(item.id)
+}, [item.id, onItemSelect])
+
+// Use React.memo for expensive renders
+export const ExpensiveMolecule = memo(function ExpensiveMolecule(props) {
+  // Complex rendering logic
+})
+```

docs/architecture/atomic/ATOMIC_VISUAL_OVERVIEW.md

@@ -0,0 +1,419 @@
+# Atomic Component Library - Visual Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CODEFORGE APPLICATION                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │
+        ┌─────────────────────┴─────────────────────┐
+        │                                           │
+        ▼                                           ▼
+┌───────────────┐                          ┌────────────────┐
+│  APP HEADER   │                          │  FEATURE PAGES │
+│  (Organism)   │                          │   (Features)   │
+└───────────────┘                          └────────────────┘
+        │                                           │
+        │                                           │
+   ┌────┴────┬─────────────┬────────────┐         │
+   │         │             │            │          │
+   ▼         ▼             ▼            ▼          ▼
+┌─────┐ ┌────────┐  ┌──────────┐  ┌────────┐  ┌────────────┐
+│ Nav │ │ Brand  │  │   Save   │  │Toolbar │  │  CodeEdit  │
+│Menu │ │  ing   │  │Indicator │  │Actions │  │ModelDesign │
+│     │ │        │  │          │  │        │  │WorkflowDes │
+└─────┘ └────────┘  └──────────┘  └────────┘  │   etc.     │
+   │         │             │            │       └────────────┘
+   │         │             │            │
+   └─────────┴─────────────┴────────────┘
+                    │
+         ┌──────────┴──────────┐
+         │                     │
+         ▼                     ▼
+   ┌──────────┐         ┌────────────┐
+   │MOLECULES │         │  ORGANISMS │
+   │  (10)    │────────▶│    (4)     │
+   └──────────┘         └────────────┘
+         │
+         │
+         ▼
+   ┌──────────┐
+   │  ATOMS   │
+   │   (7)    │
+   └──────────┘
+         │
+         │
+         ▼
+   ┌──────────┐
+   │ SHADCN   │
+   │   UI     │
+   └──────────┘
+```
+
+## Component Flow Diagram
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                        App.tsx                              │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │              AppHeader (Organism)                   │   │
+│  │  ┌────────────────────────────────────────────┐    │   │
+│  │  │  NavigationMenu (Organism)                 │    │   │
+│  │  │    • NavigationGroupHeader (Molecule)      │    │   │
+│  │  │    • NavigationItem (Molecule)             │    │   │
+│  │  │      └─ ErrorBadge (Atom)                  │    │   │
+│  │  ├────────────────────────────────────────────┤    │   │
+│  │  │  AppBranding (Molecule)                    │    │   │
+│  │  │    • AppLogo (Atom)                        │    │   │
+│  │  │    • Title + Subtitle text                 │    │   │
+│  │  ├────────────────────────────────────────────┤    │   │
+│  │  │  SaveIndicator (Molecule)                  │    │   │
+│  │  │    • StatusIcon (Atom)                     │    │   │
+│  │  │    • Time text                             │    │   │
+│  │  ├────────────────────────────────────────────┤    │   │
+│  │  │  ToolbarActions (Organism)                 │    │   │
+│  │  │    • ToolbarButton (Molecule) × 5          │    │   │
+│  │  └────────────────────────────────────────────┘    │   │
+│  └────────────────────────────────────────────────────┘   │
+│                                                            │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │              PageHeader (Organism)                  │   │
+│  │  ┌────────────────────────────────────────────┐    │   │
+│  │  │  PageHeaderContent (Molecule)              │    │   │
+│  │  │    • TabIcon (Atom)                        │    │   │
+│  │  │    • Title + Description text              │    │   │
+│  │  └────────────────────────────────────────────┘    │   │
+│  └────────────────────────────────────────────────────┘   │
+│                                                            │
+│  ┌────────────────────────────────────────────────────┐   │
+│  │         Feature Components (20+)                    │   │
+│  │    CodeEditor, ModelDesigner, ProjectDashboard...   │   │
+│  └────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow: Save Action
+
+```
+User types in editor
+         │
+         ▼
+  [useKV hook updates]
+         │
+         ▼
+   setLastSaved(Date.now())
+         │
+         ▼
+  AppHeader receives new lastSaved prop
+         │
+         ▼
+  SaveIndicator (Molecule) calculates:
+    isRecent = (now - lastSaved < 3000)
+         │
+         ▼
+  StatusIcon (Atom) renders:
+    isRecent ? CheckCircle : CloudCheck
+         │
+         ▼
+  User sees "Saved" with animation
+```
+
+## Import Dependency Graph
+
+```
+                    App.tsx
+                      │
+        ┌─────────────┼─────────────┐
+        │             │             │
+        ▼             ▼             ▼
+   Organisms     Molecules       Atoms
+        │             │             │
+        │       ┌─────┘             │
+        │       │                   │
+        ▼       ▼                   ▼
+   Molecules  Atoms            shadcn UI
+        │       │
+        │       │
+        ▼       ▼
+      Atoms  shadcn UI
+        │
+        │
+        ▼
+   shadcn UI
+```
+
+## Component Size Comparison
+
+```
+Atoms (7 components)
+████ 2KB
+Small, focused, single-purpose
+
+Molecules (10 components)
+████████ 8KB
+Moderate, composed, reusable
+
+Organisms (4 components)
+████████████ 12KB
+Large, complex, coordinating
+
+Features (20+ components)
+████████████████████████████████ 100KB+
+Very large, feature-complete, domain-specific
+```
+
+## Atomic Design Benefits
+
+```
+┌────────────────────────────────────────────────────────┐
+│                    BENEFITS                            │
+├────────────────────────────────────────────────────────┤
+│                                                        │
+│  Reusability        ████████████░ 90%                 │
+│  Atoms/molecules used everywhere                      │
+│                                                        │
+│  Maintainability    ████████████░ 85%                 │
+│  Changes propagate naturally                          │
+│                                                        │
+│  Testability        ████████████░ 95%                 │
+│  Small units = easy tests                             │
+│                                                        │
+│  Consistency        ████████████░ 90%                 │
+│  Shared atoms = uniform UI                            │
+│                                                        │
+│  Scalability        ████████████░ 85%                 │
+│  Clear patterns for growth                            │
+│                                                        │
+│  Onboarding         ████████████░ 80%                 │
+│  Self-documenting structure                           │
+│                                                        │
+└────────────────────────────────────────────────────────┘
+```
+
+## Component Complexity Matrix
+
+```
+                    │
+         Complex    │              ┌──────────────┐
+                    │              │   Features   │
+                    │              │   (20+)      │
+                    │              └──────────────┘
+                    │
+                    │      ┌───────────┐
+         Medium     │      │ Organisms │
+                    │      │    (4)    │
+                    │      └───────────┘
+                    │
+                    │  ┌──────────┐
+         Simple     │  │Molecules │
+                    │  │   (10)   │
+                    │  └──────────┘
+                    │
+         Basic      │ ┌─────┐
+                    │ │Atoms│
+                    │ │ (7) │
+                    │ └─────┘
+                    └──────────────────────────────────
+                    Few           Many
+                       Components Used
+```
+
+## File Structure Tree
+
+```
+src/
+├── components/
+│   ├── atoms/                  ← 7 building blocks
+│   │   ├── AppLogo.tsx         
+│   │   ├── TabIcon.tsx
+│   │   ├── StatusIcon.tsx
+│   │   ├── ErrorBadge.tsx
+│   │   ├── IconWrapper.tsx
+│   │   ├── LoadingSpinner.tsx
+│   │   ├── EmptyStateIcon.tsx
+│   │   └── index.ts            ← Exports all atoms
+│   │
+│   ├── molecules/              ← 10 combinations
+│   │   ├── SaveIndicator.tsx
+│   │   ├── AppBranding.tsx
+│   │   ├── PageHeaderContent.tsx
+│   │   ├── ToolbarButton.tsx
+│   │   ├── NavigationItem.tsx
+│   │   ├── NavigationGroupHeader.tsx
+│   │   ├── EmptyState.tsx
+│   │   ├── LoadingState.tsx
+│   │   ├── StatCard.tsx
+│   │   ├── LabelWithBadge.tsx
+│   │   └── index.ts            ← Exports all molecules
+│   │
+│   ├── organisms/              ← 4 complex components
+│   │   ├── NavigationMenu.tsx
+│   │   ├── PageHeader.tsx
+│   │   ├── ToolbarActions.tsx
+│   │   ├── AppHeader.tsx
+│   │   └── index.ts            ← Exports all organisms
+│   │
+│   ├── ui/                     ← shadcn components (40+)
+│   │   ├── button.tsx
+│   │   ├── card.tsx
+│   │   ├── dialog.tsx
+│   │   └── ...
+│   │
+│   ├── CodeEditor.tsx          ← Feature components
+│   ├── ModelDesigner.tsx
+│   ├── ProjectDashboard.tsx
+│   └── ...
+│
+├── lib/
+│   ├── navigation-config.tsx   ← Centralized config
+│   ├── utils.ts
+│   └── ...
+│
+└── App.tsx                     ← Main app using organisms
+```
+
+## Usage Pattern Evolution
+
+### Before (Monolithic):
+```typescript
+// App.tsx (500+ lines with inline UI)
+<header className="...">
+  <div className="logo">
+    <Code size={20} /> CodeForge
+  </div>
+  <div>
+    {lastSaved ? (
+      <CheckCircle />
+    ) : (
+      <CloudCheck />
+    )}
+    {timeAgo}
+  </div>
+  <Button onClick={handleExport}>
+    <Download /> Export
+  </Button>
+</header>
+```
+
+### After (Atomic):
+```typescript
+// App.tsx (cleaner with composed organisms)
+<AppHeader
+  lastSaved={lastSaved}
+  onExport={handleExport}
+  {...props}
+/>
+
+// AppHeader.tsx
+<header>
+  <AppBranding />
+  <SaveIndicator lastSaved={lastSaved} />
+  <ToolbarActions onExport={onExport} />
+</header>
+
+// SaveIndicator.tsx
+<div>
+  <StatusIcon type={isRecent ? 'saved' : 'synced'} />
+  <span>{timeAgo}</span>
+</div>
+```
+
+## Testing Pyramid
+
+```
+                /\
+               /  \
+              /E2E \           4 organisms
+             /------\          10 tests
+            /        \         
+           / Integr.  \        10 molecules
+          /------------\       30 tests
+         /              \
+        /      Unit      \     7 atoms
+       /------------------\    70 tests
+      /                    \
+     /    shadcn (tested)   \  40+ components
+    /------------------------\  (pre-tested)
+```
+
+## Performance Strategy
+
+```
+Atoms          →  No memo (too small, pure)
+Molecules      →  Memo if props are complex
+Organisms      →  Always memo (complex state)
+Features       →  Memo + lazy load
+
+Code Splitting:
+├── atoms.chunk.js      (2KB - always loaded)
+├── molecules.chunk.js  (8KB - always loaded)
+├── organisms.chunk.js  (12KB - always loaded)
+└── features.*.js       (100KB+ - lazy loaded)
+```
+
+## Maintenance Workflow
+
+```
+┌─────────────────┐
+│ Identify Pattern│
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Extract to Atom │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Compose Molecule│
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│Build Organism   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Use in Feature  │
+└─────────────────┘
+```
+
+## Documentation Map
+
+```
+ATOMIC_README.md             ← Start here! Quick overview
+     │
+     ├─→ ATOMIC_REFACTOR_SUMMARY.md    (What changed)
+     │
+     ├─→ ATOMIC_COMPONENTS.md           (Complete guide)
+     │       │
+     │       ├─→ Concept explanation
+     │       ├─→ Component levels
+     │       ├─→ Rules & conventions
+     │       ├─→ Best practices
+     │       └─→ Migration guide
+     │
+     ├─→ ATOMIC_USAGE_EXAMPLES.md       (Code examples)
+     │       │
+     │       ├─→ 10+ real examples
+     │       ├─→ Templates
+     │       ├─→ Testing patterns
+     │       └─→ Quick start
+     │
+     └─→ COMPONENT_MAP.md                (Visual maps)
+             │
+             ├─→ Dependency diagrams
+             ├─→ Data flow
+             ├─→ Styling patterns
+             └─→ Performance tips
+```
+
+---
+
+**Legend:**
+- 🔵 Atoms = Basic building blocks (7)
+- 🟢 Molecules = Simple combinations (10)
+- 🟡 Organisms = Complex components (4)
+- 🔴 Features = Domain-specific (20+)
+- ⚪ shadcn = Base UI library (40+)

docs/architecture/atomic/COMPONENT_MAP.md

@@ -0,0 +1,331 @@
+# Component Dependency Map
+
+This document visualizes how components are composed in the atomic structure.
+
+## App Header Composition
+
+```
+AppHeader (organism)
+├── NavigationMenu (organism)
+│   ├── Sheet (shadcn)
+│   ├── NavigationGroupHeader (molecule)
+│   │   └── CaretDown icon
+│   └── NavigationItem (molecule)
+│       ├── Icon
+│       ├── Label
+│       └── Badge (shadcn)
+├── AppBranding (molecule)
+│   ├── AppLogo (atom)
+│   │   └── Code icon
+│   └── Title + Subtitle text
+├── SaveIndicator (molecule)
+│   ├── StatusIcon (atom)
+│   │   ├── CheckCircle icon (saved)
+│   │   └── CloudCheck icon (synced)
+│   └── Time text
+├── ProjectManager (feature)
+└── ToolbarActions (organism)
+    └── ToolbarButton (molecule) × 5
+        ├── Button (shadcn)
+        └── Tooltip (shadcn)
+```
+
+## Page Header Composition
+
+```
+PageHeader (organism)
+└── PageHeaderContent (molecule)
+    ├── TabIcon (atom)
+    │   └── Icon with gradient wrapper
+    ├── Title text
+    └── Description text
+```
+
+## Navigation Menu Composition
+
+```
+NavigationMenu (organism)
+├── Sheet (shadcn)
+│   ├── SheetTrigger
+│   │   └── Button with List icon
+│   └── SheetContent
+│       ├── SheetHeader with title
+│       ├── Expand/Collapse buttons
+│       └── ScrollArea (shadcn)
+│           └── Collapsible (shadcn) × N groups
+│               ├── NavigationGroupHeader (molecule)
+│               │   ├── CaretDown icon
+│               │   ├── Group label
+│               │   └── Item count
+│               └── CollapsibleContent
+│                   └── NavigationItem (molecule) × N
+│                       ├── Icon
+│                       ├── Label
+│                       └── Badge (optional)
+```
+
+## Feature Component Examples
+
+### Dashboard Stats Grid
+```
+ProjectDashboard (feature)
+└── Grid of StatCard (molecule) × N
+    ├── IconWrapper (atom)
+    │   └── Feature icon
+    ├── Label text
+    └── Value text
+```
+
+### Empty States
+```
+EmptyState (molecule)
+├── EmptyStateIcon (atom)
+│   └── Icon with gradient background
+├── Title text
+├── Description text
+└── Action button (optional)
+```
+
+### Loading States
+```
+LoadingState (molecule)
+├── LoadingSpinner (atom)
+│   └── Animated spinner
+└── Message text
+```
+
+## Component Import Graph
+
+```
+App.tsx
+├── imports organisms
+│   ├── AppHeader
+│   │   ├── imports molecules
+│   │   │   ├── AppBranding
+│   │   │   ├── SaveIndicator
+│   │   │   └── ToolbarButton
+│   │   └── imports atoms
+│   │       ├── AppLogo
+│   │       ├── StatusIcon
+│   │       └── ErrorBadge
+│   ├── PageHeader
+│   │   └── imports molecules
+│   │       └── PageHeaderContent
+│   │           └── imports atoms
+│   │               └── TabIcon
+│   └── NavigationMenu
+│       ├── imports molecules
+│       │   ├── NavigationGroupHeader
+│       │   └── NavigationItem
+│       └── imports config
+│           └── navigation-config.tsx
+└── imports features
+    ├── CodeEditor
+    ├── ModelDesigner
+    ├── ProjectDashboard
+    └── ... (more features)
+```
+
+## Atomic Levels Quick Reference
+
+### Level 1: Atoms (7 components)
+- `AppLogo` - Application logo icon
+- `TabIcon` - Icon with styling variants
+- `StatusIcon` - Status indicator (saved/synced)
+- `ErrorBadge` - Badge showing error count
+- `IconWrapper` - Styled icon wrapper
+- `LoadingSpinner` - Animated loading spinner
+- `EmptyStateIcon` - Large icon for empty states
+
+### Level 2: Molecules (10 components)
+- `SaveIndicator` - Shows save status with time
+- `AppBranding` - Logo + app name + tagline
+- `PageHeaderContent` - Page title with icon and description
+- `ToolbarButton` - Button with tooltip
+- `NavigationItem` - Navigation link with badge
+- `NavigationGroupHeader` - Collapsible group header
+- `EmptyState` - Empty state with icon, title, description
+- `LoadingState` - Loading indicator with message
+- `StatCard` - Statistic card with icon and value
+- `LabelWithBadge` - Label with optional badge
+
+### Level 3: Organisms (4 components)
+- `NavigationMenu` - Complete navigation sidebar
+- `PageHeader` - Page header with context
+- `ToolbarActions` - Toolbar with multiple buttons
+- `AppHeader` - Complete application header
+
+### Level 4: Features (20+ components)
+See `/components` directory for full list of feature components.
+
+## Data Flow Example: Save Indicator
+
+```
+User makes change
+    ↓
+App.tsx updates KV store
+    ↓
+setLastSaved(Date.now())
+    ↓
+AppHeader receives lastSaved prop
+    ↓
+SaveIndicator (molecule) receives lastSaved
+    ↓
+Calculates isRecent = (now - lastSaved < 3s)
+    ↓
+Renders StatusIcon (atom) with type based on isRecent
+    ↓
+StatusIcon renders CheckCircle (recent) or CloudCheck (older)
+```
+
+## Styling Patterns
+
+### Gradients
+```css
+/* Used in: AppLogo, TabIcon, EmptyStateIcon */
+.gradient {
+  @apply bg-gradient-to-br from-primary to-accent;
+}
+
+.gradient-muted {
+  @apply bg-gradient-to-br from-muted to-muted/50;
+}
+
+.gradient-subtle {
+  @apply bg-gradient-to-br from-primary/20 to-accent/20;
+}
+```
+
+### Responsive Sizing
+```css
+/* Mobile-first approach used throughout */
+.text-base sm:text-xl     /* Headings scale up on larger screens */
+.w-8 sm:w-10              /* Icons grow on larger screens */
+.gap-2 sm:gap-3           /* Spacing increases on larger screens */
+.hidden sm:block          /* Show on larger screens only */
+.hidden sm:flex           /* Show as flex on larger screens */
+```
+
+### Icon Sizes
+```tsx
+// Consistent icon sizing across components
+<Icon size={14} />  // Badges, small UI elements
+<Icon size={16} />  // Toolbar buttons, navigation items
+<Icon size={18} />  // Standard buttons
+<Icon size={20} />  // Logo, prominent buttons
+<Icon size={24} />  // Page headers
+```
+
+## Testing Strategy
+
+### Unit Tests (Atoms)
+Test individual atoms in isolation:
+```typescript
+describe('StatusIcon', () => {
+  it('renders CheckCircle when type is saved', () => {
+    render(<StatusIcon type="saved" />)
+    expect(screen.getByTestId('check-circle')).toBeInTheDocument()
+  })
+})
+```
+
+### Integration Tests (Molecules)
+Test molecule composition:
+```typescript
+describe('SaveIndicator', () => {
+  it('shows "Saved" text when recently saved', () => {
+    const lastSaved = Date.now() - 1000
+    render(<SaveIndicator lastSaved={lastSaved} />)
+    expect(screen.getByText('Saved')).toBeInTheDocument()
+  })
+})
+```
+
+### E2E Tests (Organisms)
+Test complete user flows:
+```typescript
+describe('NavigationMenu', () => {
+  it('navigates to code editor when item clicked', () => {
+    render(<NavigationMenu {...props} />)
+    userEvent.click(screen.getByText('Code Editor'))
+    expect(onTabChange).toHaveBeenCalledWith('code')
+  })
+})
+```
+
+## Performance Considerations
+
+### Memoization Strategy
+```typescript
+// Atoms: Usually pure, no memo needed
+export function AppLogo() { ... }
+
+// Molecules: Memo when props are complex
+export const SaveIndicator = memo(({ lastSaved }) => { ... })
+
+// Organisms: Always memo to prevent re-renders
+export const NavigationMenu = memo(({ activeTab, ... }) => { ... })
+```
+
+### Code Splitting
+```typescript
+// Feature components are lazy-loaded
+const CodeEditor = lazy(() => import('@/components/CodeEditor'))
+const ModelDesigner = lazy(() => import('@/components/ModelDesigner'))
+
+// Atoms and molecules are NOT lazy-loaded (too small, used everywhere)
+```
+
+## Accessibility Patterns
+
+### Keyboard Navigation
+```tsx
+// All interactive elements support keyboard
+<button 
+  onClick={handleClick}
+  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
+  aria-label="Descriptive label"
+>
+```
+
+### Screen Reader Support
+```tsx
+// Icons have descriptive labels
+<Icon aria-label="Loading" />
+
+// Loading states announce
+<div role="status" aria-live="polite">Loading...</div>
+
+// Error badges announce count
+<Badge aria-label={`${count} errors`}>{count}</Badge>
+```
+
+### Focus Management
+```tsx
+// Dialogs trap focus
+<Dialog>...</Dialog>
+
+// Navigation preserves focus
+<Sheet>...</Sheet>
+
+// Tooltips are keyboard accessible
+<Tooltip>...</Tooltip>
+```
+
+## Future Enhancements
+
+### Potential New Atoms
+- `StatusDot` - Colored status indicator dot
+- `AvatarInitials` - User initials in circle
+- `KeyboardKey` - Styled keyboard key indicator
+
+### Potential New Molecules
+- `SearchInput` - Search input with icon and clear button
+- `FileIcon` - File type icon with extension
+- `Breadcrumbs` - Navigation breadcrumb trail
+- `ActionMenu` - Dropdown menu with actions
+
+### Potential New Organisms
+- `CommandPalette` - Full command palette interface
+- `QuickAccessToolbar` - Customizable quick actions
+- `NotificationCenter` - Notification list and management

docs/deployment/BAD_GATEWAY_FIX.md

@@ -0,0 +1,117 @@
+# Bad Gateway Errors - Fixed
+
+## Problem
+The application was experiencing masses of "Bad Gateway" (502) errors caused by excessive LLM API calls.
+
+## Root Causes Identified
+
+1. **Auto-scanning running every 2 seconds** - The `useAutoRepair` hook was automatically scanning all files for errors every 2 seconds, making continuous LLM calls
+2. **No rate limiting** - Multiple AI features (component generation, code improvement, error repair, etc.) were making unlimited concurrent LLM requests
+3. **No error circuit breaker** - Failed requests would retry immediately without backing off
+4. **No request throttling** - All AI operations competed for the same gateway resources
+
+## Solutions Implemented
+
+### 1. Rate Limiting System (`src/lib/rate-limiter.ts`)
+- **Per-category rate limiting**: Different limits for different AI operations
+- **Time windows**: Tracks requests over rolling 60-second windows
+- **Automatic cleanup**: Removes stale tracking data
+- **Priority queue support**: High-priority requests can retry with backoff
+- **Status tracking**: Monitor remaining capacity and reset times
+
+Configuration:
+- **AI Operations**: Max 3 requests per minute
+- **Error Scanning**: Max 1 request per 30 seconds
+
+### 2. Protected LLM Service (`src/lib/protected-llm-service.ts`)
+- **Error tracking**: Monitors consecutive failures
+- **Circuit breaker**: Pauses all requests after 5 consecutive errors
+- **User-friendly error messages**: Converts technical errors to actionable messages
+- **Automatic recovery**: Error count decreases on successful calls
+- **Request categorization**: Groups related operations for better rate limiting
+
+### 3. Disabled Automatic Scanning
+- **Removed automatic useEffect trigger** in `useAutoRepair`
+- **Manual scanning only**: Users must explicitly click "Scan" button
+- **Rate-limited when triggered**: Even manual scans respect rate limits
+
+### 4. Updated All AI Services
+- **ai-service.ts**: All methods now use `ProtectedLLMService`
+- **error-repair-service.ts**: Code repair uses rate limiting
+- **Consistent error handling**: All services handle 502/429 errors gracefully
+
+## Benefits
+
+1. **No more cascading failures**: Rate limiting prevents overwhelming the gateway
+2. **Better user experience**: Clear error messages explain what went wrong
+3. **Automatic recovery**: Circuit breaker allows system to recover from issues
+4. **Resource efficiency**: Prevents wasted requests that would fail anyway
+5. **Predictable behavior**: Users understand when operations might be delayed
+
+## How It Works Now
+
+### Normal Operation
+1. User triggers an AI feature (generate component, improve code, etc.)
+2. Request goes through `ProtectedLLMService`
+3. Rate limiter checks if request is allowed
+4. If allowed, request proceeds
+5. If rate-limited, user sees friendly message about slowing down
+
+### Error Handling
+1. If LLM call fails with 502/Bad Gateway:
+   - User sees: "Service temporarily unavailable - please wait a moment"
+   - Error count increases
+   - Request is blocked by rate limiter for the category
+
+2. If too many consecutive errors (5+):
+   - Circuit breaker trips
+   - All AI operations pause
+   - User sees: "AI service temporarily unavailable due to repeated errors"
+
+3. Recovery:
+   - Successful requests decrease error count
+   - After error count drops, circuit breaker resets
+   - Normal operation resumes
+
+### Manual Controls
+Users can check AI service status:
+```javascript
+const stats = ProtectedLLMService.getStats()
+// Returns: { totalCalls, errorCount, isPaused }
+```
+
+Users can manually reset if needed:
+```javascript
+ProtectedLLMService.reset()
+// Clears all rate limits and error counts
+```
+
+## Testing the Fix
+
+1. **Verify no automatic scanning**: Open the app - no LLM calls should fire automatically
+2. **Test rate limiting**: Try generating 5 components quickly - should see rate limit message
+3. **Test error recovery**: If you hit an error, next successful call should work
+4. **Check manual scan**: Error panel scan button should work with rate limiting
+
+## Monitoring
+
+Watch the browser console for:
+- `LLM call failed (category): error` - Individual failures
+- `Rate limit exceeded for llm-category` - Rate limiting in action
+- `Too many LLM errors detected` - Circuit breaker activation
+
+## Future Improvements
+
+1. **Retry queue**: Queue rate-limited requests and auto-retry
+2. **Progressive backoff**: Increase delays after repeated failures
+3. **Request deduplication**: Prevent identical simultaneous requests
+4. **Usage analytics**: Track which features use most AI calls
+5. **User quotas**: Per-user rate limiting for multi-tenant deployments
+
+## Files Modified
+
+- `/src/lib/rate-limiter.ts` (NEW)
+- `/src/lib/protected-llm-service.ts` (NEW)
+- `/src/lib/ai-service.ts` (UPDATED - now uses rate limiting)
+- `/src/lib/error-repair-service.ts` (UPDATED - now uses rate limiting)
+- `/src/hooks/use-auto-repair.ts` (UPDATED - disabled automatic scanning)

docs/deployment/CI_FIX_SUMMARY.md

@@ -0,0 +1,45 @@
+# CI/CD Fix Summary
+
+## Problem
+The CI/CD pipeline was failing during the `npm ci` step with the following error:
+
+```
+npm error Invalid: lock file's @github/spark@0.0.1 does not satisfy @github/spark@0.44.15
+npm error Missing: octokit@5.0.5 from lock file
+npm error Missing: @octokit/app@16.1.2 from lock file
+... (and many more missing dependencies)
+```
+
+## Root Cause
+The `package-lock.json` file was out of sync with `package.json`. This happened because:
+
+1. Dependencies were updated in `package.json` but the lock file wasn't regenerated
+2. The `@github/spark` workspace dependency version changed
+3. New octokit dependencies were added but not reflected in the lock file
+
+## Solution Applied
+Ran `npm install` to regenerate the `package-lock.json` file. This:
+
+- Updated the lock file to match all dependencies in `package.json`
+- Resolved all missing octokit dependencies
+- Synced the `@github/spark` workspace reference
+- Ensured `npm ci` will work correctly in CI/CD
+
+## Next Steps
+1. **Commit the updated `package-lock.json`** to your repository
+2. **Push the changes** to trigger the CI/CD pipeline again
+3. The `npm ci` command should now succeed
+
+## Prevention
+To avoid this issue in the future:
+
+- Always run `npm install` after updating `package.json`
+- Commit both `package.json` AND `package-lock.json` together
+- Use `npm ci` locally to test that the lock file is valid
+- Consider adding a pre-commit hook to validate lock file sync
+
+## CI/CD Command Explanation
+- `npm ci` (Clean Install) requires exact lock file match - used in CI/CD for reproducible builds
+- `npm install` updates the lock file if needed - used in development
+
+The CI/CD pipeline uses `npm ci` because it's faster and ensures consistent builds across environments.

docs/guides/CI_CD_GUIDE.md

@@ -0,0 +1,350 @@
+# CI/CD Configuration Guide
+
+This project includes comprehensive CI/CD configurations for multiple platforms. Choose the one that best fits your infrastructure.
+
+## Table of Contents
+
+- [GitHub Actions](#github-actions)
+- [GitLab CI](#gitlab-ci)
+- [Jenkins](#jenkins)
+- [CircleCI](#circleci)
+- [Docker Setup](#docker-setup)
+
+---
+
+## GitHub Actions
+
+### Location
+- `.github/workflows/ci.yml` - Main CI/CD pipeline
+- `.github/workflows/release.yml` - Release automation
+
+### Features
+- ✅ Lint and type checking
+- ✅ Unit and E2E tests
+- ✅ Docker build and push to GHCR
+- ✅ Security scanning with Trivy
+- ✅ Automated deployments to staging/production
+- ✅ Release creation with ZIP artifacts
+
+### Setup
+
+1. **Enable GitHub Actions** in your repository settings
+
+2. **Configure secrets** (Settings → Secrets and variables → Actions):
+   ```
+   CODECOV_TOKEN          # Optional: for code coverage reporting
+   SLACK_WEBHOOK          # Optional: for Slack notifications
+   STAGING_WEBHOOK_URL    # Webhook for staging deployment
+   PRODUCTION_WEBHOOK_URL # Webhook for production deployment
+   ```
+
+3. **Enable GitHub Packages** for Docker image storage (automatically enabled)
+
+4. **Branch Protection** (recommended):
+   - Require status checks to pass before merging
+   - Require pull request reviews
+
+### Usage
+
+- Push to `develop` → Runs tests and deploys to staging
+- Push to `main` → Runs full pipeline and deploys to production
+- Create tag `v*` → Triggers release workflow
+
+---
+
+## GitLab CI
+
+### Location
+- `.gitlab-ci.yml`
+
+### Features
+- ✅ Multi-stage pipeline with dependency caching
+- ✅ Parallel test execution
+- ✅ Docker build and push to GitLab Registry
+- ✅ Security scanning and audit reports
+- ✅ Manual approval for production deployments
+
+### Setup
+
+1. **Configure CI/CD variables** (Settings → CI/CD → Variables):
+   ```
+   STAGING_WEBHOOK_URL     # Webhook for staging deployment
+   PRODUCTION_WEBHOOK_URL  # Webhook for production deployment
+   ```
+
+2. **Enable GitLab Container Registry** (enabled by default)
+
+3. **Configure runners** with Docker executor:
+   ```toml
+   [[runners]]
+     name = "docker-runner"
+     executor = "docker"
+     [runners.docker]
+       image = "node:20-alpine"
+       privileged = true
+   ```
+
+### Usage
+
+- Pipeline runs automatically on push
+- Jobs are cached for faster execution
+- Production deployment requires manual approval
+
+---
+
+## Jenkins
+
+### Location
+- `Jenkinsfile`
+
+### Features
+- ✅ Declarative pipeline with parallel stages
+- ✅ Integration with Slack for notifications
+- ✅ Artifact archiving and HTML report publishing
+- ✅ Manual approval for production deployments
+- ✅ Automatic workspace cleanup
+
+### Setup
+
+1. **Install required plugins**:
+   - Pipeline
+   - NodeJS
+   - Docker Pipeline
+   - Slack Notification
+   - HTML Publisher
+
+2. **Configure Node.js** (Manage Jenkins → Tools):
+   - Add Node.js installation named "Node 20"
+   - Version: 20.x
+
+3. **Configure credentials**:
+   ```
+   docker-registry-credentials # Username/password for GHCR
+   ```
+
+4. **Set environment variables** in Jenkins configuration:
+   ```
+   GIT_REPO_OWNER
+   GIT_REPO_NAME
+   STAGING_WEBHOOK_URL
+   PRODUCTION_WEBHOOK_URL
+   SLACK_CHANNEL
+   ```
+
+5. **Create multibranch pipeline**:
+   - New Item → Multibranch Pipeline
+   - Add source: Git/GitHub
+   - Script Path: Jenkinsfile
+
+### Usage
+
+- Pipeline triggers on SCM changes (polling or webhooks)
+- View results in Blue Ocean interface
+- Approve production deployments manually
+
+---
+
+## CircleCI
+
+### Location
+- `.circleci/config.yml`
+
+### Features
+- ✅ Workflow orchestration with job dependencies
+- ✅ Docker layer caching for faster builds
+- ✅ Slack notifications via orb
+- ✅ Test result and artifact storage
+- ✅ Approval step for production deployments
+
+### Setup
+
+1. **Connect repository** to CircleCI
+
+2. **Configure environment variables** (Project Settings → Environment Variables):
+   ```
+   DOCKER_USERNAME           # GitHub username
+   DOCKER_PASSWORD           # GitHub personal access token
+   STAGING_WEBHOOK_URL       # Webhook for staging deployment
+   PRODUCTION_WEBHOOK_URL    # Webhook for production deployment
+   SLACK_ACCESS_TOKEN        # Optional: for Slack notifications
+   SLACK_DEFAULT_CHANNEL     # Optional: default Slack channel
+   ```
+
+3. **Enable Docker Layer Caching** (requires paid plan):
+   - Project Settings → Advanced → Enable Docker Layer Caching
+
+### Usage
+
+- Pipeline runs on every push
+- Manual approval required for production on `main` branch
+- View detailed insights in CircleCI dashboard
+
+---
+
+## Docker Setup
+
+### Files
+- `Dockerfile` - Multi-stage build for production
+- `docker-compose.yml` - Local development and deployment
+- `nginx.conf` - Nginx configuration for serving app
+- `.dockerignore` - Excludes unnecessary files
+
+### Build and Run Locally
+
+```bash
+# Build image
+docker build -t codeforge:local .
+
+# Run container
+docker run -p 3000:80 codeforge:local
+
+# Or use docker-compose
+docker-compose up -d
+```
+
+### Production Deployment
+
+The Docker image is automatically built and pushed to GHCR:
+
+```bash
+# Pull latest image
+docker pull ghcr.io/<username>/<repo>:latest
+
+# Run in production
+docker run -d \
+  -p 80:80 \
+  --name codeforge \
+  --restart unless-stopped \
+  ghcr.io/<username>/<repo>:latest
+```
+
+### Health Checks
+
+The container includes a health check endpoint at `/health`:
+
+```bash
+curl http://localhost:3000/health
+# Response: healthy
+```
+
+---
+
+## Common Configuration
+
+### Environment Variables
+
+All CI/CD platforms use these common environment variables:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `NODE_VERSION` | Node.js version | Yes (default: 20) |
+| `REGISTRY` | Docker registry URL | Yes (default: ghcr.io) |
+| `IMAGE_NAME` | Docker image name | Yes |
+| `STAGING_WEBHOOK_URL` | Staging deployment webhook | Optional |
+| `PRODUCTION_WEBHOOK_URL` | Production deployment webhook | Optional |
+| `CODECOV_TOKEN` | Codecov integration token | Optional |
+| `SLACK_WEBHOOK` | Slack webhook URL | Optional |
+
+### Branch Strategy
+
+- `main` - Production branch, deploys to production
+- `develop` - Development branch, deploys to staging
+- `feature/*` - Feature branches, runs tests only
+- `v*` tags - Triggers release creation
+
+### Pipeline Stages
+
+All pipelines follow a similar structure:
+
+1. **Lint** - ESLint and TypeScript checks
+2. **Test** - Unit tests with coverage
+3. **Build** - Application build
+4. **E2E** - Playwright end-to-end tests
+5. **Security** - npm audit and Trivy scan
+6. **Docker** - Build and push image
+7. **Deploy** - Staging (auto) and Production (manual)
+
+### Deployment Webhooks
+
+Configure deployment webhooks to integrate with your hosting platform:
+
+```bash
+# Example webhook payload
+{
+  "image": "ghcr.io/<username>/<repo>:latest",
+  "sha": "abc123",
+  "environment": "production"
+}
+```
+
+Supported platforms:
+- Vercel
+- Netlify
+- AWS ECS/EKS
+- Kubernetes
+- Custom deployment scripts
+
+---
+
+## Troubleshooting
+
+### GitHub Actions
+
+**Issue**: Docker push fails
+```bash
+Solution: Check GITHUB_TOKEN permissions in repository settings
+Settings → Actions → General → Workflow permissions → Read and write
+```
+
+### GitLab CI
+
+**Issue**: Runner fails to pull image
+```bash
+Solution: Check runner has access to Docker
+docker info  # Should work on runner
+```
+
+### Jenkins
+
+**Issue**: Pipeline hangs on input step
+```bash
+Solution: Check Jenkins has sufficient executors
+Manage Jenkins → Configure System → # of executors
+```
+
+### CircleCI
+
+**Issue**: Build fails with out of memory
+```bash
+Solution: Increase resource class in config.yml
+resource_class: large  # or xlarge
+```
+
+---
+
+## Additional Resources
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)
+- [Jenkins Pipeline Documentation](https://www.jenkins.io/doc/book/pipeline/)
+- [CircleCI Documentation](https://circleci.com/docs/)
+- [Docker Documentation](https://docs.docker.com/)
+
+---
+
+## Security Best Practices
+
+1. **Never commit secrets** to the repository
+2. **Use environment variables** for sensitive data
+3. **Enable branch protection** on main/develop branches
+4. **Require code reviews** before merging
+5. **Run security scans** in every pipeline
+6. **Keep dependencies updated** using Dependabot/Renovate
+7. **Use signed commits** for production deployments
+8. **Implement RBAC** for deployment approvals
+
+---
+
+## License
+
+This CI/CD configuration is part of CodeForge and follows the same license as the main project.

docs/guides/ERROR_REPAIR_GUIDE.md

@@ -0,0 +1,172 @@
+# Error Detection & Auto Repair Feature
+
+## Overview
+
+CodeForge includes an intelligent error detection and auto-repair system powered by AI that helps you identify and fix code issues automatically.
+
+## Features
+
+### 🔍 Error Detection
+
+The system automatically scans your code files for various types of errors:
+
+- **Syntax Errors**: Missing parentheses, unbalanced braces, malformed statements
+- **Import Errors**: Unused imports that clutter your code
+- **Type Errors**: Use of `any` types that reduce type safety
+- **Lint Errors**: Code style issues like using `var` instead of `const`/`let`
+
+### 🔧 Auto Repair Modes
+
+1. **Single Error Repair**
+   - Click the wrench icon next to any error
+   - AI fixes just that specific issue
+   - Get instant feedback with explanations
+
+2. **Batch File Repair**
+   - Repair all errors in a single file
+   - Click "Repair" button at the file level
+   - Fixes are applied all at once
+
+3. **Context-Aware Repair**
+   - Uses related files for better accuracy
+   - Understands your project structure
+   - Maintains consistency across files
+
+4. **Full Project Repair**
+   - Click "Repair All" to fix all files
+   - Processes multiple files in parallel
+   - Comprehensive project-wide fixes
+
+## How to Use
+
+### Quick Start
+
+1. Open the **Error Repair** tab in the main navigation
+2. Click **Scan** to detect errors in your project
+3. Review the detected errors grouped by file
+4. Choose your repair method:
+   - Click wrench icon for single error fix
+   - Click "Repair" for file-level fix
+   - Click "Repair All" for project-wide fix
+
+### Understanding Error Indicators
+
+- **🔴 Error Badge**: Red badge shows critical errors that break functionality
+- **⚠️ Warning Badge**: Yellow badge shows code quality issues
+- **ℹ️ Info Badge**: Blue badge shows suggestions for improvement
+
+### Error Panel Features
+
+- **Grouped by File**: Errors are organized by the file they appear in
+- **Line Numbers**: Jump directly to the problematic code
+- **Code Snippets**: View the problematic code inline
+- **Expandable Details**: Click to see more context
+- **Quick Navigation**: Click "Open" to jump to the file in the editor
+
+## Best Practices
+
+1. **Regular Scans**: Run scans periodically as you code
+2. **Review AI Fixes**: Always review what the AI changed
+3. **Test After Repair**: Verify your code still works as expected
+4. **Incremental Fixes**: Fix errors in small batches for easier verification
+
+## Error Types Explained
+
+### Syntax Errors
+```typescript
+// ❌ Before (missing parentheses)
+function calculate { return 5 }
+
+// ✅ After
+function calculate() { return 5 }
+```
+
+### Import Errors
+```typescript
+// ❌ Before (unused import)
+import { useState, useEffect, useMemo } from 'react'
+// Only useState is used
+
+// ✅ After
+import { useState } from 'react'
+```
+
+### Type Errors
+```typescript
+// ❌ Before (any type)
+function process(data: any) { }
+
+// ✅ After
+function process(data: string | number) { }
+```
+
+### Lint Errors
+```typescript
+// ❌ Before (var keyword)
+var count = 0
+
+// ✅ After
+const count = 0
+```
+
+## Tips & Tricks
+
+- **Badge Notification**: Look for the error count badge on the "Error Repair" tab
+- **Header Alert**: When errors are detected, a button appears in the header
+- **File Targeting**: Use file-level repair when errors are localized
+- **Context Matters**: Complex errors benefit from context-aware repair
+
+## Troubleshooting
+
+**Q: The scan isn't finding errors I can see**
+A: Some complex errors may require manual review. The scanner focuses on common, fixable issues.
+
+**Q: A fix didn't work as expected**
+A: You can undo changes in the editor. Try single-error repair for more control.
+
+**Q: AI repair is taking too long**
+A: Large files or complex errors may take time. Consider fixing smaller batches.
+
+**Q: Some errors remain after repair**
+A: Some errors may require manual intervention or additional context. Check the "remaining issues" explanation.
+
+## Integration with CodeForge
+
+The error repair system works seamlessly with other CodeForge features:
+
+- **Code Editor**: Jump directly from errors to code
+- **AI Generate**: AI-generated code is also scannable
+- **Export**: Ensure clean code before project export
+- **All Designers**: Errors in any file type are detected
+
+## Technical Details
+
+### Error Detection Algorithm
+
+1. **Lexical Analysis**: Tokenize source code
+2. **Pattern Matching**: Identify common error patterns
+3. **Import Analysis**: Track import usage
+4. **Type Checking**: Basic type validation for TypeScript
+
+### AI Repair Process
+
+1. **Context Gathering**: Collect error details and surrounding code
+2. **Prompt Construction**: Build repair prompt with constraints
+3. **LLM Processing**: Send to GPT-4o for intelligent fixes
+4. **Validation**: Parse and validate the response
+5. **Application**: Apply fixes to the codebase
+
+### Supported Languages
+
+- TypeScript (`.ts`, `.tsx`)
+- JavaScript (`.js`, `.jsx`)
+- CSS/SCSS (basic syntax checking)
+
+## Future Enhancements
+
+- Real-time error detection as you type
+- Custom error rules
+- Integration with ESLint
+- TypeScript compiler integration
+- Performance metrics
+- Error history tracking

docs/guides/FAVICON_DESIGNER_ACCESS.md

@@ -0,0 +1,80 @@
+# How to Access the Favicon Designer
+
+## Three Ways to Access
+
+### 1. Via Global Search (Recommended)
+1. Press `Ctrl+K` (or `Cmd+K` on Mac)
+2. Type "favicon"
+3. Click on "Favicon Designer" in the search results
+4. You'll be taken directly to the Favicon Designer page
+
+### 2. Via Navigation Menu
+1. Click the **hamburger menu icon** (☰) in the top-left corner of the app
+2. Look for the **"Design & Styling"** section
+3. Click on **"Favicon Designer"**
+4. The menu will close and you'll be on the Favicon Designer page
+
+### 3. Via Direct URL
+You can also access it by adding `?shortcut=favicon` to your URL
+
+## Troubleshooting a Blank Page
+
+If you navigate to the Favicon Designer and see a blank page, try these solutions:
+
+### Check if the Feature is Enabled
+1. Click the hamburger menu (☰) in the top-left
+2. Scroll to **"Tools & Configuration"** section
+3. Click on **"Features"**
+4. Find **"Favicon Designer"** in the list
+5. Make sure the toggle is **ON** (blue/enabled)
+6. Navigate back to the Favicon Designer
+
+### Clear Your Browser Cache
+Sometimes stale data can cause rendering issues:
+1. Press `Ctrl+Shift+Delete` (Windows/Linux) or `Cmd+Shift+Delete` (Mac)
+2. Clear cached images and files
+3. Refresh the page
+
+### Check Browser Console
+1. Press `F12` to open developer tools
+2. Click the **Console** tab
+3. Look for any red error messages
+4. If you see errors, they might indicate what's wrong
+
+## What You Should See
+
+When the Favicon Designer loads correctly, you should see:
+- **Left Panel**: A large preview canvas showing your favicon design
+- **Right Panel**: Design controls including:
+  - Design name input
+  - Canvas size selector (16px to 512px)
+  - Background color picker
+  - Add Elements buttons (Circle, Square, Triangle, Star, Heart, Polygon, Text, Emoji)
+  - Element list showing current elements
+  - Element editor when an element is selected
+- **Export Buttons**: At the bottom of the preview area for exporting PNG, SVG, or all sizes
+
+## Default Design
+
+The Favicon Designer should load with a default design showing:
+- Purple background (#7c3aed)
+- White "CF" text in the center
+- 128x128px canvas size
+
+## Still Having Issues?
+
+If none of the above solutions work:
+1. Try refreshing the page (`Ctrl+R` or `Cmd+R`)
+2. Try opening the app in an incognito/private browser window
+3. Check if other features/tabs are working properly
+4. The issue might be with browser compatibility or a temporary glitch
+
+## Feature Capabilities
+
+Once you're in the Favicon Designer, you can:
+- Create multiple favicon designs
+- Add shapes, text, and emojis
+- Adjust colors, positions, rotations, and sizes
+- Export in multiple formats (PNG, SVG, ICO)
+- Export all common sizes at once (16, 32, 48, 64, 128, 256, 512)
+- Duplicate and manage multiple designs

docs/guides/MIGRATION_GUIDE.md

@@ -0,0 +1,565 @@
+# Migration Guide: Moving to Phase 4 Architecture
+
+## 🎯 Overview
+
+This guide helps you migrate existing components to the new hook-based, JSON-driven architecture.
+
+## 🚦 Migration Strategy
+
+### Three Paths
+
+#### Path 1: Hook Extraction (Recommended First)
+**Best for:** Existing components with complex logic  
+**Time:** 1-2 hours per component  
+**Risk:** Low (backward compatible)
+
+#### Path 2: Component Split
+**Best for:** Large components (>150 LOC)  
+**Time:** 2-4 hours per component  
+**Risk:** Medium (requires refactoring)
+
+#### Path 3: JSON Conversion
+**Best for:** Simple, static pages  
+**Time:** 1-2 hours per page  
+**Risk:** Low (optional, new pattern)
+
+## 📝 Path 1: Hook Extraction
+
+### Step 1: Identify Business Logic
+
+**Before:**
+```typescript
+function UserManager() {
+  const [users, setUsers] = useKV('users', [])
+  const [searchQuery, setSearchQuery] = useState('')
+  const [selectedId, setSelectedId] = useState(null)
+  
+  const addUser = (user) => {
+    setUsers((prev) => [...prev, user])
+  }
+  
+  const deleteUser = (id) => {
+    setUsers((prev) => prev.filter(u => u.id !== id))
+  }
+  
+  const filteredUsers = users.filter(u => 
+    u.name.toLowerCase().includes(searchQuery.toLowerCase())
+  )
+  
+  return (
+    <div>
+      {/* 100+ lines of JSX */}
+    </div>
+  )
+}
+```
+
+### Step 2: Extract to Custom Hook
+
+**Create hook:**
+```typescript
+// src/hooks/features/use-user-manager.ts
+import { useArray, useSearch, useCRUD } from '@/hooks/data'
+
+export function useUserManager() {
+  const { items: users, add, remove, update } = useArray('users', [])
+  const { query, setQuery, results } = useSearch(users, ['name', 'email'])
+  const { selected, setSelectedId } = useCRUD(results, () => {})
+  
+  return {
+    users: results,
+    addUser: add,
+    deleteUser: remove,
+    updateUser: update,
+    searchQuery: query,
+    setSearchQuery: setQuery,
+    selectedUser: selected,
+    setSelectedUser: setSelectedId,
+  }
+}
+```
+
+**After:**
+```typescript
+import { useUserManager } from '@/hooks/features/use-user-manager'
+
+function UserManager() {
+  const {
+    users,
+    addUser,
+    deleteUser,
+    searchQuery,
+    setSearchQuery,
+    selectedUser,
+  } = useUserManager()
+  
+  return (
+    <div>
+      {/* Same JSX, now cleaner */}
+    </div>
+  )
+}
+```
+
+### Benefits
+✅ Logic is reusable  
+✅ Component is smaller  
+✅ Easy to test  
+✅ Better organization  
+
+## 📏 Path 2: Component Split
+
+### Step 1: Identify Sub-Components
+
+**Before (200 LOC):**
+```typescript
+function ProjectDashboard({ files, models, components }) {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <Card>
+        <CardHeader>
+          <CardTitle>Files</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {/* 30 lines */}
+        </CardContent>
+      </Card>
+      
+      <Card>
+        <CardHeader>
+          <CardTitle>Models</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {/* 30 lines */}
+        </CardContent>
+      </Card>
+      
+      <Card>
+        <CardHeader>
+          <CardTitle>Components</CardTitle>
+        </CardHeader>
+        <CardContent>
+          {/* 30 lines */}
+        </CardContent>
+      </Card>
+      
+      {/* More sections... */}
+    </div>
+  )
+}
+```
+
+### Step 2: Extract Sub-Components
+
+**Create small components:**
+```typescript
+// src/components/dashboard/StatsCard.tsx (< 50 LOC)
+interface StatsCardProps {
+  title: string
+  count: number
+  icon: React.ReactNode
+  onClick?: () => void
+}
+
+export function StatsCard({ title, count, icon, onClick }: StatsCardProps) {
+  return (
+    <Card className="cursor-pointer hover:shadow-lg" onClick={onClick}>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          {icon}
+          {title}
+        </CardTitle>
+      </CardHeader>
+      <CardContent>
+        <div className="text-4xl font-bold">{count}</div>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+**After (< 80 LOC):**
+```typescript
+import { StatsCard } from './dashboard/StatsCard'
+
+function ProjectDashboard({ files, models, components }) {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <StatsCard
+        title="Files"
+        count={files.length}
+        icon={<FileIcon />}
+        onClick={() => navigate('/files')}
+      />
+      
+      <StatsCard
+        title="Models"
+        count={models.length}
+        icon={<DatabaseIcon />}
+        onClick={() => navigate('/models')}
+      />
+      
+      <StatsCard
+        title="Components"
+        count={components.length}
+        icon={<ComponentIcon />}
+        onClick={() => navigate('/components')}
+      />
+    </div>
+  )
+}
+```
+
+### Benefits
+✅ Each component < 150 LOC  
+✅ Reusable sub-components  
+✅ Easier to understand  
+✅ Simpler to test  
+
+## 📄 Path 3: JSON Conversion
+
+### Step 1: Analyze Page Structure
+
+**Before:**
+```typescript
+function SettingsPage() {
+  const [name, setName] = useKV('app-name', '')
+  const [theme, setTheme] = useKV('app-theme', 'light')
+  
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Settings</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div>
+          <Label>App Name</Label>
+          <Input value={name} onChange={(e) => setName(e.target.value)} />
+        </div>
+        
+        <div>
+          <Label>Theme</Label>
+          <Select value={theme} onValueChange={setTheme}>
+            <SelectItem value="light">Light</SelectItem>
+            <SelectItem value="dark">Dark</SelectItem>
+          </Select>
+        </div>
+        
+        <Button onClick={() => toast.success('Saved!')}>Save</Button>
+      </CardContent>
+    </Card>
+  )
+}
+```
+
+### Step 2: Create JSON Schema
+
+**Create schema:**
+```json
+{
+  "id": "settings",
+  "name": "Settings",
+  "description": "Application settings page",
+  "layout": {
+    "type": "single"
+  },
+  "dataSources": [
+    {
+      "id": "appName",
+      "type": "kv",
+      "key": "app-name",
+      "defaultValue": ""
+    },
+    {
+      "id": "appTheme",
+      "type": "kv",
+      "key": "app-theme",
+      "defaultValue": "light"
+    }
+  ],
+  "components": [
+    {
+      "id": "root",
+      "type": "Card",
+      "children": [
+        {
+          "id": "header",
+          "type": "CardHeader",
+          "children": [
+            {
+              "id": "title",
+              "type": "CardTitle",
+              "props": {
+                "children": "Settings"
+              }
+            }
+          ]
+        },
+        {
+          "id": "content",
+          "type": "CardContent",
+          "props": {
+            "className": "space-y-4"
+          },
+          "children": [
+            {
+              "id": "name-input",
+              "type": "Input",
+              "dataBinding": "appName",
+              "props": {
+                "placeholder": "App Name"
+              }
+            },
+            {
+              "id": "save-button",
+              "type": "Button",
+              "props": {
+                "children": "Save"
+              },
+              "eventHandlers": {
+                "onClick": "save-settings"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "id": "save-settings",
+      "type": "custom",
+      "handler": "handleSave"
+    }
+  ]
+}
+```
+
+### Step 3: Use PageRenderer
+
+**After:**
+```typescript
+import { PageRenderer } from '@/config/orchestration'
+import settingsSchema from '@/config/pages/settings.json'
+import { toast } from 'sonner'
+
+function SettingsPage() {
+  const customHandlers = {
+    handleSave: () => {
+      toast.success('Settings saved!')
+    }
+  }
+  
+  return (
+    <PageRenderer
+      schema={settingsSchema}
+      customHandlers={customHandlers}
+    />
+  )
+}
+```
+
+### Benefits
+✅ No React code needed  
+✅ Easy to modify structure  
+✅ Testable schemas  
+✅ Rapid prototyping  
+
+## 🎯 Decision Matrix
+
+### When to Use Hooks
+
+| Scenario | Use Hooks? |
+|----------|-----------|
+| Complex business logic | ✅ Yes |
+| Reusable functionality | ✅ Yes |
+| API integration | ✅ Yes |
+| Form validation | ✅ Yes |
+| State management | ✅ Yes |
+
+### When to Split Components
+
+| Scenario | Split? |
+|----------|--------|
+| Component > 150 LOC | ✅ Yes |
+| Repeated UI patterns | ✅ Yes |
+| Testing complexity | ✅ Yes |
+| Hard to understand | ✅ Yes |
+
+### When to Use JSON
+
+| Scenario | Use JSON? |
+|----------|-----------|
+| Simple CRUD page | ✅ Yes |
+| Form-heavy page | ✅ Yes |
+| Dashboard/stats | ✅ Yes |
+| Static content | ✅ Yes |
+| Complex interactions | ❌ No (use hooks) |
+| Custom animations | ❌ No (use React) |
+
+## 📋 Migration Checklist
+
+### For Each Component
+
+- [ ] Measure LOC (Lines of Code)
+- [ ] If > 150 LOC, plan to split
+- [ ] Identify business logic to extract
+- [ ] Create custom hooks
+- [ ] Update component to use hooks
+- [ ] Test thoroughly
+- [ ] Consider JSON if applicable
+- [ ] Document changes
+
+### Quality Gates
+
+- [ ] All components < 150 LOC
+- [ ] Business logic in hooks
+- [ ] No duplicate code
+- [ ] Full type safety
+- [ ] Tests passing
+- [ ] Documentation updated
+
+## 🔧 Tools & Helpers
+
+### LOC Counter
+
+```bash
+# Count lines in a component
+wc -l src/components/MyComponent.tsx
+
+# Find large components
+find src/components -name "*.tsx" -exec wc -l {} \; | sort -rn | head -20
+```
+
+### Hook Template
+
+```typescript
+import { useKV } from '@github/spark/hooks'
+import { useCallback } from 'react'
+
+export function useMyFeature() {
+  const [data, setData] = useKV('my-feature-data', [])
+  
+  const operation = useCallback(() => {
+    // Logic here
+  }, [])
+  
+  return {
+    data,
+    operation,
+  }
+}
+```
+
+### JSON Schema Template
+
+```json
+{
+  "id": "my-page",
+  "name": "My Page",
+  "layout": { "type": "single" },
+  "dataSources": [],
+  "components": [],
+  "actions": []
+}
+```
+
+## 📚 Learning Resources
+
+### Read First
+1. [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) - Fast overview
+2. [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md) - Hook details
+3. [JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md) - JSON guide
+
+### Examples
+- `/src/hooks/data/` - Hook implementations
+- `/src/config/pages/` - JSON page examples
+- `/src/components/` - Component examples
+
+## 🆘 Common Issues
+
+### Issue: Hook Violation
+**Error:** "Hooks can only be called inside function components"
+
+**Solution:** Ensure hooks are called at the top level, not in loops/conditions
+
+```typescript
+// ❌ Wrong
+function MyComponent() {
+  if (condition) {
+    const data = useKV('key', []) // Hook in condition!
+  }
+}
+
+// ✅ Correct
+function MyComponent() {
+  const data = useKV('key', [])
+  if (condition) {
+    // Use data here
+  }
+}
+```
+
+### Issue: Stale Closure
+**Error:** State updates don't reflect current values
+
+**Solution:** Use functional updates
+
+```typescript
+// ❌ Wrong
+const add = () => {
+  setItems([...items, newItem]) // items is stale!
+}
+
+// ✅ Correct
+const add = () => {
+  setItems((current) => [...current, newItem])
+}
+```
+
+### Issue: JSON Not Rendering
+**Error:** Component not found in registry
+
+**Solution:** Register component in component-registry.ts
+
+```typescript
+import { MyComponent } from '@/components/MyComponent'
+
+export const ComponentRegistry = {
+  // ... other components
+  MyComponent,
+}
+```
+
+## 🎉 Success Stories
+
+### Before
+- 500 LOC component
+- Mixed concerns
+- Hard to test
+- Duplicate logic
+
+### After
+- 3 hooks (< 100 LOC each)
+- 5 components (< 50 LOC each)
+- Or 1 JSON schema (< 100 lines)
+- Fully tested
+- Reusable everywhere
+
+## 🚀 Next Steps
+
+1. Pick one component to migrate
+2. Follow Path 1 (Hook Extraction)
+3. Measure success (LOC reduction, testability)
+4. Share learnings with team
+5. Repeat for other components
+
+---
+
+**Need Help?**
+- Check [INDEX.md](./INDEX.md) for documentation
+- Review example hooks in `/src/hooks/`
+- Study JSON examples in `/src/config/pages/`
+- Ask questions in team chat
+
+**Good luck with your migration! 🚀**

docs/guides/PROPS_CONFIG_GUIDE.md

@@ -0,0 +1,317 @@
+# Props Configuration Guide
+
+## Overview
+
+The CodeForge application now supports **dynamic component props configuration** through the `pages.json` file. This declarative approach eliminates the need to modify `App.tsx` when adding or updating component props, making the system more maintainable and scalable.
+
+## Architecture
+
+### Key Files
+
+1. **`src/config/pages.json`** - Declarative page and props configuration
+2. **`src/config/page-loader.ts`** - Props resolution logic and interfaces
+3. **`src/App.tsx`** - Consumes the configuration and renders pages
+
+## Props Configuration Schema
+
+### Basic Props Structure
+
+```json
+{
+  "id": "example-page",
+  "component": "ExampleComponent",
+  "props": {
+    "state": ["stateKey1", "stateKey2"],
+    "actions": ["actionPropName:actionFunctionName"]
+  }
+}
+```
+
+### Props Configuration Options
+
+#### `state` Array
+
+Maps application state to component props. Supports two formats:
+
+1. **Direct mapping** (prop name = state key):
+   ```json
+   "state": ["files", "models", "theme"]
+   ```
+   Results in: `{ files, models, theme }`
+
+2. **Renamed mapping** (prop name : state key):
+   ```json
+   "state": ["trees:componentTrees", "config:flaskConfig"]
+   ```
+   Results in: `{ trees: componentTrees, config: flaskConfig }`
+
+#### `actions` Array
+
+Maps action functions (handlers/setters) to component props. Uses format:
+
+```json
+"actions": ["propName:functionName"]
+```
+
+Example:
+```json
+"actions": [
+  "onModelsChange:setModels",
+  "onFileSelect:setActiveFileId"
+]
+```
+
+### Resizable Page Configuration
+
+For pages with split-panel layouts (e.g., File Explorer + Code Editor):
+
+```json
+{
+  "id": "code",
+  "component": "CodeEditor",
+  "requiresResizable": true,
+  "props": {
+    "state": ["files", "activeFileId"],
+    "actions": ["onFileChange:handleFileChange"]
+  },
+  "resizableConfig": {
+    "leftComponent": "FileExplorer",
+    "leftProps": {
+      "state": ["files", "activeFileId"],
+      "actions": ["onFileSelect:setActiveFileId"]
+    },
+    "leftPanel": {
+      "defaultSize": 20,
+      "minSize": 15,
+      "maxSize": 30
+    },
+    "rightPanel": {
+      "defaultSize": 80
+    }
+  }
+}
+```
+
+## Available State Keys
+
+The following state variables are available in the state context:
+
+- `files` - Project files
+- `models` - Data models
+- `components` - Component definitions
+- `componentTrees` - Component tree structures
+- `workflows` - Workflow definitions
+- `lambdas` - Lambda function definitions
+- `theme` - Theme configuration
+- `playwrightTests` - Playwright test definitions
+- `storybookStories` - Storybook story definitions
+- `unitTests` - Unit test definitions
+- `flaskConfig` - Flask API configuration
+- `nextjsConfig` - Next.js project configuration
+- `npmSettings` - NPM package settings
+- `featureToggles` - Feature toggle states
+- `activeFileId` - Currently selected file ID
+
+## Available Actions
+
+The following action functions are available in the action context:
+
+- `handleFileChange` - Update file content
+- `setActiveFileId` - Set active file
+- `handleFileClose` - Close a file
+- `handleFileAdd` - Add new file
+- `setModels` - Update models
+- `setComponents` - Update components
+- `setComponentTrees` - Update component trees
+- `setWorkflows` - Update workflows
+- `setLambdas` - Update lambdas
+- `setTheme` - Update theme
+- `setPlaywrightTests` - Update Playwright tests
+- `setStorybookStories` - Update Storybook stories
+- `setUnitTests` - Update unit tests
+- `setFlaskConfig` - Update Flask config
+- `setNextjsConfig` - Update Next.js config
+- `setNpmSettings` - Update NPM settings
+- `setFeatureToggles` - Update feature toggles
+
+## Examples
+
+### Simple Component (No Props)
+
+```json
+{
+  "id": "docs",
+  "title": "Documentation",
+  "component": "DocumentationView",
+  "props": {}
+}
+```
+
+### Component with State Only
+
+```json
+{
+  "id": "models",
+  "title": "Models",
+  "component": "ModelDesigner",
+  "props": {
+    "state": ["models"]
+  }
+}
+```
+
+### Component with State and Actions
+
+```json
+{
+  "id": "models",
+  "title": "Models",
+  "component": "ModelDesigner",
+  "props": {
+    "state": ["models"],
+    "actions": ["onModelsChange:setModels"]
+  }
+}
+```
+
+### Component with Renamed Props
+
+```json
+{
+  "id": "flask",
+  "title": "Flask API",
+  "component": "FlaskDesigner",
+  "props": {
+    "state": ["config:flaskConfig"],
+    "actions": ["onConfigChange:setFlaskConfig"]
+  }
+}
+```
+
+### Dashboard with Multiple State Props
+
+```json
+{
+  "id": "dashboard",
+  "title": "Dashboard",
+  "component": "ProjectDashboard",
+  "props": {
+    "state": [
+      "files",
+      "models",
+      "components",
+      "theme",
+      "playwrightTests",
+      "storybookStories",
+      "unitTests",
+      "flaskConfig"
+    ]
+  }
+}
+```
+
+## Adding a New Page
+
+To add a new page with props configuration:
+
+1. **Add the page to `pages.json`**:
+   ```json
+   {
+     "id": "new-page",
+     "title": "New Feature",
+     "icon": "Star",
+     "component": "NewFeatureComponent",
+     "enabled": true,
+     "order": 21,
+     "props": {
+       "state": ["relevantState"],
+       "actions": ["onAction:setRelevantState"]
+     }
+   }
+   ```
+
+2. **Add the component to the lazy import map in `App.tsx`**:
+   ```typescript
+   const componentMap: Record<string, React.LazyExoticComponent<any>> = {
+     // ... existing components
+     NewFeatureComponent: lazy(() => import('@/components/NewFeatureComponent').then(m => ({ default: m.NewFeatureComponent }))),
+   }
+   ```
+
+3. **Optionally add to feature toggles** (if applicable):
+   ```json
+   {
+     "toggleKey": "newFeature"
+   }
+   ```
+
+That's it! No need to modify the `getPropsForComponent` function or other logic in `App.tsx`.
+
+## Benefits
+
+1. **Declarative Configuration** - All page configs in one place
+2. **No Code Changes** - Add/modify pages without touching `App.tsx` logic
+3. **Type Safety** - TypeScript interfaces ensure configuration validity
+4. **Maintainability** - Easy to understand and modify page props
+5. **Scalability** - Simple to add new pages and props
+6. **Consistency** - Standardized prop resolution across all pages
+
+## Migration from Old System
+
+The old hardcoded `propsMap` in `getPropsForComponent` has been replaced with dynamic resolution using `resolveProps()`. The configuration in `pages.json` now drives all prop mapping.
+
+### Before (Hardcoded in App.tsx)
+```typescript
+const propsMap: Record<string, any> = {
+  'ModelDesigner': {
+    models,
+    onModelsChange: setModels,
+  },
+  // ... 20+ more entries
+}
+```
+
+### After (Declarative in pages.json)
+```json
+{
+  "id": "models",
+  "component": "ModelDesigner",
+  "props": {
+    "state": ["models"],
+    "actions": ["onModelsChange:setModels"]
+  }
+}
+```
+
+## Future Enhancements
+
+Potential extensions to the props configuration system:
+
+1. **Computed Props** - Props derived from multiple state values
+2. **Prop Transformations** - Map/filter/reduce operations on state
+3. **Conditional Props** - Props based on feature toggles or user state
+4. **Default Values** - Fallback values for missing state
+5. **Validation Rules** - Runtime prop validation from schema
+6. **Hook Configuration** - Custom hooks to inject into components
+7. **Event Handlers** - Declarative event handler composition
+
+## Troubleshooting
+
+### Props not being passed to component
+
+1. Check that the state/action key exists in the context objects
+2. Verify the prop name mapping is correct (before:after colon)
+3. Ensure the page is enabled and not filtered by feature toggles
+4. Check browser console for resolution errors
+
+### Component not rendering
+
+1. Verify the component is added to the `componentMap` in `App.tsx`
+2. Check that the component name matches exactly (case-sensitive)
+3. Ensure the component export matches the import pattern
+
+### State updates not working
+
+1. Verify the action function name is correct
+2. Check that the setter is using functional updates for array/object state
+3. Ensure the action is properly mapped in the action context

docs/guides/PWA_GUIDE.md

@@ -0,0 +1,463 @@
+# 📱 Progressive Web App (PWA) Guide
+
+## Overview
+
+CodeForge is a fully-featured Progressive Web App that can be installed on any device and works offline. This guide covers all PWA capabilities, installation instructions, and technical details.
+
+## What is a PWA?
+
+A Progressive Web App combines the best of web and native apps:
+- **Installable** - Add to home screen or applications menu
+- **Offline-First** - Works without internet connection
+- **Fast** - Loads instantly from cache
+- **Engaging** - Native app-like experience
+- **Linkable** - Still a website with URLs
+- **Safe** - Served over HTTPS
+
+## Features
+
+### 🚀 Installation
+
+#### Desktop Installation
+**Chrome/Edge/Brave:**
+1. Visit CodeForge in your browser
+2. Look for the install icon (⊕) in the address bar
+3. Click "Install" or use the install prompt in the app
+4. The app will be added to your applications
+
+**Safari (macOS):**
+1. Open CodeForge in Safari
+2. Click File > Add to Dock
+3. The app icon will appear in your Dock
+
+**Firefox:**
+1. Visit CodeForge
+2. Click the install prompt when it appears
+3. Or use the "Install" button in the app UI
+
+#### Mobile Installation
+**iOS (Safari):**
+1. Open CodeForge in Safari
+2. Tap the Share button
+3. Select "Add to Home Screen"
+4. Tap "Add"
+
+**Android (Chrome):**
+1. Open CodeForge in Chrome
+2. Tap the menu (three dots)
+3. Select "Install app" or "Add to Home screen"
+4. Confirm installation
+
+### 💾 Offline Support
+
+CodeForge uses intelligent caching strategies to work offline:
+
+#### What Works Offline:
+- ✅ View and edit existing projects
+- ✅ Browse saved files and code
+- ✅ Use the code editor (Monaco)
+- ✅ Navigate between all tabs
+- ✅ View documentation
+- ✅ Make changes to models, components, themes
+- ✅ Create new files and components
+
+#### What Requires Internet:
+- ❌ AI-powered generation features
+- ❌ Downloading external fonts
+- ❌ Syncing projects to database
+- ❌ Fetching external resources
+
+#### Background Sync:
+When you go offline and make changes:
+1. Changes are stored locally
+2. Network status indicator appears
+3. When you reconnect, changes sync automatically
+4. You'll see "Back online" notification
+
+### 🔔 Push Notifications
+
+Enable notifications to receive updates about:
+- Project build completions
+- Error detections
+- New feature releases
+- System updates
+
+**To Enable Notifications:**
+1. Go to **PWA** tab in settings
+2. Toggle "Push Notifications"
+3. Grant permission in browser prompt
+4. You'll receive relevant notifications
+
+**To Disable:**
+- Use the toggle in PWA settings, or
+- Manage in browser settings:
+  - Chrome: Settings > Privacy > Site Settings > Notifications
+  - Safari: Preferences > Websites > Notifications
+  - Firefox: Settings > Privacy & Security > Notifications
+
+### ⚡ Performance & Caching
+
+#### Cache Strategy:
+CodeForge uses a multi-tier caching system:
+
+1. **Static Cache** - Core app files (HTML, CSS, JS)
+   - Cached on install
+   - Updated when new version deployed
+
+2. **Dynamic Cache** - User files and components
+   - Cached as you use them
+   - Limited to 50 items (oldest removed first)
+
+3. **Image Cache** - Icons and images
+   - Cached on first load
+   - Limited to 30 items
+
+#### Cache Management:
+View and manage cache in **PWA** settings tab:
+- See current cache size
+- Clear all cached data
+- Force reload with fresh data
+
+**Clear Cache:**
+1. Navigate to **PWA** tab
+2. Scroll to "Cache Management"
+3. Click "Clear Cache & Reload"
+4. App will reload with fresh data
+
+### 🔄 Updates
+
+#### Automatic Update Detection:
+- App checks for updates every time you open it
+- When an update is available, you'll see a notification
+- Click "Update Now" to reload with the new version
+
+#### Manual Update Check:
+1. Go to **PWA** tab
+2. Check "App Update" section
+3. Click "Update Now" if available
+
+#### Version Management:
+- Current version displayed in PWA settings
+- Service worker status shows if updates are pending
+- Update notifications appear automatically
+
+### ⚡ App Shortcuts
+
+Quick access to common features from your OS:
+
+**Desktop:**
+- Right-click the app icon
+- Select from shortcuts:
+  - Dashboard
+  - Code Editor
+  - Models Designer
+
+**Mobile:**
+- Long-press the app icon
+- Tap a shortcut for quick access
+
+### 📤 Share Target API
+
+Share code files directly to CodeForge:
+
+**To Share Files:**
+1. Right-click a code file in your OS
+2. Select "Share" (Windows/Android) or "Share to..." (macOS/iOS)
+3. Choose CodeForge
+4. File will open in the code editor
+
+**Supported File Types:**
+- `.ts`, `.tsx` - TypeScript files
+- `.js`, `.jsx` - JavaScript files
+- `.json` - JSON configuration
+- `.css`, `.scss` - Stylesheets
+- Any text file
+
+## Technical Implementation
+
+### Service Worker
+
+Location: `/public/sw.js`
+
+**Features:**
+- Install event: Precaches core assets
+- Activate event: Cleans up old caches
+- Fetch event: Intercepts requests with cache strategies
+- Message event: Handles cache clearing commands
+- Sync event: Background sync support
+- Push event: Push notification handling
+
+**Cache Versions:**
+```javascript
+const CACHE_VERSION = 'codeforge-v1.0.0'
+const STATIC_CACHE = 'codeforge-v1.0.0-static'
+const DYNAMIC_CACHE = 'codeforge-v1.0.0-dynamic'
+const IMAGE_CACHE = 'codeforge-v1.0.0-images'
+```
+
+### Web App Manifest
+
+Location: `/public/manifest.json`
+
+**Key Properties:**
+```json
+{
+  "name": "CodeForge - Low-Code App Builder",
+  "short_name": "CodeForge",
+  "display": "standalone",
+  "theme_color": "#7c3aed",
+  "background_color": "#0f0f14"
+}
+```
+
+**Icon Sizes:**
+- 72×72, 96×96, 128×128, 144×144, 152×152, 192×192, 384×384, 512×512
+- Maskable icons for Android
+- Shortcuts with 96×96 icons
+
+### React Hook: `usePWA`
+
+Location: `/src/hooks/use-pwa.ts`
+
+**Usage:**
+```typescript
+import { usePWA } from '@/hooks/use-pwa'
+
+function MyComponent() {
+  const { 
+    isInstallable, 
+    isInstalled, 
+    isOnline,
+    isUpdateAvailable,
+    installApp,
+    updateApp,
+    clearCache,
+    showNotification
+  } = usePWA()
+
+  // Use PWA features
+}
+```
+
+**State Properties:**
+- `isInstallable`: Can the app be installed?
+- `isInstalled`: Is the app currently installed?
+- `isOnline`: Is the device connected to internet?
+- `isUpdateAvailable`: Is a new version available?
+- `registration`: Service Worker registration object
+
+**Methods:**
+- `installApp()`: Trigger install prompt
+- `updateApp()`: Install pending update and reload
+- `clearCache()`: Clear all cached data
+- `requestNotificationPermission()`: Ask for notification permission
+- `showNotification(title, options)`: Display a notification
+
+### PWA Components
+
+**PWAInstallPrompt** - `/src/components/PWAInstallPrompt.tsx`
+- Appears after 3 seconds for installable apps
+- Dismissible with local storage memory
+- Animated card with install button
+
+**PWAUpdatePrompt** - `/src/components/PWAUpdatePrompt.tsx`
+- Appears when update is available
+- Top-right notification card
+- One-click update
+
+**PWAStatusBar** - `/src/components/PWAStatusBar.tsx`
+- Shows online/offline status
+- Appears at top when status changes
+- Auto-hides after 3 seconds when back online
+
+**PWASettings** - `/src/components/PWASettings.tsx`
+- Comprehensive PWA control panel
+- Installation status
+- Network status
+- Update management
+- Notification settings
+- Cache management
+- Feature availability
+
+## Browser Support
+
+### Full Support (Install + Offline):
+- ✅ Chrome 90+ (Desktop & Android)
+- ✅ Edge 90+ (Desktop)
+- ✅ Safari 14+ (macOS & iOS)
+- ✅ Firefox 90+ (Desktop & Android)
+- ✅ Opera 76+ (Desktop & Android)
+- ✅ Samsung Internet 14+
+
+### Partial Support:
+- ⚠️ Safari iOS 11.3-13 (Add to Home Screen, limited features)
+- ⚠️ Firefox iOS (Limited by iOS restrictions)
+
+### Not Supported:
+- ❌ Internet Explorer
+- ❌ Legacy browsers (Chrome <40, Firefox <44)
+
+## Troubleshooting
+
+### Installation Issues
+
+**"Install" button doesn't appear:**
+- Ensure you're using a supported browser
+- Check that site is served over HTTPS (or localhost)
+- Try refreshing the page
+- Check browser console for errors
+
+**App won't install on iOS:**
+- Only Safari supports installation on iOS
+- Use Share > Add to Home Screen method
+- Ensure you're not in Private Browsing mode
+
+### Offline Issues
+
+**App won't work offline:**
+- Check that service worker registered successfully (PWA settings tab)
+- Visit pages while online first to cache them
+- Clear cache and revisit pages online
+- Check browser's offline storage isn't full
+
+**Changes not syncing when back online:**
+- Check network status indicator
+- Manually save project after reconnecting
+- Clear cache and reload if persists
+
+### Notification Issues
+
+**Notifications not appearing:**
+- Check permission is granted in browser settings
+- Ensure notifications enabled in PWA settings
+- Check OS notification settings
+- Some browsers require user interaction first
+
+### Cache Issues
+
+**App showing old content:**
+1. Check for update notification
+2. Go to PWA settings
+3. Click "Clear Cache & Reload"
+4. Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
+
+**Cache size too large:**
+- Clear cache in PWA settings
+- Limits: 50 dynamic items, 30 images
+- Oldest items automatically removed
+
+## Best Practices
+
+### For Developers
+
+1. **Test Offline:**
+   - Use browser DevTools to simulate offline
+   - Chrome: DevTools > Network > Offline
+   - Test all critical user flows
+
+2. **Cache Strategy:**
+   - Static assets: Cache-first
+   - Dynamic content: Network-first with cache fallback
+   - Images: Cache with size limits
+
+3. **Update Strategy:**
+   - Notify users of updates
+   - Don't force immediate reload
+   - Allow "later" option for non-critical updates
+
+4. **Icons:**
+   - Provide multiple sizes (72px to 512px)
+   - Include maskable variants for Android
+   - Use SVG source for crisp rendering
+
+### For Users
+
+1. **Install the App:**
+   - Better performance
+   - Offline access
+   - Native app experience
+
+2. **Keep Updated:**
+   - Install updates when prompted
+   - Updates bring new features and fixes
+
+3. **Manage Storage:**
+   - Clear cache if experiencing issues
+   - Be aware of storage limits on mobile
+
+4. **Use Offline Wisely:**
+   - Save work before going offline
+   - AI features require internet
+   - Projects sync when back online
+
+## Security
+
+### HTTPS Requirement:
+- PWAs must be served over HTTPS
+- Protects data in transit
+- Required for service workers
+- Exception: localhost for development
+
+### Permissions:
+- Notification permission is opt-in
+- Location not used
+- Camera/microphone not used
+- Storage quota managed by browser
+
+### Data Privacy:
+- All data stored locally in browser
+- Service worker can't access other sites
+- Cache isolated per origin
+- Clear cache removes all local data
+
+## Performance Metrics
+
+### Lighthouse PWA Score:
+Target metrics for PWA:
+- ✅ Fast and reliable (service worker)
+- ✅ Installable (manifest)
+- ✅ PWA optimized (meta tags, icons)
+- ✅ Accessible (ARIA, contrast)
+
+### Loading Performance:
+- First load: ~2s (network dependent)
+- Subsequent loads: <500ms (from cache)
+- Offline load: <300ms (cache only)
+
+### Cache Efficiency:
+- Static cache: ~2-5 MB
+- Dynamic cache: ~10-20 MB (varies with usage)
+- Image cache: ~5-10 MB
+
+## Future Enhancements
+
+Planned PWA features:
+- 🔮 Periodic background sync
+- 🔮 Web Share API for projects
+- 🔮 File System Access API for direct saves
+- 🔮 Badging API for notification counts
+- 🔮 Improved offline AI with local models
+- 🔮 Background fetch for large exports
+- 🔮 Contact picker integration
+- 🔮 Clipboard API enhancements
+
+## Resources
+
+### Documentation:
+- [MDN PWA Guide](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps)
+- [web.dev PWA](https://web.dev/progressive-web-apps/)
+- [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)
+
+### Tools:
+- [Lighthouse](https://developers.google.com/web/tools/lighthouse)
+- [PWA Builder](https://www.pwabuilder.com/)
+- [Workbox](https://developers.google.com/web/tools/workbox)
+
+### Testing:
+- Chrome DevTools > Application tab
+- Firefox DevTools > Application tab
+- Safari Web Inspector > Storage tab
+
+---
+
+**Need Help?** Check the in-app documentation or open an issue on GitHub.

docs/guides/QUICKSTART_HOOKS.md

@@ -0,0 +1,288 @@
+# Quick Start: Using the Hook Library & JSON Orchestration
+
+## 5-Minute Quick Start
+
+### 1. Use a Data Hook
+
+```typescript
+import { useFiles } from '@/hooks/data'
+
+function MyComponent() {
+  const { files, addFile, updateFile } = useFiles()
+  
+  return (
+    <div>
+      {files.map(file => (
+        <div key={file.id}>{file.name}</div>
+      ))}
+      <button onClick={() => addFile(newFile)}>Add</button>
+    </div>
+  )
+}
+```
+
+### 2. Create a Simple Page Schema
+
+```json
+{
+  "id": "my-page",
+  "name": "My Page",
+  "layout": { "type": "single" },
+  "components": [
+    {
+      "id": "title",
+      "type": "h1",
+      "props": { "children": "Hello World" }
+    },
+    {
+      "id": "button",
+      "type": "Button",
+      "props": { "children": "Click Me" },
+      "events": [
+        { "event": "onClick", "action": "show-alert" }
+      ]
+    }
+  ],
+  "actions": [
+    {
+      "id": "show-alert",
+      "type": "custom",
+      "handler": "alert('Clicked!')"
+    }
+  ]
+}
+```
+
+### 3. Render the Page
+
+```typescript
+import { PageRenderer } from '@/components/orchestration'
+import myPageSchema from '@/config/pages/my-page.json'
+
+function App() {
+  return <PageRenderer schema={myPageSchema} />
+}
+```
+
+## Common Patterns
+
+### Pattern 1: List with CRUD
+
+```typescript
+import { useModels } from '@/hooks/data'
+import { useDialog } from '@/hooks/ui'
+
+function ModelList() {
+  const { models, addModel, updateModel, deleteModel } = useModels()
+  const { isOpen, open, close } = useDialog()
+  
+  return (
+    <>
+      <button onClick={open}>Add Model</button>
+      {models.map(model => (
+        <div key={model.id}>
+          {model.name}
+          <button onClick={() => deleteModel(model.id)}>Delete</button>
+        </div>
+      ))}
+      <Dialog open={isOpen} onOpenChange={close}>
+        {/* Add form */}
+      </Dialog>
+    </>
+  )
+}
+```
+
+### Pattern 2: Master-Detail
+
+```typescript
+import { useFiles } from '@/hooks/data'
+import { useState } from 'react'
+
+function FileEditor() {
+  const { files, updateFileContent } = useFiles()
+  const [selectedId, setSelectedId] = useState<string | null>(null)
+  
+  const selectedFile = files.find(f => f.id === selectedId)
+  
+  return (
+    <div className="grid grid-cols-2 gap-4">
+      <div>
+        {files.map(file => (
+          <button key={file.id} onClick={() => setSelectedId(file.id)}>
+            {file.name}
+          </button>
+        ))}
+      </div>
+      <div>
+        {selectedFile && (
+          <textarea
+            value={selectedFile.content}
+            onChange={e => updateFileContent(selectedFile.id, e.target.value)}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+### Pattern 3: Form with Validation
+
+```typescript
+import { useFormState } from '@/hooks/forms/use-form-state'
+import { useModels } from '@/hooks/data'
+
+function ModelForm() {
+  const { addModel } = useModels()
+  
+  const {
+    values,
+    errors,
+    setValue,
+    handleSubmit
+  } = useFormState({
+    initialValues: { name: '', description: '' },
+    validate: values => {
+      const errors: any = {}
+      if (!values.name) errors.name = 'Required'
+      return errors
+    },
+    onSubmit: async values => {
+      addModel({
+        id: Date.now().toString(),
+        ...values,
+        fields: [],
+        relations: []
+      })
+    }
+  })
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={values.name}
+        onChange={e => setValue('name', e.target.value)}
+      />
+      {errors.name && <span>{errors.name}</span>}
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+## Available Hooks
+
+### Data Hooks
+- `useFiles()` - Project files
+- `useModels()` - Prisma models
+- `useComponents()` - React components
+- `useWorkflows()` - Workflows
+- `useLambdas()` - Lambda functions
+
+### UI Hooks
+- `useDialog()` - Dialog state
+- `useConfirmation()` - Confirmation dialogs
+- `useSelection()` - Item selection
+- `useModal()` - Modals with data
+- `useTabs()` - Tab management
+- `usePanels()` - Resizable panels
+
+### Core Hooks
+- `useKVState()` - Enhanced KV storage
+- `useClipboard()` - Copy to clipboard
+- `useDebouncedSave()` - Auto-save with debounce
+
+### Orchestration Hooks
+- `usePage()` - Execute page schema
+- `useActions()` - Action execution
+
+## JSON Schema Cheat Sheet
+
+### Basic Structure
+```json
+{
+  "id": "page-id",
+  "name": "Page Name",
+  "layout": { "type": "single" },
+  "components": []
+}
+```
+
+### Component Types
+- UI: `Button`, `Card`, `Input`, `Badge`, `Textarea`
+- HTML: `div`, `span`, `h1`, `h2`, `h3`, `p`
+
+### Layout Types
+- `single` - Single column
+- `split` - Resizable panels
+- `tabs` - Tabbed interface
+- `grid` - CSS Grid
+
+### Data Binding
+```json
+{
+  "bindings": [
+    {
+      "source": "files.length",
+      "target": "children",
+      "transform": "value + ' files'"
+    }
+  ]
+}
+```
+
+### Events
+```json
+{
+  "events": [
+    {
+      "event": "onClick",
+      "action": "add-item"
+    }
+  ]
+}
+```
+
+### Actions
+```json
+{
+  "actions": [
+    {
+      "id": "add-item",
+      "type": "create",
+      "params": { "target": "Items" }
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### ✅ DO
+- Use functional updates: `setItems(current => [...current, item])`
+- Keep components under 150 LOC
+- Extract business logic to hooks
+- Use TypeScript types
+- Test hooks independently
+
+### ❌ DON'T
+- Use stale state: `setItems([...items, item])` ❌
+- Put business logic in components
+- Create components over 150 LOC
+- Skip type definitions
+- Test only the full component
+
+## Next Steps
+
+1. **Learn more about hooks**: Read [HOOK_LIBRARY_REFERENCE.md](./HOOK_LIBRARY_REFERENCE.md)
+2. **Learn JSON orchestration**: Read [JSON_ORCHESTRATION_GUIDE.md](../architecture/JSON_ORCHESTRATION_GUIDE.md)
+3. **See refactoring examples**: Read [REFACTORING_EXAMPLE.md](./REFACTORING_EXAMPLE.md)
+4. **Understand architecture**: Read [REFACTOR_PHASE3.md](./REFACTOR_PHASE3.md)
+
+## Get Help
+
+- Check the documentation files listed above
+- Look at example schemas in `/src/config/pages/`
+- Review hook implementations in `/src/hooks/`
+- See component examples in `/src/components/`

docs/guides/QUICK_REFERENCE.md

@@ -0,0 +1,321 @@
+# Quick Reference: Hooks & JSON Orchestration
+
+## 🚀 Quick Start
+
+### Using Hooks
+
+```typescript
+// 1. Import what you need
+import { useArray, useSearch } from '@/hooks/data'
+import { useDialog, useSelection } from '@/hooks/ui'
+import { useForm } from '@/hooks/forms'
+
+// 2. Use in your component
+function MyComponent() {
+  const { items, add, remove } = useArray('my-data', [])
+  const { query, results } = useSearch(items, ['name'])
+  const dialog = useDialog()
+  
+  return <div>{/* Your UI */}</div>
+}
+```
+
+### Creating JSON Pages
+
+```json
+{
+  "id": "my-page",
+  "name": "My Page",
+  "layout": { "type": "single" },
+  "dataSources": [
+    { "id": "data", "type": "kv", "key": "my-key", "defaultValue": [] }
+  ],
+  "components": [
+    { "id": "root", "type": "Card", "children": [] }
+  ],
+  "actions": [
+    { "id": "add", "type": "create", "target": "data" }
+  ]
+}
+```
+
+## 📦 Hook Cheat Sheet
+
+### Data Hooks
+
+```typescript
+// Arrays
+const { items, add, remove, update, count } = useArray('key', [])
+
+// CRUD
+const { create, read, update, remove, selected } = useCRUD(items, setItems)
+
+// Search
+const { query, setQuery, results } = useSearch(items, ['field1', 'field2'])
+
+// Sort
+const { sortedItems, toggleSort } = useSort(items, 'name')
+
+// Pagination
+const { items, page, nextPage, prevPage } = usePagination(items, 10)
+```
+
+### UI Hooks
+
+```typescript
+// Dialog
+const { isOpen, open, close } = useDialog()
+
+// Tabs
+const { activeTab, switchTab } = useTabs('default')
+
+// Selection
+const { toggle, selectAll, isSelected } = useSelection()
+
+// Clipboard
+const { copy, copied } = useClipboard('Copied!')
+```
+
+### Form Hooks
+
+```typescript
+// Single field
+const field = useFormField('', [
+  { validate: (v) => v.length > 0, message: 'Required' }
+])
+
+// Full form
+const form = useForm({
+  initialValues: { name: '', email: '' },
+  validate: (values) => ({}),
+  onSubmit: async (values) => { /* save */ }
+})
+```
+
+## 🗂️ JSON Schema Cheat Sheet
+
+### Data Sources
+
+```json
+{
+  "dataSources": [
+    { "id": "todos", "type": "kv", "key": "todos", "defaultValue": [] },
+    { "id": "user", "type": "api", "endpoint": "/api/user" },
+    { "id": "stats", "type": "computed", "transform": "calc" }
+  ]
+}
+```
+
+### Actions
+
+```json
+{
+  "actions": [
+    { "id": "add", "type": "create", "target": "todos" },
+    { "id": "edit", "type": "update", "target": "todos" },
+    { "id": "delete", "type": "delete", "target": "todos" },
+    { "id": "nav", "type": "navigate", "target": "home" },
+    { "id": "custom", "type": "custom", "handler": "myHandler" }
+  ]
+}
+```
+
+### Components
+
+```json
+{
+  "components": [
+    {
+      "id": "btn",
+      "type": "Button",
+      "props": { "children": "Click me" },
+      "eventHandlers": { "onClick": "add" }
+    },
+    {
+      "id": "input",
+      "type": "Input",
+      "dataBinding": "formData.name"
+    }
+  ]
+}
+```
+
+## 🎯 Common Patterns
+
+### Pattern 1: List with Search and Sort
+
+```typescript
+function ListPage() {
+  const { items, add, remove } = useArray('items', [])
+  const { results, setQuery } = useSearch(items, ['name'])
+  const { sortedItems, toggleSort } = useSort(results, 'name')
+  
+  return <div>{/* render sortedItems */}</div>
+}
+```
+
+### Pattern 2: Form with Validation
+
+```typescript
+function FormPage() {
+  const form = useForm({
+    initialValues: { name: '', email: '' },
+    validate: (v) => {
+      const errors: any = {}
+      if (!v.name) errors.name = 'Required'
+      if (!v.email.includes('@')) errors.email = 'Invalid'
+      return errors
+    },
+    onSubmit: async (v) => {
+      await api.save(v)
+      toast.success('Saved!')
+    }
+  })
+  
+  return <form onSubmit={form.handleSubmit}>{/* fields */}</form>
+}
+```
+
+### Pattern 3: Master-Detail View
+
+```typescript
+function MasterDetail() {
+  const { items } = useArray('items', [])
+  const { selected, setSelectedId } = useCRUD(items, () => {})
+  
+  return (
+    <div className="grid grid-cols-2">
+      <div>{/* list */}</div>
+      <div>{selected && /* detail */}</div>
+    </div>
+  )
+}
+```
+
+### Pattern 4: Bulk Operations
+
+```typescript
+function BulkActions() {
+  const { items, remove } = useArray('items', [])
+  const { selectedIds, toggle, selectAll } = useSelection()
+  
+  const deleteSelected = () => {
+    selectedIds.forEach(id => {
+      remove(item => item.id === id)
+    })
+  }
+  
+  return <div>{/* UI */}</div>
+}
+```
+
+## 🔧 Tips & Tricks
+
+### Tip 1: Compose Hooks
+```typescript
+function useMyFeature() {
+  const data = useArray('key', [])
+  const search = useSearch(data.items, ['name'])
+  return { ...data, ...search }
+}
+```
+
+### Tip 2: Custom Validation
+```typescript
+const email = useFormField('', [
+  { validate: v => v.includes('@'), message: 'Invalid email' },
+  { validate: v => v.length > 5, message: 'Too short' }
+])
+```
+
+### Tip 3: Conditional Actions
+```json
+{
+  "actions": [
+    {
+      "id": "save",
+      "type": "custom",
+      "handler": "conditionalSave"
+    }
+  ]
+}
+```
+
+```typescript
+const handlers = {
+  conditionalSave: async (data) => {
+    if (validate(data)) {
+      await save(data)
+    }
+  }
+}
+```
+
+### Tip 4: Nested Data Binding
+```json
+{
+  "id": "email",
+  "type": "Input",
+  "dataBinding": "user.profile.email"
+}
+```
+
+## 📁 File Organization
+
+```
+src/
+├── hooks/
+│   ├── data/          # useArray, useCRUD, useSearch
+│   ├── ui/            # useDialog, useTabs, useSelection
+│   └── forms/         # useForm, useFormField
+├── config/
+│   ├── orchestration/ # Engine files
+│   └── pages/         # JSON page definitions
+└── components/
+    └── ...            # React components (< 150 LOC)
+```
+
+## 🐛 Debugging
+
+### Debug Hook State
+```typescript
+const data = useArray('key', [])
+console.log('Items:', data.items)
+console.log('Count:', data.count)
+```
+
+### Debug JSON Rendering
+```typescript
+<PageRenderer schema={schema} debug={true} />
+```
+
+### Validate JSON Schema
+```typescript
+import { PageSchemaDefinition } from '@/config/orchestration/schema'
+
+const result = PageSchemaDefinition.safeParse(mySchema)
+if (!result.success) {
+  console.error(result.error)
+}
+```
+
+## 📚 Full Documentation
+
+- **Hooks**: `../api/COMPLETE_HOOK_LIBRARY.md`
+- **JSON**: `../architecture/JSON_ORCHESTRATION_COMPLETE.md`
+- **Summary**: `../history/PHASE4_IMPLEMENTATION_COMPLETE.md`
+
+## 🆘 Need Help?
+
+1. Check the documentation files
+2. Look at example pages in `/src/config/pages/`
+3. Review hook implementations in `/src/hooks/`
+4. Test with the PageRenderer
+
+---
+
+**Quick Links:**
+- Hooks: `/src/hooks/`
+- Orchestration: `/src/config/orchestration/`
+- Examples: `/src/config/pages/`
+- Docs: `../api/COMPLETE_HOOK_LIBRARY.md`

docs/guides/SEED_DATA_GUIDE.md

@@ -0,0 +1,199 @@
+# Seed Data System
+
+## Overview
+
+The application now includes a comprehensive seed data system that loads initial data from JSON configuration into the database (KV store) on first launch.
+
+## Features
+
+### 1. Automatic Data Loading
+- Seed data is automatically loaded on application startup
+- Only loads if data doesn't already exist (safe to re-run)
+- All data is stored in the KV database for persistence
+
+### 2. Seed Data Management UI
+Navigate to **Settings → Data** tab to access the Seed Data Manager with three options:
+
+- **Load Seed Data**: Populates database with initial data (only if not already loaded)
+- **Reset to Defaults**: Overwrites all data with fresh seed data
+- **Clear All Data**: Removes all data from the database (destructive action)
+
+### 3. Dashboard Integration
+The Project Dashboard displays available seed data including:
+- Number of pre-configured files
+- Number of sample models
+- Number of example components
+- And more...
+
+## Seed Data Contents
+
+The system includes the following pre-configured data:
+
+### Files (`project-files`)
+- Sample Next.js pages (page.tsx, layout.tsx)
+- Material UI integration examples
+- TypeScript configuration
+
+### Models (`project-models`)
+- User model with authentication fields
+- Post model with relationships
+- Complete Prisma schema examples
+
+### Components (`project-components`)
+- Button components with variants
+- Card components with styling
+- Reusable UI elements
+
+### Workflows (`project-workflows`)
+- User registration flow
+- Complete workflow with triggers and actions
+- Visual workflow nodes and connections
+
+### Lambdas (`project-lambdas`)
+- User data processing function
+- HTTP trigger configuration
+- Environment variable examples
+
+### Tests (`project-playwright-tests`, `project-storybook-stories`, `project-unit-tests`)
+- E2E test examples
+- Component story examples
+- Unit test templates
+
+### Component Trees (`project-component-trees`)
+- Application layout tree
+- Nested component structures
+- Material UI component hierarchies
+
+## Configuration
+
+### Adding New Seed Data
+
+Edit `/src/config/seed-data.json` to add or modify seed data:
+
+```json
+{
+  "project-files": [...],
+  "project-models": [...],
+  "your-custom-key": [...]
+}
+```
+
+### Seed Data Schema
+
+Each data type follows the TypeScript interfaces defined in `/src/types/project.ts`:
+
+- `ProjectFile`
+- `PrismaModel`
+- `ComponentNode`
+- `Workflow`
+- `Lambda`
+- `PlaywrightTest`
+- `StorybookStory`
+- `UnitTest`
+- `ComponentTree`
+
+## API Reference
+
+### Hook: `useSeedData()`
+
+```typescript
+import { useSeedData } from '@/hooks/data/use-seed-data'
+
+const { isLoaded, isLoading, loadSeedData, resetSeedData, clearAllData } = useSeedData()
+```
+
+**Returns:**
+- `isLoaded`: Boolean indicating if seed data has been loaded
+- `isLoading`: Boolean indicating if an operation is in progress
+- `loadSeedData()`: Function to load seed data (if not already loaded)
+- `resetSeedData()`: Function to reset all data to seed defaults
+- `clearAllData()`: Function to clear all data from database
+
+### Direct KV API
+
+You can also interact with seed data directly:
+
+```typescript
+// Get specific seed data
+const files = await window.spark.kv.get('project-files')
+
+// Update seed data
+await window.spark.kv.set('project-files', updatedFiles)
+
+// Delete seed data
+await window.spark.kv.delete('project-files')
+```
+
+## Components
+
+### `<SeedDataManager />`
+Management UI for seed data operations (used in Settings → Data tab)
+
+### `<SeedDataStatus />`
+Display component showing available seed data (used on Dashboard)
+
+## Best Practices
+
+1. **Always use the useKV hook** for reactive state management
+2. **Use functional updates** when modifying arrays/objects to prevent data loss
+3. **Test seed data** thoroughly before deploying
+4. **Document custom seed data** for team members
+5. **Keep seed data minimal** - only include essential examples
+
+## Example: Custom Seed Data
+
+```typescript
+// 1. Add to seed-data.json
+{
+  "my-custom-data": [
+    { "id": "1", "name": "Example 1" },
+    { "id": "2", "name": "Example 2" }
+  ]
+}
+
+// 2. Use in component
+import { useKV } from '@github/spark/hooks'
+
+function MyComponent() {
+  const [data, setData] = useKV('my-custom-data', [])
+  
+  // Always use functional updates
+  const addItem = (newItem) => {
+    setData(current => [...current, newItem])
+  }
+  
+  return (
+    <div>
+      {data.map(item => (
+        <div key={item.id}>{item.name}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Troubleshooting
+
+### Data Not Loading
+- Check browser console for errors
+- Verify seed-data.json is valid JSON
+- Ensure data keys match KV store keys
+
+### Data Persisting After Clear
+- Hard refresh the browser (Ctrl+Shift+R)
+- Check for cached service workers (PWA)
+- Verify clearAllData completed successfully
+
+### Type Errors
+- Ensure seed data matches TypeScript interfaces
+- Update types in `/src/types/project.ts` if needed
+- Run type checking: `npm run type-check`
+
+## Future Enhancements
+
+Planned improvements:
+- Import/export seed data as JSON files
+- Version control for seed data
+- Seed data migration system
+- Seed data validation UI
+- Partial seed data loading

docs/history/DELIVERY_COMPLETE.md

@@ -0,0 +1,341 @@
+# 🎉 Phase 4 Refactoring - COMPLETE
+
+## ✅ Mission Accomplished
+
+The CodeForge application has been successfully refactored with a comprehensive hook library and JSON orchestration system. All deliverables are complete and ready for use.
+
+## 📦 What Was Delivered
+
+### 1. Hook Library (12+ Hooks, 550+ LOC)
+
+#### Data Management Hooks ✅
+- `useArray` (64 LOC) - `/src/hooks/data/use-array.ts`
+- `useCRUD` (73 LOC) - `/src/hooks/data/use-crud.ts`
+- `useSearch` (42 LOC) - `/src/hooks/data/use-search.ts`
+- `useDebounce` (17 LOC) - `/src/hooks/data/use-debounce.ts`
+- `useSort` (48 LOC) - `/src/hooks/data/use-sort.ts`
+- `usePagination` (55 LOC) - `/src/hooks/data/use-pagination.ts`
+
+#### UI State Hooks ✅
+- `useDialog` (17 LOC) - `/src/hooks/ui/use-dialog.ts`
+- `useTabs` (21 LOC) - `/src/hooks/ui/use-tabs.ts`
+- `useSelection` (56 LOC) - `/src/hooks/ui/use-selection.ts`
+- `useClipboard` (28 LOC) - `/src/hooks/ui/use-clipboard.ts`
+
+#### Form Hooks ✅
+- `useForm` (73 LOC) - `/src/hooks/forms/use-form.ts`
+- `useFormField` (56 LOC) - `/src/hooks/forms/use-form-field.ts`
+
+### 2. JSON Orchestration Engine (325 LOC) ✅
+
+- `schema.ts` (71 LOC) - TypeScript/Zod schemas
+- `action-executor.ts` (83 LOC) - Action execution
+- `data-source-manager.ts` (67 LOC) - Data management
+- `component-registry.ts` (35 LOC) - Component lookup
+- `PageRenderer.tsx` (69 LOC) - React renderer
+
+**Location:** `/src/config/orchestration/`
+
+### 3. Example JSON Pages ✅
+
+- `dashboard.json` - Dashboard example
+- `simple-form.json` - Form example
+
+**Location:** `/src/config/pages/`
+
+### 4. Complete Documentation (60KB+) ✅
+
+1. **INDEX.md** (9.4KB) - Navigation hub
+2. **QUICK_REFERENCE.md** (6.5KB) - Fast lookup
+3. **COMPLETE_HOOK_LIBRARY.md** (8.5KB) - Hook API
+4. **JSON_ORCHESTRATION_COMPLETE.md** (14.8KB) - JSON guide
+5. **MIGRATION_GUIDE.md** (11.8KB) - Migration steps
+6. **PHASE4_IMPLEMENTATION_COMPLETE.md** (11.2KB) - Summary
+7. **ARCHITECTURE_VISUAL_GUIDE.md** (12.9KB) - Diagrams
+
+**Total Documentation:** 75KB across 7 files
+
+## 🎯 Key Achievements
+
+### Code Quality
+- ✅ All hooks under 150 LOC
+- ✅ All orchestration files under 85 LOC
+- ✅ Full TypeScript type safety
+- ✅ Zod schema validation
+- ✅ Zero breaking changes
+
+### Architecture
+- ✅ Complete separation of concerns
+- ✅ Reusable hook library
+- ✅ JSON-driven pages
+- ✅ Component registry
+- ✅ Action orchestration
+
+### Documentation
+- ✅ 7 comprehensive guides
+- ✅ 60KB+ of documentation
+- ✅ Code examples throughout
+- ✅ Visual diagrams
+- ✅ Migration guide
+
+## 🗂️ File Structure
+
+```
+/workspaces/spark-template/
+├── Documentation (Root Level)
+│   ├── INDEX.md                              ⭐ START HERE
+│   ├── QUICK_REFERENCE.md                    ⚡ Fast lookup
+│   ├── COMPLETE_HOOK_LIBRARY.md              🎣 Hook API
+│   ├── JSON_ORCHESTRATION_COMPLETE.md        📄 JSON guide
+│   ├── MIGRATION_GUIDE.md                    🔄 Migration steps
+│   ├── PHASE4_IMPLEMENTATION_COMPLETE.md     📊 Summary
+│   ├── ARCHITECTURE_VISUAL_GUIDE.md          🎨 Diagrams
+│   └── DELIVERY_COMPLETE.md                  ✅ This file
+│
+├── src/
+│   ├── hooks/                                 🎣 Hook Library
+│   │   ├── data/
+│   │   │   ├── use-array.ts
+│   │   │   ├── use-crud.ts
+│   │   │   ├── use-search.ts
+│   │   │   ├── use-debounce.ts
+│   │   │   ├── use-sort.ts
+│   │   │   ├── use-pagination.ts
+│   │   │   └── index.ts
+│   │   ├── ui/
+│   │   │   ├── use-dialog.ts
+│   │   │   ├── use-tabs.ts
+│   │   │   ├── use-selection.ts
+│   │   │   ├── use-clipboard.ts
+│   │   │   └── index.ts
+│   │   └── forms/
+│   │       ├── use-form.ts
+│   │       ├── use-form-field.ts
+│   │       └── index.ts
+│   │
+│   └── config/
+│       ├── orchestration/                     🎭 Engine
+│       │   ├── schema.ts
+│       │   ├── action-executor.ts
+│       │   ├── data-source-manager.ts
+│       │   ├── component-registry.ts
+│       │   ├── PageRenderer.tsx
+│       │   └── index.ts
+│       └── pages/                             📄 Examples
+│           ├── dashboard.json
+│           └── simple-form.json
+│
+└── README.md (Updated with Phase 4 info)
+```
+
+## 🚀 Getting Started
+
+### For New Users
+1. Read `INDEX.md` (2 min)
+2. Browse `QUICK_REFERENCE.md` (10 min)
+3. Try a hook from examples (30 min)
+
+### For Developers
+1. Read `COMPLETE_HOOK_LIBRARY.md` (30 min)
+2. Read `JSON_ORCHESTRATION_COMPLETE.md` (45 min)
+3. Build something (2 hours)
+
+### For Migrating Code
+1. Read `MIGRATION_GUIDE.md` (30 min)
+2. Choose migration path (5 min)
+3. Migrate first component (2 hours)
+
+## 📊 Statistics
+
+### Code Metrics
+- **Hooks Created:** 12
+- **Total Hook LOC:** ~550
+- **Average Hook Size:** ~46 LOC
+- **Orchestration Files:** 5
+- **Total Engine LOC:** ~325
+- **Example Pages:** 2
+
+### Documentation Metrics
+- **Documentation Files:** 7
+- **Total Documentation:** ~60KB
+- **Code Examples:** 50+
+- **Diagrams:** 10+
+
+### Quality Metrics
+- **Type Safety:** 100%
+- **Components < 150 LOC:** 100%
+- **Hooks < 150 LOC:** 100%
+- **Breaking Changes:** 0
+- **Backward Compatible:** ✅
+
+## 🎓 Quick Examples
+
+### Using Hooks
+```typescript
+import { useArray, useSearch } from '@/hooks/data'
+
+function MyComponent() {
+  const { items, add, remove } = useArray('items', [])
+  const { results, setQuery } = useSearch(items, ['name'])
+  
+  return <div>{/* Your UI */}</div>
+}
+```
+
+### JSON Page
+```json
+{
+  "id": "my-page",
+  "name": "My Page",
+  "layout": { "type": "single" },
+  "dataSources": [
+    { "id": "data", "type": "kv", "key": "my-data" }
+  ],
+  "components": [
+    { "id": "root", "type": "Card", "children": [] }
+  ]
+}
+```
+
+### Using PageRenderer
+```typescript
+import { PageRenderer } from '@/config/orchestration'
+import schema from '@/config/pages/my-page.json'
+
+function MyPage() {
+  return <PageRenderer schema={schema} />
+}
+```
+
+## ✨ Next Steps
+
+### Immediate (Done ✅)
+- [x] Create hook library
+- [x] Build orchestration engine
+- [x] Write documentation
+- [x] Provide examples
+- [x] Update README
+
+### Short Term (Your Turn 🎯)
+- [ ] Try using a hook
+- [ ] Create a JSON page
+- [ ] Migrate a component
+- [ ] Build custom composed hook
+
+### Long Term (Roadmap 🗺️)
+- [ ] Migrate all components
+- [ ] Visual JSON editor
+- [ ] More hook utilities
+- [ ] Performance profiling
+- [ ] Advanced patterns
+
+## 🎉 Success Criteria - ALL MET ✅
+
+| Criterion | Status | Details |
+|-----------|--------|---------|
+| Hook Library | ✅ | 12+ hooks, all < 150 LOC |
+| Orchestration | ✅ | 5 core files, ~325 LOC |
+| Type Safety | ✅ | TypeScript + Zod |
+| Documentation | ✅ | 60KB+ across 7 files |
+| Examples | ✅ | 2 JSON pages + hook examples |
+| Breaking Changes | ✅ | Zero |
+| Backward Compat | ✅ | 100% |
+| Component Size | ✅ | All < 150 LOC |
+
+## 📚 Documentation Index
+
+1. **[INDEX.md](./INDEX.md)** - Start here for navigation
+2. **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - Fast lookups
+3. **[COMPLETE_HOOK_LIBRARY.md](./COMPLETE_HOOK_LIBRARY.md)** - Full hook API
+4. **[JSON_ORCHESTRATION_COMPLETE.md](./JSON_ORCHESTRATION_COMPLETE.md)** - JSON system
+5. **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** - How to migrate
+6. **[PHASE4_IMPLEMENTATION_COMPLETE.md](./PHASE4_IMPLEMENTATION_COMPLETE.md)** - Overview
+7. **[ARCHITECTURE_VISUAL_GUIDE.md](./ARCHITECTURE_VISUAL_GUIDE.md)** - Diagrams
+
+## 💡 Key Concepts
+
+### Hooks
+Reusable business logic extracted from components. Import and use in any component.
+
+### JSON Orchestration
+Define pages using JSON schemas instead of writing React code. Rapid prototyping.
+
+### Component Registry
+Maps JSON component types to actual React components. Extensible.
+
+### Action Executor
+Handles CRUD, navigation, API calls, and custom actions from JSON schemas.
+
+### Data Source Manager
+Manages KV store, API, static, and computed data sources.
+
+## 🔗 Quick Links
+
+- **Code:** `/src/hooks/` and `/src/config/orchestration/`
+- **Examples:** `/src/config/pages/`
+- **Docs:** Root directory (INDEX.md, etc.)
+- **README:** Updated with Phase 4 info
+
+## 🆘 Need Help?
+
+1. Check `INDEX.md` for navigation
+2. Review `QUICK_REFERENCE.md` for examples
+3. Read specific docs as needed
+4. Check example implementations
+5. Try the migration guide
+
+## 🎊 Celebration!
+
+This refactoring represents:
+- **300+ hours** of architectural planning
+- **12+ custom hooks** built from scratch
+- **Complete orchestration engine** designed and implemented
+- **60KB+ documentation** written and organized
+- **Zero breaking changes** maintaining backward compatibility
+- **100% type safety** throughout
+
+**The codebase is now:**
+- ✨ More maintainable
+- 🚀 More performant
+- 🧪 More testable
+- 📖 Better documented
+- 🔄 Easier to extend
+
+---
+
+## 🎯 Final Checklist
+
+- [x] Hook library complete
+- [x] Orchestration engine complete
+- [x] Documentation complete
+- [x] Examples provided
+- [x] README updated
+- [x] Type safety verified
+- [x] Zero breaking changes
+- [x] All components < 150 LOC
+- [x] Migration guide written
+- [x] Architecture documented
+
+## 🚀 Status: DELIVERED
+
+**Version:** 6.0.0  
+**Date:** Phase 4 Complete  
+**Status:** ✅ Production Ready  
+**Breaking Changes:** None  
+**Migration Required:** Optional  
+
+---
+
+**Congratulations on completing Phase 4! 🎉**
+
+The foundation is now in place for a modern, maintainable, and scalable codebase. Happy coding! 🚀
+
+---
+
+**Questions or Issues?**
+- Check the documentation in `INDEX.md`
+- Review examples in `/src/config/pages/`
+- Study hook implementations in `/src/hooks/`
+- Follow the migration guide
+
+**Ready to build the future! 💪**

docs/history/PHASE2_REFACTORING_SUMMARY.md

@@ -0,0 +1,313 @@
+# Phase 2 Refactoring Summary
+
+## What Was Accomplished
+
+### 1. Hook Library Foundation ✅
+
+Created a comprehensive hook library structure with the following hooks:
+
+#### Core Hooks (`/src/hooks/core/`)
+- ✅ `use-kv-state.ts` - Enhanced KV wrapper with Zod validation
+- ✅ `use-debounced-save.ts` - Debounced auto-save functionality
+- ✅ `use-clipboard.ts` - Copy/paste with user feedback
+
+#### UI Hooks (`/src/hooks/ui/`)
+- ✅ `use-dialog.ts` - Dialog state management
+- ✅ `use-selection.ts` - Multi-select state management
+- ✅ `use-confirmation.ts` - Confirmation dialog orchestration
+
+#### Config Hooks (`/src/hooks/config/`)
+- ✅ `use-page-config.ts` - Load page configurations from KV/JSON
+- ✅ `use-layout-state.ts` - Persist layout state per page
+- ✅ `use-feature-flags.ts` - Runtime feature flag management
+
+### 2. JSON-Based Page Orchestration System ✅
+
+Created a complete JSON-based configuration system:
+
+- ✅ `page-schema.ts` - Zod schemas for type-safe page configs
+- ✅ `default-pages.json` - Default configurations for all 20 pages
+- ✅ Page configuration hooks for loading and persisting configs
+
+**Key Features:**
+- Define page layouts in JSON (single, split, grid, tabs)
+- Configure panel sizes, components, and constraints
+- Feature toggles per page
+- Keyboard shortcuts defined in config
+- All stored in KV database for persistence
+
+### 3. Documentation ✅
+
+Created comprehensive documentation:
+
+- ✅ `REFACTOR_PHASE2.md` - Complete refactoring plan and strategy
+- ✅ `HOOK_LIBRARY_DOCS.md` - Full hook library documentation with examples
+- Includes migration checklist and best practices
+- Example code for breaking down large components
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     KV Database                          │
+│  • page-config:{id}  → PageConfig                       │
+│  • layout-state:{id} → LayoutState                      │
+│  • feature-flags     → Record<string, boolean>          │
+└─────────────────────────────────────────────────────────┘
+                           ↕
+┌─────────────────────────────────────────────────────────┐
+│                   Config Hooks Layer                     │
+│  • usePageConfig()    • useLayoutState()                │
+│  • useFeatureFlags()  • usePageRegistry()               │
+└─────────────────────────────────────────────────────────┘
+                           ↕
+┌─────────────────────────────────────────────────────────┐
+│              Business Logic Hooks Layer                  │
+│  • use-file-manager    • use-model-manager              │
+│  • use-workflow-manager • use-idea-manager              │
+│  • use-ai-generation   • use-validation                 │
+└─────────────────────────────────────────────────────────┘
+                           ↕
+┌─────────────────────────────────────────────────────────┐
+│                  Presentation Layer                      │
+│  Components <150 LOC  →  Pure UI, no business logic    │
+│  PageOrchestrator     →  Renders from JSON configs      │
+└─────────────────────────────────────────────────────────┘
+```
+
+## JSON Page Configuration Example
+
+```json
+{
+  "id": "code-editor",
+  "title": "Code Editor",
+  "description": "Edit project files with AI assistance",
+  "icon": "Code",
+  "component": "CodeEditorPage",
+  "layout": {
+    "type": "split",
+    "direction": "horizontal",
+    "defaultSizes": [20, 80],
+    "panels": [
+      {
+        "id": "file-tree",
+        "component": "FileExplorer",
+        "minSize": 15,
+        "maxSize": 40
+      },
+      {
+        "id": "editor",
+        "component": "CodeEditor",
+        "minSize": 60
+      }
+    ]
+  },
+  "features": [
+    { "id": "ai-improve", "enabled": true },
+    { "id": "ai-explain", "enabled": true }
+  ],
+  "shortcuts": [
+    { "key": "2", "ctrl": true, "action": "navigate" }
+  ]
+}
+```
+
+## Benefits Achieved
+
+### 1. Maintainability 📈
+- Smaller components easier to understand and modify
+- Clear separation between business logic (hooks) and presentation (components)
+- Changes to logic don't require touching UI code
+
+### 2. Reusability 🔄
+- Hooks can be composed and reused across components
+- UI components are pure and composable
+- Page layouts can be reused via JSON config
+
+### 3. Testability 🧪
+- Hooks can be tested in isolation without rendering
+- Components are pure functions that are easy to test
+- JSON configs can be validated with schemas
+
+### 4. Flexibility 💪
+- Runtime configuration via JSON
+- Users can customize layouts (future feature)
+- Feature flags enable A/B testing
+- No code changes needed for layout adjustments
+
+### 5. Safety 🛡️
+- Smaller components = smaller changes
+- Type-safe with Zod validation
+- Reduced risk when modifying code
+- Clear interfaces between layers
+
+## Next Steps (Remaining Work)
+
+### Phase 2.2: Component Splitting (Priority)
+
+Break down these large components to <150 LOC each:
+
+1. **FeatureIdeaCloud.tsx** (829 LOC) → 6 components
+   - `IdeaCanvas.tsx` (80 LOC)
+   - `IdeaCard.tsx` (70 LOC)
+   - `IdeaConnection.tsx` (60 LOC)
+   - `IdeaToolbar.tsx` (50 LOC)
+   - `IdeaColorPicker.tsx` (40 LOC)
+   - `IdeaGroupBoundary.tsx` (60 LOC)
+
+2. **App.tsx** (828 LOC) → 3 components + hooks
+   - `AppShell.tsx` (100 LOC)
+   - `PageRouter.tsx` (80 LOC)
+   - `ExportDialog.tsx` (120 LOC)
+
+3. **CodeEditor.tsx** (~400 LOC) → 4 components
+4. **ModelDesigner.tsx** (~350 LOC) → 3 components
+5. **WorkflowDesigner.tsx** (~500 LOC) → 4 components
+
+### Phase 2.3: Feature Hooks Creation
+
+Create hooks for remaining features:
+
+- `use-file-manager.ts` - File CRUD operations
+- `use-model-manager.ts` - Prisma model operations
+- `use-component-manager.ts` - Component tree operations
+- `use-workflow-manager.ts` - Workflow operations
+- `use-lambda-manager.ts` - Lambda function operations
+- `use-test-manager.ts` - Test suite operations
+- `use-theme-manager.ts` - Theme operations
+- `use-project-manager.ts` - Project save/load/export
+- `use-idea-manager.ts` - Feature idea operations
+- `use-connection-manager.ts` - Idea connections (1:1 mapping)
+
+### Phase 2.4: Page Orchestration Implementation
+
+Build the orchestration system:
+
+1. Create `PageOrchestrator.tsx` component
+2. Build `DynamicLayout.tsx` for rendering layouts from config
+3. Create component registry mapping JSON → React components
+4. Build UI for editing page layouts (drag-and-drop)
+5. Migrate existing pages to use orchestration system
+
+### Phase 2.5: Database Integration
+
+Full database-driven UI:
+
+1. Store all page configs in KV by default
+2. Allow users to customize page layouts
+3. Feature flag UI for enabling/disabling features
+4. User preference persistence
+5. Export/import page configurations
+
+## Files Created
+
+```
+/workspaces/spark-template/
+├── REFACTOR_PHASE2.md              # Complete refactoring plan
+├── HOOK_LIBRARY_DOCS.md            # Hook documentation
+├── PHASE2_REFACTORING_SUMMARY.md   # This file
+├── src/
+│   ├── hooks/
+│   │   ├── core/
+│   │   │   ├── use-kv-state.ts
+│   │   │   ├── use-debounced-save.ts
+│   │   │   └── use-clipboard.ts
+│   │   ├── ui/
+│   │   │   ├── use-dialog.ts
+│   │   │   ├── use-selection.ts
+│   │   │   └── use-confirmation.ts
+│   │   └── config/
+│   │       ├── use-page-config.ts
+│   │       ├── use-layout-state.ts
+│   │       └── use-feature-flags.ts
+│   └── config/
+│       ├── page-schema.ts          # Zod schemas
+│       └── default-pages.json      # Page configurations
+```
+
+## Success Metrics
+
+- ✅ 9 reusable hooks created
+- ✅ JSON schema system implemented
+- ✅ 20 page configurations defined
+- ✅ Complete documentation written
+- ⏳ 0/5 large components split (next priority)
+- ⏳ 0/10 feature hooks created (after component splitting)
+- ⏳ PageOrchestrator not yet built (Phase 2.4)
+
+## Usage Examples
+
+### Using New Hooks
+
+```typescript
+// Simple dialog management
+const { open, openDialog, closeDialog } = useDialog()
+
+// Multi-select with full control
+const { selected, toggle, isSelected, count } = useSelection<string>()
+
+// Validated KV state
+const [user, setUser] = useKVState('user', defaultUser, UserSchema)
+
+// Load page config
+const { pageConfig } = usePageConfig('code-editor')
+
+// Feature flags
+const { isEnabled } = useFeatureFlags()
+if (isEnabled('ai-improve')) {
+  // Show AI features
+}
+```
+
+### Breaking Down Components
+
+**Old Pattern (Bad):**
+```typescript
+export function BigComponent() {
+  // 300+ lines of logic and JSX
+  const [data, setData] = useKV('data', [])
+  // 50 lines of business logic
+  return (
+    // 200 lines of JSX
+  )
+}
+```
+
+**New Pattern (Good):**
+```typescript
+// hooks/use-data-manager.ts
+export function useDataManager() {
+  const [data, setData] = useKV('data', [])
+  // All business logic here
+  return { data, addItem, removeItem, updateItem }
+}
+
+// components/DataList.tsx (80 LOC)
+export function DataList({ data, onSelect }) {
+  return <div>{/* Simple list UI */}</div>
+}
+
+// components/DataEditor.tsx (100 LOC)
+export function DataEditor({ item, onChange }) {
+  return <Card>{/* Simple editor UI */}</Card>
+}
+
+// BigComponent.tsx (90 LOC)
+export function BigComponent() {
+  const { data, addItem, removeItem } = useDataManager()
+  const [selected, setSelected] = useState(null)
+  
+  return (
+    <div className="flex gap-4">
+      <DataList data={data} onSelect={setSelected} />
+      {selected && <DataEditor item={selected} onChange={update} />}
+    </div>
+  )
+}
+```
+
+## Conclusion
+
+Phase 2 refactoring foundation is complete. The hook library and JSON configuration system provide a solid architecture for building maintainable, testable, and flexible components. The next priority is splitting the largest components to meet the <150 LOC requirement.
+
+**Status: Foundation Complete ✅ | Component Splitting In Progress ⏳**

docs/history/PHASE3_COMPLETE.md

@@ -0,0 +1,374 @@
+# Phase 3 Refactoring Complete: Hook Library & JSON Orchestration
+
+## 🎯 Mission Accomplished
+
+Successfully created a comprehensive refactoring infrastructure to reduce component complexity and improve maintainability through:
+
+1. **Hook Library** - Reusable business logic hooks
+2. **JSON Orchestration System** - Define pages with JSON schemas
+3. **Type-Safe Architecture** - Full TypeScript support
+4. **Component Size Enforcement** - All components under 150 LOC
+
+## 📦 What Was Created
+
+### 1. Hook Library (`/src/hooks/`)
+
+#### Data Management Hooks (`/data/`)
+- ✅ `use-files.ts` - Project file CRUD operations
+- ✅ `use-models.ts` - Prisma model management
+- ✅ `use-components.ts` - React component management
+- ✅ `use-workflows.ts` - Workflow management
+- ✅ `use-lambdas.ts` - Lambda function management
+
+#### Orchestration Hooks (`/orchestration/`)
+- ✅ `use-page.ts` - Execute page schemas
+- ✅ `use-actions.ts` - Action execution engine
+
+### 2. Type Definitions (`/src/types/`)
+
+- ✅ `page-schema.ts` - Complete TypeScript schemas for JSON orchestration
+  - PageSchema
+  - ComponentSchema
+  - DataSource
+  - ActionConfig
+  - HookConfig
+  - LayoutConfig
+  - DataBinding
+  - EventHandler
+
+### 3. Orchestration Components (`/src/components/orchestration/`)
+
+- ✅ `ComponentRenderer.tsx` - Renders components from JSON
+- ✅ `PageRenderer.tsx` - Renders entire pages from JSON schemas
+
+### 4. Example Page Schemas (`/src/config/pages/`)
+
+- ✅ `file-manager.json` - Split-view file manager example
+- ✅ `model-designer.json` - Model designer with AI generation
+
+### 5. Comprehensive Documentation
+
+- ✅ `REFACTOR_PHASE3.md` - Overall architecture plan
+- ✅ `JSON_ORCHESTRATION_GUIDE.md` - Complete JSON orchestration guide (10.6KB)
+- ✅ `HOOK_LIBRARY_REFERENCE.md` - Complete hook documentation (16.1KB)
+- ✅ `REFACTORING_EXAMPLE.md` - Step-by-step refactoring guide (14.5KB)
+
+## 🎨 Architecture Overview
+
+### Before Refactoring
+
+```
+App.tsx (800+ LOC)
+├── Inline state management
+├── Inline business logic
+├── Inline UI rendering
+└── Difficult to test/modify
+```
+
+### After Refactoring
+
+```
+App (150 LOC)
+├── Hooks (Business Logic)
+│   ├── useFiles()
+│   ├── useModels()
+│   └── useWorkflows()
+├── Components (<150 LOC each)
+│   ├── Toolbar
+│   ├── FileList
+│   └── Editor
+└── JSON Schemas (Optional)
+    ├── Layout config
+    ├── Component tree
+    ├── Data sources
+    └── Actions
+```
+
+## 🚀 Usage Examples
+
+### Using Data Hooks
+
+```typescript
+import { useFiles } from '@/hooks/data'
+
+function FileManager() {
+  const { files, addFile, updateFile, deleteFile } = useFiles()
+  
+  return (
+    <div>
+      {files.map(file => (
+        <div key={file.id}>{file.name}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+### Using JSON Orchestration
+
+```typescript
+import { PageRenderer } from '@/components/orchestration'
+import pageSchema from '@/config/pages/file-manager.json'
+
+function DynamicPage() {
+  return <PageRenderer schema={pageSchema} />
+}
+```
+
+### Creating Custom Hooks
+
+```typescript
+import { useFiles } from '@/hooks/data'
+import { useDialog } from '@/hooks/ui'
+
+function useFileEditor() {
+  const { files, updateFile } = useFiles()
+  const { isOpen, open, close } = useDialog()
+  
+  // Compose hooks to create custom functionality
+  return { files, isOpen, open, close, updateFile }
+}
+```
+
+## 📊 Benefits
+
+### 1. Component Size Reduction
+
+| Before | After |
+|--------|-------|
+| 500+ LOC monolithic components | <150 LOC focused components |
+| All logic in one file | Logic distributed across hooks |
+| Difficult to test | Easy to unit test |
+
+### 2. Reusability
+
+- Hooks can be used across multiple components
+- UI components are composable
+- Business logic is decoupled from UI
+
+### 3. Type Safety
+
+- Full TypeScript support
+- Compile-time error checking
+- Auto-completion in IDEs
+
+### 4. Maintainability
+
+- Single responsibility per file
+- Easy to locate bugs
+- Changes are isolated
+- New features don't affect existing code
+
+### 5. Testability
+
+```typescript
+// Test hooks independently
+describe('useFiles', () => {
+  it('should add file', () => {
+    const { result } = renderHook(() => useFiles())
+    act(() => result.current.addFile(mockFile))
+    expect(result.current.files).toHaveLength(1)
+  })
+})
+
+// Test components independently
+describe('FileList', () => {
+  it('should render files', () => {
+    const { getByText } = render(<FileList files={mockFiles} />)
+    expect(getByText('App.tsx')).toBeInTheDocument()
+  })
+})
+```
+
+## 🗺️ Migration Path
+
+### Phase 3.1: Infrastructure (✅ COMPLETE)
+- [x] Create hook library structure
+- [x] Create data management hooks
+- [x] Create orchestration hooks
+- [x] Create type definitions
+- [x] Create component renderers
+- [x] Create example schemas
+- [x] Write comprehensive documentation
+
+### Phase 3.2: Refactor Existing Components (Next Steps)
+
+Priority order based on complexity:
+
+1. **FeatureIdeaCloud** (500+ LOC)
+   - Extract `use-idea-manager.ts`
+   - Extract `use-idea-canvas.ts`
+   - Extract `use-idea-connections.ts`
+   - Create `IdeaNode.tsx`
+   - Create `IdeaToolbar.tsx`
+   - Refactor main component
+
+2. **WorkflowDesigner** (600+ LOC)
+   - Extract `use-workflow-state.ts`
+   - Extract `use-node-manager.ts`
+   - Create node components
+   - Refactor main component
+
+3. **ModelDesigner** (400+ LOC)
+   - Extract `use-model-state.ts`
+   - Extract `use-field-editor.ts`
+   - Create model card component
+   - Refactor main component
+
+4. **ComponentTreeManager** (350+ LOC)
+   - Extract `use-tree-state.ts`
+   - Create tree node components
+   - Refactor main component
+
+### Phase 3.3: JSON Schema Adoption (Future)
+
+Once components are refactored:
+1. Define JSON schemas for common pages
+2. Test schemas thoroughly
+3. Gradually migrate to schema-driven pages
+4. Build schema editor UI
+
+## 📚 Documentation Index
+
+All documentation is comprehensive and ready to use:
+
+1. **[REFACTOR_PHASE3.md](./REFACTOR_PHASE3.md)** - Architecture overview and plan
+2. **[JSON_ORCHESTRATION_GUIDE.md](./JSON_ORCHESTRATION_GUIDE.md)** - Complete guide to JSON schemas
+3. **[HOOK_LIBRARY_REFERENCE.md](./HOOK_LIBRARY_REFERENCE.md)** - All hooks documented with examples
+4. **[REFACTORING_EXAMPLE.md](./REFACTORING_EXAMPLE.md)** - Step-by-step refactoring guide
+
+## 🔧 Implementation Details
+
+### Hook Pattern
+
+All data hooks follow this pattern:
+
+```typescript
+export function useResource() {
+  const [items, setItems] = useKV<Item[]>('resource-key', [])
+  
+  const add = useCallback((item: Item) => {
+    setItems(current => [...current, item])
+  }, [setItems])
+  
+  const update = useCallback((id: string, updates: Partial<Item>) => {
+    setItems(current =>
+      current.map(item => item.id === id ? { ...item, ...updates } : item)
+    )
+  }, [setItems])
+  
+  const remove = useCallback((id: string) => {
+    setItems(current => current.filter(item => item.id !== id))
+  }, [setItems])
+  
+  return { items, add, update, remove }
+}
+```
+
+### JSON Schema Pattern
+
+All page schemas follow this structure:
+
+```json
+{
+  "id": "unique-id",
+  "name": "Page Name",
+  "layout": { "type": "single|split|tabs|grid" },
+  "components": [ /* component tree */ ],
+  "data": [ /* data sources */ ],
+  "actions": [ /* available actions */ ],
+  "hooks": [ /* custom hooks */ ]
+}
+```
+
+### Action Execution
+
+Actions are executed through the `useActions` hook:
+
+```typescript
+const { execute } = useActions(actions, context)
+
+// Execute by ID
+await execute('action-id', { param: 'value' })
+```
+
+## 🎯 Next Steps for Development
+
+### Immediate Actions
+
+1. **Start refactoring FeatureIdeaCloud**
+   - Use `REFACTORING_EXAMPLE.md` as guide
+   - Extract hooks first
+   - Then extract UI components
+   - Keep under 150 LOC per file
+
+2. **Test the hook library**
+   - Create unit tests for each hook
+   - Verify data persistence works
+   - Test edge cases
+
+3. **Validate JSON orchestration**
+   - Test example schemas
+   - Ensure PageRenderer works correctly
+   - Add more component types to ComponentRenderer
+
+### Medium-term Goals
+
+1. Refactor all major components using hooks
+2. Create JSON schemas for common pages
+3. Build schema editor for visual schema creation
+4. Add more hooks as needed
+
+### Long-term Vision
+
+1. All pages defined as JSON schemas
+2. Visual page builder using schema editor
+3. Runtime page loading from JSON
+4. User-customizable layouts
+
+## 🏆 Success Metrics
+
+- ✅ Hook library created with 5 data hooks
+- ✅ Orchestration system with 2 core hooks
+- ✅ Type-safe schema system with Zod validation
+- ✅ Component renderers for JSON execution
+- ✅ 2 example page schemas
+- ✅ 40KB+ of comprehensive documentation
+- ✅ Clear refactoring patterns established
+- ✅ Migration path defined
+
+## 🤝 Contributing
+
+When adding new hooks:
+1. Follow the established pattern
+2. Keep under 100 LOC
+3. Add TypeScript types
+4. Document in HOOK_LIBRARY_REFERENCE.md
+5. Create unit tests
+
+When creating new components:
+1. Keep under 150 LOC
+2. Extract logic to hooks
+3. Use composition over inheritance
+4. Add to component map if used in JSON
+
+## 📞 Support
+
+For questions about:
+- **Hook usage**: See HOOK_LIBRARY_REFERENCE.md
+- **JSON schemas**: See JSON_ORCHESTRATION_GUIDE.md
+- **Refactoring**: See REFACTORING_EXAMPLE.md
+- **Architecture**: See REFACTOR_PHASE3.md
+
+## 🎉 Conclusion
+
+The refactoring infrastructure is complete and ready for use. The codebase now has:
+
+- **Clear patterns** for extracting business logic
+- **Type-safe schemas** for page orchestration
+- **Comprehensive documentation** for all systems
+- **Practical examples** showing how to refactor
+
+All components can now be broken down into maintainable pieces under 150 LOC, with business logic extracted into reusable hooks and pages optionally defined as JSON schemas.
+
+**The foundation is laid. Time to refactor! 🚀**

docs/history/PHASE4_IMPLEMENTATION_COMPLETE.md

@@ -0,0 +1,412 @@
+# Phase 4 Refactoring: Complete Implementation Summary
+
+## 🎯 Mission Accomplished
+
+Successfully transformed CodeForge into a fully modular, JSON-driven architecture with comprehensive hook library and all components under 150 LOC.
+
+## 📊 What Was Delivered
+
+### 1. ✅ Comprehensive Hook Library
+
+**Location:** `/src/hooks/`
+
+#### Data Management Hooks (`/src/hooks/data/`)
+- ✅ **`useArray`** (64 LOC) - Enhanced array operations with persistence
+- ✅ **`useCRUD`** (73 LOC) - Complete CRUD operations for entities
+- ✅ **`useSearch`** (42 LOC) - Multi-field debounced search
+- ✅ **`useDebounce`** (17 LOC) - Generic value debouncing
+- ✅ **`useSort`** (48 LOC) - Multi-key sorting with direction toggle
+- ✅ **`usePagination`** (55 LOC) - Client-side pagination
+
+**Total: 6 hooks, ~300 LOC**
+
+#### UI State Hooks (`/src/hooks/ui/`)
+- ✅ **`useDialog`** (17 LOC) - Modal/dialog state management
+- ✅ **`useTabs`** (21 LOC) - Type-safe tab navigation
+- ✅ **`useSelection`** (56 LOC) - Multi-select state management
+- ✅ **`useClipboard`** (28 LOC) - Copy to clipboard with feedback
+
+**Total: 4 hooks, ~120 LOC**
+
+#### Form Hooks (`/src/hooks/forms/`)
+- ✅ **`useFormField`** (56 LOC) - Single field with validation
+- ✅ **`useForm`** (73 LOC) - Complete form management
+
+**Total: 2 hooks, ~130 LOC**
+
+#### Feature Hooks (Existing)
+- ✅ `use-feature-ideas.ts` (67 LOC)
+- ✅ `use-idea-groups.ts` (49 LOC)
+- ✅ `use-idea-connections.ts` (145 LOC)
+- ✅ `use-node-positions.ts` (40 LOC)
+
+**Grand Total: 16+ custom hooks, all under 150 LOC ✓**
+
+### 2. ✅ JSON Orchestration Engine
+
+**Location:** `/src/config/orchestration/`
+
+#### Core System Files
+1. **`schema.ts`** (71 LOC) - Complete TypeScript schema definitions
+   - PageSchema
+   - ComponentDef
+   - DataSource
+   - Action
+   - Layout
+   - Full Zod validation
+
+2. **`action-executor.ts`** (83 LOC) - Action execution engine
+   - Navigate actions
+   - CRUD actions (create, update, delete)
+   - API actions
+   - Transform actions
+   - Custom handlers
+   - Error handling
+
+3. **`data-source-manager.ts`** (67 LOC) - Data source management
+   - KV store integration
+   - API data fetching
+   - Static data
+   - Computed data sources
+   - Multi-source orchestration
+
+4. **`component-registry.ts`** (35 LOC) - Component registry
+   - Shadcn UI components
+   - Custom components
+   - Dynamic component resolution
+
+5. **`PageRenderer.tsx`** (69 LOC) - JSON-to-React renderer
+   - Schema interpretation
+   - Component tree rendering
+   - Data binding
+   - Event handling
+   - Action orchestration
+
+**Total: 5 core files, ~325 LOC**
+
+### 3. ✅ Example JSON Page Definitions
+
+**Location:** `/src/config/pages/`
+
+1. **`dashboard.json`** - JSON-driven dashboard
+   - Data source configuration
+   - Component tree
+   - Actions
+
+2. **`simple-form.json`** - Complete form example
+   - Form fields
+   - Validation
+   - Submit handling
+   - Full component hierarchy
+
+### 4. ✅ Comprehensive Documentation
+
+1. **`COMPLETE_HOOK_LIBRARY.md`** (8,546 chars)
+   - Complete API reference
+   - Usage examples
+   - Best practices
+   - Testing guidelines
+   - Composition patterns
+
+2. **`JSON_ORCHESTRATION_COMPLETE.md`** (14,771 chars)
+   - Architecture overview
+   - Schema specifications
+   - Complete examples
+   - Advanced patterns
+   - Migration strategy
+   - Debugging tips
+
+3. **`REFACTOR_PHASE4_COMPLETE.md`**
+   - Implementation summary
+   - Architecture principles
+   - Deliverables checklist
+
+## 🏗️ Architecture Overview
+
+```
+┌─────────────────────────────────────────────┐
+│           Application Layer                  │
+│  (Existing components gradually migrate)    │
+└────────────┬────────────────────────────────┘
+             │
+┌────────────▼────────────────────────────────┐
+│        JSON Orchestration Engine            │
+│                                              │
+│  ┌──────────────┐  ┌──────────────┐        │
+│  │ PageRenderer │  │ Component    │        │
+│  │              │  │ Registry     │        │
+│  └──────┬───────┘  └──────────────┘        │
+│         │                                    │
+│  ┌──────▼────────┐  ┌──────────────┐       │
+│  │ Data Source   │  │ Action       │       │
+│  │ Manager       │  │ Executor     │       │
+│  └───────────────┘  └──────────────┘       │
+└─────────────────────────────────────────────┘
+             │
+┌────────────▼────────────────────────────────┐
+│         Hook Library (12+ hooks)            │
+│                                              │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
+│  │   Data   │ │    UI    │ │  Forms   │   │
+│  │   Hooks  │ │  Hooks   │ │  Hooks   │   │
+│  └──────────┘ └──────────┘ └──────────┘   │
+└─────────────────────────────────────────────┘
+             │
+┌────────────▼────────────────────────────────┐
+│     Spark Runtime (KV, LLM, User)          │
+└─────────────────────────────────────────────┘
+```
+
+## 🎨 Design Principles Achieved
+
+### 1. Separation of Concerns ✓
+- **Hooks** = Business logic
+- **Components** = Presentation
+- **JSON** = Structure & configuration
+
+### 2. Component Size Limit ✓
+- All new hooks < 150 LOC
+- Orchestration files < 85 LOC
+- Focused, single-responsibility
+
+### 3. Type Safety ✓
+- Full TypeScript support
+- Zod schema validation
+- Runtime type checking
+
+### 4. Composability ✓
+- Hooks combine naturally
+- Actions chain together
+- Components nest recursively
+
+### 5. Testability ✓
+- Hooks testable in isolation
+- JSON schemas validate independently
+- Mock-friendly architecture
+
+## 📈 Benefits Realized
+
+### For Developers
+- **Faster development**: Reuse hooks across features
+- **Less code**: JSON replaces boilerplate React
+- **Better organization**: Clear structure and boundaries
+- **Easier debugging**: Small, focused units
+- **Type safety**: Catch errors at compile time
+
+### For the Application
+- **More maintainable**: Changes isolated to hooks or JSON
+- **More flexible**: New pages without new code
+- **More testable**: Small units easy to test
+- **Better performance**: Optimized re-renders
+- **Scalable**: Add features without complexity growth
+
+### For Users
+- **More reliable**: Tested, reusable components
+- **Faster**: Performance-optimized architecture
+- **Consistent**: Shared logic ensures consistency
+
+## 🚀 Usage Examples
+
+### Example 1: Using Hooks
+
+```typescript
+import { useArray, useSearch, useSort } from '@/hooks/data'
+import { useSelection, useDialog } from '@/hooks/ui'
+
+function ProductManager() {
+  const { items: products, add, remove } = useArray('products', [])
+  const { results, query, setQuery } = useSearch(products, ['name', 'category'])
+  const { sortedItems, toggleSort } = useSort(results, 'name')
+  const selection = useSelection()
+  const dialog = useDialog()
+  
+  return (
+    <div>
+      <Input value={query} onChange={(e) => setQuery(e.target.value)} />
+      {/* Rest of component */}
+    </div>
+  )
+}
+```
+
+### Example 2: JSON-Driven Page
+
+```json
+{
+  "id": "products",
+  "name": "Product Manager",
+  "layout": { "type": "single" },
+  "dataSources": [
+    {
+      "id": "products",
+      "type": "kv",
+      "key": "products-list",
+      "defaultValue": []
+    }
+  ],
+  "components": [
+    {
+      "id": "root",
+      "type": "Card",
+      "children": [/* ... */]
+    }
+  ],
+  "actions": [
+    {
+      "id": "add-product",
+      "type": "create",
+      "target": "products"
+    }
+  ]
+}
+```
+
+### Example 3: Hook Composition
+
+```typescript
+function useProductList() {
+  // Compose multiple hooks
+  const { items, add, remove, update } = useArray('products', [])
+  const { results, setQuery } = useSearch(items, ['name'])
+  const { sortedItems, toggleSort } = useSort(results, 'name')
+  const { items: paged, ...pagination } = usePagination(sortedItems, 10)
+  
+  return {
+    products: paged,
+    add,
+    remove,
+    update,
+    search: setQuery,
+    sort: toggleSort,
+    pagination,
+  }
+}
+```
+
+## 🔄 Migration Path
+
+### Phase 1: Setup (Done ✓)
+- [x] Create hook library structure
+- [x] Build orchestration engine
+- [x] Write documentation
+- [x] Create examples
+
+### Phase 2: Gradual Migration (Next Steps)
+1. Identify large components (>150 LOC)
+2. Extract business logic to hooks
+3. Convert static pages to JSON
+4. Test thoroughly
+5. Remove old code
+
+### Phase 3: Full Adoption
+- All new features use hooks + JSON
+- Existing features migrated iteratively
+- Complex logic in custom hooks
+- Simple pages in JSON
+
+## 📝 Key Files Reference
+
+### Hook Library
+```
+src/hooks/
+├── data/
+│   ├── use-array.ts          # Array operations
+│   ├── use-crud.ts           # CRUD operations
+│   ├── use-search.ts         # Search functionality
+│   ├── use-debounce.ts       # Debouncing
+│   ├── use-sort.ts           # Sorting
+│   ├── use-pagination.ts     # Pagination
+│   └── index.ts              # Exports
+├── ui/
+│   ├── use-dialog.ts         # Dialog state
+│   ├── use-tabs.ts           # Tab navigation
+│   ├── use-selection.ts      # Selection state
+│   ├── use-clipboard.ts      # Clipboard operations
+│   └── index.ts              # Exports
+└── forms/
+    ├── use-form.ts           # Form management
+    ├── use-form-field.ts     # Field validation
+    └── index.ts              # Exports
+```
+
+### Orchestration Engine
+```
+src/config/orchestration/
+├── schema.ts                 # TypeScript schemas
+├── action-executor.ts        # Action engine
+├── data-source-manager.ts    # Data management
+├── component-registry.ts     # Component lookup
+├── PageRenderer.tsx          # Main renderer
+└── index.ts                  # Exports
+```
+
+### Example Pages
+```
+src/config/pages/
+├── dashboard.json            # Dashboard example
+└── simple-form.json          # Form example
+```
+
+### Documentation
+```
+/
+├── COMPLETE_HOOK_LIBRARY.md           # Hook API reference
+├── JSON_ORCHESTRATION_COMPLETE.md     # Orchestration guide
+└── REFACTOR_PHASE4_COMPLETE.md        # This file
+```
+
+## ✨ Next Steps
+
+### Immediate
+1. ✅ Hook library created
+2. ✅ Orchestration engine built
+3. ✅ Documentation written
+4. ✅ Examples provided
+
+### Short Term
+1. Migrate 1-2 existing components to hooks
+2. Create JSON page for a simple feature
+3. Test with real data
+4. Gather feedback
+
+### Long Term
+1. Migrate all components to use hooks
+2. Convert static pages to JSON
+3. Build visual JSON editor
+4. Add schema hot-reloading
+5. Performance profiling
+
+## 🎉 Success Metrics
+
+- ✅ **16+ custom hooks** created
+- ✅ **All hooks < 150 LOC**
+- ✅ **Complete orchestration engine** built
+- ✅ **Full type safety** with TypeScript & Zod
+- ✅ **Comprehensive documentation** (23,000+ chars)
+- ✅ **Working examples** provided
+- ✅ **Zero breaking changes** to existing code
+- ✅ **Backward compatible** architecture
+
+## 🔥 Highlights
+
+1. **Modular by Design**: Every piece is replaceable
+2. **Type-Safe**: Full TypeScript + Zod validation
+3. **Testable**: Small units, easy to test
+4. **Documented**: Extensive guides and examples
+5. **Production Ready**: Battle-tested patterns
+6. **Future Proof**: Easy to extend and maintain
+
+## 📚 Learn More
+
+- Read `COMPLETE_HOOK_LIBRARY.md` for hook usage
+- Read `JSON_ORCHESTRATION_COMPLETE.md` for JSON pages
+- Check `/src/config/pages/` for examples
+- Explore `/src/hooks/` for implementations
+
+---
+
+**Status**: ✅ **COMPLETE**
+**Date**: 2024
+**Version**: 4.0.0
+**Breaking Changes**: None
+**Migration Required**: Optional (gradual)

docs/history/REFACTORING_EXAMPLE.md

@@ -0,0 +1,575 @@
+# Refactoring Example: Breaking Down Large Components
+
+This guide demonstrates how to refactor a monolithic component (FeatureIdeaCloud, ~500 LOC) into smaller, maintainable pieces using the hook library and JSON orchestration.
+
+## Before: Monolithic Component (500+ LOC)
+
+The original `FeatureIdeaCloud.tsx` contains:
+- State management for ideas, groups, and connections
+- ReactFlow canvas logic
+- Dialog management for creating/editing ideas
+- AI generation logic
+- Connection validation
+- All UI rendering
+
+**Problems:**
+- Hard to test individual pieces
+- Difficult to modify without breaking other parts
+- Can't reuse logic in other components
+- Takes time to understand the entire component
+
+## After: Modular Architecture (<150 LOC each)
+
+### Step 1: Extract Data Management Hook
+
+```typescript
+// src/hooks/feature-ideas/use-idea-manager.ts (60 LOC)
+import { useKV } from '@github/spark/hooks'
+import { useCallback } from 'react'
+
+export interface FeatureIdea {
+  id: string
+  title: string
+  description: string
+  category: string
+  priority: 'low' | 'medium' | 'high'
+  status: 'idea' | 'planned' | 'in-progress' | 'completed'
+  createdAt: number
+  parentGroup?: string
+}
+
+export interface IdeaGroup {
+  id: string
+  label: string
+  color: string
+  createdAt: number
+}
+
+export interface IdeaConnection {
+  id: string
+  from: string
+  to: string
+  createdAt: number
+}
+
+export function useIdeaManager() {
+  const [ideas, setIdeas] = useKV<FeatureIdea[]>('feature-ideas', [])
+  const [groups, setGroups] = useKV<IdeaGroup[]>('idea-groups', [])
+  const [connections, setConnections] = useKV<IdeaConnection[]>('idea-connections', [])
+  
+  const addIdea = useCallback((idea: FeatureIdea) => {
+    setIdeas(current => [...current, idea])
+  }, [setIdeas])
+  
+  const updateIdea = useCallback((id: string, updates: Partial<FeatureIdea>) => {
+    setIdeas(current => 
+      current.map(idea => idea.id === id ? { ...idea, ...updates } : idea)
+    )
+  }, [setIdeas])
+  
+  const deleteIdea = useCallback((id: string) => {
+    setIdeas(current => current.filter(idea => idea.id !== id))
+    setConnections(current => 
+      current.filter(conn => conn.from !== id && conn.to !== id)
+    )
+  }, [setIdeas, setConnections])
+  
+  return {
+    ideas,
+    groups,
+    connections,
+    addIdea,
+    updateIdea,
+    deleteIdea,
+  }
+}
+```
+
+### Step 2: Extract Canvas Hook
+
+```typescript
+// src/hooks/feature-ideas/use-idea-canvas.ts (80 LOC)
+import { useNodesState, useEdgesState, Node, Edge } from 'reactflow'
+import { useCallback, useEffect } from 'react'
+import { FeatureIdea, IdeaConnection } from './use-idea-manager'
+
+export function useIdeaCanvas(ideas: FeatureIdea[], connections: IdeaConnection[]) {
+  const [nodes, setNodes, onNodesChange] = useNodesState([])
+  const [edges, setEdges, onEdgesChange] = useEdgesState([])
+  
+  useEffect(() => {
+    const newNodes: Node[] = ideas.map(idea => ({
+      id: idea.id,
+      type: 'ideaNode',
+      position: { x: 0, y: 0 },
+      data: { idea }
+    }))
+    setNodes(newNodes)
+  }, [ideas, setNodes])
+  
+  useEffect(() => {
+    const newEdges: Edge[] = connections.map(conn => ({
+      id: conn.id,
+      source: conn.from,
+      target: conn.to,
+      type: 'smoothstep'
+    }))
+    setEdges(newEdges)
+  }, [connections, setEdges])
+  
+  const updateNodePosition = useCallback((nodeId: string, position: { x: number; y: number }) => {
+    setNodes(current =>
+      current.map(node =>
+        node.id === nodeId ? { ...node, position } : node
+      )
+    )
+  }, [setNodes])
+  
+  return {
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange,
+    updateNodePosition
+  }
+}
+```
+
+### Step 3: Extract Connection Logic Hook
+
+```typescript
+// src/hooks/feature-ideas/use-idea-connections.ts (70 LOC)
+import { useCallback } from 'react'
+import { Connection as RFConnection } from 'reactflow'
+import { IdeaConnection } from './use-idea-manager'
+
+export function useIdeaConnections(
+  connections: IdeaConnection[],
+  onAdd: (conn: IdeaConnection) => void,
+  onRemove: (id: string) => void
+) {
+  const canConnect = useCallback((from: string, to: string) => {
+    if (from === to) return false
+    
+    const existingConnection = connections.find(
+      conn => conn.from === from && conn.to === to
+    )
+    
+    return !existingConnection
+  }, [connections])
+  
+  const addConnection = useCallback((connection: RFConnection) => {
+    if (!canConnect(connection.source, connection.target)) {
+      return false
+    }
+    
+    const newConnection: IdeaConnection = {
+      id: `${connection.source}-${connection.target}`,
+      from: connection.source,
+      to: connection.target,
+      createdAt: Date.now()
+    }
+    
+    onAdd(newConnection)
+    return true
+  }, [canConnect, onAdd])
+  
+  const removeConnection = useCallback((id: string) => {
+    onRemove(id)
+  }, [onRemove])
+  
+  return {
+    canConnect,
+    addConnection,
+    removeConnection
+  }
+}
+```
+
+### Step 4: Create Small UI Components
+
+```typescript
+// src/components/feature-ideas/IdeaNode.tsx (50 LOC)
+import { memo } from 'react'
+import { Handle, Position } from 'reactflow'
+import { Card } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { FeatureIdea } from '@/hooks/feature-ideas/use-idea-manager'
+
+interface IdeaNodeProps {
+  idea: FeatureIdea
+  onEdit: () => void
+  onDelete: () => void
+}
+
+export const IdeaNode = memo(({ idea, onEdit, onDelete }: IdeaNodeProps) => {
+  return (
+    <Card className="p-3 min-w-[200px]">
+      <Handle type="target" position={Position.Left} />
+      
+      <div className="flex items-start justify-between gap-2 mb-2">
+        <h3 className="font-semibold text-sm">{idea.title}</h3>
+        <Badge variant={getPriorityVariant(idea.priority)}>
+          {idea.priority}
+        </Badge>
+      </div>
+      
+      <p className="text-xs text-muted-foreground mb-2">
+        {idea.description}
+      </p>
+      
+      <div className="flex gap-1">
+        <button onClick={onEdit} className="text-xs">Edit</button>
+        <button onClick={onDelete} className="text-xs text-destructive">
+          Delete
+        </button>
+      </div>
+      
+      <Handle type="source" position={Position.Right} />
+    </Card>
+  )
+})
+
+function getPriorityVariant(priority: string) {
+  switch (priority) {
+    case 'high': return 'destructive'
+    case 'medium': return 'default'
+    default: return 'secondary'
+  }
+}
+```
+
+```typescript
+// src/components/feature-ideas/IdeaToolbar.tsx (40 LOC)
+import { Button } from '@/components/ui/button'
+import { Plus, Sparkle } from '@phosphor-icons/react'
+
+interface IdeaToolbarProps {
+  onAddIdea: () => void
+  onGenerateAI: () => void
+  ideaCount: number
+}
+
+export function IdeaToolbar({ onAddIdea, onGenerateAI, ideaCount }: IdeaToolbarProps) {
+  return (
+    <div className="flex items-center justify-between p-4 border-b">
+      <div>
+        <h2 className="text-lg font-semibold">Feature Ideas</h2>
+        <p className="text-sm text-muted-foreground">
+          {ideaCount} ideas
+        </p>
+      </div>
+      
+      <div className="flex gap-2">
+        <Button onClick={onAddIdea} variant="outline">
+          <Plus className="mr-2" size={16} />
+          Add Idea
+        </Button>
+        <Button onClick={onGenerateAI}>
+          <Sparkle className="mr-2" size={16} />
+          AI Generate
+        </Button>
+      </div>
+    </div>
+  )
+}
+```
+
+### Step 5: Compose Main Component
+
+```typescript
+// src/components/FeatureIdeaCloud.tsx (120 LOC)
+import ReactFlow, { Background, Controls } from 'reactflow'
+import 'reactflow/dist/style.css'
+import { useIdeaManager } from '@/hooks/feature-ideas/use-idea-manager'
+import { useIdeaCanvas } from '@/hooks/feature-ideas/use-idea-canvas'
+import { useIdeaConnections } from '@/hooks/feature-ideas/use-idea-connections'
+import { useDialog } from '@/hooks/ui/use-dialog'
+import { IdeaNode } from './feature-ideas/IdeaNode'
+import { IdeaToolbar } from './feature-ideas/IdeaToolbar'
+import { IdeaDialog } from './feature-ideas/IdeaDialog'
+
+const nodeTypes = {
+  ideaNode: IdeaNode
+}
+
+export function FeatureIdeaCloud() {
+  const {
+    ideas,
+    connections,
+    addIdea,
+    updateIdea,
+    deleteIdea
+  } = useIdeaManager()
+  
+  const {
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange
+  } = useIdeaCanvas(ideas, connections)
+  
+  const {
+    addConnection,
+    removeConnection
+  } = useIdeaConnections(connections, addIdea, deleteIdea)
+  
+  const { isOpen, open, close } = useDialog()
+  
+  return (
+    <div className="h-full flex flex-col">
+      <IdeaToolbar
+        onAddIdea={open}
+        onGenerateAI={handleAIGenerate}
+        ideaCount={ideas.length}
+      />
+      
+      <div className="flex-1">
+        <ReactFlow
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={addConnection}
+          nodeTypes={nodeTypes}
+        >
+          <Background />
+          <Controls />
+        </ReactFlow>
+      </div>
+      
+      <IdeaDialog
+        open={isOpen}
+        onClose={close}
+        onSave={addIdea}
+      />
+    </div>
+  )
+}
+
+async function handleAIGenerate() {
+  // AI generation logic
+}
+```
+
+### Step 6: Define as JSON (Optional)
+
+```json
+{
+  "id": "feature-idea-cloud",
+  "name": "Feature Idea Cloud",
+  "description": "Visual brainstorming canvas for features",
+  "layout": {
+    "type": "single"
+  },
+  "components": [
+    {
+      "id": "toolbar",
+      "type": "IdeaToolbar",
+      "bindings": [
+        {
+          "source": "ideas.length",
+          "target": "ideaCount"
+        }
+      ],
+      "events": [
+        {
+          "event": "onAddIdea",
+          "action": "open-dialog"
+        },
+        {
+          "event": "onGenerateAI",
+          "action": "ai-generate-ideas"
+        }
+      ]
+    },
+    {
+      "id": "canvas",
+      "type": "IdeaCanvas",
+      "bindings": [
+        {
+          "source": "ideas",
+          "target": "ideas"
+        },
+        {
+          "source": "connections",
+          "target": "connections"
+        }
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "id": "ideas",
+      "name": "useIdeaManager",
+      "exports": ["ideas", "connections", "addIdea", "updateIdea", "deleteIdea"]
+    },
+    {
+      "id": "dialog",
+      "name": "useDialog",
+      "exports": ["isOpen", "open", "close"]
+    }
+  ],
+  "actions": [
+    {
+      "id": "open-dialog",
+      "type": "custom",
+      "handler": "open"
+    },
+    {
+      "id": "ai-generate-ideas",
+      "type": "ai-generate",
+      "params": {
+        "prompt": "Generate 5 creative feature ideas for a project management tool",
+        "target": "Ideas"
+      }
+    }
+  ]
+}
+```
+
+## Benefits Achieved
+
+### 1. Component Size Reduction
+
+| Component | Before | After |
+|-----------|--------|-------|
+| FeatureIdeaCloud | 500 LOC | 120 LOC |
+| Hooks | 0 | 210 LOC (3 files) |
+| UI Components | 0 | 90 LOC (2 files) |
+
+### 2. Testability
+
+```typescript
+// Easy to test individual hooks
+describe('useIdeaManager', () => {
+  it('should add idea', () => {
+    const { result } = renderHook(() => useIdeaManager())
+    act(() => {
+      result.current.addIdea(mockIdea)
+    })
+    expect(result.current.ideas).toHaveLength(1)
+  })
+})
+
+// Easy to test UI components
+describe('IdeaNode', () => {
+  it('should call onEdit when edit clicked', () => {
+    const onEdit = jest.fn()
+    const { getByText } = render(<IdeaNode idea={mockIdea} onEdit={onEdit} />)
+    fireEvent.click(getByText('Edit'))
+    expect(onEdit).toHaveBeenCalled()
+  })
+})
+```
+
+### 3. Reusability
+
+```typescript
+// Use the same hooks in different contexts
+function IdeaList() {
+  const { ideas, updateIdea } = useIdeaManager()
+  return <div>{/* List view instead of canvas */}</div>
+}
+
+function IdeaKanban() {
+  const { ideas, updateIdea } = useIdeaManager()
+  return <div>{/* Kanban board view */}</div>
+}
+```
+
+### 4. Maintainability
+
+- Each file has a single responsibility
+- Easy to locate and fix bugs
+- Changes to canvas don't affect data management
+- New features can be added without touching existing code
+
+### 5. Type Safety
+
+- Shared types between hooks and components
+- Auto-completion in IDE
+- Compile-time error checking
+
+## Migration Strategy
+
+### Phase 1: Extract Hooks (Don't break existing code)
+
+1. Create new hook files
+2. Copy logic from component to hooks
+3. Test hooks independently
+4. Keep original component working
+
+### Phase 2: Refactor Component
+
+1. Replace inline logic with hook calls
+2. Test that behavior is identical
+3. Remove commented-out old code
+
+### Phase 3: Extract UI Components
+
+1. Identify reusable UI patterns
+2. Create small components
+3. Replace inline JSX with components
+
+### Phase 4: Create JSON Schema (Optional)
+
+1. Define page schema for dynamic loading
+2. Test schema with PageRenderer
+3. Switch to schema-driven approach
+
+## Additional Examples
+
+### Example: Breaking Down ModelDesigner
+
+**Before:** 400 LOC monolithic component
+
+**After:**
+- `use-model-state.ts` (50 LOC) - Model data management
+- `use-field-editor.ts` (40 LOC) - Field editing logic
+- `use-relation-builder.ts` (45 LOC) - Relation logic
+- `ModelCard.tsx` (60 LOC) - Individual model display
+- `FieldList.tsx` (50 LOC) - Field list UI
+- `RelationGraph.tsx` (80 LOC) - Visual relation graph
+- `ModelDesigner.tsx` (130 LOC) - Main orchestration
+
+**Total:** 455 LOC across 7 files (vs 400 LOC in 1 file)
+**Benefit:** Each piece is testable and reusable
+
+### Example: Breaking Down WorkflowDesigner
+
+**Before:** 600 LOC monolithic component
+
+**After:**
+- `use-workflow-state.ts` (55 LOC)
+- `use-node-manager.ts` (60 LOC)
+- `use-workflow-canvas.ts` (75 LOC)
+- `WorkflowNode.tsx` (80 LOC)
+- `NodeConfig.tsx` (90 LOC)
+- `WorkflowToolbar.tsx` (50 LOC)
+- `WorkflowDesigner.tsx` (140 LOC)
+
+**Total:** 550 LOC across 7 files
+**Benefit:** Canvas logic separated from node configuration
+
+## Checklist for Refactoring
+
+- [ ] Identify data management logic → Extract to hook
+- [ ] Identify UI state logic → Extract to hook
+- [ ] Identify reusable UI patterns → Extract to components
+- [ ] Ensure all pieces are under 150 LOC
+- [ ] Write tests for hooks
+- [ ] Write tests for components
+- [ ] Document hook APIs
+- [ ] Create JSON schema if applicable
+- [ ] Update imports in dependent files
+- [ ] Remove old code
+
+## Next Steps
+
+1. Start with the largest components first
+2. Use this pattern as a template
+3. Create additional hooks as needed
+4. Build a library of reusable UI components
+5. Define common pages as JSON schemas
+6. Document all new hooks and components

docs/history/REFACTORING_LOG.md

@@ -0,0 +1,166 @@
+# Hook Library Refactoring - Completed
+
+## Overview
+This document tracks the comprehensive refactoring to create a robust hook library and break down large components into manageable pieces under 150 lines of code.
+
+## New Hooks Created ✅
+
+### State Management
+- ✅ `use-project-state.ts` - Centralized project state management with useKV (reduces 200+ lines of state declarations)
+- ✅ `use-file-operations.ts` - File CRUD operations (encapsulates file management logic)
+- ✅ `use-active-selection.ts` - Generic active selection management for lists with navigation
+- ✅ `use-last-saved.ts` - Track last saved timestamp automatically
+
+### Dialog & UI State
+- ✅ `use-dialog-state.ts` - Single and multiple dialog management with open/close/toggle
+- ✅ `use-tab-navigation.ts` - Tab navigation with URL query support
+
+### AI Operations
+- ✅ `use-ai-operations.ts` - AI service operations (improve, explain, generate) with loading states
+- ✅ `use-code-explanation.ts` - Code explanation dialog state management
+
+### Project Operations
+- ✅ `use-project-export.ts` - Project export and ZIP download with all file generation
+- ✅ `use-project-loader.ts` - Load project from JSON with all state updates
+
+### Utilities
+- ✅ `use-file-filters.ts` - File filtering and search operations
+- ✅ `hooks/index.ts` - Centralized export of all hooks
+
+## Component Molecules Created ✅
+
+### CodeEditor Sub-components
+- ✅ `FileTabs.tsx` (37 lines) - File tab bar with close buttons
+- ✅ `EditorActions.tsx` (31 lines) - Editor action buttons (Explain, Improve)
+- ✅ `EditorToolbar.tsx` (43 lines) - Complete editor toolbar composition
+- ✅ `MonacoEditorPanel.tsx` (27 lines) - Monaco editor wrapper with configuration
+- ✅ `EmptyEditorState.tsx` (13 lines) - Empty state display for no files
+- ✅ `CodeExplanationDialog.tsx` (52 lines) - AI explanation dialog with loading state
+- ✅ `molecules/index.ts` - Centralized export of all molecules (preserving existing ones)
+
+## Components Refactored ✅
+- ✅ `CodeEditor.tsx` - Reduced from 195 to 88 lines (55% reduction) using new hooks and molecules
+
+##  Architecture Improvements
+
+### Before Refactoring
+- Large components with 200-800+ lines
+- Mixed concerns (state, UI, logic)
+- Difficult to test individual pieces
+- Code duplication across components
+- Hard to modify without breaking things
+
+### After Refactoring
+- Small, focused components (<150 LOC)
+- Separated concerns using hooks
+- Each piece independently testable
+- Reusable hooks across components
+- Safer to make changes
+
+## Hook Benefits
+
+### Reusability
+All hooks can be composed and reused:
+```tsx
+// Any component can now use:
+const projectState = useProjectState()
+const fileOps = useFileOperations(projectState.files, projectState.setFiles)
+const { isOpen, open, close } = useDialogState()
+```
+
+### Type Safety
+Hooks maintain full TypeScript support with proper inference
+
+### Performance
+- Smaller components re-render less
+- Hooks enable better memoization opportunities
+- Isolated state updates
+
+## Next Steps for Full Refactoring
+
+### High Priority (Large Components)
+1. ModelDesigner.tsx - Break into ModelList, ModelForm, FieldEditor
+2. ComponentTreeBuilder.tsx - Split into TreeCanvas, NodePalette, NodeEditor
+3. WorkflowDesigner.tsx - Separate into WorkflowCanvas, StepEditor, ConnectionPanel
+4. FlaskDesigner.tsx - Split into BlueprintList, RouteEditor, ConfigPanel
+
+### Medium Priority  
+5. ProjectDashboard.tsx - Create StatsGrid, QuickActions, RecentActivity
+6. GlobalSearch.tsx - Split into SearchInput, ResultsList, ResultItem
+7. ErrorPanel.tsx - Create ErrorList, ErrorDetail, AutoFixPanel
+
+### Additional Hooks Needed
+- `use-model-operations.ts` - Model CRUD with validation
+- `use-workflow-builder.ts` - Workflow canvas management
+- `use-tree-builder.ts` - Component tree operations
+- `use-form-state.ts` - Generic form state with validation
+- `use-debounced-save.ts` - Auto-save with debouncing
+
+## Testing Strategy
+1. Unit test each hook independently
+2. Test molecule components in isolation
+3. Integration tests for hook composition
+4. E2E tests remain unchanged
+
+## Migration Guidelines
+
+### For Future Component Refactoring
+1. **Identify state logic** → Extract to custom hooks
+2. **Find UI patterns** → Extract to molecule components
+3. **Keep parent < 150 lines** → Split if needed
+4. **Test extracted pieces** → Ensure no regression
+5. **Update documentation** → Document new APIs
+
+### Example Pattern
+```tsx
+// Before: 300-line component
+function BigComponent() {
+  const [state1, setState1] = useState()
+  const [state2, setState2] = useState()
+  // 50 lines of complex logic
+  // 200 lines of JSX
+}
+
+// After: 80-line component
+function BigComponent() {
+  const logic = useComponentLogic()
+  return (
+    <ComponentLayout>
+      <ComponentHeader {...logic.headerProps} />
+      <ComponentBody {...logic.bodyProps} />
+      <ComponentFooter {...logic.footerProps} />
+    </ComponentLayout>
+  )
+}
+```
+
+## Metrics
+
+### Code Quality Improvements
+- **Average component size**: Reduced by ~40-60%
+- **Reusable hooks**: 11 created
+- **Reusable molecules**: 6 new (19 total)
+- **Test coverage**: Easier to achieve with smaller units
+- **Maintenance risk**: Significantly reduced
+
+### Developer Experience
+- ✅ Faster to locate specific functionality  
+- ✅ Easier to onboard new developers
+- ✅ Less cognitive load per file
+- ✅ Clear separation of concerns
+- ✅ Better IDE autocomplete and navigation
+
+##  Success Criteria Met
+- ✅ Created comprehensive hook library
+- ✅ All hooks properly typed
+- ✅ CodeEditor refactored successfully
+- ✅ Components under 150 LOC  
+- ✅ No functionality lost
+- ✅ Improved code organization
+- ✅ Ready for continued refactoring
+
+## Conclusion
+
+The hook library foundation is now in place, making future refactoring safer and faster. The CodeEditor serves as a template for refactoring other large components. Each subsequent refactoring will be easier as we build up our library of reusable hooks and molecules.
+
+**Refactoring is now significantly less risky** - we can confidently continue breaking down large components using the established patterns.

docs/history/REFACTORING_PLAN.md

@@ -0,0 +1,164 @@
+# Comprehensive Refactoring Plan
+
+## Overview
+CodeForge has grown to include 44 iterations of features, resulting in component files exceeding 150 LOC and duplicated logic. This plan establishes a systematic refactoring approach to create a maintainable, scalable architecture.
+
+## Goals
+1. ✅ All components < 150 LOC
+2. ✅ Custom hooks library for shared logic
+3. ✅ JSON-driven page orchestration
+4. ✅ Atomic component design pattern
+5. ✅ Type-safe architecture
+6. ✅ Zero breaking changes to existing features
+
+## Phase 1: Hook Extraction Library
+
+### Core Hooks to Extract
+- `use-feature-ideas.ts` - Feature idea CRUD + state management
+- `use-idea-connections.ts` - Edge/connection validation & 1:1 mapping
+- `use-reactflow-integration.ts` - ReactFlow nodes/edges state
+- `use-idea-groups.ts` - Group management logic
+- `use-ai-generation.ts` - AI-powered generation
+- `use-form-dialog.ts` - Generic form dialog state
+- `use-node-positions.ts` - Node position persistence
+
+### Hook Organization
+```
+src/hooks/
+├── feature-ideas/
+│   ├── use-feature-ideas.ts
+│   ├── use-idea-connections.ts
+│   ├── use-idea-groups.ts
+│   └── index.ts
+├── reactflow/
+│   ├── use-reactflow-integration.ts
+│   ├── use-node-positions.ts
+│   ├── use-connection-validation.ts
+│   └── index.ts
+├── dialogs/
+│   ├── use-form-dialog.ts
+│   ├── use-confirmation-dialog.ts
+│   └── index.ts
+└── ai/
+    ├── use-ai-generation.ts
+    ├── use-ai-suggestions.ts
+    └── index.ts
+```
+
+## Phase 2: Atomic Component Breakdown
+
+### FeatureIdeaCloud Component Tree
+Current: 1555 LOC → Target: Multiple components < 150 LOC each
+
+```
+FeatureIdeaCloud/ (orchestrator - 80 LOC)
+├── nodes/
+│   ├── IdeaNode.tsx (120 LOC)
+│   ├── GroupNode.tsx (80 LOC)
+│   └── NodeHandles.tsx (60 LOC)
+├── dialogs/
+│   ├── IdeaEditDialog.tsx (140 LOC)
+│   ├── IdeaViewDialog.tsx (100 LOC)
+│   ├── GroupEditDialog.tsx (120 LOC)
+│   ├── EdgeEditDialog.tsx (90 LOC)
+│   └── DebugPanel.tsx (140 LOC)
+├── panels/
+│   ├── ToolbarPanel.tsx (80 LOC)
+│   ├── HelpPanel.tsx (60 LOC)
+│   └── DebugPanel.tsx (moved above)
+└── utils/
+    ├── connection-validator.ts (100 LOC)
+    └── constants.ts (50 LOC)
+```
+
+## Phase 3: JSON Page Configuration
+
+### Configuration Format
+```json
+{
+  "pages": [
+    {
+      "id": "dashboard",
+      "title": "Dashboard",
+      "icon": "ChartBar",
+      "component": "ProjectDashboard",
+      "enabled": true,
+      "shortcut": "ctrl+1"
+    },
+    {
+      "id": "ideas",
+      "title": "Feature Ideas",
+      "icon": "Lightbulb",
+      "component": "FeatureIdeaCloud",
+      "enabled": true,
+      "toggleKey": "ideaCloud",
+      "shortcut": "ctrl+i"
+    }
+  ]
+}
+```
+
+### Page Orchestrator
+```typescript
+// src/config/pages.json - Configuration
+// src/lib/page-loader.ts - Dynamic loader
+// src/components/PageOrchestrator.tsx - Runtime renderer
+```
+
+## Phase 4: Component Size Audit
+
+### Components Requiring Refactoring
+1. **FeatureIdeaCloud.tsx** - 1555 LOC → 8 components
+2. **App.tsx** - 826 LOC → Split orchestration
+3. **CodeEditor.tsx** - Check size
+4. **ComponentTreeBuilder.tsx** - Check size
+5. **WorkflowDesigner.tsx** - Check size
+
+## Phase 5: Type Safety
+
+### Centralized Types
+```
+src/types/
+├── feature-ideas.ts
+├── projects.ts
+├── components.ts
+├── workflows.ts
+└── common.ts
+```
+
+## Implementation Order
+
+### Step 1: Create Hook Library (This Session)
+- Extract all FeatureIdeaCloud hooks
+- Extract generic dialog hooks
+- Test in isolation
+
+### Step 2: Break Down FeatureIdeaCloud (This Session)
+- Create atomic components
+- Maintain feature parity
+- Test all features work
+
+### Step 3: JSON Page Config (This Session)
+- Define page schema
+- Create loader utilities
+- Wire up to App.tsx
+
+### Step 4: Verify & Test (This Session)
+- All components < 150 LOC ✓
+- All features functional ✓
+- Performance maintained ✓
+
+## Success Metrics
+- ✅ No component > 150 LOC
+- ✅ No duplicated logic
+- ✅ All features work identically
+- ✅ Type safety maintained
+- ✅ Performance improved
+- ✅ Developer velocity increased
+
+## Notes
+- Preserve all existing functionality
+- Maintain backward compatibility
+- Keep user experience identical
+- Improve developer experience
+- Enable future scalability

docs/history/REFACTORING_SUMMARY.md

@@ -0,0 +1,230 @@
+# Refactoring Implementation Summary
+
+## What Was Accomplished
+
+### 1. ✅ Hook Library Created
+Created a comprehensive custom hooks library to extract business logic from components:
+
+**Location:** `/src/hooks/feature-ideas/`
+
+#### New Hooks:
+- **`use-feature-ideas.ts`** (67 LOC)
+  - Manages feature idea CRUD operations
+  - Handles persistence with useKV
+  - Exports: `useFeatureIdeas()`
+
+- **`use-idea-groups.ts`** (49 LOC)
+  - Manages idea group CRUD operations
+  - Group color and label management
+  - Exports: `useIdeaGroups()`
+
+- **`use-idea-connections.ts`** (145 LOC)
+  - Handles edge/connection validation
+  - Enforces 1:1 handle mapping constraint
+  - Auto-remapping logic for conflicts
+  - Exports: `useIdeaConnections()`
+
+- **`use-node-positions.ts`** (40 LOC)
+  - Manages ReactFlow node position persistence
+  - Batch and single position updates
+  - Exports: `useNodePositions()`
+
+#### Benefits:
+- ✅ All hooks < 150 LOC
+- ✅ Reusable across components
+- ✅ Testable in isolation
+- ✅ Type-safe with TypeScript
+- ✅ Consistent API patterns
+
+### 2. ✅ JSON Page Orchestration System
+
+**Location:** `/src/config/`
+
+#### Files Created:
+- **`pages.json`** - Declarative page configuration
+  - 20 pages defined with metadata
+  - Icons, shortcuts, feature toggles
+  - Order and enablement rules
+
+- **`page-loader.ts`** - Runtime utilities
+  - `getPageConfig()` - Load all pages
+  - `getPageById(id)` - Get specific page
+  - `getEnabledPages(toggles)` - Filter by feature flags
+  - `getPageShortcuts(toggles)` - Extract keyboard shortcuts
+
+#### Page Configuration Format:
+```json
+{
+  "id": "ideas",
+  "title": "Feature Ideas",
+  "icon": "Lightbulb",
+  "component": "FeatureIdeaCloud",
+  "enabled": true,
+  "toggleKey": "ideaCloud",
+  "shortcut": "ctrl+i",
+  "order": 10
+}
+```
+
+#### Benefits:
+- ✅ Single source of truth for pages
+- ✅ Easy to add/remove/reorder pages
+- ✅ No code changes for page configuration
+- ✅ Type-safe with TypeScript interfaces
+- ✅ Automatic shortcut extraction
+
+### 3. ✅ Atomic Component Foundation
+
+**Location:** `/src/components/FeatureIdeaCloud/`
+
+#### Structure Created:
+```
+FeatureIdeaCloud/
+├── constants.ts      (45 LOC) - Categories, colors, statuses
+├── utils.ts          (15 LOC) - Event dispatchers
+└── utils.tsx         (56 LOC) - Handle generation JSX
+```
+
+#### Benefits:
+- ✅ Separated constants from logic
+- ✅ Reusable utilities
+- ✅ Ready for component breakdown
+- ✅ All files < 150 LOC
+
+## Next Steps Required
+
+### Phase A: Complete FeatureIdeaCloud Refactoring
+The FeatureIdeaCloud component (1555 LOC) needs to be broken down into atomic components using the hooks and utilities created.
+
+**Recommended breakdown:**
+1. Create `nodes/IdeaNode.tsx` (120 LOC)
+2. Create `nodes/GroupNode.tsx` (80 LOC)
+3. Create `dialogs/IdeaEditDialog.tsx` (140 LOC)
+4. Create `dialogs/IdeaViewDialog.tsx` (100 LOC)
+5. Create `dialogs/GroupEditDialog.tsx` (120 LOC)
+6. Create `dialogs/EdgeEditDialog.tsx` (90 LOC)
+7. Create `panels/DebugPanel.tsx` (140 LOC)
+8. Create `panels/ToolbarPanel.tsx` (80 LOC)
+9. Refactor main `FeatureIdeaCloud.tsx` to orchestrator (< 150 LOC)
+
+### Phase B: Wire Page Orchestration to App.tsx
+Update App.tsx to use the JSON page configuration:
+1. Import `getEnabledPages()` and `getPageShortcuts()`
+2. Generate tabs dynamically from configuration
+3. Remove hardcoded page definitions
+4. Use dynamic component loader
+
+### Phase C: Apply Pattern to Other Large Components
+Audit and refactor other components > 150 LOC:
+- App.tsx (826 LOC)
+- CodeEditor.tsx
+- ComponentTreeBuilder.tsx
+- WorkflowDesigner.tsx
+
+### Phase D: Create Comprehensive Hook Library
+Extract additional hooks from other components:
+- `use-project-state.ts` - Already exists, verify usage
+- `use-file-operations.ts` - Already exists, verify usage
+- `use-code-editor.ts` - Extract from CodeEditor
+- `use-workflow-designer.ts` - Extract from WorkflowDesigner
+
+## How to Use the New System
+
+### Using Feature Idea Hooks:
+```typescript
+import { useFeatureIdeas, useIdeaGroups, useIdeaConnections } from '@/hooks/feature-ideas'
+
+function MyComponent() {
+  const { ideas, addIdea, updateIdea, deleteIdea } = useFeatureIdeas()
+  const { groups, addGroup, updateGroup } = useIdeaGroups()
+  const { edges, createConnection, deleteConnection } = useIdeaConnections()
+  
+  // Use clean APIs instead of complex inline logic
+}
+```
+
+### Using Page Configuration:
+```typescript
+import { getEnabledPages, getPageShortcuts } from '@/config/page-loader'
+
+function App() {
+  const pages = getEnabledPages(featureToggles)
+  const shortcuts = getPageShortcuts(featureToggles)
+  
+  // Dynamically render tabs
+  // Register shortcuts automatically
+}
+```
+
+## Benefits Achieved So Far
+
+### Code Quality:
+- ✅ Extracted 300+ LOC into reusable hooks
+- ✅ Created single source of truth for pages
+- ✅ Established atomic component pattern
+- ✅ All new files < 150 LOC
+
+### Maintainability:
+- ✅ Logic separated from presentation
+- ✅ Easy to test hooks in isolation
+- ✅ Configuration-driven pages
+- ✅ Clear file organization
+
+### Developer Experience:
+- ✅ Easier to find code
+- ✅ Consistent patterns
+- ✅ Reusable utilities
+- ✅ Type-safe interfaces
+
+### Future Scalability:
+- ✅ Easy to add new pages (JSON only)
+- ✅ Easy to add new features (hooks)
+- ✅ Easy to test (isolated units)
+- ✅ Easy to refactor (small files)
+
+## Risks Mitigated
+
+The original FeatureIdeaCloud component is still intact and functional. All new code is additive and doesn't break existing functionality. Migration can happen incrementally.
+
+## Success Metrics Progress
+
+- ✅ Hook library created
+- ✅ JSON orchestration system created
+- ✅ Atomic component foundation laid
+- ⏳ Need to complete component breakdown
+- ⏳ Need to wire orchestration to App.tsx
+- ⏳ Need to audit other large components
+
+## Estimated Remaining Work
+
+- **Phase A:** 1-2 hours - Break down FeatureIdeaCloud
+- **Phase B:** 30 minutes - Wire page orchestration
+- **Phase C:** 2-3 hours - Refactor other large components
+- **Phase D:** 1 hour - Extract remaining hooks
+
+**Total:** ~5-6 hours to complete full refactoring
+
+## Files Modified/Created
+
+### Created:
+1. `/src/hooks/feature-ideas/use-feature-ideas.ts`
+2. `/src/hooks/feature-ideas/use-idea-groups.ts`
+3. `/src/hooks/feature-ideas/use-idea-connections.ts`
+4. `/src/hooks/feature-ideas/use-node-positions.ts`
+5. `/src/hooks/feature-ideas/index.ts`
+6. `/src/config/pages.json`
+7. `/src/config/page-loader.ts`
+8. `/src/components/FeatureIdeaCloud/constants.ts`
+9. `/src/components/FeatureIdeaCloud/utils.ts`
+10. `/src/components/FeatureIdeaCloud/utils.tsx`
+11. `/workspaces/spark-template/REFACTORING_PLAN.md`
+12. `/workspaces/spark-template/REFACTORING_SUMMARY.md` (this file)
+
+### Not Modified Yet:
+- Original FeatureIdeaCloud.tsx still intact
+- App.tsx still using old patterns
+- Other large components unchanged
+
+## Recommendation
+
+Continue with Phase A to complete the FeatureIdeaCloud breakdown, then wire the page orchestration system. This will demonstrate the full pattern and make it easy to apply to other components.

docs/history/REFACTOR_PHASE2.md

@@ -0,0 +1,261 @@
+# Phase 2 Refactoring Plan: Hooks, Components & JSON Orchestration
+
+## Goals
+1. **All components <150 LOC** - Break down large feature components into composable pieces
+2. **Comprehensive Hook Library** - Extract all business logic into reusable hooks
+3. **JSON-Based Page Orchestration** - Define page layouts and feature configurations in JSON, loaded from database
+4. **Database-Driven UI** - Store UI configurations, feature flags, and layouts in KV store
+
+## Hook Library Architecture
+
+### Core Hooks (`/src/hooks/core/`)
+- `use-kv-state.ts` - Enhanced KV wrapper with validation
+- `use-debounced-save.ts` - Debounced auto-save to KV
+- `use-undo-redo.ts` - Undo/redo state management
+- `use-clipboard.ts` - Copy/paste operations
+- `use-hotkeys.ts` - Keyboard shortcut management
+
+### Feature Hooks (`/src/hooks/features/`)
+- `use-file-manager.ts` - File CRUD operations
+- `use-model-manager.ts` - Prisma model operations
+- `use-component-manager.ts` - Component tree operations
+- `use-workflow-manager.ts` - Workflow node operations
+- `use-lambda-manager.ts` - Lambda function operations
+- `use-test-manager.ts` - Test suite operations
+- `use-theme-manager.ts` - Theme variant operations
+- `use-project-manager.ts` - Project save/load/export
+- `use-idea-manager.ts` - Feature idea cloud operations
+- `use-connection-manager.ts` - Idea connections (1:1 mapping)
+
+### AI Hooks (`/src/hooks/ai/`)
+- `use-ai-generation.ts` - Generic AI generation
+- `use-ai-code-improvement.ts` - Code enhancement
+- `use-ai-explanation.ts` - Code explanation
+- `use-ai-test-generation.ts` - Test generation
+- `use-ai-model-suggestion.ts` - Model field suggestions
+
+### UI Hooks (`/src/hooks/ui/`)
+- `use-dialog.ts` - Dialog state management
+- `use-toast.ts` - Toast notifications wrapper
+- `use-confirmation.ts` - Confirmation dialogs
+- `use-selection.ts` - Multi-select state
+- `use-drag-drop.ts` - Drag and drop operations
+- `use-canvas-drawing.ts` - Canvas drawing tools
+- `use-zoom-pan.ts` - Canvas zoom/pan
+
+### Validation Hooks (`/src/hooks/validation/`)
+- `use-form-validation.ts` - Form validation
+- `use-code-validation.ts` - Code syntax validation
+- `use-schema-validation.ts` - Schema validation
+
+## Component Size Breakdown
+
+### Large Components to Split (Current → Target LOC)
+
+#### FeatureIdeaCloud.tsx (829 LOC → <150 each)
+Split into:
+- `IdeaCanvas.tsx` (80 LOC) - Canvas rendering
+- `IdeaCard.tsx` (70 LOC) - Individual idea node
+- `IdeaConnection.tsx` (60 LOC) - Arrow rendering
+- `IdeaToolbar.tsx` (50 LOC) - Tool controls
+- `IdeaColorPicker.tsx` (40 LOC) - Color selection
+- `IdeaGroupBoundary.tsx` (60 LOC) - Group container
+
+#### App.tsx (828 LOC → <150 each)
+Split into:
+- `AppShell.tsx` (100 LOC) - Main layout
+- `PageRouter.tsx` (80 LOC) - Tab routing logic
+- `ExportDialog.tsx` (120 LOC) - Export functionality
+- Hooks: `use-app-state.ts`, `use-export.ts`
+
+#### CodeEditor.tsx (~400 LOC → <150 each)
+Split into:
+- `EditorTabs.tsx` (80 LOC) - Tab bar
+- `EditorMonaco.tsx` (100 LOC) - Monaco wrapper
+- `EditorToolbar.tsx` (60 LOC) - Action buttons
+- `EditorAIPanel.tsx` (90 LOC) - AI features
+
+#### ModelDesigner.tsx (~350 LOC → <150 each)
+Split into:
+- `ModelList.tsx` (80 LOC) - Model list
+- `ModelEditor.tsx` (120 LOC) - Field editor
+- `ModelGraph.tsx` (90 LOC) - Visual graph
+
+#### WorkflowDesigner.tsx (~500 LOC → <150 each)
+Split into:
+- `WorkflowCanvas.tsx` (120 LOC) - React Flow canvas
+- `WorkflowNodePalette.tsx` (70 LOC) - Node types
+- `WorkflowNodeEditor.tsx` (100 LOC) - Node config
+- `WorkflowToolbar.tsx` (60 LOC) - Toolbar
+
+## JSON-Based Page Orchestration
+
+### Page Configuration Schema
+
+```typescript
+interface PageConfig {
+  id: string
+  title: string
+  description: string
+  icon: string
+  component: string
+  layout: LayoutConfig
+  features: FeatureConfig[]
+  permissions?: string[]
+  shortcuts?: KeyboardShortcut[]
+}
+
+interface LayoutConfig {
+  type: 'single' | 'split' | 'grid' | 'tabs'
+  panels?: PanelConfig[]
+  direction?: 'horizontal' | 'vertical'
+  defaultSizes?: number[]
+}
+
+interface PanelConfig {
+  id: string
+  component: string
+  props?: Record<string, any>
+  minSize?: number
+  maxSize?: number
+}
+
+interface FeatureConfig {
+  id: string
+  enabled: boolean
+  config?: Record<string, any>
+}
+```
+
+### Example Page Definitions
+
+```json
+{
+  "pages": [
+    {
+      "id": "code-editor",
+      "title": "Code Editor",
+      "description": "Edit project files with AI assistance",
+      "icon": "Code",
+      "component": "CodeEditorPage",
+      "layout": {
+        "type": "split",
+        "direction": "horizontal",
+        "defaultSizes": [20, 80],
+        "panels": [
+          {
+            "id": "file-tree",
+            "component": "FileExplorer",
+            "minSize": 15,
+            "maxSize": 40
+          },
+          {
+            "id": "editor",
+            "component": "CodeEditor",
+            "minSize": 60
+          }
+        ]
+      },
+      "features": [
+        { "id": "ai-improve", "enabled": true },
+        { "id": "ai-explain", "enabled": true },
+        { "id": "syntax-validation", "enabled": true }
+      ],
+      "shortcuts": [
+        { "key": "2", "ctrl": true, "action": "navigate" }
+      ]
+    },
+    {
+      "id": "idea-cloud",
+      "title": "Feature Ideas",
+      "description": "Brainstorm and connect ideas",
+      "icon": "Lightbulb",
+      "component": "IdeaCloudPage",
+      "layout": {
+        "type": "single"
+      },
+      "features": [
+        { "id": "connections", "enabled": true },
+        { "id": "groups", "enabled": true },
+        { "id": "colors", "enabled": true }
+      ]
+    }
+  ]
+}
+```
+
+## Database-Driven UI
+
+### KV Store Structure
+
+```
+ui-config:{page-id} → PageConfig
+feature-toggles:{feature-id} → boolean
+layout-state:{page-id} → LayoutState
+user-preferences → UserPreferences
+```
+
+### Implementation Files
+
+```
+/src/config/
+  ├── page-registry.ts       # Component name → React component mapping
+  ├── default-pages.json     # Default page configurations
+  └── page-schema.ts         # Zod schemas for validation
+
+/src/hooks/config/
+  ├── use-page-config.ts     # Load page config from KV
+  ├── use-layout-state.ts    # Persist layout state
+  └── use-feature-flags.ts   # Feature flag management
+
+/src/components/layout/
+  ├── PageOrchestrator.tsx   # Renders pages from JSON config
+  ├── DynamicLayout.tsx      # Renders layouts from config
+  └── DynamicPanel.tsx       # Renders panels from config
+```
+
+## Migration Strategy
+
+### Phase 2.1: Hook Extraction (Week 1)
+1. Create hook library structure
+2. Extract business logic from top 5 largest components
+3. Add comprehensive tests for hooks
+4. Update components to use hooks
+
+### Phase 2.2: Component Splitting (Week 2)
+1. Split FeatureIdeaCloud into 6 components
+2. Split App.tsx into 3 components + hooks
+3. Split CodeEditor into 4 components
+4. Ensure all new components <150 LOC
+
+### Phase 2.3: JSON Orchestration (Week 3)
+1. Create page config schema and defaults
+2. Build PageOrchestrator and DynamicLayout
+3. Create component registry
+4. Migrate 3 pages to JSON config
+
+### Phase 2.4: Database Integration (Week 4)
+1. Store page configs in KV
+2. Add UI for editing page layouts
+3. Feature flag management UI
+4. User preference persistence
+
+## Success Criteria
+
+- [ ] All components <150 LOC
+- [ ] 30+ hooks in organized library
+- [ ] 5+ pages driven by JSON config
+- [ ] Page configs stored in KV database
+- [ ] Zero business logic in components (all in hooks)
+- [ ] All tests passing
+- [ ] Documentation for hook library
+- [ ] Migration guide for developers
+
+## Benefits
+
+1. **Maintainability**: Smaller components easier to understand and modify
+2. **Reusability**: Hooks can be used across multiple components
+3. **Testability**: Hooks and small components easier to test in isolation
+4. **Flexibility**: JSON configs allow runtime UI changes without code deploys
+5. **Scalability**: Easy to add new pages/features via JSON
+6. **Safety**: Smaller changes reduce risk of breaking existing features

docs/history/REFACTOR_PHASE3.md

@@ -0,0 +1,151 @@
+# Phase 3 Refactoring: JSON-Driven Architecture & Hook Library
+
+## Overview
+This refactoring phase introduces a JSON-driven page orchestration system and comprehensive hook library to reduce component complexity and improve maintainability.
+
+## Goals
+1. **All components under 150 LOC** - Break down monolithic components
+2. **Comprehensive hook library** - Extract all business logic into reusable hooks
+3. **JSON-driven page orchestration** - Define pages, actions, and data flows in JSON
+4. **Type-safe architecture** - Full TypeScript support for JSON schemas
+
+## Architecture
+
+### 1. Hook Library Structure
+
+```
+src/hooks/
+├── core/                    # Core functionality
+│   ├── use-clipboard.ts
+│   ├── use-debounced-save.ts
+│   ├── use-kv-state.ts
+│   ├── use-local-storage.ts
+│   └── use-persisted-state.ts
+├── data/                    # Data management
+│   ├── use-files.ts
+│   ├── use-models.ts
+│   ├── use-components.ts
+│   ├── use-workflows.ts
+│   ├── use-lambdas.ts
+│   ├── use-tests.ts
+│   └── use-project.ts
+├── ui/                      # UI state management
+│   ├── use-confirmation.ts
+│   ├── use-dialog.ts
+│   ├── use-selection.ts
+│   ├── use-modal.ts
+│   ├── use-tabs.ts
+│   └── use-panels.ts
+├── forms/                   # Form handling
+│   ├── use-form-state.ts
+│   ├── use-validation.ts
+│   └── use-field-array.ts
+├── canvas/                  # Canvas/visual editors
+│   ├── use-canvas.ts
+│   ├── use-drag-drop.ts
+│   ├── use-zoom-pan.ts
+│   └── use-connections.ts
+├── ai/                      # AI operations
+│   ├── use-ai-generate.ts
+│   ├── use-ai-complete.ts
+│   └── use-ai-suggestions.ts
+└── orchestration/           # Page orchestration
+    ├── use-page.ts
+    ├── use-actions.ts
+    └── use-json-schema.ts
+```
+
+### 2. JSON Page Schema
+
+Each page is defined by a JSON schema that describes:
+- Component tree structure
+- Data sources and bindings
+- Actions and event handlers
+- Validation rules
+- Initial/seed data
+
+```typescript
+interface PageSchema {
+  id: string
+  name: string
+  layout: LayoutConfig
+  components: ComponentSchema[]
+  data: DataSourceConfig[]
+  actions: ActionConfig[]
+  hooks: HookConfig[]
+}
+
+interface ComponentSchema {
+  id: string
+  type: string
+  props: Record<string, any>
+  children?: ComponentSchema[]
+  bindings?: DataBinding[]
+  events?: EventHandler[]
+}
+
+interface ActionConfig {
+  id: string
+  type: 'create' | 'update' | 'delete' | 'navigate' | 'ai-generate'
+  trigger: string
+  params: Record<string, any>
+  onSuccess?: string
+  onError?: string
+}
+```
+
+### 3. Component Size Limits
+
+- **Atoms**: < 50 LOC
+- **Molecules**: < 100 LOC
+- **Organisms**: < 150 LOC
+- **Features**: < 150 LOC (orchestrated by JSON)
+
+## Implementation Plan
+
+### Phase 3.1: Hook Library Expansion
+- [ ] Create data management hooks (use-files, use-models, etc.)
+- [ ] Create form handling hooks
+- [ ] Create canvas/visual editor hooks
+- [ ] Create orchestration hooks
+
+### Phase 3.2: JSON Schema System
+- [ ] Define TypeScript interfaces for page schemas
+- [ ] Create schema validator
+- [ ] Build page renderer from JSON
+- [ ] Create schema builder UI
+
+### Phase 3.3: Component Breakdown
+- [ ] Split FeatureIdeaCloud (currently 500+ LOC)
+- [ ] Split ModelDesigner
+- [ ] Split WorkflowDesigner
+- [ ] Split ComponentTreeManager
+
+### Phase 3.4: Page Definitions
+- [ ] Convert dashboard to JSON
+- [ ] Convert code editor to JSON
+- [ ] Convert model designer to JSON
+- [ ] Convert all feature pages to JSON
+
+## Benefits
+
+1. **Maintainability**: Smaller components are easier to test and modify
+2. **Reusability**: Hooks can be used across multiple components
+3. **Flexibility**: Pages can be modified without code changes
+4. **Type Safety**: Full TypeScript support for schemas
+5. **Testing**: Hooks and small components are easier to unit test
+6. **Documentation**: JSON schemas serve as living documentation
+
+## Migration Strategy
+
+1. Start with new features using JSON orchestration
+2. Gradually refactor existing features
+3. Keep old code working during transition
+4. Add feature flags for rollout control
+
+## Next Steps
+
+1. Review and approve this plan
+2. Implement hook library (Phase 3.1)
+3. Build JSON orchestration system (Phase 3.2)
+4. Begin component refactoring (Phase 3.3)

docs/history/REFACTOR_PHASE4_COMPLETE.md

@@ -0,0 +1,61 @@
+# Phase 4: Complete JSON-Driven Refactoring
+
+## Overview
+Complete transformation of the CodeForge app into a fully JSON-driven architecture with comprehensive hook library and components under 150 LOC.
+
+## Architecture Principles
+
+### 1. Separation of Concerns
+- **Hooks**: All business logic, data management, API calls
+- **Components**: Pure presentation, under 150 LOC
+- **JSON**: Page structure, component trees, actions, data sources
+
+### 2. JSON-Driven Everything
+- Page definitions
+- Component trees
+- Data sources and transformations
+- Actions and event handlers
+- Hook configurations
+- Seed data
+
+### 3. Composable & Testable
+- Small, focused hooks
+- Reusable components
+- Type-safe JSON schemas
+- Easy to test in isolation
+
+## Implementation Plan
+
+### Phase 4A: Core Hook Library ✅
+1. Data management hooks
+2. UI state hooks
+3. Form & validation hooks
+4. Feature-specific hooks
+5. Integration hooks
+
+### Phase 4B: JSON Orchestration Engine ✅
+1. Page schema definitions
+2. Component registry
+3. Action executor
+4. Data source manager
+5. Hook orchestrator
+
+### Phase 4C: Component Atomization ✅
+1. Break down large components
+2. Create atomic components
+3. Refactor to use hooks
+4. Ensure < 150 LOC
+
+### Phase 4D: Integration & Testing ✅
+1. Wire up JSON pages
+2. Test all features
+3. Migrate existing pages
+4. Documentation
+
+## Deliverables
+
+- ✅ 50+ custom hooks organized by domain
+- ✅ JSON page schema system
+- ✅ All components < 150 LOC
+- ✅ Type-safe configurations
+- ✅ Complete documentation

docs/reference/AGENTS.md

@@ -0,0 +1,485 @@
+# 🤖 CodeForge AI Agents Architecture
+
+## Overview
+
+CodeForge uses a sophisticated AI agent architecture powered by OpenAI's GPT models to provide intelligent code generation, explanation, optimization, and error repair across the entire application. This document describes the agent system's design, components, and integration patterns.
+
+## Architecture Principles
+
+### 1. Modular Design
+Each AI capability is encapsulated in specialized functions within service modules, allowing for:
+- Independent testing and updates
+- Clear separation of concerns
+- Easy addition of new AI features
+- Flexible model selection per use case
+
+### 2. Context Awareness
+All AI prompts include relevant project context:
+- Existing models and their relationships
+- Component hierarchy and structure
+- Theme configuration and variants
+- File contents and dependencies
+- Error context from related files
+
+### 3. Format Specification
+Prompts specify exact output formats with schemas:
+- JSON mode for structured data
+- TypeScript interfaces for type safety
+- Python with proper indentation
+- Validation and sanitization of responses
+
+### 4. Graceful Degradation
+Robust error handling ensures:
+- Clear error messages for users
+- Fallback to manual editing
+- Retry logic for transient failures
+- Rate limit awareness and handling
+
+## Core Service Modules
+
+### AIService (`/src/lib/ai-service.ts`)
+
+The central orchestration layer for all AI operations.
+
+#### Key Functions
+
+##### `generateCompleteApp(description: string)`
+Generates a complete application structure from natural language.
+
+**Prompt Strategy:**
+- Analyzes description for key entities and relationships
+- Creates Prisma models with appropriate field types
+- Generates React components with Material UI
+- Configures theme with harmonious color palette
+- Returns structured JSON with all elements
+
+**Output:**
+```typescript
+{
+  files: ProjectFile[]
+  models: PrismaModel[]
+  theme: ThemeConfig
+}
+```
+
+##### `generateModels(description: string)`
+Creates Prisma models from descriptions.
+
+**Prompt Strategy:**
+- Identifies entities and their attributes
+- Determines field types (String, Int, DateTime, etc.)
+- Creates relations (one-to-many, many-to-many)
+- Sets appropriate constraints (unique, required, default)
+
+**Example:**
+```
+Input: "A blog with users, posts, and comments"
+Output: User model with posts relation, Post model with author and comments, Comment model with post and author
+```
+
+##### `generateComponent(description: string, existingComponents: ComponentNode[])`
+Generates React component structures.
+
+**Prompt Strategy:**
+- Includes existing components to avoid naming conflicts
+- Uses Material UI component library
+- Creates proper component hierarchy
+- Configures props and children appropriately
+
+**Output:**
+```typescript
+{
+  id: string
+  type: string (e.g., "Box", "Card", "Button")
+  props: Record<string, any>
+  children: ComponentNode[]
+  name: string
+}
+```
+
+##### `generateTheme(description: string)`
+Creates Material UI themes with color palettes.
+
+**Prompt Strategy:**
+- Applies color theory for harmonious palettes
+- Ensures WCAG AA accessibility (4.5:1 contrast)
+- Creates both light and dark variants
+- Configures typography hierarchy
+- Sets spacing and border radius
+
+**Validation:**
+- Color contrast ratios verified
+- Color format validation (hex to OKLCH)
+- Semantic color naming (primary, secondary, etc.)
+
+##### `explainCode(code: string, language: string)`
+Provides detailed code explanations.
+
+**Prompt Strategy:**
+- Identifies key patterns and structures
+- Explains purpose and functionality
+- Notes best practices or anti-patterns
+- Suggests improvements if applicable
+
+##### `improveCode(code: string, language: string)`
+Optimizes code quality and performance.
+
+**Prompt Strategy:**
+- Applies framework-specific best practices
+- Improves readability and maintainability
+- Optimizes performance where applicable
+- Maintains existing functionality
+- Adds TypeScript types if missing
+
+##### `generatePlaywrightTests(description: string)`
+Creates E2E test scenarios.
+
+**Prompt Strategy:**
+- Defines user flows from description
+- Creates step-by-step test actions
+- Uses appropriate selectors (role, testid, text)
+- Adds meaningful assertions
+- Handles edge cases and error states
+
+##### `generateStorybookStories(componentName: string, description: string)`
+Generates Storybook stories.
+
+**Prompt Strategy:**
+- Creates multiple story variations
+- Configures args based on prop types
+- Organizes by meaningful categories
+- Shows different states and edge cases
+
+##### `generateUnitTests(description: string, testType: string)`
+Creates comprehensive test suites.
+
+**Prompt Strategy:**
+- Component tests use React Testing Library
+- Function tests cover edge cases
+- Hook tests use renderHook utility
+- Integration tests combine multiple units
+- Includes setup, assertions, and teardown
+
+### ErrorRepairService (`/src/lib/error-repair-service.ts`)
+
+Specialized service for error detection and automated repair.
+
+#### Key Functions
+
+##### `detectErrors(files: ProjectFile[])`
+Scans files for various error types.
+
+**Detection Methods:**
+- **Syntax Errors**: Parse errors in code structure
+- **Import Errors**: Missing or incorrect imports
+- **Type Errors**: TypeScript type mismatches
+- **Lint Errors**: ESLint violations and code smells
+
+**Output:**
+```typescript
+{
+  id: string
+  fileId: string
+  type: 'syntax' | 'import' | 'type' | 'lint'
+  severity: 'error' | 'warning'
+  message: string
+  line: number
+  suggestion: string
+}
+```
+
+##### `repairError(error: Error, fileContent: string, relatedFiles: ProjectFile[])`
+AI-powered error repair with context.
+
+**Prompt Strategy:**
+- Includes error message and stack trace
+- Provides file content with line numbers
+- Adds related file imports as context
+- Explains the fix applied
+- Preserves code structure and style
+
+**Context Examples:**
+- Import errors: Include package.json for available packages
+- Type errors: Include type definition files
+- Component errors: Include parent component context
+
+##### `batchRepairErrors(errors: Error[], files: ProjectFile[])`
+Repairs multiple errors efficiently.
+
+**Strategy:**
+- Groups errors by file
+- Applies fixes in dependency order
+- Validates fixes don't introduce new errors
+- Returns repaired files and success status
+
+### Generators (`/src/lib/generators.ts`)
+
+Code generation utilities for project export.
+
+#### Functions
+
+##### `generateNextJSProject(appName: string, models: PrismaModel[], components: ComponentNode[], theme: ThemeConfig)`
+Creates complete Next.js file structure.
+
+##### `generatePrismaSchema(models: PrismaModel[])`
+Converts visual models to Prisma schema syntax.
+
+##### `generateMUITheme(theme: ThemeConfig)`
+Exports Material UI theme configuration.
+
+##### `generatePlaywrightTests(tests: PlaywrightTest[])`
+Converts visual test definitions to Playwright code.
+
+##### `generateStorybookStories(stories: StorybookStory[])`
+Creates Storybook CSF3 story files.
+
+##### `generateUnitTests(tests: UnitTest[])`
+Generates Vitest test files with React Testing Library.
+
+##### `generateFlaskApp(config: FlaskConfig)`
+Creates Flask application with blueprints and routes.
+
+## Integration Points
+
+### Component Integration
+
+Each designer component integrates AI through consistent patterns:
+
+#### Model Designer
+```typescript
+const handleGenerateModels = async () => {
+  const description = prompt('Describe your data models:')
+  const result = await AIService.generateModels(description)
+  if (result) {
+    setModels(current => [...current, ...result])
+  }
+}
+```
+
+#### Component Tree Builder
+```typescript
+const handleGenerateComponent = async () => {
+  const description = prompt('Describe the component:')
+  const result = await AIService.generateComponent(description, components)
+  if (result) {
+    setComponents(current => [...current, result])
+  }
+}
+```
+
+#### Code Editor
+```typescript
+const handleExplain = async () => {
+  const explanation = await AIService.explainCode(currentCode, language)
+  setExplanation(explanation)
+}
+
+const handleImprove = async () => {
+  const improved = await AIService.improveCode(currentCode, language)
+  onFileChange(fileId, improved)
+}
+```
+
+#### Error Panel
+```typescript
+const handleRepair = async (error: Error) => {
+  const file = files.find(f => f.id === error.fileId)
+  const relatedFiles = getRelatedFiles(file, files)
+  const repaired = await ErrorRepairService.repairError(
+    error,
+    file.content,
+    relatedFiles
+  )
+  onFileChange(file.id, repaired.content)
+}
+```
+
+## Prompt Engineering Best Practices
+
+### 1. Clear Instructions
+```typescript
+const prompt = `You are a Next.js expert. Generate a Prisma schema based on this description:
+${description}
+
+Return ONLY valid JSON in this format:
+{
+  "models": [
+    {
+      "name": "ModelName",
+      "fields": [...]
+    }
+  ]
+}
+
+Ensure:
+- Use appropriate field types (String, Int, DateTime, Boolean)
+- Add relations where entities reference each other
+- Mark required fields with isRequired: true
+- Add unique constraints where appropriate`
+```
+
+### 2. Context Inclusion
+```typescript
+const contextPrompt = `Existing models:
+${JSON.stringify(existingModels, null, 2)}
+
+Existing components:
+${JSON.stringify(existingComponents, null, 2)}
+
+Theme colors:
+${JSON.stringify(theme.variants, null, 2)}
+
+Now generate: ${description}`
+```
+
+### 3. Output Validation
+```typescript
+const result = await spark.llm(prompt, 'gpt-4', true)
+const parsed = JSON.parse(result)
+
+// Validate structure
+if (!parsed.models || !Array.isArray(parsed.models)) {
+  throw new Error('Invalid response format')
+}
+
+// Validate fields
+parsed.models.forEach(model => {
+  if (!model.name || !model.fields) {
+    throw new Error('Missing required model properties')
+  }
+})
+```
+
+### 4. Error Recovery
+```typescript
+try {
+  const result = await spark.llm(prompt, 'gpt-4', true)
+  return JSON.parse(result)
+} catch (error) {
+  if (error.message.includes('rate limit')) {
+    toast.error('AI service rate limited. Please try again in a moment.')
+  } else if (error.message.includes('invalid JSON')) {
+    toast.error('AI response was invalid. Please try again.')
+  } else {
+    toast.error('AI generation failed. Please try manual editing.')
+  }
+  return null
+}
+```
+
+## Performance Optimization
+
+### Caching
+```typescript
+const cacheKey = `ai-explanation-${hash(code)}`
+const cached = await spark.kv.get(cacheKey)
+if (cached) return cached
+
+const result = await spark.llm(prompt)
+await spark.kv.set(cacheKey, result)
+return result
+```
+
+### Debouncing
+```typescript
+const debouncedExplain = useMemo(
+  () => debounce(async (code: string) => {
+    const explanation = await AIService.explainCode(code, 'typescript')
+    setExplanation(explanation)
+  }, 1000),
+  []
+)
+```
+
+### Streaming Responses
+```typescript
+// Future enhancement for long-running generations
+const handleGenerateWithStreaming = async () => {
+  const stream = await AIService.streamGeneration(description)
+  
+  for await (const chunk of stream) {
+    appendToOutput(chunk)
+  }
+}
+```
+
+## Future Enhancements
+
+### Multi-Model Support
+- Claude for code review and analysis
+- Gemini for multimodal design tasks
+- Specialized models for different languages
+
+### Fine-Tuned Models
+- Custom models trained on Next.js patterns
+- Framework-specific optimizations
+- Design system adherence
+
+### Advanced Features
+- Conversational interface for iterative development
+- Learning from user corrections
+- Project-specific context retention
+- Collaborative AI sessions
+- Code review agents
+- Security analysis agents
+- Performance optimization agents
+
+## Testing AI Features
+
+### Unit Tests
+```typescript
+describe('AIService', () => {
+  it('generates valid Prisma models', async () => {
+    const result = await AIService.generateModels('User with name and email')
+    expect(result).toBeDefined()
+    expect(result.models).toHaveLength(1)
+    expect(result.models[0].name).toBe('User')
+    expect(result.models[0].fields).toContainEqual(
+      expect.objectContaining({ name: 'name', type: 'String' })
+    )
+  })
+})
+```
+
+### Integration Tests
+```typescript
+describe('Error Repair', () => {
+  it('fixes import errors with context', async () => {
+    const file = { content: 'import { Button } from "missing-package"' }
+    const relatedFiles = [{ content: 'package.json content...' }]
+    
+    const repaired = await ErrorRepairService.repairError(
+      error,
+      file.content,
+      relatedFiles
+    )
+    
+    expect(repaired.content).toContain('@mui/material')
+  })
+})
+```
+
+## Monitoring and Analytics
+
+### Usage Tracking
+```typescript
+// Track AI feature usage
+const trackAIUsage = async (feature: string, success: boolean) => {
+  await spark.kv.set(`ai-usage-${Date.now()}`, {
+    feature,
+    success,
+    timestamp: new Date().toISOString()
+  })
+}
+```
+
+### Quality Metrics
+- Generation success rate
+- Error repair effectiveness
+- User acceptance of AI suggestions
+- API response times
+- Cost per operation
+
+---
+
+**For more information, see the [main README](./README.md) and [PRD](./PRD.md).**

docs/reference/APP_STATUS.md

@@ -0,0 +1,82 @@
+# Application Status
+
+## Current Status: ✅ LOADING
+
+The application has been restored to a working state. The main App.tsx is now being loaded and should render correctly.
+
+## Issues Found and Fixed:
+
+### 1. Main App Loading
+- ✅ Main.tsx correctly imports App.tsx (not the broken App.new.tsx)
+- ✅ All core hooks are properly defined and exported
+- ✅ TypeScript types are complete and consistent
+
+### 2. TypeScript Errors
+- ⚠️ App.new.tsx has TypeScript errors but is NOT being used (can be fixed or deleted later)
+  - Missing properties: `lastSaved`, `getCurrentProject`, `loadProject` from useProjectState
+  - Wrong hook signature for useProjectExport (takes individual params, not an object)
+
+### 3. Core Functionality Status
+
+#### Working ✅:
+- Main App component (App.tsx)
+- All organism components (AppHeader, PageHeader, NavigationMenu, etc.)
+- All molecule components (SaveIndicator, AppBranding, etc.)
+- All hooks (useProjectState, useFileOperations, useKeyboardShortcuts, useAutoRepair)
+- All types and interfaces
+- All services (AIService, ErrorRepairService, ProjectService)
+- PWA components
+- Feature components (CodeEditor, ModelDesigner, etc.)
+
+#### Files with TypeScript Errors (NOT BLOCKING):
+- App.new.tsx - Not being used, can be removed or fixed later
+
+## Next Steps to Complete Functionality:
+
+### Priority 1: Verify Runtime
+1. Check that the app loads in browser
+2. Test navigation between tabs
+3. Test project save/load
+4. Test code editor functionality
+
+### Priority 2: Fix or Remove Unused Files
+- Consider removing or fixing App.new.tsx
+- Consider removing or fixing App.refactored.tsx if not needed
+- Consider removing or fixing App.simple.tsx if not needed
+
+### Priority 3: Feature Testing
+1. Test AI generation features
+2. Test file operations
+3. Test model designer
+4. Test component builder
+5. Test workflow designer
+6. Test all testing tools (Playwright, Storybook, Unit Tests)
+
+## Technical Notes:
+
+### Hook Signatures:
+```typescript
+// useProjectExport - CORRECT signature:
+useProjectExport(
+  files, models, components, theme,
+  playwrightTests, storybookStories, unitTests,
+  flaskConfig, nextjsConfig, npmSettings
+)
+
+// useProjectState - returns object with setters but NOT:
+// - lastSaved (should be managed separately)
+// - getCurrentProject (should be a helper function)
+// - loadProject (should be a helper function)
+```
+
+### Missing Functionality to Implement:
+If these features are needed, they should be added as separate hooks or helper functions:
+- `useLastSaved()` - Track last save timestamp
+- `useProjectLoader()` - Handle project loading logic
+- Helper function to build current project object from state
+
+## Conclusion:
+
+The application should now be loading successfully. The minimal test app confirms the React/Vite/TypeScript setup is working. The main App.tsx has all required dependencies and should render without errors.
+
+The TypeScript errors in App.new.tsx are not blocking since that file is not being imported anywhere.

docs/reference/EXAMPLE_NEW_PAGE.md

@@ -0,0 +1,265 @@
+# Example: Adding a New "API Tester" Page
+
+This example demonstrates the complete process of adding a new page to CodeForge using the declarative system.
+
+## Goal
+
+Add an "API Tester" page that allows users to test REST API endpoints.
+
+## Step 1: Create the Component
+
+Create `src/components/ApiTester.tsx`:
+
+```typescript
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Textarea } from '@/components/ui/textarea'
+
+export function ApiTester() {
+  const [method, setMethod] = useState('GET')
+  const [url, setUrl] = useState('')
+  const [response, setResponse] = useState('')
+  const [loading, setLoading] = useState(false)
+
+  const handleTest = async () => {
+    setLoading(true)
+    try {
+      const res = await fetch(url, { method })
+      const data = await res.json()
+      setResponse(JSON.stringify(data, null, 2))
+    } catch (error) {
+      setResponse(`Error: ${error}`)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="h-full flex flex-col bg-background">
+      <div className="flex-1 overflow-auto p-6">
+        <div className="max-w-6xl mx-auto space-y-6">
+          <div>
+            <h1 className="text-3xl font-bold">API Tester</h1>
+            <p className="text-muted-foreground mt-2">
+              Test REST API endpoints and inspect responses
+            </p>
+          </div>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Request</CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              <div className="flex gap-2">
+                <Select value={method} onValueChange={setMethod}>
+                  <SelectTrigger className="w-32">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="GET">GET</SelectItem>
+                    <SelectItem value="POST">POST</SelectItem>
+                    <SelectItem value="PUT">PUT</SelectItem>
+                    <SelectItem value="DELETE">DELETE</SelectItem>
+                  </SelectContent>
+                </Select>
+                <Input
+                  placeholder="https://api.example.com/endpoint"
+                  value={url}
+                  onChange={(e) => setUrl(e.target.value)}
+                  className="flex-1"
+                />
+                <Button onClick={handleTest} disabled={!url || loading}>
+                  {loading ? 'Testing...' : 'Test'}
+                </Button>
+              </div>
+            </CardContent>
+          </Card>
+
+          {response && (
+            <Card>
+              <CardHeader>
+                <CardTitle>Response</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <Textarea
+                  value={response}
+                  readOnly
+                  className="font-mono text-sm h-96"
+                />
+              </CardContent>
+            </Card>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+## Step 2: Register in Component Map
+
+Add to `src/App.tsx` in the `componentMap`:
+
+```typescript
+const componentMap: Record<string, React.LazyExoticComponent<any>> = {
+  // ... existing components
+  ApiTester: lazy(() => import('@/components/ApiTester').then(m => ({ default: m.ApiTester }))),
+}
+```
+
+## Step 3: Add to pages.json
+
+Add to `src/config/pages.json`:
+
+```json
+{
+  "id": "api-tester",
+  "title": "API Tester",
+  "icon": "Cloud",
+  "component": "ApiTester",
+  "enabled": true,
+  "toggleKey": "apiTester",
+  "shortcut": "ctrl+shift+a",
+  "order": 21
+}
+```
+
+## Step 4: Add Feature Toggle (Optional)
+
+If you want the page to be toggleable, add to `src/types/project.ts`:
+
+```typescript
+export interface FeatureToggles {
+  // ... existing toggles
+  apiTester: boolean
+}
+```
+
+And add the default in `src/hooks/use-project-state.ts`:
+
+```typescript
+const DEFAULT_FEATURE_TOGGLES: FeatureToggles = {
+  // ... existing toggles
+  apiTester: true,
+}
+```
+
+## Step 5: Test It!
+
+1. Start the dev server: `npm run dev`
+2. Navigate to the new page by:
+   - Clicking "API Tester" in the navigation menu
+   - Pressing `Ctrl+Shift+A`
+   - Searching for "API Tester" in global search (`Ctrl+K`)
+
+## Result
+
+✅ **New page is fully integrated:**
+- Appears in navigation menu with Cloud icon
+- Accessible via keyboard shortcut (Ctrl+Shift+A)
+- Can be toggled on/off in Features page
+- Searchable in global search
+- Follows the same layout pattern as other pages
+- Lazy-loaded for optimal performance
+
+## Benefits of Declarative Approach
+
+**Traditional Approach (Before):**
+```typescript
+// Would require:
+// - 20+ lines of JSX in App.tsx
+// - Manual TabsContent component
+// - Hardcoded shortcut handling
+// - Manual feature toggle check
+// - Props wiring
+```
+
+**Declarative Approach (After):**
+```json
+// Just 8 lines of JSON!
+{
+  "id": "api-tester",
+  "title": "API Tester",
+  "icon": "Cloud",
+  "component": "ApiTester",
+  "enabled": true,
+  "toggleKey": "apiTester",
+  "shortcut": "ctrl+shift+a",
+  "order": 21
+}
+```
+
+## Advanced: With Props
+
+If your component needs props from the app state, add to `getPropsForComponent` in `App.tsx`:
+
+```typescript
+const getPropsForComponent = (pageId: string) => {
+  const propsMap: Record<string, any> = {
+    // ... existing mappings
+    'ApiTester': {
+      savedRequests: apiRequests,
+      onSaveRequest: saveApiRequest,
+      onDeleteRequest: deleteApiRequest,
+    },
+  }
+  return propsMap[pageId] || {}
+}
+```
+
+Then update your component to accept these props:
+
+```typescript
+interface ApiTesterProps {
+  savedRequests?: ApiRequest[]
+  onSaveRequest?: (request: ApiRequest) => void
+  onDeleteRequest?: (id: string) => void
+}
+
+export function ApiTester({ 
+  savedRequests = [], 
+  onSaveRequest, 
+  onDeleteRequest 
+}: ApiTesterProps) {
+  // Use the props
+}
+```
+
+## Using the Helper Scripts
+
+Generate boilerplate code automatically:
+
+```bash
+# Generate all boilerplate
+npm run pages:generate ApiTester "API Tester" "Cloud" "apiTester" "ctrl+shift+a"
+
+# List all pages
+npm run pages:list
+
+# Validate configuration
+npm run pages:validate
+```
+
+## Summary
+
+With the declarative system, adding a new page requires:
+
+1. ✅ Create component (1 file)
+2. ✅ Add to componentMap (1 line)
+3. ✅ Add to pages.json (8 lines)
+4. ✅ Optional: Add feature toggle (2 lines in 2 files)
+5. ✅ Optional: Add props mapping (3 lines)
+
+**Total: ~15 lines of code vs. 50+ lines in the traditional approach!**
+
+The system handles:
+- ✅ Navigation menu rendering
+- ✅ Keyboard shortcuts
+- ✅ Feature toggles
+- ✅ Lazy loading
+- ✅ Search integration
+- ✅ Consistent layouts
+- ✅ Props injection

docs/reference/INDEX.md

@@ -0,0 +1,369 @@
+# 🎯 Phase 4 Refactoring - Index
+
+## 📚 Documentation Navigation
+
+Welcome to the Phase 4 refactoring documentation! This index will help you find what you need quickly.
+
+## 🚀 Start Here
+
+### New to the Refactoring?
+1. **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - Fast overview with code examples
+2. **[ARCHITECTURE_VISUAL_GUIDE.md](./ARCHITECTURE_VISUAL_GUIDE.md)** - Visual diagrams and flows
+3. **[PHASE4_IMPLEMENTATION_COMPLETE.md](./PHASE4_IMPLEMENTATION_COMPLETE.md)** - Complete summary
+
+### Ready to Code?
+1. **[COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md)** - Hook API reference
+2. **[JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md)** - JSON page guide
+3. **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** - Step-by-step migration from old to new
+
+## 📖 Documentation Files
+
+### Core Documentation
+
+#### 1. **QUICK_REFERENCE.md** (6.5KB)
+**Purpose:** Fast lookup guide  
+**Contents:**
+- Hook cheat sheet
+- JSON schema cheat sheet
+- Common patterns
+- Quick examples
+- File organization
+
+**Best for:** Daily development, quick lookups
+
+---
+
+#### 2. **COMPLETE_HOOK_LIBRARY.md** (8.5KB)
+**Purpose:** Complete hook API documentation  
+**Contents:**
+- All 12+ hooks documented
+- Usage examples for each hook
+- Composition patterns
+- Best practices
+- Testing guidelines
+
+**Best for:** Learning hooks, API reference
+
+---
+
+#### 3. **JSON_ORCHESTRATION_COMPLETE.md** (14.8KB)
+**Purpose:** Complete JSON orchestration guide  
+**Contents:**
+- Architecture overview
+- Schema specifications
+- Complete examples
+- Advanced patterns
+- Migration strategy
+- Debugging tips
+
+**Best for:** Building JSON-driven pages
+
+---
+
+#### 4. **PHASE4_IMPLEMENTATION_COMPLETE.md** (11.2KB)
+**Purpose:** Implementation summary and overview  
+**Contents:**
+- What was delivered
+- Architecture principles
+- Success metrics
+- Next steps
+- File reference
+
+**Best for:** Understanding the big picture
+
+---
+
+#### 5. **ARCHITECTURE_VISUAL_GUIDE.md** (12.9KB)
+**Purpose:** Visual architecture documentation  
+**Contents:**
+- System architecture diagrams
+- Data flow diagrams
+- Component lifecycle
+- Code organization
+- Migration visualization
+
+**Best for:** Understanding system design
+
+---
+
+#### 6. **MIGRATION_GUIDE.md** (11.8KB)
+**Purpose:** Step-by-step migration instructions  
+**Contents:**
+- Three migration paths (hooks, split, JSON)
+- Hook extraction guide
+- Component splitting guide
+- JSON conversion guide
+- Decision matrix
+- Common issues and solutions
+
+**Best for:** Migrating existing components
+
+---
+
+## 🗂️ Code Organization
+
+### Hook Library
+```
+src/hooks/
+├── data/              # 6 hooks (~300 LOC)
+│   ├── use-array.ts
+│   ├── use-crud.ts
+│   ├── use-search.ts
+│   ├── use-debounce.ts
+│   ├── use-sort.ts
+│   └── use-pagination.ts
+├── ui/                # 4 hooks (~120 LOC)
+│   ├── use-dialog.ts
+│   ├── use-tabs.ts
+│   ├── use-selection.ts
+│   └── use-clipboard.ts
+└── forms/             # 2 hooks (~130 LOC)
+    ├── use-form.ts
+    └── use-form-field.ts
+```
+
+### Orchestration Engine
+```
+src/config/orchestration/
+├── schema.ts                 # TypeScript/Zod schemas
+├── action-executor.ts        # Action execution
+├── data-source-manager.ts    # Data management
+├── component-registry.ts     # Component lookup
+├── PageRenderer.tsx          # Main renderer
+└── index.ts                  # Exports
+```
+
+### Example Pages
+```
+src/config/pages/
+├── dashboard.json            # Dashboard example
+└── simple-form.json          # Form example
+```
+
+## 🎓 Learning Path
+
+### Beginner (New to the system)
+1. Read **QUICK_REFERENCE.md** (15 min)
+2. Browse **ARCHITECTURE_VISUAL_GUIDE.md** (10 min)
+3. Try a simple hook from examples (30 min)
+
+**Total:** ~1 hour
+
+---
+
+### Intermediate (Ready to build)
+1. Read **COMPLETE_HOOK_LIBRARY.md** (30 min)
+2. Read **JSON_ORCHESTRATION_COMPLETE.md** (45 min)
+3. Build a small feature with hooks (2 hours)
+4. Create a JSON page (1 hour)
+
+**Total:** ~4 hours
+
+---
+
+### Advanced (Migration & patterns)
+1. Read **PHASE4_IMPLEMENTATION_COMPLETE.md** (20 min)
+2. Read **MIGRATION_GUIDE.md** (30 min)
+3. Study existing hook implementations (1 hour)
+4. Migrate a component (2-4 hours)
+5. Create custom composed hooks (2-4 hours)
+
+**Total:** ~8 hours
+
+---
+
+## 🔍 Finding Information
+
+### "How do I...?"
+
+#### Data Management
+- **Store an array?** → `useArray` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#usearray)
+- **Search items?** → `useSearch` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#usesearch)
+- **Sort items?** → `useSort` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#usesort)
+- **Paginate items?** → `usePagination` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#usepagination)
+- **CRUD operations?** → `useCRUD` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#usecrud)
+
+#### UI State
+- **Modal/dialog?** → `useDialog` in [QUICK_REFERENCE.md](./QUICK_REFERENCE.md#ui-hooks)
+- **Tabs?** → `useTabs` in [QUICK_REFERENCE.md](./QUICK_REFERENCE.md#ui-hooks)
+- **Multi-select?** → `useSelection` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#useselection)
+- **Copy to clipboard?** → `useClipboard` in [QUICK_REFERENCE.md](./QUICK_REFERENCE.md#ui-hooks)
+
+#### Forms
+- **Full form?** → `useForm` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#useform)
+- **Single field?** → `useFormField` in [COMPLETE_HOOK_LIBRARY.md](../api/COMPLETE_HOOK_LIBRARY.md#useformfield)
+
+#### JSON Pages
+- **Create a page?** → [JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md#complete-examples)
+- **Define data sources?** → [JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md#2-data-sources)
+- **Add actions?** → [JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md#3-actions)
+- **Build component tree?** → [JSON_ORCHESTRATION_COMPLETE.md](../architecture/JSON_ORCHESTRATION_COMPLETE.md#4-components)
+
+#### Architecture
+- **System design?** → [ARCHITECTURE_VISUAL_GUIDE.md](./ARCHITECTURE_VISUAL_GUIDE.md)
+- **Data flow?** → [ARCHITECTURE_VISUAL_GUIDE.md](./ARCHITECTURE_VISUAL_GUIDE.md#data-flow-diagram)
+- **Migration path?** → [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
+- **How to migrate?** → [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md#-migration-strategy)
+
+---
+
+## 📋 Quick Start Checklist
+
+### Using Hooks
+- [ ] Read hook documentation
+- [ ] Import the hook you need
+- [ ] Use in your component
+- [ ] Test the functionality
+
+### Creating JSON Pages
+- [ ] Read JSON orchestration guide
+- [ ] Create JSON schema file
+- [ ] Define data sources
+- [ ] Build component tree
+- [ ] Add actions
+- [ ] Test with PageRenderer
+
+### Migrating Components
+- [ ] Identify large component
+- [ ] Extract business logic to hooks
+- [ ] Split into smaller components
+- [ ] Create JSON schema (if applicable)
+- [ ] Test thoroughly
+- [ ] Remove old code
+
+---
+
+## 🎯 Key Concepts Summary
+
+### Hooks
+- **Purpose:** Extract and reuse business logic
+- **Size:** All under 150 LOC
+- **Location:** `/src/hooks/`
+- **Examples:** useArray, useCRUD, useSearch, useDialog, useForm
+
+### JSON Orchestration
+- **Purpose:** Define pages without code
+- **Format:** JSON schema files
+- **Location:** `/src/config/pages/`
+- **Benefits:** Rapid prototyping, easy testing, no rebuilds
+
+### Component Size
+- **Target:** Under 150 LOC
+- **Strategy:** Extract logic to hooks
+- **Focus:** Presentation only
+- **Benefits:** Readable, maintainable, testable
+
+---
+
+## 📊 Statistics
+
+### Code Written
+- **12+ custom hooks** (~550 LOC)
+- **5 orchestration files** (~325 LOC)
+- **2 example JSON pages** (~120 LOC)
+- **5 documentation files** (~54KB)
+
+### Metrics
+- ✅ All hooks < 150 LOC
+- ✅ All orchestration files < 85 LOC
+- ✅ Full type safety (TypeScript + Zod)
+- ✅ Zero breaking changes
+- ✅ Backward compatible
+
+---
+
+## 🆘 Getting Help
+
+### Documentation Issues
+1. Check this index
+2. Search within specific docs
+3. Review code examples
+4. Check `/src/config/pages/` for examples
+
+### Code Issues
+1. Review hook implementations in `/src/hooks/`
+2. Check component registry
+3. Validate JSON schemas with Zod
+4. Enable debug mode on PageRenderer
+
+### Questions
+1. What are you trying to do?
+2. Which doc is most relevant?
+3. Have you checked the examples?
+4. Need a custom solution?
+
+---
+
+## 🔗 Related Files
+
+### Implementation
+- `/src/hooks/` - Hook implementations
+- `/src/config/orchestration/` - Engine code
+- `/src/config/pages/` - Example pages
+
+### Documentation (This Section)
+- `QUICK_REFERENCE.md` - Fast lookup
+- `COMPLETE_HOOK_LIBRARY.md` - Hook API
+- `JSON_ORCHESTRATION_COMPLETE.md` - JSON guide
+- `PHASE4_IMPLEMENTATION_COMPLETE.md` - Summary
+- `ARCHITECTURE_VISUAL_GUIDE.md` - Diagrams
+
+### Legacy Documentation
+- `REFACTOR_PHASE4_COMPLETE.md` - Original plan
+- `HOOK_LIBRARY_DOCS.md` - Early hook docs
+- `JSON_ORCHESTRATION_GUIDE.md` - Early JSON docs
+
+---
+
+## ✨ What's Next?
+
+### Immediate Actions
+1. ✅ Hook library created
+2. ✅ Orchestration engine built
+3. ✅ Documentation written
+4. ✅ Examples provided
+
+### Your Next Steps
+1. 📖 Read QUICK_REFERENCE.md
+2. 🔨 Try using a hook
+3. 📄 Create a JSON page
+4. 🔄 Migrate a component
+
+### Future Enhancements
+- Visual JSON schema editor
+- More hook utilities
+- Advanced patterns
+- Performance profiling
+- Analytics integration
+
+---
+
+**Last Updated:** Phase 4 Implementation  
+**Status:** ✅ Complete  
+**Version:** 4.0.0  
+**Breaking Changes:** None  
+**Migration:** Optional (gradual)
+
+---
+
+## 📚 Full Documentation Tree
+
+```
+Documentation/
+├── INDEX.md (this file)           # Navigation hub
+├── QUICK_REFERENCE.md             # Fast lookup guide
+├── COMPLETE_HOOK_LIBRARY.md       # Hook API reference
+├── JSON_ORCHESTRATION_COMPLETE.md # JSON orchestration guide
+├── MIGRATION_GUIDE.md             # Migration instructions
+├── PHASE4_IMPLEMENTATION_COMPLETE.md # Summary
+└── ARCHITECTURE_VISUAL_GUIDE.md   # Visual diagrams
+
+Code/
+├── src/hooks/                     # Hook implementations
+├── src/config/orchestration/      # Engine code
+└── src/config/pages/              # Example JSON pages
+```
+
+---
+
+**Happy Coding! 🚀**

docs/reference/ROADMAP.md

@@ -0,0 +1,428 @@
+# 🗺️ CodeForge Product Roadmap
+
+## Vision
+
+CodeForge aims to become the most comprehensive low-code platform for full-stack application development, combining visual design tools, direct code editing, and AI-powered generation to accelerate development while maintaining professional code quality.
+
+## Release History
+
+### v1.0 - Foundation (Completed)
+**Release Date:** Initial Release
+
+Core low-code platform with essential designers:
+- ✅ Monaco Code Editor integration with syntax highlighting
+- ✅ Multi-file editing with tabs
+- ✅ Prisma Schema Designer with visual model builder
+- ✅ Component Tree Builder for React hierarchies
+- ✅ File Explorer with add/delete capabilities
+- ✅ Project export functionality
+- ✅ Auto-save to persistent storage
+
+### v1.1 - Enhanced Theming (Completed)
+**Release Date:** Week 2
+
+Advanced theming capabilities:
+- ✅ Material UI Theme Designer
+- ✅ Color palette customization
+- ✅ Typography configuration
+- ✅ Spacing and border radius controls
+- ✅ Live theme preview
+
+### v2.0 - AI Integration (Completed)
+**Release Date:** Week 3
+
+OpenAI-powered generation across all features:
+- ✅ Complete application generation from descriptions
+- ✅ AI-powered model generation
+- ✅ AI-powered component generation
+- ✅ Code explanation feature in editor
+- ✅ Code improvement suggestions
+- ✅ Natural language to code translation
+
+### v2.1 - Multi-Theme Variants (Completed)
+**Release Date:** Week 4
+
+Extended theme system:
+- ✅ Multiple theme variants (light, dark, custom)
+- ✅ Unlimited custom colors beyond standard palette
+- ✅ Theme variant switching
+- ✅ AI theme generation with accessibility checks
+- ✅ WCAG contrast validation
+
+### v3.0 - Testing Suite (Completed)
+**Release Date:** Week 5
+
+Comprehensive testing tools:
+- ✅ Playwright E2E Test Designer
+- ✅ Storybook Story Designer
+- ✅ Unit Test Designer (components, functions, hooks, integration)
+- ✅ Visual test step configuration
+- ✅ AI test generation for all test types
+- ✅ Test export with proper file structure
+
+### v3.1 - Error Detection & Repair (Completed)
+**Release Date:** Week 6
+
+Automated quality assurance:
+- ✅ Syntax error detection
+- ✅ Import error detection
+- ✅ TypeScript type error detection
+- ✅ ESLint violation detection
+- ✅ AI-powered error repair
+- ✅ Context-aware fixes using related files
+- ✅ Batch repair functionality
+- ✅ Repair explanations
+
+### v3.2 - UI Improvements (Completed)
+**Release Date:** Week 7
+
+Enhanced user experience:
+- ✅ Multi-row tab support for many open features
+- ✅ Responsive layout improvements
+- ✅ Better error state visualization
+- ✅ Improved empty states across designers
+- ✅ Loading states for AI operations
+
+### v4.0 - Full-Stack Development (Completed)
+**Release Date:** Week 8
+
+Backend and configuration tools:
+- ✅ Flask Backend Designer with blueprints
+- ✅ REST API endpoint configuration
+- ✅ CORS and authentication settings
+- ✅ Next.js settings designer
+- ✅ npm package management
+- ✅ Build script configuration
+- ✅ Package manager selection (npm/yarn/pnpm)
+- ✅ Complete project settings control
+
+### v4.1 - Enhanced Export & Documentation (Completed)
+**Release Date:** Week 9
+
+Improved export and comprehensive documentation:
+- ✅ ZIP file download for complete project export
+- ✅ Auto-generated README in exported projects
+- ✅ Copy all files to clipboard functionality
+- ✅ Comprehensive in-app documentation system
+- ✅ Sass styles guide with live examples
+- ✅ Complete roadmap documentation
+- ✅ AI agents architecture documentation
+- ✅ Project dashboard with completion metrics
+- ✅ Keyboard shortcuts for power users
+- ✅ Search functionality in documentation
+
+### v5.0 - Workflows, Lambdas & Feature Toggles (Completed)
+**Release Date:** Week 10
+
+Advanced automation and customization:
+- ✅ n8n-style workflow designer with visual node editor
+- ✅ Workflow nodes: triggers, actions, conditions, transforms, lambdas, API calls, database queries
+- ✅ Visual workflow connections and data flow
+- ✅ Lambda function designer with Monaco editor
+- ✅ Multi-runtime lambda support (JavaScript, TypeScript, Python)
+- ✅ Lambda triggers (HTTP, schedule, event, queue)
+- ✅ Environment variable management for lambdas
+- ✅ Multiple Component Trees management system
+- ✅ Feature toggle system to enable/disable designers
+- ✅ Customizable workspace based on user needs
+
+### v5.1 - CI/CD Integration (Completed)
+**Release Date:** Week 11
+
+Comprehensive DevOps pipeline configuration:
+- ✅ GitHub Actions workflow generator
+- ✅ GitLab CI/CD pipeline configuration
+- ✅ Jenkins pipeline (Jenkinsfile) generation
+- ✅ CircleCI configuration
+- ✅ Multi-stage builds and deployments
+- ✅ Environment-specific configurations
+- ✅ Automated testing in pipelines
+- ✅ Docker integration in CI/CD
+- ✅ Deployment strategies configuration
+
+### v5.2 - Project Persistence (Completed)
+**Release Date:** Week 12
+
+Complete project management system:
+- ✅ Save projects to Spark KV database
+- ✅ Load projects from database
+- ✅ Project listing with metadata (name, description, timestamps)
+- ✅ Duplicate existing projects
+- ✅ Delete projects from database
+- ✅ Export projects as JSON files
+- ✅ Import projects from JSON
+- ✅ New project creation with state reset
+- ✅ Current project indicator
+- ✅ Complete state persistence (files, models, components, trees, workflows, lambdas, themes, tests, settings)
+
+### v5.3 - Progressive Web App (Completed)
+**Release Date:** Week 13
+
+Full PWA capabilities for offline-first experience:
+- ✅ Service Worker with intelligent caching strategies
+- ✅ Web App Manifest with icons and metadata
+- ✅ Install prompt for desktop and mobile
+- ✅ Offline functionality with cache fallbacks
+- ✅ Update notifications when new version available
+- ✅ Network status indicator
+- ✅ Push notification support
+- ✅ App shortcuts for quick access
+- ✅ Share target API integration
+- ✅ Background sync capabilities
+- ✅ PWA settings panel for cache management
+- ✅ Installability detection and prompts
+
+## Upcoming Releases
+
+### v5.4 - Real-Time Preview (In Planning)
+**Estimated:** Q2 2024
+
+Live application preview:
+- [ ] Embedded iframe preview pane
+- [ ] Hot reload on code/config changes
+- [ ] Multiple device viewport simulation
+- [ ] Browser DevTools integration
+- [ ] Console output capture
+- [ ] Network request monitoring
+
+**Technical Challenges:**
+- Sandboxed execution environment
+- Hot module replacement (HMR) configuration
+- State preservation across reloads
+- Error boundary implementation
+
+### v4.3 - Data Management (In Planning)
+**Estimated:** Q2 2024
+
+Database and API integration:
+- [ ] Database seeding designer
+- [ ] Sample data generation with AI
+- [ ] API client generator from Flask definitions
+- [ ] Request/response type generation
+- [ ] API testing playground
+- [ ] Mock data management
+
+**Features:**
+- Visual seed data builder
+- Realistic data generation with AI
+- TypeScript API client with fetch/axios
+- Automatic type inference from endpoints
+
+### v4.4 - Form Builder (In Planning)
+**Estimated:** Q2-Q3 2024
+
+Visual form design:
+- [ ] Drag-and-drop form builder
+- [ ] Field type library (text, email, select, etc.)
+- [ ] Validation rule configuration
+- [ ] Conditional field visibility
+- [ ] Multi-step form support
+- [ ] Form submission handling
+- [ ] Integration with Prisma models
+
+**Technologies:**
+- React Hook Form integration
+- Zod schema validation
+- Material UI form components
+
+### v4.5 - Authentication & Security (In Planning)
+**Estimated:** Q3 2024
+
+Complete authentication system:
+- [ ] Authentication strategy designer
+- [ ] JWT configuration (frontend + backend)
+- [ ] OAuth provider integration (Google, GitHub, etc.)
+- [ ] Session management
+- [ ] Role-based access control (RBAC)
+- [ ] Protected route configuration
+- [ ] Password reset flows
+- [ ] Email verification flows
+
+**Security Features:**
+- HTTPS enforcement
+- CSRF protection
+- Rate limiting configuration
+- Security headers (CORS, CSP, etc.)
+- Input sanitization rules
+
+**Docker & Deployment:**
+- [ ] Dockerfile generation
+- [ ] docker-compose configuration
+- [ ] Environment variable management
+- [ ] Production vs development configs
+- [ ] Container orchestration templates
+
+### v5.1 - GraphQL Support (In Planning)
+**Estimated:** Q3 2024
+
+Alternative to REST APIs:
+- [ ] GraphQL schema designer
+- [ ] Resolver configuration
+- [ ] Query and mutation builder
+- [ ] Subscription support
+- [ ] Apollo Server integration
+- [ ] GraphQL client generation
+- [ ] Schema validation and introspection
+
+**Features:**
+- Visual schema builder with types and relations
+- Automatic resolver generation from Prisma
+- GraphQL Playground integration
+- Type-safe client with generated hooks
+
+### v5.2 - State Management (In Planning)
+**Estimated:** Q3-Q4 2024
+
+Advanced state patterns:
+- [ ] State management strategy selector
+- [ ] Redux Toolkit configuration
+- [ ] Zustand store designer
+- [ ] Jotai atom configuration
+- [ ] Global state designer
+- [ ] Action/reducer builder
+- [ ] Async state management (React Query)
+- [ ] State persistence configuration
+
+**Designer Features:**
+- Visual state flow diagrams
+- Action dispatching visualization
+- State inspection and debugging
+- Performance optimization suggestions
+
+### v5.3 - CI/CD & DevOps (In Planning)
+**Estimated:** Q4 2024
+
+Automated deployment pipelines:
+- [ ] GitHub Actions workflow generator
+- [ ] GitLab CI configuration
+- [ ] CircleCI pipeline builder
+- [ ] Automated testing in CI
+- [ ] Build and deployment stages
+- [ ] Environment-specific configs
+- [ ] Secrets management
+- [ ] Deployment notifications
+
+**Integrations:**
+- Vercel deployment
+- Netlify deployment
+- AWS deployment (ECS, Lambda)
+- Docker registry push
+- Database migration in CI
+
+### v6.0 - Component Libraries & Design Systems (In Planning)
+**Estimated:** Q4 2024
+
+Advanced design tooling:
+- [ ] Component library export as npm package
+- [ ] Design token management
+- [ ] Component documentation generator
+- [ ] Design system designer
+- [ ] Variant system configuration
+- [ ] Accessibility annotations
+- [ ] Component playground
+
+**Features:**
+- Automatic package.json for library
+- TypeScript declaration generation
+- Component prop documentation
+- Usage examples generation
+- Versioning and changelog
+
+### v6.1 - Collaboration (In Planning)
+**Estimated:** Q1 2025
+
+Team development features:
+- [ ] Real-time collaborative editing
+- [ ] User presence indicators
+- [ ] Comment system on code/designs
+- [ ] Change history and versioning
+- [ ] Branch/fork functionality
+- [ ] Merge conflict resolution
+- [ ] Team permissions and roles
+
+**Technical Requirements:**
+- WebSocket or WebRTC for real-time sync
+- Operational transformation (OT) or CRDT
+- User authentication and authorization
+- Activity logging and audit trails
+
+## Future Considerations (v7.0+)
+
+### Advanced AI Features
+- [ ] Conversational development interface
+- [ ] AI pair programming mode
+- [ ] Learning from user corrections
+- [ ] Project-specific AI training
+- [ ] Multi-model AI strategy (Claude, Gemini, etc.)
+- [ ] AI code review agent
+- [ ] Security vulnerability scanning with AI
+
+### Platform Expansion
+- [ ] Vue.js and Svelte support
+- [ ] Angular application generation
+- [ ] Mobile app generation (React Native)
+- [ ] Desktop app generation (Electron)
+- [ ] WordPress plugin generation
+- [ ] Shopify theme development
+
+### Advanced Integrations
+- [ ] Database provider integration (PostgreSQL, MySQL, MongoDB)
+- [ ] Cloud service integration (AWS, Azure, GCP)
+- [ ] Third-party API integration designer
+- [ ] Webhook configuration
+- [ ] Message queue integration (RabbitMQ, Kafka)
+- [ ] Caching layer configuration (Redis)
+
+### Enterprise Features
+- [ ] Self-hosted deployment option
+- [ ] Single sign-on (SSO)
+- [ ] Audit logging
+- [ ] Compliance reporting (GDPR, SOC2)
+- [ ] Custom AI model hosting
+- [ ] Enterprise support and SLAs
+
+### Community & Ecosystem
+- [ ] Template marketplace
+- [ ] Component marketplace
+- [ ] Plugin system for custom designers
+- [ ] Public project sharing
+- [ ] Community themes and palettes
+- [ ] Tutorial and learning platform
+
+## Feature Prioritization
+
+Features are prioritized based on:
+
+1. **User Impact** - How many users benefit and how significantly
+2. **Technical Feasibility** - Development complexity and dependencies
+3. **Strategic Value** - Alignment with long-term product vision
+4. **Resource Availability** - Team capacity and expertise
+5. **Market Demand** - User requests and competitive landscape
+
+## Feedback & Contributions
+
+We welcome feedback on the roadmap! If you have feature requests or want to contribute to development:
+
+1. Open an issue describing the feature request
+2. Participate in roadmap discussions
+3. Contribute code for planned features
+4. Share use cases and requirements
+
+## Versioning Strategy
+
+- **Major versions (x.0)** - Significant new capabilities, potential breaking changes
+- **Minor versions (x.y)** - New features, backwards compatible
+- **Patch versions (x.y.z)** - Bug fixes and small improvements
+
+## Release Cadence
+
+- **Major releases:** Quarterly
+- **Minor releases:** Monthly
+- **Patch releases:** As needed
+
+---
+
+**Last Updated:** Current
+**Next Review:** After v4.1 release
+
+For more details on current features, see the [README](./README.md) and [PRD](./PRD.md).

docs/reference/SECURITY.md

@@ -0,0 +1,31 @@
+Thanks for helping make GitHub safe for everyone.
+
+# Security
+
+GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub).
+
+Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. 
+
+## Reporting Security Issues
+
+If you believe you have found a security vulnerability in any GitHub-owned repository, please report it to us through coordinated disclosure.
+
+**Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.**
+
+Instead, please send an email to opensource-security[@]github.com.
+
+Please include as much of the information listed below as you can to help us better understand and resolve the issue:
+
+  * The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+## Policy
+
+See [GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)

docs/testing/CONNECTION_TEST_PLAN.md

@@ -0,0 +1,187 @@
+# Connection 1:1 Constraint Test Plan
+
+## Issue Description
+Two purple arrows (or multiple arrows) coming from the same connection point on an idea card. Each handle should support exactly ONE connection (1:1 constraint).
+
+## Implementation Details
+
+### Core Logic
+The `validateAndRemoveConflicts` function enforces the 1:1 constraint:
+- For any new connection, it checks all existing edges
+- Removes edges that conflict with the source handle OR target handle
+- Returns filtered edges, count of removed edges, and conflict descriptions
+
+### Key Functions Modified
+1. **onConnect** - Creates new connections with conflict resolution
+2. **onReconnect** - Remaps existing connections with conflict resolution
+3. **validateAndRemoveConflicts** - Core validation logic (new)
+
+## Test Cases
+
+### Test Case 1: Basic Connection Creation
+**Steps:**
+1. Go to Feature Idea Cloud
+2. Click the 🔍 Debug button to open the debug panel
+3. Drag from Idea A's right handle to Idea B's left handle
+4. Verify in debug panel that:
+   - Idea A's right handle shows ✓ (occupied)
+   - Idea B's left handle shows ✓ (occupied)
+   - Total edges increased by 1
+
+**Expected Result:** Connection created successfully, both handles marked as occupied
+
+### Test Case 2: Prevent Multiple Connections from Same Source Handle
+**Steps:**
+1. Create connection: Idea A[right] → Idea B[left]
+2. Verify connection exists in debug panel
+3. Try to create: Idea A[right] → Idea C[left]
+4. Check debug panel and toast notification
+
+**Expected Result:**
+- Toast shows "Connection remapped! (1 old connection removed)"
+- Idea A's right handle now connects to Idea C only
+- Old connection to Idea B is removed
+- Debug panel shows only 1 connection from Idea A's right handle
+
+### Test Case 3: Prevent Multiple Connections to Same Target Handle
+**Steps:**
+1. Create connection: Idea A[right] → Idea B[left]
+2. Try to create: Idea C[right] → Idea B[left]
+3. Check debug panel
+
+**Expected Result:**
+- Toast shows "Connection remapped! (1 old connection removed)"
+- Idea B's left handle now connects from Idea C only
+- Old connection from Idea A is removed
+- Debug panel shows only 1 connection to Idea B's left handle
+
+### Test Case 4: Reconnection (Remapping) from Source
+**Steps:**
+1. Create connection: Idea A[right] → Idea B[left]
+2. Drag the source end (at Idea A) to Idea A's bottom handle
+3. Check debug panel
+
+**Expected Result:**
+- Connection now goes from Idea A[bottom] → Idea B[left]
+- Idea A's right handle is now free (○)
+- Idea A's bottom handle is now occupied (✓)
+- Toast shows "Connection remapped!"
+
+### Test Case 5: Reconnection (Remapping) to Different Target
+**Steps:**
+1. Create connection: Idea A[right] → Idea B[left]
+2. Drag the target end (at Idea B) to Idea C's left handle
+3. Check debug panel
+
+**Expected Result:**
+- Connection now goes from Idea A[right] → Idea C[left]
+- Idea B's left handle is now free (○)
+- Idea C's left handle is now occupied (✓)
+
+### Test Case 6: Reconnection with Conflict Resolution
+**Steps:**
+1. Create connection 1: Idea A[right] → Idea B[left]
+2. Create connection 2: Idea C[right] → Idea D[left]
+3. Drag connection 2's target from Idea D to Idea B's left handle
+4. Check debug panel
+
+**Expected Result:**
+- Connection 1 is removed (conflict on Idea B's left handle)
+- Connection 2 now goes: Idea C[right] → Idea B[left]
+- Toast shows "Connection remapped! (1 conflicting connection removed)"
+- Idea B's left handle shows only 1 connection total
+
+### Test Case 7: Database Persistence
+**Steps:**
+1. Create several connections with various conflict resolutions
+2. Note the final state in the debug panel
+3. Refresh the page (F5)
+4. Open debug panel again
+
+**Expected Result:**
+- All connections persist exactly as they were
+- No duplicate connections on any handle
+- Debug panel shows same state as before refresh
+
+### Test Case 8: Console Logging Verification
+**Steps:**
+1. Open browser DevTools console
+2. Create a new connection
+3. Look for log entries starting with `[Connection]`
+
+**Expected Result:**
+```
+[Connection] New connection attempt: { source: "idea-X[right]", target: "idea-Y[left]" }
+[Connection Validator] Conflicts detected and resolved: [...]  // (if conflicts exist)
+[Connection] New edge created: edge-123456789
+[Connection] Total edges after addition: N
+[Connection] Edges by handle: [...]
+```
+
+### Test Case 9: Multiple Handles Per Node
+**Steps:**
+1. Create 4 different connections from a single idea using all 4 handles:
+   - Idea A[left] ← Idea B[right]
+   - Idea A[right] → Idea C[left]
+   - Idea A[top] ← Idea D[bottom]
+   - Idea A[bottom] → Idea E[top]
+2. Check debug panel for Idea A
+
+**Expected Result:**
+- All 4 handles show ✓ (occupied)
+- Total connections for Idea A: 4
+- Each handle has exactly 1 connection
+- No conflicts exist
+
+### Test Case 10: Edge Case - Same Source and Target
+**Steps:**
+1. Create connection: Idea A[right] → Idea B[left]
+2. Create connection: Idea C[right] → Idea D[left]
+3. Remap connection 2 to: Idea A[right] → Idea B[left]
+
+**Expected Result:**
+- Connection 1 is removed (conflicts on BOTH source AND target)
+- Connection 2 takes over both handles
+- Toast shows "Connection remapped! (1 conflicting connection removed)"
+- Only 1 arrow exists between Idea A and Idea B
+
+## Visual Indicators in Debug Panel
+
+The debug panel shows a grid for each idea card with 4 handle positions:
+- `← ✓` or `← ○` (left handle - incoming)
+- `→ ✓` or `→ ○` (right handle - outgoing)
+- `↑ ✓` or `↑ ○` (top handle - incoming)
+- `↓ ✓` or `↓ ○` (bottom handle - outgoing)
+
+Green background = Handle is occupied (✓)
+Gray background = Handle is free (○)
+
+## Success Criteria
+
+✅ All test cases pass
+✅ No multiple arrows from/to same connection point
+✅ Automatic conflict resolution works correctly
+✅ Changes persist to database
+✅ Console logs provide clear debugging information
+✅ Toast notifications inform user of remapping
+✅ Debug panel accurately reflects connection state
+
+## How to Run Tests
+
+1. Navigate to Feature Idea Cloud page in the app
+2. Click the 🔍 debug icon in the top-right panel
+3. Follow each test case step-by-step
+4. Verify expected results using:
+   - Visual inspection of arrows on canvas
+   - Debug panel handle occupancy display
+   - Toast notifications
+   - Browser console logs
+5. Test persistence by refreshing the page
+
+## Notes for Developer
+
+- The debug panel is ONLY for testing and can be removed once all tests pass
+- All console.log statements with `[Connection]` and `[Reconnection]` prefixes are for debugging
+- The validateAndRemoveConflicts function is the core of the 1:1 constraint
+- Each handle ID is either 'left', 'right', 'top', 'bottom', or 'default'
+- The logic treats missing sourceHandle/targetHandle as 'default'

docs/testing/E2E_TEST_SUMMARY.md

@@ -0,0 +1,295 @@
+# E2E Test Summary
+
+## Overview
+Comprehensive Playwright test suite created to ensure CodeForge functions correctly and generates code as expected.
+
+## What Was Added
+
+### 1. **Playwright Configuration** (`playwright.config.ts`)
+- Configured to run tests across Chromium, Firefox, and WebKit
+- Automatic dev server startup during test execution
+- Screenshots and traces on failure
+- HTML report generation
+
+### 2. **Comprehensive Test Suite** (`e2e/codeforge.spec.ts`)
+21 test suites covering all major features:
+
+#### Core Features
+- ✅ Application loads successfully
+- ✅ All navigation tabs display
+- ✅ Tab switching works
+- ✅ Export functionality present
+
+#### Code Editor
+- ✅ File explorer displays
+- ✅ Monaco editor loads
+- ✅ Add new files
+- ✅ File management
+
+#### Model Designer (Prisma)
+- ✅ Designer opens
+- ✅ Add model button
+- ✅ Create new models
+- ✅ Model management
+
+#### Component Designer
+- ✅ Component tree builder
+- ✅ Add components
+- ✅ Component management
+
+#### Style Designer
+- ✅ Theme editor opens
+- ✅ Light/dark variants
+- ✅ Color pickers functional
+
+#### Export & Code Generation
+- ✅ Export dialog opens
+- ✅ Files generated
+- ✅ ZIP download button
+- ✅ Copy functionality
+- ✅ Valid package.json
+- ✅ Prisma schema generated
+- ✅ Theme configuration generated
+
+#### Settings
+- ✅ Next.js configuration
+- ✅ NPM settings
+- ✅ Package management
+
+#### Feature Toggles
+- ✅ Toggle settings display
+- ✅ Features can be enabled/disabled
+- ✅ Tabs hide when features disabled
+
+#### Workflows
+- ✅ n8n-style workflow designer
+- ✅ Workflow creation
+
+#### Flask API
+- ✅ Flask designer opens
+- ✅ Configuration options
+- ✅ Blueprint management
+
+#### Testing Tools
+- ✅ Playwright designer
+- ✅ Storybook designer
+- ✅ Unit test designer
+
+#### PWA Features
+- ✅ PWA settings
+- ✅ Manifest configuration
+- ✅ Service worker options
+
+#### Additional Features
+- ✅ Favicon designer
+- ✅ Documentation view
+- ✅ Dashboard statistics
+- ✅ Keyboard shortcuts
+- ✅ Project save/load
+- ✅ Error handling
+- ✅ Responsive design (mobile/tablet)
+- ✅ No console errors
+
+### 3. **Smoke Test Suite** (`e2e/smoke.spec.ts`)
+Quick validation tests for CI/CD (17 critical tests):
+- ✅ App loads successfully with correct branding
+- ✅ All major tabs navigation (Dashboard, Code Editor, Models, Components, Component Trees, Workflows, Lambdas, Styling, Flask API, Settings, PWA, Features)
+- ✅ Project export and code generation dialog
+- ✅ Monaco editor loads in code editor
+- ✅ Model designer functionality
+- ✅ Component tree manager loads
+- ✅ Workflow designer loads
+- ✅ Lambda designer with Monaco editor
+- ✅ Style designer with color pickers
+- ✅ Flask API designer
+- ✅ PWA settings
+- ✅ Feature toggles functionality
+- ✅ Project save/load manager
+- ✅ Dashboard metrics display
+- ✅ Keyboard shortcuts dialog
+- ✅ No critical console errors
+- ✅ Responsive mobile viewport
+
+### 4. **NPM Scripts** (package.json)
+```bash
+npm run test:e2e          # Run all tests
+npm run test:e2e:ui       # Interactive UI mode
+npm run test:e2e:headed   # Watch tests run
+npm run test:e2e:smoke    # Quick smoke tests
+npm run test:e2e:debug    # Debug mode
+npm run test:e2e:report   # View HTML report
+```
+
+### 5. **CI/CD Integration**
+
+#### GitHub Actions (`.github/workflows/e2e-tests.yml`)
+- Runs on push/PR to main/develop
+- Installs Playwright browsers
+- Executes full test suite
+- Uploads reports as artifacts
+
+#### GitLab CI (`.gitlab-ci.yml`)
+- Updated to use latest Playwright image
+- Runs E2E tests in test stage
+- Artifacts include reports and test results
+- No longer allows failure
+
+#### CircleCI (`.circleci/config.yml`)
+- Updated Playwright executor to v1.57.0
+- Proper browser installation
+- Test results and artifacts stored
+- Slack notifications on failure
+
+#### Jenkins (`Jenkinsfile`)
+- E2E stage with Playwright installation
+- HTML report publishing
+- Test results archiving
+- Branch-specific execution
+
+### 6. **Documentation** (`e2e/README.md`)
+Comprehensive guide including:
+- Quick start instructions
+- Test structure explanation
+- Coverage matrix
+- Writing new tests
+- Best practices
+- Debugging guide
+- CI/CD examples
+- Common issues and solutions
+
+## Test Execution
+
+### Local Development
+```bash
+# Install browsers first
+npx playwright install
+
+# Run smoke tests (fastest - ~30s)
+npm run test:e2e:smoke
+
+# Run all tests with UI (recommended)
+npm run test:e2e:ui
+
+# Run all tests headless
+npm run test:e2e
+```
+
+### CI/CD Pipeline
+Tests automatically run on:
+- Every push to main/develop
+- Pull requests
+- Manual workflow trigger
+
+## Coverage Statistics
+
+| Category | Tests | Coverage |
+|----------|-------|----------|
+| Navigation | 8 | 100% |
+| Code Editor | 4 | 90% |
+| Designers | 15 | 85% |
+| Export | 6 | 100% |
+| Settings | 4 | 100% |
+| PWA | 3 | 100% |
+| Testing Tools | 3 | 100% |
+| Workflows | 2 | 80% |
+| Feature Toggles | 3 | 100% |
+| Error Handling | 2 | 90% |
+| Responsive | 2 | 100% |
+| **TOTAL** | **52+** | **~92%** |
+
+## Key Benefits
+
+1. **Confidence**: Every feature tested automatically
+2. **Regression Prevention**: Catches breaking changes
+3. **Code Quality**: Validates generated code structure
+4. **Documentation**: Tests serve as living documentation
+5. **CI/CD Integration**: Automated testing in all pipelines
+6. **Fast Feedback**: Smoke tests run in ~30 seconds
+7. **Debugging Tools**: UI mode, headed mode, traces, screenshots
+
+## What Gets Validated
+
+### Functional Testing
+- All tabs accessible
+- All designers open and functional
+- Buttons are enabled and clickable
+- Forms accept input
+- Monaco editor loads
+- Code generation works
+
+### Code Generation Quality
+- package.json is valid JSON
+- Prisma schemas generated
+- Theme files created
+- Flask API configuration
+- Next.js settings preserved
+- NPM dependencies included
+
+### Error Detection
+- No critical console errors
+- UI renders without crashes
+- Feature toggles work
+- State persists correctly
+
+### Cross-Browser
+- Chromium (Chrome/Edge)
+- Firefox
+- WebKit (Safari)
+
+### Responsive Design
+- Desktop (1920x1080)
+- Tablet (768x1024)
+- Mobile (375x667)
+
+## Next Steps
+
+### Immediate Actions
+1. Run smoke tests locally: `npm run test:e2e:smoke`
+2. Review test output
+3. Fix any failing tests
+4. Commit and push to trigger CI
+
+### Future Enhancements
+- [ ] Add tests for AI generation feature
+- [ ] Test drag-and-drop in component tree
+- [ ] Test Lambda editor interactions
+- [ ] Add visual regression testing
+- [ ] Test Sass styles showcase
+- [ ] Test CI/CD config generation
+- [ ] Add performance benchmarks
+- [ ] Test offline PWA functionality
+
+## Troubleshooting
+
+### If tests fail:
+1. Check if dev server is running
+2. Clear browser cache: `npx playwright cache clean`
+3. Reinstall browsers: `npx playwright install --force`
+4. Run in UI mode to debug: `npm run test:e2e:ui`
+5. Check screenshots in `test-results/`
+
+### Common Issues:
+- **Monaco not loading**: Increase timeout to 15000ms
+- **Selectors not found**: Check if feature toggle is enabled
+- **Timing issues**: Add `waitForTimeout()` after navigation
+
+## Success Criteria
+
+Tests are passing when:
+- ✅ All smoke tests pass (required for every commit)
+- ✅ Full test suite passes on main/develop
+- ✅ No critical console errors
+- ✅ Code generation produces valid files
+- ✅ All major features accessible
+- ✅ Cross-browser compatibility confirmed
+
+## Maintenance
+
+Update tests when:
+- Adding new features
+- Modifying UI structure
+- Changing navigation
+- Adding new designers
+- Updating dependencies
+
+Keep test coverage above 85% for all new features.

docs/testing/RUN_TESTS.md

@@ -0,0 +1,170 @@
+# How to Run Smoke Tests
+
+## Prerequisites
+
+Ensure Playwright browsers are installed:
+```bash
+npx playwright install
+```
+
+## Running Smoke Tests
+
+### Quick Run (Recommended)
+```bash
+npm run test:e2e:smoke
+```
+
+This will:
+1. Start the Vite dev server on port 5173
+2. Run 17 critical smoke tests
+3. Test across Chromium, Firefox, and WebKit
+4. Generate an HTML report if any tests fail
+
+**Expected Duration**: ~30-60 seconds
+
+## What the Smoke Tests Validate
+
+### ✅ Core Application
+- App loads with correct branding ("CodeForge")
+- No critical JavaScript console errors
+- Responsive design works on mobile viewports
+
+### ✅ Navigation
+- All major tabs are accessible and clickable
+- Tab panels render when selected
+- Tabs include: Dashboard, Code Editor, Models, Components, Component Trees, Workflows, Lambdas, Styling, Flask API, Settings, PWA, Features
+
+### ✅ Code Editor
+- Monaco editor loads properly
+- File explorer is visible
+- Editor has syntax highlighting
+
+### ✅ Designers
+- **Model Designer**: Opens with "Add Model" button enabled
+- **Component Tree Manager**: Displays component trees
+- **Workflow Designer**: Shows workflow creation interface
+- **Lambda Designer**: Loads with Monaco editor support
+- **Style Designer**: Color pickers are functional
+- **Flask API Designer**: Configuration interface loads
+- **PWA Settings**: Progressive Web App options available
+- **Favicon Designer**: Icon design tools accessible
+
+### ✅ Project Management
+- Export project button works
+- Generated code dialog appears
+- Download as ZIP button is enabled
+- package.json is visible in generated files
+- Project save/load functionality exists
+
+### ✅ Features
+- Feature toggles are accessible
+- Toggle switches work properly
+- Keyboard shortcuts dialog opens
+- Dashboard displays project metrics
+
+## Test Results
+
+### Success Indicators
+- All tests show ✓ (green checkmark)
+- Exit code 0
+- Message: "17 passed"
+
+### If Tests Fail
+1. Check the console output for specific failures
+2. View the HTML report: `npm run test:e2e:report`
+3. Run in UI mode for visual debugging: `npm run test:e2e:ui`
+4. Run in headed mode to watch: `npm run test:e2e:headed`
+
+## Debugging Failed Tests
+
+### View HTML Report
+```bash
+npm run test:e2e:report
+```
+Opens a browser with detailed test results, screenshots, and traces.
+
+### Interactive UI Mode
+```bash
+npm run test:e2e:ui
+```
+Opens Playwright's interactive UI to step through tests.
+
+### Watch Tests Run
+```bash
+npm run test:e2e:headed
+```
+Runs tests with browser windows visible.
+
+### Debug Mode
+```bash
+npm run test:e2e:debug
+```
+Runs tests with Playwright Inspector for step-by-step debugging.
+
+## Common Issues
+
+### Issue: "Target closed" or "Navigation timeout"
+**Solution**: Increase timeout in playwright.config.ts webServer settings or check if port 5173 is available.
+
+### Issue: "Cannot find element"
+**Solution**: Check if feature toggles are enabled. Some tabs only appear when features are active.
+
+### Issue: "Monaco editor not found"
+**Solution**: Monaco takes time to load. Tests already wait up to 15 seconds, but may need adjustment on slower systems.
+
+### Issue: Browser not installed
+**Solution**: Run `npx playwright install` to download test browsers.
+
+## CI/CD Integration
+
+These smoke tests run automatically in:
+- ✅ GitHub Actions (on push/PR)
+- ✅ GitLab CI (test stage)
+- ✅ CircleCI (e2e job)
+- ✅ Jenkins (E2E Tests stage)
+
+## Full Test Suite
+
+To run the complete test suite (all features):
+```bash
+npm run test:e2e
+```
+
+This includes 50+ tests covering all functionality in detail.
+
+## Test Coverage
+
+The smoke tests provide ~85% coverage of critical user paths:
+- ✅ 100% of navigation flows
+- ✅ 100% of core designers
+- ✅ 100% of code export functionality
+- ✅ 90% of editor integrations
+- ✅ 85% of feature toggles
+
+## Next Steps After Running Tests
+
+1. ✅ All tests pass → Proceed with confidence
+2. ⚠️ Some tests fail → Review failures, fix issues, rerun
+3. ❌ Many tests fail → Check if dev server started correctly, verify dependencies installed
+
+## Performance Benchmarks
+
+On a typical development machine:
+- **Smoke tests**: 30-60 seconds
+- **Full test suite**: 3-5 minutes
+- **Per-browser**: ~20 seconds additional
+
+## Support
+
+If tests consistently fail or you encounter issues:
+1. Check `E2E_TEST_SUMMARY.md` for detailed documentation
+2. Review `e2e/README.md` for test structure
+3. Check Playwright documentation: https://playwright.dev/
+4. Verify all dependencies are installed: `npm install`
+
+---
+
+**Last Updated**: Iteration 22
+**Test Count**: 17 smoke tests
+**Browsers**: Chromium, Firefox, WebKit
+**Framework**: Playwright v1.57.0

docs/testing/SMOKE_TEST_QUICK_REF.md

@@ -0,0 +1,337 @@
+# 🧪 Smoke Test Quick Reference
+
+## TL;DR - Run Tests Now
+
+```bash
+# 1. Install browsers (first time only)
+npx playwright install
+
+# 2. Run smoke tests
+npm run test:e2e:smoke
+```
+
+**Expected Result**: ✅ All 17 tests pass across 3 browsers in ~30-60 seconds
+
+---
+
+## What Gets Tested
+
+### ✅ 17 Critical Smoke Tests
+
+1. **App Loads** - CodeForge branding appears
+2. **Tab Navigation** - All major tabs accessible
+3. **Code Export** - Project generation works
+4. **Monaco Editor** - Code editor loads
+5. **Model Designer** - Prisma tool functional
+6. **Component Trees** - Tree manager loads
+7. **Workflows** - n8n-style designer works
+8. **Lambdas** - Function editor with Monaco
+9. **Styling** - Theme color pickers
+10. **Flask API** - Backend designer
+11. **PWA Settings** - Progressive web app config
+12. **Feature Toggles** - Toggle switches work
+13. **Project Manager** - Save/load buttons
+14. **Dashboard** - Metrics display
+15. **Keyboard Shortcuts** - Dialog opens
+16. **No Console Errors** - Clean execution
+17. **Mobile Responsive** - Works at 375px width
+
+### 🌐 Tested Across 3 Browsers
+- Chromium (Chrome/Edge)
+- Firefox
+- WebKit (Safari)
+
+**Total Test Executions**: 51 (17 tests × 3 browsers)
+
+---
+
+## Quick Commands
+
+```bash
+# Validate test setup
+bash validate-tests.sh
+
+# Smoke tests (fastest)
+npm run test:e2e:smoke
+
+# Interactive UI mode (best for debugging)
+npm run test:e2e:ui
+
+# Watch tests run (see browser)
+npm run test:e2e:headed
+
+# Full test suite (50+ tests)
+npm run test:e2e
+
+# View last test report
+npm run test:e2e:report
+```
+
+---
+
+## Expected Output
+
+### ✅ Success Looks Like
+
+```
+Running 17 tests using 3 workers
+
+  ✓ app loads successfully (Chromium)
+  ✓ can navigate to all major tabs (Chromium)
+  ✓ can export project and generate code (Chromium)
+  ✓ Monaco editor loads in code editor (Chromium)
+  ✓ model designer is functional (Chromium)
+  ...
+  ✓ no critical console errors (WebKit)
+  ✓ app is responsive on mobile viewport (WebKit)
+
+  51 passed (45s)
+```
+
+### ❌ Failure Looks Like
+
+```
+Running 17 tests using 3 workers
+
+  ✓ app loads successfully (Chromium)
+  ✓ can navigate to all major tabs (Chromium)
+  ✗ Monaco editor loads in code editor (Chromium)
+    
+    Error: Timed out waiting for selector ".monaco-editor"
+    
+  ...
+  
+  48 passed (1m 12s)
+  3 failed
+```
+
+**Action**: Check `test-results/` for screenshots and traces
+
+---
+
+## Troubleshooting
+
+### Issue: Browsers not installed
+```bash
+npx playwright install
+```
+
+### Issue: Port 5173 already in use
+```bash
+# Kill existing dev server
+npm run kill
+
+# Or use a different port in playwright.config.ts
+```
+
+### Issue: Tests timeout
+```bash
+# Increase timeout in playwright.config.ts
+# Or run with more time:
+npm run test:e2e:smoke -- --timeout=60000
+```
+
+### Issue: Tests are flaky
+```bash
+# Run in UI mode to debug
+npm run test:e2e:ui
+
+# Run specific test
+npm run test:e2e:smoke -- -g "app loads"
+```
+
+### Issue: Monaco editor not found
+**Solution**: Already handled! Tests wait up to 15 seconds for Monaco to load.
+
+---
+
+## Test Files
+
+| File | Purpose | Tests |
+|------|---------|-------|
+| `e2e/smoke.spec.ts` | Quick validation | 17 |
+| `e2e/codeforge.spec.ts` | Comprehensive suite | 50+ |
+| `playwright.config.ts` | Test configuration | - |
+
+---
+
+## CI/CD Integration
+
+Tests run automatically on:
+- ✅ Every push to main/develop
+- ✅ All pull requests
+- ✅ Manual triggers
+
+**Platforms Configured:**
+- GitHub Actions
+- GitLab CI
+- CircleCI
+- Jenkins
+
+---
+
+## Performance Benchmarks
+
+| Test Suite | Duration | Coverage |
+|------------|----------|----------|
+| Smoke Tests | 30-60s | ~85% |
+| Full Suite | 3-5min | ~92% |
+
+**Per Browser**: +15-20 seconds
+
+---
+
+## Validation Checklist
+
+Before running tests, ensure:
+- [ ] Node.js installed
+- [ ] npm dependencies installed (`npm install`)
+- [ ] Playwright browsers installed (`npx playwright install`)
+- [ ] Port 5173 available
+- [ ] No dev server already running
+
+**Quick Validation**: `bash validate-tests.sh`
+
+---
+
+## Understanding Results
+
+### Test Status Icons
+- ✓ **Green checkmark** = Test passed
+- ✗ **Red X** = Test failed
+- ⊘ **Circle with slash** = Test skipped
+- ⏸ **Pause** = Test flaky/retried
+
+### Exit Codes
+- `0` = All tests passed
+- `1` = One or more tests failed
+
+### Artifacts Generated
+- `test-results/` - Screenshots and traces
+- `playwright-report/` - HTML report
+- Console output with test summary
+
+---
+
+## Next Steps After Running Tests
+
+### ✅ All Tests Pass
+1. Proceed with deployment/merge
+2. Review performance metrics
+3. Check for any warnings
+
+### ⚠️ Some Tests Fail
+1. Check which tests failed
+2. View screenshots: `test-results/`
+3. Open HTML report: `npm run test:e2e:report`
+4. Debug failing test: `npm run test:e2e:ui`
+5. Fix issues and rerun
+
+### ❌ Many Tests Fail
+1. Verify dev server starts: `npm run dev`
+2. Check for console errors in app
+3. Ensure all dependencies installed
+4. Reinstall Playwright browsers
+5. Run validation script: `bash validate-tests.sh`
+
+---
+
+## Getting Help
+
+### Documentation
+- `e2e/README.md` - Detailed E2E test guide
+- `E2E_TEST_SUMMARY.md` - Complete test coverage
+- `RUN_TESTS.md` - Full test execution guide
+- `SMOKE_TEST_REPORT.md` - Test report template
+
+### Debugging Tools
+```bash
+# Interactive UI (recommended)
+npm run test:e2e:ui
+
+# Playwright Inspector
+npm run test:e2e:debug
+
+# Headed mode (watch browser)
+npm run test:e2e:headed
+
+# View trace file
+npx playwright show-trace test-results/.../trace.zip
+```
+
+### Resources
+- [Playwright Docs](https://playwright.dev/)
+- [GitHub Issues](https://github.com/microsoft/playwright/issues)
+
+---
+
+## Success Metrics
+
+### Test Passes ✅ When:
+- All 17 smoke tests execute successfully
+- No critical console errors detected
+- All major features are accessible
+- Code generation produces valid files
+- Tests complete in < 90 seconds
+- Works across all 3 browsers
+
+### Known Safe Warnings:
+- React DevTools not installed
+- favicon.ico 404 errors
+- manifest.json 404 warnings
+- Source map missing warnings
+
+---
+
+## Pro Tips
+
+1. **Run smoke tests before every commit**
+   ```bash
+   npm run test:e2e:smoke
+   ```
+
+2. **Use UI mode for development**
+   ```bash
+   npm run test:e2e:ui
+   ```
+
+3. **Filter tests by name**
+   ```bash
+   npm run test:e2e:smoke -- -g "Monaco"
+   ```
+
+4. **Run on single browser**
+   ```bash
+   npm run test:e2e:smoke -- --project=chromium
+   ```
+
+5. **Update snapshots if needed**
+   ```bash
+   npm run test:e2e:smoke -- -u
+   ```
+
+---
+
+## Test Coverage Summary
+
+| Feature | Covered | Notes |
+|---------|---------|-------|
+| App Loading | ✅ | Branding, no errors |
+| Navigation | ✅ | All tabs clickable |
+| Code Editor | ✅ | Monaco loads |
+| Designers | ✅ | All 8+ designers |
+| Export | ✅ | Code generation |
+| Project Mgmt | ✅ | Save/load buttons |
+| PWA | ✅ | Settings accessible |
+| Features | ✅ | Toggles work |
+| Responsive | ✅ | Mobile viewport |
+
+**Overall Coverage**: ~85% of critical user paths
+
+---
+
+**Last Updated**: Iteration 22  
+**Playwright Version**: 1.57.0  
+**Test Count**: 17 smoke tests  
+**Browsers**: Chromium, Firefox, WebKit  
+**Execution Time**: 30-60 seconds

docs/testing/SMOKE_TEST_REPORT.md

@@ -0,0 +1,309 @@
+# Smoke Test Execution Report
+
+**Date**: [Automatically filled by test run]  
+**Environment**: Local Development / CI/CD  
+**Test Suite**: e2e/smoke.spec.ts  
+**Total Tests**: 17  
+**Browsers**: Chromium, Firefox, WebKit
+
+---
+
+## Test Execution Summary
+
+| Browser  | Passed | Failed | Skipped | Duration |
+|----------|--------|--------|---------|----------|
+| Chromium | -/17   | -/17   | -/17    | -        |
+| Firefox  | -/17   | -/17   | -/17    | -        |
+| WebKit   | -/17   | -/17   | -/17    | -        |
+| **TOTAL**| **-/51**| **-/51**| **-/51**| **-**   |
+
+---
+
+## Test Results by Category
+
+### ✅ Core Application (3 tests)
+- [ ] App loads successfully with CodeForge branding
+- [ ] No critical console errors detected
+- [ ] Responsive on mobile viewport (375x667)
+
+### ✅ Navigation (1 test)
+- [ ] All major tabs accessible and clickable
+
+### ✅ Code Editor (1 test)
+- [ ] Monaco editor loads and displays properly
+
+### ✅ Designers (8 tests)
+- [ ] Model designer (Prisma) loads with Add Model button
+- [ ] Component tree manager displays
+- [ ] Workflow designer (n8n-style) loads
+- [ ] Lambda designer with Monaco editor
+- [ ] Style designer with color pickers
+- [ ] Flask API designer loads
+- [ ] PWA settings accessible
+- [ ] Feature toggle switches functional
+
+### ✅ Project Management (3 tests)
+- [ ] Export project generates code dialog
+- [ ] Project save/load manager exists
+- [ ] Dashboard displays project metrics
+
+### ✅ UI Components (1 test)
+- [ ] Keyboard shortcuts dialog opens
+
+---
+
+## Detailed Test Results
+
+### Test 1: App loads successfully
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Validates that CodeForge loads with correct branding  
+**Expected**: Header shows "CodeForge" and "Low-Code Next.js App Builder"  
+**Actual**: -  
+**Screenshot**: -  
+
+### Test 2: Can navigate to all major tabs
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests navigation across all feature tabs  
+**Expected**: All tabs clickable and show content  
+**Actual**: -  
+**Tabs Tested**: Dashboard, Code Editor, Models, Components, Component Trees, Workflows, Lambdas, Styling, Flask API, Settings, PWA, Features  
+
+### Test 3: Can export project and generate code
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests project export functionality  
+**Expected**: Dialog appears with ZIP download and package.json visible  
+**Actual**: -  
+
+### Test 4: Monaco editor loads in code editor
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Validates Monaco editor initialization  
+**Expected**: .monaco-editor element visible within 15s  
+**Actual**: -  
+
+### Test 5: Model designer is functional
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests Prisma model designer  
+**Expected**: Models tab shows Add/Create Model button  
+**Actual**: -  
+
+### Test 6: Component tree manager loads
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests component tree management interface  
+**Expected**: Component Trees tab displays tree structure  
+**Actual**: -  
+
+### Test 7: Workflow designer loads
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests n8n-style workflow designer  
+**Expected**: Workflows tab shows Create Workflow button  
+**Actual**: -  
+
+### Test 8: Lambda designer loads with Monaco
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests serverless function editor  
+**Expected**: Lambdas tab shows Create Lambda button  
+**Actual**: -  
+
+### Test 9: Style designer with color pickers loads
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests Material UI theme editor  
+**Expected**: Styling tab shows color input[type="color"]  
+**Actual**: -  
+
+### Test 10: Flask API designer loads
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests Flask backend configuration  
+**Expected**: Flask API tab shows configuration UI  
+**Actual**: -  
+
+### Test 11: PWA settings loads
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests Progressive Web App settings  
+**Expected**: PWA tab shows installation/configuration options  
+**Actual**: -  
+
+### Test 12: Feature toggles work
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests feature flag UI  
+**Expected**: Features tab shows toggle switches  
+**Actual**: -  
+
+### Test 13: Project manager save/load functionality exists
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests project persistence UI  
+**Expected**: Save/Load/New Project buttons visible  
+**Actual**: -  
+
+### Test 14: Dashboard displays project metrics
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests dashboard statistics display  
+**Expected**: Dashboard shows Files/Models/Components metrics  
+**Actual**: -  
+
+### Test 15: Keyboard shortcuts dialog opens
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests keyboard shortcuts UI  
+**Expected**: Keyboard button opens shortcuts dialog  
+**Actual**: -  
+
+### Test 16: No critical console errors
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Monitors browser console for errors  
+**Expected**: No errors except DevTools/favicon/manifest/source maps  
+**Actual**: -  
+**Errors Found**: -  
+
+### Test 17: App is responsive on mobile viewport
+**Status**: ⏳ Pending  
+**Browser**: All  
+**Duration**: -  
+**Description**: Tests mobile responsiveness  
+**Expected**: UI renders correctly at 375x667  
+**Actual**: -  
+
+---
+
+## Console Errors
+
+### Critical Errors (Blocking)
+None expected - test will fail if found
+
+### Warnings (Non-blocking)
+Expected warnings that are safe to ignore:
+- React DevTools messages
+- Favicon 404 errors
+- Manifest 404 errors
+- Source map warnings
+
+### Actual Errors Found
+[To be filled after test run]
+
+---
+
+## Performance Metrics
+
+| Metric | Target | Actual |
+|--------|--------|--------|
+| Initial Load Time | < 3s | - |
+| Monaco Load Time | < 15s | - |
+| Tab Switch Time | < 500ms | - |
+| Export Dialog Time | < 2s | - |
+| Total Test Duration | < 90s | - |
+
+---
+
+## Screenshots
+
+Screenshots are automatically captured on test failure and stored in:
+- `test-results/` directory
+- Organized by test name and browser
+
+---
+
+## Trace Files
+
+Playwright traces are captured on first retry and stored in:
+- `test-results/` directory
+- Can be viewed with: `npx playwright show-trace <trace-file>`
+
+---
+
+## Test Environment
+
+### System Information
+- OS: [To be filled]
+- Node.js: [Version]
+- npm: [Version]
+- Playwright: [Version]
+- Browsers:
+  - Chromium: [Version]
+  - Firefox: [Version]
+  - WebKit: [Version]
+
+### Application Information
+- Base URL: http://localhost:5173
+- Dev Server: Vite
+- Framework: React + TypeScript
+- Test Framework: Playwright
+
+---
+
+## Issues and Recommendations
+
+### Blockers
+[Any critical issues that prevent test execution]
+
+### Known Issues
+[Expected failures or known bugs]
+
+### Recommendations
+[Suggestions for improving test stability or coverage]
+
+---
+
+## Sign-off
+
+**Tested By**: [Name/CI System]  
+**Date**: [Date]  
+**Status**: ⏳ Pending / ✅ Passed / ❌ Failed  
+**Approved**: [ ] Yes [ ] No  
+
+---
+
+## Next Steps
+
+### If All Tests Pass ✅
+1. Proceed with deployment/merge
+2. Update test coverage documentation
+3. Archive this report
+
+### If Tests Fail ❌
+1. Review failed test details above
+2. Check screenshots and traces
+3. Run in debug mode: `npm run test:e2e:debug`
+4. Fix issues and rerun
+5. Update this report with new results
+
+### Follow-up Actions
+- [ ] Review test execution time
+- [ ] Check for flaky tests
+- [ ] Update test documentation if needed
+- [ ] Report any new bugs found
+
+---
+
+**Report Generated**: [Timestamp]  
+**Report Version**: 1.0  
+**Last Updated**: Iteration 22