fix(ci): use two-step yq approach for manifest merging (#1408)

The 'add' function doesn't exist in yq v4, causing parse errors.
Use a two-step approach that was tested locally:
1. Collect all files with '[.files] | flatten'
2. Load merged files into first manifest with 'load()'

Tested locally with yq v4.50.1

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

.coderabbit.yaml

@@ -0,0 +1,65 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+
+# CodeRabbit Configuration
+# Documentation: https://docs.coderabbit.ai/reference/configuration
+
+language: "en-US"
+
+reviews:
+  # Review profile: "chill" for fewer comments, "assertive" for more thorough feedback
+  profile: "assertive"
+
+  # Generate high-level summary in PR description
+  high_level_summary: true
+
+  # Automatic review settings
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    # Target branches for review (in addition to default branch)
+    base_branches:
+      - develop
+      - "release/*"
+      - "hotfix/*"
+    # Skip review for PRs with these title keywords (case-insensitive)
+    ignore_title_keywords:
+      - "[WIP]"
+      - "WIP:"
+      - "DO NOT MERGE"
+    # Don't review draft PRs
+    drafts: false
+
+  # Path filters - exclude generated/vendor files
+  path_filters:
+    - "!**/node_modules/**"
+    - "!**/.venv/**"
+    - "!**/dist/**"
+    - "!**/build/**"
+    - "!**/*.lock"
+    - "!**/package-lock.json"
+    - "!**/*.min.js"
+    - "!**/*.min.css"
+
+  # Path-specific review instructions
+  path_instructions:
+    - path: "apps/backend/**/*.py"
+      instructions: |
+        Focus on Python best practices, type hints, and async patterns.
+        Check for proper error handling and security considerations.
+        Verify compatibility with Python 3.12+.
+    - path: "apps/frontend/**/*.{ts,tsx}"
+      instructions: |
+        Review React patterns and TypeScript type safety.
+        Check for proper state management and component composition.
+    - path: "tests/**"
+      instructions: |
+        Ensure tests are comprehensive and follow pytest conventions.
+        Check for proper mocking and test isolation.
+
+chat:
+  auto_reply: true
+
+knowledge_base:
+  opt_out: false
+  learnings:
+    scope: "auto"

.design-system/src/lib/icons.ts

@@ -0,0 +1,39 @@
+/**
+ * Centralized Icon Exports for Design System
+ *
+ * This file serves as the single source of truth for all lucide-react icons used
+ * throughout the design system demo app. By consolidating imports here, we enable:
+ *
+ * 1. Better tracking of which icons are actually used
+ * 2. Potential code-splitting opportunities
+ * 3. Easier future migration to alternative icon solutions
+ * 4. Reduced bundle size through optimized tree-shaking
+ *
+ * Usage:
+ *   import { Check, ChevronLeft, X } from '../lib/icons';
+ *
+ * When adding new icons:
+ *   1. Import the icon from 'lucide-react'
+ *   2. Add it to the export statement in alphabetical order
+ */
+
+export {
+  Check,
+  ChevronLeft,
+  ChevronRight,
+  Github,
+  Heart,
+  MessageSquare,
+  Minus,
+  Moon,
+  MoreVertical,
+  Plus,
+  RotateCcw,
+  Slack,
+  Sparkles,
+  Star,
+  Sun,
+  Video,
+  X,
+  Zap,
+} from 'lucide-react';

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: AndyMik90

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,75 +1,27 @@
-name: Bug Report
-description: Report a bug or unexpected behavior
-labels: ["bug", "triage"]
+name: 🐛 Bug Report
+description: Something isn't working
+labels: ["bug", "needs-triage"]
 body:
-  - type: markdown
+  - type: checkboxes
+    id: checklist
     attributes:
-      value: |
-        Thanks for taking the time to report a bug! Please fill out the sections below.
-
-  - type: textarea
-    id: description
-    attributes:
-      label: Bug Description
-      description: A clear and concise description of the bug.
-      placeholder: What happened?
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected Behavior
-      description: What did you expect to happen?
-      placeholder: What should have happened?
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduce
-    attributes:
-      label: Steps to Reproduce
-      description: Steps to reproduce the behavior.
-      placeholder: |
-        1. Run command '...'
-        2. Click on '...'
-        3. See error
-    validations:
-      required: true
-
-  - type: textarea
-    id: logs
-    attributes:
-      label: Error Messages / Logs
-      description: If applicable, paste any error messages or logs.
-      render: shell
-
-  - type: textarea
-    id: screenshots
-    attributes:
-      label: Screenshots
-      description: If applicable, add screenshots to help explain the problem.
+      label: Checklist
+      options:
+        - label: I searched existing issues and this hasn't been reported
+          required: true
 
   - type: dropdown
-    id: component
+    id: area
     attributes:
-      label: Component
-      description: Which part of Auto Claude is affected?
+      label: Area
       options:
-        - Python Backend (auto-claude/)
-        - Electron UI (auto-claude-ui/)
-        - Both
+        - Frontend
+        - Backend
+        - Fullstack
         - Not sure
     validations:
       required: true
 
-  - type: input
-    id: version
-    attributes:
-      label: Auto Claude Version
-      description: What version are you running? (check package.json or git tag)
-      placeholder: "v2.0.1"
-
   - type: dropdown
     id: os
     attributes:
@@ -78,26 +30,47 @@ body:
         - macOS
         - Windows
         - Linux
-        - Other
     validations:
       required: true
 
   - type: input
-    id: python-version
+    id: version
     attributes:
-      label: Python Version
-      description: Output of `python --version`
-      placeholder: "3.12.0"
-
-  - type: input
-    id: node-version
-    attributes:
-      label: Node.js Version (for UI issues)
-      description: Output of `node --version`
-      placeholder: "20.10.0"
+      label: Version
+      placeholder: "e.g., 2.5.5"
+    validations:
+      required: true
 
   - type: textarea
-    id: additional
+    id: description
     attributes:
-      label: Additional Context
-      description: Any other context about the problem.
+      label: What happened?
+      placeholder: Describe the bug clearly and concisely. Include any error messages you encountered.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run command '...' or click on '...'
+        2. Observe behavior '...'
+        3. See error or unexpected result
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: What did you expect to happen instead? Describe the correct behavior.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: Required for UI bugs. Attach relevant logs, screenshots, or error output.
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Questions & Discussions
+  - name: 💡 Feature Request
     url: https://github.com/AndyMik90/Auto-Claude/discussions
-    about: Ask questions and discuss ideas with the community
-  - name: Documentation
-    url: https://github.com/AndyMik90/Auto-Claude#readme
-    about: Check the documentation before opening an issue
+    about: Suggest new features in GitHub Discussions
+  - name: 💬 Discord Community
+    url: https://discord.gg/QhRnz9m5HE
+    about: Questions and discussions - join our Discord!

.github/ISSUE_TEMPLATE/docs.yml

@@ -0,0 +1,37 @@
+name: 📚 Documentation
+description: Improvements or additions to documentation
+labels: ["documentation", "needs-triage", "help wanted"]
+body:
+  - type: dropdown
+    id: type
+    attributes:
+      label: Type
+      options:
+        - Missing documentation
+        - Incorrect/outdated info
+        - Improvement suggestion
+        - Typo/grammar fix
+    validations:
+      required: true
+
+  - type: input
+    id: location
+    attributes:
+      label: Location
+      description: Which file or page?
+      placeholder: "e.g., README.md or guides/setup.md"
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to change?
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'm willing to submit a PR for this

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,70 +0,0 @@
-name: Feature Request
-description: Suggest a new feature or enhancement
-labels: ["enhancement", "triage"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for suggesting a feature! Please describe your idea below.
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem Statement
-      description: What problem does this feature solve? Is this related to a frustration?
-      placeholder: I'm always frustrated when...
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: Proposed Solution
-      description: Describe the solution you'd like to see.
-      placeholder: I would like Auto Claude to...
-    validations:
-      required: true
-
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives Considered
-      description: Have you considered any alternative solutions or workarounds?
-      placeholder: I've tried...
-
-  - type: dropdown
-    id: component
-    attributes:
-      label: Component
-      description: Which part of Auto Claude would this affect?
-      options:
-        - Python Backend (auto-claude/)
-        - Electron UI (auto-claude-ui/)
-        - Both
-        - New component
-        - Not sure
-    validations:
-      required: true
-
-  - type: dropdown
-    id: priority
-    attributes:
-      label: How important is this feature to you?
-      options:
-        - Nice to have
-        - Important for my workflow
-        - Critical / Blocking my use
-
-  - type: checkboxes
-    id: contribution
-    attributes:
-      label: Contribution
-      description: Would you be willing to help implement this?
-      options:
-        - label: I'm willing to submit a PR for this feature
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: Additional Context
-      description: Add any other context, mockups, or screenshots about the feature request.

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,61 @@
+name: ❓ Question
+description: Needs clarification
+labels: ["question", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Before asking:** Check [Discord](https://discord.gg/QhRnz9m5HE) - your question may already be answered there!
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues and Discord for similar questions
+          required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Setup/Installation
+        - Frontend
+        - Backend
+        - Configuration
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Which version are you using?
+      placeholder: "e.g., 2.7.1"
+    validations:
+      required: true
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      placeholder: "Describe your question in detail..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What are you trying to achieve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: attempts
+    attributes:
+      label: What have you already tried?
+      description: What steps have you taken to resolve this?
+      placeholder: "e.g., I tried reading the docs, searched for..."

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,44 +1,89 @@
-## Summary
+## Base Branch
 
-<!-- Brief description of what this PR does -->
+- [ ] This PR targets the `develop` branch (required for all feature/fix PRs)
+- [ ] This PR targets `main` (hotfix only - maintainers)
+
+## Description
+
+<!-- What does this PR do? 2-3 sentences -->
+
+## Related Issue
+
+Closes #
 
 ## Type of Change
 
-- [ ] Bug fix (non-breaking change that fixes an issue)
-- [ ] New feature (non-breaking change that adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
-- [ ] Documentation update
-- [ ] Refactoring (no functional changes)
-- [ ] Tests (adding or updating tests)
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 📚 Documentation
+- [ ] ♻️ Refactor
+- [ ] 🧪 Test
 
-## Related Issues
+## Area
 
-<!-- Link any related issues: Fixes #123, Closes #456 -->
+- [ ] Frontend
+- [ ] Backend
+- [ ] Fullstack
 
-## Changes Made
+## Commit Message Format
 
-<!-- List the main changes in this PR -->
+Follow conventional commits: `<type>: <subject>`
 
--
--
--
+**Types:** feat, fix, docs, style, refactor, test, chore
 
-## Screenshots
-
-<!-- If applicable, add screenshots for UI changes -->
+**Example:** `feat: add user authentication system`
 
 ## Checklist
 
-- [ ] I have run `pre-commit run --all-files` and fixed any issues
-- [ ] I have added tests for my changes (if applicable)
-- [ ] All existing tests pass locally
-- [ ] I have updated documentation (if applicable)
-- [ ] My code follows the project's code style
+- [ ] I've synced with `develop` branch
+- [ ] I've tested my changes locally
+- [ ] I've followed the code principles (SOLID, DRY, KISS)
+- [ ] My PR is small and focused (< 400 lines ideally)
+- [ ] **(Python only)** All file operations specify `encoding="utf-8"` for text files
 
-## Testing
+## Platform Testing Checklist
 
-<!-- Describe how you tested these changes -->
+**CRITICAL:** This project supports Windows, macOS, and Linux. Platform-specific bugs are a common source of breakage.
 
-## Additional Notes
+- [ ] **Windows tested** (either on Windows or via CI)
+- [ ] **macOS tested** (either on macOS or via CI)
+- [ ] **Linux tested** (CI covers this)
+- [ ] Used centralized `platform/` module instead of direct `process.platform` checks
+- [ ] No hardcoded paths (used `findExecutable()` or platform abstractions)
 
-<!-- Any additional context or notes for reviewers -->
+**If you only have access to one OS:** CI now tests on all platforms. Ensure all checks pass before submitting.
+
+## CI/Testing Requirements
+
+- [ ] All CI checks pass on **all platforms** (Windows, macOS, Linux)
+- [ ] All existing tests pass
+- [ ] New features include test coverage
+- [ ] Bug fixes include regression tests
+
+## Screenshots
+
+<!-- Required for UI changes. Delete if not applicable. -->
+
+| Before | After |
+|--------|-------|
+|        |       |
+
+## Feature Toggle
+
+<!-- If feature is incomplete or experimental, how is it hidden from users? -->
+<!-- This ensures incomplete work can be merged without affecting production. -->
+
+- [ ] Behind localStorage flag: `use_feature_name`
+- [ ] Behind settings toggle
+- [ ] Behind environment variable/config
+- [ ] N/A - Feature is complete and ready for all users
+
+## Breaking Changes
+
+<!-- Does this PR introduce breaking changes? If yes, describe what breaks and migration steps. -->
+<!-- Delete this section if not applicable. -->
+
+**Breaking:** Yes / No
+
+**Details:**
+<!-- What breaks? What do users/developers need to change? -->

.github/actions/finalize-macos-notarization/action.yml

@@ -0,0 +1,160 @@
+name: 'Finalize macOS Notarization'
+description: 'Wait for Apple notarization to complete and staple tickets to DMG files'
+
+inputs:
+  apple-id:
+    description: 'Apple ID for notarization'
+    required: true
+  apple-app-specific-password:
+    description: 'Apple app-specific password'
+    required: true
+  apple-team-id:
+    description: 'Apple Team ID'
+    required: true
+  intel-notarization-id:
+    description: 'Notarization request ID for Intel build'
+    required: false
+    default: ''
+  arm64-notarization-id:
+    description: 'Notarization request ID for ARM64 build'
+    required: false
+    default: ''
+  intel-dmg-file:
+    description: 'Filename of the Intel DMG'
+    required: false
+    default: ''
+  arm64-dmg-file:
+    description: 'Filename of the ARM64 DMG'
+    required: false
+    default: ''
+  intel-artifact-path:
+    description: 'Path to Intel build artifacts'
+    required: false
+    default: 'intel'
+  arm64-artifact-path:
+    description: 'Path to ARM64 build artifacts'
+    required: false
+    default: 'arm64'
+  timeout:
+    description: 'Timeout in seconds for notarization wait'
+    required: false
+    default: '3600'
+
+outputs:
+  intel-stapled:
+    description: 'Whether Intel DMG was successfully stapled'
+    value: ${{ steps.staple.outputs.intel_stapled }}
+  arm64-stapled:
+    description: 'Whether ARM64 DMG was successfully stapled'
+    value: ${{ steps.staple.outputs.arm64_stapled }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Wait for notarization and staple
+      id: staple
+      shell: bash
+      env:
+        APPLE_ID: ${{ inputs.apple-id }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ inputs.apple-app-specific-password }}
+        APPLE_TEAM_ID: ${{ inputs.apple-team-id }}
+        INTEL_NOTARIZATION_ID: ${{ inputs.intel-notarization-id }}
+        ARM64_NOTARIZATION_ID: ${{ inputs.arm64-notarization-id }}
+        INTEL_DMG: ${{ inputs.intel-dmg-file }}
+        ARM64_DMG: ${{ inputs.arm64-dmg-file }}
+        INTEL_PATH: ${{ inputs.intel-artifact-path }}
+        ARM64_PATH: ${{ inputs.arm64-artifact-path }}
+        TIMEOUT: ${{ inputs.timeout }}
+      run: |
+        intel_stapled=false
+        arm64_stapled=false
+
+        if [ -z "$APPLE_ID" ]; then
+          echo "Skipping notarization wait: APPLE_ID not configured"
+          echo "intel_stapled=false" >> "$GITHUB_OUTPUT"
+          echo "arm64_stapled=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Warn if no notarization IDs provided (could indicate submission failure)
+        if [ -z "$INTEL_NOTARIZATION_ID" ] && [ -z "$ARM64_NOTARIZATION_ID" ]; then
+          echo "::warning::No notarization IDs provided - nothing to finalize. Check if notarization submission succeeded."
+          echo "intel_stapled=false" >> "$GITHUB_OUTPUT"
+          echo "arm64_stapled=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Wait for Intel notarization
+        if [ -n "$INTEL_NOTARIZATION_ID" ]; then
+          echo "Waiting for Intel notarization: $INTEL_NOTARIZATION_ID"
+          if ! xcrun notarytool wait "$INTEL_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --timeout "$TIMEOUT"; then
+            echo "::error::Intel notarization failed or timed out"
+            exit 1
+          fi
+          # Verify notarization was accepted (not just processed)
+          INTEL_STATUS=$(xcrun notarytool info "$INTEL_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --output-format json | jq -r '.status // "Unknown"')
+          if [ "$INTEL_STATUS" != "Accepted" ]; then
+            echo "::error::Intel notarization status is '$INTEL_STATUS', expected 'Accepted'"
+            exit 1
+          fi
+          echo "Intel notarization status: $INTEL_STATUS"
+          # Verify DMG file exists before stapling
+          if [ ! -f "$INTEL_PATH/$INTEL_DMG" ]; then
+            echo "::error::Intel DMG not found at $INTEL_PATH/$INTEL_DMG"
+            exit 1
+          fi
+          echo "Stapling Intel DMG: $INTEL_PATH/$INTEL_DMG"
+          if ! xcrun stapler staple "$INTEL_PATH/$INTEL_DMG"; then
+            echo "::error::Failed to staple Intel DMG"
+            exit 1
+          fi
+          echo "Successfully stapled Intel DMG"
+          intel_stapled=true
+        fi
+
+        # Wait for ARM64 notarization
+        if [ -n "$ARM64_NOTARIZATION_ID" ]; then
+          echo "Waiting for ARM64 notarization: $ARM64_NOTARIZATION_ID"
+          if ! xcrun notarytool wait "$ARM64_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --timeout "$TIMEOUT"; then
+            echo "::error::ARM64 notarization failed or timed out"
+            exit 1
+          fi
+          # Verify notarization was accepted (not just processed)
+          ARM64_STATUS=$(xcrun notarytool info "$ARM64_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --output-format json | jq -r '.status // "Unknown"')
+          if [ "$ARM64_STATUS" != "Accepted" ]; then
+            echo "::error::ARM64 notarization status is '$ARM64_STATUS', expected 'Accepted'"
+            exit 1
+          fi
+          echo "ARM64 notarization status: $ARM64_STATUS"
+          # Verify DMG file exists before stapling
+          if [ ! -f "$ARM64_PATH/$ARM64_DMG" ]; then
+            echo "::error::ARM64 DMG not found at $ARM64_PATH/$ARM64_DMG"
+            exit 1
+          fi
+          echo "Stapling ARM64 DMG: $ARM64_PATH/$ARM64_DMG"
+          if ! xcrun stapler staple "$ARM64_PATH/$ARM64_DMG"; then
+            echo "::error::Failed to staple ARM64 DMG"
+            exit 1
+          fi
+          echo "Successfully stapled ARM64 DMG"
+          arm64_stapled=true
+        fi
+
+        echo "intel_stapled=$intel_stapled" >> "$GITHUB_OUTPUT"
+        echo "arm64_stapled=$arm64_stapled" >> "$GITHUB_OUTPUT"

.github/actions/merge-macos-manifests/action.yml

@@ -0,0 +1,194 @@
+name: 'Merge macOS Manifests'
+description: 'Merge Intel and ARM64 macOS manifests for electron-updater'
+
+inputs:
+  dist-path:
+    description: 'Path to the dist directory containing build artifacts'
+    required: false
+    default: 'dist'
+  output-path:
+    description: 'Path to output the merged manifest'
+    required: false
+    default: 'release-assets'
+  copy-other-manifests:
+    description: 'Whether to copy Windows/Linux manifests as well'
+    required: false
+    default: 'true'
+  yq-version:
+    description: 'Version of yq to use for YAML merging'
+    required: false
+    default: 'v4.44.3'
+
+outputs:
+  merged:
+    description: 'Whether manifests were merged (true) or single architecture used (false)'
+    value: ${{ steps.merge.outputs.merged }}
+  file-count:
+    description: 'Number of files in the merged manifest'
+    value: ${{ steps.validate.outputs.file_count }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Merge macOS manifests
+      id: merge
+      shell: bash
+      env:
+        # yq SHA256 checksum for v4.44.3 linux_amd64
+        # When updating yq-version, update this checksum and the one in validate step
+        YQ_SHA256: "a2c097180dd884a8d50c956ee16a9cec070f30a7947cf4ebf87d5f36213e9ed7"
+      run: |
+        echo "=== Merging macOS update manifests ==="
+
+        # Find all latest-mac.yml files from different build artifacts
+        intel_manifest=$(find "${{ inputs.dist-path }}" -path "*/macos-intel-builds/latest-mac.yml" -type f 2>/dev/null | head -1)
+        arm64_manifest=$(find "${{ inputs.dist-path }}" -path "*/macos-arm64-builds/latest-mac.yml" -type f 2>/dev/null | head -1)
+
+        echo "Intel manifest: ${intel_manifest:-not found}"
+        echo "ARM64 manifest: ${arm64_manifest:-not found}"
+
+        mkdir -p "${{ inputs.output-path }}"
+
+        if [ -n "$intel_manifest" ] && [ -n "$arm64_manifest" ]; then
+          echo "Both architectures found - merging manifests..."
+          echo "merged=true" >> "$GITHUB_OUTPUT"
+
+          # Install yq for YAML merging (pinned version with checksum verification)
+          YQ_VERSION="${{ inputs.yq-version }}"
+          YQ_URL="https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"
+
+          echo "Downloading yq ${YQ_VERSION}..."
+          if ! wget -qO /tmp/yq "$YQ_URL"; then
+            echo "::error::Failed to download yq ${YQ_VERSION}"
+            exit 1
+          fi
+
+          # Verify checksum
+          echo "Verifying yq checksum..."
+          ACTUAL_SHA256=$(sha256sum /tmp/yq | cut -d' ' -f1)
+          if [ "$ACTUAL_SHA256" != "$YQ_SHA256" ]; then
+            echo "::error::yq checksum verification failed!"
+            echo "Expected: $YQ_SHA256"
+            echo "Actual:   $ACTUAL_SHA256"
+            rm -f /tmp/yq
+            exit 1
+          fi
+          echo "Checksum verified successfully"
+
+          sudo mv /tmp/yq /usr/local/bin/yq
+          sudo chmod +x /usr/local/bin/yq
+          echo "Installed yq version:"
+          yq --version
+
+          # Merge the files arrays from both manifests using two-step approach
+          # Step 1: Collect all files from both manifests into a temp file
+          yq eval-all '[.files] | flatten' "$intel_manifest" "$arm64_manifest" > /tmp/merged-files.yml
+
+          # Step 2: Replace files array in first manifest with merged files
+          yq eval '.files = load("/tmp/merged-files.yml")' "$intel_manifest" > "${{ inputs.output-path }}/latest-mac.yml"
+
+          echo "Merged manifest contents:"
+          cat "${{ inputs.output-path }}/latest-mac.yml"
+
+        elif [ -n "$intel_manifest" ]; then
+          echo "Only Intel manifest found - using as-is"
+          echo "merged=false" >> "$GITHUB_OUTPUT"
+          cp "$intel_manifest" "${{ inputs.output-path }}/latest-mac.yml"
+        elif [ -n "$arm64_manifest" ]; then
+          echo "Only ARM64 manifest found - using as-is"
+          echo "merged=false" >> "$GITHUB_OUTPUT"
+          cp "$arm64_manifest" "${{ inputs.output-path }}/latest-mac.yml"
+        else
+          echo "::error::No macOS manifests found - this will cause auto-update to fail"
+          exit 1
+        fi
+
+    - name: Validate merged manifest
+      id: validate
+      shell: bash
+      env:
+        # Single source of truth for yq checksum - must match merge step
+        YQ_SHA256: "a2c097180dd884a8d50c956ee16a9cec070f30a7947cf4ebf87d5f36213e9ed7"
+      run: |
+        manifest_file="${{ inputs.output-path }}/latest-mac.yml"
+
+        echo "=== Validating merged manifest ==="
+
+        # Check file exists
+        if [ ! -f "$manifest_file" ]; then
+          echo "::error::Merged manifest file not found at $manifest_file"
+          exit 1
+        fi
+
+        # Install yq if not already installed (for single-arch case)
+        if ! command -v yq &> /dev/null; then
+          YQ_VERSION="${{ inputs.yq-version }}"
+          YQ_URL="https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"
+
+          echo "Downloading yq ${YQ_VERSION}..."
+          wget -qO /tmp/yq "$YQ_URL"
+
+          # Verify checksum (YQ_SHA256 from env)
+          ACTUAL_SHA256=$(sha256sum /tmp/yq | cut -d' ' -f1)
+          if [ "$ACTUAL_SHA256" != "$YQ_SHA256" ]; then
+            echo "::error::yq checksum verification failed!"
+            echo "Expected: $YQ_SHA256"
+            echo "Actual:   $ACTUAL_SHA256"
+            exit 1
+          fi
+
+          sudo mv /tmp/yq /usr/local/bin/yq
+          sudo chmod +x /usr/local/bin/yq
+        fi
+
+        # Validate YAML is parseable
+        if ! yq eval '.' "$manifest_file" > /dev/null 2>&1; then
+          echo "::error::Merged manifest is not valid YAML"
+          cat "$manifest_file"
+          exit 1
+        fi
+        echo "YAML syntax is valid"
+
+        # Count files in manifest
+        file_count=$(yq eval '.files | length' "$manifest_file")
+        echo "file_count=$file_count" >> "$GITHUB_OUTPUT"
+        echo "Manifest contains $file_count file entries"
+
+        # Validate file count
+        if [ "$file_count" -eq 0 ]; then
+          echo "::error::Merged manifest contains no files"
+          exit 1
+        fi
+
+        # If we merged both architectures, expect at least 2 files (one per arch)
+        if [ "${{ steps.merge.outputs.merged }}" = "true" ] && [ "$file_count" -lt 2 ]; then
+          echo "::warning::Merged manifest has fewer than 2 files - merge may have failed"
+        fi
+
+        # Validate required fields exist
+        if ! yq eval '.version' "$manifest_file" | grep -q .; then
+          echo "::error::Manifest missing 'version' field"
+          exit 1
+        fi
+        echo "Version field present: $(yq eval '.version' "$manifest_file")"
+
+        echo "Manifest validation passed"
+
+    - name: Copy other manifests
+      if: inputs.copy-other-manifests == 'true'
+      shell: bash
+      run: |
+        echo "=== Copying other update manifests ==="
+
+        # Copy other manifests (Windows, Linux) - these don't have the duplicate issue
+        for manifest in latest.yml latest-linux.yml latest-linux-arm64.yml; do
+          found=$(find "${{ inputs.dist-path }}" -name "$manifest" -type f 2>/dev/null | head -1)
+          if [ -n "$found" ]; then
+            echo "Copying $manifest"
+            cp "$found" "${{ inputs.output-path }}/"
+          fi
+        done
+
+        echo ""
+        echo "=== Manifest files in ${{ inputs.output-path }} ==="
+        ls -la "${{ inputs.output-path }}"/*.yml 2>/dev/null || echo "No manifest files found"

.github/actions/setup-node-frontend/action.yml

@@ -0,0 +1,126 @@
+name: 'Setup Node.js Frontend'
+description: 'Set up Node.js with npm and cached dependencies for the frontend'
+
+inputs:
+  node-version:
+    description: 'Node.js version to use'
+    required: false
+    default: '24'
+  ignore-scripts:
+    description: 'Whether to use --ignore-scripts flag during npm ci'
+    required: false
+    default: 'false'
+
+outputs:
+  cache-hit:
+    description: 'Whether npm cache was hit'
+    value: ${{ steps.cache.outputs.cache-hit }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Node.js ${{ inputs.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Get npm cache directory
+      id: npm-cache-dir
+      shell: bash
+      run: echo "dir=$(npm config get cache)" >> "$GITHUB_OUTPUT"
+
+    - name: Cache npm dependencies
+      id: cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.npm-cache-dir.outputs.dir }}
+        key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+        restore-keys: ${{ runner.os }}-npm-
+
+    - name: Install dependencies
+      shell: bash
+      # Run npm ci from root to properly handle workspace dependencies.
+      # With npm workspaces, the lock file is at root and dependencies are hoisted there.
+      # Running npm ci in apps/frontend would fail to populate node_modules correctly.
+      run: |
+        if [ "${{ inputs.ignore-scripts }}" == "true" ]; then
+          npm ci --ignore-scripts
+        else
+          npm ci
+        fi
+
+    - name: Link node_modules for electron-builder
+      shell: bash
+      # electron-builder expects node_modules in apps/frontend for native module rebuilding.
+      # With npm workspaces, packages are hoisted to root. Create a link so electron-builder
+      # can find the modules during packaging and code signing.
+      # Uses symlink on Unix, directory junction on Windows (works without admin privileges).
+      #
+      # IMPORTANT: npm workspaces may create a partial node_modules in apps/frontend for
+      # packages that couldn't be hoisted. We must remove it and create a proper link to root.
+      run: |
+        # Verify npm ci succeeded
+        if [ ! -d "node_modules" ]; then
+          echo "::error::Root node_modules does not exist. npm ci may have failed."
+          exit 1
+        fi
+
+        # Remove any existing node_modules in apps/frontend
+        # This handles: partial directories from npm workspaces, AND broken symlinks
+        if [ -e "apps/frontend/node_modules" ] || [ -L "apps/frontend/node_modules" ]; then
+          # Check if it's a valid symlink pointing to root node_modules
+          if [ -L "apps/frontend/node_modules" ]; then
+            target=$(readlink apps/frontend/node_modules 2>/dev/null || echo "")
+            if [ "$target" = "../../node_modules" ] && [ -d "apps/frontend/node_modules" ]; then
+              echo "Correct symlink already exists: apps/frontend/node_modules -> ../../node_modules"
+            else
+              echo "Removing incorrect/broken symlink (was: $target)..."
+              rm -f "apps/frontend/node_modules"
+            fi
+          else
+            echo "Removing partial node_modules directory created by npm workspaces..."
+            rm -rf "apps/frontend/node_modules"
+          fi
+        fi
+
+        # Create link if it doesn't exist or was removed
+        if [ ! -L "apps/frontend/node_modules" ]; then
+          if [ "$RUNNER_OS" == "Windows" ]; then
+            # Use directory junction on Windows (works without admin privileges)
+            # Use PowerShell's New-Item -ItemType Junction for reliable path handling
+            abs_target=$(cygpath -w "$(pwd)/node_modules")
+            link_path=$(cygpath -w "$(pwd)/apps/frontend/node_modules")
+            powershell -Command "New-Item -ItemType Junction -Path '$link_path' -Target '$abs_target'" > /dev/null
+            if [ $? -eq 0 ]; then
+              echo "Created junction: apps/frontend/node_modules -> $abs_target"
+            else
+              echo "::error::Failed to create directory junction on Windows"
+              exit 1
+            fi
+          else
+            # Use symlink on Unix (macOS/Linux)
+            if ln -s ../../node_modules apps/frontend/node_modules; then
+              echo "Created symlink: apps/frontend/node_modules -> ../../node_modules"
+            else
+              echo "::error::Failed to create symlink"
+              exit 1
+            fi
+          fi
+        fi
+
+        # Final verification - the link must exist and resolve correctly
+        # Note: On Windows, junctions don't show as symlinks (-L), so we check if the directory exists
+        # and can be listed. On Unix, we also verify it's a symlink.
+        if [ "$RUNNER_OS" != "Windows" ] && [ ! -L "apps/frontend/node_modules" ]; then
+          echo "::error::apps/frontend/node_modules symlink was not created"
+          exit 1
+        fi
+        # Verify the link resolves to a valid directory with content
+        if ! ls apps/frontend/node_modules/electron >/dev/null 2>&1; then
+          echo "::error::apps/frontend/node_modules does not resolve correctly (electron not found)"
+          ls -la apps/frontend/ || true
+          ls apps/frontend/node_modules 2>&1 | head -5 || true
+          exit 1
+        fi
+        count=$(ls apps/frontend/node_modules 2>/dev/null | wc -l)
+        echo "Verified: apps/frontend/node_modules resolves correctly ($count entries)"

.github/actions/setup-python-backend/action.yml

@@ -0,0 +1,52 @@
+name: 'Setup Python Backend'
+description: 'Set up Python with uv package manager and cached dependencies for the backend'
+
+inputs:
+  python-version:
+    description: 'Python version to use'
+    required: false
+    default: '3.12'
+  install-test-deps:
+    description: 'Whether to install test dependencies'
+    required: false
+    default: 'false'
+
+outputs:
+  cache-hit:
+    description: 'Whether cache was hit'
+    value: ${{ steps.cache.outputs.cache-hit }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python ${{ inputs.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv package manager
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Cache uv dependencies
+      id: cache
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/uv
+          ~/AppData/Local/uv/cache
+          ~/Library/Caches/uv
+        key: uv-${{ runner.os }}-${{ runner.arch }}-${{ inputs.python-version }}-${{ hashFiles('apps/backend/requirements.txt', 'tests/requirements-test.txt') }}
+        restore-keys: |
+          uv-${{ runner.os }}-${{ runner.arch }}-${{ inputs.python-version }}-
+
+    - name: Install dependencies
+      working-directory: apps/backend
+      shell: bash
+      run: |
+        uv venv
+        uv pip install -r requirements.txt
+        if [ "${{ inputs.install-test-deps }}" == "true" ]; then
+          uv pip install -r ../../tests/requirements-test.txt
+        fi

.github/actions/submit-macos-notarization/action.yml

@@ -0,0 +1,87 @@
+name: 'Submit macOS Notarization'
+description: 'Submit a macOS DMG file for Apple notarization asynchronously'
+
+inputs:
+  apple-id:
+    description: 'Apple ID for notarization'
+    required: true
+  apple-app-specific-password:
+    description: 'Apple app-specific password'
+    required: true
+  apple-team-id:
+    description: 'Apple Team ID'
+    required: true
+  dmg-path:
+    description: 'Path to the dist directory containing the DMG file'
+    required: false
+    default: 'apps/frontend/dist'
+
+outputs:
+  notarization-id:
+    description: 'The notarization request ID'
+    value: ${{ steps.submit.outputs.notarization_id }}
+  dmg-file:
+    description: 'The DMG filename that was submitted'
+    value: ${{ steps.submit.outputs.dmg_file }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Submit notarization (async)
+      id: submit
+      shell: bash
+      env:
+        APPLE_ID: ${{ inputs.apple-id }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ inputs.apple-app-specific-password }}
+        APPLE_TEAM_ID: ${{ inputs.apple-team-id }}
+        DMG_PATH: ${{ inputs.dmg-path }}
+      run: |
+        if [ -z "$APPLE_ID" ]; then
+          echo "Skipping notarization: APPLE_ID not configured"
+          echo "notarization_id=" >> "$GITHUB_OUTPUT"
+          echo "dmg_file=" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Find the DMG file
+        DMG_FILE=$(find "$DMG_PATH" -name "*.dmg" -type f | head -1)
+        if [ -z "$DMG_FILE" ]; then
+          echo "::error::No DMG file found in $DMG_PATH"
+          exit 1
+        fi
+
+        echo "Submitting $DMG_FILE for notarization (async)..."
+
+        # Submit for notarization without waiting
+        # Capture both stdout and exit code
+        set +e
+        RESULT=$(xcrun notarytool submit "$DMG_FILE" \
+          --apple-id "$APPLE_ID" \
+          --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+          --team-id "$APPLE_TEAM_ID" \
+          --no-wait \
+          --output-format json 2>&1)
+        SUBMIT_EXIT_CODE=$?
+        set -e
+
+        echo "$RESULT"
+
+        # Check if submission command itself failed (not just missing ID)
+        if [ $SUBMIT_EXIT_CODE -ne 0 ]; then
+          echo "::error::notarytool submit failed with exit code $SUBMIT_EXIT_CODE"
+          exit 1
+        fi
+
+        # Extract the notarization ID from JSON response
+        # jq is always available on macOS runners
+        NOTARIZATION_ID=$(echo "$RESULT" | jq -r '.id // empty' 2>/dev/null)
+
+        if [ -z "$NOTARIZATION_ID" ]; then
+          echo "::error::Failed to get notarization ID from response"
+          echo "Response was: $RESULT"
+          exit 1
+        fi
+
+        echo "Notarization submitted with ID: $NOTARIZATION_ID"
+        echo "notarization_id=$NOTARIZATION_ID" >> "$GITHUB_OUTPUT"
+        echo "dmg_file=$(basename "$DMG_FILE")" >> "$GITHUB_OUTPUT"

.github/dependabot.yml

@@ -0,0 +1,37 @@
+version: 2
+updates:
+  # Python dependencies
+  - package-ecosystem: pip
+    directory: /apps/backend
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - python
+    commit-message:
+      prefix: "chore(deps)"
+
+  # npm dependencies
+  - package-ecosystem: npm
+    directory: /apps/frontend
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - javascript
+    commit-message:
+      prefix: "chore(deps)"
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci
+    commit-message:
+      prefix: "ci(deps)"

.github/release-drafter.yml

@@ -0,0 +1,35 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+
+categories:
+  - title: '## New Features'
+    labels:
+      - 'feature'
+      - 'enhancement'
+  - title: '## Bug Fixes'
+    labels:
+      - 'bug'
+      - 'fix'
+  - title: '## Improvements'
+    labels:
+      - 'improvement'
+      - 'refactor'
+  - title: '## Documentation'
+    labels:
+      - 'documentation'
+  - title: '## Other Changes'
+    labels:
+      - '*'
+
+change-template: '* $TITLE (#$NUMBER) @$AUTHOR'
+
+sort-by: merged_at
+sort-direction: ascending
+
+template: |
+  $CHANGES
+
+  **Full Changelog**: https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...$RESOLVED_VERSION
+
+  ## Contributors
+  $CONTRIBUTORS

.github/workflows/beta-release.yml

@@ -0,0 +1,742 @@
+name: Beta Release
+
+# Manual trigger for beta releases from develop branch
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Beta version (e.g., 2.8.0-beta.1)'
+        required: true
+        type: string
+      dry_run:
+        description: 'Test build without creating release'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  validate-version:
+    name: Validate beta version format
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate version format
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+
+          # Check if version matches beta semver pattern
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+-(beta|alpha|rc)\.[0-9]+$ ]]; then
+            echo "::error::Invalid version format: $VERSION"
+            echo "Version must match pattern: X.Y.Z-beta.N (e.g., 2.8.0-beta.1)"
+            exit 1
+          fi
+
+          echo "Valid beta version: $VERSION"
+
+  create-tag:
+    name: Create beta tag
+    needs: validate-version
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ github.event.inputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: develop
+
+      - name: Create and push tag
+        if: ${{ github.event.inputs.dry_run != 'true' }}
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v$VERSION" -m "Beta release v$VERSION"
+          git push origin "v$VERSION"
+          echo "Created tag v$VERSION"
+
+      - name: Create tag only (dry run)
+        if: ${{ github.event.inputs.dry_run == 'true' }}
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          echo "DRY RUN: Would create tag v$VERSION"
+
+  # Intel build on Intel runner for native compilation
+  build-macos-intel:
+    needs: create-tag
+    runs-on: macos-15-intel
+    outputs:
+      notarization_id: ${{ steps.notarize.outputs.notarization-id }}
+      dmg_file: ${{ steps.notarize.outputs.dmg-file }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use tag for real releases, develop branch for dry runs
+          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Install Rust toolchain (for building native Python packages)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-rust-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package macOS (Intel)
+        run: |
+          VERSION="${{ needs.create-tag.outputs.version }}"
+          cd apps/frontend && npm run package:mac -- --x64 --config.extraMetadata.version="$VERSION"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
+          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Submit notarization (async)
+        id: notarize
+        uses: ./.github/actions/submit-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-intel-builds
+          path: |
+            apps/frontend/dist/*.dmg
+            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+
+  # Apple Silicon build on ARM64 runner for native compilation
+  build-macos-arm64:
+    needs: create-tag
+    runs-on: macos-15
+    outputs:
+      notarization_id: ${{ steps.notarize.outputs.notarization-id }}
+      dmg_file: ${{ steps.notarize.outputs.dmg-file }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use tag for real releases, develop branch for dry runs
+          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-arm64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-arm64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package macOS (Apple Silicon)
+        run: |
+          VERSION="${{ needs.create-tag.outputs.version }}"
+          cd apps/frontend && npm run package:mac -- --arm64 --config.extraMetadata.version="$VERSION"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
+          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Submit notarization (async)
+        id: notarize
+        uses: ./.github/actions/submit-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-arm64-builds
+          path: |
+            apps/frontend/dist/*.dmg
+            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+
+  build-windows:
+    needs: create-tag
+    runs-on: windows-latest
+    permissions:
+      id-token: write  # Required for OIDC authentication with Azure
+      contents: read
+    env:
+      # Job-level env so AZURE_CLIENT_ID is available for step-level if conditions
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use tag for real releases, develop branch for dry runs
+          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~\AppData\Local\pip\Cache
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package Windows
+        shell: bash
+        run: |
+          VERSION="${{ needs.create-tag.outputs.version }}"
+          cd apps/frontend && npm run package:win -- --config.extraMetadata.version="$VERSION"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Disable electron-builder's built-in signing (we use Azure Trusted Signing instead)
+          CSC_IDENTITY_AUTO_DISCOVERY: false
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Azure Login (OIDC)
+        if: env.AZURE_CLIENT_ID != ''
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Sign Windows executable with Azure Trusted Signing
+        if: env.AZURE_CLIENT_ID != ''
+        uses: azure/trusted-signing-action@v0.5.11
+        with:
+          endpoint: https://neu.codesigning.azure.net/
+          trusted-signing-account-name: ${{ secrets.AZURE_SIGNING_ACCOUNT }}
+          certificate-profile-name: ${{ secrets.AZURE_CERTIFICATE_PROFILE }}
+          files-folder: apps/frontend/dist
+          files-folder-filter: exe
+          file-digest: SHA256
+          timestamp-rfc3161: http://timestamp.acs.microsoft.com
+          timestamp-digest: SHA256
+
+      - name: Verify Windows executable is signed
+        if: env.AZURE_CLIENT_ID != ''
+        shell: pwsh
+        run: |
+          cd apps/frontend/dist
+          $exeFile = Get-ChildItem -Filter "*.exe" | Select-Object -First 1
+          if ($exeFile) {
+            Write-Host "Verifying signature on $($exeFile.Name)..."
+            $sig = Get-AuthenticodeSignature -FilePath $exeFile.FullName
+            if ($sig.Status -ne 'Valid') {
+              Write-Host "::error::Signature verification failed: $($sig.Status)"
+              Write-Host "::error::Status Message: $($sig.StatusMessage)"
+              exit 1
+            }
+            Write-Host "✅ Signature verified successfully"
+            Write-Host "  Subject: $($sig.SignerCertificate.Subject)"
+            Write-Host "  Issuer: $($sig.SignerCertificate.Issuer)"
+            Write-Host "  Thumbprint: $($sig.SignerCertificate.Thumbprint)"
+          } else {
+            Write-Host "::error::No .exe file found to verify"
+            exit 1
+          }
+
+      - name: Regenerate checksums after signing
+        if: env.AZURE_CLIENT_ID != ''
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          cd apps/frontend/dist
+
+          # Find the installer exe (electron-builder names it with "Setup" or just the app name)
+          # electron-builder produces one installer exe per build
+          $exeFiles = Get-ChildItem -Filter "*.exe"
+          if ($exeFiles.Count -eq 0) {
+            Write-Host "::error::No .exe files found in dist folder"
+            exit 1
+          }
+
+          Write-Host "Found $($exeFiles.Count) exe file(s): $($exeFiles.Name -join ', ')"
+
+          $ymlFile = "latest.yml"
+          if (-not (Test-Path $ymlFile)) {
+            Write-Host "::error::$ymlFile not found - cannot update checksums"
+            exit 1
+          }
+
+          $content = Get-Content $ymlFile -Raw
+          $originalContent = $content
+
+          # Process each exe file and update its hash in latest.yml
+          foreach ($exeFile in $exeFiles) {
+            Write-Host "Processing $($exeFile.Name)..."
+
+            # Compute SHA512 hash and convert to base64 (electron-builder format)
+            $bytes = [System.IO.File]::ReadAllBytes($exeFile.FullName)
+            $sha512 = [System.Security.Cryptography.SHA512]::Create()
+            $hashBytes = $sha512.ComputeHash($bytes)
+            $hash = [System.Convert]::ToBase64String($hashBytes)
+            $size = $exeFile.Length
+
+            Write-Host "  Hash: $hash"
+            Write-Host "  Size: $size"
+          }
+
+          # For electron-builder, latest.yml has a single file entry for the installer
+          # Update the sha512 and size for the primary exe (first one, typically the installer)
+          $primaryExe = $exeFiles | Select-Object -First 1
+          $bytes = [System.IO.File]::ReadAllBytes($primaryExe.FullName)
+          $sha512 = [System.Security.Cryptography.SHA512]::Create()
+          $hashBytes = $sha512.ComputeHash($bytes)
+          $hash = [System.Convert]::ToBase64String($hashBytes)
+          $size = $primaryExe.Length
+
+          # Update sha512 hash (base64 pattern: alphanumeric, +, /, =)
+          $content = $content -replace 'sha512: [A-Za-z0-9+/=]+', "sha512: $hash"
+          # Update size
+          $content = $content -replace 'size: \d+', "size: $size"
+
+          if ($content -eq $originalContent) {
+            Write-Host "::error::Checksum replacement failed - content unchanged. Check if latest.yml format has changed."
+            exit 1
+          }
+
+          Set-Content -Path $ymlFile -Value $content -NoNewline
+          Write-Host "✅ Updated $ymlFile with new base64 hash and size for $($primaryExe.Name)"
+
+      - name: Skip signing notice
+        if: env.AZURE_CLIENT_ID == ''
+        run: echo "::warning::Windows signing skipped - AZURE_CLIENT_ID not configured. The .exe will be unsigned."
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-builds
+          path: |
+            apps/frontend/dist/*.exe
+            apps/frontend/dist/*.yml
+
+  build-linux:
+    needs: create-tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Use tag for real releases, develop branch for dry runs
+          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Setup Flatpak
+        run: |
+          set -e
+          sudo apt-get update
+          sudo apt-get install -y flatpak flatpak-builder
+          flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+          flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
+          flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package Linux
+        run: |
+          VERSION="${{ needs.create-tag.outputs.version }}"
+          cd apps/frontend && npm run package:linux -- --config.extraMetadata.version="$VERSION"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-builds
+          path: |
+            apps/frontend/dist/*.AppImage
+            apps/frontend/dist/*.deb
+            apps/frontend/dist/*.flatpak
+            apps/frontend/dist/*.yml
+
+  # Finalize macOS notarization (runs in parallel with Windows/Linux builds)
+  finalize-notarization:
+    needs: [build-macos-intel, build-macos-arm64]
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Intel DMG
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-intel-builds
+          path: intel
+
+      - name: Download ARM64 DMG
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-arm64-builds
+          path: arm64
+
+      - name: Wait for notarization and staple
+        uses: ./.github/actions/finalize-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+          intel-notarization-id: ${{ needs.build-macos-intel.outputs.notarization_id }}
+          arm64-notarization-id: ${{ needs.build-macos-arm64.outputs.notarization_id }}
+          intel-dmg-file: ${{ needs.build-macos-intel.outputs.dmg_file }}
+          arm64-dmg-file: ${{ needs.build-macos-arm64.outputs.dmg_file }}
+
+      - name: Upload stapled Intel DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-intel-stapled
+          path: intel/*.dmg
+
+      - name: Upload stapled ARM64 DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-arm64-stapled
+          path: arm64/*.dmg
+
+  create-release:
+    needs: [create-tag, finalize-notarization, build-windows, build-linux]
+    runs-on: ubuntu-latest
+    if: ${{ github.event.inputs.dry_run != 'true' }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: v${{ needs.create-tag.outputs.version }}
+          fetch-depth: 0
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+
+      - name: Flatten binary artifacts
+        run: |
+          mkdir -p release-assets
+
+          # Copy stapled macOS DMGs (from finalize-notarization job)
+          # Validate that stapled DMGs exist before copying
+          if ! find dist/macos-intel-stapled dist/macos-arm64-stapled -type f -name "*.dmg" 2>/dev/null | grep -q .; then
+            echo "::warning::No stapled DMGs found. Using un-stapled DMGs from build artifacts."
+            find dist/macos-intel-builds dist/macos-arm64-builds -type f -name "*.dmg" -exec cp {} release-assets/ \; 2>/dev/null || true
+          else
+            find dist/macos-intel-stapled dist/macos-arm64-stapled -type f -name "*.dmg" -exec cp {} release-assets/ \; 2>/dev/null || true
+          fi
+
+          # Copy other macOS artifacts (zip, yml, blockmap for delta updates) from original build
+          find dist/macos-intel-builds dist/macos-arm64-builds -type f \( -name "*.zip" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Copy Windows and Linux artifacts (including blockmap for delta updates)
+          find dist/windows-builds dist/linux-builds -type f \( -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Validate that at least one artifact was copied
+          artifact_count=$(find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) | wc -l)
+          if [ "$artifact_count" -eq 0 ]; then
+            echo "::error::No build artifacts found! Expected .dmg, .zip, .exe, .AppImage, .deb, or .flatpak files."
+            exit 1
+          fi
+
+          echo "Found $artifact_count binary artifact(s):"
+          ls -la release-assets/
+
+      # Merge macOS manifests from Intel and ARM64 builds
+      # See: https://github.com/electron-userland/electron-builder/issues/5592
+      - name: Merge macOS manifests
+        uses: ./.github/actions/merge-macos-manifests
+        with:
+          dist-path: dist
+          output-path: release-assets
+          copy-other-manifests: 'true'
+
+      - name: Rename and validate beta manifests
+        run: |
+          cd release-assets
+
+          echo "=== Current manifest files ==="
+          ls -la *.yml 2>/dev/null || echo "No yml files found yet"
+
+          # electron-builder generates latest*.yml files by default
+          # For beta channel, electron-updater expects beta*.yml files
+          # Rename: latest.yml -> beta.yml, latest-mac.yml -> beta-mac.yml, latest-linux.yml -> beta-linux.yml
+
+          # Windows: latest.yml -> beta.yml
+          if [ -f "latest.yml" ]; then
+            echo "Renaming latest.yml -> beta.yml (Windows)"
+            mv latest.yml beta.yml
+          fi
+
+          # macOS: latest-mac.yml -> beta-mac.yml
+          if [ -f "latest-mac.yml" ]; then
+            echo "Renaming latest-mac.yml -> beta-mac.yml (macOS)"
+            mv latest-mac.yml beta-mac.yml
+          fi
+
+          # Linux: latest-linux.yml -> beta-linux.yml
+          if [ -f "latest-linux.yml" ]; then
+            echo "Renaming latest-linux.yml -> beta-linux.yml (Linux)"
+            mv latest-linux.yml beta-linux.yml
+          fi
+
+          # Linux ARM64: latest-linux-arm64.yml -> beta-linux-arm64.yml (if exists)
+          if [ -f "latest-linux-arm64.yml" ]; then
+            echo "Renaming latest-linux-arm64.yml -> beta-linux-arm64.yml (Linux ARM64)"
+            mv latest-linux-arm64.yml beta-linux-arm64.yml
+          fi
+
+          echo ""
+          echo "=== Beta manifest files after rename ==="
+          ls -la *.yml 2>/dev/null || echo "No yml files found"
+
+          # Validate required beta manifests exist
+          missing_manifests=""
+
+          if [ ! -f "beta-mac.yml" ]; then
+            missing_manifests="$missing_manifests beta-mac.yml"
+          fi
+
+          if [ ! -f "beta.yml" ]; then
+            missing_manifests="$missing_manifests beta.yml"
+          fi
+
+          if [ ! -f "beta-linux.yml" ]; then
+            missing_manifests="$missing_manifests beta-linux.yml"
+          fi
+
+          if [ -n "$missing_manifests" ]; then
+            echo "::error::Missing required beta manifests:$missing_manifests"
+            echo "::error::Auto-update will fail on affected platforms without these files!"
+            exit 1
+          fi
+
+          echo ""
+          echo "All required beta manifests present:"
+          echo "  - beta-mac.yml (macOS)"
+          echo "  - beta.yml (Windows)"
+          echo "  - beta-linux.yml (Linux)"
+
+      - name: Generate checksums
+        run: |
+          cd release-assets
+          sha256sum ./* > checksums.sha256
+          cat checksums.sha256
+
+      - name: Create Beta Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.create-tag.outputs.version }}
+          name: v${{ needs.create-tag.outputs.version }} (Beta)
+          body: |
+            ## Beta Release v${{ needs.create-tag.outputs.version }}
+
+            This is a **beta release** for testing new features. It may contain bugs or incomplete functionality.
+
+            ### How to opt-in to beta updates
+            1. Open Auto Claude
+            2. Go to Settings > Updates
+            3. Enable "Beta Updates" toggle
+
+            ### Reporting Issues
+            Please report any issues at https://github.com/AndyMik90/Auto-Claude/issues
+
+            ---
+
+            **Full Changelog**: https://github.com/${{ github.repository }}/compare/main...v${{ needs.create-tag.outputs.version }}
+          files: release-assets/*
+          draft: false
+          prerelease: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  dry-run-summary:
+    needs: [create-tag, finalize-notarization, build-windows, build-linux]
+    runs-on: ubuntu-latest
+    if: ${{ github.event.inputs.dry_run == 'true' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+
+      - name: Flatten binary artifacts
+        run: |
+          mkdir -p release-assets
+
+          # Copy stapled macOS DMGs (from finalize-notarization job)
+          find dist/macos-intel-stapled dist/macos-arm64-stapled -type f -name "*.dmg" -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Copy other macOS artifacts (zip, yml, blockmap for delta updates) from original build
+          find dist/macos-intel-builds dist/macos-arm64-builds -type f \( -name "*.zip" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Copy Windows and Linux artifacts (including blockmap for delta updates)
+          find dist/windows-builds dist/linux-builds -type f \( -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+      # Merge macOS manifests (same logic as real release)
+      - name: Merge macOS manifests
+        uses: ./.github/actions/merge-macos-manifests
+        with:
+          dist-path: dist
+          output-path: release-assets
+          copy-other-manifests: 'true'
+
+      - name: Validate and rename beta manifests
+        run: |
+          cd release-assets
+
+          # Rename latest*.yml to beta*.yml
+          [ -f "latest.yml" ] && mv latest.yml beta.yml
+          [ -f "latest-mac.yml" ] && mv latest-mac.yml beta-mac.yml
+          [ -f "latest-linux.yml" ] && mv latest-linux.yml beta-linux.yml
+          [ -f "latest-linux-arm64.yml" ] && mv latest-linux-arm64.yml beta-linux-arm64.yml
+
+          # Validate required manifests
+          missing=""
+          [ ! -f "beta-mac.yml" ] && missing="$missing beta-mac.yml"
+          [ ! -f "beta.yml" ] && missing="$missing beta.yml"
+          [ ! -f "beta-linux.yml" ] && missing="$missing beta-linux.yml"
+
+          if [ -n "$missing" ]; then
+            echo "::warning::DRY RUN: Missing required beta manifests:$missing"
+            echo "MANIFEST_STATUS=FAILED" >> $GITHUB_ENV
+          else
+            echo "MANIFEST_STATUS=PASSED" >> $GITHUB_ENV
+
+            # Show merged manifest content for verification
+            echo ""
+            echo "=== beta-mac.yml content (should have both architectures) ==="
+            cat beta-mac.yml
+          fi
+
+      - name: Dry run summary
+        run: |
+          echo "## Beta Release Dry Run Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Version:** ${{ needs.create-tag.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          echo "### Build Artifacts" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          find dist -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          echo "### Update Manifests (Required for Auto-Update)" >> $GITHUB_STEP_SUMMARY
+          if [ "$MANIFEST_STATUS" = "PASSED" ]; then
+            echo "All required beta manifests present:" >> $GITHUB_STEP_SUMMARY
+            echo "- beta-mac.yml (macOS)" >> $GITHUB_STEP_SUMMARY
+            echo "- beta.yml (Windows)" >> $GITHUB_STEP_SUMMARY
+            echo "- beta-linux.yml (Linux)" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "**WARNING: Missing required manifests! Auto-update will fail.**" >> $GITHUB_STEP_SUMMARY
+            echo "Check build logs for details." >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          echo "To create a real release, run this workflow again with dry_run unchecked." >> $GITHUB_STEP_SUMMARY

.github/workflows/build-prebuilds.yml

@@ -0,0 +1,127 @@
+name: Build Native Module Prebuilds
+
+on:
+  # Build on releases
+  release:
+    types: [published]
+  # Manual trigger for testing
+  workflow_dispatch:
+    inputs:
+      electron_version:
+        description: 'Electron version to build for'
+        required: false
+        default: '39.2.6'
+
+env:
+  # Default Electron version - update when upgrading Electron in package.json
+  ELECTRON_VERSION: ${{ github.event.inputs.electron_version || '39.2.6' }}
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        arch: [x64]
+        # Add arm64 when GitHub Actions supports Windows ARM runners
+        # arch: [x64, arm64]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Install Visual Studio Build Tools
+        uses: microsoft/setup-msbuild@v2
+
+      - name: Install node-pty and rebuild for Electron
+        working-directory: apps/frontend
+        shell: pwsh
+        run: |
+          # Install only node-pty
+          npm install node-pty@1.1.0-beta42
+
+          # Get Electron ABI version
+          $electronAbi = (npx electron-abi $env:ELECTRON_VERSION)
+          Write-Host "Building for Electron $env:ELECTRON_VERSION (ABI: $electronAbi)"
+
+          # Rebuild node-pty for Electron
+          npx @electron/rebuild --version $env:ELECTRON_VERSION --module-dir node_modules/node-pty --arch ${{ matrix.arch }}
+
+      - name: Package prebuilt binaries
+        working-directory: apps/frontend
+        shell: pwsh
+        run: |
+          $electronAbi = (npx electron-abi $env:ELECTRON_VERSION)
+          $prebuildDir = "prebuilds/win32-${{ matrix.arch }}-electron-$electronAbi"
+
+          New-Item -ItemType Directory -Force -Path $prebuildDir
+
+          # Copy all built native files
+          $buildDir = "node_modules/node-pty/build/Release"
+          if (Test-Path $buildDir) {
+            Copy-Item "$buildDir/*.node" $prebuildDir/ -Force
+            Copy-Item "$buildDir/*.dll" $prebuildDir/ -Force -ErrorAction SilentlyContinue
+            Copy-Item "$buildDir/*.exe" $prebuildDir/ -Force -ErrorAction SilentlyContinue
+
+            # Also copy conpty files if they exist in subdirectory
+            if (Test-Path "$buildDir/conpty") {
+              Copy-Item "$buildDir/conpty/*" $prebuildDir/ -Force
+            }
+          }
+
+          # List what we packaged
+          Write-Host "Packaged prebuilds:"
+          Get-ChildItem $prebuildDir
+
+      - name: Create archive
+        working-directory: apps/frontend
+        shell: pwsh
+        run: |
+          $electronAbi = (npx electron-abi $env:ELECTRON_VERSION)
+          $archiveName = "node-pty-win32-${{ matrix.arch }}-electron-$electronAbi.zip"
+
+          Compress-Archive -Path "prebuilds/*" -DestinationPath $archiveName
+
+          Write-Host "Created archive: $archiveName"
+          Get-ChildItem $archiveName
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: node-pty-win32-${{ matrix.arch }}
+          path: apps/frontend/node-pty-*.zip
+          retention-days: 90
+
+      - name: Upload to release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v1
+        with:
+          files: apps/frontend/node-pty-*.zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Create a combined prebuilds package
+  package-prebuilds:
+    needs: build-windows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: List artifacts
+        run: |
+          echo "Downloaded artifacts:"
+          find artifacts -type f -name "*.zip"
+
+      - name: Upload combined artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: node-pty-prebuilds-all
+          path: artifacts/**/*.zip
+          retention-days: 90

.github/workflows/ci.yml

@@ -1,83 +1,165 @@
+# Cross-Platform CI Pipeline
+#
+# Tests on all target platforms (Linux, Windows, macOS) to catch
+# platform-specific bugs before they merge. ALL platforms must pass.
+#
+# Optimized: Reduced matrix (4 jobs vs 6), merged integration tests,
+# coverage on Linux only, path filters to skip on docs-only changes.
+
 name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - 'package*.json'
+      - 'requirements*.txt'
+      - 'pyproject.toml'
+      - 'tsconfig*.json'
+      - 'biome.jsonc'
+      - '.github/workflows/ci.yml'
+      - '.github/actions/**'
   pull_request:
-    branches: [main]
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - 'package*.json'
+      - 'requirements*.txt'
+      - 'pyproject.toml'
+      - 'tsconfig*.json'
+      - 'biome.jsonc'
+      - '.github/workflows/ci.yml'
+      - '.github/actions/**'
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  actions: read
 
 jobs:
-  # Python tests
+  # --------------------------------------------------------------------------
+  # Python Backend Tests - Optimized Matrix (4 jobs instead of 6)
+  # --------------------------------------------------------------------------
   test-python:
-    runs-on: ubuntu-latest
+    name: test-python (${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ['3.12', '3.13']
+        # 3.12 on all OS for cross-platform coverage
+        # 3.13 on Linux only for compatibility check (saves 2 jobs)
+        include:
+          - os: ubuntu-latest
+            python-version: '3.12'
+          - os: ubuntu-latest
+            python-version: '3.13'
+          - os: windows-latest
+            python-version: '3.12'
+          - os: macos-latest
+            python-version: '3.12'
 
     steps:
-      - name: Checkout
+      - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: Setup Python backend
+        uses: ./.github/actions/setup-python-backend
         with:
           python-version: ${{ matrix.python-version }}
+          install-test-deps: 'true'
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: "latest"
-
-      - name: Install dependencies
-        working-directory: auto-claude
+      - name: Run all tests (including platform-specific)
+        working-directory: apps/backend
+        shell: bash
+        env:
+          PYTHONPATH: ${{ github.workspace }}/apps/backend
         run: |
-          uv venv
-          uv pip install -r requirements.txt
-          uv pip install -r ../tests/requirements-test.txt
+          if [ "$RUNNER_OS" == "Windows" ]; then
+            source .venv/Scripts/activate
+          else
+            source .venv/bin/activate
+          fi
+          pytest ../../tests/ -v --tb=short -x
 
-      - name: Run tests
-        working-directory: auto-claude
+      - name: Run coverage (Linux + Python 3.12 only)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        working-directory: apps/backend
+        shell: bash
+        env:
+          PYTHONPATH: ${{ github.workspace }}/apps/backend
         run: |
           source .venv/bin/activate
-          pytest ../tests/ -v --tb=short -x
+          pytest ../../tests/ -v --cov=. --cov-report=xml --cov-report=term-missing --cov-fail-under=10
 
-      - name: Run tests with coverage
-        if: matrix.python-version == '3.12'
-        working-directory: auto-claude
-        run: |
-          source .venv/bin/activate
-          pytest ../tests/ -v --cov=. --cov-report=xml --cov-report=term-missing
-
-      - name: Upload coverage reports
-        if: matrix.python-version == '3.12'
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
         uses: codecov/codecov-action@v4
         with:
-          file: ./auto-claude/coverage.xml
+          file: ./apps/backend/coverage.xml
           fail_ci_if_error: false
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
-  # Frontend tests
+  # --------------------------------------------------------------------------
+  # Frontend Tests - All Platforms
+  # --------------------------------------------------------------------------
   test-frontend:
-    runs-on: ubuntu-latest
+    name: test-frontend (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
     steps:
-      - name: Checkout
+      - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Setup Node.js frontend
+        uses: ./.github/actions/setup-node-frontend
         with:
-          node-version: '20'
+          ignore-scripts: 'true'
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+      - name: Run TypeScript type check
+        working-directory: apps/frontend
+        run: npm run typecheck
 
-      - name: Install dependencies
-        working-directory: auto-claude-ui
-        run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Run unit tests
+        working-directory: apps/frontend
+        run: npm run test
 
-      - name: Run tests
-        working-directory: auto-claude-ui
-        run: pnpm test
+      - name: Build application
+        working-directory: apps/frontend
+        run: npm run build
+
+  # --------------------------------------------------------------------------
+  # Gate Job - Single check for branch protection
+  # --------------------------------------------------------------------------
+  ci-complete:
+    name: CI Complete
+    runs-on: ubuntu-latest
+    needs: [test-python, test-frontend]
+    if: always()
+    steps:
+      - name: Check all CI jobs passed
+        run: |
+          echo "CI Job Results:"
+          echo "  test-python:   ${{ needs.test-python.result }}"
+          echo "  test-frontend: ${{ needs.test-frontend.result }}"
+          echo ""
+
+          if [[ "${{ needs.test-python.result }}" != "success" ]] || \
+             [[ "${{ needs.test-frontend.result }}" != "success" ]]; then
+            echo "❌ One or more CI jobs failed"
+            exit 1
+          fi
+
+          echo "✅ All CI checks passed"

.github/workflows/discord-release.yml

@@ -22,4 +22,3 @@ jobs:
           footer_timestamp: true
           reduce_headings: true
           remove_github_reference_links: true
-

.github/workflows/issue-auto-label.yml

@@ -0,0 +1,53 @@
+name: Issue Auto Label
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  label-area:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Add area label from form
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const body = issue.body || '';
+
+            console.log(`Processing issue #${issue.number}: ${issue.title}`);
+
+            // Map form selection to label
+            const areaMap = {
+              'Frontend': 'area/frontend',
+              'Backend': 'area/backend',
+              'Fullstack': 'area/fullstack'
+            };
+
+            const labels = [];
+
+            for (const [key, label] of Object.entries(areaMap)) {
+              if (body.includes(key)) {
+                console.log(`Found area: ${key}, adding label: ${label}`);
+                labels.push(label);
+                break;
+              }
+            }
+
+            if (labels.length > 0) {
+              try {
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue.number,
+                  labels: labels
+                });
+                console.log(`Successfully added labels: ${labels.join(', ')}`);
+              } catch (error) {
+                core.setFailed(`Failed to add labels: ${error.message}`);
+              }
+            } else {
+              console.log('No matching area found in issue body');
+            }

.github/workflows/lint.yml

@@ -2,13 +2,32 @@ name: Lint
 
 on:
   push:
-    branches: [main]
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - '.github/workflows/lint.yml'
+      - '.github/actions/**'
+      - 'apps/frontend/biome.jsonc'
+      - '.pre-commit-config.yaml'
   pull_request:
-    branches: [main]
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - '.github/workflows/lint.yml'
+      - '.github/actions/**'
+      - 'apps/frontend/biome.jsonc'
+      - '.pre-commit-config.yaml'
+
+concurrency:
+  group: lint-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  # Python linting
+  # Python linting (Ruff) - already fast, no changes needed
   python:
+    name: Python (Ruff)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -19,40 +38,52 @@ jobs:
         with:
           python-version: '3.12'
 
+      # Pin ruff version to match .pre-commit-config.yaml
       - name: Install ruff
-        run: pip install ruff
+        run: pip install ruff==0.14.10
 
       - name: Run ruff check
-        run: ruff check auto-claude/ --output-format=github
+        run: ruff check apps/backend/ --output-format=github
 
       - name: Run ruff format check
-        run: ruff format auto-claude/ --check --diff
+        run: ruff format apps/backend/ --check --diff
 
-  # TypeScript/React linting
-  frontend:
+  # TypeScript/JavaScript linting (Biome) - 15-25x faster than ESLint
+  typescript:
+    name: TypeScript (Biome)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      # Pin version to match package.json for consistent behavior
+      - name: Setup Biome
+        uses: biomejs/setup-biome@v2
         with:
-          node-version: '20'
+          version: 2.3.11
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+      - name: Run Biome
+        working-directory: apps/frontend
+        # biome ci fails on errors by default; warnings are reported but don't block
+        # Use --error-on-warnings when ready to enforce all rules
+        run: biome ci .
 
-      - name: Install dependencies
-        working-directory: auto-claude-ui
-        run: pnpm install --frozen-lockfile --ignore-scripts
-
-      - name: Run ESLint
-        working-directory: auto-claude-ui
-        run: pnpm lint
-
-      - name: Run TypeScript check
-        working-directory: auto-claude-ui
-        run: pnpm typecheck
+  # --------------------------------------------------------------------------
+  # Gate Job - Single check for branch protection
+  # --------------------------------------------------------------------------
+  lint-complete:
+    name: Lint Complete
+    runs-on: ubuntu-latest
+    needs: [python, typescript]
+    if: always()
+    steps:
+      - name: Check lint results
+        run: |
+          if [[ "${{ needs.python.result }}" != "success" ]] || \
+             [[ "${{ needs.typescript.result }}" != "success" ]]; then
+            echo "❌ Linting failed"
+            echo "  Python:     ${{ needs.python.result }}"
+            echo "  TypeScript: ${{ needs.typescript.result }}"
+            exit 1
+          fi
+          echo "✅ All linting passed"

.github/workflows/pr-labeler.yml

@@ -0,0 +1,299 @@
+name: PR Labeler
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: pr-labeler-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    name: Auto Label PR
+    runs-on: ubuntu-latest
+    # Security: Prevent fork PRs from modifying labels (they don't have write access)
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    timeout-minutes: 5
+
+    steps:
+      - name: Label PR
+        uses: actions/github-script@v7
+        with:
+          retries: 3
+          retry-exempt-status-codes: 400,401,403,404,422
+          script: |
+            // ═══════════════════════════════════════════════════════════════
+            // CONFIGURATION - Single source of truth for all settings
+            // ═══════════════════════════════════════════════════════════════
+
+            const CONFIG = {
+              // Size thresholds (lines changed)
+              SIZE_THRESHOLDS: {
+                XS: 10,
+                S: 100,
+                M: 500,
+                L: 1000
+              },
+
+              // Conventional commit type mappings
+              TYPE_MAP: Object.freeze({
+                'feat': 'feature',
+                'fix': 'bug',
+                'docs': 'documentation',
+                'refactor': 'refactor',
+                'test': 'test',
+                'ci': 'ci',
+                'chore': 'chore',
+                'perf': 'performance',
+                'style': 'style',
+                'build': 'build'
+              }),
+
+              // Area detection paths
+              AREA_PATHS: Object.freeze({
+                frontend: 'apps/frontend/',
+                backend: 'apps/backend/',
+                ci: '.github/'
+              }),
+
+              // Label definitions
+              LABELS: Object.freeze({
+                SIZE: ['size/XS', 'size/S', 'size/M', 'size/L', 'size/XL'],
+                AREA: ['area/frontend', 'area/backend', 'area/fullstack', 'area/ci']
+              }),
+
+              // Pagination
+              MAX_FILES_PER_PAGE: 100
+            };
+
+            // ═══════════════════════════════════════════════════════════════
+            // HELPER FUNCTIONS - Small, focused, single responsibility
+            // ═══════════════════════════════════════════════════════════════
+
+            /**
+             * Safely parse conventional commit type from PR title
+             * @param {string} title - PR title
+             * @returns {{type: string|null, isBreaking: boolean}}
+             */
+            function parseConventionalCommit(title) {
+              if (!title || typeof title !== 'string') {
+                return { type: null, isBreaking: false };
+              }
+
+              // Limit input length to prevent ReDoS attacks
+              const safeTitle = title.slice(0, 200);
+              const match = safeTitle.match(/^(\w{1,20})(\([^)]{0,50}\))?(!)?:/);
+
+              if (!match) {
+                return { type: null, isBreaking: false };
+              }
+
+              return {
+                type: match[1].toLowerCase(),
+                isBreaking: match[3] === '!'
+              };
+            }
+
+            /**
+             * Determine size label based on lines changed
+             * @param {number} totalLines - Total lines changed
+             * @returns {string} Size label
+             */
+            function determineSizeLabel(totalLines) {
+              const { SIZE_THRESHOLDS } = CONFIG;
+
+              if (totalLines < SIZE_THRESHOLDS.XS) return 'size/XS';
+              if (totalLines < SIZE_THRESHOLDS.S) return 'size/S';
+              if (totalLines < SIZE_THRESHOLDS.M) return 'size/M';
+              if (totalLines < SIZE_THRESHOLDS.L) return 'size/L';
+              return 'size/XL';
+            }
+
+            /**
+             * Detect areas affected by file changes
+             * @param {Array} files - List of changed files
+             * @returns {{frontend: boolean, backend: boolean, ci: boolean}}
+             */
+            function detectAreas(files) {
+              const areas = { frontend: false, backend: false, ci: false };
+              const { AREA_PATHS } = CONFIG;
+
+              for (const file of files) {
+                const path = file.filename || '';
+                if (path.startsWith(AREA_PATHS.frontend)) areas.frontend = true;
+                if (path.startsWith(AREA_PATHS.backend)) areas.backend = true;
+                if (path.startsWith(AREA_PATHS.ci)) areas.ci = true;
+              }
+
+              return areas;
+            }
+
+            /**
+             * Determine area label based on detected areas
+             * @param {{frontend: boolean, backend: boolean, ci: boolean}} areas
+             * @returns {string|null} Area label or null
+             */
+            function determineAreaLabel(areas) {
+              if (areas.frontend && areas.backend) return 'area/fullstack';
+              if (areas.frontend) return 'area/frontend';
+              if (areas.backend) return 'area/backend';
+              if (areas.ci) return 'area/ci';
+              return null;
+            }
+
+            /**
+             * Remove labels from PR (with error handling)
+             * @param {Array} labels - Labels to remove
+             * @param {number} prNumber - PR number
+             */
+            async function removeLabels(labels, prNumber) {
+              const { owner, repo } = context.repo;
+
+              await Promise.allSettled(labels.map(async (label) => {
+                try {
+                  await github.rest.issues.removeLabel({
+                    owner,
+                    repo,
+                    issue_number: prNumber,
+                    name: label
+                  });
+                  console.log(`  ✓ Removed: ${label}`);
+                } catch (e) {
+                  // 404 means label wasn't present - that's fine
+                  if (e.status !== 404) {
+                    console.log(`  ⚠ Failed to remove ${label}: ${e.message}`);
+                  }
+                }
+              }));
+            }
+
+            /**
+             * Add labels to PR (with error handling)
+             * @param {Array} labels - Labels to add
+             * @param {number} prNumber - PR number
+             */
+            async function addLabels(labels, prNumber) {
+              if (labels.length === 0) return;
+
+              const { owner, repo } = context.repo;
+
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: prNumber,
+                  labels
+                });
+                console.log(`  ✓ Added: ${labels.join(', ')}`);
+              } catch (e) {
+                if (e.status === 404) {
+                  core.warning(`One or more labels do not exist. Create them in repository settings.`);
+                } else {
+                  throw e;
+                }
+              }
+            }
+
+            /**
+             * Fetch PR files with full pagination support
+             * @param {number} prNumber - PR number
+             * @returns {Array} List of all files (paginated)
+             */
+            async function fetchPRFiles(prNumber) {
+              const { owner, repo } = context.repo;
+
+              try {
+                // Use paginate to fetch ALL files, not just first 100
+                const files = await github.paginate(
+                  github.rest.pulls.listFiles,
+                  { owner, repo, pull_number: prNumber, per_page: CONFIG.MAX_FILES_PER_PAGE }
+                );
+                return files;
+              } catch (e) {
+                console.log(`  ⚠ Could not fetch files: ${e.message}`);
+                return [];
+              }
+            }
+
+            // ═══════════════════════════════════════════════════════════════
+            // MAIN LOGIC - Orchestrates the labeling process
+            // ═══════════════════════════════════════════════════════════════
+
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const prNumber = pr.number;
+            const title = pr.title || '';
+
+            console.log(`::group::PR #${prNumber} - Auto-labeling`);
+            console.log(`Title: ${title.slice(0, 100)}${title.length > 100 ? '...' : ''}`);
+            console.log(`Action: ${context.payload.action}`);
+
+            const labelsToAdd = new Set();
+            const labelsToRemove = new Set();
+
+            // 1. Parse conventional commit type
+            const { type, isBreaking } = parseConventionalCommit(title);
+            if (type && CONFIG.TYPE_MAP[type]) {
+              labelsToAdd.add(CONFIG.TYPE_MAP[type]);
+              console.log(`  📝 Type: ${type} → ${CONFIG.TYPE_MAP[type]}`);
+            } else {
+              console.log(`  ℹ️ No conventional commit prefix detected`);
+            }
+
+            if (isBreaking) {
+              labelsToAdd.add('breaking-change');
+              console.log(`  ⚠️ Breaking change detected`);
+            }
+
+            // 2. Detect areas from changed files
+            const files = await fetchPRFiles(prNumber);
+            const areas = detectAreas(files);
+            const areaLabel = determineAreaLabel(areas);
+
+            if (areaLabel) {
+              labelsToAdd.add(areaLabel);
+              CONFIG.LABELS.AREA.filter(l => l !== areaLabel).forEach(l => labelsToRemove.add(l));
+              console.log(`  📁 Area: ${areaLabel.replace('area/', '')}`);
+            }
+
+            // 3. Calculate size label
+            const totalLines = (pr.additions || 0) + (pr.deletions || 0);
+            const sizeLabel = determineSizeLabel(totalLines);
+            labelsToAdd.add(sizeLabel);
+            CONFIG.LABELS.SIZE.filter(l => l !== sizeLabel).forEach(l => labelsToRemove.add(l));
+            console.log(`  📏 Size: ${sizeLabel} (${totalLines} lines)`);
+
+            console.log('::endgroup::');
+
+            // 4. Apply label changes
+            console.log(`::group::Applying labels`);
+
+            // Remove labels that should be replaced (exclude ones we're adding)
+            const removeList = [...labelsToRemove].filter(l => !labelsToAdd.has(l));
+            await removeLabels(removeList, prNumber);
+
+            // Add new labels
+            await addLabels([...labelsToAdd], prNumber);
+
+            console.log('::endgroup::');
+            console.log(`✅ PR #${prNumber} labeled successfully`);
+
+            // 5. Write job summary
+            const summaryType = type ? CONFIG.TYPE_MAP[type] || 'unknown' : 'none';
+            const summaryArea = areaLabel ? areaLabel.replace('area/', '') : 'other';
+
+            await core.summary
+              .addHeading(`PR #${prNumber} Auto-Labels`, 3)
+              .addTable([
+                [{ data: 'Category', header: true }, { data: 'Label', header: true }],
+                ['Type', summaryType],
+                ['Area', summaryArea],
+                ['Size', sizeLabel]
+              ])
+              .addRaw(`\n**Files:** ${files.length} | **Lines:** +${pr.additions || 0} / -${pr.deletions || 0}\n`)
+              .write();

.github/workflows/prepare-release.yml

@@ -0,0 +1,251 @@
+name: Prepare Release
+
+# Triggers when code is pushed to main (e.g., merging develop → main)
+# If package.json version is newer than the latest tag:
+# 1. Validates CHANGELOG.md has an entry for this version (FAILS if missing)
+# 2. Extracts release notes from CHANGELOG.md
+# 3. Creates a new tag which triggers release.yml
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/frontend/package.json'
+      - 'package.json'
+  workflow_dispatch:
+    inputs:
+      force:
+        description: 'Force release even if version check fails (use with caution)'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  check-and-tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      should_release: ${{ steps.check.outputs.should_release }}
+      new_version: ${{ steps.check.outputs.new_version }}
+    steps:
+      # Fail fast with clear error if PAT_TOKEN is not configured
+      - name: Validate PAT_TOKEN is configured
+        run: |
+          if [ -z "${{ secrets.PAT_TOKEN }}" ]; then
+            echo "::error::PAT_TOKEN secret is not configured."
+            echo "::error::This secret is required for automatic release triggering."
+            echo "::error::See https://github.com/AndyMik90/Auto-Claude/pull/1043 for setup instructions."
+            exit 1
+          fi
+
+      # IMPORTANT: Use PAT_TOKEN instead of GITHUB_TOKEN
+      # When GITHUB_TOKEN pushes a tag, it does NOT trigger other workflows (GitHub security feature)
+      # PAT_TOKEN allows the tag push to trigger release.yml automatically
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.PAT_TOKEN }}
+
+      - name: Get package version
+        id: package
+        run: |
+          VERSION=$(node -p "require('./apps/frontend/package.json').version")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Package version: $VERSION"
+
+      - name: Get latest tag version
+        id: latest_tag
+        run: |
+          # Get the latest version tag (v*)
+          LATEST_TAG=$(git tag -l 'v*' --sort=-version:refname | head -n1)
+          if [ -z "$LATEST_TAG" ]; then
+            echo "No existing tags found"
+            echo "version=0.0.0" >> $GITHUB_OUTPUT
+          else
+            # Remove 'v' prefix
+            LATEST_VERSION=${LATEST_TAG#v}
+            echo "version=$LATEST_VERSION" >> $GITHUB_OUTPUT
+            echo "Latest tag: $LATEST_TAG (version: $LATEST_VERSION)"
+          fi
+
+      - name: Check if release needed
+        id: check
+        run: |
+          PACKAGE_VERSION="${{ steps.package.outputs.version }}"
+          LATEST_VERSION="${{ steps.latest_tag.outputs.version }}"
+          FORCE="${{ github.event.inputs.force }}"
+
+          echo "Comparing: package=$PACKAGE_VERSION vs latest_tag=$LATEST_VERSION"
+
+          # Use npx semver for proper semantic version comparison
+          # This correctly handles pre-release versions (2.7.3 > 2.7.3-beta.1)
+          if npx -y semver "$PACKAGE_VERSION" -r ">$LATEST_VERSION" > /dev/null 2>&1; then
+            echo "should_release=true" >> $GITHUB_OUTPUT
+            echo "new_version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
+            echo "✅ New release needed: v$PACKAGE_VERSION"
+          elif [ "$FORCE" = "true" ]; then
+            echo "should_release=true" >> $GITHUB_OUTPUT
+            echo "new_version=$PACKAGE_VERSION" >> $GITHUB_OUTPUT
+            echo "⚠️ Force release enabled: v$PACKAGE_VERSION"
+          else
+            echo "should_release=false" >> $GITHUB_OUTPUT
+            echo "⏭️ No release needed (package version not newer than latest tag)"
+          fi
+
+      # CRITICAL: Validate CHANGELOG.md has entry for this version BEFORE creating tag
+      - name: Validate and extract changelog
+        if: steps.check.outputs.should_release == 'true'
+        id: changelog
+        run: |
+          VERSION="${{ steps.check.outputs.new_version }}"
+          CHANGELOG_FILE="CHANGELOG.md"
+
+          echo "🔍 Validating CHANGELOG.md for version $VERSION..."
+
+          if [ ! -f "$CHANGELOG_FILE" ]; then
+            echo "::error::CHANGELOG.md not found! Please create CHANGELOG.md with release notes."
+            exit 1
+          fi
+
+          # Extract changelog section for this version
+          # Looks for "## X.Y.Z" header and captures until next "## " or "---" or end
+          CHANGELOG_CONTENT=$(awk -v ver="$VERSION" '
+            BEGIN { found=0; content="" }
+            /^## / {
+              if (found) exit
+              # Match version at start of header (e.g., "## 2.7.3 -" or "## 2.7.3")
+              if ($2 == ver || $2 ~ "^"ver"[[:space:]]*-") {
+                found=1
+                # Skip the header line itself, we will add our own
+                next
+              }
+            }
+            /^---$/ { if (found) exit }
+            found { content = content $0 "\n" }
+            END {
+              if (!found) {
+                print "NOT_FOUND"
+                exit 1
+              }
+              # Trim leading/trailing whitespace
+              gsub(/^[[:space:]]+|[[:space:]]+$/, "", content)
+              print content
+            }
+          ' "$CHANGELOG_FILE")
+
+          if [ "$CHANGELOG_CONTENT" = "NOT_FOUND" ] || [ -z "$CHANGELOG_CONTENT" ]; then
+            echo ""
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo "::error::  CHANGELOG VALIDATION FAILED"
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo "::error::"
+            echo "::error::  Version $VERSION not found in CHANGELOG.md!"
+            echo "::error::"
+            echo "::error::  Before releasing, please update CHANGELOG.md with an entry like:"
+            echo "::error::"
+            echo "::error::    ## $VERSION - Your Release Title"
+            echo "::error::"
+            echo "::error::    ### ✨ New Features"
+            echo "::error::    - Feature description"
+            echo "::error::"
+            echo "::error::    ### 🐛 Bug Fixes"
+            echo "::error::    - Fix description"
+            echo "::error::"
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo ""
+
+            # Also add to job summary for visibility
+            echo "## ❌ Release Blocked: Missing Changelog" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Version **$VERSION** was not found in CHANGELOG.md." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### How to fix:" >> $GITHUB_STEP_SUMMARY
+            echo "1. Update CHANGELOG.md with release notes for version $VERSION" >> $GITHUB_STEP_SUMMARY
+            echo "2. Commit and push the changes" >> $GITHUB_STEP_SUMMARY
+            echo "3. The release will automatically retry" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Expected format:" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`markdown" >> $GITHUB_STEP_SUMMARY
+            echo "## $VERSION - Release Title" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### ✨ New Features" >> $GITHUB_STEP_SUMMARY
+            echo "- Feature description" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### 🐛 Bug Fixes" >> $GITHUB_STEP_SUMMARY
+            echo "- Fix description" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+            exit 1
+          fi
+
+          echo "✅ Found changelog entry for version $VERSION"
+          echo ""
+          echo "--- Extracted Release Notes ---"
+          echo "$CHANGELOG_CONTENT"
+          echo "--- End Release Notes ---"
+
+          # Save changelog to file for artifact upload
+          echo "$CHANGELOG_CONTENT" > changelog-extract.md
+
+          # Also save to output (for short changelogs)
+          # Using heredoc for multiline output
+          {
+            echo "content<<CHANGELOG_EOF"
+            echo "$CHANGELOG_CONTENT"
+            echo "CHANGELOG_EOF"
+          } >> $GITHUB_OUTPUT
+
+          echo "changelog_valid=true" >> $GITHUB_OUTPUT
+
+      # Upload changelog as artifact for release.yml to use
+      - name: Upload changelog artifact
+        if: steps.check.outputs.should_release == 'true' && steps.changelog.outputs.changelog_valid == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: changelog-${{ steps.check.outputs.new_version }}
+          path: changelog-extract.md
+          retention-days: 1
+
+      - name: Create and push tag
+        if: steps.check.outputs.should_release == 'true' && steps.changelog.outputs.changelog_valid == 'true'
+        run: |
+          VERSION="${{ steps.check.outputs.new_version }}"
+          TAG="v$VERSION"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          echo "Creating tag: $TAG"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+          echo "✅ Tag $TAG created and pushed"
+          echo "🚀 This will trigger the release workflow"
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.check.outputs.should_release }}" = "true" ] && [ "${{ steps.changelog.outputs.changelog_valid }}" = "true" ]; then
+            echo "## 🚀 Release Triggered" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "**Version:** v${{ steps.check.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "✅ Changelog validated and extracted from CHANGELOG.md" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The release workflow has been triggered and will:" >> $GITHUB_STEP_SUMMARY
+            echo "1. Build binaries for all platforms" >> $GITHUB_STEP_SUMMARY
+            echo "2. Use changelog from CHANGELOG.md" >> $GITHUB_STEP_SUMMARY
+            echo "3. Create GitHub release" >> $GITHUB_STEP_SUMMARY
+            echo "4. Update README with new version" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ steps.check.outputs.should_release }}" = "false" ]; then
+            echo "## ⏭️ No Release Needed" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "**Package version:** ${{ steps.package.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+            echo "**Latest tag:** v${{ steps.latest_tag.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The package version is not newer than the latest tag." >> $GITHUB_STEP_SUMMARY
+            echo "To trigger a release, bump the version using:" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+            echo "node scripts/bump-version.js patch  # or minor/major" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/quality-security.yml

@@ -0,0 +1,177 @@
+name: Quality Security
+
+# CodeQL runs on all PRs, pushes to main, and weekly schedule
+# Note: CodeQL takes 20-30 min per language (40-60 min total)
+# Bandit is fast (5-10 min)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'package.json'
+      - '.github/workflows/quality-security.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'package.json'
+      - '.github/workflows/quality-security.yml'
+  schedule:
+    - cron: '0 0 * * 1' # Weekly on Monday at midnight UTC
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  codeql:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, javascript-typescript]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-extended,security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"
+
+  # Bandit runs on all PRs - it's fast (5-10 min)
+  python-security:
+    name: Python Security (Bandit)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Bandit
+        run: pip install bandit
+
+      - name: Run Bandit security scan
+        id: bandit
+        run: |
+          echo "::group::Running Bandit security scan"
+          bandit -r apps/backend/ -ll -ii -f json -o bandit-report.json || BANDIT_EXIT=$?
+          if [ "${BANDIT_EXIT:-0}" -gt 1 ]; then
+            echo "::error::Bandit scan failed with exit code $BANDIT_EXIT"
+            exit 1
+          fi
+          echo "::endgroup::"
+
+      - name: Analyze Bandit results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            if (!fs.existsSync('bandit-report.json')) {
+              core.setFailed('Bandit report not found - scan may have failed');
+              return;
+            }
+
+            const report = JSON.parse(fs.readFileSync('bandit-report.json', 'utf8'));
+            const results = report.results || [];
+
+            const high = results.filter(r => r.issue_severity === 'HIGH');
+            const medium = results.filter(r => r.issue_severity === 'MEDIUM');
+            const low = results.filter(r => r.issue_severity === 'LOW');
+
+            console.log(`::group::Bandit Security Scan Results`);
+            console.log(`Found ${results.length} issues:`);
+            console.log(`  HIGH:   ${high.length}`);
+            console.log(`  MEDIUM: ${medium.length}`);
+            console.log(`  LOW:    ${low.length}`);
+            console.log('::endgroup::');
+
+            let summary = `## Python Security Scan (Bandit)\n\n`;
+            summary += `| Severity | Count |\n`;
+            summary += `|----------|-------|\n`;
+            summary += `| High | ${high.length} |\n`;
+            summary += `| Medium | ${medium.length} |\n`;
+            summary += `| Low | ${low.length} |\n\n`;
+
+            if (high.length > 0) {
+              summary += `### High Severity Issues\n\n`;
+              for (const issue of high) {
+                summary += `- **${issue.filename}:${issue.line_number}**\n`;
+                summary += `  - ${issue.issue_text}\n`;
+                summary += `  - Test: \`${issue.test_id}\` (${issue.test_name})\n\n`;
+              }
+            }
+
+            core.summary.addRaw(summary);
+            await core.summary.write();
+
+            if (high.length > 0) {
+              core.setFailed(`Found ${high.length} high severity security issue(s)`);
+            } else {
+              console.log('No high severity security issues found');
+            }
+
+  # --------------------------------------------------------------------------
+  # Gate Job - Single check for branch protection
+  # --------------------------------------------------------------------------
+  security-summary:
+    name: Security Summary
+    runs-on: ubuntu-latest
+    needs: [codeql, python-security]
+    if: always()
+    timeout-minutes: 5
+    steps:
+      - name: Check security results
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const codeql = '${{ needs.codeql.result }}';
+            const bandit = '${{ needs.python-security.result }}';
+
+            console.log('Security Check Results:');
+            console.log(`  CodeQL:        ${codeql}`);
+            console.log(`  Bandit:        ${bandit}`);
+
+            // Only 'failure' is a real failure; 'skipped' is acceptable (e.g., path filters, PR skipping CodeQL)
+            const acceptable = ['success', 'skipped'];
+            const codeqlOk = acceptable.includes(codeql);
+            const banditOk = acceptable.includes(bandit);
+            const allPassed = codeqlOk && banditOk;
+
+            if (allPassed) {
+              console.log('\n✅ All security checks passed');
+              core.summary.addRaw('## ✅ Security Checks Passed\n\nAll security scans completed successfully.');
+            } else {
+              console.log('\n❌ Some security checks failed');
+              core.summary.addRaw('## ❌ Security Checks Failed\n\nOne or more security scans found issues.');
+              core.setFailed('Security checks failed');
+            }
+
+            await core.summary.write();

.github/workflows/release.yml

@@ -0,0 +1,679 @@
+name: Release
+# Triggers on version tags (v*) to build and publish releases
+#
+# IMPORTANT: If branch protection is enabled on 'main', the update-readme job
+# requires a PAT or GitHub App token with bypass permissions to push directly.
+# Currently uses GITHUB_TOKEN which works if "Allow GitHub Actions to create
+# and approve pull requests" is enabled OR branch protection is not configured.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Test build without creating release'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  # Intel build on Intel runner for native compilation
+  # Note: macos-15-intel is the last Intel runner, supported until Fall 2027
+  build-macos-intel:
+    runs-on: macos-15-intel
+    outputs:
+      notarization_id: ${{ steps.notarize.outputs.notarization-id }}
+      dmg_file: ${{ steps.notarize.outputs.dmg-file }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Install Rust toolchain (for building native Python packages)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-rust-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package macOS (Intel)
+        run: cd apps/frontend && npm run package:mac -- --x64
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
+          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Submit notarization (async)
+        id: notarize
+        uses: ./.github/actions/submit-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-intel-builds
+          path: |
+            apps/frontend/dist/*.dmg
+            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap
+
+  # Apple Silicon build on ARM64 runner for native compilation
+  build-macos-arm64:
+    runs-on: macos-15
+    outputs:
+      notarization_id: ${{ steps.notarize.outputs.notarization-id }}
+      dmg_file: ${{ steps.notarize.outputs.dmg-file }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-arm64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-arm64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package macOS (Apple Silicon)
+        run: cd apps/frontend && npm run package:mac -- --arm64
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CSC_LINK: ${{ secrets.MAC_CERTIFICATE }}
+          CSC_KEY_PASSWORD: ${{ secrets.MAC_CERTIFICATE_PASSWORD }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Submit notarization (async)
+        id: notarize
+        uses: ./.github/actions/submit-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-arm64-builds
+          path: |
+            apps/frontend/dist/*.dmg
+            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap
+
+  build-windows:
+    runs-on: windows-latest
+    permissions:
+      id-token: write  # Required for OIDC authentication with Azure
+      contents: read
+    env:
+      # Job-level env so AZURE_CLIENT_ID is available for step-level if conditions
+      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~\AppData\Local\pip\Cache
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package Windows
+        run: cd apps/frontend && npm run package:win
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Disable electron-builder's built-in signing (we use Azure Trusted Signing instead)
+          CSC_IDENTITY_AUTO_DISCOVERY: false
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Azure Login (OIDC)
+        if: env.AZURE_CLIENT_ID != ''
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Sign Windows executable with Azure Trusted Signing
+        if: env.AZURE_CLIENT_ID != ''
+        uses: azure/trusted-signing-action@v0.5.11
+        with:
+          endpoint: https://neu.codesigning.azure.net/
+          trusted-signing-account-name: ${{ secrets.AZURE_SIGNING_ACCOUNT }}
+          certificate-profile-name: ${{ secrets.AZURE_CERTIFICATE_PROFILE }}
+          files-folder: apps/frontend/dist
+          files-folder-filter: exe
+          file-digest: SHA256
+          timestamp-rfc3161: http://timestamp.acs.microsoft.com
+          timestamp-digest: SHA256
+
+      - name: Verify Windows executable is signed
+        if: env.AZURE_CLIENT_ID != ''
+        shell: pwsh
+        run: |
+          cd apps/frontend/dist
+          $exeFile = Get-ChildItem -Filter "*.exe" | Select-Object -First 1
+          if ($exeFile) {
+            Write-Host "Verifying signature on $($exeFile.Name)..."
+            $sig = Get-AuthenticodeSignature -FilePath $exeFile.FullName
+            if ($sig.Status -ne 'Valid') {
+              Write-Host "::error::Signature verification failed: $($sig.Status)"
+              Write-Host "::error::Status Message: $($sig.StatusMessage)"
+              exit 1
+            }
+            Write-Host "✅ Signature verified successfully"
+            Write-Host "  Subject: $($sig.SignerCertificate.Subject)"
+            Write-Host "  Issuer: $($sig.SignerCertificate.Issuer)"
+            Write-Host "  Thumbprint: $($sig.SignerCertificate.Thumbprint)"
+          } else {
+            Write-Host "::error::No .exe file found to verify"
+            exit 1
+          }
+
+      - name: Regenerate checksums after signing
+        if: env.AZURE_CLIENT_ID != ''
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          cd apps/frontend/dist
+
+          # Find the installer exe (electron-builder names it with "Setup" or just the app name)
+          # electron-builder produces one installer exe per build
+          $exeFiles = Get-ChildItem -Filter "*.exe"
+          if ($exeFiles.Count -eq 0) {
+            Write-Host "::error::No .exe files found in dist folder"
+            exit 1
+          }
+
+          Write-Host "Found $($exeFiles.Count) exe file(s): $($exeFiles.Name -join ', ')"
+
+          $ymlFile = "latest.yml"
+          if (-not (Test-Path $ymlFile)) {
+            Write-Host "::error::$ymlFile not found - cannot update checksums"
+            exit 1
+          }
+
+          $content = Get-Content $ymlFile -Raw
+          $originalContent = $content
+
+          # Process each exe file and update its hash in latest.yml
+          foreach ($exeFile in $exeFiles) {
+            Write-Host "Processing $($exeFile.Name)..."
+
+            # Compute SHA512 hash and convert to base64 (electron-builder format)
+            $bytes = [System.IO.File]::ReadAllBytes($exeFile.FullName)
+            $sha512 = [System.Security.Cryptography.SHA512]::Create()
+            $hashBytes = $sha512.ComputeHash($bytes)
+            $hash = [System.Convert]::ToBase64String($hashBytes)
+            $size = $exeFile.Length
+
+            Write-Host "  Hash: $hash"
+            Write-Host "  Size: $size"
+          }
+
+          # For electron-builder, latest.yml has a single file entry for the installer
+          # Update the sha512 and size for the primary exe (first one, typically the installer)
+          $primaryExe = $exeFiles | Select-Object -First 1
+          $bytes = [System.IO.File]::ReadAllBytes($primaryExe.FullName)
+          $sha512 = [System.Security.Cryptography.SHA512]::Create()
+          $hashBytes = $sha512.ComputeHash($bytes)
+          $hash = [System.Convert]::ToBase64String($hashBytes)
+          $size = $primaryExe.Length
+
+          # Update sha512 hash (base64 pattern: alphanumeric, +, /, =)
+          $content = $content -replace 'sha512: [A-Za-z0-9+/=]+', "sha512: $hash"
+          # Update size
+          $content = $content -replace 'size: \d+', "size: $size"
+
+          if ($content -eq $originalContent) {
+            Write-Host "::error::Checksum replacement failed - content unchanged. Check if latest.yml format has changed."
+            exit 1
+          }
+
+          Set-Content -Path $ymlFile -Value $content -NoNewline
+          Write-Host "✅ Updated $ymlFile with new base64 hash and size for $($primaryExe.Name)"
+
+      - name: Skip signing notice
+        if: env.AZURE_CLIENT_ID == ''
+        run: echo "::warning::Windows signing skipped - AZURE_CLIENT_ID not configured. The .exe will be unsigned."
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-builds
+          path: |
+            apps/frontend/dist/*.exe
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap
+
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Setup Node.js and install dependencies
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Setup Flatpak
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y flatpak flatpak-builder
+          flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+          flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
+          flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08
+
+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
+      - name: Cache bundled Python
+        uses: actions/cache@v4
+        with:
+          path: apps/frontend/python-runtime
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            python-bundle-${{ runner.os }}-x64-3.12.8-
+
+      - name: Build application
+        run: cd apps/frontend && npm run build
+        env:
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Package Linux
+        run: cd apps/frontend && npm run package:linux
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
+          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-builds
+          path: |
+            apps/frontend/dist/*.AppImage
+            apps/frontend/dist/*.deb
+            apps/frontend/dist/*.flatpak
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap
+
+  # Finalize macOS notarization (runs in parallel with Windows/Linux builds)
+  finalize-notarization:
+    needs: [build-macos-intel, build-macos-arm64]
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Intel DMG
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-intel-builds
+          path: intel
+
+      - name: Download ARM64 DMG
+        uses: actions/download-artifact@v4
+        with:
+          name: macos-arm64-builds
+          path: arm64
+
+      - name: Wait for notarization and staple
+        uses: ./.github/actions/finalize-macos-notarization
+        with:
+          apple-id: ${{ secrets.APPLE_ID }}
+          apple-app-specific-password: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          apple-team-id: ${{ secrets.APPLE_TEAM_ID }}
+          intel-notarization-id: ${{ needs.build-macos-intel.outputs.notarization_id }}
+          arm64-notarization-id: ${{ needs.build-macos-arm64.outputs.notarization_id }}
+          intel-dmg-file: ${{ needs.build-macos-intel.outputs.dmg_file }}
+          arm64-dmg-file: ${{ needs.build-macos-arm64.outputs.dmg_file }}
+
+      - name: Upload stapled Intel DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-intel-stapled
+          path: intel/*.dmg
+
+      - name: Upload stapled ARM64 DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos-arm64-stapled
+          path: arm64/*.dmg
+
+  create-release:
+    needs: [build-macos-intel, build-macos-arm64, finalize-notarization, build-windows, build-linux]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+
+      - name: Flatten binary artifacts
+        run: |
+          mkdir -p release-assets
+
+          # Copy stapled macOS DMGs (from finalize-notarization job)
+          # Validate that stapled DMGs exist before copying
+          if ! find dist/macos-intel-stapled dist/macos-arm64-stapled -type f -name "*.dmg" 2>/dev/null | grep -q .; then
+            echo "::warning::No stapled DMGs found. Using un-stapled DMGs from build artifacts."
+            find dist/macos-intel-builds dist/macos-arm64-builds -type f -name "*.dmg" -exec cp {} release-assets/ \; 2>/dev/null || true
+          else
+            find dist/macos-intel-stapled dist/macos-arm64-stapled -type f -name "*.dmg" -exec cp {} release-assets/ \; 2>/dev/null || true
+          fi
+
+          # Copy other macOS artifacts (zip, yml, blockmap) from original build
+          find dist/macos-intel-builds dist/macos-arm64-builds -type f \( -name "*.zip" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Copy Windows and Linux artifacts
+          find dist/windows-builds dist/linux-builds -type f \( -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \; 2>/dev/null || true
+
+          # Validate that installer files exist
+          installer_count=$(find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) | wc -l)
+          if [ "$installer_count" -eq 0 ]; then
+            echo "::error::No installer artifacts found! Expected .dmg, .zip, .exe, .AppImage, .deb, or .flatpak files."
+            exit 1
+          fi
+
+          echo "Found $installer_count binary artifact(s):"
+          find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) -exec basename {} \;
+
+      # Merge macOS manifests from Intel and ARM64 builds
+      # See: https://github.com/electron-userland/electron-builder/issues/5592
+      - name: Merge macOS manifests
+        uses: ./.github/actions/merge-macos-manifests
+        with:
+          dist-path: dist
+          output-path: release-assets
+          copy-other-manifests: 'true'
+
+      - name: Validate manifests
+        run: |
+          # Validate that electron-updater manifest files are present (required for auto-updates)
+          yml_count=$(find release-assets -type f -name "*.yml" | wc -l)
+          if [ "$yml_count" -eq 0 ]; then
+            echo "::error::No update manifest (.yml) files found! Auto-update will not work."
+            exit 1
+          fi
+
+          echo "Found $yml_count manifest file(s):"
+          find release-assets -type f -name "*.yml" -exec basename {} \;
+
+          # Validate required manifests exist
+          missing=""
+          [ ! -f "release-assets/latest-mac.yml" ] && missing="$missing latest-mac.yml"
+          [ ! -f "release-assets/latest.yml" ] && missing="$missing latest.yml"
+          [ ! -f "release-assets/latest-linux.yml" ] && missing="$missing latest-linux.yml"
+
+          if [ -n "$missing" ]; then
+            echo "::error::Missing required manifests:$missing"
+            echo "::error::Auto-update will fail on affected platforms!"
+            exit 1
+          fi
+
+          echo ""
+          echo "All required manifests present:"
+          echo "  - latest-mac.yml (macOS)"
+          echo "  - latest.yml (Windows)"
+          echo "  - latest-linux.yml (Linux)"
+
+          echo ""
+          echo "All release assets:"
+          ls -la release-assets/
+
+      - name: Generate checksums
+        run: |
+          cd release-assets
+          sha256sum ./* > checksums.sha256
+          cat checksums.sha256
+
+      - name: Dry run summary
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+        run: |
+          echo "## Dry Run Complete" >> $GITHUB_STEP_SUMMARY
+          echo "Build artifacts created successfully:" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          ls -la release-assets/ >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "### Checksums" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          cat release-assets/checksums.sha256 >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+      - name: Extract changelog from CHANGELOG.md
+        if: ${{ github.event_name == 'push' }}
+        id: changelog
+        run: |
+          # Extract version from tag (v2.7.2 -> 2.7.2)
+          VERSION=${GITHUB_REF_NAME#v}
+          CHANGELOG_FILE="CHANGELOG.md"
+
+          echo "📋 Extracting release notes for version $VERSION from CHANGELOG.md..."
+
+          if [ ! -f "$CHANGELOG_FILE" ]; then
+            echo "::warning::CHANGELOG.md not found, using minimal release notes"
+            echo "body=Release v$VERSION" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Extract changelog section for this version
+          # Looks for "## X.Y.Z" header and captures until next "## " or "---"
+          CHANGELOG_CONTENT=$(awk -v ver="$VERSION" '
+            BEGIN { found=0; content="" }
+            /^## / {
+              if (found) exit
+              # Match version at start of header (e.g., "## 2.7.3 -" or "## 2.7.3")
+              if ($2 == ver || $2 ~ "^"ver"[[:space:]]*-") {
+                found=1
+                next
+              }
+            }
+            /^---$/ { if (found) exit }
+            found { content = content $0 "\n" }
+            END {
+              if (!found) {
+                print "NOT_FOUND"
+                exit 0
+              }
+              # Trim leading/trailing whitespace
+              gsub(/^[[:space:]]+|[[:space:]]+$/, "", content)
+              print content
+            }
+          ' "$CHANGELOG_FILE")
+
+          if [ "$CHANGELOG_CONTENT" = "NOT_FOUND" ] || [ -z "$CHANGELOG_CONTENT" ]; then
+            echo "::warning::Version $VERSION not found in CHANGELOG.md, using minimal release notes"
+            REPO="${{ github.repository }}"
+            CHANGELOG_CONTENT="Release v$VERSION"$'\n\n'"See [CHANGELOG.md](https://github.com/${REPO}/blob/main/CHANGELOG.md) for details."
+          fi
+
+          echo "✅ Extracted changelog content"
+
+          # Save to file first (more reliable for multiline)
+          echo "$CHANGELOG_CONTENT" > changelog-body.md
+
+          # Use file-based output for multiline content
+          {
+            echo "body<<CHANGELOG_EOF"
+            cat changelog-body.md
+            echo "CHANGELOG_EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: Create Release
+        if: ${{ github.event_name == 'push' }}
+        uses: softprops/action-gh-release@v2
+        with:
+          body: |
+            ${{ steps.changelog.outputs.body }}
+
+            ---
+
+            **Full Changelog**: https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md
+
+            _VirusTotal scan results will be added automatically after release._
+          files: release-assets/*
+          draft: false
+          prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'alpha') }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Update README with new version after successful release
+  update-readme:
+    needs: [create-release]
+    runs-on: ubuntu-latest
+    # Only update README on actual releases (tag push), not dry runs
+    if: ${{ github.event_name == 'push' }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version and detect release type
+        id: version
+        run: |
+          # Extract version from tag (v2.7.2 -> 2.7.2)
+          VERSION=${GITHUB_REF_NAME#v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+          # Detect if this is a prerelease (contains - after version, e.g., 2.7.2-beta.10)
+          if [[ "$VERSION" == *-* ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+            echo "Detected PRERELEASE: $VERSION"
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+            echo "Detected STABLE release: $VERSION"
+          fi
+
+      - name: Update README.md
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          IS_PRERELEASE="${{ steps.version.outputs.is_prerelease }}"
+
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            python3 scripts/update-readme.py "$VERSION" --prerelease
+          else
+            python3 scripts/update-readme.py "$VERSION"
+          fi
+
+          echo "--- Verifying update ---"
+          grep -E "(stable-|beta-|version-)[0-9]" README.md | head -5
+
+      - name: Commit and push README update
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Check if there are changes to commit
+          if git diff --quiet README.md; then
+            echo "No changes to README.md, skipping commit"
+            exit 0
+          fi
+
+          git add README.md
+          git commit -m "docs: update README to v${{ steps.version.outputs.version }} [skip ci]"
+          git push origin main

.github/workflows/stale.yml

@@ -0,0 +1,25 @@
+name: Stale Issues
+
+on:
+  schedule:
+    - cron: '0 0 * * 0'  # Every Sunday
+  workflow_dispatch:
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: |
+            This issue has been inactive for 60 days. It will be closed in 14 days if there's no activity.
+
+            - If this is still relevant, please comment or update the issue
+            - If you're working on this, add the `in-progress` label
+          close-issue-message: 'Closed due to inactivity. Feel free to reopen if still relevant.'
+          stale-issue-label: 'stale'
+          days-before-stale: 60
+          days-before-close: 14
+          exempt-issue-labels: 'priority/critical,priority/high,in-progress,blocked'

.github/workflows/test-azure-auth.yml

@@ -0,0 +1,21 @@
+name: Test Azure Auth
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test-auth:
+    runs-on: windows-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Azure Login (OIDC)
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Success
+        run: echo "Azure authentication successful!"

.github/workflows/test-on-tag.yml

@@ -1,66 +0,0 @@
-name: Test on Tag
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  # Python tests
-  test-python:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ['3.12', '3.13']
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: "latest"
-
-      - name: Install dependencies
-        working-directory: auto-claude
-        run: |
-          uv venv
-          uv pip install -r requirements.txt
-          uv pip install -r ../tests/requirements-test.txt
-
-      - name: Run tests
-        working-directory: auto-claude
-        run: |
-          source .venv/bin/activate
-          pytest ../tests/ -v --tb=short
-
-  # Frontend tests
-  test-frontend:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Install dependencies
-        working-directory: auto-claude-ui
-        run: pnpm install --frozen-lockfile --ignore-scripts
-
-      - name: Run tests
-        working-directory: auto-claude-ui
-        run: pnpm test

.github/workflows/virustotal-scan.yml

@@ -0,0 +1,343 @@
+name: VirusTotal Scan
+
+# Runs AFTER release is published to avoid blocking release creation
+# VirusTotal scans can take 5+ minutes per file, which delays releases
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to scan (e.g., v2.8.0)'
+        required: true
+        type: string
+
+# Prevent TOCTOU race condition when updating release notes
+# If two runs target the same tag, queue them instead of running in parallel
+concurrency:
+  group: virustotal-${{ github.event.inputs.tag || github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  scan:
+    name: Scan release assets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required to update release notes
+    steps:
+      - name: Determine release tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Check for API key
+        id: check-key
+        env:
+          VT_KEY: ${{ secrets.VIRUSTOTAL_API_KEY }}
+        run: |
+          if [ -z "$VT_KEY" ]; then
+            echo "::warning::VIRUSTOTAL_API_KEY not configured, skipping scan"
+            echo "has_key=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_key=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Download release assets
+        if: steps.check-key.outputs.has_key == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ steps.tag.outputs.tag }}"
+          echo "Downloading assets for release $TAG..."
+
+          mkdir -p release-assets
+
+          # First verify the release exists
+          if ! gh release view "$TAG" --repo "${{ github.repository }}" >/dev/null 2>&1; then
+            echo "::error::Release $TAG not found"
+            exit 1
+          fi
+
+          # Download assets, distinguishing between "no matching assets" and real errors
+          set +e
+          gh release download "$TAG" \
+            --repo "${{ github.repository }}" \
+            --pattern "*.exe" \
+            --pattern "*.dmg" \
+            --pattern "*.AppImage" \
+            --pattern "*.deb" \
+            --pattern "*.flatpak" \
+            --dir release-assets 2>&1
+          exit_code=$?
+          set -e
+
+          if [ $exit_code -ne 0 ]; then
+            # Check if it's just "no assets matched" vs a real error
+            asset_count=$(gh release view "$TAG" --repo "${{ github.repository }}" --json assets -q '.assets | length')
+            if [ "$asset_count" -eq 0 ]; then
+              echo "Release has no assets yet (this is OK for new releases)"
+            else
+              # Check if any scannable assets exist that should have been downloaded
+              scannable_assets=$(gh release view "$TAG" --repo "${{ github.repository }}" --json assets \
+                -q '.assets[].name | select(test("\\.(exe|dmg|AppImage|deb|flatpak)$"))' | wc -l)
+              if [ "$scannable_assets" -gt 0 ]; then
+                echo "::error::Download failed - $scannable_assets scannable asset(s) exist but download failed"
+                exit 1
+              fi
+              echo "No assets matched the patterns (exe, dmg, AppImage, deb, flatpak)"
+            fi
+          fi
+
+          echo "Downloaded assets:"
+          ls -la release-assets/ || echo "No assets found"
+
+      - name: Scan with VirusTotal
+        if: steps.check-key.outputs.has_key == 'true'
+        id: virustotal
+        env:
+          VT_API_KEY: ${{ secrets.VIRUSTOTAL_API_KEY }}
+        run: |
+          echo "## VirusTotal Scan Results" > vt_results.md
+          echo "" >> vt_results.md
+
+          # Check if there are any files to scan
+          shopt -s nullglob
+          files=(release-assets/*.{exe,dmg,AppImage,deb,flatpak})
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No scannable files found in release assets"
+            echo "- No executable files found in release" >> vt_results.md
+            echo "vt_results<<EOF" >> $GITHUB_OUTPUT
+            cat vt_results.md >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          for file in "${files[@]}"; do
+            [ -f "$file" ] || continue
+            filename=$(basename "$file")
+            filesize=$(stat -c%s "$file" 2>/dev/null || stat -f%z "$file")
+            echo "Scanning $filename (${filesize} bytes)..."
+
+            # VirusTotal requires special upload URL for files > 32MB
+            LARGE_FILE_THRESHOLD=33554432  # 32 MB in bytes
+            if [ "$filesize" -gt "$LARGE_FILE_THRESHOLD" ]; then
+              echo "  Large file detected, requesting upload URL..."
+              upload_http_response=$(curl -s -w '\n%{http_code}' --request GET \
+                --url "https://www.virustotal.com/api/v3/files/upload_url" \
+                --header "x-apikey: $VT_API_KEY")
+              upload_http_code=$(echo "$upload_http_response" | tail -1)
+              upload_url_response=$(echo "$upload_http_response" | sed '$d')
+
+              if [ "$upload_http_code" != "200" ]; then
+                echo "::warning::Failed to get upload URL for large file $filename (HTTP $upload_http_code)"
+                echo "- $filename - ⚠️ Upload failed (large file, HTTP $upload_http_code)" >> vt_results.md
+                continue
+              fi
+
+              upload_url=$(echo "$upload_url_response" | jq -r '.data // empty')
+              if [ -z "$upload_url" ]; then
+                echo "::warning::Failed to get upload URL for large file $filename"
+                echo "Response: $upload_url_response"
+                echo "- $filename - ⚠️ Upload failed (large file)" >> vt_results.md
+                continue
+              fi
+              api_url="$upload_url"
+            else
+              api_url="https://www.virustotal.com/api/v3/files"
+            fi
+
+            # Upload file to VirusTotal (capture HTTP status code)
+            http_response=$(curl -s -w '\n%{http_code}' --request POST \
+              --url "$api_url" \
+              --header "x-apikey: $VT_API_KEY" \
+              --form "file=@$file")
+            http_code=$(echo "$http_response" | tail -1)
+            response=$(echo "$http_response" | sed '$d')
+
+            # Check HTTP status code first
+            if [ "$http_code" != "200" ]; then
+              echo "::warning::VirusTotal returned HTTP $http_code for $filename"
+              if [ "$http_code" = "429" ]; then
+                echo "- $filename - ⚠️ Scan failed (rate limited)" >> vt_results.md
+              elif [ "$http_code" = "403" ]; then
+                echo "- $filename - ⚠️ Scan failed (forbidden - check API key)" >> vt_results.md
+              else
+                echo "- $filename - ⚠️ Scan failed (HTTP $http_code)" >> vt_results.md
+              fi
+              continue
+            fi
+
+            # Check if response is valid JSON before parsing
+            if ! echo "$response" | jq -e . >/dev/null 2>&1; then
+              echo "::warning::VirusTotal returned invalid JSON for $filename"
+              echo "Response (first 500 chars): ${response:0:500}"
+              echo "- $filename - ⚠️ Scan failed (invalid response)" >> vt_results.md
+              continue
+            fi
+
+            # Check for API error response
+            error_code=$(echo "$response" | jq -r '.error.code // empty')
+            if [ -n "$error_code" ]; then
+              error_msg=$(echo "$response" | jq -r '.error.message // "Unknown error"')
+              echo "::warning::VirusTotal API error for $filename: $error_code - $error_msg"
+              echo "- $filename - ⚠️ Scan failed ($error_code)" >> vt_results.md
+              continue
+            fi
+
+            # Extract analysis ID
+            analysis_id=$(echo "$response" | jq -r '.data.id // empty')
+
+            if [ -z "$analysis_id" ]; then
+              echo "::warning::Failed to upload $filename to VirusTotal"
+              echo "Response: $response"
+              echo "- $filename - ⚠️ Upload failed" >> vt_results.md
+              continue
+            fi
+
+            echo "Uploaded $filename, analysis ID: $analysis_id"
+
+            # Wait for analysis to complete (max 5 minutes per file)
+            analysis=""
+            for i in {1..30}; do
+              sleep 10
+              analysis_http_response=$(curl -s -w '\n%{http_code}' --request GET \
+                --url "https://www.virustotal.com/api/v3/analyses/$analysis_id" \
+                --header "x-apikey: $VT_API_KEY")
+              analysis_http_code=$(echo "$analysis_http_response" | tail -1)
+              analysis=$(echo "$analysis_http_response" | sed '$d')
+
+              # Check HTTP status code
+              if [ "$analysis_http_code" != "200" ]; then
+                echo "  Warning: HTTP $analysis_http_code on attempt $i, retrying..."
+                if [ "$analysis_http_code" = "429" ]; then
+                  echo "  Rate limited, waiting longer..."
+                  sleep 30
+                fi
+                continue
+              fi
+
+              # Validate JSON response
+              if ! echo "$analysis" | jq -e . >/dev/null 2>&1; then
+                echo "  Warning: Invalid JSON response on attempt $i, retrying..."
+                continue
+              fi
+
+              status=$(echo "$analysis" | jq -r '.data.attributes.status // "unknown"')
+              echo "  Status: $status (attempt $i/30)"
+
+              if [ "$status" = "completed" ]; then
+                break
+              fi
+            done
+
+            # Handle analysis timeout - if loop completed without status=completed
+            if [ "$status" != "completed" ]; then
+              echo "::warning::Analysis timed out for $filename (status: $status after 5 minutes)"
+              file_hash=$(sha256sum "$file" | cut -d' ' -f1)
+              echo "- [$filename](https://www.virustotal.com/gui/file/$file_hash) - ⚠️ Analysis timed out" >> vt_results.md
+              continue
+            fi
+
+            # Final validation that we have valid analysis data
+            if ! echo "$analysis" | jq -e '.data.attributes.stats' >/dev/null 2>&1; then
+              echo "::warning::Could not get complete analysis for $filename, using local hash"
+              file_hash=$(sha256sum "$file" | cut -d' ' -f1)
+              echo "- [$filename](https://www.virustotal.com/gui/file/$file_hash) - ⚠️ Analysis incomplete" >> vt_results.md
+              continue
+            fi
+
+            # Get file hash for permanent URL
+            file_hash=$(echo "$analysis" | jq -r '.meta.file_info.sha256 // empty')
+
+            if [ -z "$file_hash" ]; then
+              # Fallback: calculate hash locally
+              file_hash=$(sha256sum "$file" | cut -d' ' -f1)
+            fi
+
+            # Get detection stats
+            malicious=$(echo "$analysis" | jq -r '.data.attributes.stats.malicious // 0')
+            suspicious=$(echo "$analysis" | jq -r '.data.attributes.stats.suspicious // 0')
+            undetected=$(echo "$analysis" | jq -r '.data.attributes.stats.undetected // 0')
+
+            vt_url="https://www.virustotal.com/gui/file/$file_hash"
+
+            if [ "$malicious" -gt 0 ] || [ "$suspicious" -gt 0 ]; then
+              echo "::warning::$filename has $malicious malicious and $suspicious suspicious detections (likely false positives)"
+              echo "- [$filename]($vt_url) - ⚠️ **$malicious malicious, $suspicious suspicious** detections (review recommended)" >> vt_results.md
+            else
+              echo "$filename is clean ($undetected engines, 0 detections)"
+              echo "- [$filename]($vt_url) - ✅ Clean ($undetected engines, 0 detections)" >> vt_results.md
+            fi
+          done
+
+          echo "" >> vt_results.md
+
+          # Save results for next step
+          cat vt_results.md
+          echo "vt_results<<EOF" >> $GITHUB_OUTPUT
+          cat vt_results.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Update release notes with scan results
+        if: steps.check-key.outputs.has_key == 'true' && steps.virustotal.outputs.vt_results != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ steps.tag.outputs.tag }}"
+
+          # Get current release body with error checking
+          if ! current_body=$(gh release view "$TAG" --repo "${{ github.repository }}" --json body -q '.body'); then
+            echo "::error::Failed to fetch current release body for $TAG"
+            exit 1
+          fi
+
+          # Additional safeguard for empty body
+          if [ -z "$current_body" ]; then
+            echo "::warning::Release body is empty, this may indicate a problem"
+          fi
+
+          # Check if VirusTotal results already exist in the body
+          if echo "$current_body" | grep -q "## VirusTotal Scan Results"; then
+            echo "VirusTotal results already in release notes, skipping update"
+            exit 0
+          fi
+
+          # Use file-based approach to avoid shell expansion issues
+          # First, write current body to file
+          echo "$current_body" > release-body.md
+
+          # Remove placeholder text if present (portable sed approach)
+          sed '/_VirusTotal scan results will be added automatically after release\./d' release-body.md > release-body.tmp && mv release-body.tmp release-body.md
+
+          # Append separator and VT results
+          echo "" >> release-body.md
+          echo "---" >> release-body.md
+          echo "" >> release-body.md
+          cat vt_results.md >> release-body.md
+
+          # Update release using --notes-file to avoid shell quoting issues
+          gh release edit "$TAG" \
+            --repo "${{ github.repository }}" \
+            --notes-file release-body.md
+
+          echo "✅ Updated release notes with VirusTotal scan results"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## VirusTotal Scan Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Release:** ${{ steps.tag.outputs.tag }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ steps.check-key.outputs.has_key }}" = "false" ]; then
+            echo "⚠️ Scan skipped: VIRUSTOTAL_API_KEY not configured" >> $GITHUB_STEP_SUMMARY
+          elif [ -f vt_results.md ]; then
+            cat vt_results.md >> $GITHUB_STEP_SUMMARY
+          else
+            echo "No scan results available" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/welcome.yml

@@ -0,0 +1,33 @@
+name: Welcome
+
+on:
+  pull_request_target:
+    types: [opened]
+  issues:
+    types: [opened]
+
+jobs:
+  welcome:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/first-interaction@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: |
+            👋 Thanks for opening your first issue!
+
+            A maintainer will triage this soon. In the meantime:
+            - Make sure you've provided all the requested info
+            - Join our [Discord](https://discord.gg/QhRnz9m5HE) for faster help
+          pr-message: |
+            🎉 Thanks for your first PR!
+
+            A maintainer will review it soon. Please make sure:
+            - Your branch is synced with `develop`
+            - CI checks pass
+            - You've followed our [contribution guide](https://github.com/AndyMik90/Auto-Claude/blob/develop/CONTRIBUTING.md)
+
+            Welcome to the Auto Claude community!

.gitignore

@@ -1,31 +1,71 @@
-# OS
+# ===========================
+# OS Files
+# ===========================
 .DS_Store
+.DS_Store?
+._*
 Thumbs.db
+ehthumbs.db
+Desktop.ini
 
-# Environment files (contain API keys)
+# ===========================
+# Security - Environment & Secrets
+# ===========================
 .env
-.env.local
+.env.*
+!.env.example
+/config.json
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+.secrets
+secrets/
+credentials/
 
-# Git worktrees (used by auto-build parallel mode)
-.worktrees/
-
-# IDE
+# ===========================
+# IDE & Editors
+# ===========================
 .idea/
 .vscode/
 *.swp
 *.swo
+*.sublime-workspace
+*.sublime-project
+.project
+.classpath
+.settings/
 
+# ===========================
 # Logs
+# ===========================
 logs/
 *.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
 
-# Personal notes
-OPUS_ANALYSIS_AND_IDEAS.md
+# ===========================
+# Git Worktrees (parallel builds)
+# ===========================
+.worktrees/
 
-# Documentation
-docs/
+# ===========================
+# Auto Claude Generated
+# ===========================
+.auto-claude/
+.planning/
+.auto-build-security.json
+.auto-claude-security.json
+.auto-claude-status
+.claude_settings.json
+.update-metadata.json
 
-# Python
+# ===========================
+# Python (apps/backend)
+# ===========================
 __pycache__/
 *.py[cod]
 *$py.class
@@ -33,25 +73,19 @@ __pycache__/
 .Python
 build/
 develop-eggs/
-dist/
-downloads/
 eggs/
 .eggs/
-/lib/
-/lib64/
-parts/
-sdist/
-var/
-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+MANIFEST
 
 # Virtual environments
 .venv/
 venv/
 ENV/
 env/
+.conda/
 
 # Testing
 .pytest_cache/
@@ -64,25 +98,78 @@ coverage.xml
 *.py,cover
 .hypothesis/
 
-# mypy
+# Type checking
 .mypy_cache/
 .dmypy.json
 dmypy.json
+.pytype/
+.pyre/
 
-# Auto-build generated files
-.auto-build-security.json
-.auto-claude-security.json
-.auto-claude-status
-.claude_settings.json
+# ===========================
+# Node.js (apps/frontend)
+# ===========================
+node_modules
+apps/frontend/node_modules
+.npm
+.yarn/
+.pnp.*
 
-# Development of Auto Build with Auto Build
+# Build output
+dist/
+out/
+*.tsbuildinfo
+apps/frontend/python-runtime/
+
+# Cache
+.cache/
+.parcel-cache/
+.turbo/
+.eslintcache
+.prettiercache
+
+# ===========================
+# Electron
+# ===========================
+apps/frontend/dist/
+apps/frontend/out/
+*.asar
+*.blockmap
+*.snap
+*.deb
+*.rpm
+*.AppImage
+*.dmg
+*.exe
+*.msi
+
+# ===========================
+# Testing
+# ===========================
+coverage/
+.nyc_output/
+test-results/
+playwright-report/
+playwright/.cache/
+
+# ===========================
+# Misc
+# ===========================
+*.local
+*.bak
+*.tmp
+*.temp
+
+# Development
 dev/
-
-.auto-claude/
-
+_bmad/
+_bmad-output/
+.claude/
 /docs
+OPUS_ANALYSIS_AND_IDEAS.md
+/.github/agents
 
-_bmad
-_bmad-output
-
-.claude
+# Auto Claude generated files
+.security-key
+/shared_docs
+logs/security/
+Agents.md

.husky/commit-msg

@@ -0,0 +1,81 @@
+#!/bin/sh
+
+# Commit message validation
+# Enforces conventional commit format: type(scope)!?: description
+#
+# Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+# Scope allows: letters, numbers, hyphens, underscores, slashes, dots
+# Optional ! for breaking changes
+# Examples:
+#   feat(tasks): add drag and drop support
+#   fix(terminal): resolve scroll position issue
+#   feat!: breaking change without scope
+#   feat(api)!: breaking change with scope
+#   docs: update README with setup instructions
+#   chore: update dependencies
+
+commit_msg_file=$1
+commit_msg=$(cat "$commit_msg_file")
+
+# Regex for conventional commits
+# Format: type(optional-scope)!?: description
+# Scope allows: letters, numbers, hyphens, underscores, slashes, dots (consistent with GitHub workflow)
+# Optional ! for breaking changes: feat!: or feat(scope)!:
+pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_/.-]+\))?!?: .{1,100}$"
+
+# Allow merge commits
+if echo "$commit_msg" | grep -qE "^Merge "; then
+  exit 0
+fi
+
+# Allow revert commits
+if echo "$commit_msg" | grep -qE "^Revert "; then
+  exit 0
+fi
+
+# Check first line against pattern
+first_line=$(echo "$commit_msg" | head -n 1)
+
+if ! echo "$first_line" | grep -qE "$pattern"; then
+  echo ""
+  echo "ERROR: Invalid commit message format!"
+  echo ""
+  echo "Your message: $first_line"
+  echo ""
+  echo "Expected format: type(scope)!?: description"
+  echo ""
+  echo "Valid types:"
+  echo "  feat     - A new feature"
+  echo "  fix      - A bug fix"
+  echo "  docs     - Documentation changes"
+  echo "  style    - Code style changes (formatting, semicolons, etc.)"
+  echo "  refactor - Code refactoring (no feature/fix)"
+  echo "  perf     - Performance improvements"
+  echo "  test     - Adding or updating tests"
+  echo "  build    - Build system or dependencies"
+  echo "  ci       - CI/CD configuration"
+  echo "  chore    - Other changes (maintenance)"
+  echo "  revert   - Reverting a previous commit"
+  echo ""
+  echo "Examples:"
+  echo "  feat(tasks): add drag and drop support"
+  echo "  fix(terminal): resolve scroll position issue"
+  echo "  feat!: breaking change without scope"
+  echo "  feat(api)!: breaking change with scope"
+  echo "  docs: update README"
+  echo "  chore: update dependencies"
+  echo ""
+  exit 1
+fi
+
+# Check description length (max 100 chars for first line)
+if [ ${#first_line} -gt 100 ]; then
+  echo ""
+  echo "ERROR: Commit message first line is too long!"
+  echo "Maximum: 100 characters"
+  echo "Current: ${#first_line} characters"
+  echo ""
+  exit 1
+fi
+
+exit 0

.husky/pre-commit

@@ -1,6 +1,311 @@
 #!/bin/sh
 
-# Run lint-staged in auto-claude-ui if there are staged files there
-if git diff --cached --name-only | grep -q "^auto-claude-ui/"; then
-  cd auto-claude-ui && pnpm exec lint-staged
+# =============================================================================
+# GIT WORKTREE CONTEXT HANDLING
+# =============================================================================
+# When running in a worktree, we need to preserve git context to prevent HEAD
+# corruption. However, we must also CLEAR these variables when NOT in a worktree
+# to prevent cross-worktree contamination (files leaking between worktrees).
+#
+# The bug: If GIT_DIR/GIT_WORK_TREE are set from a previous worktree session
+# and this hook runs in the main repo (where .git is a directory, not a file),
+# git commands will target the wrong repository, causing files to appear as
+# untracked in the wrong location.
+#
+# Fix: Explicitly unset these variables when NOT in a worktree context.
+# =============================================================================
+
+if [ -f ".git" ]; then
+  # We're in a worktree (.git is a file pointing to the actual git dir)
+  # Use -n with /p to only print lines that match the gitdir: prefix, head -1 for safety
+  WORKTREE_GIT_DIR=$(sed -n 's/^gitdir: //p' .git | head -1)
+  if [ -n "$WORKTREE_GIT_DIR" ] && [ -d "$WORKTREE_GIT_DIR" ]; then
+    export GIT_DIR="$WORKTREE_GIT_DIR"
+    export GIT_WORK_TREE="$(pwd)"
+  else
+    # .git file exists but is malformed or points to non-existent directory
+    # CRITICAL: Clear any inherited GIT_DIR/GIT_WORK_TREE to prevent cross-worktree leakage
+    unset GIT_DIR
+    unset GIT_WORK_TREE
+  fi
+else
+  # We're in the main repo (.git is a directory)
+  # CRITICAL: Clear any inherited GIT_DIR/GIT_WORK_TREE to prevent cross-worktree leakage
+  unset GIT_DIR
+  unset GIT_WORK_TREE
 fi
+
+# =============================================================================
+# SAFETY CHECK: Detect and fix corrupted core.worktree configuration
+# =============================================================================
+# If core.worktree is set in the main repo's config (pointing to a worktree),
+# this indicates previous corruption. Fix it automatically.
+if [ ! -f ".git" ]; then
+  CORE_WORKTREE=$(git config --get core.worktree 2>/dev/null || true)
+  if [ -n "$CORE_WORKTREE" ]; then
+    echo "Warning: Detected corrupted core.worktree setting, removing it..."
+    if ! git config --unset core.worktree 2>/dev/null; then
+      echo "Warning: Failed to unset core.worktree. Manual intervention may be needed."
+    fi
+  fi
+fi
+
+echo "Running pre-commit checks..."
+
+# =============================================================================
+# VERSION SYNC - Keep all version references in sync with root package.json
+# =============================================================================
+
+# Check if package.json is staged
+if git diff --cached --name-only | grep -q "^package.json$"; then
+  echo "package.json changed, syncing version to all files..."
+
+  # Extract version from root package.json
+  VERSION=$(node -p "require('./package.json').version")
+
+  if [ -n "$VERSION" ]; then
+    # Sync to apps/frontend/package.json
+    if [ -f "apps/frontend/package.json" ]; then
+      node -e "
+        const fs = require('fs');
+        const pkg = require('./apps/frontend/package.json');
+        if (pkg.version !== '$VERSION') {
+          pkg.version = '$VERSION';
+          fs.writeFileSync('./apps/frontend/package.json', JSON.stringify(pkg, null, 2) + '\n');
+          console.log('  Updated apps/frontend/package.json to $VERSION');
+        }
+      "
+      git add apps/frontend/package.json
+    fi
+
+    # Sync to apps/backend/__init__.py
+    if [ -f "apps/backend/__init__.py" ]; then
+      sed -i.bak "s/__version__ = \"[^\"]*\"/__version__ = \"$VERSION\"/" apps/backend/__init__.py
+      rm -f apps/backend/__init__.py.bak
+      git add apps/backend/__init__.py
+      echo "  Updated apps/backend/__init__.py to $VERSION"
+    fi
+
+    # Sync to README.md - section-aware updates (stable vs beta)
+    if [ -f "README.md" ]; then
+      # Escape hyphens for shields.io badge format (shields.io uses -- for literal hyphens)
+      ESCAPED_VERSION=$(echo "$VERSION" | sed 's/-/--/g')
+
+      # Detect if this is a prerelease (contains - after base version, e.g., 2.7.2-beta.10)
+      if echo "$VERSION" | grep -q '-'; then
+        # PRERELEASE: Update only beta sections
+        echo "  Detected PRERELEASE version: $VERSION"
+
+        # Update beta version badge (orange)
+        sed -i.bak "s/beta-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-orange/beta-$ESCAPED_VERSION-orange/g" README.md
+
+        # Update beta version badge link (within BETA_VERSION_BADGE section)
+        sed -i.bak '/<!-- BETA_VERSION_BADGE -->/,/<!-- BETA_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+        # Update beta download links (within BETA_DOWNLOADS section only)
+        # Use perl for cross-platform compatibility (BSD sed doesn't support {block} syntax)
+        for SUFFIX in "win32-x64.exe" "darwin-arm64.dmg" "darwin-x64.dmg" "linux-x86_64.AppImage" "linux-amd64.deb" "linux-x86_64.flatpak"; do
+          perl -i -pe 'if (/<!-- BETA_DOWNLOADS -->/ .. /<!-- BETA_DOWNLOADS_END -->/) { s|Auto-Claude-[0-9.a-z-]*-'"$SUFFIX"'\]\(https://github.com/AndyMik90/Auto-Claude/releases/download/v[^/]*/Auto-Claude-[^)]*-'"$SUFFIX"'\)|Auto-Claude-'"$VERSION"'-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v'"$VERSION"'/Auto-Claude-'"$VERSION"'-'"$SUFFIX"')|g }' README.md
+        done
+      else
+        # STABLE: Update stable sections and top badge
+        echo "  Detected STABLE version: $VERSION"
+
+        # Update top version badge (blue) - within TOP_VERSION_BADGE section
+        sed -i.bak '/<!-- TOP_VERSION_BADGE -->/,/<!-- TOP_VERSION_BADGE_END -->/s/version-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-blue/version-'"$ESCAPED_VERSION"'-blue/g' README.md
+        sed -i.bak '/<!-- TOP_VERSION_BADGE -->/,/<!-- TOP_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+        # Update stable version badge (blue) - within STABLE_VERSION_BADGE section
+        sed -i.bak '/<!-- STABLE_VERSION_BADGE -->/,/<!-- STABLE_VERSION_BADGE_END -->/s/stable-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-blue/stable-'"$ESCAPED_VERSION"'-blue/g' README.md
+        sed -i.bak '/<!-- STABLE_VERSION_BADGE -->/,/<!-- STABLE_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+        # Update stable download links (within STABLE_DOWNLOADS section only)
+        # Use perl for cross-platform compatibility (BSD sed doesn't support {block} syntax)
+        for SUFFIX in "win32-x64.exe" "darwin-arm64.dmg" "darwin-x64.dmg" "linux-x86_64.AppImage" "linux-amd64.deb"; do
+          perl -i -pe 'if (/<!-- STABLE_DOWNLOADS -->/ .. /<!-- STABLE_DOWNLOADS_END -->/) { s|Auto-Claude-[0-9.a-z-]*-'"$SUFFIX"'\]\(https://github.com/AndyMik90/Auto-Claude/releases/download/v[^/]*/Auto-Claude-[^)]*-'"$SUFFIX"'\)|Auto-Claude-'"$VERSION"'-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v'"$VERSION"'/Auto-Claude-'"$VERSION"'-'"$SUFFIX"')|g }' README.md
+        done
+      fi
+
+      rm -f README.md.bak
+      git add README.md
+      echo "  Updated README.md to $VERSION"
+    fi
+
+    echo "Version sync complete: $VERSION"
+  fi
+fi
+
+# =============================================================================
+# BACKEND CHECKS (Python) - Run first, before frontend
+# =============================================================================
+
+# Check if there are staged Python files in apps/backend
+if git diff --cached --name-only | grep -q "^apps/backend/.*\.py$"; then
+  echo "Python changes detected, running backend checks..."
+
+  # Determine ruff command (venv or global)
+  RUFF=""
+  if [ -f "apps/backend/.venv/bin/ruff" ]; then
+    RUFF="apps/backend/.venv/bin/ruff"
+  elif [ -f "apps/backend/.venv/Scripts/ruff.exe" ]; then
+    RUFF="apps/backend/.venv/Scripts/ruff.exe"
+  elif command -v ruff >/dev/null 2>&1; then
+    RUFF="ruff"
+  fi
+
+  if [ -n "$RUFF" ]; then
+    # Get only staged Python files in apps/backend (process only what's being committed)
+    STAGED_PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "^apps/backend/.*\.py$" || true)
+
+    if [ -n "$STAGED_PY_FILES" ]; then
+      # Run ruff linting (auto-fix) only on staged files
+      echo "Running ruff lint on staged files..."
+      echo "$STAGED_PY_FILES" | xargs $RUFF check --fix
+      if [ $? -ne 0 ]; then
+        echo "Ruff lint failed. Please fix Python linting errors before committing."
+        exit 1
+      fi
+
+      # Run ruff format (auto-fix) only on staged files
+      echo "Running ruff format on staged files..."
+      echo "$STAGED_PY_FILES" | xargs $RUFF format
+
+      # Re-stage only the files that were originally staged (in case ruff modified them)
+      echo "$STAGED_PY_FILES" | xargs git add
+    fi
+  else
+    echo "Warning: ruff not found, skipping Python linting. Install with: uv pip install ruff"
+  fi
+
+  # Run pytest (skip slow/integration tests and Windows-incompatible tests for pre-commit speed)
+  # Use subshell to isolate directory changes and prevent worktree corruption
+  echo "Running Python tests..."
+  (
+    cd apps/backend
+    # Tests to skip: graphiti (external deps), merge_file_tracker/service_orchestrator/worktree/workspace (Windows path/git issues)
+    # Also skip tests that require optional dependencies (pydantic structured outputs)
+    IGNORE_TESTS="--ignore=../../tests/test_graphiti.py --ignore=../../tests/test_merge_file_tracker.py --ignore=../../tests/test_service_orchestrator.py --ignore=../../tests/test_worktree.py --ignore=../../tests/test_workspace.py --ignore=../../tests/test_finding_validation.py --ignore=../../tests/test_sdk_structured_output.py --ignore=../../tests/test_structured_outputs.py"
+    
+    # Determine Python executable from venv
+    VENV_PYTHON=""
+    if [ -f ".venv/bin/python" ]; then
+      VENV_PYTHON=".venv/bin/python"
+    elif [ -f ".venv/Scripts/python.exe" ]; then
+      VENV_PYTHON=".venv/Scripts/python.exe"
+    fi
+    
+    if [ -n "$VENV_PYTHON" ]; then
+      # Check if pytest is installed in venv
+      if $VENV_PYTHON -c "import pytest" 2>/dev/null; then
+        PYTHONPATH=. $VENV_PYTHON -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+      else
+        echo "Warning: pytest not installed in venv. Installing test dependencies..."
+        $VENV_PYTHON -m pip install -q -r ../../tests/requirements-test.txt
+        PYTHONPATH=. $VENV_PYTHON -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+      fi
+    elif [ -d ".venv" ]; then
+      echo "Warning: venv exists but Python not found in it, using system Python"
+      PYTHONPATH=. python -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+    else
+      echo "Warning: No .venv found in apps/backend, using system Python"
+      PYTHONPATH=. python -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+    fi
+  )
+  if [ $? -ne 0 ]; then
+    echo "Python tests failed. Please fix failing tests before committing."
+    exit 1
+  fi
+
+  echo "Backend checks passed!"
+fi
+
+# =============================================================================
+# FRONTEND CHECKS (TypeScript/React)
+# =============================================================================
+
+# Check if there are staged files in apps/frontend
+if git diff --cached --name-only | grep -q "^apps/frontend/"; then
+  echo "Frontend changes detected, running frontend checks..."
+
+  # Detect if we're in a worktree and check if dependencies are available
+  IS_WORKTREE=false
+  DEPS_AVAILABLE=true
+
+  if [ -f ".git" ]; then
+    # .git is a file (not directory) in worktrees
+    IS_WORKTREE=true
+    echo "Detected git worktree environment"
+  fi
+
+  # Check if node_modules has actual dependencies by looking for a known package
+  # @lydell/node-pty is required for terminal code and is a common source of TypeScript errors
+  # It may be in root node_modules (hoisted) or apps/frontend/node_modules
+  # Note: -d follows symlinks automatically, so this works for both real dirs and symlinks
+  # We check for the full package path (@lydell/node-pty) rather than just the namespace
+  # for precise detection - ensures the actual dependency is installed, not just any @lydell package
+  if [ ! -d "node_modules/@lydell/node-pty" ] && [ ! -d "apps/frontend/node_modules/@lydell/node-pty" ]; then
+    DEPS_AVAILABLE=false
+  fi
+
+  if [ "$DEPS_AVAILABLE" = false ]; then
+    if [ "$IS_WORKTREE" = true ]; then
+      # In worktree without dependencies - warn but allow commit
+      echo ""
+      echo "⚠️  WARNING: node_modules not available in this worktree."
+      echo "   TypeScript and lint checks will be skipped."
+      echo "   This is expected for auto-claude worktrees."
+      echo "   Full validation will occur when PR is created/merged."
+      echo ""
+    else
+      # Main repo without dependencies - this is an error
+      echo "Error: node_modules not found. Run 'npm install' first."
+      exit 1
+    fi
+  else
+    # Dependencies available - run full frontend checks
+    # Use subshell to isolate directory changes and prevent worktree corruption
+    (
+      cd apps/frontend
+
+      # Run lint-staged (handles staged .ts/.tsx files)
+      npm exec lint-staged
+      if [ $? -ne 0 ]; then
+        echo "lint-staged failed. Please fix linting errors before committing."
+        exit 1
+      fi
+
+      # Run TypeScript type check
+      echo "Running type check..."
+      npm run typecheck
+      if [ $? -ne 0 ]; then
+        echo "Type check failed. Please fix TypeScript errors before committing."
+        exit 1
+      fi
+
+      # Run linting
+      echo "Running lint..."
+      npm run lint
+      if [ $? -ne 0 ]; then
+        echo "Lint failed. Run 'npm run lint:fix' to auto-fix issues."
+        exit 1
+      fi
+
+      # Check for vulnerabilities (only critical severity)
+      # Note: Using critical level because electron-builder has a known high-severity
+      # tar vulnerability (CVE-2026-23745) that cannot be fixed until electron-builder
+      # releases an update with tar@7.x support. This is a build dependency, not runtime.
+      echo "Checking for vulnerabilities..."
+      npm audit --audit-level=critical
+      if [ $? -ne 0 ]; then
+        echo "Critical severity vulnerabilities found. Run 'npm audit fix' to resolve."
+        exit 1
+      fi
+    )
+    if [ $? -ne 0 ]; then
+      exit 1
+    fi
+    echo "Frontend checks passed!"
+  fi
+fi
+
+echo "All pre-commit checks passed!"

.pre-commit-config.yaml

@@ -1,36 +1,184 @@
 repos:
-  # Python linting (auto-claude/)
+  # Version sync - propagate root package.json version to all files
+  # NOTE: Skip in worktrees - version sync modifies root files which don't exist in worktree
+  - repo: local
+    hooks:
+      - id: version-sync
+        name: Version Sync
+        entry: bash
+        args:
+          - -c
+          - |
+            # Skip in worktrees - .git is a file pointing to main repo, not a directory
+            # Version sync modifies root-level files that may not exist in worktree context
+            if [ -f ".git" ]; then
+              echo "Skipping version-sync in worktree (root files not accessible)"
+              exit 0
+            fi
+            VERSION=$(node -p "require('./package.json').version")
+            if [ -n "$VERSION" ]; then
+
+              # Sync to apps/frontend/package.json
+              node -e "
+                const fs = require('fs');
+                const p = require('./apps/frontend/package.json');
+                const v = process.argv[1];
+                if (p.version !== v) {
+                  p.version = v;
+                  fs.writeFileSync('./apps/frontend/package.json', JSON.stringify(p, null, 2) + '\n');
+                }
+              " "$VERSION"
+
+              # Sync to apps/backend/__init__.py
+              sed -i.bak "s/__version__ = \"[^\"]*\"/__version__ = \"$VERSION\"/" apps/backend/__init__.py && rm -f apps/backend/__init__.py.bak
+
+              # Sync to README.md - section-aware updates (stable vs beta)
+              ESCAPED_VERSION=$(echo "$VERSION" | sed 's/-/--/g')
+
+              # Detect if this is a prerelease (contains - after base version)
+              if echo "$VERSION" | grep -q '-'; then
+                # PRERELEASE: Update only beta sections
+                echo "  Detected PRERELEASE version: $VERSION"
+
+                # Update beta version badge (orange)
+                sed -i.bak "s/beta-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-orange/beta-$ESCAPED_VERSION-orange/g" README.md
+
+                # Update beta version badge link
+                sed -i.bak '/<!-- BETA_VERSION_BADGE -->/,/<!-- BETA_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+                # Update beta download links (within BETA_DOWNLOADS section only)
+                for SUFFIX in "win32-x64.exe" "darwin-arm64.dmg" "darwin-x64.dmg" "linux-x86_64.AppImage" "linux-amd64.deb" "linux-x86_64.flatpak"; do
+                  sed -i.bak '/<!-- BETA_DOWNLOADS -->/,/<!-- BETA_DOWNLOADS_END -->/{s|Auto-Claude-[0-9.a-z-]*-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v[^/]*/Auto-Claude-[^)]*-'"$SUFFIX"')|Auto-Claude-'"$VERSION"'-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v'"$VERSION"'/Auto-Claude-'"$VERSION"'-'"$SUFFIX"')|g}' README.md
+                done
+              else
+                # STABLE: Update stable sections and top badge
+                echo "  Detected STABLE version: $VERSION"
+
+                # Update top version badge (blue)
+                sed -i.bak '/<!-- TOP_VERSION_BADGE -->/,/<!-- TOP_VERSION_BADGE_END -->/s/version-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-blue/version-'"$ESCAPED_VERSION"'-blue/g' README.md
+                sed -i.bak '/<!-- TOP_VERSION_BADGE -->/,/<!-- TOP_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+                # Update stable version badge (blue)
+                sed -i.bak '/<!-- STABLE_VERSION_BADGE -->/,/<!-- STABLE_VERSION_BADGE_END -->/s/stable-[0-9]*\.[0-9]*\.[0-9]*\(--[a-z]*\.[0-9]*\)*-blue/stable-'"$ESCAPED_VERSION"'-blue/g' README.md
+                sed -i.bak '/<!-- STABLE_VERSION_BADGE -->/,/<!-- STABLE_VERSION_BADGE_END -->/s|releases/tag/v[0-9.a-z-]*)|releases/tag/v'"$VERSION"')|g' README.md
+
+                # Update stable download links (within STABLE_DOWNLOADS section only)
+                for SUFFIX in "win32-x64.exe" "darwin-arm64.dmg" "darwin-x64.dmg" "linux-x86_64.AppImage" "linux-amd64.deb"; do
+                  sed -i.bak '/<!-- STABLE_DOWNLOADS -->/,/<!-- STABLE_DOWNLOADS_END -->/{s|Auto-Claude-[0-9.a-z-]*-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v[^/]*/Auto-Claude-[^)]*-'"$SUFFIX"')|Auto-Claude-'"$VERSION"'-'"$SUFFIX"'](https://github.com/AndyMik90/Auto-Claude/releases/download/v'"$VERSION"'/Auto-Claude-'"$VERSION"'-'"$SUFFIX"')|g}' README.md
+                done
+              fi
+              rm -f README.md.bak
+
+              # Stage changes
+              git add apps/frontend/package.json apps/backend/__init__.py README.md 2>/dev/null || true
+            fi
+        language: system
+        files: ^package\.json$
+        pass_filenames: false
+
+  # Python encoding check - prevent regression of UTF-8 encoding fixes (PR #782)
+  - repo: local
+    hooks:
+      - id: check-file-encoding
+        name: Check file encoding parameters
+        entry: python scripts/check_encoding.py
+        language: system
+        types: [python]
+        files: ^apps/backend/
+        description: Ensures all file operations specify encoding="utf-8"
+
+  # Python linting (apps/backend/)
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.3
+    rev: v0.14.10
     hooks:
       - id: ruff
         args: [--fix]
-        files: ^auto-claude/
+        files: ^apps/backend/
       - id: ruff-format
-        files: ^auto-claude/
+        files: ^apps/backend/
 
-  # Frontend linting (auto-claude-ui/)
+  # Python tests (apps/backend/) - skip slow/integration tests for pre-commit speed
+  # Tests to skip: graphiti (external deps), merge_file_tracker/service_orchestrator/worktree/workspace (Windows path/git issues)
+  # NOTE: Skip this hook in worktrees (where .git is a file, not a directory)
   - repo: local
     hooks:
-      - id: eslint
-        name: ESLint
-        entry: bash -c 'cd auto-claude-ui && pnpm lint'
+      - id: pytest
+        name: Python Tests
+        entry: bash
+        args:
+          - -c
+          - |
+            # Skip in worktrees - .git is a file pointing to main repo, not a directory
+            # This prevents path resolution issues with ../../tests/ in worktree context
+            if [ -f ".git" ]; then
+              echo "Skipping pytest in worktree (path resolution would fail)"
+              exit 0
+            fi
+            cd apps/backend
+            if [ -f ".venv/bin/pytest" ]; then
+              PYTEST_CMD=".venv/bin/pytest"
+            elif [ -f ".venv/Scripts/pytest.exe" ]; then
+              PYTEST_CMD=".venv/Scripts/pytest.exe"
+            else
+              PYTEST_CMD="python -m pytest"
+            fi
+            PYTHONPATH=. $PYTEST_CMD \
+              ../../tests/ \
+              -v \
+              --tb=short \
+              -x \
+              -m "not slow and not integration" \
+              --ignore=../../tests/test_graphiti.py \
+              --ignore=../../tests/test_merge_file_tracker.py \
+              --ignore=../../tests/test_service_orchestrator.py \
+              --ignore=../../tests/test_worktree.py \
+              --ignore=../../tests/test_workspace.py
         language: system
-        files: ^auto-claude-ui/.*\.(ts|tsx|js|jsx)$
+        files: ^(apps/backend/.*\.py$|tests/.*\.py$)
+        pass_filenames: false
+
+  # Frontend linting (apps/frontend/) - Biome is 15-25x faster than ESLint
+  # NOTE: These hooks check for worktree context to avoid npm/node_modules issues
+  - repo: local
+    hooks:
+      - id: biome
+        name: Biome (lint + format)
+        entry: bash
+        args:
+          - -c
+          - |
+            # Skip in worktrees if node_modules doesn't exist (Biome not installed)
+            if [ -f ".git" ] && [ ! -d "apps/frontend/node_modules" ]; then
+              echo "Skipping Biome in worktree (node_modules not found)"
+              exit 0
+            fi
+            cd apps/frontend && npx biome check --write --no-errors-on-unmatched .
+        language: system
+        files: ^apps/frontend/.*\.(ts|tsx|js|jsx|json)$
         pass_filenames: false
 
       - id: typecheck
         name: TypeScript Check
-        entry: bash -c 'cd auto-claude-ui && pnpm typecheck'
+        entry: bash
+        args:
+          - -c
+          - |
+            # Skip in worktrees if node_modules doesn't exist (dependencies not installed)
+            if [ -f ".git" ] && [ ! -d "apps/frontend/node_modules" ]; then
+              echo "Skipping TypeScript check in worktree (node_modules not found)"
+              exit 0
+            fi
+            cd apps/frontend && npm run typecheck
         language: system
-        files: ^auto-claude-ui/.*\.(ts|tsx)$
+        files: ^apps/frontend/.*\.(ts|tsx)$
         pass_filenames: false
 
   # General checks
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
+        exclude: pnpm-lock\.yaml$
       - id: check-added-large-files

CLA.md

@@ -0,0 +1,76 @@
+# Auto Claude Individual Contributor License Agreement
+
+Thank you for your interest in contributing to Auto Claude. This Contributor License Agreement ("Agreement") documents the rights granted by contributors to the Project.
+
+By signing this Agreement, you accept and agree to the following terms and conditions for your present and future Contributions submitted to the Project.
+
+## 1. Definitions
+
+**"You" (or "Your")** means the individual who submits a Contribution to the Project.
+
+**"Contribution"** means any original work of authorship, including any modifications or additions to an existing work, that is intentionally submitted by You to the Project for inclusion in, or documentation of, the Project. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Project or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Project for the purpose of discussing and improving the Project.
+
+**"Project"** means Auto Claude, a multi-agent autonomous coding framework, currently available at https://github.com/AndyMik90/Auto-Claude.
+
+**"Project Owner"** means Andre Mikalsen and any designated successors or assignees.
+
+## 2. Grant of Copyright License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to the Project Owner and to recipients of software distributed by the Project Owner a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to:
+
+- Reproduce, prepare derivative works of, publicly display, publicly perform, and distribute Your Contributions and such derivative works
+- Sublicense any or all of the foregoing rights to third parties
+
+## 3. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to the Project Owner and to recipients of software distributed by the Project Owner a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer Your Contributions, where such license applies only to those patent claims licensable by You that are necessarily infringed by Your Contribution(s) alone or by combination of Your Contribution(s) with the Project to which such Contribution(s) was submitted.
+
+## 4. Future Licensing Flexibility
+
+You understand and agree that the Project Owner may, in the future, license the Project, including Your Contributions, under additional licenses beyond the current GNU Affero General Public License version 3.0 (AGPL-3.0). Such additional licenses may include commercial or enterprise licenses.
+
+This provision ensures the Project has proper licensing flexibility should such licensing options be introduced in the future. The open source version of the Project will continue to be available under AGPL-3.0.
+
+## 5. Representations
+
+You represent that:
+
+(a) You are legally entitled to grant the above licenses. If your employer(s) has rights to intellectual property that you create that includes your Contributions, you represent that you have received permission to make Contributions on behalf of that employer, or that your employer has waived such rights for your Contributions to the Project.
+
+(b) Each of Your Contributions is Your original creation. You represent that Your Contribution submissions include complete details of any third-party license or other restriction (including, but not limited to, related patents and trademarks) of which you are personally aware and which are associated with any part of Your Contributions.
+
+(c) Your Contribution does not violate any third-party rights, including but not limited to intellectual property rights, privacy rights, or contractual obligations.
+
+## 6. Support and Warranty Disclaimer
+
+You are not expected to provide support for Your Contributions, except to the extent You desire to provide support. You may provide support for free, for a fee, or not at all.
+
+UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, YOU PROVIDE YOUR CONTRIBUTIONS ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+
+## 7. No Obligation to Use
+
+You understand that the decision to include Your Contribution in any project or source repository is entirely at the discretion of the Project Owner, and this Agreement does not guarantee that Your Contributions will be included in any product.
+
+## 8. Contributor Rights
+
+You retain full copyright ownership of Your Contributions. Nothing in this Agreement shall be interpreted to prohibit you from licensing Your Contributions under different terms to third parties or from using Your Contributions for any other purpose.
+
+## 9. Notification
+
+You agree to notify the Project Owner of any facts or circumstances of which you become aware that would make these representations inaccurate in any respect.
+
+---
+
+## How to Sign
+
+To sign this CLA, comment on your Pull Request with:
+
+```
+I have read the CLA Document and I hereby sign the CLA
+```
+
+Your signature will be recorded automatically.
+
+---
+
+*This CLA is based on the Apache Software Foundation Individual Contributor License Agreement v2.0.*

CLAUDE.md

@@ -4,83 +4,155 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Auto Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. It uses the Claude Code SDK to run agents in isolated workspaces with security controls.
+Auto Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. It uses the Claude Agent SDK to run agents in isolated workspaces with security controls.
+
+**CRITICAL: All AI interactions use the Claude Agent SDK (`claude-agent-sdk` package), NOT the Anthropic API directly.**
+
+## Project Structure
+
+```
+autonomous-coding/
+├── apps/
+│   ├── backend/           # Python backend/CLI - ALL agent logic lives here
+│   │   ├── core/          # Client, auth, security
+│   │   ├── agents/        # Agent implementations
+│   │   ├── spec_agents/   # Spec creation agents
+│   │   ├── integrations/  # Graphiti, Linear, GitHub
+│   │   └── prompts/       # Agent system prompts
+│   └── frontend/          # Electron desktop UI
+├── guides/                # Documentation
+├── tests/                 # Test suite
+└── scripts/               # Build and utility scripts
+```
+
+**When working with AI/LLM code:**
+- Look in `apps/backend/core/client.py` for the Claude SDK client setup
+- Reference `apps/backend/agents/` for working agent implementations
+- Check `apps/backend/spec_agents/` for spec creation agent examples
+- NEVER use `anthropic.Anthropic()` directly - always use `create_client()` from `core.client`
+
+**Frontend (Electron Desktop App):**
+- Built with Electron, React, TypeScript
+- AI agents can perform E2E testing using the Electron MCP server
+- When bug fixing or implementing features, use the Electron MCP server for automated testing
+- See "End-to-End Testing" section below for details
 
 ## Commands
 
 ### Setup
-```bash
-# Install dependencies (from auto-claude/)
-uv venv && uv pip install -r requirements.txt
-# Or: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
 
-# Set up OAuth token
-claude setup-token
-# Add to auto-claude/.env: CLAUDE_CODE_OAUTH_TOKEN=your-token
+**Requirements:**
+- Python 3.12+ (required for backend)
+- Node.js (for frontend)
+
+```bash
+# Install all dependencies from root
+npm run install:all
+
+# Or install separately:
+# Backend (from apps/backend/)
+cd apps/backend && uv venv && uv pip install -r requirements.txt
+
+# Frontend (from apps/frontend/)
+cd apps/frontend && npm install
+
+# Authenticate (token auto-saved to Keychain)
+claude
+# Then type: /login
+# Press Enter to open browser and complete OAuth
 ```
 
 ### Creating and Running Specs
 ```bash
+cd apps/backend
+
 # Create a spec interactively
-python auto-claude/spec_runner.py --interactive
+python spec_runner.py --interactive
 
 # Create spec from task description
-python auto-claude/spec_runner.py --task "Add user authentication"
+python spec_runner.py --task "Add user authentication"
 
 # Force complexity level (simple/standard/complex)
-python auto-claude/spec_runner.py --task "Fix button" --complexity simple
+python spec_runner.py --task "Fix button" --complexity simple
 
 # Run autonomous build
-python auto-claude/run.py --spec 001
+python run.py --spec 001
 
 # List all specs
-python auto-claude/run.py --list
+python run.py --list
 ```
 
 ### Workspace Management
 ```bash
+cd apps/backend
+
 # Review changes in isolated worktree
-python auto-claude/run.py --spec 001 --review
+python run.py --spec 001 --review
 
 # Merge completed build into project
-python auto-claude/run.py --spec 001 --merge
+python run.py --spec 001 --merge
 
 # Discard build
-python auto-claude/run.py --spec 001 --discard
+python run.py --spec 001 --discard
 ```
 
 ### QA Validation
 ```bash
+cd apps/backend
+
 # Run QA manually
-python auto-claude/run.py --spec 001 --qa
+python run.py --spec 001 --qa
 
 # Check QA status
-python auto-claude/run.py --spec 001 --qa-status
+python run.py --spec 001 --qa-status
 ```
 
 ### Testing
 ```bash
 # Install test dependencies (required first time)
-cd auto-claude && uv pip install -r ../tests/requirements-test.txt
+cd apps/backend && uv pip install -r ../../tests/requirements-test.txt
 
 # Run all tests (use virtual environment pytest)
-auto-claude/.venv/bin/pytest tests/ -v
+apps/backend/.venv/bin/pytest tests/ -v
 
 # Run single test file
-auto-claude/.venv/bin/pytest tests/test_security.py -v
+apps/backend/.venv/bin/pytest tests/test_security.py -v
 
 # Run specific test
-auto-claude/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v
+apps/backend/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v
 
 # Skip slow tests
-auto-claude/.venv/bin/pytest tests/ -m "not slow"
+apps/backend/.venv/bin/pytest tests/ -m "not slow"
+
+# Or from root
+npm run test:backend
 ```
 
 ### Spec Validation
 ```bash
-python auto-claude/validate_spec.py --spec-dir auto-claude/specs/001-feature --checkpoint all
+python apps/backend/validate_spec.py --spec-dir apps/backend/specs/001-feature --checkpoint all
 ```
 
+### Releases
+```bash
+# 1. Bump version on your branch (creates commit, no tag)
+node scripts/bump-version.js patch   # 2.8.0 -> 2.8.1
+node scripts/bump-version.js minor   # 2.8.0 -> 2.9.0
+node scripts/bump-version.js major   # 2.8.0 -> 3.0.0
+
+# 2. Push and create PR to main
+git push origin your-branch
+gh pr create --base main
+
+# 3. Merge PR → GitHub Actions automatically:
+#    - Creates tag
+#    - Builds all platforms
+#    - Creates release with changelog
+#    - Updates README
+```
+
+See [RELEASE.md](RELEASE.md) for detailed release process documentation.
+
 ## Architecture
 
 ### Core Pipeline
@@ -93,21 +165,43 @@ python auto-claude/validate_spec.py --spec-dir auto-claude/specs/001-feature --c
 **Implementation (run.py → agent.py)** - Multi-session build:
 1. Planner Agent creates subtask-based implementation plan
 2. Coder Agent implements subtasks (can spawn subagents for parallel work)
-3. QA Reviewer validates acceptance criteria
-4. QA Fixer resolves issues in a loop
+3. QA Reviewer validates acceptance criteria (can perform E2E testing via Electron MCP for frontend changes)
+4. QA Fixer resolves issues in a loop (with E2E testing to verify fixes)
 
-### Key Components
+### Key Components (apps/backend/)
 
-- **client.py** - Claude SDK client with security hooks and tool permissions
-- **security.py** + **project_analyzer.py** - Dynamic command allowlisting based on detected project stack
-- **worktree.py** - Git worktree isolation for safe feature development
-- **memory.py** - File-based session memory (primary, always-available storage)
-- **graphiti_memory.py** - Optional graph-based cross-session memory with semantic search
-- **graphiti_providers.py** - Multi-provider factory for Graphiti (OpenAI, Anthropic, Azure, Ollama)
+**Core Infrastructure:**
+- **core/client.py** - Claude Agent SDK client factory with security hooks and tool permissions
+- **core/security.py** - Dynamic command allowlisting based on detected project stack
+- **core/auth.py** - OAuth token management for Claude SDK authentication
+- **agents/** - Agent implementations (planner, coder, qa_reviewer, qa_fixer)
+- **spec_agents/** - Spec creation agents (gatherer, researcher, writer, critic)
+
+**Memory & Context:**
+- **integrations/graphiti/** - Graphiti memory system (mandatory)
+  - `queries_pkg/graphiti.py` - Main GraphitiMemory class
+  - `queries_pkg/client.py` - LadybugDB client wrapper
+  - `queries_pkg/queries.py` - Graph query operations
+  - `queries_pkg/search.py` - Semantic search logic
+  - `queries_pkg/schema.py` - Graph schema definitions
 - **graphiti_config.py** - Configuration and validation for Graphiti integration
-- **linear_updater.py** - Optional Linear integration for progress tracking
+- **graphiti_providers.py** - Multi-provider factory (OpenAI, Anthropic, Azure, Ollama, Google AI)
+- **agents/memory_manager.py** - Session memory orchestration
 
-### Agent Prompts (auto-claude/prompts/)
+**Workspace & Security:**
+- **cli/worktree.py** - Git worktree isolation for safe feature development
+- **context/project_analyzer.py** - Project stack detection for dynamic tooling
+- **auto_claude_tools.py** - Custom MCP tools integration
+
+**Integrations:**
+- **linear_updater.py** - Optional Linear integration for progress tracking
+- **runners/github/** - GitHub Issues & PRs automation
+- **Electron MCP** - E2E testing integration for QA agents (Chrome DevTools Protocol)
+  - Enabled with `ELECTRON_MCP_ENABLED=true` in `.env`
+  - Allows QA agents to interact with running Electron app
+  - See "End-to-End Testing" section for details
+
+### Agent Prompts (apps/backend/prompts/)
 
 | Prompt | Purpose |
 |--------|---------|
@@ -124,7 +218,7 @@ python auto-claude/validate_spec.py --spec-dir auto-claude/specs/001-feature --c
 
 ### Spec Directory Structure
 
-Each spec in `auto-claude/specs/XXX-name/` contains:
+Each spec in `.auto-claude/specs/XXX-name/` contains:
 - `spec.md` - Feature specification
 - `requirements.json` - Structured user requirements
 - `context.json` - Discovered codebase context
@@ -155,6 +249,23 @@ main (user's branch)
 4. User runs `--merge` to add to their project
 5. User pushes to remote when ready
 
+### Contributing to Upstream
+
+**CRITICAL: When submitting PRs to AndyMik90/Auto-Claude, always target the `develop` branch, NOT `main`.**
+
+**Correct workflow for contributions:**
+1. Fetch upstream: `git fetch upstream`
+2. Create feature branch from upstream/develop: `git checkout -b fix/my-fix upstream/develop`
+3. Make changes and commit with sign-off: `git commit -s -m "fix: description"`
+4. Push to your fork: `git push origin fix/my-fix`
+5. Create PR targeting `develop`: `gh pr create --repo AndyMik90/Auto-Claude --base develop`
+
+**Verify before PR:**
+```bash
+# Ensure only your commits are included
+git log --oneline upstream/develop..HEAD
+```
+
 ### Security Model
 
 Three-layer defense:
@@ -164,38 +275,369 @@ Three-layer defense:
 
 Security profile cached in `.auto-claude-security.json`.
 
-### Memory System
+### Claude Agent SDK Integration
 
-Dual-layer memory architecture:
+**CRITICAL: Auto Claude uses the Claude Agent SDK for ALL AI interactions. Never use the Anthropic API directly.**
 
-**File-Based Memory (Primary)** - `memory.py`
-- Zero dependencies, always available
-- Human-readable files in `specs/XXX/memory/`
-- Session insights, patterns, gotchas, codebase map
+**Client Location:** `apps/backend/core/client.py`
 
-**Graphiti Memory (Optional Enhancement)** - `graphiti_memory.py`
-- Graph database with semantic search (FalkorDB)
-- Cross-session context retrieval
-- Multi-provider support (V2):
-  - LLM: OpenAI, Anthropic, Azure OpenAI, Ollama
-  - Embedders: OpenAI, Voyage AI, Azure OpenAI, Ollama
+The `create_client()` function creates a configured `ClaudeSDKClient` instance with:
+- Multi-layered security (sandbox, permissions, security hooks)
+- Agent-specific tool permissions (planner, coder, qa_reviewer, qa_fixer)
+- Dynamic MCP server integration based on project capabilities
+- Extended thinking token budget control
 
-Enable with: `GRAPHITI_ENABLED=true` + provider credentials. See `.env.example`.
+**Example usage in agents:**
+```python
+from core.client import create_client
 
-## Project Structure
+# Create SDK client (NOT raw Anthropic API client)
+client = create_client(
+    project_dir=project_dir,
+    spec_dir=spec_dir,
+    model="claude-sonnet-4-5-20250929",
+    agent_type="coder",
+    max_thinking_tokens=None  # or 5000/10000/16000
+)
 
-Auto Claude can be used in two ways:
-
-**As a standalone CLI tool** (original project):
-```bash
-python auto-claude/run.py --spec 001
+# Run agent session
+response = client.create_agent_session(
+    name="coder-agent-session",
+    starting_message="Implement the authentication feature"
+)
 ```
 
-**With the optional Electron frontend** (`auto-claude-ui/`):
-- Provides a GUI for task management and progress tracking
-- Wraps the CLI commands - the backend works independently
+**Why use the SDK:**
+- Pre-configured security (sandbox, allowlists, hooks)
+- Automatic MCP server integration (Context7, Linear, Graphiti, Electron, Puppeteer)
+- Tool permissions based on agent role
+- Session management and recovery
+- Unified API across all agent types
 
-**Directory layout:**
-- `auto-claude/` - Python backend/CLI (the framework code)
-- `auto-claude-ui/` - Optional Electron frontend
-- `.auto-claude/specs/` - Per-project data (specs, plans, QA reports) - gitignored
+**Where to find working examples:**
+- `apps/backend/agents/planner.py` - Planner agent
+- `apps/backend/agents/coder.py` - Coder agent
+- `apps/backend/agents/qa_reviewer.py` - QA reviewer
+- `apps/backend/agents/qa_fixer.py` - QA fixer
+- `apps/backend/spec_agents/` - Spec creation agents
+
+### Memory System
+
+**Graphiti Memory (Mandatory)** - `integrations/graphiti/`
+
+Auto Claude uses Graphiti as its primary memory system with embedded LadybugDB (no Docker required):
+
+- **Graph database with semantic search** - Knowledge graph for cross-session context
+- **Session insights** - Patterns, gotchas, discoveries automatically extracted
+- **Multi-provider support:**
+  - LLM: OpenAI, Anthropic, Azure OpenAI, Ollama, Google AI (Gemini)
+  - Embedders: OpenAI, Voyage AI, Azure OpenAI, Ollama, Google AI
+- **Modular architecture:** (`integrations/graphiti/queries_pkg/`)
+  - `graphiti.py` - Main GraphitiMemory class
+  - `client.py` - LadybugDB client wrapper
+  - `queries.py` - Graph query operations
+  - `search.py` - Semantic search logic
+  - `schema.py` - Graph schema definitions
+
+**Configuration:**
+- Set provider credentials in `apps/backend/.env` (see `.env.example`)
+- Required env vars: `GRAPHITI_ENABLED=true`, `ANTHROPIC_API_KEY` or other provider keys
+- Memory data stored in `.auto-claude/specs/XXX/graphiti/`
+
+**Usage in agents:**
+```python
+from integrations.graphiti.memory import get_graphiti_memory
+
+memory = get_graphiti_memory(spec_dir, project_dir)
+context = memory.get_context_for_session("Implementing feature X")
+memory.add_session_insight("Pattern: use React hooks for state")
+```
+
+## Development Guidelines
+
+### Frontend Internationalization (i18n)
+
+**CRITICAL: Always use i18n translation keys for all user-facing text in the frontend.**
+
+The frontend uses `react-i18next` for internationalization. All labels, buttons, messages, and user-facing text MUST use translation keys.
+
+**Translation file locations:**
+- `apps/frontend/src/shared/i18n/locales/en/*.json` - English translations
+- `apps/frontend/src/shared/i18n/locales/fr/*.json` - French translations
+
+**Translation namespaces:**
+- `common.json` - Shared labels, buttons, common terms
+- `navigation.json` - Sidebar navigation items, sections
+- `settings.json` - Settings page content
+- `dialogs.json` - Dialog boxes and modals
+- `tasks.json` - Task/spec related content
+- `errors.json` - Error messages (structured error information with substitution support)
+- `onboarding.json` - Onboarding wizard content
+- `welcome.json` - Welcome screen content
+
+**Usage pattern:**
+```tsx
+import { useTranslation } from 'react-i18next';
+
+// In component
+const { t } = useTranslation(['navigation', 'common']);
+
+// Use translation keys, NOT hardcoded strings
+<span>{t('navigation:items.githubPRs')}</span>  // ✅ CORRECT
+<span>GitHub PRs</span>                          // ❌ WRONG
+```
+
+**Error messages with substitution:**
+
+```tsx
+// For error messages with dynamic content, use interpolation
+const { t } = useTranslation(['errors']);
+
+// errors.json: { "task": { "parseError": "Failed to parse: {{error}}" } }
+<span>{t('errors:task.parseError', { error: errorMessage })}</span>
+```
+
+**When adding new UI text:**
+1. Add the translation key to ALL language files (at minimum: `en/*.json` and `fr/*.json`)
+2. Use `namespace:section.key` format (e.g., `navigation:items.githubPRs`)
+3. Never use hardcoded strings in JSX/TSX files
+
+### Cross-Platform Development
+
+**CRITICAL: This project supports Windows, macOS, and Linux. Platform-specific bugs are the #1 source of breakage.**
+
+#### The Problem
+
+When developers on macOS fix something using Mac-specific assumptions, it breaks on Windows. When Windows developers fix something, it breaks on macOS. This happens because:
+
+1. **CI only tested on Linux** - Platform-specific bugs weren't caught until after merge
+2. **Scattered platform checks** - `process.platform === 'win32'` checks were spread across 50+ files
+3. **Hardcoded paths** - Direct paths like `C:\Program Files` or `/opt/homebrew/bin` throughout code
+
+#### The Solution
+
+**1. Centralized Platform Abstraction**
+
+All platform-specific code now lives in dedicated modules:
+
+- **Frontend:** `apps/frontend/src/main/platform/`
+- **Backend:** `apps/backend/core/platform/`
+
+**Import from these modules instead of checking `process.platform` directly:**
+
+```typescript
+// ❌ WRONG - Direct platform check
+if (process.platform === 'win32') {
+  // Windows logic
+}
+
+// ✅ CORRECT - Use abstraction
+import { isWindows, getPathDelimiter } from './platform';
+
+if (isWindows()) {
+  // Windows logic
+}
+```
+
+**2. Multi-Platform CI**
+
+CI now tests on **all three platforms** (Windows, macOS, Linux). A PR cannot merge unless all platforms pass:
+
+```yaml
+# .github/workflows/ci.yml
+strategy:
+  matrix:
+    os: [ubuntu-latest, windows-latest, macos-latest]
+```
+
+**3. Platform Module API**
+
+The platform module provides:
+
+| Function | Purpose |
+|----------|---------|
+| `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |
+| `getPathDelimiter()` | Get `;` (Windows) or `:` (Unix) |
+| `getExecutableExtension()` | Get `.exe` (Windows) or `` (Unix) |
+| `findExecutable(name)` | Find executables across platforms |
+| `getBinaryDirectories()` | Get platform-specific bin paths |
+| `requiresShell(command)` | Check if .cmd/.bat needs shell on Windows |
+
+**4. Path Handling Best Practices**
+
+```typescript
+// ❌ WRONG - Hardcoded Windows path
+const claudePath = 'C:\\Program Files\\Claude\\claude.exe';
+
+// ❌ WRONG - Hardcoded macOS path
+const brewPath = '/opt/homebrew/bin/python3';
+
+// ❌ WRONG - Manual path joining
+const fullPath = dir + '/subdir/file.txt';
+
+// ✅ CORRECT - Use platform abstraction
+import { findExecutable, joinPaths } from './platform';
+
+const claudePath = await findExecutable('claude');
+const fullPath = joinPaths(dir, 'subdir', 'file.txt');
+```
+
+**5. Testing Platform-Specific Code**
+
+```typescript
+// Mock process.platform for testing
+import { isWindows } from './platform';
+
+// In tests, use jest.mock or similar
+jest.mock('./platform', () => ({
+  isWindows: () => true  // Simulate Windows
+}));
+```
+
+**6. When You Need Platform-Specific Code**
+
+If you must write platform-specific code:
+
+1. **Add it to the platform module** - Not scattered in your feature code
+2. **Write tests for all platforms** - Mock `process.platform` to test each case
+3. **Use feature detection** - Check for file/path existence, not just OS name
+4. **Document why** - Explain the platform difference in comments
+
+**7. Submitting Platform-Specific Fixes**
+
+When fixing a platform-specific bug:
+
+1. Ensure your fix doesn't break other platforms
+2. Test locally if you have access to other OSs
+3. Rely on CI to catch issues you can't test
+4. Consider adding a test that mocks other platforms
+
+**Example: Adding a New Tool Detection**
+
+```typescript
+// ✅ CORRECT - Add to platform/paths.ts
+export function getMyToolPaths(): string[] {
+  if (isWindows()) {
+    return [
+      joinPaths('C:', 'Program Files', 'MyTool', 'tool.exe'),
+      // ... more Windows paths
+    ];
+  }
+  return [
+    joinPaths('/usr', 'local', 'bin', 'mytool'),
+    // ... more Unix paths
+  ];
+}
+
+// ✅ CORRECT - Use in your code
+import { findExecutable, getMyToolPaths } from './platform';
+
+const toolPath = await findExecutable('mytool', getMyToolPaths());
+```
+
+### End-to-End Testing (Electron App)
+
+**IMPORTANT: When bug fixing or implementing new features in the frontend, AI agents can perform automated E2E testing using the Electron MCP server.**
+
+The Electron MCP server allows QA agents to interact with the running Electron app via Chrome DevTools Protocol:
+
+**Setup:**
+1. Start the Electron app with remote debugging enabled:
+   ```bash
+   npm run dev  # Already configured with --remote-debugging-port=9222
+   ```
+
+2. Enable Electron MCP in `apps/backend/.env`:
+   ```bash
+   ELECTRON_MCP_ENABLED=true
+   ELECTRON_DEBUG_PORT=9222  # Default port
+   ```
+
+**Available Testing Capabilities:**
+
+QA agents (`qa_reviewer` and `qa_fixer`) automatically get access to Electron MCP tools:
+
+1. **Window Management**
+   - `mcp__electron__get_electron_window_info` - Get info about running windows
+   - `mcp__electron__take_screenshot` - Capture screenshots for visual verification
+
+2. **UI Interaction**
+   - `mcp__electron__send_command_to_electron` with commands:
+     - `click_by_text` - Click buttons/links by visible text
+     - `click_by_selector` - Click elements by CSS selector
+     - `fill_input` - Fill form fields by placeholder or selector
+     - `select_option` - Select dropdown options
+     - `send_keyboard_shortcut` - Send keyboard shortcuts (Enter, Ctrl+N, etc.)
+     - `navigate_to_hash` - Navigate to hash routes (#settings, #create, etc.)
+
+3. **Page Inspection**
+   - `get_page_structure` - Get organized overview of page elements
+   - `debug_elements` - Get debugging info about buttons and forms
+   - `verify_form_state` - Check form state and validation
+   - `eval` - Execute custom JavaScript code
+
+4. **Logging**
+   - `mcp__electron__read_electron_logs` - Read console logs for debugging
+
+**Example E2E Test Flow:**
+
+```python
+# 1. Agent takes screenshot to see current state
+agent: "Take a screenshot to see the current UI"
+# Uses: mcp__electron__take_screenshot
+
+# 2. Agent inspects page structure
+agent: "Get page structure to find available buttons"
+# Uses: mcp__electron__send_command_to_electron (command: "get_page_structure")
+
+# 3. Agent clicks a button to navigate
+agent: "Click the 'Create New Spec' button"
+# Uses: mcp__electron__send_command_to_electron (command: "click_by_text", args: {text: "Create New Spec"})
+
+# 4. Agent fills out a form
+agent: "Fill the task description field"
+# Uses: mcp__electron__send_command_to_electron (command: "fill_input", args: {placeholder: "Describe your task", value: "Add login feature"})
+
+# 5. Agent submits and verifies
+agent: "Click Submit and verify success"
+# Uses: click_by_text → take_screenshot → verify result
+```
+
+**When to Use E2E Testing:**
+
+- **Bug Fixes**: Reproduce the bug, apply fix, verify it's resolved
+- **New Features**: Implement feature, test the UI flow end-to-end
+- **UI Changes**: Verify visual changes and interactions work correctly
+- **Form Validation**: Test form submission, validation, error handling
+
+**Configuration in `core/client.py`:**
+
+The client automatically enables Electron MCP tools for QA agents when:
+- Project is detected as Electron (`is_electron` capability)
+- `ELECTRON_MCP_ENABLED=true` is set
+- Agent type is `qa_reviewer` or `qa_fixer`
+
+**Note:** Screenshots are automatically compressed (1280x720, quality 60, JPEG) to stay under Claude SDK's 1MB JSON message buffer limit.
+
+## Running the Application
+
+**As a standalone CLI tool**:
+```bash
+cd apps/backend
+python run.py --spec 001
+```
+
+**With the Electron frontend**:
+```bash
+npm start        # Build and run desktop app
+npm run dev      # Run in development mode (includes --remote-debugging-port=9222 for E2E testing)
+```
+
+**For E2E Testing with QA Agents:**
+1. Start the Electron app: `npm run dev`
+2. Enable Electron MCP in `apps/backend/.env`: `ELECTRON_MCP_ENABLED=true`
+3. Run QA: `python run.py --spec 001 --qa`
+4. QA agents will automatically interact with the running app for testing
+
+**Project data storage:**
+- `.auto-claude/specs/` - Per-project data (specs, plans, QA reports, memory) - gitignored

CONTRIBUTING.md

@@ -4,57 +4,177 @@ Thank you for your interest in contributing to Auto Claude! This document provid
 
 ## Table of Contents
 
+- [Contributor License Agreement (CLA)](#contributor-license-agreement-cla)
 - [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
 - [Development Setup](#development-setup)
   - [Python Backend](#python-backend)
   - [Electron Frontend](#electron-frontend)
+- [Running from Source](#running-from-source)
 - [Pre-commit Hooks](#pre-commit-hooks)
 - [Code Style](#code-style)
 - [Testing](#testing)
 - [Continuous Integration](#continuous-integration)
 - [Git Workflow](#git-workflow)
+  - [Working with Forks](#working-with-forks)
+  - [Branch Overview](#branch-overview)
+  - [Main Branches](#main-branches)
+  - [Supporting Branches](#supporting-branches)
   - [Branch Naming](#branch-naming)
+  - [Where to Branch From](#where-to-branch-from)
+  - [Pull Request Targets](#pull-request-targets)
+  - [Release Process](#release-process-maintainers)
   - [Commit Messages](#commit-messages)
+  - [PR Hygiene](#pr-hygiene)
 - [Pull Request Process](#pull-request-process)
 - [Issue Reporting](#issue-reporting)
 - [Architecture Overview](#architecture-overview)
 
+## Contributor License Agreement (CLA)
+
+All contributors must sign our Contributor License Agreement (CLA) before contributions can be accepted.
+
+### Why We Require a CLA
+
+Auto Claude is currently licensed under AGPL-3.0. The CLA ensures the project has proper licensing flexibility should we introduce additional licensing options (such as commercial/enterprise licenses) in the future.
+
+You retain full copyright ownership of your contributions.
+
+### How to Sign
+
+1. Open a Pull Request
+2. The CLA bot will automatically comment with instructions
+3. Comment on the PR with: `I have read the CLA Document and I hereby sign the CLA`
+4. Done - you only need to sign once, and it applies to all future contributions
+
+Read the full CLA here: [CLA.md](CLA.md)
+
 ## Prerequisites
 
 Before contributing, ensure you have the following installed:
 
-- **Python 3.8+** - For the backend framework
-- **Node.js 18+** - For the Electron frontend
-- **pnpm** - Package manager for the frontend (`npm install -g pnpm`)
+- **Python 3.12+** - For the backend framework
+- **Node.js 24+** - For the Electron frontend
+- **npm 10+** - Package manager for the frontend (comes with Node.js)
 - **uv** (recommended) or **pip** - Python package manager
+- **CMake** - Required for building native dependencies (e.g., LadybugDB)
 - **Git** - Version control
-- **Docker** (optional) - For running FalkorDB if using Graphiti memory
+
+### Installing Python 3.12
+
+**Windows:**
+```bash
+winget install Python.Python.3.12
+```
+
+**macOS:**
+```bash
+brew install python@3.12
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt install python3.12 python3.12-venv
+```
+
+**Linux (Fedora):**
+```bash
+sudo dnf install python3.12
+```
+
+### Installing Node.js 24+
+
+**Windows:**
+```bash
+winget install OpenJS.NodeJS.LTS
+```
+
+**macOS:**
+```bash
+brew install node@24
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+sudo apt install -y nodejs
+```
+
+**Linux (Fedora):**
+```bash
+sudo dnf install nodejs npm
+```
+
+### Installing CMake
+
+**Windows:**
+```bash
+winget install Kitware.CMake
+```
+
+**macOS:**
+```bash
+brew install cmake
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+sudo apt install cmake
+```
+
+**Linux (Fedora):**
+```bash
+sudo dnf install cmake
+```
+
+## Quick Start
+
+The fastest way to get started:
+
+```bash
+# Clone the repository
+git clone https://github.com/AndyMik90/Auto-Claude.git
+cd Auto-Claude
+
+# Install all dependencies (cross-platform)
+npm run install:all
+
+# Run in development mode
+npm run dev
+
+# Or build and run production
+npm start
+```
 
 ## Development Setup
 
 The project consists of two main components:
 
-1. **Python Backend** (`auto-claude/`) - The core autonomous coding framework
-2. **Electron Frontend** (`auto-claude-ui/`) - Optional desktop UI
+1. **Python Backend** (`apps/backend/`) - The core autonomous coding framework
+2. **Electron Frontend** (`apps/frontend/`) - Optional desktop UI
 
 ### Python Backend
 
+The recommended way is to use `npm run install:backend` (or `npm run install:all` from the root), which automatically installs both runtime and test dependencies. You can also set up manually:
+
 ```bash
-# Navigate to the auto-claude directory
-cd auto-claude
+# Navigate to the backend directory
+cd apps/backend
 
-# Create virtual environment (using uv - recommended)
-uv venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-uv pip install -r requirements.txt
+# Create virtual environment
+# Windows:
+py -3.12 -m venv .venv
+.venv\Scripts\activate
 
-# Or using standard Python
-python3 -m venv .venv
+# macOS/Linux:
+python3.12 -m venv .venv
 source .venv/bin/activate
+
+# Install dependencies
 pip install -r requirements.txt
 
 # Install test dependencies
-pip install -r ../tests/requirements-test.txt
+pip install -r ../../tests/requirements-test.txt
 
 # Set up environment
 cp .env.example .env
@@ -64,22 +184,75 @@ cp .env.example .env
 ### Electron Frontend
 
 ```bash
-# Navigate to the UI directory
-cd auto-claude-ui
+# Navigate to the frontend directory
+cd apps/frontend
 
 # Install dependencies
-pnpm install
+npm install
 
 # Start development server
-pnpm dev
+npm run dev
 
 # Build for production
-pnpm build
+npm run build
 
 # Package for distribution
-pnpm package
+npm run package
 ```
 
+## Running from Source
+
+If you want to run Auto Claude from source (for development or testing unreleased features), follow these steps:
+
+### Step 1: Clone and Set Up
+
+```bash
+git clone https://github.com/AndyMik90/Auto-Claude.git
+cd Auto-Claude/apps/backend
+
+# Using uv (recommended)
+uv venv && uv pip install -r requirements.txt
+
+# Or using standard Python
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+
+# Set up environment
+cd apps/backend
+cp .env.example .env
+# Edit .env and add your CLAUDE_CODE_OAUTH_TOKEN (get it via: claude setup-token)
+```
+
+### Step 2: Run the Desktop UI
+
+```bash
+cd ../frontend
+
+# Install dependencies
+npm install
+
+# Development mode (hot reload)
+npm run dev
+
+# Or production build
+npm run build && npm run start
+```
+
+<details>
+<summary><b>Windows users:</b> If installation fails with node-gyp errors, click here</summary>
+
+Auto Claude automatically downloads prebuilt binaries for Windows. If prebuilts aren't available for your Electron version yet, you'll need Visual Studio Build Tools:
+
+1. Download [Visual Studio Build Tools 2022](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+2. Select "Desktop development with C++" workload
+3. In "Individual Components", add "MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs"
+4. Restart terminal and run `npm install` again
+
+</details>
+
+> **Note:** For regular usage, we recommend downloading the pre-built releases from [GitHub Releases](https://github.com/AndyMik90/Auto-Claude/releases). Running from source is primarily for contributors and those testing unreleased features.
+
 ## Pre-commit Hooks
 
 We use [pre-commit](https://pre-commit.com/) to run linting and formatting checks before each commit. This ensures code quality and consistency across the project.
@@ -100,10 +273,10 @@ When you commit, the following checks run automatically:
 
 | Check | Scope | Description |
 |-------|-------|-------------|
-| **ruff** | `auto-claude/` | Python linter with auto-fix |
-| **ruff-format** | `auto-claude/` | Python code formatter |
-| **eslint** | `auto-claude-ui/` | TypeScript/React linter |
-| **typecheck** | `auto-claude-ui/` | TypeScript type checking |
+| **ruff** | `apps/backend/` | Python linter with auto-fix |
+| **ruff-format** | `apps/backend/` | Python code formatter |
+| **eslint** | `apps/frontend/` | TypeScript/React linter |
+| **typecheck** | `apps/frontend/` | TypeScript type checking |
 | **trailing-whitespace** | All files | Removes trailing whitespace |
 | **end-of-file-fixer** | All files | Ensures files end with newline |
 | **check-yaml** | All files | Validates YAML syntax |
@@ -160,7 +333,7 @@ def gnc(sd):
 ### TypeScript/React
 
 - Use TypeScript strict mode
-- Follow the existing component patterns in `auto-claude-ui/src/`
+- Follow the existing component patterns in `apps/frontend/src/`
 - Use functional components with hooks
 - Prefer named exports over default exports
 - Use the UI components from `src/renderer/components/ui/`
@@ -185,25 +358,88 @@ export default function(props) {
 - End files with a newline
 - Keep line length under 100 characters when practical
 
+### File Encoding (Python)
+
+**Always specify `encoding="utf-8"` for text file operations** to ensure Windows compatibility.
+
+Windows Python defaults to `cp1252` encoding instead of UTF-8, causing errors with:
+- Emoji (🚀, ✅, ❌)
+- International characters (ñ, é, 中文, العربية)
+- Special symbols (™, ©, ®)
+
+**DO:**
+
+```python
+# Reading files
+with open(path, encoding="utf-8") as f:
+    content = f.read()
+
+# Writing files
+with open(path, "w", encoding="utf-8") as f:
+    f.write(content)
+
+# Path methods
+from pathlib import Path
+content = Path(file).read_text(encoding="utf-8")
+Path(file).write_text(content, encoding="utf-8")
+
+# JSON files - reading
+import json
+with open(path, encoding="utf-8") as f:
+    data = json.load(f)
+
+# JSON files - writing
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+```
+
+**DON'T:**
+
+```python
+# Wrong - platform-dependent encoding
+with open(path) as f:
+    content = f.read()
+
+# Wrong - Path methods without encoding
+content = Path(file).read_text()
+
+# Wrong - encoding on json.dump (not open!)
+json.dump(data, f, encoding="utf-8")  # ERROR
+```
+
+**Binary files - NO encoding:**
+
+```python
+with open(path, "rb") as f:  # Correct
+    data = f.read()
+```
+
+Our pre-commit hooks automatically check for missing encoding parameters. See [PR #782](https://github.com/AndyMik90/Auto-Claude/pull/782) for the comprehensive encoding fix and [guides/windows-development.md](guides/windows-development.md) for Windows-specific development guidance.
+
 ## Testing
 
 ### Python Tests
 
 ```bash
-# Run all tests
-pytest tests/ -v
+# Run all tests (from repository root)
+npm run test:backend
+
+# Or manually with pytest
+cd apps/backend
+.venv/Scripts/pytest.exe ../tests -v          # Windows
+.venv/bin/pytest ../tests -v                   # macOS/Linux
 
 # Run a specific test file
-pytest tests/test_security.py -v
+npm run test:backend -- tests/test_security.py -v
 
 # Run a specific test
-pytest tests/test_security.py::test_bash_command_validation -v
+npm run test:backend -- tests/test_security.py::test_bash_command_validation -v
 
 # Skip slow tests
-pytest tests/ -m "not slow"
+npm run test:backend -- -m "not slow"
 
 # Run with coverage
-pytest tests/ --cov=auto-claude --cov-report=html
+pytest tests/ --cov=apps/backend --cov-report=html
 ```
 
 Test configuration is in `tests/pytest.ini`.
@@ -211,26 +447,26 @@ Test configuration is in `tests/pytest.ini`.
 ### Frontend Tests
 
 ```bash
-cd auto-claude-ui
+cd apps/frontend
 
 # Run unit tests
-pnpm test
+npm test
 
 # Run tests in watch mode
-pnpm test:watch
+npm run test:watch
 
 # Run with coverage
-pnpm test:coverage
+npm run test:coverage
 
 # Run E2E tests (requires built app)
-pnpm build
-pnpm test:e2e
+npm run build
+npm run test:e2e
 
 # Run linting
-pnpm lint
+npm run lint
 
 # Run type checking
-pnpm typecheck
+npm run typecheck
 ```
 
 ### Testing Requirements
@@ -252,7 +488,6 @@ All pull requests and pushes to `main` trigger automated CI checks via GitHub Ac
 |----------|---------|----------------|
 | **CI** | Push to `main`, PRs | Python tests (3.11 & 3.12), Frontend tests |
 | **Lint** | Push to `main`, PRs | Ruff (Python), ESLint + TypeScript (Frontend) |
-| **Test on Tag** | Version tags (`v*`) | Full test suite before release |
 
 ### PR Requirements
 
@@ -268,19 +503,116 @@ Before a PR can be merged:
 
 ```bash
 # Python tests
-cd auto-claude
+cd apps/backend
 source .venv/bin/activate
-pytest ../tests/ -v
+pytest ../../tests/ -v
 
 # Frontend tests
-cd auto-claude-ui
-pnpm test
-pnpm lint
-pnpm typecheck
+cd apps/frontend
+npm test
+npm run lint
+npm run typecheck
 ```
 
 ## Git Workflow
 
+We use a **Git Flow** branching strategy to manage releases and parallel development.
+
+### Working with Forks
+
+When contributing to Auto Claude, you'll typically fork the repository first. Proper fork configuration is essential to avoid sync issues.
+
+#### Initial Fork Setup
+
+```bash
+# 1. Fork on GitHub (click the Fork button on the repo page)
+
+# 2. Clone YOUR fork (not the original repo)
+git clone https://github.com/YOUR-USERNAME/Auto-Claude.git
+cd Auto-Claude
+
+# 3. Verify your remotes point to YOUR fork
+git remote -v
+# Should show:
+# origin  https://github.com/YOUR-USERNAME/Auto-Claude.git (fetch)
+# origin  https://github.com/YOUR-USERNAME/Auto-Claude.git (push)
+
+# 4. Add upstream remote to sync with the original repo
+git remote add upstream https://github.com/AndyMik90/Auto-Claude.git
+```
+
+#### Keeping Your Fork Updated
+
+```bash
+# Fetch latest changes from upstream
+git fetch upstream
+
+# Sync your develop branch with upstream
+git checkout develop
+git merge upstream/develop
+git push origin develop
+```
+
+#### Converting a Fork to Standalone
+
+> ⚠️ **Common Issue:** After making a fork standalone (e.g., disconnecting from the original repo on GitHub), your local git configuration may still reference the original forked repository, causing push/pull issues.
+
+If you convert your fork to a standalone repository:
+
+```bash
+# 1. Update origin to point to your standalone repo
+git remote set-url origin https://github.com/YOUR-USERNAME/Your-Standalone-Repo.git
+
+# 2. Remove the upstream remote (no longer applicable)
+git remote remove upstream
+
+# 3. Verify your configuration
+git remote -v
+# Should only show your standalone repo as origin
+
+# 4. Update your default branch tracking if needed
+git branch --set-upstream-to=origin/main main
+git branch --set-upstream-to=origin/develop develop
+```
+
+#### Troubleshooting Fork Issues
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| `Permission denied` on push | Origin points to upstream repo | `git remote set-url origin <your-fork-url>` |
+| `Repository not found` | Fork was deleted or made standalone | Update remote URL to current repo location |
+| Can't push to develop | Local branch tracks wrong remote | `git branch --set-upstream-to=origin/develop` |
+| Commits show wrong author | Git config not set | `git config user.email "you@example.com"` |
+
+### Branch Overview
+
+```
+main (stable)          ← Only released, tested code (tagged versions)
+  │
+develop                ← Integration branch - all PRs merge here first
+  │
+├── feature/xxx        ← New features
+├── fix/xxx            ← Bug fixes
+├── release/vX.Y.Z     ← Release preparation
+└── hotfix/xxx         ← Emergency production fixes
+```
+
+### Main Branches
+
+| Branch | Purpose | Protected |
+|--------|---------|-----------|
+| `main` | Production-ready code. Only receives merges from `release/*` or `hotfix/*` branches. Every merge is tagged (v2.7.0, v2.8.0, etc.) | ✅ Yes |
+| `develop` | Integration branch where all features and fixes are combined. This is the default target for all PRs. | ✅ Yes |
+
+### Supporting Branches
+
+| Branch Type | Branch From | Merge To | Purpose |
+|-------------|-------------|----------|---------|
+| `feature/*` | `develop` | `develop` | New features and enhancements |
+| `fix/*` | `develop` | `develop` | Bug fixes (non-critical) |
+| `release/*` | `develop` | `main` + `develop` | Release preparation and final testing |
+| `hotfix/*` | `main` | `main` + `develop` | Critical production bug fixes |
+
 ### Branch Naming
 
 Use descriptive branch names with a prefix indicating the type of change:
@@ -289,10 +621,146 @@ Use descriptive branch names with a prefix indicating the type of change:
 |--------|---------|---------|
 | `feature/` | New feature | `feature/add-dark-mode` |
 | `fix/` | Bug fix | `fix/memory-leak-in-worker` |
+| `hotfix/` | Urgent production fix | `hotfix/critical-crash-fix` |
 | `docs/` | Documentation | `docs/update-readme` |
 | `refactor/` | Code refactoring | `refactor/simplify-auth-flow` |
 | `test/` | Test additions/fixes | `test/add-integration-tests` |
 | `chore/` | Maintenance tasks | `chore/update-dependencies` |
+| `release/` | Release preparation | `release/v2.8.0` |
+| `hotfix/` | Emergency fixes | `hotfix/critical-auth-bug` |
+
+### Where to Branch From
+
+```bash
+# For features and bug fixes - ALWAYS branch from develop
+git checkout develop
+git pull origin develop
+git checkout -b feature/my-new-feature
+
+# For hotfixes only - branch from main
+git checkout main
+git pull origin main
+git checkout -b hotfix/critical-fix
+```
+
+### Pull Request Targets
+
+> ⚠️ **Important:** All PRs should target `develop`, NOT `main`!
+
+| Your Branch Type | Target Branch |
+|------------------|---------------|
+| `feature/*` | `develop` |
+| `fix/*` | `develop` |
+| `docs/*` | `develop` |
+| `refactor/*` | `develop` |
+| `test/*` | `develop` |
+| `chore/*` | `develop` |
+| `hotfix/*` | `main` (maintainers only) |
+| `release/*` | `main` (maintainers only) |
+
+### Release Process (Maintainers)
+
+When ready to release a new version:
+
+```bash
+# 1. Create release branch from develop
+git checkout develop
+git pull origin develop
+git checkout -b release/v2.8.0
+
+# 2. Update version numbers, CHANGELOG, final fixes only
+# No new features allowed in release branches!
+
+# 3. Merge to main and tag
+git checkout main
+git merge release/v2.8.0
+git tag v2.8.0
+git push origin main --tags
+
+# 4. Merge back to develop (important!)
+git checkout develop
+git merge release/v2.8.0
+git push origin develop
+
+# 5. Delete release branch
+git branch -d release/v2.8.0
+git push origin --delete release/v2.8.0
+```
+
+### Beta Release Process (Maintainers)
+
+Beta releases allow users to test new features before they're included in a stable release. Beta releases are published from the `develop` branch.
+
+**Creating a Beta Release:**
+
+1. Go to **Actions** → **Beta Release** workflow in GitHub
+2. Click **Run workflow**
+3. Enter the beta version (e.g., `2.8.0-beta.1`)
+4. Optionally enable dry run to test without publishing
+5. Click **Run workflow**
+
+The workflow will:
+- Validate the version format
+- Update `package.json` on develop
+- Create and push a tag (e.g., `v2.8.0-beta.1`)
+- Build installers for all platforms
+- Create a GitHub pre-release
+
+**Version Format:**
+```
+X.Y.Z-beta.N   (e.g., 2.8.0-beta.1, 2.8.0-beta.2)
+X.Y.Z-alpha.N  (e.g., 2.8.0-alpha.1)
+X.Y.Z-rc.N     (e.g., 2.8.0-rc.1)
+```
+
+**For Users:**
+Users can opt into beta updates in Settings → Updates → "Beta Updates" toggle. When enabled, the app will check for and install beta versions. Users can switch back to stable at any time.
+
+### Hotfix Workflow
+
+For urgent production fixes that can't wait for the normal release cycle:
+
+**1. Create hotfix from main**
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/150-critical-fix
+```
+
+**2. Fix the issue**
+
+```bash
+# ... make changes ...
+git commit -m "hotfix: fix critical crash on startup"
+```
+
+**3. Open PR to main (fast-track review)**
+
+```bash
+gh pr create --base main --title "hotfix: fix critical crash on startup"
+```
+
+**4. After merge to main, sync to develop**
+
+```bash
+git checkout develop
+git pull origin develop
+git merge main
+git push origin develop
+```
+
+```
+main ─────●─────●─────●─────●───── (production)
+          ↑     ↑     ↑     ↑
+develop ──●─────●─────●─────●───── (integration)
+          ↑     ↑     ↑
+feature/123 ────●
+feature/124 ──────────●
+hotfix/125 ─────────────────●───── (from main, merge to both)
+```
+
+> **Note:** Hotfixes branch FROM `main` and merge TO `main` first, then sync back to `develop` to keep branches aligned.
 
 ### Commit Messages
 
@@ -324,19 +792,60 @@ git commit -m "WIP"
 - **body**: Detailed explanation if needed (wrap at 72 chars)
 - **footer**: Reference issues, breaking changes
 
+### PR Hygiene
+
+**Rebasing:**
+- **Rebase onto develop** before opening a PR and before merge to maintain linear history
+- Use `git fetch origin && git rebase origin/develop` to sync your branch
+- Use `--force-with-lease` when force-pushing rebased branches (safer than `--force`)
+- Notify reviewers after force-pushing during active review
+- **Exception:** Never rebase after PR is approved and others have reviewed specific commits
+
+**Commit organization:**
+- **Squash fixup commits** (typos, "oops", review feedback) into their parent commits
+- **Keep logically distinct changes** as separate commits that could be reverted independently
+- Each commit should compile and pass tests independently
+- No "WIP", "fix tests", or "lint" commits in final PR - squash these
+
+**Before requesting review:**
+```bash
+# Ensure up-to-date with develop
+git fetch origin && git rebase origin/develop
+
+# Clean up commit history (squash fixups, reword messages)
+git rebase -i origin/develop
+
+# Force push with safety check
+git push --force-with-lease
+
+# Verify everything works
+npm run test:backend
+cd apps/frontend && npm test && npm run lint && npm run typecheck
+```
+
+**PR size:**
+- Keep PRs small (<400 lines changed ideally)
+- Split large features into stacked PRs if possible
+
 ## Pull Request Process
 
-1. **Fork the repository** and create your branch from `main`
+1. **Fork the repository** and create your branch from `develop` (not main!)
+
+   ```bash
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/your-feature-name
+   ```
 
 2. **Make your changes** following the code style guidelines
 
 3. **Test thoroughly**:
    ```bash
-   # Python
-   pytest tests/ -v
+   # Python (from repository root)
+   npm run test:backend
 
    # Frontend
-   cd auto-claude-ui && pnpm test && pnpm lint && pnpm typecheck
+   cd apps/frontend && npm test && npm run lint && npm run typecheck
    ```
 
 4. **Update documentation** if your changes affect:
@@ -395,7 +904,7 @@ When requesting a feature:
 
 Auto Claude consists of two main parts:
 
-### Python Backend (`auto-claude/`)
+### Python Backend (`apps/backend/`)
 
 The core autonomous coding framework:
 
@@ -405,9 +914,9 @@ The core autonomous coding framework:
 - **Memory**: `memory.py` (file-based), `graphiti_memory.py` (graph-based)
 - **QA**: `qa_loop.py`, `prompts/qa_*.md`
 
-### Electron Frontend (`auto-claude-ui/`)
+### Electron Frontend (`apps/frontend/`)
 
-Optional desktop interface:
+Desktop interface:
 
 - **Main Process**: `src/main/` - Electron main process, IPC handlers
 - **Renderer**: `src/renderer/` - React UI components

LICENSE

@@ -658,4 +658,4 @@ specific requirements.
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.

README.md

@@ -1,300 +1,222 @@
 # Auto Claude
 
-Your AI coding companion. Build features, fix bugs, and ship faster — with autonomous agents that plan, code, and validate for you.
+**Autonomous multi-agent coding framework that plans, builds, and validates software for you.**
 
 ![Auto Claude Kanban Board](.github/assets/Auto-Claude-Kanban.png)
 
-[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/maj9EWmY)
-
-## What It Does ✨
-
-**Auto Claude is a desktop app that supercharges your AI coding workflow.** Whether you're a vibe coder just getting started or an experienced developer, Auto Claude meets you where you are.
-
-- **Autonomous Tasks** — Describe what you want to build, and agents handle planning, coding, and validation while you focus on other work
-- **Agent Terminals** — Run Claude Code in up to 12 terminals with a clean layout, smart naming based on context, and one-click task context injection
-- **Safe by Default** — All work happens in git worktrees, keeping your main branch undisturbed until you're ready to merge
-- **Self-Validating** — Built-in QA agents check their own work before you review
-
-**The result?** 10x your output while maintaining code quality.
-
-## Key Features
-
-- **Parallel Agents**: Run multiple builds simultaneously while you focus on other work
-- **Context Engineering**: Agents understand your codebase structure before writing code
-- **Self-Validating**: Built-in QA loop catches issues before you review
-- **Isolated Workspaces**: All work happens in git worktrees — your code stays safe
-- **AI Merge Resolution**: Intelligent conflict resolution when merging back to main — no manual conflict fixing
-- **Memory Layer**: Agents remember insights across sessions for smarter decisions
-- **Cross-Platform**: Desktop app runs on Mac, Windows, and Linux
-- **Any Project Type**: Build web apps, APIs, CLIs — works with any software project
-
-## 🚀 Quick Start (Desktop UI)
-
-The Desktop UI is the recommended way to use Auto Claude. It provides visual task management, real-time progress tracking, and a Kanban board interface.
-
-### Prerequisites
-
-1. **Node.js 18+** - [Download Node.js](https://nodejs.org/)
-2. **Python 3.9+** - [Download Python](https://www.python.org/downloads/)
-3. **Docker Desktop** - Required for the Memory Layer
-4. **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
-5. **Claude Subscription** - Requires [Claude Pro or Max](https://claude.ai/upgrade) for Claude Code access
+[![License](https://img.shields.io/badge/license-AGPL--3.0-green?style=flat-square)](./agpl-3.0.txt)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/KCXaPBr4Dj)
+[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@AndreMikalsen)
+[![CI](https://img.shields.io/github/actions/workflow/status/AndyMik90/Auto-Claude/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AndyMik90/Auto-Claude/actions)
 
 ---
 
-### Installing Docker Desktop
+## Download
 
-Docker runs the FalkorDB database that powers Auto Claude's cross-session memory.
+### Stable Release
 
-| Operating System | Download Link |
-|------------------|---------------|
-| **Mac (Apple Silicon M1/M2/M3/M4)** | [Download for Apple Chip](https://desktop.docker.com/mac/main/arm64/Docker.dmg) |
-| **Mac (Intel)** | [Download for Intel Chip](https://desktop.docker.com/mac/main/amd64/Docker.dmg) |
-| **Windows** | [Download for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe) |
-| **Linux** | [Installation Guide](https://docs.docker.com/desktop/install/linux-install/) |
+<!-- STABLE_VERSION_BADGE -->
+[![Stable](https://img.shields.io/badge/stable-2.7.4-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.4)
+<!-- STABLE_VERSION_BADGE_END -->
 
-> **Not sure which Mac?** Click the Apple menu (🍎) → "About This Mac". Look for "Chip" - M1/M2/M3/M4 = Apple Silicon, otherwise Intel.
+<!-- STABLE_DOWNLOADS -->
+| Platform | Download |
+|----------|----------|
+| **Windows** | [Auto-Claude-2.7.4-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.4-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.4-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.4-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.4-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.4-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-linux-x86_64.flatpak) |
+<!-- STABLE_DOWNLOADS_END -->
 
-**After installing:** Open Docker Desktop and wait for the whale icon (🐳) to appear in your menu bar/system tray.
+### Beta Release
 
-> **Using the Desktop UI?** It automatically detects Docker status and offers one-click FalkorDB setup. No terminal commands needed!
+> ⚠️ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)
 
-📚 **For detailed installation steps, troubleshooting, and advanced configuration, see [guides/DOCKER-SETUP.md](guides/DOCKER-SETUP.md)**
+<!-- BETA_VERSION_BADGE -->
+[![Beta](https://img.shields.io/badge/beta-2.7.2--beta.10-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2-beta.10)
+<!-- BETA_VERSION_BADGE_END -->
+
+<!-- BETA_DOWNLOADS -->
+| Platform | Download |
+|----------|----------|
+| **Windows** | [Auto-Claude-2.7.2-beta.10-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.2-beta.10-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.2-beta.10-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak) |
+<!-- BETA_DOWNLOADS_END -->
+
+> All releases include SHA256 checksums and VirusTotal scan results for security verification.
 
 ---
 
-### Step 1: Set Up the Python Backend
+## Requirements
 
-The Desktop UI runs Python scripts behind the scenes. Set up the Python environment:
-
-```bash
-cd auto-claude
-
-# Using uv (recommended)
-uv venv && uv pip install -r requirements.txt
-
-# Or using standard Python
-python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
-```
-
-### Step 2: Start the Memory Layer
-
-The Auto Claude Memory Layer provides cross-session context retention using a graph database:
-
-```bash
-# Make sure Docker Desktop is running, then:
-docker-compose up -d falkordb
-```
-
-### Step 3: Install and Launch the Desktop UI
-
-```bash
-cd auto-claude-ui
-
-# Install dependencies (pnpm recommended, npm works too)
-pnpm install
-# or: npm install
-
-# Build and start the application
-pnpm run build && pnpm run start
-# or: npm run build && npm run start
-```
-
-### Step 4: Start Building
-
-1. Add your project in the UI
-2. Create a new task describing what you want to build
-3. Watch as Auto Claude creates a spec, plans, and implements your feature
-4. Review changes and merge when satisfied
+- **Claude Pro/Max subscription** - [Get one here](https://claude.ai/upgrade)
+- **Claude Code CLI** - `npm install -g @anthropic-ai/claude-code`
+- **Git repository** - Your project must be initialized as a git repo
 
 ---
 
-## 🎯 Features
+## Quick Start
+
+1. **Download and install** the app for your platform
+2. **Open your project** - Select a git repository folder
+3. **Connect Claude** - The app will guide you through OAuth setup
+4. **Create a task** - Describe what you want to build
+5. **Watch it work** - Agents plan, code, and validate autonomously
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Autonomous Tasks** | Describe your goal; agents handle planning, implementation, and validation |
+| **Parallel Execution** | Run multiple builds simultaneously with up to 12 agent terminals |
+| **Isolated Workspaces** | All changes happen in git worktrees - your main branch stays safe |
+| **Self-Validating QA** | Built-in quality assurance loop catches issues before you review |
+| **AI-Powered Merge** | Automatic conflict resolution when integrating back to main |
+| **Memory Layer** | Agents retain insights across sessions for smarter builds |
+| **GitHub/GitLab Integration** | Import issues, investigate with AI, create merge requests |
+| **Linear Integration** | Sync tasks with Linear for team progress tracking |
+| **Cross-Platform** | Native desktop apps for Windows, macOS, and Linux |
+| **Auto-Updates** | App updates automatically when new versions are released |
+
+---
+
+## Interface
 
 ### Kanban Board
-
-Plan tasks and let AI handle the planning, coding, and validation — all in a visual interface. Track progress from "Planning" to "Done" while agents work autonomously.
+Visual task management from planning through completion. Create tasks and monitor agent progress in real-time.
 
 ### Agent Terminals
+AI-powered terminals with one-click task context injection. Spawn multiple agents for parallel work.
 
-Spawn up to 12 AI-powered terminals for hands-on coding. Inject task context with a click, reference files from your project, and work rapidly across multiple sessions.
-
-**Power users:** Connect multiple Claude Code subscriptions to run even more agents in parallel — perfect for teams or heavy workloads.
-
-![Auto Claude Agent Terminals](.github/assets/Auto-Claude-Agents-terminals.png)
-
-### Insights
-
-Have a conversation about your project in a ChatGPT-style interface. Ask questions, get explanations, and explore your codebase through natural dialogue.
+![Agent Terminals](.github/assets/Auto-Claude-Agents-terminals.png)
 
 ### Roadmap
+AI-assisted feature planning with competitor analysis and audience targeting.
 
-Based on your target audience, AI anticipates and plans the most impactful features you should focus on. Prioritize what matters most to your users.
+![Roadmap](.github/assets/Auto-Claude-roadmap.png)
 
-![Auto Claude Roadmap](.github/assets/Auto-Claude-roadmap.png)
-
-### Ideation
-
-Let AI help you create a project that shines. Rapidly understand your codebase and discover:
-- Code improvements and refactoring opportunities
-- Performance bottlenecks
-- Security vulnerabilities
-- Documentation gaps
-- UI/UX enhancements
-- Overall code quality issues
-
-### Changelog
-
-Write professional changelogs effortlessly. Generate release notes from completed Auto Claude tasks or integrate with GitHub to create masterclass changelogs automatically.
-
-### Context
-
-See exactly what Auto Claude understands about your project — the tech stack, file structure, patterns, and insights it uses to write better code.
-
-### AI Merge Resolution
-
-When your main branch evolves while a build is in progress, Auto Claude automatically resolves merge conflicts using AI — no manual `<<<<<<< HEAD` fixing required.
-
-**How it works:**
-1. **Git Auto-Merge First** — Simple non-conflicting changes merge instantly without AI
-2. **Conflict-Only AI** — For actual conflicts, AI receives only the specific conflict regions (not entire files), achieving ~98% prompt reduction
-3. **Parallel Processing** — Multiple conflicting files resolve simultaneously for faster merges
-4. **Syntax Validation** — Every merge is validated before being applied
-
-**The result:** A build that was 50+ commits behind main merges in seconds instead of requiring manual conflict resolution.
+### Additional Features
+- **Insights** - Chat interface for exploring your codebase
+- **Ideation** - Discover improvements, performance issues, and vulnerabilities
+- **Changelog** - Generate release notes from completed tasks
 
 ---
 
-## CLI Usage (Terminal-Only)
-
-For terminal-based workflows, headless servers, or CI/CD integration, see **[guides/CLI-USAGE.md](guides/CLI-USAGE.md)**.
-
-## ⚙️ How It Works
-
-Auto Claude focuses on three core principles: **context engineering** (understanding your codebase before writing code), **good coding standards** (following best practices and patterns), and **validation logic** (ensuring code works before you see it).
-
-### The Agent Pipeline
-
-**Phase 1: Spec Creation** (3-8 phases based on complexity)
-
-Before any code is written, agents gather context and create a detailed specification:
-
-1. **Discovery** — Analyzes your project structure and tech stack
-2. **Requirements** — Gathers what you want to build through interactive conversation
-3. **Research** — Validates external integrations against real documentation
-4. **Context Discovery** — Finds relevant files in your codebase
-5. **Spec Writer** — Creates a comprehensive specification document
-6. **Spec Critic** — Self-critiques using extended thinking to find issues early
-7. **Planner** — Breaks work into subtasks with dependencies
-8. **Validation** — Ensures all outputs are valid before proceeding
-
-**Phase 2: Implementation**
-
-With a validated spec, coding agents execute the plan:
-
-1. **Planner Agent** — Creates subtask-based implementation plan
-2. **Coder Agent** — Implements subtasks one-by-one with verification
-3. **QA Reviewer** — Validates all acceptance criteria
-4. **QA Fixer** — Fixes issues in a self-healing loop (up to 50 iterations)
-
-Each session runs with a fresh context window. Progress is tracked via `implementation_plan.json` and Git commits.
-
-**Phase 3: Merge**
-
-When you're ready to merge, AI handles any conflicts that arose while you were working:
-
-1. **Conflict Detection** — Identifies files modified in both main and the build
-2. **3-Tier Resolution** — Git auto-merge → Conflict-only AI → Full-file AI (fallback)
-3. **Parallel Merge** — Multiple files resolve simultaneously
-4. **Staged for Review** — Changes are staged but not committed, so you can review before finalizing
-
-### 🔒 Security Model
-
-Three-layer defense keeps your code safe:
-- **OS Sandbox** — Bash commands run in isolation
-- **Filesystem Restrictions** — Operations limited to project directory
-- **Command Allowlist** — Only approved commands based on your project's stack
-
-### 🧠 Memory Layer
-
-The Memory Layer is a **hybrid RAG system** combining graph nodes with semantic search to deliver the best possible context during AI coding. Agents remember insights from previous sessions, discovered codebase patterns persist and are reusable, and historical context helps agents make smarter decisions.
-
-**Architecture:**
-- **Backend**: FalkorDB (graph database) via Docker
-- **Library**: Graphiti for knowledge graph operations
-- **Providers**: OpenAI, Anthropic, Azure OpenAI, or Ollama (local/offline)
-
-| Setup | LLM | Embeddings | Notes |
-|-------|-----|------------|-------|
-| **OpenAI** | OpenAI | OpenAI | Simplest - single API key |
-| **Anthropic + Voyage** | Anthropic | Voyage AI | High quality |
-| **Ollama** | Ollama | Ollama | Fully offline |
-| **Azure** | Azure OpenAI | Azure OpenAI | Enterprise |
-
 ## Project Structure
 
 ```
-your-project/
-├── .worktrees/               # Created during build (git-ignored)
-│   └── auto-claude/          # Isolated workspace for AI coding
-├── .auto-claude/             # Per-project data (specs, plans, QA reports)
-│   ├── specs/                # Task specifications
-│   ├── roadmap/              # Project roadmap
-│   └── ideation/             # Ideas and planning
-├── auto-claude/              # Python backend (framework code)
-│   ├── run.py                # Build entry point
-│   ├── spec_runner.py        # Spec creation orchestrator
-│   ├── prompts/              # Agent prompt templates
-│   └── ...
-├── auto-claude-ui/           # Electron desktop application
-│   └── ...
-└── docker-compose.yml        # FalkorDB for Memory Layer
+Auto-Claude/
+├── apps/
+│   ├── backend/     # Python agents, specs, QA pipeline
+│   └── frontend/    # Electron desktop application
+├── guides/          # Additional documentation
+├── tests/           # Test suite
+└── scripts/         # Build utilities
 ```
 
-## Environment Variables (CLI Only)
+---
 
-> **Desktop UI users:** These are configured through the app settings — no manual setup needed.
+## CLI Usage
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token from `claude setup-token` |
-| `AUTO_BUILD_MODEL` | No | Model override (default: claude-opus-4-5-20251101) |
-| `GRAPHITI_ENABLED` | Recommended | Set to `true` to enable Memory Layer |
-| `GRAPHITI_LLM_PROVIDER` | For Memory | LLM provider: openai, anthropic, azure_openai, ollama |
-| `GRAPHITI_EMBEDDER_PROVIDER` | For Memory | Embedder: openai, voyage, azure_openai, ollama |
-| `OPENAI_API_KEY` | For OpenAI | Required for OpenAI provider |
-| `ANTHROPIC_API_KEY` | For Anthropic | Required for Anthropic LLM |
-| `VOYAGE_API_KEY` | For Voyage | Required for Voyage embeddings |
+For headless operation, CI/CD integration, or terminal-only workflows:
 
-See `auto-claude/.env.example` for complete configuration options.
+```bash
+cd apps/backend
 
-## 💬 Community
+# Create a spec interactively
+python spec_runner.py --interactive
 
-Join our Discord to get help, share what you're building, and connect with other Auto Claude users:
+# Run autonomous build
+python run.py --spec 001
 
-[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/maj9EWmY)
+# Review and merge
+python run.py --spec 001 --review
+python run.py --spec 001 --merge
+```
 
-## 🤝 Contributing
+See [guides/CLI-USAGE.md](guides/CLI-USAGE.md) for complete CLI documentation.
 
-We welcome contributions! Whether it's bug fixes, new features, or documentation improvements.
+---
 
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on how to get started.
+## Development
 
-## Acknowledgments
+Want to build from source or contribute? See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development setup instructions.
 
-This framework was inspired by Anthropic's [Autonomous Coding Agent](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding). Thank you to the Anthropic team for their innovative work on autonomous coding systems.
+For Linux-specific builds (Flatpak, AppImage), see [guides/linux.md](guides/linux.md).
+
+---
+
+## Security
+
+Auto Claude uses a three-layer security model:
+
+1. **OS Sandbox** - Bash commands run in isolation
+2. **Filesystem Restrictions** - Operations limited to project directory
+3. **Dynamic Command Allowlist** - Only approved commands based on detected project stack
+
+All releases are:
+- Scanned with VirusTotal before publishing
+- Include SHA256 checksums for verification
+- Code-signed where applicable (macOS)
+
+---
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run install:all` | Install backend and frontend dependencies |
+| `npm start` | Build and run the desktop app |
+| `npm run dev` | Run in development mode with hot reload |
+| `npm run package` | Package for current platform |
+| `npm run package:mac` | Package for macOS |
+| `npm run package:win` | Package for Windows |
+| `npm run package:linux` | Package for Linux |
+| `npm run package:flatpak` | Package as Flatpak (see [guides/linux.md](guides/linux.md)) |
+| `npm run lint` | Run linter |
+| `npm test` | Run frontend tests |
+| `npm run test:backend` | Run backend tests |
+
+---
+
+## Contributing
+
+We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for:
+- Development setup instructions
+- Code style guidelines
+- Testing requirements
+- Pull request process
+
+---
+
+## Community
+
+- **Discord** - [Join our community](https://discord.gg/KCXaPBr4Dj)
+- **Issues** - [Report bugs or request features](https://github.com/AndyMik90/Auto-Claude/issues)
+- **Discussions** - [Ask questions](https://github.com/AndyMik90/Auto-Claude/discussions)
+
+---
 
 ## License
 
 **AGPL-3.0** - GNU Affero General Public License v3.0
 
-This software is licensed under AGPL-3.0, which means:
+Auto Claude is free to use. If you modify and distribute it, or run it as a service, your code must also be open source under AGPL-3.0.
 
-- **Attribution Required**: You must give appropriate credit, provide a link to the license, and indicate if changes were made. When using Auto Claude, please credit the project.
-- **Open Source Required**: If you modify this software and distribute it or run it as a service, you must release your source code under AGPL-3.0.
-- **Network Use (Copyleft)**: If you run this software as a network service (e.g., SaaS), users interacting with it over a network must be able to receive the source code.
-- **No Closed-Source Usage**: You cannot use this software in proprietary/closed-source projects without open-sourcing your entire project under AGPL-3.0.
+Commercial licensing available for closed-source use cases.
 
-**In simple terms**: You can use Auto Claude freely, but if you build on it, your code must also be open source under AGPL-3.0 and attribute this project. Closed-source commercial use requires a separate license.
+---
 
-For commercial licensing inquiries (closed-source usage), please contact the maintainers.
+## Star History
+
+[![GitHub Repo stars](https://img.shields.io/github/stars/AndyMik90/Auto-Claude?style=social)](https://github.com/AndyMik90/Auto-Claude/stargazers)
+
+[![Star History Chart](https://api.star-history.com/svg?repos=AndyMik90/Auto-Claude&type=Date)](https://star-history.com/#AndyMik90/Auto-Claude&Date)

RELEASE.md

@@ -0,0 +1,254 @@
+# Release Process
+
+This document describes how releases are created for Auto Claude.
+
+## Overview
+
+Auto Claude uses an automated release pipeline that ensures releases are only published after all builds succeed. This prevents version mismatches between documentation and actual releases.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           RELEASE FLOW                                       │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   develop branch                    main branch                              │
+│   ──────────────                    ───────────                              │
+│        │                                 │                                   │
+│        │  1. bump-version.js             │                                   │
+│        │     (creates commit)            │                                   │
+│        │                                 │                                   │
+│        ▼                                 │                                   │
+│   ┌─────────┐                           │                                   │
+│   │ v2.8.0  │  2. Create PR             │                                   │
+│   │ commit  │ ────────────────────►     │                                   │
+│   └─────────┘                           │                                   │
+│                                          │                                   │
+│                           3. Merge PR    ▼                                   │
+│                                    ┌──────────┐                              │
+│                                    │ v2.8.0   │                              │
+│                                    │ on main  │                              │
+│                                    └────┬─────┘                              │
+│                                         │                                    │
+│                     ┌───────────────────┴───────────────────┐               │
+│                     │     GitHub Actions (automatic)         │               │
+│                     ├───────────────────────────────────────┤               │
+│                     │ 4. prepare-release.yml                 │               │
+│                     │    - Detects version > latest tag      │               │
+│                     │    - Creates tag v2.8.0                │               │
+│                     │                                        │               │
+│                     │ 5. release.yml (triggered by tag)      │               │
+│                     │    - Builds macOS (Intel + ARM)        │               │
+│                     │    - Builds Windows                    │               │
+│                     │    - Builds Linux                      │               │
+│                     │    - Generates changelog               │               │
+│                     │    - Creates GitHub release            │               │
+│                     │    - Updates README                    │               │
+│                     └───────────────────────────────────────┘               │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## For Maintainers: Creating a Release
+
+### Step 1: Bump the Version
+
+On your development branch (typically `develop` or a feature branch):
+
+```bash
+# Navigate to project root
+cd /path/to/auto-claude
+
+# Bump version (choose one)
+node scripts/bump-version.js patch   # 2.7.1 -> 2.7.2 (bug fixes)
+node scripts/bump-version.js minor   # 2.7.1 -> 2.8.0 (new features)
+node scripts/bump-version.js major   # 2.7.1 -> 3.0.0 (breaking changes)
+node scripts/bump-version.js 2.8.0   # Set specific version
+```
+
+This will:
+- Update `apps/frontend/package.json`
+- Update `package.json` (root)
+- Update `apps/backend/__init__.py`
+- Check if `CHANGELOG.md` has an entry for the new version (warns if missing)
+- Create a commit with message `chore: bump version to X.Y.Z`
+
+### Step 2: Update CHANGELOG.md (REQUIRED)
+
+**IMPORTANT: The release will fail if CHANGELOG.md doesn't have an entry for the new version.**
+
+Add release notes to `CHANGELOG.md` at the top of the file:
+
+```markdown
+## 2.8.0 - Your Release Title
+
+### ✨ New Features
+- Feature description
+
+### 🛠️ Improvements
+- Improvement description
+
+### 🐛 Bug Fixes
+- Fix description
+
+---
+```
+
+Then amend the version bump commit:
+
+```bash
+git add CHANGELOG.md
+git commit --amend --no-edit
+```
+
+### Step 3: Push and Create PR
+
+```bash
+# Push your branch
+git push origin your-branch
+
+# Create PR to main (via GitHub UI or gh CLI)
+gh pr create --base main --title "Release v2.8.0"
+```
+
+### Step 4: Merge to Main
+
+Once the PR is approved and merged to `main`, GitHub Actions will automatically:
+
+1. **Detect the version bump** (`prepare-release.yml`)
+2. **Validate CHANGELOG.md** has an entry for the new version (FAILS if missing)
+3. **Extract release notes** from CHANGELOG.md
+4. **Create a git tag** (e.g., `v2.8.0`)
+5. **Trigger the release workflow** (`release.yml`)
+6. **Build binaries** for all platforms:
+   - macOS Intel (x64) - code signed & notarized
+   - macOS Apple Silicon (arm64) - code signed & notarized
+   - Windows (NSIS installer) - code signed
+   - Linux (AppImage + .deb)
+7. **Scan binaries** with VirusTotal
+8. **Create GitHub release** with release notes from CHANGELOG.md
+9. **Update README** with new version badge and download links
+
+### Step 5: Verify
+
+After merging, check:
+- [GitHub Actions](https://github.com/AndyMik90/Auto-Claude/actions) - ensure all workflows pass
+- [Releases](https://github.com/AndyMik90/Auto-Claude/releases) - verify release was created
+- [README](https://github.com/AndyMik90/Auto-Claude#download) - confirm version updated
+
+## Version Numbering
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (X.0.0): Breaking changes, incompatible API changes
+- **MINOR** (0.X.0): New features, backwards compatible
+- **PATCH** (0.0.X): Bug fixes, backwards compatible
+
+## Changelog Management
+
+Release notes are managed in `CHANGELOG.md` and used for GitHub releases.
+
+### Changelog Format
+
+Each version entry in `CHANGELOG.md` should follow this format:
+
+```markdown
+## X.Y.Z - Release Title
+
+### ✨ New Features
+- Feature description with context
+
+### 🛠️ Improvements
+- Improvement description
+
+### 🐛 Bug Fixes
+- Fix description
+
+---
+```
+
+### Changelog Validation
+
+The release workflow **validates** that `CHANGELOG.md` has an entry for the version being released:
+
+- If the entry is **missing**, the release is **blocked** with a clear error message
+- If the entry **exists**, its content is used for the GitHub release notes
+
+### Writing Good Release Notes
+
+- **Be specific**: Instead of "Fixed bug", write "Fixed crash when opening large files"
+- **Group by impact**: Features first, then improvements, then fixes
+- **Credit contributors**: Mention contributors for significant changes
+- **Link issues**: Reference GitHub issues where relevant (e.g., "Fixes #123")
+
+## Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `prepare-release.yml` | Push to `main` | Detects version bump, **validates CHANGELOG.md**, creates tag |
+| `release.yml` | Tag `v*` pushed | Builds binaries, extracts changelog, creates release |
+| `update-readme` (in release.yml) | After release | Updates README with new version |
+
+## Troubleshooting
+
+### Release didn't trigger after merge
+
+1. Check if version in `package.json` is greater than latest tag:
+   ```bash
+   git tag -l 'v*' --sort=-version:refname | head -1
+   cat apps/frontend/package.json | grep version
+   ```
+
+2. Ensure the merge commit touched `package.json`:
+   ```bash
+   git diff HEAD~1 --name-only | grep package.json
+   ```
+
+### Release blocked: Missing changelog entry
+
+If you see "CHANGELOG VALIDATION FAILED" in the workflow:
+
+1. The `prepare-release.yml` workflow validated that `CHANGELOG.md` doesn't have an entry for the new version
+2. **Fix**: Add an entry to `CHANGELOG.md` with the format `## X.Y.Z - Title`
+3. Commit and push the changelog update
+4. The workflow will automatically retry when the changes are pushed to `main`
+
+```bash
+# Add changelog entry, then:
+git add CHANGELOG.md
+git commit -m "docs: add changelog for vX.Y.Z"
+git push origin main
+```
+
+### Build failed after tag was created
+
+- The release won't be published if builds fail
+- Fix the issue and create a new patch version
+- Don't reuse failed version numbers
+
+### README shows wrong version
+
+- README is only updated after successful release
+- If release failed, README keeps the previous version (this is intentional)
+- Once you successfully release, README will update automatically
+
+## Manual Release (Emergency Only)
+
+In rare cases where you need to bypass the automated flow:
+
+```bash
+# Create tag manually (NOT RECOMMENDED)
+git tag -a v2.8.0 -m "Release v2.8.0"
+git push origin v2.8.0
+
+# This will trigger release.yml directly
+```
+
+**Warning:** Only do this if you're certain the version in package.json matches the tag.
+
+## Security
+
+- All macOS binaries are code signed with Apple Developer certificate
+- All macOS binaries are notarized by Apple
+- Windows binaries are code signed
+- All binaries are scanned with VirusTotal
+- SHA256 checksums are generated for all artifacts

apps/backend/.env.example

@@ -1,14 +1,41 @@
 # Auto Claude Environment Variables
 # Copy this file to .env and fill in your values
 
-# Claude Code OAuth Token (REQUIRED)
-# Get this by running: claude setup-token
-CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
+# =============================================================================
+# AUTHENTICATION (REQUIRED)
+# =============================================================================
+# Auto Claude uses Claude Code OAuth authentication.
+# Direct API keys (ANTHROPIC_API_KEY) are NOT supported to prevent silent billing.
+#
+# Option 1: Run `claude setup-token` to save token to system keychain (recommended)
+#           (macOS: Keychain, Windows: Credential Manager, Linux: secret-service)
+# Option 2: Set the token explicitly:
+# CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
+#
+# For enterprise/proxy setups (CCR):
+# ANTHROPIC_AUTH_TOKEN=sk-zcf-x-ccr
+
+# =============================================================================
+# CUSTOM API ENDPOINT (OPTIONAL)
+# =============================================================================
+# Override the default Anthropic API endpoint. Useful for:
+#   - Local proxies (ccr, litellm)
+#   - API gateways
+#   - Self-hosted Claude instances
+#
+# ANTHROPIC_BASE_URL=http://127.0.0.1:3456
+#
+# Related settings (usually set together with ANTHROPIC_BASE_URL):
+# NO_PROXY=127.0.0.1
+# DISABLE_TELEMETRY=true
+# DISABLE_COST_WARNINGS=true
+# API_TIMEOUT_MS=600000
 
 # Model override (OPTIONAL)
 # Default: claude-opus-4-5-20251101
 # AUTO_BUILD_MODEL=claude-opus-4-5-20251101
 
+
 # =============================================================================
 # GIT/WORKTREE SETTINGS (OPTIONAL)
 # =============================================================================
@@ -49,6 +76,38 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # Pre-configured Project ID (OPTIONAL - will create project if not set)
 # LINEAR_PROJECT_ID=
 
+# =============================================================================
+# GITLAB INTEGRATION (OPTIONAL)
+# =============================================================================
+# Enable GitLab integration for issue tracking and merge requests.
+# Supports both GitLab.com and self-hosted GitLab instances.
+#
+# Authentication Options (choose one):
+#
+#   Option 1: glab CLI OAuth (Recommended)
+#   Install glab CLI: https://gitlab.com/gitlab-org/cli#installation
+#   Then run: glab auth login
+#   This opens your browser for OAuth authentication. Once complete,
+#   Auto Claude will automatically use your glab credentials (no env vars needed).
+#   For self-hosted: glab auth login --hostname gitlab.example.com
+#
+#   Option 2: Personal Access Token
+#   Set GITLAB_TOKEN below. Token auth is used if set, otherwise falls back to glab CLI.
+
+# GitLab Instance URL (OPTIONAL - defaults to gitlab.com)
+# For self-hosted: GITLAB_INSTANCE_URL=https://gitlab.example.com
+# GITLAB_INSTANCE_URL=https://gitlab.com
+
+# GitLab Personal Access Token (OPTIONAL - only needed if not using glab CLI)
+# Required scope: api (covers issues, merge requests, releases, project info)
+# Optional scope: write_repository (only if creating new GitLab projects from local repos)
+# Get from: https://gitlab.com/-/user_settings/personal_access_tokens
+# GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
+
+# GitLab Project (OPTIONAL - format: group/project or numeric ID)
+# If not set, will auto-detect from git remote
+# GITLAB_PROJECT=mygroup/myproject
+
 # =============================================================================
 # UI SETTINGS (OPTIONAL)
 # =============================================================================
@@ -72,10 +131,11 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 #   1. Start your Electron app with remote debugging:
 #      ./YourElectronApp --remote-debugging-port=9222
 #
-#   2. For auto-claude-ui specifically:
+#   2. For auto-claude-ui specifically (use the MCP-enabled scripts):
 #      cd auto-claude-ui
-#      pnpm build
-#      ./dist/mac-arm64/Auto\ Claude.app/Contents/MacOS/Auto\ Claude --remote-debugging-port=9222
+#      pnpm run dev:mcp     # Development mode with MCP debugging
+#      # OR for production build:
+#      pnpm run start:mcp   # Production mode with MCP debugging
 #
 # Note: Only QA agents (qa_reviewer, qa_fixer) receive Electron MCP tools.
 # Coder and Planner agents do NOT have access to these tools to minimize
@@ -90,24 +150,35 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # ELECTRON_DEBUG_PORT=9222
 
 # =============================================================================
-# GRAPHITI MEMORY INTEGRATION V2 (OPTIONAL)
+# GRAPHITI MEMORY INTEGRATION (REQUIRED)
 # =============================================================================
-# Enable Graphiti-based persistent memory layer for cross-session context
-# retention. Uses FalkorDB as the graph database backend.
+# Graphiti-based persistent memory layer for cross-session context
+# retention. Uses LadybugDB as the embedded graph database.
 #
-# V2 supports multiple LLM and embedder providers:
+# REQUIREMENTS:
+#   - Python 3.12 or higher
+#   - Install: pip install real_ladybug graphiti-core
+#
+# Supports multiple LLM and embedder providers:
 #   - OpenAI (default)
 #   - Anthropic (LLM only, use with Voyage for embeddings)
 #   - Azure OpenAI
 #   - Ollama (local, fully offline)
-#
-# Prerequisites:
-#   1. Start FalkorDB: docker-compose up -d falkordb
-#   2. Install Graphiti: pip install graphiti-core[falkordb]
-#   3. Configure your chosen provider (see below)
+#   - Google AI (Gemini)
 
-# Enable Graphiti integration (default: false)
-# GRAPHITI_ENABLED=true
+# Graphiti is enabled by default. Set to false to disable memory features.
+GRAPHITI_ENABLED=true
+
+# =============================================================================
+# GRAPHITI: Database Settings
+# =============================================================================
+# LadybugDB stores data in a local directory (no Docker required).
+
+# Database name (default: auto_claude_memory)
+# GRAPHITI_DATABASE=auto_claude_memory
+
+# Database storage path (default: ~/.auto-claude/memories)
+# GRAPHITI_DB_PATH=~/.auto-claude/memories
 
 # =============================================================================
 # GRAPHITI: Provider Selection
@@ -115,10 +186,10 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # Choose which providers to use for LLM and embeddings.
 # Default is "openai" for both.
 
-# LLM provider: openai | anthropic | azure_openai | ollama
+# LLM provider: openai | anthropic | azure_openai | ollama | google | openrouter
 # GRAPHITI_LLM_PROVIDER=openai
 
-# Embedder provider: openai | voyage | azure_openai | ollama
+# Embedder provider: openai | voyage | azure_openai | ollama | google | openrouter
 # GRAPHITI_EMBEDDER_PROVIDER=openai
 
 # =============================================================================
@@ -130,8 +201,8 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # OpenAI API Key
 # OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
-# OpenAI Model for LLM (default: gpt-5-mini)
-# OPENAI_MODEL=gpt-5-mini
+# OpenAI Model for LLM (default: gpt-4o-mini)
+# OPENAI_MODEL=gpt-4o-mini
 
 # OpenAI Model for embeddings (default: text-embedding-3-small)
 # Available: text-embedding-3-small (1536 dim), text-embedding-3-large (3072 dim)
@@ -166,6 +237,45 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # Available: voyage-3 (1024 dim), voyage-3-lite (512 dim)
 # VOYAGE_EMBEDDING_MODEL=voyage-3
 
+# =============================================================================
+# GRAPHITI: Google AI Provider
+# =============================================================================
+# Use Google AI (Gemini) for both LLM and embeddings.
+# Get API key from: https://aistudio.google.com/apikey
+#
+# Required: GOOGLE_API_KEY
+
+# Google AI API Key
+# GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Google LLM Model (default: gemini-2.0-flash)
+# GOOGLE_LLM_MODEL=gemini-2.0-flash
+
+# Google Embedding Model (default: text-embedding-004)
+# GOOGLE_EMBEDDING_MODEL=text-embedding-004
+
+# =============================================================================
+# GRAPHITI: OpenRouter Provider (Multi-provider aggregator)
+# =============================================================================
+# Use OpenRouter to access multiple LLM providers through a single API.
+# OpenRouter provides access to Anthropic, OpenAI, Google, and many other models.
+# Get API key from: https://openrouter.ai/keys
+#
+# Required: OPENROUTER_API_KEY
+
+# OpenRouter API Key
+# OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# OpenRouter Base URL (default: https://openrouter.ai/api/v1)
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+
+# OpenRouter LLM Model (default: anthropic/claude-sonnet-4)
+# Popular choices: anthropic/claude-sonnet-4, openai/gpt-4o, google/gemini-2.0-flash
+# OPENROUTER_LLM_MODEL=anthropic/claude-sonnet-4
+
+# OpenRouter Embedding Model (default: openai/text-embedding-3-small)
+# OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small
+
 # =============================================================================
 # GRAPHITI: Azure OpenAI Provider
 # =============================================================================
@@ -181,7 +291,7 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
 
 # Azure OpenAI Deployment Names
-# AZURE_OPENAI_LLM_DEPLOYMENT=gpt-5
+# AZURE_OPENAI_LLM_DEPLOYMENT=gpt-4
 # AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small
 
 # =============================================================================
@@ -213,66 +323,6 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # Common values: nomic-embed-text=768, mxbai-embed-large=1024, all-minilm=384
 # OLLAMA_EMBEDDING_DIM=768
 
-# =============================================================================
-# GRAPHITI MCP SERVER (OPTIONAL - Agent-accessible knowledge graph)
-# =============================================================================
-# Enable Graphiti MCP server for direct agent access to knowledge graph.
-# This is SEPARATE from GRAPHITI_ENABLED (Python library integration).
-#
-# With MCP server enabled, Claude agents can directly:
-#   - Search for relevant context (search_nodes, search_facts)
-#   - Add discoveries to the graph (add_episode)
-#   - Retrieve recent sessions (get_episodes)
-#
-# Quick Start (uses docker-compose.yml in project root):
-#   1. Set OPENAI_API_KEY in your .env file (or export it)
-#   2. Run: docker-compose up -d
-#   3. Set GRAPHITI_MCP_URL below
-#
-# Manual Docker (alternative):
-#   docker run -d -p 8000:8000 \
-#     -e DATABASE_TYPE=falkordb \
-#     -e OPENAI_API_KEY=$OPENAI_API_KEY \
-#     -e FALKORDB_URI=redis://host.docker.internal:6379 \
-#     falkordb/graphiti-knowledge-graph-mcp
-#
-# See: https://docs.falkordb.com/agentic-memory/graphiti-mcp-server.html
-
-# Graphiti MCP Server URL (setting this enables MCP integration)
-# GRAPHITI_MCP_URL=http://localhost:8000/mcp/
-
-# Graphiti MCP Server Port (for docker-compose, default: 8000)
-# GRAPHITI_MCP_PORT=8000
-
-# Optional: Override model settings for MCP server
-# GRAPHITI_MODEL_NAME=gpt-4o-mini
-# GRAPHITI_EMBEDDING_MODEL=text-embedding-3-small
-
-# =============================================================================
-# GRAPHITI: FalkorDB Connection Settings
-# =============================================================================
-# Configure the FalkorDB graph database connection.
-# Start FalkorDB: docker run -p 6379:6379 falkordb/falkordb:latest
-
-# FalkorDB Host (default: localhost)
-# GRAPHITI_FALKORDB_HOST=localhost
-
-# FalkorDB Port (default: 6379)
-# GRAPHITI_FALKORDB_PORT=6379
-
-# FalkorDB Password (default: empty)
-# GRAPHITI_FALKORDB_PASSWORD=
-
-# Graph Database Name (default: auto_claude_memory)
-# GRAPHITI_DATABASE=auto_claude_memory
-
-# =============================================================================
-# GRAPHITI: Miscellaneous Settings
-# =============================================================================
-
-# Disable Graphiti telemetry (default: true)
-# GRAPHITI_TELEMETRY_ENABLED=false
-
 # =============================================================================
 # GRAPHITI: Example Configurations
 # =============================================================================
@@ -304,5 +354,19 @@ CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 # GRAPHITI_EMBEDDER_PROVIDER=azure_openai
 # AZURE_OPENAI_API_KEY=xxxxxxxx
 # AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com/...
-# AZURE_OPENAI_LLM_DEPLOYMENT=gpt-5
+# AZURE_OPENAI_LLM_DEPLOYMENT=gpt-4
 # AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small
+#
+# --- Example 5: Google AI (Gemini) ---
+# GRAPHITI_ENABLED=true
+# GRAPHITI_LLM_PROVIDER=google
+# GRAPHITI_EMBEDDER_PROVIDER=google
+# GOOGLE_API_KEY=AIzaSyxxxxxxxx
+#
+# --- Example 6: OpenRouter (multi-provider aggregator) ---
+# GRAPHITI_ENABLED=true
+# GRAPHITI_LLM_PROVIDER=openrouter
+# GRAPHITI_EMBEDDER_PROVIDER=openrouter
+# OPENROUTER_API_KEY=sk-or-xxxxxxxx
+# OPENROUTER_LLM_MODEL=anthropic/claude-sonnet-4
+# OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small

apps/backend/.gitignore

@@ -5,6 +5,7 @@
 
 # Virtual environment
 .venv/
+.venv*/
 venv/
 env/
 
@@ -60,3 +61,6 @@ Thumbs.db
 
 # Tests (development only)
 tests/
+
+# Auto Claude data directory
+.auto-claude/

apps/backend/INVESTIGATION.md

@@ -0,0 +1,421 @@
+# Token Encryption Investigation
+
+## Issue Summary
+
+Auto-Claude users are experiencing API 401 errors ("Invalid bearer token") because the Python backend is passing encrypted tokens (with `enc:` prefix) directly to the Claude Agent SDK without decryption. Standalone Claude Code terminals work correctly because they decrypt these tokens before use.
+
+**Key insight from user thehaffk:** "python cant unencrypt claude token and it launches session with CLAUDE_CODE_OAUTH_TOKEN=enc:djEwtxMGISt3tQ..."
+
+## Token Storage Format
+
+### Encrypted Token Format
+
+Claude Code CLI stores OAuth tokens in an encrypted format with the prefix `enc:`:
+
+```text
+enc:djEwtxMGISt3tQ...
+```
+
+This format is used when tokens are stored in:
+- **macOS**: Keychain (service: "Claude Code-credentials")
+- **Linux**: Secret Service API (DBus, via secretstorage library)
+- **Windows**: Credential Manager / .credentials.json files
+
+### Decrypted Token Format
+
+Valid Claude OAuth tokens have the format:
+```text
+sk-ant-oat01-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+## Current Token Flow (BROKEN)
+
+1. **Token Storage**: Claude Code CLI stores encrypted token with `enc:` prefix in system keychain
+2. **Token Retrieval**: `apps/backend/core/auth.py::get_auth_token()` retrieves token from:
+   - Environment variable `CLAUDE_CODE_OAUTH_TOKEN`
+   - OR system keychain via `get_token_from_keychain()`
+3. **❌ NO DECRYPTION**: Token is returned as-is with `enc:` prefix intact
+4. **SDK Initialization**: Encrypted token passed to Claude Agent SDK
+5. **API Call Fails**: SDK sends encrypted token to API → 401 error
+
+### Proof of Broken Flow
+
+Test in `apps/backend`:
+```python
+import os
+os.environ['CLAUDE_CODE_OAUTH_TOKEN'] = 'enc:test123'
+
+from core.auth import get_auth_token
+token = get_auth_token()
+print(f"Token: {token}")  # Output: "enc:test123"
+print(f"Encrypted: {token.startswith('enc:')}")  # Output: True
+```
+
+## How Standalone Claude Code CLI Handles Tokens
+
+### Current Understanding
+
+1. **Token Detection**: CLI checks if token starts with `enc:` prefix
+2. **Decryption**: If encrypted, CLI decrypts using platform-specific keyring access
+3. **Authentication**: Decrypted `sk-ant-oat01-` token is used for API calls
+
+### Missing Documentation
+
+Web search for "Claude Code CLI encrypted token enc: prefix decryption" found:
+- Token storage formats (JSON with accessToken, refreshToken, expiresAt)
+- Security issues (tokens exposed in debug logs before v2.1.0)
+- Keychain access patterns for macOS/Linux/Windows
+
+**❌ NOT FOUND**: Specific documentation on how Claude Code CLI decrypts `enc:` tokens
+
+Sources:
+- [Claude Code CLI over SSH on macOS: Fixing Keychain Access](https://phoenixtrap.com/2025/10/26/claude-code-cli-over-ssh-on-macos-fixing-keychain-access/)
+- [Identity and Access Management - Claude Code Docs](https://code.claude.com/docs/en/iam)
+- [Claude Code sessions should be encrypted | yoav.blog](https://yoav.blog/2026/01/09/claude-code-sessions-should-be-encrypted/)
+
+## Decryption Approach Options
+
+### Option 1: Claude Agent SDK Built-in Decryption
+
+**Status**: NEEDS VERIFICATION
+
+The Claude Agent SDK (`claude-agent-sdk>=0.1.19`) may handle decryption internally if:
+- Token is passed to SDK still encrypted
+- SDK detects `enc:` prefix
+- SDK has access to system keyring for decryption
+
+**Action Required**: Check if SDK has decryption capabilities by examining:
+- SDK source code or documentation
+- Whether SDK expects encrypted vs decrypted tokens
+- If SDK requires specific environment variables for decryption
+
+### Option 2: Python Backend Decryption (Recommended)
+
+**Approach**: Implement decryption in `apps/backend/core/auth.py` before passing to SDK
+
+**Implementation Pattern**:
+```python
+def get_auth_token() -> str | None:
+    """Get authentication token (decrypted if necessary)."""
+    token = _retrieve_token_from_sources()  # From env or keychain
+
+    if token and token.startswith("enc:"):
+        # Decrypt the token
+        token = decrypt_token(token)
+
+    return token
+
+def decrypt_token(encrypted_token: str) -> str:
+    """
+    Decrypt Claude Code encrypted token.
+
+    Args:
+        encrypted_token: Token with 'enc:' prefix
+
+    Returns:
+        Decrypted token in format 'sk-ant-oat01-...'
+    """
+    # Remove 'enc:' prefix
+    encrypted_data = encrypted_token[4:]
+
+    # TODO: Implement decryption logic
+    # Questions to answer:
+    # 1. What encryption algorithm does Claude Code use?
+    # 2. Where is the decryption key stored?
+    # 3. Is the decryption key platform-specific (per-user)?
+    # 4. Can we reuse Claude Code's decryption mechanism?
+
+    raise NotImplementedError("Token decryption not yet implemented")
+```
+
+### Option 3: Call Claude Code CLI for Decryption
+
+**Approach**: Use the Claude Code CLI binary to decrypt tokens
+
+```python
+def decrypt_token(encrypted_token: str) -> str:
+    """Decrypt token by invoking Claude Code CLI."""
+    # Find claude binary
+    claude_path = shutil.which("claude") or "~/.local/bin/claude"
+
+    # Use CLI command to get decrypted token
+    # (if such a command exists - needs research)
+    result = subprocess.run(
+        [claude_path, "auth", "decrypt", encrypted_token],
+        capture_output=True,
+        text=True
+    )
+
+    return result.stdout.strip()
+```
+
+**Issues**:
+- Requires Claude Code CLI to be installed
+- No documented CLI command for token decryption
+- Adds external dependency
+
+## Required Investigation Steps
+
+### 1. Verify SDK Decryption Capabilities
+
+**Task**: Check if `claude-agent-sdk` handles `enc:` tokens automatically
+
+**Method**:
+```bash
+# In environment with SDK installed
+python3 << 'EOF'
+import os
+os.environ['CLAUDE_CODE_OAUTH_TOKEN'] = 'enc:...'  # Real encrypted token
+
+from claude_agent_sdk import Client
+# Try creating client - does it decrypt internally?
+client = Client()
+# Check if authentication works
+EOF
+```
+
+### 2. Reverse Engineer Claude Code CLI Decryption
+
+**Task**: Understand how Claude CLI decrypts tokens
+
+**Method**:
+- Examine Claude CLI binary (if possible)
+- Trace system calls when CLI runs (strace on Linux, dtruss on macOS)
+- Check if CLI accesses specific keychain entries for decryption keys
+- Look for encryption/decryption libraries used by CLI
+
+### 3. Find Decryption Key Storage
+
+**Task**: Locate where decryption keys are stored
+
+**Hypothesis**: Decryption key stored in:
+- macOS: Keychain (separate entry from encrypted token)
+- Linux: Secret Service API
+- Windows: Credential Manager
+
+**Verification**:
+```bash
+# macOS: List all keychain entries
+security find-generic-password -a "$(whoami)" | grep -i claude
+
+# Linux: Use secretstorage to list all items
+python3 -c "import secretstorage; ..."
+```
+
+## Recommended Decryption Approach for Python Backend
+
+Based on investigation so far, the recommended approach is:
+
+1. **Detect encrypted tokens**: Check for `enc:` prefix in `get_auth_token()`
+2. **Decrypt before use**: Implement `decrypt_token()` function
+3. **Platform-specific decryption**: Use appropriate keyring library:
+   - macOS: Use `subprocess` with `/usr/bin/security` to access decryption key
+   - Linux: Use `secretstorage` library to access Secret Service API
+   - Windows: Access Credential Manager or credentials.json
+4. **Backward compatibility**: Support both encrypted and plaintext tokens
+5. **Error handling**: Provide clear error messages if decryption fails
+
+## Complete Token Flow Trace (Frontend → Backend)
+
+### 1. Token Retrieval (Frontend)
+
+**File**: `apps/frontend/src/main/services/profile-service.ts`
+
+The frontend retrieves the OAuth token from the system keychain but **does not decrypt it**. When no API profile is active (OAuth mode), the frontend returns an empty environment object, which means it relies on:
+- The token already being in the environment as `CLAUDE_CODE_OAUTH_TOKEN`
+- OR the Python backend retrieving it from the keychain
+
+**Key Code**:
+```typescript
+// Line 223: Returns empty object in OAuth mode, allowing
+// CLAUDE_CODE_OAUTH_TOKEN to be used from system keychain
+```
+
+### 2. Environment Variable Passing (Frontend → PTY)
+
+**File**: `apps/frontend/src/main/terminal/pty-manager.ts`
+
+The PTY manager spawns the terminal shell with environment variables, including `CLAUDE_CODE_OAUTH_TOKEN`:
+
+**Key Code** (Lines 149-152):
+```typescript
+// Remove ANTHROPIC_API_KEY to ensure Claude Code uses OAuth tokens
+// (CLAUDE_CODE_OAUTH_TOKEN from profileEnv) instead of API keys
+const { DEBUG: _DEBUG, ANTHROPIC_API_KEY: _ANTHROPIC_API_KEY, ...cleanEnv } = process.env;
+```
+
+**Important**: The frontend passes through whatever token value exists in the environment - it does NOT check for `enc:` prefix or decrypt it.
+
+### 3. Token Retrieval (Backend)
+
+**File**: `apps/backend/core/auth.py`
+
+#### 3.1. get_auth_token()
+
+This function retrieves the token from multiple sources:
+
+```python
+def get_auth_token() -> str | None:
+    # First check environment variables
+    for var in AUTH_TOKEN_ENV_VARS:  # CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN
+        token = os.environ.get(var)
+        if token:
+            return token  # ❌ Returns immediately without checking for enc: prefix
+
+    # Fallback to system credential store
+    return get_token_from_keychain()  # ❌ Also returns without decryption
+```
+
+**Issue**: Returns token as-is with `enc:` prefix intact.
+
+#### 3.2. require_auth_token()
+
+This function calls `get_auth_token()` and raises an error if no token is found:
+
+```python
+def require_auth_token() -> str:
+    token = get_auth_token()  # ❌ Gets encrypted token
+    if not token:
+        raise ValueError("No OAuth token found...")
+    return token  # ❌ Returns encrypted token
+```
+
+**Issue**: No decryption step between retrieval and return.
+
+#### 3.3. ensure_claude_code_oauth_token()
+
+This function ensures the environment variable is set:
+
+```python
+def ensure_claude_code_oauth_token() -> None:
+    if os.environ.get("CLAUDE_CODE_OAUTH_TOKEN"):
+        return
+
+    token = get_auth_token()  # ❌ Gets encrypted token
+    if token:
+        os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = token  # ❌ Sets encrypted token
+```
+
+**Issue**: Propagates encrypted token to environment variable.
+
+### 4. Token Usage in SDK Client Creation (Backend)
+
+#### 4.1. Full Client Creation
+
+**File**: `apps/backend/core/client.py` (see `create_client()` function)
+
+```python
+def create_client(...):
+    oauth_token = require_auth_token()  # ❌ Gets encrypted token
+    # Ensure SDK can access it via its expected env var
+    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token  # ❌ Sets encrypted token
+```
+
+**Issue**: Encrypted token is passed to the Claude Agent SDK, which expects a decrypted `sk-ant-oat01-` token.
+
+#### 4.2. Simple Client Creation
+
+**File**: `apps/backend/core/simple_client.py` (see `create_simple_client()` function)
+
+```python
+def create_simple_client(...):
+    # Get authentication
+    oauth_token = require_auth_token()  # ❌ Gets encrypted token
+    import os
+    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token  # ❌ Sets encrypted token
+```
+
+**Issue**: Same problem - encrypted token passed to SDK.
+
+#### 4.3. Other Usages
+
+**Files**:
+- `apps/backend/core/workspace.py` (Line 1966) - AI merge operations
+- `apps/backend/runners/insights_runner.py` - Insights analysis
+- `apps/backend/runners/github/batch_issues.py` - GitHub batch operations
+- `apps/backend/integrations/linear/updater.py` - Linear integration
+- `apps/backend/commit_message.py` - Commit message generation
+- `apps/backend/analysis/insight_extractor.py` - Code insights
+- `apps/backend/merge/ai_resolver/claude_client.py` - Merge resolution
+
+**All follow the same pattern**: Call `ensure_claude_code_oauth_token()` → encrypted token in environment → SDK receives encrypted token → API 401 error.
+
+### 5. Where Decryption Should Be Inserted
+
+Based on the flow analysis, decryption should be added at **the earliest point of token retrieval** to avoid duplicating decryption logic:
+
+**RECOMMENDED INSERTION POINT**: `apps/backend/core/auth.py::get_auth_token()`
+
+```python
+def get_auth_token() -> str | None:
+    # First check environment variables
+    for var in AUTH_TOKEN_ENV_VARS:
+        token = os.environ.get(var)
+        if token:
+            # ✅ INSERT DECRYPTION HERE
+            if token.startswith("enc:"):
+                token = decrypt_token(token)
+            return token
+
+    # Fallback to system credential store
+    token = get_token_from_keychain()
+    # ✅ ALSO DECRYPT KEYCHAIN TOKENS
+    if token and token.startswith("enc:"):
+        token = decrypt_token(token)
+    return token
+```
+
+**Benefits of this approach**:
+1. Single location for decryption logic
+2. All downstream functions automatically get decrypted tokens
+3. Backward compatible (plaintext tokens pass through unchanged)
+4. Consistent behavior across all token sources (env vars and keychain)
+
+**Alternative insertion points** (NOT recommended):
+- `require_auth_token()` - Would need similar logic in `get_auth_token()` for non-required usage
+- `create_client()` - Would need duplication in `create_simple_client()` and all other clients
+- `ensure_claude_code_oauth_token()` - Would miss direct `get_auth_token()` calls
+
+## Next Steps
+
+1. ✅ Document current token flow and identify issue (THIS FILE - COMPLETED)
+2. ✅ Trace token flow from frontend to backend (THIS FILE - COMPLETED)
+3. ✅ Identify where decryption should be inserted (THIS FILE - COMPLETED)
+4. ⏳ Verify if Claude Agent SDK handles decryption internally
+5. ⏳ Reverse engineer or document Claude Code CLI decryption mechanism
+6. ⏳ Implement `decrypt_token()` function in `apps/backend/core/auth.py`
+7. ⏳ Add encryption detection and auto-decryption to `get_auth_token()`
+8. ⏳ Test with real encrypted tokens on macOS and Linux
+9. ⏳ Add comprehensive error handling for decryption failures
+
+## Open Questions
+
+1. **What encryption algorithm does Claude Code use for `enc:` tokens?**
+   - Possible: AES-256, ChaCha20, or similar
+   - Key derivation method?
+
+2. **Where is the decryption key stored?**
+   - Same keychain entry as encrypted token?
+   - Separate keychain entry?
+   - Derived from system/user credentials?
+
+3. **Does Claude Agent SDK expect encrypted or decrypted tokens?**
+   - If it expects decrypted: we must decrypt before passing
+   - If it handles encryption: we may be missing SDK configuration
+
+4. **Is there a Claude Code CLI command to decrypt tokens?**
+   - `claude auth decrypt <token>`?
+   - `claude auth get-token`?
+   - No documented command found in research
+
+5. **Can we reuse Claude Code's decryption mechanism?**
+   - Import decryption functions from CLI?
+   - Call CLI as subprocess?
+   - Implement decryption ourselves?
+
+## References
+
+- Issue: [GitHub #1223: API Error 401](https://github.com/AndyMik90/Auto-Claude/issues/1223)
+- Current auth implementation: `apps/backend/core/auth.py`
+- SDK client initialization: `apps/backend/core/client.py`
+- Requirements: `apps/backend/requirements.txt` (includes `secretstorage>=3.3.3` for Linux)

apps/backend/README.md

@@ -0,0 +1,122 @@
+# Auto Claude Backend
+
+Autonomous coding framework powered by Claude AI. Builds software features through coordinated multi-agent sessions.
+
+## Getting Started
+
+### 1. Install
+
+```bash
+cd apps/backend
+python -m pip install -r requirements.txt
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+```
+
+Authenticate with Claude Code (token auto-saved to Keychain):
+```bash
+claude
+# Type: /login
+# Press Enter to open browser
+```
+
+Token is auto-detected from macOS Keychain / Windows Credential Manager.
+
+### 3. Run
+
+```bash
+# List available specs
+python run.py --list
+
+# Run a spec
+python run.py --spec 001
+```
+
+## Requirements
+
+- Python 3.10+
+- Claude API token
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `--list` | List all specs |
+| `--spec 001` | Run spec 001 |
+| `--spec 001 --isolated` | Run in isolated workspace |
+| `--spec 001 --direct` | Run directly in repo |
+| `--spec 001 --merge` | Merge completed build |
+| `--spec 001 --review` | Review build changes |
+| `--spec 001 --discard` | Discard build |
+| `--spec 001 --qa` | Run QA validation |
+| `--list-worktrees` | List all worktrees |
+| `--help` | Show all options |
+
+## Configuration
+
+Optional `.env` settings:
+
+| Variable | Description |
+|----------|-------------|
+| `AUTO_BUILD_MODEL` | Override Claude model |
+| `DEBUG=true` | Enable debug logging |
+| `LINEAR_API_KEY` | Enable Linear integration |
+| `GRAPHITI_ENABLED=true` | Enable memory system |
+
+## Troubleshooting
+
+**"tree-sitter not available"** - Safe to ignore, uses regex fallback.
+
+**Missing module errors** - Run `python -m pip install -r requirements.txt`
+
+**Debug mode** - Set `DEBUG=true DEBUG_LEVEL=2` before running.
+
+---
+
+## For Developers
+
+### Project Structure
+
+```
+backend/
+├── agents/          # AI agent execution
+├── analysis/        # Code analysis
+├── cli/             # Command-line interface
+├── core/            # Core utilities
+├── integrations/    # External services (Linear, Graphiti)
+├── merge/           # Git merge handling
+├── project/         # Project detection
+├── prompts/         # Prompt templates
+├── qa/              # QA validation
+├── spec/            # Spec management
+└── ui/              # Terminal UI
+```
+
+### Design Principles
+
+- **SOLID** - Single responsibility, clean interfaces
+- **DRY** - Shared utilities in `core/`
+- **KISS** - Simple flat imports via facade modules
+
+### Import Convention
+
+```python
+# Use facade modules for clean imports
+from debug import debug, debug_error
+from progress import count_subtasks
+from workspace import setup_workspace
+```
+
+### Adding Features
+
+1. Create module in appropriate folder
+2. Export API in `__init__.py`
+3. Add facade module at root if commonly imported
+
+## License
+
+AGPL-3.0

apps/backend/__init__.py

@@ -0,0 +1,23 @@
+"""
+Auto Claude Backend - Autonomous Coding Framework
+==================================================
+
+Multi-agent autonomous coding framework that builds software through
+coordinated AI agent sessions.
+
+This package provides:
+- Autonomous agent execution for building features from specs
+- Workspace isolation via git worktrees
+- QA validation loops
+- Memory management (Graphiti + file-based)
+- Linear integration for project management
+
+Quick Start:
+    python run.py --spec 001    # Run a spec
+    python run.py --list        # List all specs
+
+See README.md for full documentation.
+"""
+
+__version__ = "2.7.5"
+__author__ = "Auto Claude Team"

apps/backend/agents/README.md

@@ -26,7 +26,7 @@ auto-claude/agents/
 ### `utils.py` (3.6 KB)
 - Git operations: `get_latest_commit()`, `get_commit_count()`
 - Plan management: `load_implementation_plan()`, `find_subtask_in_plan()`, `find_phase_for_subtask()`
-- Workspace sync: `sync_plan_to_source()`
+- Workspace sync: `sync_spec_to_source()`
 
 ### `memory.py` (13 KB)
 - Dual-layer memory system (Graphiti primary, file-based fallback)
@@ -73,7 +73,7 @@ from agents import (
     # Utilities
     get_latest_commit,
     load_implementation_plan,
-    sync_plan_to_source,
+    sync_spec_to_source,
 )
 ```
 

apps/backend/agents/__init__.py

@@ -0,0 +1,96 @@
+"""
+Agents Module
+=============
+
+Modular agent system for autonomous coding.
+
+This module provides:
+- run_autonomous_agent: Main coder agent loop
+- run_followup_planner: Follow-up planner for completed specs
+- Memory management (Graphiti + file-based fallback)
+- Session management and post-processing
+- Utility functions for git and plan management
+
+Uses lazy imports to avoid circular dependencies.
+"""
+
+# Explicit import required by CodeQL static analysis
+# (CodeQL doesn't recognize __getattr__ dynamic exports)
+from .utils import sync_spec_to_source
+
+__all__ = [
+    # Main API
+    "run_autonomous_agent",
+    "run_followup_planner",
+    # Memory
+    "debug_memory_system_status",
+    "get_graphiti_context",
+    "save_session_memory",
+    "save_session_to_graphiti",
+    # Session
+    "run_agent_session",
+    "post_session_processing",
+    # Utils
+    "get_latest_commit",
+    "get_commit_count",
+    "load_implementation_plan",
+    "find_subtask_in_plan",
+    "find_phase_for_subtask",
+    "sync_spec_to_source",
+    # Constants
+    "AUTO_CONTINUE_DELAY_SECONDS",
+    "HUMAN_INTERVENTION_FILE",
+]
+
+
+def __getattr__(name):
+    """Lazy imports to avoid circular dependencies."""
+    if name in ("AUTO_CONTINUE_DELAY_SECONDS", "HUMAN_INTERVENTION_FILE"):
+        from .base import AUTO_CONTINUE_DELAY_SECONDS, HUMAN_INTERVENTION_FILE
+
+        return locals()[name]
+    elif name == "run_autonomous_agent":
+        from .coder import run_autonomous_agent
+
+        return run_autonomous_agent
+    elif name in (
+        "debug_memory_system_status",
+        "get_graphiti_context",
+        "save_session_memory",
+        "save_session_to_graphiti",
+    ):
+        from .memory_manager import (
+            debug_memory_system_status,
+            get_graphiti_context,
+            save_session_memory,
+            save_session_to_graphiti,
+        )
+
+        return locals()[name]
+    elif name == "run_followup_planner":
+        from .planner import run_followup_planner
+
+        return run_followup_planner
+    elif name in ("post_session_processing", "run_agent_session"):
+        from .session import post_session_processing, run_agent_session
+
+        return locals()[name]
+    elif name in (
+        "find_phase_for_subtask",
+        "find_subtask_in_plan",
+        "get_commit_count",
+        "get_latest_commit",
+        "load_implementation_plan",
+        "sync_spec_to_source",
+    ):
+        from .utils import (
+            find_phase_for_subtask,
+            find_subtask_in_plan,
+            get_commit_count,
+            get_latest_commit,
+            load_implementation_plan,
+            sync_spec_to_source,
+        )
+
+        return locals()[name]
+    raise AttributeError(f"module 'agents' has no attribute '{name}'")

apps/backend/agents/coder.py

@@ -7,9 +7,10 @@ Main autonomous agent loop that runs the coder agent to implement subtasks.
 
 import asyncio
 import logging
+import os
 from pathlib import Path
 
-from client import create_client
+from core.client import create_client
 from linear_updater import (
     LinearTaskState,
     is_linear_enabled,
@@ -17,6 +18,8 @@ from linear_updater import (
     linear_task_started,
     linear_task_stuck,
 )
+from phase_config import get_phase_model, get_phase_thinking_budget
+from phase_event import ExecutionPhase, emit_phase
 from progress import (
     count_subtasks,
     count_subtasks_detailed,
@@ -35,6 +38,7 @@ from prompt_generator import (
 )
 from prompts import is_first_run
 from recovery import RecoveryManager
+from security.constants import PROJECT_DIR_ENV_VAR
 from task_logger import (
     LogPhase,
     get_task_logger,
@@ -60,7 +64,7 @@ from .utils import (
     get_commit_count,
     get_latest_commit,
     load_implementation_plan,
-    sync_plan_to_source,
+    sync_spec_to_source,
 )
 
 logger = logging.getLogger(__name__)
@@ -88,6 +92,10 @@ async def run_autonomous_agent(
         verbose: Whether to show detailed output
         source_spec_dir: Original spec directory in main project (for syncing from worktree)
     """
+    # Set environment variable for security hooks to find the correct project directory
+    # This is needed because os.getcwd() may return the wrong directory in worktree mode
+    os.environ[PROJECT_DIR_ENV_VAR] = str(project_dir.resolve())
+
     # Initialize recovery manager (handles memory persistence)
     recovery_manager = RecoveryManager(spec_dir, project_dir)
 
@@ -128,6 +136,25 @@ async def run_autonomous_agent(
     # Track which phase we're in for logging
     current_log_phase = LogPhase.CODING
     is_planning_phase = False
+    planning_retry_context: str | None = None
+    planning_validation_failures = 0
+    max_planning_validation_retries = 3
+
+    def _validate_and_fix_implementation_plan() -> tuple[bool, list[str]]:
+        from spec.validate_pkg import SpecValidator, auto_fix_plan
+
+        spec_validator = SpecValidator(spec_dir)
+        result = spec_validator.validate_implementation_plan()
+        if result.valid:
+            return True, []
+
+        fixed = auto_fix_plan(spec_dir)
+        if fixed:
+            result = spec_validator.validate_implementation_plan()
+            if result.valid:
+                return True, []
+
+        return False, result.errors
 
     if first_run:
         print_status(
@@ -145,6 +172,7 @@ async def run_autonomous_agent(
 
         # Update status for planning phase
         status_manager.update(state=BuildState.PLANNING)
+        emit_phase(ExecutionPhase.PLANNING, "Creating implementation plan")
         is_planning_phase = True
         current_log_phase = LogPhase.PLANNING
 
@@ -172,6 +200,9 @@ async def run_autonomous_agent(
         if task_logger:
             task_logger.start_phase(LogPhase.CODING, "Continuing implementation...")
 
+        # Emit phase event when continuing build
+        emit_phase(ExecutionPhase.CODING, "Continuing implementation")
+
     # Show human intervention hint
     content = [
         bold("INTERACTIVE CONTROLS"),
@@ -195,7 +226,7 @@ async def run_autonomous_agent(
             print("  PAUSED BY HUMAN")
             print("=" * 70)
 
-            pause_content = pause_file.read_text().strip()
+            pause_content = pause_file.read_text(encoding="utf-8").strip()
             if pause_content:
                 print(f"\nMessage: {pause_content}")
 
@@ -211,8 +242,8 @@ async def run_autonomous_agent(
             print("To continue, run the script again without --max-iterations")
             break
 
-        # Get the next subtask to work on
-        next_subtask = get_next_subtask(spec_dir)
+        # Get the next subtask to work on (planner sessions shouldn't bind to a subtask)
+        next_subtask = None if first_run else get_next_subtask(spec_dir)
         subtask_id = next_subtask.get("id") if next_subtask else None
         phase_name = next_subtask.get("phase_name") if next_subtask else None
 
@@ -244,12 +275,42 @@ async def run_autonomous_agent(
         commit_before = get_latest_commit(project_dir)
         commit_count_before = get_commit_count(project_dir)
 
-        # Create client (fresh context)
-        client = create_client(project_dir, spec_dir, model)
+        # Get the phase-specific model and thinking level (respects task_metadata.json configuration)
+        # first_run means we're in planning phase, otherwise coding phase
+        current_phase = "planning" if first_run else "coding"
+        phase_model = get_phase_model(spec_dir, current_phase, model)
+        phase_thinking_budget = get_phase_thinking_budget(spec_dir, current_phase)
+
+        # Create client (fresh context) with phase-specific model and thinking
+        # Use appropriate agent_type for correct tool permissions and thinking budget
+        client = create_client(
+            project_dir,
+            spec_dir,
+            phase_model,
+            agent_type="planner" if first_run else "coder",
+            max_thinking_tokens=phase_thinking_budget,
+        )
 
         # Generate appropriate prompt
         if first_run:
             prompt = generate_planner_prompt(spec_dir, project_dir)
+            if planning_retry_context:
+                prompt += "\n\n" + planning_retry_context
+
+            # Retrieve Graphiti memory context for planning phase
+            # This gives the planner knowledge of previous patterns, gotchas, and insights
+            planner_context = await get_graphiti_context(
+                spec_dir,
+                project_dir,
+                {
+                    "description": "Planning implementation for new feature",
+                    "id": "planner",
+                },
+            )
+            if planner_context:
+                prompt += "\n\n" + planner_context
+                print_status("Graphiti memory context loaded for planner", "success")
+
             first_run = False
             current_log_phase = LogPhase.PLANNING
 
@@ -258,9 +319,12 @@ async def run_autonomous_agent(
                 task_logger.set_session(iteration)
         else:
             # Switch to coding phase after planning
+            just_transitioned_from_planning = False
             if is_planning_phase:
+                just_transitioned_from_planning = True
                 is_planning_phase = False
                 current_log_phase = LogPhase.CODING
+                emit_phase(ExecutionPhase.CODING, "Starting implementation")
                 if task_logger:
                     task_logger.end_phase(
                         LogPhase.PLANNING,
@@ -270,10 +334,41 @@ async def run_autonomous_agent(
                     task_logger.start_phase(
                         LogPhase.CODING, "Starting implementation..."
                     )
+                # In worktree mode, the UI prefers planning logs from the main spec dir.
+                # Ensure the planning->coding transition is immediately reflected there.
+                if sync_spec_to_source(spec_dir, source_spec_dir):
+                    print_status("Phase transition synced to main project", "success")
 
             if not next_subtask:
-                print("No pending subtasks found - build may be complete!")
-                break
+                # FIX for Issue #495: Race condition after planning phase
+                # The implementation_plan.json may not be fully flushed to disk yet,
+                # or there may be a brief delay before subtasks become available.
+                # Retry with exponential backoff before giving up.
+                if just_transitioned_from_planning:
+                    print_status(
+                        "Waiting for implementation plan to be ready...", "progress"
+                    )
+                    for retry_attempt in range(3):
+                        delay = (retry_attempt + 1) * 2  # 2s, 4s, 6s
+                        await asyncio.sleep(delay)
+                        next_subtask = get_next_subtask(spec_dir)
+                        if next_subtask:
+                            # Update subtask_id and phase_name after successful retry
+                            subtask_id = next_subtask.get("id")
+                            phase_name = next_subtask.get("phase_name")
+                            print_status(
+                                f"Found subtask {subtask_id} after {delay}s delay",
+                                "success",
+                            )
+                            break
+                        print_status(
+                            f"Retry {retry_attempt + 1}/3: No subtask found yet...",
+                            "warning",
+                        )
+
+                if not next_subtask:
+                    print("No pending subtasks found - build may be complete!")
+                    break
 
             # Get attempt count for recovery context
             attempt_count = recovery_manager.get_attempt_count(subtask_id)
@@ -328,8 +423,46 @@ async def run_autonomous_agent(
                 client, prompt, spec_dir, verbose, phase=current_log_phase
             )
 
+        plan_validated = False
+        if is_planning_phase and status != "error":
+            valid, errors = _validate_and_fix_implementation_plan()
+            if valid:
+                plan_validated = True
+                planning_retry_context = None
+            else:
+                planning_validation_failures += 1
+                if planning_validation_failures >= max_planning_validation_retries:
+                    print_status(
+                        "implementation_plan.json validation failed too many times",
+                        "error",
+                    )
+                    for err in errors:
+                        print(f"  - {err}")
+                    status_manager.update(state=BuildState.ERROR)
+                    return
+
+                print_status(
+                    "implementation_plan.json invalid - retrying planner", "warning"
+                )
+                for err in errors:
+                    print(f"  - {err}")
+
+                planning_retry_context = (
+                    "## IMPLEMENTATION PLAN VALIDATION ERRORS\n\n"
+                    "The previous `implementation_plan.json` is INVALID.\n"
+                    "You MUST rewrite it to match the required schema:\n"
+                    "- Top-level: `feature`, `workflow_type`, `phases`\n"
+                    "- Each phase: `id` (or `phase`) and `name`, and `subtasks`\n"
+                    "- Each subtask: `id`, `description`, `status` (use `pending` for not started)\n\n"
+                    "Validation errors:\n" + "\n".join(f"- {e}" for e in errors)
+                )
+                # Stay in planning mode for the next iteration
+                first_run = True
+                status = "continue"
+
         # === POST-SESSION PROCESSING (100% reliable) ===
-        if subtask_id and not first_run:
+        # Only run post-session processing for coding sessions.
+        if subtask_id and current_log_phase == LogPhase.CODING:
             linear_is_enabled = (
                 linear_task is not None and linear_task.task_id is not None
             )
@@ -367,17 +500,18 @@ async def run_autonomous_agent(
                         attempt_count=attempt_count,
                     )
                     print_status("Linear notified of stuck subtask", "info")
-        elif is_planning_phase and source_spec_dir:
+        elif plan_validated and source_spec_dir:
             # After planning phase, sync the newly created implementation plan back to source
-            if sync_plan_to_source(spec_dir, source_spec_dir):
+            if sync_spec_to_source(spec_dir, source_spec_dir):
                 print_status("Implementation plan synced to main project", "success")
 
         # Handle session status
         if status == "complete":
+            # Don't emit COMPLETE here - subtasks are done but QA hasn't run yet
+            # QA loop will emit COMPLETE after actual approval
             print_build_complete_banner(spec_dir)
             status_manager.update(state=BuildState.COMPLETE)
 
-            # End coding phase in task logger
             if task_logger:
                 task_logger.end_phase(
                     LogPhase.CODING,
@@ -385,7 +519,6 @@ async def run_autonomous_agent(
                     message="All subtasks completed successfully",
                 )
 
-            # Notify Linear that build is complete (moving to QA)
             if linear_task and linear_task.task_id:
                 await linear_build_complete(spec_dir)
                 print_status("Linear notified: build complete, ready for QA", "success")
@@ -401,7 +534,9 @@ async def run_autonomous_agent(
             print_progress_summary(spec_dir)
 
             # Update state back to building
-            status_manager.update(state=BuildState.BUILDING)
+            status_manager.update(
+                state=BuildState.PLANNING if is_planning_phase else BuildState.BUILDING
+            )
 
             # Show next subtask info
             next_subtask = get_next_subtask(spec_dir)
@@ -420,6 +555,7 @@ async def run_autonomous_agent(
             await asyncio.sleep(AUTO_CONTINUE_DELAY_SECONDS)
 
         elif status == "error":
+            emit_phase(ExecutionPhase.FAILED, "Session encountered an error")
             print_status("Session encountered an error", "error")
             print(muted("Will retry with a fresh session..."))
             status_manager.update(state=BuildState.ERROR)

apps/backend/agents/memory_manager.py

@@ -24,6 +24,7 @@ from graphiti_config import get_graphiti_status, is_graphiti_enabled
 # Import from parent memory package
 # Now safe since this module is named memory_manager (not memory)
 from memory import save_session_insights as save_file_based_memory
+from memory.graphiti_helpers import get_graphiti_memory
 
 logger = logging.getLogger(__name__)
 
@@ -113,24 +114,20 @@ async def get_graphiti_context(
             debug("memory", "Graphiti not enabled, skipping context retrieval")
         return None
 
+    memory = None
     try:
-        from graphiti_memory import GraphitiMemory
-
-        # Create memory manager
-        memory = GraphitiMemory(spec_dir, project_dir)
-
-        if not memory.is_enabled:
+        # Use centralized helper for GraphitiMemory instantiation
+        memory = get_graphiti_memory(spec_dir, project_dir)
+        if memory is None:
             if is_debug_enabled():
-                debug_warning("memory", "GraphitiMemory.is_enabled=False")
+                debug_warning("memory", "GraphitiMemory not available")
             return None
-
         # Build search query from subtask description
         subtask_desc = subtask.get("description", "")
         subtask_id = subtask.get("id", "")
         query = f"{subtask_desc} {subtask_id}".strip()
 
         if not query:
-            await memory.close()
             if is_debug_enabled():
                 debug_warning("memory", "Empty query, skipping context retrieval")
             return None
@@ -146,20 +143,26 @@ async def get_graphiti_context(
         # Get relevant context
         context_items = await memory.get_relevant_context(query, num_results=5)
 
+        # Get patterns and gotchas specifically (THE FIX for learning loop!)
+        # This retrieves PATTERN and GOTCHA episode types for cross-session learning
+        patterns, gotchas = await memory.get_patterns_and_gotchas(
+            query, num_results=3, min_score=0.5
+        )
+
         # Also get recent session history
         session_history = await memory.get_session_history(limit=3)
 
-        await memory.close()
-
         if is_debug_enabled():
             debug(
                 "memory",
                 "Graphiti context retrieval complete",
                 context_items_found=len(context_items) if context_items else 0,
+                patterns_found=len(patterns) if patterns else 0,
+                gotchas_found=len(gotchas) if gotchas else 0,
                 session_history_found=len(session_history) if session_history else 0,
             )
 
-        if not context_items and not session_history:
+        if not context_items and not session_history and not patterns and not gotchas:
             if is_debug_enabled():
                 debug("memory", "No relevant context found in Graphiti")
             return None
@@ -175,6 +178,34 @@ async def get_graphiti_context(
                 item_type = item.get("type", "unknown")
                 sections.append(f"- **[{item_type}]** {content}\n")
 
+        # Add patterns section (cross-session learning)
+        if patterns:
+            sections.append("### Learned Patterns\n")
+            sections.append("_Patterns discovered in previous sessions:_\n")
+            for p in patterns:
+                pattern_text = p.get("pattern", "")
+                applies_to = p.get("applies_to", "")
+                if applies_to:
+                    sections.append(
+                        f"- **Pattern**: {pattern_text}\n  _Applies to:_ {applies_to}\n"
+                    )
+                else:
+                    sections.append(f"- **Pattern**: {pattern_text}\n")
+
+        # Add gotchas section (cross-session learning)
+        if gotchas:
+            sections.append("### Known Gotchas\n")
+            sections.append("_Pitfalls to avoid:_\n")
+            for g in gotchas:
+                gotcha_text = g.get("gotcha", "")
+                solution = g.get("solution", "")
+                if solution:
+                    sections.append(
+                        f"- **Gotcha**: {gotcha_text}\n  _Solution:_ {solution}\n"
+                    )
+                else:
+                    sections.append(f"- **Gotcha**: {gotcha_text}\n")
+
         if session_history:
             sections.append("### Recent Session Insights\n")
             for session in session_history[:2]:  # Only show last 2
@@ -193,14 +224,20 @@ async def get_graphiti_context(
 
         return "\n".join(sections)
 
-    except ImportError:
-        logger.debug("Graphiti packages not installed")
-        if is_debug_enabled():
-            debug_warning("memory", "Graphiti packages not installed")
-        return None
     except Exception as e:
         logger.warning(f"Failed to get Graphiti context: {e}")
+        if is_debug_enabled():
+            debug_error("memory", "Graphiti context retrieval failed", error=str(e))
         return None
+    finally:
+        # Always close the memory connection (swallow exceptions to avoid overriding)
+        if memory is not None:
+            try:
+                await memory.close()
+            except Exception as e:
+                logger.debug(
+                    "Failed to close Graphiti memory connection", exc_info=True
+                )
 
 
 async def save_session_memory(
@@ -285,20 +322,24 @@ async def save_session_memory(
         if is_debug_enabled():
             debug("memory", "Attempting PRIMARY storage: Graphiti")
 
+        memory = None
         try:
-            from graphiti_memory import GraphitiMemory
+            # Use centralized helper for GraphitiMemory instantiation
+            memory = get_graphiti_memory(spec_dir, project_dir)
+            if memory is None:
+                if is_debug_enabled():
+                    debug_warning("memory", "GraphitiMemory not available")
+                # Continue to file-based fallback
+            else:
+                if is_debug_enabled():
+                    debug_detailed(
+                        "memory",
+                        "GraphitiMemory instance created",
+                        is_enabled=memory.is_enabled,
+                        group_id=getattr(memory, "group_id", "unknown"),
+                    )
 
-            memory = GraphitiMemory(spec_dir, project_dir)
-
-            if is_debug_enabled():
-                debug_detailed(
-                    "memory",
-                    "GraphitiMemory instance created",
-                    is_enabled=memory.is_enabled,
-                    group_id=getattr(memory, "group_id", "unknown"),
-                )
-
-            if memory.is_enabled:
+            if memory is not None and memory.is_enabled:
                 if is_debug_enabled():
                     debug("memory", "Saving to Graphiti...")
 
@@ -315,8 +356,6 @@ async def save_session_memory(
                     # Fallback to basic session insights
                     result = await memory.save_session_insights(session_num, insights)
 
-                await memory.close()
-
                 if result:
                     logger.info(
                         f"Session {session_num} insights saved to Graphiti (primary)"
@@ -337,23 +376,32 @@ async def save_session_memory(
                         debug_warning(
                             "memory", "Graphiti save returned False, using FALLBACK"
                         )
-            else:
-                logger.warning(
-                    "Graphiti memory not enabled, falling back to file-based"
-                )
+            elif memory is None:
                 if is_debug_enabled():
                     debug_warning(
-                        "memory", "GraphitiMemory.is_enabled=False, using FALLBACK"
+                        "memory", "GraphitiMemory not available, using FALLBACK"
                     )
+            else:
+                # memory is not None but memory.is_enabled is False
+                logger.warning(
+                    "GraphitiMemory.is_enabled=False, falling back to file-based"
+                )
+                if is_debug_enabled():
+                    debug_warning("memory", "GraphitiMemory disabled, using FALLBACK")
 
-        except ImportError as e:
-            logger.debug("Graphiti packages not installed, falling back to file-based")
-            if is_debug_enabled():
-                debug_warning("memory", "Graphiti packages not installed", error=str(e))
         except Exception as e:
             logger.warning(f"Graphiti save failed: {e}, falling back to file-based")
             if is_debug_enabled():
                 debug_error("memory", "Graphiti save failed", error=str(e))
+        finally:
+            # Always close the memory connection (swallow exceptions to avoid overriding)
+            if memory is not None:
+                try:
+                    await memory.close()
+                except Exception as e:
+                    logger.debug(
+                        "Failed to close Graphiti memory connection", exc_info=e
+                    )
     else:
         if is_debug_enabled():
             debug("memory", "Graphiti not enabled, skipping to FALLBACK")

apps/backend/agents/planner.py

@@ -8,7 +8,9 @@ Handles follow-up planner sessions for adding new subtasks to completed specs.
 import logging
 from pathlib import Path
 
-from client import create_client
+from core.client import create_client
+from phase_config import get_phase_model, get_phase_thinking_budget
+from phase_event import ExecutionPhase, emit_phase
 from task_logger import (
     LogPhase,
     get_task_logger,
@@ -66,6 +68,7 @@ async def run_followup_planner(
     # Initialize status manager for ccstatusline
     status_manager = StatusManager(project_dir)
     status_manager.set_active(spec_dir.name, BuildState.PLANNING)
+    emit_phase(ExecutionPhase.PLANNING, "Follow-up planning")
 
     # Initialize task logger for persistent logging
     task_logger = get_task_logger(spec_dir)
@@ -88,8 +91,16 @@ async def run_followup_planner(
         task_logger.start_phase(LogPhase.PLANNING, "Starting follow-up planning...")
         task_logger.set_session(1)
 
-    # Create client (fresh context)
-    client = create_client(project_dir, spec_dir, model)
+    # Create client with phase-specific model and thinking budget
+    # Respects task_metadata.json configuration when no CLI override
+    planning_model = get_phase_model(spec_dir, "planning", model)
+    planning_thinking_budget = get_phase_thinking_budget(spec_dir, "planning")
+    client = create_client(
+        project_dir,
+        spec_dir,
+        planning_model,
+        max_thinking_tokens=planning_thinking_budget,
+    )
 
     # Generate follow-up planner prompt
     prompt = get_followup_planner_prompt(spec_dir)
@@ -130,7 +141,7 @@ async def run_followup_planner(
             if pending_subtasks:
                 # Reset the plan status to in_progress (in case planner didn't)
                 plan.reset_for_followup()
-                plan.save(plan_file)
+                await plan.async_save(plan_file)
 
                 print()
                 content = [

apps/backend/agents/session.py

@@ -10,6 +10,7 @@ import logging
 from pathlib import Path
 
 from claude_agent_sdk import ClaudeSDKClient
+from debug import debug, debug_detailed, debug_error, debug_section, debug_success
 from insight_extractor import extract_session_insights
 from linear_updater import (
     linear_subtask_completed,
@@ -20,6 +21,7 @@ from progress import (
     is_build_complete,
 )
 from recovery import RecoveryManager
+from security.tool_input_validator import get_safe_tool_input
 from task_logger import (
     LogEntryType,
     LogPhase,
@@ -38,7 +40,7 @@ from .utils import (
     get_commit_count,
     get_latest_commit,
     load_implementation_plan,
-    sync_plan_to_source,
+    sync_spec_to_source,
 )
 
 logger = logging.getLogger(__name__)
@@ -80,7 +82,7 @@ async def post_session_processing(
     print(muted("--- Post-Session Processing ---"))
 
     # Sync implementation plan back to source (for worktree mode)
-    if sync_plan_to_source(spec_dir, source_spec_dir):
+    if sync_spec_to_source(spec_dir, source_spec_dir):
         print_status("Implementation plan synced to main project", "success")
 
     # Check if implementation plan was updated
@@ -332,20 +334,40 @@ async def run_agent_session(
         - "complete" if all subtasks complete
         - "error" if an error occurred
     """
+    debug_section("session", f"Agent Session - {phase.value}")
+    debug(
+        "session",
+        "Starting agent session",
+        spec_dir=str(spec_dir),
+        phase=phase.value,
+        prompt_length=len(message),
+        prompt_preview=message[:200] + "..." if len(message) > 200 else message,
+    )
     print("Sending prompt to Claude Agent SDK...\n")
 
     # Get task logger for this spec
     task_logger = get_task_logger(spec_dir)
     current_tool = None
+    message_count = 0
+    tool_count = 0
 
     try:
         # Send the query
+        debug("session", "Sending query to Claude SDK...")
         await client.query(message)
+        debug_success("session", "Query sent successfully")
 
         # Collect response text and show tool use
         response_text = ""
+        debug("session", "Starting to receive response stream...")
         async for msg in client.receive_response():
             msg_type = type(msg).__name__
+            message_count += 1
+            debug_detailed(
+                "session",
+                f"Received message #{message_count}",
+                msg_type=msg_type,
+            )
 
             # Handle AssistantMessage (text and tool use)
             if msg_type == "AssistantMessage" and hasattr(msg, "content"):
@@ -365,31 +387,43 @@ async def run_agent_session(
                             )
                     elif block_type == "ToolUseBlock" and hasattr(block, "name"):
                         tool_name = block.name
-                        tool_input = None
+                        tool_input_display = None
+                        tool_count += 1
+
+                        # Safely extract tool input (handles None, non-dict, etc.)
+                        inp = get_safe_tool_input(block)
 
                         # Extract meaningful tool input for display
-                        if hasattr(block, "input") and block.input:
-                            inp = block.input
-                            if isinstance(inp, dict):
-                                if "pattern" in inp:
-                                    tool_input = f"pattern: {inp['pattern']}"
-                                elif "file_path" in inp:
-                                    fp = inp["file_path"]
-                                    if len(fp) > 50:
-                                        fp = "..." + fp[-47:]
-                                    tool_input = fp
-                                elif "command" in inp:
-                                    cmd = inp["command"]
-                                    if len(cmd) > 50:
-                                        cmd = cmd[:47] + "..."
-                                    tool_input = cmd
-                                elif "path" in inp:
-                                    tool_input = inp["path"]
+                        if inp:
+                            if "pattern" in inp:
+                                tool_input_display = f"pattern: {inp['pattern']}"
+                            elif "file_path" in inp:
+                                fp = inp["file_path"]
+                                if len(fp) > 50:
+                                    fp = "..." + fp[-47:]
+                                tool_input_display = fp
+                            elif "command" in inp:
+                                cmd = inp["command"]
+                                if len(cmd) > 50:
+                                    cmd = cmd[:47] + "..."
+                                tool_input_display = cmd
+                            elif "path" in inp:
+                                tool_input_display = inp["path"]
+
+                        debug(
+                            "session",
+                            f"Tool call #{tool_count}: {tool_name}",
+                            tool_input=tool_input_display,
+                            full_input=str(inp)[:500] if inp else None,
+                        )
 
                         # Log tool start (handles printing too)
                         if task_logger:
                             task_logger.tool_start(
-                                tool_name, tool_input, phase, print_to_console=True
+                                tool_name,
+                                tool_input_display,
+                                phase,
+                                print_to_console=True,
                             )
                         else:
                             print(f"\n[Tool: {tool_name}]", flush=True)
@@ -411,8 +445,14 @@ async def run_agent_session(
                         result_content = getattr(block, "content", "")
                         is_error = getattr(block, "is_error", False)
 
-                        # Check if command was blocked by security hook
-                        if "blocked" in str(result_content).lower():
+                        # Check if this is an error (not just content containing "blocked")
+                        if is_error and "blocked" in str(result_content).lower():
+                            # Actual blocked command by security hook
+                            debug_error(
+                                "session",
+                                f"Tool BLOCKED: {current_tool}",
+                                result=str(result_content)[:300],
+                            )
                             print(f"   [BLOCKED] {result_content}", flush=True)
                             if task_logger and current_tool:
                                 task_logger.tool_end(
@@ -425,6 +465,11 @@ async def run_agent_session(
                         elif is_error:
                             # Show errors (truncated)
                             error_str = str(result_content)[:500]
+                            debug_error(
+                                "session",
+                                f"Tool error: {current_tool}",
+                                error=error_str[:200],
+                            )
                             print(f"   [Error] {error_str}", flush=True)
                             if task_logger and current_tool:
                                 # Store full error in detail for expandable view
@@ -437,6 +482,11 @@ async def run_agent_session(
                                 )
                         else:
                             # Tool succeeded
+                            debug_detailed(
+                                "session",
+                                f"Tool success: {current_tool}",
+                                result_length=len(str(result_content)),
+                            )
                             if verbose:
                                 result_str = str(result_content)[:200]
                                 print(f"   [Done] {result_str}", flush=True)
@@ -472,11 +522,32 @@ async def run_agent_session(
 
         # Check if build is complete
         if is_build_complete(spec_dir):
+            debug_success(
+                "session",
+                "Session completed - build is complete",
+                message_count=message_count,
+                tool_count=tool_count,
+                response_length=len(response_text),
+            )
             return "complete", response_text
 
+        debug_success(
+            "session",
+            "Session completed - continuing",
+            message_count=message_count,
+            tool_count=tool_count,
+            response_length=len(response_text),
+        )
         return "continue", response_text
 
     except Exception as e:
+        debug_error(
+            "session",
+            f"Session error: {e}",
+            exception_type=type(e).__name__,
+            message_count=message_count,
+            tool_count=tool_count,
+        )
         print(f"Error during agent session: {e}")
         if task_logger:
             task_logger.log_error(f"Session error: {e}", phase)

apps/backend/agents/tools_pkg/__init__.py

@@ -30,16 +30,32 @@ Usage:
 """
 
 from .models import (
+    # Agent configuration registry
+    AGENT_CONFIGS,
+    # Base tools
+    BASE_READ_TOOLS,
+    BASE_WRITE_TOOLS,
+    # MCP tool lists
+    CONTEXT7_TOOLS,
     ELECTRON_TOOLS,
+    GRAPHITI_MCP_TOOLS,
+    LINEAR_TOOLS,
+    PUPPETEER_TOOLS,
+    # Auto-Claude tool names
     TOOL_GET_BUILD_PROGRESS,
     TOOL_GET_SESSION_CONTEXT,
     TOOL_RECORD_DISCOVERY,
     TOOL_RECORD_GOTCHA,
     TOOL_UPDATE_QA_STATUS,
     TOOL_UPDATE_SUBTASK_STATUS,
+    WEB_TOOLS,
+    # Config functions
+    get_agent_config,
+    get_default_thinking_level,
+    get_required_mcp_servers,
     is_electron_mcp_enabled,
 )
-from .permissions import get_allowed_tools
+from .permissions import get_all_agent_types, get_allowed_tools
 from .registry import create_auto_claude_mcp_server, is_tools_available
 
 __all__ = [
@@ -47,14 +63,29 @@ __all__ = [
     "create_auto_claude_mcp_server",
     "get_allowed_tools",
     "is_tools_available",
-    # Tool name constants
+    # Agent configuration registry
+    "AGENT_CONFIGS",
+    "get_agent_config",
+    "get_required_mcp_servers",
+    "get_default_thinking_level",
+    "get_all_agent_types",
+    # Base tool lists
+    "BASE_READ_TOOLS",
+    "BASE_WRITE_TOOLS",
+    "WEB_TOOLS",
+    # MCP tool lists
+    "CONTEXT7_TOOLS",
+    "LINEAR_TOOLS",
+    "GRAPHITI_MCP_TOOLS",
+    "ELECTRON_TOOLS",
+    "PUPPETEER_TOOLS",
+    # Auto-Claude tool name constants
     "TOOL_UPDATE_SUBTASK_STATUS",
     "TOOL_GET_BUILD_PROGRESS",
     "TOOL_RECORD_DISCOVERY",
     "TOOL_RECORD_GOTCHA",
     "TOOL_GET_SESSION_CONTEXT",
     "TOOL_UPDATE_QA_STATUS",
-    # Electron MCP
-    "ELECTRON_TOOLS",
+    # Config
     "is_electron_mcp_enabled",
 ]

apps/backend/agents/tools_pkg/models.py

@@ -0,0 +1,512 @@
+"""
+Tool Models and Constants
+==========================
+
+Defines tool name constants and configuration for auto-claude MCP tools.
+
+This module is the single source of truth for all tool definitions used by
+the Claude Agent SDK client. Tool lists are organized by category:
+
+- Base tools: Core file operations (Read, Write, Edit, etc.)
+- Web tools: Documentation and research (WebFetch, WebSearch)
+- MCP tools: External integrations (Context7, Linear, Graphiti, etc.)
+- Auto-Claude tools: Custom build management tools
+"""
+
+import os
+
+# =============================================================================
+# Base Tools (Built-in Claude Code tools)
+# =============================================================================
+
+# Core file operation tools
+BASE_READ_TOOLS = ["Read", "Glob", "Grep"]
+BASE_WRITE_TOOLS = ["Write", "Edit", "Bash"]
+
+# Web tools for documentation lookup and research
+# Always available to all agents for accessing external information
+WEB_TOOLS = ["WebFetch", "WebSearch"]
+
+# =============================================================================
+# Auto-Claude MCP Tools (Custom build management)
+# =============================================================================
+
+# Auto-Claude MCP tool names (prefixed with mcp__auto-claude__)
+TOOL_UPDATE_SUBTASK_STATUS = "mcp__auto-claude__update_subtask_status"
+TOOL_GET_BUILD_PROGRESS = "mcp__auto-claude__get_build_progress"
+TOOL_RECORD_DISCOVERY = "mcp__auto-claude__record_discovery"
+TOOL_RECORD_GOTCHA = "mcp__auto-claude__record_gotcha"
+TOOL_GET_SESSION_CONTEXT = "mcp__auto-claude__get_session_context"
+TOOL_UPDATE_QA_STATUS = "mcp__auto-claude__update_qa_status"
+
+# =============================================================================
+# External MCP Tools
+# =============================================================================
+
+# Context7 MCP tools for documentation lookup (always enabled)
+CONTEXT7_TOOLS = [
+    "mcp__context7__resolve-library-id",
+    "mcp__context7__get-library-docs",
+]
+
+# Linear MCP tools for project management (when LINEAR_API_KEY is set)
+LINEAR_TOOLS = [
+    "mcp__linear-server__list_teams",
+    "mcp__linear-server__get_team",
+    "mcp__linear-server__list_projects",
+    "mcp__linear-server__get_project",
+    "mcp__linear-server__create_project",
+    "mcp__linear-server__update_project",
+    "mcp__linear-server__list_issues",
+    "mcp__linear-server__get_issue",
+    "mcp__linear-server__create_issue",
+    "mcp__linear-server__update_issue",
+    "mcp__linear-server__list_comments",
+    "mcp__linear-server__create_comment",
+    "mcp__linear-server__list_issue_statuses",
+    "mcp__linear-server__list_issue_labels",
+    "mcp__linear-server__list_users",
+    "mcp__linear-server__get_user",
+]
+
+# Graphiti MCP tools for knowledge graph memory (when GRAPHITI_MCP_URL is set)
+# See: https://github.com/getzep/graphiti
+GRAPHITI_MCP_TOOLS = [
+    "mcp__graphiti-memory__search_nodes",  # Search entity summaries
+    "mcp__graphiti-memory__search_facts",  # Search relationships between entities
+    "mcp__graphiti-memory__add_episode",  # Add data to knowledge graph
+    "mcp__graphiti-memory__get_episodes",  # Retrieve recent episodes
+    "mcp__graphiti-memory__get_entity_edge",  # Get specific entity/relationship
+]
+
+# =============================================================================
+# Browser Automation MCP Tools (QA agents only)
+# =============================================================================
+
+# Puppeteer MCP tools for web browser automation
+# Used for web frontend validation (non-Electron web apps)
+# NOTE: Screenshots must be compressed (1280x720, quality 60, JPEG) to stay under
+# Claude SDK's 1MB JSON message buffer limit. See GitHub issue #74.
+PUPPETEER_TOOLS = [
+    "mcp__puppeteer__puppeteer_connect_active_tab",
+    "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",
+]
+
+# Electron MCP tools for desktop app automation (when ELECTRON_MCP_ENABLED is set)
+# Uses electron-mcp-server to connect to Electron apps via Chrome DevTools Protocol.
+# Electron app must be started with --remote-debugging-port=9222 (or ELECTRON_DEBUG_PORT).
+# These tools are only available to QA agents (qa_reviewer, qa_fixer), not Coder/Planner.
+# NOTE: Screenshots must be compressed to stay under Claude SDK's 1MB JSON message buffer limit.
+ELECTRON_TOOLS = [
+    "mcp__electron__get_electron_window_info",  # Get info about running Electron windows
+    "mcp__electron__take_screenshot",  # Capture screenshot of Electron window
+    "mcp__electron__send_command_to_electron",  # Send commands (click, fill, evaluate JS)
+    "mcp__electron__read_electron_logs",  # Read console logs from Electron app
+]
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+
+def is_electron_mcp_enabled() -> bool:
+    """
+    Check if Electron MCP server integration is enabled.
+
+    Requires ELECTRON_MCP_ENABLED to be set to 'true'.
+    When enabled, QA agents can use Electron MCP tools to connect to Electron apps
+    via Chrome DevTools Protocol on the configured debug port.
+    """
+    return os.environ.get("ELECTRON_MCP_ENABLED", "").lower() == "true"
+
+
+# =============================================================================
+# Agent Configuration Registry
+# =============================================================================
+# Single source of truth for phase → tools → MCP servers mapping.
+# This enables phase-aware tool control and context window optimization.
+
+AGENT_CONFIGS = {
+    # ═══════════════════════════════════════════════════════════════════════
+    # SPEC CREATION PHASES (Minimal tools, fast startup)
+    # ═══════════════════════════════════════════════════════════════════════
+    "spec_gatherer": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": [],  # No MCP needed - just reads project
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    "spec_researcher": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7"],  # Needs docs lookup
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    "spec_writer": {
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS,
+        "mcp_servers": [],  # Just writes spec.md
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "spec_critic": {
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],  # Self-critique, no external tools
+        "auto_claude_tools": [],
+        "thinking_default": "ultrathink",
+    },
+    "spec_discovery": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    "spec_context": {
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    "spec_validation": {
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "spec_compaction": {
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    # ═══════════════════════════════════════════════════════════════════════
+    # BUILD PHASES (Full tools + Graphiti memory)
+    # Note: "linear" is conditional on project setting "update_linear_with_tasks"
+    # ═══════════════════════════════════════════════════════════════════════
+    "planner": {
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7", "graphiti", "auto-claude"],
+        "mcp_servers_optional": ["linear"],  # Only if project setting enabled
+        "auto_claude_tools": [
+            TOOL_GET_BUILD_PROGRESS,
+            TOOL_GET_SESSION_CONTEXT,
+            TOOL_RECORD_DISCOVERY,
+        ],
+        "thinking_default": "high",
+    },
+    "coder": {
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7", "graphiti", "auto-claude"],
+        "mcp_servers_optional": ["linear"],
+        "auto_claude_tools": [
+            TOOL_UPDATE_SUBTASK_STATUS,
+            TOOL_GET_BUILD_PROGRESS,
+            TOOL_RECORD_DISCOVERY,
+            TOOL_RECORD_GOTCHA,
+            TOOL_GET_SESSION_CONTEXT,
+        ],
+        "thinking_default": "none",  # Coding doesn't use extended thinking
+    },
+    # ═══════════════════════════════════════════════════════════════════════
+    # QA PHASES (Read + test + browser + Graphiti memory)
+    # ═══════════════════════════════════════════════════════════════════════
+    "qa_reviewer": {
+        # Read + Write/Edit (for QA reports and plan updates) + Bash (for tests)
+        # Note: Reviewer writes to spec directory only (qa_report.md, implementation_plan.json)
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7", "graphiti", "auto-claude", "browser"],
+        "mcp_servers_optional": ["linear"],  # For updating issue status
+        "auto_claude_tools": [
+            TOOL_GET_BUILD_PROGRESS,
+            TOOL_UPDATE_QA_STATUS,
+            TOOL_GET_SESSION_CONTEXT,
+        ],
+        "thinking_default": "high",
+    },
+    "qa_fixer": {
+        "tools": BASE_READ_TOOLS + BASE_WRITE_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7", "graphiti", "auto-claude", "browser"],
+        "mcp_servers_optional": ["linear"],
+        "auto_claude_tools": [
+            TOOL_UPDATE_SUBTASK_STATUS,
+            TOOL_GET_BUILD_PROGRESS,
+            TOOL_UPDATE_QA_STATUS,
+            TOOL_RECORD_GOTCHA,
+        ],
+        "thinking_default": "medium",
+    },
+    # ═══════════════════════════════════════════════════════════════════════
+    # UTILITY PHASES (Minimal, no MCP)
+    # ═══════════════════════════════════════════════════════════════════════
+    "insights": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        # Note: Default to "none" because insight_extractor uses Haiku which doesn't support thinking
+        # If using Sonnet/Opus models, override max_thinking_tokens in create_simple_client()
+        "thinking_default": "none",
+    },
+    "merge_resolver": {
+        "tools": [],  # Text-only analysis
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "low",
+    },
+    "commit_message": {
+        "tools": [],
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "low",
+    },
+    "pr_reviewer": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only
+        "mcp_servers": ["context7"],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "pr_orchestrator_parallel": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only for parallel PR orchestrator
+        "mcp_servers": ["context7"],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "pr_followup_parallel": {
+        "tools": BASE_READ_TOOLS
+        + WEB_TOOLS,  # Read-only for parallel followup reviewer
+        "mcp_servers": ["context7"],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    # ═══════════════════════════════════════════════════════════════════════
+    # ANALYSIS PHASES
+    # ═══════════════════════════════════════════════════════════════════════
+    "analysis": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7"],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
+    "batch_analysis": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "low",
+    },
+    "batch_validation": {
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "low",
+    },
+    # ═══════════════════════════════════════════════════════════════════════
+    # ROADMAP & IDEATION
+    # ═══════════════════════════════════════════════════════════════════════
+    "roadmap_discovery": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7"],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "competitor_analysis": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": ["context7"],  # WebSearch for competitor research
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+    "ideation": {
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "high",
+    },
+}
+
+
+# =============================================================================
+# Agent Config Helper Functions
+# =============================================================================
+
+
+def get_agent_config(agent_type: str) -> dict:
+    """
+    Get full configuration for an agent type.
+
+    Args:
+        agent_type: The agent type identifier (e.g., 'coder', 'planner', 'qa_reviewer')
+
+    Returns:
+        Configuration dict containing tools, mcp_servers, auto_claude_tools, thinking_default
+
+    Raises:
+        ValueError: If agent_type is not found in AGENT_CONFIGS (strict mode)
+    """
+    if agent_type not in AGENT_CONFIGS:
+        raise ValueError(
+            f"Unknown agent type: '{agent_type}'. "
+            f"Valid types: {sorted(AGENT_CONFIGS.keys())}"
+        )
+    return AGENT_CONFIGS[agent_type]
+
+
+def _map_mcp_server_name(
+    name: str, custom_server_ids: list[str] | None = None
+) -> str | None:
+    """
+    Map user-friendly MCP server names to internal identifiers.
+    Also accepts custom server IDs directly.
+
+    Args:
+        name: User-provided MCP server name
+        custom_server_ids: List of custom server IDs to accept as-is
+
+    Returns:
+        Internal server identifier or None if not recognized
+    """
+    if not name:
+        return None
+    mappings = {
+        "context7": "context7",
+        "graphiti-memory": "graphiti",
+        "graphiti": "graphiti",
+        "linear": "linear",
+        "electron": "electron",
+        "puppeteer": "puppeteer",
+        "auto-claude": "auto-claude",
+    }
+    # Check if it's a known mapping
+    mapped = mappings.get(name.lower().strip())
+    if mapped:
+        return mapped
+    # Check if it's a custom server ID (accept as-is)
+    if custom_server_ids and name in custom_server_ids:
+        return name
+    return None
+
+
+def get_required_mcp_servers(
+    agent_type: str,
+    project_capabilities: dict | None = None,
+    linear_enabled: bool = False,
+    mcp_config: dict | None = None,
+) -> list[str]:
+    """
+    Get MCP servers required for this agent type.
+
+    Handles dynamic server selection:
+    - "browser" → electron (if is_electron) or puppeteer (if is_web_frontend)
+    - "linear" → only if in mcp_servers_optional AND linear_enabled is True
+    - "graphiti" → only if GRAPHITI_MCP_URL is set
+    - Respects per-project MCP config overrides from .auto-claude/.env
+    - Applies per-agent ADD/REMOVE overrides from AGENT_MCP_<agent>_ADD/REMOVE
+
+    Args:
+        agent_type: The agent type identifier
+        project_capabilities: Dict from detect_project_capabilities() or None
+        linear_enabled: Whether Linear integration is enabled for this project
+        mcp_config: Per-project MCP server toggles from .auto-claude/.env
+                   Keys: CONTEXT7_ENABLED, LINEAR_MCP_ENABLED, ELECTRON_MCP_ENABLED,
+                         PUPPETEER_MCP_ENABLED, AGENT_MCP_<agent>_ADD/REMOVE
+
+    Returns:
+        List of MCP server names to start
+    """
+    config = get_agent_config(agent_type)
+    servers = list(config.get("mcp_servers", []))
+
+    # Load per-project config (or use defaults)
+    if mcp_config is None:
+        mcp_config = {}
+
+    # Filter context7 if explicitly disabled by project config
+    if "context7" in servers:
+        context7_enabled = mcp_config.get("CONTEXT7_ENABLED", "true")
+        if str(context7_enabled).lower() == "false":
+            servers = [s for s in servers if s != "context7"]
+
+    # Handle optional servers (e.g., Linear if project setting enabled)
+    optional = config.get("mcp_servers_optional", [])
+    if "linear" in optional and linear_enabled:
+        # Also check per-project LINEAR_MCP_ENABLED override
+        linear_mcp_enabled = mcp_config.get("LINEAR_MCP_ENABLED", "true")
+        if str(linear_mcp_enabled).lower() != "false":
+            servers.append("linear")
+
+    # Handle dynamic "browser" → electron/puppeteer based on project type and config
+    if "browser" in servers:
+        servers = [s for s in servers if s != "browser"]
+        if project_capabilities:
+            is_electron = project_capabilities.get("is_electron", False)
+            is_web_frontend = project_capabilities.get("is_web_frontend", False)
+
+            # Check per-project overrides (default false for both)
+            electron_enabled = mcp_config.get("ELECTRON_MCP_ENABLED", "false")
+            puppeteer_enabled = mcp_config.get("PUPPETEER_MCP_ENABLED", "false")
+
+            # Electron: enabled by project config OR global env var
+            if is_electron and (
+                str(electron_enabled).lower() == "true" or is_electron_mcp_enabled()
+            ):
+                servers.append("electron")
+            # Puppeteer: enabled by project config (no global env var)
+            elif is_web_frontend and not is_electron:
+                if str(puppeteer_enabled).lower() == "true":
+                    servers.append("puppeteer")
+
+    # Filter graphiti if not enabled
+    if "graphiti" in servers:
+        if not os.environ.get("GRAPHITI_MCP_URL"):
+            servers = [s for s in servers if s != "graphiti"]
+
+    # ========== Apply per-agent MCP overrides ==========
+    # Format: AGENT_MCP_<agent_type>_ADD=server1,server2
+    #         AGENT_MCP_<agent_type>_REMOVE=server1,server2
+    add_key = f"AGENT_MCP_{agent_type}_ADD"
+    remove_key = f"AGENT_MCP_{agent_type}_REMOVE"
+
+    # Extract custom server IDs for mapping (allows custom servers to be recognized)
+    custom_servers = mcp_config.get("CUSTOM_MCP_SERVERS", [])
+    custom_server_ids = [s.get("id") for s in custom_servers if s.get("id")]
+
+    # Process additions
+    if add_key in mcp_config:
+        additions = [
+            s.strip() for s in str(mcp_config[add_key]).split(",") if s.strip()
+        ]
+        for server in additions:
+            mapped = _map_mcp_server_name(server, custom_server_ids)
+            if mapped and mapped not in servers:
+                servers.append(mapped)
+
+    # Process removals (but never remove auto-claude)
+    if remove_key in mcp_config:
+        removals = [
+            s.strip() for s in str(mcp_config[remove_key]).split(",") if s.strip()
+        ]
+        for server in removals:
+            mapped = _map_mcp_server_name(server, custom_server_ids)
+            if mapped and mapped != "auto-claude":  # auto-claude cannot be removed
+                servers = [s for s in servers if s != mapped]
+
+    return servers
+
+
+def get_default_thinking_level(agent_type: str) -> str:
+    """
+    Get default thinking level string for agent type.
+
+    This returns the thinking level name (e.g., 'medium', 'high'), not the token budget.
+    To convert to tokens, use phase_config.get_thinking_budget(level).
+
+    Args:
+        agent_type: The agent type identifier
+
+    Returns:
+        Thinking level string (none, low, medium, high, ultrathink)
+    """
+    config = get_agent_config(agent_type)
+    return config.get("thinking_default", "medium")

apps/backend/agents/tools_pkg/permissions.py

@@ -0,0 +1,120 @@
+"""
+Agent Tool Permissions
+======================
+
+Manages which tools are allowed for each agent type to prevent context
+pollution and accidental misuse.
+
+Supports dynamic tool filtering based on project capabilities to optimize
+context window usage. For example, Electron tools are only included for
+Electron projects, not for Next.js or CLI projects.
+
+This module now uses AGENT_CONFIGS from models.py as the single source of truth
+for tool permissions. The get_allowed_tools() function remains the primary API
+for backwards compatibility.
+"""
+
+from .models import (
+    AGENT_CONFIGS,
+    CONTEXT7_TOOLS,
+    ELECTRON_TOOLS,
+    GRAPHITI_MCP_TOOLS,
+    LINEAR_TOOLS,
+    PUPPETEER_TOOLS,
+    get_agent_config,
+    get_required_mcp_servers,
+)
+from .registry import is_tools_available
+
+
+def get_allowed_tools(
+    agent_type: str,
+    project_capabilities: dict | None = None,
+    linear_enabled: bool = False,
+    mcp_config: dict | None = None,
+) -> list[str]:
+    """
+    Get the list of allowed tools for a specific agent type.
+
+    This ensures each agent only sees tools relevant to their role,
+    preventing context pollution and accidental misuse.
+
+    Uses AGENT_CONFIGS as the single source of truth for tool permissions.
+    Dynamic MCP tools are added based on project capabilities and required servers.
+
+    Args:
+        agent_type: Agent type identifier (e.g., 'coder', 'planner', 'qa_reviewer')
+        project_capabilities: Optional dict from detect_project_capabilities()
+                            containing flags like is_electron, is_web_frontend, etc.
+        linear_enabled: Whether Linear integration is enabled for this project
+        mcp_config: Per-project MCP server toggles from .auto-claude/.env
+
+    Returns:
+        List of allowed tool names
+
+    Raises:
+        ValueError: If agent_type is not found in AGENT_CONFIGS
+    """
+    # Get agent configuration (raises ValueError if unknown type)
+    config = get_agent_config(agent_type)
+
+    # Start with base tools from config
+    tools = list(config.get("tools", []))
+
+    # Get required MCP servers for this agent
+    required_servers = get_required_mcp_servers(
+        agent_type,
+        project_capabilities,
+        linear_enabled,
+        mcp_config,
+    )
+
+    # Add auto-claude tools ONLY if the MCP server is available
+    # This prevents allowing tools that won't work because the server isn't running
+    if "auto-claude" in required_servers and is_tools_available():
+        tools.extend(config.get("auto_claude_tools", []))
+
+    # Add MCP tool names based on required servers
+    tools.extend(_get_mcp_tools_for_servers(required_servers))
+
+    return tools
+
+
+def _get_mcp_tools_for_servers(servers: list[str]) -> list[str]:
+    """
+    Get the list of MCP tools for a list of required servers.
+
+    Maps server names to their corresponding tool lists.
+
+    Args:
+        servers: List of MCP server names (e.g., ['context7', 'linear', 'electron'])
+
+    Returns:
+        List of MCP tool names for all specified servers
+    """
+    tools = []
+
+    for server in servers:
+        if server == "context7":
+            tools.extend(CONTEXT7_TOOLS)
+        elif server == "linear":
+            tools.extend(LINEAR_TOOLS)
+        elif server == "graphiti":
+            tools.extend(GRAPHITI_MCP_TOOLS)
+        elif server == "electron":
+            tools.extend(ELECTRON_TOOLS)
+        elif server == "puppeteer":
+            tools.extend(PUPPETEER_TOOLS)
+        # auto-claude tools are already added via config["auto_claude_tools"]
+
+    return tools
+
+
+def get_all_agent_types() -> list[str]:
+    """
+    Get all registered agent types.
+
+    Returns:
+        Sorted list of all agent type identifiers
+    """
+    return sorted(AGENT_CONFIGS.keys())

apps/backend/agents/tools_pkg/tools/memory.py

@@ -4,9 +4,16 @@ Session Memory Tools
 
 Tools for recording and retrieving session memory, including discoveries,
 gotchas, and patterns.
+
+Dual-storage approach:
+- File-based: Always available, works offline, spec-specific
+- LadybugDB: When Graphiti is enabled, also saves to graph database for
+  cross-session retrieval and Memory UI display
 """
 
+import asyncio
 import json
+import logging
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -19,6 +26,110 @@ except ImportError:
     SDK_TOOLS_AVAILABLE = False
     tool = None
 
+logger = logging.getLogger(__name__)
+
+
+async def _save_to_graphiti_async(
+    spec_dir: Path,
+    project_dir: Path,
+    save_type: str,
+    data: dict,
+) -> bool:
+    """
+    Save data to Graphiti/LadybugDB (async implementation).
+
+    Args:
+        spec_dir: Spec directory for GraphitiMemory initialization
+        project_dir: Project root directory
+        save_type: Type of save - 'discovery', 'gotcha', or 'pattern'
+        data: Data to save
+
+    Returns:
+        True if save succeeded, False otherwise
+    """
+    try:
+        # Use centralized helper for GraphitiMemory instantiation
+        # The helper handles enablement checks internally
+        from memory.graphiti_helpers import get_graphiti_memory
+
+        memory = get_graphiti_memory(spec_dir, project_dir)
+        if memory is None:
+            return False
+
+        try:
+            if save_type == "discovery":
+                # Save as codebase discovery
+                # Format: {file_path: description}
+                result = await memory.save_codebase_discoveries(
+                    {data["file_path"]: data["description"]}
+                )
+            elif save_type == "gotcha":
+                # Save as gotcha
+                gotcha_text = data["gotcha"]
+                if data.get("context"):
+                    gotcha_text += f" (Context: {data['context']})"
+                result = await memory.save_gotcha(gotcha_text)
+            elif save_type == "pattern":
+                # Save as pattern
+                result = await memory.save_pattern(data["pattern"])
+            else:
+                result = False
+            return result
+        finally:
+            # Always close the memory connection (swallow exceptions to avoid overriding)
+            try:
+                await memory.close()
+            except Exception as e:
+                logger.debug(
+                    "Failed to close Graphiti memory connection", exc_info=True
+                )
+
+    except Exception as e:
+        logger.warning(f"Failed to save to Graphiti: {e}")
+        return False
+
+
+def _save_to_graphiti_sync(
+    spec_dir: Path,
+    project_dir: Path,
+    save_type: str,
+    data: dict,
+) -> bool:
+    """
+    Save data to Graphiti/LadybugDB (synchronous wrapper for sync contexts only).
+
+    NOTE: This should only be called from synchronous code. For async callers,
+    use _save_to_graphiti_async() directly to ensure proper resource cleanup.
+
+    Args:
+        spec_dir: Spec directory for GraphitiMemory initialization
+        project_dir: Project root directory
+        save_type: Type of save - 'discovery', 'gotcha', or 'pattern'
+        data: Data to save
+
+    Returns:
+        True if save succeeded, False otherwise
+    """
+    try:
+        # Check if we're already in an async context
+        try:
+            asyncio.get_running_loop()
+            # We're in an async context - caller should use _save_to_graphiti_async
+            # Log a warning and return False to avoid the resource leak bug
+            logger.warning(
+                "_save_to_graphiti_sync called from async context. "
+                "Use _save_to_graphiti_async instead for proper cleanup."
+            )
+            return False
+        except RuntimeError:
+            # No running loop - safe to create one
+            return asyncio.run(
+                _save_to_graphiti_async(spec_dir, project_dir, save_type, data)
+            )
+    except Exception as e:
+        logger.warning(f"Failed to save to Graphiti: {e}")
+        return False
+
 
 def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
     """
@@ -45,7 +156,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         {"file_path": str, "description": str, "category": str},
     )
     async def record_discovery(args: dict[str, Any]) -> dict[str, Any]:
-        """Record a discovery to the codebase map."""
+        """Record a discovery to the codebase map (file + Graphiti)."""
         file_path = args["file_path"]
         description = args["description"]
         category = args.get("category", "general")
@@ -54,11 +165,13 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         memory_dir.mkdir(exist_ok=True)
 
         codebase_map_file = memory_dir / "codebase_map.json"
+        saved_to_graphiti = False
 
         try:
+            # PRIMARY: Save to file-based storage (always works)
             # Load existing map or create new
             if codebase_map_file.exists():
-                with open(codebase_map_file) as f:
+                with open(codebase_map_file, encoding="utf-8") as f:
                     codebase_map = json.load(f)
             else:
                 codebase_map = {
@@ -74,14 +187,26 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
             }
             codebase_map["last_updated"] = datetime.now(timezone.utc).isoformat()
 
-            with open(codebase_map_file, "w") as f:
+            with open(codebase_map_file, "w", encoding="utf-8") as f:
                 json.dump(codebase_map, f, indent=2)
 
+            # SECONDARY: Also save to Graphiti/LadybugDB (for Memory UI)
+            saved_to_graphiti = await _save_to_graphiti_async(
+                spec_dir,
+                project_dir,
+                "discovery",
+                {
+                    "file_path": file_path,
+                    "description": f"[{category}] {description}",
+                },
+            )
+
+            storage_note = " (also saved to memory graph)" if saved_to_graphiti else ""
             return {
                 "content": [
                     {
                         "type": "text",
-                        "text": f"Recorded discovery for '{file_path}': {description}",
+                        "text": f"Recorded discovery for '{file_path}': {description}{storage_note}",
                     }
                 ]
             }
@@ -102,7 +227,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         {"gotcha": str, "context": str},
     )
     async def record_gotcha(args: dict[str, Any]) -> dict[str, Any]:
-        """Record a gotcha to session memory."""
+        """Record a gotcha to session memory (file + Graphiti)."""
         gotcha = args["gotcha"]
         context = args.get("context", "")
 
@@ -110,8 +235,10 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         memory_dir.mkdir(exist_ok=True)
 
         gotchas_file = memory_dir / "gotchas.md"
+        saved_to_graphiti = False
 
         try:
+            # PRIMARY: Save to file-based storage (always works)
             timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
 
             entry = f"\n## [{timestamp}]\n{gotcha}"
@@ -119,14 +246,27 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
                 entry += f"\n\n_Context: {context}_"
             entry += "\n"
 
-            with open(gotchas_file, "a") as f:
+            with open(gotchas_file, "a", encoding="utf-8") as f:
                 if not gotchas_file.exists() or gotchas_file.stat().st_size == 0:
                     f.write(
                         "# Gotchas & Pitfalls\n\nThings to watch out for in this codebase.\n"
                     )
                 f.write(entry)
 
-            return {"content": [{"type": "text", "text": f"Recorded gotcha: {gotcha}"}]}
+            # SECONDARY: Also save to Graphiti/LadybugDB (for Memory UI)
+            saved_to_graphiti = await _save_to_graphiti_async(
+                spec_dir,
+                project_dir,
+                "gotcha",
+                {"gotcha": gotcha, "context": context},
+            )
+
+            storage_note = " (also saved to memory graph)" if saved_to_graphiti else ""
+            return {
+                "content": [
+                    {"type": "text", "text": f"Recorded gotcha: {gotcha}{storage_note}"}
+                ]
+            }
 
         except Exception as e:
             return {
@@ -163,7 +303,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         codebase_map_file = memory_dir / "codebase_map.json"
         if codebase_map_file.exists():
             try:
-                with open(codebase_map_file) as f:
+                with open(codebase_map_file, encoding="utf-8") as f:
                     codebase_map = json.load(f)
 
                 discoveries = codebase_map.get("discovered_files", {})
@@ -179,7 +319,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         gotchas_file = memory_dir / "gotchas.md"
         if gotchas_file.exists():
             try:
-                content = gotchas_file.read_text()
+                content = gotchas_file.read_text(encoding="utf-8")
                 if content.strip():
                     result_parts.append("\n## Gotchas")
                     # Take last 1000 chars to avoid too much context
@@ -193,7 +333,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
         patterns_file = memory_dir / "patterns.md"
         if patterns_file.exists():
             try:
-                content = patterns_file.read_text()
+                content = patterns_file.read_text(encoding="utf-8")
                 if content.strip():
                     result_parts.append("\n## Patterns")
                     result_parts.append(

apps/backend/agents/tools_pkg/tools/progress.py

@@ -57,7 +57,7 @@ def create_progress_tools(spec_dir: Path, project_dir: Path) -> list:
             }
 
         try:
-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                 plan = json.load(f)
 
             stats = {

apps/backend/agents/tools_pkg/tools/qa.py

@@ -0,0 +1,208 @@
+"""
+QA Management Tools
+===================
+
+Tools for managing QA status and sign-off in implementation_plan.json.
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from core.file_utils import write_json_atomic
+from spec.validate_pkg.auto_fix import auto_fix_plan
+
+try:
+    from claude_agent_sdk import tool
+
+    SDK_TOOLS_AVAILABLE = True
+except ImportError:
+    SDK_TOOLS_AVAILABLE = False
+    tool = None
+
+
+def _apply_qa_update(
+    plan: dict[str, Any],
+    status: str,
+    issues: list[Any],
+    tests_passed: dict[str, Any],
+) -> int:
+    """
+    Apply QA update to the plan and return the new QA session number.
+
+    Args:
+        plan: The implementation plan dict
+        status: QA status (pending, in_review, approved, rejected, fixes_applied)
+        issues: List of issues found
+        tests_passed: Dict of test results
+
+    Returns:
+        The new QA session number
+    """
+    # Get current QA session number
+    current_qa = plan.get("qa_signoff", {})
+    qa_session = current_qa.get("qa_session", 0)
+    if status in ["in_review", "rejected"]:
+        qa_session += 1
+
+    plan["qa_signoff"] = {
+        "status": status,
+        "qa_session": qa_session,
+        "issues_found": issues,
+        "tests_passed": tests_passed,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "ready_for_qa_revalidation": status == "fixes_applied",
+    }
+
+    # Update plan status to match QA result
+    # This ensures the UI shows the correct column after QA
+    if status == "approved":
+        plan["status"] = "human_review"
+        plan["planStatus"] = "review"
+    elif status == "rejected":
+        plan["status"] = "human_review"
+        plan["planStatus"] = "review"
+
+    plan["last_updated"] = datetime.now(timezone.utc).isoformat()
+
+    return qa_session
+
+
+def create_qa_tools(spec_dir: Path, project_dir: Path) -> list:
+    """
+    Create QA management tools.
+
+    Args:
+        spec_dir: Path to the spec directory
+        project_dir: Path to the project root
+
+    Returns:
+        List of QA tool functions
+    """
+    if not SDK_TOOLS_AVAILABLE:
+        return []
+
+    tools = []
+
+    # -------------------------------------------------------------------------
+    # Tool: update_qa_status
+    # -------------------------------------------------------------------------
+    @tool(
+        "update_qa_status",
+        "Update the QA sign-off status in implementation_plan.json. Use after QA review.",
+        {"status": str, "issues": str, "tests_passed": str},
+    )
+    async def update_qa_status(args: dict[str, Any]) -> dict[str, Any]:
+        """Update QA status in the implementation plan."""
+        status = args["status"]
+        issues_str = args.get("issues", "[]")
+        tests_str = args.get("tests_passed", "{}")
+
+        valid_statuses = [
+            "pending",
+            "in_review",
+            "approved",
+            "rejected",
+            "fixes_applied",
+        ]
+        if status not in valid_statuses:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error: Invalid QA status '{status}'. Must be one of: {valid_statuses}",
+                    }
+                ]
+            }
+
+        plan_file = spec_dir / "implementation_plan.json"
+        if not plan_file.exists():
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "Error: implementation_plan.json not found",
+                    }
+                ]
+            }
+
+        try:
+            # Parse issues and tests
+            try:
+                issues = json.loads(issues_str) if issues_str else []
+            except json.JSONDecodeError:
+                issues = [{"description": issues_str}] if issues_str else []
+
+            try:
+                tests_passed = json.loads(tests_str) if tests_str else {}
+            except json.JSONDecodeError:
+                tests_passed = {}
+
+            with open(plan_file, encoding="utf-8") as f:
+                plan = json.load(f)
+
+            qa_session = _apply_qa_update(plan, status, issues, tests_passed)
+
+            # Use atomic write to prevent file corruption
+            write_json_atomic(plan_file, plan, indent=2)
+
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Updated QA status to '{status}' (session {qa_session})",
+                    }
+                ]
+            }
+
+        except json.JSONDecodeError as e:
+            # Attempt to auto-fix the plan and retry
+            if auto_fix_plan(spec_dir):
+                # Retry after fix
+                try:
+                    with open(plan_file, encoding="utf-8") as f:
+                        plan = json.load(f)
+
+                    qa_session = _apply_qa_update(plan, status, issues, tests_passed)
+                    write_json_atomic(plan_file, plan, indent=2)
+
+                    return {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": f"Updated QA status to '{status}' (session {qa_session}) (after auto-fix)",
+                            }
+                        ]
+                    }
+                except Exception as retry_err:
+                    logging.warning(
+                        f"QA update retry failed after auto-fix: {retry_err} (original error: {e})"
+                    )
+                    return {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": f"Error: QA update failed after auto-fix: {retry_err} (original JSON error: {e})",
+                            }
+                        ]
+                    }
+
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error: Invalid JSON in implementation_plan.json: {e}",
+                    }
+                ]
+            }
+
+        except Exception as e:
+            return {
+                "content": [{"type": "text", "text": f"Error updating QA status: {e}"}]
+            }
+
+    tools.append(update_qa_status)
+
+    return tools

apps/backend/agents/tools_pkg/tools/subtask.py

@@ -6,10 +6,14 @@ Tools for managing subtask status in implementation_plan.json.
 """
 
 import json
+import logging
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+from core.file_utils import write_json_atomic
+from spec.validate_pkg.auto_fix import auto_fix_plan
+
 try:
     from claude_agent_sdk import tool
 
@@ -19,6 +23,43 @@ except ImportError:
     tool = None
 
 
+def _update_subtask_in_plan(
+    plan: dict[str, Any],
+    subtask_id: str,
+    status: str,
+    notes: str,
+) -> bool:
+    """
+    Update a subtask in the plan.
+
+    Args:
+        plan: The implementation plan dict
+        subtask_id: ID of the subtask to update
+        status: New status (pending, in_progress, completed, failed)
+        notes: Optional notes to add
+
+    Returns:
+        True if subtask was found and updated, False otherwise
+    """
+    subtask_found = False
+    for phase in plan.get("phases", []):
+        for subtask in phase.get("subtasks", []):
+            if subtask.get("id") == subtask_id:
+                subtask["status"] = status
+                if notes:
+                    subtask["notes"] = notes
+                subtask["updated_at"] = datetime.now(timezone.utc).isoformat()
+                subtask_found = True
+                break
+        if subtask_found:
+            break
+
+    if subtask_found:
+        plan["last_updated"] = datetime.now(timezone.utc).isoformat()
+
+    return subtask_found
+
+
 def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
     """
     Create subtask management tools.
@@ -72,22 +113,10 @@ def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
             }
 
         try:
-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                 plan = json.load(f)
 
-            # Find and update the subtask
-            subtask_found = False
-            for phase in plan.get("phases", []):
-                for subtask in phase.get("subtasks", []):
-                    if subtask.get("id") == subtask_id:
-                        subtask["status"] = status
-                        if notes:
-                            subtask["notes"] = notes
-                        subtask["updated_at"] = datetime.now(timezone.utc).isoformat()
-                        subtask_found = True
-                        break
-                if subtask_found:
-                    break
+            subtask_found = _update_subtask_in_plan(plan, subtask_id, status, notes)
 
             if not subtask_found:
                 return {
@@ -99,11 +128,8 @@ def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
                     ]
                 }
 
-            # Update plan metadata
-            plan["last_updated"] = datetime.now(timezone.utc).isoformat()
-
-            with open(plan_file, "w") as f:
-                json.dump(plan, f, indent=2)
+            # Use atomic write to prevent file corruption
+            write_json_atomic(plan_file, plan, indent=2)
 
             return {
                 "content": [
@@ -115,6 +141,49 @@ def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
             }
 
         except json.JSONDecodeError as e:
+            # Attempt to auto-fix the plan and retry
+            if auto_fix_plan(spec_dir):
+                # Retry after fix
+                try:
+                    with open(plan_file, encoding="utf-8") as f:
+                        plan = json.load(f)
+
+                    subtask_found = _update_subtask_in_plan(
+                        plan, subtask_id, status, notes
+                    )
+
+                    if subtask_found:
+                        write_json_atomic(plan_file, plan, indent=2)
+                        return {
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": f"Successfully updated subtask '{subtask_id}' to status '{status}' (after auto-fix)",
+                                }
+                            ]
+                        }
+                    else:
+                        return {
+                            "content": [
+                                {
+                                    "type": "text",
+                                    "text": f"Error: Subtask '{subtask_id}' not found in implementation plan (after auto-fix)",
+                                }
+                            ]
+                        }
+                except Exception as retry_err:
+                    logging.warning(
+                        f"Subtask update retry failed after auto-fix: {retry_err}"
+                    )
+                    return {
+                        "content": [
+                            {
+                                "type": "text",
+                                "text": f"Error: Subtask update failed after auto-fix: {retry_err}",
+                            }
+                        ]
+                    }
+
             return {
                 "content": [
                     {

apps/backend/agents/utils.py

@@ -0,0 +1,181 @@
+"""
+Utility Functions for Agent System
+===================================
+
+Helper functions for git operations, plan management, and file syncing.
+"""
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from core.git_executable import run_git
+
+logger = logging.getLogger(__name__)
+
+
+def get_latest_commit(project_dir: Path) -> str | None:
+    """Get the hash of the latest git commit."""
+    result = run_git(
+        ["rev-parse", "HEAD"],
+        cwd=project_dir,
+        timeout=10,
+    )
+    if result.returncode == 0:
+        return result.stdout.strip()
+    return None
+
+
+def get_commit_count(project_dir: Path) -> int:
+    """Get the total number of commits."""
+    result = run_git(
+        ["rev-list", "--count", "HEAD"],
+        cwd=project_dir,
+        timeout=10,
+    )
+    if result.returncode == 0:
+        try:
+            return int(result.stdout.strip())
+        except ValueError:
+            return 0
+    return 0
+
+
+def load_implementation_plan(spec_dir: Path) -> dict | None:
+    """Load the implementation plan JSON."""
+    plan_file = spec_dir / "implementation_plan.json"
+    if not plan_file.exists():
+        return None
+    try:
+        with open(plan_file, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+
+
+def find_subtask_in_plan(plan: dict, subtask_id: str) -> dict | None:
+    """Find a subtask by ID in the plan."""
+    for phase in plan.get("phases", []):
+        for subtask in phase.get("subtasks", []):
+            if subtask.get("id") == subtask_id:
+                return subtask
+    return None
+
+
+def find_phase_for_subtask(plan: dict, subtask_id: str) -> dict | None:
+    """Find the phase containing a subtask."""
+    for phase in plan.get("phases", []):
+        for subtask in phase.get("subtasks", []):
+            if subtask.get("id") == subtask_id:
+                return phase
+    return None
+
+
+def sync_spec_to_source(spec_dir: Path, source_spec_dir: Path | None) -> bool:
+    """
+    Sync ALL spec files from worktree back to source spec directory.
+
+    When running in isolated mode (worktrees), the agent creates and updates
+    many files inside the worktree's spec directory. This function syncs ALL
+    of them back to the main project's spec directory.
+
+    IMPORTANT: Since .auto-claude/ is gitignored, this sync happens to the
+    local filesystem regardless of what branch the user is on. The worktree
+    may be on a different branch (e.g., auto-claude/093-task), but the sync
+    target is always the main project's .auto-claude/specs/ directory.
+
+    Files synced (all files in spec directory):
+    - implementation_plan.json - Task status and subtask completion
+    - build-progress.txt - Session-by-session progress notes
+    - task_logs.json - Execution logs
+    - review_state.json - QA review state
+    - critique_report.json - Spec critique findings
+    - suggested_commit_message.txt - Commit suggestions
+    - REGRESSION_TEST_REPORT.md - Test regression report
+    - spec.md, context.json, etc. - Original spec files (for completeness)
+    - memory/ directory - Codebase map, patterns, gotchas, session insights
+
+    Args:
+        spec_dir: Current spec directory (inside worktree)
+        source_spec_dir: Original spec directory in main project (outside worktree)
+
+    Returns:
+        True if sync was performed, False if not needed or failed
+    """
+    # Skip if no source specified or same path (not in worktree mode)
+    if not source_spec_dir:
+        return False
+
+    # Resolve paths and check if they're different
+    spec_dir_resolved = spec_dir.resolve()
+    source_spec_dir_resolved = source_spec_dir.resolve()
+
+    if spec_dir_resolved == source_spec_dir_resolved:
+        return False  # Same directory, no sync needed
+
+    synced_any = False
+
+    # Ensure source directory exists
+    source_spec_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Sync all files and directories from worktree spec to source spec
+        for item in spec_dir.iterdir():
+            # Skip symlinks to prevent path traversal attacks
+            if item.is_symlink():
+                logger.warning(f"Skipping symlink during sync: {item.name}")
+                continue
+
+            source_item = source_spec_dir / item.name
+
+            if item.is_file():
+                # Copy file (preserves timestamps)
+                shutil.copy2(item, source_item)
+                logger.debug(f"Synced {item.name} to source")
+                synced_any = True
+
+            elif item.is_dir():
+                # Recursively sync directory
+                _sync_directory(item, source_item)
+                synced_any = True
+
+    except Exception as e:
+        logger.warning(f"Failed to sync spec directory to source: {e}")
+
+    return synced_any
+
+
+def _sync_directory(source_dir: Path, target_dir: Path) -> None:
+    """
+    Recursively sync a directory from source to target.
+
+    Args:
+        source_dir: Source directory (in worktree)
+        target_dir: Target directory (in main project)
+    """
+    # Create target directory if needed
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    for item in source_dir.iterdir():
+        # Skip symlinks to prevent path traversal attacks
+        if item.is_symlink():
+            logger.warning(
+                f"Skipping symlink during sync: {source_dir.name}/{item.name}"
+            )
+            continue
+
+        target_item = target_dir / item.name
+
+        if item.is_file():
+            shutil.copy2(item, target_item)
+            logger.debug(f"Synced {source_dir.name}/{item.name} to source")
+        elif item.is_dir():
+            # Recurse into subdirectories
+            _sync_directory(item, target_item)
+
+
+# Keep the old name as an alias for backward compatibility
+def sync_plan_to_source(spec_dir: Path, source_spec_dir: Path | None) -> bool:
+    """Alias for sync_spec_to_source for backward compatibility."""
+    return sync_spec_to_source(spec_dir, source_spec_dir)

apps/backend/analysis/__init__.py

@@ -6,6 +6,9 @@ Code analysis and project scanning tools.
 """
 
 # Import from analyzers subpackage (these are the modular analyzers)
+
+from __future__ import annotations
+
 from .analyzers import (
     ProjectAnalyzer as ModularProjectAnalyzer,
 )

apps/backend/analysis/analyzer.py

@@ -27,6 +27,8 @@ This module now serves as a facade to the modular analyzer system in the analyze
 All actual implementation is in focused submodules for better maintainability.
 """
 
+from __future__ import annotations
+
 import json
 from pathlib import Path
 

apps/backend/analysis/analyzers/__init__.py

@@ -11,6 +11,8 @@ Main exports:
 - analyze_service: Convenience function for service analysis
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 
@@ -44,7 +46,7 @@ def analyze_project(project_dir: Path, output_file: Path | None = None) -> dict:
 
     if output_file:
         output_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w") as f:
+        with open(output_file, "w", encoding="utf-8") as f:
             json.dump(results, f, indent=2)
         print(f"Project index saved to: {output_file}")
 
@@ -85,7 +87,7 @@ def analyze_service(
 
     if output_file:
         output_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w") as f:
+        with open(output_file, "w", encoding="utf-8") as f:
             json.dump(results, f, indent=2)
         print(f"Service analysis saved to: {output_file}")
 

apps/backend/analysis/analyzers/base.py

@@ -5,6 +5,8 @@ Base Analyzer Module
 Provides common constants, utilities, and base functionality shared across all analyzers.
 """
 
+from __future__ import annotations
+
 import json
 from pathlib import Path
 
@@ -97,7 +99,7 @@ class BaseAnalyzer:
     def _read_file(self, path: str) -> str:
         """Read a file relative to the analyzer's path."""
         try:
-            return (self.path / path).read_text()
+            return (self.path / path).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             return ""
 

apps/backend/analysis/analyzers/context/__init__.py

@@ -5,6 +5,8 @@ Context Analyzer Package
 Contains specialized detectors for comprehensive project context analysis.
 """
 
+from __future__ import annotations
+
 from .api_docs_detector import ApiDocsDetector
 from .auth_detector import AuthDetector
 from .env_detector import EnvironmentDetector

apps/backend/analysis/analyzers/context/api_docs_detector.py

@@ -8,6 +8,8 @@ Detects API documentation tools and configurations:
 - API documentation endpoints
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 

apps/backend/analysis/analyzers/context/auth_detector.py

@@ -11,6 +11,8 @@ Detects authentication and authorization patterns:
 - Auth middleware and decorators
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any
@@ -124,7 +126,7 @@ class AuthDetector(BaseAnalyzer):
 
         for py_file in all_py_files:
             try:
-                content = py_file.read_text()
+                content = py_file.read_text(encoding="utf-8")
                 # Find custom decorators
                 if (
                     "@require" in content

apps/backend/analysis/analyzers/context/env_detector.py

@@ -9,6 +9,8 @@ Detects and analyzes environment variables from multiple sources:
 - Source code (os.getenv, process.env)
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any

apps/backend/analysis/analyzers/context/jobs_detector.py

@@ -9,6 +9,8 @@ Detects background job and task queue systems:
 - Scheduled tasks and cron jobs
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any
@@ -50,7 +52,7 @@ class JobsDetector(BaseAnalyzer):
         tasks = []
         for task_file in celery_files:
             try:
-                content = task_file.read_text()
+                content = task_file.read_text(encoding="utf-8")
                 # Find @celery.task or @shared_task decorators
                 task_pattern = r"@(?:celery\.task|shared_task|app\.task)\s*(?:\([^)]*\))?\s*def\s+(\w+)"
                 task_matches = re.findall(task_pattern, content)

apps/backend/analysis/analyzers/context/migrations_detector.py

@@ -10,6 +10,8 @@ Detects database migration tools and configurations:
 - Prisma
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 

apps/backend/analysis/analyzers/context/monitoring_detector.py

@@ -9,6 +9,8 @@ Detects monitoring and observability setup:
 - Logging infrastructure
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 
@@ -75,7 +77,7 @@ class MonitoringDetector(BaseAnalyzer):
                 continue
 
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
                 # Look for actual Prometheus imports or usage patterns
                 prometheus_patterns = [
                     "from prometheus_client import",

apps/backend/analysis/analyzers/context/services_detector.py

@@ -13,6 +13,8 @@ Detects external service integrations based on dependencies:
 - Monitoring tools (Sentry, Datadog, New Relic)
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any

apps/backend/analysis/analyzers/context_analyzer.py

@@ -14,6 +14,8 @@ Orchestrates comprehensive project context analysis including:
 This module delegates to specialized detectors for clean separation of concerns.
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 

apps/backend/analysis/analyzers/database_detector.py

@@ -7,6 +7,8 @@ Detects database models and schemas across different ORMs:
 - JavaScript/TypeScript: Prisma, TypeORM, Drizzle, Mongoose
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 
@@ -50,7 +52,7 @@ class DatabaseDetector(BaseAnalyzer):
 
         for file_path in py_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -117,7 +119,7 @@ class DatabaseDetector(BaseAnalyzer):
 
         for file_path in model_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -166,7 +168,7 @@ class DatabaseDetector(BaseAnalyzer):
             return models
 
         try:
-            content = schema_file.read_text()
+            content = schema_file.read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             return models
 
@@ -214,7 +216,7 @@ class DatabaseDetector(BaseAnalyzer):
 
         for file_path in ts_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -263,7 +265,7 @@ class DatabaseDetector(BaseAnalyzer):
 
         for file_path in schema_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -293,7 +295,7 @@ class DatabaseDetector(BaseAnalyzer):
 
         for file_path in model_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 

apps/backend/analysis/analyzers/framework_analyzer.py

@@ -6,6 +6,8 @@ Detects programming languages, frameworks, and related technologies across diffe
 Supports Python, Node.js/TypeScript, Go, Rust, and Ruby frameworks.
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 
@@ -73,6 +75,15 @@ class FrameworkAnalyzer(BaseAnalyzer):
             content = self._read_file("Cargo.toml")
             self._detect_rust_framework(content)
 
+        # Swift/iOS detection (check BEFORE Ruby - iOS projects often have Gemfile for CocoaPods/Fastlane)
+        elif self._exists("Package.swift") or any(self.path.glob("*.xcodeproj")):
+            self.analysis["language"] = "Swift"
+            if self._exists("Package.swift"):
+                self.analysis["package_manager"] = "Swift Package Manager"
+            else:
+                self.analysis["package_manager"] = "Xcode"
+            self._detect_swift_framework()
+
         # Ruby detection
         elif self._exists("Gemfile"):
             self.analysis["language"] = "Ruby"
@@ -288,12 +299,115 @@ class FrameworkAnalyzer(BaseAnalyzer):
         if "sidekiq" in content.lower():
             self.analysis["task_queue"] = "Sidekiq"
 
+    def _detect_swift_framework(self) -> None:
+        """Detect Swift/iOS framework and dependencies."""
+        try:
+            # Scan Swift files for imports, excluding hidden/vendor dirs
+            swift_files = []
+            for swift_file in self.path.rglob("*.swift"):
+                # Skip hidden directories, node_modules, .worktrees, etc.
+                if any(
+                    part.startswith(".") or part in ("node_modules", "Pods", "Carthage")
+                    for part in swift_file.parts
+                ):
+                    continue
+                swift_files.append(swift_file)
+                if len(swift_files) >= 50:  # Limit for performance
+                    break
+
+            imports = set()
+            for swift_file in swift_files:
+                try:
+                    content = swift_file.read_text(encoding="utf-8", errors="ignore")
+                    for line in content.split("\n"):
+                        line = line.strip()
+                        if line.startswith("import "):
+                            module = line.replace("import ", "").split()[0]
+                            imports.add(module)
+                except Exception:
+                    continue
+
+            # Detect UI framework
+            if "SwiftUI" in imports:
+                self.analysis["framework"] = "SwiftUI"
+                self.analysis["type"] = "mobile"
+            elif "UIKit" in imports:
+                self.analysis["framework"] = "UIKit"
+                self.analysis["type"] = "mobile"
+            elif "AppKit" in imports:
+                self.analysis["framework"] = "AppKit"
+                self.analysis["type"] = "desktop"
+
+            # Detect iOS/Apple frameworks
+            apple_frameworks = []
+            framework_map = {
+                "Combine": "Combine",
+                "CoreData": "CoreData",
+                "MapKit": "MapKit",
+                "WidgetKit": "WidgetKit",
+                "CoreLocation": "CoreLocation",
+                "StoreKit": "StoreKit",
+                "CloudKit": "CloudKit",
+                "ActivityKit": "ActivityKit",
+                "UserNotifications": "UserNotifications",
+            }
+            for key, name in framework_map.items():
+                if key in imports:
+                    apple_frameworks.append(name)
+
+            if apple_frameworks:
+                self.analysis["apple_frameworks"] = apple_frameworks
+
+            # Detect SPM dependencies from Package.swift or xcodeproj
+            dependencies = self._detect_spm_dependencies()
+            if dependencies:
+                self.analysis["spm_dependencies"] = dependencies
+        except Exception:
+            # Silently fail if Swift detection has issues
+            pass
+
+    def _detect_spm_dependencies(self) -> list[str]:
+        """Detect Swift Package Manager dependencies."""
+        dependencies = []
+
+        # Try Package.swift first
+        if self._exists("Package.swift"):
+            content = self._read_file("Package.swift")
+            # Look for .package(url: "...", patterns
+            import re
+
+            urls = re.findall(r'\.package\s*\([^)]*url:\s*"([^"]+)"', content)
+            for url in urls:
+                # Extract package name from URL
+                name = url.rstrip("/").split("/")[-1].replace(".git", "")
+                if name:
+                    dependencies.append(name)
+
+        # Also check xcodeproj for XCRemoteSwiftPackageReference
+        for xcodeproj in self.path.glob("*.xcodeproj"):
+            pbxproj = xcodeproj / "project.pbxproj"
+            if pbxproj.exists():
+                try:
+                    content = pbxproj.read_text(encoding="utf-8", errors="ignore")
+                    import re
+
+                    # Match repositoryURL patterns
+                    urls = re.findall(r'repositoryURL\s*=\s*"([^"]+)"', content)
+                    for url in urls:
+                        name = url.rstrip("/").split("/")[-1].replace(".git", "")
+                        if name and name not in dependencies:
+                            dependencies.append(name)
+                except Exception:
+                    continue
+
+        return dependencies
+
     def _detect_node_package_manager(self) -> str:
         """Detect Node.js package manager."""
         if self._exists("pnpm-lock.yaml"):
             return "pnpm"
         elif self._exists("yarn.lock"):
             return "yarn"
-        elif self._exists("bun.lockb"):
+        elif self._exists("bun.lockb") or self._exists("bun.lock"):
             return "bun"
         return "npm"

apps/backend/analysis/analyzers/port_detector.py

@@ -6,6 +6,8 @@ Detects application ports from multiple sources including entry points,
 environment files, Docker Compose, configuration files, and scripts.
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any

apps/backend/analysis/analyzers/project_analyzer_module.py

@@ -5,6 +5,8 @@ Project Analyzer Module
 Analyzes entire projects, detecting monorepo structures, services, infrastructure, and conventions.
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 from typing import Any
 
@@ -285,6 +287,6 @@ class ProjectAnalyzer:
 
     def _read_file(self, path: str) -> str:
         try:
-            return (self.project_dir / path).read_text()
+            return (self.project_dir / path).read_text(encoding="utf-8")
         except (OSError, UnicodeDecodeError):
             return ""

apps/backend/analysis/analyzers/route_detector.py

@@ -9,6 +9,8 @@ Detects API routes and endpoints across different frameworks:
 - Rust: Axum, Actix
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 
@@ -64,7 +66,7 @@ class RouteDetector(BaseAnalyzer):
 
         for file_path in files_to_check:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -128,7 +130,7 @@ class RouteDetector(BaseAnalyzer):
 
         for file_path in files_to_check:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -177,7 +179,7 @@ class RouteDetector(BaseAnalyzer):
 
         for file_path in url_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -216,7 +218,7 @@ class RouteDetector(BaseAnalyzer):
         files_to_check = js_files + ts_files
         for file_path in files_to_check:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -281,7 +283,7 @@ class RouteDetector(BaseAnalyzer):
                 route_path = re.sub(r"\[([^\]]+)\]", r":\1", route_path)
 
                 try:
-                    content = route_file.read_text()
+                    content = route_file.read_text(encoding="utf-8")
                     # Detect exported methods: export async function GET(request)
                     methods = re.findall(
                         r"export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)",
@@ -346,7 +348,7 @@ class RouteDetector(BaseAnalyzer):
 
         for file_path in go_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 
@@ -382,7 +384,7 @@ class RouteDetector(BaseAnalyzer):
 
         for file_path in rust_files:
             try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
                 continue
 

apps/backend/analysis/analyzers/service_analyzer.py

@@ -6,6 +6,8 @@ Main ServiceAnalyzer class that coordinates all analysis for a single service/pa
 Integrates framework detection, route analysis, database models, and context extraction.
 """
 
+from __future__ import annotations
+
 import re
 from pathlib import Path
 from typing import Any

apps/backend/analysis/ci_discovery.py

@@ -22,6 +22,8 @@ Usage:
         print(f"Test Commands: {result.test_commands}")
 """
 
+from __future__ import annotations
+
 import json
 import re
 from dataclasses import dataclass, field
@@ -161,7 +163,7 @@ class CIDiscovery:
             )
 
             try:
-                content = wf_file.read_text()
+                content = wf_file.read_text(encoding="utf-8")
                 workflow_data = self._parse_yaml(content)
 
                 if not workflow_data:
@@ -240,7 +242,7 @@ class CIDiscovery:
         )
 
         try:
-            content = config_file.read_text()
+            content = config_file.read_text(encoding="utf-8")
             data = self._parse_yaml(content)
 
             if not data:
@@ -310,7 +312,7 @@ class CIDiscovery:
         )
 
         try:
-            content = config_file.read_text()
+            content = config_file.read_text(encoding="utf-8")
             data = self._parse_yaml(content)
 
             if not data:
@@ -368,7 +370,7 @@ class CIDiscovery:
         )
 
         try:
-            content = jenkinsfile.read_text()
+            content = jenkinsfile.read_text(encoding="utf-8")
 
             # Extract sh commands using regex
             sh_pattern = re.compile(r'sh\s+[\'"]([^\'"]+)[\'"]')

apps/backend/analysis/insight_extractor.py

@@ -9,6 +9,8 @@ Uses the Claude Agent SDK (same as the rest of the system) for extraction.
 Falls back to generic insights if extraction fails (never blocks the build).
 """
 
+from __future__ import annotations
+
 import json
 import logging
 import os
@@ -28,8 +30,12 @@ except ImportError:
     ClaudeAgentOptions = None
     ClaudeSDKClient = None
 
+from core.auth import ensure_claude_code_oauth_token, get_auth_token
+
 # Default model for insight extraction (fast and cheap)
-DEFAULT_EXTRACTION_MODEL = "claude-3-5-haiku-latest"
+# Note: Using Haiku 4.5 for fast, cheap extraction. Haiku does not support
+# extended thinking, so thinking_default is set to "none" in models.py
+DEFAULT_EXTRACTION_MODEL = "claude-haiku-4-5-20251001"
 
 # Maximum diff size to send to the LLM (avoid context limits)
 MAX_DIFF_CHARS = 15000
@@ -40,10 +46,10 @@ MAX_ATTEMPTS_TO_INCLUDE = 3
 
 def is_extraction_enabled() -> bool:
     """Check if insight extraction is enabled."""
-    # Extraction requires Claude SDK and OAuth token
+    # Extraction requires Claude SDK and authentication token
     if not SDK_AVAILABLE:
         return False
-    if not os.environ.get("CLAUDE_CODE_OAUTH_TOKEN"):
+    if not get_auth_token():
         return False
     enabled_str = os.environ.get("INSIGHT_EXTRACTION_ENABLED", "true").lower()
     return enabled_str in ("true", "1", "yes")
@@ -231,7 +237,7 @@ def _get_subtask_description(spec_dir: Path, subtask_id: str) -> str:
         return f"Subtask: {subtask_id}"
 
     try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
             plan = json.load(f)
 
         # Search through phases for the subtask
@@ -274,7 +280,7 @@ def _build_extraction_prompt(inputs: dict) -> str:
     prompt_file = Path(__file__).parent / "prompts" / "insight_extractor.md"
 
     if prompt_file.exists():
-        base_prompt = prompt_file.read_text()
+        base_prompt = prompt_file.read_text(encoding="utf-8")
     else:
         # Fallback if prompt file missing
         base_prompt = """Extract structured insights from this coding session.
@@ -348,11 +354,13 @@ async def run_insight_extraction(
         logger.warning("Claude SDK not available, skipping insight extraction")
         return None
 
-    oauth_token = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN")
-    if not oauth_token:
-        logger.warning("CLAUDE_CODE_OAUTH_TOKEN not set, skipping insight extraction")
+    if not get_auth_token():
+        logger.warning("No authentication token found, skipping insight extraction")
         return None
 
+    # Ensure SDK can find the token
+    ensure_claude_code_oauth_token()
+
     model = get_extraction_model()
     prompt = _build_extraction_prompt(inputs)
 
@@ -360,19 +368,19 @@ async def run_insight_extraction(
     cwd = str(project_dir.resolve()) if project_dir else os.getcwd()
 
     try:
-        # Create a minimal SDK client for insight extraction
-        # No tools needed - just text generation
-        client = ClaudeSDKClient(
-            options=ClaudeAgentOptions(
-                model=model,
-                system_prompt=(
-                    "You are an expert code analyst. You extract structured insights from coding sessions. "
-                    "Always respond with valid JSON only, no markdown formatting or explanations."
-                ),
-                allowed_tools=[],  # No tools needed for extraction
-                max_turns=1,  # Single turn extraction
-                cwd=cwd,
-            )
+        # Use simple_client for insight extraction
+        from pathlib import Path
+
+        from core.simple_client import create_simple_client
+
+        client = create_simple_client(
+            agent_type="insights",
+            model=model,
+            system_prompt=(
+                "You are an expert code analyst. You extract structured insights from coding sessions. "
+                "Always respond with valid JSON only, no markdown formatting or explanations."
+            ),
+            cwd=Path(cwd) if cwd else None,
         )
 
         # Use async context manager
@@ -381,12 +389,40 @@ async def run_insight_extraction(
 
             # Collect the response
             response_text = ""
+            message_count = 0
+            text_blocks_found = 0
+
             async for msg in client.receive_response():
                 msg_type = type(msg).__name__
+                message_count += 1
+
                 if msg_type == "AssistantMessage" and hasattr(msg, "content"):
                     for block in msg.content:
-                        if hasattr(block, "text"):
-                            response_text += block.text
+                        # Must check block type - only TextBlock has .text attribute
+                        block_type = type(block).__name__
+                        if block_type == "TextBlock" and hasattr(block, "text"):
+                            text_blocks_found += 1
+                            if block.text:  # Only add non-empty text
+                                response_text += block.text
+                            else:
+                                logger.debug(
+                                    f"Found empty TextBlock in response (block #{text_blocks_found})"
+                                )
+
+            # Log response collection summary
+            logger.debug(
+                f"Insight extraction response: {message_count} messages, "
+                f"{text_blocks_found} text blocks, {len(response_text)} chars collected"
+            )
+
+            # Validate we received content before parsing
+            if not response_text.strip():
+                logger.warning(
+                    f"Insight extraction returned empty response. "
+                    f"Messages received: {message_count}, TextBlocks found: {text_blocks_found}. "
+                    f"This may indicate the AI model did not respond with text content."
+                )
+                return None
 
         # Parse JSON from response
         return parse_insights(response_text)
@@ -409,6 +445,11 @@ def parse_insights(response_text: str) -> dict | None:
     # Try to extract JSON from the response
     text = response_text.strip()
 
+    # Early validation - check for empty response
+    if not text:
+        logger.warning("Cannot parse insights: response text is empty")
+        return None
+
     # Handle markdown code blocks
     if text.startswith("```"):
         # Remove code block markers
@@ -416,17 +457,26 @@ def parse_insights(response_text: str) -> dict | None:
         # Remove first line (```json or ```)
         if lines[0].startswith("```"):
             lines = lines[1:]
-        # Remove last line if it's ``
+        # Remove last line if it's ```
         if lines and lines[-1].strip() == "```":
             lines = lines[:-1]
-        text = "\n".join(lines)
+        text = "\n".join(lines).strip()
+
+        # Check again after removing code blocks
+        if not text:
+            logger.warning(
+                "Cannot parse insights: response contained only markdown code block markers with no content"
+            )
+            return None
 
     try:
         insights = json.loads(text)
 
         # Validate structure
         if not isinstance(insights, dict):
-            logger.warning("Insights is not a dict")
+            logger.warning(
+                f"Insights is not a dict, got type: {type(insights).__name__}"
+            )
             return None
 
         # Ensure required keys exist with defaults
@@ -440,7 +490,13 @@ def parse_insights(response_text: str) -> dict | None:
 
     except json.JSONDecodeError as e:
         logger.warning(f"Failed to parse insights JSON: {e}")
-        logger.debug(f"Response text was: {text[:500]}")
+        # Show more context in the error message
+        preview_length = min(500, len(text))
+        logger.warning(
+            f"Response text preview (first {preview_length} chars): {text[:preview_length]}"
+        )
+        if len(text) > preview_length:
+            logger.warning(f"... (total length: {len(text)} chars)")
         return None
 
 

apps/backend/analysis/project_analyzer.py

@@ -28,6 +28,9 @@ needed for the detected tech stack, while blocking dangerous operations.
 """
 
 # Re-export all public API from the project module
+
+from __future__ import annotations
+
 from project import (
     # Command registries
     BASE_COMMANDS,

apps/backend/analysis/risk_classifier.py

@@ -21,6 +21,8 @@ Usage:
     test_types = classifier.get_required_test_types(spec_dir)
 """
 
+from __future__ import annotations
+
 import json
 from dataclasses import dataclass, field
 from pathlib import Path

apps/backend/analysis/security_scanner.py

@@ -21,6 +21,8 @@ Usage:
         print("Security issues found - blocking QA approval")
 """
 
+from __future__ import annotations
+
 import json
 import subprocess
 from dataclasses import dataclass, field

apps/backend/analysis/test_discovery.py

@@ -22,6 +22,8 @@ Usage:
     print(f"Test command: {result['test_command']}")
 """
 
+from __future__ import annotations
+
 import json
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -273,7 +275,7 @@ class TestDiscovery:
             return "yarn"
         if (project_dir / "package-lock.json").exists():
             return "npm"
-        if (project_dir / "bun.lockb").exists():
+        if (project_dir / "bun.lockb").exists() or (project_dir / "bun.lock").exists():
             return "bun"
         if (project_dir / "uv.lock").exists():
             return "uv"
@@ -300,7 +302,7 @@ class TestDiscovery:
         try:
             with open(package_json, encoding="utf-8") as f:
                 pkg = json.load(f)
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
             return
 
         deps = pkg.get("dependencies", {})
@@ -396,7 +398,7 @@ class TestDiscovery:
         # Check pyproject.toml
         pyproject = project_dir / "pyproject.toml"
         if pyproject.exists():
-            content = pyproject.read_text()
+            content = pyproject.read_text(encoding="utf-8")
 
             # Check for pytest
             if "pytest" in content:
@@ -416,7 +418,7 @@ class TestDiscovery:
         # Check requirements.txt
         requirements = project_dir / "requirements.txt"
         if requirements.exists():
-            content = requirements.read_text().lower()
+            content = requirements.read_text(encoding="utf-8").lower()
             if "pytest" in content and not any(
                 f.name == "pytest" for f in result.frameworks
             ):
@@ -494,7 +496,7 @@ class TestDiscovery:
         if not gemfile.exists():
             return
 
-        content = gemfile.read_text().lower()
+        content = gemfile.read_text(encoding="utf-8").lower()
 
         if "rspec" in content or (project_dir / ".rspec").exists():
             result.frameworks.append(

apps/backend/analyzer.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Analyzer facade module.
+
+Provides backward compatibility for scripts that import from analyzer.py at the root.
+Actual implementation is in analysis/analyzer.py.
+"""
+
+from analysis.analyzer import (
+    ProjectAnalyzer,
+    ServiceAnalyzer,
+    analyze_project,
+    analyze_service,
+    main,
+)
+
+__all__ = [
+    "ServiceAnalyzer",
+    "ProjectAnalyzer",
+    "analyze_project",
+    "analyze_service",
+    "main",
+]
+
+if __name__ == "__main__":
+    main()

apps/backend/auto_claude_tools.py

@@ -0,0 +1,36 @@
+"""
+Auto Claude tools module facade.
+
+Provides MCP tools for agent operations.
+Re-exports from agents.tools_pkg for clean imports.
+"""
+
+from agents.tools_pkg.models import (  # noqa: F401
+    ELECTRON_TOOLS,
+    TOOL_GET_BUILD_PROGRESS,
+    TOOL_GET_SESSION_CONTEXT,
+    TOOL_RECORD_DISCOVERY,
+    TOOL_RECORD_GOTCHA,
+    TOOL_UPDATE_QA_STATUS,
+    TOOL_UPDATE_SUBTASK_STATUS,
+    is_electron_mcp_enabled,
+)
+from agents.tools_pkg.permissions import get_allowed_tools  # noqa: F401
+from agents.tools_pkg.registry import (  # noqa: F401
+    create_auto_claude_mcp_server,
+    is_tools_available,
+)
+
+__all__ = [
+    "create_auto_claude_mcp_server",
+    "get_allowed_tools",
+    "is_tools_available",
+    "TOOL_UPDATE_SUBTASK_STATUS",
+    "TOOL_GET_BUILD_PROGRESS",
+    "TOOL_RECORD_DISCOVERY",
+    "TOOL_RECORD_GOTCHA",
+    "TOOL_GET_SESSION_CONTEXT",
+    "TOOL_UPDATE_QA_STATUS",
+    "ELECTRON_TOOLS",
+    "is_electron_mcp_enabled",
+]

apps/backend/cli/batch_commands.py

@@ -0,0 +1,266 @@
+"""
+Batch Task Management Commands
+==============================
+
+Commands for creating and managing multiple tasks from batch files.
+"""
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+from ui import highlight, print_status
+
+
+def handle_batch_create_command(batch_file: str, project_dir: str) -> bool:
+    """
+    Create multiple tasks from a batch JSON file.
+
+    Args:
+        batch_file: Path to JSON file with task definitions
+        project_dir: Project directory
+
+    Returns:
+        True if successful
+    """
+    batch_path = Path(batch_file)
+
+    if not batch_path.exists():
+        print_status(f"Batch file not found: {batch_file}", "error")
+        return False
+
+    try:
+        with open(batch_path, encoding="utf-8") as f:
+            batch_data = json.load(f)
+    except json.JSONDecodeError as e:
+        print_status(f"Invalid JSON in batch file: {e}", "error")
+        return False
+
+    tasks = batch_data.get("tasks", [])
+    if not tasks:
+        print_status("No tasks found in batch file", "warning")
+        return False
+
+    print_status(f"Creating {len(tasks)} tasks from batch file", "info")
+    print()
+
+    specs_dir = Path(project_dir) / ".auto-claude" / "specs"
+    specs_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find next spec ID
+    existing_specs = [d.name for d in specs_dir.iterdir() if d.is_dir()]
+    next_id = (
+        max([int(s.split("-")[0]) for s in existing_specs if s[0].isdigit()] or [0]) + 1
+    )
+
+    created_specs = []
+
+    for idx, task in enumerate(tasks, 1):
+        spec_id = f"{next_id:03d}"
+        task_title = task.get("title", f"Task {idx}")
+        task_slug = task_title.lower().replace(" ", "-")[:50]
+        spec_name = f"{spec_id}-{task_slug}"
+        spec_dir = specs_dir / spec_name
+        spec_dir.mkdir(exist_ok=True)
+
+        # Create requirements.json
+        requirements = {
+            "task_description": task.get("description", task_title),
+            "description": task.get("description", task_title),
+            "workflow_type": task.get("workflow_type", "feature"),
+            "services_involved": task.get("services", ["frontend"]),
+            "priority": task.get("priority", 5),
+            "complexity_inferred": task.get("complexity", "standard"),
+            "inferred_from": {},
+            "created_at": Path(spec_dir).stat().st_mtime,
+            "estimate": {
+                "estimated_hours": task.get("estimated_hours", 4.0),
+                "estimated_days": task.get("estimated_days", 0.5),
+            },
+        }
+
+        req_file = spec_dir / "requirements.json"
+        with open(req_file, "w", encoding="utf-8") as f:
+            json.dump(requirements, f, indent=2, default=str)
+
+        created_specs.append(
+            {
+                "id": spec_id,
+                "name": spec_name,
+                "title": task_title,
+                "status": "pending_spec_creation",
+            }
+        )
+
+        print_status(
+            f"[{idx}/{len(tasks)}] Created {spec_id} - {task_title}", "success"
+        )
+        next_id += 1
+
+    print()
+    print_status(f"Created {len(created_specs)} spec(s) successfully", "success")
+    print()
+
+    # Show summary
+    print(highlight("Next steps:"))
+    print("  1. Generate specs: spec_runner.py --continue <spec_id>")
+    print("  2. Approve specs and build them")
+    print("  3. Run: python run.py --spec <id> to execute")
+
+    return True
+
+
+def handle_batch_status_command(project_dir: str) -> bool:
+    """
+    Show status of all specs in project.
+
+    Args:
+        project_dir: Project directory
+
+    Returns:
+        True if successful
+    """
+    specs_dir = Path(project_dir) / ".auto-claude" / "specs"
+
+    if not specs_dir.exists():
+        print_status("No specs found in project", "warning")
+        return True
+
+    specs = sorted([d for d in specs_dir.iterdir() if d.is_dir()])
+
+    if not specs:
+        print_status("No specs found", "warning")
+        return True
+
+    print_status(f"Found {len(specs)} spec(s)", "info")
+    print()
+
+    for spec_dir in specs:
+        spec_name = spec_dir.name
+        req_file = spec_dir / "requirements.json"
+
+        status = "unknown"
+        title = spec_name
+
+        if req_file.exists():
+            try:
+                with open(req_file, encoding="utf-8") as f:
+                    req = json.load(f)
+                    title = req.get("task_description", title)
+            except json.JSONDecodeError:
+                pass
+
+        # Determine status
+        if (spec_dir / "spec.md").exists():
+            status = "spec_created"
+        elif (spec_dir / "implementation_plan.json").exists():
+            status = "building"
+        elif (spec_dir / "qa_report.md").exists():
+            status = "qa_approved"
+        else:
+            status = "pending_spec"
+
+        status_icon = {
+            "pending_spec": "⏳",
+            "spec_created": "📋",
+            "building": "⚙️",
+            "qa_approved": "✅",
+            "unknown": "❓",
+        }.get(status, "❓")
+
+        print(f"{status_icon} {spec_name:<40} {title}")
+
+    return True
+
+
+def handle_batch_cleanup_command(project_dir: str, dry_run: bool = True) -> bool:
+    """
+    Clean up completed specs and worktrees.
+
+    Args:
+        project_dir: Project directory
+        dry_run: If True, show what would be deleted
+
+    Returns:
+        True if successful
+    """
+    specs_dir = Path(project_dir) / ".auto-claude" / "specs"
+    worktrees_dir = Path(project_dir) / ".auto-claude" / "worktrees" / "tasks"
+
+    if not specs_dir.exists():
+        print_status("No specs directory found", "info")
+        return True
+
+    # Find completed specs
+    completed = []
+    for spec_dir in specs_dir.iterdir():
+        if spec_dir.is_dir() and (spec_dir / "qa_report.md").exists():
+            completed.append(spec_dir.name)
+
+    if not completed:
+        print_status("No completed specs to clean up", "info")
+        return True
+
+    print_status(f"Found {len(completed)} completed spec(s)", "info")
+
+    if dry_run:
+        print()
+        print("Would remove:")
+        for spec_name in completed:
+            print(f"  - {spec_name}")
+            wt_path = worktrees_dir / spec_name
+            if wt_path.exists():
+                print(f"    └─ .auto-claude/worktrees/tasks/{spec_name}/")
+        print()
+        print("Run with --no-dry-run to actually delete")
+    else:
+        # Actually delete specs and worktrees
+        deleted_count = 0
+        for spec_name in completed:
+            spec_path = specs_dir / spec_name
+            wt_path = worktrees_dir / spec_name
+
+            # Remove worktree first (if exists)
+            if wt_path.exists():
+                try:
+                    result = subprocess.run(
+                        ["git", "worktree", "remove", "--force", str(wt_path)],
+                        cwd=project_dir,
+                        capture_output=True,
+                        text=True,
+                        timeout=30,
+                    )
+                    if result.returncode == 0:
+                        print_status(f"Removed worktree: {spec_name}", "success")
+                    else:
+                        # Fallback: remove directory manually if git fails
+                        shutil.rmtree(wt_path, ignore_errors=True)
+                        print_status(
+                            f"Removed worktree directory: {spec_name}", "success"
+                        )
+                except subprocess.TimeoutExpired:
+                    # Timeout: fall back to manual removal
+                    shutil.rmtree(wt_path, ignore_errors=True)
+                    print_status(
+                        f"Worktree removal timed out, removed directory: {spec_name}",
+                        "warning",
+                    )
+                except Exception as e:
+                    print_status(
+                        f"Failed to remove worktree {spec_name}: {e}", "warning"
+                    )
+
+            # Remove spec directory
+            if spec_path.exists():
+                try:
+                    shutil.rmtree(spec_path)
+                    print_status(f"Removed spec: {spec_name}", "success")
+                    deleted_count += 1
+                except Exception as e:
+                    print_status(f"Failed to remove spec {spec_name}: {e}", "error")
+
+        print()
+        print_status(f"Cleaned up {deleted_count} spec(s)", "info")
+
+    return True

apps/backend/cli/build_commands.py

@@ -68,7 +68,7 @@ def handle_build_command(
     Args:
         project_dir: Project root directory
         spec_dir: Spec directory path
-        model: Model to use
+        model: Model to use (used as default; may be overridden by task_metadata.json)
         max_iterations: Maximum number of iterations (None for unlimited)
         verbose: Enable verbose output
         force_isolated: Force isolated workspace mode
@@ -79,21 +79,37 @@ def handle_build_command(
         base_branch: Base branch for worktree creation (default: current branch)
     """
     # Lazy imports to avoid loading heavy modules
-    from agent import run_autonomous_agent, sync_plan_to_source
+    from agent import run_autonomous_agent, sync_spec_to_source
     from debug import (
         debug,
         debug_info,
         debug_section,
         debug_success,
     )
+    from phase_config import get_phase_model
+    from prompts_pkg.prompts import get_base_branch_from_metadata
     from qa_loop import run_qa_validation_loop, should_run_qa
 
     from .utils import print_banner, validate_environment
 
+    # Get the resolved model for the planning phase (first phase of build)
+    # This respects task_metadata.json phase configuration from the UI
+    planning_model = get_phase_model(spec_dir, "planning", model)
+    coding_model = get_phase_model(spec_dir, "coding", model)
+    qa_model = get_phase_model(spec_dir, "qa", model)
+
     print_banner()
     print(f"\nProject directory: {project_dir}")
     print(f"Spec: {spec_dir.name}")
-    print(f"Model: {model}")
+    # Show phase-specific models if they differ
+    if planning_model != coding_model or coding_model != qa_model:
+        print(
+            f"Models: Planning={planning_model.split('-')[1] if '-' in planning_model else planning_model}, "
+            f"Coding={coding_model.split('-')[1] if '-' in coding_model else coding_model}, "
+            f"QA={qa_model.split('-')[1] if '-' in qa_model else qa_model}"
+        )
+    else:
+        print(f"Model: {planning_model}")
 
     if max_iterations:
         print(f"Max iterations: {max_iterations}")
@@ -179,6 +195,14 @@ def handle_build_command(
         auto_continue=auto_continue,
     )
 
+    # If base_branch not provided via CLI, try to read from task_metadata.json
+    # This ensures the backend uses the branch configured in the frontend
+    if base_branch is None:
+        metadata_branch = get_base_branch_from_metadata(spec_dir)
+        if metadata_branch:
+            base_branch = metadata_branch
+            debug("run.py", f"Using base branch from task metadata: {base_branch}")
+
     if workspace_mode == WorkspaceMode.ISOLATED:
         # Keep reference to original spec directory for syncing progress back
         source_spec_dir = spec_dir
@@ -259,7 +283,7 @@ def handle_build_command(
 
                 # Sync implementation plan to main project after QA
                 # This ensures the main project has the latest status (human_review)
-                if sync_plan_to_source(spec_dir, source_spec_dir):
+                if sync_spec_to_source(spec_dir, source_spec_dir):
                     debug_info(
                         "run.py", "Implementation plan synced to main project after QA"
                     )
@@ -397,7 +421,7 @@ def _handle_build_interrupt(
         if human_input:
             # Save to HUMAN_INPUT.md
             input_file = spec_dir / "HUMAN_INPUT.md"
-            input_file.write_text(human_input)
+            input_file.write_text(human_input, encoding="utf-8")
 
             content = [
                 success(f"{icon(Icons.SUCCESS)} INSTRUCTIONS SAVED"),