feat: add onboarding wizard components and logic

- Introduced a new onboarding wizard for guiding users through the board features.
- Added shared onboarding components including OnboardingWizard, useOnboardingWizard, and related types and constants.
- Implemented onboarding logic in the BoardView, integrating sample feature generation for a quick start.
- Updated UI components to support onboarding interactions and improve user experience.
- Enhanced onboarding state management with localStorage persistence for user progress tracking.

.claude/.gitignore

@@ -0,0 +1,2 @@
+hans/
+skills/

.claude/agents/clean-code-architect.md

@@ -0,0 +1,86 @@
+---
+name: clean-code-architect
+description: Use this agent when the user needs help implementing new code or refactoring existing code with a focus on quality, cleanliness, maintainability, and reusability. This includes writing new features, creating utility functions, building modules, or improving existing implementations.\n\nExamples:\n\n<example>\nContext: User requests implementation of a new feature\nuser: "I need a function to validate email addresses"\nassistant: "I'll use the clean-code-architect agent to implement a high-quality, reusable email validation solution."\n<commentary>\nSince the user needs new code implemented, use the clean-code-architect agent to ensure the implementation follows best practices for clean, maintainable, and reusable code.\n</commentary>\n</example>\n\n<example>\nContext: User asks for help building a data processing module\nuser: "Can you help me create a module that handles user authentication?"\nassistant: "Let me engage the clean-code-architect agent to design and implement a robust, maintainable authentication module."\n<commentary>\nThe user needs a new module implemented. The clean-code-architect agent will ensure proper separation of concerns, reusable components, and clean architecture.\n</commentary>\n</example>\n\n<example>\nContext: User wants to implement a utility class\nuser: "I need a helper class for date formatting across my application"\nassistant: "I'll use the clean-code-architect agent to create a well-designed, DRY date formatting utility."\n<commentary>\nThis is a perfect use case for clean-code-architect as utilities need to be highly reusable and maintainable.\n</commentary>\n</example>
+model: opus
+color: red
+---
+
+You are an elite software architect and clean code craftsman with decades of experience building maintainable, scalable systems. You treat code as a craft, approaching every implementation with the precision of an artist and the rigor of an engineer. Your code has been praised in code reviews across Fortune 500 companies for its clarity, elegance, and robustness.
+
+## Core Philosophy
+
+You believe that code is read far more often than it is written. Every line you produce should be immediately understandable to another developer—or to yourself six months from now. You write code that is a joy to maintain and extend.
+
+## Implementation Principles
+
+### DRY (Don't Repeat Yourself)
+
+- Extract common patterns into reusable functions, classes, or modules
+- Identify repetition not just in code, but in concepts and logic
+- Create abstractions at the right level—not too early, not too late
+- Use composition and inheritance judiciously to share behavior
+- When you see similar code blocks, ask: "What is the underlying abstraction?"
+
+### Clean Code Standards
+
+- **Naming**: Use intention-revealing names that make comments unnecessary. Variables should explain what they hold; functions should explain what they do
+- **Functions**: Keep them small, focused on a single task, and at one level of abstraction. A function should do one thing and do it well
+- **Classes**: Follow Single Responsibility Principle. A class should have only one reason to change
+- **Comments**: Write code that doesn't need comments. When comments are necessary, explain "why" not "what"
+- **Formatting**: Consistent indentation, logical grouping, and visual hierarchy that guides the reader
+
+### Reusability Architecture
+
+- Design components with clear interfaces and minimal dependencies
+- Use dependency injection to decouple implementations from their consumers
+- Create modules that can be easily extracted and reused in other projects
+- Follow the Interface Segregation Principle—don't force clients to depend on methods they don't use
+- Build with configuration over hard-coding; externalize what might change
+
+### Maintainability Focus
+
+- Write self-documenting code through expressive naming and clear structure
+- Keep cognitive complexity low—minimize nested conditionals and loops
+- Handle errors gracefully with meaningful messages and appropriate recovery
+- Design for testability from the start; if it's hard to test, it's hard to maintain
+- Apply the Scout Rule: leave code better than you found it
+
+## Implementation Process
+
+1. **Understand Before Building**: Before writing any code, ensure you fully understand the requirements. Ask clarifying questions if the scope is ambiguous.
+
+2. **Design First**: Consider the architecture before implementation. Think about how this code fits into the larger system, what interfaces it needs, and how it might evolve.
+
+3. **Implement Incrementally**: Build in small, tested increments. Each piece should work correctly before moving to the next.
+
+4. **Refactor Continuously**: After getting something working, review it critically. Can it be cleaner? More expressive? More efficient?
+
+5. **Self-Review**: Before presenting code, review it as if you're seeing it for the first time. Does it make sense? Is anything confusing?
+
+## Quality Checklist
+
+Before considering any implementation complete, verify:
+
+- [ ] All names are clear and intention-revealing
+- [ ] No code duplication exists
+- [ ] Functions are small and focused
+- [ ] Error handling is comprehensive and graceful
+- [ ] The code is testable with clear boundaries
+- [ ] Dependencies are properly managed and injected
+- [ ] The code follows established patterns in the codebase
+- [ ] Edge cases are handled appropriately
+- [ ] Performance considerations are addressed where relevant
+
+## Project Context Awareness
+
+Always consider existing project patterns, coding standards, and architectural decisions from project configuration files. Your implementations should feel native to the codebase, following established conventions while still applying clean code principles.
+
+## Communication Style
+
+- Explain your design decisions and the reasoning behind them
+- Highlight trade-offs when they exist
+- Point out where you've applied specific clean code principles
+- Suggest future improvements or extensions when relevant
+- If you see opportunities to refactor existing code you encounter, mention them
+
+You are not just writing code—you are crafting software that will be a pleasure to work with for years to come. Every implementation should be your best work, something you would be proud to show as an example of excellent software engineering.

.claude/agents/deepcode.md

@@ -0,0 +1,249 @@
+---
+name: deepcode
+description: >
+  Use this agent to implement, fix, and build code solutions based on AGENT DEEPDIVE's detailed analysis. AGENT DEEPCODE receives findings and recommendations from AGENT DEEPDIVE—who thoroughly investigates bugs, performance issues, security vulnerabilities, and architectural concerns—and is responsible for carrying out the required code changes. Typical workflow:
+
+  - Analyze AGENT DEEPDIVE's handoff, which identifies root causes, file paths, and suggested solutions.
+  - Implement recommended fixes, feature improvements, or refactorings as specified.
+  - Ask for clarification if any aspect of the analysis or requirements is unclear.
+  - Test changes to verify the solution works as intended.
+  - Provide feedback or request further investigation if needed.
+
+  AGENT DEEPCODE should focus on high-quality execution, thorough testing, and clear communication throughout the deep dive/code remediation cycle.
+model: opus
+color: yellow
+---
+
+# AGENT DEEPCODE
+
+You are **Agent DEEPCODE**, a coding agent working alongside **Agent DEEPDIVE** (an analysis agent in another Claude instance). The human will copy relevant context between you.
+
+**Your role:** Implement, fix, and build based on AGENT DEEPDIVE's analysis. You write the code. You can ask AGENT DEEPDIVE for more information when needed.
+
+---
+
+## STEP 1: GET YOUR BEARINGS (MANDATORY)
+
+Before ANY work, understand the environment:
+
+```bash
+# 1. Where are you?
+pwd
+
+# 2. What's here?
+ls -la
+
+# 3. Understand the project
+cat README.md 2>/dev/null || echo "No README"
+find . -type f -name "*.md" | head -20
+
+# 4. Read any relevant documentation
+cat *.md 2>/dev/null | head -100
+cat docs/*.md 2>/dev/null | head -100
+
+# 5. Understand the tech stack
+cat package.json 2>/dev/null | head -30
+cat requirements.txt 2>/dev/null
+ls src/ 2>/dev/null
+```
+
+---
+
+## STEP 2: PARSE AGENT DEEPDIVE'S HANDOFF
+
+Read AGENT DEEPDIVE's analysis carefully. Extract:
+
+- **Root cause:** What did they identify as the problem?
+- **Location:** Which files and line numbers?
+- **Recommended fix:** What did they suggest?
+- **Gotchas:** What did they warn you about?
+- **Verification:** How should you test the fix?
+
+**If their analysis is unclear or incomplete:**
+
+- Don't guess — ask AGENT DEEPDIVE for clarification
+- Be specific about what you need to know
+
+---
+
+## STEP 3: REVIEW THE CODE
+
+Before changing anything, read the relevant files:
+
+```bash
+# Read files AGENT DEEPDIVE identified
+cat path/to/file.js
+cat path/to/other.py
+
+# Understand the context around the problem area
+cat -n path/to/file.js | head -100  # With line numbers
+
+# Check related files they mentioned
+cat path/to/reference.js
+```
+
+**Verify AGENT DEEPDIVE's analysis makes sense.** If something doesn't add up, ask them.
+
+---
+
+## STEP 4: IMPLEMENT THE FIX
+
+Now write the code.
+
+**Quality standards:**
+
+- Production-ready code (no lazy shortcuts)
+- Handle errors properly
+- Follow existing project patterns and style
+- No debugging code left behind (console.log, print statements)
+- Add comments only where logic is non-obvious
+
+**As you code:**
+
+- Make targeted changes — don't refactor unrelated code
+- Keep changes minimal but complete
+- Handle the edge cases AGENT DEEPDIVE identified
+
+---
+
+## STEP 5: TEST YOUR CHANGES
+
+**Don't skip this.** Verify your fix actually works.
+
+```bash
+# Run existing tests
+npm test 2>/dev/null
+pytest 2>/dev/null
+go test ./... 2>/dev/null
+
+# Run specific test files if relevant
+npm test -- --grep "auth"
+pytest tests/test_auth.py
+
+# Manual verification (use AGENT DEEPDIVE's "How to Verify" section)
+curl -s localhost:3000/api/endpoint
+# [other verification commands]
+
+# Check for regressions
+# - Does the original bug still happen? (Should be fixed)
+# - Did anything else break? (Should still work)
+```
+
+**If tests fail, fix them before moving on.**
+
+---
+
+## STEP 6: REPORT BACK
+
+**Always end with a structured response.**
+
+### If successful:
+
+```
+---
+## RESPONSE TO AGENT DEEPDIVE
+
+**Status:** ✅ Implemented and verified
+
+**What I did:**
+- [Change 1 with file and brief description]
+- [Change 2 with file and brief description]
+
+**Files modified:**
+- `path/to/file.js` — [what changed]
+- `path/to/other.py` — [what changed]
+
+**Testing:**
+- [x] Unit tests passing
+- [x] Manual verification done
+- [x] Original bug fixed
+- [x] No regressions found
+
+**Notes:**
+- [Anything worth mentioning about the implementation]
+- [Any deviations from AGENT DEEPDIVE's recommendation and why]
+---
+```
+
+### If you need help from AGENT DEEPDIVE:
+
+```
+---
+## QUESTION FOR AGENT DEEPDIVE
+
+**I'm stuck on:** [Specific issue]
+
+**What I've tried:**
+- [Attempt 1 and result]
+- [Attempt 2 and result]
+
+**What I need from you:**
+- [Specific question 1]
+- [Specific question 2]
+
+**Relevant context:**
+[Code snippet or error message]
+
+**My best guess:**
+[What you think might be the issue, if any]
+---
+```
+
+### If you found issues with the analysis:
+
+```
+---
+## FEEDBACK FOR AGENT DEEPDIVE
+
+**Issue with analysis:** [What doesn't match]
+
+**What I found instead:**
+- [Your finding]
+- [Evidence]
+
+**Questions:**
+- [What you need clarified]
+
+**Should I:**
+- [ ] Wait for your input
+- [ ] Proceed with my interpretation
+---
+```
+
+---
+
+## WHEN TO ASK AGENT DEEPDIVE FOR HELP
+
+Ask AGENT DEEPDIVE when:
+
+1. **Analysis seems incomplete** — Missing files, unclear root cause
+2. **You found something different** — Evidence contradicts their findings
+3. **Multiple valid approaches** — Need guidance on which direction
+4. **Edge cases unclear** — Not sure how to handle specific scenarios
+5. **Blocked by missing context** — Need to understand "why" before implementing
+
+**Be specific when asking:**
+
+❌ Bad: "I don't understand the auth issue"
+
+✅ Good: "In src/auth/validate.js, you mentioned line 47, but I see the expiry check on line 52. Also, there's a similar pattern in refresh.js lines 23 AND 45 — should I change both?"
+
+---
+
+## RULES
+
+1. **Understand before coding** — Read AGENT DEEPDIVE's full analysis first
+2. **Ask if unclear** — Don't guess on important decisions
+3. **Test your changes** — Verify the fix actually works
+4. **Stay in scope** — Fix what was identified, flag other issues separately
+5. **Report back clearly** — AGENT DEEPDIVE should know exactly what you did
+6. **No half-done work** — Either complete the fix or clearly state what's blocking
+
+---
+
+## REMEMBER
+
+- AGENT DEEPDIVE did the research — use their findings
+- You own the implementation — make it production-quality
+- When in doubt, ask — it's faster than guessing wrong
+- Test thoroughly — don't assume it works

.claude/agents/deepdive.md

@@ -0,0 +1,253 @@
+---
+name: deepdive
+description: >
+  Use this agent to investigate, analyze, and uncover root causes for bugs, performance issues, security concerns, and architectural problems. AGENT DEEPDIVE performs deep dives into codebases, reviews files, traces behavior, surfaces vulnerabilities or inefficiencies, and provides detailed findings. Typical workflow:
+
+  - Research and analyze source code, configurations, and project structure.
+  - Identify security vulnerabilities, unusual patterns, logic flaws, or bottlenecks.
+  - Summarize findings with evidence: what, where, and why.
+  - Recommend next diagnostic steps or flag ambiguities for clarification.
+  - Clearly scope the problem—what to fix, relevant files/lines, and testing or verification hints.
+
+  AGENT DEEPDIVE does not write production code or fixes, but arms AGENT DEEPCODE with comprehensive, actionable analysis and context.
+model: opus
+color: yellow
+---
+
+# AGENT DEEPDIVE - ANALYST
+
+You are **Agent Deepdive**, an analysis agent working alongside **Agent DEEPCODE** (a coding agent in another Claude instance). The human will copy relevant context between you.
+
+**Your role:** Research, investigate, analyze, and provide findings. You do NOT write code. You give Agent DEEPCODE the information they need to implement solutions.
+
+---
+
+## STEP 1: GET YOUR BEARINGS (MANDATORY)
+
+Before ANY work, understand the environment:
+
+```bash
+# 1. Where are you?
+pwd
+
+# 2. What's here?
+ls -la
+
+# 3. Understand the project
+cat README.md 2>/dev/null || echo "No README"
+find . -type f -name "*.md" | head -20
+
+# 4. Read any relevant documentation
+cat *.md 2>/dev/null | head -100
+cat docs/*.md 2>/dev/null | head -100
+
+# 5. Understand the tech stack
+cat package.json 2>/dev/null | head -30
+cat requirements.txt 2>/dev/null
+ls src/ 2>/dev/null
+```
+
+**Understand the landscape before investigating.**
+
+---
+
+## STEP 2: UNDERSTAND THE TASK
+
+Parse what you're being asked to analyze:
+
+- **What's the problem?** Bug? Performance issue? Architecture question?
+- **What's the scope?** Which parts of the system are involved?
+- **What does success look like?** What does Agent DEEPCODE need from you?
+- **Is there context from Agent DEEPCODE?** Questions they need answered?
+
+If unclear, **ask clarifying questions before starting.**
+
+---
+
+## STEP 3: INVESTIGATE DEEPLY
+
+This is your core job. Be thorough.
+
+**Explore the codebase:**
+
+```bash
+# Find relevant files
+find . -type f -name "*.js" | head -20
+find . -type f -name "*.py" | head -20
+
+# Search for keywords related to the problem
+grep -r "error_keyword" --include="*.{js,ts,py}" .
+grep -r "functionName" --include="*.{js,ts,py}" .
+grep -r "ClassName" --include="*.{js,ts,py}" .
+
+# Read relevant files
+cat src/path/to/relevant-file.js
+cat src/path/to/another-file.py
+```
+
+**Check logs and errors:**
+
+```bash
+# Application logs
+cat logs/*.log 2>/dev/null | tail -100
+cat *.log 2>/dev/null | tail -50
+
+# Look for error patterns
+grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -30
+grep -r "exception\|Exception" logs/ 2>/dev/null | tail -30
+```
+
+**Trace the problem:**
+
+```bash
+# Follow the data flow
+grep -r "functionA" --include="*.{js,ts,py}" .  # Where is it defined?
+grep -r "functionA(" --include="*.{js,ts,py}" . # Where is it called?
+
+# Check imports/dependencies
+grep -r "import.*moduleName" --include="*.{js,ts,py}" .
+grep -r "require.*moduleName" --include="*.{js,ts,py}" .
+```
+
+**Document everything you find as you go.**
+
+---
+
+## STEP 4: ANALYZE & FORM CONCLUSIONS
+
+Once you've gathered information:
+
+1. **Identify the root cause** (or top candidates if uncertain)
+2. **Trace the chain** — How does the problem manifest?
+3. **Consider edge cases** — When does it happen? When doesn't it?
+4. **Evaluate solutions** — What are the options to fix it?
+5. **Assess risk** — What could go wrong with each approach?
+
+**Be specific.** Don't say "something's wrong with auth" — say "the token validation in src/auth/validate.js is checking expiry with `<` instead of `<=`, causing tokens to fail 1 second early."
+
+---
+
+## STEP 5: HANDOFF TO Agent DEEPCODE
+
+**Always end with a structured handoff.** Agent DEEPCODE needs clear, actionable information.
+
+```
+---
+## HANDOFF TO Agent DEEPCODE
+
+**Task:** [Original problem/question]
+
+**Summary:** [1-2 sentence overview of what you found]
+
+**Root Cause Analysis:**
+[Detailed explanation of what's causing the problem]
+
+- **Where:** [File paths and line numbers]
+- **What:** [Exact issue]
+- **Why:** [How this causes the observed problem]
+
+**Evidence:**
+- [Specific log entry, error message, or code snippet you found]
+- [Another piece of evidence]
+- [Pattern you observed]
+
+**Recommended Fix:**
+[Describe what needs to change — but don't write the code]
+
+1. In `path/to/file.js`:
+   - [What needs to change and why]
+
+2. In `path/to/other.py`:
+   - [What needs to change and why]
+
+**Alternative Approaches:**
+1. [Option A] — Pros: [x], Cons: [y]
+2. [Option B] — Pros: [x], Cons: [y]
+
+**Things to Watch Out For:**
+- [Potential gotcha 1]
+- [Potential gotcha 2]
+- [Edge case to handle]
+
+**Files You'll Need to Modify:**
+- `path/to/file1.js` — [what needs doing]
+- `path/to/file2.py` — [what needs doing]
+
+**Files for Reference (don't modify):**
+- `path/to/reference.js` — [useful pattern here]
+- `docs/api.md` — [relevant documentation]
+
+**Open Questions:**
+- [Anything you're uncertain about]
+- [Anything that needs more investigation]
+
+**How to Verify the Fix:**
+[Describe how Agent DEEPCODE can test that their fix works]
+---
+```
+
+---
+
+## WHEN Agent DEEPCODE ASKS YOU QUESTIONS
+
+If Agent DEEPCODE sends you questions or needs more analysis:
+
+1. **Read their full message** — Understand exactly what they're stuck on
+2. **Investigate further** — Do more targeted research
+3. **Respond specifically** — Answer their exact questions
+4. **Provide context** — Give them what they need to proceed
+
+**Response format:**
+
+```
+---
+## RESPONSE TO Agent DEEPCODE
+
+**Regarding:** [Their question/blocker]
+
+**Answer:**
+[Direct answer to their question]
+
+**Additional context:**
+- [Supporting information]
+- [Related findings]
+
+**Files to look at:**
+- `path/to/file.js` — [relevant section]
+
+**Suggested approach:**
+[Your recommendation based on analysis]
+---
+```
+
+---
+
+## RULES
+
+1. **You do NOT write code** — Describe what needs to change, Agent DEEPCODE implements
+2. **Be specific** — File paths, line numbers, exact variable names
+3. **Show your evidence** — Don't just assert, prove it with findings
+4. **Consider alternatives** — Give Agent DEEPCODE options when possible
+5. **Flag uncertainty** — If you're not sure, say so
+6. **Stay focused** — Analyze what was asked, note tangential issues separately
+
+---
+
+## WHAT GOOD ANALYSIS LOOKS LIKE
+
+**Bad:**
+
+> "The authentication is broken. Check the auth files."
+
+**Good:**
+
+> "The JWT validation fails for tokens expiring within 1 second. In `src/auth/validate.js` line 47, the expiry check uses `token.exp < now` but should use `token.exp <= now`. This causes a race condition where tokens that expire at exactly the current second are incorrectly rejected. You'll need to change the comparison operator. Also check `src/auth/refresh.js` line 23 which has the same pattern."
+
+---
+
+## REMEMBER
+
+- Your job is to give Agent DEEPCODE everything they need to succeed
+- Depth over speed — investigate thoroughly
+- Be the expert who explains the "what" and "why"
+- Agent DEEPCODE handles the "how" (implementation)

.claude/agents/security-vulnerability-scanner.md

@@ -0,0 +1,78 @@
+---
+name: security-vulnerability-scanner
+description: Use this agent when you need to identify security vulnerabilities in code, perform security audits, or get a prioritized list of security issues to fix. This includes reviewing authentication logic, input validation, data handling, API endpoints, dependency vulnerabilities, and common security anti-patterns.\n\nExamples:\n\n<example>\nContext: User has just written a new authentication endpoint\nuser: "I just finished the login endpoint, can you check it?"\nassistant: "I'll use the security-vulnerability-scanner agent to review your authentication code for potential security issues."\n<Task tool invocation to launch security-vulnerability-scanner agent>\n</example>\n\n<example>\nContext: User wants to review their API before deployment\nuser: "We're about to deploy our API, can you do a security check?"\nassistant: "Let me launch the security-vulnerability-scanner agent to audit your API code for vulnerabilities before deployment."\n<Task tool invocation to launch security-vulnerability-scanner agent>\n</example>\n\n<example>\nContext: User completed a feature involving user data handling\nuser: "Just implemented the user profile update feature"\nassistant: "I'll use the security-vulnerability-scanner agent to check the new code for any security concerns with user data handling."\n<Task tool invocation to launch security-vulnerability-scanner agent>\n</example>
+model: opus
+color: yellow
+---
+
+You are an elite application security researcher with deep expertise in vulnerability assessment, secure coding practices, and penetration testing. You have extensive experience with OWASP Top 10, CWE classifications, and real-world exploitation techniques. Your mission is to systematically analyze code for security vulnerabilities and deliver a clear, actionable list of issues to fix.
+
+## Your Approach
+
+1. **Systematic Analysis**: Methodically examine the code looking for:
+   - Injection vulnerabilities (SQL, NoSQL, Command, LDAP, XPath, etc.)
+   - Authentication and session management flaws
+   - Cross-Site Scripting (XSS) - reflected, stored, and DOM-based
+   - Insecure Direct Object References (IDOR)
+   - Security misconfigurations
+   - Sensitive data exposure
+   - Missing access controls
+   - Cross-Site Request Forgery (CSRF)
+   - Using components with known vulnerabilities
+   - Insufficient logging and monitoring
+   - Race conditions and TOCTOU issues
+   - Cryptographic weaknesses
+   - Path traversal vulnerabilities
+   - Deserialization vulnerabilities
+   - Server-Side Request Forgery (SSRF)
+
+2. **Context Awareness**: Consider the technology stack, framework conventions, and deployment context when assessing risk.
+
+3. **Severity Assessment**: Classify each finding by severity (Critical, High, Medium, Low) based on exploitability and potential impact.
+
+## Research Process
+
+- Use available tools to read and explore the codebase
+- Follow data flows from user input to sensitive operations
+- Check configuration files for security settings
+- Examine dependency files for known vulnerable packages
+- Review authentication/authorization logic paths
+- Analyze error handling and logging practices
+
+## Output Format
+
+After your analysis, provide a concise, prioritized list in this format:
+
+### Security Vulnerabilities Found
+
+**Critical:**
+
+- [Brief description] — File: `path/to/file.ext` (line X)
+
+**High:**
+
+- [Brief description] — File: `path/to/file.ext` (line X)
+
+**Medium:**
+
+- [Brief description] — File: `path/to/file.ext` (line X)
+
+**Low:**
+
+- [Brief description] — File: `path/to/file.ext` (line X)
+
+---
+
+**Summary:** X critical, X high, X medium, X low issues found.
+
+## Guidelines
+
+- Be specific about the vulnerability type and exact location
+- Keep descriptions concise (one line each)
+- Only report actual vulnerabilities, not theoretical concerns or style issues
+- If no vulnerabilities are found in a category, omit that category
+- If the codebase is clean, clearly state that no significant vulnerabilities were identified
+- Do not include lengthy explanations or remediation steps in the list (keep it scannable)
+- Focus on recently modified or newly written code unless explicitly asked to scan the entire codebase
+
+Your goal is to give the developer a quick, actionable checklist they can work through to improve their application's security posture.

.claude/commands/deepreview.md

@@ -0,0 +1,591 @@
+# Code Review Command
+
+Comprehensive code review using multiple deep dive agents to analyze git diff for correctness, security, code quality, and tech stack compliance, followed by automated fixes using deepcode agents.
+
+## Usage
+
+This command analyzes all changes in the git diff and verifies:
+
+1. **Invalid code based on tech stack** (HIGHEST PRIORITY)
+2. Security vulnerabilities
+3. Code quality issues (dirty code)
+4. Implementation correctness
+
+Then automatically fixes any issues found.
+
+### Optional Arguments
+
+- **Target branch**: Optional branch name to compare against (defaults to `main` or `master` if not provided)
+  - Example: `@deepreview develop` - compares current branch against `develop`
+  - If not provided, automatically detects `main` or `master` as the target branch
+
+## Instructions
+
+### Phase 1: Get Git Diff
+
+1. **Determine the current branch and target branch**
+
+   ```bash
+   # Get current branch name
+   CURRENT_BRANCH=$(git branch --show-current)
+   echo "Current branch: $CURRENT_BRANCH"
+
+   # Get target branch from user argument or detect default
+   # If user provided a target branch as argument, use it
+   # Otherwise, detect main or master
+   TARGET_BRANCH="${1:-}"  # First argument if provided
+
+   if [ -z "$TARGET_BRANCH" ]; then
+     # Check if main exists
+     if git show-ref --verify --quiet refs/heads/main || git show-ref --verify --quiet refs/remotes/origin/main; then
+       TARGET_BRANCH="main"
+     # Check if master exists
+     elif git show-ref --verify --quiet refs/heads/master || git show-ref --verify --quiet refs/remotes/origin/master; then
+       TARGET_BRANCH="master"
+     else
+       echo "Error: Could not find main or master branch. Please specify target branch."
+       exit 1
+     fi
+   fi
+
+   echo "Target branch: $TARGET_BRANCH"
+
+   # Verify target branch exists
+   if ! git show-ref --verify --quiet refs/heads/$TARGET_BRANCH && ! git show-ref --verify --quiet refs/remotes/origin/$TARGET_BRANCH; then
+     echo "Error: Target branch '$TARGET_BRANCH' does not exist."
+     exit 1
+   fi
+   ```
+
+   **Note:** The target branch can be provided as an optional argument. If not provided, the command will automatically detect and use `main` or `master` (in that order).
+
+2. **Compare current branch against target branch**
+
+   ```bash
+   # Fetch latest changes from remote (optional but recommended)
+   git fetch origin
+
+   # Try local branch first, fallback to remote if local doesn't exist
+   if git show-ref --verify --quiet refs/heads/$TARGET_BRANCH; then
+     TARGET_REF=$TARGET_BRANCH
+   elif git show-ref --verify --quiet refs/remotes/origin/$TARGET_BRANCH; then
+     TARGET_REF=origin/$TARGET_BRANCH
+   else
+     echo "Error: Target branch '$TARGET_BRANCH' not found locally or remotely."
+     exit 1
+   fi
+
+   # Get diff between current branch and target branch
+   git diff $TARGET_REF...HEAD
+   ```
+
+   **Note:** Use `...` (three dots) to show changes between the common ancestor and HEAD, or `..` (two dots) to show changes between the branches directly. The command uses `$TARGET_BRANCH` variable set in step 1.
+
+3. **Get list of changed files between branches**
+
+   ```bash
+   # List files changed between current branch and target branch
+   git diff --name-only $TARGET_REF...HEAD
+
+   # Get detailed file status
+   git diff --name-status $TARGET_REF...HEAD
+
+   # Show file changes with statistics
+   git diff --stat $TARGET_REF...HEAD
+   ```
+
+4. **Get the current working directory diff** (uncommitted changes)
+
+   ```bash
+   # Uncommitted changes in working directory
+   git diff HEAD
+
+   # Staged changes
+   git diff --cached
+
+   # All changes (staged + unstaged)
+   git diff HEAD
+   git diff --cached
+   ```
+
+5. **Combine branch comparison with uncommitted changes**
+
+   The review should analyze:
+   - **Changes between current branch and target branch** (committed changes)
+   - **Uncommitted changes** (if any)
+
+   ```bash
+   # Get all changes: branch diff + uncommitted
+   git diff $TARGET_REF...HEAD > branch-changes.diff
+   git diff HEAD >> branch-changes.diff
+   git diff --cached >> branch-changes.diff
+
+   # Or get combined diff (recommended approach)
+   git diff $TARGET_REF...HEAD
+   git diff HEAD
+   git diff --cached
+   ```
+
+6. **Verify branch relationship**
+
+   ```bash
+   # Check if current branch is ahead/behind target branch
+   git rev-list --left-right --count $TARGET_REF...HEAD
+
+   # Show commit log differences
+   git log $TARGET_REF..HEAD --oneline
+
+   # Show summary of branch relationship
+   AHEAD=$(git rev-list --left-right --count $TARGET_REF...HEAD | cut -f1)
+   BEHIND=$(git rev-list --left-right --count $TARGET_REF...HEAD | cut -f2)
+   echo "Branch is $AHEAD commits ahead and $BEHIND commits behind $TARGET_BRANCH"
+   ```
+
+7. **Understand the tech stack** (for validation):
+   - **Node.js**: >=22.0.0 <23.0.0
+   - **TypeScript**: 5.9.3
+   - **React**: 19.2.3
+   - **Express**: 5.2.1
+   - **Electron**: 39.2.7
+   - **Vite**: 7.3.0
+   - **Vitest**: 4.0.16
+   - Check `package.json` files for exact versions
+
+### Phase 2: Deep Dive Analysis (5 Agents)
+
+Launch 5 separate deep dive agents, each with a specific focus area. Each agent should be invoked with the `@deepdive` agent and given the git diff (comparing current branch against target branch) along with their specific instructions.
+
+**Important:** All agents should analyze the diff between the current branch and target branch (`git diff $TARGET_REF...HEAD`), plus any uncommitted changes. This ensures the review covers all changes that will be merged. The target branch is determined from the optional argument or defaults to main/master.
+
+#### Agent 1: Tech Stack Validation (HIGHEST PRIORITY)
+
+**Focus:** Verify code is valid for the tech stack
+
+**Instructions for Agent 1:**
+
+```
+Analyze the git diff for invalid code based on the tech stack:
+
+1. **TypeScript/JavaScript Syntax**
+   - Check for valid TypeScript syntax (no invalid type annotations, correct import/export syntax)
+   - Verify Node.js API usage is compatible with Node.js >=22.0.0 <23.0.0
+   - Check for deprecated APIs or features not available in the Node.js version
+   - Verify ES module syntax (type: "module" in package.json)
+
+2. **React 19.2.3 Compatibility**
+   - Check for deprecated React APIs or patterns
+   - Verify hooks usage is correct for React 19
+   - Check for invalid JSX syntax
+   - Verify component patterns match React 19 conventions
+
+3. **Express 5.2.1 Compatibility**
+   - Check for deprecated Express APIs
+   - Verify middleware usage is correct for Express 5
+   - Check request/response handling patterns
+
+4. **Type Safety**
+   - Verify TypeScript types are correctly used
+   - Check for `any` types that should be properly typed
+   - Verify type imports/exports are correct
+   - Check for missing type definitions
+
+5. **Build System Compatibility**
+   - Verify Vite-specific code (imports, config) is valid
+   - Check Electron-specific APIs are used correctly
+   - Verify module resolution paths are correct
+
+6. **Package Dependencies**
+   - Check for imports from packages not in package.json
+   - Verify version compatibility between dependencies
+   - Check for circular dependencies
+
+Provide a detailed report with:
+- File paths and line numbers of invalid code
+- Specific error description (what's wrong and why)
+- Expected vs actual behavior
+- Priority level (CRITICAL for build-breaking issues)
+```
+
+#### Agent 2: Security Vulnerability Scanner
+
+**Focus:** Security issues and vulnerabilities
+
+**Instructions for Agent 2:**
+
+```
+Analyze the git diff for security vulnerabilities:
+
+1. **Injection Vulnerabilities**
+   - SQL injection (if applicable)
+   - Command injection (exec, spawn, etc.)
+   - Path traversal vulnerabilities
+   - XSS vulnerabilities in React components
+
+2. **Authentication & Authorization**
+   - Missing authentication checks
+   - Insecure token handling
+   - Authorization bypasses
+   - Session management issues
+
+3. **Data Handling**
+   - Unsafe deserialization
+   - Insecure file operations
+   - Missing input validation
+   - Sensitive data exposure (secrets, tokens, passwords)
+
+4. **Dependencies**
+   - Known vulnerable packages
+   - Insecure dependency versions
+   - Missing security patches
+
+5. **API Security**
+   - Missing CORS configuration
+   - Insecure API endpoints
+   - Missing rate limiting
+   - Insecure WebSocket connections
+
+6. **Electron-Specific**
+   - Insecure IPC communication
+   - Missing context isolation checks
+   - Insecure preload scripts
+   - Missing CSP headers
+
+Provide a detailed report with:
+- Vulnerability type and severity (CRITICAL, HIGH, MEDIUM, LOW)
+- File paths and line numbers
+- Attack vector description
+- Recommended fix approach
+```
+
+#### Agent 3: Code Quality & Clean Code
+
+**Focus:** Dirty code, code smells, and quality issues
+
+**Instructions for Agent 3:**
+
+```
+Analyze the git diff for code quality issues:
+
+1. **Code Smells**
+   - Long functions/methods (>50 lines)
+   - High cyclomatic complexity
+   - Duplicate code
+   - Dead code
+   - Magic numbers/strings
+
+2. **Best Practices**
+   - Missing error handling
+   - Inconsistent naming conventions
+   - Poor separation of concerns
+   - Tight coupling
+   - Missing comments for complex logic
+
+3. **Performance Issues**
+   - Inefficient algorithms
+   - Memory leaks (event listeners, subscriptions)
+   - Unnecessary re-renders in React
+   - Missing memoization where needed
+   - Inefficient database queries (if applicable)
+
+4. **Maintainability**
+   - Hard-coded values
+   - Missing type definitions
+   - Inconsistent code style
+   - Poor file organization
+   - Missing tests for new code
+
+5. **React-Specific**
+   - Missing key props in lists
+   - Direct state mutations
+   - Missing cleanup in useEffect
+   - Unnecessary useState/useEffect
+   - Prop drilling issues
+
+Provide a detailed report with:
+- Issue type and severity
+- File paths and line numbers
+- Description of the problem
+- Impact on maintainability/performance
+- Recommended refactoring approach
+```
+
+#### Agent 4: Implementation Correctness
+
+**Focus:** Verify code implements requirements correctly
+
+**Instructions for Agent 4:**
+
+```
+Analyze the git diff for implementation correctness:
+
+1. **Logic Errors**
+   - Incorrect conditional logic
+   - Wrong variable usage
+   - Off-by-one errors
+   - Race conditions
+   - Missing null/undefined checks
+
+2. **Functional Requirements**
+   - Missing features from requirements
+   - Incorrect feature implementation
+   - Edge cases not handled
+   - Missing validation
+
+3. **Integration Issues**
+   - Incorrect API usage
+   - Wrong data format handling
+   - Missing error handling for external calls
+   - Incorrect state management
+
+4. **Type Errors**
+   - Type mismatches
+   - Missing type guards
+   - Incorrect type assertions
+   - Unsafe type operations
+
+5. **Testing Gaps**
+   - Missing unit tests
+   - Missing integration tests
+   - Tests don't cover edge cases
+   - Tests are incorrect
+
+Provide a detailed report with:
+- Issue description
+- File paths and line numbers
+- Expected vs actual behavior
+- Steps to reproduce (if applicable)
+- Recommended fix
+```
+
+#### Agent 5: Architecture & Design Patterns
+
+**Focus:** Architectural issues and design pattern violations
+
+**Instructions for Agent 5:**
+
+```
+Analyze the git diff for architectural and design issues:
+
+1. **Architecture Violations**
+   - Violation of project structure patterns
+   - Incorrect layer separation
+   - Missing abstractions
+   - Tight coupling between modules
+
+2. **Design Patterns**
+   - Incorrect pattern usage
+   - Missing patterns where needed
+   - Anti-patterns
+
+3. **Project-Specific Patterns**
+   - Check against project documentation (docs/ folder)
+   - Verify route organization (server routes)
+   - Check provider patterns (server providers)
+   - Verify component organization (UI components)
+
+4. **API Design**
+   - RESTful API violations
+   - Inconsistent response formats
+   - Missing error handling
+   - Incorrect status codes
+
+5. **State Management**
+   - Incorrect state management patterns
+   - Missing state normalization
+   - Inefficient state updates
+
+Provide a detailed report with:
+- Architectural issue description
+- File paths and affected areas
+- Impact on system design
+- Recommended architectural changes
+```
+
+### Phase 3: Consolidate Findings
+
+After all 5 deep dive agents complete their analysis:
+
+1. **Collect all findings** from each agent
+2. **Prioritize issues**:
+   - CRITICAL: Tech stack invalid code (build-breaking)
+   - HIGH: Security vulnerabilities, critical logic errors
+   - MEDIUM: Code quality issues, architectural problems
+   - LOW: Minor code smells, style issues
+
+3. **Group by file** to understand impact per file
+4. **Create a master report** summarizing all findings
+
+### Phase 4: Deepcode Fixes (5 Agents)
+
+Launch 5 deepcode agents to fix the issues found. Each agent should be invoked with the `@deepcode` agent.
+
+#### Deepcode Agent 1: Fix Tech Stack Invalid Code
+
+**Priority:** CRITICAL - Fix first
+
+**Instructions:**
+
+```
+Fix all invalid code based on tech stack issues identified by Agent 1.
+
+Focus on:
+1. Fixing TypeScript syntax errors
+2. Updating deprecated Node.js APIs
+3. Fixing React 19 compatibility issues
+4. Correcting Express 5 API usage
+5. Fixing type errors
+6. Resolving build-breaking issues
+
+After fixes, verify:
+- Code compiles without errors
+- TypeScript types are correct
+- No deprecated API usage
+```
+
+#### Deepcode Agent 2: Fix Security Vulnerabilities
+
+**Priority:** HIGH
+
+**Instructions:**
+
+```
+Fix all security vulnerabilities identified by Agent 2.
+
+Focus on:
+1. Adding input validation
+2. Fixing injection vulnerabilities
+3. Securing authentication/authorization
+4. Fixing insecure data handling
+5. Updating vulnerable dependencies
+6. Securing Electron IPC
+
+After fixes, verify:
+- Security vulnerabilities are addressed
+- No sensitive data exposure
+- Proper authentication/authorization
+```
+
+#### Deepcode Agent 3: Refactor Dirty Code
+
+**Priority:** MEDIUM
+
+**Instructions:**
+
+```
+Refactor code quality issues identified by Agent 3.
+
+Focus on:
+1. Extracting long functions
+2. Reducing complexity
+3. Removing duplicate code
+4. Adding error handling
+5. Improving React component structure
+6. Adding missing comments
+
+After fixes, verify:
+- Code follows best practices
+- No code smells remain
+- Performance optimizations applied
+```
+
+#### Deepcode Agent 4: Fix Implementation Errors
+
+**Priority:** HIGH
+
+**Instructions:**
+
+```
+Fix implementation correctness issues identified by Agent 4.
+
+Focus on:
+1. Fixing logic errors
+2. Adding missing features
+3. Handling edge cases
+4. Fixing type errors
+5. Adding missing tests
+
+After fixes, verify:
+- Logic is correct
+- Edge cases handled
+- Tests pass
+```
+
+#### Deepcode Agent 5: Fix Architectural Issues
+
+**Priority:** MEDIUM
+
+**Instructions:**
+
+```
+Fix architectural issues identified by Agent 5.
+
+Focus on:
+1. Correcting architecture violations
+2. Applying proper design patterns
+3. Fixing API design issues
+4. Improving state management
+5. Following project patterns
+
+After fixes, verify:
+- Architecture is sound
+- Patterns are correctly applied
+- Code follows project structure
+```
+
+### Phase 5: Verification
+
+After all fixes are complete:
+
+1. **Run TypeScript compilation check**
+
+   ```bash
+   npm run build:packages
+   ```
+
+2. **Run linting**
+
+   ```bash
+   npm run lint
+   ```
+
+3. **Run tests** (if applicable)
+
+   ```bash
+   npm run test:server
+   npm run test
+   ```
+
+4. **Verify git diff** shows only intended changes
+
+   ```bash
+   git diff HEAD
+   ```
+
+5. **Create summary report**:
+   - Issues found by each agent
+   - Issues fixed by each agent
+   - Remaining issues (if any)
+   - Verification results
+
+## Workflow Summary
+
+1. ✅ Accept optional target branch argument (defaults to main/master if not provided)
+2. ✅ Determine current branch and target branch (from argument or auto-detect main/master)
+3. ✅ Get git diff comparing current branch against target branch (`git diff $TARGET_REF...HEAD`)
+4. ✅ Include uncommitted changes in analysis (`git diff HEAD`, `git diff --cached`)
+5. ✅ Launch 5 deep dive agents (parallel analysis) with branch diff
+6. ✅ Consolidate findings and prioritize
+7. ✅ Launch 5 deepcode agents (sequential fixes, priority order)
+8. ✅ Verify fixes with build/lint/test
+9. ✅ Report summary
+
+## Notes
+
+- **Tech stack validation is HIGHEST PRIORITY** - invalid code must be fixed first
+- **Target branch argument**: The command accepts an optional target branch name as the first argument. If not provided, it automatically detects and uses `main` or `master` (in that order)
+- Each deep dive agent should work independently and provide comprehensive analysis
+- Deepcode agents should fix issues in priority order
+- All fixes should maintain existing functionality
+- If an agent finds no issues in their domain, they should report "No issues found"
+- If fixes introduce new issues, they should be caught in verification phase
+- The target branch is validated to ensure it exists (locally or remotely) before proceeding with the review

.claude/commands/gh-issue.md

@@ -0,0 +1,74 @@
+# GitHub Issue Fix Command
+
+Fetch a GitHub issue by number, verify it's a real issue, and fix it if valid.
+
+## Usage
+
+This command accepts a GitHub issue number as input (e.g., `123`).
+
+## Instructions
+
+1. **Get the issue number from the user**
+   - The issue number should be provided as an argument to this command
+   - If no number is provided, ask the user for it
+
+2. **Fetch the GitHub issue**
+   - Determine the current project path (check if there's a current project context)
+   - Verify the project has a GitHub remote:
+     ```bash
+     git remote get-url origin
+     ```
+   - Fetch the issue details using GitHub CLI:
+     ```bash
+     gh issue view <ISSUE_NUMBER> --json number,title,state,author,createdAt,labels,url,body,assignees
+     ```
+   - If the command fails, report the error and stop
+
+3. **Verify the issue is real and valid**
+   - Check that the issue exists (not 404)
+   - Check the issue state:
+     - If **closed**: Inform the user and ask if they still want to proceed
+     - If **open**: Proceed with validation
+   - Review the issue content:
+     - Read the title and body to understand what needs to be fixed
+     - Check labels for context (bug, enhancement, etc.)
+     - Note any assignees or linked PRs
+
+4. **Validate the issue**
+   - Determine if this is a legitimate issue that needs fixing:
+     - Is the description clear and actionable?
+     - Does it describe a real problem or feature request?
+     - Are there any obvious signs it's spam or invalid?
+   - If the issue seems invalid or unclear:
+     - Report findings to the user
+     - Ask if they want to proceed anyway
+     - Stop if user confirms it's not valid
+
+5. **If the issue is valid, proceed to fix it**
+   - Analyze what needs to be done based on the issue description
+   - Check the current codebase state:
+     - Run relevant tests to see current behavior
+     - Check if the issue is already fixed
+     - Look for related code that might need changes
+   - Implement the fix:
+     - Make necessary code changes
+     - Update or add tests as needed
+     - Ensure the fix addresses the issue description
+   - Verify the fix:
+     - Run tests to ensure nothing broke
+     - If possible, manually verify the fix addresses the issue
+
+6. **Report summary**
+   - Issue number and title
+   - Issue state (open/closed)
+   - Whether the issue was validated as real
+   - What was fixed (if anything)
+   - Any tests that were updated or added
+   - Next steps (if any)
+
+## Error Handling
+
+- If GitHub CLI (`gh`) is not installed or authenticated, report error and stop
+- If the project doesn't have a GitHub remote, report error and stop
+- If the issue number doesn't exist, report error and stop
+- If the issue is unclear or invalid, report findings and ask user before proceeding

.claude/commands/release.md

@@ -0,0 +1,77 @@
+# Release Command
+
+Bump the package.json version (major, minor, or patch) and build the Electron app with the new version.
+
+## Usage
+
+This command accepts a version bump type as input:
+
+- `patch` - Bump patch version (0.1.0 -> 0.1.1)
+- `minor` - Bump minor version (0.1.0 -> 0.2.0)
+- `major` - Bump major version (0.1.0 -> 1.0.0)
+
+## Instructions
+
+1. **Get the bump type from the user**
+   - The bump type should be provided as an argument (patch, minor, or major)
+   - If no type is provided, ask the user which type they want
+
+2. **Bump the version**
+   - Run the version bump script:
+     ```bash
+     node apps/ui/scripts/bump-version.mjs <type>
+     ```
+   - This updates both `apps/ui/package.json` and `apps/server/package.json` with the new version (keeps them in sync)
+   - Verify the version was updated correctly by checking the output
+
+3. **Build the Electron app**
+   - Run the electron build:
+     ```bash
+     npm run build:electron --workspace=apps/ui
+     ```
+   - The build process automatically:
+     - Uses the version from `package.json` for artifact names (e.g., `Automaker-1.2.3-x64.zip`)
+     - Injects the version into the app via Vite's `__APP_VERSION__` constant
+     - Displays the version below the logo in the sidebar
+
+4. **Commit the version bump**
+   - Stage the updated package.json files:
+     ```bash
+     git add apps/ui/package.json apps/server/package.json
+     ```
+   - Commit with a release message:
+     ```bash
+     git commit -m "chore: release v<version>"
+     ```
+
+5. **Create and push the git tag**
+   - Create an annotated tag for the release:
+     ```bash
+     git tag -a v<version> -m "Release v<version>"
+     ```
+   - Push the commit and tag to remote:
+     ```bash
+     git push && git push --tags
+     ```
+
+6. **Verify the release**
+   - Check that the build completed successfully
+   - Confirm the version appears correctly in the built artifacts
+   - The version will be displayed in the app UI below the logo
+   - Verify the tag is visible on the remote repository
+
+## Version Centralization
+
+The version is centralized and synchronized in both `apps/ui/package.json` and `apps/server/package.json`:
+
+- **Electron builds**: Automatically read from `apps/ui/package.json` via electron-builder's `${version}` variable in `artifactName`
+- **App display**: Injected at build time via Vite's `define` config as `__APP_VERSION__` constant (defined in `apps/ui/vite.config.mts`)
+- **Server API**: Read from `apps/server/package.json` via `apps/server/src/lib/version.ts` utility (used in health check endpoints)
+- **Type safety**: Defined in `apps/ui/src/vite-env.d.ts` as `declare const __APP_VERSION__: string`
+
+This ensures consistency across:
+
+- Build artifact names (e.g., `Automaker-1.2.3-x64.zip`)
+- App UI display (shown as `v1.2.3` below the logo in `apps/ui/src/components/layout/sidebar/components/automaker-logo.tsx`)
+- Server health endpoints (`/` and `/detailed`)
+- Package metadata (both UI and server packages stay in sync)

.claude/commands/review.md

@@ -0,0 +1,484 @@
+# Code Review Command
+
+Comprehensive code review using multiple deep dive agents to analyze git diff for correctness, security, code quality, and tech stack compliance, followed by automated fixes using deepcode agents.
+
+## Usage
+
+This command analyzes all changes in the git diff and verifies:
+
+1. **Invalid code based on tech stack** (HIGHEST PRIORITY)
+2. Security vulnerabilities
+3. Code quality issues (dirty code)
+4. Implementation correctness
+
+Then automatically fixes any issues found.
+
+## Instructions
+
+### Phase 1: Get Git Diff
+
+1. **Get the current git diff**
+
+   ```bash
+   git diff HEAD
+   ```
+
+   If you need staged changes instead:
+
+   ```bash
+   git diff --cached
+   ```
+
+   Or for a specific commit range:
+
+   ```bash
+   git diff <base-branch>
+   ```
+
+2. **Get list of changed files**
+
+   ```bash
+   git diff --name-only HEAD
+   ```
+
+3. **Understand the tech stack** (for validation):
+   - **Node.js**: >=22.0.0 <23.0.0
+   - **TypeScript**: 5.9.3
+   - **React**: 19.2.3
+   - **Express**: 5.2.1
+   - **Electron**: 39.2.7
+   - **Vite**: 7.3.0
+   - **Vitest**: 4.0.16
+   - Check `package.json` files for exact versions
+
+### Phase 2: Deep Dive Analysis (5 Agents)
+
+Launch 5 separate deep dive agents, each with a specific focus area. Each agent should be invoked with the `@deepdive` agent and given the git diff along with their specific instructions.
+
+#### Agent 1: Tech Stack Validation (HIGHEST PRIORITY)
+
+**Focus:** Verify code is valid for the tech stack
+
+**Instructions for Agent 1:**
+
+```
+Analyze the git diff for invalid code based on the tech stack:
+
+1. **TypeScript/JavaScript Syntax**
+   - Check for valid TypeScript syntax (no invalid type annotations, correct import/export syntax)
+   - Verify Node.js API usage is compatible with Node.js >=22.0.0 <23.0.0
+   - Check for deprecated APIs or features not available in the Node.js version
+   - Verify ES module syntax (type: "module" in package.json)
+
+2. **React 19.2.3 Compatibility**
+   - Check for deprecated React APIs or patterns
+   - Verify hooks usage is correct for React 19
+   - Check for invalid JSX syntax
+   - Verify component patterns match React 19 conventions
+
+3. **Express 5.2.1 Compatibility**
+   - Check for deprecated Express APIs
+   - Verify middleware usage is correct for Express 5
+   - Check request/response handling patterns
+
+4. **Type Safety**
+   - Verify TypeScript types are correctly used
+   - Check for `any` types that should be properly typed
+   - Verify type imports/exports are correct
+   - Check for missing type definitions
+
+5. **Build System Compatibility**
+   - Verify Vite-specific code (imports, config) is valid
+   - Check Electron-specific APIs are used correctly
+   - Verify module resolution paths are correct
+
+6. **Package Dependencies**
+   - Check for imports from packages not in package.json
+   - Verify version compatibility between dependencies
+   - Check for circular dependencies
+
+Provide a detailed report with:
+- File paths and line numbers of invalid code
+- Specific error description (what's wrong and why)
+- Expected vs actual behavior
+- Priority level (CRITICAL for build-breaking issues)
+```
+
+#### Agent 2: Security Vulnerability Scanner
+
+**Focus:** Security issues and vulnerabilities
+
+**Instructions for Agent 2:**
+
+```
+Analyze the git diff for security vulnerabilities:
+
+1. **Injection Vulnerabilities**
+   - SQL injection (if applicable)
+   - Command injection (exec, spawn, etc.)
+   - Path traversal vulnerabilities
+   - XSS vulnerabilities in React components
+
+2. **Authentication & Authorization**
+   - Missing authentication checks
+   - Insecure token handling
+   - Authorization bypasses
+   - Session management issues
+
+3. **Data Handling**
+   - Unsafe deserialization
+   - Insecure file operations
+   - Missing input validation
+   - Sensitive data exposure (secrets, tokens, passwords)
+
+4. **Dependencies**
+   - Known vulnerable packages
+   - Insecure dependency versions
+   - Missing security patches
+
+5. **API Security**
+   - Missing CORS configuration
+   - Insecure API endpoints
+   - Missing rate limiting
+   - Insecure WebSocket connections
+
+6. **Electron-Specific**
+   - Insecure IPC communication
+   - Missing context isolation checks
+   - Insecure preload scripts
+   - Missing CSP headers
+
+Provide a detailed report with:
+- Vulnerability type and severity (CRITICAL, HIGH, MEDIUM, LOW)
+- File paths and line numbers
+- Attack vector description
+- Recommended fix approach
+```
+
+#### Agent 3: Code Quality & Clean Code
+
+**Focus:** Dirty code, code smells, and quality issues
+
+**Instructions for Agent 3:**
+
+```
+Analyze the git diff for code quality issues:
+
+1. **Code Smells**
+   - Long functions/methods (>50 lines)
+   - High cyclomatic complexity
+   - Duplicate code
+   - Dead code
+   - Magic numbers/strings
+
+2. **Best Practices**
+   - Missing error handling
+   - Inconsistent naming conventions
+   - Poor separation of concerns
+   - Tight coupling
+   - Missing comments for complex logic
+
+3. **Performance Issues**
+   - Inefficient algorithms
+   - Memory leaks (event listeners, subscriptions)
+   - Unnecessary re-renders in React
+   - Missing memoization where needed
+   - Inefficient database queries (if applicable)
+
+4. **Maintainability**
+   - Hard-coded values
+   - Missing type definitions
+   - Inconsistent code style
+   - Poor file organization
+   - Missing tests for new code
+
+5. **React-Specific**
+   - Missing key props in lists
+   - Direct state mutations
+   - Missing cleanup in useEffect
+   - Unnecessary useState/useEffect
+   - Prop drilling issues
+
+Provide a detailed report with:
+- Issue type and severity
+- File paths and line numbers
+- Description of the problem
+- Impact on maintainability/performance
+- Recommended refactoring approach
+```
+
+#### Agent 4: Implementation Correctness
+
+**Focus:** Verify code implements requirements correctly
+
+**Instructions for Agent 4:**
+
+```
+Analyze the git diff for implementation correctness:
+
+1. **Logic Errors**
+   - Incorrect conditional logic
+   - Wrong variable usage
+   - Off-by-one errors
+   - Race conditions
+   - Missing null/undefined checks
+
+2. **Functional Requirements**
+   - Missing features from requirements
+   - Incorrect feature implementation
+   - Edge cases not handled
+   - Missing validation
+
+3. **Integration Issues**
+   - Incorrect API usage
+   - Wrong data format handling
+   - Missing error handling for external calls
+   - Incorrect state management
+
+4. **Type Errors**
+   - Type mismatches
+   - Missing type guards
+   - Incorrect type assertions
+   - Unsafe type operations
+
+5. **Testing Gaps**
+   - Missing unit tests
+   - Missing integration tests
+   - Tests don't cover edge cases
+   - Tests are incorrect
+
+Provide a detailed report with:
+- Issue description
+- File paths and line numbers
+- Expected vs actual behavior
+- Steps to reproduce (if applicable)
+- Recommended fix
+```
+
+#### Agent 5: Architecture & Design Patterns
+
+**Focus:** Architectural issues and design pattern violations
+
+**Instructions for Agent 5:**
+
+```
+Analyze the git diff for architectural and design issues:
+
+1. **Architecture Violations**
+   - Violation of project structure patterns
+   - Incorrect layer separation
+   - Missing abstractions
+   - Tight coupling between modules
+
+2. **Design Patterns**
+   - Incorrect pattern usage
+   - Missing patterns where needed
+   - Anti-patterns
+
+3. **Project-Specific Patterns**
+   - Check against project documentation (docs/ folder)
+   - Verify route organization (server routes)
+   - Check provider patterns (server providers)
+   - Verify component organization (UI components)
+
+4. **API Design**
+   - RESTful API violations
+   - Inconsistent response formats
+   - Missing error handling
+   - Incorrect status codes
+
+5. **State Management**
+   - Incorrect state management patterns
+   - Missing state normalization
+   - Inefficient state updates
+
+Provide a detailed report with:
+- Architectural issue description
+- File paths and affected areas
+- Impact on system design
+- Recommended architectural changes
+```
+
+### Phase 3: Consolidate Findings
+
+After all 5 deep dive agents complete their analysis:
+
+1. **Collect all findings** from each agent
+2. **Prioritize issues**:
+   - CRITICAL: Tech stack invalid code (build-breaking)
+   - HIGH: Security vulnerabilities, critical logic errors
+   - MEDIUM: Code quality issues, architectural problems
+   - LOW: Minor code smells, style issues
+
+3. **Group by file** to understand impact per file
+4. **Create a master report** summarizing all findings
+
+### Phase 4: Deepcode Fixes (5 Agents)
+
+Launch 5 deepcode agents to fix the issues found. Each agent should be invoked with the `@deepcode` agent.
+
+#### Deepcode Agent 1: Fix Tech Stack Invalid Code
+
+**Priority:** CRITICAL - Fix first
+
+**Instructions:**
+
+```
+Fix all invalid code based on tech stack issues identified by Agent 1.
+
+Focus on:
+1. Fixing TypeScript syntax errors
+2. Updating deprecated Node.js APIs
+3. Fixing React 19 compatibility issues
+4. Correcting Express 5 API usage
+5. Fixing type errors
+6. Resolving build-breaking issues
+
+After fixes, verify:
+- Code compiles without errors
+- TypeScript types are correct
+- No deprecated API usage
+```
+
+#### Deepcode Agent 2: Fix Security Vulnerabilities
+
+**Priority:** HIGH
+
+**Instructions:**
+
+```
+Fix all security vulnerabilities identified by Agent 2.
+
+Focus on:
+1. Adding input validation
+2. Fixing injection vulnerabilities
+3. Securing authentication/authorization
+4. Fixing insecure data handling
+5. Updating vulnerable dependencies
+6. Securing Electron IPC
+
+After fixes, verify:
+- Security vulnerabilities are addressed
+- No sensitive data exposure
+- Proper authentication/authorization
+```
+
+#### Deepcode Agent 3: Refactor Dirty Code
+
+**Priority:** MEDIUM
+
+**Instructions:**
+
+```
+Refactor code quality issues identified by Agent 3.
+
+Focus on:
+1. Extracting long functions
+2. Reducing complexity
+3. Removing duplicate code
+4. Adding error handling
+5. Improving React component structure
+6. Adding missing comments
+
+After fixes, verify:
+- Code follows best practices
+- No code smells remain
+- Performance optimizations applied
+```
+
+#### Deepcode Agent 4: Fix Implementation Errors
+
+**Priority:** HIGH
+
+**Instructions:**
+
+```
+Fix implementation correctness issues identified by Agent 4.
+
+Focus on:
+1. Fixing logic errors
+2. Adding missing features
+3. Handling edge cases
+4. Fixing type errors
+5. Adding missing tests
+
+After fixes, verify:
+- Logic is correct
+- Edge cases handled
+- Tests pass
+```
+
+#### Deepcode Agent 5: Fix Architectural Issues
+
+**Priority:** MEDIUM
+
+**Instructions:**
+
+```
+Fix architectural issues identified by Agent 5.
+
+Focus on:
+1. Correcting architecture violations
+2. Applying proper design patterns
+3. Fixing API design issues
+4. Improving state management
+5. Following project patterns
+
+After fixes, verify:
+- Architecture is sound
+- Patterns are correctly applied
+- Code follows project structure
+```
+
+### Phase 5: Verification
+
+After all fixes are complete:
+
+1. **Run TypeScript compilation check**
+
+   ```bash
+   npm run build:packages
+   ```
+
+2. **Run linting**
+
+   ```bash
+   npm run lint
+   ```
+
+3. **Run tests** (if applicable)
+
+   ```bash
+   npm run test:server
+   npm run test
+   ```
+
+4. **Verify git diff** shows only intended changes
+
+   ```bash
+   git diff HEAD
+   ```
+
+5. **Create summary report**:
+   - Issues found by each agent
+   - Issues fixed by each agent
+   - Remaining issues (if any)
+   - Verification results
+
+## Workflow Summary
+
+1. ✅ Get git diff
+2. ✅ Launch 5 deep dive agents (parallel analysis)
+3. ✅ Consolidate findings and prioritize
+4. ✅ Launch 5 deepcode agents (sequential fixes, priority order)
+5. ✅ Verify fixes with build/lint/test
+6. ✅ Report summary
+
+## Notes
+
+- **Tech stack validation is HIGHEST PRIORITY** - invalid code must be fixed first
+- Each deep dive agent should work independently and provide comprehensive analysis
+- Deepcode agents should fix issues in priority order
+- All fixes should maintain existing functionality
+- If an agent finds no issues in their domain, they should report "No issues found"
+- If fixes introduce new issues, they should be caught in verification phase

.claude/commands/thorough.md

@@ -0,0 +1,45 @@
+When you think you are done, you are NOT done.
+
+You must run a mandatory 3-pass verification before concluding:
+
+## Pass 1: Correctness & Functionality
+
+- [ ] Verify logic matches requirements and specifications
+- [ ] Check type safety (TypeScript types are correct and complete)
+- [ ] Ensure imports are correct and follow project conventions
+- [ ] Verify all functions/classes work as intended
+- [ ] Check that return values and side effects are correct
+- [ ] Run relevant tests if they exist, or verify testability
+- [ ] Confirm integration with existing code works properly
+
+## Pass 2: Edge Cases & Safety
+
+- [ ] Handle null/undefined inputs gracefully
+- [ ] Validate all user inputs and external data
+- [ ] Check error handling (try/catch, error boundaries, etc.)
+- [ ] Verify security considerations (no sensitive data exposure, proper auth checks)
+- [ ] Test boundary conditions (empty arrays, zero values, max lengths, etc.)
+- [ ] Ensure resource cleanup (file handles, connections, timers)
+- [ ] Check for potential race conditions or async issues
+- [ ] Verify file path security (no directory traversal vulnerabilities)
+
+## Pass 3: Maintainability & Code Quality
+
+- [ ] Code follows project style guide and conventions
+- [ ] Functions/classes are single-purpose and well-named
+- [ ] Remove dead code, unused imports, and console.logs
+- [ ] Extract magic numbers/strings into named constants
+- [ ] Check for code duplication (DRY principle)
+- [ ] Verify appropriate abstraction levels (not over/under-engineered)
+- [ ] Add necessary comments for complex logic
+- [ ] Ensure consistent error messages and logging
+- [ ] Check that code is readable and self-documenting
+- [ ] Verify proper separation of concerns
+
+**For each pass, explicitly report:**
+
+- What you checked
+- Any issues found and how they were fixed
+- Any remaining concerns or trade-offs
+
+Only after completing all three passes with explicit findings may you conclude the work is done.

.claude/commands/validate-build.md

@@ -0,0 +1,49 @@
+# Project Build and Fix Command
+
+Run all builds and intelligently fix any failures based on what changed.
+
+## Instructions
+
+1. **Run the build**
+
+   ```bash
+   npm run build
+   ```
+
+   This builds all packages and the UI application.
+
+2. **If the build succeeds**, report success and stop.
+
+3. **If the build fails**, analyze the failures:
+   - Note which build step failed and the error messages
+   - Check for TypeScript compilation errors, missing dependencies, or configuration issues
+   - Run `git diff main` to see what code has changed
+
+4. **Determine the nature of the failure**:
+   - **If the failure is due to intentional changes** (new features, refactoring, dependency updates):
+     - Fix any TypeScript type errors introduced by the changes
+     - Update build configuration if needed (e.g., tsconfig.json, vite.config.mts)
+     - Ensure all new dependencies are properly installed
+     - Fix import paths or module resolution issues
+
+   - **If the failure appears to be a regression** (broken imports, missing files, configuration errors):
+     - Fix the source code to restore the build
+     - Check for accidentally deleted files or broken references
+     - Verify build configuration files are correct
+
+5. **Common build issues to check**:
+   - **TypeScript errors**: Fix type mismatches, missing types, or incorrect imports
+   - **Missing dependencies**: Run `npm install` if packages are missing
+   - **Import/export errors**: Fix incorrect import paths or missing exports
+   - **Build configuration**: Check tsconfig.json, vite.config.mts, or other build configs
+   - **Package build order**: Ensure `build:packages` completes before building apps
+
+6. **How to decide if it's intentional vs regression**:
+   - Look at the git diff and commit messages
+   - If the change was deliberate and introduced new code that needs fixing → fix the new code
+   - If the change broke existing functionality that should still build → fix the regression
+   - When in doubt, ask the user
+
+7. **After making fixes**, re-run the build to verify everything compiles successfully.
+
+8. **Report summary** of what was fixed (TypeScript errors, configuration issues, missing dependencies, etc.).

.claude/commands/validate-tests.md

@@ -0,0 +1,36 @@
+# Project Test and Fix Command
+
+Run all tests and intelligently fix any failures based on what changed.
+
+## Instructions
+
+1. **Run all tests**
+
+   ```bash
+   npm run test:all
+   ```
+
+2. **If all tests pass**, report success and stop.
+
+3. **If any tests fail**, analyze the failures:
+   - Note which tests failed and their error messages
+   - Run `git diff main` to see what code has changed
+
+4. **Determine the nature of the change**:
+   - **If the logic change is intentional** (new feature, refactor, behavior change):
+     - Update the failing tests to match the new expected behavior
+     - The tests should reflect what the code NOW does correctly
+
+   - **If the logic change appears to be a bug** (regression, unintended side effect):
+     - Fix the source code to restore the expected behavior
+     - Do NOT modify the tests - they are catching a real bug
+
+5. **How to decide if it's a bug vs intentional change**:
+   - Look at the git diff and commit messages
+   - If the change was deliberate and the test expectations are now outdated → update tests
+   - If the change broke existing functionality that should still work → fix the code
+   - When in doubt, ask the user
+
+6. **After making fixes**, re-run the tests to verify everything passes.
+
+7. **Report summary** of what was fixed (tests updated vs code fixed).

.claude_settings.json

@@ -1,24 +0,0 @@
-{
-  "sandbox": {
-    "enabled": true,
-    "autoAllowBashIfSandboxed": true
-  },
-  "permissions": {
-    "defaultMode": "acceptEdits",
-    "allow": [
-      "Read(./**)",
-      "Write(./**)",
-      "Edit(./**)",
-      "Glob(./**)",
-      "Grep(./**)",
-      "Bash(*)",
-      "mcp__puppeteer__puppeteer_navigate",
-      "mcp__puppeteer__puppeteer_screenshot",
-      "mcp__puppeteer__puppeteer_click",
-      "mcp__puppeteer__puppeteer_fill",
-      "mcp__puppeteer__puppeteer_select",
-      "mcp__puppeteer__puppeteer_hover",
-      "mcp__puppeteer__puppeteer_evaluate"
-    ]
-  }
-}

.dockerignore

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+**/node_modules/
+
+# Build outputs
+dist/
+**/dist/
+dist-electron/
+**/dist-electron/
+build/
+**/build/
+.next/
+**/.next/
+.nuxt/
+**/.nuxt/
+out/
+**/out/
+.cache/
+**/.cache/

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,117 @@
+name: Bug Report
+description: File a bug report to help us improve Automaker
+title: '[Bug]: '
+labels: ['bug']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the form below with as much detail as possible.
+
+  - type: dropdown
+    id: operating-system
+    attributes:
+      label: Operating System
+      description: What operating system are you using?
+      options:
+        - macOS
+        - Windows
+        - Linux
+        - Other
+      default: 0
+    validations:
+      required: true
+
+  - type: dropdown
+    id: run-mode
+    attributes:
+      label: Run Mode
+      description: How are you running Automaker?
+      options:
+        - Electron (Desktop App)
+        - Web (Browser)
+        - Docker
+      default: 0
+    validations:
+      required: true
+
+  - type: input
+    id: app-version
+    attributes:
+      label: App Version
+      description: What version of Automaker are you using? (e.g., 0.1.0)
+      placeholder: '0.1.0'
+    validations:
+      required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+      placeholder: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: A clear and concise description of what actually happened.
+      placeholder: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots
+      description: If applicable, add screenshots to help explain your problem.
+      placeholder: Drag and drop screenshots here or paste image URLs
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: If applicable, paste relevant logs or error messages.
+      placeholder: Paste logs here...
+      render: shell
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here.
+      placeholder: Any additional information that might be helpful...
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Checklist
+      options:
+        - label: I have searched existing issues to ensure this bug hasn't been reported already
+          required: true
+        - label: I have provided all required information above
+          required: true

.github/workflows/e2e-tests.yml

@@ -31,24 +31,99 @@ jobs:
       - name: Build server
         run: npm run build --workspace=apps/server
 
+      - name: Set up Git user
+        run: |
+          git config --global user.name "GitHub CI"
+          git config --global user.email "ci@example.com"
+
       - name: Start backend server
-        run: npm run start --workspace=apps/server &
+        run: |
+          echo "Starting backend server..."
+          # Start server in background and save PID
+          npm run start --workspace=apps/server > backend.log 2>&1 &
+          SERVER_PID=$!
+          echo "Server started with PID: $SERVER_PID"
+          echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
+
         env:
           PORT: 3008
           NODE_ENV: test
+          # Use a deterministic API key so Playwright can log in reliably
+          AUTOMAKER_API_KEY: test-api-key-for-e2e-tests
+          # Reduce log noise in CI
+          AUTOMAKER_HIDE_API_KEY: 'true'
+          # Avoid real API calls during CI
+          AUTOMAKER_MOCK_AGENT: 'true'
+          # Simulate containerized environment to skip sandbox confirmation dialogs
+          IS_CONTAINERIZED: 'true'
 
       - name: Wait for backend server
         run: |
           echo "Waiting for backend server to be ready..."
-          for i in {1..30}; do
-            if curl -s http://localhost:3008/api/health > /dev/null 2>&1; then
+
+          # Check if server process is running
+          if [ -z "$SERVER_PID" ]; then
+            echo "ERROR: Server PID not found in environment"
+            cat backend.log 2>/dev/null || echo "No backend log found"
+            exit 1
+          fi
+
+          # Check if process is actually running
+          if ! kill -0 $SERVER_PID 2>/dev/null; then
+            echo "ERROR: Server process $SERVER_PID is not running!"
+            echo "=== Backend logs ==="
+            cat backend.log
+            echo ""
+            echo "=== Recent system logs ==="
+            dmesg 2>/dev/null | tail -20 || echo "No dmesg available"
+            exit 1
+          fi
+
+          # Wait for health endpoint
+          for i in {1..60}; do
+            if curl -s -f http://localhost:3008/api/health > /dev/null 2>&1; then
               echo "Backend server is ready!"
+              echo "=== Backend logs ==="
+              cat backend.log
+              echo ""
+              echo "Health check response:"
+              curl -s http://localhost:3008/api/health | jq . 2>/dev/null || echo "Health check: $(curl -s http://localhost:3008/api/health 2>/dev/null || echo 'No response')"
               exit 0
             fi
-            echo "Waiting... ($i/30)"
+            
+            # Check if server process is still running
+            if ! kill -0 $SERVER_PID 2>/dev/null; then
+              echo "ERROR: Server process died during wait!"
+              echo "=== Backend logs ==="
+              cat backend.log
+              exit 1
+            fi
+            
+            echo "Waiting... ($i/60)"
             sleep 1
           done
-          echo "Backend server failed to start!"
+
+          echo "ERROR: Backend server failed to start within 60 seconds!"
+          echo "=== Backend logs ==="
+          cat backend.log
+          echo ""
+          echo "=== Process status ==="
+          ps aux | grep -E "(node|tsx)" | grep -v grep || echo "No node processes found"
+          echo ""
+          echo "=== Port status ==="
+          netstat -tlnp 2>/dev/null | grep :3008 || echo "Port 3008 not listening"
+          lsof -i :3008 2>/dev/null || echo "lsof not available or port not in use"
+          echo ""
+          echo "=== Health endpoint test ==="
+          curl -v http://localhost:3008/api/health 2>&1 || echo "Health endpoint failed"
+
+          # Kill the server process if it's still hanging
+          if kill -0 $SERVER_PID 2>/dev/null; then
+            echo ""
+            echo "Killing stuck server process..."
+            kill -9 $SERVER_PID 2>/dev/null || true
+          fi
+
           exit 1
 
       - name: Run E2E tests
@@ -59,6 +134,20 @@ jobs:
           CI: true
           VITE_SERVER_URL: http://localhost:3008
           VITE_SKIP_SETUP: 'true'
+          # Keep UI-side login/defaults consistent
+          AUTOMAKER_API_KEY: test-api-key-for-e2e-tests
+
+      - name: Print backend logs on failure
+        if: failure()
+        run: |
+          echo "=== E2E Tests Failed - Backend Logs ==="
+          cat backend.log 2>/dev/null || echo "No backend log found"
+          echo ""
+          echo "=== Process status at failure ==="
+          ps aux | grep -E "(node|tsx)" | grep -v grep || echo "No node processes found"
+          echo ""
+          echo "=== Port status ==="
+          netstat -tlnp 2>/dev/null | grep :3008 || echo "Port 3008 not listening"
 
       - name: Upload Playwright report
         uses: actions/upload-artifact@v4
@@ -68,10 +157,22 @@ jobs:
           path: apps/ui/playwright-report/
           retention-days: 7
 
-      - name: Upload test results
+      - name: Upload test results (screenshots, traces, videos)
         uses: actions/upload-artifact@v4
-        if: failure()
+        if: always()
         with:
           name: test-results
-          path: apps/ui/test-results/
+          path: |
+            apps/ui/test-results/
           retention-days: 7
+          if-no-files-found: ignore
+
+      - name: Cleanup - Kill backend server
+        if: always()
+        run: |
+          if [ -n "$SERVER_PID" ]; then
+            echo "Cleaning up backend server (PID: $SERVER_PID)..."
+            kill $SERVER_PID 2>/dev/null || true
+            kill -9 $SERVER_PID 2>/dev/null || true
+            echo "Backend server cleanup complete"
+          fi

.github/workflows/security-audit.yml

@@ -26,5 +26,5 @@ jobs:
           check-lockfile: 'true'
 
       - name: Run npm audit
-        run: npm audit --audit-level=moderate
+        run: npm audit --audit-level=critical
         continue-on-error: false

.gitignore

@@ -73,10 +73,25 @@ blob-report/
 !.env.example
 !.env.local.example
 
+# Codex config (contains API keys)
+.codex/config.toml
+
 # TypeScript
 *.tsbuildinfo
 
 # Misc
 *.pem
 
-docker-compose.override.yml
+docker-compose.override.yml
+.claude/docker-compose.override.yml
+.claude/hans/
+
+pnpm-lock.yaml
+yarn.lock
+
+# Fork-specific workflow files (should never be committed)
+DEVELOPMENT_WORKFLOW.md
+check-sync.sh
+# API key files
+data/.api-key
+data/credentials.json

.husky/pre-commit

@@ -1 +1,46 @@
-npx lint-staged
+#!/usr/bin/env sh
+
+# Try to load nvm if available (optional - works without it too)
+if [ -z "$NVM_DIR" ]; then
+  # Check for Herd's nvm first (macOS with Herd)
+  if [ -s "$HOME/Library/Application Support/Herd/config/nvm/nvm.sh" ]; then
+    export NVM_DIR="$HOME/Library/Application Support/Herd/config/nvm"
+  # Then check standard nvm location
+  elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+    export NVM_DIR="$HOME/.nvm"
+  fi
+fi
+
+# Source nvm if found (silently skip if not available)
+[ -n "$NVM_DIR" ] && [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" 2>/dev/null
+
+# Load node version from .nvmrc if using nvm (silently skip if nvm not available or fails)
+if [ -f .nvmrc ] && command -v nvm >/dev/null 2>&1; then
+  # Check if Unix nvm was sourced (it's a shell function with NVM_DIR set)
+  if [ -n "$NVM_DIR" ] && type nvm 2>/dev/null | grep -q "function"; then
+    # Unix nvm: reads .nvmrc automatically
+    nvm use >/dev/null 2>&1 || true
+  else
+    # nvm-windows: needs explicit version from .nvmrc
+    NODE_VERSION=$(cat .nvmrc | tr -d '[:space:]')
+    if [ -n "$NODE_VERSION" ]; then
+      nvm use "$NODE_VERSION" >/dev/null 2>&1 || true
+    fi
+  fi
+fi
+
+# Ensure common system paths are in PATH (for systems without nvm)
+# This helps find node/npm installed via Homebrew, system packages, etc.
+export PATH="$PATH:/usr/local/bin:/opt/homebrew/bin:/usr/bin"
+
+# Run lint-staged - works with or without nvm
+# Prefer npx, fallback to npm exec, both work with system-installed Node.js
+if command -v npx >/dev/null 2>&1; then
+  npx lint-staged
+elif command -v npm >/dev/null 2>&1; then
+  npm exec -- lint-staged
+else
+  echo "Error: Neither npx nor npm found in PATH."
+  echo "Please ensure Node.js is installed (via nvm, Homebrew, system package manager, etc.)"
+  exit 1
+fi

.nvmrc

@@ -0,0 +1,2 @@
+22
+

.prettierignore

@@ -23,6 +23,8 @@ pnpm-lock.yaml
 # Generated files
 *.min.js
 *.min.css
+routeTree.gen.ts
+apps/ui/src/routeTree.gen.ts
 
 # Test artifacts
 test-results/

CLAUDE.md

@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Automaker is an autonomous AI development studio built as an npm workspace monorepo. It provides a Kanban-based workflow where AI agents (powered by Claude Agent SDK) implement features in isolated git worktrees.
+
+## Common Commands
+
+```bash
+# Development
+npm run dev                 # Interactive launcher (choose web or electron)
+npm run dev:web             # Web browser mode (localhost:3007)
+npm run dev:electron        # Desktop app mode
+npm run dev:electron:debug  # Desktop with DevTools open
+
+# Building
+npm run build               # Build web application
+npm run build:packages      # Build all shared packages (required before other builds)
+npm run build:electron      # Build desktop app for current platform
+npm run build:server        # Build server only
+
+# Testing
+npm run test                # E2E tests (Playwright, headless)
+npm run test:headed         # E2E tests with browser visible
+npm run test:server         # Server unit tests (Vitest)
+npm run test:packages       # All shared package tests
+npm run test:all            # All tests (packages + server)
+
+# Single test file
+npm run test:server -- tests/unit/specific.test.ts
+
+# Linting and formatting
+npm run lint                # ESLint
+npm run format              # Prettier write
+npm run format:check        # Prettier check
+```
+
+## Architecture
+
+### Monorepo Structure
+
+```
+automaker/
+├── apps/
+│   ├── ui/           # React + Vite + Electron frontend (port 3007)
+│   └── server/       # Express + WebSocket backend (port 3008)
+└── libs/             # Shared packages (@automaker/*)
+    ├── types/        # Core TypeScript definitions (no dependencies)
+    ├── utils/        # Logging, errors, image processing, context loading
+    ├── prompts/      # AI prompt templates
+    ├── platform/     # Path management, security, process spawning
+    ├── model-resolver/    # Claude model alias resolution
+    ├── dependency-resolver/  # Feature dependency ordering
+    └── git-utils/    # Git operations & worktree management
+```
+
+### Package Dependency Chain
+
+Packages can only depend on packages above them:
+
+```
+@automaker/types (no dependencies)
+    ↓
+@automaker/utils, @automaker/prompts, @automaker/platform, @automaker/model-resolver, @automaker/dependency-resolver
+    ↓
+@automaker/git-utils
+    ↓
+@automaker/server, @automaker/ui
+```
+
+### Key Technologies
+
+- **Frontend**: React 19, Vite 7, Electron 39, TanStack Router, Zustand 5, Tailwind CSS 4
+- **Backend**: Express 5, WebSocket (ws), Claude Agent SDK, node-pty
+- **Testing**: Playwright (E2E), Vitest (unit)
+
+### Server Architecture
+
+The server (`apps/server/src/`) follows a modular pattern:
+
+- `routes/` - Express route handlers organized by feature (agent, features, auto-mode, worktree, etc.)
+- `services/` - Business logic (AgentService, AutoModeService, FeatureLoader, TerminalService)
+- `providers/` - AI provider abstraction (currently Claude via Claude Agent SDK)
+- `lib/` - Utilities (events, auth, worktree metadata)
+
+### Frontend Architecture
+
+The UI (`apps/ui/src/`) uses:
+
+- `routes/` - TanStack Router file-based routing
+- `components/views/` - Main view components (board, settings, terminal, etc.)
+- `store/` - Zustand stores with persistence (app-store.ts, setup-store.ts)
+- `hooks/` - Custom React hooks
+- `lib/` - Utilities and API client
+
+## Data Storage
+
+### Per-Project Data (`.automaker/`)
+
+```
+.automaker/
+├── features/              # Feature JSON files and images
+│   └── {featureId}/
+│       ├── feature.json
+│       ├── agent-output.md
+│       └── images/
+├── context/               # Context files for AI agents (CLAUDE.md, etc.)
+├── settings.json          # Project-specific settings
+├── spec.md               # Project specification
+└── analysis.json         # Project structure analysis
+```
+
+### Global Data (`DATA_DIR`, default `./data`)
+
+```
+data/
+├── settings.json          # Global settings, profiles, shortcuts
+├── credentials.json       # API keys
+├── sessions-metadata.json # Chat session metadata
+└── agent-sessions/        # Conversation histories
+```
+
+## Import Conventions
+
+Always import from shared packages, never from old paths:
+
+```typescript
+// ✅ Correct
+import type { Feature, ExecuteOptions } from '@automaker/types';
+import { createLogger, classifyError } from '@automaker/utils';
+import { getEnhancementPrompt } from '@automaker/prompts';
+import { getFeatureDir, ensureAutomakerDir } from '@automaker/platform';
+import { resolveModelString } from '@automaker/model-resolver';
+import { resolveDependencies } from '@automaker/dependency-resolver';
+import { getGitRepositoryDiffs } from '@automaker/git-utils';
+
+// ❌ Never import from old paths
+import { Feature } from '../services/feature-loader'; // Wrong
+import { createLogger } from '../lib/logger'; // Wrong
+```
+
+## Key Patterns
+
+### Event-Driven Architecture
+
+All server operations emit events that stream to the frontend via WebSocket. Events are created using `createEventEmitter()` from `lib/events.ts`.
+
+### Git Worktree Isolation
+
+Each feature executes in an isolated git worktree, created via `@automaker/git-utils`. This protects the main branch during AI agent execution.
+
+### Context Files
+
+Project-specific rules are stored in `.automaker/context/` and automatically loaded into agent prompts via `loadContextFiles()` from `@automaker/utils`.
+
+### Model Resolution
+
+Use `resolveModelString()` from `@automaker/model-resolver` to convert model aliases:
+
+- `haiku` → `claude-haiku-4-5`
+- `sonnet` → `claude-sonnet-4-20250514`
+- `opus` → `claude-opus-4-5-20251101`
+
+## Environment Variables
+
+- `ANTHROPIC_API_KEY` - Anthropic API key (or use Claude Code CLI auth)
+- `PORT` - Server port (default: 3008)
+- `DATA_DIR` - Data storage directory (default: ./data)
+- `ALLOWED_ROOT_DIRECTORY` - Restrict file operations to specific directory
+- `AUTOMAKER_MOCK_AGENT=true` - Enable mock agent mode for CI testing

CONTRIBUTING.md

@@ -0,0 +1,685 @@
+# Contributing to Automaker
+
+Thank you for your interest in contributing to Automaker! We're excited to have you join our community of developers building the future of autonomous AI development.
+
+Automaker is an autonomous AI development studio that provides a Kanban-based workflow where AI agents implement features in isolated git worktrees. Whether you're fixing bugs, adding features, improving documentation, or suggesting ideas, your contributions help make this project better for everyone.
+
+This guide will help you get started with contributing to Automaker. Please take a moment to read through these guidelines to ensure a smooth contribution process.
+
+## Contribution License Agreement
+
+**Important:** By submitting, pushing, or contributing any code, documentation, pull requests, issues, or other materials to the Automaker project, you agree to assign all right, title, and interest in and to your contributions, including all copyrights, patents, and other intellectual property rights, to the Core Contributors of Automaker. This assignment is irrevocable and includes the right to use, modify, distribute, and monetize your contributions in any manner.
+
+**You understand and agree that you will have no right to receive any royalties, compensation, or other financial benefits from any revenue, income, or commercial use generated from your contributed code or any derivative works thereof.** All contributions are made without expectation of payment or financial return.
+
+For complete details on contribution terms and rights assignment, please review [Section 5 (CONTRIBUTIONS AND RIGHTS ASSIGNMENT) of the LICENSE](LICENSE#5-contributions-and-rights-assignment).
+
+## Table of Contents
+
+- [Contributing to Automaker](#contributing-to-automaker)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Fork and Clone](#fork-and-clone)
+    - [Development Setup](#development-setup)
+    - [Project Structure](#project-structure)
+  - [Pull Request Process](#pull-request-process)
+    - [Branch Naming Convention](#branch-naming-convention)
+    - [Commit Message Format](#commit-message-format)
+    - [Submitting a Pull Request](#submitting-a-pull-request)
+      - [1. Prepare Your Changes](#1-prepare-your-changes)
+      - [2. Run Pre-submission Checks](#2-run-pre-submission-checks)
+      - [3. Push Your Changes](#3-push-your-changes)
+      - [4. Open a Pull Request](#4-open-a-pull-request)
+      - [PR Requirements Checklist](#pr-requirements-checklist)
+    - [Review Process](#review-process)
+      - [What to Expect](#what-to-expect)
+      - [Review Focus Areas](#review-focus-areas)
+      - [Responding to Feedback](#responding-to-feedback)
+      - [Approval Criteria](#approval-criteria)
+      - [Getting Help](#getting-help)
+  - [Code Style Guidelines](#code-style-guidelines)
+  - [Testing Requirements](#testing-requirements)
+    - [Running Tests](#running-tests)
+    - [Test Frameworks](#test-frameworks)
+      - [End-to-End Tests (Playwright)](#end-to-end-tests-playwright)
+      - [Unit Tests (Vitest)](#unit-tests-vitest)
+    - [Writing Tests](#writing-tests)
+      - [When to Write Tests](#when-to-write-tests)
+    - [CI/CD Pipeline](#cicd-pipeline)
+      - [CI Checks](#ci-checks)
+      - [CI Testing Environment](#ci-testing-environment)
+      - [Viewing CI Results](#viewing-ci-results)
+      - [Common CI Failures](#common-ci-failures)
+    - [Coverage Requirements](#coverage-requirements)
+  - [Issue Reporting](#issue-reporting)
+    - [Bug Reports](#bug-reports)
+      - [Before Reporting](#before-reporting)
+      - [Bug Report Template](#bug-report-template)
+    - [Feature Requests](#feature-requests)
+      - [Before Requesting](#before-requesting)
+      - [Feature Request Template](#feature-request-template)
+    - [Security Issues](#security-issues)
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+Before contributing to Automaker, ensure you have the following installed on your system:
+
+- **Node.js 18+** (tested with Node.js 22)
+  - Download from [nodejs.org](https://nodejs.org/)
+  - Verify installation: `node --version`
+- **npm** (comes with Node.js)
+  - Verify installation: `npm --version`
+- **Git** for version control
+  - Verify installation: `git --version`
+- **Claude Code CLI** or **Anthropic API Key** (for AI agent functionality)
+  - Required to run the AI development features
+
+**Optional but recommended:**
+
+- A code editor with TypeScript support (VS Code recommended)
+- GitHub CLI (`gh`) for easier PR management
+
+### Fork and Clone
+
+1. **Fork the repository** on GitHub
+   - Navigate to [https://github.com/AutoMaker-Org/automaker](https://github.com/AutoMaker-Org/automaker)
+   - Click the "Fork" button in the top-right corner
+   - This creates your own copy of the repository
+
+2. **Clone your fork locally**
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/automaker.git
+   cd automaker
+   ```
+
+3. **Add the upstream remote** to keep your fork in sync
+
+   ```bash
+   git remote add upstream https://github.com/AutoMaker-Org/automaker.git
+   ```
+
+4. **Verify remotes**
+   ```bash
+   git remote -v
+   # Should show:
+   # origin    https://github.com/YOUR_USERNAME/automaker.git (fetch)
+   # origin    https://github.com/YOUR_USERNAME/automaker.git (push)
+   # upstream  https://github.com/AutoMaker-Org/automaker.git (fetch)
+   # upstream  https://github.com/AutoMaker-Org/automaker.git (push)
+   ```
+
+### Development Setup
+
+1. **Install dependencies**
+
+   ```bash
+   npm install
+   ```
+
+2. **Build shared packages** (required before running the app)
+
+   ```bash
+   npm run build:packages
+   ```
+
+3. **Start the development server**
+   ```bash
+   npm run dev          # Interactive launcher - choose mode
+   npm run dev:web      # Browser mode (web interface)
+   npm run dev:electron # Desktop app mode
+   ```
+
+**Common development commands:**
+
+| Command                  | Description                      |
+| ------------------------ | -------------------------------- |
+| `npm run dev`            | Interactive development launcher |
+| `npm run dev:web`        | Start in browser mode            |
+| `npm run dev:electron`   | Start desktop app                |
+| `npm run build`          | Build all packages and apps      |
+| `npm run build:packages` | Build shared packages only       |
+| `npm run lint`           | Run ESLint checks                |
+| `npm run format`         | Format code with Prettier        |
+| `npm run format:check`   | Check formatting without changes |
+| `npm run test`           | Run E2E tests (Playwright)       |
+| `npm run test:server`    | Run server unit tests            |
+| `npm run test:packages`  | Run package tests                |
+| `npm run test:all`       | Run all tests                    |
+
+### Project Structure
+
+Automaker is organized as an npm workspace monorepo:
+
+```
+automaker/
+├── apps/
+│   ├── ui/              # React + Vite + Electron frontend
+│   └── server/          # Express + WebSocket backend
+├── libs/
+│   ├── @automaker/types/            # Shared TypeScript types
+│   ├── @automaker/utils/            # Utility functions
+│   ├── @automaker/prompts/          # AI prompt templates
+│   ├── @automaker/platform/         # Platform abstractions
+│   ├── @automaker/model-resolver/   # AI model resolution
+│   ├── @automaker/dependency-resolver/ # Dependency management
+│   └── @automaker/git-utils/        # Git operations
+├── docs/                # Documentation
+└── package.json         # Root package configuration
+```
+
+**Key conventions:**
+
+- Always import from `@automaker/*` shared packages, never use relative paths to `libs/`
+- Frontend code lives in `apps/ui/`
+- Backend code lives in `apps/server/`
+- Shared logic should be in the appropriate `libs/` package
+
+---
+
+## Pull Request Process
+
+This section covers everything you need to know about contributing changes through pull requests, from creating your branch to getting your code merged.
+
+### Branch Naming Convention
+
+We use a consistent branch naming pattern to keep our repository organized:
+
+```
+<type>/<description>
+```
+
+**Branch types:**
+
+| Type       | Purpose                  | Example                           |
+| ---------- | ------------------------ | --------------------------------- |
+| `feature`  | New functionality        | `feature/add-user-authentication` |
+| `fix`      | Bug fixes                | `fix/resolve-memory-leak`         |
+| `docs`     | Documentation changes    | `docs/update-contributing-guide`  |
+| `refactor` | Code restructuring       | `refactor/simplify-api-handlers`  |
+| `test`     | Adding or updating tests | `test/add-utils-unit-tests`       |
+| `chore`    | Maintenance tasks        | `chore/update-dependencies`       |
+
+**Guidelines:**
+
+- Use lowercase letters and hyphens (no underscores or spaces)
+- Keep descriptions short but descriptive
+- Include issue number when applicable: `feature/123-add-login`
+
+```bash
+# Create and checkout a new feature branch
+git checkout -b feature/add-dark-mode
+
+# Create a fix branch with issue reference
+git checkout -b fix/456-resolve-login-error
+```
+
+### Commit Message Format
+
+We follow the **Conventional Commits** style for clear, readable commit history:
+
+```
+<type>: <description>
+
+[optional body]
+```
+
+**Commit types:**
+
+| Type       | Purpose                     |
+| ---------- | --------------------------- |
+| `feat`     | New feature                 |
+| `fix`      | Bug fix                     |
+| `docs`     | Documentation only          |
+| `style`    | Formatting (no code change) |
+| `refactor` | Code restructuring          |
+| `test`     | Adding or updating tests    |
+| `chore`    | Maintenance tasks           |
+
+**Guidelines:**
+
+- Use **imperative mood** ("Add feature" not "Added feature")
+- Keep first line under **72 characters**
+- Capitalize the first letter after the type prefix
+- No period at the end of the subject line
+- Add a blank line before the body for detailed explanations
+
+**Examples:**
+
+```bash
+# Simple commit
+git commit -m "feat: Add user authentication flow"
+
+# Commit with body for more context
+git commit -m "fix: Resolve memory leak in WebSocket handler
+
+The connection cleanup was not being called when clients
+disconnected unexpectedly. Added proper cleanup in the
+error handler to prevent memory accumulation."
+
+# Documentation update
+git commit -m "docs: Update API documentation"
+
+# Refactoring
+git commit -m "refactor: Simplify state management logic"
+```
+
+### Submitting a Pull Request
+
+Follow these steps to submit your contribution:
+
+#### 1. Prepare Your Changes
+
+Ensure you've synced with the latest upstream changes:
+
+```bash
+# Fetch latest changes from upstream
+git fetch upstream
+
+# Rebase your branch on main (if needed)
+git rebase upstream/main
+```
+
+#### 2. Run Pre-submission Checks
+
+Before opening your PR, verify everything passes locally:
+
+```bash
+# Run all tests
+npm run test:all
+
+# Check formatting
+npm run format:check
+
+# Run linter
+npm run lint
+
+# Build to verify no compile errors
+npm run build
+```
+
+#### 3. Push Your Changes
+
+```bash
+# Push your branch to your fork
+git push origin feature/your-feature-name
+```
+
+#### 4. Open a Pull Request
+
+1. Go to your fork on GitHub
+2. Click "Compare & pull request" for your branch
+3. Ensure the base repository is `AutoMaker-Org/automaker` and base branch is `main`
+4. Fill out the PR template completely
+
+#### PR Requirements Checklist
+
+Your PR should include:
+
+- [ ] **Clear title** describing the change (use conventional commit format)
+- [ ] **Description** explaining what changed and why
+- [ ] **Link to related issue** (if applicable): `Closes #123` or `Fixes #456`
+- [ ] **All CI checks passing** (format, lint, build, tests)
+- [ ] **No merge conflicts** with main branch
+- [ ] **Tests included** for new functionality
+- [ ] **Documentation updated** if adding/changing public APIs
+
+**Example PR Description:**
+
+```markdown
+## Summary
+
+This PR adds dark mode support to the Automaker UI.
+
+- Implements theme toggle in settings panel
+- Adds CSS custom properties for theme colors
+- Persists theme preference to localStorage
+
+## Related Issue
+
+Closes #123
+
+## Testing
+
+- [x] Tested toggle functionality in Chrome and Firefox
+- [x] Verified theme persists across page reloads
+- [x] Checked accessibility contrast ratios
+
+## Screenshots
+
+[Include before/after screenshots for UI changes]
+```
+
+### Review Process
+
+All contributions go through code review to maintain quality:
+
+#### What to Expect
+
+1. **CI Checks Run First** - Automated checks (format, lint, build, tests) must pass before review
+2. **Maintainer Review** - The project maintainers will review your PR and decide whether to merge it
+3. **Feedback & Discussion** - The reviewer may ask questions or request changes
+4. **Iteration** - Make requested changes and push updates to the same branch
+5. **Approval & Merge** - Once approved and checks pass, your PR will be merged
+
+#### Review Focus Areas
+
+The reviewer checks for:
+
+- **Correctness** - Does the code work as intended?
+- **Clean Code** - Does it follow our [code style guidelines](#code-style-guidelines)?
+- **Test Coverage** - Are new features properly tested?
+- **Documentation** - Are public APIs documented?
+- **Breaking Changes** - Are any breaking changes discussed first?
+
+#### Responding to Feedback
+
+- Respond to **all** review comments, even if just to acknowledge
+- Ask questions if feedback is unclear
+- Push additional commits to address feedback (don't force-push during review)
+- Mark conversations as resolved once addressed
+
+#### Approval Criteria
+
+Your PR is ready to merge when:
+
+- ✅ All CI checks pass
+- ✅ The maintainer has approved the changes
+- ✅ All review comments are addressed
+- ✅ No unresolved merge conflicts
+
+#### Getting Help
+
+If your PR seems stuck:
+
+- Comment asking for status update (mention @webdevcody if needed)
+- Reach out on [Discord](https://discord.gg/jjem7aEDKU)
+- Make sure all checks are passing and you've responded to all feedback
+
+---
+
+## Code Style Guidelines
+
+Automaker uses automated tooling to enforce code style. Run `npm run format` to format code and `npm run lint` to check for issues. Pre-commit hooks automatically format staged files before committing.
+
+---
+
+## Testing Requirements
+
+Testing helps prevent regressions. Automaker uses **Playwright** for end-to-end testing and **Vitest** for unit tests.
+
+### Running Tests
+
+Use these commands to run tests locally:
+
+| Command                        | Description                           |
+| ------------------------------ | ------------------------------------- |
+| `npm run test`                 | Run E2E tests (Playwright)            |
+| `npm run test:server`          | Run server unit tests (Vitest)        |
+| `npm run test:packages`        | Run shared package tests              |
+| `npm run test:all`             | Run all tests                         |
+| `npm run test:server:coverage` | Run server tests with coverage report |
+
+**Before submitting a PR**, always run the full test suite:
+
+```bash
+npm run test:all
+```
+
+### Test Frameworks
+
+#### End-to-End Tests (Playwright)
+
+E2E tests verify the entire application works correctly from a user's perspective.
+
+- **Framework:** [Playwright](https://playwright.dev/)
+- **Location:** `e2e/` directory
+- **Test ports:** UI on port 3007, Server on port 3008
+
+**Running E2E tests:**
+
+```bash
+# Run all E2E tests
+npm run test
+
+# Run with headed browser (useful for debugging)
+npx playwright test --headed
+
+# Run a specific test file
+npm test --workspace=@automaker/ui -- tests/example.spec.ts
+```
+
+**E2E Test Guidelines:**
+
+- Write tests from a user's perspective
+- Use descriptive test names that explain the scenario
+- Clean up test data after each test
+- Use appropriate timeouts for async operations
+- Prefer `locator` over direct selectors for resilience
+
+#### Unit Tests (Vitest)
+
+Unit tests verify individual functions and modules work correctly in isolation.
+
+- **Framework:** [Vitest](https://vitest.dev/)
+- **Location:** In the `tests/` directory within each package (e.g., `apps/server/tests/`)
+
+**Running unit tests:**
+
+```bash
+# Run all server unit tests
+npm run test:server
+
+# Run with coverage report
+npm run test:server:coverage
+
+# Run package tests
+npm run test:packages
+
+# Run in watch mode during development
+npx vitest --watch
+```
+
+**Unit Test Guidelines:**
+
+- Keep tests small and focused on one behavior
+- Use descriptive test names: `it('should return null when user is not found')`
+- Follow the AAA pattern: Arrange, Act, Assert
+- Mock external dependencies to isolate the unit under test
+- Aim for meaningful coverage, not just line coverage
+
+### Writing Tests
+
+#### When to Write Tests
+
+- **New features:** All new features should include tests
+- **Bug fixes:** Add a test that reproduces the bug before fixing
+- **Refactoring:** Ensure existing tests pass after refactoring
+- **Public APIs:** All public APIs must have test coverage
+
+### CI/CD Pipeline
+
+Automaker uses **GitHub Actions** for continuous integration. Every pull request triggers automated checks.
+
+#### CI Checks
+
+The following checks must pass before your PR can be merged:
+
+| Check             | Description                                   |
+| ----------------- | --------------------------------------------- |
+| **Format**        | Verifies code is formatted with Prettier      |
+| **Build**         | Ensures the project compiles without errors   |
+| **Package Tests** | Runs tests for shared `@automaker/*` packages |
+| **Server Tests**  | Runs server unit tests with coverage          |
+
+#### CI Testing Environment
+
+For CI environments, Automaker supports a mock agent mode:
+
+```bash
+# Enable mock agent mode for CI testing
+AUTOMAKER_MOCK_AGENT=true npm run test
+```
+
+This allows tests to run without requiring a real Claude API connection.
+
+#### Viewing CI Results
+
+1. Go to your PR on GitHub
+2. Scroll to the "Checks" section at the bottom
+3. Click on any failed check to see detailed logs
+4. Fix issues locally and push updates
+
+#### Common CI Failures
+
+| Issue               | Solution                                      |
+| ------------------- | --------------------------------------------- |
+| Format check failed | Run `npm run format` locally                  |
+| Build failed        | Run `npm run build` and fix TypeScript errors |
+| Tests failed        | Run `npm run test:all` locally to reproduce   |
+| Coverage decreased  | Add tests for new code paths                  |
+
+### Coverage Requirements
+
+While we don't enforce strict coverage percentages, we expect:
+
+- **New features:** Should include comprehensive tests
+- **Bug fixes:** Should include a regression test
+- **Critical paths:** Must have test coverage (authentication, data persistence, etc.)
+
+To view coverage reports locally:
+
+```bash
+npm run test:server:coverage
+```
+
+This generates an HTML report you can open in your browser to see which lines are covered.
+
+---
+
+## Issue Reporting
+
+Found a bug or have an idea for a new feature? We'd love to hear from you! This section explains how to report issues effectively.
+
+### Bug Reports
+
+When reporting a bug, please provide as much information as possible to help us understand and reproduce the issue.
+
+#### Before Reporting
+
+1. **Search existing issues** - Check if the bug has already been reported
+2. **Try the latest version** - Make sure you're running the latest version of Automaker
+3. **Reproduce the issue** - Verify you can consistently reproduce the bug
+
+#### Bug Report Template
+
+When creating a bug report, include:
+
+- **Title:** A clear, descriptive title summarizing the issue
+- **Environment:**
+  - Operating System and version
+  - Node.js version (`node --version`)
+  - Automaker version or commit hash
+- **Steps to Reproduce:** Numbered list of steps to reproduce the bug
+- **Expected Behavior:** What you expected to happen
+- **Actual Behavior:** What actually happened
+- **Logs/Screenshots:** Any relevant error messages, console output, or screenshots
+
+**Example Bug Report:**
+
+```markdown
+## Bug: WebSocket connection drops after 5 minutes of inactivity
+
+### Environment
+
+- OS: Windows 11
+- Node.js: 22.11.0
+- Automaker: commit abc1234
+
+### Steps to Reproduce
+
+1. Start the application with `npm run dev:web`
+2. Open the Kanban board
+3. Leave the browser tab open for 5+ minutes without interaction
+4. Try to move a card
+
+### Expected Behavior
+
+The card should move to the new column.
+
+### Actual Behavior
+
+The UI shows "Connection lost" and the card doesn't move.
+
+### Logs
+
+[WebSocket] Connection closed: 1006
+```
+
+### Feature Requests
+
+We welcome ideas for improving Automaker! Here's how to submit a feature request:
+
+#### Before Requesting
+
+1. **Check existing issues** - Your idea may already be proposed or in development
+2. **Consider scope** - Think about whether the feature fits Automaker's mission as an autonomous AI development studio
+
+#### Feature Request Template
+
+A good feature request includes:
+
+- **Title:** A brief, descriptive title
+- **Problem Statement:** What problem does this feature solve?
+- **Proposed Solution:** How do you envision this working?
+- **Alternatives Considered:** What other approaches did you consider?
+- **Additional Context:** Mockups, examples, or references that help explain your idea
+
+**Example Feature Request:**
+
+```markdown
+## Feature: Dark Mode Support
+
+### Problem Statement
+
+Working late at night, the bright UI causes eye strain and doesn't match
+my system's dark theme preference.
+
+### Proposed Solution
+
+Add a theme toggle in the settings panel that allows switching between
+light and dark modes. Ideally, it should also detect system preference.
+
+### Alternatives Considered
+
+- Browser extension to force dark mode (doesn't work well with custom styling)
+- Custom CSS override (breaks with updates)
+
+### Additional Context
+
+Similar to how VS Code handles themes - a dropdown in settings with
+immediate preview.
+```
+
+### Security Issues
+
+**Important:** If you discover a security vulnerability, please do NOT open a public issue. Instead:
+
+1. Join our [Discord server](https://discord.gg/jjem7aEDKU) and send a direct message to the user `@webdevcody`
+2. Include detailed steps to reproduce
+3. Allow time for us to address the issue before public disclosure
+
+We take security seriously and appreciate responsible disclosure.
+
+---
+
+For license and contribution terms, see the [LICENSE](LICENSE) file in the repository root and the [README.md](README.md#license) for more details.
+
+---
+
+Thank you for contributing to Automaker!

Dockerfile

@@ -0,0 +1,203 @@
+# Automaker Multi-Stage Dockerfile
+# Single Dockerfile for both server and UI builds
+# Usage:
+#   docker build --target server -t automaker-server .
+#   docker build --target ui -t automaker-ui .
+# Or use docker-compose which selects targets automatically
+
+# =============================================================================
+# BASE STAGE - Common setup for all builds (DRY: defined once, used by all)
+# =============================================================================
+FROM node:22-slim AS base
+
+# Install build dependencies for native modules (node-pty)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 make g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy root package files
+COPY package*.json ./
+
+# Copy all libs package.json files (centralized - add new libs here)
+COPY libs/types/package*.json ./libs/types/
+COPY libs/utils/package*.json ./libs/utils/
+COPY libs/prompts/package*.json ./libs/prompts/
+COPY libs/platform/package*.json ./libs/platform/
+COPY libs/model-resolver/package*.json ./libs/model-resolver/
+COPY libs/dependency-resolver/package*.json ./libs/dependency-resolver/
+COPY libs/git-utils/package*.json ./libs/git-utils/
+
+# Copy scripts (needed by npm workspace)
+COPY scripts ./scripts
+
+# =============================================================================
+# SERVER BUILD STAGE
+# =============================================================================
+FROM base AS server-builder
+
+# Copy server-specific package.json
+COPY apps/server/package*.json ./apps/server/
+
+# Install dependencies (--ignore-scripts to skip husky/prepare, then rebuild native modules)
+RUN npm ci --ignore-scripts && npm rebuild node-pty
+
+# Copy all source files
+COPY libs ./libs
+COPY apps/server ./apps/server
+
+# Build packages in dependency order, then build server
+RUN npm run build:packages && npm run build --workspace=apps/server
+
+# =============================================================================
+# SERVER PRODUCTION STAGE
+# =============================================================================
+FROM node:22-slim AS server
+
+# Build argument for tracking which commit this image was built from
+ARG GIT_COMMIT_SHA=unknown
+LABEL automaker.git.commit.sha="${GIT_COMMIT_SHA}"
+
+# Install git, curl, bash (for terminal), gosu (for user switching), and GitHub CLI (pinned version, multi-arch)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git curl bash gosu ca-certificates openssh-client \
+    && GH_VERSION="2.63.2" \
+    && ARCH=$(uname -m) \
+    && case "$ARCH" in \
+        x86_64) GH_ARCH="amd64" ;; \
+        aarch64|arm64) GH_ARCH="arm64" ;; \
+        *) echo "Unsupported architecture: $ARCH" && exit 1 ;; \
+    esac \
+    && curl -L "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_${GH_ARCH}.tar.gz" -o gh.tar.gz \
+    && tar -xzf gh.tar.gz \
+    && mv gh_${GH_VERSION}_linux_${GH_ARCH}/bin/gh /usr/local/bin/gh \
+    && rm -rf gh.tar.gz gh_${GH_VERSION}_linux_${GH_ARCH} \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Claude CLI globally (available to all users via npm global bin)
+RUN npm install -g @anthropic-ai/claude-code
+
+# Create non-root user with home directory BEFORE installing Cursor CLI
+RUN groupadd -g 1001 automaker && \
+    useradd -u 1001 -g automaker -m -d /home/automaker -s /bin/bash automaker && \
+    mkdir -p /home/automaker/.local/bin && \
+    mkdir -p /home/automaker/.cursor && \
+    chown -R automaker:automaker /home/automaker && \
+    chmod 700 /home/automaker/.cursor
+
+# Install Cursor CLI as the automaker user
+# Set HOME explicitly and install to /home/automaker/.local/bin/
+USER automaker
+ENV HOME=/home/automaker
+RUN curl https://cursor.com/install -fsS | bash && \
+    echo "=== Checking Cursor CLI installation ===" && \
+    ls -la /home/automaker/.local/bin/ && \
+    echo "=== PATH is: $PATH ===" && \
+    (which cursor-agent && cursor-agent --version) || echo "cursor-agent installed (may need auth setup)"
+USER root
+
+# Add PATH to profile so it's available in all interactive shells (for login shells)
+RUN mkdir -p /etc/profile.d && \
+    echo 'export PATH="/home/automaker/.local/bin:$PATH"' > /etc/profile.d/cursor-cli.sh && \
+    chmod +x /etc/profile.d/cursor-cli.sh
+
+# Add to automaker's .bashrc for bash interactive shells
+RUN echo 'export PATH="/home/automaker/.local/bin:$PATH"' >> /home/automaker/.bashrc && \
+    chown automaker:automaker /home/automaker/.bashrc
+
+# Also add to root's .bashrc since docker exec defaults to root
+RUN echo 'export PATH="/home/automaker/.local/bin:$PATH"' >> /root/.bashrc
+
+WORKDIR /app
+
+# Copy root package.json (needed for workspace resolution)
+COPY --from=server-builder /app/package*.json ./
+
+# Copy built libs (workspace packages are symlinked in node_modules)
+COPY --from=server-builder /app/libs ./libs
+
+# Copy built server
+COPY --from=server-builder /app/apps/server/dist ./apps/server/dist
+COPY --from=server-builder /app/apps/server/package*.json ./apps/server/
+
+# Copy node_modules (includes symlinks to libs)
+COPY --from=server-builder /app/node_modules ./node_modules
+
+# Create data and projects directories
+RUN mkdir -p /data /projects && chown automaker:automaker /data /projects
+
+# Configure git for mounted volumes and authentication
+# Use --system so it's not overwritten by mounted user .gitconfig
+RUN git config --system --add safe.directory '*' && \
+    # Use gh as credential helper (works with GH_TOKEN env var)
+    git config --system credential.helper '!gh auth git-credential'
+
+# Copy entrypoint script for fixing permissions on mounted volumes
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Note: We stay as root here so entrypoint can fix permissions
+# The entrypoint script will switch to automaker user before running the command
+
+# Environment variables
+ENV PORT=3008
+ENV DATA_DIR=/data
+ENV HOME=/home/automaker
+# Add user's local bin to PATH for cursor-agent
+ENV PATH="/home/automaker/.local/bin:${PATH}"
+
+# Expose port
+EXPOSE 3008
+
+# Health check (using curl since it's already installed, more reliable than busybox wget)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:3008/api/health || exit 1
+
+# Use entrypoint to fix permissions before starting
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+
+# Start server
+CMD ["node", "apps/server/dist/index.js"]
+
+# =============================================================================
+# UI BUILD STAGE
+# =============================================================================
+FROM base AS ui-builder
+
+# Copy UI-specific package.json
+COPY apps/ui/package*.json ./apps/ui/
+
+# Install dependencies (--ignore-scripts to skip husky and build:packages in prepare script)
+RUN npm ci --ignore-scripts
+
+# Copy all source files
+COPY libs ./libs
+COPY apps/ui ./apps/ui
+
+# Build packages in dependency order, then build UI
+# VITE_SERVER_URL tells the UI where to find the API server
+# Use ARG to allow overriding at build time: --build-arg VITE_SERVER_URL=http://api.example.com
+ARG VITE_SERVER_URL=http://localhost:3008
+ENV VITE_SKIP_ELECTRON=true
+ENV VITE_SERVER_URL=${VITE_SERVER_URL}
+RUN npm run build:packages && npm run build --workspace=apps/ui
+
+# =============================================================================
+# UI PRODUCTION STAGE
+# =============================================================================
+FROM nginx:alpine AS ui
+
+# Build argument for tracking which commit this image was built from
+ARG GIT_COMMIT_SHA=unknown
+LABEL automaker.git.commit.sha="${GIT_COMMIT_SHA}"
+
+# Copy built files
+COPY --from=ui-builder /app/apps/ui/dist /usr/share/nginx/html
+
+# Copy nginx config for SPA routing
+COPY apps/ui/nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+
+CMD ["nginx", "-g", "daemon off;"]

Dockerfile.dev

@@ -0,0 +1,80 @@
+# Automaker Development Dockerfile
+# For development with live reload via volume mounting
+# Source code is NOT copied - it's mounted as a volume
+#
+# Usage:
+#   docker compose -f docker-compose.dev.yml up
+
+FROM node:22-slim
+
+# Install build dependencies for native modules (node-pty) and runtime tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 make g++ \
+    git curl bash gosu ca-certificates openssh-client \
+    && GH_VERSION="2.63.2" \
+    && ARCH=$(uname -m) \
+    && case "$ARCH" in \
+        x86_64) GH_ARCH="amd64" ;; \
+        aarch64|arm64) GH_ARCH="arm64" ;; \
+        *) echo "Unsupported architecture: $ARCH" && exit 1 ;; \
+    esac \
+    && curl -L "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_${GH_ARCH}.tar.gz" -o gh.tar.gz \
+    && tar -xzf gh.tar.gz \
+    && mv gh_${GH_VERSION}_linux_${GH_ARCH}/bin/gh /usr/local/bin/gh \
+    && rm -rf gh.tar.gz gh_${GH_VERSION}_linux_${GH_ARCH} \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Claude CLI globally
+RUN npm install -g @anthropic-ai/claude-code
+
+# Create non-root user
+RUN groupadd -g 1001 automaker && \
+    useradd -u 1001 -g automaker -m -d /home/automaker -s /bin/bash automaker && \
+    mkdir -p /home/automaker/.local/bin && \
+    mkdir -p /home/automaker/.cursor && \
+    chown -R automaker:automaker /home/automaker && \
+    chmod 700 /home/automaker/.cursor
+
+# Install Cursor CLI as automaker user
+USER automaker
+ENV HOME=/home/automaker
+RUN curl https://cursor.com/install -fsS | bash || true
+USER root
+
+# Add PATH to profile for Cursor CLI
+RUN mkdir -p /etc/profile.d && \
+    echo 'export PATH="/home/automaker/.local/bin:$PATH"' > /etc/profile.d/cursor-cli.sh && \
+    chmod +x /etc/profile.d/cursor-cli.sh
+
+# Add to user bashrc files
+RUN echo 'export PATH="/home/automaker/.local/bin:$PATH"' >> /home/automaker/.bashrc && \
+    chown automaker:automaker /home/automaker/.bashrc
+RUN echo 'export PATH="/home/automaker/.local/bin:$PATH"' >> /root/.bashrc
+
+WORKDIR /app
+
+# Create directories with proper permissions
+RUN mkdir -p /data /projects && chown automaker:automaker /data /projects
+
+# Configure git for mounted volumes
+RUN git config --system --add safe.directory '*' && \
+    git config --system credential.helper '!gh auth git-credential'
+
+# Copy entrypoint script
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# Environment variables
+ENV PORT=3008
+ENV DATA_DIR=/data
+ENV HOME=/home/automaker
+ENV PATH="/home/automaker/.local/bin:${PATH}"
+
+# Expose both dev ports
+EXPOSE 3007 3008
+
+# Use entrypoint for permission handling
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+
+# Default command - will be overridden by docker-compose
+CMD ["npm", "run", "dev:web"]

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="apps/ui/public/readme_logo.png" alt="Automaker Logo" height="80" />
+  <img src="apps/ui/public/readme_logo.svg" alt="Automaker Logo" height="80" />
 </p>
 
 > **[!TIP]**
@@ -19,7 +19,7 @@
 
 - [What Makes Automaker Different?](#what-makes-automaker-different)
   - [The Workflow](#the-workflow)
-  - [Powered by Claude Code](#powered-by-claude-code)
+  - [Powered by Claude Agent SDK](#powered-by-claude-agent-sdk)
   - [Why This Matters](#why-this-matters)
 - [Security Disclaimer](#security-disclaimer)
 - [Community & Support](#community--support)
@@ -28,22 +28,36 @@
   - [Quick Start](#quick-start)
 - [How to Run](#how-to-run)
   - [Development Mode](#development-mode)
-    - [Electron Desktop App (Recommended)](#electron-desktop-app-recommended)
-    - [Web Browser Mode](#web-browser-mode)
   - [Building for Production](#building-for-production)
-  - [Running Production Build](#running-production-build)
   - [Testing](#testing)
   - [Linting](#linting)
-  - [Authentication Options](#authentication-options)
-  - [Persistent Setup (Optional)](#persistent-setup-optional)
+  - [Environment Configuration](#environment-configuration)
+  - [Authentication Setup](#authentication-setup)
 - [Features](#features)
+  - [Core Workflow](#core-workflow)
+  - [AI & Planning](#ai--planning)
+  - [Project Management](#project-management)
+  - [Collaboration & Review](#collaboration--review)
+  - [Developer Tools](#developer-tools)
+  - [Advanced Features](#advanced-features)
 - [Tech Stack](#tech-stack)
+  - [Frontend](#frontend)
+  - [Backend](#backend)
+  - [Testing & Quality](#testing--quality)
+  - [Shared Libraries](#shared-libraries)
+- [Available Views](#available-views)
+- [Architecture](#architecture)
+  - [Monorepo Structure](#monorepo-structure)
+  - [How It Works](#how-it-works)
+  - [Key Architectural Patterns](#key-architectural-patterns)
+  - [Security & Isolation](#security--isolation)
+  - [Data Storage](#data-storage)
 - [Learn More](#learn-more)
 - [License](#license)
 
 </details>
 
-Automaker is an autonomous AI development studio that transforms how you build software. Instead of manually writing every line of code, you describe features on a Kanban board and watch as AI agents powered by Claude Code automatically implement them.
+Automaker is an autonomous AI development studio that transforms how you build software. Instead of manually writing every line of code, you describe features on a Kanban board and watch as AI agents powered by Claude Agent SDK automatically implement them. Built with React, Vite, Electron, and Express, Automaker provides a complete workflow for managing AI agents through a desktop application (or web browser), with features like real-time streaming, git worktree isolation, plan approval, and multi-agent task execution.
 
 ![Automaker UI](https://i.imgur.com/jdwKydM.png)
 
@@ -59,30 +73,14 @@ Traditional development tools help you write code. Automaker helps you **orchest
 4. **Review & Verify** - Review the changes, run tests, and approve when ready
 5. **Ship Faster** - Build entire applications in days, not weeks
 
-### Powered by Claude Code
+### Powered by Claude Agent SDK
 
-Automaker leverages the [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code) to give AI agents full access to your codebase. Agents can read files, write code, execute commands, run tests, and make git commits—all while working in isolated git worktrees to keep your main branch safe.
+Automaker leverages the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) to give AI agents full access to your codebase. Agents can read files, write code, execute commands, run tests, and make git commits—all while working in isolated git worktrees to keep your main branch safe. The SDK provides autonomous AI agents that can use tools, make decisions, and complete complex multi-step tasks without constant human intervention.
 
 ### Why This Matters
 
 The future of software development is **agentic coding**—where developers become architects directing AI agents rather than manual coders. Automaker puts this future in your hands today, letting you experience what it's like to build software 10x faster with AI agents handling the implementation while you focus on architecture and business logic.
 
----
-
-> **[!CAUTION]**
->
-> ## Security Disclaimer
->
-> **This software uses AI-powered tooling that has access to your operating system and can read, modify, and delete files. Use at your own risk.**
->
-> We have reviewed this codebase for security vulnerabilities, but you assume all risk when running this software. You should review the code yourself before running it.
->
-> **We do not recommend running Automaker directly on your local computer** due to the risk of AI agents having access to your entire file system. Please sandbox this application using Docker or a virtual machine.
->
-> **[Read the full disclaimer](./DISCLAIMER.md)**
-
----
-
 ## Community & Support
 
 Join the **Agentic Jumpstart** to connect with other builders exploring **agentic coding** and autonomous development workflows.
@@ -95,8 +93,7 @@ In the Discord, you can:
 - 🚀 Show off projects built with AI agents
 - 🤝 Collaborate with other developers and contributors
 
-👉 **Join the Discord:**  
-https://discord.gg/jjem7aEDKU
+👉 **Join the Discord:** [Agentic Jumpstart Discord](https://discord.gg/jjem7aEDKU)
 
 ---
 
@@ -104,28 +101,49 @@ https://discord.gg/jjem7aEDKU
 
 ### Prerequisites
 
-- Node.js 18+
-- npm
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- **Node.js 18+** (tested with Node.js 22)
+- **npm** (comes with Node.js)
+- **Authentication** (choose one):
+  - **[Claude Code CLI](https://code.claude.com/docs/en/overview)** (recommended) - Install and authenticate, credentials used automatically
+  - **Anthropic API Key** - Direct API key for Claude Agent SDK ([get one here](https://console.anthropic.com/))
 
 ### Quick Start
 
 ```bash
-# 1. Clone the repo
+# 1. Clone the repository
 git clone https://github.com/AutoMaker-Org/automaker.git
 cd automaker
 
 # 2. Install dependencies
 npm install
 
-# 3. Build local shared packages
+# 3. Build shared packages (can be skipped - npm run dev does it automatically)
 npm run build:packages
 
-# 4. Run Automaker (pick your mode)
+# 4. Start Automaker
 npm run dev
-# Then choose your run mode when prompted, or use specific commands below
+# Choose between:
+#   1. Web Application (browser at localhost:3007)
+#   2. Desktop Application (Electron - recommended)
 ```
 
+**Authentication Setup:** On first run, Automaker will automatically show a setup wizard where you can configure authentication. You can choose to:
+
+- Use **Claude Code CLI** (recommended) - Automaker will detect your CLI credentials automatically
+- Enter an **API key** directly in the wizard
+
+If you prefer to set up authentication before running (e.g., for headless deployments or CI/CD), you can set it manually:
+
+```bash
+# Option A: Environment variable
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Option B: Create .env file in project root
+echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
+```
+
+**For Development:** `npm run dev` starts the development server with Vite live reload and hot module replacement for fast refresh and instant updates as you make changes.
+
 ## How to Run
 
 ### Development Mode
@@ -163,31 +181,159 @@ npm run dev:web
 
 ### Building for Production
 
+#### Web Application
+
 ```bash
-# Build Next.js app
+# Build for web deployment (uses Vite)
 npm run build
-
-# Build Electron app for distribution
-npm run build:electron
 ```
 
-### Running Production Build
+#### Desktop Application
 
 ```bash
-# Start production Next.js server
-npm run start
+# Build for current platform (macOS/Windows/Linux)
+npm run build:electron
+
+# Platform-specific builds
+npm run build:electron:mac     # macOS (DMG + ZIP, x64 + arm64)
+npm run build:electron:win     # Windows (NSIS installer, x64)
+npm run build:electron:linux   # Linux (AppImage + DEB, x64)
+
+# Output directory: apps/ui/release/
 ```
 
+#### Docker Deployment
+
+Docker provides the most secure way to run Automaker by isolating it from your host filesystem.
+
+```bash
+# Build and run with Docker Compose
+docker-compose up -d
+
+# Access UI at http://localhost:3007
+# API at http://localhost:3008
+
+# View logs
+docker-compose logs -f
+
+# Stop containers
+docker-compose down
+```
+
+##### Configuration
+
+Create a `.env` file in the project root if using API key authentication:
+
+```bash
+# Optional: Anthropic API key (not needed if using Claude CLI authentication)
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Note:** Most users authenticate via Claude CLI instead of API keys. See [Claude CLI Authentication](#claude-cli-authentication-optional) below.
+
+##### Working with Projects (Host Directory Access)
+
+By default, the container is isolated from your host filesystem. To work on projects from your host machine, create a `docker-compose.override.yml` file (gitignored):
+
+```yaml
+services:
+  server:
+    volumes:
+      # Mount your project directories
+      - /path/to/your/project:/projects/your-project
+```
+
+##### Claude CLI Authentication (Optional)
+
+To use Claude Code CLI authentication instead of an API key, mount your Claude CLI config directory:
+
+```yaml
+services:
+  server:
+    volumes:
+      # Linux/macOS
+      - ~/.claude:/home/automaker/.claude
+      # Windows
+      - C:/Users/YourName/.claude:/home/automaker/.claude
+```
+
+**Note:** The Claude CLI config must be writable (do not use `:ro` flag) as the CLI writes debug files.
+
+##### GitHub CLI Authentication (For Git Push/PR Operations)
+
+To enable git push and GitHub CLI operations inside the container:
+
+```yaml
+services:
+  server:
+    volumes:
+      # Mount GitHub CLI config
+      # Linux/macOS
+      - ~/.config/gh:/home/automaker/.config/gh
+      # Windows
+      - 'C:/Users/YourName/AppData/Roaming/GitHub CLI:/home/automaker/.config/gh'
+
+      # Mount git config for user identity (name, email)
+      - ~/.gitconfig:/home/automaker/.gitconfig:ro
+    environment:
+      # GitHub token (required on Windows where tokens are in Credential Manager)
+      # Get your token with: gh auth token
+      - GH_TOKEN=${GH_TOKEN}
+```
+
+Then add `GH_TOKEN` to your `.env` file:
+
+```bash
+GH_TOKEN=gho_your_github_token_here
+```
+
+##### Complete docker-compose.override.yml Example
+
+```yaml
+services:
+  server:
+    volumes:
+      # Your projects
+      - /path/to/project1:/projects/project1
+      - /path/to/project2:/projects/project2
+
+      # Authentication configs
+      - ~/.claude:/home/automaker/.claude
+      - ~/.config/gh:/home/automaker/.config/gh
+      - ~/.gitconfig:/home/automaker/.gitconfig:ro
+    environment:
+      - GH_TOKEN=${GH_TOKEN}
+```
+
+##### Architecture Support
+
+The Docker image supports both AMD64 and ARM64 architectures. The GitHub CLI and Claude CLI are automatically downloaded for the correct architecture during build.
+
 ### Testing
 
-```bash
-# Run tests headless
-npm run test
+#### End-to-End Tests (Playwright)
 
-# Run tests with browser visible
-npm run test:headed
+```bash
+npm run test            # Headless E2E tests
+npm run test:headed     # Browser visible E2E tests
 ```
 
+#### Unit Tests (Vitest)
+
+```bash
+npm run test:server              # Server unit tests
+npm run test:server:coverage     # Server tests with coverage
+npm run test:packages            # All shared package tests
+npm run test:all                 # Packages + server tests
+```
+
+#### Test Configuration
+
+- E2E tests run on ports 3007 (UI) and 3008 (server)
+- Automatically starts test servers before running
+- Uses Chromium browser via Playwright
+- Mock agent mode available in CI with `AUTOMAKER_MOCK_AGENT=true`
+
 ### Linting
 
 ```bash
@@ -195,59 +341,300 @@ npm run test:headed
 npm run lint
 ```
 
-### Authentication Options
+### Environment Configuration
 
-Automaker supports multiple authentication methods (in order of priority):
+#### Authentication (if not using Claude Code CLI)
 
-| Method           | Environment Variable | Description                     |
-| ---------------- | -------------------- | ------------------------------- |
-| API Key (env)    | `ANTHROPIC_API_KEY`  | Anthropic API key               |
-| API Key (stored) | —                    | Anthropic API key stored in app |
+- `ANTHROPIC_API_KEY` - Your Anthropic API key for Claude Agent SDK (not needed if using Claude Code CLI)
 
-### Persistent Setup (Optional)
+#### Optional - Server
+
+- `PORT` - Server port (default: 3008)
+- `DATA_DIR` - Data storage directory (default: ./data)
+- `ENABLE_REQUEST_LOGGING` - HTTP request logging (default: true)
+
+#### Optional - Security
+
+- `AUTOMAKER_API_KEY` - Optional API authentication for the server
+- `ALLOWED_ROOT_DIRECTORY` - Restrict file operations to specific directory
+- `CORS_ORIGIN` - CORS policy (default: \*)
+
+#### Optional - Development
+
+- `VITE_SKIP_ELECTRON` - Skip Electron in dev mode
+- `OPEN_DEVTOOLS` - Auto-open DevTools in Electron
+
+### Authentication Setup
+
+#### Option 1: Claude Code CLI (Recommended)
+
+Install and authenticate the Claude Code CLI following the [official quickstart guide](https://code.claude.com/docs/en/quickstart).
+
+Once authenticated, Automaker will automatically detect and use your CLI credentials. No additional configuration needed!
+
+#### Option 2: Direct API Key
+
+If you prefer not to use the CLI, you can provide an Anthropic API key directly using one of these methods:
+
+##### 2a. Shell Configuration
 
 Add to your `~/.bashrc` or `~/.zshrc`:
 
 ```bash
-export ANTHROPIC_API_KEY="YOUR_API_KEY_HERE"
+export ANTHROPIC_API_KEY="sk-ant-..."
 ```
 
-Then restart your terminal or run `source ~/.bashrc`.
+Then restart your terminal or run `source ~/.bashrc` (or `source ~/.zshrc`).
+
+##### 2b. .env File
+
+Create a `.env` file in the project root (gitignored):
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+PORT=3008
+DATA_DIR=./data
+```
+
+##### 2c. In-App Storage
+
+The application can store your API key securely in the settings UI. The key is persisted in the `DATA_DIR` directory.
 
 ## Features
 
+### Core Workflow
+
 - 📋 **Kanban Board** - Visual drag-and-drop board to manage features through backlog, in progress, waiting approval, and verified stages
 - 🤖 **AI Agent Integration** - Automatic AI agent assignment to implement features when moved to "In Progress"
-- 🧠 **Multi-Model Support** - Choose from multiple AI models including Claude Opus, Sonnet, and more
-- 💭 **Extended Thinking** - Enable extended thinking modes for complex problem-solving
-- 📡 **Real-time Agent Output** - View live agent output, logs, and file diffs as features are being implemented
-- 🔍 **Project Analysis** - AI-powered project structure analysis to understand your codebase
-- 📁 **Context Management** - Add context files to help AI agents understand your project better
-- 💡 **Feature Suggestions** - AI-generated feature suggestions based on your project
-- 🖼️ **Image Support** - Attach images and screenshots to feature descriptions
-- ⚡ **Concurrent Processing** - Configure concurrency to process multiple features simultaneously
-- 🧪 **Test Integration** - Automatic test running and verification for implemented features
-- 🔀 **Git Integration** - View git diffs and track changes made by AI agents
-- 👤 **AI Profiles** - Create and manage different AI agent profiles for various tasks
-- 💬 **Chat History** - Keep track of conversations and interactions with AI agents
-- ⌨️ **Keyboard Shortcuts** - Efficient navigation and actions via keyboard shortcuts
-- 🎨 **Dark/Light Theme** - Beautiful UI with theme support
-- 🖥️ **Cross-Platform** - Desktop application built with Electron for Windows, macOS, and Linux
+- 🔀 **Git Worktree Isolation** - Each feature executes in isolated git worktrees to protect your main branch
+- 📡 **Real-time Streaming** - Watch AI agents work in real-time with live tool usage, progress updates, and task completion
+- 🔄 **Follow-up Instructions** - Send additional instructions to running agents without stopping them
+
+### AI & Planning
+
+- 🧠 **Multi-Model Support** - Choose from Claude Opus, Sonnet, and Haiku per feature
+- 💭 **Extended Thinking** - Enable thinking modes (none, medium, deep, ultra) for complex problem-solving
+- 📝 **Planning Modes** - Four planning levels: skip (direct implementation), lite (quick plan), spec (task breakdown), full (phased execution)
+- ✅ **Plan Approval** - Review and approve AI-generated plans before implementation begins
+- 📊 **Multi-Agent Task Execution** - Spec mode spawns dedicated agents per task for focused implementation
+
+### Project Management
+
+- 🔍 **Project Analysis** - AI-powered codebase analysis to understand your project structure
+- 💡 **Feature Suggestions** - AI-generated feature suggestions based on project analysis
+- 📁 **Context Management** - Add markdown, images, and documentation files that agents automatically reference
+- 🔗 **Dependency Blocking** - Features can depend on other features, enforcing execution order
+- 🌳 **Graph View** - Visualize feature dependencies with interactive graph visualization
+- 📋 **GitHub Integration** - Import issues, validate feasibility, and convert to tasks automatically
+
+### Collaboration & Review
+
+- 🧪 **Verification Workflow** - Features move to "Waiting Approval" for review and testing
+- 💬 **Agent Chat** - Interactive chat sessions with AI agents for exploratory work
+- 👤 **AI Profiles** - Create custom agent configurations with different prompts, models, and settings
+- 📜 **Session History** - Persistent chat sessions across restarts with full conversation history
+- 🔍 **Git Diff Viewer** - Review changes made by agents before approving
+
+### Developer Tools
+
+- 🖥️ **Integrated Terminal** - Full terminal access with tabs, splits, and persistent sessions
+- 🖼️ **Image Support** - Attach screenshots and diagrams to feature descriptions for visual context
+- ⚡ **Concurrent Execution** - Configure how many features can run simultaneously (default: 3)
+- ⌨️ **Keyboard Shortcuts** - Fully customizable shortcuts for navigation and actions
+- 🎨 **Theme System** - 25+ themes including Dark, Light, Dracula, Nord, Catppuccin, and more
+- 🖥️ **Cross-Platform** - Desktop app for macOS (x64, arm64), Windows (x64), and Linux (x64)
+- 🌐 **Web Mode** - Run in browser or as Electron desktop app
+
+### Advanced Features
+
+- 🔐 **Docker Isolation** - Security-focused Docker deployment with no host filesystem access
+- 🎯 **Worktree Management** - Create, switch, commit, and create PRs from worktrees
+- 📊 **Usage Tracking** - Monitor Claude API usage with detailed metrics
+- 🔊 **Audio Notifications** - Optional completion sounds (mutable in settings)
+- 💾 **Auto-save** - All work automatically persisted to `.automaker/` directory
 
 ## Tech Stack
 
-- [Next.js](https://nextjs.org) - React framework
-- [Electron](https://www.electronjs.org/) - Desktop application framework
-- [Tailwind CSS](https://tailwindcss.com/) - Styling
-- [Zustand](https://zustand-demo.pmnd.rs/) - State management
-- [dnd-kit](https://dndkit.com/) - Drag and drop functionality
+### Frontend
+
+- **React 19** - UI framework
+- **Vite 7** - Build tool and development server
+- **Electron 39** - Desktop application framework
+- **TypeScript 5.9** - Type safety
+- **TanStack Router** - File-based routing
+- **Zustand 5** - State management with persistence
+- **Tailwind CSS 4** - Utility-first styling with 25+ themes
+- **Radix UI** - Accessible component primitives
+- **dnd-kit** - Drag and drop for Kanban board
+- **@xyflow/react** - Graph visualization for dependencies
+- **xterm.js** - Integrated terminal emulator
+- **CodeMirror 6** - Code editor for XML/syntax highlighting
+- **Lucide Icons** - Icon library
+
+### Backend
+
+- **Node.js** - JavaScript runtime with ES modules
+- **Express 5** - HTTP server framework
+- **TypeScript 5.9** - Type safety
+- **Claude Agent SDK** - AI agent integration (@anthropic-ai/claude-agent-sdk)
+- **WebSocket (ws)** - Real-time event streaming
+- **node-pty** - PTY terminal sessions
+
+### Testing & Quality
+
+- **Playwright** - End-to-end testing
+- **Vitest** - Unit testing framework
+- **ESLint 9** - Code linting
+- **Prettier 3** - Code formatting
+- **Husky** - Git hooks for pre-commit formatting
+
+### Shared Libraries
+
+- **@automaker/types** - Shared TypeScript definitions
+- **@automaker/utils** - Logging, error handling, image processing
+- **@automaker/prompts** - AI prompt templates
+- **@automaker/platform** - Path management and security
+- **@automaker/model-resolver** - Claude model alias resolution
+- **@automaker/dependency-resolver** - Feature dependency ordering
+- **@automaker/git-utils** - Git operations and worktree management
+
+## Available Views
+
+Automaker provides several specialized views accessible via the sidebar or keyboard shortcuts:
+
+| View               | Shortcut | Description                                                                                      |
+| ------------------ | -------- | ------------------------------------------------------------------------------------------------ |
+| **Board**          | `K`      | Kanban board for managing feature workflow (Backlog → In Progress → Waiting Approval → Verified) |
+| **Agent**          | `A`      | Interactive chat sessions with AI agents for exploratory work and questions                      |
+| **Spec**           | `D`      | Project specification editor with AI-powered generation and feature suggestions                  |
+| **Context**        | `C`      | Manage context files (markdown, images) that AI agents automatically reference                   |
+| **Profiles**       | `M`      | Create and manage AI agent profiles with custom prompts and configurations                       |
+| **Settings**       | `S`      | Configure themes, shortcuts, defaults, authentication, and more                                  |
+| **Terminal**       | `T`      | Integrated terminal with tabs, splits, and persistent sessions                                   |
+| **GitHub Issues**  | -        | Import and validate GitHub issues, convert to tasks                                              |
+| **Running Agents** | -        | View all active agents across projects with status and progress                                  |
+
+### Keyboard Navigation
+
+All shortcuts are customizable in Settings. Default shortcuts:
+
+- **Navigation:** `K` (Board), `A` (Agent), `D` (Spec), `C` (Context), `S` (Settings), `M` (Profiles), `T` (Terminal)
+- **UI:** `` ` `` (Toggle sidebar)
+- **Actions:** `N` (New item in current view), `G` (Start next features), `O` (Open project), `P` (Project picker)
+- **Projects:** `Q`/`E` (Cycle previous/next project)
+
+## Architecture
+
+### Monorepo Structure
+
+Automaker is built as an npm workspace monorepo with two main applications and seven shared packages:
+
+```text
+automaker/
+├── apps/
+│   ├── ui/          # React + Vite + Electron frontend
+│   └── server/      # Express + WebSocket backend
+└── libs/            # Shared packages
+    ├── types/                  # Core TypeScript definitions
+    ├── utils/                  # Logging, errors, utilities
+    ├── prompts/                # AI prompt templates
+    ├── platform/               # Path management, security
+    ├── model-resolver/         # Claude model aliasing
+    ├── dependency-resolver/    # Feature dependency ordering
+    └── git-utils/              # Git operations & worktree management
+```
+
+### How It Works
+
+1. **Feature Definition** - Users create feature cards on the Kanban board with descriptions, images, and configuration
+2. **Git Worktree Creation** - When a feature starts, a git worktree is created for isolated development
+3. **Agent Execution** - Claude Agent SDK executes in the worktree with full file system and command access
+4. **Real-time Streaming** - Agent output streams via WebSocket to the frontend for live monitoring
+5. **Plan Approval** (optional) - For spec/full planning modes, agents generate plans that require user approval
+6. **Multi-Agent Tasks** (spec mode) - Each task in the spec gets a dedicated agent for focused implementation
+7. **Verification** - Features move to "Waiting Approval" where changes can be reviewed via git diff
+8. **Integration** - After approval, changes can be committed and PRs created from the worktree
+
+### Key Architectural Patterns
+
+- **Event-Driven Architecture** - All server operations emit events that stream to the frontend
+- **Provider Pattern** - Extensible AI provider system (currently Claude, designed for future providers)
+- **Service-Oriented Backend** - Modular services for agent management, features, terminals, settings
+- **State Management** - Zustand with persistence for frontend state across restarts
+- **File-Based Storage** - No database; features stored as JSON files in `.automaker/` directory
+
+### Security & Isolation
+
+- **Git Worktrees** - Each feature executes in an isolated git worktree, protecting your main branch
+- **Path Sandboxing** - Optional `ALLOWED_ROOT_DIRECTORY` restricts file access
+- **Docker Isolation** - Recommended deployment uses Docker with no host filesystem access
+- **Plan Approval** - Optional plan review before implementation prevents unwanted changes
+
+### Data Storage
+
+Automaker uses a file-based storage system (no database required):
+
+#### Per-Project Data
+
+Stored in `{projectPath}/.automaker/`:
+
+```text
+.automaker/
+├── features/              # Feature JSON files and images
+│   └── {featureId}/
+│       ├── feature.json   # Feature metadata
+│       ├── agent-output.md # AI agent output log
+│       └── images/        # Attached images
+├── context/               # Context files for AI agents
+├── settings.json          # Project-specific settings
+├── spec.md               # Project specification
+├── analysis.json         # Project structure analysis
+└── feature-suggestions.json # AI-generated suggestions
+```
+
+#### Global Data
+
+Stored in `DATA_DIR` (default `./data`):
+
+```text
+data/
+├── settings.json          # Global settings, profiles, shortcuts
+├── credentials.json       # API keys (encrypted)
+├── sessions-metadata.json # Chat session metadata
+└── agent-sessions/        # Conversation histories
+    └── {sessionId}.json
+```
+
+---
+
+> **[!CAUTION]**
+>
+> ## Security Disclaimer
+>
+> **This software uses AI-powered tooling that has access to your operating system and can read, modify, and delete files. Use at your own risk.**
+>
+> We have reviewed this codebase for security vulnerabilities, but you assume all risk when running this software. You should review the code yourself before running it.
+>
+> **We do not recommend running Automaker directly on your local computer** due to the risk of AI agents having access to your entire file system. Please sandbox this application using Docker or a virtual machine.
+>
+> **[Read the full disclaimer](./DISCLAIMER.md)**
+
+---
 
 ## Learn More
 
-To learn more about Next.js, take a look at the following resources:
+### Documentation
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- [Contributing Guide](./CONTRIBUTING.md) - How to contribute to Automaker
+- [Project Documentation](./docs/) - Architecture guides, patterns, and developer docs
+- [Docker Isolation Guide](./docs/docker-isolation.md) - Security-focused Docker deployment
+- [Shared Packages Guide](./docs/llm-shared-packages.md) - Using monorepo packages
+
+### Community
+
+Join the **Agentic Jumpstart** Discord to connect with other builders exploring **agentic coding**:
+
+👉 [Agentic Jumpstart Discord](https://discord.gg/jjem7aEDKU)
 
 ## License
 

TODO.md

@@ -0,0 +1,17 @@
+# Bugs
+
+- Setting the default model does not seem like it works.
+
+# UX
+
+- Consolidate all models to a single place in the settings instead of having AI profiles and all this other stuff
+- Simplify the create feature modal. It should just be one page. I don't need nessa tabs and all these nested buttons. It's too complex.
+- added to do's list checkbox directly into the card so as it's going through if there's any to do items we can see those update live
+- When the feature is done, I want to see a summary of the LLM. That's the first thing I should see when I double click the card.
+- I went away to mass edit all my features. For example, when I created a new project, it added auto testing on every single feature card. Now I have to manually go through one by one and change those. Have a way to mass edit those, the configuration of all them.
+- Double check and debug if there's memory leaks. It seems like the memory of automaker grows like 3 gigabytes. It's 5gb right now and I'm running three different cursor cli features implementing at the same time.
+- Typing in the text area of the plan mode was super laggy.
+- When I have a bunch of features running at the same time, it seems like I cannot edit the features in the backlog. Like they don't persist their file changes and I think this is because of the secure FS file has an internal queue to prevent hitting that file open write limit. We may have to reconsider refactoring away from file system and do Postgres or SQLite or something.
+- modals are not scrollable if height of the screen is small enough
+- and the Agent Runner add an archival button for the new sessions.
+- investigate a potential issue with the feature cards not refreshing. I see a lock icon on the feature card But it doesn't go away until I open the card and edit it and I turn the testing mode off. I think there's like a refresh sync issue.

apps/app/server-bundle/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@automaker/server-bundle",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "dist/index.js",
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.61",
-    "cors": "^2.8.5",
-    "dotenv": "^17.2.3",
-    "express": "^5.1.0",
-    "morgan": "^1.10.1",
-    "node-pty": "1.1.0-beta41",
-    "ws": "^8.18.0"
-  }
-}

apps/server/.env.example

@@ -8,6 +8,20 @@
 # Your Anthropic API key for Claude models
 ANTHROPIC_API_KEY=sk-ant-...
 
+# ============================================
+# OPTIONAL - Additional API Keys
+# ============================================
+
+# OpenAI API key for Codex/GPT models
+OPENAI_API_KEY=sk-...
+
+# Cursor API key for Cursor models
+CURSOR_API_KEY=...
+
+# OAuth credentials for CLI authentication (extracted automatically)
+CLAUDE_OAUTH_CREDENTIALS=
+CURSOR_AUTH_TOKEN=
+
 # ============================================
 # OPTIONAL - Security
 # ============================================
@@ -24,7 +38,7 @@ ALLOWED_ROOT_DIRECTORY=
 
 # CORS origin - which domains can access the API
 # Use "*" for development, set specific origin for production
-CORS_ORIGIN=*
+CORS_ORIGIN=http://localhost:3007
 
 # ============================================
 # OPTIONAL - Server
@@ -48,3 +62,15 @@ TERMINAL_ENABLED=true
 TERMINAL_PASSWORD=
 
 ENABLE_REQUEST_LOGGING=false
+
+# ============================================
+# OPTIONAL - Debugging
+# ============================================
+
+# Enable raw output logging for agent streams (default: false)
+# When enabled, saves unprocessed stream events to raw-output.jsonl
+# in each feature's directory (.automaker/features/{id}/raw-output.jsonl)
+# Useful for debugging provider streaming issues, improving log parsing,
+# or analyzing how different providers (Claude, Cursor) stream responses
+# Note: This adds disk I/O overhead, only enable when debugging
+AUTOMAKER_DEBUG_RAW_OUTPUT=false

apps/server/Dockerfile

@@ -1,67 +0,0 @@
-# Automaker Backend Server
-# Multi-stage build for minimal production image
-
-# Build stage
-FROM node:20-alpine AS builder
-
-# Install build dependencies for native modules (node-pty)
-RUN apk add --no-cache python3 make g++
-
-WORKDIR /app
-
-# Copy package files and scripts needed for postinstall
-COPY package*.json ./
-COPY apps/server/package*.json ./apps/server/
-COPY scripts ./scripts
-
-# Install dependencies
-RUN npm ci --workspace=apps/server
-
-# Copy source
-COPY apps/server ./apps/server
-
-# Build TypeScript
-RUN npm run build --workspace=apps/server
-
-# Production stage
-FROM node:20-alpine
-
-# Install git, curl, and GitHub CLI (pinned version for reproducible builds)
-RUN apk add --no-cache git curl && \
-    GH_VERSION="2.63.2" && \
-    curl -L "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_amd64.tar.gz" -o gh.tar.gz && \
-    tar -xzf gh.tar.gz && \
-    mv "gh_${GH_VERSION}_linux_amd64/bin/gh" /usr/local/bin/gh && \
-    rm -rf gh.tar.gz "gh_${GH_VERSION}_linux_amd64"
-
-WORKDIR /app
-
-# Create non-root user
-RUN addgroup -g 1001 -S automaker && \
-    adduser -S automaker -u 1001
-
-# Copy built files and production dependencies
-COPY --from=builder /app/apps/server/dist ./dist
-COPY --from=builder /app/apps/server/package*.json ./
-COPY --from=builder /app/node_modules ./node_modules
-
-# Create data directory
-RUN mkdir -p /data && chown automaker:automaker /data
-
-# Switch to non-root user
-USER automaker
-
-# Environment variables
-ENV NODE_ENV=production
-ENV PORT=3008
-ENV DATA_DIR=/data
-
-# Expose port
-EXPOSE 3008
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-    CMD wget --no-verbose --tries=1 --spider http://localhost:3008/api/health || exit 1
-
-# Start server
-CMD ["node", "dist/index.js"]

apps/server/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@automaker/server",
-  "version": "0.1.0",
+  "version": "0.9.0",
   "description": "Backend server for Automaker - provides API for both web and Electron modes",
   "author": "AutoMaker Team",
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
+  "engines": {
+    "node": ">=22.0.0 <23.0.0"
+  },
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
     "dev": "tsx watch src/index.ts",
+    "dev:test": "tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
     "lint": "eslint src/",
@@ -20,31 +24,36 @@
     "test:unit": "vitest run tests/unit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.1.72",
-    "@automaker/dependency-resolver": "^1.0.0",
-    "@automaker/git-utils": "^1.0.0",
-    "@automaker/model-resolver": "^1.0.0",
-    "@automaker/platform": "^1.0.0",
-    "@automaker/prompts": "^1.0.0",
-    "@automaker/types": "^1.0.0",
-    "@automaker/utils": "^1.0.0",
-    "cors": "^2.8.5",
-    "dotenv": "^17.2.3",
-    "express": "^5.2.1",
-    "morgan": "^1.10.1",
+    "@anthropic-ai/claude-agent-sdk": "0.1.76",
+    "@automaker/dependency-resolver": "1.0.0",
+    "@automaker/git-utils": "1.0.0",
+    "@automaker/model-resolver": "1.0.0",
+    "@automaker/platform": "1.0.0",
+    "@automaker/prompts": "1.0.0",
+    "@automaker/types": "1.0.0",
+    "@automaker/utils": "1.0.0",
+    "@modelcontextprotocol/sdk": "1.25.2",
+    "@openai/codex-sdk": "^0.77.0",
+    "cookie-parser": "1.4.7",
+    "cors": "2.8.5",
+    "dotenv": "17.2.3",
+    "express": "5.2.1",
+    "morgan": "1.10.1",
     "node-pty": "1.1.0-beta41",
-    "ws": "^8.18.3"
+    "ws": "8.18.3"
   },
   "devDependencies": {
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/morgan": "^1.9.10",
-    "@types/node": "^22",
-    "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vitest/ui": "^4.0.16",
-    "tsx": "^4.21.0",
-    "typescript": "^5",
-    "vitest": "^4.0.16"
+    "@types/cookie": "0.6.0",
+    "@types/cookie-parser": "1.4.10",
+    "@types/cors": "2.8.19",
+    "@types/express": "5.0.6",
+    "@types/morgan": "1.9.10",
+    "@types/node": "22.19.3",
+    "@types/ws": "8.18.1",
+    "@vitest/coverage-v8": "4.0.16",
+    "@vitest/ui": "4.0.16",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.16"
   }
 }

apps/server/src/index.ts

@@ -9,15 +9,22 @@
 import express from 'express';
 import cors from 'cors';
 import morgan from 'morgan';
+import cookieParser from 'cookie-parser';
+import cookie from 'cookie';
 import { WebSocketServer, WebSocket } from 'ws';
 import { createServer } from 'http';
 import dotenv from 'dotenv';
 
 import { createEventEmitter, type EventEmitter } from './lib/events.js';
 import { initAllowedPaths } from '@automaker/platform';
-import { authMiddleware, getAuthStatus } from './lib/auth.js';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('Server');
+import { authMiddleware, validateWsConnectionToken, checkRawAuthentication } from './lib/auth.js';
+import { requireJsonContentType } from './middleware/require-json-content-type.js';
+import { createAuthRoutes } from './routes/auth/index.js';
 import { createFsRoutes } from './routes/fs/index.js';
-import { createHealthRoutes } from './routes/health/index.js';
+import { createHealthRoutes, createDetailedHandler } from './routes/health/index.js';
 import { createAgentRoutes } from './routes/agent/index.js';
 import { createSessionsRoutes } from './routes/sessions/index.js';
 import { createFeaturesRoutes } from './routes/features/index.js';
@@ -46,8 +53,20 @@ import { SettingsService } from './services/settings-service.js';
 import { createSpecRegenerationRoutes } from './routes/app-spec/index.js';
 import { createClaudeRoutes } from './routes/claude/index.js';
 import { ClaudeUsageService } from './services/claude-usage-service.js';
+import { createCodexRoutes } from './routes/codex/index.js';
+import { CodexUsageService } from './services/codex-usage-service.js';
+import { CodexAppServerService } from './services/codex-app-server-service.js';
+import { CodexModelCacheService } from './services/codex-model-cache-service.js';
 import { createGitHubRoutes } from './routes/github/index.js';
 import { createContextRoutes } from './routes/context/index.js';
+import { createBacklogPlanRoutes } from './routes/backlog-plan/index.js';
+import { cleanupStaleValidations } from './routes/github/routes/validation-common.js';
+import { createMCPRoutes } from './routes/mcp/index.js';
+import { MCPTestService } from './services/mcp-test-service.js';
+import { createPipelineRoutes } from './routes/pipeline/index.js';
+import { pipelineService } from './services/pipeline-service.js';
+import { createIdeationRoutes } from './routes/ideation/index.js';
+import { IdeationService } from './services/ideation-service.js';
 
 // Load environment variables
 dotenv.config();
@@ -60,7 +79,7 @@ const ENABLE_REQUEST_LOGGING = process.env.ENABLE_REQUEST_LOGGING !== 'false'; /
 const hasAnthropicKey = !!process.env.ANTHROPIC_API_KEY;
 
 if (!hasAnthropicKey) {
-  console.warn(`
+  logger.warn(`
 ╔═══════════════════════════════════════════════════════════════════════╗
 ║  ⚠️  WARNING: No Claude authentication configured                      ║
 ║                                                                       ║
@@ -73,7 +92,7 @@ if (!hasAnthropicKey) {
 ╚═══════════════════════════════════════════════════════════════════════╝
 `);
 } else {
-  console.log('[Server] ✓ ANTHROPIC_API_KEY detected (API key auth)');
+  logger.info('✓ ANTHROPIC_API_KEY detected (API key auth)');
 }
 
 // Initialize security
@@ -85,7 +104,7 @@ const app = express();
 // Middleware
 // Custom colored logger showing only endpoint and status code (configurable via ENABLE_REQUEST_LOGGING env var)
 if (ENABLE_REQUEST_LOGGING) {
-  morgan.token('status-colored', (req, res) => {
+  morgan.token('status-colored', (_req, res) => {
     const status = res.statusCode;
     if (status >= 500) return `\x1b[31m${status}\x1b[0m`; // Red for server errors
     if (status >= 400) return `\x1b[33m${status}\x1b[0m`; // Yellow for client errors
@@ -99,56 +118,123 @@ if (ENABLE_REQUEST_LOGGING) {
     })
   );
 }
+// CORS configuration
+// When using credentials (cookies), origin cannot be '*'
+// We dynamically allow the requesting origin for local development
 app.use(
   cors({
-    origin: process.env.CORS_ORIGIN || '*',
+    origin: (origin, callback) => {
+      // Allow requests with no origin (like mobile apps, curl, Electron)
+      if (!origin) {
+        callback(null, true);
+        return;
+      }
+
+      // If CORS_ORIGIN is set, use it (can be comma-separated list)
+      const allowedOrigins = process.env.CORS_ORIGIN?.split(',').map((o) => o.trim());
+      if (allowedOrigins && allowedOrigins.length > 0 && allowedOrigins[0] !== '*') {
+        if (allowedOrigins.includes(origin)) {
+          callback(null, origin);
+        } else {
+          callback(new Error('Not allowed by CORS'));
+        }
+        return;
+      }
+
+      // For local development, allow localhost origins
+      if (
+        origin.startsWith('http://localhost:') ||
+        origin.startsWith('http://127.0.0.1:') ||
+        origin.startsWith('http://[::1]:')
+      ) {
+        callback(null, origin);
+        return;
+      }
+
+      // Reject other origins by default for security
+      callback(new Error('Not allowed by CORS'));
+    },
     credentials: true,
   })
 );
 app.use(express.json({ limit: '50mb' }));
+app.use(cookieParser());
 
 // Create shared event emitter for streaming
 const events: EventEmitter = createEventEmitter();
 
 // Create services
-const agentService = new AgentService(DATA_DIR, events);
-const featureLoader = new FeatureLoader();
-const autoModeService = new AutoModeService(events);
+// Note: settingsService is created first so it can be injected into other services
 const settingsService = new SettingsService(DATA_DIR);
+const agentService = new AgentService(DATA_DIR, events, settingsService);
+const featureLoader = new FeatureLoader();
+const autoModeService = new AutoModeService(events, settingsService);
 const claudeUsageService = new ClaudeUsageService();
+const codexAppServerService = new CodexAppServerService();
+const codexModelCacheService = new CodexModelCacheService(DATA_DIR, codexAppServerService);
+const codexUsageService = new CodexUsageService(codexAppServerService);
+const mcpTestService = new MCPTestService(settingsService);
+const ideationService = new IdeationService(events, settingsService, featureLoader);
 
 // Initialize services
 (async () => {
   await agentService.initialize();
-  console.log('[Server] Agent service initialized');
+  logger.info('Agent service initialized');
+
+  // Bootstrap Codex model cache in background (don't block server startup)
+  void codexModelCacheService.getModels().catch((err) => {
+    logger.error('Failed to bootstrap Codex model cache:', err);
+  });
 })();
 
-// Mount API routes - health is unauthenticated for monitoring
+// Run stale validation cleanup every hour to prevent memory leaks from crashed validations
+const VALIDATION_CLEANUP_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+setInterval(() => {
+  const cleaned = cleanupStaleValidations();
+  if (cleaned > 0) {
+    logger.info(`Cleaned up ${cleaned} stale validation entries`);
+  }
+}, VALIDATION_CLEANUP_INTERVAL_MS);
+
+// Require Content-Type: application/json for all API POST/PUT/PATCH requests
+// This helps prevent CSRF and content-type confusion attacks
+app.use('/api', requireJsonContentType);
+
+// Mount API routes - health, auth, and setup are unauthenticated
 app.use('/api/health', createHealthRoutes());
+app.use('/api/auth', createAuthRoutes());
+app.use('/api/setup', createSetupRoutes());
 
 // Apply authentication to all other routes
 app.use('/api', authMiddleware);
 
+// Protected health endpoint with detailed info
+app.get('/api/health/detailed', createDetailedHandler());
+
 app.use('/api/fs', createFsRoutes(events));
 app.use('/api/agent', createAgentRoutes(agentService, events));
 app.use('/api/sessions', createSessionsRoutes(agentService));
 app.use('/api/features', createFeaturesRoutes(featureLoader));
 app.use('/api/auto-mode', createAutoModeRoutes(autoModeService));
-app.use('/api/enhance-prompt', createEnhancePromptRoutes());
+app.use('/api/enhance-prompt', createEnhancePromptRoutes(settingsService));
 app.use('/api/worktree', createWorktreeRoutes());
 app.use('/api/git', createGitRoutes());
-app.use('/api/setup', createSetupRoutes());
-app.use('/api/suggestions', createSuggestionsRoutes(events));
+app.use('/api/suggestions', createSuggestionsRoutes(events, settingsService));
 app.use('/api/models', createModelsRoutes());
-app.use('/api/spec-regeneration', createSpecRegenerationRoutes(events));
+app.use('/api/spec-regeneration', createSpecRegenerationRoutes(events, settingsService));
 app.use('/api/running-agents', createRunningAgentsRoutes(autoModeService));
 app.use('/api/workspace', createWorkspaceRoutes());
 app.use('/api/templates', createTemplatesRoutes());
 app.use('/api/terminal', createTerminalRoutes());
 app.use('/api/settings', createSettingsRoutes(settingsService));
 app.use('/api/claude', createClaudeRoutes(claudeUsageService));
-app.use('/api/github', createGitHubRoutes());
-app.use('/api/context', createContextRoutes());
+app.use('/api/codex', createCodexRoutes(codexUsageService, codexModelCacheService));
+app.use('/api/github', createGitHubRoutes(events, settingsService));
+app.use('/api/context', createContextRoutes(settingsService));
+app.use('/api/backlog-plan', createBacklogPlanRoutes(events, settingsService));
+app.use('/api/mcp', createMCPRoutes(mcpTestService));
+app.use('/api/pipeline', createPipelineRoutes(pipelineService));
+app.use('/api/ideation', createIdeationRoutes(events, ideationService, featureLoader));
 
 // Create HTTP server
 const server = createServer(app);
@@ -158,10 +244,55 @@ const wss = new WebSocketServer({ noServer: true });
 const terminalWss = new WebSocketServer({ noServer: true });
 const terminalService = getTerminalService();
 
+/**
+ * Authenticate WebSocket upgrade requests
+ * Checks for API key in header/query, session token in header/query, OR valid session cookie
+ */
+function authenticateWebSocket(request: import('http').IncomingMessage): boolean {
+  const url = new URL(request.url || '', `http://${request.headers.host}`);
+
+  // Convert URL search params to query object
+  const query: Record<string, string | undefined> = {};
+  url.searchParams.forEach((value, key) => {
+    query[key] = value;
+  });
+
+  // Parse cookies from header
+  const cookieHeader = request.headers.cookie;
+  const cookies = cookieHeader ? cookie.parse(cookieHeader) : {};
+
+  // Use shared authentication logic for standard auth methods
+  if (
+    checkRawAuthentication(
+      request.headers as Record<string, string | string[] | undefined>,
+      query,
+      cookies
+    )
+  ) {
+    return true;
+  }
+
+  // Additionally check for short-lived WebSocket connection token (WebSocket-specific)
+  const wsToken = url.searchParams.get('wsToken');
+  if (wsToken && validateWsConnectionToken(wsToken)) {
+    return true;
+  }
+
+  return false;
+}
+
 // Handle HTTP upgrade requests manually to route to correct WebSocket server
 server.on('upgrade', (request, socket, head) => {
   const { pathname } = new URL(request.url || '', `http://${request.headers.host}`);
 
+  // Authenticate all WebSocket connections
+  if (!authenticateWebSocket(request)) {
+    logger.info('Authentication failed, rejecting connection');
+    socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+    socket.destroy();
+    return;
+  }
+
   if (pathname === '/api/events') {
     wss.handleUpgrade(request, socket, head, (ws) => {
       wss.emit('connection', ws, request);
@@ -177,22 +308,38 @@ server.on('upgrade', (request, socket, head) => {
 
 // Events WebSocket connection handler
 wss.on('connection', (ws: WebSocket) => {
-  console.log('[WebSocket] Client connected');
+  logger.info('Client connected, ready state:', ws.readyState);
 
   // Subscribe to all events and forward to this client
   const unsubscribe = events.subscribe((type, payload) => {
+    logger.info('Event received:', {
+      type,
+      hasPayload: !!payload,
+      payloadKeys: payload ? Object.keys(payload) : [],
+      wsReadyState: ws.readyState,
+      wsOpen: ws.readyState === WebSocket.OPEN,
+    });
+
     if (ws.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify({ type, payload }));
+      const message = JSON.stringify({ type, payload });
+      logger.info('Sending event to client:', {
+        type,
+        messageLength: message.length,
+        sessionId: (payload as any)?.sessionId,
+      });
+      ws.send(message);
+    } else {
+      logger.info('WARNING: Cannot send event, WebSocket not open. ReadyState:', ws.readyState);
     }
   });
 
   ws.on('close', () => {
-    console.log('[WebSocket] Client disconnected');
+    logger.info('Client disconnected');
     unsubscribe();
   });
 
   ws.on('error', (error) => {
-    console.error('[WebSocket] Error:', error);
+    logger.error('ERROR:', error);
     unsubscribe();
   });
 });
@@ -219,24 +366,24 @@ terminalWss.on('connection', (ws: WebSocket, req: import('http').IncomingMessage
   const sessionId = url.searchParams.get('sessionId');
   const token = url.searchParams.get('token');
 
-  console.log(`[Terminal WS] Connection attempt for session: ${sessionId}`);
+  logger.info(`Connection attempt for session: ${sessionId}`);
 
   // Check if terminal is enabled
   if (!isTerminalEnabled()) {
-    console.log('[Terminal WS] Terminal is disabled');
+    logger.info('Terminal is disabled');
     ws.close(4003, 'Terminal access is disabled');
     return;
   }
 
   // Validate token if password is required
   if (isTerminalPasswordRequired() && !validateTerminalToken(token || undefined)) {
-    console.log('[Terminal WS] Invalid or missing token');
+    logger.info('Invalid or missing token');
     ws.close(4001, 'Authentication required');
     return;
   }
 
   if (!sessionId) {
-    console.log('[Terminal WS] No session ID provided');
+    logger.info('No session ID provided');
     ws.close(4002, 'Session ID required');
     return;
   }
@@ -244,12 +391,12 @@ terminalWss.on('connection', (ws: WebSocket, req: import('http').IncomingMessage
   // Check if session exists
   const session = terminalService.getSession(sessionId);
   if (!session) {
-    console.log(`[Terminal WS] Session ${sessionId} not found`);
+    logger.info(`Session ${sessionId} not found`);
     ws.close(4004, 'Session not found');
     return;
   }
 
-  console.log(`[Terminal WS] Client connected to session ${sessionId}`);
+  logger.info(`Client connected to session ${sessionId}`);
 
   // Track this connection
   if (!terminalConnections.has(sessionId)) {
@@ -365,15 +512,15 @@ terminalWss.on('connection', (ws: WebSocket, req: import('http').IncomingMessage
           break;
 
         default:
-          console.warn(`[Terminal WS] Unknown message type: ${msg.type}`);
+          logger.warn(`Unknown message type: ${msg.type}`);
       }
     } catch (error) {
-      console.error('[Terminal WS] Error processing message:', error);
+      logger.error('Error processing message:', error);
     }
   });
 
   ws.on('close', () => {
-    console.log(`[Terminal WS] Client disconnected from session ${sessionId}`);
+    logger.info(`Client disconnected from session ${sessionId}`);
     unsubscribeData();
     unsubscribeExit();
 
@@ -392,7 +539,7 @@ terminalWss.on('connection', (ws: WebSocket, req: import('http').IncomingMessage
   });
 
   ws.on('error', (error) => {
-    console.error(`[Terminal WS] Error on session ${sessionId}:`, error);
+    logger.error(`Error on session ${sessionId}:`, error);
     unsubscribeData();
     unsubscribeExit();
   });
@@ -407,7 +554,7 @@ const startServer = (port: number) => {
         : 'enabled'
       : 'disabled';
     const portStr = port.toString().padEnd(4);
-    console.log(`
+    logger.info(`
 ╔═══════════════════════════════════════════════════════╗
 ║           Automaker Backend Server                    ║
 ╠═══════════════════════════════════════════════════════╣
@@ -422,7 +569,7 @@ const startServer = (port: number) => {
 
   server.on('error', (error: NodeJS.ErrnoException) => {
     if (error.code === 'EADDRINUSE') {
-      console.error(`
+      logger.error(`
 ╔═══════════════════════════════════════════════════════╗
 ║  ❌ ERROR: Port ${port} is already in use              ║
 ╠═══════════════════════════════════════════════════════╣
@@ -442,7 +589,7 @@ const startServer = (port: number) => {
 `);
       process.exit(1);
     } else {
-      console.error('[Server] Error starting server:', error);
+      logger.error('Error starting server:', error);
       process.exit(1);
     }
   });
@@ -450,21 +597,41 @@ const startServer = (port: number) => {
 
 startServer(PORT);
 
+// Global error handlers to prevent crashes from uncaught errors
+process.on('unhandledRejection', (reason: unknown, _promise: Promise<unknown>) => {
+  logger.error('Unhandled Promise Rejection:', {
+    reason: reason instanceof Error ? reason.message : String(reason),
+    stack: reason instanceof Error ? reason.stack : undefined,
+  });
+  // Don't exit - log the error and continue running
+  // This prevents the server from crashing due to unhandled rejections
+});
+
+process.on('uncaughtException', (error: Error) => {
+  logger.error('Uncaught Exception:', {
+    message: error.message,
+    stack: error.stack,
+  });
+  // Exit on uncaught exceptions to prevent undefined behavior
+  // The process is in an unknown state after an uncaught exception
+  process.exit(1);
+});
+
 // Graceful shutdown
 process.on('SIGTERM', () => {
-  console.log('SIGTERM received, shutting down...');
+  logger.info('SIGTERM received, shutting down...');
   terminalService.cleanup();
   server.close(() => {
-    console.log('Server closed');
+    logger.info('Server closed');
     process.exit(0);
   });
 });
 
 process.on('SIGINT', () => {
-  console.log('SIGINT received, shutting down...');
+  logger.info('SIGINT received, shutting down...');
   terminalService.cleanup();
   server.close(() => {
-    console.log('Server closed');
+    logger.info('Server closed');
     process.exit(0);
   });
 });

apps/server/src/lib/agent-discovery.ts

@@ -0,0 +1,257 @@
+/**
+ * Agent Discovery - Scans filesystem for AGENT.md files
+ *
+ * Discovers agents from:
+ * - ~/.claude/agents/ (user-level, global)
+ * - .claude/agents/ (project-level)
+ *
+ * Similar to Skills, but for custom subagents defined in AGENT.md files.
+ */
+
+import path from 'path';
+import os from 'os';
+import { createLogger } from '@automaker/utils';
+import { secureFs, systemPaths } from '@automaker/platform';
+import type { AgentDefinition } from '@automaker/types';
+
+const logger = createLogger('AgentDiscovery');
+
+export interface FilesystemAgent {
+  name: string; // Directory name (e.g., 'code-reviewer')
+  definition: AgentDefinition;
+  source: 'user' | 'project';
+  filePath: string; // Full path to AGENT.md
+}
+
+/**
+ * Parse agent content string into AgentDefinition
+ * Format:
+ * ---
+ * name: agent-name  # Optional
+ * description: When to use this agent
+ * tools: tool1, tool2, tool3  # Optional (comma or space separated list)
+ * model: sonnet  # Optional: sonnet, opus, haiku
+ * ---
+ * System prompt content here...
+ */
+function parseAgentContent(content: string, filePath: string): AgentDefinition | null {
+  // Extract frontmatter
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!frontmatterMatch) {
+    logger.warn(`Invalid agent file format (missing frontmatter): ${filePath}`);
+    return null;
+  }
+
+  const [, frontmatter, prompt] = frontmatterMatch;
+
+  // Parse description (required)
+  const description = frontmatter.match(/description:\s*(.+)/)?.[1]?.trim();
+  if (!description) {
+    logger.warn(`Missing description in agent file: ${filePath}`);
+    return null;
+  }
+
+  // Parse tools (optional) - supports both comma-separated and space-separated
+  const toolsMatch = frontmatter.match(/tools:\s*(.+)/);
+  const tools = toolsMatch
+    ? toolsMatch[1]
+        .split(/[,\s]+/) // Split by comma or whitespace
+        .map((t) => t.trim())
+        .filter((t) => t && t !== '')
+    : undefined;
+
+  // Parse model (optional) - validate against allowed values
+  const modelMatch = frontmatter.match(/model:\s*(\w+)/);
+  const modelValue = modelMatch?.[1]?.trim();
+  const validModels = ['sonnet', 'opus', 'haiku', 'inherit'] as const;
+  const model =
+    modelValue && validModels.includes(modelValue as (typeof validModels)[number])
+      ? (modelValue as 'sonnet' | 'opus' | 'haiku' | 'inherit')
+      : undefined;
+
+  if (modelValue && !model) {
+    logger.warn(
+      `Invalid model "${modelValue}" in agent file: ${filePath}. Expected one of: ${validModels.join(', ')}`
+    );
+  }
+
+  return {
+    description,
+    prompt: prompt.trim(),
+    tools,
+    model,
+  };
+}
+
+/**
+ * Directory entry with type information
+ */
+interface DirEntry {
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+}
+
+/**
+ * Filesystem adapter interface for abstracting systemPaths vs secureFs
+ */
+interface FsAdapter {
+  exists: (filePath: string) => Promise<boolean>;
+  readdir: (dirPath: string) => Promise<DirEntry[]>;
+  readFile: (filePath: string) => Promise<string>;
+}
+
+/**
+ * Create a filesystem adapter for system paths (user directory)
+ */
+function createSystemPathAdapter(): FsAdapter {
+  return {
+    exists: (filePath) => Promise.resolve(systemPaths.systemPathExists(filePath)),
+    readdir: async (dirPath) => {
+      const entryNames = await systemPaths.systemPathReaddir(dirPath);
+      const entries: DirEntry[] = [];
+      for (const name of entryNames) {
+        const stat = await systemPaths.systemPathStat(path.join(dirPath, name));
+        entries.push({
+          name,
+          isFile: stat.isFile(),
+          isDirectory: stat.isDirectory(),
+        });
+      }
+      return entries;
+    },
+    readFile: (filePath) => systemPaths.systemPathReadFile(filePath, 'utf-8') as Promise<string>,
+  };
+}
+
+/**
+ * Create a filesystem adapter for project paths (secureFs)
+ */
+function createSecureFsAdapter(): FsAdapter {
+  return {
+    exists: (filePath) =>
+      secureFs
+        .access(filePath)
+        .then(() => true)
+        .catch(() => false),
+    readdir: async (dirPath) => {
+      const entries = await secureFs.readdir(dirPath, { withFileTypes: true });
+      return entries.map((entry) => ({
+        name: entry.name,
+        isFile: entry.isFile(),
+        isDirectory: entry.isDirectory(),
+      }));
+    },
+    readFile: (filePath) => secureFs.readFile(filePath, 'utf-8') as Promise<string>,
+  };
+}
+
+/**
+ * Parse agent file using the provided filesystem adapter
+ */
+async function parseAgentFileWithAdapter(
+  filePath: string,
+  fsAdapter: FsAdapter
+): Promise<AgentDefinition | null> {
+  try {
+    const content = await fsAdapter.readFile(filePath);
+    return parseAgentContent(content, filePath);
+  } catch (error) {
+    logger.error(`Failed to parse agent file: ${filePath}`, error);
+    return null;
+  }
+}
+
+/**
+ * Scan a directory for agent .md files
+ * Agents can be in two formats:
+ * 1. Flat: agent-name.md (file directly in agents/)
+ * 2. Subdirectory: agent-name/AGENT.md (folder + file, similar to Skills)
+ */
+async function scanAgentsDirectory(
+  baseDir: string,
+  source: 'user' | 'project'
+): Promise<FilesystemAgent[]> {
+  const agents: FilesystemAgent[] = [];
+  const fsAdapter = source === 'user' ? createSystemPathAdapter() : createSecureFsAdapter();
+
+  try {
+    // Check if directory exists
+    const exists = await fsAdapter.exists(baseDir);
+    if (!exists) {
+      logger.debug(`Directory does not exist: ${baseDir}`);
+      return agents;
+    }
+
+    // Read all entries in the directory
+    const entries = await fsAdapter.readdir(baseDir);
+
+    for (const entry of entries) {
+      // Check for flat .md file format (agent-name.md)
+      if (entry.isFile && entry.name.endsWith('.md')) {
+        const agentName = entry.name.slice(0, -3); // Remove .md extension
+        const agentFilePath = path.join(baseDir, entry.name);
+        const definition = await parseAgentFileWithAdapter(agentFilePath, fsAdapter);
+        if (definition) {
+          agents.push({
+            name: agentName,
+            definition,
+            source,
+            filePath: agentFilePath,
+          });
+          logger.debug(`Discovered ${source} agent (flat): ${agentName}`);
+        }
+      }
+      // Check for subdirectory format (agent-name/AGENT.md)
+      else if (entry.isDirectory) {
+        const agentFilePath = path.join(baseDir, entry.name, 'AGENT.md');
+        const agentFileExists = await fsAdapter.exists(agentFilePath);
+
+        if (agentFileExists) {
+          const definition = await parseAgentFileWithAdapter(agentFilePath, fsAdapter);
+          if (definition) {
+            agents.push({
+              name: entry.name,
+              definition,
+              source,
+              filePath: agentFilePath,
+            });
+            logger.debug(`Discovered ${source} agent (subdirectory): ${entry.name}`);
+          }
+        }
+      }
+    }
+  } catch (error) {
+    logger.error(`Failed to scan agents directory: ${baseDir}`, error);
+  }
+
+  return agents;
+}
+
+/**
+ * Discover all filesystem-based agents from user and project sources
+ */
+export async function discoverFilesystemAgents(
+  projectPath?: string,
+  sources: Array<'user' | 'project'> = ['user', 'project']
+): Promise<FilesystemAgent[]> {
+  const agents: FilesystemAgent[] = [];
+
+  // Discover user-level agents from ~/.claude/agents/
+  if (sources.includes('user')) {
+    const userAgentsDir = path.join(os.homedir(), '.claude', 'agents');
+    const userAgents = await scanAgentsDirectory(userAgentsDir, 'user');
+    agents.push(...userAgents);
+    logger.info(`Discovered ${userAgents.length} user-level agents from ${userAgentsDir}`);
+  }
+
+  // Discover project-level agents from .claude/agents/
+  if (sources.includes('project') && projectPath) {
+    const projectAgentsDir = path.join(projectPath, '.claude', 'agents');
+    const projectAgents = await scanAgentsDirectory(projectAgentsDir, 'project');
+    agents.push(...projectAgents);
+    logger.info(`Discovered ${projectAgents.length} project-level agents from ${projectAgentsDir}`);
+  }
+
+  return agents;
+}

apps/server/src/lib/auth-utils.ts

@@ -0,0 +1,263 @@
+/**
+ * Secure authentication utilities that avoid environment variable race conditions
+ */
+
+import { spawn } from 'child_process';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('AuthUtils');
+
+export interface SecureAuthEnv {
+  [key: string]: string | undefined;
+}
+
+export interface AuthValidationResult {
+  isValid: boolean;
+  error?: string;
+  normalizedKey?: string;
+}
+
+/**
+ * Validates API key format without modifying process.env
+ */
+export function validateApiKey(
+  key: string,
+  provider: 'anthropic' | 'openai' | 'cursor'
+): AuthValidationResult {
+  if (!key || typeof key !== 'string' || key.trim().length === 0) {
+    return { isValid: false, error: 'API key is required' };
+  }
+
+  const trimmedKey = key.trim();
+
+  switch (provider) {
+    case 'anthropic':
+      if (!trimmedKey.startsWith('sk-ant-')) {
+        return {
+          isValid: false,
+          error: 'Invalid Anthropic API key format. Should start with "sk-ant-"',
+        };
+      }
+      if (trimmedKey.length < 20) {
+        return { isValid: false, error: 'Anthropic API key too short' };
+      }
+      break;
+
+    case 'openai':
+      if (!trimmedKey.startsWith('sk-')) {
+        return { isValid: false, error: 'Invalid OpenAI API key format. Should start with "sk-"' };
+      }
+      if (trimmedKey.length < 20) {
+        return { isValid: false, error: 'OpenAI API key too short' };
+      }
+      break;
+
+    case 'cursor':
+      // Cursor API keys might have different format
+      if (trimmedKey.length < 10) {
+        return { isValid: false, error: 'Cursor API key too short' };
+      }
+      break;
+  }
+
+  return { isValid: true, normalizedKey: trimmedKey };
+}
+
+/**
+ * Creates a secure environment object for authentication testing
+ * without modifying the global process.env
+ */
+export function createSecureAuthEnv(
+  authMethod: 'cli' | 'api_key',
+  apiKey?: string,
+  provider: 'anthropic' | 'openai' | 'cursor' = 'anthropic'
+): SecureAuthEnv {
+  const env: SecureAuthEnv = { ...process.env };
+
+  if (authMethod === 'cli') {
+    // For CLI auth, remove the API key to force CLI authentication
+    const envKey = provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    delete env[envKey];
+  } else if (authMethod === 'api_key' && apiKey) {
+    // For API key auth, validate and set the provided key
+    const validation = validateApiKey(apiKey, provider);
+    if (!validation.isValid) {
+      throw new Error(validation.error);
+    }
+    const envKey = provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    env[envKey] = validation.normalizedKey;
+  }
+
+  return env;
+}
+
+/**
+ * Creates a temporary environment override for the current process
+ * WARNING: This should only be used in isolated contexts and immediately cleaned up
+ */
+export function createTempEnvOverride(authEnv: SecureAuthEnv): () => void {
+  const originalEnv = { ...process.env };
+
+  // Apply the auth environment
+  Object.assign(process.env, authEnv);
+
+  // Return cleanup function
+  return () => {
+    // Restore original environment
+    Object.keys(process.env).forEach((key) => {
+      if (!(key in originalEnv)) {
+        delete process.env[key];
+      }
+    });
+    Object.assign(process.env, originalEnv);
+  };
+}
+
+/**
+ * Spawns a process with secure environment isolation
+ */
+export function spawnSecureAuth(
+  command: string,
+  args: string[],
+  authEnv: SecureAuthEnv,
+  options: {
+    cwd?: string;
+    timeout?: number;
+  } = {}
+): Promise<{ stdout: string; stderr: string; exitCode: number | null }> {
+  return new Promise((resolve, reject) => {
+    const { cwd = process.cwd(), timeout = 30000 } = options;
+
+    logger.debug(`Spawning secure auth process: ${command} ${args.join(' ')}`);
+
+    const child = spawn(command, args, {
+      cwd,
+      env: authEnv,
+      stdio: 'pipe',
+      shell: false,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let isResolved = false;
+
+    const timeoutId = setTimeout(() => {
+      if (!isResolved) {
+        child.kill('SIGTERM');
+        isResolved = true;
+        reject(new Error('Authentication process timed out'));
+      }
+    }, timeout);
+
+    child.stdout?.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timeoutId);
+      if (!isResolved) {
+        isResolved = true;
+        resolve({ stdout, stderr, exitCode: code });
+      }
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timeoutId);
+      if (!isResolved) {
+        isResolved = true;
+        reject(error);
+      }
+    });
+  });
+}
+
+/**
+ * Safely extracts environment variable without race conditions
+ */
+export function safeGetEnv(key: string): string | undefined {
+  return process.env[key];
+}
+
+/**
+ * Checks if an environment variable would be modified without actually modifying it
+ */
+export function wouldModifyEnv(key: string, newValue: string): boolean {
+  const currentValue = safeGetEnv(key);
+  return currentValue !== newValue;
+}
+
+/**
+ * Secure auth session management
+ */
+export class AuthSessionManager {
+  private static activeSessions = new Map<string, SecureAuthEnv>();
+
+  static createSession(
+    sessionId: string,
+    authMethod: 'cli' | 'api_key',
+    apiKey?: string,
+    provider: 'anthropic' | 'openai' | 'cursor' = 'anthropic'
+  ): SecureAuthEnv {
+    const env = createSecureAuthEnv(authMethod, apiKey, provider);
+    this.activeSessions.set(sessionId, env);
+    return env;
+  }
+
+  static getSession(sessionId: string): SecureAuthEnv | undefined {
+    return this.activeSessions.get(sessionId);
+  }
+
+  static destroySession(sessionId: string): void {
+    this.activeSessions.delete(sessionId);
+  }
+
+  static cleanup(): void {
+    this.activeSessions.clear();
+  }
+}
+
+/**
+ * Rate limiting for auth attempts to prevent abuse
+ */
+export class AuthRateLimiter {
+  private attempts = new Map<string, { count: number; lastAttempt: number }>();
+
+  constructor(
+    private maxAttempts = 5,
+    private windowMs = 60000
+  ) {}
+
+  canAttempt(identifier: string): boolean {
+    const now = Date.now();
+    const record = this.attempts.get(identifier);
+
+    if (!record || now - record.lastAttempt > this.windowMs) {
+      this.attempts.set(identifier, { count: 1, lastAttempt: now });
+      return true;
+    }
+
+    if (record.count >= this.maxAttempts) {
+      return false;
+    }
+
+    record.count++;
+    record.lastAttempt = now;
+    return true;
+  }
+
+  getRemainingAttempts(identifier: string): number {
+    const record = this.attempts.get(identifier);
+    if (!record) return this.maxAttempts;
+    return Math.max(0, this.maxAttempts - record.count);
+  }
+
+  getResetTime(identifier: string): Date | null {
+    const record = this.attempts.get(identifier);
+    if (!record) return null;
+    return new Date(record.lastAttempt + this.windowMs);
+  }
+}

apps/server/src/lib/auth.ts

@@ -1,54 +1,381 @@
 /**
  * Authentication middleware for API security
  *
- * Supports API key authentication via header or environment variable.
+ * Supports two authentication methods:
+ * 1. Header-based (X-API-Key) - Used by Electron mode
+ * 2. Cookie-based (HTTP-only session cookie) - Used by web mode
+ *
+ * Auto-generates an API key on first run if none is configured.
  */
 
 import type { Request, Response, NextFunction } from 'express';
+import crypto from 'crypto';
+import path from 'path';
+import * as secureFs from './secure-fs.js';
+import { createLogger } from '@automaker/utils';
 
-// API key from environment (optional - if not set, auth is disabled)
-const API_KEY = process.env.AUTOMAKER_API_KEY;
+const logger = createLogger('Auth');
+
+const DATA_DIR = process.env.DATA_DIR || './data';
+const API_KEY_FILE = path.join(DATA_DIR, '.api-key');
+const SESSIONS_FILE = path.join(DATA_DIR, '.sessions');
+const SESSION_COOKIE_NAME = 'automaker_session';
+const SESSION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const WS_TOKEN_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes for WebSocket connection tokens
+
+// Session store - persisted to file for survival across server restarts
+const validSessions = new Map<string, { createdAt: number; expiresAt: number }>();
+
+// Short-lived WebSocket connection tokens (in-memory only, not persisted)
+const wsConnectionTokens = new Map<string, { createdAt: number; expiresAt: number }>();
+
+// Clean up expired WebSocket tokens periodically
+setInterval(() => {
+  const now = Date.now();
+  wsConnectionTokens.forEach((data, token) => {
+    if (data.expiresAt <= now) {
+      wsConnectionTokens.delete(token);
+    }
+  });
+}, 60 * 1000); // Clean up every minute
+
+/**
+ * Load sessions from file on startup
+ */
+function loadSessions(): void {
+  try {
+    if (secureFs.existsSync(SESSIONS_FILE)) {
+      const data = secureFs.readFileSync(SESSIONS_FILE, 'utf-8') as string;
+      const sessions = JSON.parse(data) as Array<
+        [string, { createdAt: number; expiresAt: number }]
+      >;
+      const now = Date.now();
+      let loadedCount = 0;
+      let expiredCount = 0;
+
+      for (const [token, session] of sessions) {
+        // Only load non-expired sessions
+        if (session.expiresAt > now) {
+          validSessions.set(token, session);
+          loadedCount++;
+        } else {
+          expiredCount++;
+        }
+      }
+
+      if (loadedCount > 0 || expiredCount > 0) {
+        logger.info(`Loaded ${loadedCount} sessions (${expiredCount} expired)`);
+      }
+    }
+  } catch (error) {
+    logger.warn('Error loading sessions:', error);
+  }
+}
+
+/**
+ * Save sessions to file (async)
+ */
+async function saveSessions(): Promise<void> {
+  try {
+    await secureFs.mkdir(path.dirname(SESSIONS_FILE), { recursive: true });
+    const sessions = Array.from(validSessions.entries());
+    await secureFs.writeFile(SESSIONS_FILE, JSON.stringify(sessions), {
+      encoding: 'utf-8',
+      mode: 0o600,
+    });
+  } catch (error) {
+    logger.error('Failed to save sessions:', error);
+  }
+}
+
+// Load existing sessions on startup
+loadSessions();
+
+/**
+ * Ensure an API key exists - either from env var, file, or generate new one.
+ * This provides CSRF protection by requiring a secret key for all API requests.
+ */
+function ensureApiKey(): string {
+  // First check environment variable (Electron passes it this way)
+  if (process.env.AUTOMAKER_API_KEY) {
+    logger.info('Using API key from environment variable');
+    return process.env.AUTOMAKER_API_KEY;
+  }
+
+  // Try to read from file
+  try {
+    if (secureFs.existsSync(API_KEY_FILE)) {
+      const key = (secureFs.readFileSync(API_KEY_FILE, 'utf-8') as string).trim();
+      if (key) {
+        logger.info('Loaded API key from file');
+        return key;
+      }
+    }
+  } catch (error) {
+    logger.warn('Error reading API key file:', error);
+  }
+
+  // Generate new key
+  const newKey = crypto.randomUUID();
+  try {
+    secureFs.mkdirSync(path.dirname(API_KEY_FILE), { recursive: true });
+    secureFs.writeFileSync(API_KEY_FILE, newKey, { encoding: 'utf-8', mode: 0o600 });
+    logger.info('Generated new API key');
+  } catch (error) {
+    logger.error('Failed to save API key:', error);
+  }
+  return newKey;
+}
+
+// API key - always generated/loaded on startup for CSRF protection
+const API_KEY = ensureApiKey();
+
+// Print API key to console for web mode users (unless suppressed for production logging)
+if (process.env.AUTOMAKER_HIDE_API_KEY !== 'true') {
+  logger.info(`
+╔═══════════════════════════════════════════════════════════════════════╗
+║  🔐 API Key for Web Mode Authentication                               ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║                                                                       ║
+║  When accessing via browser, you'll be prompted to enter this key:    ║
+║                                                                       ║
+║    ${API_KEY}
+║                                                                       ║
+║  In Electron mode, authentication is handled automatically.          ║
+╚═══════════════════════════════════════════════════════════════════════╝
+`);
+} else {
+  logger.info('API key banner hidden (AUTOMAKER_HIDE_API_KEY=true)');
+}
+
+/**
+ * Generate a cryptographically secure session token
+ */
+function generateSessionToken(): string {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Create a new session and return the token
+ */
+export async function createSession(): Promise<string> {
+  const token = generateSessionToken();
+  const now = Date.now();
+  validSessions.set(token, {
+    createdAt: now,
+    expiresAt: now + SESSION_MAX_AGE_MS,
+  });
+  await saveSessions(); // Persist to file
+  return token;
+}
+
+/**
+ * Validate a session token
+ * Note: This returns synchronously but triggers async persistence if session expired
+ */
+export function validateSession(token: string): boolean {
+  const session = validSessions.get(token);
+  if (!session) return false;
+
+  if (Date.now() > session.expiresAt) {
+    validSessions.delete(token);
+    // Fire-and-forget: persist removal asynchronously
+    saveSessions().catch((err) => logger.error('Error saving sessions:', err));
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Invalidate a session token
+ */
+export async function invalidateSession(token: string): Promise<void> {
+  validSessions.delete(token);
+  await saveSessions(); // Persist removal
+}
+
+/**
+ * Create a short-lived WebSocket connection token
+ * Used for initial WebSocket handshake authentication
+ */
+export function createWsConnectionToken(): string {
+  const token = generateSessionToken();
+  const now = Date.now();
+  wsConnectionTokens.set(token, {
+    createdAt: now,
+    expiresAt: now + WS_TOKEN_MAX_AGE_MS,
+  });
+  return token;
+}
+
+/**
+ * Validate a WebSocket connection token
+ * These tokens are single-use and short-lived (5 minutes)
+ * Token is invalidated immediately after first successful use
+ */
+export function validateWsConnectionToken(token: string): boolean {
+  const tokenData = wsConnectionTokens.get(token);
+  if (!tokenData) return false;
+
+  // Always delete the token (single-use)
+  wsConnectionTokens.delete(token);
+
+  // Check if expired
+  if (Date.now() > tokenData.expiresAt) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate the API key using timing-safe comparison
+ * Prevents timing attacks that could leak information about the key
+ */
+export function validateApiKey(key: string): boolean {
+  if (!key || typeof key !== 'string') return false;
+
+  // Both buffers must be the same length for timingSafeEqual
+  const keyBuffer = Buffer.from(key);
+  const apiKeyBuffer = Buffer.from(API_KEY);
+
+  // If lengths differ, compare against a dummy to maintain constant time
+  if (keyBuffer.length !== apiKeyBuffer.length) {
+    crypto.timingSafeEqual(apiKeyBuffer, apiKeyBuffer);
+    return false;
+  }
+
+  return crypto.timingSafeEqual(keyBuffer, apiKeyBuffer);
+}
+
+/**
+ * Get session cookie options
+ */
+export function getSessionCookieOptions(): {
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: 'strict' | 'lax' | 'none';
+  maxAge: number;
+  path: string;
+} {
+  return {
+    httpOnly: true, // JavaScript cannot access this cookie
+    secure: process.env.NODE_ENV === 'production', // HTTPS only in production
+    sameSite: 'lax', // Sent for same-site requests and top-level navigations, but not cross-origin fetch/XHR
+    maxAge: SESSION_MAX_AGE_MS,
+    path: '/',
+  };
+}
+
+/**
+ * Get the session cookie name
+ */
+export function getSessionCookieName(): string {
+  return SESSION_COOKIE_NAME;
+}
+
+/**
+ * Authentication result type
+ */
+type AuthResult =
+  | { authenticated: true }
+  | { authenticated: false; errorType: 'invalid_api_key' | 'invalid_session' | 'no_auth' };
+
+/**
+ * Core authentication check - shared between middleware and status check
+ * Extracts auth credentials from various sources and validates them
+ */
+function checkAuthentication(
+  headers: Record<string, string | string[] | undefined>,
+  query: Record<string, string | undefined>,
+  cookies: Record<string, string | undefined>
+): AuthResult {
+  // Check for API key in header (Electron mode)
+  const headerKey = headers['x-api-key'] as string | undefined;
+  if (headerKey) {
+    if (validateApiKey(headerKey)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_api_key' };
+  }
+
+  // Check for session token in header (web mode with explicit token)
+  const sessionTokenHeader = headers['x-session-token'] as string | undefined;
+  if (sessionTokenHeader) {
+    if (validateSession(sessionTokenHeader)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_session' };
+  }
+
+  // Check for API key in query parameter (fallback)
+  const queryKey = query.apiKey;
+  if (queryKey) {
+    if (validateApiKey(queryKey)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_api_key' };
+  }
+
+  // Check for session cookie (web mode)
+  const sessionToken = cookies[SESSION_COOKIE_NAME];
+  if (sessionToken && validateSession(sessionToken)) {
+    return { authenticated: true };
+  }
+
+  return { authenticated: false, errorType: 'no_auth' };
+}
 
 /**
  * Authentication middleware
  *
- * If AUTOMAKER_API_KEY is set, requires matching key in X-API-Key header.
- * If not set, allows all requests (development mode).
+ * Accepts either:
+ * 1. X-API-Key header (for Electron mode)
+ * 2. X-Session-Token header (for web mode with explicit token)
+ * 3. apiKey query parameter (fallback for cases where headers can't be set)
+ * 4. Session cookie (for web mode)
  */
 export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
-  // If no API key is configured, allow all requests
-  if (!API_KEY) {
+  const result = checkAuthentication(
+    req.headers as Record<string, string | string[] | undefined>,
+    req.query as Record<string, string | undefined>,
+    (req.cookies || {}) as Record<string, string | undefined>
+  );
+
+  if (result.authenticated) {
     next();
     return;
   }
 
-  // Check for API key in header
-  const providedKey = req.headers['x-api-key'] as string | undefined;
-
-  if (!providedKey) {
-    res.status(401).json({
-      success: false,
-      error: 'Authentication required. Provide X-API-Key header.',
-    });
-    return;
+  // Return appropriate error based on what failed
+  switch (result.errorType) {
+    case 'invalid_api_key':
+      res.status(403).json({
+        success: false,
+        error: 'Invalid API key.',
+      });
+      break;
+    case 'invalid_session':
+      res.status(403).json({
+        success: false,
+        error: 'Invalid or expired session token.',
+      });
+      break;
+    case 'no_auth':
+    default:
+      res.status(401).json({
+        success: false,
+        error: 'Authentication required.',
+      });
   }
-
-  if (providedKey !== API_KEY) {
-    res.status(403).json({
-      success: false,
-      error: 'Invalid API key.',
-    });
-    return;
-  }
-
-  next();
 }
 
 /**
- * Check if authentication is enabled
+ * Check if authentication is enabled (always true now)
  */
 export function isAuthEnabled(): boolean {
-  return !!API_KEY;
+  return true;
 }
 
 /**
@@ -56,7 +383,31 @@ export function isAuthEnabled(): boolean {
  */
 export function getAuthStatus(): { enabled: boolean; method: string } {
   return {
-    enabled: !!API_KEY,
-    method: API_KEY ? 'api_key' : 'none',
+    enabled: true,
+    method: 'api_key_or_session',
   };
 }
+
+/**
+ * Check if a request is authenticated (for status endpoint)
+ */
+export function isRequestAuthenticated(req: Request): boolean {
+  const result = checkAuthentication(
+    req.headers as Record<string, string | string[] | undefined>,
+    req.query as Record<string, string | undefined>,
+    (req.cookies || {}) as Record<string, string | undefined>
+  );
+  return result.authenticated;
+}
+
+/**
+ * Check if raw credentials are authenticated
+ * Used for WebSocket authentication where we don't have Express request objects
+ */
+export function checkRawAuthentication(
+  headers: Record<string, string | string[] | undefined>,
+  query: Record<string, string | undefined>,
+  cookies: Record<string, string | undefined>
+): boolean {
+  return checkAuthentication(headers, query, cookies).authenticated;
+}

apps/server/src/lib/cli-detection.ts

@@ -0,0 +1,447 @@
+/**
+ * Unified CLI Detection Framework
+ *
+ * Provides consistent CLI detection and management across all providers
+ */
+
+import { spawn, execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('CliDetection');
+
+export interface CliInfo {
+  name: string;
+  command: string;
+  version?: string;
+  path?: string;
+  installed: boolean;
+  authenticated: boolean;
+  authMethod: 'cli' | 'api_key' | 'none';
+  platform?: string;
+  architectures?: string[];
+}
+
+export interface CliDetectionOptions {
+  timeout?: number;
+  includeWsl?: boolean;
+  wslDistribution?: string;
+}
+
+export interface CliDetectionResult {
+  cli: CliInfo;
+  detected: boolean;
+  issues: string[];
+}
+
+export interface UnifiedCliDetection {
+  claude?: CliDetectionResult;
+  codex?: CliDetectionResult;
+  cursor?: CliDetectionResult;
+}
+
+/**
+ * CLI Configuration for different providers
+ */
+const CLI_CONFIGS = {
+  claude: {
+    name: 'Claude CLI',
+    commands: ['claude'],
+    versionArgs: ['--version'],
+    installCommands: {
+      darwin: 'brew install anthropics/claude/claude',
+      linux: 'curl -fsSL https://claude.ai/install.sh | sh',
+      win32: 'iwr https://claude.ai/install.ps1 -UseBasicParsing | iex',
+    },
+  },
+  codex: {
+    name: 'Codex CLI',
+    commands: ['codex', 'openai'],
+    versionArgs: ['--version'],
+    installCommands: {
+      darwin: 'npm install -g @openai/codex-cli',
+      linux: 'npm install -g @openai/codex-cli',
+      win32: 'npm install -g @openai/codex-cli',
+    },
+  },
+  cursor: {
+    name: 'Cursor CLI',
+    commands: ['cursor-agent', 'cursor'],
+    versionArgs: ['--version'],
+    installCommands: {
+      darwin: 'brew install cursor/cursor/cursor-agent',
+      linux: 'curl -fsSL https://cursor.sh/install.sh | sh',
+      win32: 'iwr https://cursor.sh/install.ps1 -UseBasicParsing | iex',
+    },
+  },
+} as const;
+
+/**
+ * Detect if a CLI is installed and available
+ */
+export async function detectCli(
+  provider: keyof typeof CLI_CONFIGS,
+  options: CliDetectionOptions = {}
+): Promise<CliDetectionResult> {
+  const config = CLI_CONFIGS[provider];
+  const { timeout = 5000, includeWsl = false, wslDistribution } = options;
+  const issues: string[] = [];
+
+  const cliInfo: CliInfo = {
+    name: config.name,
+    command: '',
+    installed: false,
+    authenticated: false,
+    authMethod: 'none',
+  };
+
+  try {
+    // Find the command in PATH
+    const command = await findCommand([...config.commands]);
+    if (command) {
+      cliInfo.command = command;
+    }
+
+    if (!cliInfo.command) {
+      issues.push(`${config.name} not found in PATH`);
+      return { cli: cliInfo, detected: false, issues };
+    }
+
+    cliInfo.path = cliInfo.command;
+    cliInfo.installed = true;
+
+    // Get version
+    try {
+      cliInfo.version = await getCliVersion(cliInfo.command, [...config.versionArgs], timeout);
+    } catch (error) {
+      issues.push(`Failed to get ${config.name} version: ${error}`);
+    }
+
+    // Check authentication
+    cliInfo.authMethod = await checkCliAuth(provider, cliInfo.command);
+    cliInfo.authenticated = cliInfo.authMethod !== 'none';
+
+    return { cli: cliInfo, detected: true, issues };
+  } catch (error) {
+    issues.push(`Error detecting ${config.name}: ${error}`);
+    return { cli: cliInfo, detected: false, issues };
+  }
+}
+
+/**
+ * Detect all CLIs in the system
+ */
+export async function detectAllCLis(
+  options: CliDetectionOptions = {}
+): Promise<UnifiedCliDetection> {
+  const results: UnifiedCliDetection = {};
+
+  // Detect all providers in parallel
+  const providers = Object.keys(CLI_CONFIGS) as Array<keyof typeof CLI_CONFIGS>;
+  const detectionPromises = providers.map(async (provider) => {
+    const result = await detectCli(provider, options);
+    return { provider, result };
+  });
+
+  const detections = await Promise.all(detectionPromises);
+
+  for (const { provider, result } of detections) {
+    results[provider] = result;
+  }
+
+  return results;
+}
+
+/**
+ * Find the first available command from a list of alternatives
+ */
+export async function findCommand(commands: string[]): Promise<string | null> {
+  for (const command of commands) {
+    try {
+      const whichCommand = process.platform === 'win32' ? 'where' : 'which';
+      const result = execSync(`${whichCommand} ${command}`, {
+        encoding: 'utf8',
+        timeout: 2000,
+      }).trim();
+
+      if (result) {
+        return result.split('\n')[0]; // Take first result on Windows
+      }
+    } catch {
+      // Command not found, try next
+    }
+  }
+  return null;
+}
+
+/**
+ * Get CLI version
+ */
+export async function getCliVersion(
+  command: string,
+  args: string[],
+  timeout: number = 5000
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: 'pipe',
+      timeout,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0 && stdout) {
+        resolve(stdout.trim());
+      } else if (stderr) {
+        reject(stderr.trim());
+      } else {
+        reject(`Command exited with code ${code}`);
+      }
+    });
+
+    child.on('error', reject);
+  });
+}
+
+/**
+ * Check authentication status for a CLI
+ */
+export async function checkCliAuth(
+  provider: keyof typeof CLI_CONFIGS,
+  command: string
+): Promise<'cli' | 'api_key' | 'none'> {
+  try {
+    switch (provider) {
+      case 'claude':
+        return await checkClaudeAuth(command);
+      case 'codex':
+        return await checkCodexAuth(command);
+      case 'cursor':
+        return await checkCursorAuth(command);
+      default:
+        return 'none';
+    }
+  } catch {
+    return 'none';
+  }
+}
+
+/**
+ * Check Claude CLI authentication
+ */
+async function checkClaudeAuth(command: string): Promise<'cli' | 'api_key' | 'none'> {
+  try {
+    // Check for environment variable
+    if (process.env.ANTHROPIC_API_KEY) {
+      return 'api_key';
+    }
+
+    // Try running a simple command to check CLI auth
+    const result = await getCliVersion(command, ['--version'], 3000);
+    if (result) {
+      return 'cli'; // If version works, assume CLI is authenticated
+    }
+  } catch {
+    // Version command might work even without auth, so we need a better check
+  }
+
+  // Try a more specific auth check
+  return new Promise((resolve) => {
+    const child = spawn(command, ['whoami'], {
+      stdio: 'pipe',
+      timeout: 3000,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout?.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (code === 0 && stdout && !stderr.includes('not authenticated')) {
+        resolve('cli');
+      } else {
+        resolve('none');
+      }
+    });
+
+    child.on('error', () => {
+      resolve('none');
+    });
+  });
+}
+
+/**
+ * Check Codex CLI authentication
+ */
+async function checkCodexAuth(command: string): Promise<'cli' | 'api_key' | 'none'> {
+  // Check for environment variable
+  if (process.env.OPENAI_API_KEY) {
+    return 'api_key';
+  }
+
+  try {
+    // Try a simple auth check
+    const result = await getCliVersion(command, ['--version'], 3000);
+    if (result) {
+      return 'cli';
+    }
+  } catch {
+    // Version check failed
+  }
+
+  return 'none';
+}
+
+/**
+ * Check Cursor CLI authentication
+ */
+async function checkCursorAuth(command: string): Promise<'cli' | 'api_key' | 'none'> {
+  // Check for environment variable
+  if (process.env.CURSOR_API_KEY) {
+    return 'api_key';
+  }
+
+  // Check for credentials files
+  const credentialPaths = [
+    path.join(os.homedir(), '.cursor', 'credentials.json'),
+    path.join(os.homedir(), '.config', 'cursor', 'credentials.json'),
+    path.join(os.homedir(), '.cursor', 'auth.json'),
+    path.join(os.homedir(), '.config', 'cursor', 'auth.json'),
+  ];
+
+  for (const credPath of credentialPaths) {
+    try {
+      if (fs.existsSync(credPath)) {
+        const content = fs.readFileSync(credPath, 'utf8');
+        const creds = JSON.parse(content);
+        if (creds.accessToken || creds.token || creds.apiKey) {
+          return 'cli';
+        }
+      }
+    } catch {
+      // Invalid credentials file
+    }
+  }
+
+  // Try a simple command
+  try {
+    const result = await getCliVersion(command, ['--version'], 3000);
+    if (result) {
+      return 'cli';
+    }
+  } catch {
+    // Version check failed
+  }
+
+  return 'none';
+}
+
+/**
+ * Get installation instructions for a provider
+ */
+export function getInstallInstructions(
+  provider: keyof typeof CLI_CONFIGS,
+  platform: NodeJS.Platform = process.platform
+): string {
+  const config = CLI_CONFIGS[provider];
+  const command = config.installCommands[platform as keyof typeof config.installCommands];
+
+  if (!command) {
+    return `No installation instructions available for ${provider} on ${platform}`;
+  }
+
+  return command;
+}
+
+/**
+ * Get platform-specific CLI paths and versions
+ */
+export function getPlatformCliPaths(provider: keyof typeof CLI_CONFIGS): string[] {
+  const config = CLI_CONFIGS[provider];
+  const platform = process.platform;
+
+  switch (platform) {
+    case 'darwin':
+      return [
+        `/usr/local/bin/${config.commands[0]}`,
+        `/opt/homebrew/bin/${config.commands[0]}`,
+        path.join(os.homedir(), '.local', 'bin', config.commands[0]),
+      ];
+
+    case 'linux':
+      return [
+        `/usr/bin/${config.commands[0]}`,
+        `/usr/local/bin/${config.commands[0]}`,
+        path.join(os.homedir(), '.local', 'bin', config.commands[0]),
+        path.join(os.homedir(), '.npm', 'global', 'bin', config.commands[0]),
+      ];
+
+    case 'win32':
+      return [
+        path.join(
+          os.homedir(),
+          'AppData',
+          'Local',
+          'Programs',
+          config.commands[0],
+          `${config.commands[0]}.exe`
+        ),
+        path.join(process.env.ProgramFiles || '', config.commands[0], `${config.commands[0]}.exe`),
+        path.join(
+          process.env.ProgramFiles || '',
+          config.commands[0],
+          'bin',
+          `${config.commands[0]}.exe`
+        ),
+      ];
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Validate CLI installation
+ */
+export function validateCliInstallation(cliInfo: CliInfo): {
+  valid: boolean;
+  issues: string[];
+} {
+  const issues: string[] = [];
+
+  if (!cliInfo.installed) {
+    issues.push('CLI is not installed');
+  }
+
+  if (cliInfo.installed && !cliInfo.version) {
+    issues.push('Could not determine CLI version');
+  }
+
+  if (cliInfo.installed && cliInfo.authMethod === 'none') {
+    issues.push('CLI is not authenticated');
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+  };
+}

apps/server/src/lib/codex-auth.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared utility for checking Codex CLI authentication status
+ *
+ * Uses 'codex login status' command to verify authentication.
+ * Never assumes authenticated - only returns true if CLI confirms.
+ */
+
+import { spawnProcess } from '@automaker/platform';
+import { findCodexCliPath } from '@automaker/platform';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('CodexAuth');
+
+const CODEX_COMMAND = 'codex';
+const OPENAI_API_KEY_ENV = 'OPENAI_API_KEY';
+
+export interface CodexAuthCheckResult {
+  authenticated: boolean;
+  method: 'api_key_env' | 'cli_authenticated' | 'none';
+}
+
+/**
+ * Check Codex authentication status using 'codex login status' command
+ *
+ * @param cliPath Optional CLI path. If not provided, will attempt to find it.
+ * @returns Authentication status and method
+ */
+export async function checkCodexAuthentication(
+  cliPath?: string | null
+): Promise<CodexAuthCheckResult> {
+  const resolvedCliPath = cliPath || (await findCodexCliPath());
+  const hasApiKey = !!process.env[OPENAI_API_KEY_ENV];
+
+  // If CLI is not installed, cannot be authenticated
+  if (!resolvedCliPath) {
+    logger.info('CLI not found');
+    return { authenticated: false, method: 'none' };
+  }
+
+  try {
+    const result = await spawnProcess({
+      command: resolvedCliPath || CODEX_COMMAND,
+      args: ['login', 'status'],
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        TERM: 'dumb', // Avoid interactive output
+      },
+    });
+
+    // Check both stdout and stderr for "logged in" - Codex CLI outputs to stderr
+    const combinedOutput = (result.stdout + result.stderr).toLowerCase();
+    const isLoggedIn = combinedOutput.includes('logged in');
+
+    if (result.exitCode === 0 && isLoggedIn) {
+      // Determine auth method based on what we know
+      const method = hasApiKey ? 'api_key_env' : 'cli_authenticated';
+      logger.info(`✓ Authenticated (${method})`);
+      return { authenticated: true, method };
+    }
+
+    logger.info('Not authenticated');
+    return { authenticated: false, method: 'none' };
+  } catch (error) {
+    logger.error('Failed to check authentication:', error);
+    return { authenticated: false, method: 'none' };
+  }
+}

apps/server/src/lib/error-handler.ts

@@ -0,0 +1,414 @@
+/**
+ * Unified Error Handling System for CLI Providers
+ *
+ * Provides consistent error classification, user-friendly messages, and debugging support
+ * across all AI providers (Claude, Codex, Cursor)
+ */
+
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('ErrorHandler');
+
+export enum ErrorType {
+  AUTHENTICATION = 'authentication',
+  BILLING = 'billing',
+  RATE_LIMIT = 'rate_limit',
+  NETWORK = 'network',
+  TIMEOUT = 'timeout',
+  VALIDATION = 'validation',
+  PERMISSION = 'permission',
+  CLI_NOT_FOUND = 'cli_not_found',
+  CLI_NOT_INSTALLED = 'cli_not_installed',
+  MODEL_NOT_SUPPORTED = 'model_not_supported',
+  INVALID_REQUEST = 'invalid_request',
+  SERVER_ERROR = 'server_error',
+  UNKNOWN = 'unknown',
+}
+
+export enum ErrorSeverity {
+  LOW = 'low',
+  MEDIUM = 'medium',
+  HIGH = 'high',
+  CRITICAL = 'critical',
+}
+
+export interface ErrorClassification {
+  type: ErrorType;
+  severity: ErrorSeverity;
+  userMessage: string;
+  technicalMessage: string;
+  suggestedAction?: string;
+  retryable: boolean;
+  provider?: string;
+  context?: Record<string, any>;
+}
+
+export interface ErrorPattern {
+  type: ErrorType;
+  severity: ErrorSeverity;
+  patterns: RegExp[];
+  userMessage: string;
+  suggestedAction?: string;
+  retryable: boolean;
+}
+
+/**
+ * Error patterns for different types of errors
+ */
+const ERROR_PATTERNS: ErrorPattern[] = [
+  // Authentication errors
+  {
+    type: ErrorType.AUTHENTICATION,
+    severity: ErrorSeverity.HIGH,
+    patterns: [
+      /unauthorized/i,
+      /authentication.*fail/i,
+      /invalid_api_key/i,
+      /invalid api key/i,
+      /not authenticated/i,
+      /please.*log/i,
+      /token.*revoked/i,
+      /oauth.*error/i,
+      /credentials.*invalid/i,
+    ],
+    userMessage: 'Authentication failed. Please check your API key or login credentials.',
+    suggestedAction:
+      "Verify your API key is correct and hasn't expired, or run the CLI login command.",
+    retryable: false,
+  },
+
+  // Billing errors
+  {
+    type: ErrorType.BILLING,
+    severity: ErrorSeverity.HIGH,
+    patterns: [
+      /credit.*balance.*low/i,
+      /insufficient.*credit/i,
+      /billing.*issue/i,
+      /payment.*required/i,
+      /usage.*exceeded/i,
+      /quota.*exceeded/i,
+      /add.*credit/i,
+    ],
+    userMessage: 'Account has insufficient credits or billing issues.',
+    suggestedAction: 'Please add credits to your account or check your billing settings.',
+    retryable: false,
+  },
+
+  // Rate limit errors
+  {
+    type: ErrorType.RATE_LIMIT,
+    severity: ErrorSeverity.MEDIUM,
+    patterns: [
+      /rate.*limit/i,
+      /too.*many.*request/i,
+      /limit.*reached/i,
+      /try.*later/i,
+      /429/i,
+      /reset.*time/i,
+      /upgrade.*plan/i,
+    ],
+    userMessage: 'Rate limit reached. Please wait before trying again.',
+    suggestedAction: 'Wait a few minutes before retrying, or consider upgrading your plan.',
+    retryable: true,
+  },
+
+  // Network errors
+  {
+    type: ErrorType.NETWORK,
+    severity: ErrorSeverity.MEDIUM,
+    patterns: [/network/i, /connection/i, /dns/i, /timeout/i, /econnrefused/i, /enotfound/i],
+    userMessage: 'Network connection issue.',
+    suggestedAction: 'Check your internet connection and try again.',
+    retryable: true,
+  },
+
+  // Timeout errors
+  {
+    type: ErrorType.TIMEOUT,
+    severity: ErrorSeverity.MEDIUM,
+    patterns: [/timeout/i, /aborted/i, /time.*out/i],
+    userMessage: 'Operation timed out.',
+    suggestedAction: 'Try again with a simpler request or check your connection.',
+    retryable: true,
+  },
+
+  // Permission errors
+  {
+    type: ErrorType.PERMISSION,
+    severity: ErrorSeverity.HIGH,
+    patterns: [/permission.*denied/i, /access.*denied/i, /forbidden/i, /403/i, /not.*authorized/i],
+    userMessage: 'Permission denied.',
+    suggestedAction: 'Check if you have the required permissions for this operation.',
+    retryable: false,
+  },
+
+  // CLI not found
+  {
+    type: ErrorType.CLI_NOT_FOUND,
+    severity: ErrorSeverity.HIGH,
+    patterns: [/command not found/i, /not recognized/i, /not.*installed/i, /ENOENT/i],
+    userMessage: 'CLI tool not found.',
+    suggestedAction: "Please install the required CLI tool and ensure it's in your PATH.",
+    retryable: false,
+  },
+
+  // Model not supported
+  {
+    type: ErrorType.MODEL_NOT_SUPPORTED,
+    severity: ErrorSeverity.HIGH,
+    patterns: [/model.*not.*support/i, /unknown.*model/i, /invalid.*model/i],
+    userMessage: 'Model not supported.',
+    suggestedAction: 'Check available models and use a supported one.',
+    retryable: false,
+  },
+
+  // Server errors
+  {
+    type: ErrorType.SERVER_ERROR,
+    severity: ErrorSeverity.HIGH,
+    patterns: [/internal.*server/i, /server.*error/i, /500/i, /502/i, /503/i, /504/i],
+    userMessage: 'Server error occurred.',
+    suggestedAction: 'Try again in a few minutes or contact support if the issue persists.',
+    retryable: true,
+  },
+];
+
+/**
+ * Classify an error into a specific type with user-friendly message
+ */
+export function classifyError(
+  error: unknown,
+  provider?: string,
+  context?: Record<string, any>
+): ErrorClassification {
+  const errorText = getErrorText(error);
+
+  // Try to match against known patterns
+  for (const pattern of ERROR_PATTERNS) {
+    for (const regex of pattern.patterns) {
+      if (regex.test(errorText)) {
+        return {
+          type: pattern.type,
+          severity: pattern.severity,
+          userMessage: pattern.userMessage,
+          technicalMessage: errorText,
+          suggestedAction: pattern.suggestedAction,
+          retryable: pattern.retryable,
+          provider,
+          context,
+        };
+      }
+    }
+  }
+
+  // Unknown error
+  return {
+    type: ErrorType.UNKNOWN,
+    severity: ErrorSeverity.MEDIUM,
+    userMessage: 'An unexpected error occurred.',
+    technicalMessage: errorText,
+    suggestedAction: 'Please try again or contact support if the issue persists.',
+    retryable: true,
+    provider,
+    context,
+  };
+}
+
+/**
+ * Get a user-friendly error message
+ */
+export function getUserFriendlyErrorMessage(error: unknown, provider?: string): string {
+  const classification = classifyError(error, provider);
+
+  let message = classification.userMessage;
+
+  if (classification.suggestedAction) {
+    message += ` ${classification.suggestedAction}`;
+  }
+
+  // Add provider-specific context if available
+  if (provider) {
+    message = `[${provider.toUpperCase()}] ${message}`;
+  }
+
+  return message;
+}
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  const classification = classifyError(error);
+  return classification.retryable;
+}
+
+/**
+ * Check if an error is authentication-related
+ */
+export function isAuthenticationError(error: unknown): boolean {
+  const classification = classifyError(error);
+  return classification.type === ErrorType.AUTHENTICATION;
+}
+
+/**
+ * Check if an error is billing-related
+ */
+export function isBillingError(error: unknown): boolean {
+  const classification = classifyError(error);
+  return classification.type === ErrorType.BILLING;
+}
+
+/**
+ * Check if an error is rate limit related
+ */
+export function isRateLimitError(error: unknown): boolean {
+  const classification = classifyError(error);
+  return classification.type === ErrorType.RATE_LIMIT;
+}
+
+/**
+ * Get error text from various error types
+ */
+function getErrorText(error: unknown): string {
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === 'object' && error !== null) {
+    // Handle structured error objects
+    const errorObj = error as any;
+
+    if (errorObj.message) {
+      return errorObj.message;
+    }
+
+    if (errorObj.error?.message) {
+      return errorObj.error.message;
+    }
+
+    if (errorObj.error) {
+      return typeof errorObj.error === 'string' ? errorObj.error : JSON.stringify(errorObj.error);
+    }
+
+    return JSON.stringify(error);
+  }
+
+  return String(error);
+}
+
+/**
+ * Create a standardized error response
+ */
+export function createErrorResponse(
+  error: unknown,
+  provider?: string,
+  context?: Record<string, any>
+): {
+  success: false;
+  error: string;
+  errorType: ErrorType;
+  severity: ErrorSeverity;
+  retryable: boolean;
+  suggestedAction?: string;
+} {
+  const classification = classifyError(error, provider, context);
+
+  return {
+    success: false,
+    error: classification.userMessage,
+    errorType: classification.type,
+    severity: classification.severity,
+    retryable: classification.retryable,
+    suggestedAction: classification.suggestedAction,
+  };
+}
+
+/**
+ * Log error with full context
+ */
+export function logError(
+  error: unknown,
+  provider?: string,
+  operation?: string,
+  additionalContext?: Record<string, any>
+): void {
+  const classification = classifyError(error, provider, {
+    operation,
+    ...additionalContext,
+  });
+
+  logger.error(`Error in ${provider || 'unknown'}${operation ? ` during ${operation}` : ''}`, {
+    type: classification.type,
+    severity: classification.severity,
+    message: classification.userMessage,
+    technicalMessage: classification.technicalMessage,
+    retryable: classification.retryable,
+    suggestedAction: classification.suggestedAction,
+    context: classification.context,
+  });
+}
+
+/**
+ * Provider-specific error handlers
+ */
+export const ProviderErrorHandler = {
+  claude: {
+    classify: (error: unknown) => classifyError(error, 'claude'),
+    getUserMessage: (error: unknown) => getUserFriendlyErrorMessage(error, 'claude'),
+    isAuth: (error: unknown) => isAuthenticationError(error),
+    isBilling: (error: unknown) => isBillingError(error),
+    isRateLimit: (error: unknown) => isRateLimitError(error),
+  },
+
+  codex: {
+    classify: (error: unknown) => classifyError(error, 'codex'),
+    getUserMessage: (error: unknown) => getUserFriendlyErrorMessage(error, 'codex'),
+    isAuth: (error: unknown) => isAuthenticationError(error),
+    isBilling: (error: unknown) => isBillingError(error),
+    isRateLimit: (error: unknown) => isRateLimitError(error),
+  },
+
+  cursor: {
+    classify: (error: unknown) => classifyError(error, 'cursor'),
+    getUserMessage: (error: unknown) => getUserFriendlyErrorMessage(error, 'cursor'),
+    isAuth: (error: unknown) => isAuthenticationError(error),
+    isBilling: (error: unknown) => isBillingError(error),
+    isRateLimit: (error: unknown) => isRateLimitError(error),
+  },
+};
+
+/**
+ * Create a retry handler for retryable errors
+ */
+export function createRetryHandler(maxRetries: number = 3, baseDelay: number = 1000) {
+  return async function <T>(
+    operation: () => Promise<T>,
+    shouldRetry: (error: unknown) => boolean = isRetryableError
+  ): Promise<T> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+
+        if (attempt === maxRetries || !shouldRetry(error)) {
+          throw error;
+        }
+
+        // Exponential backoff with jitter
+        const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+        logger.debug(`Retrying operation in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+
+    throw lastError;
+  };
+}

apps/server/src/lib/events.ts

@@ -3,6 +3,9 @@
  */
 
 import type { EventType, EventCallback } from '@automaker/types';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('Events');
 
 // Re-export event types from shared package
 export type { EventType, EventCallback };
@@ -21,7 +24,7 @@ export function createEventEmitter(): EventEmitter {
         try {
           callback(type, payload);
         } catch (error) {
-          console.error('Error in event subscriber:', error);
+          logger.error('Error in event subscriber:', error);
         }
       }
     },

apps/server/src/lib/json-extractor.ts

@@ -0,0 +1,211 @@
+/**
+ * JSON Extraction Utilities
+ *
+ * Robust JSON extraction from AI responses that may contain markdown,
+ * code blocks, or other text mixed with JSON content.
+ *
+ * Used by various routes that parse structured output from Cursor or
+ * Claude responses when structured output is not available.
+ */
+
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('JsonExtractor');
+
+/**
+ * Logger interface for optional custom logging
+ */
+export interface JsonExtractorLogger {
+  debug: (message: string, ...args: unknown[]) => void;
+  warn?: (message: string, ...args: unknown[]) => void;
+}
+
+/**
+ * Options for JSON extraction
+ */
+export interface ExtractJsonOptions {
+  /** Custom logger (defaults to internal logger) */
+  logger?: JsonExtractorLogger;
+  /** Required key that must be present in the extracted JSON */
+  requiredKey?: string;
+  /** Whether the required key's value must be an array */
+  requireArray?: boolean;
+}
+
+/**
+ * Extract JSON from response text using multiple strategies.
+ *
+ * Strategies tried in order:
+ * 1. JSON in ```json code block
+ * 2. JSON in ``` code block (no language)
+ * 3. Find JSON object by matching braces (starting with requiredKey if specified)
+ * 4. Find any JSON object by matching braces
+ * 5. Parse entire response as JSON
+ *
+ * @param responseText - The raw response text that may contain JSON
+ * @param options - Optional extraction options
+ * @returns Parsed JSON object or null if extraction fails
+ */
+export function extractJson<T = Record<string, unknown>>(
+  responseText: string,
+  options: ExtractJsonOptions = {}
+): T | null {
+  const log = options.logger || logger;
+  const requiredKey = options.requiredKey;
+  const requireArray = options.requireArray ?? false;
+
+  /**
+   * Validate that the result has the required key/structure
+   */
+  const validateResult = (result: unknown): result is T => {
+    if (!result || typeof result !== 'object') return false;
+    if (requiredKey) {
+      const obj = result as Record<string, unknown>;
+      if (!(requiredKey in obj)) return false;
+      if (requireArray && !Array.isArray(obj[requiredKey])) return false;
+    }
+    return true;
+  };
+
+  /**
+   * Find matching closing brace by counting brackets
+   */
+  const findMatchingBrace = (text: string, startIdx: number): number => {
+    let depth = 0;
+    for (let i = startIdx; i < text.length; i++) {
+      if (text[i] === '{') depth++;
+      if (text[i] === '}') {
+        depth--;
+        if (depth === 0) {
+          return i + 1;
+        }
+      }
+    }
+    return -1;
+  };
+
+  const strategies = [
+    // Strategy 1: JSON in ```json code block
+    () => {
+      const match = responseText.match(/```json\s*([\s\S]*?)```/);
+      if (match) {
+        log.debug('Extracting JSON from ```json code block');
+        return JSON.parse(match[1].trim());
+      }
+      return null;
+    },
+
+    // Strategy 2: JSON in ``` code block (no language specified)
+    () => {
+      const match = responseText.match(/```\s*([\s\S]*?)```/);
+      if (match) {
+        const content = match[1].trim();
+        // Only try if it looks like JSON (starts with { or [)
+        if (content.startsWith('{') || content.startsWith('[')) {
+          log.debug('Extracting JSON from ``` code block');
+          return JSON.parse(content);
+        }
+      }
+      return null;
+    },
+
+    // Strategy 3: Find JSON object containing the required key (if specified)
+    () => {
+      if (!requiredKey) return null;
+
+      const searchPattern = `{"${requiredKey}"`;
+      const startIdx = responseText.indexOf(searchPattern);
+      if (startIdx === -1) return null;
+
+      const endIdx = findMatchingBrace(responseText, startIdx);
+      if (endIdx > startIdx) {
+        log.debug(`Extracting JSON with required key "${requiredKey}"`);
+        return JSON.parse(responseText.slice(startIdx, endIdx));
+      }
+      return null;
+    },
+
+    // Strategy 4: Find any JSON object by matching braces
+    () => {
+      const startIdx = responseText.indexOf('{');
+      if (startIdx === -1) return null;
+
+      const endIdx = findMatchingBrace(responseText, startIdx);
+      if (endIdx > startIdx) {
+        log.debug('Extracting JSON by brace matching');
+        return JSON.parse(responseText.slice(startIdx, endIdx));
+      }
+      return null;
+    },
+
+    // Strategy 5: Find JSON using first { to last } (may be less accurate)
+    () => {
+      const firstBrace = responseText.indexOf('{');
+      const lastBrace = responseText.lastIndexOf('}');
+      if (firstBrace !== -1 && lastBrace > firstBrace) {
+        log.debug('Extracting JSON from first { to last }');
+        return JSON.parse(responseText.slice(firstBrace, lastBrace + 1));
+      }
+      return null;
+    },
+
+    // Strategy 6: Try parsing the entire response as JSON
+    () => {
+      const trimmed = responseText.trim();
+      if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        log.debug('Parsing entire response as JSON');
+        return JSON.parse(trimmed);
+      }
+      return null;
+    },
+  ];
+
+  for (const strategy of strategies) {
+    try {
+      const result = strategy();
+      if (validateResult(result)) {
+        log.debug('Successfully extracted JSON');
+        return result as T;
+      }
+    } catch {
+      // Strategy failed, try next
+    }
+  }
+
+  log.debug('Failed to extract JSON from response');
+  return null;
+}
+
+/**
+ * Extract JSON with a specific required key.
+ * Convenience wrapper around extractJson.
+ *
+ * @param responseText - The raw response text
+ * @param requiredKey - Key that must be present in the extracted JSON
+ * @param options - Additional options
+ * @returns Parsed JSON object or null
+ */
+export function extractJsonWithKey<T = Record<string, unknown>>(
+  responseText: string,
+  requiredKey: string,
+  options: Omit<ExtractJsonOptions, 'requiredKey'> = {}
+): T | null {
+  return extractJson<T>(responseText, { ...options, requiredKey });
+}
+
+/**
+ * Extract JSON that has a required array property.
+ * Useful for extracting responses like { "suggestions": [...] }
+ *
+ * @param responseText - The raw response text
+ * @param arrayKey - Key that must contain an array
+ * @param options - Additional options
+ * @returns Parsed JSON object or null
+ */
+export function extractJsonWithArray<T = Record<string, unknown>>(
+  responseText: string,
+  arrayKey: string,
+  options: Omit<ExtractJsonOptions, 'requiredKey' | 'requireArray'> = {}
+): T | null {
+  return extractJson<T>(responseText, { ...options, requiredKey: arrayKey, requireArray: true });
+}

apps/server/src/lib/permission-enforcer.ts

@@ -0,0 +1,173 @@
+/**
+ * Permission enforcement utilities for Cursor provider
+ */
+
+import type { CursorCliConfigFile } from '@automaker/types';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('PermissionEnforcer');
+
+export interface PermissionCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+/**
+ * Check if a tool call is allowed based on permissions
+ */
+export function checkToolCallPermission(
+  toolCall: any,
+  permissions: CursorCliConfigFile | null
+): PermissionCheckResult {
+  if (!permissions || !permissions.permissions) {
+    // If no permissions are configured, allow everything (backward compatibility)
+    return { allowed: true };
+  }
+
+  const { allow = [], deny = [] } = permissions.permissions;
+
+  // Check shell tool calls
+  if (toolCall.shellToolCall?.args?.command) {
+    const command = toolCall.shellToolCall.args.command;
+    const toolName = `Shell(${extractCommandName(command)})`;
+
+    // Check deny list first (deny takes precedence)
+    for (const denyRule of deny) {
+      if (matchesRule(toolName, denyRule)) {
+        return {
+          allowed: false,
+          reason: `Operation blocked by permission rule: ${denyRule}`,
+        };
+      }
+    }
+
+    // Then check allow list
+    for (const allowRule of allow) {
+      if (matchesRule(toolName, allowRule)) {
+        return { allowed: true };
+      }
+    }
+
+    return {
+      allowed: false,
+      reason: `Operation not in allow list: ${toolName}`,
+    };
+  }
+
+  // Check read tool calls
+  if (toolCall.readToolCall?.args?.path) {
+    const path = toolCall.readToolCall.args.path;
+    const toolName = `Read(${path})`;
+
+    // Check deny list first
+    for (const denyRule of deny) {
+      if (matchesRule(toolName, denyRule)) {
+        return {
+          allowed: false,
+          reason: `Read operation blocked by permission rule: ${denyRule}`,
+        };
+      }
+    }
+
+    // Then check allow list
+    for (const allowRule of allow) {
+      if (matchesRule(toolName, allowRule)) {
+        return { allowed: true };
+      }
+    }
+
+    return {
+      allowed: false,
+      reason: `Read operation not in allow list: ${toolName}`,
+    };
+  }
+
+  // Check write tool calls
+  if (toolCall.writeToolCall?.args?.path) {
+    const path = toolCall.writeToolCall.args.path;
+    const toolName = `Write(${path})`;
+
+    // Check deny list first
+    for (const denyRule of deny) {
+      if (matchesRule(toolName, denyRule)) {
+        return {
+          allowed: false,
+          reason: `Write operation blocked by permission rule: ${denyRule}`,
+        };
+      }
+    }
+
+    // Then check allow list
+    for (const allowRule of allow) {
+      if (matchesRule(toolName, allowRule)) {
+        return { allowed: true };
+      }
+    }
+
+    return {
+      allowed: false,
+      reason: `Write operation not in allow list: ${toolName}`,
+    };
+  }
+
+  // For other tool types, allow by default for now
+  return { allowed: true };
+}
+
+/**
+ * Extract the base command name from a shell command
+ */
+function extractCommandName(command: string): string {
+  // Remove leading spaces and get the first word
+  const trimmed = command.trim();
+  const firstWord = trimmed.split(/\s+/)[0];
+  return firstWord || 'unknown';
+}
+
+/**
+ * Check if a tool name matches a permission rule
+ */
+function matchesRule(toolName: string, rule: string): boolean {
+  // Exact match
+  if (toolName === rule) {
+    return true;
+  }
+
+  // Wildcard patterns
+  if (rule.includes('*')) {
+    const regex = new RegExp(rule.replace(/\*/g, '.*'));
+    return regex.test(toolName);
+  }
+
+  // Prefix match for shell commands (e.g., "Shell(git)" matches "Shell(git status)")
+  if (rule.startsWith('Shell(') && toolName.startsWith('Shell(')) {
+    const ruleCommand = rule.slice(6, -1); // Remove "Shell(" and ")"
+    const toolCommand = extractCommandName(toolName.slice(6, -1)); // Remove "Shell(" and ")"
+    return toolCommand.startsWith(ruleCommand);
+  }
+
+  return false;
+}
+
+/**
+ * Log permission violations
+ */
+export function logPermissionViolation(toolCall: any, reason: string, sessionId?: string): void {
+  const sessionIdStr = sessionId ? ` [${sessionId}]` : '';
+
+  if (toolCall.shellToolCall?.args?.command) {
+    logger.warn(
+      `Permission violation${sessionIdStr}: Shell command blocked - ${toolCall.shellToolCall.args.command} (${reason})`
+    );
+  } else if (toolCall.readToolCall?.args?.path) {
+    logger.warn(
+      `Permission violation${sessionIdStr}: Read operation blocked - ${toolCall.readToolCall.args.path} (${reason})`
+    );
+  } else if (toolCall.writeToolCall?.args?.path) {
+    logger.warn(
+      `Permission violation${sessionIdStr}: Write operation blocked - ${toolCall.writeToolCall.args.path} (${reason})`
+    );
+  } else {
+    logger.warn(`Permission violation${sessionIdStr}: Tool call blocked (${reason})`, { toolCall });
+  }
+}

apps/server/src/lib/sdk-options.ts

@@ -18,9 +18,80 @@
 import type { Options } from '@anthropic-ai/claude-agent-sdk';
 import path from 'path';
 import { resolveModelString } from '@automaker/model-resolver';
-import { DEFAULT_MODELS, CLAUDE_MODEL_MAP } from '@automaker/types';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('SdkOptions');
+import {
+  DEFAULT_MODELS,
+  CLAUDE_MODEL_MAP,
+  type McpServerConfig,
+  type ThinkingLevel,
+  getThinkingTokenBudget,
+} from '@automaker/types';
 import { isPathAllowed, PathNotAllowedError, getAllowedRootDirectory } from '@automaker/platform';
 
+/**
+ * Result of sandbox compatibility check
+ */
+export interface SandboxCompatibilityResult {
+  /** Whether sandbox mode can be enabled for this path */
+  enabled: boolean;
+  /** Optional message explaining why sandbox is disabled */
+  message?: string;
+}
+
+/**
+ * Check if a working directory is compatible with sandbox mode.
+ * Some paths (like cloud storage mounts) may not work with sandboxed execution.
+ *
+ * @param cwd - The working directory to check
+ * @param sandboxRequested - Whether sandbox mode was requested by settings
+ * @returns Object indicating if sandbox can be enabled and why not if disabled
+ */
+export function checkSandboxCompatibility(
+  cwd: string,
+  sandboxRequested: boolean
+): SandboxCompatibilityResult {
+  if (!sandboxRequested) {
+    return { enabled: false };
+  }
+
+  const resolvedCwd = path.resolve(cwd);
+
+  // Check for cloud storage paths that may not be compatible with sandbox
+  const cloudStoragePatterns = [
+    // macOS mounted volumes
+    /^\/Volumes\/GoogleDrive/i,
+    /^\/Volumes\/Dropbox/i,
+    /^\/Volumes\/OneDrive/i,
+    /^\/Volumes\/iCloud/i,
+    // macOS home directory
+    /^\/Users\/[^/]+\/Google Drive/i,
+    /^\/Users\/[^/]+\/Dropbox/i,
+    /^\/Users\/[^/]+\/OneDrive/i,
+    /^\/Users\/[^/]+\/Library\/Mobile Documents/i, // iCloud
+    // Linux home directory
+    /^\/home\/[^/]+\/Google Drive/i,
+    /^\/home\/[^/]+\/Dropbox/i,
+    /^\/home\/[^/]+\/OneDrive/i,
+    // Windows
+    /^C:\\Users\\[^\\]+\\Google Drive/i,
+    /^C:\\Users\\[^\\]+\\Dropbox/i,
+    /^C:\\Users\\[^\\]+\\OneDrive/i,
+  ];
+
+  for (const pattern of cloudStoragePatterns) {
+    if (pattern.test(resolvedCwd)) {
+      return {
+        enabled: false,
+        message: `Sandbox disabled: Cloud storage path detected (${resolvedCwd}). Sandbox mode may not work correctly with cloud-synced directories.`,
+      };
+    }
+  }
+
+  return { enabled: true };
+}
+
 /**
  * Validate that a working directory is allowed by ALLOWED_ROOT_DIRECTORY.
  * This is the centralized security check for ALL AI model invocations.
@@ -129,13 +200,104 @@ export function getModelForUseCase(
 
 /**
  * Base options that apply to all SDK calls
+ * AUTONOMOUS MODE: Always bypass permissions for fully autonomous operation
  */
 function getBaseOptions(): Partial<Options> {
   return {
-    permissionMode: 'acceptEdits',
+    permissionMode: 'bypassPermissions',
+    allowDangerouslySkipPermissions: true,
   };
 }
 
+/**
+ * MCP options result
+ */
+interface McpOptions {
+  /** Options to spread for MCP servers */
+  mcpServerOptions: Partial<Options>;
+}
+
+/**
+ * Build MCP-related options based on configuration.
+ *
+ * @param config - The SDK options config
+ * @returns Object with MCP server settings to spread into final options
+ */
+function buildMcpOptions(config: CreateSdkOptionsConfig): McpOptions {
+  return {
+    // Include MCP servers if configured
+    mcpServerOptions: config.mcpServers ? { mcpServers: config.mcpServers } : {},
+  };
+}
+
+/**
+ * Build thinking options for SDK configuration.
+ * Converts ThinkingLevel to maxThinkingTokens for the Claude SDK.
+ *
+ * @param thinkingLevel - The thinking level to convert
+ * @returns Object with maxThinkingTokens if thinking is enabled
+ */
+function buildThinkingOptions(thinkingLevel?: ThinkingLevel): Partial<Options> {
+  const maxThinkingTokens = getThinkingTokenBudget(thinkingLevel);
+  logger.debug(
+    `buildThinkingOptions: thinkingLevel="${thinkingLevel}" -> maxThinkingTokens=${maxThinkingTokens}`
+  );
+  return maxThinkingTokens ? { maxThinkingTokens } : {};
+}
+
+/**
+ * Build system prompt configuration based on autoLoadClaudeMd setting.
+ * When autoLoadClaudeMd is true:
+ * - Uses preset mode with 'claude_code' to enable CLAUDE.md auto-loading
+ * - If there's a custom systemPrompt, appends it to the preset
+ * - Sets settingSources to ['project'] for SDK to load CLAUDE.md files
+ *
+ * @param config - The SDK options config
+ * @returns Object with systemPrompt and settingSources for SDK options
+ */
+function buildClaudeMdOptions(config: CreateSdkOptionsConfig): {
+  systemPrompt?: string | SystemPromptConfig;
+  settingSources?: Array<'user' | 'project' | 'local'>;
+} {
+  if (!config.autoLoadClaudeMd) {
+    // Standard mode - just pass through the system prompt as-is
+    return config.systemPrompt ? { systemPrompt: config.systemPrompt } : {};
+  }
+
+  // Auto-load CLAUDE.md mode - use preset with settingSources
+  const result: {
+    systemPrompt: SystemPromptConfig;
+    settingSources: Array<'user' | 'project' | 'local'>;
+  } = {
+    systemPrompt: {
+      type: 'preset',
+      preset: 'claude_code',
+    },
+    // Load both user (~/.claude/CLAUDE.md) and project (.claude/CLAUDE.md) settings
+    settingSources: ['user', 'project'],
+  };
+
+  // If there's a custom system prompt, append it to the preset
+  if (config.systemPrompt) {
+    result.systemPrompt.append = config.systemPrompt;
+  }
+
+  return result;
+}
+
+/**
+ * System prompt configuration for SDK options
+ * When using preset mode with claude_code, CLAUDE.md files are automatically loaded
+ */
+export interface SystemPromptConfig {
+  /** Use preset mode with claude_code to enable CLAUDE.md auto-loading */
+  type: 'preset';
+  /** The preset to use - 'claude_code' enables CLAUDE.md loading */
+  preset: 'claude_code';
+  /** Optional additional prompt to append to the preset */
+  append?: string;
+}
+
 /**
  * Options configuration for creating SDK options
  */
@@ -160,8 +322,25 @@ export interface CreateSdkOptionsConfig {
     type: 'json_schema';
     schema: Record<string, unknown>;
   };
+
+  /** Enable auto-loading of CLAUDE.md files via SDK's settingSources */
+  autoLoadClaudeMd?: boolean;
+
+  /** MCP servers to make available to the agent */
+  mcpServers?: Record<string, McpServerConfig>;
+
+  /** Extended thinking level for Claude models */
+  thinkingLevel?: ThinkingLevel;
 }
 
+// Re-export MCP types from @automaker/types for convenience
+export type {
+  McpServerConfig,
+  McpStdioServerConfig,
+  McpSSEServerConfig,
+  McpHttpServerConfig,
+} from '@automaker/types';
+
 /**
  * Create SDK options for spec generation
  *
@@ -169,11 +348,18 @@ export interface CreateSdkOptionsConfig {
  * - Uses read-only tools for codebase analysis
  * - Extended turns for thorough exploration
  * - Opus model by default (can be overridden)
+ * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createSpecGenerationOptions(config: CreateSdkOptionsConfig): Options {
   // Validate working directory before creating options
   validateWorkingDirectory(config.cwd);
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
   return {
     ...getBaseOptions(),
     // Override permissionMode - spec generation only needs read-only tools
@@ -184,7 +370,8 @@ export function createSpecGenerationOptions(config: CreateSdkOptionsConfig): Opt
     maxTurns: MAX_TURNS.maximum,
     cwd: config.cwd,
     allowedTools: [...TOOL_PRESETS.specGeneration],
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
     ...(config.outputFormat && { outputFormat: config.outputFormat }),
   };
@@ -197,11 +384,18 @@ export function createSpecGenerationOptions(config: CreateSdkOptionsConfig): Opt
  * - Uses read-only tools (just needs to read the spec)
  * - Quick turns since it's mostly JSON generation
  * - Sonnet model by default for speed
+ * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createFeatureGenerationOptions(config: CreateSdkOptionsConfig): Options {
   // Validate working directory before creating options
   validateWorkingDirectory(config.cwd);
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
   return {
     ...getBaseOptions(),
     // Override permissionMode - feature generation only needs read-only tools
@@ -210,7 +404,8 @@ export function createFeatureGenerationOptions(config: CreateSdkOptionsConfig):
     maxTurns: MAX_TURNS.quick,
     cwd: config.cwd,
     allowedTools: [...TOOL_PRESETS.readOnly],
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
   };
 }
@@ -222,18 +417,26 @@ export function createFeatureGenerationOptions(config: CreateSdkOptionsConfig):
  * - Uses read-only tools for analysis
  * - Standard turns to allow thorough codebase exploration and structured output generation
  * - Opus model by default for thorough analysis
+ * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createSuggestionsOptions(config: CreateSdkOptionsConfig): Options {
   // Validate working directory before creating options
   validateWorkingDirectory(config.cwd);
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('suggestions', config.model),
     maxTurns: MAX_TURNS.extended,
     cwd: config.cwd,
     allowedTools: [...TOOL_PRESETS.readOnly],
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
     ...(config.outputFormat && { outputFormat: config.outputFormat }),
   };
@@ -246,7 +449,7 @@ export function createSuggestionsOptions(config: CreateSdkOptionsConfig): Option
  * - Full tool access for code modification
  * - Standard turns for interactive sessions
  * - Model priority: explicit model > session model > chat default
- * - Sandbox enabled for bash safety
+ * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createChatOptions(config: CreateSdkOptionsConfig): Options {
   // Validate working directory before creating options
@@ -255,18 +458,25 @@ export function createChatOptions(config: CreateSdkOptionsConfig): Options {
   // Model priority: explicit model > session model > chat default
   const effectiveModel = config.model || config.sessionModel;
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('chat', effectiveModel),
     maxTurns: MAX_TURNS.standard,
     cwd: config.cwd,
     allowedTools: [...TOOL_PRESETS.chat],
-    sandbox: {
-      enabled: true,
-      autoAllowBashIfSandboxed: true,
-    },
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }
 
@@ -277,24 +487,31 @@ export function createChatOptions(config: CreateSdkOptionsConfig): Options {
  * - Full tool access for code modification and implementation
  * - Extended turns for thorough feature implementation
  * - Uses default model (can be overridden)
- * - Sandbox enabled for bash safety
+ * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createAutoModeOptions(config: CreateSdkOptionsConfig): Options {
   // Validate working directory before creating options
   validateWorkingDirectory(config.cwd);
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('auto', config.model),
     maxTurns: MAX_TURNS.maximum,
     cwd: config.cwd,
     allowedTools: [...TOOL_PRESETS.fullAccess],
-    sandbox: {
-      enabled: true,
-      autoAllowBashIfSandboxed: true,
-    },
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }
 
@@ -302,25 +519,40 @@ export function createAutoModeOptions(config: CreateSdkOptionsConfig): Options {
  * Create custom SDK options with explicit configuration
  *
  * Use this when the preset options don't fit your use case.
+ * When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createCustomOptions(
   config: CreateSdkOptionsConfig & {
     maxTurns?: number;
     allowedTools?: readonly string[];
-    sandbox?: { enabled: boolean; autoAllowBashIfSandboxed?: boolean };
   }
 ): Options {
   // Validate working directory before creating options
   validateWorkingDirectory(config.cwd);
 
+  // Build CLAUDE.md auto-loading options if enabled
+  const claudeMdOptions = buildClaudeMdOptions(config);
+
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
+  // Build thinking options
+  const thinkingOptions = buildThinkingOptions(config.thinkingLevel);
+
+  // For custom options: use explicit allowedTools if provided, otherwise default to readOnly
+  const effectiveAllowedTools = config.allowedTools
+    ? [...config.allowedTools]
+    : [...TOOL_PRESETS.readOnly];
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('default', config.model),
     maxTurns: config.maxTurns ?? MAX_TURNS.maximum,
     cwd: config.cwd,
-    allowedTools: config.allowedTools ? [...config.allowedTools] : [...TOOL_PRESETS.readOnly],
-    ...(config.sandbox && { sandbox: config.sandbox }),
-    ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    allowedTools: effectiveAllowedTools,
+    ...claudeMdOptions,
+    ...thinkingOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }

apps/server/src/lib/secure-fs.ts

@@ -6,6 +6,7 @@
 import { secureFs } from '@automaker/platform';
 
 export const {
+  // Async methods
   access,
   readFile,
   writeFile,
@@ -20,4 +21,19 @@ export const {
   lstat,
   joinPath,
   resolvePath,
+  // Sync methods
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  accessSync,
+  unlinkSync,
+  rmSync,
+  // Throttling configuration and monitoring
+  configureThrottling,
+  getThrottlingConfig,
+  getPendingOperations,
+  getActiveOperations,
 } = secureFs;

apps/server/src/lib/settings-helpers.ts

@@ -0,0 +1,323 @@
+/**
+ * Helper utilities for loading settings and context file handling across different parts of the server
+ */
+
+import type { SettingsService } from '../services/settings-service.js';
+import type { ContextFilesResult, ContextFileInfo } from '@automaker/utils';
+import { createLogger } from '@automaker/utils';
+import type { MCPServerConfig, McpServerConfig, PromptCustomization } from '@automaker/types';
+import {
+  mergeAutoModePrompts,
+  mergeAgentPrompts,
+  mergeBacklogPlanPrompts,
+  mergeEnhancementPrompts,
+} from '@automaker/prompts';
+
+const logger = createLogger('SettingsHelper');
+
+/**
+ * Get the autoLoadClaudeMd setting, with project settings taking precedence over global.
+ * Returns false if settings service is not available.
+ *
+ * @param projectPath - Path to the project
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages (e.g., '[DescribeImage]')
+ * @returns Promise resolving to the autoLoadClaudeMd setting value
+ */
+export async function getAutoLoadClaudeMdSetting(
+  projectPath: string,
+  settingsService?: SettingsService | null,
+  logPrefix = '[SettingsHelper]'
+): Promise<boolean> {
+  if (!settingsService) {
+    logger.info(`${logPrefix} SettingsService not available, autoLoadClaudeMd disabled`);
+    return false;
+  }
+
+  try {
+    // Check project settings first (takes precedence)
+    const projectSettings = await settingsService.getProjectSettings(projectPath);
+    if (projectSettings.autoLoadClaudeMd !== undefined) {
+      logger.info(
+        `${logPrefix} autoLoadClaudeMd from project settings: ${projectSettings.autoLoadClaudeMd}`
+      );
+      return projectSettings.autoLoadClaudeMd;
+    }
+
+    // Fall back to global settings
+    const globalSettings = await settingsService.getGlobalSettings();
+    const result = globalSettings.autoLoadClaudeMd ?? false;
+    logger.info(`${logPrefix} autoLoadClaudeMd from global settings: ${result}`);
+    return result;
+  } catch (error) {
+    logger.error(`${logPrefix} Failed to load autoLoadClaudeMd setting:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Filters out CLAUDE.md from context files when autoLoadClaudeMd is enabled
+ * and rebuilds the formatted prompt without it.
+ *
+ * When autoLoadClaudeMd is true, the SDK handles CLAUDE.md loading via settingSources,
+ * so we need to exclude it from the manual context loading to avoid duplication.
+ * Other context files (CODE_QUALITY.md, CONVENTIONS.md, etc.) are preserved.
+ *
+ * @param contextResult - Result from loadContextFiles
+ * @param autoLoadClaudeMd - Whether SDK auto-loading is enabled
+ * @returns Filtered context prompt (empty string if no non-CLAUDE.md files)
+ */
+export function filterClaudeMdFromContext(
+  contextResult: ContextFilesResult,
+  autoLoadClaudeMd: boolean
+): string {
+  // If autoLoadClaudeMd is disabled, return the original prompt unchanged
+  if (!autoLoadClaudeMd || contextResult.files.length === 0) {
+    return contextResult.formattedPrompt;
+  }
+
+  // Filter out CLAUDE.md (case-insensitive)
+  const nonClaudeFiles = contextResult.files.filter((f) => f.name.toLowerCase() !== 'claude.md');
+
+  // If all files were CLAUDE.md, return empty string
+  if (nonClaudeFiles.length === 0) {
+    return '';
+  }
+
+  // Rebuild prompt without CLAUDE.md using the same format as loadContextFiles
+  const formattedFiles = nonClaudeFiles.map((file) => formatContextFileEntry(file));
+
+  return `# Project Context Files
+
+The following context files provide project-specific rules, conventions, and guidelines.
+Each file serves a specific purpose - use the description to understand when to reference it.
+If you need more details about a context file, you can read the full file at the path provided.
+
+**IMPORTANT**: You MUST follow the rules and conventions specified in these files.
+- Follow ALL commands exactly as shown (e.g., if the project uses \`pnpm\`, NEVER use \`npm\` or \`npx\`)
+- Follow ALL coding conventions, commit message formats, and architectural patterns specified
+- Reference these rules before running ANY shell commands or making commits
+
+---
+
+${formattedFiles.join('\n\n---\n\n')}
+
+---
+
+**REMINDER**: Before taking any action, verify you are following the conventions specified above.
+`;
+}
+
+/**
+ * Format a single context file entry for the prompt
+ * (Matches the format used in @automaker/utils/context-loader.ts)
+ */
+function formatContextFileEntry(file: ContextFileInfo): string {
+  const header = `## ${file.name}`;
+  const pathInfo = `**Path:** \`${file.path}\``;
+  const descriptionInfo = file.description ? `\n**Purpose:** ${file.description}` : '';
+  return `${header}\n${pathInfo}${descriptionInfo}\n\n${file.content}`;
+}
+
+/**
+ * Get enabled MCP servers from global settings, converted to SDK format.
+ * Returns an empty object if settings service is not available or no servers are configured.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages (e.g., '[AgentService]')
+ * @returns Promise resolving to MCP servers in SDK format (keyed by name)
+ */
+export async function getMCPServersFromSettings(
+  settingsService?: SettingsService | null,
+  logPrefix = '[SettingsHelper]'
+): Promise<Record<string, McpServerConfig>> {
+  if (!settingsService) {
+    return {};
+  }
+
+  try {
+    const globalSettings = await settingsService.getGlobalSettings();
+    const mcpServers = globalSettings.mcpServers || [];
+
+    // Filter to only enabled servers and convert to SDK format
+    const enabledServers = mcpServers.filter((s) => s.enabled !== false);
+
+    if (enabledServers.length === 0) {
+      return {};
+    }
+
+    // Convert settings format to SDK format (keyed by name)
+    const sdkServers: Record<string, McpServerConfig> = {};
+    for (const server of enabledServers) {
+      sdkServers[server.name] = convertToSdkFormat(server);
+    }
+
+    logger.info(
+      `${logPrefix} Loaded ${enabledServers.length} MCP server(s): ${enabledServers.map((s) => s.name).join(', ')}`
+    );
+
+    return sdkServers;
+  } catch (error) {
+    logger.error(`${logPrefix} Failed to load MCP servers setting:`, error);
+    return {};
+  }
+}
+
+/**
+ * Convert a settings MCPServerConfig to SDK McpServerConfig format.
+ * Validates required fields and throws informative errors if missing.
+ */
+function convertToSdkFormat(server: MCPServerConfig): McpServerConfig {
+  if (server.type === 'sse') {
+    if (!server.url) {
+      throw new Error(`SSE MCP server "${server.name}" is missing a URL.`);
+    }
+    return {
+      type: 'sse',
+      url: server.url,
+      headers: server.headers,
+    };
+  }
+
+  if (server.type === 'http') {
+    if (!server.url) {
+      throw new Error(`HTTP MCP server "${server.name}" is missing a URL.`);
+    }
+    return {
+      type: 'http',
+      url: server.url,
+      headers: server.headers,
+    };
+  }
+
+  // Default to stdio
+  if (!server.command) {
+    throw new Error(`Stdio MCP server "${server.name}" is missing a command.`);
+  }
+  return {
+    type: 'stdio',
+    command: server.command,
+    args: server.args,
+    env: server.env,
+  };
+}
+
+/**
+ * Get prompt customization from global settings and merge with defaults.
+ * Returns prompts merged with built-in defaults - custom prompts override defaults.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages
+ * @returns Promise resolving to merged prompts for all categories
+ */
+export async function getPromptCustomization(
+  settingsService?: SettingsService | null,
+  logPrefix = '[PromptHelper]'
+): Promise<{
+  autoMode: ReturnType<typeof mergeAutoModePrompts>;
+  agent: ReturnType<typeof mergeAgentPrompts>;
+  backlogPlan: ReturnType<typeof mergeBacklogPlanPrompts>;
+  enhancement: ReturnType<typeof mergeEnhancementPrompts>;
+}> {
+  let customization: PromptCustomization = {};
+
+  if (settingsService) {
+    try {
+      const globalSettings = await settingsService.getGlobalSettings();
+      customization = globalSettings.promptCustomization || {};
+      logger.info(`${logPrefix} Loaded prompt customization from settings`);
+    } catch (error) {
+      logger.error(`${logPrefix} Failed to load prompt customization:`, error);
+      // Fall through to use empty customization (all defaults)
+    }
+  } else {
+    logger.info(`${logPrefix} SettingsService not available, using default prompts`);
+  }
+
+  return {
+    autoMode: mergeAutoModePrompts(customization.autoMode),
+    agent: mergeAgentPrompts(customization.agent),
+    backlogPlan: mergeBacklogPlanPrompts(customization.backlogPlan),
+    enhancement: mergeEnhancementPrompts(customization.enhancement),
+  };
+}
+
+/**
+ * Get Skills configuration from settings.
+ * Returns configuration for enabling skills and which sources to load from.
+ *
+ * @param settingsService - Settings service instance
+ * @returns Skills configuration with enabled state, sources, and tool inclusion flag
+ */
+export async function getSkillsConfiguration(settingsService: SettingsService): Promise<{
+  enabled: boolean;
+  sources: Array<'user' | 'project'>;
+  shouldIncludeInTools: boolean;
+}> {
+  const settings = await settingsService.getGlobalSettings();
+  const enabled = settings.enableSkills ?? true; // Default enabled
+  const sources = settings.skillsSources ?? ['user', 'project']; // Default both sources
+
+  return {
+    enabled,
+    sources,
+    shouldIncludeInTools: enabled && sources.length > 0,
+  };
+}
+
+/**
+ * Get Subagents configuration from settings.
+ * Returns configuration for enabling subagents and which sources to load from.
+ *
+ * @param settingsService - Settings service instance
+ * @returns Subagents configuration with enabled state, sources, and tool inclusion flag
+ */
+export async function getSubagentsConfiguration(settingsService: SettingsService): Promise<{
+  enabled: boolean;
+  sources: Array<'user' | 'project'>;
+  shouldIncludeInTools: boolean;
+}> {
+  const settings = await settingsService.getGlobalSettings();
+  const enabled = settings.enableSubagents ?? true; // Default enabled
+  const sources = settings.subagentsSources ?? ['user', 'project']; // Default both sources
+
+  return {
+    enabled,
+    sources,
+    shouldIncludeInTools: enabled && sources.length > 0,
+  };
+}
+
+/**
+ * Get custom subagents from settings, merging global and project-level definitions.
+ * Project-level subagents take precedence over global ones with the same name.
+ *
+ * @param settingsService - Settings service instance
+ * @param projectPath - Path to the project for loading project-specific subagents
+ * @returns Record of agent names to definitions, or undefined if none configured
+ */
+export async function getCustomSubagents(
+  settingsService: SettingsService,
+  projectPath?: string
+): Promise<Record<string, import('@automaker/types').AgentDefinition> | undefined> {
+  // Get global subagents
+  const globalSettings = await settingsService.getGlobalSettings();
+  const globalSubagents = globalSettings.customSubagents || {};
+
+  // If no project path, return only global subagents
+  if (!projectPath) {
+    return Object.keys(globalSubagents).length > 0 ? globalSubagents : undefined;
+  }
+
+  // Get project-specific subagents
+  const projectSettings = await settingsService.getProjectSettings(projectPath);
+  const projectSubagents = projectSettings.customSubagents || {};
+
+  // Merge: project-level takes precedence
+  const merged = {
+    ...globalSubagents,
+    ...projectSubagents,
+  };
+
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}

apps/server/src/lib/validation-storage.ts

@@ -0,0 +1,181 @@
+/**
+ * Validation Storage - CRUD operations for GitHub issue validation results
+ *
+ * Stores validation results in .automaker/validations/{issueNumber}/validation.json
+ * Results include the validation verdict, metadata, and timestamp for cache invalidation.
+ */
+
+import * as secureFs from './secure-fs.js';
+import { getValidationsDir, getValidationDir, getValidationPath } from '@automaker/platform';
+import type { StoredValidation } from '@automaker/types';
+
+// Re-export StoredValidation for convenience
+export type { StoredValidation };
+
+/** Number of hours before a validation is considered stale */
+const VALIDATION_CACHE_TTL_HOURS = 24;
+
+/**
+ * Write validation result to storage
+ *
+ * Creates the validation directory if needed and stores the result as JSON.
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param issueNumber - GitHub issue number
+ * @param data - Validation data to store
+ */
+export async function writeValidation(
+  projectPath: string,
+  issueNumber: number,
+  data: StoredValidation
+): Promise<void> {
+  const validationDir = getValidationDir(projectPath, issueNumber);
+  const validationPath = getValidationPath(projectPath, issueNumber);
+
+  // Ensure directory exists
+  await secureFs.mkdir(validationDir, { recursive: true });
+
+  // Write validation result
+  await secureFs.writeFile(validationPath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Read validation result from storage
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param issueNumber - GitHub issue number
+ * @returns Stored validation or null if not found
+ */
+export async function readValidation(
+  projectPath: string,
+  issueNumber: number
+): Promise<StoredValidation | null> {
+  try {
+    const validationPath = getValidationPath(projectPath, issueNumber);
+    const content = (await secureFs.readFile(validationPath, 'utf-8')) as string;
+    return JSON.parse(content) as StoredValidation;
+  } catch {
+    // File doesn't exist or can't be read
+    return null;
+  }
+}
+
+/**
+ * Get all stored validations for a project
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Array of stored validations
+ */
+export async function getAllValidations(projectPath: string): Promise<StoredValidation[]> {
+  const validationsDir = getValidationsDir(projectPath);
+
+  try {
+    const dirs = await secureFs.readdir(validationsDir, { withFileTypes: true });
+
+    // Read all validation files in parallel for better performance
+    const promises = dirs
+      .filter((dir) => dir.isDirectory())
+      .map((dir) => {
+        const issueNumber = parseInt(dir.name, 10);
+        if (!isNaN(issueNumber)) {
+          return readValidation(projectPath, issueNumber);
+        }
+        return Promise.resolve(null);
+      });
+
+    const results = await Promise.all(promises);
+    const validations = results.filter((v): v is StoredValidation => v !== null);
+
+    // Sort by issue number
+    validations.sort((a, b) => a.issueNumber - b.issueNumber);
+
+    return validations;
+  } catch {
+    // Directory doesn't exist
+    return [];
+  }
+}
+
+/**
+ * Delete a validation from storage
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param issueNumber - GitHub issue number
+ * @returns true if validation was deleted, false if not found
+ */
+export async function deleteValidation(projectPath: string, issueNumber: number): Promise<boolean> {
+  try {
+    const validationDir = getValidationDir(projectPath, issueNumber);
+    await secureFs.rm(validationDir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a validation is stale (older than TTL)
+ *
+ * @param validation - Stored validation to check
+ * @returns true if validation is older than 24 hours
+ */
+export function isValidationStale(validation: StoredValidation): boolean {
+  const validatedAt = new Date(validation.validatedAt);
+  const now = new Date();
+  const hoursDiff = (now.getTime() - validatedAt.getTime()) / (1000 * 60 * 60);
+  return hoursDiff > VALIDATION_CACHE_TTL_HOURS;
+}
+
+/**
+ * Get validation with freshness info
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param issueNumber - GitHub issue number
+ * @returns Object with validation and isStale flag, or null if not found
+ */
+export async function getValidationWithFreshness(
+  projectPath: string,
+  issueNumber: number
+): Promise<{ validation: StoredValidation; isStale: boolean } | null> {
+  const validation = await readValidation(projectPath, issueNumber);
+  if (!validation) {
+    return null;
+  }
+
+  return {
+    validation,
+    isStale: isValidationStale(validation),
+  };
+}
+
+/**
+ * Mark a validation as viewed by the user
+ *
+ * @param projectPath - Absolute path to project directory
+ * @param issueNumber - GitHub issue number
+ * @returns true if validation was marked as viewed, false if not found
+ */
+export async function markValidationViewed(
+  projectPath: string,
+  issueNumber: number
+): Promise<boolean> {
+  const validation = await readValidation(projectPath, issueNumber);
+  if (!validation) {
+    return false;
+  }
+
+  validation.viewedAt = new Date().toISOString();
+  await writeValidation(projectPath, issueNumber, validation);
+  return true;
+}
+
+/**
+ * Get count of unviewed, non-stale validations for a project
+ *
+ * @param projectPath - Absolute path to project directory
+ * @returns Number of unviewed validations
+ */
+export async function getUnviewedValidationsCount(projectPath: string): Promise<number> {
+  const validations = await getAllValidations(projectPath);
+  return validations.filter((v) => !v.viewedAt && !isValidationStale(v)).length;
+}

apps/server/src/lib/version.ts

@@ -0,0 +1,36 @@
+/**
+ * Version utility - Reads version from package.json
+ */
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('Version');
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+let cachedVersion: string | null = null;
+
+/**
+ * Get the version from package.json
+ * Caches the result for performance
+ */
+export function getVersion(): string {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+
+  try {
+    const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const version = packageJson.version || '0.0.0';
+    cachedVersion = version;
+    return version;
+  } catch (error) {
+    logger.warn('Failed to read version from package.json:', error);
+    return '0.0.0';
+  }
+}

apps/server/src/middleware/require-json-content-type.ts

@@ -0,0 +1,50 @@
+/**
+ * Middleware to enforce Content-Type: application/json for request bodies
+ *
+ * This security middleware prevents malicious requests by requiring proper
+ * Content-Type headers for all POST, PUT, and PATCH requests.
+ *
+ * Rejecting requests without proper Content-Type helps prevent:
+ * - CSRF attacks via form submissions (which use application/x-www-form-urlencoded)
+ * - Content-type confusion attacks
+ * - Malformed request exploitation
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+
+// HTTP methods that typically include request bodies
+const METHODS_REQUIRING_JSON = ['POST', 'PUT', 'PATCH'];
+
+/**
+ * Middleware that requires Content-Type: application/json for POST/PUT/PATCH requests
+ *
+ * Returns 415 Unsupported Media Type if:
+ * - The request method is POST, PUT, or PATCH
+ * - AND the Content-Type header is missing or not application/json
+ *
+ * Allows requests to pass through if:
+ * - The request method is GET, DELETE, OPTIONS, HEAD, etc.
+ * - OR the Content-Type is properly set to application/json (with optional charset)
+ */
+export function requireJsonContentType(req: Request, res: Response, next: NextFunction): void {
+  // Skip validation for methods that don't require a body
+  if (!METHODS_REQUIRING_JSON.includes(req.method)) {
+    next();
+    return;
+  }
+
+  const contentType = req.headers['content-type'];
+
+  // Check if Content-Type header exists and contains application/json
+  // Allows for charset parameter: "application/json; charset=utf-8"
+  if (!contentType || !contentType.toLowerCase().includes('application/json')) {
+    res.status(415).json({
+      success: false,
+      error: 'Unsupported Media Type',
+      message: 'Content-Type header must be application/json',
+    });
+    return;
+  }
+
+  next();
+}

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

@@ -7,6 +7,10 @@
 
 import { query, type Options } from '@anthropic-ai/claude-agent-sdk';
 import { BaseProvider } from './base-provider.js';
+import { classifyError, getUserFriendlyErrorMessage, createLogger } from '@automaker/utils';
+
+const logger = createLogger('ClaudeProvider');
+import { getThinkingTokenBudget, validateBareModelId } from '@automaker/types';
 import type {
   ExecuteOptions,
   ProviderMessage,
@@ -14,6 +18,32 @@ import type {
   ModelDefinition,
 } from './types.js';
 
+// Explicit allowlist of environment variables to pass to the SDK.
+// Only these vars are passed - nothing else from process.env leaks through.
+const ALLOWED_ENV_VARS = [
+  'ANTHROPIC_API_KEY',
+  'PATH',
+  'HOME',
+  'SHELL',
+  'TERM',
+  'USER',
+  'LANG',
+  'LC_ALL',
+];
+
+/**
+ * Build environment for the SDK with only explicitly allowed variables
+ */
+function buildEnv(): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = {};
+  for (const key of ALLOWED_ENV_VARS) {
+    if (process.env[key]) {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+}
+
 export class ClaudeProvider extends BaseProvider {
   getName(): string {
     return 'claude';
@@ -23,6 +53,10 @@ export class ClaudeProvider extends BaseProvider {
    * Execute a query using Claude Agent SDK
    */
   async *executeQuery(options: ExecuteOptions): AsyncGenerator<ProviderMessage> {
+    // Validate that model doesn't have a provider prefix
+    // AgentService should strip prefixes before passing to providers
+    validateBareModelId(options.model, 'ClaudeProvider');
+
     const {
       prompt,
       model,
@@ -33,28 +67,38 @@ export class ClaudeProvider extends BaseProvider {
       abortController,
       conversationHistory,
       sdkSessionId,
+      thinkingLevel,
     } = options;
 
-    // Build Claude SDK options
-    const defaultTools = ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash', 'WebSearch', 'WebFetch'];
-    const toolsToUse = allowedTools || defaultTools;
+    // Convert thinking level to token budget
+    const maxThinkingTokens = getThinkingTokenBudget(thinkingLevel);
 
+    // Build Claude SDK options
     const sdkOptions: Options = {
       model,
       systemPrompt,
       maxTurns,
       cwd,
-      allowedTools: toolsToUse,
-      permissionMode: 'acceptEdits',
-      sandbox: {
-        enabled: true,
-        autoAllowBashIfSandboxed: true,
-      },
+      // Pass only explicitly allowed environment variables to SDK
+      env: buildEnv(),
+      // Pass through allowedTools if provided by caller (decided by sdk-options.ts)
+      ...(allowedTools && { allowedTools }),
+      // AUTONOMOUS MODE: Always bypass permissions for fully autonomous operation
+      permissionMode: 'bypassPermissions',
+      allowDangerouslySkipPermissions: true,
       abortController,
       // Resume existing SDK session if we have a session ID
       ...(sdkSessionId && conversationHistory && conversationHistory.length > 0
         ? { resume: sdkSessionId }
         : {}),
+      // Forward settingSources for CLAUDE.md file loading
+      ...(options.settingSources && { settingSources: options.settingSources }),
+      // Forward MCP servers configuration
+      ...(options.mcpServers && { mcpServers: options.mcpServers }),
+      // Extended thinking configuration
+      ...(maxThinkingTokens && { maxThinkingTokens }),
+      // Subagents configuration for specialized task delegation
+      ...(options.agents && { agents: options.agents }),
     };
 
     // Build prompt payload
@@ -88,8 +132,32 @@ export class ClaudeProvider extends BaseProvider {
         yield msg as ProviderMessage;
       }
     } catch (error) {
-      console.error('[ClaudeProvider] executeQuery() error during execution:', error);
-      throw error;
+      // Enhance error with user-friendly message and classification
+      const errorInfo = classifyError(error);
+      const userMessage = getUserFriendlyErrorMessage(error);
+
+      logger.error('executeQuery() error during execution:', {
+        type: errorInfo.type,
+        message: errorInfo.message,
+        isRateLimit: errorInfo.isRateLimit,
+        retryAfter: errorInfo.retryAfter,
+        stack: (error as Error).stack,
+      });
+
+      // Build enhanced error message with additional guidance for rate limits
+      const message = errorInfo.isRateLimit
+        ? `${userMessage}\n\nTip: If you're running multiple features in auto-mode, consider reducing concurrency (maxConcurrency setting) to avoid hitting rate limits.`
+        : userMessage;
+
+      const enhancedError = new Error(message);
+      (enhancedError as any).originalError = error;
+      (enhancedError as any).type = errorInfo.type;
+
+      if (errorInfo.isRateLimit) {
+        (enhancedError as any).retryAfter = errorInfo.retryAfter;
+      }
+
+      throw enhancedError;
     }
   }
 

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

@@ -0,0 +1,558 @@
+/**
+ * CliProvider - Abstract base class for CLI-based AI providers
+ *
+ * Provides common infrastructure for CLI tools that spawn subprocesses
+ * and stream JSONL output. Handles:
+ * - Platform-specific CLI detection (PATH, common locations)
+ * - Windows execution strategies (WSL, npx, direct, cmd)
+ * - JSONL subprocess spawning and streaming
+ * - Error mapping infrastructure
+ *
+ * @example
+ * ```typescript
+ * class CursorProvider extends CliProvider {
+ *   getCliName(): string { return 'cursor-agent'; }
+ *   getSpawnConfig(): CliSpawnConfig {
+ *     return {
+ *       windowsStrategy: 'wsl',
+ *       commonPaths: {
+ *         linux: ['~/.local/bin/cursor-agent'],
+ *         darwin: ['~/.local/bin/cursor-agent'],
+ *       }
+ *     };
+ *   }
+ *   // ... implement abstract methods
+ * }
+ * ```
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { BaseProvider } from './base-provider.js';
+import type { ProviderConfig, ExecuteOptions, ProviderMessage } from './types.js';
+import {
+  spawnJSONLProcess,
+  type SubprocessOptions,
+  isWslAvailable,
+  findCliInWsl,
+  createWslCommand,
+  windowsToWslPath,
+  type WslCliResult,
+} from '@automaker/platform';
+import { createLogger, isAbortError } from '@automaker/utils';
+
+/**
+ * Spawn strategy for CLI tools on Windows
+ *
+ * Different CLI tools require different execution strategies:
+ * - 'wsl': Requires WSL, CLI only available on Linux/macOS (e.g., cursor-agent)
+ * - 'npx': Installed globally via npm/npx, use `npx <package>` to run
+ * - 'direct': Native Windows binary, can spawn directly
+ * - 'cmd': Windows batch file (.cmd/.bat), needs cmd.exe shell
+ */
+export type SpawnStrategy = 'wsl' | 'npx' | 'direct' | 'cmd';
+
+/**
+ * Configuration for CLI tool spawning
+ */
+export interface CliSpawnConfig {
+  /** How to spawn on Windows */
+  windowsStrategy: SpawnStrategy;
+
+  /** NPX package name (required if windowsStrategy is 'npx') */
+  npxPackage?: string;
+
+  /** Preferred WSL distribution (if windowsStrategy is 'wsl') */
+  wslDistribution?: string;
+
+  /**
+   * Common installation paths per platform
+   * Use ~ for home directory (will be expanded)
+   * Keys: 'linux', 'darwin', 'win32'
+   */
+  commonPaths: Record<string, string[]>;
+
+  /** Version check command (defaults to --version) */
+  versionCommand?: string;
+}
+
+/**
+ * CLI error information for consistent error handling
+ */
+export interface CliErrorInfo {
+  code: string;
+  message: string;
+  recoverable: boolean;
+  suggestion?: string;
+}
+
+/**
+ * Detection result from CLI path finding
+ */
+export interface CliDetectionResult {
+  /** Path to the CLI (or 'npx' for npx strategy) */
+  cliPath: string | null;
+  /** Whether using WSL mode */
+  useWsl: boolean;
+  /** WSL path if using WSL */
+  wslCliPath?: string;
+  /** WSL distribution if using WSL */
+  wslDistribution?: string;
+  /** Detected strategy used */
+  strategy: SpawnStrategy | 'native';
+}
+
+// Create logger for CLI operations
+const cliLogger = createLogger('CliProvider');
+
+/**
+ * Abstract base class for CLI-based providers
+ *
+ * Subclasses must implement:
+ * - getCliName(): CLI executable name
+ * - getSpawnConfig(): Platform-specific spawn configuration
+ * - buildCliArgs(): Convert ExecuteOptions to CLI arguments
+ * - normalizeEvent(): Convert CLI output to ProviderMessage
+ */
+export abstract class CliProvider extends BaseProvider {
+  // CLI detection results (cached after first detection)
+  protected cliPath: string | null = null;
+  protected useWsl: boolean = false;
+  protected wslCliPath: string | null = null;
+  protected wslDistribution: string | undefined = undefined;
+  protected detectedStrategy: SpawnStrategy | 'native' = 'native';
+
+  // NPX args (used when strategy is 'npx')
+  protected npxArgs: string[] = [];
+
+  constructor(config: ProviderConfig = {}) {
+    super(config);
+    // Detection happens lazily on first use
+  }
+
+  // ==========================================================================
+  // Abstract methods - must be implemented by subclasses
+  // ==========================================================================
+
+  /**
+   * Get the CLI executable name (e.g., 'cursor-agent', 'aider')
+   */
+  abstract getCliName(): string;
+
+  /**
+   * Get spawn configuration for this CLI
+   */
+  abstract getSpawnConfig(): CliSpawnConfig;
+
+  /**
+   * Build CLI arguments from execution options
+   * @param options Execution options
+   * @returns Array of CLI arguments
+   */
+  abstract buildCliArgs(options: ExecuteOptions): string[];
+
+  /**
+   * Normalize a raw CLI event to ProviderMessage format
+   * @param event Raw event from CLI JSONL output
+   * @returns Normalized ProviderMessage or null to skip
+   */
+  abstract normalizeEvent(event: unknown): ProviderMessage | null;
+
+  // ==========================================================================
+  // Optional overrides
+  // ==========================================================================
+
+  /**
+   * Map CLI stderr/exit code to error info
+   * Override to provide CLI-specific error mapping
+   */
+  protected mapError(stderr: string, exitCode: number | null): CliErrorInfo {
+    const lower = stderr.toLowerCase();
+
+    // Common authentication errors
+    if (
+      lower.includes('not authenticated') ||
+      lower.includes('please log in') ||
+      lower.includes('unauthorized')
+    ) {
+      return {
+        code: 'NOT_AUTHENTICATED',
+        message: `${this.getCliName()} is not authenticated`,
+        recoverable: true,
+        suggestion: `Run "${this.getCliName()} login" to authenticate`,
+      };
+    }
+
+    // Rate limiting
+    if (
+      lower.includes('rate limit') ||
+      lower.includes('too many requests') ||
+      lower.includes('429')
+    ) {
+      return {
+        code: 'RATE_LIMITED',
+        message: 'API rate limit exceeded',
+        recoverable: true,
+        suggestion: 'Wait a few minutes and try again',
+      };
+    }
+
+    // Network errors
+    if (
+      lower.includes('network') ||
+      lower.includes('connection') ||
+      lower.includes('econnrefused') ||
+      lower.includes('timeout')
+    ) {
+      return {
+        code: 'NETWORK_ERROR',
+        message: 'Network connection error',
+        recoverable: true,
+        suggestion: 'Check your internet connection and try again',
+      };
+    }
+
+    // Process killed
+    if (exitCode === 137 || lower.includes('killed') || lower.includes('sigterm')) {
+      return {
+        code: 'PROCESS_CRASHED',
+        message: 'Process was terminated',
+        recoverable: true,
+        suggestion: 'The process may have run out of memory. Try a simpler task.',
+      };
+    }
+
+    // Generic error
+    return {
+      code: 'UNKNOWN_ERROR',
+      message: stderr || `Process exited with code ${exitCode}`,
+      recoverable: false,
+    };
+  }
+
+  /**
+   * Get installation instructions for this CLI
+   * Override to provide CLI-specific instructions
+   */
+  protected getInstallInstructions(): string {
+    const cliName = this.getCliName();
+    const config = this.getSpawnConfig();
+
+    if (process.platform === 'win32') {
+      switch (config.windowsStrategy) {
+        case 'wsl':
+          return `${cliName} requires WSL on Windows. Install WSL, then run inside WSL to install.`;
+        case 'npx':
+          return `Install with: npm install -g ${config.npxPackage || cliName}`;
+        case 'cmd':
+        case 'direct':
+          return `${cliName} is not installed. Check the documentation for installation instructions.`;
+      }
+    }
+
+    return `${cliName} is not installed. Check the documentation for installation instructions.`;
+  }
+
+  // ==========================================================================
+  // CLI Detection
+  // ==========================================================================
+
+  /**
+   * Expand ~ to home directory in path
+   */
+  private expandPath(p: string): string {
+    if (p.startsWith('~')) {
+      return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+  }
+
+  /**
+   * Find CLI in PATH using 'which' (Unix) or 'where' (Windows)
+   */
+  private findCliInPath(): string | null {
+    const cliName = this.getCliName();
+
+    try {
+      const command = process.platform === 'win32' ? 'where' : 'which';
+      const result = execSync(`${command} ${cliName}`, {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+      })
+        .trim()
+        .split('\n')[0];
+
+      if (result && fs.existsSync(result)) {
+        cliLogger.debug(`Found ${cliName} in PATH: ${result}`);
+        return result;
+      }
+    } catch {
+      // Not in PATH
+    }
+
+    return null;
+  }
+
+  /**
+   * Find CLI in common installation paths for current platform
+   */
+  private findCliInCommonPaths(): string | null {
+    const config = this.getSpawnConfig();
+    const cliName = this.getCliName();
+    const platform = process.platform as 'linux' | 'darwin' | 'win32';
+    const paths = config.commonPaths[platform] || [];
+
+    for (const p of paths) {
+      const expandedPath = this.expandPath(p);
+      if (fs.existsSync(expandedPath)) {
+        cliLogger.debug(`Found ${cliName} at: ${expandedPath}`);
+        return expandedPath;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Detect CLI installation using appropriate strategy
+   */
+  protected detectCli(): CliDetectionResult {
+    const config = this.getSpawnConfig();
+    const cliName = this.getCliName();
+    const wslLogger = (msg: string) => cliLogger.debug(msg);
+
+    // Windows - use configured strategy
+    if (process.platform === 'win32') {
+      switch (config.windowsStrategy) {
+        case 'wsl': {
+          // Check WSL for CLI
+          if (isWslAvailable({ logger: wslLogger })) {
+            const wslResult: WslCliResult | null = findCliInWsl(cliName, {
+              logger: wslLogger,
+              distribution: config.wslDistribution,
+            });
+            if (wslResult) {
+              cliLogger.debug(
+                `Using ${cliName} via WSL (${wslResult.distribution || 'default'}): ${wslResult.wslPath}`
+              );
+              return {
+                cliPath: 'wsl.exe',
+                useWsl: true,
+                wslCliPath: wslResult.wslPath,
+                wslDistribution: wslResult.distribution,
+                strategy: 'wsl',
+              };
+            }
+          }
+          cliLogger.debug(`${cliName} not found (WSL not available or CLI not installed in WSL)`);
+          return { cliPath: null, useWsl: false, strategy: 'wsl' };
+        }
+
+        case 'npx': {
+          // For npx, we don't need to find the CLI, just return npx
+          cliLogger.debug(`Using ${cliName} via npx (package: ${config.npxPackage})`);
+          return {
+            cliPath: 'npx',
+            useWsl: false,
+            strategy: 'npx',
+          };
+        }
+
+        case 'direct':
+        case 'cmd': {
+          // Native Windows - check PATH and common paths
+          const pathResult = this.findCliInPath();
+          if (pathResult) {
+            return { cliPath: pathResult, useWsl: false, strategy: config.windowsStrategy };
+          }
+
+          const commonResult = this.findCliInCommonPaths();
+          if (commonResult) {
+            return { cliPath: commonResult, useWsl: false, strategy: config.windowsStrategy };
+          }
+
+          cliLogger.debug(`${cliName} not found on Windows`);
+          return { cliPath: null, useWsl: false, strategy: config.windowsStrategy };
+        }
+      }
+    }
+
+    // Linux/macOS - native execution
+    const pathResult = this.findCliInPath();
+    if (pathResult) {
+      return { cliPath: pathResult, useWsl: false, strategy: 'native' };
+    }
+
+    const commonResult = this.findCliInCommonPaths();
+    if (commonResult) {
+      return { cliPath: commonResult, useWsl: false, strategy: 'native' };
+    }
+
+    cliLogger.debug(`${cliName} not found`);
+    return { cliPath: null, useWsl: false, strategy: 'native' };
+  }
+
+  /**
+   * Ensure CLI is detected (lazy initialization)
+   */
+  protected ensureCliDetected(): void {
+    if (this.cliPath !== null || this.detectedStrategy !== 'native') {
+      return; // Already detected
+    }
+
+    const result = this.detectCli();
+    this.cliPath = result.cliPath;
+    this.useWsl = result.useWsl;
+    this.wslCliPath = result.wslCliPath || null;
+    this.wslDistribution = result.wslDistribution;
+    this.detectedStrategy = result.strategy;
+
+    // Set up npx args if using npx strategy
+    const config = this.getSpawnConfig();
+    if (result.strategy === 'npx' && config.npxPackage) {
+      this.npxArgs = [config.npxPackage];
+    }
+  }
+
+  /**
+   * Check if CLI is installed
+   */
+  async isInstalled(): Promise<boolean> {
+    this.ensureCliDetected();
+    return this.cliPath !== null;
+  }
+
+  // ==========================================================================
+  // Subprocess Spawning
+  // ==========================================================================
+
+  /**
+   * Build subprocess options based on detected strategy
+   */
+  protected buildSubprocessOptions(options: ExecuteOptions, cliArgs: string[]): SubprocessOptions {
+    this.ensureCliDetected();
+
+    if (!this.cliPath) {
+      throw new Error(`${this.getCliName()} CLI not found. ${this.getInstallInstructions()}`);
+    }
+
+    const cwd = options.cwd || process.cwd();
+
+    // Filter undefined values from process.env
+    const filteredEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        filteredEnv[key] = value;
+      }
+    }
+
+    // WSL strategy
+    if (this.useWsl && this.wslCliPath) {
+      const wslCwd = windowsToWslPath(cwd);
+      const wslCmd = createWslCommand(this.wslCliPath, cliArgs, {
+        distribution: this.wslDistribution,
+      });
+
+      // Add --cd flag to change directory inside WSL
+      let args: string[];
+      if (this.wslDistribution) {
+        args = ['-d', this.wslDistribution, '--cd', wslCwd, this.wslCliPath, ...cliArgs];
+      } else {
+        args = ['--cd', wslCwd, this.wslCliPath, ...cliArgs];
+      }
+
+      cliLogger.debug(`WSL spawn: ${wslCmd.command} ${args.slice(0, 6).join(' ')}...`);
+
+      return {
+        command: wslCmd.command,
+        args,
+        cwd, // Windows cwd for spawn
+        env: filteredEnv,
+        abortController: options.abortController,
+        timeout: 120000, // CLI operations may take longer
+      };
+    }
+
+    // NPX strategy
+    if (this.detectedStrategy === 'npx') {
+      const allArgs = [...this.npxArgs, ...cliArgs];
+      cliLogger.debug(`NPX spawn: npx ${allArgs.slice(0, 6).join(' ')}...`);
+
+      return {
+        command: 'npx',
+        args: allArgs,
+        cwd,
+        env: filteredEnv,
+        abortController: options.abortController,
+        timeout: 120000,
+      };
+    }
+
+    // Direct strategy (native Unix or Windows direct/cmd)
+    cliLogger.debug(`Direct spawn: ${this.cliPath} ${cliArgs.slice(0, 6).join(' ')}...`);
+
+    return {
+      command: this.cliPath,
+      args: cliArgs,
+      cwd,
+      env: filteredEnv,
+      abortController: options.abortController,
+      timeout: 120000,
+    };
+  }
+
+  /**
+   * Execute a query using the CLI with JSONL streaming
+   *
+   * This is a default implementation that:
+   * 1. Builds CLI args from options
+   * 2. Spawns the subprocess with appropriate strategy
+   * 3. Streams and normalizes events
+   *
+   * Subclasses can override for custom behavior.
+   */
+  async *executeQuery(options: ExecuteOptions): AsyncGenerator<ProviderMessage> {
+    this.ensureCliDetected();
+
+    if (!this.cliPath) {
+      throw new Error(`${this.getCliName()} CLI not found. ${this.getInstallInstructions()}`);
+    }
+
+    const cliArgs = this.buildCliArgs(options);
+    const subprocessOptions = this.buildSubprocessOptions(options, cliArgs);
+
+    try {
+      for await (const rawEvent of spawnJSONLProcess(subprocessOptions)) {
+        const normalized = this.normalizeEvent(rawEvent);
+        if (normalized) {
+          yield normalized;
+        }
+      }
+    } catch (error) {
+      if (isAbortError(error)) {
+        cliLogger.debug('Query aborted');
+        return;
+      }
+
+      // Map CLI errors
+      if (error instanceof Error && 'stderr' in error) {
+        const errorInfo = this.mapError(
+          (error as { stderr?: string }).stderr || error.message,
+          (error as { exitCode?: number | null }).exitCode ?? null
+        );
+
+        const cliError = new Error(errorInfo.message) as Error & CliErrorInfo;
+        cliError.code = errorInfo.code;
+        cliError.recoverable = errorInfo.recoverable;
+        cliError.suggestion = errorInfo.suggestion;
+        throw cliError;
+      }
+
+      throw error;
+    }
+  }
+}

apps/server/src/providers/codex-config-manager.ts

@@ -0,0 +1,85 @@
+/**
+ * Codex Config Manager - Writes MCP server configuration for Codex CLI
+ */
+
+import path from 'path';
+import type { McpServerConfig } from '@automaker/types';
+import * as secureFs from '../lib/secure-fs.js';
+
+const CODEX_CONFIG_DIR = '.codex';
+const CODEX_CONFIG_FILENAME = 'config.toml';
+const CODEX_MCP_SECTION = 'mcp_servers';
+
+function formatTomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function formatTomlArray(values: string[]): string {
+  const formatted = values.map((value) => formatTomlString(value)).join(', ');
+  return `[${formatted}]`;
+}
+
+function formatTomlInlineTable(values: Record<string, string>): string {
+  const entries = Object.entries(values).map(
+    ([key, value]) => `${key} = ${formatTomlString(value)}`
+  );
+  return `{ ${entries.join(', ')} }`;
+}
+
+function formatTomlKey(key: string): string {
+  return `"${key.replace(/"/g, '\\"')}"`;
+}
+
+function buildServerBlock(name: string, server: McpServerConfig): string[] {
+  const lines: string[] = [];
+  const section = `${CODEX_MCP_SECTION}.${formatTomlKey(name)}`;
+  lines.push(`[${section}]`);
+
+  if (server.type) {
+    lines.push(`type = ${formatTomlString(server.type)}`);
+  }
+
+  if ('command' in server && server.command) {
+    lines.push(`command = ${formatTomlString(server.command)}`);
+  }
+
+  if ('args' in server && server.args && server.args.length > 0) {
+    lines.push(`args = ${formatTomlArray(server.args)}`);
+  }
+
+  if ('env' in server && server.env && Object.keys(server.env).length > 0) {
+    lines.push(`env = ${formatTomlInlineTable(server.env)}`);
+  }
+
+  if ('url' in server && server.url) {
+    lines.push(`url = ${formatTomlString(server.url)}`);
+  }
+
+  if ('headers' in server && server.headers && Object.keys(server.headers).length > 0) {
+    lines.push(`headers = ${formatTomlInlineTable(server.headers)}`);
+  }
+
+  return lines;
+}
+
+export class CodexConfigManager {
+  async configureMcpServers(
+    cwd: string,
+    mcpServers: Record<string, McpServerConfig>
+  ): Promise<void> {
+    const configDir = path.join(cwd, CODEX_CONFIG_DIR);
+    const configPath = path.join(configDir, CODEX_CONFIG_FILENAME);
+
+    await secureFs.mkdir(configDir, { recursive: true });
+
+    const blocks: string[] = [];
+    for (const [name, server] of Object.entries(mcpServers)) {
+      blocks.push(...buildServerBlock(name, server), '');
+    }
+
+    const content = blocks.join('\n').trim();
+    if (content) {
+      await secureFs.writeFile(configPath, content + '\n', 'utf-8');
+    }
+  }
+}

apps/server/src/providers/codex-models.ts

@@ -0,0 +1,111 @@
+/**
+ * Codex Model Definitions
+ *
+ * Official Codex CLI models as documented at https://developers.openai.com/codex/models/
+ */
+
+import { CODEX_MODEL_MAP } from '@automaker/types';
+import type { ModelDefinition } from './types.js';
+
+const CONTEXT_WINDOW_256K = 256000;
+const CONTEXT_WINDOW_128K = 128000;
+const MAX_OUTPUT_32K = 32000;
+const MAX_OUTPUT_16K = 16000;
+
+/**
+ * All available Codex models with their specifications
+ * Based on https://developers.openai.com/codex/models/
+ */
+export const CODEX_MODELS: ModelDefinition[] = [
+  // ========== Recommended Codex Models ==========
+  {
+    id: CODEX_MODEL_MAP.gpt52Codex,
+    name: 'GPT-5.2-Codex',
+    modelString: CODEX_MODEL_MAP.gpt52Codex,
+    provider: 'openai',
+    description:
+      'Most advanced agentic coding model for complex software engineering (default for ChatGPT users).',
+    contextWindow: CONTEXT_WINDOW_256K,
+    maxOutputTokens: MAX_OUTPUT_32K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'premium' as const,
+    default: true,
+    hasReasoning: true,
+  },
+  {
+    id: CODEX_MODEL_MAP.gpt51CodexMax,
+    name: 'GPT-5.1-Codex-Max',
+    modelString: CODEX_MODEL_MAP.gpt51CodexMax,
+    provider: 'openai',
+    description: 'Optimized for long-horizon, agentic coding tasks in Codex.',
+    contextWindow: CONTEXT_WINDOW_256K,
+    maxOutputTokens: MAX_OUTPUT_32K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'premium' as const,
+    hasReasoning: true,
+  },
+  {
+    id: CODEX_MODEL_MAP.gpt51CodexMini,
+    name: 'GPT-5.1-Codex-Mini',
+    modelString: CODEX_MODEL_MAP.gpt51CodexMini,
+    provider: 'openai',
+    description: 'Smaller, more cost-effective version for faster workflows.',
+    contextWindow: CONTEXT_WINDOW_128K,
+    maxOutputTokens: MAX_OUTPUT_16K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'basic' as const,
+    hasReasoning: false,
+  },
+
+  // ========== General-Purpose GPT Models ==========
+  {
+    id: CODEX_MODEL_MAP.gpt52,
+    name: 'GPT-5.2',
+    modelString: CODEX_MODEL_MAP.gpt52,
+    provider: 'openai',
+    description: 'Best general agentic model for tasks across industries and domains.',
+    contextWindow: CONTEXT_WINDOW_256K,
+    maxOutputTokens: MAX_OUTPUT_32K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'standard' as const,
+    hasReasoning: true,
+  },
+  {
+    id: CODEX_MODEL_MAP.gpt51,
+    name: 'GPT-5.1',
+    modelString: CODEX_MODEL_MAP.gpt51,
+    provider: 'openai',
+    description: 'Great for coding and agentic tasks across domains.',
+    contextWindow: CONTEXT_WINDOW_256K,
+    maxOutputTokens: MAX_OUTPUT_32K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'standard' as const,
+    hasReasoning: true,
+  },
+];
+
+/**
+ * Get model definition by ID
+ */
+export function getCodexModelById(modelId: string): ModelDefinition | undefined {
+  return CODEX_MODELS.find((m) => m.id === modelId || m.modelString === modelId);
+}
+
+/**
+ * Get all models that support reasoning
+ */
+export function getReasoningModels(): ModelDefinition[] {
+  return CODEX_MODELS.filter((m) => m.hasReasoning);
+}
+
+/**
+ * Get models by tier
+ */
+export function getModelsByTier(tier: 'premium' | 'standard' | 'basic'): ModelDefinition[] {
+  return CODEX_MODELS.filter((m) => m.tier === tier);
+}

apps/server/src/providers/codex-sdk-client.ts

@@ -0,0 +1,173 @@
+/**
+ * Codex SDK client - Executes Codex queries via official @openai/codex-sdk
+ *
+ * Used for programmatic control of Codex from within the application.
+ * Provides cleaner integration than spawning CLI processes.
+ */
+
+import { Codex } from '@openai/codex-sdk';
+import { formatHistoryAsText, classifyError, getUserFriendlyErrorMessage } from '@automaker/utils';
+import { supportsReasoningEffort } from '@automaker/types';
+import type { ExecuteOptions, ProviderMessage } from './types.js';
+
+const OPENAI_API_KEY_ENV = 'OPENAI_API_KEY';
+const SDK_HISTORY_HEADER = 'Current request:\n';
+const DEFAULT_RESPONSE_TEXT = '';
+const SDK_ERROR_DETAILS_LABEL = 'Details:';
+
+type PromptBlock = {
+  type: string;
+  text?: string;
+  source?: {
+    type?: string;
+    media_type?: string;
+    data?: string;
+  };
+};
+
+function resolveApiKey(): string {
+  const apiKey = process.env[OPENAI_API_KEY_ENV];
+  if (!apiKey) {
+    throw new Error('OPENAI_API_KEY is not set.');
+  }
+  return apiKey;
+}
+
+function normalizePromptBlocks(prompt: ExecuteOptions['prompt']): PromptBlock[] {
+  if (Array.isArray(prompt)) {
+    return prompt as PromptBlock[];
+  }
+  return [{ type: 'text', text: prompt }];
+}
+
+function buildPromptText(options: ExecuteOptions, systemPrompt: string | null): string {
+  const historyText =
+    options.conversationHistory && options.conversationHistory.length > 0
+      ? formatHistoryAsText(options.conversationHistory)
+      : '';
+
+  const promptBlocks = normalizePromptBlocks(options.prompt);
+  const promptTexts: string[] = [];
+
+  for (const block of promptBlocks) {
+    if (block.type === 'text' && typeof block.text === 'string' && block.text.trim()) {
+      promptTexts.push(block.text);
+    }
+  }
+
+  const promptContent = promptTexts.join('\n\n');
+  if (!promptContent.trim()) {
+    throw new Error('Codex SDK prompt is empty.');
+  }
+
+  const parts: string[] = [];
+  if (systemPrompt) {
+    parts.push(`System: ${systemPrompt}`);
+  }
+  if (historyText) {
+    parts.push(historyText);
+  }
+  parts.push(`${SDK_HISTORY_HEADER}${promptContent}`);
+
+  return parts.join('\n\n');
+}
+
+function buildSdkErrorMessage(rawMessage: string, userMessage: string): string {
+  if (!rawMessage) {
+    return userMessage;
+  }
+  if (!userMessage || rawMessage === userMessage) {
+    return rawMessage;
+  }
+  return `${userMessage}\n\n${SDK_ERROR_DETAILS_LABEL} ${rawMessage}`;
+}
+
+/**
+ * Execute a query using the official Codex SDK
+ *
+ * The SDK provides a cleaner interface than spawning CLI processes:
+ * - Handles authentication automatically
+ * - Provides TypeScript types
+ * - Supports thread management and resumption
+ * - Better error handling
+ */
+export async function* executeCodexSdkQuery(
+  options: ExecuteOptions,
+  systemPrompt: string | null
+): AsyncGenerator<ProviderMessage> {
+  try {
+    const apiKey = resolveApiKey();
+    const codex = new Codex({ apiKey });
+
+    // Resume existing thread or start new one
+    let thread;
+    if (options.sdkSessionId) {
+      try {
+        thread = codex.resumeThread(options.sdkSessionId);
+      } catch {
+        // If resume fails, start a new thread
+        thread = codex.startThread();
+      }
+    } else {
+      thread = codex.startThread();
+    }
+
+    const promptText = buildPromptText(options, systemPrompt);
+
+    // Build run options with reasoning effort if supported
+    const runOptions: {
+      signal?: AbortSignal;
+      reasoning?: { effort: string };
+    } = {
+      signal: options.abortController?.signal,
+    };
+
+    // Add reasoning effort if model supports it and reasoningEffort is specified
+    if (
+      options.reasoningEffort &&
+      supportsReasoningEffort(options.model) &&
+      options.reasoningEffort !== 'none'
+    ) {
+      runOptions.reasoning = { effort: options.reasoningEffort };
+    }
+
+    // Run the query
+    const result = await thread.run(promptText, runOptions);
+
+    // Extract response text (from finalResponse property)
+    const outputText = result.finalResponse ?? DEFAULT_RESPONSE_TEXT;
+
+    // Get thread ID (may be null if not populated yet)
+    const threadId = thread.id ?? undefined;
+
+    // Yield assistant message
+    yield {
+      type: 'assistant',
+      session_id: threadId,
+      message: {
+        role: 'assistant',
+        content: [{ type: 'text', text: outputText }],
+      },
+    };
+
+    // Yield result
+    yield {
+      type: 'result',
+      subtype: 'success',
+      session_id: threadId,
+      result: outputText,
+    };
+  } catch (error) {
+    const errorInfo = classifyError(error);
+    const userMessage = getUserFriendlyErrorMessage(error);
+    const combinedMessage = buildSdkErrorMessage(errorInfo.message, userMessage);
+    console.error('[CodexSDK] executeQuery() error during execution:', {
+      type: errorInfo.type,
+      message: errorInfo.message,
+      isRateLimit: errorInfo.isRateLimit,
+      retryAfter: errorInfo.retryAfter,
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+    yield { type: 'error', error: combinedMessage };
+  }
+}

apps/server/src/providers/codex-tool-mapping.ts

@@ -0,0 +1,436 @@
+export type CodexToolResolution = {
+  name: string;
+  input: Record<string, unknown>;
+};
+
+export type CodexTodoItem = {
+  content: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  activeForm?: string;
+};
+
+const TOOL_NAME_BASH = 'Bash';
+const TOOL_NAME_READ = 'Read';
+const TOOL_NAME_EDIT = 'Edit';
+const TOOL_NAME_WRITE = 'Write';
+const TOOL_NAME_GREP = 'Grep';
+const TOOL_NAME_GLOB = 'Glob';
+const TOOL_NAME_TODO = 'TodoWrite';
+const TOOL_NAME_DELETE = 'Delete';
+const TOOL_NAME_LS = 'Ls';
+
+const INPUT_KEY_COMMAND = 'command';
+const INPUT_KEY_FILE_PATH = 'file_path';
+const INPUT_KEY_PATTERN = 'pattern';
+
+const SHELL_WRAPPER_PATTERNS = [
+  /^\/bin\/bash\s+-lc\s+["']([\s\S]+)["']$/,
+  /^bash\s+-lc\s+["']([\s\S]+)["']$/,
+  /^\/bin\/sh\s+-lc\s+["']([\s\S]+)["']$/,
+  /^sh\s+-lc\s+["']([\s\S]+)["']$/,
+  /^cmd\.exe\s+\/c\s+["']?([\s\S]+)["']?$/i,
+  /^powershell(?:\.exe)?\s+-Command\s+["']?([\s\S]+)["']?$/i,
+  /^pwsh(?:\.exe)?\s+-Command\s+["']?([\s\S]+)["']?$/i,
+] as const;
+
+const COMMAND_SEPARATOR_PATTERN = /\s*(?:&&|\|\||;)\s*/;
+const SEGMENT_SKIP_PREFIXES = ['cd ', 'export ', 'set ', 'pushd '] as const;
+const WRAPPER_COMMANDS = new Set(['sudo', 'env', 'command']);
+const READ_COMMANDS = new Set(['cat', 'sed', 'head', 'tail', 'less', 'more', 'bat', 'stat', 'wc']);
+const SEARCH_COMMANDS = new Set(['rg', 'grep', 'ag', 'ack']);
+const GLOB_COMMANDS = new Set(['ls', 'find', 'fd', 'tree']);
+const DELETE_COMMANDS = new Set(['rm', 'del', 'erase', 'remove', 'unlink']);
+const LIST_COMMANDS = new Set(['ls', 'dir', 'll', 'la']);
+const WRITE_COMMANDS = new Set(['tee', 'touch', 'mkdir']);
+const APPLY_PATCH_COMMAND = 'apply_patch';
+const APPLY_PATCH_PATTERN = /\bapply_patch\b/;
+const REDIRECTION_TARGET_PATTERN = /(?:>>|>)\s*([^\s]+)/;
+const SED_IN_PLACE_FLAGS = new Set(['-i', '--in-place']);
+const PERL_IN_PLACE_FLAG = /-.*i/;
+const SEARCH_PATTERN_FLAGS = new Set(['-e', '--regexp']);
+const SEARCH_VALUE_FLAGS = new Set([
+  '-g',
+  '--glob',
+  '--iglob',
+  '--type',
+  '--type-add',
+  '--type-clear',
+  '--encoding',
+]);
+const SEARCH_FILE_LIST_FLAGS = new Set(['--files']);
+const TODO_LINE_PATTERN = /^[-*]\s*(?:\[(?<status>[ x~])\]\s*)?(?<content>.+)$/;
+const TODO_STATUS_COMPLETED = 'completed';
+const TODO_STATUS_IN_PROGRESS = 'in_progress';
+const TODO_STATUS_PENDING = 'pending';
+const PATCH_FILE_MARKERS = [
+  '*** Update File: ',
+  '*** Add File: ',
+  '*** Delete File: ',
+  '*** Move to: ',
+] as const;
+
+function stripShellWrapper(command: string): string {
+  const trimmed = command.trim();
+  for (const pattern of SHELL_WRAPPER_PATTERNS) {
+    const match = trimmed.match(pattern);
+    if (match && match[1]) {
+      return unescapeCommand(match[1].trim());
+    }
+  }
+  return trimmed;
+}
+
+function unescapeCommand(command: string): string {
+  return command.replace(/\\(["'])/g, '$1');
+}
+
+function extractPrimarySegment(command: string): string {
+  const segments = command
+    .split(COMMAND_SEPARATOR_PATTERN)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+
+  for (const segment of segments) {
+    const shouldSkip = SEGMENT_SKIP_PREFIXES.some((prefix) => segment.startsWith(prefix));
+    if (!shouldSkip) {
+      return segment;
+    }
+  }
+
+  return command.trim();
+}
+
+function tokenizeCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let isEscaped = false;
+
+  for (const char of command) {
+    if (isEscaped) {
+      current += char;
+      isEscaped = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      isEscaped = true;
+      continue;
+    }
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+
+    if (!inSingleQuote && !inDoubleQuote && /\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+function stripWrapperTokens(tokens: string[]): string[] {
+  let index = 0;
+  while (index < tokens.length && WRAPPER_COMMANDS.has(tokens[index].toLowerCase())) {
+    index += 1;
+  }
+  return tokens.slice(index);
+}
+
+function extractFilePathFromTokens(tokens: string[]): string | null {
+  const candidates = tokens.slice(1).filter((token) => token && !token.startsWith('-'));
+  if (candidates.length === 0) return null;
+  return candidates[candidates.length - 1];
+}
+
+function extractSearchPattern(tokens: string[]): string | null {
+  const remaining = tokens.slice(1);
+
+  for (let index = 0; index < remaining.length; index += 1) {
+    const token = remaining[index];
+    if (token === '--') {
+      return remaining[index + 1] ?? null;
+    }
+    if (SEARCH_PATTERN_FLAGS.has(token)) {
+      return remaining[index + 1] ?? null;
+    }
+    if (SEARCH_VALUE_FLAGS.has(token)) {
+      index += 1;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      continue;
+    }
+    return token;
+  }
+
+  return null;
+}
+
+function extractTeeTarget(tokens: string[]): string | null {
+  const teeIndex = tokens.findIndex((token) => token === 'tee');
+  if (teeIndex < 0) return null;
+  const candidate = tokens[teeIndex + 1];
+  return candidate && !candidate.startsWith('-') ? candidate : null;
+}
+
+function extractRedirectionTarget(command: string): string | null {
+  const match = command.match(REDIRECTION_TARGET_PATTERN);
+  return match?.[1] ?? null;
+}
+
+function extractFilePathFromDeleteTokens(tokens: string[]): string | null {
+  // rm file.txt or rm /path/to/file.txt
+  // Skip flags and get the first non-flag argument
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token && !token.startsWith('-')) {
+      return token;
+    }
+  }
+  return null;
+}
+
+function hasSedInPlaceFlag(tokens: string[]): boolean {
+  return tokens.some((token) => SED_IN_PLACE_FLAGS.has(token) || token.startsWith('-i'));
+}
+
+function hasPerlInPlaceFlag(tokens: string[]): boolean {
+  return tokens.some((token) => PERL_IN_PLACE_FLAG.test(token));
+}
+
+function extractPatchFilePath(command: string): string | null {
+  for (const marker of PATCH_FILE_MARKERS) {
+    const index = command.indexOf(marker);
+    if (index < 0) continue;
+    const start = index + marker.length;
+    const end = command.indexOf('\n', start);
+    const rawPath = (end === -1 ? command.slice(start) : command.slice(start, end)).trim();
+    if (rawPath) return rawPath;
+  }
+  return null;
+}
+
+function buildInputWithFilePath(filePath: string | null): Record<string, unknown> {
+  return filePath ? { [INPUT_KEY_FILE_PATH]: filePath } : {};
+}
+
+function buildInputWithPattern(pattern: string | null): Record<string, unknown> {
+  return pattern ? { [INPUT_KEY_PATTERN]: pattern } : {};
+}
+
+export function resolveCodexToolCall(command: string): CodexToolResolution {
+  const normalized = stripShellWrapper(command);
+  const primarySegment = extractPrimarySegment(normalized);
+  const tokens = stripWrapperTokens(tokenizeCommand(primarySegment));
+  const commandToken = tokens[0]?.toLowerCase() ?? '';
+
+  const redirectionTarget = extractRedirectionTarget(primarySegment);
+  if (redirectionTarget) {
+    return {
+      name: TOOL_NAME_WRITE,
+      input: buildInputWithFilePath(redirectionTarget),
+    };
+  }
+
+  if (commandToken === APPLY_PATCH_COMMAND || APPLY_PATCH_PATTERN.test(primarySegment)) {
+    return {
+      name: TOOL_NAME_EDIT,
+      input: buildInputWithFilePath(extractPatchFilePath(primarySegment)),
+    };
+  }
+
+  if (commandToken === 'sed' && hasSedInPlaceFlag(tokens)) {
+    return {
+      name: TOOL_NAME_EDIT,
+      input: buildInputWithFilePath(extractFilePathFromTokens(tokens)),
+    };
+  }
+
+  if (commandToken === 'perl' && hasPerlInPlaceFlag(tokens)) {
+    return {
+      name: TOOL_NAME_EDIT,
+      input: buildInputWithFilePath(extractFilePathFromTokens(tokens)),
+    };
+  }
+
+  if (WRITE_COMMANDS.has(commandToken)) {
+    const filePath =
+      commandToken === 'tee' ? extractTeeTarget(tokens) : extractFilePathFromTokens(tokens);
+    return {
+      name: TOOL_NAME_WRITE,
+      input: buildInputWithFilePath(filePath),
+    };
+  }
+
+  if (SEARCH_COMMANDS.has(commandToken)) {
+    if (tokens.some((token) => SEARCH_FILE_LIST_FLAGS.has(token))) {
+      return {
+        name: TOOL_NAME_GLOB,
+        input: buildInputWithPattern(extractFilePathFromTokens(tokens)),
+      };
+    }
+
+    return {
+      name: TOOL_NAME_GREP,
+      input: buildInputWithPattern(extractSearchPattern(tokens)),
+    };
+  }
+
+  // Handle Delete commands (rm, del, erase, remove, unlink)
+  if (DELETE_COMMANDS.has(commandToken)) {
+    // Skip if -r or -rf flags (recursive delete should go to Bash)
+    if (
+      tokens.some((token) => token === '-r' || token === '-rf' || token === '-f' || token === '-rf')
+    ) {
+      return {
+        name: TOOL_NAME_BASH,
+        input: { [INPUT_KEY_COMMAND]: normalized },
+      };
+    }
+    // Simple file deletion - extract the file path
+    const filePath = extractFilePathFromDeleteTokens(tokens);
+    if (filePath) {
+      return {
+        name: TOOL_NAME_DELETE,
+        input: { path: filePath },
+      };
+    }
+    // Fall back to bash if we can't determine the file path
+    return {
+      name: TOOL_NAME_BASH,
+      input: { [INPUT_KEY_COMMAND]: normalized },
+    };
+  }
+
+  // Handle simple Ls commands (just listing, not find/glob)
+  if (LIST_COMMANDS.has(commandToken)) {
+    const filePath = extractFilePathFromTokens(tokens);
+    return {
+      name: TOOL_NAME_LS,
+      input: { path: filePath || '.' },
+    };
+  }
+
+  if (GLOB_COMMANDS.has(commandToken)) {
+    return {
+      name: TOOL_NAME_GLOB,
+      input: buildInputWithPattern(extractFilePathFromTokens(tokens)),
+    };
+  }
+
+  if (READ_COMMANDS.has(commandToken)) {
+    return {
+      name: TOOL_NAME_READ,
+      input: buildInputWithFilePath(extractFilePathFromTokens(tokens)),
+    };
+  }
+
+  return {
+    name: TOOL_NAME_BASH,
+    input: { [INPUT_KEY_COMMAND]: normalized },
+  };
+}
+
+function parseTodoLines(lines: string[]): CodexTodoItem[] {
+  const todos: CodexTodoItem[] = [];
+
+  for (const line of lines) {
+    const match = line.match(TODO_LINE_PATTERN);
+    if (!match?.groups?.content) continue;
+
+    const statusToken = match.groups.status;
+    const status =
+      statusToken === 'x'
+        ? TODO_STATUS_COMPLETED
+        : statusToken === '~'
+          ? TODO_STATUS_IN_PROGRESS
+          : TODO_STATUS_PENDING;
+
+    todos.push({ content: match.groups.content.trim(), status });
+  }
+
+  return todos;
+}
+
+function extractTodoFromArray(value: unknown[]): CodexTodoItem[] {
+  return value
+    .map((entry) => {
+      if (typeof entry === 'string') {
+        return { content: entry, status: TODO_STATUS_PENDING };
+      }
+      if (entry && typeof entry === 'object') {
+        const record = entry as Record<string, unknown>;
+        const content =
+          typeof record.content === 'string'
+            ? record.content
+            : typeof record.text === 'string'
+              ? record.text
+              : typeof record.title === 'string'
+                ? record.title
+                : null;
+        if (!content) return null;
+        const status =
+          record.status === TODO_STATUS_COMPLETED ||
+          record.status === TODO_STATUS_IN_PROGRESS ||
+          record.status === TODO_STATUS_PENDING
+            ? (record.status as CodexTodoItem['status'])
+            : TODO_STATUS_PENDING;
+        const activeForm = typeof record.activeForm === 'string' ? record.activeForm : undefined;
+        return { content, status, activeForm };
+      }
+      return null;
+    })
+    .filter((item): item is CodexTodoItem => Boolean(item));
+}
+
+export function extractCodexTodoItems(item: Record<string, unknown>): CodexTodoItem[] | null {
+  const todosValue = item.todos;
+  if (Array.isArray(todosValue)) {
+    const todos = extractTodoFromArray(todosValue);
+    return todos.length > 0 ? todos : null;
+  }
+
+  const itemsValue = item.items;
+  if (Array.isArray(itemsValue)) {
+    const todos = extractTodoFromArray(itemsValue);
+    return todos.length > 0 ? todos : null;
+  }
+
+  const textValue =
+    typeof item.text === 'string'
+      ? item.text
+      : typeof item.content === 'string'
+        ? item.content
+        : null;
+  if (!textValue) return null;
+
+  const lines = textValue
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const todos = parseTodoLines(lines);
+  return todos.length > 0 ? todos : null;
+}
+
+export function getCodexTodoToolName(): string {
+  return TOOL_NAME_TODO;
+}

apps/server/src/providers/cursor-config-manager.ts

@@ -0,0 +1,197 @@
+/**
+ * Cursor CLI Configuration Manager
+ *
+ * Manages Cursor CLI configuration stored in .automaker/cursor-config.json
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getAllCursorModelIds, type CursorCliConfig, type CursorModelId } from '@automaker/types';
+import { createLogger } from '@automaker/utils';
+import { getAutomakerDir } from '@automaker/platform';
+
+// Create logger for this module
+const logger = createLogger('CursorConfigManager');
+
+/**
+ * Manages Cursor CLI configuration
+ * Config location: .automaker/cursor-config.json
+ */
+export class CursorConfigManager {
+  private configPath: string;
+  private config: CursorCliConfig;
+
+  constructor(projectPath: string) {
+    // Use getAutomakerDir for consistent path resolution
+    this.configPath = path.join(getAutomakerDir(projectPath), 'cursor-config.json');
+    this.config = this.loadConfig();
+  }
+
+  /**
+   * Load configuration from disk
+   */
+  private loadConfig(): CursorCliConfig {
+    try {
+      if (fs.existsSync(this.configPath)) {
+        const content = fs.readFileSync(this.configPath, 'utf8');
+        const parsed = JSON.parse(content) as CursorCliConfig;
+        logger.debug(`Loaded config from ${this.configPath}`);
+        return parsed;
+      }
+    } catch (error) {
+      logger.warn('Failed to load config:', error);
+    }
+
+    // Return default config with all available models
+    return {
+      defaultModel: 'auto',
+      models: getAllCursorModelIds(),
+    };
+  }
+
+  /**
+   * Save configuration to disk
+   */
+  private saveConfig(): void {
+    try {
+      const dir = path.dirname(this.configPath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.configPath, JSON.stringify(this.config, null, 2));
+      logger.debug('Config saved');
+    } catch (error) {
+      logger.error('Failed to save config:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the full configuration
+   */
+  getConfig(): CursorCliConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Get the default model
+   */
+  getDefaultModel(): CursorModelId {
+    return this.config.defaultModel || 'auto';
+  }
+
+  /**
+   * Set the default model
+   */
+  setDefaultModel(model: CursorModelId): void {
+    this.config.defaultModel = model;
+    this.saveConfig();
+    logger.info(`Default model set to: ${model}`);
+  }
+
+  /**
+   * Get enabled models
+   */
+  getEnabledModels(): CursorModelId[] {
+    return this.config.models || ['auto'];
+  }
+
+  /**
+   * Set enabled models
+   */
+  setEnabledModels(models: CursorModelId[]): void {
+    this.config.models = models;
+    this.saveConfig();
+    logger.info(`Enabled models updated: ${models.join(', ')}`);
+  }
+
+  /**
+   * Add a model to enabled list
+   */
+  addModel(model: CursorModelId): void {
+    if (!this.config.models) {
+      this.config.models = [];
+    }
+    if (!this.config.models.includes(model)) {
+      this.config.models.push(model);
+      this.saveConfig();
+      logger.info(`Model added: ${model}`);
+    }
+  }
+
+  /**
+   * Remove a model from enabled list
+   */
+  removeModel(model: CursorModelId): void {
+    if (this.config.models) {
+      this.config.models = this.config.models.filter((m) => m !== model);
+      this.saveConfig();
+      logger.info(`Model removed: ${model}`);
+    }
+  }
+
+  /**
+   * Check if a model is enabled
+   */
+  isModelEnabled(model: CursorModelId): boolean {
+    return this.config.models?.includes(model) ?? false;
+  }
+
+  /**
+   * Get MCP server configurations
+   */
+  getMcpServers(): string[] {
+    return this.config.mcpServers || [];
+  }
+
+  /**
+   * Set MCP server configurations
+   */
+  setMcpServers(servers: string[]): void {
+    this.config.mcpServers = servers;
+    this.saveConfig();
+    logger.info(`MCP servers updated: ${servers.join(', ')}`);
+  }
+
+  /**
+   * Get Cursor rules paths
+   */
+  getRules(): string[] {
+    return this.config.rules || [];
+  }
+
+  /**
+   * Set Cursor rules paths
+   */
+  setRules(rules: string[]): void {
+    this.config.rules = rules;
+    this.saveConfig();
+    logger.info(`Rules updated: ${rules.join(', ')}`);
+  }
+
+  /**
+   * Reset configuration to defaults
+   */
+  reset(): void {
+    this.config = {
+      defaultModel: 'auto',
+      models: getAllCursorModelIds(),
+    };
+    this.saveConfig();
+    logger.info('Config reset to defaults');
+  }
+
+  /**
+   * Check if config file exists
+   */
+  exists(): boolean {
+    return fs.existsSync(this.configPath);
+  }
+
+  /**
+   * Get the config file path
+   */
+  getConfigPath(): string {
+    return this.configPath;
+  }
+}

apps/server/src/providers/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Provider exports
+ */
+
+// Base providers
+export { BaseProvider } from './base-provider.js';
+export {
+  CliProvider,
+  type SpawnStrategy,
+  type CliSpawnConfig,
+  type CliErrorInfo,
+} from './cli-provider.js';
+export type {
+  ProviderConfig,
+  ExecuteOptions,
+  ProviderMessage,
+  InstallationStatus,
+  ModelDefinition,
+} from './types.js';
+
+// Claude provider
+export { ClaudeProvider } from './claude-provider.js';
+
+// Cursor provider
+export { CursorProvider, CursorErrorCode, CursorError } from './cursor-provider.js';
+export { CursorConfigManager } from './cursor-config-manager.js';
+
+// OpenCode provider
+export { OpencodeProvider } from './opencode-provider.js';
+
+// Provider factory
+export { ProviderFactory } from './provider-factory.js';

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

@@ -0,0 +1,676 @@
+/**
+ * OpenCode Provider - Executes queries using opencode CLI
+ *
+ * Extends CliProvider with OpenCode-specific configuration:
+ * - Event normalization for OpenCode's stream-json format
+ * - Model definitions for anthropic, openai, and google models
+ * - NPX-based Windows execution strategy
+ * - Platform-specific npm global installation paths
+ *
+ * Spawns the opencode CLI with --output-format stream-json for streaming responses.
+ */
+
+import * as path from 'path';
+import * as os from 'os';
+import { CliProvider, type CliSpawnConfig } from './cli-provider.js';
+import type {
+  ProviderConfig,
+  ExecuteOptions,
+  ProviderMessage,
+  ModelDefinition,
+  InstallationStatus,
+  ContentBlock,
+} from '@automaker/types';
+import { stripProviderPrefix } from '@automaker/types';
+import { type SubprocessOptions, getOpenCodeAuthIndicators } from '@automaker/platform';
+
+// =============================================================================
+// OpenCode Auth Types
+// =============================================================================
+
+export interface OpenCodeAuthStatus {
+  authenticated: boolean;
+  method: 'api_key' | 'oauth' | 'none';
+  hasOAuthToken?: boolean;
+  hasApiKey?: boolean;
+}
+
+// =============================================================================
+// OpenCode Stream Event Types
+// =============================================================================
+
+/**
+ * Base interface for all OpenCode stream events
+ * OpenCode uses underscore format: step_start, step_finish, text
+ */
+interface OpenCodeBaseEvent {
+  /** Event type identifier */
+  type: string;
+  /** Timestamp of the event */
+  timestamp?: number;
+  /** Session ID */
+  sessionID?: string;
+  /** Part object containing the actual event data */
+  part?: Record<string, unknown>;
+}
+
+/**
+ * Text event - Text output from the model
+ * Format: {"type":"text","part":{"text":"content",...}}
+ */
+export interface OpenCodeTextEvent extends OpenCodeBaseEvent {
+  type: 'text';
+  part: {
+    type: 'text';
+    text: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Tool call event - Request to execute a tool
+ */
+export interface OpenCodeToolCallEvent extends OpenCodeBaseEvent {
+  type: 'tool_call';
+  part: {
+    type: 'tool-call';
+    name: string;
+    call_id?: string;
+    args: unknown;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Tool result event - Output from a tool execution
+ */
+export interface OpenCodeToolResultEvent extends OpenCodeBaseEvent {
+  type: 'tool_result';
+  part: {
+    type: 'tool-result';
+    call_id?: string;
+    output: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Tool error event - Tool execution failed
+ */
+export interface OpenCodeToolErrorEvent extends OpenCodeBaseEvent {
+  type: 'tool_error';
+  part: {
+    type: 'tool-error';
+    call_id?: string;
+    error: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Start step event - Begins an agentic loop iteration
+ * Format: {"type":"step_start","part":{...}}
+ */
+export interface OpenCodeStartStepEvent extends OpenCodeBaseEvent {
+  type: 'step_start';
+  part?: {
+    type: 'step-start';
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Finish step event - Completes an agentic loop iteration
+ * Format: {"type":"step_finish","part":{"reason":"stop",...}}
+ */
+export interface OpenCodeFinishStepEvent extends OpenCodeBaseEvent {
+  type: 'step_finish';
+  part?: {
+    type: 'step-finish';
+    reason?: string;
+    error?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Union type of all OpenCode stream events
+ */
+export type OpenCodeStreamEvent =
+  | OpenCodeTextEvent
+  | OpenCodeToolCallEvent
+  | OpenCodeToolResultEvent
+  | OpenCodeToolErrorEvent
+  | OpenCodeStartStepEvent
+  | OpenCodeFinishStepEvent;
+
+// =============================================================================
+// Tool Use ID Generation
+// =============================================================================
+
+/** Counter for generating unique tool use IDs when call_id is not provided */
+let toolUseIdCounter = 0;
+
+/**
+ * Generate a unique tool use ID for tool calls without explicit IDs
+ */
+function generateToolUseId(): string {
+  toolUseIdCounter += 1;
+  return `opencode-tool-${toolUseIdCounter}`;
+}
+
+/**
+ * Reset the tool use ID counter (useful for testing)
+ */
+export function resetToolUseIdCounter(): void {
+  toolUseIdCounter = 0;
+}
+
+// =============================================================================
+// Provider Implementation
+// =============================================================================
+
+/**
+ * OpencodeProvider - Integrates opencode CLI as an AI provider
+ *
+ * OpenCode is an npm-distributed CLI tool that provides access to
+ * multiple AI model providers through a unified interface.
+ */
+export class OpencodeProvider extends CliProvider {
+  constructor(config: ProviderConfig = {}) {
+    super(config);
+  }
+
+  // ==========================================================================
+  // CliProvider Abstract Method Implementations
+  // ==========================================================================
+
+  getName(): string {
+    return 'opencode';
+  }
+
+  getCliName(): string {
+    return 'opencode';
+  }
+
+  getSpawnConfig(): CliSpawnConfig {
+    return {
+      windowsStrategy: 'npx',
+      npxPackage: 'opencode-ai@latest',
+      commonPaths: {
+        linux: [
+          path.join(os.homedir(), '.opencode/bin/opencode'),
+          path.join(os.homedir(), '.npm-global/bin/opencode'),
+          '/usr/local/bin/opencode',
+          '/usr/bin/opencode',
+          path.join(os.homedir(), '.local/bin/opencode'),
+        ],
+        darwin: [
+          path.join(os.homedir(), '.opencode/bin/opencode'),
+          path.join(os.homedir(), '.npm-global/bin/opencode'),
+          '/usr/local/bin/opencode',
+          '/opt/homebrew/bin/opencode',
+          path.join(os.homedir(), '.local/bin/opencode'),
+        ],
+        win32: [
+          path.join(os.homedir(), '.opencode', 'bin', 'opencode.exe'),
+          path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'opencode.cmd'),
+          path.join(os.homedir(), 'AppData', 'Roaming', 'npm', 'opencode'),
+          path.join(process.env.APPDATA || '', 'npm', 'opencode.cmd'),
+        ],
+      },
+    };
+  }
+
+  /**
+   * Build CLI arguments for the `opencode run` command
+   *
+   * Arguments built:
+   * - 'run' subcommand for executing queries
+   * - '--format', 'json' for JSON streaming output
+   * - '--model', '<model>' for model selection (if specified)
+   * - Message passed via stdin (no positional args needed)
+   *
+   * The prompt is passed via stdin to avoid shell escaping issues.
+   * OpenCode will read from stdin when no positional message arguments are provided.
+   *
+   * @param options - Execution options containing model, cwd, etc.
+   * @returns Array of CLI arguments for opencode run
+   */
+  buildCliArgs(options: ExecuteOptions): string[] {
+    const args: string[] = ['run'];
+
+    // Add JSON output format for streaming
+    args.push('--format', 'json');
+
+    // Handle model selection
+    // Strip 'opencode-' prefix if present, OpenCode uses native format
+    if (options.model) {
+      const model = stripProviderPrefix(options.model);
+      args.push('--model', model);
+    }
+
+    // Note: Working directory is set via subprocess cwd option, not CLI args
+    // Note: Message is passed via stdin, OpenCode reads from stdin automatically
+
+    return args;
+  }
+
+  // ==========================================================================
+  // Prompt Handling
+  // ==========================================================================
+
+  /**
+   * Extract prompt text from ExecuteOptions for passing via stdin
+   *
+   * Handles both string prompts and array-based prompts with content blocks.
+   * For array prompts with images, extracts only text content (images would
+   * need separate handling via file paths if OpenCode supports them).
+   *
+   * @param options - Execution options containing the prompt
+   * @returns Plain text prompt string
+   */
+  private extractPromptText(options: ExecuteOptions): string {
+    if (typeof options.prompt === 'string') {
+      return options.prompt;
+    }
+
+    // Array-based prompt - extract text content
+    if (Array.isArray(options.prompt)) {
+      return options.prompt
+        .filter((block) => block.type === 'text' && block.text)
+        .map((block) => block.text)
+        .join('\n');
+    }
+
+    throw new Error('Invalid prompt format: expected string or content block array');
+  }
+
+  /**
+   * Build subprocess options with stdin data for prompt
+   *
+   * Extends the base class method to add stdinData containing the prompt.
+   * This allows passing prompts via stdin instead of CLI arguments,
+   * avoiding shell escaping issues with special characters.
+   *
+   * @param options - Execution options
+   * @param cliArgs - CLI arguments from buildCliArgs
+   * @returns SubprocessOptions with stdinData set
+   */
+  protected buildSubprocessOptions(options: ExecuteOptions, cliArgs: string[]): SubprocessOptions {
+    const subprocessOptions = super.buildSubprocessOptions(options, cliArgs);
+
+    // Pass prompt via stdin to avoid shell interpretation of special characters
+    // like $(), backticks, quotes, etc. that may appear in prompts or file content
+    subprocessOptions.stdinData = this.extractPromptText(options);
+
+    return subprocessOptions;
+  }
+
+  /**
+   * Normalize a raw CLI event to ProviderMessage format
+   *
+   * Maps OpenCode event types to the standard ProviderMessage structure:
+   * - text -> type: 'assistant', content with type: 'text'
+   * - step_start -> null (informational, no message needed)
+   * - step_finish -> type: 'result', subtype: 'success' (or error if failed)
+   * - tool_call -> type: 'assistant', content with type: 'tool_use'
+   * - tool_result -> type: 'assistant', content with type: 'tool_result'
+   * - tool_error -> type: 'error'
+   *
+   * @param event - Raw event from OpenCode CLI JSONL output
+   * @returns Normalized ProviderMessage or null to skip the event
+   */
+  normalizeEvent(event: unknown): ProviderMessage | null {
+    if (!event || typeof event !== 'object') {
+      return null;
+    }
+
+    const openCodeEvent = event as OpenCodeStreamEvent;
+
+    switch (openCodeEvent.type) {
+      case 'text': {
+        const textEvent = openCodeEvent as OpenCodeTextEvent;
+
+        // Skip if no text content
+        if (!textEvent.part?.text) {
+          return null;
+        }
+
+        const content: ContentBlock[] = [
+          {
+            type: 'text',
+            text: textEvent.part.text,
+          },
+        ];
+
+        return {
+          type: 'assistant',
+          session_id: textEvent.sessionID,
+          message: {
+            role: 'assistant',
+            content,
+          },
+        };
+      }
+
+      case 'step_start': {
+        // Start step is informational - no message needed
+        return null;
+      }
+
+      case 'step_finish': {
+        const finishEvent = openCodeEvent as OpenCodeFinishStepEvent;
+
+        // Check if the step failed (either has error field or reason is 'error')
+        if (finishEvent.part?.error || finishEvent.part?.reason === 'error') {
+          return {
+            type: 'error',
+            session_id: finishEvent.sessionID,
+            error: finishEvent.part?.error || 'Step execution failed',
+          };
+        }
+
+        // Successful completion
+        const result: { type: 'result'; subtype: 'success'; session_id?: string; result?: string } =
+          {
+            type: 'result',
+            subtype: 'success',
+          };
+
+        if (finishEvent.sessionID) {
+          result.session_id = finishEvent.sessionID;
+        }
+
+        // Safely handle arbitrary result payloads from CLI: ensure we assign a string.
+        const rawResult =
+          (finishEvent.part && (finishEvent.part as Record<string, unknown>).result) ?? undefined;
+        if (rawResult !== undefined) {
+          result.result = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
+        }
+
+        return result;
+      }
+
+      case 'tool_call': {
+        const toolEvent = openCodeEvent as OpenCodeToolCallEvent;
+
+        if (!toolEvent.part) {
+          return null;
+        }
+
+        // Generate a tool use ID if not provided
+        const toolUseId = toolEvent.part.call_id || generateToolUseId();
+
+        const content: ContentBlock[] = [
+          {
+            type: 'tool_use',
+            name: toolEvent.part.name,
+            tool_use_id: toolUseId,
+            input: toolEvent.part.args,
+          },
+        ];
+
+        return {
+          type: 'assistant',
+          session_id: toolEvent.sessionID,
+          message: {
+            role: 'assistant',
+            content,
+          },
+        };
+      }
+
+      case 'tool_result': {
+        const resultEvent = openCodeEvent as OpenCodeToolResultEvent;
+
+        if (!resultEvent.part) {
+          return null;
+        }
+
+        const content: ContentBlock[] = [
+          {
+            type: 'tool_result',
+            tool_use_id: resultEvent.part.call_id,
+            content: resultEvent.part.output,
+          },
+        ];
+
+        return {
+          type: 'assistant',
+          session_id: resultEvent.sessionID,
+          message: {
+            role: 'assistant',
+            content,
+          },
+        };
+      }
+
+      case 'tool_error': {
+        const errorEvent = openCodeEvent as OpenCodeToolErrorEvent;
+
+        return {
+          type: 'error',
+          session_id: errorEvent.sessionID,
+          error: errorEvent.part?.error || 'Tool execution failed',
+        };
+      }
+
+      default: {
+        // Unknown event type - skip it
+        return null;
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Model Configuration
+  // ==========================================================================
+
+  /**
+   * Get available models for OpenCode
+   *
+   * Returns model definitions for supported AI providers:
+   * - Anthropic Claude models (Sonnet, Opus, Haiku)
+   * - OpenAI GPT-4o
+   * - Google Gemini 2.5 Pro
+   */
+  getAvailableModels(): ModelDefinition[] {
+    return [
+      // OpenCode Free Tier Models
+      {
+        id: 'opencode/big-pickle',
+        name: 'Big Pickle (Free)',
+        modelString: 'opencode/big-pickle',
+        provider: 'opencode',
+        description: 'OpenCode free tier model - great for general coding',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'basic',
+      },
+      {
+        id: 'opencode/gpt-5-nano',
+        name: 'GPT-5 Nano (Free)',
+        modelString: 'opencode/gpt-5-nano',
+        provider: 'opencode',
+        description: 'Fast and lightweight free tier model',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'basic',
+      },
+      {
+        id: 'opencode/grok-code',
+        name: 'Grok Code (Free)',
+        modelString: 'opencode/grok-code',
+        provider: 'opencode',
+        description: 'OpenCode free tier Grok model for coding',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'basic',
+      },
+      // Amazon Bedrock - Claude Models
+      {
+        id: 'amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0',
+        name: 'Claude Sonnet 4.5 (Bedrock)',
+        modelString: 'amazon-bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0',
+        provider: 'opencode',
+        description: 'Latest Claude Sonnet via AWS Bedrock - fast and intelligent',
+        supportsTools: true,
+        supportsVision: true,
+        tier: 'premium',
+        default: true,
+      },
+      {
+        id: 'amazon-bedrock/anthropic.claude-opus-4-5-20251101-v1:0',
+        name: 'Claude Opus 4.5 (Bedrock)',
+        modelString: 'amazon-bedrock/anthropic.claude-opus-4-5-20251101-v1:0',
+        provider: 'opencode',
+        description: 'Most capable Claude model via AWS Bedrock',
+        supportsTools: true,
+        supportsVision: true,
+        tier: 'premium',
+      },
+      {
+        id: 'amazon-bedrock/anthropic.claude-haiku-4-5-20251001-v1:0',
+        name: 'Claude Haiku 4.5 (Bedrock)',
+        modelString: 'amazon-bedrock/anthropic.claude-haiku-4-5-20251001-v1:0',
+        provider: 'opencode',
+        description: 'Fastest Claude model via AWS Bedrock',
+        supportsTools: true,
+        supportsVision: true,
+        tier: 'standard',
+      },
+      // Amazon Bedrock - DeepSeek Models
+      {
+        id: 'amazon-bedrock/deepseek.r1-v1:0',
+        name: 'DeepSeek R1 (Bedrock)',
+        modelString: 'amazon-bedrock/deepseek.r1-v1:0',
+        provider: 'opencode',
+        description: 'DeepSeek R1 reasoning model - excellent for coding',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'premium',
+      },
+      // Amazon Bedrock - Amazon Nova Models
+      {
+        id: 'amazon-bedrock/amazon.nova-pro-v1:0',
+        name: 'Amazon Nova Pro (Bedrock)',
+        modelString: 'amazon-bedrock/amazon.nova-pro-v1:0',
+        provider: 'opencode',
+        description: 'Amazon Nova Pro - balanced performance',
+        supportsTools: true,
+        supportsVision: true,
+        tier: 'standard',
+      },
+      // Amazon Bedrock - Meta Llama Models
+      {
+        id: 'amazon-bedrock/meta.llama4-maverick-17b-instruct-v1:0',
+        name: 'Llama 4 Maverick 17B (Bedrock)',
+        modelString: 'amazon-bedrock/meta.llama4-maverick-17b-instruct-v1:0',
+        provider: 'opencode',
+        description: 'Meta Llama 4 Maverick via AWS Bedrock',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'standard',
+      },
+      // Amazon Bedrock - Qwen Models
+      {
+        id: 'amazon-bedrock/qwen.qwen3-coder-480b-a35b-v1:0',
+        name: 'Qwen3 Coder 480B (Bedrock)',
+        modelString: 'amazon-bedrock/qwen.qwen3-coder-480b-a35b-v1:0',
+        provider: 'opencode',
+        description: 'Qwen3 Coder 480B - excellent for coding',
+        supportsTools: true,
+        supportsVision: false,
+        tier: 'premium',
+      },
+    ];
+  }
+
+  // ==========================================================================
+  // Feature Support
+  // ==========================================================================
+
+  /**
+   * Check if a feature is supported by OpenCode
+   *
+   * Supported features:
+   * - tools: Function calling / tool use
+   * - text: Text generation
+   * - vision: Image understanding
+   */
+  supportsFeature(feature: string): boolean {
+    const supportedFeatures = ['tools', 'text', 'vision'];
+    return supportedFeatures.includes(feature);
+  }
+
+  // ==========================================================================
+  // Authentication
+  // ==========================================================================
+
+  /**
+   * Check authentication status for OpenCode CLI
+   *
+   * Checks for authentication via:
+   * - OAuth token in auth file
+   * - API key in auth file
+   */
+  async checkAuth(): Promise<OpenCodeAuthStatus> {
+    const authIndicators = await getOpenCodeAuthIndicators();
+
+    // Check for OAuth token
+    if (authIndicators.hasOAuthToken) {
+      return {
+        authenticated: true,
+        method: 'oauth',
+        hasOAuthToken: true,
+        hasApiKey: authIndicators.hasApiKey,
+      };
+    }
+
+    // Check for API key
+    if (authIndicators.hasApiKey) {
+      return {
+        authenticated: true,
+        method: 'api_key',
+        hasOAuthToken: false,
+        hasApiKey: true,
+      };
+    }
+
+    return {
+      authenticated: false,
+      method: 'none',
+      hasOAuthToken: false,
+      hasApiKey: false,
+    };
+  }
+
+  // ==========================================================================
+  // Installation Detection
+  // ==========================================================================
+
+  /**
+   * Detect OpenCode installation status
+   *
+   * Checks if the opencode CLI is available either through:
+   * - Direct installation (npm global)
+   * - NPX (fallback on Windows)
+   * Also checks authentication status.
+   */
+  async detectInstallation(): Promise<InstallationStatus> {
+    this.ensureCliDetected();
+
+    const installed = await this.isInstalled();
+    const auth = await this.checkAuth();
+
+    return {
+      installed,
+      path: this.cliPath || undefined,
+      method: this.detectedStrategy === 'npx' ? 'npm' : 'cli',
+      authenticated: auth.authenticated,
+      hasApiKey: auth.hasApiKey,
+      hasOAuthToken: auth.hasOAuthToken,
+    };
+  }
+}

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

@@ -1,51 +1,168 @@
 /**
  * Provider Factory - Routes model IDs to the appropriate provider
  *
- * This factory implements model-based routing to automatically select
- * the correct provider based on the model string. This makes adding
- * new providers (Cursor, OpenCode, etc.) trivial - just add one line.
+ * Uses a registry pattern for dynamic provider registration.
+ * Providers register themselves on import, making it easy to add new providers.
  */
 
 import { BaseProvider } from './base-provider.js';
-import { ClaudeProvider } from './claude-provider.js';
-import type { InstallationStatus } from './types.js';
+import type { InstallationStatus, ModelDefinition } from './types.js';
+import { isCursorModel, isCodexModel, isOpencodeModel, type ModelProvider } from '@automaker/types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const DISCONNECTED_MARKERS: Record<string, string> = {
+  claude: '.claude-disconnected',
+  codex: '.codex-disconnected',
+  cursor: '.cursor-disconnected',
+  opencode: '.opencode-disconnected',
+};
+
+/**
+ * Check if a provider CLI is disconnected from the app
+ */
+export function isProviderDisconnected(providerName: string): boolean {
+  const markerFile = DISCONNECTED_MARKERS[providerName.toLowerCase()];
+  if (!markerFile) return false;
+
+  const markerPath = path.join(process.cwd(), '.automaker', markerFile);
+  return fs.existsSync(markerPath);
+}
+
+/**
+ * Provider registration entry
+ */
+interface ProviderRegistration {
+  /** Factory function to create provider instance */
+  factory: () => BaseProvider;
+  /** Aliases for this provider (e.g., 'anthropic' for 'claude') */
+  aliases?: string[];
+  /** Function to check if this provider can handle a model ID */
+  canHandleModel?: (modelId: string) => boolean;
+  /** Priority for model matching (higher = checked first) */
+  priority?: number;
+}
+
+/**
+ * Provider registry - stores registered providers
+ */
+const providerRegistry = new Map<string, ProviderRegistration>();
+
+/**
+ * Register a provider with the factory
+ *
+ * @param name Provider name (e.g., 'claude', 'cursor')
+ * @param registration Provider registration config
+ */
+export function registerProvider(name: string, registration: ProviderRegistration): void {
+  providerRegistry.set(name.toLowerCase(), registration);
+}
 
 export class ProviderFactory {
   /**
-   * Get the appropriate provider for a given model ID
+   * Determine which provider to use for a given model
    *
-   * @param modelId Model identifier (e.g., "claude-opus-4-5-20251101", "gpt-5.2", "cursor-fast")
-   * @returns Provider instance for the model
+   * @param model Model identifier
+   * @returns Provider name (ModelProvider type)
    */
-  static getProviderForModel(modelId: string): BaseProvider {
-    const lowerModel = modelId.toLowerCase();
+  static getProviderNameForModel(model: string): ModelProvider {
+    const lowerModel = model.toLowerCase();
 
-    // Claude models (claude-*, opus, sonnet, haiku)
-    if (lowerModel.startsWith('claude-') || ['haiku', 'sonnet', 'opus'].includes(lowerModel)) {
-      return new ClaudeProvider();
+    // Get all registered providers sorted by priority (descending)
+    const registrations = Array.from(providerRegistry.entries()).sort(
+      ([, a], [, b]) => (b.priority ?? 0) - (a.priority ?? 0)
+    );
+
+    // Check each provider's canHandleModel function
+    for (const [name, reg] of registrations) {
+      if (reg.canHandleModel?.(lowerModel)) {
+        return name as ModelProvider;
+      }
     }
 
-    // Future providers:
-    // if (lowerModel.startsWith("cursor-")) {
-    //   return new CursorProvider();
-    // }
-    // if (lowerModel.startsWith("opencode-")) {
-    //   return new OpenCodeProvider();
-    // }
+    // Fallback: Check for explicit prefixes
+    for (const [name] of registrations) {
+      if (lowerModel.startsWith(`${name}-`)) {
+        return name as ModelProvider;
+      }
+    }
 
-    // Default to Claude for unknown models
-    console.warn(`[ProviderFactory] Unknown model prefix for "${modelId}", defaulting to Claude`);
-    return new ClaudeProvider();
+    // Default to claude (first registered provider or claude)
+    return 'claude';
+  }
+
+  /**
+   * Get the appropriate provider for a given model ID
+   *
+   * @param modelId Model identifier (e.g., "claude-opus-4-5-20251101", "cursor-gpt-4o", "cursor-auto")
+   * @param options Optional settings
+   * @param options.throwOnDisconnected Throw error if provider is disconnected (default: true)
+   * @returns Provider instance for the model
+   * @throws Error if provider is disconnected and throwOnDisconnected is true
+   */
+  static getProviderForModel(
+    modelId: string,
+    options: { throwOnDisconnected?: boolean } = {}
+  ): BaseProvider {
+    const { throwOnDisconnected = true } = options;
+    const providerName = this.getProviderForModelName(modelId);
+
+    // Check if provider is disconnected
+    if (throwOnDisconnected && isProviderDisconnected(providerName)) {
+      throw new Error(
+        `${providerName.charAt(0).toUpperCase() + providerName.slice(1)} CLI is disconnected from the app. ` +
+          `Please go to Settings > Providers and click "Sign In" to reconnect.`
+      );
+    }
+
+    const provider = this.getProviderByName(providerName);
+
+    if (!provider) {
+      // Fallback to claude if provider not found
+      const claudeReg = providerRegistry.get('claude');
+      if (claudeReg) {
+        return claudeReg.factory();
+      }
+      throw new Error(`No provider found for model: ${modelId}`);
+    }
+
+    return provider;
+  }
+
+  /**
+   * Get the provider name for a given model ID (without creating provider instance)
+   */
+  static getProviderForModelName(modelId: string): string {
+    const lowerModel = modelId.toLowerCase();
+
+    // Get all registered providers sorted by priority (descending)
+    const registrations = Array.from(providerRegistry.entries()).sort(
+      ([, a], [, b]) => (b.priority ?? 0) - (a.priority ?? 0)
+    );
+
+    // Check each provider's canHandleModel function
+    for (const [name, reg] of registrations) {
+      if (reg.canHandleModel?.(lowerModel)) {
+        return name;
+      }
+    }
+
+    // Fallback: Check for explicit prefixes
+    for (const [name] of registrations) {
+      if (lowerModel.startsWith(`${name}-`)) {
+        return name;
+      }
+    }
+
+    // Default to claude (first registered provider or claude)
+    return 'claude';
   }
 
   /**
    * Get all available providers
    */
   static getAllProviders(): BaseProvider[] {
-    return [
-      new ClaudeProvider(),
-      // Future providers...
-    ];
+    return Array.from(providerRegistry.values()).map((reg) => reg.factory());
   }
 
   /**
@@ -54,11 +171,10 @@ export class ProviderFactory {
    * @returns Map of provider name to installation status
    */
   static async checkAllProviders(): Promise<Record<string, InstallationStatus>> {
-    const providers = this.getAllProviders();
     const statuses: Record<string, InstallationStatus> = {};
 
-    for (const provider of providers) {
-      const name = provider.getName();
+    for (const [name, reg] of providerRegistry.entries()) {
+      const provider = reg.factory();
       const status = await provider.detectInstallation();
       statuses[name] = status;
     }
@@ -69,40 +185,119 @@ export class ProviderFactory {
   /**
    * Get provider by name (for direct access if needed)
    *
-   * @param name Provider name (e.g., "claude", "cursor")
+   * @param name Provider name (e.g., "claude", "cursor") or alias (e.g., "anthropic")
    * @returns Provider instance or null if not found
    */
   static getProviderByName(name: string): BaseProvider | null {
     const lowerName = name.toLowerCase();
 
-    switch (lowerName) {
-      case 'claude':
-      case 'anthropic':
-        return new ClaudeProvider();
-
-      // Future providers:
-      // case "cursor":
-      //   return new CursorProvider();
-      // case "opencode":
-      //   return new OpenCodeProvider();
-
-      default:
-        return null;
+    // Direct lookup
+    const directReg = providerRegistry.get(lowerName);
+    if (directReg) {
+      return directReg.factory();
     }
+
+    // Check aliases
+    for (const [, reg] of providerRegistry.entries()) {
+      if (reg.aliases?.includes(lowerName)) {
+        return reg.factory();
+      }
+    }
+
+    return null;
   }
 
   /**
    * Get all available models from all providers
    */
-  static getAllAvailableModels() {
+  static getAllAvailableModels(): ModelDefinition[] {
     const providers = this.getAllProviders();
-    const allModels = [];
+    return providers.flatMap((p) => p.getAvailableModels());
+  }
 
-    for (const provider of providers) {
-      const models = provider.getAvailableModels();
-      allModels.push(...models);
+  /**
+   * Get list of registered provider names
+   */
+  static getRegisteredProviderNames(): string[] {
+    return Array.from(providerRegistry.keys());
+  }
+
+  /**
+   * Check if a specific model supports vision/image input
+   *
+   * @param modelId Model identifier
+   * @returns Whether the model supports vision (defaults to true if model not found)
+   */
+  static modelSupportsVision(modelId: string): boolean {
+    const provider = this.getProviderForModel(modelId);
+    const models = provider.getAvailableModels();
+
+    // Find the model in the available models list
+    for (const model of models) {
+      if (
+        model.id === modelId ||
+        model.modelString === modelId ||
+        model.id.endsWith(`-${modelId}`) ||
+        model.modelString.endsWith(`-${modelId}`) ||
+        model.modelString === modelId.replace(/^(claude|cursor|codex)-/, '') ||
+        model.modelString === modelId.replace(/-(claude|cursor|codex)$/, '')
+      ) {
+        return model.supportsVision ?? true;
+      }
     }
 
-    return allModels;
+    // Also try exact match with model string from provider's model map
+    for (const model of models) {
+      if (model.modelString === modelId || model.id === modelId) {
+        return model.supportsVision ?? true;
+      }
+    }
+
+    // Default to true (Claude SDK supports vision by default)
+    return true;
   }
 }
+
+// =============================================================================
+// Provider Registrations
+// =============================================================================
+
+// Import providers for registration side-effects
+import { ClaudeProvider } from './claude-provider.js';
+import { CursorProvider } from './cursor-provider.js';
+import { CodexProvider } from './codex-provider.js';
+import { OpencodeProvider } from './opencode-provider.js';
+
+// Register Claude provider
+registerProvider('claude', {
+  factory: () => new ClaudeProvider(),
+  aliases: ['anthropic'],
+  canHandleModel: (model: string) => {
+    return (
+      model.startsWith('claude-') || ['opus', 'sonnet', 'haiku'].some((n) => model.includes(n))
+    );
+  },
+  priority: 0, // Default priority
+});
+
+// Register Cursor provider
+registerProvider('cursor', {
+  factory: () => new CursorProvider(),
+  canHandleModel: (model: string) => isCursorModel(model),
+  priority: 10, // Higher priority - check Cursor models first
+});
+
+// Register Codex provider
+registerProvider('codex', {
+  factory: () => new CodexProvider(),
+  aliases: ['openai'],
+  canHandleModel: (model: string) => isCodexModel(model),
+  priority: 5, // Medium priority - check after Cursor but before Claude
+});
+
+// Register OpenCode provider
+registerProvider('opencode', {
+  factory: () => new OpencodeProvider(),
+  canHandleModel: (model: string) => isOpencodeModel(model),
+  priority: 3, // Between codex (5) and claude (0)
+});

apps/server/src/providers/types.ts

@@ -1,104 +1,22 @@
 /**
  * Shared types for AI model providers
+ *
+ * Re-exports types from @automaker/types for consistency across the codebase.
+ * All provider types are defined in @automaker/types to avoid duplication.
  */
 
-/**
- * Configuration for a provider instance
- */
-export interface ProviderConfig {
-  apiKey?: string;
-  cliPath?: string;
-  env?: Record<string, string>;
-}
-
-/**
- * Message in conversation history
- */
-export interface ConversationMessage {
-  role: 'user' | 'assistant';
-  content: string | Array<{ type: string; text?: string; source?: object }>;
-}
-
-/**
- * Options for executing a query via a provider
- */
-export interface ExecuteOptions {
-  prompt: string | Array<{ type: string; text?: string; source?: object }>;
-  model: string;
-  cwd: string;
-  systemPrompt?: string;
-  maxTurns?: number;
-  allowedTools?: string[];
-  mcpServers?: Record<string, unknown>;
-  abortController?: AbortController;
-  conversationHistory?: ConversationMessage[]; // Previous messages for context
-  sdkSessionId?: string; // Claude SDK session ID for resuming conversations
-}
-
-/**
- * Content block in a provider message (matches Claude SDK format)
- */
-export interface ContentBlock {
-  type: 'text' | 'tool_use' | 'thinking' | 'tool_result';
-  text?: string;
-  thinking?: string;
-  name?: string;
-  input?: unknown;
-  tool_use_id?: string;
-  content?: string;
-}
-
-/**
- * Message returned by a provider (matches Claude SDK streaming format)
- */
-export interface ProviderMessage {
-  type: 'assistant' | 'user' | 'error' | 'result';
-  subtype?: 'success' | 'error';
-  session_id?: string;
-  message?: {
-    role: 'user' | 'assistant';
-    content: ContentBlock[];
-  };
-  result?: string;
-  error?: string;
-  parent_tool_use_id?: string | null;
-}
-
-/**
- * Installation status for a provider
- */
-export interface InstallationStatus {
-  installed: boolean;
-  path?: string;
-  version?: string;
-  method?: 'cli' | 'npm' | 'brew' | 'sdk';
-  hasApiKey?: boolean;
-  authenticated?: boolean;
-  error?: string;
-}
-
-/**
- * Validation result
- */
-export interface ValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings?: string[];
-}
-
-/**
- * Model definition
- */
-export interface ModelDefinition {
-  id: string;
-  name: string;
-  modelString: string;
-  provider: string;
-  description: string;
-  contextWindow?: number;
-  maxOutputTokens?: number;
-  supportsVision?: boolean;
-  supportsTools?: boolean;
-  tier?: 'basic' | 'standard' | 'premium';
-  default?: boolean;
-}
+// Re-export all provider types from @automaker/types
+export type {
+  ProviderConfig,
+  ConversationMessage,
+  ExecuteOptions,
+  McpServerConfig,
+  McpStdioServerConfig,
+  McpSSEServerConfig,
+  McpHttpServerConfig,
+  ContentBlock,
+  ProviderMessage,
+  InstallationStatus,
+  ValidationResult,
+  ModelDefinition,
+} from '@automaker/types';

apps/server/src/routes/agent/index.ts

@@ -12,6 +12,10 @@ import { createHistoryHandler } from './routes/history.js';
 import { createStopHandler } from './routes/stop.js';
 import { createClearHandler } from './routes/clear.js';
 import { createModelHandler } from './routes/model.js';
+import { createQueueAddHandler } from './routes/queue-add.js';
+import { createQueueListHandler } from './routes/queue-list.js';
+import { createQueueRemoveHandler } from './routes/queue-remove.js';
+import { createQueueClearHandler } from './routes/queue-clear.js';
 
 export function createAgentRoutes(agentService: AgentService, _events: EventEmitter): Router {
   const router = Router();
@@ -27,5 +31,15 @@ export function createAgentRoutes(agentService: AgentService, _events: EventEmit
   router.post('/clear', createClearHandler(agentService));
   router.post('/model', createModelHandler(agentService));
 
+  // Queue routes
+  router.post(
+    '/queue/add',
+    validatePathParams('imagePaths[]'),
+    createQueueAddHandler(agentService)
+  );
+  router.post('/queue/list', createQueueListHandler(agentService));
+  router.post('/queue/remove', createQueueRemoveHandler(agentService));
+  router.post('/queue/clear', createQueueClearHandler(agentService));
+
   return router;
 }

apps/server/src/routes/agent/routes/queue-add.ts

@@ -0,0 +1,41 @@
+/**
+ * POST /queue/add endpoint - Add a prompt to the queue
+ */
+
+import type { Request, Response } from 'express';
+import type { ThinkingLevel } from '@automaker/types';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueAddHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId, message, imagePaths, model, thinkingLevel } = req.body as {
+        sessionId: string;
+        message: string;
+        imagePaths?: string[];
+        model?: string;
+        thinkingLevel?: ThinkingLevel;
+      };
+
+      if (!sessionId || !message) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId and message are required',
+        });
+        return;
+      }
+
+      const result = await agentService.addToQueue(sessionId, {
+        message,
+        imagePaths,
+        model,
+        thinkingLevel,
+      });
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Add to queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-clear.ts

@@ -0,0 +1,29 @@
+/**
+ * POST /queue/clear endpoint - Clear all prompts from the queue
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueClearHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId } = req.body as { sessionId: string };
+
+      if (!sessionId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId is required',
+        });
+        return;
+      }
+
+      const result = await agentService.clearQueue(sessionId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Clear queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-list.ts

@@ -0,0 +1,29 @@
+/**
+ * POST /queue/list endpoint - List queued prompts
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueListHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId } = req.body as { sessionId: string };
+
+      if (!sessionId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId is required',
+        });
+        return;
+      }
+
+      const result = agentService.getQueue(sessionId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'List queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/queue-remove.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /queue/remove endpoint - Remove a prompt from the queue
+ */
+
+import type { Request, Response } from 'express';
+import { AgentService } from '../../../services/agent-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createQueueRemoveHandler(agentService: AgentService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId, promptId } = req.body as {
+        sessionId: string;
+        promptId: string;
+      };
+
+      if (!sessionId || !promptId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId and promptId are required',
+        });
+        return;
+      }
+
+      const result = await agentService.removeFromQueue(sessionId, promptId);
+      res.json(result);
+    } catch (error) {
+      logError(error, 'Remove from queue failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/agent/routes/send.ts

@@ -3,6 +3,7 @@
  */
 
 import type { Request, Response } from 'express';
+import type { ThinkingLevel } from '@automaker/types';
 import { AgentService } from '../../../services/agent-service.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
@@ -11,15 +12,27 @@ const logger = createLogger('Agent');
 export function createSendHandler(agentService: AgentService) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
-      const { sessionId, message, workingDirectory, imagePaths, model } = req.body as {
-        sessionId: string;
-        message: string;
-        workingDirectory?: string;
-        imagePaths?: string[];
-        model?: string;
-      };
+      const { sessionId, message, workingDirectory, imagePaths, model, thinkingLevel } =
+        req.body as {
+          sessionId: string;
+          message: string;
+          workingDirectory?: string;
+          imagePaths?: string[];
+          model?: string;
+          thinkingLevel?: ThinkingLevel;
+        };
+
+      logger.debug('Received request:', {
+        sessionId,
+        messageLength: message?.length,
+        workingDirectory,
+        imageCount: imagePaths?.length || 0,
+        model,
+        thinkingLevel,
+      });
 
       if (!sessionId || !message) {
+        logger.warn('Validation failed - missing sessionId or message');
         res.status(400).json({
           success: false,
           error: 'sessionId and message are required',
@@ -27,6 +40,8 @@ export function createSendHandler(agentService: AgentService) {
         return;
       }
 
+      logger.debug('Validation passed, calling agentService.sendMessage()');
+
       // Start the message processing (don't await - it streams via WebSocket)
       agentService
         .sendMessage({
@@ -35,14 +50,19 @@ export function createSendHandler(agentService: AgentService) {
           workingDirectory,
           imagePaths,
           model,
+          thinkingLevel,
         })
         .catch((error) => {
+          logger.error('Background error in sendMessage():', error);
           logError(error, 'Send message failed (background)');
         });
 
+      logger.debug('Returning immediate response to client');
+
       // Return immediately - responses come via WebSocket
       res.json({ success: true, message: 'Message sent' });
     } catch (error) {
+      logger.error('Synchronous error:', error);
       logError(error, 'Send message failed');
       res.status(500).json({ success: false, error: getErrorMessage(error) });
     }

apps/server/src/routes/app-spec/common.ts

@@ -6,26 +6,57 @@ import { createLogger } from '@automaker/utils';
 
 const logger = createLogger('SpecRegeneration');
 
-// Shared state for tracking generation status - private
-let isRunning = false;
-let currentAbortController: AbortController | null = null;
+// Shared state for tracking generation status - scoped by project path
+const runningProjects = new Map<string, boolean>();
+const abortControllers = new Map<string, AbortController>();
 
 /**
- * Get the current running state
+ * Get the running state for a specific project
  */
-export function getSpecRegenerationStatus(): {
+export function getSpecRegenerationStatus(projectPath?: string): {
   isRunning: boolean;
   currentAbortController: AbortController | null;
+  projectPath?: string;
 } {
-  return { isRunning, currentAbortController };
+  if (projectPath) {
+    return {
+      isRunning: runningProjects.get(projectPath) || false,
+      currentAbortController: abortControllers.get(projectPath) || null,
+      projectPath,
+    };
+  }
+  // Fallback: check if any project is running (for backward compatibility)
+  const isAnyRunning = Array.from(runningProjects.values()).some((running) => running);
+  return { isRunning: isAnyRunning, currentAbortController: null };
 }
 
 /**
- * Set the running state and abort controller
+ * Get the project path that is currently running (if any)
  */
-export function setRunningState(running: boolean, controller: AbortController | null = null): void {
-  isRunning = running;
-  currentAbortController = controller;
+export function getRunningProjectPath(): string | null {
+  for (const [path, running] of runningProjects.entries()) {
+    if (running) return path;
+  }
+  return null;
+}
+
+/**
+ * Set the running state and abort controller for a specific project
+ */
+export function setRunningState(
+  projectPath: string,
+  running: boolean,
+  controller: AbortController | null = null
+): void {
+  if (running) {
+    runningProjects.set(projectPath, true);
+    if (controller) {
+      abortControllers.set(projectPath, controller);
+    }
+  } else {
+    runningProjects.delete(projectPath);
+    abortControllers.delete(projectPath);
+  }
 }
 
 /**

apps/server/src/routes/app-spec/generate-features-from-spec.ts

@@ -1,15 +1,23 @@
 /**
  * Generate features from existing app_spec.txt
+ *
+ * Model is configurable via phaseModels.featureGenerationModel in settings
+ * (defaults to Sonnet for balanced speed and quality).
  */
 
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import * as secureFs from '../../lib/secure-fs.js';
 import type { EventEmitter } from '../../lib/events.js';
 import { createLogger } from '@automaker/utils';
+import { DEFAULT_PHASE_MODELS, isCursorModel, stripProviderPrefix } from '@automaker/types';
+import { resolvePhaseModel } from '@automaker/model-resolver';
 import { createFeatureGenerationOptions } from '../../lib/sdk-options.js';
+import { ProviderFactory } from '../../providers/provider-factory.js';
 import { logAuthStatus } from './common.js';
 import { parseAndCreateFeatures } from './parse-and-create-features.js';
 import { getAppSpecPath } from '@automaker/platform';
+import type { SettingsService } from '../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
 
 const logger = createLogger('SpecRegeneration');
 
@@ -19,7 +27,8 @@ export async function generateFeaturesFromSpec(
   projectPath: string,
   events: EventEmitter,
   abortController: AbortController,
-  maxFeatures?: number
+  maxFeatures?: number,
+  settingsService?: SettingsService
 ): Promise<void> {
   const featureCount = maxFeatures ?? DEFAULT_MAX_FEATURES;
   logger.debug('========== generateFeaturesFromSpec() started ==========');
@@ -91,42 +100,55 @@ IMPORTANT: Do not ask for clarification. The specification is provided above. Ge
     projectPath: projectPath,
   });
 
-  const options = createFeatureGenerationOptions({
-    cwd: projectPath,
-    abortController,
-  });
+  // Load autoLoadClaudeMd setting
+  const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+    projectPath,
+    settingsService,
+    '[FeatureGeneration]'
+  );
 
-  logger.debug('SDK Options:', JSON.stringify(options, null, 2));
-  logger.info('Calling Claude Agent SDK query() for features...');
+  // Get model from phase settings
+  const settings = await settingsService?.getGlobalSettings();
+  const phaseModelEntry =
+    settings?.phaseModels?.featureGenerationModel || DEFAULT_PHASE_MODELS.featureGenerationModel;
+  const { model, thinkingLevel } = resolvePhaseModel(phaseModelEntry);
 
-  logAuthStatus('Right before SDK query() for features');
-
-  let stream;
-  try {
-    stream = query({ prompt, options });
-    logger.debug('query() returned stream successfully');
-  } catch (queryError) {
-    logger.error('❌ query() threw an exception:');
-    logger.error('Error:', queryError);
-    throw queryError;
-  }
+  logger.info('Using model:', model);
 
   let responseText = '';
   let messageCount = 0;
 
-  logger.debug('Starting to iterate over feature stream...');
+  // Route to appropriate provider based on model type
+  if (isCursorModel(model)) {
+    // Use Cursor provider for Cursor models
+    logger.info('[FeatureGeneration] Using Cursor provider');
 
-  try {
-    for await (const msg of stream) {
+    const provider = ProviderFactory.getProviderForModel(model);
+    // Strip provider prefix - providers expect bare model IDs
+    const bareModel = stripProviderPrefix(model);
+
+    // Add explicit instructions for Cursor to return JSON in response
+    const cursorPrompt = `${prompt}
+
+CRITICAL INSTRUCTIONS:
+1. DO NOT write any files. Return the JSON in your response only.
+2. Respond with ONLY a JSON object - no explanations, no markdown, just raw JSON.
+3. Your entire response should be valid JSON starting with { and ending with }. No text before or after.`;
+
+    for await (const msg of provider.executeQuery({
+      prompt: cursorPrompt,
+      model: bareModel,
+      cwd: projectPath,
+      maxTurns: 250,
+      allowedTools: ['Read', 'Glob', 'Grep'],
+      abortController,
+      readOnly: true, // Feature generation only reads code, doesn't write
+    })) {
       messageCount++;
-      logger.debug(
-        `Feature stream message #${messageCount}:`,
-        JSON.stringify({ type: msg.type, subtype: (msg as any).subtype }, null, 2)
-      );
 
-      if (msg.type === 'assistant' && msg.message.content) {
+      if (msg.type === 'assistant' && msg.message?.content) {
         for (const block of msg.message.content) {
-          if (block.type === 'text') {
+          if (block.type === 'text' && block.text) {
             responseText += block.text;
             logger.debug(`Feature text block received (${block.text.length} chars)`);
             events.emit('spec-regeneration:event', {
@@ -136,18 +158,75 @@ IMPORTANT: Do not ask for clarification. The specification is provided above. Ge
             });
           }
         }
-      } else if (msg.type === 'result' && (msg as any).subtype === 'success') {
-        logger.debug('Received success result for features');
-        responseText = (msg as any).result || responseText;
-      } else if ((msg as { type: string }).type === 'error') {
-        logger.error('❌ Received error message from feature stream:');
-        logger.error('Error message:', JSON.stringify(msg, null, 2));
+      } else if (msg.type === 'result' && msg.subtype === 'success' && msg.result) {
+        // Use result if it's a final accumulated message
+        if (msg.result.length > responseText.length) {
+          responseText = msg.result;
+        }
       }
     }
-  } catch (streamError) {
-    logger.error('❌ Error while iterating feature stream:');
-    logger.error('Stream error:', streamError);
-    throw streamError;
+  } else {
+    // Use Claude SDK for Claude models
+    logger.info('[FeatureGeneration] Using Claude SDK');
+
+    const options = createFeatureGenerationOptions({
+      cwd: projectPath,
+      abortController,
+      autoLoadClaudeMd,
+      model,
+      thinkingLevel, // Pass thinking level for extended thinking
+    });
+
+    logger.debug('SDK Options:', JSON.stringify(options, null, 2));
+    logger.info('Calling Claude Agent SDK query() for features...');
+
+    logAuthStatus('Right before SDK query() for features');
+
+    let stream;
+    try {
+      stream = query({ prompt, options });
+      logger.debug('query() returned stream successfully');
+    } catch (queryError) {
+      logger.error('❌ query() threw an exception:');
+      logger.error('Error:', queryError);
+      throw queryError;
+    }
+
+    logger.debug('Starting to iterate over feature stream...');
+
+    try {
+      for await (const msg of stream) {
+        messageCount++;
+        logger.debug(
+          `Feature stream message #${messageCount}:`,
+          JSON.stringify({ type: msg.type, subtype: (msg as any).subtype }, null, 2)
+        );
+
+        if (msg.type === 'assistant' && msg.message.content) {
+          for (const block of msg.message.content) {
+            if (block.type === 'text') {
+              responseText += block.text;
+              logger.debug(`Feature text block received (${block.text.length} chars)`);
+              events.emit('spec-regeneration:event', {
+                type: 'spec_regeneration_progress',
+                content: block.text,
+                projectPath: projectPath,
+              });
+            }
+          }
+        } else if (msg.type === 'result' && (msg as any).subtype === 'success') {
+          logger.debug('Received success result for features');
+          responseText = (msg as any).result || responseText;
+        } else if ((msg as { type: string }).type === 'error') {
+          logger.error('❌ Received error message from feature stream:');
+          logger.error('Error message:', JSON.stringify(msg, null, 2));
+        }
+      }
+    } catch (streamError) {
+      logger.error('❌ Error while iterating feature stream:');
+      logger.error('Stream error:', streamError);
+      throw streamError;
+    }
   }
 
   logger.info(`Feature stream complete. Total messages: ${messageCount}`);

apps/server/src/routes/app-spec/generate-spec.ts

@@ -1,5 +1,8 @@
 /**
  * Generate app_spec.txt from project overview
+ *
+ * Model is configurable via phaseModels.specGenerationModel in settings
+ * (defaults to Opus for high-quality specification generation).
  */
 
 import { query } from '@anthropic-ai/claude-agent-sdk';
@@ -13,10 +16,16 @@ import {
   type SpecOutput,
 } from '../../lib/app-spec-format.js';
 import { createLogger } from '@automaker/utils';
+import { DEFAULT_PHASE_MODELS, isCursorModel, stripProviderPrefix } from '@automaker/types';
+import { resolvePhaseModel } from '@automaker/model-resolver';
 import { createSpecGenerationOptions } from '../../lib/sdk-options.js';
+import { extractJson } from '../../lib/json-extractor.js';
+import { ProviderFactory } from '../../providers/provider-factory.js';
 import { logAuthStatus } from './common.js';
 import { generateFeaturesFromSpec } from './generate-features-from-spec.js';
 import { ensureAutomakerDir, getAppSpecPath } from '@automaker/platform';
+import type { SettingsService } from '../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
 
 const logger = createLogger('SpecRegeneration');
 
@@ -27,7 +36,8 @@ export async function generateSpec(
   abortController: AbortController,
   generateFeatures?: boolean,
   analyzeProject?: boolean,
-  maxFeatures?: number
+  maxFeatures?: number,
+  settingsService?: SettingsService
 ): Promise<void> {
   logger.info('========== generateSpec() started ==========');
   logger.info('projectPath:', projectPath);
@@ -83,101 +93,190 @@ ${getStructuredSpecPromptInstruction()}`;
     content: 'Starting spec generation...\n',
   });
 
-  const options = createSpecGenerationOptions({
-    cwd: projectPath,
-    abortController,
-    outputFormat: {
-      type: 'json_schema',
-      schema: specOutputSchema,
-    },
-  });
+  // Load autoLoadClaudeMd setting
+  const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+    projectPath,
+    settingsService,
+    '[SpecRegeneration]'
+  );
 
-  logger.debug('SDK Options:', JSON.stringify(options, null, 2));
-  logger.info('Calling Claude Agent SDK query()...');
+  // Get model from phase settings
+  const settings = await settingsService?.getGlobalSettings();
+  const phaseModelEntry =
+    settings?.phaseModels?.specGenerationModel || DEFAULT_PHASE_MODELS.specGenerationModel;
+  const { model, thinkingLevel } = resolvePhaseModel(phaseModelEntry);
 
-  // Log auth status right before the SDK call
-  logAuthStatus('Right before SDK query()');
-
-  let stream;
-  try {
-    stream = query({ prompt, options });
-    logger.debug('query() returned stream successfully');
-  } catch (queryError) {
-    logger.error('❌ query() threw an exception:');
-    logger.error('Error:', queryError);
-    throw queryError;
-  }
+  logger.info('Using model:', model);
 
   let responseText = '';
   let messageCount = 0;
   let structuredOutput: SpecOutput | null = null;
 
-  logger.info('Starting to iterate over stream...');
+  // Route to appropriate provider based on model type
+  if (isCursorModel(model)) {
+    // Use Cursor provider for Cursor models
+    logger.info('[SpecGeneration] Using Cursor provider');
 
-  try {
-    for await (const msg of stream) {
+    const provider = ProviderFactory.getProviderForModel(model);
+    // Strip provider prefix - providers expect bare model IDs
+    const bareModel = stripProviderPrefix(model);
+
+    // For Cursor, include the JSON schema in the prompt with clear instructions
+    // to return JSON in the response (not write to a file)
+    const cursorPrompt = `${prompt}
+
+CRITICAL INSTRUCTIONS:
+1. DO NOT write any files. DO NOT create any files like "project_specification.json".
+2. After analyzing the project, respond with ONLY a JSON object - no explanations, no markdown, just raw JSON.
+3. The JSON must match this exact schema:
+
+${JSON.stringify(specOutputSchema, null, 2)}
+
+Your entire response should be valid JSON starting with { and ending with }. No text before or after.`;
+
+    for await (const msg of provider.executeQuery({
+      prompt: cursorPrompt,
+      model: bareModel,
+      cwd: projectPath,
+      maxTurns: 250,
+      allowedTools: ['Read', 'Glob', 'Grep'],
+      abortController,
+      readOnly: true, // Spec generation only reads code, we write the spec ourselves
+    })) {
       messageCount++;
-      logger.info(
-        `Stream message #${messageCount}: type=${msg.type}, subtype=${(msg as any).subtype}`
-      );
 
-      if (msg.type === 'assistant') {
-        const msgAny = msg as any;
-        if (msgAny.message?.content) {
-          for (const block of msgAny.message.content) {
-            if (block.type === 'text') {
-              responseText += block.text;
-              logger.info(
-                `Text block received (${block.text.length} chars), total now: ${responseText.length} chars`
-              );
-              events.emit('spec-regeneration:event', {
-                type: 'spec_regeneration_progress',
-                content: block.text,
-                projectPath: projectPath,
-              });
-            } else if (block.type === 'tool_use') {
-              logger.info('Tool use:', block.name);
-              events.emit('spec-regeneration:event', {
-                type: 'spec_tool',
-                tool: block.name,
-                input: block.input,
-              });
-            }
+      if (msg.type === 'assistant' && msg.message?.content) {
+        for (const block of msg.message.content) {
+          if (block.type === 'text' && block.text) {
+            responseText += block.text;
+            logger.info(
+              `Text block received (${block.text.length} chars), total now: ${responseText.length} chars`
+            );
+            events.emit('spec-regeneration:event', {
+              type: 'spec_regeneration_progress',
+              content: block.text,
+              projectPath: projectPath,
+            });
+          } else if (block.type === 'tool_use') {
+            logger.info('Tool use:', block.name);
+            events.emit('spec-regeneration:event', {
+              type: 'spec_tool',
+              tool: block.name,
+              input: block.input,
+            });
           }
         }
-      } else if (msg.type === 'result' && (msg as any).subtype === 'success') {
-        logger.info('Received success result');
-        // Check for structured output - this is the reliable way to get spec data
-        const resultMsg = msg as any;
-        if (resultMsg.structured_output) {
-          structuredOutput = resultMsg.structured_output as SpecOutput;
-          logger.info('✅ Received structured output');
-          logger.debug('Structured output:', JSON.stringify(structuredOutput, null, 2));
-        } else {
-          logger.warn('⚠️ No structured output in result, will fall back to text parsing');
+      } else if (msg.type === 'result' && msg.subtype === 'success' && msg.result) {
+        // Use result if it's a final accumulated message
+        if (msg.result.length > responseText.length) {
+          responseText = msg.result;
         }
-      } else if (msg.type === 'result') {
-        // Handle error result types
-        const subtype = (msg as any).subtype;
-        logger.info(`Result message: subtype=${subtype}`);
-        if (subtype === 'error_max_turns') {
-          logger.error('❌ Hit max turns limit!');
-        } else if (subtype === 'error_max_structured_output_retries') {
-          logger.error('❌ Failed to produce valid structured output after retries');
-          throw new Error('Could not produce valid spec output');
-        }
-      } else if ((msg as { type: string }).type === 'error') {
-        logger.error('❌ Received error message from stream:');
-        logger.error('Error message:', JSON.stringify(msg, null, 2));
-      } else if (msg.type === 'user') {
-        // Log user messages (tool results)
-        logger.info(`User message (tool result): ${JSON.stringify(msg).substring(0, 500)}`);
       }
     }
-  } catch (streamError) {
-    logger.error('❌ Error while iterating stream:');
-    logger.error('Stream error:', streamError);
-    throw streamError;
+
+    // Parse JSON from the response text using shared utility
+    if (responseText) {
+      structuredOutput = extractJson<SpecOutput>(responseText, { logger });
+    }
+  } else {
+    // Use Claude SDK for Claude models
+    logger.info('[SpecGeneration] Using Claude SDK');
+
+    const options = createSpecGenerationOptions({
+      cwd: projectPath,
+      abortController,
+      autoLoadClaudeMd,
+      model,
+      thinkingLevel, // Pass thinking level for extended thinking
+      outputFormat: {
+        type: 'json_schema',
+        schema: specOutputSchema,
+      },
+    });
+
+    logger.debug('SDK Options:', JSON.stringify(options, null, 2));
+    logger.info('Calling Claude Agent SDK query()...');
+
+    // Log auth status right before the SDK call
+    logAuthStatus('Right before SDK query()');
+
+    let stream;
+    try {
+      stream = query({ prompt, options });
+      logger.debug('query() returned stream successfully');
+    } catch (queryError) {
+      logger.error('❌ query() threw an exception:');
+      logger.error('Error:', queryError);
+      throw queryError;
+    }
+
+    logger.info('Starting to iterate over stream...');
+
+    try {
+      for await (const msg of stream) {
+        messageCount++;
+        logger.info(
+          `Stream message #${messageCount}: type=${msg.type}, subtype=${(msg as any).subtype}`
+        );
+
+        if (msg.type === 'assistant') {
+          const msgAny = msg as any;
+          if (msgAny.message?.content) {
+            for (const block of msgAny.message.content) {
+              if (block.type === 'text') {
+                responseText += block.text;
+                logger.info(
+                  `Text block received (${block.text.length} chars), total now: ${responseText.length} chars`
+                );
+                events.emit('spec-regeneration:event', {
+                  type: 'spec_regeneration_progress',
+                  content: block.text,
+                  projectPath: projectPath,
+                });
+              } else if (block.type === 'tool_use') {
+                logger.info('Tool use:', block.name);
+                events.emit('spec-regeneration:event', {
+                  type: 'spec_tool',
+                  tool: block.name,
+                  input: block.input,
+                });
+              }
+            }
+          }
+        } else if (msg.type === 'result' && (msg as any).subtype === 'success') {
+          logger.info('Received success result');
+          // Check for structured output - this is the reliable way to get spec data
+          const resultMsg = msg as any;
+          if (resultMsg.structured_output) {
+            structuredOutput = resultMsg.structured_output as SpecOutput;
+            logger.info('✅ Received structured output');
+            logger.debug('Structured output:', JSON.stringify(structuredOutput, null, 2));
+          } else {
+            logger.warn('⚠️ No structured output in result, will fall back to text parsing');
+          }
+        } else if (msg.type === 'result') {
+          // Handle error result types
+          const subtype = (msg as any).subtype;
+          logger.info(`Result message: subtype=${subtype}`);
+          if (subtype === 'error_max_turns') {
+            logger.error('❌ Hit max turns limit!');
+          } else if (subtype === 'error_max_structured_output_retries') {
+            logger.error('❌ Failed to produce valid structured output after retries');
+            throw new Error('Could not produce valid spec output');
+          }
+        } else if ((msg as { type: string }).type === 'error') {
+          logger.error('❌ Received error message from stream:');
+          logger.error('Error message:', JSON.stringify(msg, null, 2));
+        } else if (msg.type === 'user') {
+          // Log user messages (tool results)
+          logger.info(`User message (tool result): ${JSON.stringify(msg).substring(0, 500)}`);
+        }
+      }
+    } catch (streamError) {
+      logger.error('❌ Error while iterating stream:');
+      logger.error('Stream error:', streamError);
+      throw streamError;
+    }
   }
 
   logger.info(`Stream iteration complete. Total messages: ${messageCount}`);
@@ -269,7 +368,13 @@ ${getStructuredSpecPromptInstruction()}`;
     // Create a new abort controller for feature generation
     const featureAbortController = new AbortController();
     try {
-      await generateFeaturesFromSpec(projectPath, events, featureAbortController, maxFeatures);
+      await generateFeaturesFromSpec(
+        projectPath,
+        events,
+        featureAbortController,
+        maxFeatures,
+        settingsService
+      );
       // Final completion will be emitted by generateFeaturesFromSpec -> parseAndCreateFeatures
     } catch (featureError) {
       logger.error('Feature generation failed:', featureError);

apps/server/src/routes/app-spec/index.ts

@@ -9,13 +9,17 @@ import { createGenerateHandler } from './routes/generate.js';
 import { createGenerateFeaturesHandler } from './routes/generate-features.js';
 import { createStopHandler } from './routes/stop.js';
 import { createStatusHandler } from './routes/status.js';
+import type { SettingsService } from '../../services/settings-service.js';
 
-export function createSpecRegenerationRoutes(events: EventEmitter): Router {
+export function createSpecRegenerationRoutes(
+  events: EventEmitter,
+  settingsService?: SettingsService
+): Router {
   const router = Router();
 
   router.post('/create', createCreateHandler(events));
-  router.post('/generate', createGenerateHandler(events));
-  router.post('/generate-features', createGenerateFeaturesHandler(events));
+  router.post('/generate', createGenerateHandler(events, settingsService));
+  router.post('/generate-features', createGenerateFeaturesHandler(events, settingsService));
   router.post('/stop', createStopHandler());
   router.get('/status', createStatusHandler());
 

apps/server/src/routes/app-spec/parse-and-create-features.ts

@@ -7,6 +7,7 @@ import * as secureFs from '../../lib/secure-fs.js';
 import type { EventEmitter } from '../../lib/events.js';
 import { createLogger } from '@automaker/utils';
 import { getFeaturesDir } from '@automaker/platform';
+import { extractJsonWithArray } from '../../lib/json-extractor.js';
 
 const logger = createLogger('SpecRegeneration');
 
@@ -22,23 +23,30 @@ export async function parseAndCreateFeatures(
   logger.info('========== END CONTENT ==========');
 
   try {
-    // Extract JSON from response
-    logger.info('Extracting JSON from response...');
-    logger.info(`Looking for pattern: /{[\\s\\S]*"features"[\\s\\S]*}/`);
-    const jsonMatch = content.match(/\{[\s\S]*"features"[\s\S]*\}/);
-    if (!jsonMatch) {
-      logger.error('❌ No valid JSON found in response');
+    // Extract JSON from response using shared utility
+    logger.info('Extracting JSON from response using extractJsonWithArray...');
+
+    interface FeaturesResponse {
+      features: Array<{
+        id: string;
+        category?: string;
+        title: string;
+        description: string;
+        priority?: number;
+        complexity?: string;
+        dependencies?: string[];
+      }>;
+    }
+
+    const parsed = extractJsonWithArray<FeaturesResponse>(content, 'features', { logger });
+
+    if (!parsed || !parsed.features) {
+      logger.error('❌ No valid JSON with "features" array found in response');
       logger.error('Full content received:');
       logger.error(content);
       throw new Error('No valid JSON found in response');
     }
 
-    logger.info(`JSON match found (${jsonMatch[0].length} chars)`);
-    logger.info('========== MATCHED JSON ==========');
-    logger.info(jsonMatch[0]);
-    logger.info('========== END MATCHED JSON ==========');
-
-    const parsed = JSON.parse(jsonMatch[0]);
     logger.info(`Parsed ${parsed.features?.length || 0} features`);
     logger.info('Parsed features:', JSON.stringify(parsed.features, null, 2));
 

apps/server/src/routes/app-spec/routes/create.ts

@@ -47,17 +47,17 @@ export function createCreateHandler(events: EventEmitter) {
         return;
       }
 
-      const { isRunning } = getSpecRegenerationStatus();
+      const { isRunning } = getSpecRegenerationStatus(projectPath);
       if (isRunning) {
-        logger.warn('Generation already running, rejecting request');
-        res.json({ success: false, error: 'Spec generation already running' });
+        logger.warn('Generation already running for project:', projectPath);
+        res.json({ success: false, error: 'Spec generation already running for this project' });
         return;
       }
 
       logAuthStatus('Before starting generation');
 
       const abortController = new AbortController();
-      setRunningState(true, abortController);
+      setRunningState(projectPath, true, abortController);
       logger.info('Starting background generation task...');
 
       // Start generation in background
@@ -80,7 +80,7 @@ export function createCreateHandler(events: EventEmitter) {
         })
         .finally(() => {
           logger.info('Generation task finished (success or error)');
-          setRunningState(false, null);
+          setRunningState(projectPath, false, null);
         });
 
       logger.info('Returning success response (generation running in background)');

apps/server/src/routes/app-spec/routes/generate-features.ts

@@ -13,10 +13,14 @@ import {
   getErrorMessage,
 } from '../common.js';
 import { generateFeaturesFromSpec } from '../generate-features-from-spec.js';
+import type { SettingsService } from '../../../services/settings-service.js';
 
 const logger = createLogger('SpecRegeneration');
 
-export function createGenerateFeaturesHandler(events: EventEmitter) {
+export function createGenerateFeaturesHandler(
+  events: EventEmitter,
+  settingsService?: SettingsService
+) {
   return async (req: Request, res: Response): Promise<void> => {
     logger.info('========== /generate-features endpoint called ==========');
     logger.debug('Request body:', JSON.stringify(req.body, null, 2));
@@ -36,20 +40,20 @@ export function createGenerateFeaturesHandler(events: EventEmitter) {
         return;
       }
 
-      const { isRunning } = getSpecRegenerationStatus();
+      const { isRunning } = getSpecRegenerationStatus(projectPath);
       if (isRunning) {
-        logger.warn('Generation already running, rejecting request');
-        res.json({ success: false, error: 'Generation already running' });
+        logger.warn('Generation already running for project:', projectPath);
+        res.json({ success: false, error: 'Generation already running for this project' });
         return;
       }
 
       logAuthStatus('Before starting feature generation');
 
       const abortController = new AbortController();
-      setRunningState(true, abortController);
+      setRunningState(projectPath, true, abortController);
       logger.info('Starting background feature generation task...');
 
-      generateFeaturesFromSpec(projectPath, events, abortController, maxFeatures)
+      generateFeaturesFromSpec(projectPath, events, abortController, maxFeatures, settingsService)
         .catch((error) => {
           logError(error, 'Feature generation failed with error');
           events.emit('spec-regeneration:event', {
@@ -59,7 +63,7 @@ export function createGenerateFeaturesHandler(events: EventEmitter) {
         })
         .finally(() => {
           logger.info('Feature generation task finished (success or error)');
-          setRunningState(false, null);
+          setRunningState(projectPath, false, null);
         });
 
       logger.info('Returning success response (generation running in background)');

apps/server/src/routes/app-spec/routes/generate.ts

@@ -13,10 +13,11 @@ import {
   getErrorMessage,
 } from '../common.js';
 import { generateSpec } from '../generate-spec.js';
+import type { SettingsService } from '../../../services/settings-service.js';
 
 const logger = createLogger('SpecRegeneration');
 
-export function createGenerateHandler(events: EventEmitter) {
+export function createGenerateHandler(events: EventEmitter, settingsService?: SettingsService) {
   return async (req: Request, res: Response): Promise<void> => {
     logger.info('========== /generate endpoint called ==========');
     logger.debug('Request body:', JSON.stringify(req.body, null, 2));
@@ -47,17 +48,17 @@ export function createGenerateHandler(events: EventEmitter) {
         return;
       }
 
-      const { isRunning } = getSpecRegenerationStatus();
+      const { isRunning } = getSpecRegenerationStatus(projectPath);
       if (isRunning) {
-        logger.warn('Generation already running, rejecting request');
-        res.json({ success: false, error: 'Spec generation already running' });
+        logger.warn('Generation already running for project:', projectPath);
+        res.json({ success: false, error: 'Spec generation already running for this project' });
         return;
       }
 
       logAuthStatus('Before starting generation');
 
       const abortController = new AbortController();
-      setRunningState(true, abortController);
+      setRunningState(projectPath, true, abortController);
       logger.info('Starting background generation task...');
 
       generateSpec(
@@ -67,7 +68,8 @@ export function createGenerateHandler(events: EventEmitter) {
         abortController,
         generateFeatures,
         analyzeProject,
-        maxFeatures
+        maxFeatures,
+        settingsService
       )
         .catch((error) => {
           logError(error, 'Generation failed with error');
@@ -79,7 +81,7 @@ export function createGenerateHandler(events: EventEmitter) {
         })
         .finally(() => {
           logger.info('Generation task finished (success or error)');
-          setRunningState(false, null);
+          setRunningState(projectPath, false, null);
         });
 
       logger.info('Returning success response (generation running in background)');

apps/server/src/routes/app-spec/routes/status.ts

@@ -6,10 +6,11 @@ import type { Request, Response } from 'express';
 import { getSpecRegenerationStatus, getErrorMessage } from '../common.js';
 
 export function createStatusHandler() {
-  return async (_req: Request, res: Response): Promise<void> => {
+  return async (req: Request, res: Response): Promise<void> => {
     try {
-      const { isRunning } = getSpecRegenerationStatus();
-      res.json({ success: true, isRunning });
+      const projectPath = req.query.projectPath as string | undefined;
+      const { isRunning } = getSpecRegenerationStatus(projectPath);
+      res.json({ success: true, isRunning, projectPath });
     } catch (error) {
       res.status(500).json({ success: false, error: getErrorMessage(error) });
     }

apps/server/src/routes/app-spec/routes/stop.ts

@@ -6,13 +6,16 @@ import type { Request, Response } from 'express';
 import { getSpecRegenerationStatus, setRunningState, getErrorMessage } from '../common.js';
 
 export function createStopHandler() {
-  return async (_req: Request, res: Response): Promise<void> => {
+  return async (req: Request, res: Response): Promise<void> => {
     try {
-      const { currentAbortController } = getSpecRegenerationStatus();
+      const { projectPath } = req.body as { projectPath?: string };
+      const { currentAbortController } = getSpecRegenerationStatus(projectPath);
       if (currentAbortController) {
         currentAbortController.abort();
       }
-      setRunningState(false, null);
+      if (projectPath) {
+        setRunningState(projectPath, false, null);
+      }
       res.json({ success: true });
     } catch (error) {
       res.status(500).json({ success: false, error: getErrorMessage(error) });

apps/server/src/routes/auth/index.ts

@@ -0,0 +1,248 @@
+/**
+ * Auth routes - Login, logout, and status endpoints
+ *
+ * Security model:
+ * - Web mode: User enters API key (shown on server console) to get HTTP-only session cookie
+ * - Electron mode: Uses X-API-Key header (handled automatically via IPC)
+ *
+ * The session cookie is:
+ * - HTTP-only: JavaScript cannot read it (protects against XSS)
+ * - SameSite=Strict: Only sent for same-site requests (protects against CSRF)
+ *
+ * Mounted at /api/auth in the main server (BEFORE auth middleware).
+ */
+
+import { Router } from 'express';
+import type { Request } from 'express';
+import {
+  validateApiKey,
+  createSession,
+  invalidateSession,
+  getSessionCookieOptions,
+  getSessionCookieName,
+  isRequestAuthenticated,
+  createWsConnectionToken,
+} from '../../lib/auth.js';
+
+// Rate limiting configuration
+const RATE_LIMIT_WINDOW_MS = 60 * 1000; // 1 minute window
+const RATE_LIMIT_MAX_ATTEMPTS = 5; // Max 5 attempts per window
+
+// Check if we're in test mode - disable rate limiting for E2E tests
+const isTestMode = process.env.AUTOMAKER_MOCK_AGENT === 'true';
+
+// In-memory rate limit tracking (resets on server restart)
+const loginAttempts = new Map<string, { count: number; windowStart: number }>();
+
+// Clean up old rate limit entries periodically (every 5 minutes)
+setInterval(
+  () => {
+    const now = Date.now();
+    loginAttempts.forEach((data, ip) => {
+      if (now - data.windowStart > RATE_LIMIT_WINDOW_MS * 2) {
+        loginAttempts.delete(ip);
+      }
+    });
+  },
+  5 * 60 * 1000
+);
+
+/**
+ * Get client IP address from request
+ * Handles X-Forwarded-For header for reverse proxy setups
+ */
+function getClientIp(req: Request): string {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (forwarded) {
+    // X-Forwarded-For can be a comma-separated list; take the first (original client)
+    const forwardedIp = Array.isArray(forwarded) ? forwarded[0] : forwarded.split(',')[0];
+    return forwardedIp.trim();
+  }
+  return req.ip || req.socket.remoteAddress || 'unknown';
+}
+
+/**
+ * Check if an IP is rate limited
+ * Returns { limited: boolean, retryAfter?: number }
+ */
+function checkRateLimit(ip: string): { limited: boolean; retryAfter?: number } {
+  const now = Date.now();
+  const attempt = loginAttempts.get(ip);
+
+  if (!attempt) {
+    return { limited: false };
+  }
+
+  // Check if window has expired
+  if (now - attempt.windowStart > RATE_LIMIT_WINDOW_MS) {
+    loginAttempts.delete(ip);
+    return { limited: false };
+  }
+
+  // Check if over limit
+  if (attempt.count >= RATE_LIMIT_MAX_ATTEMPTS) {
+    const retryAfter = Math.ceil((RATE_LIMIT_WINDOW_MS - (now - attempt.windowStart)) / 1000);
+    return { limited: true, retryAfter };
+  }
+
+  return { limited: false };
+}
+
+/**
+ * Record a login attempt for rate limiting
+ */
+function recordLoginAttempt(ip: string): void {
+  const now = Date.now();
+  const attempt = loginAttempts.get(ip);
+
+  if (!attempt || now - attempt.windowStart > RATE_LIMIT_WINDOW_MS) {
+    // Start new window
+    loginAttempts.set(ip, { count: 1, windowStart: now });
+  } else {
+    // Increment existing window
+    attempt.count++;
+  }
+}
+
+/**
+ * Create auth routes
+ *
+ * @returns Express Router with auth endpoints
+ */
+export function createAuthRoutes(): Router {
+  const router = Router();
+
+  /**
+   * GET /api/auth/status
+   *
+   * Returns whether the current request is authenticated.
+   * Used by the UI to determine if login is needed.
+   */
+  router.get('/status', (req, res) => {
+    const authenticated = isRequestAuthenticated(req);
+    res.json({
+      success: true,
+      authenticated,
+      required: true,
+    });
+  });
+
+  /**
+   * POST /api/auth/login
+   *
+   * Validates the API key and sets a session cookie.
+   * Body: { apiKey: string }
+   *
+   * Rate limited to 5 attempts per minute per IP to prevent brute force attacks.
+   */
+  router.post('/login', async (req, res) => {
+    const clientIp = getClientIp(req);
+
+    // Skip rate limiting in test mode to allow parallel E2E tests
+    if (!isTestMode) {
+      // Check rate limit before processing
+      const rateLimit = checkRateLimit(clientIp);
+      if (rateLimit.limited) {
+        res.status(429).json({
+          success: false,
+          error: 'Too many login attempts. Please try again later.',
+          retryAfter: rateLimit.retryAfter,
+        });
+        return;
+      }
+    }
+
+    const { apiKey } = req.body as { apiKey?: string };
+
+    if (!apiKey) {
+      res.status(400).json({
+        success: false,
+        error: 'API key is required.',
+      });
+      return;
+    }
+
+    // Record this attempt (only for actual API key validation attempts, skip in test mode)
+    if (!isTestMode) {
+      recordLoginAttempt(clientIp);
+    }
+
+    if (!validateApiKey(apiKey)) {
+      res.status(401).json({
+        success: false,
+        error: 'Invalid API key.',
+      });
+      return;
+    }
+
+    // Create session and set cookie
+    const sessionToken = await createSession();
+    const cookieOptions = getSessionCookieOptions();
+    const cookieName = getSessionCookieName();
+
+    res.cookie(cookieName, sessionToken, cookieOptions);
+    res.json({
+      success: true,
+      message: 'Logged in successfully.',
+      // Return token for explicit header-based auth (works around cross-origin cookie issues)
+      token: sessionToken,
+    });
+  });
+
+  /**
+   * GET /api/auth/token
+   *
+   * Generates a short-lived WebSocket connection token if the user has a valid session.
+   * This token is used for initial WebSocket handshake authentication and expires in 5 minutes.
+   * The token is NOT the session cookie value - it's a separate, short-lived token.
+   */
+  router.get('/token', (req, res) => {
+    // Validate the session is still valid (via cookie, API key, or session token header)
+    if (!isRequestAuthenticated(req)) {
+      res.status(401).json({
+        success: false,
+        error: 'Authentication required.',
+      });
+      return;
+    }
+
+    // Generate a new short-lived WebSocket connection token
+    const wsToken = createWsConnectionToken();
+
+    res.json({
+      success: true,
+      token: wsToken,
+      expiresIn: 300, // 5 minutes in seconds
+    });
+  });
+
+  /**
+   * POST /api/auth/logout
+   *
+   * Clears the session cookie and invalidates the session.
+   */
+  router.post('/logout', async (req, res) => {
+    const cookieName = getSessionCookieName();
+    const sessionToken = req.cookies?.[cookieName] as string | undefined;
+
+    if (sessionToken) {
+      await invalidateSession(sessionToken);
+    }
+
+    // Clear the cookie by setting it to empty with immediate expiration
+    // Using res.cookie() with maxAge: 0 is more reliable than clearCookie()
+    // in cross-origin development environments
+    res.cookie(cookieName, '', {
+      ...getSessionCookieOptions(),
+      maxAge: 0,
+      expires: new Date(0),
+    });
+
+    res.json({
+      success: true,
+      message: 'Logged out successfully.',
+    });
+  });
+
+  return router;
+}

apps/server/src/routes/auto-mode/index.ts

@@ -17,6 +17,7 @@ import { createAnalyzeProjectHandler } from './routes/analyze-project.js';
 import { createFollowUpFeatureHandler } from './routes/follow-up-feature.js';
 import { createCommitFeatureHandler } from './routes/commit-feature.js';
 import { createApprovePlanHandler } from './routes/approve-plan.js';
+import { createResumeInterruptedHandler } from './routes/resume-interrupted.js';
 
 export function createAutoModeRoutes(autoModeService: AutoModeService): Router {
   const router = Router();
@@ -63,6 +64,11 @@ export function createAutoModeRoutes(autoModeService: AutoModeService): Router {
     validatePathParams('projectPath'),
     createApprovePlanHandler(autoModeService)
   );
+  router.post(
+    '/resume-interrupted',
+    validatePathParams('projectPath'),
+    createResumeInterruptedHandler(autoModeService)
+  );
 
   return router;
 }

apps/server/src/routes/auto-mode/routes/follow-up-feature.ts

@@ -31,7 +31,9 @@ export function createFollowUpFeatureHandler(autoModeService: AutoModeService) {
       // Start follow-up in background
       // followUpFeature derives workDir from feature.branchName
       autoModeService
-        .followUpFeature(projectPath, featureId, prompt, imagePaths, useWorktrees ?? true)
+        // Default to false to match run-feature/resume-feature behavior.
+        // Worktrees should only be used when explicitly enabled by the user.
+        .followUpFeature(projectPath, featureId, prompt, imagePaths, useWorktrees ?? false)
         .catch((error) => {
           logger.error(`[AutoMode] Follow up feature ${featureId} error:`, error);
         })

apps/server/src/routes/auto-mode/routes/resume-feature.ts

@@ -31,7 +31,7 @@ export function createResumeFeatureHandler(autoModeService: AutoModeService) {
       autoModeService
         .resumeFeature(projectPath, featureId, useWorktrees ?? false)
         .catch((error) => {
-          logger.error(`[AutoMode] Resume feature ${featureId} error:`, error);
+          logger.error(`Resume feature ${featureId} error:`, error);
         });
 
       res.json({ success: true });

apps/server/src/routes/auto-mode/routes/resume-interrupted.ts

@@ -0,0 +1,42 @@
+/**
+ * Resume Interrupted Features Handler
+ *
+ * Checks for features that were interrupted (in pipeline steps or in_progress)
+ * when the server was restarted and resumes them.
+ */
+
+import type { Request, Response } from 'express';
+import { createLogger } from '@automaker/utils';
+import type { AutoModeService } from '../../../services/auto-mode-service.js';
+
+const logger = createLogger('ResumeInterrupted');
+
+interface ResumeInterruptedRequest {
+  projectPath: string;
+}
+
+export function createResumeInterruptedHandler(autoModeService: AutoModeService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    const { projectPath } = req.body as ResumeInterruptedRequest;
+
+    if (!projectPath) {
+      res.status(400).json({ error: 'Project path is required' });
+      return;
+    }
+
+    logger.info(`Checking for interrupted features in ${projectPath}`);
+
+    try {
+      await autoModeService.resumeInterruptedFeatures(projectPath);
+      res.json({
+        success: true,
+        message: 'Resume check completed',
+      });
+    } catch (error) {
+      logger.error('Error resuming interrupted features:', error);
+      res.status(500).json({
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+  };
+}

apps/server/src/routes/auto-mode/routes/run-feature.ts

@@ -31,7 +31,7 @@ export function createRunFeatureHandler(autoModeService: AutoModeService) {
       autoModeService
         .executeFeature(projectPath, featureId, useWorktrees ?? false, false)
         .catch((error) => {
-          logger.error(`[AutoMode] Feature ${featureId} error:`, error);
+          logger.error(`Feature ${featureId} error:`, error);
         })
         .finally(() => {
           // Release the starting slot when execution completes (success or error)

apps/server/src/routes/backlog-plan/common.ts

@@ -0,0 +1,39 @@
+/**
+ * Common utilities for backlog plan routes
+ */
+
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('BacklogPlan');
+
+// State for tracking running generation
+let isRunning = false;
+let currentAbortController: AbortController | null = null;
+
+export function getBacklogPlanStatus(): { isRunning: boolean } {
+  return { isRunning };
+}
+
+export function setRunningState(running: boolean, abortController?: AbortController | null): void {
+  isRunning = running;
+  if (abortController !== undefined) {
+    currentAbortController = abortController;
+  }
+}
+
+export function getAbortController(): AbortController | null {
+  return currentAbortController;
+}
+
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function logError(error: unknown, context: string): void {
+  logger.error(`[BacklogPlan] ${context}:`, getErrorMessage(error));
+}
+
+export { logger };

apps/server/src/routes/backlog-plan/generate-plan.ts

@@ -0,0 +1,222 @@
+/**
+ * Generate backlog plan using Claude AI
+ *
+ * Model is configurable via phaseModels.backlogPlanningModel in settings
+ * (defaults to Sonnet). Can be overridden per-call via model parameter.
+ */
+
+import type { EventEmitter } from '../../lib/events.js';
+import type { Feature, BacklogPlanResult, BacklogChange, DependencyUpdate } from '@automaker/types';
+import {
+  DEFAULT_PHASE_MODELS,
+  isCursorModel,
+  stripProviderPrefix,
+  type ThinkingLevel,
+} from '@automaker/types';
+import { resolvePhaseModel } from '@automaker/model-resolver';
+import { FeatureLoader } from '../../services/feature-loader.js';
+import { ProviderFactory } from '../../providers/provider-factory.js';
+import { extractJsonWithArray } from '../../lib/json-extractor.js';
+import { logger, setRunningState, getErrorMessage } from './common.js';
+import type { SettingsService } from '../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting, getPromptCustomization } from '../../lib/settings-helpers.js';
+
+const featureLoader = new FeatureLoader();
+
+/**
+ * Format features for the AI prompt
+ */
+function formatFeaturesForPrompt(features: Feature[]): string {
+  if (features.length === 0) {
+    return 'No features in backlog yet.';
+  }
+
+  return features
+    .map((f) => {
+      const deps = f.dependencies?.length ? `Dependencies: [${f.dependencies.join(', ')}]` : '';
+      const priority = f.priority !== undefined ? `Priority: ${f.priority}` : '';
+      return `- ID: ${f.id}
+  Title: ${f.title || 'Untitled'}
+  Description: ${f.description}
+  Category: ${f.category}
+  Status: ${f.status || 'backlog'}
+  ${priority}
+  ${deps}`.trim();
+    })
+    .join('\n\n');
+}
+
+/**
+ * Parse the AI response into a BacklogPlanResult
+ */
+function parsePlanResponse(response: string): BacklogPlanResult {
+  // Use shared JSON extraction utility for robust parsing
+  // extractJsonWithArray validates that 'changes' exists AND is an array
+  const parsed = extractJsonWithArray<BacklogPlanResult>(response, 'changes', {
+    logger,
+  });
+
+  if (parsed) {
+    return parsed;
+  }
+
+  // If parsing fails, log details and return an empty result
+  logger.warn('[BacklogPlan] Failed to parse AI response as JSON');
+  logger.warn('[BacklogPlan] Response text length:', response.length);
+  logger.warn('[BacklogPlan] Response preview:', response.slice(0, 500));
+  if (response.length === 0) {
+    logger.error('[BacklogPlan] Response text is EMPTY! No content was extracted from stream.');
+  }
+  return {
+    changes: [],
+    summary: 'Failed to parse AI response',
+    dependencyUpdates: [],
+  };
+}
+
+/**
+ * Generate a backlog modification plan based on user prompt
+ */
+export async function generateBacklogPlan(
+  projectPath: string,
+  prompt: string,
+  events: EventEmitter,
+  abortController: AbortController,
+  settingsService?: SettingsService,
+  model?: string
+): Promise<BacklogPlanResult> {
+  try {
+    // Load current features
+    const features = await featureLoader.getAll(projectPath);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_progress',
+      content: `Loaded ${features.length} features from backlog`,
+    });
+
+    // Load prompts from settings
+    const prompts = await getPromptCustomization(settingsService, '[BacklogPlan]');
+
+    // Build the system prompt
+    const systemPrompt = prompts.backlogPlan.systemPrompt;
+
+    // Build the user prompt from template
+    const currentFeatures = formatFeaturesForPrompt(features);
+    const userPrompt = prompts.backlogPlan.userPromptTemplate
+      .replace('{{currentFeatures}}', currentFeatures)
+      .replace('{{userRequest}}', prompt);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_progress',
+      content: 'Generating plan with AI...',
+    });
+
+    // Get the model to use from settings or provided override
+    let effectiveModel = model;
+    let thinkingLevel: ThinkingLevel | undefined;
+    if (!effectiveModel) {
+      const settings = await settingsService?.getGlobalSettings();
+      const phaseModelEntry =
+        settings?.phaseModels?.backlogPlanningModel || DEFAULT_PHASE_MODELS.backlogPlanningModel;
+      const resolved = resolvePhaseModel(phaseModelEntry);
+      effectiveModel = resolved.model;
+      thinkingLevel = resolved.thinkingLevel;
+    }
+    logger.info('[BacklogPlan] Using model:', effectiveModel);
+
+    const provider = ProviderFactory.getProviderForModel(effectiveModel);
+    // Strip provider prefix - providers expect bare model IDs
+    const bareModel = stripProviderPrefix(effectiveModel);
+
+    // Get autoLoadClaudeMd setting
+    const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+      projectPath,
+      settingsService,
+      '[BacklogPlan]'
+    );
+
+    // For Cursor models, we need to combine prompts with explicit instructions
+    // because Cursor doesn't support systemPrompt separation like Claude SDK
+    let finalPrompt = userPrompt;
+    let finalSystemPrompt: string | undefined = systemPrompt;
+
+    if (isCursorModel(effectiveModel)) {
+      logger.info('[BacklogPlan] Using Cursor model - adding explicit no-file-write instructions');
+      finalPrompt = `${systemPrompt}
+
+CRITICAL INSTRUCTIONS:
+1. DO NOT write any files. Return the JSON in your response only.
+2. DO NOT use Write, Edit, or any file modification tools.
+3. Respond with ONLY a JSON object - no explanations, no markdown, just raw JSON.
+4. Your entire response should be valid JSON starting with { and ending with }.
+5. No text before or after the JSON object.
+
+${userPrompt}`;
+      finalSystemPrompt = undefined; // System prompt is now embedded in the user prompt
+    }
+
+    // Execute the query
+    const stream = provider.executeQuery({
+      prompt: finalPrompt,
+      model: bareModel,
+      cwd: projectPath,
+      systemPrompt: finalSystemPrompt,
+      maxTurns: 1,
+      allowedTools: [], // No tools needed for this
+      abortController,
+      settingSources: autoLoadClaudeMd ? ['user', 'project'] : undefined,
+      readOnly: true, // Plan generation only generates text, doesn't write files
+      thinkingLevel, // Pass thinking level for extended thinking
+    });
+
+    let responseText = '';
+
+    for await (const msg of stream) {
+      if (abortController.signal.aborted) {
+        throw new Error('Generation aborted');
+      }
+
+      if (msg.type === 'assistant') {
+        if (msg.message?.content) {
+          for (const block of msg.message.content) {
+            if (block.type === 'text') {
+              responseText += block.text;
+            }
+          }
+        }
+      } else if (msg.type === 'result' && msg.subtype === 'success' && msg.result) {
+        // Use result if it's a final accumulated message (from Cursor provider)
+        logger.info('[BacklogPlan] Received result from Cursor, length:', msg.result.length);
+        logger.info('[BacklogPlan] Previous responseText length:', responseText.length);
+        if (msg.result.length > responseText.length) {
+          logger.info('[BacklogPlan] Using Cursor result (longer than accumulated text)');
+          responseText = msg.result;
+        } else {
+          logger.info('[BacklogPlan] Keeping accumulated text (longer than Cursor result)');
+        }
+      }
+    }
+
+    // Parse the response
+    const result = parsePlanResponse(responseText);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_complete',
+      result,
+    });
+
+    return result;
+  } catch (error) {
+    const errorMessage = getErrorMessage(error);
+    logger.error('[BacklogPlan] Generation failed:', errorMessage);
+
+    events.emit('backlog-plan:event', {
+      type: 'backlog_plan_error',
+      error: errorMessage,
+    });
+
+    throw error;
+  } finally {
+    setRunningState(false, null);
+  }
+}

apps/server/src/routes/backlog-plan/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Backlog Plan routes - HTTP API for AI-assisted backlog modification
+ */
+
+import { Router } from 'express';
+import type { EventEmitter } from '../../lib/events.js';
+import { validatePathParams } from '../../middleware/validate-paths.js';
+import { createGenerateHandler } from './routes/generate.js';
+import { createStopHandler } from './routes/stop.js';
+import { createStatusHandler } from './routes/status.js';
+import { createApplyHandler } from './routes/apply.js';
+import type { SettingsService } from '../../services/settings-service.js';
+
+export function createBacklogPlanRoutes(
+  events: EventEmitter,
+  settingsService?: SettingsService
+): Router {
+  const router = Router();
+
+  router.post(
+    '/generate',
+    validatePathParams('projectPath'),
+    createGenerateHandler(events, settingsService)
+  );
+  router.post('/stop', createStopHandler());
+  router.get('/status', createStatusHandler());
+  router.post('/apply', validatePathParams('projectPath'), createApplyHandler());
+
+  return router;
+}

apps/server/src/routes/backlog-plan/routes/apply.ts

@@ -0,0 +1,147 @@
+/**
+ * POST /apply endpoint - Apply a backlog plan
+ */
+
+import type { Request, Response } from 'express';
+import type { BacklogPlanResult, BacklogChange, Feature } from '@automaker/types';
+import { FeatureLoader } from '../../../services/feature-loader.js';
+import { getErrorMessage, logError, logger } from '../common.js';
+
+const featureLoader = new FeatureLoader();
+
+export function createApplyHandler() {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, plan } = req.body as {
+        projectPath: string;
+        plan: BacklogPlanResult;
+      };
+
+      if (!projectPath) {
+        res.status(400).json({ success: false, error: 'projectPath required' });
+        return;
+      }
+
+      if (!plan || !plan.changes) {
+        res.status(400).json({ success: false, error: 'plan with changes required' });
+        return;
+      }
+
+      const appliedChanges: string[] = [];
+
+      // Load current features for dependency validation
+      const allFeatures = await featureLoader.getAll(projectPath);
+      const featureMap = new Map(allFeatures.map((f) => [f.id, f]));
+
+      // Process changes in order: deletes first, then adds, then updates
+      // This ensures we can remove dependencies before they cause issues
+
+      // 1. First pass: Handle deletes
+      const deletions = plan.changes.filter((c) => c.type === 'delete');
+      for (const change of deletions) {
+        if (!change.featureId) continue;
+
+        try {
+          // Before deleting, update any features that depend on this one
+          for (const feature of allFeatures) {
+            if (feature.dependencies?.includes(change.featureId)) {
+              const newDeps = feature.dependencies.filter((d) => d !== change.featureId);
+              await featureLoader.update(projectPath, feature.id, { dependencies: newDeps });
+              logger.info(
+                `[BacklogPlan] Removed dependency ${change.featureId} from ${feature.id}`
+              );
+            }
+          }
+
+          // Now delete the feature
+          const deleted = await featureLoader.delete(projectPath, change.featureId);
+          if (deleted) {
+            appliedChanges.push(`deleted:${change.featureId}`);
+            featureMap.delete(change.featureId);
+            logger.info(`[BacklogPlan] Deleted feature ${change.featureId}`);
+          }
+        } catch (error) {
+          logger.error(
+            `[BacklogPlan] Failed to delete ${change.featureId}:`,
+            getErrorMessage(error)
+          );
+        }
+      }
+
+      // 2. Second pass: Handle adds
+      const additions = plan.changes.filter((c) => c.type === 'add');
+      for (const change of additions) {
+        if (!change.feature) continue;
+
+        try {
+          // Create the new feature
+          const newFeature = await featureLoader.create(projectPath, {
+            title: change.feature.title,
+            description: change.feature.description || '',
+            category: change.feature.category || 'Uncategorized',
+            dependencies: change.feature.dependencies,
+            priority: change.feature.priority,
+            status: 'backlog',
+          });
+
+          appliedChanges.push(`added:${newFeature.id}`);
+          featureMap.set(newFeature.id, newFeature);
+          logger.info(`[BacklogPlan] Created feature ${newFeature.id}: ${newFeature.title}`);
+        } catch (error) {
+          logger.error(`[BacklogPlan] Failed to add feature:`, getErrorMessage(error));
+        }
+      }
+
+      // 3. Third pass: Handle updates
+      const updates = plan.changes.filter((c) => c.type === 'update');
+      for (const change of updates) {
+        if (!change.featureId || !change.feature) continue;
+
+        try {
+          const updated = await featureLoader.update(projectPath, change.featureId, change.feature);
+          appliedChanges.push(`updated:${change.featureId}`);
+          featureMap.set(change.featureId, updated);
+          logger.info(`[BacklogPlan] Updated feature ${change.featureId}`);
+        } catch (error) {
+          logger.error(
+            `[BacklogPlan] Failed to update ${change.featureId}:`,
+            getErrorMessage(error)
+          );
+        }
+      }
+
+      // 4. Apply dependency updates from the plan
+      if (plan.dependencyUpdates) {
+        for (const depUpdate of plan.dependencyUpdates) {
+          try {
+            const feature = featureMap.get(depUpdate.featureId);
+            if (feature) {
+              const currentDeps = feature.dependencies || [];
+              const newDeps = currentDeps
+                .filter((d) => !depUpdate.removedDependencies.includes(d))
+                .concat(depUpdate.addedDependencies.filter((d) => !currentDeps.includes(d)));
+
+              await featureLoader.update(projectPath, depUpdate.featureId, {
+                dependencies: newDeps,
+              });
+              logger.info(`[BacklogPlan] Updated dependencies for ${depUpdate.featureId}`);
+            }
+          } catch (error) {
+            logger.error(
+              `[BacklogPlan] Failed to update dependencies for ${depUpdate.featureId}:`,
+              getErrorMessage(error)
+            );
+          }
+        }
+      }
+
+      res.json({
+        success: true,
+        appliedChanges,
+      });
+    } catch (error) {
+      logError(error, 'Apply backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/generate.ts

@@ -0,0 +1,62 @@
+/**
+ * POST /generate endpoint - Generate a backlog plan
+ */
+
+import type { Request, Response } from 'express';
+import type { EventEmitter } from '../../../lib/events.js';
+import { getBacklogPlanStatus, setRunningState, getErrorMessage, logError } from '../common.js';
+import { generateBacklogPlan } from '../generate-plan.js';
+import type { SettingsService } from '../../../services/settings-service.js';
+
+export function createGenerateHandler(events: EventEmitter, settingsService?: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, prompt, model } = req.body as {
+        projectPath: string;
+        prompt: string;
+        model?: string;
+      };
+
+      if (!projectPath) {
+        res.status(400).json({ success: false, error: 'projectPath required' });
+        return;
+      }
+
+      if (!prompt) {
+        res.status(400).json({ success: false, error: 'prompt required' });
+        return;
+      }
+
+      const { isRunning } = getBacklogPlanStatus();
+      if (isRunning) {
+        res.json({
+          success: false,
+          error: 'Backlog plan generation is already running',
+        });
+        return;
+      }
+
+      setRunningState(true);
+      const abortController = new AbortController();
+      setRunningState(true, abortController);
+
+      // Start generation in background
+      generateBacklogPlan(projectPath, prompt, events, abortController, settingsService, model)
+        .catch((error) => {
+          logError(error, 'Generate backlog plan failed (background)');
+          events.emit('backlog-plan:event', {
+            type: 'backlog_plan_error',
+            error: getErrorMessage(error),
+          });
+        })
+        .finally(() => {
+          setRunningState(false, null);
+        });
+
+      res.json({ success: true });
+    } catch (error) {
+      logError(error, 'Generate backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/status.ts

@@ -0,0 +1,18 @@
+/**
+ * GET /status endpoint - Get backlog plan generation status
+ */
+
+import type { Request, Response } from 'express';
+import { getBacklogPlanStatus, getErrorMessage, logError } from '../common.js';
+
+export function createStatusHandler() {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const status = getBacklogPlanStatus();
+      res.json({ success: true, ...status });
+    } catch (error) {
+      logError(error, 'Get backlog plan status failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/backlog-plan/routes/stop.ts

@@ -0,0 +1,22 @@
+/**
+ * POST /stop endpoint - Stop the current backlog plan generation
+ */
+
+import type { Request, Response } from 'express';
+import { getAbortController, setRunningState, getErrorMessage, logError } from '../common.js';
+
+export function createStopHandler() {
+  return async (_req: Request, res: Response): Promise<void> => {
+    try {
+      const abortController = getAbortController();
+      if (abortController) {
+        abortController.abort();
+        setRunningState(false, null);
+      }
+      res.json({ success: true });
+    } catch (error) {
+      logError(error, 'Stop backlog plan failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/claude/index.ts

@@ -1,5 +1,8 @@
 import { Router, Request, Response } from 'express';
 import { ClaudeUsageService } from '../../services/claude-usage-service.js';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('Claude');
 
 export function createClaudeRoutes(service: ClaudeUsageService): Router {
   const router = Router();
@@ -10,7 +13,10 @@ export function createClaudeRoutes(service: ClaudeUsageService): Router {
       // Check if Claude CLI is available first
       const isAvailable = await service.isAvailable();
       if (!isAvailable) {
-        res.status(503).json({
+        // IMPORTANT: This endpoint is behind Automaker session auth already.
+        // Use a 200 + error payload for Claude CLI issues so the UI doesn't
+        // interpret it as an invalid Automaker session (401/403 triggers logout).
+        res.status(200).json({
           error: 'Claude CLI not found',
           message: "Please install Claude Code CLI and run 'claude login' to authenticate",
         });
@@ -23,17 +29,18 @@ export function createClaudeRoutes(service: ClaudeUsageService): Router {
       const message = error instanceof Error ? error.message : 'Unknown error';
 
       if (message.includes('Authentication required') || message.includes('token_expired')) {
-        res.status(401).json({
+        // Do NOT use 401/403 here: that status code is reserved for Automaker session auth.
+        res.status(200).json({
           error: 'Authentication required',
           message: "Please run 'claude login' to authenticate",
         });
       } else if (message.includes('timed out')) {
-        res.status(504).json({
+        res.status(200).json({
           error: 'Command timed out',
           message: 'The Claude CLI took too long to respond',
         });
       } else {
-        console.error('Error fetching usage:', error);
+        logger.error('Error fetching usage:', error);
         res.status(500).json({ error: message });
       }
     }

apps/server/src/routes/codex/index.ts

@@ -0,0 +1,90 @@
+import { Router, Request, Response } from 'express';
+import { CodexUsageService } from '../../services/codex-usage-service.js';
+import { CodexModelCacheService } from '../../services/codex-model-cache-service.js';
+import { createLogger } from '@automaker/utils';
+
+const logger = createLogger('Codex');
+
+export function createCodexRoutes(
+  usageService: CodexUsageService,
+  modelCacheService: CodexModelCacheService
+): Router {
+  const router = Router();
+
+  // Get current usage (attempts to fetch from Codex CLI)
+  router.get('/usage', async (_req: Request, res: Response) => {
+    try {
+      // Check if Codex CLI is available first
+      const isAvailable = await usageService.isAvailable();
+      if (!isAvailable) {
+        // IMPORTANT: This endpoint is behind Automaker session auth already.
+        // Use a 200 + error payload for Codex CLI issues so the UI doesn't
+        // interpret it as an invalid Automaker session (401/403 triggers logout).
+        res.status(200).json({
+          error: 'Codex CLI not found',
+          message: "Please install Codex CLI and run 'codex login' to authenticate",
+        });
+        return;
+      }
+
+      const usage = await usageService.fetchUsageData();
+      res.json(usage);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+
+      if (message.includes('not authenticated') || message.includes('login')) {
+        // Do NOT use 401/403 here: that status code is reserved for Automaker session auth.
+        res.status(200).json({
+          error: 'Authentication required',
+          message: "Please run 'codex login' to authenticate",
+        });
+      } else if (message.includes('not available') || message.includes('does not provide')) {
+        // This is the expected case - Codex doesn't provide usage stats
+        res.status(200).json({
+          error: 'Usage statistics not available',
+          message: message,
+        });
+      } else if (message.includes('timed out')) {
+        res.status(200).json({
+          error: 'Command timed out',
+          message: 'The Codex CLI took too long to respond',
+        });
+      } else {
+        logger.error('Error fetching usage:', error);
+        res.status(500).json({ error: message });
+      }
+    }
+  });
+
+  // Get available Codex models (cached)
+  router.get('/models', async (req: Request, res: Response) => {
+    try {
+      const forceRefresh = req.query.refresh === 'true';
+      const { models, cachedAt } = await modelCacheService.getModelsWithMetadata(forceRefresh);
+
+      if (models.length === 0) {
+        res.status(503).json({
+          success: false,
+          error: 'Codex CLI not available or not authenticated',
+          message: "Please install Codex CLI and run 'codex login' to authenticate",
+        });
+        return;
+      }
+
+      res.json({
+        success: true,
+        models,
+        cachedAt,
+      });
+    } catch (error) {
+      logger.error('Error fetching models:', error);
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      res.status(500).json({
+        success: false,
+        error: message,
+      });
+    }
+  });
+
+  return router;
+}

apps/server/src/routes/context/index.ts

@@ -8,17 +8,19 @@
 import { Router } from 'express';
 import { createDescribeImageHandler } from './routes/describe-image.js';
 import { createDescribeFileHandler } from './routes/describe-file.js';
+import type { SettingsService } from '../../services/settings-service.js';
 
 /**
  * Create the context router
  *
+ * @param settingsService - Optional settings service for loading autoLoadClaudeMd setting
  * @returns Express router with context endpoints
  */
-export function createContextRoutes(): Router {
+export function createContextRoutes(settingsService?: SettingsService): Router {
   const router = Router();
 
-  router.post('/describe-image', createDescribeImageHandler());
-  router.post('/describe-file', createDescribeFileHandler());
+  router.post('/describe-image', createDescribeImageHandler(settingsService));
+  router.post('/describe-file', createDescribeFileHandler(settingsService));
 
   return router;
 }

apps/server/src/routes/context/routes/describe-file.ts

@@ -1,8 +1,9 @@
 /**
  * POST /context/describe-file endpoint - Generate description for a text file
  *
- * Uses Claude Haiku to analyze a text file and generate a concise description
- * suitable for context file metadata.
+ * Uses AI to analyze a text file and generate a concise description
+ * suitable for context file metadata. Model is configurable via
+ * phaseModels.fileDescriptionModel in settings (defaults to Haiku).
  *
  * SECURITY: This endpoint validates file paths against ALLOWED_ROOT_DIRECTORY
  * and reads file content directly (not via Claude's Read tool) to prevent
@@ -12,11 +13,15 @@
 import type { Request, Response } from 'express';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { createLogger } from '@automaker/utils';
-import { CLAUDE_MODEL_MAP } from '@automaker/types';
+import { DEFAULT_PHASE_MODELS, isCursorModel, stripProviderPrefix } from '@automaker/types';
 import { PathNotAllowedError } from '@automaker/platform';
+import { resolvePhaseModel } from '@automaker/model-resolver';
 import { createCustomOptions } from '../../../lib/sdk-options.js';
+import { ProviderFactory } from '../../../providers/provider-factory.js';
 import * as secureFs from '../../../lib/secure-fs.js';
 import * as path from 'path';
+import type { SettingsService } from '../../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting } from '../../../lib/settings-helpers.js';
 
 const logger = createLogger('DescribeFile');
 
@@ -72,9 +77,12 @@ async function extractTextFromStream(
 /**
  * Create the describe-file request handler
  *
+ * @param settingsService - Optional settings service for loading autoLoadClaudeMd setting
  * @returns Express request handler for file description
  */
-export function createDescribeFileHandler(): (req: Request, res: Response) => Promise<void> {
+export function createDescribeFileHandler(
+  settingsService?: SettingsService
+): (req: Request, res: Response) => Promise<void> {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { filePath } = req.body as DescribeFileRequestBody;
@@ -89,7 +97,7 @@ export function createDescribeFileHandler(): (req: Request, res: Response) => Pr
         return;
       }
 
-      logger.info(`[DescribeFile] Starting description generation for: ${filePath}`);
+      logger.info(`Starting description generation for: ${filePath}`);
 
       // Resolve the path for logging and cwd derivation
       const resolvedPath = secureFs.resolvePath(filePath);
@@ -104,7 +112,7 @@ export function createDescribeFileHandler(): (req: Request, res: Response) => Pr
       } catch (readError) {
         // Path not allowed - return 403 Forbidden
         if (readError instanceof PathNotAllowedError) {
-          logger.warn(`[DescribeFile] Path not allowed: ${filePath}`);
+          logger.warn(`Path not allowed: ${filePath}`);
           const response: DescribeFileErrorResponse = {
             success: false,
             error: 'File path is not within the allowed directory',
@@ -120,7 +128,7 @@ export function createDescribeFileHandler(): (req: Request, res: Response) => Pr
           'code' in readError &&
           readError.code === 'ENOENT'
         ) {
-          logger.warn(`[DescribeFile] File not found: ${resolvedPath}`);
+          logger.warn(`File not found: ${resolvedPath}`);
           const response: DescribeFileErrorResponse = {
             success: false,
             error: `File not found: ${filePath}`,
@@ -130,7 +138,7 @@ export function createDescribeFileHandler(): (req: Request, res: Response) => Pr
         }
 
         const errorMessage = readError instanceof Error ? readError.message : 'Unknown error';
-        logger.error(`[DescribeFile] Failed to read file: ${errorMessage}`);
+        logger.error(`Failed to read file: ${errorMessage}`);
         const response: DescribeFileErrorResponse = {
           success: false,
           error: `Failed to read file: ${errorMessage}`,
@@ -165,29 +173,84 @@ File: ${fileName}${truncated ? ' (truncated)' : ''}`;
       // Use the file's directory as the working directory
       const cwd = path.dirname(resolvedPath);
 
-      // Use centralized SDK options with proper cwd validation
-      // No tools needed since we're passing file content directly
-      const sdkOptions = createCustomOptions({
+      // Load autoLoadClaudeMd setting
+      const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
         cwd,
-        model: CLAUDE_MODEL_MAP.haiku,
-        maxTurns: 1,
-        allowedTools: [],
-        sandbox: { enabled: true, autoAllowBashIfSandboxed: true },
-      });
+        settingsService,
+        '[DescribeFile]'
+      );
 
-      const promptGenerator = (async function* () {
-        yield {
-          type: 'user' as const,
-          session_id: '',
-          message: { role: 'user' as const, content: promptContent },
-          parent_tool_use_id: null,
-        };
-      })();
+      // Get model from phase settings
+      const settings = await settingsService?.getGlobalSettings();
+      logger.info(`Raw phaseModels from settings:`, JSON.stringify(settings?.phaseModels, null, 2));
+      const phaseModelEntry =
+        settings?.phaseModels?.fileDescriptionModel || DEFAULT_PHASE_MODELS.fileDescriptionModel;
+      logger.info(`fileDescriptionModel entry:`, JSON.stringify(phaseModelEntry));
+      const { model, thinkingLevel } = resolvePhaseModel(phaseModelEntry);
 
-      const stream = query({ prompt: promptGenerator, options: sdkOptions });
+      logger.info(`Resolved model: ${model}, thinkingLevel: ${thinkingLevel}`);
 
-      // Extract the description from the response
-      const description = await extractTextFromStream(stream);
+      let description: string;
+
+      // Route to appropriate provider based on model type
+      if (isCursorModel(model)) {
+        // Use Cursor provider for Cursor models
+        logger.info(`Using Cursor provider for model: ${model}`);
+
+        const provider = ProviderFactory.getProviderForModel(model);
+        // Strip provider prefix - providers expect bare model IDs
+        const bareModel = stripProviderPrefix(model);
+
+        // Build a simple text prompt for Cursor (no multi-part content blocks)
+        const cursorPrompt = `${instructionText}\n\n--- FILE CONTENT ---\n${contentToAnalyze}`;
+
+        let responseText = '';
+        for await (const msg of provider.executeQuery({
+          prompt: cursorPrompt,
+          model: bareModel,
+          cwd,
+          maxTurns: 1,
+          allowedTools: [],
+          readOnly: true, // File description only reads, doesn't write
+        })) {
+          if (msg.type === 'assistant' && msg.message?.content) {
+            for (const block of msg.message.content) {
+              if (block.type === 'text' && block.text) {
+                responseText += block.text;
+              }
+            }
+          }
+        }
+        description = responseText;
+      } else {
+        // Use Claude SDK for Claude models
+        logger.info(`Using Claude SDK for model: ${model}`);
+
+        // Use centralized SDK options with proper cwd validation
+        // No tools needed since we're passing file content directly
+        const sdkOptions = createCustomOptions({
+          cwd,
+          model,
+          maxTurns: 1,
+          allowedTools: [],
+          autoLoadClaudeMd,
+          thinkingLevel, // Pass thinking level for extended thinking
+        });
+
+        const promptGenerator = (async function* () {
+          yield {
+            type: 'user' as const,
+            session_id: '',
+            message: { role: 'user' as const, content: promptContent },
+            parent_tool_use_id: null,
+          };
+        })();
+
+        const stream = query({ prompt: promptGenerator, options: sdkOptions });
+
+        // Extract the description from the response
+        description = await extractTextFromStream(stream);
+      }
 
       if (!description || description.trim().length === 0) {
         logger.warn('Received empty response from Claude');

apps/server/src/routes/context/routes/describe-image.ts

@@ -1,8 +1,9 @@
 /**
  * POST /context/describe-image endpoint - Generate description for an image
  *
- * Uses Claude Haiku to analyze an image and generate a concise description
- * suitable for context file metadata.
+ * Uses AI to analyze an image and generate a concise description
+ * suitable for context file metadata. Model is configurable via
+ * phaseModels.imageDescriptionModel in settings (defaults to Haiku).
  *
  * IMPORTANT:
  * The agent runner (chat/auto-mode) sends images as multi-part content blocks (base64 image blocks),
@@ -13,10 +14,14 @@
 import type { Request, Response } from 'express';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { createLogger, readImageAsBase64 } from '@automaker/utils';
-import { CLAUDE_MODEL_MAP } from '@automaker/types';
+import { DEFAULT_PHASE_MODELS, isCursorModel, stripProviderPrefix } from '@automaker/types';
+import { resolvePhaseModel } from '@automaker/model-resolver';
 import { createCustomOptions } from '../../../lib/sdk-options.js';
-import * as fs from 'fs';
+import { ProviderFactory } from '../../../providers/provider-factory.js';
+import * as secureFs from '../../../lib/secure-fs.js';
 import * as path from 'path';
+import type { SettingsService } from '../../../services/settings-service.js';
+import { getAutoLoadClaudeMdSetting } from '../../../lib/settings-helpers.js';
 
 const logger = createLogger('DescribeImage');
 
@@ -55,13 +60,13 @@ function filterSafeHeaders(headers: Record<string, unknown>): Record<string, unk
  */
 function findActualFilePath(requestedPath: string): string | null {
   // First, try the exact path
-  if (fs.existsSync(requestedPath)) {
+  if (secureFs.existsSync(requestedPath)) {
     return requestedPath;
   }
 
   // Try with Unicode normalization
   const normalizedPath = requestedPath.normalize('NFC');
-  if (fs.existsSync(normalizedPath)) {
+  if (secureFs.existsSync(normalizedPath)) {
     return normalizedPath;
   }
 
@@ -70,12 +75,12 @@ function findActualFilePath(requestedPath: string): string | null {
   const dir = path.dirname(requestedPath);
   const baseName = path.basename(requestedPath);
 
-  if (!fs.existsSync(dir)) {
+  if (!secureFs.existsSync(dir)) {
     return null;
   }
 
   try {
-    const files = fs.readdirSync(dir);
+    const files = secureFs.readdirSync(dir);
 
     // Normalize the requested basename for comparison
     // Replace various space-like characters with regular space for comparison
@@ -226,9 +231,12 @@ async function extractTextFromStream(
  * Uses Claude SDK query with multi-part content blocks to include the image (base64),
  * matching the agent runner behavior.
  *
+ * @param settingsService - Optional settings service for loading autoLoadClaudeMd setting
  * @returns Express request handler for image description
  */
-export function createDescribeImageHandler(): (req: Request, res: Response) => Promise<void> {
+export function createDescribeImageHandler(
+  settingsService?: SettingsService
+): (req: Request, res: Response) => Promise<void> {
   return async (req: Request, res: Response): Promise<void> => {
     const requestId = `describe-image-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
     const startedAt = Date.now();
@@ -276,9 +284,9 @@ export function createDescribeImageHandler(): (req: Request, res: Response) => P
       }
 
       // Log path + stats (this is often where issues start: missing file, perms, size)
-      let stat: fs.Stats | null = null;
+      let stat: ReturnType<typeof secureFs.statSync> | null = null;
       try {
-        stat = fs.statSync(actualPath);
+        stat = secureFs.statSync(actualPath);
         logger.info(
           `[${requestId}] fileStats size=${stat.size} bytes mtime=${stat.mtime.toISOString()}`
         );
@@ -325,39 +333,97 @@ export function createDescribeImageHandler(): (req: Request, res: Response) => P
       const cwd = path.dirname(actualPath);
       logger.info(`[${requestId}] Using cwd=${cwd}`);
 
-      // Use the same centralized option builder used across the server (validates cwd)
-      const sdkOptions = createCustomOptions({
+      // Load autoLoadClaudeMd setting
+      const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
         cwd,
-        model: CLAUDE_MODEL_MAP.haiku,
-        maxTurns: 1,
-        allowedTools: [],
-        sandbox: { enabled: true, autoAllowBashIfSandboxed: true },
-      });
-
-      logger.info(
-        `[${requestId}] SDK options model=${sdkOptions.model} maxTurns=${sdkOptions.maxTurns} allowedTools=${JSON.stringify(
-          sdkOptions.allowedTools
-        )} sandbox=${JSON.stringify(sdkOptions.sandbox)}`
+        settingsService,
+        '[DescribeImage]'
       );
 
-      const promptGenerator = (async function* () {
-        yield {
-          type: 'user' as const,
-          session_id: '',
-          message: { role: 'user' as const, content: promptContent },
-          parent_tool_use_id: null,
-        };
-      })();
+      // Get model from phase settings
+      const settings = await settingsService?.getGlobalSettings();
+      const phaseModelEntry =
+        settings?.phaseModels?.imageDescriptionModel || DEFAULT_PHASE_MODELS.imageDescriptionModel;
+      const { model, thinkingLevel } = resolvePhaseModel(phaseModelEntry);
 
-      logger.info(`[${requestId}] Calling query()...`);
-      const queryStart = Date.now();
-      const stream = query({ prompt: promptGenerator, options: sdkOptions });
-      logger.info(`[${requestId}] query() returned stream in ${Date.now() - queryStart}ms`);
+      logger.info(`[${requestId}] Using model: ${model}`);
 
-      // Extract the description from the response
-      const extractStart = Date.now();
-      const description = await extractTextFromStream(stream, requestId);
-      logger.info(`[${requestId}] extractMs=${Date.now() - extractStart}`);
+      let description: string;
+
+      // Route to appropriate provider based on model type
+      if (isCursorModel(model)) {
+        // Use Cursor provider for Cursor models
+        // Note: Cursor may have limited support for image content blocks
+        logger.info(`[${requestId}] Using Cursor provider for model: ${model}`);
+
+        const provider = ProviderFactory.getProviderForModel(model);
+        // Strip provider prefix - providers expect bare model IDs
+        const bareModel = stripProviderPrefix(model);
+
+        // Build prompt with image reference for Cursor
+        // Note: Cursor CLI may not support base64 image blocks directly,
+        // so we include the image path as context
+        const cursorPrompt = `${instructionText}\n\nImage file: ${actualPath}\nMIME type: ${imageData.mimeType}`;
+
+        let responseText = '';
+        const queryStart = Date.now();
+        for await (const msg of provider.executeQuery({
+          prompt: cursorPrompt,
+          model: bareModel,
+          cwd,
+          maxTurns: 1,
+          allowedTools: ['Read'], // Allow Read tool so Cursor can read the image if needed
+          readOnly: true, // Image description only reads, doesn't write
+        })) {
+          if (msg.type === 'assistant' && msg.message?.content) {
+            for (const block of msg.message.content) {
+              if (block.type === 'text' && block.text) {
+                responseText += block.text;
+              }
+            }
+          }
+        }
+        logger.info(`[${requestId}] Cursor query completed in ${Date.now() - queryStart}ms`);
+        description = responseText;
+      } else {
+        // Use Claude SDK for Claude models (supports image content blocks)
+        logger.info(`[${requestId}] Using Claude SDK for model: ${model}`);
+
+        // Use the same centralized option builder used across the server (validates cwd)
+        const sdkOptions = createCustomOptions({
+          cwd,
+          model,
+          maxTurns: 1,
+          allowedTools: [],
+          autoLoadClaudeMd,
+          thinkingLevel, // Pass thinking level for extended thinking
+        });
+
+        logger.info(
+          `[${requestId}] SDK options model=${sdkOptions.model} maxTurns=${sdkOptions.maxTurns} allowedTools=${JSON.stringify(
+            sdkOptions.allowedTools
+          )}`
+        );
+
+        const promptGenerator = (async function* () {
+          yield {
+            type: 'user' as const,
+            session_id: '',
+            message: { role: 'user' as const, content: promptContent },
+            parent_tool_use_id: null,
+          };
+        })();
+
+        logger.info(`[${requestId}] Calling query()...`);
+        const queryStart = Date.now();
+        const stream = query({ prompt: promptGenerator, options: sdkOptions });
+        logger.info(`[${requestId}] query() returned stream in ${Date.now() - queryStart}ms`);
+
+        // Extract the description from the response
+        const extractStart = Date.now();
+        description = await extractTextFromStream(stream, requestId);
+        logger.info(`[${requestId}] extractMs=${Date.now() - extractStart}`);
+      }
 
       if (!description || description.trim().length === 0) {
         logger.warn(`[${requestId}] Received empty response from Claude`);

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

@@ -6,17 +6,19 @@
  */
 
 import { Router } from 'express';
+import type { SettingsService } from '../../services/settings-service.js';
 import { createEnhanceHandler } from './routes/enhance.js';
 
 /**
  * Create the enhance-prompt router
  *
+ * @param settingsService - Settings service for loading custom prompts
  * @returns Express router with enhance-prompt endpoints
  */
-export function createEnhancePromptRoutes(): Router {
+export function createEnhancePromptRoutes(settingsService?: SettingsService): Router {
   const router = Router();
 
-  router.post('/', createEnhanceHandler());
+  router.post('/', createEnhanceHandler(settingsService));
 
   return router;
 }

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

@@ -1,7 +1,7 @@
 /**
  * POST /enhance-prompt endpoint - Enhance user input text
  *
- * Uses Claude AI to enhance text based on the specified enhancement mode.
+ * Uses Claude AI or Cursor to enhance text based on the specified enhancement mode.
  * Supports modes: improve, technical, simplify, acceptance
  */
 
@@ -9,9 +9,17 @@ import type { Request, Response } from 'express';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { createLogger } from '@automaker/utils';
 import { resolveModelString } from '@automaker/model-resolver';
-import { CLAUDE_MODEL_MAP } from '@automaker/types';
 import {
-  getSystemPrompt,
+  CLAUDE_MODEL_MAP,
+  isCursorModel,
+  stripProviderPrefix,
+  ThinkingLevel,
+  getThinkingTokenBudget,
+} from '@automaker/types';
+import { ProviderFactory } from '../../../providers/provider-factory.js';
+import type { SettingsService } from '../../../services/settings-service.js';
+import { getPromptCustomization } from '../../../lib/settings-helpers.js';
+import {
   buildUserPrompt,
   isValidEnhancementMode,
   type EnhancementMode,
@@ -29,6 +37,8 @@ interface EnhanceRequestBody {
   enhancementMode: string;
   /** Optional model override */
   model?: string;
+  /** Optional thinking level for Claude models (ignored for Cursor models) */
+  thinkingLevel?: ThinkingLevel;
 }
 
 /**
@@ -80,15 +90,56 @@ async function extractTextFromStream(
   return responseText;
 }
 
+/**
+ * Execute enhancement using Cursor provider
+ *
+ * @param prompt - The enhancement prompt
+ * @param model - The Cursor model to use
+ * @returns The enhanced text
+ */
+async function executeWithCursor(prompt: string, model: string): Promise<string> {
+  const provider = ProviderFactory.getProviderForModel(model);
+  // Strip provider prefix - providers expect bare model IDs
+  const bareModel = stripProviderPrefix(model);
+
+  let responseText = '';
+
+  for await (const msg of provider.executeQuery({
+    prompt,
+    model: bareModel,
+    cwd: process.cwd(), // Enhancement doesn't need a specific working directory
+    readOnly: true, // Prompt enhancement only generates text, doesn't write files
+  })) {
+    if (msg.type === 'assistant' && msg.message?.content) {
+      for (const block of msg.message.content) {
+        if (block.type === 'text' && block.text) {
+          responseText += block.text;
+        }
+      }
+    } else if (msg.type === 'result' && msg.subtype === 'success' && msg.result) {
+      // Use result if it's a final accumulated message
+      if (msg.result.length > responseText.length) {
+        responseText = msg.result;
+      }
+    }
+  }
+
+  return responseText;
+}
+
 /**
  * Create the enhance request handler
  *
+ * @param settingsService - Optional settings service for loading custom prompts
  * @returns Express request handler for text enhancement
  */
-export function createEnhanceHandler(): (req: Request, res: Response) => Promise<void> {
+export function createEnhanceHandler(
+  settingsService?: SettingsService
+): (req: Request, res: Response) => Promise<void> {
   return async (req: Request, res: Response): Promise<void> => {
     try {
-      const { originalText, enhancementMode, model } = req.body as EnhanceRequestBody;
+      const { originalText, enhancementMode, model, thinkingLevel } =
+        req.body as EnhanceRequestBody;
 
       // Validate required fields
       if (!originalText || typeof originalText !== 'string') {
@@ -128,8 +179,20 @@ export function createEnhanceHandler(): (req: Request, res: Response) => Promise
 
       logger.info(`Enhancing text with mode: ${validMode}, length: ${trimmedText.length} chars`);
 
-      // Get the system prompt for this mode
-      const systemPrompt = getSystemPrompt(validMode);
+      // Load enhancement prompts from settings (merges custom + defaults)
+      const prompts = await getPromptCustomization(settingsService, '[EnhancePrompt]');
+
+      // Get the system prompt for this mode from merged prompts
+      const systemPromptMap: Record<EnhancementMode, string> = {
+        improve: prompts.enhancement.improveSystemPrompt,
+        technical: prompts.enhancement.technicalSystemPrompt,
+        simplify: prompts.enhancement.simplifySystemPrompt,
+        acceptance: prompts.enhancement.acceptanceSystemPrompt,
+        'ux-reviewer': prompts.enhancement.uxReviewerSystemPrompt,
+      };
+      const systemPrompt = systemPromptMap[validMode];
+
+      logger.debug(`Using ${validMode} system prompt (length: ${systemPrompt.length} chars)`);
 
       // Build the user prompt with few-shot examples
       // This helps the model understand this is text transformation, not a coding task
@@ -140,24 +203,43 @@ export function createEnhanceHandler(): (req: Request, res: Response) => Promise
 
       logger.debug(`Using model: ${resolvedModel}`);
 
-      // Call Claude SDK with minimal configuration for text transformation
-      // Key: no tools, just text completion
-      const stream = query({
-        prompt: userPrompt,
-        options: {
+      let enhancedText: string;
+
+      // Route to appropriate provider based on model
+      if (isCursorModel(resolvedModel)) {
+        // Use Cursor provider for Cursor models
+        logger.info(`Using Cursor provider for model: ${resolvedModel}`);
+
+        // Cursor doesn't have a separate system prompt concept, so combine them
+        const combinedPrompt = `${systemPrompt}\n\n${userPrompt}`;
+        enhancedText = await executeWithCursor(combinedPrompt, resolvedModel);
+      } else {
+        // Use Claude SDK for Claude models
+        logger.info(`Using Claude provider for model: ${resolvedModel}`);
+
+        // Convert thinkingLevel to maxThinkingTokens for SDK
+        const maxThinkingTokens = getThinkingTokenBudget(thinkingLevel);
+        const queryOptions: Parameters<typeof query>[0]['options'] = {
           model: resolvedModel,
           systemPrompt,
           maxTurns: 1,
           allowedTools: [],
           permissionMode: 'acceptEdits',
-        },
-      });
+        };
+        if (maxThinkingTokens) {
+          queryOptions.maxThinkingTokens = maxThinkingTokens;
+        }
 
-      // Extract the enhanced text from the response
-      const enhancedText = await extractTextFromStream(stream);
+        const stream = query({
+          prompt: userPrompt,
+          options: queryOptions,
+        });
+
+        enhancedText = await extractTextFromStream(stream);
+      }
 
       if (!enhancedText || enhancedText.trim().length === 0) {
-        logger.warn('Received empty response from Claude');
+        logger.warn('Received empty response from AI');
         const response: EnhanceErrorResponse = {
           success: false,
           error: 'Failed to generate enhanced text - empty response',

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

@@ -9,8 +9,10 @@ import { createListHandler } from './routes/list.js';
 import { createGetHandler } from './routes/get.js';
 import { createCreateHandler } from './routes/create.js';
 import { createUpdateHandler } from './routes/update.js';
+import { createBulkUpdateHandler } from './routes/bulk-update.js';
+import { createBulkDeleteHandler } from './routes/bulk-delete.js';
 import { createDeleteHandler } from './routes/delete.js';
-import { createAgentOutputHandler } from './routes/agent-output.js';
+import { createAgentOutputHandler, createRawOutputHandler } from './routes/agent-output.js';
 import { createGenerateTitleHandler } from './routes/generate-title.js';
 
 export function createFeaturesRoutes(featureLoader: FeatureLoader): Router {
@@ -20,8 +22,19 @@ export function createFeaturesRoutes(featureLoader: FeatureLoader): Router {
   router.post('/get', validatePathParams('projectPath'), createGetHandler(featureLoader));
   router.post('/create', validatePathParams('projectPath'), createCreateHandler(featureLoader));
   router.post('/update', validatePathParams('projectPath'), createUpdateHandler(featureLoader));
+  router.post(
+    '/bulk-update',
+    validatePathParams('projectPath'),
+    createBulkUpdateHandler(featureLoader)
+  );
+  router.post(
+    '/bulk-delete',
+    validatePathParams('projectPath'),
+    createBulkDeleteHandler(featureLoader)
+  );
   router.post('/delete', validatePathParams('projectPath'), createDeleteHandler(featureLoader));
   router.post('/agent-output', createAgentOutputHandler(featureLoader));
+  router.post('/raw-output', createRawOutputHandler(featureLoader));
   router.post('/generate-title', createGenerateTitleHandler());
 
   return router;

apps/server/src/routes/features/routes/agent-output.ts

@@ -1,5 +1,6 @@
 /**
  * POST /agent-output endpoint - Get agent output for a feature
+ * POST /raw-output endpoint - Get raw JSONL output for debugging
  */
 
 import type { Request, Response } from 'express';
@@ -30,3 +31,31 @@ export function createAgentOutputHandler(featureLoader: FeatureLoader) {
     }
   };
 }
+
+/**
+ * Handler for getting raw JSONL output for debugging
+ */
+export function createRawOutputHandler(featureLoader: FeatureLoader) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, featureId } = req.body as {
+        projectPath: string;
+        featureId: string;
+      };
+
+      if (!projectPath || !featureId) {
+        res.status(400).json({
+          success: false,
+          error: 'projectPath and featureId are required',
+        });
+        return;
+      }
+
+      const content = await featureLoader.getRawOutput(projectPath, featureId);
+      res.json({ success: true, content });
+    } catch (error) {
+      logError(error, 'Get raw output failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/features/routes/bulk-delete.ts

@@ -0,0 +1,61 @@
+/**
+ * POST /bulk-delete endpoint - Delete multiple features at once
+ */
+
+import type { Request, Response } from 'express';
+import { FeatureLoader } from '../../../services/feature-loader.js';
+import { getErrorMessage, logError } from '../common.js';
+
+interface BulkDeleteRequest {
+  projectPath: string;
+  featureIds: string[];
+}
+
+interface BulkDeleteResult {
+  featureId: string;
+  success: boolean;
+  error?: string;
+}
+
+export function createBulkDeleteHandler(featureLoader: FeatureLoader) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { projectPath, featureIds } = req.body as BulkDeleteRequest;
+
+      if (!projectPath || !featureIds || !Array.isArray(featureIds) || featureIds.length === 0) {
+        res.status(400).json({
+          success: false,
+          error: 'projectPath and featureIds (non-empty array) are required',
+        });
+        return;
+      }
+
+      const results = await Promise.all(
+        featureIds.map(async (featureId) => {
+          const success = await featureLoader.delete(projectPath, featureId);
+          if (success) {
+            return { featureId, success: true };
+          }
+          return {
+            featureId,
+            success: false,
+            error: 'Deletion failed. Check server logs for details.',
+          };
+        })
+      );
+
+      const successCount = results.reduce((count, r) => count + (r.success ? 1 : 0), 0);
+      const failureCount = results.length - successCount;
+
+      res.json({
+        success: failureCount === 0,
+        deletedCount: successCount,
+        failedCount: failureCount,
+        results,
+      });
+    } catch (error) {
+      logError(error, 'Bulk delete features failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}