feat(enhance): add project context to prompt enhancements

* feat(terminal): Add core infrastructure for custom terminal configurations

- Add TerminalConfig types to settings schema (global & project-specific)
- Create RC generator with hex-to-xterm-256 color mapping
- Create RC file manager for .automaker/terminal/ directory
- Add terminal theme color data (40 themes) to platform package
- Integrate terminal config injection into TerminalService
- Support bash, zsh, and sh with proper env var injection (BASH_ENV, ZDOTDIR, ENV)
- Add onThemeChange hook for theme synchronization

Part of custom terminal configurations feature implementation.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(terminal): Wire terminal service with settings service

- Pass SettingsService to TerminalService constructor
- Initialize terminal service with settings service dependency
- Enable terminal config injection to work with actual settings

This completes Steps 1-4 of the terminal configuration plan:
- RC Generator (color mapping, prompt formats)
- RC File Manager (file I/O, atomic writes)
- Settings Schema (GlobalSettings + ProjectSettings)
- Terminal Service Integration (env var injection)

Next steps: Settings UI and theme change hooks.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(terminal): Add Settings UI and theme change synchronization

Complete Steps 5 & 6 of terminal configuration implementation:

Settings UI Components:
- Add PromptPreview component with live theme-aware rendering
- Add TerminalConfigSection with comprehensive controls:
  * Enable/disable toggle with confirmation dialog
  * Custom prompt toggle
  * Prompt format selector (4 formats)
  * Git branch/status toggles
  * Custom aliases textarea
  * Custom env vars key-value editor with validation
  * Info box explaining behavior
- Integrate into existing TerminalSection

Theme Change Hook:
- Add theme detection in update-global settings route
- Regenerate RC files for all projects when theme changes
- Skip projects with terminal config disabled
- Error handling with per-project logging
- Inject terminal service with settings service dependency

This completes the full terminal configuration feature:
✓ RC Generator (color mapping, prompts)
✓ RC File Manager (file I/O, versioning)
✓ Settings Schema (types, defaults)
✓ Terminal Service Integration (env vars, PTY spawn)
✓ Settings UI (comprehensive controls, preview)
✓ Theme Synchronization (automatic RC regeneration)

New terminals will use custom prompts matching app theme.
Existing terminals unaffected. User RC files preserved.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(terminal): Add error handling and explicit field mapping for terminal config

- Add try-catch block to handleToggleEnabled
- Explicitly set all required terminalConfig fields
- Add console logging for debugging
- Show error toast if update fails
- Include rcFileVersion: 1 in config object

This should fix the issue where the toggle doesn't enable after
clicking OK in the confirmation dialog.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(terminal): Use React Query mutation hook for settings updates

The issue was that `updateGlobalSettings` doesn't exist in the app store.
The correct pattern is to use the `useUpdateGlobalSettings` hook from
use-settings-mutations.ts, which is a React Query mutation.

Changes:
- Import useUpdateGlobalSettings from mutations hook
- Use mutation.mutate() instead of direct function call
- Add proper onSuccess/onError callbacks
- Remove async/await pattern (React Query handles this)

This fixes the toggle not enabling after clicking OK in the confirmation dialog.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(terminal): Use React Query hook for globalSettings instead of store

The root cause: Component was reading globalSettings from the app store,
which doesn't update reactively when the mutation completes.

Solution: Use useGlobalSettings() React Query hook which:
- Automatically refetches when the mutation invalidates the cache
- Triggers re-render with updated data
- Makes the toggle reflect the new state

Now the flow is:
1. User clicks toggle → confirmation dialog
2. Click OK → mutation.mutate() called
3. Mutation succeeds → invalidates queryKeys.settings.global()
4. Query refetches → component re-renders with new globalSettings
5. Toggle shows enabled state ✓

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* debug(terminal): Add detailed logging for terminal config application

Add logging to track:
- When terminal config check happens
- CWD being used
- Global and project enabled states
- Effective enabled state

This will help diagnose why RC files aren't being generated
when opening terminals in Automaker.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* Fix terminal rc updates and bash rcfile loading

* feat(terminal): add banner on shell start

* feat(terminal): colorize banner per theme

* chore(terminal): bump rc version for banner colors

* feat(terminal): match banner colors to launcher

* feat(terminal): add prompt customization controls

* feat: integrate oh-my-posh prompt themes

* fix: resolve oh-my-posh theme path

* fix: correct oh-my-posh config invocation

* docs: add terminal theme screenshot

* fix: address review feedback and stabilize e2e test

* ui: split terminal config into separate card

* fix: enable cross-platform Warp terminal detection

- Remove macOS-only platform restriction for Warp
- Add Linux CLI alias 'warp-terminal' (primary on Linux)
- Add CLI launch handler using --cwd flag
- Fixes issue where Warp was not detected on Linux systems

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

README.md

@@ -288,6 +288,31 @@ services:
 
 **Note:** The Claude CLI config must be writable (do not use `:ro` flag) as the CLI writes debug files.
 
+> **⚠️ Important: Linux/WSL Users**
+>
+> The container runs as UID 1001 by default. If your host user has a different UID (common on Linux/WSL where the first user is UID 1000), you must create a `.env` file to match your host user:
+>
+> ```bash
+> # Check your UID/GID
+> id -u  # outputs your UID (e.g., 1000)
+> id -g  # outputs your GID (e.g., 1000)
+> ```
+>
+> Create a `.env` file in the automaker directory:
+>
+> ```
+> UID=1000
+> GID=1000
+> ```
+>
+> Then rebuild the images:
+>
+> ```bash
+> docker compose build
+> ```
+>
+> Without this, files written by the container will be inaccessible to your host user.
+
 ##### GitHub CLI Authentication (For Git Push/PR Operations)
 
 To enable git push and GitHub CLI operations inside the container:

apps/server/src/index.ts

@@ -390,7 +390,7 @@ const server = createServer(app);
 // WebSocket servers using noServer mode for proper multi-path support
 const wss = new WebSocketServer({ noServer: true });
 const terminalWss = new WebSocketServer({ noServer: true });
-const terminalService = getTerminalService();
+const terminalService = getTerminalService(settingsService);
 
 /**
  * Authenticate WebSocket upgrade requests

apps/server/src/lib/terminal-themes-data.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal Theme Data - Re-export terminal themes from platform package
+ *
+ * This module re-exports terminal theme data for use in the server.
+ */
+
+import { terminalThemeColors, getTerminalThemeColors as getThemeColors } from '@automaker/platform';
+import type { ThemeMode } from '@automaker/types';
+import type { TerminalTheme } from '@automaker/platform';
+
+/**
+ * Get terminal theme colors for a given theme mode
+ */
+export function getTerminalThemeColors(theme: ThemeMode): TerminalTheme {
+  return getThemeColors(theme);
+}
+
+/**
+ * Get all terminal themes
+ */
+export function getAllTerminalThemes(): Record<ThemeMode, TerminalTheme> {
+  return terminalThemeColors;
+}
+
+export default terminalThemeColors;

apps/server/src/providers/cursor-provider.ts

@@ -14,6 +14,7 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { findCliInWsl, isWslAvailable } from '@automaker/platform';
 import {
   CliProvider,
   type CliSpawnConfig,
@@ -286,15 +287,113 @@ export class CursorProvider extends CliProvider {
 
   getSpawnConfig(): CliSpawnConfig {
     return {
-      windowsStrategy: 'wsl', // cursor-agent requires WSL on Windows
+      windowsStrategy: 'direct',
       commonPaths: {
         linux: [
           path.join(os.homedir(), '.local/bin/cursor-agent'), // Primary symlink location
           '/usr/local/bin/cursor-agent',
         ],
         darwin: [path.join(os.homedir(), '.local/bin/cursor-agent'), '/usr/local/bin/cursor-agent'],
-        // Windows paths are not used - we check for WSL installation instead
+        win32: [
-        win32: [],
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            'npm',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            'npm',
+            'cursor.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            '.npm-global',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            '.npm-global',
+            'bin',
+            'cursor.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'pnpm',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'pnpm',
+            'cursor.cmd'
+          ),
+        ],
       },
     };
   }
@@ -487,6 +586,92 @@ export class CursorProvider extends CliProvider {
    * 2. Cursor IDE with 'cursor agent' subcommand support
    */
   protected detectCli(): CliDetectionResult {
+    if (process.platform === 'win32') {
+      const findInPath = (command: string): string | null => {
+        try {
+          const result = execSync(`where ${command}`, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+          })
+            .trim()
+            .split(/\r?\n/)[0];
+
+          if (result && fs.existsSync(result)) {
+            return result;
+          }
+        } catch {
+          // Not in PATH
+        }
+
+        return null;
+      };
+
+      const isCursorAgentBinary = (cliPath: string) =>
+        cliPath.toLowerCase().includes('cursor-agent');
+
+      const supportsCursorAgentSubcommand = (cliPath: string) => {
+        try {
+          execSync(`"${cliPath}" agent --version`, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: 'pipe',
+            windowsHide: true,
+          });
+          return true;
+        } catch {
+          return false;
+        }
+      };
+
+      const pathResult = findInPath('cursor-agent') || findInPath('cursor');
+      if (pathResult) {
+        if (isCursorAgentBinary(pathResult) || supportsCursorAgentSubcommand(pathResult)) {
+          return {
+            cliPath: pathResult,
+            useWsl: false,
+            strategy: pathResult.toLowerCase().endsWith('.cmd') ? 'cmd' : 'direct',
+          };
+        }
+      }
+
+      const config = this.getSpawnConfig();
+      for (const candidate of config.commonPaths.win32 || []) {
+        const resolved = candidate;
+        if (!fs.existsSync(resolved)) {
+          continue;
+        }
+        if (isCursorAgentBinary(resolved) || supportsCursorAgentSubcommand(resolved)) {
+          return {
+            cliPath: resolved,
+            useWsl: false,
+            strategy: resolved.toLowerCase().endsWith('.cmd') ? 'cmd' : 'direct',
+          };
+        }
+      }
+
+      const wslLogger = (msg: string) => logger.debug(msg);
+      if (isWslAvailable({ logger: wslLogger })) {
+        const wslResult = findCliInWsl('cursor-agent', { logger: wslLogger });
+        if (wslResult) {
+          logger.debug(
+            `Using cursor-agent via WSL (${wslResult.distribution || 'default'}): ${wslResult.wslPath}`
+          );
+          return {
+            cliPath: 'wsl.exe',
+            useWsl: true,
+            wslCliPath: wslResult.wslPath,
+            wslDistribution: wslResult.distribution,
+            strategy: 'wsl',
+          };
+        }
+      }
+
+      logger.debug('cursor-agent not found on Windows');
+      return { cliPath: null, useWsl: false, strategy: 'direct' };
+    }
+
     // First try standard detection (PATH, common paths, WSL)
     const result = super.detectCli();
     if (result.cliPath) {
@@ -495,7 +680,7 @@ export class CursorProvider extends CliProvider {
 
     // Cursor-specific: Check versions directory for any installed version
     // This handles cases where cursor-agent is installed but not in PATH
-    if (process.platform !== 'win32' && fs.existsSync(CursorProvider.VERSIONS_DIR)) {
+    if (fs.existsSync(CursorProvider.VERSIONS_DIR)) {
       try {
         const versions = fs
           .readdirSync(CursorProvider.VERSIONS_DIR)
@@ -521,33 +706,31 @@ export class CursorProvider extends CliProvider {
 
     // If cursor-agent not found, try to find 'cursor' IDE and use 'cursor agent' subcommand
     // The Cursor IDE includes the agent as a subcommand: cursor agent
-    if (process.platform !== 'win32') {
+    const cursorPaths = [
-      const cursorPaths = [
+      '/usr/bin/cursor',
-        '/usr/bin/cursor',
+      '/usr/local/bin/cursor',
-        '/usr/local/bin/cursor',
+      path.join(os.homedir(), '.local/bin/cursor'),
-        path.join(os.homedir(), '.local/bin/cursor'),
+      '/opt/cursor/cursor',
-        '/opt/cursor/cursor',
+    ];
-      ];
 
-      for (const cursorPath of cursorPaths) {
+    for (const cursorPath of cursorPaths) {
-        if (fs.existsSync(cursorPath)) {
+      if (fs.existsSync(cursorPath)) {
-          // Verify cursor agent subcommand works
+        // Verify cursor agent subcommand works
-          try {
+        try {
-            execSync(`"${cursorPath}" agent --version`, {
+          execSync(`"${cursorPath}" agent --version`, {
-              encoding: 'utf8',
+            encoding: 'utf8',
-              timeout: 5000,
+            timeout: 5000,
-              stdio: 'pipe',
+            stdio: 'pipe',
-            });
+          });
-            logger.debug(`Using cursor agent via Cursor IDE: ${cursorPath}`);
+          logger.debug(`Using cursor agent via Cursor IDE: ${cursorPath}`);
-            // Return cursor path but we'll use 'cursor agent' subcommand
+          // Return cursor path but we'll use 'cursor agent' subcommand
-            return {
+          return {
-              cliPath: cursorPath,
+            cliPath: cursorPath,
-              useWsl: false,
+            useWsl: false,
-              strategy: 'native',
+            strategy: 'native',
-            };
+          };
-          } catch {
+        } catch {
-            // cursor agent subcommand doesn't work, try next path
+          // cursor agent subcommand doesn't work, try next path
-          }
         }
       }
     }

apps/server/src/routes/enhance-prompt/routes/enhance.ts

@@ -10,14 +10,23 @@ import type { Request, Response } from 'express';
 import { createLogger } from '@automaker/utils';
 import { resolveModelString } from '@automaker/model-resolver';
 import { CLAUDE_MODEL_MAP, type ThinkingLevel } from '@automaker/types';
+import { getAppSpecPath } from '@automaker/platform';
 import { simpleQuery } from '../../../providers/simple-query-service.js';
 import type { SettingsService } from '../../../services/settings-service.js';
 import { getPromptCustomization, getProviderByModelId } from '../../../lib/settings-helpers.js';
+import { FeatureLoader } from '../../../services/feature-loader.js';
+import * as secureFs from '../../../lib/secure-fs.js';
 import {
   buildUserPrompt,
   isValidEnhancementMode,
   type EnhancementMode,
 } from '../../../lib/enhancement-prompts.js';
+import {
+  extractTechnologyStack,
+  extractXmlElements,
+  extractXmlSection,
+  unescapeXml,
+} from '../../../lib/xml-extractor.js';
 
 const logger = createLogger('EnhancePrompt');
 
@@ -53,6 +62,66 @@ interface EnhanceErrorResponse {
   error: string;
 }
 
+async function buildProjectContext(projectPath: string): Promise<string | null> {
+  const contextBlocks: string[] = [];
+
+  try {
+    const appSpecPath = getAppSpecPath(projectPath);
+    const specContent = (await secureFs.readFile(appSpecPath, 'utf-8')) as string;
+
+    const projectName = extractXmlSection(specContent, 'project_name');
+    const overview = extractXmlSection(specContent, 'overview');
+    const techStack = extractTechnologyStack(specContent);
+    const coreSection = extractXmlSection(specContent, 'core_capabilities');
+    const coreCapabilities = coreSection ? extractXmlElements(coreSection, 'capability') : [];
+
+    const summaryLines: string[] = [];
+    if (projectName) {
+      summaryLines.push(`Name: ${unescapeXml(projectName.trim())}`);
+    }
+    if (overview) {
+      summaryLines.push(`Overview: ${unescapeXml(overview.trim())}`);
+    }
+    if (techStack.length > 0) {
+      summaryLines.push(`Tech Stack: ${techStack.join(', ')}`);
+    }
+    if (coreCapabilities.length > 0) {
+      summaryLines.push(`Core Capabilities: ${coreCapabilities.slice(0, 10).join(', ')}`);
+    }
+
+    if (summaryLines.length > 0) {
+      contextBlocks.push(`PROJECT CONTEXT:\n${summaryLines.map((line) => `- ${line}`).join('\n')}`);
+    }
+  } catch (error) {
+    logger.debug('No app_spec.txt context available for enhancement', error);
+  }
+
+  try {
+    const featureLoader = new FeatureLoader();
+    const features = await featureLoader.getAll(projectPath);
+    const featureTitles = features
+      .map((feature) => feature.title || feature.name || feature.id)
+      .filter((title) => Boolean(title));
+
+    if (featureTitles.length > 0) {
+      const listed = featureTitles.slice(0, 30).map((title) => `- ${title}`);
+      contextBlocks.push(
+        `EXISTING FEATURES (avoid duplicates):\n${listed.join('\n')}${
+          featureTitles.length > 30 ? '\n- ...' : ''
+        }`
+      );
+    }
+  } catch (error) {
+    logger.debug('Failed to load existing features for enhancement context', error);
+  }
+
+  if (contextBlocks.length === 0) {
+    return null;
+  }
+
+  return contextBlocks.join('\n\n');
+}
+
 /**
  * Create the enhance request handler
  *
@@ -122,6 +191,10 @@ export function createEnhanceHandler(
 
       // Build the user prompt with few-shot examples
       const userPrompt = buildUserPrompt(validMode, trimmedText, true);
+      const projectContext = projectPath ? await buildProjectContext(projectPath) : null;
+      if (projectContext) {
+        logger.debug('Including project context in enhancement prompt');
+      }
 
       // Check if the model is a provider model (like "GLM-4.5-Air")
       // If so, get the provider config and resolved Claude model
@@ -156,7 +229,7 @@ export function createEnhanceHandler(
       // The system prompt is combined with user prompt since some providers
       // don't have a separate system prompt concept
       const result = await simpleQuery({
-        prompt: `${systemPrompt}\n\n${userPrompt}`,
+        prompt: [systemPrompt, projectContext, userPrompt].filter(Boolean).join('\n\n'),
         model: resolvedModel,
         cwd: process.cwd(), // Enhancement doesn't need a specific working directory
         maxTurns: 1,

apps/server/src/routes/features/routes/create.ts

@@ -43,7 +43,7 @@ export function createCreateHandler(featureLoader: FeatureLoader, events?: Event
       if (events) {
         events.emit('feature:created', {
           featureId: created.id,
-          featureName: created.name,
+          featureName: created.title || 'Untitled Feature',
           projectPath,
         });
       }

apps/server/src/routes/fs/routes/save-board-background.ts

@@ -31,7 +31,9 @@ export function createSaveBoardBackgroundHandler() {
       await secureFs.mkdir(boardDir, { recursive: true });
 
       // Decode base64 data (remove data URL prefix if present)
-      const base64Data = data.replace(/^data:image\/\w+;base64,/, '');
+      // Use a regex that handles all data URL formats including those with extra params
+      // e.g., data:image/gif;charset=utf-8;base64,R0lGOD...
+      const base64Data = data.replace(/^data:[^,]+,/, '');
       const buffer = Buffer.from(base64Data, 'base64');
 
       // Use a fixed filename for the board background (overwrite previous)

apps/server/src/routes/fs/routes/save-image.ts

@@ -31,7 +31,9 @@ export function createSaveImageHandler() {
       await secureFs.mkdir(imagesDir, { recursive: true });
 
       // Decode base64 data (remove data URL prefix if present)
-      const base64Data = data.replace(/^data:image\/\w+;base64,/, '');
+      // Use a regex that handles all data URL formats including those with extra params
+      // e.g., data:image/gif;charset=utf-8;base64,R0lGOD...
+      const base64Data = data.replace(/^data:[^,]+,/, '');
       const buffer = Buffer.from(base64Data, 'base64');
 
       // Generate unique filename with timestamp

apps/server/src/routes/settings/routes/update-global.ts

@@ -14,6 +14,7 @@ import type { GlobalSettings } from '../../../types/settings.js';
 import { getErrorMessage, logError, logger } from '../common.js';
 import { setLogLevel, LogLevel } from '@automaker/utils';
 import { setRequestLoggingEnabled } from '../../../index.js';
+import { getTerminalService } from '../../../services/terminal-service.js';
 
 /**
  * Map server log level string to LogLevel enum
@@ -57,6 +58,10 @@ export function createUpdateGlobalHandler(settingsService: SettingsService) {
         }, localStorageMigrated=${(updates as any).localStorageMigrated ?? 'n/a'}`
       );
 
+      // Get old settings to detect theme changes
+      const oldSettings = await settingsService.getGlobalSettings();
+      const oldTheme = oldSettings?.theme;
+
       logger.info('[SERVER_SETTINGS_UPDATE] Calling updateGlobalSettings...');
       const settings = await settingsService.updateGlobalSettings(updates);
       logger.info(
@@ -64,6 +69,37 @@ export function createUpdateGlobalHandler(settingsService: SettingsService) {
         settings.projects?.length ?? 0
       );
 
+      // Handle theme change - regenerate terminal RC files for all projects
+      if ('theme' in updates && updates.theme && updates.theme !== oldTheme) {
+        const terminalService = getTerminalService(settingsService);
+        const newTheme = updates.theme;
+
+        logger.info(
+          `[TERMINAL_CONFIG] Theme changed from ${oldTheme} to ${newTheme}, regenerating RC files`
+        );
+
+        // Regenerate RC files for all projects with terminal config enabled
+        const projects = settings.projects || [];
+        for (const project of projects) {
+          try {
+            const projectSettings = await settingsService.getProjectSettings(project.path);
+            // Check if terminal config is enabled (global or project-specific)
+            const terminalConfigEnabled =
+              projectSettings.terminalConfig?.enabled !== false &&
+              settings.terminalConfig?.enabled === true;
+
+            if (terminalConfigEnabled) {
+              await terminalService.onThemeChange(project.path, newTheme);
+              logger.info(`[TERMINAL_CONFIG] Regenerated RC files for project: ${project.name}`);
+            }
+          } catch (error) {
+            logger.warn(
+              `[TERMINAL_CONFIG] Failed to regenerate RC files for project ${project.name}: ${error}`
+            );
+          }
+        }
+      }
+
       // Apply server log level if it was updated
       if ('serverLogLevel' in updates && updates.serverLogLevel) {
         const level = LOG_LEVEL_MAP[updates.serverLogLevel];

apps/server/src/routes/worktree/routes/init-git.ts

@@ -43,10 +43,14 @@ export function createInitGitHandler() {
         // .git doesn't exist, continue with initialization
       }
 
-      // Initialize git and create an initial empty commit
+      // Initialize git with 'main' as the default branch (matching GitHub's standard since 2020)
-      await execAsync(`git init && git commit --allow-empty -m "Initial commit"`, {
+      // and create an initial empty commit
-        cwd: projectPath,
+      await execAsync(
-      });
+        `git init --initial-branch=main && git commit --allow-empty -m "Initial commit"`,
+        {
+          cwd: projectPath,
+        }
+      );
 
       res.json({
         success: true,

apps/server/src/services/auto-mode-service.ts

@@ -4597,21 +4597,54 @@ This mock response was generated because AUTOMAKER_MOCK_AGENT=true was set.
                           planVersion,
                         });
 
-                        // Build revision prompt
+                        // Build revision prompt using customizable template
-                        let revisionPrompt = `The user has requested revisions to the plan/specification.
+                        const revisionPrompts = await getPromptCustomization(
+                          this.settingsService,
+                          '[AutoMode]'
+                        );
 
-## Previous Plan (v${planVersion - 1})
+                        // Get task format example based on planning mode
-${hasEdits ? approvalResult.editedPlan : currentPlanContent}
+                        const taskFormatExample =
+                          planningMode === 'full'
+                            ? `\`\`\`tasks
+## Phase 1: Foundation
+- [ ] T001: [Description] | File: [path/to/file]
+- [ ] T002: [Description] | File: [path/to/file]
 
-## User Feedback
+## Phase 2: Core Implementation
-${approvalResult.feedback || 'Please revise the plan based on the edits above.'}
+- [ ] T003: [Description] | File: [path/to/file]
+- [ ] T004: [Description] | File: [path/to/file]
+\`\`\``
+                            : `\`\`\`tasks
+- [ ] T001: [Description] | File: [path/to/file]
+- [ ] T002: [Description] | File: [path/to/file]
+- [ ] T003: [Description] | File: [path/to/file]
+\`\`\``;
 
-## Instructions
+                        let revisionPrompt = revisionPrompts.taskExecution.planRevisionTemplate;
-Please regenerate the specification incorporating the user's feedback.
+                        revisionPrompt = revisionPrompt.replace(
-Keep the same format with the \`\`\`tasks block for task definitions.
+                          /\{\{planVersion\}\}/g,
-After generating the revised spec, output:
+                          String(planVersion - 1)
-"[SPEC_GENERATED] Please review the revised specification above."
+                        );
-`;
+                        revisionPrompt = revisionPrompt.replace(
+                          /\{\{previousPlan\}\}/g,
+                          hasEdits
+                            ? approvalResult.editedPlan || currentPlanContent
+                            : currentPlanContent
+                        );
+                        revisionPrompt = revisionPrompt.replace(
+                          /\{\{userFeedback\}\}/g,
+                          approvalResult.feedback ||
+                            'Please revise the plan based on the edits above.'
+                        );
+                        revisionPrompt = revisionPrompt.replace(
+                          /\{\{planningMode\}\}/g,
+                          planningMode
+                        );
+                        revisionPrompt = revisionPrompt.replace(
+                          /\{\{taskFormatExample\}\}/g,
+                          taskFormatExample
+                        );
 
                         // Update status to regenerating
                         await this.updateFeaturePlanSpec(projectPath, featureId, {
@@ -4663,6 +4696,26 @@ After generating the revised spec, output:
                         const revisedTasks = parseTasksFromSpec(currentPlanContent);
                         logger.info(`Revised plan has ${revisedTasks.length} tasks`);
 
+                        // Warn if no tasks found in spec/full mode - this may cause fallback to single-agent
+                        if (
+                          revisedTasks.length === 0 &&
+                          (planningMode === 'spec' || planningMode === 'full')
+                        ) {
+                          logger.warn(
+                            `WARNING: Revised plan in ${planningMode} mode has no tasks! ` +
+                              `This will cause fallback to single-agent execution. ` +
+                              `The AI may have omitted the required \`\`\`tasks block.`
+                          );
+                          this.emitAutoModeEvent('plan_revision_warning', {
+                            featureId,
+                            projectPath,
+                            branchName,
+                            planningMode,
+                            warning:
+                              'Revised plan missing tasks block - will use single-agent execution',
+                          });
+                        }
+
                         // Update planSpec with revised content
                         await this.updateFeaturePlanSpec(projectPath, featureId, {
                           status: 'generated',

apps/server/src/services/event-hook-service.ts

@@ -169,9 +169,10 @@ export class EventHookService {
     }
 
     // Build context for variable substitution
+    // Use loaded featureName (from feature.title) or fall back to payload.featureName
     const context: HookContext = {
       featureId: payload.featureId,
-      featureName: payload.featureName,
+      featureName: featureName || payload.featureName,
       projectPath: payload.projectPath,
       projectName: payload.projectPath ? this.extractProjectName(payload.projectPath) : undefined,
       error: payload.error || payload.message,

apps/server/src/services/terminal-service.ts

@@ -13,6 +13,14 @@ import * as path from 'path';
 // to enforce ALLOWED_ROOT_DIRECTORY security boundary
 import * as secureFs from '../lib/secure-fs.js';
 import { createLogger } from '@automaker/utils';
+import type { SettingsService } from './settings-service.js';
+import { getTerminalThemeColors, getAllTerminalThemes } from '../lib/terminal-themes-data.js';
+import {
+  getRcFilePath,
+  getTerminalDir,
+  ensureRcFilesUpToDate,
+  type TerminalConfig,
+} from '@automaker/platform';
 
 const logger = createLogger('Terminal');
 // System paths module handles shell binary checks and WSL detection
@@ -24,6 +32,27 @@ import {
   getShellPaths,
 } from '@automaker/platform';
 
+const BASH_LOGIN_ARG = '--login';
+const BASH_RCFILE_ARG = '--rcfile';
+const SHELL_NAME_BASH = 'bash';
+const SHELL_NAME_ZSH = 'zsh';
+const SHELL_NAME_SH = 'sh';
+const DEFAULT_SHOW_USER_HOST = true;
+const DEFAULT_SHOW_PATH = true;
+const DEFAULT_SHOW_TIME = false;
+const DEFAULT_SHOW_EXIT_STATUS = false;
+const DEFAULT_PATH_DEPTH = 0;
+const DEFAULT_PATH_STYLE: TerminalConfig['pathStyle'] = 'full';
+const DEFAULT_CUSTOM_PROMPT = true;
+const DEFAULT_PROMPT_FORMAT: TerminalConfig['promptFormat'] = 'standard';
+const DEFAULT_SHOW_GIT_BRANCH = true;
+const DEFAULT_SHOW_GIT_STATUS = true;
+const DEFAULT_CUSTOM_ALIASES = '';
+const DEFAULT_CUSTOM_ENV_VARS: Record<string, string> = {};
+const PROMPT_THEME_CUSTOM = 'custom';
+const PROMPT_THEME_PREFIX = 'omp-';
+const OMP_THEME_ENV_VAR = 'AUTOMAKER_OMP_THEME';
+
 // Maximum scrollback buffer size (characters)
 const MAX_SCROLLBACK_SIZE = 50000; // ~50KB per terminal
 
@@ -42,6 +71,114 @@ let maxSessions = parseInt(process.env.TERMINAL_MAX_SESSIONS || '1000', 10);
 const OUTPUT_THROTTLE_MS = 4; // ~250fps max update rate for responsive input
 const OUTPUT_BATCH_SIZE = 4096; // Smaller batches for lower latency
 
+function applyBashRcFileArgs(args: string[], rcFilePath: string): string[] {
+  const sanitizedArgs: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === BASH_LOGIN_ARG) {
+      continue;
+    }
+    if (arg === BASH_RCFILE_ARG) {
+      index += 1;
+      continue;
+    }
+    sanitizedArgs.push(arg);
+  }
+
+  sanitizedArgs.push(BASH_RCFILE_ARG, rcFilePath);
+  return sanitizedArgs;
+}
+
+function normalizePathStyle(
+  pathStyle: TerminalConfig['pathStyle'] | undefined
+): TerminalConfig['pathStyle'] {
+  if (pathStyle === 'short' || pathStyle === 'basename') {
+    return pathStyle;
+  }
+  return DEFAULT_PATH_STYLE;
+}
+
+function normalizePathDepth(pathDepth: number | undefined): number {
+  const depth =
+    typeof pathDepth === 'number' && Number.isFinite(pathDepth) ? pathDepth : DEFAULT_PATH_DEPTH;
+  return Math.max(DEFAULT_PATH_DEPTH, Math.floor(depth));
+}
+
+function getShellBasename(shellPath: string): string {
+  const lastSep = Math.max(shellPath.lastIndexOf('/'), shellPath.lastIndexOf('\\'));
+  return lastSep >= 0 ? shellPath.slice(lastSep + 1) : shellPath;
+}
+
+function getShellArgsForPath(shellPath: string): string[] {
+  const shellName = getShellBasename(shellPath).toLowerCase().replace('.exe', '');
+  if (shellName === 'powershell' || shellName === 'pwsh' || shellName === 'cmd') {
+    return [];
+  }
+  if (shellName === SHELL_NAME_SH) {
+    return [];
+  }
+  return [BASH_LOGIN_ARG];
+}
+
+function resolveOmpThemeName(promptTheme: string | undefined): string | null {
+  if (!promptTheme || promptTheme === PROMPT_THEME_CUSTOM) {
+    return null;
+  }
+  if (promptTheme.startsWith(PROMPT_THEME_PREFIX)) {
+    return promptTheme.slice(PROMPT_THEME_PREFIX.length);
+  }
+  return null;
+}
+
+function buildEffectiveTerminalConfig(
+  globalTerminalConfig: TerminalConfig | undefined,
+  projectTerminalConfig: Partial<TerminalConfig> | undefined
+): TerminalConfig {
+  const mergedEnvVars = {
+    ...(globalTerminalConfig?.customEnvVars ?? DEFAULT_CUSTOM_ENV_VARS),
+    ...(projectTerminalConfig?.customEnvVars ?? DEFAULT_CUSTOM_ENV_VARS),
+  };
+
+  return {
+    enabled: projectTerminalConfig?.enabled ?? globalTerminalConfig?.enabled ?? false,
+    customPrompt: globalTerminalConfig?.customPrompt ?? DEFAULT_CUSTOM_PROMPT,
+    promptFormat: globalTerminalConfig?.promptFormat ?? DEFAULT_PROMPT_FORMAT,
+    showGitBranch:
+      projectTerminalConfig?.showGitBranch ??
+      globalTerminalConfig?.showGitBranch ??
+      DEFAULT_SHOW_GIT_BRANCH,
+    showGitStatus:
+      projectTerminalConfig?.showGitStatus ??
+      globalTerminalConfig?.showGitStatus ??
+      DEFAULT_SHOW_GIT_STATUS,
+    showUserHost:
+      projectTerminalConfig?.showUserHost ??
+      globalTerminalConfig?.showUserHost ??
+      DEFAULT_SHOW_USER_HOST,
+    showPath:
+      projectTerminalConfig?.showPath ?? globalTerminalConfig?.showPath ?? DEFAULT_SHOW_PATH,
+    pathStyle: normalizePathStyle(
+      projectTerminalConfig?.pathStyle ?? globalTerminalConfig?.pathStyle
+    ),
+    pathDepth: normalizePathDepth(
+      projectTerminalConfig?.pathDepth ?? globalTerminalConfig?.pathDepth
+    ),
+    showTime:
+      projectTerminalConfig?.showTime ?? globalTerminalConfig?.showTime ?? DEFAULT_SHOW_TIME,
+    showExitStatus:
+      projectTerminalConfig?.showExitStatus ??
+      globalTerminalConfig?.showExitStatus ??
+      DEFAULT_SHOW_EXIT_STATUS,
+    customAliases:
+      projectTerminalConfig?.customAliases ??
+      globalTerminalConfig?.customAliases ??
+      DEFAULT_CUSTOM_ALIASES,
+    customEnvVars: mergedEnvVars,
+    rcFileVersion: globalTerminalConfig?.rcFileVersion,
+  };
+}
+
 export interface TerminalSession {
   id: string;
   pty: pty.IPty;
@@ -77,6 +214,12 @@ export class TerminalService extends EventEmitter {
     !!(process.versions && (process.versions as Record<string, string>).electron) ||
     !!process.env.ELECTRON_RUN_AS_NODE;
   private useConptyFallback = false; // Track if we need to use winpty fallback on Windows
+  private settingsService: SettingsService | null = null;
+
+  constructor(settingsService?: SettingsService) {
+    super();
+    this.settingsService = settingsService || null;
+  }
 
   /**
    * Kill a PTY process with platform-specific handling.
@@ -102,37 +245,19 @@ export class TerminalService extends EventEmitter {
     const platform = os.platform();
     const shellPaths = getShellPaths();
 
-    // Helper to get basename handling both path separators
-    const getBasename = (shellPath: string): string => {
-      const lastSep = Math.max(shellPath.lastIndexOf('/'), shellPath.lastIndexOf('\\'));
-      return lastSep >= 0 ? shellPath.slice(lastSep + 1) : shellPath;
-    };
-
-    // Helper to get shell args based on shell name
-    const getShellArgs = (shell: string): string[] => {
-      const shellName = getBasename(shell).toLowerCase().replace('.exe', '');
-      // PowerShell and cmd don't need --login
-      if (shellName === 'powershell' || shellName === 'pwsh' || shellName === 'cmd') {
-        return [];
-      }
-      // sh doesn't support --login in all implementations
-      if (shellName === 'sh') {
-        return [];
-      }
-      // bash, zsh, and other POSIX shells support --login
-      return ['--login'];
-    };
-
     // Check if running in WSL - prefer user's shell or bash with --login
     if (platform === 'linux' && this.isWSL()) {
       const userShell = process.env.SHELL;
       if (userShell) {
         // Try to find userShell in allowed paths
         for (const allowedShell of shellPaths) {
-          if (allowedShell === userShell || getBasename(allowedShell) === getBasename(userShell)) {
+          if (
+            allowedShell === userShell ||
+            getShellBasename(allowedShell) === getShellBasename(userShell)
+          ) {
             try {
               if (systemPathExists(allowedShell)) {
-                return { shell: allowedShell, args: getShellArgs(allowedShell) };
+                return { shell: allowedShell, args: getShellArgsForPath(allowedShell) };
               }
             } catch {
               // Path not allowed, continue searching
@@ -144,7 +269,7 @@ export class TerminalService extends EventEmitter {
       for (const shell of shellPaths) {
         try {
           if (systemPathExists(shell)) {
-            return { shell, args: getShellArgs(shell) };
+            return { shell, args: getShellArgsForPath(shell) };
           }
         } catch {
           // Path not allowed, continue
@@ -158,10 +283,13 @@ export class TerminalService extends EventEmitter {
     if (userShell && platform !== 'win32') {
       // Try to find userShell in allowed paths
       for (const allowedShell of shellPaths) {
-        if (allowedShell === userShell || getBasename(allowedShell) === getBasename(userShell)) {
+        if (
+          allowedShell === userShell ||
+          getShellBasename(allowedShell) === getShellBasename(userShell)
+        ) {
           try {
             if (systemPathExists(allowedShell)) {
-              return { shell: allowedShell, args: getShellArgs(allowedShell) };
+              return { shell: allowedShell, args: getShellArgsForPath(allowedShell) };
             }
           } catch {
             // Path not allowed, continue searching
@@ -174,7 +302,7 @@ export class TerminalService extends EventEmitter {
     for (const shell of shellPaths) {
       try {
         if (systemPathExists(shell)) {
-          return { shell, args: getShellArgs(shell) };
+          return { shell, args: getShellArgsForPath(shell) };
         }
       } catch {
         // Path not allowed or doesn't exist, continue to next
@@ -313,8 +441,9 @@ export class TerminalService extends EventEmitter {
 
     const id = `term-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
 
-    const { shell: detectedShell, args: shellArgs } = this.detectShell();
+    const { shell: detectedShell, args: detectedShellArgs } = this.detectShell();
     const shell = options.shell || detectedShell;
+    let shellArgs = options.shell ? getShellArgsForPath(shell) : [...detectedShellArgs];
 
     // Validate and resolve working directory
     // Uses secureFs internally to enforce ALLOWED_ROOT_DIRECTORY
@@ -332,6 +461,89 @@ export class TerminalService extends EventEmitter {
       }
     }
 
+    // Terminal config injection (custom prompts, themes)
+    const terminalConfigEnv: Record<string, string> = {};
+    if (this.settingsService) {
+      try {
+        logger.info(
+          `[createSession] Checking terminal config for session ${id}, cwd: ${options.cwd || cwd}`
+        );
+        const globalSettings = await this.settingsService.getGlobalSettings();
+        const projectSettings = options.cwd
+          ? await this.settingsService.getProjectSettings(options.cwd)
+          : null;
+
+        const globalTerminalConfig = globalSettings?.terminalConfig;
+        const projectTerminalConfig = projectSettings?.terminalConfig;
+        const effectiveConfig = buildEffectiveTerminalConfig(
+          globalTerminalConfig,
+          projectTerminalConfig
+        );
+
+        logger.info(
+          `[createSession] Terminal config: global.enabled=${globalTerminalConfig?.enabled}, project.enabled=${projectTerminalConfig?.enabled}`
+        );
+        logger.info(
+          `[createSession] Terminal config effective enabled: ${effectiveConfig.enabled}`
+        );
+
+        if (effectiveConfig.enabled && globalTerminalConfig) {
+          const currentTheme = globalSettings?.theme || 'dark';
+          const themeColors = getTerminalThemeColors(currentTheme);
+          const allThemes = getAllTerminalThemes();
+          const promptTheme =
+            projectTerminalConfig?.promptTheme ?? globalTerminalConfig.promptTheme;
+          const ompThemeName = resolveOmpThemeName(promptTheme);
+
+          // Ensure RC files are up to date
+          await ensureRcFilesUpToDate(
+            options.cwd || cwd,
+            currentTheme,
+            effectiveConfig,
+            themeColors,
+            allThemes
+          );
+
+          // Set shell-specific env vars
+          const shellName = getShellBasename(shell).toLowerCase();
+          if (ompThemeName && effectiveConfig.customPrompt) {
+            terminalConfigEnv[OMP_THEME_ENV_VAR] = ompThemeName;
+          }
+
+          if (shellName.includes(SHELL_NAME_BASH)) {
+            const bashRcFilePath = getRcFilePath(options.cwd || cwd, SHELL_NAME_BASH);
+            terminalConfigEnv.BASH_ENV = bashRcFilePath;
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+            shellArgs = applyBashRcFileArgs(shellArgs, bashRcFilePath);
+          } else if (shellName.includes(SHELL_NAME_ZSH)) {
+            terminalConfigEnv.ZDOTDIR = getTerminalDir(options.cwd || cwd);
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+          } else if (shellName === SHELL_NAME_SH) {
+            terminalConfigEnv.ENV = getRcFilePath(options.cwd || cwd, SHELL_NAME_SH);
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+          }
+
+          // Add custom env vars from config
+          Object.assign(terminalConfigEnv, effectiveConfig.customEnvVars);
+
+          logger.info(
+            `[createSession] Terminal config enabled for session ${id}, shell: ${shellName}`
+          );
+        }
+      } catch (error) {
+        logger.warn(`[createSession] Failed to apply terminal config: ${error}`);
+      }
+    }
+
     const env: Record<string, string> = {
       ...cleanEnv,
       TERM: 'xterm-256color',
@@ -341,6 +553,7 @@ export class TerminalService extends EventEmitter {
       LANG: process.env.LANG || 'en_US.UTF-8',
       LC_ALL: process.env.LC_ALL || process.env.LANG || 'en_US.UTF-8',
       ...options.env,
+      ...terminalConfigEnv, // Apply terminal config env vars last (highest priority)
     };
 
     logger.info(`Creating session ${id} with shell: ${shell} in ${cwd}`);
@@ -652,6 +865,44 @@ export class TerminalService extends EventEmitter {
     return () => this.exitCallbacks.delete(callback);
   }
 
+  /**
+   * Handle theme change - regenerate RC files with new theme colors
+   */
+  async onThemeChange(projectPath: string, newTheme: string): Promise<void> {
+    if (!this.settingsService) {
+      logger.warn('[onThemeChange] SettingsService not available');
+      return;
+    }
+
+    try {
+      const globalSettings = await this.settingsService.getGlobalSettings();
+      const terminalConfig = globalSettings?.terminalConfig;
+      const projectSettings = await this.settingsService.getProjectSettings(projectPath);
+      const projectTerminalConfig = projectSettings?.terminalConfig;
+      const effectiveConfig = buildEffectiveTerminalConfig(terminalConfig, projectTerminalConfig);
+
+      if (effectiveConfig.enabled && terminalConfig) {
+        const themeColors = getTerminalThemeColors(
+          newTheme as import('@automaker/types').ThemeMode
+        );
+        const allThemes = getAllTerminalThemes();
+
+        // Regenerate RC files with new theme
+        await ensureRcFilesUpToDate(
+          projectPath,
+          newTheme as import('@automaker/types').ThemeMode,
+          effectiveConfig,
+          themeColors,
+          allThemes
+        );
+
+        logger.info(`[onThemeChange] Regenerated RC files for theme: ${newTheme}`);
+      }
+    } catch (error) {
+      logger.error(`[onThemeChange] Failed to regenerate RC files: ${error}`);
+    }
+  }
+
   /**
    * Clean up all sessions
    */
@@ -676,9 +927,9 @@ export class TerminalService extends EventEmitter {
 // Singleton instance
 let terminalService: TerminalService | null = null;
 
-export function getTerminalService(): TerminalService {
+export function getTerminalService(settingsService?: SettingsService): TerminalService {
   if (!terminalService) {
-    terminalService = new TerminalService();
+    terminalService = new TerminalService(settingsService);
   }
   return terminalService;
 }

apps/server/tests/integration/helpers/git-test-repo.ts

@@ -20,8 +20,8 @@ export interface TestRepo {
 export async function createTestGitRepo(): Promise<TestRepo> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-test-'));
 
-  // Initialize git repo
+  // Initialize git repo with 'main' as the default branch (matching GitHub's standard)
-  await execAsync('git init', { cwd: tmpDir });
+  await execAsync('git init --initial-branch=main', { cwd: tmpDir });
 
   // Use environment variables instead of git config to avoid affecting user's git config
   // These env vars override git config without modifying it
@@ -38,9 +38,6 @@ export async function createTestGitRepo(): Promise<TestRepo> {
   await execAsync('git add .', { cwd: tmpDir, env: gitEnv });
   await execAsync('git commit -m "Initial commit"', { cwd: tmpDir, env: gitEnv });
 
-  // Create main branch explicitly
-  await execAsync('git branch -M main', { cwd: tmpDir });
-
   return {
     path: tmpDir,
     cleanup: async () => {

apps/server/tests/integration/routes/worktree/create.integration.test.ts

@@ -14,7 +14,8 @@ describe('worktree create route - repositories without commits', () => {
 
   async function initRepoWithoutCommit() {
     repoPath = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-no-commit-'));
-    await execAsync('git init', { cwd: repoPath });
+    // Initialize with 'main' as the default branch (matching GitHub's standard)
+    await execAsync('git init --initial-branch=main', { cwd: repoPath });
     // Don't set git config - use environment variables in commit operations instead
     // to avoid affecting user's git config
     // Intentionally skip creating an initial commit

apps/server/tests/unit/services/dev-server-service.test.ts

@@ -30,11 +30,16 @@ import net from 'net';
 
 describe('dev-server-service.ts', () => {
   let testDir: string;
+  let originalHostname: string | undefined;
 
   beforeEach(async () => {
     vi.clearAllMocks();
     vi.resetModules();
 
+    // Store and set HOSTNAME for consistent test behavior
+    originalHostname = process.env.HOSTNAME;
+    process.env.HOSTNAME = 'localhost';
+
     testDir = path.join(os.tmpdir(), `dev-server-test-${Date.now()}`);
     await fs.mkdir(testDir, { recursive: true });
 
@@ -56,6 +61,13 @@ describe('dev-server-service.ts', () => {
   });
 
   afterEach(async () => {
+    // Restore original HOSTNAME
+    if (originalHostname === undefined) {
+      delete process.env.HOSTNAME;
+    } else {
+      process.env.HOSTNAME = originalHostname;
+    }
+
     try {
       await fs.rm(testDir, { recursive: true, force: true });
     } catch {

apps/ui/scripts/prepare-server.mjs

@@ -7,8 +7,8 @@
  */
 
 import { execSync } from 'child_process';
-import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readFileSync, lstatSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -112,6 +112,29 @@ execSync('npm install --omit=dev', {
   },
 });
 
+// Step 6b: Replace symlinks for local packages with real copies
+// npm install creates symlinks for file: references, but these break when packaged by electron-builder
+console.log('🔗 Replacing symlinks with real directory copies...');
+const nodeModulesAutomaker = join(BUNDLE_DIR, 'node_modules', '@automaker');
+for (const pkgName of LOCAL_PACKAGES) {
+  const pkgDir = pkgName.replace('@automaker/', '');
+  const nmPkgPath = join(nodeModulesAutomaker, pkgDir);
+  try {
+    // lstatSync does not follow symlinks, allowing us to check for broken ones
+    if (lstatSync(nmPkgPath).isSymbolicLink()) {
+      const realPath = resolve(BUNDLE_DIR, 'libs', pkgDir);
+      rmSync(nmPkgPath);
+      cpSync(realPath, nmPkgPath, { recursive: true });
+      console.log(`   ✓ Replaced symlink: ${pkgName}`);
+    }
+  } catch (error) {
+    // If the path doesn't exist, lstatSync throws ENOENT. We can safely ignore this.
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
 // Step 7: Rebuild native modules for current architecture
 // This is critical for modules like node-pty that have native bindings
 console.log('🔨 Rebuilding native modules for current architecture...');

apps/ui/src/components/layout/project-switcher/components/edit-project-dialog.tsx

@@ -15,6 +15,7 @@ import { getAuthenticatedImageUrl } from '@/lib/api-fetch';
 import { getHttpApiClient } from '@/lib/http-api-client';
 import type { Project } from '@/lib/electron';
 import { IconPicker } from './icon-picker';
+import { toast } from 'sonner';
 
 interface EditProjectDialogProps {
   project: Project;
@@ -52,11 +53,18 @@ export function EditProjectDialog({ project, open, onOpenChange }: EditProjectDi
     // Validate file type
     const validTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
     if (!validTypes.includes(file.type)) {
+      toast.error(
+        `Invalid file type: ${file.type || 'unknown'}. Please use JPG, PNG, GIF or WebP.`
+      );
       return;
     }
 
-    // Validate file size (max 2MB for icons)
+    // Validate file size (max 5MB for icons - allows animated GIFs)
-    if (file.size > 2 * 1024 * 1024) {
+    const maxSize = 5 * 1024 * 1024;
+    if (file.size > maxSize) {
+      toast.error(
+        `File too large (${(file.size / 1024 / 1024).toFixed(2)} MB). Maximum size is 5 MB.`
+      );
       return;
     }
 
@@ -72,15 +80,24 @@ export function EditProjectDialog({ project, open, onOpenChange }: EditProjectDi
           file.type,
           project.path
         );
+
         if (result.success && result.path) {
           setCustomIconPath(result.path);
           // Clear the Lucide icon when custom icon is set
           setIcon(null);
+          toast.success('Icon uploaded successfully');
+        } else {
+          toast.error('Failed to upload icon');
         }
         setIsUploadingIcon(false);
       };
+      reader.onerror = () => {
+        toast.error('Failed to read file');
+        setIsUploadingIcon(false);
+      };
       reader.readAsDataURL(file);
     } catch {
+      toast.error('Failed to upload icon');
       setIsUploadingIcon(false);
     }
   };
@@ -162,7 +179,7 @@ export function EditProjectDialog({ project, open, onOpenChange }: EditProjectDi
                     {isUploadingIcon ? 'Uploading...' : 'Upload Custom Icon'}
                   </Button>
                   <p className="text-xs text-muted-foreground mt-1">
-                    PNG, JPG, GIF or WebP. Max 2MB.
+                    PNG, JPG, GIF or WebP. Max 5MB.
                   </p>
                 </div>
               </div>

apps/ui/src/components/layout/project-switcher/components/project-context-menu.tsx

@@ -59,7 +59,7 @@ interface ThemeButtonProps {
   /** Handler for pointer leave events (used to clear preview) */
   onPointerLeave: (e: React.PointerEvent) => void;
   /** Handler for click events (used to select theme) */
-  onClick: () => void;
+  onClick: (e: React.MouseEvent) => void;
 }
 
 /**
@@ -77,6 +77,7 @@ const ThemeButton = memo(function ThemeButton({
   const Icon = option.icon;
   return (
     <button
+      type="button"
       onPointerEnter={onPointerEnter}
       onPointerLeave={onPointerLeave}
       onClick={onClick}
@@ -145,7 +146,10 @@ const ThemeColumn = memo(function ThemeColumn({
             isSelected={selectedTheme === option.value}
             onPointerEnter={() => onPreviewEnter(option.value)}
             onPointerLeave={onPreviewLeave}
-            onClick={() => onSelect(option.value)}
+            onClick={(e) => {
+              e.stopPropagation();
+              onSelect(option.value);
+            }}
           />
         ))}
       </div>
@@ -193,7 +197,6 @@ export function ProjectContextMenu({
   const {
     moveProjectToTrash,
     theme: globalTheme,
-    setTheme,
     setProjectTheme,
     setPreviewTheme,
   } = useAppStore();
@@ -316,13 +319,24 @@ export function ProjectContextMenu({
 
   const handleThemeSelect = useCallback(
     (value: ThemeMode | typeof USE_GLOBAL_THEME) => {
+      // Clear any pending close timeout to prevent race conditions
+      if (closeTimeoutRef.current) {
+        clearTimeout(closeTimeoutRef.current);
+        closeTimeoutRef.current = null;
+      }
+
+      // Close menu first
+      setShowThemeSubmenu(false);
+      onClose();
+
+      // Then apply theme changes
       setPreviewTheme(null);
       const isUsingGlobal = value === USE_GLOBAL_THEME;
-      setTheme(isUsingGlobal ? globalTheme : value);
+      // Only set project theme - don't change global theme
+      // The UI uses getEffectiveTheme() which handles: previewTheme ?? projectTheme ?? globalTheme
       setProjectTheme(project.id, isUsingGlobal ? null : value);
-      setShowThemeSubmenu(false);
     },
-    [globalTheme, project.id, setPreviewTheme, setProjectTheme, setTheme]
+    [onClose, project.id, setPreviewTheme, setProjectTheme]
   );
 
   const handleConfirmRemove = useCallback(() => {
@@ -426,9 +440,13 @@ export function ProjectContextMenu({
                   <div className="p-2">
                     {/* Use Global Option */}
                     <button
+                      type="button"
                       onPointerEnter={() => handlePreviewEnter(globalTheme)}
                       onPointerLeave={handlePreviewLeave}
-                      onClick={() => handleThemeSelect(USE_GLOBAL_THEME)}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        handleThemeSelect(USE_GLOBAL_THEME);
+                      }}
                       className={cn(
                         'w-full flex items-center gap-2 px-3 py-2 rounded-md',
                         'text-sm font-medium text-left',

apps/ui/src/components/layout/project-switcher/components/project-switcher-item.tsx

@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { Folder, LucideIcon } from 'lucide-react';
 import * as LucideIcons from 'lucide-react';
 import { cn, sanitizeForTestId } from '@/lib/utils';
@@ -19,6 +20,8 @@ export function ProjectSwitcherItem({
   onClick,
   onContextMenu,
 }: ProjectSwitcherItemProps) {
+  const [imageError, setImageError] = useState(false);
+
   // Convert index to hotkey label: 0 -> "1", 1 -> "2", ..., 8 -> "9", 9 -> "0"
   const hotkeyLabel =
     hotkeyIndex !== undefined && hotkeyIndex >= 0 && hotkeyIndex <= 9
@@ -35,7 +38,7 @@ export function ProjectSwitcherItem({
   };
 
   const IconComponent = getIconComponent();
-  const hasCustomIcon = !!project.customIconPath;
+  const hasCustomIcon = !!project.customIconPath && !imageError;
 
   // Combine project.id with sanitized name for uniqueness and readability
   // Format: project-switcher-{id}-{sanitizedName}
@@ -74,6 +77,7 @@ export function ProjectSwitcherItem({
             'w-8 h-8 rounded-lg object-cover transition-all duration-200',
             isActive ? 'ring-1 ring-brand-500/50' : 'group-hover:scale-110'
           )}
+          onError={() => setImageError(true)}
         />
       ) : (
         <IconComponent

apps/ui/src/components/layout/project-switcher/project-switcher.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback, useEffect } from 'react';
 import { Plus, Bug, FolderOpen, BookOpen } from 'lucide-react';
 import { useNavigate, useLocation } from '@tanstack/react-router';
-import { cn } from '@/lib/utils';
+import { cn, isMac } from '@/lib/utils';
 import { useAppStore } from '@/store/app-store';
 import { useOSDetection } from '@/hooks/use-os-detection';
 import { ProjectSwitcherItem } from './components/project-switcher-item';
@@ -11,9 +11,12 @@ import { NotificationBell } from './components/notification-bell';
 import { NewProjectModal } from '@/components/dialogs/new-project-modal';
 import { OnboardingDialog } from '@/components/layout/sidebar/dialogs';
 import { useProjectCreation } from '@/components/layout/sidebar/hooks';
-import { SIDEBAR_FEATURE_FLAGS } from '@/components/layout/sidebar/constants';
+import {
+  MACOS_ELECTRON_TOP_PADDING_CLASS,
+  SIDEBAR_FEATURE_FLAGS,
+} from '@/components/layout/sidebar/constants';
 import type { Project } from '@/lib/electron';
-import { getElectronAPI } from '@/lib/electron';
+import { getElectronAPI, isElectron } from '@/lib/electron';
 import { initializeProject, hasAppSpec, hasAutomakerDir } from '@/lib/project-init';
 import { toast } from 'sonner';
 import { CreateSpecDialog } from '@/components/views/spec-view/dialogs';
@@ -279,7 +282,12 @@ export function ProjectSwitcher() {
         data-testid="project-switcher"
       >
         {/* Automaker Logo and Version */}
-        <div className="flex flex-col items-center pt-3 pb-2 px-2">
+        <div
+          className={cn(
+            'flex flex-col items-center pb-2 px-2',
+            isMac && isElectron() ? MACOS_ELECTRON_TOP_PADDING_CLASS : 'pt-3'
+          )}
+        >
           <button
             onClick={() => navigate({ to: '/dashboard' })}
             className="group flex flex-col items-center gap-0.5"

apps/ui/src/components/layout/sidebar/components/project-selector-with-options.tsx

@@ -100,14 +100,8 @@ export function ProjectSelectorWithOptions({
 
   const { sensors, handleDragEnd } = useDragAndDrop({ projects, reorderProjects });
 
-  const {
+  const { globalTheme, setProjectTheme, setPreviewTheme, handlePreviewEnter, handlePreviewLeave } =
-    globalTheme,
+    useProjectTheme();
-    setTheme,
-    setProjectTheme,
-    setPreviewTheme,
-    handlePreviewEnter,
-    handlePreviewLeave,
-  } = useProjectTheme();
 
   if (!sidebarOpen || projects.length === 0) {
     return null;
@@ -281,11 +275,8 @@ export function ProjectSelectorWithOptions({
                   onValueChange={(value) => {
                     if (currentProject) {
                       setPreviewTheme(null);
-                      if (value !== '') {
+                      // Only set project theme - don't change global theme
-                        setTheme(value as ThemeMode);
+                      // The UI uses getEffectiveTheme() which handles: previewTheme ?? projectTheme ?? globalTheme
-                      } else {
-                        setTheme(globalTheme);
-                      }
                       setProjectTheme(
                         currentProject.id,
                         value === '' ? null : (value as ThemeMode)

apps/ui/src/components/layout/sidebar/components/sidebar-header.tsx

@@ -6,6 +6,7 @@ import type { LucideIcon } from 'lucide-react';
 import { cn, isMac } from '@/lib/utils';
 import { formatShortcut } from '@/store/app-store';
 import { isElectron, type Project } from '@/lib/electron';
+import { MACOS_ELECTRON_TOP_PADDING_CLASS } from '../constants';
 import { getAuthenticatedImageUrl } from '@/lib/api-fetch';
 import { useAppStore } from '@/store/app-store';
 import {
@@ -89,7 +90,7 @@ export function SidebarHeader({
       <div
         className={cn(
           'shrink-0 flex flex-col items-center relative px-2 pt-3 pb-2',
-          isMac && isElectron() && 'pt-[10px]'
+          isMac && isElectron() && MACOS_ELECTRON_TOP_PADDING_CLASS
         )}
       >
         <Tooltip>
@@ -240,7 +241,7 @@ export function SidebarHeader({
     <div
       className={cn(
         'shrink-0 flex flex-col relative px-3 pt-3 pb-2',
-        isMac && isElectron() && 'pt-[10px]'
+        isMac && isElectron() && MACOS_ELECTRON_TOP_PADDING_CLASS
       )}
     >
       {/* Header with logo and project dropdown */}

apps/ui/src/components/layout/sidebar/components/sidebar-navigation.tsx

@@ -1,8 +1,13 @@
 import { useCallback, useEffect, useRef } from 'react';
 import type { NavigateOptions } from '@tanstack/react-router';
-import { ChevronDown, Wrench, Github } from 'lucide-react';
+import { ChevronDown, Wrench, Github, Folder } from 'lucide-react';
-import { cn } from '@/lib/utils';
+import * as LucideIcons from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { cn, isMac } from '@/lib/utils';
+import { isElectron } from '@/lib/electron';
+import { MACOS_ELECTRON_TOP_PADDING_CLASS } from '../constants';
 import { formatShortcut, useAppStore } from '@/store/app-store';
+import { getAuthenticatedImageUrl } from '@/lib/api-fetch';
 import type { NavSection } from '../types';
 import type { Project } from '@/lib/electron';
 import type { SidebarStyle } from '@automaker/types';
@@ -97,15 +102,52 @@ export function SidebarNavigation({
     return !!currentProject;
   });
 
+  // Get the icon component for the current project
+  const getProjectIcon = (): LucideIcon => {
+    if (currentProject?.icon && currentProject.icon in LucideIcons) {
+      return (LucideIcons as unknown as Record<string, LucideIcon>)[currentProject.icon];
+    }
+    return Folder;
+  };
+
+  const ProjectIcon = getProjectIcon();
+  const hasCustomIcon = !!currentProject?.customIconPath;
+
   return (
     <nav
       ref={navRef}
       className={cn(
         'flex-1 overflow-y-auto scrollbar-hide px-3 pb-2',
         // Add top padding in discord mode since there's no header
-        sidebarStyle === 'discord' ? 'pt-3' : 'mt-1'
+        // Extra padding for macOS Electron to avoid traffic light overlap
+        sidebarStyle === 'discord'
+          ? isMac && isElectron()
+            ? MACOS_ELECTRON_TOP_PADDING_CLASS
+            : 'pt-3'
+          : 'mt-1'
       )}
     >
+      {/* Project name display for classic/discord mode */}
+      {sidebarStyle === 'discord' && currentProject && sidebarOpen && (
+        <div className="mb-3">
+          <div className="flex items-center gap-2.5 px-3 py-2">
+            {hasCustomIcon ? (
+              <img
+                src={getAuthenticatedImageUrl(currentProject.customIconPath!, currentProject.path)}
+                alt={currentProject.name}
+                className="w-5 h-5 rounded object-cover"
+              />
+            ) : (
+              <ProjectIcon className="w-5 h-5 text-brand-500 shrink-0" />
+            )}
+            <span className="text-sm font-medium text-foreground truncate">
+              {currentProject.name}
+            </span>
+          </div>
+          <div className="h-px bg-border/40 mx-1 mt-1" />
+        </div>
+      )}
+
       {/* Navigation sections */}
       {visibleSections.map((section, sectionIdx) => {
         const isCollapsed = section.label ? collapsedNavSections[section.label] : false;

apps/ui/src/components/layout/sidebar/components/theme-menu-item.tsx

@@ -9,19 +9,15 @@ export const ThemeMenuItem = memo(function ThemeMenuItem({
 }: ThemeMenuItemProps) {
   const Icon = option.icon;
   return (
-    <div
+    <DropdownMenuRadioItem
-      key={option.value}
+      value={option.value}
+      data-testid={`project-theme-${option.value}`}
+      className="text-xs py-1.5"
       onPointerEnter={() => onPreviewEnter(option.value)}
       onPointerLeave={onPreviewLeave}
     >
-      <DropdownMenuRadioItem
+      <Icon className="w-3.5 h-3.5 mr-1.5" style={{ color: option.color }} />
-        value={option.value}
+      <span>{option.label}</span>
-        data-testid={`project-theme-${option.value}`}
+    </DropdownMenuRadioItem>
-        className="text-xs py-1.5"
-      >
-        <Icon className="w-3.5 h-3.5 mr-1.5" style={{ color: option.color }} />
-        <span>{option.label}</span>
-      </DropdownMenuRadioItem>
-    </div>
   );
 });

apps/ui/src/components/layout/sidebar/constants.ts

@@ -1,5 +1,11 @@
 import { darkThemes, lightThemes } from '@/config/theme-options';
 
+/**
+ * Tailwind class for top padding on macOS Electron to avoid overlapping with traffic light window controls.
+ * This padding is applied conditionally when running on macOS in Electron.
+ */
+export const MACOS_ELECTRON_TOP_PADDING_CLASS = 'pt-[38px]';
+
 /**
  * Shared constants for theme submenu positioning and layout.
  * Used across project-context-menu and project-selector-with-options components

apps/ui/src/components/ui/provider-icon.tsx

@@ -116,9 +116,8 @@ const PROVIDER_ICON_DEFINITIONS: Record<ProviderIconKey, ProviderIconDefinition>
   },
   copilot: {
     viewBox: '0 0 98 96',
-    // Official GitHub Octocat logo mark
+    // Official GitHub Octocat logo mark (theme-aware via currentColor)
     path: 'M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z',
-    fill: '#ffffff',
   },
 };
 

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

@@ -437,6 +437,63 @@ export function BoardView() {
   // Auto mode hook - pass current worktree to get worktree-specific state
   // Must be after selectedWorktree is defined
   const autoMode = useAutoMode(selectedWorktree);
+
+  const refreshBoardState = useCallback(async () => {
+    if (!currentProject) return;
+
+    const projectPath = currentProject.path;
+    const beforeFeatures = (
+      queryClient.getQueryData(queryKeys.features.all(projectPath)) as Feature[] | undefined
+    )?.length;
+    const beforeWorktrees = (
+      queryClient.getQueryData(queryKeys.worktrees.all(projectPath)) as
+        | { worktrees?: unknown[] }
+        | undefined
+    )?.worktrees?.length;
+    const beforeRunningAgents = (
+      queryClient.getQueryData(queryKeys.runningAgents.all()) as { count?: number } | undefined
+    )?.count;
+    const beforeAutoModeRunning = autoMode.isRunning;
+
+    try {
+      await Promise.all([
+        queryClient.refetchQueries({ queryKey: queryKeys.features.all(projectPath) }),
+        queryClient.refetchQueries({ queryKey: queryKeys.runningAgents.all() }),
+        queryClient.refetchQueries({ queryKey: queryKeys.worktrees.all(projectPath) }),
+        autoMode.refreshStatus(),
+      ]);
+
+      const afterFeatures = (
+        queryClient.getQueryData(queryKeys.features.all(projectPath)) as Feature[] | undefined
+      )?.length;
+      const afterWorktrees = (
+        queryClient.getQueryData(queryKeys.worktrees.all(projectPath)) as
+          | { worktrees?: unknown[] }
+          | undefined
+      )?.worktrees?.length;
+      const afterRunningAgents = (
+        queryClient.getQueryData(queryKeys.runningAgents.all()) as { count?: number } | undefined
+      )?.count;
+      const afterAutoModeRunning = autoMode.isRunning;
+
+      if (
+        beforeFeatures !== afterFeatures ||
+        beforeWorktrees !== afterWorktrees ||
+        beforeRunningAgents !== afterRunningAgents ||
+        beforeAutoModeRunning !== afterAutoModeRunning
+      ) {
+        logger.info('[Board] Refresh detected state mismatch', {
+          features: { before: beforeFeatures, after: afterFeatures },
+          worktrees: { before: beforeWorktrees, after: afterWorktrees },
+          runningAgents: { before: beforeRunningAgents, after: afterRunningAgents },
+          autoModeRunning: { before: beforeAutoModeRunning, after: afterAutoModeRunning },
+        });
+      }
+    } catch (error) {
+      logger.error('[Board] Failed to refresh board state:', error);
+      toast.error('Failed to refresh board state');
+    }
+  }, [autoMode, currentProject, queryClient]);
   // Get runningTasks from the hook (scoped to current project/worktree)
   const runningAutoTasks = autoMode.runningTasks;
   // Get worktree-specific maxConcurrency from the hook
@@ -1275,8 +1332,10 @@ export function BoardView() {
         maxConcurrency={maxConcurrency}
         runningAgentsCount={runningAutoTasks.length}
         onConcurrencyChange={(newMaxConcurrency) => {
-          if (currentProject && selectedWorktree) {
+          if (currentProject) {
-            const branchName = selectedWorktree.isMain ? null : selectedWorktree.branch;
+            // If selectedWorktree is undefined or it's the main worktree, branchName will be null.
+            // Otherwise, use the branch name.
+            const branchName = selectedWorktree?.isMain === false ? selectedWorktree.branch : null;
             setMaxConcurrencyForWorktree(currentProject.id, branchName, newMaxConcurrency);
 
             // Persist to server settings so capacity checks use the correct value
@@ -1319,6 +1378,7 @@ export function BoardView() {
         isCreatingSpec={isCreatingSpec}
         creatingSpecProjectPath={creatingSpecProjectPath}
         onShowBoardBackground={() => setShowBoardBackgroundModal(true)}
+        onRefreshBoard={refreshBoardState}
         viewMode={viewMode}
         onViewModeChange={setViewMode}
       />

apps/ui/src/components/views/board-view/board-header.tsx

@@ -1,7 +1,9 @@
 import { useCallback, useState } from 'react';
 import { Switch } from '@/components/ui/switch';
 import { Label } from '@/components/ui/label';
-import { Wand2, GitBranch, ClipboardCheck } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
+import { Wand2, GitBranch, ClipboardCheck, RefreshCw } from 'lucide-react';
 import { UsagePopover } from '@/components/usage-popover';
 import { useAppStore } from '@/store/app-store';
 import { useSetupStore } from '@/store/setup-store';
@@ -35,6 +37,7 @@ interface BoardHeaderProps {
   creatingSpecProjectPath?: string;
   // Board controls props
   onShowBoardBackground: () => void;
+  onRefreshBoard: () => Promise<void>;
   // View toggle props
   viewMode: ViewMode;
   onViewModeChange: (mode: ViewMode) => void;
@@ -60,6 +63,7 @@ export function BoardHeader({
   isCreatingSpec,
   creatingSpecProjectPath,
   onShowBoardBackground,
+  onRefreshBoard,
   viewMode,
   onViewModeChange,
 }: BoardHeaderProps) {
@@ -110,9 +114,20 @@ export function BoardHeader({
 
   // State for mobile actions panel
   const [showActionsPanel, setShowActionsPanel] = useState(false);
+  const [isRefreshingBoard, setIsRefreshingBoard] = useState(false);
 
   const isTablet = useIsTablet();
 
+  const handleRefreshBoard = useCallback(async () => {
+    if (isRefreshingBoard) return;
+    setIsRefreshingBoard(true);
+    try {
+      await onRefreshBoard();
+    } finally {
+      setIsRefreshingBoard(false);
+    }
+  }, [isRefreshingBoard, onRefreshBoard]);
+
   return (
     <div className="flex items-center justify-between gap-5 p-4 border-b border-border bg-glass backdrop-blur-md">
       <div className="flex items-center gap-4">
@@ -127,6 +142,22 @@ export function BoardHeader({
         <BoardControls isMounted={isMounted} onShowBoardBackground={onShowBoardBackground} />
       </div>
       <div className="flex gap-4 items-center">
+        {isMounted && !isTablet && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="secondary"
+                size="icon-sm"
+                onClick={handleRefreshBoard}
+                disabled={isRefreshingBoard}
+                aria-label="Refresh board state from server"
+              >
+                <RefreshCw className={isRefreshingBoard ? 'w-4 h-4 animate-spin' : 'w-4 h-4'} />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom">Refresh board state from server</TooltipContent>
+          </Tooltip>
+        )}
         {/* Usage Popover - show if either provider is authenticated, only on desktop */}
         {isMounted && !isTablet && (showClaudeUsage || showCodexUsage) && <UsagePopover />}
 

apps/ui/src/components/views/board-view/dialogs/create-pr-dialog.tsx

@@ -241,9 +241,9 @@ export function CreatePRDialog({
             <GitPullRequest className="w-5 h-5" />
             Create Pull Request
           </DialogTitle>
-          <DialogDescription>
+          <DialogDescription className="break-words">
             Push changes and create a pull request from{' '}
-            <code className="font-mono bg-muted px-1 rounded">{worktree.branch}</code>
+            <code className="font-mono bg-muted px-1 rounded break-all">{worktree.branch}</code>
           </DialogDescription>
         </DialogHeader>
 

apps/ui/src/components/views/project-settings-view/project-identity-section.tsx

@@ -68,10 +68,10 @@ export function ProjectIdentitySection({ project }: ProjectIdentitySectionProps)
       return;
     }
 
-    // Validate file size (max 2MB for icons)
+    // Validate file size (max 5MB for icons - allows animated GIFs)
-    if (file.size > 2 * 1024 * 1024) {
+    if (file.size > 5 * 1024 * 1024) {
       toast.error('File too large', {
-        description: 'Please upload an image smaller than 2MB.',
+        description: 'Please upload an image smaller than 5MB.',
       });
       return;
     }
@@ -208,7 +208,7 @@ export function ProjectIdentitySection({ project }: ProjectIdentitySectionProps)
                   {isUploadingIcon ? 'Uploading...' : 'Upload Custom Icon'}
                 </Button>
                 <p className="text-xs text-muted-foreground mt-1">
-                  PNG, JPG, GIF or WebP. Max 2MB.
+                  PNG, JPG, GIF or WebP. Max 5MB.
                 </p>
               </div>
             </div>

apps/ui/src/components/views/settings-view/event-hooks/event-history-view.tsx

@@ -19,6 +19,7 @@ import type { StoredEventSummary, StoredEvent, EventHookTrigger } from '@automak
 import { EVENT_HOOK_TRIGGER_LABELS } from '@automaker/types';
 import { getHttpApiClient } from '@/lib/http-api-client';
 import { ConfirmDialog } from '@/components/ui/confirm-dialog';
+import { toast } from 'sonner';
 
 export function EventHistoryView() {
   const currentProject = useAppStore((state) => state.currentProject);
@@ -85,16 +86,18 @@ export function EventHistoryView() {
         const failCount = hookResults.filter((r) => !r.success).length;
 
         if (hooksTriggered === 0) {
-          alert('No matching hooks found for this event trigger.');
+          toast.info('No matching hooks found for this event trigger.');
         } else if (failCount === 0) {
-          alert(`Successfully ran ${successCount} hook(s).`);
+          toast.success(`Successfully ran ${successCount} hook(s).`);
         } else {
-          alert(`Ran ${hooksTriggered} hook(s): ${successCount} succeeded, ${failCount} failed.`);
+          toast.warning(
+            `Ran ${hooksTriggered} hook(s): ${successCount} succeeded, ${failCount} failed.`
+          );
         }
       }
     } catch (error) {
       console.error('Failed to replay event:', error);
-      alert('Failed to replay event. Check console for details.');
+      toast.error('Failed to replay event. Check console for details.');
     } finally {
       setReplayingEvent(null);
     }

apps/ui/src/components/views/settings-view/terminal/prompt-preview.tsx

@@ -0,0 +1,283 @@
+/**
+ * Prompt Preview - Shows a live preview of the custom terminal prompt
+ */
+
+import type { ReactNode } from 'react';
+import { cn } from '@/lib/utils';
+import type { ThemeMode } from '@automaker/types';
+import { getTerminalTheme } from '@/config/terminal-themes';
+
+interface PromptPreviewProps {
+  format: 'standard' | 'minimal' | 'powerline' | 'starship';
+  theme: ThemeMode;
+  showGitBranch: boolean;
+  showGitStatus: boolean;
+  showUserHost: boolean;
+  showPath: boolean;
+  pathStyle: 'full' | 'short' | 'basename';
+  pathDepth: number;
+  showTime: boolean;
+  showExitStatus: boolean;
+  isOmpTheme?: boolean;
+  promptThemeLabel?: string;
+  className?: string;
+}
+
+export function PromptPreview({
+  format,
+  theme,
+  showGitBranch,
+  showGitStatus,
+  showUserHost,
+  showPath,
+  pathStyle,
+  pathDepth,
+  showTime,
+  showExitStatus,
+  isOmpTheme = false,
+  promptThemeLabel,
+  className,
+}: PromptPreviewProps) {
+  const terminalTheme = getTerminalTheme(theme);
+
+  const formatPath = (inputPath: string) => {
+    let displayPath = inputPath;
+    let prefix = '';
+
+    if (displayPath.startsWith('~/')) {
+      prefix = '~/';
+      displayPath = displayPath.slice(2);
+    } else if (displayPath.startsWith('/')) {
+      prefix = '/';
+      displayPath = displayPath.slice(1);
+    }
+
+    const segments = displayPath.split('/').filter((segment) => segment.length > 0);
+    const depth = Math.max(0, pathDepth);
+    const trimmedSegments = depth > 0 ? segments.slice(-depth) : segments;
+
+    let formattedSegments = trimmedSegments;
+    if (pathStyle === 'basename' && trimmedSegments.length > 0) {
+      formattedSegments = [trimmedSegments[trimmedSegments.length - 1]];
+    } else if (pathStyle === 'short') {
+      formattedSegments = trimmedSegments.map((segment, index) => {
+        if (index < trimmedSegments.length - 1) {
+          return segment.slice(0, 1);
+        }
+        return segment;
+      });
+    }
+
+    const joined = formattedSegments.join('/');
+    if (prefix === '/' && joined.length === 0) {
+      return '/';
+    }
+    if (prefix === '~/' && joined.length === 0) {
+      return '~';
+    }
+    return `${prefix}${joined}`;
+  };
+
+  // Generate preview text based on format
+  const renderPrompt = () => {
+    if (isOmpTheme) {
+      return (
+        <div className="font-mono text-sm leading-relaxed space-y-2">
+          <div style={{ color: terminalTheme.magenta }}>
+            {promptThemeLabel ?? 'Oh My Posh theme'}
+          </div>
+          <div className="text-xs text-muted-foreground">
+            Rendered by the oh-my-posh CLI in the terminal.
+          </div>
+          <div className="text-xs text-muted-foreground">
+            Preview here stays generic to avoid misleading output.
+          </div>
+        </div>
+      );
+    }
+
+    const user = 'user';
+    const host = 'automaker';
+    const path = formatPath('~/projects/automaker');
+    const branch = showGitBranch ? 'main' : null;
+    const dirty = showGitStatus && showGitBranch ? '*' : '';
+    const time = showTime ? '[14:32]' : '';
+    const status = showExitStatus ? '✗ 1' : '';
+
+    const gitInfo = branch ? ` (${branch}${dirty})` : '';
+
+    switch (format) {
+      case 'minimal': {
+        return (
+          <div className="font-mono text-sm leading-relaxed">
+            {showTime && <span style={{ color: terminalTheme.magenta }}>{time} </span>}
+            {showUserHost && (
+              <span style={{ color: terminalTheme.cyan }}>
+                {user}
+                <span style={{ color: terminalTheme.foreground }}>@</span>
+                <span style={{ color: terminalTheme.blue }}>{host}</span>{' '}
+              </span>
+            )}
+            {showPath && <span style={{ color: terminalTheme.yellow }}>{path}</span>}
+            {gitInfo && <span style={{ color: terminalTheme.magenta }}>{gitInfo}</span>}
+            {showExitStatus && <span style={{ color: terminalTheme.red }}> {status}</span>}
+            <span style={{ color: terminalTheme.green }}> $</span>
+            <span className="ml-1 animate-pulse">▊</span>
+          </div>
+        );
+      }
+
+      case 'powerline': {
+        const powerlineSegments: ReactNode[] = [];
+        if (showUserHost) {
+          powerlineSegments.push(
+            <span key="user-host" style={{ color: terminalTheme.cyan }}>
+              [{user}
+              <span style={{ color: terminalTheme.foreground }}>@</span>
+              <span style={{ color: terminalTheme.blue }}>{host}</span>]
+            </span>
+          );
+        }
+        if (showPath) {
+          powerlineSegments.push(
+            <span key="path" style={{ color: terminalTheme.yellow }}>
+              [{path}]
+            </span>
+          );
+        }
+        const powerlineCore = powerlineSegments.flatMap((segment, index) =>
+          index === 0
+            ? [segment]
+            : [
+                <span key={`sep-${index}`} style={{ color: terminalTheme.cyan }}>
+                  ─
+                </span>,
+                segment,
+              ]
+        );
+        const powerlineExtras: ReactNode[] = [];
+        if (gitInfo) {
+          powerlineExtras.push(
+            <span key="git" style={{ color: terminalTheme.magenta }}>
+              {gitInfo}
+            </span>
+          );
+        }
+        if (showTime) {
+          powerlineExtras.push(
+            <span key="time" style={{ color: terminalTheme.magenta }}>
+              {time}
+            </span>
+          );
+        }
+        if (showExitStatus) {
+          powerlineExtras.push(
+            <span key="status" style={{ color: terminalTheme.red }}>
+              {status}
+            </span>
+          );
+        }
+        const powerlineLine: ReactNode[] = [...powerlineCore];
+        if (powerlineExtras.length > 0) {
+          if (powerlineLine.length > 0) {
+            powerlineLine.push(' ');
+          }
+          powerlineLine.push(...powerlineExtras);
+        }
+
+        return (
+          <div className="font-mono text-sm leading-relaxed space-y-1">
+            <div>
+              <span style={{ color: terminalTheme.cyan }}>┌─</span>
+              {powerlineLine}
+            </div>
+            <div>
+              <span style={{ color: terminalTheme.cyan }}>└─</span>
+              <span style={{ color: terminalTheme.green }}>$</span>
+              <span className="ml-1 animate-pulse">▊</span>
+            </div>
+          </div>
+        );
+      }
+
+      case 'starship': {
+        return (
+          <div className="font-mono text-sm leading-relaxed space-y-1">
+            <div>
+              {showTime && <span style={{ color: terminalTheme.magenta }}>{time} </span>}
+              {showUserHost && (
+                <>
+                  <span style={{ color: terminalTheme.cyan }}>{user}</span>
+                  <span style={{ color: terminalTheme.foreground }}>@</span>
+                  <span style={{ color: terminalTheme.blue }}>{host}</span>
+                </>
+              )}
+              {showPath && (
+                <>
+                  <span style={{ color: terminalTheme.foreground }}> in </span>
+                  <span style={{ color: terminalTheme.yellow }}>{path}</span>
+                </>
+              )}
+              {branch && (
+                <>
+                  <span style={{ color: terminalTheme.foreground }}> on </span>
+                  <span style={{ color: terminalTheme.magenta }}>
+                    {branch}
+                    {dirty}
+                  </span>
+                </>
+              )}
+              {showExitStatus && <span style={{ color: terminalTheme.red }}> {status}</span>}
+            </div>
+            <div>
+              <span style={{ color: terminalTheme.green }}>❯</span>
+              <span className="ml-1 animate-pulse">▊</span>
+            </div>
+          </div>
+        );
+      }
+
+      case 'standard':
+      default: {
+        return (
+          <div className="font-mono text-sm leading-relaxed">
+            {showTime && <span style={{ color: terminalTheme.magenta }}>{time} </span>}
+            {showUserHost && (
+              <>
+                <span style={{ color: terminalTheme.cyan }}>[{user}</span>
+                <span style={{ color: terminalTheme.foreground }}>@</span>
+                <span style={{ color: terminalTheme.blue }}>{host}</span>
+                <span style={{ color: terminalTheme.cyan }}>]</span>
+              </>
+            )}
+            {showPath && <span style={{ color: terminalTheme.yellow }}> {path}</span>}
+            {gitInfo && <span style={{ color: terminalTheme.magenta }}>{gitInfo}</span>}
+            {showExitStatus && <span style={{ color: terminalTheme.red }}> {status}</span>}
+            <span style={{ color: terminalTheme.green }}> $</span>
+            <span className="ml-1 animate-pulse">▊</span>
+          </div>
+        );
+      }
+    }
+  };
+
+  return (
+    <div
+      className={cn(
+        'rounded-lg border p-4',
+        'bg-[var(--terminal-bg)] text-[var(--terminal-fg)]',
+        'shadow-inner',
+        className
+      )}
+      style={
+        {
+          '--terminal-bg': terminalTheme.background,
+          '--terminal-fg': terminalTheme.foreground,
+        } as React.CSSProperties
+      }
+    >
+      <div className="mb-2 text-xs text-muted-foreground opacity-70">Preview</div>
+      {renderPrompt()}
+    </div>
+  );
+}

apps/ui/src/components/views/settings-view/terminal/prompt-theme-presets.ts

@@ -0,0 +1,253 @@
+import type { TerminalPromptTheme } from '@automaker/types';
+
+export const PROMPT_THEME_CUSTOM_ID: TerminalPromptTheme = 'custom';
+
+export const OMP_THEME_NAMES = [
+  '1_shell',
+  'M365Princess',
+  'agnoster',
+  'agnoster.minimal',
+  'agnosterplus',
+  'aliens',
+  'amro',
+  'atomic',
+  'atomicBit',
+  'avit',
+  'blue-owl',
+  'blueish',
+  'bubbles',
+  'bubblesextra',
+  'bubblesline',
+  'capr4n',
+  'catppuccin',
+  'catppuccin_frappe',
+  'catppuccin_latte',
+  'catppuccin_macchiato',
+  'catppuccin_mocha',
+  'cert',
+  'chips',
+  'cinnamon',
+  'clean-detailed',
+  'cloud-context',
+  'cloud-native-azure',
+  'cobalt2',
+  'craver',
+  'darkblood',
+  'devious-diamonds',
+  'di4am0nd',
+  'dracula',
+  'easy-term',
+  'emodipt',
+  'emodipt-extend',
+  'fish',
+  'free-ukraine',
+  'froczh',
+  'gmay',
+  'glowsticks',
+  'grandpa-style',
+  'gruvbox',
+  'half-life',
+  'honukai',
+  'hotstick.minimal',
+  'hul10',
+  'hunk',
+  'huvix',
+  'if_tea',
+  'illusi0n',
+  'iterm2',
+  'jandedobbeleer',
+  'jblab_2021',
+  'jonnychipz',
+  'json',
+  'jtracey93',
+  'jv_sitecorian',
+  'kali',
+  'kushal',
+  'lambda',
+  'lambdageneration',
+  'larserikfinholt',
+  'lightgreen',
+  'marcduiker',
+  'markbull',
+  'material',
+  'microverse-power',
+  'mojada',
+  'montys',
+  'mt',
+  'multiverse-neon',
+  'negligible',
+  'neko',
+  'night-owl',
+  'nordtron',
+  'nu4a',
+  'onehalf.minimal',
+  'paradox',
+  'pararussel',
+  'patriksvensson',
+  'peru',
+  'pixelrobots',
+  'plague',
+  'poshmon',
+  'powerlevel10k_classic',
+  'powerlevel10k_lean',
+  'powerlevel10k_modern',
+  'powerlevel10k_rainbow',
+  'powerline',
+  'probua.minimal',
+  'pure',
+  'quick-term',
+  'remk',
+  'robbyrussell',
+  'rudolfs-dark',
+  'rudolfs-light',
+  'sim-web',
+  'slim',
+  'slimfat',
+  'smoothie',
+  'sonicboom_dark',
+  'sonicboom_light',
+  'sorin',
+  'space',
+  'spaceship',
+  'star',
+  'stelbent-compact.minimal',
+  'stelbent.minimal',
+  'takuya',
+  'the-unnamed',
+  'thecyberden',
+  'tiwahu',
+  'tokyo',
+  'tokyonight_storm',
+  'tonybaloney',
+  'uew',
+  'unicorn',
+  'velvet',
+  'wholespace',
+  'wopian',
+  'xtoys',
+  'ys',
+  'zash',
+] as const;
+
+type OmpThemeName = (typeof OMP_THEME_NAMES)[number];
+
+type PromptFormat = 'standard' | 'minimal' | 'powerline' | 'starship';
+
+type PathStyle = 'full' | 'short' | 'basename';
+
+export interface PromptThemeConfig {
+  promptFormat: PromptFormat;
+  showGitBranch: boolean;
+  showGitStatus: boolean;
+  showUserHost: boolean;
+  showPath: boolean;
+  pathStyle: PathStyle;
+  pathDepth: number;
+  showTime: boolean;
+  showExitStatus: boolean;
+}
+
+export interface PromptThemePreset {
+  id: TerminalPromptTheme;
+  label: string;
+  description: string;
+  config: PromptThemeConfig;
+}
+
+const PATH_DEPTH_FULL = 0;
+const PATH_DEPTH_TWO = 2;
+const PATH_DEPTH_THREE = 3;
+
+const POWERLINE_HINTS = ['powerline', 'powerlevel10k', 'agnoster', 'bubbles', 'smoothie'];
+const MINIMAL_HINTS = ['minimal', 'pure', 'slim', 'negligible'];
+const STARSHIP_HINTS = ['spaceship', 'star'];
+const SHORT_PATH_HINTS = ['compact', 'lean', 'slim'];
+const TIME_HINTS = ['time', 'clock'];
+const EXIT_STATUS_HINTS = ['status', 'exit', 'fail', 'error'];
+
+function toPromptThemeId(name: OmpThemeName): TerminalPromptTheme {
+  return `omp-${name}` as TerminalPromptTheme;
+}
+
+function formatLabel(name: string): string {
+  const cleaned = name.replace(/[._-]+/g, ' ').trim();
+  return cleaned
+    .split(' ')
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function buildPresetConfig(name: OmpThemeName): PromptThemeConfig {
+  const lower = name.toLowerCase();
+  const isPowerline = POWERLINE_HINTS.some((hint) => lower.includes(hint));
+  const isMinimal = MINIMAL_HINTS.some((hint) => lower.includes(hint));
+  const isStarship = STARSHIP_HINTS.some((hint) => lower.includes(hint));
+  let promptFormat: PromptFormat = 'standard';
+
+  if (isPowerline) {
+    promptFormat = 'powerline';
+  } else if (isMinimal) {
+    promptFormat = 'minimal';
+  } else if (isStarship) {
+    promptFormat = 'starship';
+  }
+
+  const showUserHost = !isMinimal;
+  const showPath = true;
+  const pathStyle: PathStyle = isMinimal ? 'short' : 'full';
+  let pathDepth = isMinimal ? PATH_DEPTH_THREE : PATH_DEPTH_FULL;
+
+  if (SHORT_PATH_HINTS.some((hint) => lower.includes(hint))) {
+    pathDepth = PATH_DEPTH_TWO;
+  }
+
+  if (lower.includes('powerlevel10k')) {
+    pathDepth = PATH_DEPTH_THREE;
+  }
+
+  const showTime = TIME_HINTS.some((hint) => lower.includes(hint));
+  const showExitStatus = EXIT_STATUS_HINTS.some((hint) => lower.includes(hint));
+
+  return {
+    promptFormat,
+    showGitBranch: true,
+    showGitStatus: true,
+    showUserHost,
+    showPath,
+    pathStyle,
+    pathDepth,
+    showTime,
+    showExitStatus,
+  };
+}
+
+export const PROMPT_THEME_PRESETS: PromptThemePreset[] = OMP_THEME_NAMES.map((name) => ({
+  id: toPromptThemeId(name),
+  label: `${formatLabel(name)} (OMP)`,
+  description: 'Oh My Posh theme preset',
+  config: buildPresetConfig(name),
+}));
+
+export function getPromptThemePreset(presetId: TerminalPromptTheme): PromptThemePreset | null {
+  return PROMPT_THEME_PRESETS.find((preset) => preset.id === presetId) ?? null;
+}
+
+export function getMatchingPromptThemeId(config: PromptThemeConfig): TerminalPromptTheme {
+  const match = PROMPT_THEME_PRESETS.find((preset) => {
+    const presetConfig = preset.config;
+    return (
+      presetConfig.promptFormat === config.promptFormat &&
+      presetConfig.showGitBranch === config.showGitBranch &&
+      presetConfig.showGitStatus === config.showGitStatus &&
+      presetConfig.showUserHost === config.showUserHost &&
+      presetConfig.showPath === config.showPath &&
+      presetConfig.pathStyle === config.pathStyle &&
+      presetConfig.pathDepth === config.pathDepth &&
+      presetConfig.showTime === config.showTime &&
+      presetConfig.showExitStatus === config.showExitStatus
+    );
+  });
+
+  return match?.id ?? PROMPT_THEME_CUSTOM_ID;
+}

apps/ui/src/components/views/settings-view/terminal/terminal-config-section.tsx

@@ -0,0 +1,662 @@
+/**
+ * Terminal Config Section - Custom terminal configurations with theme synchronization
+ *
+ * This component provides UI for enabling custom terminal prompts that automatically
+ * sync with Automaker's 40 themes. It's an opt-in feature that generates shell configs
+ * in .automaker/terminal/ without modifying user's existing RC files.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Wand2, GitBranch, Info, Plus, X } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { useAppStore } from '@/store/app-store';
+import { toast } from 'sonner';
+import { PromptPreview } from './prompt-preview';
+import type { TerminalPromptTheme } from '@automaker/types';
+import {
+  PROMPT_THEME_CUSTOM_ID,
+  PROMPT_THEME_PRESETS,
+  getMatchingPromptThemeId,
+  getPromptThemePreset,
+  type PromptThemeConfig,
+} from './prompt-theme-presets';
+import { useUpdateGlobalSettings } from '@/hooks/mutations/use-settings-mutations';
+import { useGlobalSettings } from '@/hooks/queries/use-settings';
+import { ConfirmDialog } from '@/components/ui/confirm-dialog';
+
+export function TerminalConfigSection() {
+  const PATH_DEPTH_MIN = 0;
+  const PATH_DEPTH_MAX = 10;
+  const ENV_VAR_UPDATE_DEBOUNCE_MS = 400;
+  const ENV_VAR_ID_PREFIX = 'env';
+  const TERMINAL_RC_FILE_VERSION = 11;
+  const { theme } = useAppStore();
+  const { data: globalSettings } = useGlobalSettings();
+  const updateGlobalSettings = useUpdateGlobalSettings({ showSuccessToast: false });
+  const envVarIdRef = useRef(0);
+  const envVarUpdateTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const createEnvVarEntry = useCallback(
+    (key = '', value = '') => {
+      envVarIdRef.current += 1;
+      return {
+        id: `${ENV_VAR_ID_PREFIX}-${envVarIdRef.current}`,
+        key,
+        value,
+      };
+    },
+    [ENV_VAR_ID_PREFIX]
+  );
+  const [localEnvVars, setLocalEnvVars] = useState<
+    Array<{ id: string; key: string; value: string }>
+  >(() =>
+    Object.entries(globalSettings?.terminalConfig?.customEnvVars || {}).map(([key, value]) =>
+      createEnvVarEntry(key, value)
+    )
+  );
+  const [showEnableConfirm, setShowEnableConfirm] = useState(false);
+
+  const clampPathDepth = (value: number) =>
+    Math.min(PATH_DEPTH_MAX, Math.max(PATH_DEPTH_MIN, value));
+
+  const defaultTerminalConfig = {
+    enabled: false,
+    customPrompt: true,
+    promptFormat: 'standard' as const,
+    promptTheme: PROMPT_THEME_CUSTOM_ID,
+    showGitBranch: true,
+    showGitStatus: true,
+    showUserHost: true,
+    showPath: true,
+    pathStyle: 'full' as const,
+    pathDepth: PATH_DEPTH_MIN,
+    showTime: false,
+    showExitStatus: false,
+    customAliases: '',
+    customEnvVars: {},
+  };
+
+  const terminalConfig = {
+    ...defaultTerminalConfig,
+    ...globalSettings?.terminalConfig,
+    customAliases:
+      globalSettings?.terminalConfig?.customAliases ?? defaultTerminalConfig.customAliases,
+    customEnvVars:
+      globalSettings?.terminalConfig?.customEnvVars ?? defaultTerminalConfig.customEnvVars,
+  };
+
+  const promptThemeConfig: PromptThemeConfig = {
+    promptFormat: terminalConfig.promptFormat,
+    showGitBranch: terminalConfig.showGitBranch,
+    showGitStatus: terminalConfig.showGitStatus,
+    showUserHost: terminalConfig.showUserHost,
+    showPath: terminalConfig.showPath,
+    pathStyle: terminalConfig.pathStyle,
+    pathDepth: terminalConfig.pathDepth,
+    showTime: terminalConfig.showTime,
+    showExitStatus: terminalConfig.showExitStatus,
+  };
+
+  const storedPromptTheme = terminalConfig.promptTheme;
+  const activePromptThemeId =
+    storedPromptTheme === PROMPT_THEME_CUSTOM_ID
+      ? PROMPT_THEME_CUSTOM_ID
+      : (storedPromptTheme ?? getMatchingPromptThemeId(promptThemeConfig));
+  const isOmpTheme =
+    storedPromptTheme !== undefined && storedPromptTheme !== PROMPT_THEME_CUSTOM_ID;
+  const promptThemePreset = isOmpTheme
+    ? getPromptThemePreset(storedPromptTheme as TerminalPromptTheme)
+    : null;
+
+  const applyEnabledUpdate = (enabled: boolean) => {
+    // Ensure all required fields are present
+    const updatedConfig = {
+      enabled,
+      customPrompt: terminalConfig.customPrompt,
+      promptFormat: terminalConfig.promptFormat,
+      showGitBranch: terminalConfig.showGitBranch,
+      showGitStatus: terminalConfig.showGitStatus,
+      showUserHost: terminalConfig.showUserHost,
+      showPath: terminalConfig.showPath,
+      pathStyle: terminalConfig.pathStyle,
+      pathDepth: terminalConfig.pathDepth,
+      showTime: terminalConfig.showTime,
+      showExitStatus: terminalConfig.showExitStatus,
+      promptTheme: terminalConfig.promptTheme ?? PROMPT_THEME_CUSTOM_ID,
+      customAliases: terminalConfig.customAliases,
+      customEnvVars: terminalConfig.customEnvVars,
+      rcFileVersion: TERMINAL_RC_FILE_VERSION,
+    };
+
+    updateGlobalSettings.mutate(
+      { terminalConfig: updatedConfig },
+      {
+        onSuccess: () => {
+          toast.success(
+            enabled ? 'Custom terminal configs enabled' : 'Custom terminal configs disabled',
+            {
+              description: enabled
+                ? 'New terminals will use custom prompts'
+                : '.automaker/terminal/ will be cleaned up',
+            }
+          );
+        },
+        onError: (error) => {
+          console.error('[TerminalConfig] Failed to update settings:', error);
+          toast.error('Failed to update terminal config', {
+            description: error instanceof Error ? error.message : 'Unknown error',
+          });
+        },
+      }
+    );
+  };
+
+  useEffect(() => {
+    setLocalEnvVars(
+      Object.entries(globalSettings?.terminalConfig?.customEnvVars || {}).map(([key, value]) =>
+        createEnvVarEntry(key, value)
+      )
+    );
+  }, [createEnvVarEntry, globalSettings?.terminalConfig?.customEnvVars]);
+
+  useEffect(() => {
+    return () => {
+      if (envVarUpdateTimeoutRef.current) {
+        clearTimeout(envVarUpdateTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  const handleToggleEnabled = async (enabled: boolean) => {
+    if (enabled) {
+      setShowEnableConfirm(true);
+      return;
+    }
+
+    applyEnabledUpdate(false);
+  };
+
+  const handleUpdateConfig = (updates: Partial<typeof terminalConfig>) => {
+    const nextPromptTheme = updates.promptTheme ?? PROMPT_THEME_CUSTOM_ID;
+
+    updateGlobalSettings.mutate(
+      {
+        terminalConfig: {
+          ...terminalConfig,
+          ...updates,
+          promptTheme: nextPromptTheme,
+        },
+      },
+      {
+        onError: (error) => {
+          console.error('[TerminalConfig] Failed to update settings:', error);
+          toast.error('Failed to update terminal config', {
+            description: error instanceof Error ? error.message : 'Unknown error',
+          });
+        },
+      }
+    );
+  };
+
+  const scheduleEnvVarsUpdate = (envVarsObject: Record<string, string>) => {
+    if (envVarUpdateTimeoutRef.current) {
+      clearTimeout(envVarUpdateTimeoutRef.current);
+    }
+    envVarUpdateTimeoutRef.current = setTimeout(() => {
+      handleUpdateConfig({ customEnvVars: envVarsObject });
+    }, ENV_VAR_UPDATE_DEBOUNCE_MS);
+  };
+
+  const handlePromptThemeChange = (themeId: string) => {
+    if (themeId === PROMPT_THEME_CUSTOM_ID) {
+      handleUpdateConfig({ promptTheme: PROMPT_THEME_CUSTOM_ID });
+      return;
+    }
+
+    const preset = getPromptThemePreset(themeId as TerminalPromptTheme);
+    if (!preset) {
+      handleUpdateConfig({ promptTheme: PROMPT_THEME_CUSTOM_ID });
+      return;
+    }
+
+    handleUpdateConfig({
+      ...preset.config,
+      promptTheme: preset.id,
+    });
+  };
+
+  const addEnvVar = () => {
+    setLocalEnvVars([...localEnvVars, createEnvVarEntry()]);
+  };
+
+  const removeEnvVar = (id: string) => {
+    const newVars = localEnvVars.filter((envVar) => envVar.id !== id);
+    setLocalEnvVars(newVars);
+
+    // Update settings
+    const envVarsObject = newVars.reduce(
+      (acc, { key, value }) => {
+        if (key) acc[key] = value;
+        return acc;
+      },
+      {} as Record<string, string>
+    );
+
+    scheduleEnvVarsUpdate(envVarsObject);
+  };
+
+  const updateEnvVar = (id: string, field: 'key' | 'value', newValue: string) => {
+    const newVars = localEnvVars.map((envVar) =>
+      envVar.id === id ? { ...envVar, [field]: newValue } : envVar
+    );
+    setLocalEnvVars(newVars);
+
+    // Validate and update settings (only if key is valid)
+    const envVarsObject = newVars.reduce(
+      (acc, { key, value }) => {
+        // Only include vars with valid keys (alphanumeric + underscore)
+        if (key && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key)) {
+          acc[key] = value;
+        }
+        return acc;
+      },
+      {} as Record<string, string>
+    );
+
+    scheduleEnvVarsUpdate(envVarsObject);
+  };
+
+  return (
+    <div
+      className={cn(
+        'rounded-2xl overflow-hidden',
+        'border border-border/50',
+        'bg-gradient-to-br from-card/90 via-card/70 to-card/80 backdrop-blur-xl',
+        'shadow-sm shadow-black/5'
+      )}
+    >
+      <div className="p-6 border-b border-border/50 bg-gradient-to-r from-transparent via-purple-500/5 to-transparent">
+        <div className="flex items-center gap-3 mb-2">
+          <div className="w-9 h-9 rounded-xl bg-gradient-to-br from-purple-500/20 to-purple-600/10 flex items-center justify-center border border-purple-500/20">
+            <Wand2 className="w-5 h-5 text-purple-500" />
+          </div>
+          <h2 className="text-lg font-semibold text-foreground tracking-tight">
+            Custom Terminal Configurations
+          </h2>
+        </div>
+        <p className="text-sm text-muted-foreground/80 ml-12">
+          Generate custom shell prompts that automatically sync with your app theme. Opt-in feature
+          that creates configs in .automaker/terminal/ without modifying your existing RC files.
+        </p>
+      </div>
+
+      <div className="p-6 space-y-6">
+        {/* Enable Toggle */}
+        <div className="flex items-center justify-between">
+          <div className="space-y-1">
+            <Label className="text-foreground font-medium">Enable Custom Configurations</Label>
+            <p className="text-xs text-muted-foreground">
+              Create theme-synced shell configs in .automaker/terminal/
+            </p>
+          </div>
+          <Switch checked={terminalConfig.enabled} onCheckedChange={handleToggleEnabled} />
+        </div>
+
+        {terminalConfig.enabled && (
+          <>
+            {/* Info Box */}
+            <div className="rounded-lg border border-purple-500/20 bg-purple-500/5 p-3 flex gap-2">
+              <Info className="h-4 w-4 text-purple-500 flex-shrink-0 mt-0.5" />
+              <div className="text-xs text-foreground/80">
+                <strong>How it works:</strong> Custom configs are applied to new terminals only.
+                Your ~/.bashrc and ~/.zshrc are still loaded first. Close and reopen terminals to
+                see changes.
+              </div>
+            </div>
+
+            {/* Custom Prompt Toggle */}
+            <div className="flex items-center justify-between">
+              <div className="space-y-1">
+                <Label className="text-foreground font-medium">Custom Prompt</Label>
+                <p className="text-xs text-muted-foreground">
+                  Override default shell prompt with themed version
+                </p>
+              </div>
+              <Switch
+                checked={terminalConfig.customPrompt}
+                onCheckedChange={(checked) => handleUpdateConfig({ customPrompt: checked })}
+              />
+            </div>
+
+            {terminalConfig.customPrompt && (
+              <>
+                {/* Prompt Format */}
+                <div className="space-y-3">
+                  <Label className="text-foreground font-medium">Prompt Theme (Oh My Posh)</Label>
+                  <Select value={activePromptThemeId} onValueChange={handlePromptThemeChange}>
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value={PROMPT_THEME_CUSTOM_ID}>
+                        <div className="space-y-0.5">
+                          <div>Custom</div>
+                          <div className="text-xs text-muted-foreground">
+                            Hand-tuned configuration
+                          </div>
+                        </div>
+                      </SelectItem>
+                      {PROMPT_THEME_PRESETS.map((preset) => (
+                        <SelectItem key={preset.id} value={preset.id}>
+                          <div className="space-y-0.5">
+                            <div>{preset.label}</div>
+                            <div className="text-xs text-muted-foreground">
+                              {preset.description}
+                            </div>
+                          </div>
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+
+                {isOmpTheme && (
+                  <div className="rounded-lg border border-emerald-500/20 bg-emerald-500/5 p-3 flex gap-2">
+                    <Info className="h-4 w-4 text-emerald-500 flex-shrink-0 mt-0.5" />
+                    <div className="text-xs text-foreground/80">
+                      <strong>{promptThemePreset?.label ?? 'Oh My Posh theme'}</strong> uses the
+                      oh-my-posh CLI for rendering. Ensure it&apos;s installed for the full theme.
+                      Prompt format and segment toggles are ignored while an OMP theme is selected.
+                    </div>
+                  </div>
+                )}
+
+                <div className="space-y-3">
+                  <Label className="text-foreground font-medium">Prompt Format</Label>
+                  <Select
+                    value={terminalConfig.promptFormat}
+                    onValueChange={(value: 'standard' | 'minimal' | 'powerline' | 'starship') =>
+                      handleUpdateConfig({ promptFormat: value })
+                    }
+                    disabled={isOmpTheme}
+                  >
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="standard">
+                        <div className="space-y-0.5">
+                          <div>Standard</div>
+                          <div className="text-xs text-muted-foreground">
+                            [user@host] ~/path (main*) $
+                          </div>
+                        </div>
+                      </SelectItem>
+                      <SelectItem value="minimal">
+                        <div className="space-y-0.5">
+                          <div>Minimal</div>
+                          <div className="text-xs text-muted-foreground">~/path (main*) $</div>
+                        </div>
+                      </SelectItem>
+                      <SelectItem value="powerline">
+                        <div className="space-y-0.5">
+                          <div>Powerline</div>
+                          <div className="text-xs text-muted-foreground">
+                            ┌─[user@host]─[~/path]─[main*]
+                          </div>
+                        </div>
+                      </SelectItem>
+                      <SelectItem value="starship">
+                        <div className="space-y-0.5">
+                          <div>Starship-Inspired</div>
+                          <div className="text-xs text-muted-foreground">
+                            user@host in ~/path on main*
+                          </div>
+                        </div>
+                      </SelectItem>
+                    </SelectContent>
+                  </Select>
+                </div>
+
+                {/* Git Info Toggles */}
+                <div className="space-y-4 pl-4 border-l-2 border-border/30">
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <GitBranch className="w-4 h-4 text-muted-foreground" />
+                      <Label className="text-sm">Show Git Branch</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showGitBranch}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showGitBranch: checked })}
+                      disabled={isOmpTheme}
+                    />
+                  </div>
+
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm text-muted-foreground">*</span>
+                      <Label className="text-sm">Show Git Status (dirty indicator)</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showGitStatus}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showGitStatus: checked })}
+                      disabled={!terminalConfig.showGitBranch || isOmpTheme}
+                    />
+                  </div>
+                </div>
+
+                {/* Prompt Segments */}
+                <div className="space-y-4 pl-4 border-l-2 border-border/30">
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <Wand2 className="w-4 h-4 text-muted-foreground" />
+                      <Label className="text-sm">Show User & Host</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showUserHost}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showUserHost: checked })}
+                      disabled={isOmpTheme}
+                    />
+                  </div>
+
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm text-muted-foreground">~/</span>
+                      <Label className="text-sm">Show Path</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showPath}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showPath: checked })}
+                      disabled={isOmpTheme}
+                    />
+                  </div>
+
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm text-muted-foreground">⏱</span>
+                      <Label className="text-sm">Show Time</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showTime}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showTime: checked })}
+                      disabled={isOmpTheme}
+                    />
+                  </div>
+
+                  <div className="flex items-center justify-between">
+                    <div className="flex items-center gap-2">
+                      <span className="text-sm text-muted-foreground">✗</span>
+                      <Label className="text-sm">Show Exit Status</Label>
+                    </div>
+                    <Switch
+                      checked={terminalConfig.showExitStatus}
+                      onCheckedChange={(checked) => handleUpdateConfig({ showExitStatus: checked })}
+                      disabled={isOmpTheme}
+                    />
+                  </div>
+
+                  <div className="grid gap-3 sm:grid-cols-2">
+                    <div className="space-y-2">
+                      <Label className="text-xs text-muted-foreground">Path Style</Label>
+                      <Select
+                        value={terminalConfig.pathStyle}
+                        onValueChange={(value: 'full' | 'short' | 'basename') =>
+                          handleUpdateConfig({ pathStyle: value })
+                        }
+                        disabled={!terminalConfig.showPath || isOmpTheme}
+                      >
+                        <SelectTrigger>
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          <SelectItem value="full">Full</SelectItem>
+                          <SelectItem value="short">Short</SelectItem>
+                          <SelectItem value="basename">Basename</SelectItem>
+                        </SelectContent>
+                      </Select>
+                    </div>
+
+                    <div className="space-y-2">
+                      <Label className="text-xs text-muted-foreground">Path Depth</Label>
+                      <Input
+                        type="number"
+                        min={PATH_DEPTH_MIN}
+                        max={PATH_DEPTH_MAX}
+                        value={terminalConfig.pathDepth}
+                        onChange={(event) =>
+                          handleUpdateConfig({
+                            pathDepth: clampPathDepth(Number(event.target.value) || 0),
+                          })
+                        }
+                        disabled={!terminalConfig.showPath || isOmpTheme}
+                      />
+                    </div>
+                  </div>
+                </div>
+
+                {/* Live Preview */}
+                <div className="space-y-3">
+                  <Label className="text-foreground font-medium">Preview</Label>
+                  <PromptPreview
+                    format={terminalConfig.promptFormat}
+                    theme={theme}
+                    showGitBranch={terminalConfig.showGitBranch}
+                    showGitStatus={terminalConfig.showGitStatus}
+                    showUserHost={terminalConfig.showUserHost}
+                    showPath={terminalConfig.showPath}
+                    pathStyle={terminalConfig.pathStyle}
+                    pathDepth={terminalConfig.pathDepth}
+                    showTime={terminalConfig.showTime}
+                    showExitStatus={terminalConfig.showExitStatus}
+                    isOmpTheme={isOmpTheme}
+                    promptThemeLabel={promptThemePreset?.label}
+                  />
+                </div>
+              </>
+            )}
+
+            {/* Custom Aliases */}
+            <div className="space-y-3">
+              <div className="space-y-1">
+                <Label className="text-foreground font-medium">Custom Aliases</Label>
+                <p className="text-xs text-muted-foreground">
+                  Add shell aliases (one per line, e.g., alias ll='ls -la')
+                </p>
+              </div>
+              <Textarea
+                value={terminalConfig.customAliases}
+                onChange={(e) => handleUpdateConfig({ customAliases: e.target.value })}
+                placeholder="# Custom aliases&#10;alias gs='git status'&#10;alias ll='ls -la'&#10;alias ..='cd ..'"
+                className="font-mono text-sm h-32"
+              />
+            </div>
+
+            {/* Custom Environment Variables */}
+            <div className="space-y-3">
+              <div className="flex items-center justify-between">
+                <div className="space-y-1">
+                  <Label className="text-foreground font-medium">
+                    Custom Environment Variables
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    Add custom env vars (alphanumeric + underscore only)
+                  </p>
+                </div>
+                <Button variant="outline" size="sm" onClick={addEnvVar} className="h-8 gap-1.5">
+                  <Plus className="w-3.5 h-3.5" />
+                  Add
+                </Button>
+              </div>
+
+              {localEnvVars.length > 0 && (
+                <div className="space-y-2">
+                  {localEnvVars.map((envVar) => (
+                    <div key={envVar.id} className="flex gap-2 items-start">
+                      <Input
+                        value={envVar.key}
+                        onChange={(e) => updateEnvVar(envVar.id, 'key', e.target.value)}
+                        placeholder="VAR_NAME"
+                        className={cn(
+                          'font-mono text-sm flex-1',
+                          envVar.key &&
+                            !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(envVar.key) &&
+                            'border-destructive'
+                        )}
+                      />
+                      <Input
+                        value={envVar.value}
+                        onChange={(e) => updateEnvVar(envVar.id, 'value', e.target.value)}
+                        placeholder="value"
+                        className="font-mono text-sm flex-[2]"
+                      />
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        onClick={() => removeEnvVar(envVar.id)}
+                        className="h-9 w-9 p-0 text-muted-foreground hover:text-destructive"
+                      >
+                        <X className="w-4 h-4" />
+                      </Button>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          </>
+        )}
+      </div>
+
+      <ConfirmDialog
+        open={showEnableConfirm}
+        onOpenChange={setShowEnableConfirm}
+        title="Enable custom terminal configurations"
+        description="Automaker will generate per-project shell configuration files for your terminal."
+        icon={Info}
+        confirmText="Enable"
+        onConfirm={() => applyEnabledUpdate(true)}
+      >
+        <div className="space-y-3 text-sm text-muted-foreground">
+          <ul className="list-disc space-y-1 pl-5">
+            <li>Creates shell config files in `.automaker/terminal/`</li>
+            <li>Applies prompts and colors that match your app theme</li>
+            <li>Leaves your existing `~/.bashrc` and `~/.zshrc` untouched</li>
+          </ul>
+          <p className="text-xs text-muted-foreground">
+            New terminal sessions will use the custom prompt; existing sessions are unchanged.
+          </p>
+        </div>
+      </ConfirmDialog>
+    </div>
+  );
+}

apps/ui/src/components/views/settings-view/terminal/terminal-section.tsx

@@ -24,6 +24,7 @@ import { TERMINAL_FONT_OPTIONS } from '@/config/terminal-themes';
 import { DEFAULT_FONT_VALUE } from '@/config/ui-font-options';
 import { useAvailableTerminals } from '@/components/views/board-view/worktree-panel/hooks/use-available-terminals';
 import { getTerminalIcon } from '@/components/icons/terminal-icons';
+import { TerminalConfigSection } from './terminal-config-section';
 
 export function TerminalSection() {
   const {
@@ -53,253 +54,258 @@ export function TerminalSection() {
   const { terminals, isRefreshing, refresh } = useAvailableTerminals();
 
   return (
-    <div
+    <div className="space-y-6">
-      className={cn(
+      <div
-        'rounded-2xl overflow-hidden',
+        className={cn(
-        'border border-border/50',
+          'rounded-2xl overflow-hidden',
-        'bg-gradient-to-br from-card/90 via-card/70 to-card/80 backdrop-blur-xl',
+          'border border-border/50',
-        'shadow-sm shadow-black/5'
+          'bg-gradient-to-br from-card/90 via-card/70 to-card/80 backdrop-blur-xl',
-      )}
+          'shadow-sm shadow-black/5'
-    >
+        )}
-      <div className="p-6 border-b border-border/50 bg-gradient-to-r from-transparent via-accent/5 to-transparent">
+      >
-        <div className="flex items-center gap-3 mb-2">
+        <div className="p-6 border-b border-border/50 bg-gradient-to-r from-transparent via-accent/5 to-transparent">
-          <div className="w-9 h-9 rounded-xl bg-gradient-to-br from-green-500/20 to-green-600/10 flex items-center justify-center border border-green-500/20">
+          <div className="flex items-center gap-3 mb-2">
-            <SquareTerminal className="w-5 h-5 text-green-500" />
+            <div className="w-9 h-9 rounded-xl bg-gradient-to-br from-green-500/20 to-green-600/10 flex items-center justify-center border border-green-500/20">
+              <SquareTerminal className="w-5 h-5 text-green-500" />
+            </div>
+            <h2 className="text-lg font-semibold text-foreground tracking-tight">Terminal</h2>
           </div>
-          <h2 className="text-lg font-semibold text-foreground tracking-tight">Terminal</h2>
+          <p className="text-sm text-muted-foreground/80 ml-12">
-        </div>
+            Customize terminal appearance and behavior. Theme follows your app theme in Appearance
-        <p className="text-sm text-muted-foreground/80 ml-12">
+            settings.
-          Customize terminal appearance and behavior. Theme follows your app theme in Appearance
-          settings.
-        </p>
-      </div>
-      <div className="p-6 space-y-6">
-        {/* Default External Terminal */}
-        <div className="space-y-3">
-          <div className="flex items-center justify-between">
-            <Label className="text-foreground font-medium">Default External Terminal</Label>
-            <Button
-              variant="ghost"
-              size="sm"
-              className="h-7 w-7 p-0"
-              onClick={refresh}
-              disabled={isRefreshing}
-              title="Refresh available terminals"
-              aria-label="Refresh available terminals"
-            >
-              <RefreshCw className={cn('w-3.5 h-3.5', isRefreshing && 'animate-spin')} />
-            </Button>
-          </div>
-          <p className="text-xs text-muted-foreground">
-            Terminal to use when selecting "Open in Terminal" from the worktree menu
           </p>
-          <Select
+        </div>
-            value={defaultTerminalId ?? 'integrated'}
+        <div className="p-6 space-y-6">
-            onValueChange={(value) => {
+          {/* Default External Terminal */}
-              setDefaultTerminalId(value === 'integrated' ? null : value);
+          <div className="space-y-3">
-              toast.success(
+            <div className="flex items-center justify-between">
-                value === 'integrated'
+              <Label className="text-foreground font-medium">Default External Terminal</Label>
-                  ? 'Integrated terminal set as default'
+              <Button
-                  : 'Default terminal changed'
+                variant="ghost"
-              );
+                size="sm"
-            }}
+                className="h-7 w-7 p-0"
-          >
+                onClick={refresh}
-            <SelectTrigger className="w-full">
+                disabled={isRefreshing}
-              <SelectValue placeholder="Select a terminal" />
+                title="Refresh available terminals"
-            </SelectTrigger>
+                aria-label="Refresh available terminals"
-            <SelectContent>
+              >
-              <SelectItem value="integrated">
+                <RefreshCw className={cn('w-3.5 h-3.5', isRefreshing && 'animate-spin')} />
-                <span className="flex items-center gap-2">
+              </Button>
-                  <Terminal className="w-4 h-4" />
+            </div>
-                  Integrated Terminal
+            <p className="text-xs text-muted-foreground">
-                </span>
+              Terminal to use when selecting "Open in Terminal" from the worktree menu
-              </SelectItem>
-              {terminals.map((terminal) => {
-                const TerminalIcon = getTerminalIcon(terminal.id);
-                return (
-                  <SelectItem key={terminal.id} value={terminal.id}>
-                    <span className="flex items-center gap-2">
-                      <TerminalIcon className="w-4 h-4" />
-                      {terminal.name}
-                    </span>
-                  </SelectItem>
-                );
-              })}
-            </SelectContent>
-          </Select>
-          {terminals.length === 0 && !isRefreshing && (
-            <p className="text-xs text-muted-foreground italic">
-              No external terminals detected. Click refresh to re-scan.
             </p>
-          )}
+            <Select
-        </div>
+              value={defaultTerminalId ?? 'integrated'}
-
+              onValueChange={(value) => {
-        {/* Default Open Mode */}
+                setDefaultTerminalId(value === 'integrated' ? null : value);
-        <div className="space-y-3">
+                toast.success(
-          <Label className="text-foreground font-medium">Default Open Mode</Label>
+                  value === 'integrated'
-          <p className="text-xs text-muted-foreground">
+                    ? 'Integrated terminal set as default'
-            How to open the integrated terminal when using "Open in Terminal" from the worktree menu
+                    : 'Default terminal changed'
-          </p>
+                );
-          <Select
+              }}
-            value={openTerminalMode}
+            >
-            onValueChange={(value: 'newTab' | 'split') => {
+              <SelectTrigger className="w-full">
-              setOpenTerminalMode(value);
+                <SelectValue placeholder="Select a terminal" />
-              toast.success(
+              </SelectTrigger>
-                value === 'newTab'
+              <SelectContent>
-                  ? 'New terminals will open in new tabs'
+                <SelectItem value="integrated">
-                  : 'New terminals will split the current tab'
+                  <span className="flex items-center gap-2">
-              );
+                    <Terminal className="w-4 h-4" />
-            }}
+                    Integrated Terminal
-          >
-            <SelectTrigger className="w-full">
-              <SelectValue />
-            </SelectTrigger>
-            <SelectContent>
-              <SelectItem value="newTab">
-                <span className="flex items-center gap-2">
-                  <SquarePlus className="w-4 h-4" />
-                  New Tab
-                </span>
-              </SelectItem>
-              <SelectItem value="split">
-                <span className="flex items-center gap-2">
-                  <SplitSquareHorizontal className="w-4 h-4" />
-                  Split Current Tab
-                </span>
-              </SelectItem>
-            </SelectContent>
-          </Select>
-        </div>
-
-        {/* Font Family */}
-        <div className="space-y-3">
-          <Label className="text-foreground font-medium">Font Family</Label>
-          <Select
-            value={fontFamily || DEFAULT_FONT_VALUE}
-            onValueChange={(value) => {
-              setTerminalFontFamily(value);
-              toast.info('Font family changed', {
-                description: 'Restart terminal for changes to take effect',
-              });
-            }}
-          >
-            <SelectTrigger className="w-full">
-              <SelectValue placeholder="Default (Menlo / Monaco)" />
-            </SelectTrigger>
-            <SelectContent>
-              {TERMINAL_FONT_OPTIONS.map((option) => (
-                <SelectItem key={option.value} value={option.value}>
-                  <span
-                    style={{
-                      fontFamily: option.value === DEFAULT_FONT_VALUE ? undefined : option.value,
-                    }}
-                  >
-                    {option.label}
                   </span>
                 </SelectItem>
-              ))}
+                {terminals.map((terminal) => {
-            </SelectContent>
+                  const TerminalIcon = getTerminalIcon(terminal.id);
-          </Select>
+                  return (
-        </div>
+                    <SelectItem key={terminal.id} value={terminal.id}>
-
+                      <span className="flex items-center gap-2">
-        {/* Default Font Size */}
+                        <TerminalIcon className="w-4 h-4" />
-        <div className="space-y-3">
+                        {terminal.name}
-          <div className="flex items-center justify-between">
+                      </span>
-            <Label className="text-foreground font-medium">Default Font Size</Label>
+                    </SelectItem>
-            <span className="text-sm text-muted-foreground">{defaultFontSize}px</span>
+                  );
+                })}
+              </SelectContent>
+            </Select>
+            {terminals.length === 0 && !isRefreshing && (
+              <p className="text-xs text-muted-foreground italic">
+                No external terminals detected. Click refresh to re-scan.
+              </p>
+            )}
           </div>
-          <Slider
-            value={[defaultFontSize]}
-            min={8}
-            max={32}
-            step={1}
-            onValueChange={([value]) => setTerminalDefaultFontSize(value)}
-            className="flex-1"
-          />
-        </div>
 
-        {/* Line Height */}
+          {/* Default Open Mode */}
-        <div className="space-y-3">
+          <div className="space-y-3">
-          <div className="flex items-center justify-between">
+            <Label className="text-foreground font-medium">Default Open Mode</Label>
-            <Label className="text-foreground font-medium">Line Height</Label>
-            <span className="text-sm text-muted-foreground">{lineHeight.toFixed(1)}</span>
-          </div>
-          <Slider
-            value={[lineHeight]}
-            min={1.0}
-            max={2.0}
-            step={0.1}
-            onValueChange={([value]) => {
-              setTerminalLineHeight(value);
-            }}
-            onValueCommit={() => {
-              toast.info('Line height changed', {
-                description: 'Restart terminal for changes to take effect',
-              });
-            }}
-            className="flex-1"
-          />
-        </div>
-
-        {/* Scrollback Lines */}
-        <div className="space-y-3">
-          <div className="flex items-center justify-between">
-            <Label className="text-foreground font-medium">Scrollback Buffer</Label>
-            <span className="text-sm text-muted-foreground">
-              {(scrollbackLines / 1000).toFixed(0)}k lines
-            </span>
-          </div>
-          <Slider
-            value={[scrollbackLines]}
-            min={1000}
-            max={100000}
-            step={1000}
-            onValueChange={([value]) => setTerminalScrollbackLines(value)}
-            onValueCommit={() => {
-              toast.info('Scrollback changed', {
-                description: 'Restart terminal for changes to take effect',
-              });
-            }}
-            className="flex-1"
-          />
-        </div>
-
-        {/* Default Run Script */}
-        <div className="space-y-3">
-          <Label className="text-foreground font-medium">Default Run Script</Label>
-          <p className="text-xs text-muted-foreground">
-            Command to run automatically when opening a new terminal (e.g., "claude", "codex")
-          </p>
-          <Input
-            value={defaultRunScript}
-            onChange={(e) => setTerminalDefaultRunScript(e.target.value)}
-            placeholder="e.g., claude, codex, npm run dev"
-            className="bg-accent/30 border-border/50"
-          />
-        </div>
-
-        {/* Screen Reader Mode */}
-        <div className="flex items-center justify-between">
-          <div className="space-y-1">
-            <Label className="text-foreground font-medium">Screen Reader Mode</Label>
             <p className="text-xs text-muted-foreground">
-              Enable accessibility mode for screen readers
+              How to open the integrated terminal when using "Open in Terminal" from the worktree
+              menu
             </p>
+            <Select
+              value={openTerminalMode}
+              onValueChange={(value: 'newTab' | 'split') => {
+                setOpenTerminalMode(value);
+                toast.success(
+                  value === 'newTab'
+                    ? 'New terminals will open in new tabs'
+                    : 'New terminals will split the current tab'
+                );
+              }}
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="newTab">
+                  <span className="flex items-center gap-2">
+                    <SquarePlus className="w-4 h-4" />
+                    New Tab
+                  </span>
+                </SelectItem>
+                <SelectItem value="split">
+                  <span className="flex items-center gap-2">
+                    <SplitSquareHorizontal className="w-4 h-4" />
+                    Split Current Tab
+                  </span>
+                </SelectItem>
+              </SelectContent>
+            </Select>
           </div>
-          <Switch
+
-            checked={screenReaderMode}
+          {/* Font Family */}
-            onCheckedChange={(checked) => {
+          <div className="space-y-3">
-              setTerminalScreenReaderMode(checked);
+            <Label className="text-foreground font-medium">Font Family</Label>
-              toast.success(
+            <Select
-                checked ? 'Screen reader mode enabled' : 'Screen reader mode disabled',
+              value={fontFamily || DEFAULT_FONT_VALUE}
-                {
+              onValueChange={(value) => {
+                setTerminalFontFamily(value);
+                toast.info('Font family changed', {
                   description: 'Restart terminal for changes to take effect',
-                }
+                });
-              );
+              }}
-            }}
+            >
-          />
+              <SelectTrigger className="w-full">
+                <SelectValue placeholder="Default (Menlo / Monaco)" />
+              </SelectTrigger>
+              <SelectContent>
+                {TERMINAL_FONT_OPTIONS.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    <span
+                      style={{
+                        fontFamily: option.value === DEFAULT_FONT_VALUE ? undefined : option.value,
+                      }}
+                    >
+                      {option.label}
+                    </span>
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          {/* Default Font Size */}
+          <div className="space-y-3">
+            <div className="flex items-center justify-between">
+              <Label className="text-foreground font-medium">Default Font Size</Label>
+              <span className="text-sm text-muted-foreground">{defaultFontSize}px</span>
+            </div>
+            <Slider
+              value={[defaultFontSize]}
+              min={8}
+              max={32}
+              step={1}
+              onValueChange={([value]) => setTerminalDefaultFontSize(value)}
+              className="flex-1"
+            />
+          </div>
+
+          {/* Line Height */}
+          <div className="space-y-3">
+            <div className="flex items-center justify-between">
+              <Label className="text-foreground font-medium">Line Height</Label>
+              <span className="text-sm text-muted-foreground">{lineHeight.toFixed(1)}</span>
+            </div>
+            <Slider
+              value={[lineHeight]}
+              min={1.0}
+              max={2.0}
+              step={0.1}
+              onValueChange={([value]) => {
+                setTerminalLineHeight(value);
+              }}
+              onValueCommit={() => {
+                toast.info('Line height changed', {
+                  description: 'Restart terminal for changes to take effect',
+                });
+              }}
+              className="flex-1"
+            />
+          </div>
+
+          {/* Scrollback Lines */}
+          <div className="space-y-3">
+            <div className="flex items-center justify-between">
+              <Label className="text-foreground font-medium">Scrollback Buffer</Label>
+              <span className="text-sm text-muted-foreground">
+                {(scrollbackLines / 1000).toFixed(0)}k lines
+              </span>
+            </div>
+            <Slider
+              value={[scrollbackLines]}
+              min={1000}
+              max={100000}
+              step={1000}
+              onValueChange={([value]) => setTerminalScrollbackLines(value)}
+              onValueCommit={() => {
+                toast.info('Scrollback changed', {
+                  description: 'Restart terminal for changes to take effect',
+                });
+              }}
+              className="flex-1"
+            />
+          </div>
+
+          {/* Default Run Script */}
+          <div className="space-y-3">
+            <Label className="text-foreground font-medium">Default Run Script</Label>
+            <p className="text-xs text-muted-foreground">
+              Command to run automatically when opening a new terminal (e.g., "claude", "codex")
+            </p>
+            <Input
+              value={defaultRunScript}
+              onChange={(e) => setTerminalDefaultRunScript(e.target.value)}
+              placeholder="e.g., claude, codex, npm run dev"
+              className="bg-accent/30 border-border/50"
+            />
+          </div>
+
+          {/* Screen Reader Mode */}
+          <div className="flex items-center justify-between">
+            <div className="space-y-1">
+              <Label className="text-foreground font-medium">Screen Reader Mode</Label>
+              <p className="text-xs text-muted-foreground">
+                Enable accessibility mode for screen readers
+              </p>
+            </div>
+            <Switch
+              checked={screenReaderMode}
+              onCheckedChange={(checked) => {
+                setTerminalScreenReaderMode(checked);
+                toast.success(
+                  checked ? 'Screen reader mode enabled' : 'Screen reader mode disabled',
+                  {
+                    description: 'Restart terminal for changes to take effect',
+                  }
+                );
+              }}
+            />
+          </div>
         </div>
       </div>
+
+      <TerminalConfigSection />
     </div>
   );
 }

apps/ui/src/electron/constants.ts

@@ -0,0 +1,47 @@
+/**
+ * Electron main process constants
+ *
+ * Centralized configuration for window sizing, ports, and file names.
+ */
+
+// ============================================
+// Window sizing constants for kanban layout
+// ============================================
+// Calculation: 4 columns × 280px + 3 gaps × 20px + 40px padding = 1220px board content
+// With sidebar expanded (288px): 1220 + 288 = 1508px
+// Minimum window dimensions - reduced to allow smaller windows since kanban now supports horizontal scrolling
+export const MIN_WIDTH_COLLAPSED = 600; // Reduced - horizontal scrolling handles overflow
+export const MIN_HEIGHT = 500; // Reduced to allow more flexibility
+export const DEFAULT_WIDTH = 1600;
+export const DEFAULT_HEIGHT = 950;
+
+// ============================================
+// Port defaults
+// ============================================
+// Default ports (can be overridden via env) - will be dynamically assigned if these are in use
+// When launched via root init.mjs we pass:
+// - PORT (backend)
+// - TEST_PORT (vite dev server / static)
+// Guard against NaN from non-numeric environment variables
+const parsedServerPort = Number.parseInt(process.env.PORT ?? '', 10);
+const parsedStaticPort = Number.parseInt(process.env.TEST_PORT ?? '', 10);
+export const DEFAULT_SERVER_PORT = Number.isFinite(parsedServerPort) ? parsedServerPort : 3008;
+export const DEFAULT_STATIC_PORT = Number.isFinite(parsedStaticPort) ? parsedStaticPort : 3007;
+
+// ============================================
+// File names for userData storage
+// ============================================
+export const API_KEY_FILENAME = '.api-key';
+export const WINDOW_BOUNDS_FILENAME = 'window-bounds.json';
+
+// ============================================
+// Window bounds interface
+// ============================================
+// Matches @automaker/types WindowBounds
+export interface WindowBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  isMaximized: boolean;
+}

apps/ui/src/electron/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Electron main process modules
+ *
+ * Re-exports for convenient importing.
+ */
+
+// Constants and types
+export * from './constants';
+export { state } from './state';
+
+// Utilities
+export { isPortAvailable, findAvailablePort } from './utils/port-manager';
+export { getIconPath } from './utils/icon-manager';
+
+// Security
+export { ensureApiKey, getApiKey } from './security/api-key-manager';
+
+// Windows
+export {
+  loadWindowBounds,
+  saveWindowBounds,
+  validateBounds,
+  scheduleSaveWindowBounds,
+} from './windows/window-bounds';
+export { createWindow } from './windows/main-window';
+
+// Server
+export { startStaticServer, stopStaticServer } from './server/static-server';
+export { startServer, waitForServer, stopServer } from './server/backend-server';
+
+// IPC
+export { IPC_CHANNELS, registerAllHandlers } from './ipc';

apps/ui/src/electron/ipc/app-handlers.ts

@@ -0,0 +1,37 @@
+/**
+ * App IPC handlers
+ *
+ * Handles app-related operations like getting paths, version info, and quitting.
+ */
+
+import { ipcMain, app } from 'electron';
+import { createLogger } from '@automaker/utils/logger';
+import { IPC_CHANNELS } from './channels';
+
+const logger = createLogger('AppHandlers');
+
+/**
+ * Register app IPC handlers
+ */
+export function registerAppHandlers(): void {
+  // Get app path
+  ipcMain.handle(IPC_CHANNELS.APP.GET_PATH, async (_, name: Parameters<typeof app.getPath>[0]) => {
+    return app.getPath(name);
+  });
+
+  // Get app version
+  ipcMain.handle(IPC_CHANNELS.APP.GET_VERSION, async () => {
+    return app.getVersion();
+  });
+
+  // Check if app is packaged
+  ipcMain.handle(IPC_CHANNELS.APP.IS_PACKAGED, async () => {
+    return app.isPackaged;
+  });
+
+  // Quit the application
+  ipcMain.handle(IPC_CHANNELS.APP.QUIT, () => {
+    logger.info('Quitting application via IPC request');
+    app.quit();
+  });
+}

apps/ui/src/electron/ipc/auth-handlers.ts

@@ -0,0 +1,34 @@
+/**
+ * Auth IPC handlers
+ *
+ * Handles authentication-related operations.
+ */
+
+import { ipcMain } from 'electron';
+import { IPC_CHANNELS } from './channels';
+import { state } from '../state';
+
+/**
+ * Register auth IPC handlers
+ */
+export function registerAuthHandlers(): void {
+  // Get API key for authentication
+  // Returns null in external server mode to trigger session-based auth
+  // Only returns API key to the main window to prevent leaking to untrusted senders
+  ipcMain.handle(IPC_CHANNELS.AUTH.GET_API_KEY, (event) => {
+    // Validate sender is the main window
+    if (event.sender !== state.mainWindow?.webContents) {
+      return null;
+    }
+    if (state.isExternalServerMode) {
+      return null;
+    }
+    return state.apiKey;
+  });
+
+  // Check if running in external server mode (Docker API)
+  // Used by renderer to determine auth flow
+  ipcMain.handle(IPC_CHANNELS.AUTH.IS_EXTERNAL_SERVER_MODE, () => {
+    return state.isExternalServerMode;
+  });
+}

apps/ui/src/electron/ipc/channels.ts

@@ -0,0 +1,36 @@
+/**
+ * IPC channel constants
+ *
+ * Single source of truth for all IPC channel names.
+ * Used by both main process handlers and preload script.
+ */
+
+export const IPC_CHANNELS = {
+  DIALOG: {
+    OPEN_DIRECTORY: 'dialog:openDirectory',
+    OPEN_FILE: 'dialog:openFile',
+    SAVE_FILE: 'dialog:saveFile',
+  },
+  SHELL: {
+    OPEN_EXTERNAL: 'shell:openExternal',
+    OPEN_PATH: 'shell:openPath',
+    OPEN_IN_EDITOR: 'shell:openInEditor',
+  },
+  APP: {
+    GET_PATH: 'app:getPath',
+    GET_VERSION: 'app:getVersion',
+    IS_PACKAGED: 'app:isPackaged',
+    QUIT: 'app:quit',
+  },
+  AUTH: {
+    GET_API_KEY: 'auth:getApiKey',
+    IS_EXTERNAL_SERVER_MODE: 'auth:isExternalServerMode',
+  },
+  WINDOW: {
+    UPDATE_MIN_WIDTH: 'window:updateMinWidth',
+  },
+  SERVER: {
+    GET_URL: 'server:getUrl',
+  },
+  PING: 'ping',
+} as const;

apps/ui/src/electron/ipc/dialog-handlers.ts

@@ -0,0 +1,72 @@
+/**
+ * Dialog IPC handlers
+ *
+ * Handles native file dialog operations.
+ */
+
+import { ipcMain, dialog } from 'electron';
+import { isPathAllowed, getAllowedRootDirectory } from '@automaker/platform';
+import { IPC_CHANNELS } from './channels';
+import { state } from '../state';
+
+/**
+ * Register dialog IPC handlers
+ */
+export function registerDialogHandlers(): void {
+  // Open directory dialog
+  ipcMain.handle(IPC_CHANNELS.DIALOG.OPEN_DIRECTORY, async () => {
+    if (!state.mainWindow) {
+      return { canceled: true, filePaths: [] };
+    }
+    const result = await dialog.showOpenDialog(state.mainWindow, {
+      properties: ['openDirectory', 'createDirectory'],
+    });
+
+    // Validate selected path against ALLOWED_ROOT_DIRECTORY if configured
+    if (!result.canceled && result.filePaths.length > 0) {
+      const selectedPath = result.filePaths[0];
+      if (!isPathAllowed(selectedPath)) {
+        const allowedRoot = getAllowedRootDirectory();
+        const errorMessage = allowedRoot
+          ? `The selected directory is not allowed. Please select a directory within: ${allowedRoot}`
+          : 'The selected directory is not allowed.';
+
+        dialog.showErrorBox('Directory Not Allowed', errorMessage);
+
+        return { canceled: true, filePaths: [] };
+      }
+    }
+
+    return result;
+  });
+
+  // Open file dialog
+  // Filter properties to maintain file-only intent and prevent renderer from requesting directories
+  ipcMain.handle(
+    IPC_CHANNELS.DIALOG.OPEN_FILE,
+    async (_, options: Record<string, unknown> = {}) => {
+      if (!state.mainWindow) {
+        return { canceled: true, filePaths: [] };
+      }
+      // Ensure openFile is always present and filter out directory-related properties
+      const inputProperties = (options.properties as string[]) ?? [];
+      const properties = ['openFile', ...inputProperties].filter(
+        (p) => p !== 'openDirectory' && p !== 'createDirectory'
+      );
+      const result = await dialog.showOpenDialog(state.mainWindow, {
+        ...options,
+        properties: properties as Electron.OpenDialogOptions['properties'],
+      });
+      return result;
+    }
+  );
+
+  // Save file dialog
+  ipcMain.handle(IPC_CHANNELS.DIALOG.SAVE_FILE, async (_, options = {}) => {
+    if (!state.mainWindow) {
+      return { canceled: true, filePath: undefined };
+    }
+    const result = await dialog.showSaveDialog(state.mainWindow, options);
+    return result;
+  });
+}

apps/ui/src/electron/ipc/index.ts

@@ -0,0 +1,26 @@
+/**
+ * IPC handlers aggregator
+ *
+ * Registers all IPC handlers in one place.
+ */
+
+import { registerDialogHandlers } from './dialog-handlers';
+import { registerShellHandlers } from './shell-handlers';
+import { registerAppHandlers } from './app-handlers';
+import { registerAuthHandlers } from './auth-handlers';
+import { registerWindowHandlers } from './window-handlers';
+import { registerServerHandlers } from './server-handlers';
+
+export { IPC_CHANNELS } from './channels';
+
+/**
+ * Register all IPC handlers
+ */
+export function registerAllHandlers(): void {
+  registerDialogHandlers();
+  registerShellHandlers();
+  registerAppHandlers();
+  registerAuthHandlers();
+  registerWindowHandlers();
+  registerServerHandlers();
+}

apps/ui/src/electron/ipc/server-handlers.ts

@@ -0,0 +1,24 @@
+/**
+ * Server IPC handlers
+ *
+ * Handles server-related operations.
+ */
+
+import { ipcMain } from 'electron';
+import { IPC_CHANNELS } from './channels';
+import { state } from '../state';
+
+/**
+ * Register server IPC handlers
+ */
+export function registerServerHandlers(): void {
+  // Get server URL for HTTP client
+  ipcMain.handle(IPC_CHANNELS.SERVER.GET_URL, async () => {
+    return `http://localhost:${state.serverPort}`;
+  });
+
+  // Ping - for connection check
+  ipcMain.handle(IPC_CHANNELS.PING, async () => {
+    return 'pong';
+  });
+}

apps/ui/src/electron/ipc/shell-handlers.ts

@@ -0,0 +1,61 @@
+/**
+ * Shell IPC handlers
+ *
+ * Handles shell operations like opening external links and files.
+ */
+
+import { ipcMain, shell } from 'electron';
+import { IPC_CHANNELS } from './channels';
+
+/**
+ * Register shell IPC handlers
+ */
+export function registerShellHandlers(): void {
+  // Open external URL
+  ipcMain.handle(IPC_CHANNELS.SHELL.OPEN_EXTERNAL, async (_, url: string) => {
+    try {
+      await shell.openExternal(url);
+      return { success: true };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  });
+
+  // Open file path
+  ipcMain.handle(IPC_CHANNELS.SHELL.OPEN_PATH, async (_, filePath: string) => {
+    try {
+      await shell.openPath(filePath);
+      return { success: true };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  });
+
+  // Open file in editor (VS Code, etc.) with optional line/column
+  ipcMain.handle(
+    IPC_CHANNELS.SHELL.OPEN_IN_EDITOR,
+    async (_, filePath: string, line?: number, column?: number) => {
+      try {
+        // Build VS Code URL scheme: vscode://file/path:line:column
+        // This works on all platforms where VS Code is installed
+        // URL encode the path to handle special characters (spaces, brackets, etc.)
+        // Handle both Unix (/) and Windows (\) path separators
+        const normalizedPath = filePath.replace(/\\/g, '/');
+        const segments = normalizedPath.split('/').map(encodeURIComponent);
+        const encodedPath = segments.join('/');
+        // VS Code URL format requires a leading slash after 'file'
+        let url = `vscode://file/${encodedPath}`;
+        if (line !== undefined && line > 0) {
+          url += `:${line}`;
+          if (column !== undefined && column > 0) {
+            url += `:${column}`;
+          }
+        }
+        await shell.openExternal(url);
+        return { success: true };
+      } catch (error) {
+        return { success: false, error: (error as Error).message };
+      }
+    }
+  );
+}

apps/ui/src/electron/ipc/window-handlers.ts

@@ -0,0 +1,24 @@
+/**
+ * Window IPC handlers
+ *
+ * Handles window management operations.
+ */
+
+import { ipcMain } from 'electron';
+import { IPC_CHANNELS } from './channels';
+import { MIN_WIDTH_COLLAPSED, MIN_HEIGHT } from '../constants';
+import { state } from '../state';
+
+/**
+ * Register window IPC handlers
+ */
+export function registerWindowHandlers(): void {
+  // Update minimum width based on sidebar state
+  // Now uses a fixed small minimum since horizontal scrolling handles overflow
+  ipcMain.handle(IPC_CHANNELS.WINDOW.UPDATE_MIN_WIDTH, (_, _sidebarExpanded: boolean) => {
+    if (!state.mainWindow || state.mainWindow.isDestroyed()) return;
+
+    // Always use the smaller minimum width - horizontal scrolling handles any overflow
+    state.mainWindow.setMinimumSize(MIN_WIDTH_COLLAPSED, MIN_HEIGHT);
+  });
+}

apps/ui/src/electron/security/api-key-manager.ts

@@ -0,0 +1,58 @@
+/**
+ * API key management
+ *
+ * Handles generation, storage, and retrieval of the API key for CSRF protection.
+ * Uses centralized electronUserData methods for path validation.
+ */
+
+import crypto from 'crypto';
+import {
+  electronUserDataExists,
+  electronUserDataReadFileSync,
+  electronUserDataWriteFileSync,
+} from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+import { API_KEY_FILENAME } from '../constants';
+import { state } from '../state';
+
+const logger = createLogger('ApiKeyManager');
+
+/**
+ * Ensure an API key exists - load from file or generate new one.
+ * This key is passed to the server for CSRF protection.
+ * Uses centralized electronUserData methods for path validation.
+ */
+export function ensureApiKey(): string {
+  try {
+    if (electronUserDataExists(API_KEY_FILENAME)) {
+      const key = electronUserDataReadFileSync(API_KEY_FILENAME).trim();
+      if (key) {
+        state.apiKey = key;
+        logger.info('Loaded existing API key');
+        return state.apiKey;
+      }
+    }
+  } catch (error) {
+    logger.warn('Error reading API key:', error);
+  }
+
+  // Generate new key
+  state.apiKey = crypto.randomUUID();
+  try {
+    electronUserDataWriteFileSync(API_KEY_FILENAME, state.apiKey, {
+      encoding: 'utf-8',
+      mode: 0o600,
+    });
+    logger.info('Generated new API key');
+  } catch (error) {
+    logger.error('Failed to save API key:', error);
+  }
+  return state.apiKey;
+}
+
+/**
+ * Get the current API key
+ */
+export function getApiKey(): string | null {
+  return state.apiKey;
+}

apps/ui/src/electron/server/backend-server.ts

@@ -0,0 +1,230 @@
+/**
+ * Backend server management
+ *
+ * Handles starting, stopping, and monitoring the Express backend server.
+ * Uses centralized methods for path validation.
+ */
+
+import path from 'path';
+import http from 'http';
+import { spawn, execSync } from 'child_process';
+import { app } from 'electron';
+import {
+  findNodeExecutable,
+  buildEnhancedPath,
+  electronAppExists,
+  systemPathExists,
+} from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+import { state } from '../state';
+
+const logger = createLogger('BackendServer');
+const serverLogger = createLogger('Server');
+
+/**
+ * Start the backend server
+ * Uses centralized methods for path validation.
+ */
+export async function startServer(): Promise<void> {
+  const isDev = !app.isPackaged;
+
+  // Find Node.js executable (handles desktop launcher scenarios)
+  const nodeResult = findNodeExecutable({
+    skipSearch: isDev,
+    logger: (msg: string) => logger.info(msg),
+  });
+  const command = nodeResult.nodePath;
+
+  // Validate that the found Node executable actually exists
+  // systemPathExists is used because node-finder returns system paths
+  if (command !== 'node') {
+    let exists: boolean;
+    try {
+      exists = systemPathExists(command);
+    } catch (error) {
+      const originalError = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to verify Node.js executable at: ${command} (source: ${nodeResult.source}). Reason: ${originalError}`
+      );
+    }
+    if (!exists) {
+      throw new Error(`Node.js executable not found at: ${command} (source: ${nodeResult.source})`);
+    }
+  }
+
+  let args: string[];
+  let serverPath: string;
+
+  // __dirname is apps/ui/dist-electron (Vite bundles all into single file)
+  if (isDev) {
+    serverPath = path.join(__dirname, '../../server/src/index.ts');
+
+    const serverNodeModules = path.join(__dirname, '../../server/node_modules/tsx');
+    const rootNodeModules = path.join(__dirname, '../../../node_modules/tsx');
+
+    let tsxCliPath: string;
+    // Check for tsx in app bundle paths, fallback to require.resolve
+    const serverTsxPath = path.join(serverNodeModules, 'dist/cli.mjs');
+    const rootTsxPath = path.join(rootNodeModules, 'dist/cli.mjs');
+
+    try {
+      if (electronAppExists(serverTsxPath)) {
+        tsxCliPath = serverTsxPath;
+      } else if (electronAppExists(rootTsxPath)) {
+        tsxCliPath = rootTsxPath;
+      } else {
+        // Fallback to require.resolve
+        tsxCliPath = require.resolve('tsx/cli.mjs', {
+          paths: [path.join(__dirname, '../../server')],
+        });
+      }
+    } catch {
+      // electronAppExists threw or require.resolve failed
+      try {
+        tsxCliPath = require.resolve('tsx/cli.mjs', {
+          paths: [path.join(__dirname, '../../server')],
+        });
+      } catch {
+        throw new Error("Could not find tsx. Please run 'npm install' in the server directory.");
+      }
+    }
+
+    args = [tsxCliPath, 'watch', serverPath];
+  } else {
+    serverPath = path.join(process.resourcesPath, 'server', 'index.js');
+    args = [serverPath];
+
+    if (!electronAppExists(serverPath)) {
+      throw new Error(`Server not found at: ${serverPath}`);
+    }
+  }
+
+  const serverNodeModules = app.isPackaged
+    ? path.join(process.resourcesPath, 'server', 'node_modules')
+    : path.join(__dirname, '../../server/node_modules');
+
+  // Server root directory - where .env file is located
+  // In dev: apps/server (not apps/server/src)
+  // In production: resources/server
+  const serverRoot = app.isPackaged
+    ? path.join(process.resourcesPath, 'server')
+    : path.join(__dirname, '../../server');
+
+  // IMPORTANT: Use shared data directory (not Electron's user data directory)
+  // This ensures Electron and web mode share the same settings/projects
+  // In dev: project root/data (navigate from __dirname which is apps/ui/dist-electron)
+  // In production: same as Electron user data (for app isolation)
+  const dataDir = app.isPackaged
+    ? app.getPath('userData')
+    : path.join(__dirname, '../../..', 'data');
+  logger.info(
+    `[DATA_DIR] app.isPackaged=${app.isPackaged}, __dirname=${__dirname}, dataDir=${dataDir}`
+  );
+
+  // Build enhanced PATH that includes Node.js directory (cross-platform)
+  const enhancedPath = buildEnhancedPath(command, process.env.PATH || '');
+  if (enhancedPath !== process.env.PATH) {
+    logger.info('Enhanced PATH with Node directory:', path.dirname(command));
+  }
+
+  const env = {
+    ...process.env,
+    PATH: enhancedPath,
+    PORT: state.serverPort.toString(),
+    DATA_DIR: dataDir,
+    NODE_PATH: serverNodeModules,
+    // Pass API key to server for CSRF protection
+    AUTOMAKER_API_KEY: state.apiKey!,
+    // Only set ALLOWED_ROOT_DIRECTORY if explicitly provided in environment
+    // If not set, server will allow access to all paths
+    ...(process.env.ALLOWED_ROOT_DIRECTORY && {
+      ALLOWED_ROOT_DIRECTORY: process.env.ALLOWED_ROOT_DIRECTORY,
+    }),
+  };
+
+  logger.info('Server will use port', state.serverPort);
+  logger.info('[DATA_DIR_SPAWN] env.DATA_DIR=', env.DATA_DIR);
+
+  logger.info('Starting backend server...');
+  logger.info('Server path:', serverPath);
+  logger.info('Server root (cwd):', serverRoot);
+  logger.info('NODE_PATH:', serverNodeModules);
+
+  state.serverProcess = spawn(command, args, {
+    cwd: serverRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  state.serverProcess.stdout?.on('data', (data) => {
+    serverLogger.info(data.toString().trim());
+  });
+
+  state.serverProcess.stderr?.on('data', (data) => {
+    serverLogger.error(data.toString().trim());
+  });
+
+  state.serverProcess.on('close', (code) => {
+    serverLogger.info('Process exited with code', code);
+    state.serverProcess = null;
+  });
+
+  state.serverProcess.on('error', (err) => {
+    serverLogger.error('Failed to start server process:', err);
+    state.serverProcess = null;
+  });
+
+  await waitForServer();
+}
+
+/**
+ * Wait for server to be available
+ */
+export async function waitForServer(maxAttempts = 30): Promise<void> {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const req = http.get(`http://localhost:${state.serverPort}/api/health`, (res) => {
+          if (res.statusCode === 200) {
+            resolve();
+          } else {
+            reject(new Error(`Status: ${res.statusCode}`));
+          }
+        });
+        req.on('error', reject);
+        req.setTimeout(1000, () => {
+          req.destroy();
+          reject(new Error('Timeout'));
+        });
+      });
+      logger.info('Server is ready');
+      return;
+    } catch {
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  }
+
+  throw new Error('Server failed to start');
+}
+
+/**
+ * Stop the backend server if running
+ */
+export function stopServer(): void {
+  if (state.serverProcess && state.serverProcess.pid) {
+    logger.info('Stopping server...');
+    if (process.platform === 'win32') {
+      try {
+        // Windows: use taskkill with /t to kill entire process tree
+        // This prevents orphaned node processes when closing the app
+        // Using execSync to ensure process is killed before app exits
+        execSync(`taskkill /f /t /pid ${state.serverProcess.pid}`, { stdio: 'ignore' });
+      } catch (error) {
+        logger.error('Failed to kill server process:', (error as Error).message);
+      }
+    } else {
+      state.serverProcess.kill('SIGTERM');
+    }
+    state.serverProcess = null;
+  }
+}

apps/ui/src/electron/server/static-server.ts

@@ -0,0 +1,101 @@
+/**
+ * Static file server for production builds
+ *
+ * Serves the built frontend files in production mode.
+ * Uses centralized electronApp methods for serving static files from app bundle.
+ */
+
+import path from 'path';
+import http from 'http';
+import { electronAppExists, electronAppStat, electronAppReadFile } from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+import { state } from '../state';
+
+const logger = createLogger('StaticServer');
+
+/**
+ * MIME type mapping for static files
+ */
+const CONTENT_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+};
+
+/**
+ * Start static file server for production builds
+ * Uses centralized electronApp methods for serving static files from app bundle.
+ */
+export async function startStaticServer(): Promise<void> {
+  // __dirname is apps/ui/dist-electron (Vite bundles all into single file)
+  const staticPath = path.join(__dirname, '../dist');
+
+  state.staticServer = http.createServer((request, response) => {
+    let filePath = path.join(staticPath, request.url?.split('?')[0] || '/');
+
+    if (filePath.endsWith('/')) {
+      filePath = path.join(filePath, 'index.html');
+    } else if (!path.extname(filePath)) {
+      // For client-side routing, serve index.html for paths without extensions
+      const possibleFile = filePath + '.html';
+      try {
+        if (!electronAppExists(filePath) && !electronAppExists(possibleFile)) {
+          filePath = path.join(staticPath, 'index.html');
+        } else if (electronAppExists(possibleFile)) {
+          filePath = possibleFile;
+        }
+      } catch {
+        filePath = path.join(staticPath, 'index.html');
+      }
+    }
+
+    electronAppStat(filePath, (err, stats) => {
+      if (err || !stats?.isFile()) {
+        filePath = path.join(staticPath, 'index.html');
+      }
+
+      electronAppReadFile(filePath, (error, content) => {
+        if (error || !content) {
+          response.writeHead(500);
+          response.end('Server Error');
+          return;
+        }
+
+        const ext = path.extname(filePath);
+        response.writeHead(200, {
+          'Content-Type': CONTENT_TYPES[ext] || 'application/octet-stream',
+        });
+        response.end(content);
+      });
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    state.staticServer!.listen(state.staticPort, () => {
+      logger.info('Static server running at http://localhost:' + state.staticPort);
+      resolve();
+    });
+    state.staticServer!.on('error', reject);
+  });
+}
+
+/**
+ * Stop the static server if running
+ */
+export function stopStaticServer(): void {
+  if (state.staticServer) {
+    logger.info('Stopping static server...');
+    state.staticServer.close();
+    state.staticServer = null;
+  }
+}

apps/ui/src/electron/state.ts

@@ -0,0 +1,33 @@
+/**
+ * Electron main process shared state
+ *
+ * Centralized state container to avoid circular dependencies.
+ * All modules access shared state through this object.
+ */
+
+import { BrowserWindow } from 'electron';
+import { ChildProcess } from 'child_process';
+import { Server } from 'http';
+import { DEFAULT_SERVER_PORT, DEFAULT_STATIC_PORT } from './constants';
+
+export interface ElectronState {
+  mainWindow: BrowserWindow | null;
+  serverProcess: ChildProcess | null;
+  staticServer: Server | null;
+  serverPort: number;
+  staticPort: number;
+  apiKey: string | null;
+  isExternalServerMode: boolean;
+  saveWindowBoundsTimeout: ReturnType<typeof setTimeout> | null;
+}
+
+export const state: ElectronState = {
+  mainWindow: null,
+  serverProcess: null,
+  staticServer: null,
+  serverPort: DEFAULT_SERVER_PORT,
+  staticPort: DEFAULT_STATIC_PORT,
+  apiKey: null,
+  isExternalServerMode: false,
+  saveWindowBoundsTimeout: null,
+};

apps/ui/src/electron/utils/icon-manager.ts

@@ -0,0 +1,46 @@
+/**
+ * Icon management utilities
+ *
+ * Functions for getting the application icon path.
+ */
+
+import path from 'path';
+import { app } from 'electron';
+import { electronAppExists } from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+
+const logger = createLogger('IconManager');
+
+/**
+ * Get icon path - works in both dev and production, cross-platform
+ * Uses centralized electronApp methods for path validation.
+ */
+export function getIconPath(): string | null {
+  const isDev = !app.isPackaged;
+
+  let iconFile: string;
+  if (process.platform === 'win32') {
+    iconFile = 'icon.ico';
+  } else if (process.platform === 'darwin') {
+    iconFile = 'logo_larger.png';
+  } else {
+    iconFile = 'logo_larger.png';
+  }
+
+  // __dirname is apps/ui/dist-electron (Vite bundles all into single file)
+  const iconPath = isDev
+    ? path.join(__dirname, '../public', iconFile)
+    : path.join(__dirname, '../dist/public', iconFile);
+
+  try {
+    if (!electronAppExists(iconPath)) {
+      logger.warn('Icon not found at:', iconPath);
+      return null;
+    }
+  } catch (error) {
+    logger.warn('Icon check failed:', iconPath, error);
+    return null;
+  }
+
+  return iconPath;
+}

apps/ui/src/electron/utils/port-manager.ts

@@ -0,0 +1,42 @@
+/**
+ * Port management utilities
+ *
+ * Functions for checking port availability and finding open ports.
+ * No Electron dependencies - pure utility module.
+ */
+
+import net from 'net';
+
+/**
+ * Check if a port is available
+ */
+export function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => {
+      resolve(false);
+    });
+    server.once('listening', () => {
+      server.close(() => {
+        resolve(true);
+      });
+    });
+    // Use Node's default binding semantics (matches most dev servers)
+    // This avoids false-positives when a port is taken on IPv6/dual-stack.
+    server.listen(port);
+  });
+}
+
+/**
+ * Find an available port starting from the preferred port
+ * Tries up to 100 ports in sequence
+ */
+export async function findAvailablePort(preferredPort: number): Promise<number> {
+  for (let offset = 0; offset < 100; offset++) {
+    const port = preferredPort + offset;
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`Could not find an available port starting from ${preferredPort}`);
+}

apps/ui/src/electron/windows/main-window.ts

@@ -0,0 +1,116 @@
+/**
+ * Main window creation and lifecycle
+ *
+ * Handles creating the main BrowserWindow and its event handlers.
+ */
+
+import path from 'path';
+import { app, BrowserWindow, shell } from 'electron';
+import { createLogger } from '@automaker/utils/logger';
+import { MIN_WIDTH_COLLAPSED, MIN_HEIGHT, DEFAULT_WIDTH, DEFAULT_HEIGHT } from '../constants';
+import { state } from '../state';
+import { getIconPath } from '../utils/icon-manager';
+import {
+  loadWindowBounds,
+  saveWindowBounds,
+  validateBounds,
+  scheduleSaveWindowBounds,
+} from './window-bounds';
+
+const logger = createLogger('MainWindow');
+
+// Development environment
+const VITE_DEV_SERVER_URL = process.env.VITE_DEV_SERVER_URL;
+
+/**
+ * Create the main window
+ */
+export function createWindow(): void {
+  const isDev = !app.isPackaged;
+  const iconPath = getIconPath();
+
+  // Load and validate saved window bounds
+  const savedBounds = loadWindowBounds();
+  const validBounds = savedBounds ? validateBounds(savedBounds) : null;
+
+  const windowOptions: Electron.BrowserWindowConstructorOptions = {
+    width: validBounds?.width ?? DEFAULT_WIDTH,
+    height: validBounds?.height ?? DEFAULT_HEIGHT,
+    x: validBounds?.x,
+    y: validBounds?.y,
+    minWidth: MIN_WIDTH_COLLAPSED, // Small minimum - horizontal scrolling handles overflow
+    minHeight: MIN_HEIGHT,
+    webPreferences: {
+      // __dirname is apps/ui/dist-electron (Vite bundles all into single file)
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+    // titleBarStyle is macOS-only; use hiddenInset for native look on macOS
+    ...(process.platform === 'darwin' && { titleBarStyle: 'hiddenInset' as const }),
+    backgroundColor: '#0a0a0a',
+  };
+
+  if (iconPath) {
+    windowOptions.icon = iconPath;
+  }
+
+  state.mainWindow = new BrowserWindow(windowOptions);
+
+  // Restore maximized state if previously maximized
+  if (validBounds?.isMaximized) {
+    state.mainWindow.maximize();
+  }
+
+  // Load Vite dev server in development or static server in production
+  if (VITE_DEV_SERVER_URL) {
+    state.mainWindow.loadURL(VITE_DEV_SERVER_URL);
+  } else if (isDev) {
+    // Fallback for dev without Vite server URL
+    state.mainWindow.loadURL(`http://localhost:${state.staticPort}`);
+  } else {
+    state.mainWindow.loadURL(`http://localhost:${state.staticPort}`);
+  }
+
+  if (isDev && process.env.OPEN_DEVTOOLS === 'true') {
+    state.mainWindow.webContents.openDevTools();
+  }
+
+  // Save window bounds on close, resize, and move
+  state.mainWindow.on('close', () => {
+    // Save immediately before closing (not debounced)
+    if (state.mainWindow && !state.mainWindow.isDestroyed()) {
+      const isMaximized = state.mainWindow.isMaximized();
+      const bounds = isMaximized
+        ? state.mainWindow.getNormalBounds()
+        : state.mainWindow.getBounds();
+
+      saveWindowBounds({
+        x: bounds.x,
+        y: bounds.y,
+        width: bounds.width,
+        height: bounds.height,
+        isMaximized,
+      });
+    }
+  });
+
+  state.mainWindow.on('closed', () => {
+    state.mainWindow = null;
+  });
+
+  state.mainWindow.on('resized', () => {
+    scheduleSaveWindowBounds();
+  });
+
+  state.mainWindow.on('moved', () => {
+    scheduleSaveWindowBounds();
+  });
+
+  state.mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+    shell.openExternal(url);
+    return { action: 'deny' };
+  });
+
+  logger.info('Main window created');
+}

apps/ui/src/electron/windows/window-bounds.ts

@@ -0,0 +1,130 @@
+/**
+ * Window bounds management
+ *
+ * Functions for loading, saving, and validating window bounds.
+ * Uses centralized electronUserData methods for path validation.
+ */
+
+import { screen } from 'electron';
+import {
+  electronUserDataExists,
+  electronUserDataReadFileSync,
+  electronUserDataWriteFileSync,
+} from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+import {
+  WindowBounds,
+  WINDOW_BOUNDS_FILENAME,
+  MIN_WIDTH_COLLAPSED,
+  MIN_HEIGHT,
+} from '../constants';
+import { state } from '../state';
+
+const logger = createLogger('WindowBounds');
+
+/**
+ * Load saved window bounds from disk
+ * Uses centralized electronUserData methods for path validation.
+ */
+export function loadWindowBounds(): WindowBounds | null {
+  try {
+    if (electronUserDataExists(WINDOW_BOUNDS_FILENAME)) {
+      const data = electronUserDataReadFileSync(WINDOW_BOUNDS_FILENAME);
+      const bounds = JSON.parse(data) as WindowBounds;
+      // Validate the loaded data has required fields
+      if (
+        typeof bounds.x === 'number' &&
+        typeof bounds.y === 'number' &&
+        typeof bounds.width === 'number' &&
+        typeof bounds.height === 'number'
+      ) {
+        return bounds;
+      }
+    }
+  } catch (error) {
+    logger.warn('Failed to load window bounds:', (error as Error).message);
+  }
+  return null;
+}
+
+/**
+ * Save window bounds to disk
+ * Uses centralized electronUserData methods for path validation.
+ */
+export function saveWindowBounds(bounds: WindowBounds): void {
+  try {
+    electronUserDataWriteFileSync(WINDOW_BOUNDS_FILENAME, JSON.stringify(bounds, null, 2));
+    logger.info('Window bounds saved');
+  } catch (error) {
+    logger.warn('Failed to save window bounds:', (error as Error).message);
+  }
+}
+
+/**
+ * Schedule a debounced save of window bounds (500ms delay)
+ */
+export function scheduleSaveWindowBounds(): void {
+  if (!state.mainWindow || state.mainWindow.isDestroyed()) return;
+
+  if (state.saveWindowBoundsTimeout) {
+    clearTimeout(state.saveWindowBoundsTimeout);
+  }
+
+  state.saveWindowBoundsTimeout = setTimeout(() => {
+    if (!state.mainWindow || state.mainWindow.isDestroyed()) return;
+
+    const isMaximized = state.mainWindow.isMaximized();
+    // Use getNormalBounds() for maximized windows to save pre-maximized size
+    const bounds = isMaximized ? state.mainWindow.getNormalBounds() : state.mainWindow.getBounds();
+
+    saveWindowBounds({
+      x: bounds.x,
+      y: bounds.y,
+      width: bounds.width,
+      height: bounds.height,
+      isMaximized,
+    });
+  }, 500);
+}
+
+/**
+ * Validate that window bounds are visible on at least one display
+ * Returns adjusted bounds if needed, or null if completely off-screen
+ */
+export function validateBounds(bounds: WindowBounds): WindowBounds {
+  const displays = screen.getAllDisplays();
+
+  // Check if window center is visible on any display
+  const centerX = bounds.x + bounds.width / 2;
+  const centerY = bounds.y + bounds.height / 2;
+
+  let isVisible = false;
+  for (const display of displays) {
+    const { x, y, width, height } = display.workArea;
+    if (centerX >= x && centerX <= x + width && centerY >= y && centerY <= y + height) {
+      isVisible = true;
+      break;
+    }
+  }
+
+  if (!isVisible) {
+    // Window is off-screen, reset to primary display
+    const primaryDisplay = screen.getPrimaryDisplay();
+    const { x, y, width, height } = primaryDisplay.workArea;
+
+    return {
+      x: x + Math.floor((width - bounds.width) / 2),
+      y: y + Math.floor((height - bounds.height) / 2),
+      width: Math.min(bounds.width, width),
+      height: Math.min(bounds.height, height),
+      isMaximized: bounds.isMaximized,
+    };
+  }
+
+  // Ensure minimum dimensions
+  return {
+    ...bounds,
+    width: Math.max(bounds.width, MIN_WIDTH_COLLAPSED),
+    height: Math.max(bounds.height, MIN_HEIGHT),
+  };
+}

apps/ui/src/hooks/queries/use-features.ts

@@ -10,11 +10,12 @@ import { useQuery } from '@tanstack/react-query';
 import { getElectronAPI } from '@/lib/electron';
 import { queryKeys } from '@/lib/query-keys';
 import { STALE_TIMES } from '@/lib/query-client';
-import { getGlobalEventsRecent } from '@/hooks/use-event-recency';
+import { createSmartPollingInterval, getGlobalEventsRecent } from '@/hooks/use-event-recency';
 import type { Feature } from '@/store/app-store';
 
 const FEATURES_REFETCH_ON_FOCUS = false;
 const FEATURES_REFETCH_ON_RECONNECT = false;
+const FEATURES_POLLING_INTERVAL = 30000;
 /** Default polling interval for agent output when WebSocket is inactive */
 const AGENT_OUTPUT_POLLING_INTERVAL = 5000;
 
@@ -43,6 +44,7 @@ export function useFeatures(projectPath: string | undefined) {
     },
     enabled: !!projectPath,
     staleTime: STALE_TIMES.FEATURES,
+    refetchInterval: createSmartPollingInterval(FEATURES_POLLING_INTERVAL),
     refetchOnWindowFocus: FEATURES_REFETCH_ON_FOCUS,
     refetchOnReconnect: FEATURES_REFETCH_ON_RECONNECT,
   });

apps/ui/src/hooks/queries/use-running-agents.ts

@@ -9,9 +9,11 @@ import { useQuery } from '@tanstack/react-query';
 import { getElectronAPI, type RunningAgent } from '@/lib/electron';
 import { queryKeys } from '@/lib/query-keys';
 import { STALE_TIMES } from '@/lib/query-client';
+import { createSmartPollingInterval } from '@/hooks/use-event-recency';
 
 const RUNNING_AGENTS_REFETCH_ON_FOCUS = false;
 const RUNNING_AGENTS_REFETCH_ON_RECONNECT = false;
+const RUNNING_AGENTS_POLLING_INTERVAL = 30000;
 
 interface RunningAgentsResult {
   agents: RunningAgent[];
@@ -47,8 +49,7 @@ export function useRunningAgents() {
       };
     },
     staleTime: STALE_TIMES.RUNNING_AGENTS,
-    // Note: Don't use refetchInterval here - rely on WebSocket invalidation
+    refetchInterval: createSmartPollingInterval(RUNNING_AGENTS_POLLING_INTERVAL),
-    // for real-time updates instead of polling
     refetchOnWindowFocus: RUNNING_AGENTS_REFETCH_ON_FOCUS,
     refetchOnReconnect: RUNNING_AGENTS_REFETCH_ON_RECONNECT,
   });

apps/ui/src/hooks/queries/use-worktrees.ts

@@ -8,9 +8,11 @@ import { useQuery } from '@tanstack/react-query';
 import { getElectronAPI } from '@/lib/electron';
 import { queryKeys } from '@/lib/query-keys';
 import { STALE_TIMES } from '@/lib/query-client';
+import { createSmartPollingInterval } from '@/hooks/use-event-recency';
 
 const WORKTREE_REFETCH_ON_FOCUS = false;
 const WORKTREE_REFETCH_ON_RECONNECT = false;
+const WORKTREES_POLLING_INTERVAL = 30000;
 
 interface WorktreeInfo {
   path: string;
@@ -65,6 +67,7 @@ export function useWorktrees(projectPath: string | undefined, includeDetails = t
     },
     enabled: !!projectPath,
     staleTime: STALE_TIMES.WORKTREES,
+    refetchInterval: createSmartPollingInterval(WORKTREES_POLLING_INTERVAL),
     refetchOnWindowFocus: WORKTREE_REFETCH_ON_FOCUS,
     refetchOnReconnect: WORKTREE_REFETCH_ON_RECONNECT,
   });

apps/ui/src/hooks/use-auto-mode.ts

@@ -6,10 +6,12 @@ import { useAppStore } from '@/store/app-store';
 import { getElectronAPI } from '@/lib/electron';
 import type { AutoModeEvent } from '@/types/electron';
 import type { WorktreeInfo } from '@/components/views/board-view/worktree-panel/types';
+import { getGlobalEventsRecent } from '@/hooks/use-event-recency';
 
 const logger = createLogger('AutoMode');
 
 const AUTO_MODE_SESSION_KEY = 'automaker:autoModeRunningByWorktreeKey';
+const AUTO_MODE_POLLING_INTERVAL = 30000;
 
 /**
  * Generate a worktree key for session storage
@@ -140,42 +142,54 @@ export function useAutoMode(worktree?: WorktreeInfo) {
   // Check if we can start a new task based on concurrency limit
   const canStartNewTask = runningAutoTasks.length < maxConcurrency;
 
+  const refreshStatus = useCallback(async () => {
+    if (!currentProject) return;
+
+    try {
+      const api = getElectronAPI();
+      if (!api?.autoMode?.status) return;
+
+      const result = await api.autoMode.status(currentProject.path, branchName);
+      if (result.success && result.isAutoLoopRunning !== undefined) {
+        const backendIsRunning = result.isAutoLoopRunning;
+
+        if (backendIsRunning !== isAutoModeRunning) {
+          const worktreeDesc = branchName ? `worktree ${branchName}` : 'main worktree';
+          logger.info(
+            `[AutoMode] Syncing UI state with backend for ${worktreeDesc} in ${currentProject.path}: ${backendIsRunning ? 'ON' : 'OFF'}`
+          );
+          setAutoModeRunning(
+            currentProject.id,
+            branchName,
+            backendIsRunning,
+            result.maxConcurrency,
+            result.runningFeatures
+          );
+          setAutoModeSessionForWorktree(currentProject.path, branchName, backendIsRunning);
+        }
+      }
+    } catch (error) {
+      logger.error('Error syncing auto mode state with backend:', error);
+    }
+  }, [branchName, currentProject, isAutoModeRunning, setAutoModeRunning]);
+
   // On mount, query backend for current auto loop status and sync UI state.
   // This handles cases where the backend is still running after a page refresh.
+  useEffect(() => {
+    void refreshStatus();
+  }, [refreshStatus]);
+
+  // Periodic polling fallback when WebSocket events are stale.
   useEffect(() => {
     if (!currentProject) return;
 
-    const syncWithBackend = async () => {
+    const interval = setInterval(() => {
-      try {
+      if (getGlobalEventsRecent()) return;
-        const api = getElectronAPI();
+      void refreshStatus();
-        if (!api?.autoMode?.status) return;
+    }, AUTO_MODE_POLLING_INTERVAL);
 
-        const result = await api.autoMode.status(currentProject.path, branchName);
+    return () => clearInterval(interval);
-        if (result.success && result.isAutoLoopRunning !== undefined) {
+  }, [currentProject, refreshStatus]);
-          const backendIsRunning = result.isAutoLoopRunning;
-
-          if (backendIsRunning !== isAutoModeRunning) {
-            const worktreeDesc = branchName ? `worktree ${branchName}` : 'main worktree';
-            logger.info(
-              `[AutoMode] Syncing UI state with backend for ${worktreeDesc} in ${currentProject.path}: ${backendIsRunning ? 'ON' : 'OFF'}`
-            );
-            setAutoModeRunning(
-              currentProject.id,
-              branchName,
-              backendIsRunning,
-              result.maxConcurrency,
-              result.runningFeatures
-            );
-            setAutoModeSessionForWorktree(currentProject.path, branchName, backendIsRunning);
-          }
-        }
-      } catch (error) {
-        logger.error('Error syncing auto mode state with backend:', error);
-      }
-    };
-
-    syncWithBackend();
-  }, [currentProject, branchName, setAutoModeRunning]);
 
   // Handle auto mode events - listen globally for all projects/worktrees
   useEffect(() => {
@@ -672,5 +686,6 @@ export function useAutoMode(worktree?: WorktreeInfo) {
     start,
     stop,
     stopFeature,
+    refreshStatus,
   };
 }

apps/ui/src/lib/http-api-client.ts

@@ -946,7 +946,7 @@ export class HttpApiClient implements ElectronAPI {
     return response.json();
   }
 
-  private async get<T>(endpoint: string): Promise<T> {
+  async get<T>(endpoint: string): Promise<T> {
     // Ensure API key is initialized before making request
     await waitForApiKeyInit();
     const response = await fetch(`${this.serverUrl}${endpoint}`, {
@@ -976,7 +976,7 @@ export class HttpApiClient implements ElectronAPI {
     return response.json();
   }
 
-  private async put<T>(endpoint: string, body?: unknown): Promise<T> {
+  async put<T>(endpoint: string, body?: unknown): Promise<T> {
     // Ensure API key is initialized before making request
     await waitForApiKeyInit();
     const response = await fetch(`${this.serverUrl}${endpoint}`, {

apps/ui/src/main.ts

@@ -1,45 +1,42 @@
 /**
- * Electron main process (TypeScript)
+ * Electron main process entry point
  *
- * This version spawns the backend server and uses HTTP API for most operations.
+ * Handles app lifecycle, initialization, and coordination of modular components.
- * Only native features (dialogs, shell) use IPC.
+ *
+ * Architecture:
+ * - electron/constants.ts      - Window sizing, port defaults, filenames
+ * - electron/state.ts          - Shared state container
+ * - electron/utils/            - Port and icon utilities
+ * - electron/security/         - API key management
+ * - electron/windows/          - Window bounds and main window creation
+ * - electron/server/           - Backend and static server management
+ * - electron/ipc/              - IPC handlers (dialog, shell, app, auth, window, server)
  *
  * SECURITY: All file system access uses centralized methods from @automaker/platform.
  */
 
 import path from 'path';
-import { spawn, execSync, ChildProcess } from 'child_process';
+import { app, BrowserWindow, dialog } from 'electron';
-import crypto from 'crypto';
-import http, { Server } from 'http';
-import net from 'net';
-import { app, BrowserWindow, ipcMain, dialog, shell, screen } from 'electron';
-import { createLogger } from '@automaker/utils/logger';
 import {
-  findNodeExecutable,
-  buildEnhancedPath,
-  initAllowedPaths,
-  isPathAllowed,
-  getAllowedRootDirectory,
-  // Electron userData operations
   setElectronUserDataPath,
-  electronUserDataReadFileSync,
-  electronUserDataWriteFileSync,
-  electronUserDataExists,
-  // Electron app bundle operations
   setElectronAppPaths,
-  electronAppExists,
+  initAllowedPaths,
-  electronAppStat,
-  electronAppReadFile,
-  // System path operations
-  systemPathExists,
 } from '@automaker/platform';
+import { createLogger } from '@automaker/utils/logger';
+import { DEFAULT_SERVER_PORT, DEFAULT_STATIC_PORT } from './electron/constants';
+import { state } from './electron/state';
+import { findAvailablePort } from './electron/utils/port-manager';
+import { getIconPath } from './electron/utils/icon-manager';
+import { ensureApiKey } from './electron/security/api-key-manager';
+import { createWindow } from './electron/windows/main-window';
+import { startStaticServer, stopStaticServer } from './electron/server/static-server';
+import { startServer, waitForServer, stopServer } from './electron/server/backend-server';
+import { registerAllHandlers } from './electron/ipc';
 
 const logger = createLogger('Electron');
-const serverLogger = createLogger('Server');
 
 // Development environment
 const isDev = !app.isPackaged;
-const VITE_DEV_SERVER_URL = process.env.VITE_DEV_SERVER_URL;
 
 // Load environment variables from .env file (development only)
 if (isDev) {
@@ -51,608 +48,18 @@ if (isDev) {
   }
 }
 
-let mainWindow: BrowserWindow | null = null;
+// Register IPC handlers
-let serverProcess: ChildProcess | null = null;
+registerAllHandlers();
-let staticServer: Server | null = null;
-
-// Default ports (can be overridden via env) - will be dynamically assigned if these are in use
-// When launched via root init.mjs we pass:
-// - PORT (backend)
-// - TEST_PORT (vite dev server / static)
-const DEFAULT_SERVER_PORT = parseInt(process.env.PORT || '3008', 10);
-const DEFAULT_STATIC_PORT = parseInt(process.env.TEST_PORT || '3007', 10);
-
-// Actual ports in use (set during startup)
-let serverPort = DEFAULT_SERVER_PORT;
-let staticPort = DEFAULT_STATIC_PORT;
-
-/**
- * Check if a port is available
- */
-function isPortAvailable(port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.once('error', () => {
-      resolve(false);
-    });
-    server.once('listening', () => {
-      server.close(() => {
-        resolve(true);
-      });
-    });
-    // Use Node's default binding semantics (matches most dev servers)
-    // This avoids false-positives when a port is taken on IPv6/dual-stack.
-    server.listen(port);
-  });
-}
-
-/**
- * Find an available port starting from the preferred port
- * Tries up to 100 ports in sequence
- */
-async function findAvailablePort(preferredPort: number): Promise<number> {
-  for (let offset = 0; offset < 100; offset++) {
-    const port = preferredPort + offset;
-    if (await isPortAvailable(port)) {
-      return port;
-    }
-  }
-  throw new Error(`Could not find an available port starting from ${preferredPort}`);
-}
-
-// ============================================
-// Window sizing constants for kanban layout
-// ============================================
-// Calculation: 4 columns × 280px + 3 gaps × 20px + 40px padding = 1220px board content
-// With sidebar expanded (288px): 1220 + 288 = 1508px
-// Minimum window dimensions - reduced to allow smaller windows since kanban now supports horizontal scrolling
-const MIN_WIDTH_COLLAPSED = 600; // Reduced - horizontal scrolling handles overflow
-const MIN_HEIGHT = 500; // Reduced to allow more flexibility
-const DEFAULT_WIDTH = 1600;
-const DEFAULT_HEIGHT = 950;
-
-// Window bounds interface (matches @automaker/types WindowBounds)
-interface WindowBounds {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  isMaximized: boolean;
-}
-
-// Debounce timer for saving window bounds
-let saveWindowBoundsTimeout: ReturnType<typeof setTimeout> | null = null;
-
-// API key for CSRF protection
-let apiKey: string | null = null;
-
-// Track if we're using an external server (Docker API mode)
-let isExternalServerMode = false;
-
-/**
- * Get the relative path to API key file within userData
- */
-const API_KEY_FILENAME = '.api-key';
-
-/**
- * Ensure an API key exists - load from file or generate new one.
- * This key is passed to the server for CSRF protection.
- * Uses centralized electronUserData methods for path validation.
- */
-function ensureApiKey(): string {
-  try {
-    if (electronUserDataExists(API_KEY_FILENAME)) {
-      const key = electronUserDataReadFileSync(API_KEY_FILENAME).trim();
-      if (key) {
-        apiKey = key;
-        logger.info('Loaded existing API key');
-        return apiKey;
-      }
-    }
-  } catch (error) {
-    logger.warn('Error reading API key:', error);
-  }
-
-  // Generate new key
-  apiKey = crypto.randomUUID();
-  try {
-    electronUserDataWriteFileSync(API_KEY_FILENAME, apiKey, { encoding: 'utf-8', mode: 0o600 });
-    logger.info('Generated new API key');
-  } catch (error) {
-    logger.error('Failed to save API key:', error);
-  }
-  return apiKey;
-}
-
-/**
- * Get icon path - works in both dev and production, cross-platform
- * Uses centralized electronApp methods for path validation.
- */
-function getIconPath(): string | null {
-  let iconFile: string;
-  if (process.platform === 'win32') {
-    iconFile = 'icon.ico';
-  } else if (process.platform === 'darwin') {
-    iconFile = 'logo_larger.png';
-  } else {
-    iconFile = 'logo_larger.png';
-  }
-
-  const iconPath = isDev
-    ? path.join(__dirname, '../public', iconFile)
-    : path.join(__dirname, '../dist/public', iconFile);
-
-  try {
-    if (!electronAppExists(iconPath)) {
-      logger.warn('Icon not found at:', iconPath);
-      return null;
-    }
-  } catch (error) {
-    logger.warn('Icon check failed:', iconPath, error);
-    return null;
-  }
-
-  return iconPath;
-}
-
-/**
- * Relative path to window bounds settings file within userData
- */
-const WINDOW_BOUNDS_FILENAME = 'window-bounds.json';
-
-/**
- * Load saved window bounds from disk
- * Uses centralized electronUserData methods for path validation.
- */
-function loadWindowBounds(): WindowBounds | null {
-  try {
-    if (electronUserDataExists(WINDOW_BOUNDS_FILENAME)) {
-      const data = electronUserDataReadFileSync(WINDOW_BOUNDS_FILENAME);
-      const bounds = JSON.parse(data) as WindowBounds;
-      // Validate the loaded data has required fields
-      if (
-        typeof bounds.x === 'number' &&
-        typeof bounds.y === 'number' &&
-        typeof bounds.width === 'number' &&
-        typeof bounds.height === 'number'
-      ) {
-        return bounds;
-      }
-    }
-  } catch (error) {
-    logger.warn('Failed to load window bounds:', (error as Error).message);
-  }
-  return null;
-}
-
-/**
- * Save window bounds to disk
- * Uses centralized electronUserData methods for path validation.
- */
-function saveWindowBounds(bounds: WindowBounds): void {
-  try {
-    electronUserDataWriteFileSync(WINDOW_BOUNDS_FILENAME, JSON.stringify(bounds, null, 2));
-    logger.info('Window bounds saved');
-  } catch (error) {
-    logger.warn('Failed to save window bounds:', (error as Error).message);
-  }
-}
-
-/**
- * Schedule a debounced save of window bounds (500ms delay)
- */
-function scheduleSaveWindowBounds(): void {
-  if (!mainWindow || mainWindow.isDestroyed()) return;
-
-  if (saveWindowBoundsTimeout) {
-    clearTimeout(saveWindowBoundsTimeout);
-  }
-
-  saveWindowBoundsTimeout = setTimeout(() => {
-    if (!mainWindow || mainWindow.isDestroyed()) return;
-
-    const isMaximized = mainWindow.isMaximized();
-    // Use getNormalBounds() for maximized windows to save pre-maximized size
-    const bounds = isMaximized ? mainWindow.getNormalBounds() : mainWindow.getBounds();
-
-    saveWindowBounds({
-      x: bounds.x,
-      y: bounds.y,
-      width: bounds.width,
-      height: bounds.height,
-      isMaximized,
-    });
-  }, 500);
-}
-
-/**
- * Validate that window bounds are visible on at least one display
- * Returns adjusted bounds if needed, or null if completely off-screen
- */
-function validateBounds(bounds: WindowBounds): WindowBounds {
-  const displays = screen.getAllDisplays();
-
-  // Check if window center is visible on any display
-  const centerX = bounds.x + bounds.width / 2;
-  const centerY = bounds.y + bounds.height / 2;
-
-  let isVisible = false;
-  for (const display of displays) {
-    const { x, y, width, height } = display.workArea;
-    if (centerX >= x && centerX <= x + width && centerY >= y && centerY <= y + height) {
-      isVisible = true;
-      break;
-    }
-  }
-
-  if (!isVisible) {
-    // Window is off-screen, reset to primary display
-    const primaryDisplay = screen.getPrimaryDisplay();
-    const { x, y, width, height } = primaryDisplay.workArea;
-
-    return {
-      x: x + Math.floor((width - bounds.width) / 2),
-      y: y + Math.floor((height - bounds.height) / 2),
-      width: Math.min(bounds.width, width),
-      height: Math.min(bounds.height, height),
-      isMaximized: bounds.isMaximized,
-    };
-  }
-
-  // Ensure minimum dimensions
-  return {
-    ...bounds,
-    width: Math.max(bounds.width, MIN_WIDTH_COLLAPSED),
-    height: Math.max(bounds.height, MIN_HEIGHT),
-  };
-}
-
-/**
- * Start static file server for production builds
- * Uses centralized electronApp methods for serving static files from app bundle.
- */
-async function startStaticServer(): Promise<void> {
-  const staticPath = path.join(__dirname, '../dist');
-
-  staticServer = http.createServer((request, response) => {
-    let filePath = path.join(staticPath, request.url?.split('?')[0] || '/');
-
-    if (filePath.endsWith('/')) {
-      filePath = path.join(filePath, 'index.html');
-    } else if (!path.extname(filePath)) {
-      // For client-side routing, serve index.html for paths without extensions
-      const possibleFile = filePath + '.html';
-      try {
-        if (!electronAppExists(filePath) && !electronAppExists(possibleFile)) {
-          filePath = path.join(staticPath, 'index.html');
-        } else if (electronAppExists(possibleFile)) {
-          filePath = possibleFile;
-        }
-      } catch {
-        filePath = path.join(staticPath, 'index.html');
-      }
-    }
-
-    electronAppStat(filePath, (err, stats) => {
-      if (err || !stats?.isFile()) {
-        filePath = path.join(staticPath, 'index.html');
-      }
-
-      electronAppReadFile(filePath, (error, content) => {
-        if (error || !content) {
-          response.writeHead(500);
-          response.end('Server Error');
-          return;
-        }
-
-        const ext = path.extname(filePath);
-        const contentTypes: Record<string, string> = {
-          '.html': 'text/html',
-          '.js': 'application/javascript',
-          '.css': 'text/css',
-          '.json': 'application/json',
-          '.png': 'image/png',
-          '.jpg': 'image/jpeg',
-          '.gif': 'image/gif',
-          '.svg': 'image/svg+xml',
-          '.ico': 'image/x-icon',
-          '.woff': 'font/woff',
-          '.woff2': 'font/woff2',
-          '.ttf': 'font/ttf',
-          '.eot': 'application/vnd.ms-fontobject',
-        };
-
-        response.writeHead(200, {
-          'Content-Type': contentTypes[ext] || 'application/octet-stream',
-        });
-        response.end(content);
-      });
-    });
-  });
-
-  return new Promise((resolve, reject) => {
-    staticServer!.listen(staticPort, () => {
-      logger.info('Static server running at http://localhost:' + staticPort);
-      resolve();
-    });
-    staticServer!.on('error', reject);
-  });
-}
-
-/**
- * Start the backend server
- * Uses centralized methods for path validation.
- */
-async function startServer(): Promise<void> {
-  // Find Node.js executable (handles desktop launcher scenarios)
-  const nodeResult = findNodeExecutable({
-    skipSearch: isDev,
-    logger: (msg: string) => logger.info(msg),
-  });
-  const command = nodeResult.nodePath;
-
-  // Validate that the found Node executable actually exists
-  // systemPathExists is used because node-finder returns system paths
-  if (command !== 'node') {
-    let exists: boolean;
-    try {
-      exists = systemPathExists(command);
-    } catch (error) {
-      const originalError = error instanceof Error ? error.message : String(error);
-      throw new Error(
-        `Failed to verify Node.js executable at: ${command} (source: ${nodeResult.source}). Reason: ${originalError}`
-      );
-    }
-    if (!exists) {
-      throw new Error(`Node.js executable not found at: ${command} (source: ${nodeResult.source})`);
-    }
-  }
-
-  let args: string[];
-  let serverPath: string;
-
-  if (isDev) {
-    serverPath = path.join(__dirname, '../../server/src/index.ts');
-
-    const serverNodeModules = path.join(__dirname, '../../server/node_modules/tsx');
-    const rootNodeModules = path.join(__dirname, '../../../node_modules/tsx');
-
-    let tsxCliPath: string;
-    // Check for tsx in app bundle paths
-    try {
-      if (electronAppExists(path.join(serverNodeModules, 'dist/cli.mjs'))) {
-        tsxCliPath = path.join(serverNodeModules, 'dist/cli.mjs');
-      } else if (electronAppExists(path.join(rootNodeModules, 'dist/cli.mjs'))) {
-        tsxCliPath = path.join(rootNodeModules, 'dist/cli.mjs');
-      } else {
-        try {
-          tsxCliPath = require.resolve('tsx/cli.mjs', {
-            paths: [path.join(__dirname, '../../server')],
-          });
-        } catch {
-          throw new Error("Could not find tsx. Please run 'npm install' in the server directory.");
-        }
-      }
-    } catch {
-      try {
-        tsxCliPath = require.resolve('tsx/cli.mjs', {
-          paths: [path.join(__dirname, '../../server')],
-        });
-      } catch {
-        throw new Error("Could not find tsx. Please run 'npm install' in the server directory.");
-      }
-    }
-
-    args = [tsxCliPath, 'watch', serverPath];
-  } else {
-    serverPath = path.join(process.resourcesPath, 'server', 'index.js');
-    args = [serverPath];
-
-    try {
-      if (!electronAppExists(serverPath)) {
-        throw new Error(`Server not found at: ${serverPath}`);
-      }
-    } catch {
-      throw new Error(`Server not found at: ${serverPath}`);
-    }
-  }
-
-  const serverNodeModules = app.isPackaged
-    ? path.join(process.resourcesPath, 'server', 'node_modules')
-    : path.join(__dirname, '../../server/node_modules');
-
-  // Server root directory - where .env file is located
-  // In dev: apps/server (not apps/server/src)
-  // In production: resources/server
-  const serverRoot = app.isPackaged
-    ? path.join(process.resourcesPath, 'server')
-    : path.join(__dirname, '../../server');
-
-  // IMPORTANT: Use shared data directory (not Electron's user data directory)
-  // This ensures Electron and web mode share the same settings/projects
-  // In dev: project root/data (navigate from __dirname which is apps/server/dist or apps/ui/dist-electron)
-  // In production: same as Electron user data (for app isolation)
-  const dataDir = app.isPackaged
-    ? app.getPath('userData')
-    : path.join(__dirname, '../../..', 'data');
-  logger.info(
-    `[DATA_DIR] app.isPackaged=${app.isPackaged}, __dirname=${__dirname}, dataDir=${dataDir}`
-  );
-
-  // Build enhanced PATH that includes Node.js directory (cross-platform)
-  const enhancedPath = buildEnhancedPath(command, process.env.PATH || '');
-  if (enhancedPath !== process.env.PATH) {
-    logger.info('Enhanced PATH with Node directory:', path.dirname(command));
-  }
-
-  const env = {
-    ...process.env,
-    PATH: enhancedPath,
-    PORT: serverPort.toString(),
-    DATA_DIR: dataDir,
-    NODE_PATH: serverNodeModules,
-    // Pass API key to server for CSRF protection
-    AUTOMAKER_API_KEY: apiKey!,
-    // Only set ALLOWED_ROOT_DIRECTORY if explicitly provided in environment
-    // If not set, server will allow access to all paths
-    ...(process.env.ALLOWED_ROOT_DIRECTORY && {
-      ALLOWED_ROOT_DIRECTORY: process.env.ALLOWED_ROOT_DIRECTORY,
-    }),
-  };
-
-  logger.info('Server will use port', serverPort);
-  logger.info('[DATA_DIR_SPAWN] env.DATA_DIR=', env.DATA_DIR);
-
-  logger.info('Starting backend server...');
-  logger.info('Server path:', serverPath);
-  logger.info('Server root (cwd):', serverRoot);
-  logger.info('NODE_PATH:', serverNodeModules);
-
-  serverProcess = spawn(command, args, {
-    cwd: serverRoot,
-    env,
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-
-  serverProcess.stdout?.on('data', (data) => {
-    serverLogger.info(data.toString().trim());
-  });
-
-  serverProcess.stderr?.on('data', (data) => {
-    serverLogger.error(data.toString().trim());
-  });
-
-  serverProcess.on('close', (code) => {
-    serverLogger.info('Process exited with code', code);
-    serverProcess = null;
-  });
-
-  serverProcess.on('error', (err) => {
-    serverLogger.error('Failed to start server process:', err);
-    serverProcess = null;
-  });
-
-  await waitForServer();
-}
-
-/**
- * Wait for server to be available
- */
-async function waitForServer(maxAttempts = 30): Promise<void> {
-  for (let i = 0; i < maxAttempts; i++) {
-    try {
-      await new Promise<void>((resolve, reject) => {
-        const req = http.get(`http://localhost:${serverPort}/api/health`, (res) => {
-          if (res.statusCode === 200) {
-            resolve();
-          } else {
-            reject(new Error(`Status: ${res.statusCode}`));
-          }
-        });
-        req.on('error', reject);
-        req.setTimeout(1000, () => {
-          req.destroy();
-          reject(new Error('Timeout'));
-        });
-      });
-      logger.info('Server is ready');
-      return;
-    } catch {
-      await new Promise((r) => setTimeout(r, 500));
-    }
-  }
-
-  throw new Error('Server failed to start');
-}
-
-/**
- * Create the main window
- */
-function createWindow(): void {
-  const iconPath = getIconPath();
-
-  // Load and validate saved window bounds
-  const savedBounds = loadWindowBounds();
-  const validBounds = savedBounds ? validateBounds(savedBounds) : null;
-
-  const windowOptions: Electron.BrowserWindowConstructorOptions = {
-    width: validBounds?.width ?? DEFAULT_WIDTH,
-    height: validBounds?.height ?? DEFAULT_HEIGHT,
-    x: validBounds?.x,
-    y: validBounds?.y,
-    minWidth: MIN_WIDTH_COLLAPSED, // Small minimum - horizontal scrolling handles overflow
-    minHeight: MIN_HEIGHT,
-    webPreferences: {
-      preload: path.join(__dirname, 'preload.js'),
-      contextIsolation: true,
-      nodeIntegration: false,
-    },
-    titleBarStyle: 'hiddenInset',
-    backgroundColor: '#0a0a0a',
-  };
-
-  if (iconPath) {
-    windowOptions.icon = iconPath;
-  }
-
-  mainWindow = new BrowserWindow(windowOptions);
-
-  // Restore maximized state if previously maximized
-  if (validBounds?.isMaximized) {
-    mainWindow.maximize();
-  }
-
-  // Load Vite dev server in development or static server in production
-  if (VITE_DEV_SERVER_URL) {
-    mainWindow.loadURL(VITE_DEV_SERVER_URL);
-  } else if (isDev) {
-    // Fallback for dev without Vite server URL
-    mainWindow.loadURL(`http://localhost:${staticPort}`);
-  } else {
-    mainWindow.loadURL(`http://localhost:${staticPort}`);
-  }
-
-  if (isDev && process.env.OPEN_DEVTOOLS === 'true') {
-    mainWindow.webContents.openDevTools();
-  }
-
-  // Save window bounds on close, resize, and move
-  mainWindow.on('close', () => {
-    // Save immediately before closing (not debounced)
-    if (mainWindow && !mainWindow.isDestroyed()) {
-      const isMaximized = mainWindow.isMaximized();
-      const bounds = isMaximized ? mainWindow.getNormalBounds() : mainWindow.getBounds();
-
-      saveWindowBounds({
-        x: bounds.x,
-        y: bounds.y,
-        width: bounds.width,
-        height: bounds.height,
-        isMaximized,
-      });
-    }
-  });
-
-  mainWindow.on('closed', () => {
-    mainWindow = null;
-  });
-
-  mainWindow.on('resized', () => {
-    scheduleSaveWindowBounds();
-  });
-
-  mainWindow.on('moved', () => {
-    scheduleSaveWindowBounds();
-  });
-
-  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
-    shell.openExternal(url);
-    return { action: 'deny' };
-  });
-}
 
 // App lifecycle
-app.whenReady().then(async () => {
+app.whenReady().then(handleAppReady);
+app.on('window-all-closed', handleWindowAllClosed);
+app.on('before-quit', handleBeforeQuit);
+
+/**
+ * Handle app.whenReady()
+ */
+async function handleAppReady(): Promise<void> {
   // In production, use Automaker dir in appData for app isolation
   // In development, use project root for shared data between Electron and web mode
   let userDataPathToUse: string;
@@ -661,10 +68,12 @@ app.whenReady().then(async () => {
     // Production: Ensure userData path is consistent so files land in Automaker dir
     try {
       const desiredUserDataPath = path.join(app.getPath('appData'), 'Automaker');
+
       if (app.getPath('userData') !== desiredUserDataPath) {
         app.setPath('userData', desiredUserDataPath);
         logger.info('[PRODUCTION] userData path set to:', desiredUserDataPath);
       }
+
       userDataPathToUse = desiredUserDataPath;
     } catch (error) {
       logger.warn('[PRODUCTION] Failed to set userData path:', (error as Error).message);
@@ -676,6 +85,7 @@ app.whenReady().then(async () => {
     // __dirname is apps/ui/dist-electron, so go up to get project root
     const projectRoot = path.join(__dirname, '../../..');
     userDataPathToUse = path.join(projectRoot, 'data');
+
     try {
       app.setPath('userData', userDataPathToUse);
       logger.info('[DEVELOPMENT] userData path explicitly set to:', userDataPathToUse);
@@ -701,6 +111,7 @@ app.whenReady().then(async () => {
   } else {
     setElectronAppPaths(__dirname, process.resourcesPath);
   }
+
   logger.info('Initialized path security helpers');
 
   // Initialize security settings for path validation
@@ -711,6 +122,7 @@ app.whenReady().then(async () => {
     : path.join(process.cwd(), 'data');
   process.env.DATA_DIR = mainProcessDataDir;
   logger.info('[MAIN_PROCESS_DATA_DIR]', mainProcessDataDir);
+
   // ALLOWED_ROOT_DIRECTORY should already be in process.env if set by user
   // (it will be passed to server process, but we also need it in main process for dialog validation)
   initAllowedPaths();
@@ -729,12 +141,12 @@ app.whenReady().then(async () => {
   try {
     // Check if we should skip the embedded server (for Docker API mode)
     const skipEmbeddedServer = process.env.SKIP_EMBEDDED_SERVER === 'true';
-    isExternalServerMode = skipEmbeddedServer;
+    state.isExternalServerMode = skipEmbeddedServer;
 
     if (skipEmbeddedServer) {
       // Use the default server port (Docker container runs on 3008)
-      serverPort = DEFAULT_SERVER_PORT;
+      state.serverPort = DEFAULT_SERVER_PORT;
-      logger.info('SKIP_EMBEDDED_SERVER=true, using external server at port', serverPort);
+      logger.info('SKIP_EMBEDDED_SERVER=true, using external server at port', state.serverPort);
 
       // Wait for external server to be ready
       logger.info('Waiting for external server...');
@@ -751,15 +163,25 @@ app.whenReady().then(async () => {
       ensureApiKey();
 
       // Find available ports (prevents conflicts with other apps using same ports)
-      serverPort = await findAvailablePort(DEFAULT_SERVER_PORT);
+      state.serverPort = await findAvailablePort(DEFAULT_SERVER_PORT);
-      if (serverPort !== DEFAULT_SERVER_PORT) {
+      if (state.serverPort !== DEFAULT_SERVER_PORT) {
-        logger.info('Default server port', DEFAULT_SERVER_PORT, 'in use, using port', serverPort);
+        logger.info(
+          'Default server port',
+          DEFAULT_SERVER_PORT,
+          'in use, using port',
+          state.serverPort
+        );
       }
     }
 
-    staticPort = await findAvailablePort(DEFAULT_STATIC_PORT);
+    state.staticPort = await findAvailablePort(DEFAULT_STATIC_PORT);
-    if (staticPort !== DEFAULT_STATIC_PORT) {
+    if (state.staticPort !== DEFAULT_STATIC_PORT) {
-      logger.info('Default static port', DEFAULT_STATIC_PORT, 'in use, using port', staticPort);
+      logger.info(
+        'Default static port',
+        DEFAULT_STATIC_PORT,
+        'in use, using port',
+        state.staticPort
+      );
     }
 
     // Start static file server in production
@@ -776,8 +198,10 @@ app.whenReady().then(async () => {
     createWindow();
   } catch (error) {
     logger.error('Failed to start:', error);
+
     const errorMessage = (error as Error).message;
     const isNodeError = errorMessage.includes('Node.js');
+
     dialog.showErrorBox(
       'Automaker Failed to Start',
       `The application failed to start.\n\n${errorMessage}\n\n${
@@ -794,207 +218,25 @@ app.whenReady().then(async () => {
       createWindow();
     }
   });
-});
+}
 
-app.on('window-all-closed', () => {
+/**
+ * Handle window-all-closed event
+ */
+function handleWindowAllClosed(): void {
   // On macOS, keep the app and servers running when all windows are closed
   // (standard macOS behavior). On other platforms, stop servers and quit.
   if (process.platform !== 'darwin') {
-    if (serverProcess && serverProcess.pid) {
+    stopServer();
-      logger.info('All windows closed, stopping server...');
+    stopStaticServer();
-      if (process.platform === 'win32') {
-        try {
-          execSync(`taskkill /f /t /pid ${serverProcess.pid}`, { stdio: 'ignore' });
-        } catch (error) {
-          logger.error('Failed to kill server process:', (error as Error).message);
-        }
-      } else {
-        serverProcess.kill('SIGTERM');
-      }
-      serverProcess = null;
-    }
-
-    if (staticServer) {
-      logger.info('Stopping static server...');
-      staticServer.close();
-      staticServer = null;
-    }
-
     app.quit();
   }
-});
+}
 
-app.on('before-quit', () => {
+/**
-  if (serverProcess && serverProcess.pid) {
+ * Handle before-quit event
-    logger.info('Stopping server...');
+ */
-    if (process.platform === 'win32') {
+function handleBeforeQuit(): void {
-      try {
+  stopServer();
-        // Windows: use taskkill with /t to kill entire process tree
+  stopStaticServer();
-        // This prevents orphaned node processes when closing the app
+}
-        // Using execSync to ensure process is killed before app exits
-        execSync(`taskkill /f /t /pid ${serverProcess.pid}`, { stdio: 'ignore' });
-      } catch (error) {
-        logger.error('Failed to kill server process:', (error as Error).message);
-      }
-    } else {
-      serverProcess.kill('SIGTERM');
-    }
-    serverProcess = null;
-  }
-
-  if (staticServer) {
-    logger.info('Stopping static server...');
-    staticServer.close();
-    staticServer = null;
-  }
-});
-
-// ============================================
-// IPC Handlers - Only native features
-// ============================================
-
-// Native file dialogs
-ipcMain.handle('dialog:openDirectory', async () => {
-  if (!mainWindow) {
-    return { canceled: true, filePaths: [] };
-  }
-  const result = await dialog.showOpenDialog(mainWindow, {
-    properties: ['openDirectory', 'createDirectory'],
-  });
-
-  // Validate selected path against ALLOWED_ROOT_DIRECTORY if configured
-  if (!result.canceled && result.filePaths.length > 0) {
-    const selectedPath = result.filePaths[0];
-    if (!isPathAllowed(selectedPath)) {
-      const allowedRoot = getAllowedRootDirectory();
-      const errorMessage = allowedRoot
-        ? `The selected directory is not allowed. Please select a directory within: ${allowedRoot}`
-        : 'The selected directory is not allowed.';
-
-      await dialog.showErrorBox('Directory Not Allowed', errorMessage);
-
-      return { canceled: true, filePaths: [] };
-    }
-  }
-
-  return result;
-});
-
-ipcMain.handle('dialog:openFile', async (_, options = {}) => {
-  if (!mainWindow) {
-    return { canceled: true, filePaths: [] };
-  }
-  const result = await dialog.showOpenDialog(mainWindow, {
-    properties: ['openFile'],
-    ...options,
-  });
-  return result;
-});
-
-ipcMain.handle('dialog:saveFile', async (_, options = {}) => {
-  if (!mainWindow) {
-    return { canceled: true, filePath: undefined };
-  }
-  const result = await dialog.showSaveDialog(mainWindow, options);
-  return result;
-});
-
-// Shell operations
-ipcMain.handle('shell:openExternal', async (_, url: string) => {
-  try {
-    await shell.openExternal(url);
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: (error as Error).message };
-  }
-});
-
-ipcMain.handle('shell:openPath', async (_, filePath: string) => {
-  try {
-    await shell.openPath(filePath);
-    return { success: true };
-  } catch (error) {
-    return { success: false, error: (error as Error).message };
-  }
-});
-
-// Open file in editor (VS Code, etc.) with optional line/column
-ipcMain.handle(
-  'shell:openInEditor',
-  async (_, filePath: string, line?: number, column?: number) => {
-    try {
-      // Build VS Code URL scheme: vscode://file/path:line:column
-      // This works on all platforms where VS Code is installed
-      // URL encode the path to handle special characters (spaces, brackets, etc.)
-      // Handle both Unix (/) and Windows (\) path separators
-      const normalizedPath = filePath.replace(/\\/g, '/');
-      const encodedPath = normalizedPath.startsWith('/')
-        ? '/' + normalizedPath.slice(1).split('/').map(encodeURIComponent).join('/')
-        : normalizedPath.split('/').map(encodeURIComponent).join('/');
-      let url = `vscode://file${encodedPath}`;
-      if (line !== undefined && line > 0) {
-        url += `:${line}`;
-        if (column !== undefined && column > 0) {
-          url += `:${column}`;
-        }
-      }
-      await shell.openExternal(url);
-      return { success: true };
-    } catch (error) {
-      return { success: false, error: (error as Error).message };
-    }
-  }
-);
-
-// App info
-ipcMain.handle('app:getPath', async (_, name: Parameters<typeof app.getPath>[0]) => {
-  return app.getPath(name);
-});
-
-ipcMain.handle('app:getVersion', async () => {
-  return app.getVersion();
-});
-
-ipcMain.handle('app:isPackaged', async () => {
-  return app.isPackaged;
-});
-
-// Ping - for connection check
-ipcMain.handle('ping', async () => {
-  return 'pong';
-});
-
-// Get server URL for HTTP client
-ipcMain.handle('server:getUrl', async () => {
-  return `http://localhost:${serverPort}`;
-});
-
-// Get API key for authentication
-// Returns null in external server mode to trigger session-based auth
-ipcMain.handle('auth:getApiKey', () => {
-  if (isExternalServerMode) {
-    return null;
-  }
-  return apiKey;
-});
-
-// Check if running in external server mode (Docker API)
-// Used by renderer to determine auth flow
-ipcMain.handle('auth:isExternalServerMode', () => {
-  return isExternalServerMode;
-});
-
-// Window management - update minimum width based on sidebar state
-// Now uses a fixed small minimum since horizontal scrolling handles overflow
-ipcMain.handle('window:updateMinWidth', (_, _sidebarExpanded: boolean) => {
-  if (!mainWindow || mainWindow.isDestroyed()) return;
-
-  // Always use the smaller minimum width - horizontal scrolling handles any overflow
-  mainWindow.setMinimumSize(MIN_WIDTH_COLLAPSED, MIN_HEIGHT);
-});
-
-// Quit the application (used when user denies sandbox risk confirmation)
-ipcMain.handle('app:quit', () => {
-  logger.info('Quitting application via IPC request');
-  app.quit();
-});

apps/ui/src/preload.ts

@@ -7,6 +7,7 @@
 
 import { contextBridge, ipcRenderer, OpenDialogOptions, SaveDialogOptions } from 'electron';
 import { createLogger } from '@automaker/utils/logger';
+import { IPC_CHANNELS } from './electron/ipc/channels';
 
 const logger = createLogger('Preload');
 
@@ -17,48 +18,49 @@ contextBridge.exposeInMainWorld('electronAPI', {
   isElectron: true,
 
   // Connection check
-  ping: (): Promise<string> => ipcRenderer.invoke('ping'),
+  ping: (): Promise<string> => ipcRenderer.invoke(IPC_CHANNELS.PING),
 
   // Get server URL for HTTP client
-  getServerUrl: (): Promise<string> => ipcRenderer.invoke('server:getUrl'),
+  getServerUrl: (): Promise<string> => ipcRenderer.invoke(IPC_CHANNELS.SERVER.GET_URL),
 
   // Get API key for authentication
-  getApiKey: (): Promise<string | null> => ipcRenderer.invoke('auth:getApiKey'),
+  getApiKey: (): Promise<string | null> => ipcRenderer.invoke(IPC_CHANNELS.AUTH.GET_API_KEY),
 
   // Check if running in external server mode (Docker API)
-  isExternalServerMode: (): Promise<boolean> => ipcRenderer.invoke('auth:isExternalServerMode'),
+  isExternalServerMode: (): Promise<boolean> =>
+    ipcRenderer.invoke(IPC_CHANNELS.AUTH.IS_EXTERNAL_SERVER_MODE),
 
   // Native dialogs - better UX than prompt()
   openDirectory: (): Promise<Electron.OpenDialogReturnValue> =>
-    ipcRenderer.invoke('dialog:openDirectory'),
+    ipcRenderer.invoke(IPC_CHANNELS.DIALOG.OPEN_DIRECTORY),
   openFile: (options?: OpenDialogOptions): Promise<Electron.OpenDialogReturnValue> =>
-    ipcRenderer.invoke('dialog:openFile', options),
+    ipcRenderer.invoke(IPC_CHANNELS.DIALOG.OPEN_FILE, options),
   saveFile: (options?: SaveDialogOptions): Promise<Electron.SaveDialogReturnValue> =>
-    ipcRenderer.invoke('dialog:saveFile', options),
+    ipcRenderer.invoke(IPC_CHANNELS.DIALOG.SAVE_FILE, options),
 
   // Shell operations
   openExternalLink: (url: string): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke('shell:openExternal', url),
+    ipcRenderer.invoke(IPC_CHANNELS.SHELL.OPEN_EXTERNAL, url),
   openPath: (filePath: string): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke('shell:openPath', filePath),
+    ipcRenderer.invoke(IPC_CHANNELS.SHELL.OPEN_PATH, filePath),
   openInEditor: (
     filePath: string,
     line?: number,
     column?: number
   ): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke('shell:openInEditor', filePath, line, column),
+    ipcRenderer.invoke(IPC_CHANNELS.SHELL.OPEN_IN_EDITOR, filePath, line, column),
 
   // App info
-  getPath: (name: string): Promise<string> => ipcRenderer.invoke('app:getPath', name),
+  getPath: (name: string): Promise<string> => ipcRenderer.invoke(IPC_CHANNELS.APP.GET_PATH, name),
-  getVersion: (): Promise<string> => ipcRenderer.invoke('app:getVersion'),
+  getVersion: (): Promise<string> => ipcRenderer.invoke(IPC_CHANNELS.APP.GET_VERSION),
-  isPackaged: (): Promise<boolean> => ipcRenderer.invoke('app:isPackaged'),
+  isPackaged: (): Promise<boolean> => ipcRenderer.invoke(IPC_CHANNELS.APP.IS_PACKAGED),
 
   // Window management
   updateMinWidth: (sidebarExpanded: boolean): Promise<void> =>
-    ipcRenderer.invoke('window:updateMinWidth', sidebarExpanded),
+    ipcRenderer.invoke(IPC_CHANNELS.WINDOW.UPDATE_MIN_WIDTH, sidebarExpanded),
 
   // App control
-  quit: (): Promise<void> => ipcRenderer.invoke('app:quit'),
+  quit: (): Promise<void> => ipcRenderer.invoke(IPC_CHANNELS.APP.QUIT),
 });
 
 logger.info('Electron API exposed (TypeScript)');

apps/ui/src/store/defaults/background-settings.ts

@@ -0,0 +1,13 @@
+import type { BackgroundSettings } from '../types/ui-types';
+
+// Default background settings for board backgrounds
+export const defaultBackgroundSettings: BackgroundSettings = {
+  imagePath: null,
+  cardOpacity: 100,
+  columnOpacity: 100,
+  columnBorderEnabled: true,
+  cardGlassmorphism: true,
+  cardBorderEnabled: true,
+  cardBorderOpacity: 100,
+  hideScrollbar: false,
+};

apps/ui/src/store/defaults/constants.ts

@@ -0,0 +1,2 @@
+// Maximum number of output lines to keep in init script state (prevents unbounded memory growth)
+export const MAX_INIT_OUTPUT_LINES = 500;

apps/ui/src/store/defaults/index.ts

@@ -0,0 +1,3 @@
+export { defaultBackgroundSettings } from './background-settings';
+export { defaultTerminalState } from './terminal-defaults';
+export { MAX_INIT_OUTPUT_LINES } from './constants';

apps/ui/src/store/defaults/terminal-defaults.ts

@@ -0,0 +1,21 @@
+import { DEFAULT_FONT_VALUE } from '@/config/ui-font-options';
+import type { TerminalState } from '../types/terminal-types';
+
+// Default terminal state values
+export const defaultTerminalState: TerminalState = {
+  isUnlocked: false,
+  authToken: null,
+  tabs: [],
+  activeTabId: null,
+  activeSessionId: null,
+  maximizedSessionId: null,
+  defaultFontSize: 14,
+  defaultRunScript: '',
+  screenReaderMode: false,
+  fontFamily: DEFAULT_FONT_VALUE,
+  scrollbackLines: 5000,
+  lineHeight: 1.0,
+  maxSessions: 100,
+  lastActiveProjectPath: null,
+  openTerminalMode: 'newTab',
+};

apps/ui/src/store/types/chat-types.ts

@@ -0,0 +1,40 @@
+export interface ImageAttachment {
+  id?: string; // Optional - may not be present in messages loaded from server
+  data: string; // base64 encoded image data
+  mimeType: string; // e.g., "image/png", "image/jpeg"
+  filename: string;
+  size?: number; // file size in bytes - optional for messages from server
+}
+
+export interface TextFileAttachment {
+  id: string;
+  content: string; // text content of the file
+  mimeType: string; // e.g., "text/plain", "text/markdown"
+  filename: string;
+  size: number; // file size in bytes
+}
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: Date;
+  images?: ImageAttachment[];
+  textFiles?: TextFileAttachment[];
+}
+
+export interface ChatSession {
+  id: string;
+  title: string;
+  projectId: string;
+  messages: ChatMessage[];
+  createdAt: Date;
+  updatedAt: Date;
+  archived: boolean;
+}
+
+// UI-specific: base64-encoded images with required id and size (extends ImageAttachment)
+export interface FeatureImage extends ImageAttachment {
+  id: string; // Required (overrides optional in ImageAttachment)
+  size: number; // Required (overrides optional in ImageAttachment)
+}

apps/ui/src/store/types/index.ts

@@ -0,0 +1,7 @@
+export * from './usage-types';
+export * from './ui-types';
+export * from './settings-types';
+export * from './chat-types';
+export * from './terminal-types';
+export * from './project-types';
+export * from './state-types';

apps/ui/src/store/types/project-types.ts

@@ -0,0 +1,66 @@
+import type {
+  Feature as BaseFeature,
+  FeatureImagePath,
+  FeatureTextFilePath,
+  ThinkingLevel,
+  ReasoningEffort,
+  FeatureStatusWithPipeline,
+  PlanSpec,
+} from '@automaker/types';
+import type { FeatureImage } from './chat-types';
+
+// Available models for feature execution
+export type ClaudeModel = 'opus' | 'sonnet' | 'haiku';
+
+export interface Feature extends Omit<
+  BaseFeature,
+  | 'steps'
+  | 'imagePaths'
+  | 'textFilePaths'
+  | 'status'
+  | 'planSpec'
+  | 'dependencies'
+  | 'model'
+  | 'branchName'
+  | 'thinkingLevel'
+  | 'reasoningEffort'
+  | 'summary'
+> {
+  id: string;
+  title?: string;
+  titleGenerating?: boolean;
+  category: string;
+  description: string;
+  steps: string[]; // Required in UI (not optional)
+  status: FeatureStatusWithPipeline;
+  images?: FeatureImage[]; // UI-specific base64 images
+  imagePaths?: FeatureImagePath[]; // Stricter type than base (no string | union)
+  textFilePaths?: FeatureTextFilePath[]; // Text file attachments for context
+  justFinishedAt?: string; // UI-specific: ISO timestamp when agent just finished
+  prUrl?: string; // UI-specific: Pull request URL
+  planSpec?: PlanSpec; // Explicit planSpec type to override BaseFeature's index signature
+  dependencies?: string[]; // Explicit type to override BaseFeature's index signature
+  model?: string; // Explicit type to override BaseFeature's index signature
+  branchName?: string; // Explicit type to override BaseFeature's index signature
+  thinkingLevel?: ThinkingLevel; // Explicit type to override BaseFeature's index signature
+  reasoningEffort?: ReasoningEffort; // Explicit type to override BaseFeature's index signature
+  summary?: string; // Explicit type to override BaseFeature's index signature
+}
+
+// File tree node for project analysis
+export interface FileTreeNode {
+  name: string;
+  path: string;
+  isDirectory: boolean;
+  extension?: string;
+  children?: FileTreeNode[];
+}
+
+// Project analysis result
+export interface ProjectAnalysis {
+  fileTree: FileTreeNode[];
+  totalFiles: number;
+  totalDirectories: number;
+  filesByExtension: Record<string, number>;
+  analyzedAt: string;
+}

apps/ui/src/store/types/settings-types.ts

@@ -0,0 +1,5 @@
+export interface ApiKeys {
+  anthropic: string;
+  google: string;
+  openai: string;
+}

apps/ui/src/store/types/state-types.ts

@@ -0,0 +1,799 @@
+import type { Project, TrashedProject } from '@/lib/electron';
+import type {
+  ModelAlias,
+  PlanningMode,
+  ThinkingLevel,
+  ReasoningEffort,
+  ModelProvider,
+  CursorModelId,
+  CodexModelId,
+  OpencodeModelId,
+  GeminiModelId,
+  CopilotModelId,
+  PhaseModelConfig,
+  PhaseModelKey,
+  PhaseModelEntry,
+  MCPServerConfig,
+  PipelineConfig,
+  PipelineStep,
+  PromptCustomization,
+  ModelDefinition,
+  ServerLogLevel,
+  EventHook,
+  ClaudeApiProfile,
+  ClaudeCompatibleProvider,
+  SidebarStyle,
+} from '@automaker/types';
+
+import type {
+  ViewMode,
+  ThemeMode,
+  BoardViewMode,
+  KeyboardShortcuts,
+  BackgroundSettings,
+} from './ui-types';
+import type { ApiKeys } from './settings-types';
+import type { ChatMessage, ChatSession, FeatureImage } from './chat-types';
+import type { TerminalState, TerminalPanelContent, PersistedTerminalState } from './terminal-types';
+import type { Feature, ProjectAnalysis } from './project-types';
+import type { ClaudeUsage, CodexUsage } from './usage-types';
+
+/** State for worktree init script execution */
+export interface InitScriptState {
+  status: 'idle' | 'running' | 'success' | 'failed';
+  branch: string;
+  output: string[];
+  error?: string;
+}
+
+export interface AutoModeActivity {
+  id: string;
+  featureId: string;
+  timestamp: Date;
+  type:
+    | 'start'
+    | 'progress'
+    | 'tool'
+    | 'complete'
+    | 'error'
+    | 'planning'
+    | 'action'
+    | 'verification';
+  message: string;
+  tool?: string;
+  passes?: boolean;
+  phase?: 'planning' | 'action' | 'verification';
+  errorType?: 'authentication' | 'execution';
+}
+
+export interface AppState {
+  // Project state
+  projects: Project[];
+  currentProject: Project | null;
+  trashedProjects: TrashedProject[];
+  projectHistory: string[]; // Array of project IDs in MRU order (most recent first)
+  projectHistoryIndex: number; // Current position in project history for cycling
+
+  // View state
+  currentView: ViewMode;
+  sidebarOpen: boolean;
+  sidebarStyle: SidebarStyle; // 'unified' (modern) or 'discord' (classic two-sidebar layout)
+  collapsedNavSections: Record<string, boolean>; // Collapsed state of nav sections (key: section label)
+  mobileSidebarHidden: boolean; // Completely hides sidebar on mobile
+
+  // Agent Session state (per-project, keyed by project path)
+  lastSelectedSessionByProject: Record<string, string>; // projectPath -> sessionId
+
+  // Theme
+  theme: ThemeMode;
+
+  // Fonts (global defaults)
+  fontFamilySans: string | null; // null = use default Geist Sans
+  fontFamilyMono: string | null; // null = use default Geist Mono
+
+  // Features/Kanban
+  features: Feature[];
+
+  // App spec
+  appSpec: string;
+
+  // IPC status
+  ipcConnected: boolean;
+
+  // API Keys
+  apiKeys: ApiKeys;
+
+  // Chat Sessions
+  chatSessions: ChatSession[];
+  currentChatSession: ChatSession | null;
+  chatHistoryOpen: boolean;
+
+  // Auto Mode (per-worktree state, keyed by "${projectId}::${branchName ?? '__main__'}")
+  autoModeByWorktree: Record<
+    string,
+    {
+      isRunning: boolean;
+      runningTasks: string[]; // Feature IDs being worked on
+      branchName: string | null; // null = main worktree
+      maxConcurrency?: number; // Maximum concurrent features for this worktree (defaults to 3)
+    }
+  >;
+  autoModeActivityLog: AutoModeActivity[];
+  maxConcurrency: number; // Legacy: Maximum number of concurrent agent tasks (deprecated, use per-worktree maxConcurrency)
+
+  // Kanban Card Display Settings
+  boardViewMode: BoardViewMode; // Whether to show kanban or dependency graph view
+
+  // Feature Default Settings
+  defaultSkipTests: boolean; // Default value for skip tests when creating new features
+  enableDependencyBlocking: boolean; // When true, show blocked badges and warnings for features with incomplete dependencies (default: true)
+  skipVerificationInAutoMode: boolean; // When true, auto-mode grabs features even if dependencies are not verified (only checks they're not running)
+  enableAiCommitMessages: boolean; // When true, auto-generate commit messages using AI when opening commit dialog
+  planUseSelectedWorktreeBranch: boolean; // When true, Plan dialog creates features on the currently selected worktree branch
+  addFeatureUseSelectedWorktreeBranch: boolean; // When true, Add Feature dialog defaults to custom mode with selected worktree branch
+
+  // Worktree Settings
+  useWorktrees: boolean; // Whether to use git worktree isolation for features (default: true)
+
+  // User-managed Worktrees (per-project)
+  // projectPath -> { path: worktreePath or null for main, branch: branch name }
+  currentWorktreeByProject: Record<string, { path: string | null; branch: string }>;
+  worktreesByProject: Record<
+    string,
+    Array<{
+      path: string;
+      branch: string;
+      isMain: boolean;
+      isCurrent: boolean;
+      hasWorktree: boolean;
+      hasChanges?: boolean;
+      changedFilesCount?: number;
+    }>
+  >;
+
+  // Keyboard Shortcuts
+  keyboardShortcuts: KeyboardShortcuts; // User-defined keyboard shortcuts
+
+  // Audio Settings
+  muteDoneSound: boolean; // When true, mute the notification sound when agents complete (default: false)
+
+  // Splash Screen Settings
+  disableSplashScreen: boolean; // When true, skip showing the splash screen overlay on startup
+
+  // Server Log Level Settings
+  serverLogLevel: ServerLogLevel; // Log level for the API server (error, warn, info, debug)
+  enableRequestLogging: boolean; // Enable HTTP request logging (Morgan)
+
+  // Developer Tools Settings
+  showQueryDevtools: boolean; // Show React Query DevTools panel (only in development mode)
+
+  // Enhancement Model Settings
+  enhancementModel: ModelAlias; // Model used for feature enhancement (default: sonnet)
+
+  // Validation Model Settings
+  validationModel: ModelAlias; // Model used for GitHub issue validation (default: opus)
+
+  // Phase Model Settings - per-phase AI model configuration
+  phaseModels: PhaseModelConfig;
+  favoriteModels: string[];
+
+  // Cursor CLI Settings (global)
+  enabledCursorModels: CursorModelId[]; // Which Cursor models are available in feature modal
+  cursorDefaultModel: CursorModelId; // Default Cursor model selection
+
+  // Codex CLI Settings (global)
+  enabledCodexModels: CodexModelId[]; // Which Codex models are available in feature modal
+  codexDefaultModel: CodexModelId; // Default Codex model selection
+  codexAutoLoadAgents: boolean; // Auto-load .codex/AGENTS.md files
+  codexSandboxMode: 'read-only' | 'workspace-write' | 'danger-full-access'; // Sandbox policy
+  codexApprovalPolicy: 'untrusted' | 'on-failure' | 'on-request' | 'never'; // Approval policy
+  codexEnableWebSearch: boolean; // Enable web search capability
+  codexEnableImages: boolean; // Enable image processing
+
+  // OpenCode CLI Settings (global)
+  // Static OpenCode settings are persisted via SETTINGS_FIELDS_TO_SYNC
+  enabledOpencodeModels: OpencodeModelId[]; // Which static OpenCode models are available
+  opencodeDefaultModel: OpencodeModelId; // Default OpenCode model selection
+  // Dynamic models are session-only (not persisted) because they're discovered at runtime
+  // from `opencode models` CLI and depend on current provider authentication state
+  dynamicOpencodeModels: ModelDefinition[]; // Dynamically discovered models from OpenCode CLI
+  enabledDynamicModelIds: string[]; // Which dynamic models are enabled
+  cachedOpencodeProviders: Array<{
+    id: string;
+    name: string;
+    authenticated: boolean;
+    authMethod?: string;
+  }>; // Cached providers
+  opencodeModelsLoading: boolean; // Whether OpenCode models are being fetched
+  opencodeModelsError: string | null; // Error message if fetch failed
+  opencodeModelsLastFetched: number | null; // Timestamp of last successful fetch
+  opencodeModelsLastFailedAt: number | null; // Timestamp of last failed fetch
+
+  // Gemini CLI Settings (global)
+  enabledGeminiModels: GeminiModelId[]; // Which Gemini models are available in feature modal
+  geminiDefaultModel: GeminiModelId; // Default Gemini model selection
+
+  // Copilot SDK Settings (global)
+  enabledCopilotModels: CopilotModelId[]; // Which Copilot models are available in feature modal
+  copilotDefaultModel: CopilotModelId; // Default Copilot model selection
+
+  // Provider Visibility Settings
+  disabledProviders: ModelProvider[]; // Providers that are disabled and hidden from dropdowns
+
+  // Claude Agent SDK Settings
+  autoLoadClaudeMd: boolean; // Auto-load CLAUDE.md files using SDK's settingSources option
+  skipSandboxWarning: boolean; // Skip the sandbox environment warning dialog on startup
+
+  // MCP Servers
+  mcpServers: MCPServerConfig[]; // List of configured MCP servers for agent use
+
+  // Editor Configuration
+  defaultEditorCommand: string | null; // Default editor for "Open In" action
+
+  // Terminal Configuration
+  defaultTerminalId: string | null; // Default external terminal for "Open In Terminal" action (null = integrated)
+
+  // Skills Configuration
+  enableSkills: boolean; // Enable Skills functionality (loads from .claude/skills/ directories)
+  skillsSources: Array<'user' | 'project'>; // Which directories to load Skills from
+
+  // Subagents Configuration
+  enableSubagents: boolean; // Enable Custom Subagents functionality (loads from .claude/agents/ directories)
+  subagentsSources: Array<'user' | 'project'>; // Which directories to load Subagents from
+
+  // Prompt Customization
+  promptCustomization: PromptCustomization; // Custom prompts for Auto Mode, Agent, Backlog Plan, Enhancement
+
+  // Event Hooks
+  eventHooks: EventHook[]; // Event hooks for custom commands or webhooks
+
+  // Claude-Compatible Providers (new system)
+  claudeCompatibleProviders: ClaudeCompatibleProvider[]; // Providers that expose models to dropdowns
+
+  // Claude API Profiles (deprecated - kept for backward compatibility)
+  claudeApiProfiles: ClaudeApiProfile[]; // Claude-compatible API endpoint profiles
+  activeClaudeApiProfileId: string | null; // Active profile ID (null = use direct Anthropic API)
+
+  // Project Analysis
+  projectAnalysis: ProjectAnalysis | null;
+  isAnalyzing: boolean;
+
+  // Board Background Settings (per-project, keyed by project path)
+  boardBackgroundByProject: Record<string, BackgroundSettings>;
+
+  // Theme Preview (for hover preview in theme selectors)
+  previewTheme: ThemeMode | null;
+
+  // Terminal state
+  terminalState: TerminalState;
+
+  // Terminal layout persistence (per-project, keyed by project path)
+  // Stores the tab/split structure so it can be restored when switching projects
+  terminalLayoutByProject: Record<string, PersistedTerminalState>;
+
+  // Spec Creation State (per-project, keyed by project path)
+  // Tracks which project is currently having its spec generated
+  specCreatingForProject: string | null;
+
+  defaultPlanningMode: PlanningMode;
+  defaultRequirePlanApproval: boolean;
+  defaultFeatureModel: PhaseModelEntry;
+
+  // Plan Approval State
+  // When a plan requires user approval, this holds the pending approval details
+  pendingPlanApproval: {
+    featureId: string;
+    projectPath: string;
+    planContent: string;
+    planningMode: 'lite' | 'spec' | 'full';
+  } | null;
+
+  // Claude Usage Tracking
+  claudeRefreshInterval: number; // Refresh interval in seconds (default: 60)
+  claudeUsage: ClaudeUsage | null;
+  claudeUsageLastUpdated: number | null;
+
+  // Codex Usage Tracking
+  codexUsage: CodexUsage | null;
+  codexUsageLastUpdated: number | null;
+
+  // Codex Models (dynamically fetched)
+  codexModels: Array<{
+    id: string;
+    label: string;
+    description: string;
+    hasThinking: boolean;
+    supportsVision: boolean;
+    tier: 'premium' | 'standard' | 'basic';
+    isDefault: boolean;
+  }>;
+  codexModelsLoading: boolean;
+  codexModelsError: string | null;
+  codexModelsLastFetched: number | null;
+  codexModelsLastFailedAt: number | null;
+
+  // Pipeline Configuration (per-project, keyed by project path)
+  pipelineConfigByProject: Record<string, PipelineConfig>;
+
+  // Worktree Panel Visibility (per-project, keyed by project path)
+  // Whether the worktree panel row is visible (default: true)
+  worktreePanelVisibleByProject: Record<string, boolean>;
+
+  // Init Script Indicator Visibility (per-project, keyed by project path)
+  // Whether to show the floating init script indicator panel (default: true)
+  showInitScriptIndicatorByProject: Record<string, boolean>;
+
+  // Default Delete Branch With Worktree (per-project, keyed by project path)
+  // Whether to default the "delete branch" checkbox when deleting a worktree (default: false)
+  defaultDeleteBranchByProject: Record<string, boolean>;
+
+  // Auto-dismiss Init Script Indicator (per-project, keyed by project path)
+  // Whether to auto-dismiss the indicator after completion (default: true)
+  autoDismissInitScriptIndicatorByProject: Record<string, boolean>;
+
+  // Use Worktrees Override (per-project, keyed by project path)
+  // undefined = use global setting, true/false = project-specific override
+  useWorktreesByProject: Record<string, boolean | undefined>;
+
+  // UI State (previously in localStorage, now synced via API)
+  /** Whether worktree panel is collapsed in board view */
+  worktreePanelCollapsed: boolean;
+  /** Last directory opened in file picker */
+  lastProjectDir: string;
+  /** Recently accessed folders for quick access */
+  recentFolders: string[];
+
+  // Init Script State (keyed by "projectPath::branch" to support concurrent scripts)
+  initScriptState: Record<string, InitScriptState>;
+}
+
+export interface AppActions {
+  // Project actions
+  setProjects: (projects: Project[]) => void;
+  addProject: (project: Project) => void;
+  removeProject: (projectId: string) => void;
+  moveProjectToTrash: (projectId: string) => void;
+  restoreTrashedProject: (projectId: string) => void;
+  deleteTrashedProject: (projectId: string) => void;
+  emptyTrash: () => void;
+  setCurrentProject: (project: Project | null) => void;
+  upsertAndSetCurrentProject: (path: string, name: string, theme?: ThemeMode) => Project; // Upsert project by path and set as current
+  reorderProjects: (oldIndex: number, newIndex: number) => void;
+  cyclePrevProject: () => void; // Cycle back through project history (Q)
+  cycleNextProject: () => void; // Cycle forward through project history (E)
+  clearProjectHistory: () => void; // Clear history, keeping only current project
+  toggleProjectFavorite: (projectId: string) => void; // Toggle project favorite status
+  setProjectIcon: (projectId: string, icon: string | null) => void; // Set project icon (null to clear)
+  setProjectCustomIcon: (projectId: string, customIconPath: string | null) => void; // Set custom project icon image path (null to clear)
+  setProjectName: (projectId: string, name: string) => void; // Update project name
+
+  // View actions
+  setCurrentView: (view: ViewMode) => void;
+  toggleSidebar: () => void;
+  setSidebarOpen: (open: boolean) => void;
+  setSidebarStyle: (style: SidebarStyle) => void;
+  setCollapsedNavSections: (sections: Record<string, boolean>) => void;
+  toggleNavSection: (sectionLabel: string) => void;
+  toggleMobileSidebarHidden: () => void;
+  setMobileSidebarHidden: (hidden: boolean) => void;
+
+  // Theme actions
+  setTheme: (theme: ThemeMode) => void;
+  setProjectTheme: (projectId: string, theme: ThemeMode | null) => void; // Set per-project theme (null to clear)
+  getEffectiveTheme: () => ThemeMode; // Get the effective theme (project, global, or preview if set)
+  setPreviewTheme: (theme: ThemeMode | null) => void; // Set preview theme for hover preview (null to clear)
+
+  // Font actions (global + per-project override)
+  setFontSans: (fontFamily: string | null) => void; // Set global UI/sans font (null to clear)
+  setFontMono: (fontFamily: string | null) => void; // Set global code/mono font (null to clear)
+  setProjectFontSans: (projectId: string, fontFamily: string | null) => void; // Set per-project UI/sans font override (null = use global)
+  setProjectFontMono: (projectId: string, fontFamily: string | null) => void; // Set per-project code/mono font override (null = use global)
+  getEffectiveFontSans: () => string | null; // Get effective UI font (project override -> global -> null for default)
+  getEffectiveFontMono: () => string | null; // Get effective code font (project override -> global -> null for default)
+
+  // Claude API Profile actions (per-project override)
+  /** @deprecated Use setProjectPhaseModelOverride instead */
+  setProjectClaudeApiProfile: (projectId: string, profileId: string | null | undefined) => void; // Set per-project Claude API profile (undefined = use global, null = direct API, string = specific profile)
+
+  // Project Phase Model Overrides
+  setProjectPhaseModelOverride: (
+    projectId: string,
+    phase: PhaseModelKey,
+    entry: PhaseModelEntry | null // null = use global
+  ) => void;
+  clearAllProjectPhaseModelOverrides: (projectId: string) => void;
+
+  // Project Default Feature Model Override
+  setProjectDefaultFeatureModel: (
+    projectId: string,
+    entry: PhaseModelEntry | null // null = use global
+  ) => void;
+
+  // Feature actions
+  setFeatures: (features: Feature[]) => void;
+  updateFeature: (id: string, updates: Partial<Feature>) => void;
+  addFeature: (feature: Omit<Feature, 'id'> & Partial<Pick<Feature, 'id'>>) => Feature;
+  removeFeature: (id: string) => void;
+  moveFeature: (id: string, newStatus: Feature['status']) => void;
+
+  // App spec actions
+  setAppSpec: (spec: string) => void;
+
+  // IPC actions
+  setIpcConnected: (connected: boolean) => void;
+
+  // API Keys actions
+  setApiKeys: (keys: Partial<ApiKeys>) => void;
+
+  // Chat Session actions
+  createChatSession: (title?: string) => ChatSession;
+  updateChatSession: (sessionId: string, updates: Partial<ChatSession>) => void;
+  addMessageToSession: (sessionId: string, message: ChatMessage) => void;
+  setCurrentChatSession: (session: ChatSession | null) => void;
+  archiveChatSession: (sessionId: string) => void;
+  unarchiveChatSession: (sessionId: string) => void;
+  deleteChatSession: (sessionId: string) => void;
+  setChatHistoryOpen: (open: boolean) => void;
+  toggleChatHistory: () => void;
+
+  // Auto Mode actions (per-worktree)
+  setAutoModeRunning: (
+    projectId: string,
+    branchName: string | null,
+    running: boolean,
+    maxConcurrency?: number,
+    runningTasks?: string[]
+  ) => void;
+  addRunningTask: (projectId: string, branchName: string | null, taskId: string) => void;
+  removeRunningTask: (projectId: string, branchName: string | null, taskId: string) => void;
+  clearRunningTasks: (projectId: string, branchName: string | null) => void;
+  getAutoModeState: (
+    projectId: string,
+    branchName: string | null
+  ) => {
+    isRunning: boolean;
+    runningTasks: string[];
+    branchName: string | null;
+    maxConcurrency?: number;
+  };
+  /** Helper to generate worktree key from projectId and branchName */
+  getWorktreeKey: (projectId: string, branchName: string | null) => string;
+  addAutoModeActivity: (activity: Omit<AutoModeActivity, 'id' | 'timestamp'>) => void;
+  clearAutoModeActivity: () => void;
+  setMaxConcurrency: (max: number) => void; // Legacy: kept for backward compatibility
+  getMaxConcurrencyForWorktree: (projectId: string, branchName: string | null) => number;
+  setMaxConcurrencyForWorktree: (
+    projectId: string,
+    branchName: string | null,
+    maxConcurrency: number
+  ) => void;
+
+  // Kanban Card Settings actions
+  setBoardViewMode: (mode: BoardViewMode) => void;
+
+  // Feature Default Settings actions
+  setDefaultSkipTests: (skip: boolean) => void;
+  setEnableDependencyBlocking: (enabled: boolean) => void;
+  setSkipVerificationInAutoMode: (enabled: boolean) => Promise<void>;
+  setEnableAiCommitMessages: (enabled: boolean) => Promise<void>;
+  setPlanUseSelectedWorktreeBranch: (enabled: boolean) => Promise<void>;
+  setAddFeatureUseSelectedWorktreeBranch: (enabled: boolean) => Promise<void>;
+
+  // Worktree Settings actions
+  setUseWorktrees: (enabled: boolean) => void;
+  setCurrentWorktree: (projectPath: string, worktreePath: string | null, branch: string) => void;
+  setWorktrees: (
+    projectPath: string,
+    worktrees: Array<{
+      path: string;
+      branch: string;
+      isMain: boolean;
+      isCurrent: boolean;
+      hasWorktree: boolean;
+      hasChanges?: boolean;
+      changedFilesCount?: number;
+    }>
+  ) => void;
+  getCurrentWorktree: (projectPath: string) => { path: string | null; branch: string } | null;
+  getWorktrees: (projectPath: string) => Array<{
+    path: string;
+    branch: string;
+    isMain: boolean;
+    isCurrent: boolean;
+    hasWorktree: boolean;
+    hasChanges?: boolean;
+    changedFilesCount?: number;
+  }>;
+  isPrimaryWorktreeBranch: (projectPath: string, branchName: string) => boolean;
+  getPrimaryWorktreeBranch: (projectPath: string) => string | null;
+
+  // Keyboard Shortcuts actions
+  setKeyboardShortcut: (key: keyof KeyboardShortcuts, value: string) => void;
+  setKeyboardShortcuts: (shortcuts: Partial<KeyboardShortcuts>) => void;
+  resetKeyboardShortcuts: () => void;
+
+  // Audio Settings actions
+  setMuteDoneSound: (muted: boolean) => void;
+
+  // Splash Screen actions
+  setDisableSplashScreen: (disabled: boolean) => void;
+
+  // Server Log Level actions
+  setServerLogLevel: (level: ServerLogLevel) => void;
+  setEnableRequestLogging: (enabled: boolean) => void;
+
+  // Developer Tools actions
+  setShowQueryDevtools: (show: boolean) => void;
+
+  // Enhancement Model actions
+  setEnhancementModel: (model: ModelAlias) => void;
+
+  // Validation Model actions
+  setValidationModel: (model: ModelAlias) => void;
+
+  // Phase Model actions
+  setPhaseModel: (phase: PhaseModelKey, entry: PhaseModelEntry) => Promise<void>;
+  setPhaseModels: (models: Partial<PhaseModelConfig>) => Promise<void>;
+  resetPhaseModels: () => Promise<void>;
+  toggleFavoriteModel: (modelId: string) => void;
+
+  // Cursor CLI Settings actions
+  setEnabledCursorModels: (models: CursorModelId[]) => void;
+  setCursorDefaultModel: (model: CursorModelId) => void;
+  toggleCursorModel: (model: CursorModelId, enabled: boolean) => void;
+
+  // Codex CLI Settings actions
+  setEnabledCodexModels: (models: CodexModelId[]) => void;
+  setCodexDefaultModel: (model: CodexModelId) => void;
+  toggleCodexModel: (model: CodexModelId, enabled: boolean) => void;
+  setCodexAutoLoadAgents: (enabled: boolean) => Promise<void>;
+  setCodexSandboxMode: (
+    mode: 'read-only' | 'workspace-write' | 'danger-full-access'
+  ) => Promise<void>;
+  setCodexApprovalPolicy: (
+    policy: 'untrusted' | 'on-failure' | 'on-request' | 'never'
+  ) => Promise<void>;
+  setCodexEnableWebSearch: (enabled: boolean) => Promise<void>;
+  setCodexEnableImages: (enabled: boolean) => Promise<void>;
+
+  // OpenCode CLI Settings actions
+  setEnabledOpencodeModels: (models: OpencodeModelId[]) => void;
+  setOpencodeDefaultModel: (model: OpencodeModelId) => void;
+  toggleOpencodeModel: (model: OpencodeModelId, enabled: boolean) => void;
+  setDynamicOpencodeModels: (models: ModelDefinition[]) => void;
+  setEnabledDynamicModelIds: (ids: string[]) => void;
+  toggleDynamicModel: (modelId: string, enabled: boolean) => void;
+  setCachedOpencodeProviders: (
+    providers: Array<{ id: string; name: string; authenticated: boolean; authMethod?: string }>
+  ) => void;
+
+  // Gemini CLI Settings actions
+  setEnabledGeminiModels: (models: GeminiModelId[]) => void;
+  setGeminiDefaultModel: (model: GeminiModelId) => void;
+  toggleGeminiModel: (model: GeminiModelId, enabled: boolean) => void;
+
+  // Copilot SDK Settings actions
+  setEnabledCopilotModels: (models: CopilotModelId[]) => void;
+  setCopilotDefaultModel: (model: CopilotModelId) => void;
+  toggleCopilotModel: (model: CopilotModelId, enabled: boolean) => void;
+
+  // Provider Visibility Settings actions
+  setDisabledProviders: (providers: ModelProvider[]) => void;
+  toggleProviderDisabled: (provider: ModelProvider, disabled: boolean) => void;
+  isProviderDisabled: (provider: ModelProvider) => boolean;
+
+  // Claude Agent SDK Settings actions
+  setAutoLoadClaudeMd: (enabled: boolean) => Promise<void>;
+  setSkipSandboxWarning: (skip: boolean) => Promise<void>;
+
+  // Editor Configuration actions
+  setDefaultEditorCommand: (command: string | null) => void;
+
+  // Terminal Configuration actions
+  setDefaultTerminalId: (terminalId: string | null) => void;
+
+  // Prompt Customization actions
+  setPromptCustomization: (customization: PromptCustomization) => Promise<void>;
+
+  // Event Hook actions
+  setEventHooks: (hooks: EventHook[]) => void;
+
+  // Claude-Compatible Provider actions (new system)
+  addClaudeCompatibleProvider: (provider: ClaudeCompatibleProvider) => Promise<void>;
+  updateClaudeCompatibleProvider: (
+    id: string,
+    updates: Partial<ClaudeCompatibleProvider>
+  ) => Promise<void>;
+  deleteClaudeCompatibleProvider: (id: string) => Promise<void>;
+  setClaudeCompatibleProviders: (providers: ClaudeCompatibleProvider[]) => Promise<void>;
+  toggleClaudeCompatibleProviderEnabled: (id: string) => Promise<void>;
+
+  // Claude API Profile actions (deprecated - kept for backward compatibility)
+  addClaudeApiProfile: (profile: ClaudeApiProfile) => Promise<void>;
+  updateClaudeApiProfile: (id: string, updates: Partial<ClaudeApiProfile>) => Promise<void>;
+  deleteClaudeApiProfile: (id: string) => Promise<void>;
+  setActiveClaudeApiProfile: (id: string | null) => Promise<void>;
+  setClaudeApiProfiles: (profiles: ClaudeApiProfile[]) => Promise<void>;
+
+  // MCP Server actions
+  addMCPServer: (server: Omit<MCPServerConfig, 'id'>) => void;
+  updateMCPServer: (id: string, updates: Partial<MCPServerConfig>) => void;
+  removeMCPServer: (id: string) => void;
+  reorderMCPServers: (oldIndex: number, newIndex: number) => void;
+
+  // Project Analysis actions
+  setProjectAnalysis: (analysis: ProjectAnalysis | null) => void;
+  setIsAnalyzing: (analyzing: boolean) => void;
+  clearAnalysis: () => void;
+
+  // Agent Session actions
+  setLastSelectedSession: (projectPath: string, sessionId: string | null) => void;
+  getLastSelectedSession: (projectPath: string) => string | null;
+
+  // Board Background actions
+  setBoardBackground: (projectPath: string, imagePath: string | null) => void;
+  setCardOpacity: (projectPath: string, opacity: number) => void;
+  setColumnOpacity: (projectPath: string, opacity: number) => void;
+  setColumnBorderEnabled: (projectPath: string, enabled: boolean) => void;
+  getBoardBackground: (projectPath: string) => {
+    imagePath: string | null;
+    cardOpacity: number;
+    columnOpacity: number;
+    columnBorderEnabled: boolean;
+    cardGlassmorphism: boolean;
+    cardBorderEnabled: boolean;
+    cardBorderOpacity: number;
+    hideScrollbar: boolean;
+  };
+  setCardGlassmorphism: (projectPath: string, enabled: boolean) => void;
+  setCardBorderEnabled: (projectPath: string, enabled: boolean) => void;
+  setCardBorderOpacity: (projectPath: string, opacity: number) => void;
+  setHideScrollbar: (projectPath: string, hide: boolean) => void;
+  clearBoardBackground: (projectPath: string) => void;
+
+  // Terminal actions
+  setTerminalUnlocked: (unlocked: boolean, token?: string) => void;
+  setActiveTerminalSession: (sessionId: string | null) => void;
+  toggleTerminalMaximized: (sessionId: string) => void;
+  addTerminalToLayout: (
+    sessionId: string,
+    direction?: 'horizontal' | 'vertical',
+    targetSessionId?: string,
+    branchName?: string
+  ) => void;
+  removeTerminalFromLayout: (sessionId: string) => void;
+  swapTerminals: (sessionId1: string, sessionId2: string) => void;
+  clearTerminalState: () => void;
+  setTerminalPanelFontSize: (sessionId: string, fontSize: number) => void;
+  setTerminalDefaultFontSize: (fontSize: number) => void;
+  setTerminalDefaultRunScript: (script: string) => void;
+  setTerminalScreenReaderMode: (enabled: boolean) => void;
+  setTerminalFontFamily: (fontFamily: string) => void;
+  setTerminalScrollbackLines: (lines: number) => void;
+  setTerminalLineHeight: (lineHeight: number) => void;
+  setTerminalMaxSessions: (maxSessions: number) => void;
+  setTerminalLastActiveProjectPath: (projectPath: string | null) => void;
+  setOpenTerminalMode: (mode: 'newTab' | 'split') => void;
+  addTerminalTab: (name?: string) => string;
+  removeTerminalTab: (tabId: string) => void;
+  setActiveTerminalTab: (tabId: string) => void;
+  renameTerminalTab: (tabId: string, name: string) => void;
+  reorderTerminalTabs: (fromTabId: string, toTabId: string) => void;
+  moveTerminalToTab: (sessionId: string, targetTabId: string | 'new') => void;
+  addTerminalToTab: (
+    sessionId: string,
+    tabId: string,
+    direction?: 'horizontal' | 'vertical',
+    branchName?: string
+  ) => void;
+  setTerminalTabLayout: (
+    tabId: string,
+    layout: TerminalPanelContent,
+    activeSessionId?: string
+  ) => void;
+  updateTerminalPanelSizes: (tabId: string, panelKeys: string[], sizes: number[]) => void;
+  saveTerminalLayout: (projectPath: string) => void;
+  getPersistedTerminalLayout: (projectPath: string) => PersistedTerminalState | null;
+  clearPersistedTerminalLayout: (projectPath: string) => void;
+
+  // Spec Creation actions
+  setSpecCreatingForProject: (projectPath: string | null) => void;
+  isSpecCreatingForProject: (projectPath: string) => boolean;
+
+  setDefaultPlanningMode: (mode: PlanningMode) => void;
+  setDefaultRequirePlanApproval: (require: boolean) => void;
+  setDefaultFeatureModel: (entry: PhaseModelEntry) => void;
+
+  // Plan Approval actions
+  setPendingPlanApproval: (
+    approval: {
+      featureId: string;
+      projectPath: string;
+      planContent: string;
+      planningMode: 'lite' | 'spec' | 'full';
+    } | null
+  ) => void;
+
+  // Pipeline actions
+  setPipelineConfig: (projectPath: string, config: PipelineConfig) => void;
+  getPipelineConfig: (projectPath: string) => PipelineConfig | null;
+  addPipelineStep: (
+    projectPath: string,
+    step: Omit<PipelineStep, 'id' | 'createdAt' | 'updatedAt'>
+  ) => PipelineStep;
+  updatePipelineStep: (
+    projectPath: string,
+    stepId: string,
+    updates: Partial<Omit<PipelineStep, 'id' | 'createdAt'>>
+  ) => void;
+  deletePipelineStep: (projectPath: string, stepId: string) => void;
+  reorderPipelineSteps: (projectPath: string, stepIds: string[]) => void;
+
+  // Worktree Panel Visibility actions (per-project)
+  setWorktreePanelVisible: (projectPath: string, visible: boolean) => void;
+  getWorktreePanelVisible: (projectPath: string) => boolean;
+
+  // Init Script Indicator Visibility actions (per-project)
+  setShowInitScriptIndicator: (projectPath: string, visible: boolean) => void;
+  getShowInitScriptIndicator: (projectPath: string) => boolean;
+
+  // Default Delete Branch actions (per-project)
+  setDefaultDeleteBranch: (projectPath: string, deleteBranch: boolean) => void;
+  getDefaultDeleteBranch: (projectPath: string) => boolean;
+
+  // Auto-dismiss Init Script Indicator actions (per-project)
+  setAutoDismissInitScriptIndicator: (projectPath: string, autoDismiss: boolean) => void;
+  getAutoDismissInitScriptIndicator: (projectPath: string) => boolean;
+
+  // Use Worktrees Override actions (per-project)
+  setProjectUseWorktrees: (projectPath: string, useWorktrees: boolean | null) => void; // null = use global
+  getProjectUseWorktrees: (projectPath: string) => boolean | undefined; // undefined = using global
+  getEffectiveUseWorktrees: (projectPath: string) => boolean; // Returns actual value (project or global fallback)
+
+  // UI State actions (previously in localStorage, now synced via API)
+  setWorktreePanelCollapsed: (collapsed: boolean) => void;
+  setLastProjectDir: (dir: string) => void;
+  setRecentFolders: (folders: string[]) => void;
+  addRecentFolder: (folder: string) => void;
+
+  // Claude Usage Tracking actions
+  setClaudeRefreshInterval: (interval: number) => void;
+  setClaudeUsageLastUpdated: (timestamp: number) => void;
+  setClaudeUsage: (usage: ClaudeUsage | null) => void;
+
+  // Codex Usage Tracking actions
+  setCodexUsage: (usage: CodexUsage | null) => void;
+
+  // Codex Models actions
+  fetchCodexModels: (forceRefresh?: boolean) => Promise<void>;
+  setCodexModels: (
+    models: Array<{
+      id: string;
+      label: string;
+      description: string;
+      hasThinking: boolean;
+      supportsVision: boolean;
+      tier: 'premium' | 'standard' | 'basic';
+      isDefault: boolean;
+    }>
+  ) => void;
+
+  // OpenCode Models actions
+  fetchOpencodeModels: (forceRefresh?: boolean) => Promise<void>;
+
+  // Init Script State actions (keyed by projectPath::branch to support concurrent scripts)
+  setInitScriptState: (
+    projectPath: string,
+    branch: string,
+    state: Partial<InitScriptState>
+  ) => void;
+  appendInitScriptOutput: (projectPath: string, branch: string, content: string) => void;
+  clearInitScriptState: (projectPath: string, branch: string) => void;
+  getInitScriptState: (projectPath: string, branch: string) => InitScriptState | null;
+  getInitScriptStatesForProject: (
+    projectPath: string
+  ) => Array<{ key: string; state: InitScriptState }>;
+
+  // Reset
+  reset: () => void;
+}

apps/ui/src/store/types/terminal-types.ts

@@ -0,0 +1,82 @@
+// Terminal panel layout types (recursive for splits)
+export type TerminalPanelContent =
+  | { type: 'terminal'; sessionId: string; size?: number; fontSize?: number; branchName?: string }
+  | { type: 'testRunner'; sessionId: string; size?: number; worktreePath: string }
+  | {
+      type: 'split';
+      id: string; // Stable ID for React key stability
+      direction: 'horizontal' | 'vertical';
+      panels: TerminalPanelContent[];
+      size?: number;
+    };
+
+// Terminal tab - each tab has its own layout
+export interface TerminalTab {
+  id: string;
+  name: string;
+  layout: TerminalPanelContent | null;
+}
+
+export interface TerminalState {
+  isUnlocked: boolean;
+  authToken: string | null;
+  tabs: TerminalTab[];
+  activeTabId: string | null;
+  activeSessionId: string | null;
+  maximizedSessionId: string | null; // Session ID of the maximized terminal pane (null if none)
+  defaultFontSize: number; // Default font size for new terminals
+  defaultRunScript: string; // Script to run when a new terminal is created (e.g., "claude" to start Claude Code)
+  screenReaderMode: boolean; // Enable screen reader accessibility mode
+  fontFamily: string; // Font family for terminal text
+  scrollbackLines: number; // Number of lines to keep in scrollback buffer
+  lineHeight: number; // Line height multiplier for terminal text
+  maxSessions: number; // Maximum concurrent terminal sessions (server setting)
+  lastActiveProjectPath: string | null; // Last project path to detect route changes vs project switches
+  openTerminalMode: 'newTab' | 'split'; // How to open terminals from "Open in Terminal" action
+}
+
+// Persisted terminal layout - now includes sessionIds for reconnection
+// Used to restore terminal layout structure when switching projects
+export type PersistedTerminalPanel =
+  | { type: 'terminal'; size?: number; fontSize?: number; sessionId?: string; branchName?: string }
+  | { type: 'testRunner'; size?: number; sessionId?: string; worktreePath?: string }
+  | {
+      type: 'split';
+      id?: string; // Optional for backwards compatibility with older persisted layouts
+      direction: 'horizontal' | 'vertical';
+      panels: PersistedTerminalPanel[];
+      size?: number;
+    };
+
+// Helper to generate unique split IDs
+export const generateSplitId = () =>
+  `split-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+export interface PersistedTerminalTab {
+  id: string;
+  name: string;
+  layout: PersistedTerminalPanel | null;
+}
+
+export interface PersistedTerminalState {
+  tabs: PersistedTerminalTab[];
+  activeTabIndex: number; // Use index instead of ID since IDs are regenerated
+  defaultFontSize: number;
+  defaultRunScript?: string; // Optional to support existing persisted data
+  screenReaderMode?: boolean; // Optional to support existing persisted data
+  fontFamily?: string; // Optional to support existing persisted data
+  scrollbackLines?: number; // Optional to support existing persisted data
+  lineHeight?: number; // Optional to support existing persisted data
+}
+
+// Persisted terminal settings - stored globally (not per-project)
+export interface PersistedTerminalSettings {
+  defaultFontSize: number;
+  defaultRunScript: string;
+  screenReaderMode: boolean;
+  fontFamily: string;
+  scrollbackLines: number;
+  lineHeight: number;
+  maxSessions: number;
+  openTerminalMode: 'newTab' | 'split';
+}

apps/ui/src/store/types/ui-types.ts

@@ -0,0 +1,119 @@
+export type ViewMode =
+  | 'welcome'
+  | 'setup'
+  | 'spec'
+  | 'board'
+  | 'agent'
+  | 'settings'
+  | 'interview'
+  | 'context'
+  | 'running-agents'
+  | 'terminal'
+  | 'wiki'
+  | 'ideation';
+
+export type ThemeMode =
+  // Special modes
+  | 'system'
+  // Dark themes
+  | 'dark'
+  | 'retro'
+  | 'dracula'
+  | 'nord'
+  | 'monokai'
+  | 'tokyonight'
+  | 'solarized'
+  | 'gruvbox'
+  | 'catppuccin'
+  | 'onedark'
+  | 'synthwave'
+  | 'red'
+  | 'sunset'
+  | 'gray'
+  | 'forest'
+  | 'ocean'
+  | 'ember'
+  | 'ayu-dark'
+  | 'ayu-mirage'
+  | 'matcha'
+  // Light themes
+  | 'light'
+  | 'cream'
+  | 'solarizedlight'
+  | 'github'
+  | 'paper'
+  | 'rose'
+  | 'mint'
+  | 'lavender'
+  | 'sand'
+  | 'sky'
+  | 'peach'
+  | 'snow'
+  | 'sepia'
+  | 'gruvboxlight'
+  | 'nordlight'
+  | 'blossom'
+  | 'ayu-light'
+  | 'onelight'
+  | 'bluloco'
+  | 'feather';
+
+export type BoardViewMode = 'kanban' | 'graph';
+
+// Keyboard Shortcut with optional modifiers
+export interface ShortcutKey {
+  key: string; // The main key (e.g., "K", "N", "1")
+  shift?: boolean; // Shift key modifier
+  cmdCtrl?: boolean; // Cmd on Mac, Ctrl on Windows/Linux
+  alt?: boolean; // Alt/Option key modifier
+}
+
+// Board background settings
+export interface BackgroundSettings {
+  imagePath: string | null;
+  imageVersion?: number;
+  cardOpacity: number;
+  columnOpacity: number;
+  columnBorderEnabled: boolean;
+  cardGlassmorphism: boolean;
+  cardBorderEnabled: boolean;
+  cardBorderOpacity: number;
+  hideScrollbar: boolean;
+}
+
+// Keyboard Shortcuts - stored as strings like "K", "Shift+N", "Cmd+K"
+export interface KeyboardShortcuts {
+  // Navigation shortcuts
+  board: string;
+  graph: string;
+  agent: string;
+  spec: string;
+  context: string;
+  memory: string;
+  settings: string;
+  projectSettings: string;
+  terminal: string;
+  ideation: string;
+  notifications: string;
+  githubIssues: string;
+  githubPrs: string;
+
+  // UI shortcuts
+  toggleSidebar: string;
+
+  // Action shortcuts
+  addFeature: string;
+  addContextFile: string;
+  startNext: string;
+  newSession: string;
+  openProject: string;
+  projectPicker: string;
+  cyclePrevProject: string;
+  cycleNextProject: string;
+
+  // Terminal shortcuts
+  splitTerminalRight: string;
+  splitTerminalDown: string;
+  closeTerminal: string;
+  newTerminalTab: string;
+}

apps/ui/src/store/types/usage-types.ts

@@ -0,0 +1,60 @@
+// Claude Usage interface matching the server response
+export type ClaudeUsage = {
+  sessionTokensUsed: number;
+  sessionLimit: number;
+  sessionPercentage: number;
+  sessionResetTime: string;
+  sessionResetText: string;
+
+  weeklyTokensUsed: number;
+  weeklyLimit: number;
+  weeklyPercentage: number;
+  weeklyResetTime: string;
+  weeklyResetText: string;
+
+  sonnetWeeklyTokensUsed: number;
+  sonnetWeeklyPercentage: number;
+  sonnetResetText: string;
+
+  costUsed: number | null;
+  costLimit: number | null;
+  costCurrency: string | null;
+
+  lastUpdated: string;
+  userTimezone: string;
+};
+
+// Response type for Claude usage API (can be success or error)
+export type ClaudeUsageResponse = ClaudeUsage | { error: string; message?: string };
+
+// Codex Usage types
+export type CodexPlanType =
+  | 'free'
+  | 'plus'
+  | 'pro'
+  | 'team'
+  | 'business'
+  | 'enterprise'
+  | 'edu'
+  | 'unknown';
+
+export interface CodexRateLimitWindow {
+  limit: number;
+  used: number;
+  remaining: number;
+  usedPercent: number; // Percentage used (0-100)
+  windowDurationMins: number; // Duration in minutes
+  resetsAt: number; // Unix timestamp in seconds
+}
+
+export interface CodexUsage {
+  rateLimits: {
+    primary?: CodexRateLimitWindow;
+    secondary?: CodexRateLimitWindow;
+    planType?: CodexPlanType;
+  } | null;
+  lastUpdated: string;
+}
+
+// Response type for Codex usage API (can be success or error)
+export type CodexUsageResponse = CodexUsage | { error: string; message?: string };

apps/ui/src/store/utils/index.ts

@@ -0,0 +1,13 @@
+// Theme utilities (PUBLIC)
+export {
+  THEME_STORAGE_KEY,
+  getStoredTheme,
+  getStoredFontSans,
+  getStoredFontMono,
+} from './theme-utils';
+
+// Shortcut utilities (PUBLIC)
+export { parseShortcut, formatShortcut, DEFAULT_KEYBOARD_SHORTCUTS } from './shortcut-utils';
+
+// Usage utilities (PUBLIC)
+export { isClaudeUsageAtLimit } from './usage-utils';

apps/ui/src/store/utils/shortcut-utils.ts

@@ -0,0 +1,117 @@
+import type { ShortcutKey, KeyboardShortcuts } from '../types/ui-types';
+
+// Helper to parse shortcut string to ShortcutKey object
+export function parseShortcut(shortcut: string | undefined | null): ShortcutKey {
+  if (!shortcut) return { key: '' };
+  const parts = shortcut.split('+').map((p) => p.trim());
+  const result: ShortcutKey = { key: parts[parts.length - 1] };
+
+  // Normalize common OS-specific modifiers (Cmd/Ctrl/Win/Super symbols) into cmdCtrl
+  for (let i = 0; i < parts.length - 1; i++) {
+    const modifier = parts[i].toLowerCase();
+    if (modifier === 'shift') result.shift = true;
+    else if (
+      modifier === 'cmd' ||
+      modifier === 'ctrl' ||
+      modifier === 'win' ||
+      modifier === 'super' ||
+      modifier === '⌘' ||
+      modifier === '^' ||
+      modifier === '⊞' ||
+      modifier === '◆'
+    )
+      result.cmdCtrl = true;
+    else if (modifier === 'alt' || modifier === 'opt' || modifier === 'option' || modifier === '⌥')
+      result.alt = true;
+  }
+
+  return result;
+}
+
+// Helper to format ShortcutKey to display string
+export function formatShortcut(shortcut: string | undefined | null, forDisplay = false): string {
+  if (!shortcut) return '';
+  const parsed = parseShortcut(shortcut);
+  const parts: string[] = [];
+
+  // Prefer User-Agent Client Hints when available; fall back to legacy
+  const platform: 'darwin' | 'win32' | 'linux' = (() => {
+    if (typeof navigator === 'undefined') return 'linux';
+
+    const uaPlatform = (
+      navigator as Navigator & { userAgentData?: { platform?: string } }
+    ).userAgentData?.platform?.toLowerCase?.();
+    const legacyPlatform = navigator.platform?.toLowerCase?.();
+    const platformString = uaPlatform || legacyPlatform || '';
+
+    if (platformString.includes('mac')) return 'darwin';
+    if (platformString.includes('win')) return 'win32';
+    return 'linux';
+  })();
+
+  // Primary modifier - OS-specific
+  if (parsed.cmdCtrl) {
+    if (forDisplay) {
+      parts.push(platform === 'darwin' ? '⌘' : platform === 'win32' ? '⊞' : '◆');
+    } else {
+      parts.push(platform === 'darwin' ? 'Cmd' : platform === 'win32' ? 'Win' : 'Super');
+    }
+  }
+
+  // Alt/Option
+  if (parsed.alt) {
+    parts.push(
+      forDisplay ? (platform === 'darwin' ? '⌥' : 'Alt') : platform === 'darwin' ? 'Opt' : 'Alt'
+    );
+  }
+
+  // Shift
+  if (parsed.shift) {
+    parts.push(forDisplay ? '⇧' : 'Shift');
+  }
+
+  parts.push(parsed.key.toUpperCase());
+
+  // Add spacing when displaying symbols
+  return parts.join(forDisplay ? ' ' : '+');
+}
+
+// Default keyboard shortcuts
+export const DEFAULT_KEYBOARD_SHORTCUTS: KeyboardShortcuts = {
+  // Navigation
+  board: 'K',
+  graph: 'H',
+  agent: 'A',
+  spec: 'D',
+  context: 'C',
+  memory: 'Y',
+  settings: 'S',
+  projectSettings: 'Shift+S',
+  terminal: 'T',
+  ideation: 'I',
+  notifications: 'X',
+  githubIssues: 'G',
+  githubPrs: 'R',
+
+  // UI
+  toggleSidebar: '`',
+
+  // Actions
+  // Note: Some shortcuts share the same key (e.g., "N" for addFeature, newSession)
+  // This is intentional as they are context-specific and only active in their respective views
+  addFeature: 'N', // Only active in board view
+  addContextFile: 'N', // Only active in context view
+  startNext: 'G', // Only active in board view
+  newSession: 'N', // Only active in agent view
+  openProject: 'O', // Global shortcut
+  projectPicker: 'P', // Global shortcut
+  cyclePrevProject: 'Q', // Global shortcut
+  cycleNextProject: 'E', // Global shortcut
+
+  // Terminal shortcuts (only active in terminal view)
+  // Using Alt modifier to avoid conflicts with both terminal signals AND browser shortcuts
+  splitTerminalRight: 'Alt+D',
+  splitTerminalDown: 'Alt+S',
+  closeTerminal: 'Alt+W',
+  newTerminalTab: 'Alt+T',
+};

apps/ui/src/store/utils/theme-utils.ts

@@ -0,0 +1,117 @@
+import { getItem, setItem, removeItem } from '@/lib/storage';
+import { DEFAULT_FONT_VALUE } from '@/config/ui-font-options';
+import type { Project } from '@/lib/electron';
+import type { ThemeMode } from '../types/ui-types';
+
+// LocalStorage keys for persistence (fallback when server settings aren't available)
+export const THEME_STORAGE_KEY = 'automaker:theme';
+const FONT_SANS_STORAGE_KEY = 'automaker:font-sans';
+const FONT_MONO_STORAGE_KEY = 'automaker:font-mono';
+
+/**
+ * Get the theme from localStorage as a fallback
+ * Used before server settings are loaded (e.g., on login/setup pages)
+ */
+export function getStoredTheme(): ThemeMode | null {
+  const stored = getItem(THEME_STORAGE_KEY);
+  if (stored) return stored as ThemeMode;
+
+  // Backwards compatibility: older versions stored theme inside the Zustand persist blob.
+  // We intentionally keep reading it as a fallback so users don't get a "default theme flash"
+  // on login/logged-out pages if THEME_STORAGE_KEY hasn't been written yet.
+  try {
+    const legacy = getItem('automaker-storage');
+    if (!legacy) return null;
+    interface LegacyStorageFormat {
+      state?: { theme?: string };
+      theme?: string;
+    }
+    const parsed = JSON.parse(legacy) as LegacyStorageFormat;
+    const theme = parsed.state?.theme ?? parsed.theme;
+    if (typeof theme === 'string' && theme.length > 0) {
+      return theme as ThemeMode;
+    }
+  } catch {
+    // Ignore legacy parse errors
+  }
+
+  return null;
+}
+
+/**
+ * Helper to get effective font value with validation
+ * Returns the font to use (project override -> global -> null for default)
+ * @param projectFont - The project-specific font override
+ * @param globalFont - The global font setting
+ * @param fontOptions - The list of valid font options for validation
+ */
+export function getEffectiveFont(
+  projectFont: string | undefined,
+  globalFont: string | null,
+  fontOptions: readonly { value: string; label: string }[]
+): string | null {
+  const isValidFont = (font: string | null | undefined): boolean => {
+    if (!font || font === DEFAULT_FONT_VALUE) return true;
+    return fontOptions.some((opt) => opt.value === font);
+  };
+
+  if (projectFont) {
+    if (isValidFont(projectFont)) {
+      return projectFont === DEFAULT_FONT_VALUE ? null : projectFont;
+    }
+    // Invalid project font -> fall through to check global font
+  }
+  if (!isValidFont(globalFont)) return null; // Fallback to default if font not in list
+  return globalFont === DEFAULT_FONT_VALUE ? null : globalFont;
+}
+
+/**
+ * Save theme to localStorage for immediate persistence
+ * This is used as a fallback when server settings can't be loaded
+ */
+export function saveThemeToStorage(theme: ThemeMode): void {
+  setItem(THEME_STORAGE_KEY, theme);
+}
+
+/**
+ * Get fonts from localStorage as a fallback
+ * Used before server settings are loaded (e.g., on login/setup pages)
+ */
+export function getStoredFontSans(): string | null {
+  return getItem(FONT_SANS_STORAGE_KEY);
+}
+
+export function getStoredFontMono(): string | null {
+  return getItem(FONT_MONO_STORAGE_KEY);
+}
+
+/**
+ * Save fonts to localStorage for immediate persistence
+ * This is used as a fallback when server settings can't be loaded
+ */
+export function saveFontSansToStorage(fontFamily: string | null): void {
+  if (fontFamily) {
+    setItem(FONT_SANS_STORAGE_KEY, fontFamily);
+  } else {
+    // Remove from storage if null (using default)
+    removeItem(FONT_SANS_STORAGE_KEY);
+  }
+}
+
+export function saveFontMonoToStorage(fontFamily: string | null): void {
+  if (fontFamily) {
+    setItem(FONT_MONO_STORAGE_KEY, fontFamily);
+  } else {
+    // Remove from storage if null (using default)
+    removeItem(FONT_MONO_STORAGE_KEY);
+  }
+}
+
+export function persistEffectiveThemeForProject(
+  project: Project | null,
+  fallbackTheme: ThemeMode
+): void {
+  const projectTheme = project?.theme as ThemeMode | undefined;
+  const themeToStore = projectTheme ?? fallbackTheme;
+  saveThemeToStorage(themeToStore);
+}

apps/ui/src/store/utils/usage-utils.ts

@@ -0,0 +1,34 @@
+import type { ClaudeUsage } from '../types/usage-types';
+
+/**
+ * Check if Claude usage is at its limit (any of: session >= 100%, weekly >= 100%, OR cost >= limit)
+ * Returns true if any limit is reached, meaning auto mode should pause feature pickup.
+ */
+export function isClaudeUsageAtLimit(claudeUsage: ClaudeUsage | null): boolean {
+  if (!claudeUsage) {
+    // No usage data available - don't block
+    return false;
+  }
+
+  // Check session limit (5-hour window)
+  if (claudeUsage.sessionPercentage >= 100) {
+    return true;
+  }
+
+  // Check weekly limit
+  if (claudeUsage.weeklyPercentage >= 100) {
+    return true;
+  }
+
+  // Check cost limit (if configured)
+  if (
+    claudeUsage.costLimit !== null &&
+    claudeUsage.costLimit > 0 &&
+    claudeUsage.costUsed !== null &&
+    claudeUsage.costUsed >= claudeUsage.costLimit
+  ) {
+    return true;
+  }
+
+  return false;
+}

apps/ui/tests/features/edit-feature.spec.ts

@@ -80,6 +80,7 @@ test.describe('Edit Feature', () => {
     await clickAddFeature(page);
     await fillAddFeatureDialog(page, originalDescription);
     await confirmAddFeature(page);
+    await page.waitForTimeout(2000);
 
     // Wait for the feature to appear in the backlog
     await expect(async () => {
@@ -88,7 +89,7 @@ test.describe('Edit Feature', () => {
         hasText: originalDescription,
       });
       expect(await featureCard.count()).toBeGreaterThan(0);
-    }).toPass({ timeout: 10000 });
+    }).toPass({ timeout: 20000 });
 
     // Get the feature ID from the card
     const featureCard = page

docs/terminal-custom-configs-plan.md

@@ -0,0 +1,632 @@
+# Implementation Plan: Custom Terminal Configurations with Theme Synchronization
+
+## Overview
+
+Implement custom shell configuration files (.bashrc, .zshrc) that automatically sync with Automaker's 40 themes, providing a seamless terminal experience where prompt colors match the app theme. This is an **opt-in feature** that creates configs in `.automaker/terminal/` without modifying user's existing RC files.
+
+## Architecture
+
+### Core Components
+
+1. **RC Generator** (`libs/platform/src/rc-generator.ts`) - NEW
+   - Template-based generation for bash/zsh/sh
+   - Theme-to-ANSI color mapping from hex values
+   - Git info integration (branch, dirty status)
+   - Prompt format templates (standard, minimal, powerline, starship-inspired)
+
+2. **RC File Manager** (`libs/platform/src/rc-file-manager.ts`) - NEW
+   - File I/O for `.automaker/terminal/` directory
+   - Version checking and regeneration logic
+   - Path resolution for different shells
+
+3. **Terminal Service** (`apps/server/src/services/terminal-service.ts`) - MODIFY
+   - Inject BASH_ENV/ZDOTDIR environment variables when spawning PTY
+   - Hook for theme change regeneration
+   - Backwards compatible (no change when disabled)
+
+4. **Settings Schema** (`libs/types/src/settings.ts`) - MODIFY
+   - Add `terminalConfig` to GlobalSettings and ProjectSettings
+   - Include enable toggle, prompt format, git info toggles, custom aliases/env vars
+
+5. **Settings UI** (`apps/ui/src/components/views/settings-view/terminal/terminal-config-section.tsx`) - NEW
+   - Enable/disable toggle with explanation
+   - Prompt format selector (4 formats)
+   - Git info toggles (branch/status)
+   - Custom aliases textarea
+   - Custom env vars key-value editor
+   - Live preview panel showing example prompt
+
+## File Structure
+
+```
+.automaker/terminal/
+├── bashrc.sh          # Bash config (sourced via BASH_ENV)
+├── zshrc.zsh          # Zsh config (via ZDOTDIR)
+├── common.sh          # Shared functions (git prompt, etc.)
+├── themes/
+│   ├── dark.sh        # Theme-specific color exports (40 files)
+│   ├── dracula.sh
+│   ├── nord.sh
+│   └── ... (38 more)
+├── version.txt        # RC file format version (for migrations)
+└── user-custom.sh     # User's additional customizations (optional)
+```
+
+## Implementation Steps
+
+### Step 1: Create RC Generator Package
+
+**File**: `libs/platform/src/rc-generator.ts`
+
+**Key Functions**:
+
+```typescript
+// Main generation functions
+export function generateBashrc(theme: ThemeMode, config: TerminalConfig): string;
+export function generateZshrc(theme: ThemeMode, config: TerminalConfig): string;
+export function generateCommonFunctions(): string;
+export function generateThemeColors(theme: ThemeMode): string;
+
+// Color mapping
+export function hexToXterm256(hex: string): number;
+export function getThemeANSIColors(terminalTheme: TerminalTheme): ANSIColors;
+```
+
+**Templates**:
+
+- Source user's original ~/.bashrc or ~/.zshrc first
+- Load theme colors from `themes/${AUTOMAKER_THEME}.sh`
+- Set custom PS1/PROMPT only if `AUTOMAKER_CUSTOM_PROMPT=true`
+- Include git prompt function: `automaker_git_prompt()`
+
+**Example bashrc.sh template**:
+
+```bash
+#!/bin/bash
+# Automaker Terminal Configuration v1.0
+
+# Source user's original bashrc first
+if [ -f "$HOME/.bashrc" ]; then
+    source "$HOME/.bashrc"
+fi
+
+# Load Automaker theme colors
+AUTOMAKER_THEME="${AUTOMAKER_THEME:-dark}"
+if [ -f "${BASH_SOURCE%/*}/themes/$AUTOMAKER_THEME.sh" ]; then
+    source "${BASH_SOURCE%/*}/themes/$AUTOMAKER_THEME.sh"
+fi
+
+# Load common functions (git prompt)
+source "${BASH_SOURCE%/*}/common.sh"
+
+# Set custom prompt (only if enabled)
+if [ "$AUTOMAKER_CUSTOM_PROMPT" = "true" ]; then
+    PS1="\[$COLOR_USER\]\u@\h\[$COLOR_RESET\] "
+    PS1="$PS1\[$COLOR_PATH\]\w\[$COLOR_RESET\]"
+    PS1="$PS1\$(automaker_git_prompt) "
+    PS1="$PS1\[$COLOR_PROMPT\]\$\[$COLOR_RESET\] "
+fi
+
+# Load user customizations (if exists)
+if [ -f "${BASH_SOURCE%/*}/user-custom.sh" ]; then
+    source "${BASH_SOURCE%/*}/user-custom.sh"
+fi
+```
+
+**Color Mapping Algorithm**:
+
+1. Get hex colors from `apps/ui/src/config/terminal-themes.ts` (TerminalTheme interface)
+2. Convert hex to RGB
+3. Map to closest xterm-256 color code using Euclidean distance in RGB space
+4. Generate ANSI escape codes: `\[\e[38;5;{code}m\]` for foreground
+
+### Step 2: Create RC File Manager
+
+**File**: `libs/platform/src/rc-file-manager.ts`
+
+**Key Functions**:
+
+```typescript
+export async function ensureTerminalDir(projectPath: string): Promise<void>;
+export async function writeRcFiles(
+  projectPath: string,
+  theme: ThemeMode,
+  config: TerminalConfig
+): Promise<void>;
+export function getRcFilePath(projectPath: string, shell: 'bash' | 'zsh' | 'sh'): string;
+export async function checkRcFileVersion(projectPath: string): Promise<number | null>;
+export async function needsRegeneration(
+  projectPath: string,
+  theme: ThemeMode,
+  config: TerminalConfig
+): Promise<boolean>;
+```
+
+**File Operations**:
+
+- Create `.automaker/terminal/` if doesn't exist
+- Write RC files with 0644 permissions
+- Write theme color files (40 themes × 1 file each)
+- Create version.txt with format version (currently "11")
+- Support atomic writes (write to temp, then rename)
+
+### Step 3: Add Settings Schema
+
+**File**: `libs/types/src/settings.ts`
+
+**Add to GlobalSettings** (around line 842):
+
+```typescript
+/** Terminal configuration settings */
+terminalConfig?: {
+  /** Enable custom terminal configurations (default: false) */
+  enabled: boolean;
+
+  /** Enable custom prompt (default: true when enabled) */
+  customPrompt: boolean;
+
+  /** Prompt format template */
+  promptFormat: 'standard' | 'minimal' | 'powerline' | 'starship';
+
+  /** Prompt theme preset */
+  promptTheme?: TerminalPromptTheme;
+
+  /** Show git branch in prompt (default: true) */
+  showGitBranch: boolean;
+
+  /** Show git status dirty indicator (default: true) */
+  showGitStatus: boolean;
+
+  /** Show user and host in prompt (default: true) */
+  showUserHost: boolean;
+
+  /** Show path in prompt (default: true) */
+  showPath: boolean;
+
+  /** Path display style */
+  pathStyle: 'full' | 'short' | 'basename';
+
+  /** Limit path depth (0 = full path) */
+  pathDepth: number;
+
+  /** Show current time in prompt (default: false) */
+  showTime: boolean;
+
+  /** Show last command exit status when non-zero (default: false) */
+  showExitStatus: boolean;
+
+  /** User-provided custom aliases (multiline string) */
+  customAliases: string;
+
+  /** User-provided custom env vars */
+  customEnvVars: Record<string, string>;
+
+  /** RC file format version (for migration) */
+  rcFileVersion?: number;
+};
+```
+
+**Add to ProjectSettings**:
+
+```typescript
+/** Project-specific terminal config overrides */
+terminalConfig?: {
+  /** Override global enabled setting */
+  enabled?: boolean;
+
+  /** Override prompt theme preset */
+  promptTheme?: TerminalPromptTheme;
+
+  /** Override showing user/host */
+  showUserHost?: boolean;
+
+  /** Override showing path */
+  showPath?: boolean;
+
+  /** Override path style */
+  pathStyle?: 'full' | 'short' | 'basename';
+
+  /** Override path depth (0 = full path) */
+  pathDepth?: number;
+
+  /** Override showing time */
+  showTime?: boolean;
+
+  /** Override showing exit status */
+  showExitStatus?: boolean;
+
+  /** Project-specific custom aliases */
+  customAliases?: string;
+
+  /** Project-specific env vars */
+  customEnvVars?: Record<string, string>;
+
+  /** Custom welcome message for this project */
+  welcomeMessage?: string;
+};
+```
+
+**Defaults**:
+
+```typescript
+const DEFAULT_TERMINAL_CONFIG = {
+  enabled: false,
+  customPrompt: true,
+  promptFormat: 'standard' as const,
+  promptTheme: 'custom' as const,
+  showGitBranch: true,
+  showGitStatus: true,
+  showUserHost: true,
+  showPath: true,
+  pathStyle: 'full' as const,
+  pathDepth: 0,
+  showTime: false,
+  showExitStatus: false,
+  customAliases: '',
+  customEnvVars: {},
+  rcFileVersion: 11,
+};
+```
+
+**Oh My Posh Themes**:
+
+- When `promptTheme` starts with `omp-` and `oh-my-posh` is available, the generated RC files will
+  initialize oh-my-posh with the selected theme name.
+- If oh-my-posh is not installed, the prompt falls back to the Automaker-built prompt format.
+- `POSH_THEMES_PATH` is exported to the standard user themes directory so themes resolve offline.
+
+### Step 4: Modify Terminal Service
+
+**File**: `apps/server/src/services/terminal-service.ts`
+
+**Modification Point**: In `createSession()` method, around line 335-344 where `env` object is built.
+
+**Add before PTY spawn**:
+
+```typescript
+// Get terminal config from settings
+const terminalConfig = await this.settingsService?.getGlobalSettings();
+const projectSettings = options.projectPath
+  ? await this.settingsService?.getProjectSettings(options.projectPath)
+  : null;
+
+const effectiveTerminalConfig = {
+  ...terminalConfig?.terminalConfig,
+  ...projectSettings?.terminalConfig,
+};
+
+if (effectiveTerminalConfig?.enabled) {
+  // Ensure RC files are up to date
+  const currentTheme = terminalConfig?.theme || 'dark';
+  await ensureRcFilesUpToDate(options.projectPath || cwd, currentTheme, effectiveTerminalConfig);
+
+  // Set shell-specific env vars
+  const shellName = path.basename(shell).toLowerCase();
+
+  if (shellName.includes('bash')) {
+    env.BASH_ENV = getRcFilePath(options.projectPath || cwd, 'bash');
+    env.AUTOMAKER_CUSTOM_PROMPT = effectiveTerminalConfig.customPrompt ? 'true' : 'false';
+    env.AUTOMAKER_THEME = currentTheme;
+  } else if (shellName.includes('zsh')) {
+    env.ZDOTDIR = path.join(options.projectPath || cwd, '.automaker', 'terminal');
+    env.AUTOMAKER_CUSTOM_PROMPT = effectiveTerminalConfig.customPrompt ? 'true' : 'false';
+    env.AUTOMAKER_THEME = currentTheme;
+  } else if (shellName === 'sh') {
+    env.ENV = getRcFilePath(options.projectPath || cwd, 'sh');
+    env.AUTOMAKER_CUSTOM_PROMPT = effectiveTerminalConfig.customPrompt ? 'true' : 'false';
+    env.AUTOMAKER_THEME = currentTheme;
+  }
+}
+```
+
+**Add new method for theme changes**:
+
+```typescript
+async onThemeChange(projectPath: string, newTheme: ThemeMode): Promise<void> {
+  const globalSettings = await this.settingsService?.getGlobalSettings();
+  const terminalConfig = globalSettings?.terminalConfig;
+
+  if (terminalConfig?.enabled) {
+    // Regenerate RC files with new theme
+    await writeRcFiles(projectPath, newTheme, terminalConfig);
+  }
+}
+```
+
+### Step 5: Create Settings UI
+
+**File**: `apps/ui/src/components/views/settings-view/terminal/terminal-config-section.tsx`
+
+**Component Structure**:
+
+```typescript
+export function TerminalConfigSection() {
+  return (
+    <div>
+      {/* Enable Toggle with Warning */}
+      <div>
+        <Label>Custom Terminal Configurations</Label>
+        <Switch checked={enabled} onCheckedChange={handleToggle} />
+        <p>Creates custom shell configs in .automaker/terminal/</p>
+      </div>
+
+      {enabled && (
+        <>
+          {/* Custom Prompt Toggle */}
+          <Switch checked={customPrompt} />
+
+          {/* Prompt Format Selector */}
+          <Select value={promptFormat} onValueChange={setPromptFormat}>
+            <option value="standard">Standard</option>
+            <option value="minimal">Minimal</option>
+            <option value="powerline">Powerline</option>
+            <option value="starship">Starship-Inspired</option>
+          </Select>
+
+          {/* Git Info Toggles */}
+          <Switch checked={showGitBranch} label="Show Git Branch" />
+          <Switch checked={showGitStatus} label="Show Git Status" />
+
+          {/* Custom Aliases */}
+          <Textarea
+            value={customAliases}
+            placeholder="# Custom aliases\nalias ll='ls -la'"
+          />
+
+          {/* Custom Env Vars */}
+          <KeyValueEditor
+            value={customEnvVars}
+            onChange={setCustomEnvVars}
+          />
+
+          {/* Live Preview Panel */}
+          <PromptPreview
+            format={promptFormat}
+            theme={effectiveTheme}
+            gitBranch={showGitBranch ? 'main' : null}
+            gitDirty={showGitStatus}
+          />
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+**Preview Component**:
+Shows example prompt like: `[user@host] ~/projects/automaker (main*) $`
+Updates instantly when theme or format changes.
+
+### Step 6: Theme Change Hook
+
+**File**: `apps/server/src/routes/settings.ts`
+
+**Hook into theme update endpoint**:
+
+```typescript
+// After updating theme in settings
+if (oldTheme !== newTheme) {
+  // Regenerate RC files for all projects with terminal config enabled
+  const projects = settings.projects;
+  for (const project of projects) {
+    const projectSettings = await settingsService.getProjectSettings(project.path);
+    if (projectSettings.terminalConfig?.enabled !== false) {
+      await terminalService.onThemeChange(project.path, newTheme);
+    }
+  }
+}
+```
+
+## Shell Configuration Strategy
+
+### Bash (via BASH_ENV)
+
+- Set `BASH_ENV=/path/to/.automaker/terminal/bashrc.sh`
+- BASH_ENV is loaded for all shells (interactive and non-interactive)
+- User's ~/.bashrc is sourced first within our bashrc.sh
+- No need for `--rcfile` flag (which would skip ~/.bashrc)
+
+### Zsh (via ZDOTDIR)
+
+- Set `ZDOTDIR=/path/to/.automaker/terminal/`
+- Create `.zshrc` symlink: `zshrc.zsh`
+- User's ~/.zshrc is sourced within our zshrc.zsh
+- Zsh's canonical configuration directory mechanism
+
+### Sh (via ENV)
+
+- Set `ENV=/path/to/.automaker/terminal/common.sh`
+- POSIX shell standard environment variable
+- Minimal prompt (POSIX sh doesn't support advanced prompts)
+
+## Prompt Formats
+
+### 1. Standard
+
+```
+[user@host] ~/path/to/project (main*) $
+```
+
+### 2. Minimal
+
+```
+~/project (main*) $
+```
+
+### 3. Powerline (Unicode box-drawing)
+
+```
+┌─[user@host]─[~/path]─[main*]
+└─$
+```
+
+### 4. Starship-Inspired
+
+```
+user@host in ~/path on main*
+❯
+```
+
+## Theme Synchronization
+
+### On Initial Enable
+
+1. User toggles "Enable Custom Terminal Configs"
+2. Show confirmation dialog explaining what will happen
+3. Generate RC files for current theme
+4. Set `rcFileVersion: 11` in settings
+
+### On Theme Change
+
+1. User changes app theme in settings
+2. Settings API detects theme change
+3. Call `terminalService.onThemeChange()` for each project
+4. Regenerate theme color files (`.automaker/terminal/themes/`)
+5. Existing terminals keep old theme (expected behavior)
+6. New terminals use new theme
+
+### On Disable
+
+1. User toggles off "Enable Custom Terminal Configs"
+2. Delete `.automaker/terminal/` directory
+3. New terminals spawn without custom env vars
+4. Existing terminals continue with current config until restarted
+
+## Critical Files
+
+### Files to Modify
+
+1. `/home/dhanush/Projects/automaker/apps/server/src/services/terminal-service.ts` - Add env var injection logic at line ~335-344
+2. `/home/dhanush/Projects/automaker/libs/types/src/settings.ts` - Add terminalConfig to GlobalSettings (~line 842) and ProjectSettings
+3. `/home/dhanush/Projects/automaker/apps/server/src/routes/settings.ts` - Add theme change hook
+
+### Files to Create
+
+1. `/home/dhanush/Projects/automaker/libs/platform/src/rc-generator.ts` - RC file generation logic
+2. `/home/dhanush/Projects/automaker/libs/platform/src/rc-file-manager.ts` - File I/O and path resolution
+3. `/home/dhanush/Projects/automaker/apps/ui/src/components/views/settings-view/terminal/terminal-config-section.tsx` - Settings UI
+4. `/home/dhanush/Projects/automaker/apps/ui/src/components/views/settings-view/terminal/prompt-preview.tsx` - Live preview component
+
+### Files to Read
+
+1. `/home/dhanush/Projects/automaker/apps/ui/src/config/terminal-themes.ts` - Source of theme hex colors for ANSI mapping
+
+## Testing Approach
+
+### Unit Tests
+
+- `rc-generator.test.ts`: Test template generation for all 40 themes
+- `rc-file-manager.test.ts`: Test file I/O and version checking
+- `terminal-service.test.ts`: Test env var injection with mocked PTY spawn
+
+### E2E Tests
+
+- Enable custom configs in settings
+- Change theme and verify new terminals use new colors
+- Add custom aliases and verify they work in terminal
+- Test all 4 prompt formats
+- Test disable flow (files removed, terminals work normally)
+
+### Manual Testing Checklist
+
+- [ ] Test on macOS with zsh
+- [ ] Test on Linux with bash
+- [ ] Test all 40 themes have correct colors
+- [ ] Test git prompt in repo vs non-repo directories
+- [ ] Test custom aliases execution
+- [ ] Test custom env vars available
+- [ ] Test project-specific overrides
+- [ ] Test disable/re-enable flow
+
+## Verification
+
+### End-to-End Test
+
+1. Enable custom terminal configs in settings
+2. Set prompt format to "powerline"
+3. Add custom alias: `alias gs='git status'`
+4. Change theme to "dracula"
+5. Open new terminal
+6. Verify:
+   - Prompt uses powerline format with theme colors
+   - Git branch shows if in repo
+   - `gs` alias works
+   - User's ~/.bashrc still loaded (test with known alias from user's file)
+7. Change theme to "nord"
+8. Open new terminal
+9. Verify prompt colors changed to match nord theme
+10. Disable custom configs
+11. Verify `.automaker/terminal/` deleted
+12. Open new terminal
+13. Verify standard prompt without custom config
+
+### Success Criteria
+
+- ✅ Feature can be enabled/disabled in settings
+- ✅ RC files generated in `.automaker/terminal/`
+- ✅ Prompt colors match theme (all 40 themes)
+- ✅ Git branch/status shown in prompt
+- ✅ Custom aliases work
+- ✅ Custom env vars available
+- ✅ User's original ~/.bashrc or ~/.zshrc still loads
+- ✅ Theme changes regenerate color files
+- ✅ Works on Mac (zsh) and Linux (bash)
+- ✅ No breaking changes to existing terminal functionality
+
+## Security & Safety
+
+### File Permissions
+
+- RC files: 0644 (user read/write, others read)
+- Directory: 0755 (user rwx, others rx)
+- No secrets in RC files
+
+### Input Sanitization
+
+- Escape special characters in custom aliases
+- Validate env var names (alphanumeric + underscore only)
+- No eval of user-provided code
+- Shell escaping for all user inputs
+
+### Backwards Compatibility
+
+- Feature disabled by default
+- Existing terminals unaffected when disabled
+- User's original RC files always sourced first
+- Easy rollback (just disable and delete files)
+
+## Branch Creation
+
+Per PR workflow in DEVELOPMENT_WORKFLOW.md:
+
+1. Create feature branch: `git checkout -b feature/custom-terminal-configs`
+2. Implement changes following this plan
+3. Test thoroughly
+4. Merge upstream RC before shipping: `git merge upstream/v0.14.0rc --no-edit`
+5. Push to origin: `git push -u origin feature/custom-terminal-configs`
+6. Create PR targeting `main` branch
+
+## Documentation
+
+After implementation, create comprehensive documentation at:
+`/home/dhanush/Projects/automaker/docs/terminal-custom-configs.md`
+
+**Documentation should cover**:
+
+- Feature overview and benefits
+- How to enable custom terminal configs
+- Prompt format options with examples
+- Custom aliases and env vars
+- Theme synchronization behavior
+- Troubleshooting common issues
+- How to disable the feature
+- Technical details for contributors
+
+## Timeline Estimate
+
+- Week 1: Core infrastructure (RC generator, file manager, settings schema)
+- Week 2: Terminal service integration, theme sync
+- Week 3: Settings UI, preview component
+- Week 4: Testing, documentation, polish
+
+Total: ~4 weeks for complete implementation

libs/platform/src/index.ts

@@ -186,3 +186,37 @@ export {
   findTerminalById,
   openInExternalTerminal,
 } from './terminal.js';
+
+// RC Generator - Shell configuration file generation
+export {
+  hexToXterm256,
+  getThemeANSIColors,
+  generateBashrc,
+  generateZshrc,
+  generateCommonFunctions,
+  generateThemeColors,
+  getShellName,
+  type TerminalConfig,
+  type TerminalTheme,
+  type ANSIColors,
+} from './rc-generator.js';
+
+// RC File Manager - Shell configuration file I/O
+export {
+  RC_FILE_VERSION,
+  getTerminalDir,
+  getThemesDir,
+  getRcFilePath,
+  ensureTerminalDir,
+  checkRcFileVersion,
+  needsRegeneration,
+  writeAllThemeFiles,
+  writeThemeFile,
+  writeRcFiles,
+  ensureRcFilesUpToDate,
+  deleteTerminalDir,
+  ensureUserCustomFile,
+} from './rc-file-manager.js';
+
+// Terminal Theme Colors - Raw theme color data for all 40 themes
+export { terminalThemeColors, getTerminalThemeColors } from './terminal-theme-colors.js';

libs/platform/src/rc-file-manager.ts

@@ -0,0 +1,308 @@
+/**
+ * RC File Manager - Manage shell configuration files in .automaker/terminal/
+ *
+ * This module handles file I/O operations for generating and managing shell RC files,
+ * including version checking and regeneration logic.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import type { ThemeMode } from '@automaker/types';
+import {
+  generateBashrc,
+  generateZshrc,
+  generateCommonFunctions,
+  generateThemeColors,
+  type TerminalConfig,
+  type TerminalTheme,
+} from './rc-generator.js';
+
+/**
+ * Current RC file format version
+ */
+export const RC_FILE_VERSION = 11;
+
+const RC_SIGNATURE_FILENAME = 'config.sha256';
+
+/**
+ * Get the terminal directory path
+ */
+export function getTerminalDir(projectPath: string): string {
+  return path.join(projectPath, '.automaker', 'terminal');
+}
+
+/**
+ * Get the themes directory path
+ */
+export function getThemesDir(projectPath: string): string {
+  return path.join(getTerminalDir(projectPath), 'themes');
+}
+
+/**
+ * Get RC file path for specific shell
+ */
+export function getRcFilePath(projectPath: string, shell: 'bash' | 'zsh' | 'sh'): string {
+  const terminalDir = getTerminalDir(projectPath);
+  switch (shell) {
+    case 'bash':
+      return path.join(terminalDir, 'bashrc.sh');
+    case 'zsh':
+      return path.join(terminalDir, '.zshrc'); // Zsh looks for .zshrc in ZDOTDIR
+    case 'sh':
+      return path.join(terminalDir, 'common.sh');
+  }
+}
+
+/**
+ * Ensure terminal directory exists
+ */
+export async function ensureTerminalDir(projectPath: string): Promise<void> {
+  const terminalDir = getTerminalDir(projectPath);
+  const themesDir = getThemesDir(projectPath);
+
+  await fs.mkdir(terminalDir, { recursive: true, mode: 0o755 });
+  await fs.mkdir(themesDir, { recursive: true, mode: 0o755 });
+}
+
+/**
+ * Write RC file with atomic write (write to temp, then rename)
+ */
+async function atomicWriteFile(
+  filePath: string,
+  content: string,
+  mode: number = 0o644
+): Promise<void> {
+  const tempPath = `${filePath}.tmp`;
+  await fs.writeFile(tempPath, content, { encoding: 'utf8', mode });
+  await fs.rename(tempPath, filePath);
+}
+
+function sortObjectKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortObjectKeys(item));
+  }
+
+  if (value && typeof value === 'object') {
+    const sortedEntries = Object.entries(value as Record<string, unknown>)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right));
+
+    const sortedObject: Record<string, unknown> = {};
+    for (const [key, entryValue] of sortedEntries) {
+      sortedObject[key] = sortObjectKeys(entryValue);
+    }
+    return sortedObject;
+  }
+
+  return value;
+}
+
+function buildConfigSignature(theme: ThemeMode, config: TerminalConfig): string {
+  const payload = { theme, config: sortObjectKeys(config) };
+  const serializedPayload = JSON.stringify(payload);
+  return createHash('sha256').update(serializedPayload).digest('hex');
+}
+
+async function readSignatureFile(projectPath: string): Promise<string | null> {
+  const signaturePath = path.join(getTerminalDir(projectPath), RC_SIGNATURE_FILENAME);
+  try {
+    const signature = await fs.readFile(signaturePath, 'utf8');
+    return signature.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeSignatureFile(projectPath: string, signature: string): Promise<void> {
+  const signaturePath = path.join(getTerminalDir(projectPath), RC_SIGNATURE_FILENAME);
+  await atomicWriteFile(signaturePath, `${signature}\n`, 0o644);
+}
+
+/**
+ * Check current RC file version
+ */
+export async function checkRcFileVersion(projectPath: string): Promise<number | null> {
+  const versionPath = path.join(getTerminalDir(projectPath), 'version.txt');
+  try {
+    const content = await fs.readFile(versionPath, 'utf8');
+    const version = parseInt(content.trim(), 10);
+    return isNaN(version) ? null : version;
+  } catch (error) {
+    return null; // File doesn't exist or can't be read
+  }
+}
+
+/**
+ * Write version file
+ */
+async function writeVersionFile(projectPath: string, version: number): Promise<void> {
+  const versionPath = path.join(getTerminalDir(projectPath), 'version.txt');
+  await atomicWriteFile(versionPath, `${version}\n`, 0o644);
+}
+
+/**
+ * Check if RC files need regeneration
+ */
+export async function needsRegeneration(
+  projectPath: string,
+  theme: ThemeMode,
+  config: TerminalConfig
+): Promise<boolean> {
+  const currentVersion = await checkRcFileVersion(projectPath);
+
+  // Regenerate if version doesn't match or files don't exist
+  if (currentVersion !== RC_FILE_VERSION) {
+    return true;
+  }
+
+  const expectedSignature = buildConfigSignature(theme, config);
+  const existingSignature = await readSignatureFile(projectPath);
+  if (!existingSignature || existingSignature !== expectedSignature) {
+    return true;
+  }
+
+  // Check if critical files exist
+  const bashrcPath = getRcFilePath(projectPath, 'bash');
+  const zshrcPath = getRcFilePath(projectPath, 'zsh');
+  const commonPath = path.join(getTerminalDir(projectPath), 'common.sh');
+  const themeFilePath = path.join(getThemesDir(projectPath), `${theme}.sh`);
+
+  try {
+    await Promise.all([
+      fs.access(bashrcPath),
+      fs.access(zshrcPath),
+      fs.access(commonPath),
+      fs.access(themeFilePath),
+    ]);
+    return false; // All files exist
+  } catch {
+    return true; // Some files are missing
+  }
+}
+
+/**
+ * Write all theme color files (all 40 themes)
+ */
+export async function writeAllThemeFiles(
+  projectPath: string,
+  terminalThemes: Record<ThemeMode, TerminalTheme>
+): Promise<void> {
+  const themesDir = getThemesDir(projectPath);
+  await fs.mkdir(themesDir, { recursive: true, mode: 0o755 });
+
+  const themeEntries = Object.entries(terminalThemes);
+  await Promise.all(
+    themeEntries.map(async ([themeName, theme]) => {
+      const themeFilePath = path.join(themesDir, `${themeName}.sh`);
+      const content = generateThemeColors(theme);
+      await atomicWriteFile(themeFilePath, content, 0o644);
+    })
+  );
+}
+
+/**
+ * Write a single theme color file
+ */
+export async function writeThemeFile(
+  projectPath: string,
+  theme: ThemeMode,
+  themeColors: TerminalTheme
+): Promise<void> {
+  const themesDir = getThemesDir(projectPath);
+  await fs.mkdir(themesDir, { recursive: true, mode: 0o755 });
+
+  const themeFilePath = path.join(themesDir, `${theme}.sh`);
+  const content = generateThemeColors(themeColors);
+  await atomicWriteFile(themeFilePath, content, 0o644);
+}
+
+/**
+ * Write all RC files
+ */
+export async function writeRcFiles(
+  projectPath: string,
+  theme: ThemeMode,
+  config: TerminalConfig,
+  themeColors: TerminalTheme,
+  allThemes: Record<ThemeMode, TerminalTheme>
+): Promise<void> {
+  await ensureTerminalDir(projectPath);
+
+  // Write common functions file
+  const commonPath = path.join(getTerminalDir(projectPath), 'common.sh');
+  const commonContent = generateCommonFunctions(config);
+  await atomicWriteFile(commonPath, commonContent, 0o644);
+
+  // Write bashrc
+  const bashrcPath = getRcFilePath(projectPath, 'bash');
+  const bashrcContent = generateBashrc(themeColors, config);
+  await atomicWriteFile(bashrcPath, bashrcContent, 0o644);
+
+  // Write zshrc
+  const zshrcPath = getRcFilePath(projectPath, 'zsh');
+  const zshrcContent = generateZshrc(themeColors, config);
+  await atomicWriteFile(zshrcPath, zshrcContent, 0o644);
+
+  // Write all theme files (40 themes)
+  await writeAllThemeFiles(projectPath, allThemes);
+
+  // Write version file
+  await writeVersionFile(projectPath, RC_FILE_VERSION);
+
+  // Write config signature for change detection
+  const signature = buildConfigSignature(theme, config);
+  await writeSignatureFile(projectPath, signature);
+}
+
+/**
+ * Ensure RC files are up to date
+ */
+export async function ensureRcFilesUpToDate(
+  projectPath: string,
+  theme: ThemeMode,
+  config: TerminalConfig,
+  themeColors: TerminalTheme,
+  allThemes: Record<ThemeMode, TerminalTheme>
+): Promise<void> {
+  const needsRegen = await needsRegeneration(projectPath, theme, config);
+  if (needsRegen) {
+    await writeRcFiles(projectPath, theme, config, themeColors, allThemes);
+  }
+}
+
+/**
+ * Delete terminal directory (for disable flow)
+ */
+export async function deleteTerminalDir(projectPath: string): Promise<void> {
+  const terminalDir = getTerminalDir(projectPath);
+  try {
+    await fs.rm(terminalDir, { recursive: true, force: true });
+  } catch (error) {
+    // Ignore errors if directory doesn't exist
+  }
+}
+
+/**
+ * Create user-custom.sh placeholder if it doesn't exist
+ */
+export async function ensureUserCustomFile(projectPath: string): Promise<void> {
+  const userCustomPath = path.join(getTerminalDir(projectPath), 'user-custom.sh');
+  try {
+    await fs.access(userCustomPath);
+  } catch {
+    // File doesn't exist, create it
+    const content = `#!/bin/sh
+# Automaker User Customizations
+# Add your custom shell configuration here
+# This file will not be overwritten by Automaker
+
+# Example: Add custom aliases
+# alias myalias='command'
+
+# Example: Add custom environment variables
+# export MY_VAR="value"
+`;
+    await atomicWriteFile(userCustomPath, content, 0o644);
+  }
+}

libs/platform/src/rc-generator.ts

@@ -0,0 +1,972 @@
+/**
+ * RC Generator - Generate shell configuration files for custom terminal prompts
+ *
+ * This module generates bash/zsh/sh configuration files that sync with Automaker's themes,
+ * providing custom prompts with theme-matched colors while preserving user's existing RC files.
+ */
+
+import type { ThemeMode } from '@automaker/types';
+
+/**
+ * Terminal configuration options
+ */
+export interface TerminalConfig {
+  enabled: boolean;
+  customPrompt: boolean;
+  promptFormat: 'standard' | 'minimal' | 'powerline' | 'starship';
+  showGitBranch: boolean;
+  showGitStatus: boolean;
+  showUserHost: boolean;
+  showPath: boolean;
+  pathStyle: 'full' | 'short' | 'basename';
+  pathDepth: number;
+  showTime: boolean;
+  showExitStatus: boolean;
+  customAliases: string;
+  customEnvVars: Record<string, string>;
+  rcFileVersion?: number;
+}
+
+/**
+ * Terminal theme colors (hex values)
+ */
+export interface TerminalTheme {
+  background: string;
+  foreground: string;
+  cursor: string;
+  cursorAccent: string;
+  selectionBackground: string;
+  selectionForeground?: string;
+  black: string;
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  brightBlack: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+}
+
+/**
+ * ANSI color codes for shell prompts
+ */
+export interface ANSIColors {
+  user: string;
+  host: string;
+  path: string;
+  gitBranch: string;
+  gitDirty: string;
+  prompt: string;
+  reset: string;
+}
+
+const STARTUP_COLOR_PRIMARY = 51;
+const STARTUP_COLOR_SECONDARY = 39;
+const STARTUP_COLOR_ACCENT = 33;
+const DEFAULT_PATH_DEPTH = 0;
+const DEFAULT_PATH_STYLE: TerminalConfig['pathStyle'] = 'full';
+const OMP_THEME_ENV_VAR = 'AUTOMAKER_OMP_THEME';
+const OMP_BINARY = 'oh-my-posh';
+const OMP_SHELL_BASH = 'bash';
+const OMP_SHELL_ZSH = 'zsh';
+
+/**
+ * Convert hex color to RGB
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  if (!result) {
+    throw new Error(`Invalid hex color: ${hex}`);
+  }
+  return {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16),
+  };
+}
+
+/**
+ * Calculate Euclidean distance between two RGB colors
+ */
+function colorDistance(
+  c1: { r: number; g: number; b: number },
+  c2: { r: number; g: number; b: number }
+): number {
+  return Math.sqrt(Math.pow(c1.r - c2.r, 2) + Math.pow(c1.g - c2.g, 2) + Math.pow(c1.b - c2.b, 2));
+}
+
+/**
+ * xterm-256 color palette (simplified - standard colors + 6x6x6 RGB cube + grayscale)
+ */
+const XTERM_256_PALETTE: Array<{ r: number; g: number; b: number }> = [];
+
+// Standard colors (0-15) - already handled by ANSI basic colors
+// RGB cube (16-231): 6x6x6 cube with levels 0, 95, 135, 175, 215, 255
+const levels = [0, 95, 135, 175, 215, 255];
+for (let r = 0; r < 6; r++) {
+  for (let g = 0; g < 6; g++) {
+    for (let b = 0; b < 6; b++) {
+      XTERM_256_PALETTE.push({ r: levels[r], g: levels[g], b: levels[b] });
+    }
+  }
+}
+
+// Grayscale (232-255): 24 shades from #080808 to #eeeeee
+for (let i = 0; i < 24; i++) {
+  const gray = 8 + i * 10;
+  XTERM_256_PALETTE.push({ r: gray, g: gray, b: gray });
+}
+
+/**
+ * Convert hex color to closest xterm-256 color code
+ */
+export function hexToXterm256(hex: string): number {
+  const rgb = hexToRgb(hex);
+  let closestIndex = 16; // Start from RGB cube
+  let minDistance = Infinity;
+
+  XTERM_256_PALETTE.forEach((color, index) => {
+    const distance = colorDistance(rgb, color);
+    if (distance < minDistance) {
+      minDistance = distance;
+      closestIndex = index + 16; // Offset by 16 (standard colors)
+    }
+  });
+
+  return closestIndex;
+}
+
+/**
+ * Get ANSI color codes from theme colors
+ */
+export function getThemeANSIColors(theme: TerminalTheme): ANSIColors {
+  return {
+    user: `\\[\\e[38;5;${hexToXterm256(theme.cyan)}m\\]`,
+    host: `\\[\\e[38;5;${hexToXterm256(theme.blue)}m\\]`,
+    path: `\\[\\e[38;5;${hexToXterm256(theme.yellow)}m\\]`,
+    gitBranch: `\\[\\e[38;5;${hexToXterm256(theme.magenta)}m\\]`,
+    gitDirty: `\\[\\e[38;5;${hexToXterm256(theme.red)}m\\]`,
+    prompt: `\\[\\e[38;5;${hexToXterm256(theme.green)}m\\]`,
+    reset: '\\[\\e[0m\\]',
+  };
+}
+
+/**
+ * Escape shell special characters in user input
+ */
+function shellEscape(str: string): string {
+  return str.replace(/([`$\\"])/g, '\\$1');
+}
+
+/**
+ * Validate environment variable name
+ */
+function isValidEnvVarName(name: string): boolean {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}
+
+function stripPromptEscapes(ansiColor: string): string {
+  return ansiColor.replace(/\\\[/g, '').replace(/\\\]/g, '');
+}
+
+function normalizePathStyle(
+  pathStyle: TerminalConfig['pathStyle'] | undefined
+): TerminalConfig['pathStyle'] {
+  if (pathStyle === 'short' || pathStyle === 'basename') {
+    return pathStyle;
+  }
+  return DEFAULT_PATH_STYLE;
+}
+
+function normalizePathDepth(pathDepth: number | undefined): number {
+  const depth =
+    typeof pathDepth === 'number' && Number.isFinite(pathDepth) ? pathDepth : DEFAULT_PATH_DEPTH;
+  return Math.max(DEFAULT_PATH_DEPTH, Math.floor(depth));
+}
+
+function generateOhMyPoshInit(
+  shell: typeof OMP_SHELL_BASH | typeof OMP_SHELL_ZSH,
+  fallback: string
+) {
+  const themeVar = `$${OMP_THEME_ENV_VAR}`;
+  const initCommand = `${OMP_BINARY} init ${shell} --config`;
+  return `if [ -n "${themeVar}" ] && command -v ${OMP_BINARY} >/dev/null 2>&1; then
+    automaker_omp_theme="$(automaker_resolve_omp_theme)"
+    if [ -n "$automaker_omp_theme" ]; then
+        eval "$(${initCommand} "$automaker_omp_theme")"
+    else
+        ${fallback}
+    fi
+else
+    ${fallback}
+fi`;
+}
+
+/**
+ * Generate common shell functions (git prompt, etc.)
+ */
+export function generateCommonFunctions(config: TerminalConfig): string {
+  const gitPrompt = config.showGitBranch
+    ? `
+automaker_git_prompt() {
+  local branch=""
+  local dirty=""
+
+  # Check if we're in a git repository
+  if git rev-parse --git-dir > /dev/null 2>&1; then
+    # Get current branch name
+    branch=$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse --short HEAD 2>/dev/null)
+
+    ${
+      config.showGitStatus
+        ? `
+    # Check if working directory is dirty
+    if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+      dirty="*"
+    fi
+    `
+        : ''
+    }
+
+    if [ -n "$branch" ]; then
+      echo -n " ($branch$dirty)"
+    fi
+  fi
+}
+`
+    : `
+automaker_git_prompt() {
+  # Git prompt disabled
+  echo -n ""
+}
+`;
+
+  return `#!/bin/sh
+# Automaker Terminal Configuration - Common Functions v1.0
+
+${gitPrompt}
+
+AUTOMAKER_INFO_UNKNOWN="Unknown"
+AUTOMAKER_BANNER_LABEL_WIDTH=12
+AUTOMAKER_BYTES_PER_KIB=1024
+AUTOMAKER_KIB_PER_MIB=1024
+AUTOMAKER_MIB_PER_GIB=1024
+AUTOMAKER_COLOR_PRIMARY="\\033[38;5;${STARTUP_COLOR_PRIMARY}m"
+AUTOMAKER_COLOR_SECONDARY="\\033[38;5;${STARTUP_COLOR_SECONDARY}m"
+AUTOMAKER_COLOR_ACCENT="\\033[38;5;${STARTUP_COLOR_ACCENT}m"
+AUTOMAKER_COLOR_RESET="\\033[0m"
+AUTOMAKER_SHOW_TIME="${config.showTime === true ? 'true' : 'false'}"
+AUTOMAKER_SHOW_EXIT_STATUS="${config.showExitStatus === true ? 'true' : 'false'}"
+AUTOMAKER_SHOW_USER_HOST="${config.showUserHost === false ? 'false' : 'true'}"
+AUTOMAKER_SHOW_PATH="${config.showPath === false ? 'false' : 'true'}"
+AUTOMAKER_PATH_STYLE="${normalizePathStyle(config.pathStyle)}"
+AUTOMAKER_PATH_DEPTH=${normalizePathDepth(config.pathDepth)}
+automaker_default_themes_dir="\${XDG_DATA_HOME:-\$HOME/.local/share}/oh-my-posh/themes"
+if [ -z "$POSH_THEMES_PATH" ] || [ ! -d "$POSH_THEMES_PATH" ]; then
+  POSH_THEMES_PATH="$automaker_default_themes_dir"
+fi
+export POSH_THEMES_PATH
+
+automaker_resolve_omp_theme() {
+  automaker_theme_name="$AUTOMAKER_OMP_THEME"
+  if [ -z "$automaker_theme_name" ]; then
+    return 1
+  fi
+
+  if [ -f "$automaker_theme_name" ]; then
+    printf '%s' "$automaker_theme_name"
+    return 0
+  fi
+
+  automaker_themes_base="\${POSH_THEMES_PATH%/}"
+  if [ -n "$automaker_themes_base" ]; then
+    if [ -f "$automaker_themes_base/$automaker_theme_name.omp.json" ]; then
+      printf '%s' "$automaker_themes_base/$automaker_theme_name.omp.json"
+      return 0
+    fi
+    if [ -f "$automaker_themes_base/$automaker_theme_name.omp.yaml" ]; then
+      printf '%s' "$automaker_themes_base/$automaker_theme_name.omp.yaml"
+      return 0
+    fi
+  fi
+
+  return 1
+}
+
+automaker_command_exists() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+automaker_get_os() {
+  if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    if [ -n "$PRETTY_NAME" ]; then
+      echo "$PRETTY_NAME"
+      return
+    fi
+    if [ -n "$NAME" ] && [ -n "$VERSION" ]; then
+      echo "$NAME $VERSION"
+      return
+    fi
+  fi
+
+  if automaker_command_exists sw_vers; then
+    echo "$(sw_vers -productName) $(sw_vers -productVersion)"
+    return
+  fi
+
+  uname -s 2>/dev/null || echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_get_uptime() {
+  if automaker_command_exists uptime; then
+    if uptime -p >/dev/null 2>&1; then
+      uptime -p
+      return
+    fi
+    uptime 2>/dev/null | sed 's/.*up \\([^,]*\\).*/\\1/' || uptime 2>/dev/null
+    return
+  fi
+
+  echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_get_cpu() {
+  if automaker_command_exists lscpu; then
+    lscpu | sed -n 's/Model name:[[:space:]]*//p' | head -n 1
+    return
+  fi
+
+  if automaker_command_exists sysctl; then
+    sysctl -n machdep.cpu.brand_string 2>/dev/null || sysctl -n hw.model 2>/dev/null
+    return
+  fi
+
+  uname -m 2>/dev/null || echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_get_memory() {
+  if automaker_command_exists free; then
+    free -h | awk '/Mem:/ {print $3 " / " $2}'
+    return
+  fi
+
+  if automaker_command_exists vm_stat; then
+    local page_size
+    local pages_free
+    local pages_active
+    local pages_inactive
+    local pages_wired
+    local pages_total
+    page_size=$(vm_stat | awk '/page size of/ {print $8}')
+    pages_free=$(vm_stat | awk '/Pages free/ {print $3}' | tr -d '.')
+    pages_active=$(vm_stat | awk '/Pages active/ {print $3}' | tr -d '.')
+    pages_inactive=$(vm_stat | awk '/Pages inactive/ {print $3}' | tr -d '.')
+    pages_wired=$(vm_stat | awk '/Pages wired down/ {print $4}' | tr -d '.')
+    pages_total=$((pages_free + pages_active + pages_inactive + pages_wired))
+    awk -v total="$pages_total" -v free="$pages_free" -v size="$page_size" \
+      -v bytes_kib="$AUTOMAKER_BYTES_PER_KIB" \
+      -v kib_mib="$AUTOMAKER_KIB_PER_MIB" \
+      -v mib_gib="$AUTOMAKER_MIB_PER_GIB" \
+      'BEGIN {
+      total_gb = total * size / bytes_kib / kib_mib / mib_gib;
+      used_gb = (total - free) * size / bytes_kib / kib_mib / mib_gib;
+      printf("%.1f GB / %.1f GB", used_gb, total_gb);
+    }'
+    return
+  fi
+
+  if automaker_command_exists sysctl; then
+    local total_bytes
+    total_bytes=$(sysctl -n hw.memsize 2>/dev/null)
+    if [ -n "$total_bytes" ]; then
+      awk -v total="$total_bytes" \
+        -v bytes_kib="$AUTOMAKER_BYTES_PER_KIB" \
+        -v kib_mib="$AUTOMAKER_KIB_PER_MIB" \
+        -v mib_gib="$AUTOMAKER_MIB_PER_GIB" \
+        'BEGIN {printf("%.1f GB", total / bytes_kib / kib_mib / mib_gib)}'
+      return
+    fi
+  fi
+
+  echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_get_disk() {
+  if automaker_command_exists df; then
+    df -h / 2>/dev/null | awk 'NR==2 {print $3 " / " $2}'
+    return
+  fi
+
+  echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_get_ip() {
+  if automaker_command_exists hostname; then
+    local ip_addr
+    ip_addr=$(hostname -I 2>/dev/null | awk '{print $1}')
+    if [ -n "$ip_addr" ]; then
+      echo "$ip_addr"
+      return
+    fi
+  fi
+
+  if automaker_command_exists ipconfig; then
+    local ip_addr
+    ip_addr=$(ipconfig getifaddr en0 2>/dev/null)
+    if [ -n "$ip_addr" ]; then
+      echo "$ip_addr"
+      return
+    fi
+  fi
+
+  echo "$AUTOMAKER_INFO_UNKNOWN"
+}
+
+automaker_trim_path_depth() {
+  local path="$1"
+  local depth="$2"
+  if [ -z "$depth" ] || [ "$depth" -le 0 ]; then
+    echo "$path"
+    return
+  fi
+
+  echo "$path" | awk -v depth="$depth" -F/ '{
+    prefix=""
+    start=1
+    if ($1=="") { prefix="/"; start=2 }
+    else if ($1=="~") { prefix="~/"; start=2 }
+    n=NF
+    if (n < start) {
+      if (prefix=="/") { print "/" }
+      else if (prefix=="~/") { print "~" }
+      else { print $0 }
+      next
+    }
+    segCount = n - start + 1
+    d = depth
+    if (d > segCount) { d = segCount }
+    out=""
+    for (i = n - d + 1; i <= n; i++) {
+      out = out (out=="" ? "" : "/") $i
+    }
+    if (prefix=="/") {
+      if (out=="") { out="/" } else { out="/" out }
+    } else if (prefix=="~/") {
+      if (out=="") { out="~" } else { out="~/" out }
+    }
+    print out
+  }'
+}
+
+automaker_shorten_path() {
+  local path="$1"
+  echo "$path" | awk -F/ '{
+    prefix=""
+    start=1
+    if ($1=="") { prefix="/"; start=2 }
+    else if ($1=="~") { prefix="~/"; start=2 }
+    n=NF
+    if (n < start) {
+      if (prefix=="/") { print "/" }
+      else if (prefix=="~/") { print "~" }
+      else { print $0 }
+      next
+    }
+    out=""
+    for (i = start; i <= n; i++) {
+      seg = $i
+      if (i < n && length(seg) > 0) { seg = substr(seg, 1, 1) }
+      out = out (out=="" ? "" : "/") seg
+    }
+    if (prefix=="/") { out="/" out }
+    else if (prefix=="~/") { out="~/" out }
+    print out
+  }'
+}
+
+automaker_prompt_path() {
+  if [ "$AUTOMAKER_SHOW_PATH" != "true" ]; then
+    return
+  fi
+
+  local current_path="$PWD"
+  if [ -n "$HOME" ] && [ "\${current_path#"$HOME"}" != "$current_path" ]; then
+    current_path="~\${current_path#$HOME}"
+  fi
+
+  if [ "$AUTOMAKER_PATH_DEPTH" -gt 0 ]; then
+    current_path=$(automaker_trim_path_depth "$current_path" "$AUTOMAKER_PATH_DEPTH")
+  fi
+
+  case "$AUTOMAKER_PATH_STYLE" in
+    basename)
+      if [ "$current_path" = "/" ] || [ "$current_path" = "~" ]; then
+        echo -n "$current_path"
+      else
+        echo -n "\${current_path##*/}"
+      fi
+      ;;
+    short)
+      echo -n "$(automaker_shorten_path "$current_path")"
+      ;;
+    full|*)
+      echo -n "$current_path"
+      ;;
+  esac
+}
+
+automaker_prompt_time() {
+  if [ "$AUTOMAKER_SHOW_TIME" != "true" ]; then
+    return
+  fi
+
+  date +%H:%M
+}
+
+automaker_prompt_status() {
+  automaker_last_status=$?
+  if [ "$AUTOMAKER_SHOW_EXIT_STATUS" != "true" ]; then
+    return
+  fi
+
+  if [ "$automaker_last_status" -eq 0 ]; then
+    return
+  fi
+
+  printf "✗ %s" "$automaker_last_status"
+}
+
+automaker_show_banner() {
+  local label_width="$AUTOMAKER_BANNER_LABEL_WIDTH"
+  local logo_line_1="  █▀▀█ █  █ ▀▀█▀▀ █▀▀█ █▀▄▀█ █▀▀█ █ █ █▀▀ █▀▀█  "
+  local logo_line_2="  █▄▄█ █  █   █   █  █ █ ▀ █ █▄▄█ █▀▄ █▀▀ █▄▄▀  "
+  local logo_line_3="  ▀  ▀  ▀▀▀   ▀   ▀▀▀▀ ▀   ▀ ▀  ▀ ▀ ▀ ▀▀▀ ▀ ▀▀  "
+  local accent_color="\${AUTOMAKER_COLOR_PRIMARY}"
+  local secondary_color="\${AUTOMAKER_COLOR_SECONDARY}"
+  local tertiary_color="\${AUTOMAKER_COLOR_ACCENT}"
+  local label_color="\${AUTOMAKER_COLOR_SECONDARY}"
+  local reset_color="\${AUTOMAKER_COLOR_RESET}"
+
+  printf "%b%s%b\n" "$accent_color" "$logo_line_1" "$reset_color"
+  printf "%b%s%b\n" "$secondary_color" "$logo_line_2" "$reset_color"
+  printf "%b%s%b\n" "$tertiary_color" "$logo_line_3" "$reset_color"
+  printf "\n"
+
+  local shell_name="\${SHELL##*/}"
+  if [ -z "$shell_name" ]; then
+    shell_name=$(basename "$0" 2>/dev/null || echo "shell")
+  fi
+  local user_host="\${USER:-unknown}@$(hostname 2>/dev/null || echo unknown)"
+  printf "%b%s%b\n" "$label_color" "$user_host" "$reset_color"
+
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "OS:" "$reset_color" "$(automaker_get_os)"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Uptime:" "$reset_color" "$(automaker_get_uptime)"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Shell:" "$reset_color" "$shell_name"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Terminal:" "$reset_color" "\${TERM_PROGRAM:-$TERM}"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "CPU:" "$reset_color" "$(automaker_get_cpu)"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Memory:" "$reset_color" "$(automaker_get_memory)"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Disk:" "$reset_color" "$(automaker_get_disk)"
+  printf "%b%-\${label_width}s%b %s\n" "$label_color" "Local IP:" "$reset_color" "$(automaker_get_ip)"
+  printf "\n"
+}
+
+automaker_show_banner_once() {
+  case "$-" in
+    *i*) ;;
+    *) return ;;
+  esac
+
+  if [ "$AUTOMAKER_BANNER_SHOWN" = "true" ]; then
+    return
+  fi
+
+  automaker_show_banner
+  export AUTOMAKER_BANNER_SHOWN="true"
+}
+`;
+}
+
+/**
+ * Generate prompt based on format
+ */
+function generatePrompt(
+  format: TerminalConfig['promptFormat'],
+  colors: ANSIColors,
+  config: TerminalConfig
+): string {
+  const userHostSegment = config.showUserHost
+    ? `${colors.user}\\u${colors.reset}@${colors.host}\\h${colors.reset}`
+    : '';
+  const pathSegment = config.showPath
+    ? `${colors.path}\\$(automaker_prompt_path)${colors.reset}`
+    : '';
+  const gitSegment = config.showGitBranch
+    ? `${colors.gitBranch}\\$(automaker_git_prompt)${colors.reset}`
+    : '';
+  const timeSegment = config.showTime
+    ? `${colors.gitBranch}[\\$(automaker_prompt_time)]${colors.reset}`
+    : '';
+  const statusSegment = config.showExitStatus
+    ? `${colors.gitDirty}\\$(automaker_prompt_status)${colors.reset}`
+    : '';
+
+  switch (format) {
+    case 'minimal': {
+      const minimalSegments = [timeSegment, userHostSegment, pathSegment, gitSegment, statusSegment]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PS1="${minimalSegments ? `${minimalSegments} ` : ''}${colors.prompt}\\$${colors.reset} "`;
+    }
+
+    case 'powerline': {
+      const powerlineCoreSegments = [
+        userHostSegment ? `[${userHostSegment}]` : '',
+        pathSegment ? `[${pathSegment}]` : '',
+      ].filter((segment) => segment.length > 0);
+      const powerlineCore = powerlineCoreSegments.join('─');
+      const powerlineExtras = [gitSegment, timeSegment, statusSegment]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      const powerlineLine = [powerlineCore, powerlineExtras]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PS1="┌─${powerlineLine}\\n└─${colors.prompt}\\$${colors.reset} "`;
+    }
+
+    case 'starship': {
+      let starshipLine = '';
+      if (userHostSegment && pathSegment) {
+        starshipLine = `${userHostSegment} in ${pathSegment}`;
+      } else {
+        starshipLine = [userHostSegment, pathSegment]
+          .filter((segment) => segment.length > 0)
+          .join(' ');
+      }
+      if (gitSegment) {
+        starshipLine = `${starshipLine}${starshipLine ? ' on ' : ''}${gitSegment}`;
+      }
+      const starshipSegments = [timeSegment, starshipLine, statusSegment]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PS1="${starshipSegments}\\n${colors.prompt}❯${colors.reset} "`;
+    }
+
+    case 'standard':
+    default: {
+      const standardSegments = [
+        timeSegment,
+        userHostSegment ? `[${userHostSegment}]` : '',
+        pathSegment,
+        gitSegment,
+        statusSegment,
+      ]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PS1="${standardSegments ? `${standardSegments} ` : ''}${colors.prompt}\\$${colors.reset} "`;
+    }
+  }
+}
+
+/**
+ * Generate Zsh prompt based on format
+ */
+function generateZshPrompt(
+  format: TerminalConfig['promptFormat'],
+  colors: ANSIColors,
+  config: TerminalConfig
+): string {
+  // Convert bash-style \u, \h, \w to zsh-style %n, %m, %~
+  // Remove bash-style escaping \[ \] (not needed in zsh)
+  const zshColors = {
+    user: colors.user
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    host: colors.host
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    path: colors.path
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    gitBranch: colors.gitBranch
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    gitDirty: colors.gitDirty
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    prompt: colors.prompt
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+    reset: colors.reset
+      .replace(/\\[\[\]\\e]/g, '')
+      .replace(/\\e/g, '%{')
+      .replace(/m\\]/g, 'm%}'),
+  };
+
+  const userHostSegment = config.showUserHost
+    ? `[${zshColors.user}%n${zshColors.reset}@${zshColors.host}%m${zshColors.reset}]`
+    : '';
+  const pathSegment = config.showPath
+    ? `${zshColors.path}$(automaker_prompt_path)${zshColors.reset}`
+    : '';
+  const gitSegment = config.showGitBranch
+    ? `${zshColors.gitBranch}$(automaker_git_prompt)${zshColors.reset}`
+    : '';
+  const timeSegment = config.showTime
+    ? `${zshColors.gitBranch}[$(automaker_prompt_time)]${zshColors.reset}`
+    : '';
+  const statusSegment = config.showExitStatus
+    ? `${zshColors.gitDirty}$(automaker_prompt_status)${zshColors.reset}`
+    : '';
+  const segments = [timeSegment, userHostSegment, pathSegment, gitSegment, statusSegment].filter(
+    (segment) => segment.length > 0
+  );
+  const inlineSegments = segments.join(' ');
+  const inlineWithSpace = inlineSegments ? `${inlineSegments} ` : '';
+
+  switch (format) {
+    case 'minimal': {
+      return `PROMPT="${inlineWithSpace}${zshColors.prompt}%#${zshColors.reset} "`;
+    }
+
+    case 'powerline': {
+      const powerlineCoreSegments = [
+        userHostSegment ? `[${userHostSegment}]` : '',
+        pathSegment ? `[${pathSegment}]` : '',
+      ].filter((segment) => segment.length > 0);
+      const powerlineCore = powerlineCoreSegments.join('─');
+      const powerlineExtras = [gitSegment, timeSegment, statusSegment]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      const powerlineLine = [powerlineCore, powerlineExtras]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PROMPT="┌─${powerlineLine}
+└─${zshColors.prompt}%#${zshColors.reset} "`;
+    }
+
+    case 'starship': {
+      let starshipLine = '';
+      if (userHostSegment && pathSegment) {
+        starshipLine = `${userHostSegment} in ${pathSegment}`;
+      } else {
+        starshipLine = [userHostSegment, pathSegment]
+          .filter((segment) => segment.length > 0)
+          .join(' ');
+      }
+      if (gitSegment) {
+        starshipLine = `${starshipLine}${starshipLine ? ' on ' : ''}${gitSegment}`;
+      }
+      const starshipSegments = [timeSegment, starshipLine, statusSegment]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PROMPT="${starshipSegments}
+${zshColors.prompt}❯${zshColors.reset} "`;
+    }
+
+    case 'standard':
+    default: {
+      const standardSegments = [
+        timeSegment,
+        userHostSegment ? `[${userHostSegment}]` : '',
+        pathSegment,
+        gitSegment,
+        statusSegment,
+      ]
+        .filter((segment) => segment.length > 0)
+        .join(' ');
+      return `PROMPT="${standardSegments ? `${standardSegments} ` : ''}${zshColors.prompt}%#${zshColors.reset} "`;
+    }
+  }
+}
+
+/**
+ * Generate custom aliases section
+ */
+function generateAliases(config: TerminalConfig): string {
+  if (!config.customAliases) return '';
+
+  // Escape and validate aliases
+  const escapedAliases = shellEscape(config.customAliases);
+  return `
+# Custom aliases
+${escapedAliases}
+`;
+}
+
+/**
+ * Generate custom environment variables section
+ */
+function generateEnvVars(config: TerminalConfig): string {
+  if (!config.customEnvVars || Object.keys(config.customEnvVars).length === 0) {
+    return '';
+  }
+
+  const validEnvVars = Object.entries(config.customEnvVars)
+    .filter(([name]) => isValidEnvVarName(name))
+    .map(([name, value]) => `export ${name}="${shellEscape(value)}"`)
+    .join('\n');
+
+  return validEnvVars
+    ? `
+# Custom environment variables
+${validEnvVars}
+`
+    : '';
+}
+
+/**
+ * Generate bashrc configuration
+ */
+export function generateBashrc(theme: TerminalTheme, config: TerminalConfig): string {
+  const colors = getThemeANSIColors(theme);
+  const promptLine = generatePrompt(config.promptFormat, colors, config);
+  const promptInitializer = generateOhMyPoshInit(OMP_SHELL_BASH, promptLine);
+
+  return `#!/bin/bash
+# Automaker Terminal Configuration v1.0
+# This file is automatically generated - manual edits will be overwritten
+
+# Source user's original bashrc first (preserves user configuration)
+if [ -f "$HOME/.bashrc" ]; then
+    source "$HOME/.bashrc"
+fi
+
+# Load Automaker theme colors
+AUTOMAKER_THEME="\${AUTOMAKER_THEME:-dark}"
+if [ -f "\${BASH_SOURCE%/*}/themes/$AUTOMAKER_THEME.sh" ]; then
+    source "\${BASH_SOURCE%/*}/themes/$AUTOMAKER_THEME.sh"
+fi
+
+# Load common functions (git prompt)
+if [ -f "\${BASH_SOURCE%/*}/common.sh" ]; then
+    source "\${BASH_SOURCE%/*}/common.sh"
+fi
+
+# Show Automaker banner on shell start
+if command -v automaker_show_banner_once >/dev/null 2>&1; then
+    automaker_show_banner_once
+fi
+
+# Set custom prompt (only if enabled)
+if [ "$AUTOMAKER_CUSTOM_PROMPT" = "true" ]; then
+    ${promptInitializer}
+fi
+${generateAliases(config)}${generateEnvVars(config)}
+# Load user customizations (if exists)
+if [ -f "\${BASH_SOURCE%/*}/user-custom.sh" ]; then
+    source "\${BASH_SOURCE%/*}/user-custom.sh"
+fi
+`;
+}
+
+/**
+ * Generate zshrc configuration
+ */
+export function generateZshrc(theme: TerminalTheme, config: TerminalConfig): string {
+  const colors = getThemeANSIColors(theme);
+  const promptLine = generateZshPrompt(config.promptFormat, colors, config);
+  const promptInitializer = generateOhMyPoshInit(OMP_SHELL_ZSH, promptLine);
+
+  return `#!/bin/zsh
+# Automaker Terminal Configuration v1.0
+# This file is automatically generated - manual edits will be overwritten
+
+# Source user's original zshrc first (preserves user configuration)
+if [ -f "$HOME/.zshrc" ]; then
+    source "$HOME/.zshrc"
+fi
+
+# Load Automaker theme colors
+AUTOMAKER_THEME="\${AUTOMAKER_THEME:-dark}"
+if [ -f "\${ZDOTDIR:-\${0:a:h}}/themes/$AUTOMAKER_THEME.sh" ]; then
+    source "\${ZDOTDIR:-\${0:a:h}}/themes/$AUTOMAKER_THEME.sh"
+fi
+
+# Load common functions (git prompt)
+if [ -f "\${ZDOTDIR:-\${0:a:h}}/common.sh" ]; then
+    source "\${ZDOTDIR:-\${0:a:h}}/common.sh"
+fi
+
+# Enable command substitution in PROMPT
+setopt PROMPT_SUBST
+
+# Show Automaker banner on shell start
+if command -v automaker_show_banner_once >/dev/null 2>&1; then
+    automaker_show_banner_once
+fi
+
+# Set custom prompt (only if enabled)
+if [ "$AUTOMAKER_CUSTOM_PROMPT" = "true" ]; then
+    ${promptInitializer}
+fi
+${generateAliases(config)}${generateEnvVars(config)}
+# Load user customizations (if exists)
+if [ -f "\${ZDOTDIR:-\${0:a:h}}/user-custom.sh" ]; then
+    source "\${ZDOTDIR:-\${0:a:h}}/user-custom.sh"
+fi
+`;
+}
+
+/**
+ * Generate theme color exports for shell
+ */
+export function generateThemeColors(theme: TerminalTheme): string {
+  const colors = getThemeANSIColors(theme);
+  const rawColors = {
+    user: stripPromptEscapes(colors.user),
+    host: stripPromptEscapes(colors.host),
+    path: stripPromptEscapes(colors.path),
+    gitBranch: stripPromptEscapes(colors.gitBranch),
+    gitDirty: stripPromptEscapes(colors.gitDirty),
+    prompt: stripPromptEscapes(colors.prompt),
+    reset: stripPromptEscapes(colors.reset),
+  };
+
+  return `#!/bin/sh
+# Automaker Theme Colors
+# This file is automatically generated - manual edits will be overwritten
+
+# ANSI color codes for prompt
+export COLOR_USER="${colors.user}"
+export COLOR_HOST="${colors.host}"
+export COLOR_PATH="${colors.path}"
+export COLOR_GIT_BRANCH="${colors.gitBranch}"
+export COLOR_GIT_DIRTY="${colors.gitDirty}"
+export COLOR_PROMPT="${colors.prompt}"
+export COLOR_RESET="${colors.reset}"
+
+# ANSI color codes for banner output (no prompt escapes)
+export COLOR_USER_RAW="${rawColors.user}"
+export COLOR_HOST_RAW="${rawColors.host}"
+export COLOR_PATH_RAW="${rawColors.path}"
+export COLOR_GIT_BRANCH_RAW="${rawColors.gitBranch}"
+export COLOR_GIT_DIRTY_RAW="${rawColors.gitDirty}"
+export COLOR_PROMPT_RAW="${rawColors.prompt}"
+export COLOR_RESET_RAW="${rawColors.reset}"
+`;
+}
+
+/**
+ * Get shell name from file extension
+ */
+export function getShellName(rcFile: string): 'bash' | 'zsh' | 'sh' | null {
+  if (rcFile.endsWith('.sh') && rcFile.includes('bashrc')) return 'bash';
+  if (rcFile.endsWith('.zsh') || rcFile.endsWith('.zshrc')) return 'zsh';
+  if (rcFile.endsWith('.sh')) return 'sh';
+  return null;
+}

libs/platform/src/system-paths.ts

@@ -750,6 +750,9 @@ export function electronUserDataWriteFileSync(
     throw new Error('[SystemPaths] Electron userData path not initialized');
   }
   const fullPath = path.join(electronUserDataPath, relativePath);
+  // Ensure parent directory exists (may not exist on first launch)
+  const dir = path.dirname(fullPath);
+  fsSync.mkdirSync(dir, { recursive: true });
   fsSync.writeFileSync(fullPath, data, options);
 }
 

libs/platform/src/terminal-theme-colors.ts

@@ -0,0 +1,468 @@
+/**
+ * Terminal Theme Colors - Color definitions for all 40 themes
+ *
+ * This module contains only the raw color data for terminal themes,
+ * extracted from the UI package to avoid circular dependencies.
+ * These colors are used by both UI (xterm.js) and server (RC file generation).
+ */
+
+import type { ThemeMode } from '@automaker/types';
+import type { TerminalTheme } from './rc-generator.js';
+
+// Dark theme (default)
+const darkTheme: TerminalTheme = {
+  background: '#0a0a0a',
+  foreground: '#d4d4d4',
+  cursor: '#d4d4d4',
+  cursorAccent: '#0a0a0a',
+  selectionBackground: '#264f78',
+  black: '#1e1e1e',
+  red: '#f44747',
+  green: '#6a9955',
+  yellow: '#dcdcaa',
+  blue: '#569cd6',
+  magenta: '#c586c0',
+  cyan: '#4ec9b0',
+  white: '#d4d4d4',
+  brightBlack: '#808080',
+  brightRed: '#f44747',
+  brightGreen: '#6a9955',
+  brightYellow: '#dcdcaa',
+  brightBlue: '#569cd6',
+  brightMagenta: '#c586c0',
+  brightCyan: '#4ec9b0',
+  brightWhite: '#ffffff',
+};
+
+// Light theme
+const lightTheme: TerminalTheme = {
+  background: '#ffffff',
+  foreground: '#383a42',
+  cursor: '#383a42',
+  cursorAccent: '#ffffff',
+  selectionBackground: '#add6ff',
+  black: '#383a42',
+  red: '#e45649',
+  green: '#50a14f',
+  yellow: '#c18401',
+  blue: '#4078f2',
+  magenta: '#a626a4',
+  cyan: '#0184bc',
+  white: '#fafafa',
+  brightBlack: '#4f525e',
+  brightRed: '#e06c75',
+  brightGreen: '#98c379',
+  brightYellow: '#e5c07b',
+  brightBlue: '#61afef',
+  brightMagenta: '#c678dd',
+  brightCyan: '#56b6c2',
+  brightWhite: '#ffffff',
+};
+
+// Retro / Cyberpunk theme - neon green on black
+const retroTheme: TerminalTheme = {
+  background: '#000000',
+  foreground: '#39ff14',
+  cursor: '#39ff14',
+  cursorAccent: '#000000',
+  selectionBackground: '#39ff14',
+  selectionForeground: '#000000',
+  black: '#000000',
+  red: '#ff0055',
+  green: '#39ff14',
+  yellow: '#ffff00',
+  blue: '#00ffff',
+  magenta: '#ff00ff',
+  cyan: '#00ffff',
+  white: '#39ff14',
+  brightBlack: '#555555',
+  brightRed: '#ff5555',
+  brightGreen: '#55ff55',
+  brightYellow: '#ffff55',
+  brightBlue: '#55ffff',
+  brightMagenta: '#ff55ff',
+  brightCyan: '#55ffff',
+  brightWhite: '#ffffff',
+};
+
+// Dracula theme
+const draculaTheme: TerminalTheme = {
+  background: '#282a36',
+  foreground: '#f8f8f2',
+  cursor: '#f8f8f2',
+  cursorAccent: '#282a36',
+  selectionBackground: '#44475a',
+  black: '#21222c',
+  red: '#ff5555',
+  green: '#50fa7b',
+  yellow: '#f1fa8c',
+  blue: '#bd93f9',
+  magenta: '#ff79c6',
+  cyan: '#8be9fd',
+  white: '#f8f8f2',
+  brightBlack: '#6272a4',
+  brightRed: '#ff6e6e',
+  brightGreen: '#69ff94',
+  brightYellow: '#ffffa5',
+  brightBlue: '#d6acff',
+  brightMagenta: '#ff92df',
+  brightCyan: '#a4ffff',
+  brightWhite: '#ffffff',
+};
+
+// Nord theme
+const nordTheme: TerminalTheme = {
+  background: '#2e3440',
+  foreground: '#d8dee9',
+  cursor: '#d8dee9',
+  cursorAccent: '#2e3440',
+  selectionBackground: '#434c5e',
+  black: '#3b4252',
+  red: '#bf616a',
+  green: '#a3be8c',
+  yellow: '#ebcb8b',
+  blue: '#81a1c1',
+  magenta: '#b48ead',
+  cyan: '#88c0d0',
+  white: '#e5e9f0',
+  brightBlack: '#4c566a',
+  brightRed: '#bf616a',
+  brightGreen: '#a3be8c',
+  brightYellow: '#ebcb8b',
+  brightBlue: '#81a1c1',
+  brightMagenta: '#b48ead',
+  brightCyan: '#8fbcbb',
+  brightWhite: '#eceff4',
+};
+
+// Monokai theme
+const monokaiTheme: TerminalTheme = {
+  background: '#272822',
+  foreground: '#f8f8f2',
+  cursor: '#f8f8f2',
+  cursorAccent: '#272822',
+  selectionBackground: '#49483e',
+  black: '#272822',
+  red: '#f92672',
+  green: '#a6e22e',
+  yellow: '#f4bf75',
+  blue: '#66d9ef',
+  magenta: '#ae81ff',
+  cyan: '#a1efe4',
+  white: '#f8f8f2',
+  brightBlack: '#75715e',
+  brightRed: '#f92672',
+  brightGreen: '#a6e22e',
+  brightYellow: '#f4bf75',
+  brightBlue: '#66d9ef',
+  brightMagenta: '#ae81ff',
+  brightCyan: '#a1efe4',
+  brightWhite: '#f9f8f5',
+};
+
+// Tokyo Night theme
+const tokyonightTheme: TerminalTheme = {
+  background: '#1a1b26',
+  foreground: '#a9b1d6',
+  cursor: '#c0caf5',
+  cursorAccent: '#1a1b26',
+  selectionBackground: '#33467c',
+  black: '#15161e',
+  red: '#f7768e',
+  green: '#9ece6a',
+  yellow: '#e0af68',
+  blue: '#7aa2f7',
+  magenta: '#bb9af7',
+  cyan: '#7dcfff',
+  white: '#a9b1d6',
+  brightBlack: '#414868',
+  brightRed: '#f7768e',
+  brightGreen: '#9ece6a',
+  brightYellow: '#e0af68',
+  brightBlue: '#7aa2f7',
+  brightMagenta: '#bb9af7',
+  brightCyan: '#7dcfff',
+  brightWhite: '#c0caf5',
+};
+
+// Solarized Dark theme
+const solarizedTheme: TerminalTheme = {
+  background: '#002b36',
+  foreground: '#93a1a1',
+  cursor: '#93a1a1',
+  cursorAccent: '#002b36',
+  selectionBackground: '#073642',
+  black: '#073642',
+  red: '#dc322f',
+  green: '#859900',
+  yellow: '#b58900',
+  blue: '#268bd2',
+  magenta: '#d33682',
+  cyan: '#2aa198',
+  white: '#eee8d5',
+  brightBlack: '#002b36',
+  brightRed: '#cb4b16',
+  brightGreen: '#586e75',
+  brightYellow: '#657b83',
+  brightBlue: '#839496',
+  brightMagenta: '#6c71c4',
+  brightCyan: '#93a1a1',
+  brightWhite: '#fdf6e3',
+};
+
+// Gruvbox Dark theme
+const gruvboxTheme: TerminalTheme = {
+  background: '#282828',
+  foreground: '#ebdbb2',
+  cursor: '#ebdbb2',
+  cursorAccent: '#282828',
+  selectionBackground: '#504945',
+  black: '#282828',
+  red: '#cc241d',
+  green: '#98971a',
+  yellow: '#d79921',
+  blue: '#458588',
+  magenta: '#b16286',
+  cyan: '#689d6a',
+  white: '#a89984',
+  brightBlack: '#928374',
+  brightRed: '#fb4934',
+  brightGreen: '#b8bb26',
+  brightYellow: '#fabd2f',
+  brightBlue: '#83a598',
+  brightMagenta: '#d3869b',
+  brightCyan: '#8ec07c',
+  brightWhite: '#ebdbb2',
+};
+
+// Catppuccin Mocha theme
+const catppuccinTheme: TerminalTheme = {
+  background: '#1e1e2e',
+  foreground: '#cdd6f4',
+  cursor: '#f5e0dc',
+  cursorAccent: '#1e1e2e',
+  selectionBackground: '#45475a',
+  black: '#45475a',
+  red: '#f38ba8',
+  green: '#a6e3a1',
+  yellow: '#f9e2af',
+  blue: '#89b4fa',
+  magenta: '#cba6f7',
+  cyan: '#94e2d5',
+  white: '#bac2de',
+  brightBlack: '#585b70',
+  brightRed: '#f38ba8',
+  brightGreen: '#a6e3a1',
+  brightYellow: '#f9e2af',
+  brightBlue: '#89b4fa',
+  brightMagenta: '#cba6f7',
+  brightCyan: '#94e2d5',
+  brightWhite: '#a6adc8',
+};
+
+// One Dark theme
+const onedarkTheme: TerminalTheme = {
+  background: '#282c34',
+  foreground: '#abb2bf',
+  cursor: '#528bff',
+  cursorAccent: '#282c34',
+  selectionBackground: '#3e4451',
+  black: '#282c34',
+  red: '#e06c75',
+  green: '#98c379',
+  yellow: '#e5c07b',
+  blue: '#61afef',
+  magenta: '#c678dd',
+  cyan: '#56b6c2',
+  white: '#abb2bf',
+  brightBlack: '#5c6370',
+  brightRed: '#e06c75',
+  brightGreen: '#98c379',
+  brightYellow: '#e5c07b',
+  brightBlue: '#61afef',
+  brightMagenta: '#c678dd',
+  brightCyan: '#56b6c2',
+  brightWhite: '#ffffff',
+};
+
+// Synthwave '84 theme
+const synthwaveTheme: TerminalTheme = {
+  background: '#262335',
+  foreground: '#ffffff',
+  cursor: '#ff7edb',
+  cursorAccent: '#262335',
+  selectionBackground: '#463465',
+  black: '#262335',
+  red: '#fe4450',
+  green: '#72f1b8',
+  yellow: '#fede5d',
+  blue: '#03edf9',
+  magenta: '#ff7edb',
+  cyan: '#03edf9',
+  white: '#ffffff',
+  brightBlack: '#614d85',
+  brightRed: '#fe4450',
+  brightGreen: '#72f1b8',
+  brightYellow: '#f97e72',
+  brightBlue: '#03edf9',
+  brightMagenta: '#ff7edb',
+  brightCyan: '#03edf9',
+  brightWhite: '#ffffff',
+};
+
+// Red theme
+const redTheme: TerminalTheme = {
+  background: '#1a0a0a',
+  foreground: '#c8b0b0',
+  cursor: '#ff4444',
+  cursorAccent: '#1a0a0a',
+  selectionBackground: '#5a2020',
+  black: '#2a1010',
+  red: '#ff4444',
+  green: '#6a9a6a',
+  yellow: '#ccaa55',
+  blue: '#6688aa',
+  magenta: '#aa5588',
+  cyan: '#558888',
+  white: '#b0a0a0',
+  brightBlack: '#6a4040',
+  brightRed: '#ff6666',
+  brightGreen: '#88bb88',
+  brightYellow: '#ddbb66',
+  brightBlue: '#88aacc',
+  brightMagenta: '#cc77aa',
+  brightCyan: '#77aaaa',
+  brightWhite: '#d0c0c0',
+};
+
+// Cream theme
+const creamTheme: TerminalTheme = {
+  background: '#f5f3ee',
+  foreground: '#5a4a3a',
+  cursor: '#9d6b53',
+  cursorAccent: '#f5f3ee',
+  selectionBackground: '#d4c4b0',
+  black: '#5a4a3a',
+  red: '#c85a4f',
+  green: '#7a9a6a',
+  yellow: '#c9a554',
+  blue: '#6b8aaa',
+  magenta: '#a66a8a',
+  cyan: '#5a9a8a',
+  white: '#b0a090',
+  brightBlack: '#8a7a6a',
+  brightRed: '#e07060',
+  brightGreen: '#90b080',
+  brightYellow: '#e0bb70',
+  brightBlue: '#80a0c0',
+  brightMagenta: '#c080a0',
+  brightCyan: '#70b0a0',
+  brightWhite: '#d0c0b0',
+};
+
+// Sunset theme
+const sunsetTheme: TerminalTheme = {
+  background: '#1e1a24',
+  foreground: '#f2e8dd',
+  cursor: '#dd8855',
+  cursorAccent: '#1e1a24',
+  selectionBackground: '#3a2a40',
+  black: '#1e1a24',
+  red: '#dd6655',
+  green: '#88bb77',
+  yellow: '#ddaa66',
+  blue: '#6699cc',
+  magenta: '#cc7799',
+  cyan: '#66ccaa',
+  white: '#e8d8c8',
+  brightBlack: '#4a3a50',
+  brightRed: '#ee8866',
+  brightGreen: '#99cc88',
+  brightYellow: '#eebb77',
+  brightBlue: '#88aadd',
+  brightMagenta: '#dd88aa',
+  brightCyan: '#88ddbb',
+  brightWhite: '#f5e8dd',
+};
+
+// Gray theme
+const grayTheme: TerminalTheme = {
+  background: '#2a2d32',
+  foreground: '#d0d0d5',
+  cursor: '#8fa0c0',
+  cursorAccent: '#2a2d32',
+  selectionBackground: '#3a3f48',
+  black: '#2a2d32',
+  red: '#d87070',
+  green: '#78b088',
+  yellow: '#d0b060',
+  blue: '#7090c0',
+  magenta: '#a880b0',
+  cyan: '#60a0b0',
+  white: '#b0b0b8',
+  brightBlack: '#606068',
+  brightRed: '#e88888',
+  brightGreen: '#90c8a0',
+  brightYellow: '#e0c878',
+  brightBlue: '#90b0d8',
+  brightMagenta: '#c098c8',
+  brightCyan: '#80b8c8',
+  brightWhite: '#e0e0e8',
+};
+
+/**
+ * Theme color mapping for all 40 themes
+ */
+export const terminalThemeColors: Record<ThemeMode, TerminalTheme> = {
+  // Special
+  system: darkTheme, // Resolved at runtime based on OS preference
+  // Dark themes (16)
+  dark: darkTheme,
+  retro: retroTheme,
+  dracula: draculaTheme,
+  nord: nordTheme,
+  monokai: monokaiTheme,
+  tokyonight: tokyonightTheme,
+  solarized: solarizedTheme,
+  gruvbox: gruvboxTheme,
+  catppuccin: catppuccinTheme,
+  onedark: onedarkTheme,
+  synthwave: synthwaveTheme,
+  red: redTheme,
+  sunset: sunsetTheme,
+  gray: grayTheme,
+  forest: gruvboxTheme, // Green-ish theme
+  ocean: nordTheme, // Blue-ish theme
+  ember: monokaiTheme, // Warm orange theme
+  'ayu-dark': darkTheme,
+  'ayu-mirage': darkTheme,
+  matcha: nordTheme,
+  // Light themes (16)
+  light: lightTheme,
+  cream: creamTheme,
+  solarizedlight: lightTheme,
+  github: lightTheme,
+  paper: lightTheme,
+  rose: lightTheme,
+  mint: lightTheme,
+  lavender: lightTheme,
+  sand: creamTheme,
+  sky: lightTheme,
+  peach: creamTheme,
+  snow: lightTheme,
+  sepia: creamTheme,
+  gruvboxlight: creamTheme,
+  nordlight: lightTheme,
+  blossom: lightTheme,
+  'ayu-light': lightTheme,
+  onelight: lightTheme,
+  bluloco: lightTheme,
+  feather: lightTheme,
+};
+
+/**
+ * Get terminal theme colors for a given theme mode
+ */
+export function getTerminalThemeColors(theme: ThemeMode): TerminalTheme {
+  return terminalThemeColors[theme] || darkTheme;
+}

libs/platform/src/terminal.ts

@@ -140,9 +140,9 @@ const SUPPORTED_TERMINALS: TerminalDefinition[] = [
   {
     id: 'warp',
     name: 'Warp',
-    cliCommand: 'warp',
+    cliCommand: 'warp-cli',
+    cliAliases: ['warp-terminal', 'warp'],
     macAppName: 'Warp',
-    platform: 'darwin',
   },
   {
     id: 'ghostty',
@@ -476,6 +476,11 @@ async function executeTerminalCommand(terminal: TerminalInfo, targetPath: string
       await spawnDetached(command, [`--working-directory=${targetPath}`]);
       break;
 
+    case 'warp':
+      // Warp: uses --cwd flag (CLI mode, not app bundle)
+      await spawnDetached(command, ['--cwd', targetPath]);
+      break;
+
     case 'alacritty':
       // Alacritty: uses --working-directory flag
       await spawnDetached(command, ['--working-directory', targetPath]);

libs/platform/tests/rc-file-manager.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { needsRegeneration, writeRcFiles } from '../src/rc-file-manager';
+import { terminalThemeColors } from '../src/terminal-theme-colors';
+import type { TerminalConfig } from '../src/rc-generator';
+import type { ThemeMode } from '@automaker/types';
+
+describe('rc-file-manager.ts', () => {
+  let tempDir: string;
+  let projectPath: string;
+
+  const TEMP_DIR_PREFIX = 'platform-rc-files-test-';
+  const PROJECT_DIR_NAME = 'test-project';
+  const THEME_DARK = 'dark' as ThemeMode;
+  const THEME_LIGHT = 'light' as ThemeMode;
+  const PROMPT_FORMAT_STANDARD: TerminalConfig['promptFormat'] = 'standard';
+  const PROMPT_FORMAT_MINIMAL: TerminalConfig['promptFormat'] = 'minimal';
+  const EMPTY_ALIASES = '';
+  const PATH_STYLE_FULL: TerminalConfig['pathStyle'] = 'full';
+  const PATH_DEPTH_DEFAULT = 0;
+
+  const baseConfig: TerminalConfig = {
+    enabled: true,
+    customPrompt: true,
+    promptFormat: PROMPT_FORMAT_STANDARD,
+    showGitBranch: true,
+    showGitStatus: true,
+    showUserHost: true,
+    showPath: true,
+    pathStyle: PATH_STYLE_FULL,
+    pathDepth: PATH_DEPTH_DEFAULT,
+    showTime: false,
+    showExitStatus: false,
+    customAliases: EMPTY_ALIASES,
+    customEnvVars: {},
+  };
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), TEMP_DIR_PREFIX));
+    projectPath = path.join(tempDir, PROJECT_DIR_NAME);
+    await fs.mkdir(projectPath, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should not regenerate when signature matches', async () => {
+    await writeRcFiles(
+      projectPath,
+      THEME_DARK,
+      baseConfig,
+      terminalThemeColors[THEME_DARK],
+      terminalThemeColors
+    );
+
+    const needsRegen = await needsRegeneration(projectPath, THEME_DARK, baseConfig);
+
+    expect(needsRegen).toBe(false);
+  });
+
+  it('should regenerate when config changes', async () => {
+    await writeRcFiles(
+      projectPath,
+      THEME_DARK,
+      baseConfig,
+      terminalThemeColors[THEME_DARK],
+      terminalThemeColors
+    );
+
+    const updatedConfig: TerminalConfig = {
+      ...baseConfig,
+      promptFormat: PROMPT_FORMAT_MINIMAL,
+    };
+
+    const needsRegen = await needsRegeneration(projectPath, THEME_DARK, updatedConfig);
+
+    expect(needsRegen).toBe(true);
+  });
+
+  it('should regenerate when theme changes', async () => {
+    await writeRcFiles(
+      projectPath,
+      THEME_DARK,
+      baseConfig,
+      terminalThemeColors[THEME_DARK],
+      terminalThemeColors
+    );
+
+    const needsRegen = await needsRegeneration(projectPath, THEME_LIGHT, baseConfig);
+
+    expect(needsRegen).toBe(true);
+  });
+});

libs/platform/tests/rc-generator.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { generateCommonFunctions, generateThemeColors } from '../src/rc-generator';
+import { terminalThemeColors } from '../src/terminal-theme-colors';
+import type { TerminalConfig } from '../src/rc-generator';
+import type { ThemeMode } from '@automaker/types';
+
+describe('rc-generator.ts', () => {
+  const THEME_DARK = 'dark' as ThemeMode;
+  const PROMPT_FORMAT_STANDARD: TerminalConfig['promptFormat'] = 'standard';
+  const EMPTY_ALIASES = '';
+  const EMPTY_ENV_VARS = {};
+  const PATH_STYLE_FULL: TerminalConfig['pathStyle'] = 'full';
+  const PATH_DEPTH_DEFAULT = 0;
+  const EXPECTED_BANNER_FUNCTION = 'automaker_show_banner_once';
+  const RAW_COLOR_PREFIX = 'export COLOR_USER_RAW=';
+  const RAW_COLOR_ESCAPE_START = '\\\\[';
+  const RAW_COLOR_ESCAPE_END = '\\\\]';
+  const STARTUP_PRIMARY_COLOR = '38;5;51m';
+  const STARTUP_SECONDARY_COLOR = '38;5;39m';
+  const STARTUP_ACCENT_COLOR = '38;5;33m';
+
+  const baseConfig: TerminalConfig = {
+    enabled: true,
+    customPrompt: true,
+    promptFormat: PROMPT_FORMAT_STANDARD,
+    showGitBranch: true,
+    showGitStatus: true,
+    showUserHost: true,
+    showPath: true,
+    pathStyle: PATH_STYLE_FULL,
+    pathDepth: PATH_DEPTH_DEFAULT,
+    showTime: false,
+    showExitStatus: false,
+    customAliases: EMPTY_ALIASES,
+    customEnvVars: EMPTY_ENV_VARS,
+  };
+
+  it('includes banner functions in common shell script', () => {
+    const output = generateCommonFunctions(baseConfig);
+
+    expect(output).toContain(EXPECTED_BANNER_FUNCTION);
+    expect(output).toContain(STARTUP_PRIMARY_COLOR);
+    expect(output).toContain(STARTUP_SECONDARY_COLOR);
+    expect(output).toContain(STARTUP_ACCENT_COLOR);
+  });
+
+  it('exports raw banner colors without prompt escape wrappers', () => {
+    const output = generateThemeColors(terminalThemeColors[THEME_DARK]);
+    const rawLine = output.split('\n').find((line) => line.startsWith(RAW_COLOR_PREFIX));
+
+    expect(rawLine).toBeDefined();
+    expect(rawLine).not.toContain(RAW_COLOR_ESCAPE_START);
+    expect(rawLine).not.toContain(RAW_COLOR_ESCAPE_END);
+  });
+});

libs/prompts/src/defaults.ts

@@ -965,8 +965,20 @@ export const DEFAULT_PLAN_REVISION_TEMPLATE = `The user has requested revisions
 
 ## Instructions
 Please regenerate the specification incorporating the user's feedback.
-Keep the same format with the \`\`\`tasks block for task definitions.
+**Current planning mode: {{planningMode}}**
-After generating the revised spec, output:
+
+**CRITICAL REQUIREMENT**: Your revised specification MUST include a \`\`\`tasks code block containing task definitions in the EXACT format shown below. This is MANDATORY - without the tasks block, the system cannot track or execute tasks properly.
+
+### Required Task Format
+{{taskFormatExample}}
+
+**IMPORTANT**:
+1. The \`\`\`tasks block must appear in your response
+2. Each task MUST start with "- [ ] T###:" where ### is a sequential number (T001, T002, T003, etc.)
+3. Each task MUST include "| File:" followed by the primary file path
+4. Tasks should be ordered by dependencies (foundational tasks first)
+
+After generating the revised spec with the tasks block, output:
 "[SPEC_GENERATED] Please review the revised specification above."`;
 
 export const DEFAULT_CONTINUATION_AFTER_APPROVAL_TEMPLATE = `The plan/specification has been approved. Now implement it.

libs/types/src/settings.ts

@@ -27,14 +27,16 @@ export type { ModelAlias };
  *
  * Includes system theme and multiple color schemes organized by dark/light:
  * - System: Respects OS dark/light mode preference
- * - Dark themes (16): dark, retro, dracula, nord, monokai, tokyonight, solarized,
+ * - Dark themes (20): dark, retro, dracula, nord, monokai, tokyonight, solarized,
- *   gruvbox, catppuccin, onedark, synthwave, red, sunset, gray, forest, ocean
+ *   gruvbox, catppuccin, onedark, synthwave, red, sunset, gray, forest, ocean,
- * - Light themes (16): light, cream, solarizedlight, github, paper, rose, mint,
+ *   ember, ayu-dark, ayu-mirage, matcha
- *   lavender, sand, sky, peach, snow, sepia, gruvboxlight, nordlight, blossom
+ * - Light themes (20): light, cream, solarizedlight, github, paper, rose, mint,
+ *   lavender, sand, sky, peach, snow, sepia, gruvboxlight, nordlight, blossom,
+ *   ayu-light, onelight, bluloco, feather
  */
 export type ThemeMode =
   | 'system'
-  // Dark themes (16)
+  // Dark themes (20)
   | 'dark'
   | 'retro'
   | 'dracula'
@@ -51,7 +53,11 @@ export type ThemeMode =
   | 'gray'
   | 'forest'
   | 'ocean'
-  // Light themes (16)
+  | 'ember'
+  | 'ayu-dark'
+  | 'ayu-mirage'
+  | 'matcha'
+  // Light themes (20)
   | 'light'
   | 'cream'
   | 'solarizedlight'
@@ -67,7 +73,138 @@ export type ThemeMode =
   | 'sepia'
   | 'gruvboxlight'
   | 'nordlight'
-  | 'blossom';
+  | 'blossom'
+  | 'ayu-light'
+  | 'onelight'
+  | 'bluloco'
+  | 'feather';
+
+export type TerminalPromptTheme =
+  | 'custom'
+  | 'omp-1_shell'
+  | 'omp-agnoster'
+  | 'omp-agnoster.minimal'
+  | 'omp-agnosterplus'
+  | 'omp-aliens'
+  | 'omp-amro'
+  | 'omp-atomic'
+  | 'omp-atomicBit'
+  | 'omp-avit'
+  | 'omp-blue-owl'
+  | 'omp-blueish'
+  | 'omp-bubbles'
+  | 'omp-bubblesextra'
+  | 'omp-bubblesline'
+  | 'omp-capr4n'
+  | 'omp-catppuccin'
+  | 'omp-catppuccin_frappe'
+  | 'omp-catppuccin_latte'
+  | 'omp-catppuccin_macchiato'
+  | 'omp-catppuccin_mocha'
+  | 'omp-cert'
+  | 'omp-chips'
+  | 'omp-cinnamon'
+  | 'omp-clean-detailed'
+  | 'omp-cloud-context'
+  | 'omp-cloud-native-azure'
+  | 'omp-cobalt2'
+  | 'omp-craver'
+  | 'omp-darkblood'
+  | 'omp-devious-diamonds'
+  | 'omp-di4am0nd'
+  | 'omp-dracula'
+  | 'omp-easy-term'
+  | 'omp-emodipt'
+  | 'omp-emodipt-extend'
+  | 'omp-fish'
+  | 'omp-free-ukraine'
+  | 'omp-froczh'
+  | 'omp-gmay'
+  | 'omp-glowsticks'
+  | 'omp-grandpa-style'
+  | 'omp-gruvbox'
+  | 'omp-half-life'
+  | 'omp-honukai'
+  | 'omp-hotstick.minimal'
+  | 'omp-hul10'
+  | 'omp-hunk'
+  | 'omp-huvix'
+  | 'omp-if_tea'
+  | 'omp-illusi0n'
+  | 'omp-iterm2'
+  | 'omp-jandedobbeleer'
+  | 'omp-jblab_2021'
+  | 'omp-jonnychipz'
+  | 'omp-json'
+  | 'omp-jtracey93'
+  | 'omp-jv_sitecorian'
+  | 'omp-kali'
+  | 'omp-kushal'
+  | 'omp-lambda'
+  | 'omp-lambdageneration'
+  | 'omp-larserikfinholt'
+  | 'omp-lightgreen'
+  | 'omp-M365Princess'
+  | 'omp-marcduiker'
+  | 'omp-markbull'
+  | 'omp-material'
+  | 'omp-microverse-power'
+  | 'omp-mojada'
+  | 'omp-montys'
+  | 'omp-mt'
+  | 'omp-multiverse-neon'
+  | 'omp-negligible'
+  | 'omp-neko'
+  | 'omp-night-owl'
+  | 'omp-nordtron'
+  | 'omp-nu4a'
+  | 'omp-onehalf.minimal'
+  | 'omp-paradox'
+  | 'omp-pararussel'
+  | 'omp-patriksvensson'
+  | 'omp-peru'
+  | 'omp-pixelrobots'
+  | 'omp-plague'
+  | 'omp-poshmon'
+  | 'omp-powerlevel10k_classic'
+  | 'omp-powerlevel10k_lean'
+  | 'omp-powerlevel10k_modern'
+  | 'omp-powerlevel10k_rainbow'
+  | 'omp-powerline'
+  | 'omp-probua.minimal'
+  | 'omp-pure'
+  | 'omp-quick-term'
+  | 'omp-remk'
+  | 'omp-robbyrussell'
+  | 'omp-rudolfs-dark'
+  | 'omp-rudolfs-light'
+  | 'omp-sim-web'
+  | 'omp-slim'
+  | 'omp-slimfat'
+  | 'omp-smoothie'
+  | 'omp-sonicboom_dark'
+  | 'omp-sonicboom_light'
+  | 'omp-sorin'
+  | 'omp-space'
+  | 'omp-spaceship'
+  | 'omp-star'
+  | 'omp-stelbent-compact.minimal'
+  | 'omp-stelbent.minimal'
+  | 'omp-takuya'
+  | 'omp-the-unnamed'
+  | 'omp-thecyberden'
+  | 'omp-tiwahu'
+  | 'omp-tokyo'
+  | 'omp-tokyonight_storm'
+  | 'omp-tonybaloney'
+  | 'omp-uew'
+  | 'omp-unicorn'
+  | 'omp-velvet'
+  | 'omp-wholespace'
+  | 'omp-wopian'
+  | 'omp-xtoys'
+  | 'omp-ys'
+  | 'omp-zash';
 
 /** PlanningMode - Planning levels for feature generation workflows */
 export type PlanningMode = 'skip' | 'lite' | 'spec' | 'full';
@@ -840,6 +977,39 @@ export interface GlobalSettings {
   // Terminal Configuration
   /** How to open terminals from "Open in Terminal" worktree action */
   openTerminalMode?: 'newTab' | 'split';
+  /** Custom terminal configuration settings (prompt theming, aliases, env vars) */
+  terminalConfig?: {
+    /** Enable custom terminal configurations (default: false) */
+    enabled: boolean;
+    /** Enable custom prompt (default: true when enabled) */
+    customPrompt: boolean;
+    /** Prompt format template */
+    promptFormat: 'standard' | 'minimal' | 'powerline' | 'starship';
+    /** Prompt theme preset */
+    promptTheme?: TerminalPromptTheme;
+    /** Show git branch in prompt (default: true) */
+    showGitBranch: boolean;
+    /** Show git status dirty indicator (default: true) */
+    showGitStatus: boolean;
+    /** Show user and host in prompt (default: true) */
+    showUserHost: boolean;
+    /** Show path in prompt (default: true) */
+    showPath: boolean;
+    /** Path display style */
+    pathStyle: 'full' | 'short' | 'basename';
+    /** Limit path depth (0 = full path) */
+    pathDepth: number;
+    /** Show current time in prompt (default: false) */
+    showTime: boolean;
+    /** Show last command exit status when non-zero (default: false) */
+    showExitStatus: boolean;
+    /** User-provided custom aliases (multiline string) */
+    customAliases: string;
+    /** User-provided custom env vars */
+    customEnvVars: Record<string, string>;
+    /** RC file format version (for migration) */
+    rcFileVersion?: number;
+  };
 
   // UI State Preferences
   /** Whether sidebar is currently open */
@@ -1245,6 +1415,33 @@ export interface ProjectSettings {
    */
   defaultFeatureModel?: PhaseModelEntry;
 
+  // Terminal Configuration Override (per-project)
+  /** Project-specific terminal config overrides */
+  terminalConfig?: {
+    /** Override global enabled setting */
+    enabled?: boolean;
+    /** Override prompt theme preset */
+    promptTheme?: TerminalPromptTheme;
+    /** Override showing user/host */
+    showUserHost?: boolean;
+    /** Override showing path */
+    showPath?: boolean;
+    /** Override path style */
+    pathStyle?: 'full' | 'short' | 'basename';
+    /** Override path depth (0 = full path) */
+    pathDepth?: number;
+    /** Override showing time */
+    showTime?: boolean;
+    /** Override showing exit status */
+    showExitStatus?: boolean;
+    /** Project-specific custom aliases */
+    customAliases?: string;
+    /** Project-specific env vars */
+    customEnvVars?: Record<string, string>;
+    /** Custom welcome message for this project */
+    welcomeMessage?: string;
+  };
+
   // Deprecated Claude API Profile Override
   /**
    * @deprecated Use phaseModelOverrides instead.

start-automaker.sh

@@ -9,7 +9,11 @@ set -e
 # ============================================================================
 # CONFIGURATION & CONSTANTS
 # ============================================================================
-export $(grep -v '^#' .env | xargs)
+if [ -f .env ]; then
+    set -a
+    . ./.env
+    set +a
+fi
 APP_NAME="Automaker"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 HISTORY_FILE="${HOME}/.automaker_launcher_history"
@@ -1154,7 +1158,9 @@ fi
 # Execute the appropriate command
 case $MODE in
     web)
-        export $(grep -v '^#' .env | xargs) 
+        if [ -f .env ]; then
+            export $(grep -v '^#' .env | xargs)
+        fi
         export TEST_PORT="$WEB_PORT"
         export VITE_SERVER_URL="http://${APP_HOST}:$SERVER_PORT"
         export PORT="$SERVER_PORT"