Deploy from 7af131fd

Dockerfile

@@ -0,0 +1,76 @@
+# =============================================================================
+# GitPilot - Hugging Face Spaces Dockerfile
+# =============================================================================
+# Deploys GitPilot (FastAPI backend + React frontend) as a single container
+# with OllaBridge Cloud integration for LLM inference.
+#
+# Architecture:
+#   React UI (Vite build) -> FastAPI backend -> OllaBridge Cloud / any LLM
+# =============================================================================
+
+# -- Stage 1: Build React frontend -------------------------------------------
+FROM node:20-slim AS frontend-builder
+
+WORKDIR /build
+
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci --production=false
+
+COPY frontend/ ./
+RUN npm run build
+
+# -- Stage 2: Python runtime -------------------------------------------------
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 appuser && \
+    mkdir -p /app /tmp/gitpilot && \
+    chown -R appuser:appuser /app /tmp/gitpilot
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY gitpilot ./gitpilot
+
+# Copy built frontend into gitpilot/web/
+COPY --from=frontend-builder /build/dist/ ./gitpilot/web/
+
+# Install Python dependencies (pip-only for reliability on HF Spaces)
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir \
+        "fastapi>=0.111.0" \
+        "uvicorn[standard]>=0.30.0" \
+        "httpx>=0.27.0" \
+        "python-dotenv>=1.1.0" \
+        "typer>=0.12.0" \
+        "pydantic>=2.7.0" \
+        "rich>=13.0.0" \
+        "pyjwt[crypto]>=2.8.0" \
+        "litellm" \
+        "crewai>=0.76.9" \
+        "crewai-tools>=0.13.4" \
+        "anthropic>=0.39.0" && \
+    pip install --no-cache-dir -e .
+
+COPY deploy/huggingface/start.sh /app/start.sh
+RUN chmod +x /app/start.sh
+
+ENV PORT=7860 \
+    HOST=0.0.0.0 \
+    HOME=/tmp \
+    GITPILOT_PROVIDER=ollabridge \
+    OLLABRIDGE_BASE_URL=https://ruslanmv-ollabridge.hf.space \
+    GITPILOT_OLLABRIDGE_MODEL=qwen2.5:1.5b \
+    CORS_ORIGINS="*" \
+    GITPILOT_CONFIG_DIR=/tmp/gitpilot
+
+USER appuser
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD curl -f http://localhost:7860/api/health || exit 1
+
+CMD ["/app/start.sh"]

README.md

@@ -0,0 +1,79 @@
+---
+title: GitPilot
+emoji: "\U0001F916"
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: true
+license: mit
+short_description: Enterprise AI Coding Assistant for GitHub Repositories
+---
+
+# GitPilot — Hugging Face Spaces
+
+**Enterprise-grade AI coding assistant** for GitHub repositories with multi-LLM support, visual workflow insights, and intelligent code analysis.
+
+## What This Does
+
+This Space runs the full GitPilot stack:
+1. **React Frontend** — Professional dark-theme UI with chat, file browser, and workflow visualization
+2. **FastAPI Backend** — 80+ API endpoints for repository management, AI chat, planning, and execution
+3. **Multi-Agent AI** — CrewAI orchestration with 7 switchable agent topologies
+
+## LLM Providers
+
+GitPilot connects to your favorite LLM provider. Configure in **Admin / LLM Settings**:
+
+| Provider | Default | API Key Required |
+|---|---|---|
+| **OllaBridge Cloud** (default) | `qwen2.5:1.5b` | No |
+| OpenAI | `gpt-4o-mini` | Yes |
+| Anthropic Claude | `claude-sonnet-4-5` | Yes |
+| Ollama (local) | `llama3` | No |
+| Custom endpoint | Any model | Optional |
+
+## Quick Start
+
+1. Open the Space UI
+2. Enter your **GitHub Token** (Settings -> GitHub)
+3. Select a repository from the sidebar
+4. Start chatting with your AI coding assistant
+
+## API Endpoints
+
+| Endpoint | Description |
+|---|---|
+| `GET /api/health` | Health check |
+| `POST /api/chat/message` | Chat with AI assistant |
+| `POST /api/chat/plan` | Generate implementation plan |
+| `GET /api/repos` | List repositories |
+| `GET /api/settings` | View/update settings |
+| `GET /docs` | Interactive API docs (Swagger) |
+
+## Connect to OllaBridge Cloud
+
+By default, GitPilot connects to [OllaBridge Cloud](https://huggingface.co/spaces/ruslanmv/ollabridge) for LLM inference. This provides free access to open-source models without needing API keys.
+
+To use your own OllaBridge instance:
+1. Go to **Admin / LLM Settings**
+2. Select **OllaBridge** provider
+3. Enter your OllaBridge URL and model
+
+## Environment Variables
+
+Configure via HF Spaces secrets:
+
+| Variable | Description | Default |
+|---|---|---|
+| `GITPILOT_PROVIDER` | LLM provider | `ollabridge` |
+| `OLLABRIDGE_BASE_URL` | OllaBridge Cloud URL | `https://ruslanmv-ollabridge.hf.space` |
+| `GITHUB_TOKEN` | GitHub personal access token | - |
+| `OPENAI_API_KEY` | OpenAI API key (if using OpenAI) | - |
+| `ANTHROPIC_API_KEY` | Anthropic API key (if using Claude) | - |
+
+## Links
+
+- [GitPilot Repository](https://github.com/ruslanmv/gitpilot)
+- [OllaBridge Cloud](https://huggingface.co/spaces/ruslanmv/ollabridge)
+- [Documentation](https://github.com/ruslanmv/gitpilot#readme)

REPO_README.md

@@ -0,0 +1,1241 @@
+# GitPilot
+
+<div align="center">
+
+**🚀 The AI Coding Companion That Understands Your GitHub Repositories**
+
+[![PyPI version](https://badge.fury.io/py/gitcopilot.svg)](https://pypi.org/project/gitcopilot/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/ruslanmv/gitpilot.svg?style=social&label=Star)](https://github.com/ruslanmv/gitpilot)
+
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Example Usage](#-example-usage) • [Documentation](#-complete-workflow-guide) • [Contributing](#-contributing)
+
+</div>
+
+---
+
+## ⭐ Star Us on GitHub!
+
+**If GitPilot saves you time or helps your projects, please give us a star!** ⭐
+
+Your support helps us:
+- 🚀 Build new features faster
+- 🐛 Fix bugs and improve stability
+- 📚 Create better documentation
+- 🌍 Grow the community
+
+**[⭐ Click here to star GitPilot on GitHub](https://github.com/ruslanmv/gitpilot)** — it takes just 2 seconds and means the world to us! 💙
+
+---
+
+## 🌟 What is GitPilot?
+
+GitPilot is a **production-ready agentic AI assistant** that acts as your intelligent coding companion for GitHub repositories. Unlike copy-paste coding assistants, GitPilot:
+
+* **🧠 Understands your entire codebase** – Analyzes project structure, file relationships, and cross-repository dependencies
+* **📋 Shows clear plans before executing** – Always presents an "Answer + Action Plan" with structured file operations (CREATE/MODIFY/DELETE/READ)
+* **🔄 Manages multiple LLM providers** – Seamlessly switch between OpenAI, Claude, Watsonx, and Ollama with smart model routing
+* **👁️ Visualizes agent workflows** – See exactly how the multi-agent system thinks and operates
+* **🔗 Works locally and with GitHub** – Full local file editing, terminal execution, and GitHub integration
+* **🔌 Extensible ecosystem** – MCP server connections, plugin marketplace, /command skills, and IDE extensions
+* **🛡️ Built-in security scanning** – AI-powered vulnerability detection beyond traditional SAST tools
+* **🤖 Self-improving agents** – Learns from outcomes and adapts strategies per project over time
+
+**Built with CrewAI, FastAPI, and React** — GitPilot combines the power of multi-agent AI with a beautiful, modern web interface and the extensibility of a platform.
+
+![](assets/2025-11-15-01-18-56.png)
+
+---
+
+## ✨ Example Usage
+
+### Installation
+
+```bash
+# Install from PyPI
+pip install gitcopilot
+
+# Set your GitHub token
+export GITPILOT_GITHUB_TOKEN="ghp_your_token_here"
+
+# Set your LLM API key (choose one)
+export OPENAI_API_KEY="sk-..."
+# or
+export ANTHROPIC_API_KEY="sk-ant-..."
+# or
+export WATSONX_API_KEY="your_api_key"
+export WATSONX_PROJECT_ID="your_project_id"
+
+# Launch GitPilot
+gitpilot
+```
+
+### Basic Workflow
+
+```bash
+# 1. Start GitPilot (opens in browser automatically)
+gitpilot
+
+# 2. Select a repository from the sidebar
+#    → Search your GitHub repos
+#    → Click to connect
+
+# 3. Ask GitPilot to make changes
+#    Example: "Add a new API endpoint for user login with JWT authentication"
+
+# 4. Review the generated plan
+#    ✓ Answer: Explanation of what will be done
+#    ✓ Action Plan: Structured steps with file operations
+#      - CREATE: src/api/auth.py
+#      - MODIFY: src/routes/index.py
+#      - READ: README.md (for analysis)
+#      - DELETE: deprecated/old_auth.py
+
+# 5. Approve & Execute
+#    → GitPilot applies changes to your repository
+#    → View execution log with detailed results
+```
+
+### Real-World Examples
+
+**Add a new feature:**
+```
+User: Add a rate limiter to all API endpoints to prevent abuse
+
+GitPilot Response:
+Answer: I'll implement rate limiting using a middleware approach with Redis
+for distributed rate limiting support.
+
+Action Plan:
+  Step 1: Create rate limiter middleware
+    - CREATE: src/middleware/rate_limiter.py
+  Step 2: Add Redis client configuration
+    - MODIFY: src/config.py
+  Step 3: Apply middleware to all routes
+    - MODIFY: src/main.py
+  Step 4: Add rate limit tests
+    - CREATE: tests/test_rate_limiter.py
+```
+
+**Refactor existing code:**
+```
+User: Refactor the user authentication to use async/await instead of callbacks
+
+GitPilot Response:
+Answer: I'll convert all authentication functions to async/await pattern,
+update the database queries, and ensure all tests pass.
+
+Action Plan:
+  Step 1: Analyze current authentication implementation
+    - READ: src/services/auth_service.py
+    - READ: src/routes/auth.py
+  Step 2: Convert auth service to async
+    - MODIFY: src/services/auth_service.py (12 functions)
+  Step 3: Update route handlers
+    - MODIFY: src/routes/auth.py
+  Step 4: Migrate database calls
+    - MODIFY: src/db/user_repository.py
+  Step 5: Update unit tests
+    - MODIFY: tests/test_auth_service.py
+```
+
+**Fix a bug:**
+```
+User: Fix the bug where empty email validation returns a 500 error instead of 400
+
+GitPilot Response:
+Answer: I'll add proper input validation with Pydantic models and return
+appropriate HTTP 400 errors with helpful messages.
+
+Action Plan:
+  Step 1: Add Pydantic validation model
+    - CREATE: src/models/user_input.py
+  Step 2: Update login endpoint with validation
+    - MODIFY: src/routes/auth.py
+  Step 3: Add validation error handler
+    - MODIFY: src/main.py
+  Step 4: Add test cases for validation
+    - MODIFY: tests/test_validation.py
+```
+
+---
+
+## 🎯 Key Features
+
+### 1. **Answer + Action Plan UX**
+Every AI response is structured into two clear sections:
+- **Answer**: Natural language explanation of what will be done and why
+- **Action Plan**: Structured list of steps with explicit file operations:
+  - 🟢 **CREATE** – New files to be added
+  - 🔵 **MODIFY** – Existing files to be changed
+  - 🔴 **DELETE** – Files to be removed
+  - 📖 **READ** – Files to analyze (no changes)
+
+See exactly what will happen before approving execution!
+
+### 2. **Full Multi-LLM Support with Smart Routing** ✨
+All four LLM providers are fully operational and tested:
+- ✅ **OpenAI** – GPT-4o, GPT-4o-mini, GPT-4-turbo
+- ✅ **Claude (Anthropic)** – Claude 4.5 Sonnet, Claude 3 Opus
+- ✅ **IBM Watsonx.ai** – Llama 3.3, Granite 3.x models
+- ✅ **Ollama** – Local models (Llama3, Mistral, CodeLlama, Phi3)
+
+Switch between providers seamlessly through the Admin UI without restart. The **smart model router** automatically selects the optimal model (fast/balanced/powerful) for each task based on complexity analysis, keeping costs low while maintaining quality where it matters.
+
+### 3. **Local Workspace & Terminal Execution** 🆕
+GitPilot now works directly on your local filesystem — just like Claude Code:
+- **Local file editing** – Read, write, search, and delete files in a sandboxed workspace
+- **Terminal execution** – Run shell commands (`npm test`, `make build`, `python -m pytest`) with timeout and output capping
+- **Git operations** – Commit, push, diff, stash, merge — all from the workspace
+- **Path traversal protection** – All file operations are sandboxed to prevent escaping the workspace directory
+
+### 4. **Session Management & Checkpoints** 🆕
+Persistent sessions that survive restarts and support time-travel:
+- **Resume any session** – Pick up exactly where you left off
+- **Fork sessions** – Branch a conversation to try different approaches
+- **Checkpoint & rewind** – Snapshot workspace state at key moments and roll back if something goes wrong
+- **CI/CD headless mode** – Run GitPilot non-interactively via `gitpilot run --headless` for automation pipelines
+
+### 5. **Hook System & Permissions** 🆕
+Fine-grained control over what agents can do:
+- **Lifecycle hooks** – Register shell commands that fire on events like `pre_commit`, `post_edit`, or `pre_push` — blocking hooks can veto risky actions
+- **Three permission modes** – `normal` (ask before risky ops), `plan` (read-only), `auto` (approve everything)
+- **Path-based blocking** – Prevent agents from touching `.env`, `*.pem`, or any sensitive file pattern
+
+### 6. **Project Context Memory (GITPILOT.md)** 🆕
+The equivalent of Claude Code's `CLAUDE.md` — teach your agents project-specific conventions:
+- Create `.gitpilot/GITPILOT.md` with your code style, testing, and commit message rules
+- Add modular rules in `.gitpilot/rules/*.md`
+- Agents automatically learn patterns from session outcomes and store them in `.gitpilot/memory.json`
+
+### 7. **MCP Server Connections** 🆕
+Connect GitPilot to any MCP (Model Context Protocol) server — databases, Slack, Figma, Sentry, and more:
+- **stdio, HTTP, and SSE transports** – Connect to local subprocess servers or remote endpoints
+- **JSON-RPC 2.0** – Full protocol compliance with tool discovery and invocation
+- **Auto-wrap as CrewAI tools** – MCP tools are automatically available to all agents
+- Configure servers in `.gitpilot/mcp.json` with environment variable expansion
+
+### 8. **Plugin Marketplace & /Command Skills** 🆕
+Extend GitPilot with community plugins and project-specific skills:
+- **Install plugins** from git URLs or local paths — each plugin can provide skills, hooks, and MCP configs
+- **Define skills** as markdown files in `.gitpilot/skills/*.md` with YAML front-matter and template variables
+- **Invoke skills** via `/command` syntax in chat or the CLI: `gitpilot skill review`
+- **Auto-trigger skills** based on context patterns (e.g., auto-run lint after edits)
+
+### 9. **Vision & Image Analysis** 🆕
+Multimodal capabilities powered by OpenAI, Anthropic, and Ollama vision models:
+- **Analyse screenshots** – Describe UI bugs, extract text via OCR, review design mockups
+- **Compare before/after** – Detect visual regressions between two screenshots
+- **Base64 encoding** with format validation (PNG, JPG, GIF, WebP, BMP, SVG) and 20 MB size limit
+
+### 10. **AI-Powered Security Scanner** 🆕
+Go beyond traditional SAST tools with pattern-based and context-aware vulnerability detection:
+- **Secret detection** – AWS keys, GitHub tokens, JWTs, Slack tokens, private keys, passwords in code
+- **Code vulnerability patterns** – SQL injection, command injection, XSS, SSRF, path traversal, weak crypto, insecure CORS, disabled SSL verification
+- **Diff scanning** – Scan only added lines in a git diff for CI/CD integration
+- **CWE mapping** – Every finding links to its CWE identifier with actionable recommendations
+- **CLI command** – `gitpilot scan /path/to/repo` with confidence thresholds and severity summaries
+
+### 11. **Predictive Workflow Engine** 🆕
+Proactive suggestions based on what you just did:
+- After merging a PR → suggest updating the changelog
+- After test failure → suggest debugging approach
+- After dependency update → suggest running full test suite
+- After editing security-sensitive code → suggest security review
+- 8 built-in trigger rules with configurable cooldowns and relevance scoring
+- Add custom prediction rules for your own workflows
+
+### 12. **Parallel Multi-Agent Teams** 🆕
+Split large tasks across multiple agents working simultaneously:
+- **Task decomposition** – Automatically split complex tasks into independent subtasks
+- **Parallel execution** – Agents work concurrently via `asyncio.gather`, each on its own git worktree
+- **Conflict detection** – Merging detects file-level conflicts when multiple agents touch the same files
+- **Custom or auto-generated plans** — provide your own subtask descriptions or let the engine split evenly
+
+### 13. **Self-Improving Agents** 🆕
+GitPilot learns from every interaction and becomes specialised to each project over time:
+- **Outcome evaluation** – Checks signals like tests_passed, pr_approved, error_fixed
+- **Pattern extraction** – Generates natural-language insights from successes and failures
+- **Per-repo persistence** – Learned strategies are stored in JSON and loaded in future sessions
+- **Preferred style tracking** – Record project-specific code style preferences that agents follow
+
+### 14. **Cross-Repository Intelligence** 🆕
+Understand dependencies and impact across your entire codebase:
+- **Dependency graph construction** – Parses `package.json`, `requirements.txt`, `pyproject.toml`, and `go.mod`
+- **Impact analysis** – BFS traversal to find all affected repos when updating a dependency, with risk assessment (low/medium/high/critical)
+- **Shared convention detection** – Find common config patterns across multiple repos
+- **Migration planning** – Generate step-by-step migration plans when replacing one package with another
+
+### 15. **Natural Language Database Queries** 🆕
+Query your project's databases using plain English through MCP connections:
+- **NL-to-SQL translation** – Rule-based translation with schema-aware table and column matching
+- **Safety validation** – Read-only mode blocks INSERT/UPDATE/DELETE; read-write mode blocks DROP/TRUNCATE
+- **Query explanation** – Translate SQL back to human-readable descriptions
+- **Tabular output** – Results formatted as plain-text tables for CLI or API consumption
+
+### 16. **IDE Extensions** 🆕
+Use GitPilot from your favourite editor:
+- **VS Code extension** – Sidebar chat panel, inline actions, keybindings (Ctrl+Shift+G), skill invocation, and server configuration
+- Connects to the GitPilot API server — all the same agents and tools available from within your editor
+
+### 17. **Topology Registry — Switchable Agent Architectures** 🆕
+Seven pre-wired agent topologies that control routing, execution, and visualization in one place:
+- **System architectures** (Default fan-out, GitPilot Code ReAct loop) and **task pipelines** (Feature Builder, Bug Hunter, Code Inspector, Architect Mode, Quick Fix) — each with its own agent roster, execution style, and flow graph
+- **Zero-latency classifier** selects the best topology from the user's message without an extra LLM call, while the Flow Viewer dropdown lets you switch or pin a topology at any time
+
+### 18. **Agent Flow Viewer**
+Interactive visual representation of the CrewAI multi-agent system using ReactFlow:
+- **Repository Explorer** – Thoroughly explores codebase structure
+- **Refactor Planner** – Creates safe, step-by-step plans with verified file operations
+- **Code Writer** – Implements approved changes with AI-generated content
+- **Code Reviewer** – Reviews for quality and safety
+- **Local Editor & Terminal** – Direct file editing and shell execution agents
+- **GitHub API Tools** – Manages file operations and commits
+
+### 19. **Admin / Settings Console**
+Full-featured LLM provider configuration with:
+- **OpenAI** – API key, model selection, optional base URL
+- **Claude** – API key, model selection (Claude 4.5 Sonnet recommended)
+- **IBM Watsonx.ai** – API key, project ID, model selection, regional URLs
+- **Ollama** – Base URL (local), model selection
+
+Settings are persisted to `~/.gitpilot/settings.json` and survive restarts.
+
+### 20. **MCP / A2A Agent Integration (ContextForge Compatible)**
+GitPilot can optionally run as an **A2A agent server** that can be **imported by URL** into **MCP ContextForge (MCP Gateway)** and exposed as MCP tools. This makes GitPilot usable not only from the web UI, but also from:
+- MCP-enabled IDEs and CLIs
+- automation pipelines (CI/CD)
+- other AI agents orchestrated by an MCP gateway
+
+A2A mode is **feature-flagged** and does **not** affect the existing UI/API unless enabled.
+
+---
+
+## 🚀 Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install gitcopilot
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/ruslanmv/gitpilot.git
+cd gitpilot
+
+# Install dependencies
+make install
+
+# Build frontend
+make frontend-build
+
+# Run GitPilot
+gitpilot
+```
+
+### Using Docker (Coming Soon)
+
+```bash
+docker pull ruslanmv/gitpilot
+docker run -p 8000:8000 -e GITHUB_TOKEN=your_token ruslanmv/gitpilot
+```
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Python 3.11+**
+- **GitHub Personal Access Token** (with `repo` scope)
+- **API key** for at least one LLM provider (OpenAI, Claude, Watsonx, or Ollama)
+
+### 1. Configure GitHub Access
+
+Create a **GitHub Personal Access Token** at https://github.com/settings/tokens with `repo` scope:
+
+```bash
+export GITPILOT_GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXX"
+# or
+export GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXX"
+```
+
+### 2. Configure LLM Provider
+
+You can configure providers via the web UI's Admin/Settings page, or set environment variables:
+
+#### OpenAI
+```bash
+export OPENAI_API_KEY="sk-..."
+export GITPILOT_OPENAI_MODEL="gpt-4o-mini"  # optional
+```
+
+#### Claude (Anthropic)
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GITPILOT_CLAUDE_MODEL="claude-3-5-sonnet-20241022"  # optional
+```
+
+**Note:** Claude integration now includes automatic environment variable configuration for seamless CrewAI compatibility.
+
+#### IBM Watsonx.ai
+```bash
+export WATSONX_API_KEY="your-watsonx-api-key"
+export WATSONX_PROJECT_ID="your-project-id"  # Required!
+export WATSONX_BASE_URL="https://us-south.ml.cloud.ibm.com"  # optional, region-specific
+export GITPILOT_WATSONX_MODEL="ibm/granite-3-8b-instruct"  # optional
+```
+
+**Note:** Watsonx integration requires both API key and Project ID for proper authentication.
+
+#### Ollama (Local Models)
+```bash
+export OLLAMA_BASE_URL="http://localhost:11434"
+export GITPILOT_OLLAMA_MODEL="llama3"  # optional
+```
+
+### 3. Run GitPilot
+
+```bash
+gitpilot
+```
+
+This will:
+1. Start the FastAPI backend on `http://127.0.0.1:8000`
+2. Serve the web UI at the root URL
+3. Open your default browser automatically
+
+Alternative commands:
+```bash
+# Custom host and port
+gitpilot serve --host 0.0.0.0 --port 8000
+
+# API only (no browser auto-open)
+gitpilot-api
+
+# Headless mode for CI/CD
+gitpilot run --repo owner/repo --message "fix the login bug" --headless
+
+# Initialize project conventions
+gitpilot init
+
+# Security scan
+gitpilot scan /path/to/repo
+
+# Get proactive suggestions
+gitpilot predict "Tests failed in auth module"
+
+# Manage plugins
+gitpilot plugin install https://github.com/example/my-plugin.git
+gitpilot plugin list
+
+# List and invoke skills
+gitpilot skill list
+gitpilot skill review
+
+# List available models
+gitpilot list-models --provider openai
+
+# Using make (for development)
+make run
+```
+
+---
+
+## 🔌 MCP / A2A Integration 🆕
+
+GitPilot can run as a **self-contained MCP server** with A2A endpoints. You can use it standalone or optionally integrate with **MCP ContextForge gateway** for advanced multi-agent workflows.
+
+### Two deployment modes
+1. **Simple MCP Server** (recommended for most users)
+   - Just GitPilot with A2A endpoints enabled
+   - Direct MCP client connections
+   - Use `make mcp` to deploy
+
+2. **Full MCP Gateway** (optional - with ContextForge)
+   - Complete MCP ContextForge infrastructure
+   - Advanced gateway features and orchestration
+   - Use `make gateway` to deploy
+
+### Why this matters
+- **Direct MCP access**: Use GitPilot from MCP-enabled IDEs/CLIs without additional infrastructure
+- **No UI required**: Call GitPilot programmatically from automation pipelines
+- **Composable**: GitPilot can act as the "repo editor agent" inside larger multi-agent workflows
+- **Gateway optional**: Full ContextForge gateway only needed for advanced orchestration scenarios
+
+### Enable A2A mode (does not change existing behavior)
+A2A endpoints are disabled by default. Enable them using environment variables:
+
+```bash
+export GITPILOT_ENABLE_A2A=true
+
+# Recommended: protect the A2A endpoint (gateway will inject this header)
+export GITPILOT_A2A_REQUIRE_AUTH=true
+export GITPILOT_A2A_SHARED_SECRET="REPLACE_WITH_LONG_RANDOM_SECRET"
+```
+
+Then start GitPilot as usual:
+
+```bash
+gitpilot serve --host 0.0.0.0 --port 8000
+```
+
+### A2A endpoints
+
+When enabled, GitPilot exposes:
+
+* `POST /a2a/invoke` – A2A invoke endpoint (JSON-RPC + envelope fallback)
+* `POST /a2a/v1/invoke` – Versioned alias (recommended for gateways)
+* `GET /a2a/health` – Health check
+* `GET /a2a/manifest` – Capability discovery (methods + auth hints)
+
+### Auth model (gateway-friendly)
+
+GitPilot supports a gateway-friendly model:
+
+* **Gateway → GitPilot authentication**:
+  * `X-A2A-Secret: <shared_secret>` *(recommended)*
+    or
+  * `Authorization: Bearer <shared_secret>`
+
+* **GitHub auth (optional)**:
+  * `X-Github-Token: <token>`
+    *(recommended when not using a GitHub App internally)*
+
+> Tip: Avoid sending GitHub tokens in request bodies. Prefer headers to reduce accidental logging exposure.
+
+### Register GitPilot in MCP ContextForge (Optional - Gateway Only)
+
+**Note:** This section is only needed if you're using the **full MCP ContextForge gateway** (`make gateway`). If you're using the simple MCP server (`make mcp`), you can connect MCP clients directly to GitPilot's A2A endpoints.
+
+Once the full gateway stack is deployed, register GitPilot as an A2A agent in ContextForge by providing the endpoint URL (note trailing `/` is recommended for JSON-RPC mode):
+
+* Endpoint URL:
+  * `https://YOUR_GITPILOT_DOMAIN/a2a/v1/invoke/`
+* Agent type:
+  * `jsonrpc`
+* Inject auth header:
+  * `X-A2A-Secret: <shared_secret>`
+
+After registration, MCP clients connected to the gateway will see GitPilot as an MCP tool (name depends on the gateway configuration).
+
+### Supported A2A methods (stable contract)
+
+GitPilot exposes a small, composable set of methods:
+
+* `repo.connect` – validate access and return repo metadata
+* `repo.tree` – list repository tree / files
+* `repo.read` – read a file
+* `repo.write` – create/update a file (commit)
+* `plan.generate` – generate an action plan for a goal
+* `plan.execute` – execute an approved plan
+* `repo.search` *(optional)* – search repositories
+
+These methods are designed to remain stable even if internal implementation changes.
+
+### Quick Start Deployment
+
+#### Option 1: Simple MCP Server (Recommended)
+```bash
+# Configure MCP server
+cp .env.a2a.example .env.a2a
+# Edit .env.a2a and set GITPILOT_A2A_SHARED_SECRET
+
+# Start GitPilot MCP server
+make mcp
+```
+
+This starts GitPilot with A2A endpoints only - perfect for most use cases.
+
+#### Option 2: Full MCP Gateway (Optional - with ContextForge)
+Only needed if you want the complete MCP ContextForge gateway infrastructure:
+
+```bash
+# 1. Download ContextForge and place at: deploy/a2a-mcp/mcp-context-forge
+# 2. Configure environment
+cd deploy/a2a-mcp
+cp .env.stack.example .env.stack
+# Edit .env.stack and set secrets
+
+# 3. Start full gateway stack
+cd ../..
+make gateway
+
+# 4. Register GitPilot agent in ContextForge
+export CF_ADMIN_BEARER="<jwt-token>"
+export GITPILOT_A2A_SECRET="<same-as-env-stack>"
+make gateway-register
+```
+
+**Note:** Most users only need `make mcp`. The full gateway is optional for advanced setups.
+
+See `deploy/a2a-mcp/README.md` for detailed deployment instructions.
+
+### Cloud deployment note
+Because the A2A adapter is stateless, GitPilot can be deployed with multiple replicas behind a load balancer. For long-running executions, consider adding async job execution (Redis/Postgres) in a future release.
+
+---
+
+## 📖 Complete Workflow Guide
+
+### Initial Setup
+
+**Step 1: Launch GitPilot**
+```bash
+gitpilot
+```
+Your browser opens to `http://127.0.0.1:8000`
+
+**Step 2: Configure LLM Provider**
+1. Click **"⚙️ Admin / Settings"** in the sidebar
+2. Select your preferred provider (e.g., OpenAI, Claude, Watsonx, or Ollama)
+3. Enter your credentials:
+   - **OpenAI**: API key + model
+   - **Claude**: API key + model
+   - **Watsonx**: API key + Project ID + model + base URL
+   - **Ollama**: Base URL + model
+4. Click **"Save settings"**
+5. See the success message confirming your settings are saved
+
+**Step 3: Connect to GitHub Repository**
+1. Click **"📁 Workspace"** to return to the main interface
+2. In the sidebar, use the search box to find your repository
+3. Click **"Search my repos"** to list all accessible repositories
+4. Click on any repository to connect
+5. The **Project Context Panel** will show repository information
+6. Use the **Refresh** button to update permissions and file counts
+
+### Development Workflow
+
+**Step 1: Browse Your Codebase**
+- The **Project Context** panel shows repository metadata
+- Browse the file tree to understand structure
+- Click on files to preview their contents
+- Use the **Refresh** button to update the file tree after changes
+
+**Step 2: Describe Your Task**
+In the chat panel, describe what you want in natural language:
+
+**Example 1: Add a Feature**
+```
+Add a new API endpoint at /api/users/{id}/profile that returns
+user profile information including name, email, and bio.
+```
+
+**Example 2: Refactor Code**
+```
+Refactor the authentication middleware to use JWT tokens
+instead of session cookies. Update all related tests.
+```
+
+**Example 3: Analyze and Generate**
+```
+Analyze the README.md file and generate Python example code
+that demonstrates the main features.
+```
+
+**Example 4: Fix a Bug**
+```
+The login endpoint is returning 500 errors when the email
+field is empty. Add proper validation and return a 400
+with a helpful error message.
+```
+
+**Step 3: Review the Answer + Action Plan**
+GitPilot will show you:
+
+**Answer Section:**
+- Clear explanation of what will be done
+- Why this approach was chosen
+- Overall summary of changes
+
+**Action Plan Section:**
+- Numbered steps with descriptions
+- File operations with colored pills:
+  - 🟢 CREATE – Files to be created
+  - 🔵 MODIFY – Files to be modified
+  - 🔴 DELETE – Files to be removed
+  - 📖 READ – Files to analyze (no changes)
+- Summary totals (e.g., "2 files to create, 3 files to modify, 1 file to read")
+- Risk warnings when applicable
+
+**Step 4: Execute or Refine**
+- If the plan looks good: Click **"Approve & Execute"**
+- If you want changes: Provide feedback in the chat
+  ```
+  The plan looks good, but please also add rate limiting
+  to the new endpoint to prevent abuse.
+  ```
+- GitPilot will update the plan based on your feedback
+
+**Step 5: View Execution Results**
+After execution, see a detailed log:
+```
+Step 1: Create authentication endpoint
+  ✓ Created src/api/auth.py
+  ✓ Modified src/routes/index.py
+
+Step 2: Add authentication tests
+  ✓ Created tests/test_auth.py
+  ℹ️ READ-only: inspected README.md
+```
+
+**Step 6: Refresh File Tree**
+After agent operations:
+- Click the **Refresh** button in the file tree header
+- See newly created/modified files appear
+- Verify changes were applied correctly
+
+**Step 7: View Agent Workflow (Optional)**
+Click **"🔄 Agent Flow"** to see:
+- How agents collaborate (Explorer → Planner → Code Writer → Reviewer)
+- Data flow between components
+- The complete multi-agent system architecture
+
+---
+
+## 🏗️ Architecture
+
+### Frontend Structure
+
+```
+frontend/
+├── App.jsx                         # Main application with navigation
+├── components/
+│   ├── AssistantMessage.jsx       # Answer + Action Plan display
+│   ├── ChatPanel.jsx              # AI chat interface
+│   ├── FileTree.jsx               # Repository file browser with refresh
+│   ├── FlowViewer.jsx             # Agent workflow visualization
+│   ├── Footer.jsx                 # Footer with GitHub star CTA
+│   ├── LlmSettings.jsx            # Provider configuration UI
+│   ├── PlanView.jsx               # Enhanced plan rendering with READ support
+│   ├── ProjectContextPanel.jsx    # Repository context with refresh
+│   └── RepoSelector.jsx           # Repository search/selection
+├── styles.css                      # Global styles with dark theme
+├── index.html                      # Entry point
+└── package.json                    # Dependencies (React, ReactFlow)
+```
+
+### Backend Structure
+
+```
+gitpilot/
+├── __init__.py
+├── api.py                          # FastAPI routes (80+ endpoints)
+├── agentic.py                      # CrewAI multi-agent orchestration
+├── agent_router.py                 # NLP-based request routing
+├── agent_tools.py                  # GitHub API exploration tools
+├── cli.py                          # CLI (serve, run, scan, predict, plugin, skill)
+├── github_api.py                   # GitHub REST API client
+├── github_app.py                   # GitHub App installation management
+├── github_issues.py                # Issue CRUD operations
+├── github_pulls.py                 # Pull request operations
+├── github_search.py                # Code, issue, repo, user search
+├── github_oauth.py                 # OAuth web + device flow
+├── llm_provider.py                 # Multi-provider LLM factory
+├── settings.py                     # Configuration management
+├── topology_registry.py            # Switchable agent topologies (7 built-in)
+│
+│   # --- Phase 1: Feature Parity ---
+├── workspace.py                    # Local git clone & file operations
+├── local_tools.py                  # CrewAI tools for local editing
+├── terminal.py                     # Sandboxed shell command execution
+├── session.py                      # Session persistence & checkpoints
+├── hooks.py                        # Lifecycle event hooks
+├── memory.py                       # GITPILOT.md context memory
+├── permissions.py                  # Fine-grained permission policies
+├── headless.py                     # CI/CD headless execution mode
+│
+│   # --- Phase 2: Ecosystem Superiority ---
+├── mcp_client.py                   # MCP server connector (stdio/HTTP/SSE)
+├── plugins.py                      # Plugin marketplace & management
+├── skills.py                       # /command skill system
+├── vision.py                       # Multimodal image analysis
+├── smart_model_router.py           # Auto-route tasks to optimal model
+│
+│   # --- Phase 3: Intelligence Superiority ---
+├── agent_teams.py                  # Parallel multi-agent on git worktrees
+├── learning.py                     # Self-improving agents (per-repo)
+├── cross_repo.py                   # Dependency graphs & impact analysis
+├── predictions.py                  # Predictive workflow suggestions
+├── security.py                     # AI-powered security scanner
+├── nl_database.py                  # Natural language SQL via MCP
+│
+├── a2a_adapter.py                  # Optional A2A/MCP gateway adapter
+└── web/                            # Production frontend build
+    ├── index.html
+    └── assets/
+```
+
+### API Endpoints (80+)
+
+#### Repository Management
+- `GET /api/repos` – List user repositories (paginated + search)
+- `GET /api/repos/{owner}/{repo}/tree` – Get repository file tree
+- `GET /api/repos/{owner}/{repo}/file` – Get file contents
+- `POST /api/repos/{owner}/{repo}/file` – Update/commit file
+
+#### Issues & Pull Requests
+- `GET/POST/PATCH /api/repos/{owner}/{repo}/issues` – Full issue CRUD
+- `GET/POST /api/repos/{owner}/{repo}/pulls` – Pull request management
+- `PUT /api/repos/{owner}/{repo}/pulls/{n}/merge` – Merge pull request
+
+#### Search
+- `GET /api/search/code` – Search code across GitHub
+- `GET /api/search/issues` – Search issues and pull requests
+- `GET /api/search/repositories` – Search repositories
+- `GET /api/search/users` – Search users and organisations
+
+#### Chat & Planning
+- `POST /api/chat/message` – Conversational dispatcher (auto-routes to agents)
+- `POST /api/chat/plan` – Generate execution plan
+- `POST /api/chat/execute` – Execute approved plan
+- `POST /api/chat/execute-with-pr` – Execute and auto-create pull request
+- `POST /api/chat/route` – Preview routing without execution
+
+#### Sessions & Hooks (Phase 1)
+- `GET/POST/DELETE /api/sessions` – Session CRUD
+- `POST /api/sessions/{id}/checkpoint` – Create checkpoint
+- `GET/POST/DELETE /api/hooks` – Hook registration
+- `GET/PUT /api/permissions` – Permission mode management
+- `GET/POST /api/repos/{owner}/{repo}/context` – Project memory
+
+#### MCP, Plugins & Skills (Phase 2)
+- `GET /api/mcp/servers` – List configured MCP servers
+- `POST /api/mcp/connect/{name}` – Connect to MCP server
+- `POST /api/mcp/call` – Call a tool on a connected server
+- `GET/POST/DELETE /api/plugins` – Plugin management
+- `GET/POST /api/skills` – Skill listing and invocation
+- `POST /api/vision/analyze` – Analyse an image with a text prompt
+- `POST /api/model-router/select` – Preview model selection for a task
+
+#### Intelligence (Phase 3)
+- `POST /api/agent-teams/plan` – Split task into parallel subtasks
+- `POST /api/agent-teams/execute` – Execute subtasks in parallel
+- `POST /api/learning/evaluate` – Evaluate action outcome for learning
+- `GET /api/learning/insights/{owner}/{repo}` – Get learned insights
+- `POST /api/cross-repo/dependencies` – Build dependency graph
+- `POST /api/cross-repo/impact` – Impact analysis for package update
+- `POST /api/predictions/suggest` – Get proactive suggestions
+- `POST /api/security/scan-file` – Scan file for vulnerabilities
+- `POST /api/security/scan-directory` – Recursive directory scan
+- `POST /api/security/scan-diff` – Scan git diff for issues
+- `POST /api/nl-database/translate` – Natural language to SQL
+- `POST /api/nl-database/explain` – Explain SQL in plain English
+
+#### Workflow Visualization & Topologies
+- `GET /api/flow/current` – Get agent workflow graph (supports `?topology=` param)
+- `GET /api/flow/topologies` – List available agent topologies
+- `GET /api/flow/topology/{id}` – Get graph for a specific topology
+- `POST /api/flow/classify` – Auto-detect best topology for a message
+- `GET /api/settings/topology` – Read saved topology preference
+- `POST /api/settings/topology` – Save topology preference
+
+#### A2A / MCP Integration (Optional)
+Enabled only when `GITPILOT_ENABLE_A2A=true`:
+
+- `POST /a2a/invoke` – A2A invoke endpoint (JSON-RPC + envelope)
+- `POST /a2a/v1/invoke` – Versioned A2A endpoint (recommended)
+- `GET /a2a/health` – A2A health check
+- `GET /a2a/manifest` – A2A capability discovery (methods + schemas)
+
+---
+
+## 🛠️ Development
+
+### Build Commands (Makefile)
+
+```bash
+# Install all dependencies
+make install
+
+# Install frontend dependencies only
+make frontend-install
+
+# Build frontend for production
+make frontend-build
+
+# Run development server
+make run
+
+# Run tests (846 tests across 28 test files)
+make test
+
+# Lint code
+make lint
+
+# Format code
+make fmt
+
+# Build Python package
+make build
+
+# Clean build artifacts
+make clean
+
+# MCP Server Deployment (Simple - Recommended)
+make mcp              # Start GitPilot MCP server (A2A endpoints)
+make mcp-down         # Stop GitPilot MCP server
+make mcp-logs         # View MCP server logs
+
+# MCP Gateway Deployment (Optional - Full ContextForge Stack)
+make gateway          # Start GitPilot + MCP ContextForge gateway
+make gateway-down     # Stop MCP ContextForge gateway
+make gateway-logs     # View gateway logs
+make gateway-register # Register agent in ContextForge
+```
+
+### CLI Commands
+
+```bash
+gitpilot                          # Start server with web UI (default)
+gitpilot serve --host 0.0.0.0    # Custom host/port
+gitpilot config                   # Show current configuration
+gitpilot version                  # Show version
+gitpilot run -r owner/repo -m "task"  # Headless execution for CI/CD
+gitpilot init                     # Initialize .gitpilot/ with template
+gitpilot scan /path              # Security scan a directory or file
+gitpilot predict "context text"   # Get proactive suggestions
+gitpilot plugin install <source>  # Install a plugin
+gitpilot plugin list              # List installed plugins
+gitpilot skill list               # List available skills
+gitpilot skill <name>             # Invoke a skill
+gitpilot list-models              # List LLM models for active provider
+```
+
+### Frontend Development
+
+```bash
+cd frontend
+
+# Install dependencies
+npm install
+
+# Development mode with hot reload
+npm run dev
+
+# Build for production
+npm run build
+```
+
+---
+
+## 📦 Publishing to PyPI
+
+GitPilot uses automated publishing via GitHub Actions with OIDC-based trusted publishing.
+
+### Automated Release Workflow
+
+1. **Update version** in `gitpilot/version.py`
+2. **Create and publish a GitHub release** (tag format: `vX.Y.Z`)
+3. **GitHub Actions automatically**:
+   - Builds source distribution and wheel
+   - Uploads artifacts to the release
+   - Publishes to PyPI via trusted publishing
+
+See [.github/workflows/release.yml](.github/workflows/release.yml) for details.
+
+### Manual Publishing (Alternative)
+
+```bash
+# Build distributions
+make build
+
+# Publish to TestPyPI
+make publish-test
+
+# Publish to PyPI
+make publish
+```
+
+---
+
+## 📸 Screenshots
+
+### Example: File Deletion
+![](assets/2025-11-16-00-25-49.png)
+
+### Example: Content Generation
+![](assets/2025-11-16-00-29-47.png)
+
+### Example: File Creation
+![](assets/2025-11-16-01-01-40.png)
+
+### Example multiple operations
+![](assets/2025-11-27-00-25-53.png)
+
+---
+
+## 🤝 Contributing
+
+**We love contributions!** Whether it's bug fixes, new features, or documentation improvements.
+
+### How to Contribute
+
+1. ⭐ **Star the repository** (if you haven't already!)
+2. 🍴 Fork the repository
+3. 🌿 Create a feature branch (`git checkout -b feature/amazing-feature`)
+4. ✍️ Make your changes
+5. ✅ Run tests (`make test`)
+6. 🎨 Run linter (`make lint`)
+7. 📝 Commit your changes (`git commit -m 'Add amazing feature'`)
+8. 🚀 Push to the branch (`git push origin feature/amazing-feature`)
+9. 🎯 Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/gitpilot.git
+cd gitpilot
+
+# Install dependencies
+make install
+
+# Create a branch
+git checkout -b feature/my-feature
+
+# Make changes and test
+make run
+make test
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 👨‍💻 Author
+
+**Ruslan Magana Vsevolodovna**
+
+- GitHub: [@ruslanmv](https://github.com/ruslanmv)
+- Website: [ruslanmv.com](https://ruslanmv.com)
+
+---
+
+## 🙏 Acknowledgments
+
+- **CrewAI** – Multi-agent orchestration framework
+- **FastAPI** – Modern, fast web framework
+- **React** – UI library
+- **ReactFlow** – Interactive node-based diagrams
+- **Vite** – Fast build tool
+- **MCP (Model Context Protocol)** – By Anthropic, for tool interoperability
+- **OWASP Top 10** – Security vulnerability categorisation
+- **BIRD benchmark** and **DIN-SQL** research – Text-to-SQL approaches
+- **Horvitz (1999)** – Proactive assistance in HCI research
+- **All our contributors and stargazers!** ⭐
+
+---
+
+## 📞 Support
+
+- **Issues**: https://github.com/ruslanmv/gitpilot/issues
+- **Discussions**: https://github.com/ruslanmv/gitpilot/discussions
+- **Documentation**: [Full Documentation](https://github.com/ruslanmv/gitpilot#readme)
+
+---
+
+## 🗺️ Roadmap
+
+### Recently Released (v0.2.0) 🆕
+
+**Phase 1 — Feature Parity with Claude Code:**
+- ✅ **Local Workspace Manager** – Clone repos, read/write/search files locally
+- ✅ **Terminal Execution** – Sandboxed shell commands with timeout and output capping
+- ✅ **Session Persistence** – Resume, fork, checkpoint, and rewind sessions
+- ✅ **Hook System** – Lifecycle events (pre_commit, post_edit) with blocking support
+- ✅ **Permission Policies** – Three modes (normal/plan/auto) with path-based blocking
+- ✅ **Context Memory (GITPILOT.md)** – Project conventions injected into agent prompts
+- ✅ **Headless CI/CD Mode** – `gitpilot run --headless` for automation pipelines
+
+**Phase 2 — Ecosystem Superiority:**
+- ✅ **MCP Client** – Connect to any MCP server (databases, Slack, Figma, Sentry)
+- ✅ **Plugin Marketplace** – Install/uninstall plugins from git or local paths
+- ✅ **Skill System** – /command skills defined as markdown with template variables
+- ✅ **Vision Analysis** – Multimodal image analysis via OpenAI, Anthropic, or Ollama
+- ✅ **Smart Model Router** – Auto-route tasks to optimal model by complexity
+- ✅ **VS Code Extension** – Sidebar chat, inline actions, and keybindings
+
+**Phase 3 — Intelligence Superiority (no competitor has this):**
+- ✅ **Agent Teams** – Parallel multi-agent execution on git worktrees
+- ✅ **Self-Improving Agents** – Learn from outcomes and adapt per-project
+- ✅ **Cross-Repo Intelligence** – Dependency graphs and impact analysis across repos
+- ✅ **Predictive Workflows** – Proactive suggestions based on context patterns
+- ✅ **AI Security Scanner** – Secret detection, injection analysis, CWE mapping
+- ✅ **NL Database Queries** – Natural language to SQL translation via MCP
+- ✅ **Topology Registry** – Seven switchable agent architectures with zero-latency message classification and visual topology selector
+
+### Previous Features (v0.1.2)
+- ✅ Full Multi-LLM Support – All 4 providers fully tested
+- ✅ Answer + Action Plan UX with structured file operations
+- ✅ Real Execution Engine with GitHub operations
+- ✅ Agent Flow Viewer with ReactFlow
+- ✅ MCP / A2A Integration (ContextForge compatible)
+- ✅ Issue and Pull Request management APIs
+- ✅ Code, issue, repository, and user search
+- ✅ OAuth web + device flow authentication
+
+### Planned Features (v0.2.1+)
+- 🔄 Frontend components for terminal, sessions, checkpoints, and security dashboard
+- 🔄 JetBrains IDE plugin
+- 🔄 Real-time collaboration (shared sessions, audit log)
+- 🔄 Automated test generation from code changes
+- 🔄 Slack/Discord notification hooks
+- 🔄 LLM-powered semantic diff review
+- 🔄 OSV dependency vulnerability scanning
+- 🔄 Custom agent templates and agent marketplace
+
+---
+
+## ⚠️ Important Notes
+
+### Security Best Practices
+
+1. **Never commit API keys** to version control
+2. **Use environment variables** or the Admin UI for credentials
+3. **Rotate tokens regularly**
+4. **Limit GitHub token scopes** to only what's needed
+5. **Review all plans** before approving execution
+6. **Verify GitHub App installations** before granting write access
+7. **Run `gitpilot scan`** before releases to catch secrets, injection risks, and insecure configurations
+8. **Use permission modes** – run agents in `plan` mode (read-only) when exploring unfamiliar codebases
+
+### LLM Provider Configuration
+
+**All providers now fully supported!** ✨
+
+Each provider has specific requirements:
+
+**OpenAI**
+- Requires: `OPENAI_API_KEY`
+- Optional: `GITPILOT_OPENAI_MODEL`, `OPENAI_BASE_URL`
+
+**Claude (Anthropic)**
+- Requires: `ANTHROPIC_API_KEY`
+- Optional: `GITPILOT_CLAUDE_MODEL`, `ANTHROPIC_BASE_URL`
+- Note: Environment variables are automatically configured by GitPilot
+
+**IBM Watsonx.ai**
+- Requires: `WATSONX_API_KEY`, `WATSONX_PROJECT_ID`
+- Optional: `WATSONX_BASE_URL`, `GITPILOT_WATSONX_MODEL`
+- Note: Project ID is essential for proper authentication
+
+**Ollama**
+- Requires: `OLLAMA_BASE_URL`
+- Optional: `GITPILOT_OLLAMA_MODEL`
+- Note: Runs locally, no API key needed
+
+### File Action Types
+
+GitPilot supports four file operation types in plans:
+
+- **CREATE** (🟢) – Add new files with AI-generated content
+- **MODIFY** (🔵) – Update existing files intelligently
+- **DELETE** (🔴) – Remove files safely
+- **READ** (📖) – Analyze files without making changes (new!)
+
+READ operations allow agents to gather context and information without modifying your repository, enabling better-informed plans.
+
+---
+
+## 🎓 Learn More
+
+### Understanding the Agent System
+
+GitPilot uses a multi-agent architecture where each request is routed to the right set of agents by the **agent router**, which analyses your message using NLP patterns and dispatches to one of 12+ specialised agent types:
+
+**Core Agents:**
+- **Repository Explorer** – Scans codebase structure and gathers context
+- **Refactor Planner** – Creates structured step-by-step plans with file operations
+- **Code Writer** – Generates AI-powered content for new and modified files
+- **Code Reviewer** – Reviews changes for quality, safety, and adherence to conventions
+
+**Local Agents (Phase 1):**
+- **Local Editor** – Reads, writes, and searches files directly on disk
+- **Terminal Agent** – Executes shell commands (`npm test`, `make build`, `pytest`)
+
+**Specialised Agents (v2):**
+- **Issue Agent** – Creates, updates, labels, and comments on GitHub issues
+- **PR Agent** – Creates pull requests, lists files, manages merges
+- **Search Agent** – Searches code, issues, repos, and users across GitHub
+- **Learning Agent** – Evaluates outcomes and improves strategies over time
+
+**Intelligence Layer (Phase 3):**
+- **Agent Teams** – Multiple agents work in parallel on subtasks with conflict detection
+- **Predictive Engine** – Suggests next actions before you ask
+- **Security Scanner** – Detects secrets, injection risks, and insecure configurations
+- **Cross-Repo Analyser** – Maps dependencies and assesses impact across repositories
+
+The **smart model router** selects the optimal LLM for each task — simple queries go to fast/cheap models while complex reasoning gets the most powerful model available.
+
+### Choosing the Right LLM Provider
+
+**OpenAI (GPT-4o, GPT-4o-mini)**
+- ✅ Best for: General-purpose coding, fast responses
+- ✅ Strengths: Excellent code quality, great at following instructions
+- ✅ Status: Fully tested and working
+- ⚠️ Costs: Moderate to high
+
+**Claude (Claude 4.5 Sonnet)**
+- ✅ Best for: Complex refactoring, detailed analysis
+- ✅ Strengths: Deep reasoning, excellent at planning
+- ✅ Status: Fully tested and working (latest integration fixes applied)
+- ⚠️ Costs: Moderate to high
+
+**Watsonx (Llama 3.3, Granite 3.x)**
+- ✅ Best for: Enterprise deployments, privacy-focused
+- ✅ Strengths: On-premise option, compliance-friendly
+- ✅ Status: Fully tested and working (project_id integration fixed)
+- ⚠️ Costs: Subscription-based
+
+**Ollama (Local Models)**
+- ✅ Best for: Cost-free operation, offline work
+- ✅ Strengths: Zero API costs, complete privacy
+- ✅ Status: Fully tested and working
+- ⚠️ Performance: Depends on hardware, may be slower
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues and Solutions
+
+**Issue: "ANTHROPIC_API_KEY is required" error with Claude**
+- **Solution**: This is now automatically handled. Update to latest version or ensure environment variables are set via Admin UI.
+
+**Issue: "Fallback to LiteLLM is not available" with Watsonx**
+- **Solution**: Ensure you've set both `WATSONX_API_KEY` and `WATSONX_PROJECT_ID`. Install `litellm` if needed: `pip install litellm`
+
+**Issue: Plan generation fails with validation error**
+- **Solution**: Update to latest version which includes READ action support in schema validation.
+
+**Issue: "Read Only" status despite having write access**
+- **Solution**: Install the GitPilot GitHub App on your repository. Click the install link in the UI or refresh permissions.
+
+**Issue: File tree not updating after agent operations**
+- **Solution**: Click the Refresh button in the file tree header to see newly created/modified files.
+
+For more issues, visit our [GitHub Issues](https://github.com/ruslanmv/gitpilot/issues) page.
+
+---
+
+<div align="center">
+
+**⭐ Don't forget to star GitPilot if you find it useful! ⭐**
+
+[⭐ Star on GitHub](https://github.com/ruslanmv/gitpilot) • [📖 Documentation](https://github.com/ruslanmv/gitpilot#readme) • [🐛 Report Bug](https://github.com/ruslanmv/gitpilot/issues) • [💡 Request Feature](https://github.com/ruslanmv/gitpilot/issues)
+
+**GitPilot** – Your AI Coding Companion for GitHub 🚀
+
+Made with ❤️ by [Ruslan Magana Vsevolodovna](https://github.com/ruslanmv)
+
+</div>

deploy/huggingface/start.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# =============================================================================
+# GitPilot — HF Spaces Startup Script
+# =============================================================================
+# Starts GitPilot FastAPI server with React frontend on HuggingFace Spaces.
+# Pre-configured to use OllaBridge Cloud as the default LLM provider.
+# =============================================================================
+
+set -e
+
+echo "=============================================="
+echo "  GitPilot — Hugging Face Spaces"
+echo "=============================================="
+echo ""
+
+# -- Ensure writable directories exist ----------------------------------------
+mkdir -p /tmp/gitpilot /tmp/gitpilot/workspaces /tmp/gitpilot/sessions
+export HOME=/tmp
+export GITPILOT_CONFIG_DIR=/tmp/gitpilot
+
+# -- Display configuration ---------------------------------------------------
+echo "[1/2] Configuration:"
+echo "       Provider: ${GITPILOT_PROVIDER:-ollabridge}"
+echo "       OllaBridge URL: ${OLLABRIDGE_BASE_URL:-https://ruslanmv-ollabridge.hf.space}"
+echo "       Model: ${GITPILOT_OLLABRIDGE_MODEL:-qwen2.5:1.5b}"
+echo ""
+
+# -- Check OllaBridge Cloud connectivity (non-blocking) ----------------------
+echo "[2/2] Checking LLM provider..."
+if curl -sf "${OLLABRIDGE_BASE_URL:-https://ruslanmv-ollabridge.hf.space}/health" > /dev/null 2>&1; then
+    echo "       OllaBridge Cloud is reachable"
+else
+    echo "       OllaBridge Cloud not reachable (will retry on first request)"
+    echo "       You can configure a different provider in Admin / LLM Settings"
+fi
+echo ""
+
+echo "=============================================="
+echo "  Ready! Endpoints:"
+echo "  - UI:        / (React frontend)"
+echo "  - API:       /api/health"
+echo "  - API Docs:  /docs"
+echo "  - Chat:      /api/chat/message"
+echo "  - Settings:  /api/settings"
+echo "=============================================="
+echo ""
+
+# -- Start GitPilot (foreground) ----------------------------------------------
+exec python -m uvicorn gitpilot.api:app \
+    --host "${HOST:-0.0.0.0}" \
+    --port "${PORT:-7860}" \
+    --workers 1 \
+    --timeout-keep-alive 120 \
+    --no-access-log

frontend/.dockerignore

@@ -0,0 +1,39 @@
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Build
+dist/
+build/
+
+# Environment
+.env
+.env.local
+.env.development
+.env.test
+.env.production.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Testing
+coverage/
+.nyc_output/
+
+# Misc
+*.log

frontend/.env.example

@@ -0,0 +1,7 @@
+# Frontend Environment Variables
+
+# Backend API URL
+# Leave empty for local development (uses Vite proxy to localhost:8000)
+# Set to your Render backend URL for production deployment on Vercel
+# Example: VITE_BACKEND_URL=https://gitpilot-backend.onrender.com
+VITE_BACKEND_URL=

frontend/.env.production.example

@@ -0,0 +1,5 @@
+# Production Environment Variables (Vercel)
+
+# Backend API URL - REQUIRED for production
+# Point this to your Render backend URL
+VITE_BACKEND_URL=https://gitpilot-backend.onrender.com

frontend/App.jsx

@@ -0,0 +1,909 @@
+// frontend/App.jsx
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import LoginPage from "./components/LoginPage.jsx";
+import RepoSelector from "./components/RepoSelector.jsx";
+import ProjectContextPanel from "./components/ProjectContextPanel.jsx";
+import ChatPanel from "./components/ChatPanel.jsx";
+import LlmSettings from "./components/LlmSettings.jsx";
+import FlowViewer from "./components/FlowViewer.jsx";
+import Footer from "./components/Footer.jsx";
+import ProjectSettingsModal from "./components/ProjectSettingsModal.jsx";
+import SessionSidebar from "./components/SessionSidebar.jsx";
+import ContextBar from "./components/ContextBar.jsx";
+import AddRepoModal from "./components/AddRepoModal.jsx";
+import { apiUrl, safeFetchJSON, fetchStatus } from "./utils/api.js";
+
+function makeRepoKey(repo) {
+  if (!repo) return null;
+  return repo.full_name || `${repo.owner}/${repo.name}`;
+}
+
+function uniq(arr) {
+  return Array.from(new Set((arr || []).filter(Boolean)));
+}
+
+export default function App() {
+  // ---- Multi-repo context state ----
+  const [contextRepos, setContextRepos] = useState([]);
+  // Each entry: { repoKey: "owner/repo", repo: {...}, branch: "main" }
+  const [activeRepoKey, setActiveRepoKey] = useState(null);
+  const [addRepoOpen, setAddRepoOpen] = useState(false);
+
+  const [activePage, setActivePage] = useState("workspace");
+  const [isAuthenticated, setIsAuthenticated] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [userInfo, setUserInfo] = useState(null);
+
+  // Repo + Session State Machine
+  const [repoStateByKey, setRepoStateByKey] = useState({});
+  const [toast, setToast] = useState(null);
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [adminTab, setAdminTab] = useState("overview");
+  const [adminStatus, setAdminStatus] = useState(null);
+
+  // Fetch admin status when overview tab is active
+  useEffect(() => {
+    if (activePage === "admin" && adminTab === "overview") {
+      fetchStatus()
+        .then(data => setAdminStatus(data))
+        .catch(() => setAdminStatus(null));
+    }
+  }, [activePage, adminTab]);
+
+  // Claude-Code-on-Web: Session sidebar + Environment state
+  const [activeSessionId, setActiveSessionId] = useState(null);
+  const [activeEnvId, setActiveEnvId] = useState("default");
+  const [sessionRefreshNonce, setSessionRefreshNonce] = useState(0);
+
+  // ---- Derived `repo` — keeps all downstream consumers unchanged ----
+  const repo = useMemo(() => {
+    const entry = contextRepos.find((r) => r.repoKey === activeRepoKey);
+    return entry?.repo || null;
+  }, [contextRepos, activeRepoKey]);
+
+  const repoKey = activeRepoKey;
+
+  // Convenient selectors
+  const currentRepoState = repoKey ? repoStateByKey[repoKey] : null;
+
+  const defaultBranch = currentRepoState?.defaultBranch || repo?.default_branch || "main";
+  const currentBranch = currentRepoState?.currentBranch || defaultBranch;
+  const sessionBranches = currentRepoState?.sessionBranches || [];
+  const lastExecution = currentRepoState?.lastExecution || null;
+  const pulseNonce = currentRepoState?.pulseNonce || 0;
+  const chatByBranch = currentRepoState?.chatByBranch || {};
+
+  // ---------------------------------------------------------------------------
+  // Multi-repo context management
+  // ---------------------------------------------------------------------------
+  const addRepoToContext = useCallback((r) => {
+    const key = makeRepoKey(r);
+    if (!key) return;
+
+    setContextRepos((prev) => {
+      // Don't add duplicates
+      if (prev.some((e) => e.repoKey === key)) {
+        // Already in context — just activate it
+        setActiveRepoKey(key);
+        return prev;
+      }
+      const entry = { repoKey: key, repo: r, branch: r.default_branch || "main" };
+      const next = [...prev, entry];
+      return next;
+    });
+    setActiveRepoKey(key);
+    setAddRepoOpen(false);
+  }, []);
+
+  const removeRepoFromContext = useCallback((key) => {
+    setContextRepos((prev) => {
+      const next = prev.filter((e) => e.repoKey !== key);
+      // Reassign active if we removed the active one
+      setActiveRepoKey((curActive) => {
+        if (curActive === key) {
+          return next.length > 0 ? next[0].repoKey : null;
+        }
+        return curActive;
+      });
+      return next;
+    });
+  }, []);
+
+  const clearAllContext = useCallback(() => {
+    setContextRepos([]);
+    setActiveRepoKey(null);
+  }, []);
+
+  const handleContextBranchChange = useCallback((targetRepoKey, newBranch) => {
+    // Update branch in contextRepos
+    setContextRepos((prev) =>
+      prev.map((e) =>
+        e.repoKey === targetRepoKey ? { ...e, branch: newBranch } : e
+      )
+    );
+    // Update branch in repoStateByKey
+    setRepoStateByKey((prev) => {
+      const cur = prev[targetRepoKey];
+      if (!cur) return prev;
+      return {
+        ...prev,
+        [targetRepoKey]: { ...cur, currentBranch: newBranch },
+      };
+    });
+  }, []);
+
+  // Init / reconcile repo state when active repo changes
+  useEffect(() => {
+    if (!repoKey || !repo) return;
+
+    setRepoStateByKey((prev) => {
+      const existing = prev[repoKey];
+      const d = repo.default_branch || "main";
+
+      if (!existing) {
+        return {
+          ...prev,
+          [repoKey]: {
+            defaultBranch: d,
+            currentBranch: d,
+            sessionBranches: [],
+            lastExecution: null,
+            pulseNonce: 0,
+            chatByBranch: {
+              [d]: { messages: [], plan: null },
+            },
+          },
+        };
+      }
+
+      const next = { ...existing };
+      next.defaultBranch = d;
+
+      if (!next.chatByBranch?.[d]) {
+        next.chatByBranch = {
+          ...(next.chatByBranch || {}),
+          [d]: { messages: [], plan: null },
+        };
+      }
+
+      if (!next.currentBranch) next.currentBranch = d;
+
+      return { ...prev, [repoKey]: next };
+    });
+  }, [repoKey, repo?.id, repo?.default_branch]);
+
+  const showToast = (title, message) => {
+    setToast({ title, message });
+    window.setTimeout(() => setToast(null), 5000);
+  };
+
+  // ---------------------------------------------------------------------------
+  // Session management — every chat is backed by a Session (Claude Code parity)
+  // ---------------------------------------------------------------------------
+
+  // Guard against double-creation during concurrent send() calls
+  const _creatingSessionRef = useRef(false);
+
+  /**
+   * ensureSession — Create a session on-demand (implicit).
+   *
+   * Called by ChatPanel before the first message is sent.  If a session
+   * already exists it returns the current ID immediately.  Otherwise it
+   * creates one, seeds the initial messages into chatBySession so the
+   * useEffect reset doesn't wipe them, and returns the new ID.
+   *
+   * @param {string} [sessionName] — optional title (first user prompt, truncated)
+   * @param {Array}  [seedMessages] — messages to pre-populate into the new session
+   * @returns {Promise<string|null>} the session ID
+   */
+  const ensureSession = useCallback(async (sessionName, seedMessages) => {
+    if (activeSessionId) return activeSessionId;
+    if (!repo) return null;
+    if (_creatingSessionRef.current) return null; // already in flight
+    _creatingSessionRef.current = true;
+
+    try {
+      const token = localStorage.getItem("github_token");
+      const headers = {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      };
+      const res = await fetch("/api/sessions", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          repo_full_name: repoKey,
+          branch: currentBranch,
+          name: sessionName || undefined,
+          repos: contextRepos.map((e) => ({
+            full_name: e.repoKey,
+            branch: e.branch,
+            mode: e.repoKey === activeRepoKey ? "write" : "read",
+          })),
+          active_repo: activeRepoKey,
+        }),
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      const newId = data.session_id;
+
+      // Seed the session's chat state BEFORE setting activeSessionId so
+      // the ChatPanel useEffect sync picks up the messages instead of []
+      if (seedMessages && seedMessages.length > 0) {
+        setChatBySession((prev) => ({
+          ...prev,
+          [newId]: { messages: seedMessages, plan: null },
+        }));
+      }
+
+      setActiveSessionId(newId);
+      setSessionRefreshNonce((n) => n + 1);
+      return newId;
+    } catch (err) {
+      console.warn("Failed to create session:", err);
+      return null;
+    } finally {
+      _creatingSessionRef.current = false;
+    }
+  }, [activeSessionId, repo, repoKey, currentBranch, contextRepos, activeRepoKey]);
+
+  // Explicit "New Session" button — clears chat and starts fresh
+  const handleNewSession = async () => {
+    // Clear the current session so ensureSession creates a new one
+    setActiveSessionId(null);
+    try {
+      const token = localStorage.getItem("github_token");
+      const headers = {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      };
+      const res = await fetch("/api/sessions", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          repo_full_name: repoKey,
+          branch: currentBranch,
+          repos: contextRepos.map((e) => ({
+            full_name: e.repoKey,
+            branch: e.branch,
+            mode: e.repoKey === activeRepoKey ? "write" : "read",
+          })),
+          active_repo: activeRepoKey,
+        }),
+      });
+      if (!res.ok) return;
+      const data = await res.json();
+      setActiveSessionId(data.session_id);
+      setSessionRefreshNonce((n) => n + 1);
+      showToast("Session Created", `New session started.`);
+    } catch (err) {
+      console.warn("Failed to create session:", err);
+    }
+  };
+
+  const handleSelectSession = (session) => {
+    setActiveSessionId(session.id);
+    if (session.branch && session.branch !== currentBranch) {
+      handleBranchChange(session.branch);
+    }
+  };
+
+  // When a session is deleted: if it was the active session, clear the
+  // chat so the user returns to a fresh "new conversation" state.
+  // Non-active session deletions only affect the sidebar (handled there).
+  const handleDeleteSession = useCallback((deletedId) => {
+    if (deletedId === activeSessionId) {
+      setActiveSessionId(null);
+      // Clean up the in-memory chat state for the deleted session
+      setChatBySession((prev) => {
+        const next = { ...prev };
+        delete next[deletedId];
+        return next;
+      });
+      // Also clear the branch-keyed chat (the persistence effect may have
+      // written the first user message there before the session was created)
+      if (repoKey) {
+        setRepoStateByKey((prev) => {
+          const cur = prev[repoKey];
+          if (!cur) return prev;
+          const branchKey = cur.currentBranch || cur.defaultBranch || defaultBranch;
+          return {
+            ...prev,
+            [repoKey]: {
+              ...cur,
+              chatByBranch: {
+                ...(cur.chatByBranch || {}),
+                [branchKey]: { messages: [], plan: null },
+              },
+            },
+          };
+        });
+      }
+    }
+  }, [activeSessionId, repoKey, defaultBranch]);
+
+  // ---------------------------------------------------------------------------
+  // Chat persistence helpers
+  // ---------------------------------------------------------------------------
+  const updateChatForCurrentBranch = (patch) => {
+    if (!repoKey) return;
+
+    setRepoStateByKey((prev) => {
+      const cur = prev[repoKey];
+      if (!cur) return prev;
+
+      const branchKey = cur.currentBranch || cur.defaultBranch || defaultBranch;
+
+      const existing = cur.chatByBranch?.[branchKey] || {
+        messages: [],
+        plan: null,
+      };
+
+      return {
+        ...prev,
+        [repoKey]: {
+          ...cur,
+          chatByBranch: {
+            ...(cur.chatByBranch || {}),
+            [branchKey]: { ...existing, ...patch },
+          },
+        },
+      };
+    });
+  };
+
+  const currentChatState = useMemo(() => {
+    const b = currentBranch || defaultBranch;
+    return chatByBranch[b] || { messages: [], plan: null };
+  }, [chatByBranch, currentBranch, defaultBranch]);
+
+  // ---------------------------------------------------------------------------
+  // Session-scoped chat state: isolate messages per (session + branch) instead
+  // of per-branch alone.  This prevents session A's messages from leaking into
+  // session B when both sessions share the same branch.
+  // ---------------------------------------------------------------------------
+  const [chatBySession, setChatBySession] = useState({});
+
+  const sessionChatState = useMemo(() => {
+    if (!activeSessionId) {
+      // No session — fall back to legacy branch-keyed chat
+      return currentChatState;
+    }
+    return chatBySession[activeSessionId] || { messages: [], plan: null };
+  }, [activeSessionId, chatBySession, currentChatState]);
+
+  const updateSessionChat = (patch) => {
+    if (activeSessionId) {
+      setChatBySession((prev) => ({
+        ...prev,
+        [activeSessionId]: {
+          ...(prev[activeSessionId] || { messages: [], plan: null }),
+          ...patch,
+        },
+      }));
+    } else {
+      // No active session — use legacy branch-keyed persistence
+      updateChatForCurrentBranch(patch);
+    }
+  };
+
+  // ---------------------------------------------------------------------------
+  // Branch change (manual — for active repo)
+  // ---------------------------------------------------------------------------
+  const handleBranchChange = (nextBranch) => {
+    if (!repoKey) return;
+    if (!nextBranch || nextBranch === currentBranch) return;
+
+    setRepoStateByKey((prev) => {
+      const cur = prev[repoKey];
+      if (!cur) return prev;
+
+      const nextState = { ...cur, currentBranch: nextBranch };
+
+      // If switching BACK to main/default -> clear main chat (new task start)
+      if (nextBranch === cur.defaultBranch) {
+        nextState.chatByBranch = {
+          ...nextState.chatByBranch,
+          [nextBranch]: { messages: [], plan: null },
+        };
+      }
+
+      return { ...prev, [repoKey]: nextState };
+    });
+
+    // Also update contextRepos branch tracking
+    setContextRepos((prev) =>
+      prev.map((e) =>
+        e.repoKey === repoKey ? { ...e, branch: nextBranch } : e
+      )
+    );
+
+    if (nextBranch === defaultBranch) {
+      showToast("New Session", `Switched to ${defaultBranch}. Chat cleared.`);
+    } else {
+      showToast("Context Switched", `Now viewing ${nextBranch}.`);
+    }
+  };
+
+  // ---------------------------------------------------------------------------
+  // Execution complete
+  // ---------------------------------------------------------------------------
+  const handleExecutionComplete = ({
+    branch,
+    mode,
+    commit_url,
+    message,
+    completionMsg,
+    sourceBranch,
+  }) => {
+    if (!repoKey || !branch) return;
+
+    setRepoStateByKey((prev) => {
+      const cur =
+        prev[repoKey] || {
+          defaultBranch,
+          currentBranch: defaultBranch,
+          sessionBranches: [],
+          lastExecution: null,
+          pulseNonce: 0,
+          chatByBranch: { [defaultBranch]: { messages: [], plan: null } },
+        };
+
+      const next = { ...cur };
+      next.lastExecution = { mode, branch, ts: Date.now() };
+
+      if (!next.chatByBranch) next.chatByBranch = {};
+
+      const prevBranchKey =
+        sourceBranch || cur.currentBranch || cur.defaultBranch || defaultBranch;
+
+      const successSystemMsg = {
+        role: "system",
+        isSuccess: true,
+        link: commit_url,
+        content:
+          mode === "hard-switch"
+            ? `🌱 **Session Started:** Created branch \`${branch}\`.`
+            : `✅ **Update Published:** Commits pushed to \`${branch}\`.`,
+      };
+
+      const normalizedCompletion =
+        completionMsg && (completionMsg.answer || completionMsg.content || completionMsg.executionLog)
+          ? {
+              from: completionMsg.from || "ai",
+              role: completionMsg.role || "assistant",
+              answer: completionMsg.answer,
+              content: completionMsg.content,
+              executionLog: completionMsg.executionLog,
+            }
+          : null;
+
+      if (mode === "hard-switch") {
+        next.sessionBranches = uniq([...(next.sessionBranches || []), branch]);
+        next.currentBranch = branch;
+        next.pulseNonce = (next.pulseNonce || 0) + 1;
+
+        const existingTargetChat = next.chatByBranch[branch];
+        const isExistingSession =
+          existingTargetChat && (existingTargetChat.messages || []).length > 0;
+
+        if (isExistingSession) {
+          const appended = [
+            ...(existingTargetChat.messages || []),
+            ...(normalizedCompletion ? [normalizedCompletion] : []),
+            successSystemMsg,
+          ];
+
+          next.chatByBranch[branch] = {
+            ...existingTargetChat,
+            messages: appended,
+            plan: null,
+          };
+        } else {
+          const prevChat =
+            (cur.chatByBranch && cur.chatByBranch[prevBranchKey]) || { messages: [], plan: null };
+
+          next.chatByBranch[branch] = {
+            messages: [
+              ...(prevChat.messages || []),
+              ...(normalizedCompletion ? [normalizedCompletion] : []),
+              successSystemMsg,
+            ],
+            plan: null,
+          };
+        }
+
+        if (!next.chatByBranch[next.defaultBranch]) {
+          next.chatByBranch[next.defaultBranch] = { messages: [], plan: null };
+        }
+      } else if (mode === "sticky") {
+        next.currentBranch = cur.currentBranch || branch;
+
+        const targetChat = next.chatByBranch[branch] || { messages: [], plan: null };
+
+        next.chatByBranch[branch] = {
+          messages: [
+            ...(targetChat.messages || []),
+            ...(normalizedCompletion ? [normalizedCompletion] : []),
+            successSystemMsg,
+          ],
+          plan: null,
+        };
+      }
+
+      return { ...prev, [repoKey]: next };
+    });
+
+    if (mode === "hard-switch") {
+      showToast("Context Switched", `Active on ${branch}.`);
+    } else {
+      showToast("Changes Committed", `Updated ${branch}.`);
+    }
+  };
+
+  // ---------------------------------------------------------------------------
+  // Auth & Render
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    checkAuthentication();
+  }, []);
+
+  const checkAuthentication = async () => {
+    const token = localStorage.getItem("github_token");
+    const user = localStorage.getItem("github_user");
+    if (token && user) {
+      try {
+        const data = await safeFetchJSON(apiUrl("/api/auth/validate"), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ access_token: token }),
+        });
+        if (data.authenticated) {
+          setIsAuthenticated(true);
+          setUserInfo(JSON.parse(user));
+          setIsLoading(false);
+          return;
+        }
+      } catch (err) {
+        console.error(err);
+      }
+      localStorage.removeItem("github_token");
+      localStorage.removeItem("github_user");
+    }
+    setIsAuthenticated(false);
+    setIsLoading(false);
+  };
+
+  const handleAuthenticated = (session) => {
+    setIsAuthenticated(true);
+    setUserInfo(session.user);
+  };
+
+  const handleLogout = () => {
+    localStorage.removeItem("github_token");
+    localStorage.removeItem("github_user");
+    setIsAuthenticated(false);
+    setUserInfo(null);
+    clearAllContext();
+  };
+
+  if (isLoading)
+    return (
+      <div className="app-root">
+        <div className="loading-spinner"></div>
+      </div>
+    );
+
+  if (!isAuthenticated) return <LoginPage onAuthenticated={handleAuthenticated} />;
+
+  const hasContext = contextRepos.length > 0;
+
+  return (
+    <div className="app-root">
+      <div className="main-wrapper">
+        <aside className="sidebar">
+          {/* ---- Brand ---- */}
+          <div className="logo-row">
+            <div className="logo-square">GP</div>
+            <div>
+              <div className="logo-title">GitPilot</div>
+              <div className="logo-subtitle">Agentic GitHub Copilot</div>
+            </div>
+          </div>
+
+          {/* ---- Navigation ---- */}
+          <div className="main-nav">
+            <button
+              className={"nav-btn" + (activePage === "workspace" ? " nav-btn-active" : "")}
+              onClick={() => setActivePage("workspace")}
+            >
+              Workspace
+            </button>
+            <button
+              className={"nav-btn" + (activePage === "flow" ? " nav-btn-active" : "")}
+              onClick={() => setActivePage("flow")}
+            >
+              Agent Workflow
+            </button>
+            <button
+              className={"nav-btn" + (activePage === "admin" ? " nav-btn-active" : "")}
+              onClick={() => setActivePage("admin")}
+            >
+              Admin
+            </button>
+          </div>
+
+          {/* ---- Repository Switcher (shown when no context) ---- */}
+          {!hasContext && (
+            <RepoSelector onSelect={(r) => addRepoToContext(r)} />
+          )}
+
+          {/* ---- Sessions ---- */}
+          {repo && (
+            <SessionSidebar
+              repo={repo}
+              activeSessionId={activeSessionId}
+              onSelectSession={handleSelectSession}
+              onNewSession={handleNewSession}
+              onDeleteSession={handleDeleteSession}
+              refreshNonce={sessionRefreshNonce}
+            />
+          )}
+
+          {/* ---- User ---- */}
+          {userInfo && (
+            <div className="user-profile">
+              <div className="user-profile-header">
+                <img src={userInfo.avatar_url} alt={userInfo.login} className="user-avatar" />
+                <div className="user-info">
+                  <div className="user-name">{userInfo.name || userInfo.login}</div>
+                  <div className="user-login">@{userInfo.login}</div>
+                </div>
+              </div>
+              <button className="btn-logout" onClick={handleLogout}>
+                Logout
+              </button>
+            </div>
+          )}
+        </aside>
+
+        <main className="workspace">
+          {activePage === "admin" && (
+            <div style={{ padding: "24px", maxWidth: "960px", margin: "0 auto" }}>
+              {/* Admin Navigation */}
+              <div style={{ display: "flex", gap: "8px", marginBottom: "24px", flexWrap: "wrap" }}>
+                {["overview", "providers", "workspace-modes", "integrations", "sessions", "skills", "security", "advanced"].map(tab => (
+                  <button
+                    key={tab}
+                    onClick={() => setAdminTab(tab)}
+                    style={{
+                      padding: "8px 16px",
+                      borderRadius: "6px",
+                      border: adminTab === tab ? "1px solid #3B82F6" : "1px solid #333",
+                      background: adminTab === tab ? "#1e3a5f" : "#1a1b26",
+                      color: adminTab === tab ? "#93c5fd" : "#a0a0b0",
+                      cursor: "pointer",
+                      fontSize: "13px",
+                      textTransform: "capitalize",
+                    }}
+                  >
+                    {tab.replace("-", " ")}
+                  </button>
+                ))}
+              </div>
+
+              {/* Overview */}
+              {adminTab === "overview" && (
+                <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr 1fr", gap: "16px" }}>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>Server</div>
+                    <div style={{ fontSize: "16px", fontWeight: 600 }}>{adminStatus?.server_ready ? "Connected" : "Checking..."}</div>
+                    <div style={{ fontSize: "12px", opacity: 0.5 }}>127.0.0.1:8000</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>Provider</div>
+                    <div style={{ fontSize: "16px", fontWeight: 600 }}>{adminStatus?.provider?.name || "Loading..."}</div>
+                    <div style={{ fontSize: "12px", opacity: 0.5 }}>{adminStatus?.provider?.configured ? `${adminStatus.provider.model || "Ready"}` : "Not configured"}</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>Workspace Modes</div>
+                    <div style={{ fontSize: "12px" }}>Folder: {adminStatus?.workspace?.folder_mode_available ? "Yes" : "—"}</div>
+                    <div style={{ fontSize: "12px" }}>Local Git: {adminStatus?.workspace?.local_git_available ? "Yes" : "—"}</div>
+                    <div style={{ fontSize: "12px" }}>GitHub: {adminStatus?.workspace?.github_mode_available ? "Yes" : "Optional"}</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>GitHub</div>
+                    <div style={{ fontSize: "14px" }}>{adminStatus?.github?.connected ? "Connected" : "Optional"}</div>
+                    <div style={{ fontSize: "12px", opacity: 0.5 }}>{adminStatus?.github?.username || "Not linked"}</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>Sessions</div>
+                    <div style={{ fontSize: "14px" }}>—</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "16px", border: "1px solid #2a2b36" }}>
+                    <div style={{ fontSize: "12px", opacity: 0.6, marginBottom: "8px" }}>Get Started</div>
+                    <button onClick={() => setAdminTab("providers")} style={{ padding: "6px 12px", background: "#3B82F6", color: "#fff", border: "none", borderRadius: "4px", cursor: "pointer", fontSize: "12px", marginRight: "4px" }}>Configure Provider</button>
+                  </div>
+                </div>
+              )}
+
+              {/* Providers */}
+              {adminTab === "providers" && (
+                <div>
+                  <h3 style={{ marginBottom: "16px" }}>AI Providers</h3>
+                  <LlmSettings />
+                </div>
+              )}
+
+              {/* Workspace Modes */}
+              {adminTab === "workspace-modes" && (
+                <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr 1fr", gap: "16px" }}>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "20px", border: "1px solid #2a2b36" }}>
+                    <h4 style={{ marginBottom: "8px" }}>Folder Mode</h4>
+                    <p style={{ fontSize: "12px", opacity: 0.7, marginBottom: "12px" }}>Work with any local folder. No Git required.</p>
+                    <div style={{ fontSize: "12px" }}>Requires: Open folder</div>
+                    <div style={{ fontSize: "12px" }}>Enables: Chat, explain, review</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "20px", border: "1px solid #2a2b36" }}>
+                    <h4 style={{ marginBottom: "8px" }}>Local Git Mode</h4>
+                    <p style={{ fontSize: "12px", opacity: 0.7, marginBottom: "12px" }}>Full repo + branch context for AI assistance.</p>
+                    <div style={{ fontSize: "12px" }}>Requires: Git repository</div>
+                    <div style={{ fontSize: "12px" }}>Enables: All local features</div>
+                  </div>
+                  <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "20px", border: "1px solid #2a2b36" }}>
+                    <h4 style={{ marginBottom: "8px" }}>GitHub Mode</h4>
+                    <p style={{ fontSize: "12px", opacity: 0.7, marginBottom: "12px" }}>PRs, issues, remote workflows via GitHub API.</p>
+                    <div style={{ fontSize: "12px" }}>Requires: GitHub token</div>
+                    <div style={{ fontSize: "12px" }}>Enables: Full platform features</div>
+                  </div>
+                </div>
+              )}
+
+              {/* Integrations */}
+              {adminTab === "integrations" && (
+                <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "20px", border: "1px solid #2a2b36" }}>
+                  <h4 style={{ marginBottom: "8px" }}>GitHub Integration</h4>
+                  <p style={{ fontSize: "12px", opacity: 0.7, marginBottom: "12px" }}>GitHub is optional. Connect to enable PRs, issues, and remote workflows.</p>
+                  <button style={{ padding: "8px 16px", background: "#3B82F6", color: "#fff", border: "none", borderRadius: "4px", cursor: "pointer" }}>Connect GitHub</button>
+                </div>
+              )}
+
+              {/* Security */}
+              {adminTab === "security" && (
+                <div style={{ background: "#1a1b26", borderRadius: "8px", padding: "20px", border: "1px solid #2a2b36" }}>
+                  <h4 style={{ marginBottom: "8px" }}>Security Scanning</h4>
+                  <p style={{ fontSize: "12px", opacity: 0.7, marginBottom: "12px" }}>Run security scans on your workspace to detect vulnerabilities, secrets, and code issues.</p>
+                  <button style={{ padding: "8px 16px", background: "#3B82F6", color: "#fff", border: "none", borderRadius: "4px", cursor: "pointer" }}>Scan Workspace</button>
+                </div>
+              )}
+
+              {/* Sessions */}
+              {adminTab === "sessions" && (
+                <div>
+                  <h3 style={{ marginBottom: "16px" }}>Sessions</h3>
+                  <p style={{ fontSize: "12px", opacity: 0.7 }}>Session management is available in the main workspace view.</p>
+                </div>
+              )}
+
+              {/* Skills & Plugins */}
+              {adminTab === "skills" && (
+                <div>
+                  <h3 style={{ marginBottom: "16px" }}>Skills & Plugins</h3>
+                  <p style={{ fontSize: "12px", opacity: 0.7 }}>Skills and plugins extend GitPilot capabilities. View and manage them from the main workspace.</p>
+                </div>
+              )}
+
+              {/* Advanced */}
+              {adminTab === "advanced" && (
+                <div>
+                  <h3 style={{ marginBottom: "16px" }}>Advanced Settings</h3>
+                  <p style={{ fontSize: "12px", opacity: 0.7 }}>Advanced configuration options are available in the Settings modal.</p>
+                  <button onClick={() => setSettingsOpen(true)} style={{ padding: "8px 16px", background: "#3B82F6", color: "#fff", border: "none", borderRadius: "4px", cursor: "pointer", marginTop: "12px" }}>Open Settings</button>
+                </div>
+              )}
+            </div>
+          )}
+          {activePage === "flow" && <FlowViewer />}
+          {activePage === "workspace" &&
+            (repo ? (
+              <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
+                {/* ---- Context Bar (single source of truth for repo selection) ---- */}
+                <ContextBar
+                  contextRepos={contextRepos}
+                  activeRepoKey={activeRepoKey}
+                  repoStateByKey={repoStateByKey}
+                  onActivate={setActiveRepoKey}
+                  onRemove={removeRepoFromContext}
+                  onAdd={() => setAddRepoOpen(true)}
+                  onBranchChange={handleContextBranchChange}
+                />
+
+                <div className="workspace-grid" style={{ flex: 1 }}>
+                  <aside className="gp-context-column">
+                    <ProjectContextPanel
+                      repo={repo}
+                      defaultBranch={defaultBranch}
+                      currentBranch={currentBranch}
+                      sessionBranches={sessionBranches}
+                      onBranchChange={handleBranchChange}
+                      pulseNonce={pulseNonce}
+                      lastExecution={lastExecution}
+                      onSettingsClick={() => setSettingsOpen(true)}
+                    />
+                  </aside>
+
+                  <main className="gp-chat-column">
+                    <div className="panel-header">
+                      <span>GitPilot chat</span>
+                    </div>
+
+                    <ChatPanel
+                      repo={repo}
+                      defaultBranch={defaultBranch}
+                      currentBranch={currentBranch}
+                      onExecutionComplete={handleExecutionComplete}
+                      sessionChatState={sessionChatState}
+                      onSessionChatStateChange={updateSessionChat}
+                      sessionId={activeSessionId}
+                      onEnsureSession={ensureSession}
+                    />
+                  </main>
+                </div>
+              </div>
+            ) : (
+              <div className="empty-state">
+                <div className="empty-bot">🤖</div>
+                <h1>Select a repository</h1>
+                <p>Select a repo to begin agentic workflow.</p>
+              </div>
+            ))}
+        </main>
+      </div>
+
+      <Footer />
+
+      {repo && (
+        <ProjectSettingsModal
+          owner={repo.full_name?.split("/")[0] || repo.owner}
+          repo={repo.full_name?.split("/")[1] || repo.name}
+          isOpen={settingsOpen}
+          onClose={() => setSettingsOpen(false)}
+          activeEnvId={activeEnvId}
+          onEnvChange={setActiveEnvId}
+        />
+      )}
+
+      {/* Add Repo Modal */}
+      <AddRepoModal
+        isOpen={addRepoOpen}
+        onSelect={addRepoToContext}
+        onClose={() => setAddRepoOpen(false)}
+        excludeKeys={contextRepos.map((e) => e.repoKey)}
+      />
+
+      {toast && (
+        <div className="toast-notification">
+          <div style={{ fontSize: 12, fontWeight: 700 }}>{toast.title}</div>
+          <div style={{ fontSize: 12, opacity: 0.82 }}>{toast.message}</div>
+        </div>
+      )}
+
+      <style>{`
+        .toast-notification {
+          position: fixed;
+          top: 72px;
+          right: 18px;
+          z-index: 9999;
+          background: #0b0b0d;
+          color: #EDEDED;
+          border: 1px solid rgba(255,255,255,0.12);
+          border-left: 3px solid #3B82F6;
+          border-radius: 10px;
+          padding: 12px 14px;
+          min-width: 320px;
+          box-shadow: 0 10px 30px rgba(0,0,0,0.4);
+        }
+      `}</style>
+    </div>
+  );
+}

frontend/components/AddRepoModal.jsx

@@ -0,0 +1,256 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { authFetch } from "../utils/api.js";
+
+/**
+ * AddRepoModal — lightweight portal modal for adding repos to context.
+ *
+ * Embeds a minimal repo search/list (not the full RepoSelector) to keep
+ * the modal focused. Filters out repos already in context.
+ */
+export default function AddRepoModal({ isOpen, onSelect, onClose, excludeKeys = [] }) {
+  const [query, setQuery] = useState("");
+  const [repos, setRepos] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  const fetchRepos = useCallback(
+    async (searchQuery) => {
+      setLoading(true);
+      try {
+        const params = new URLSearchParams({ per_page: "50" });
+        if (searchQuery) params.set("query", searchQuery);
+        const res = await authFetch(`/api/repos?${params}`);
+        if (!res.ok) return;
+        const data = await res.json();
+        setRepos(data.repositories || []);
+      } catch (err) {
+        console.warn("AddRepoModal: fetch failed:", err);
+      } finally {
+        setLoading(false);
+      }
+    },
+    []
+  );
+
+  useEffect(() => {
+    if (isOpen) {
+      setQuery("");
+      fetchRepos("");
+    }
+  }, [isOpen, fetchRepos]);
+
+  // Debounced search
+  useEffect(() => {
+    if (!isOpen) return;
+    const t = setTimeout(() => fetchRepos(query), 300);
+    return () => clearTimeout(t);
+  }, [query, isOpen, fetchRepos]);
+
+  const excludeSet = new Set(excludeKeys);
+  const filtered = repos.filter((r) => {
+    const key = r.full_name || `${r.owner}/${r.name}`;
+    return !excludeSet.has(key);
+  });
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div
+      style={styles.overlay}
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onClose();
+      }}
+    >
+      <div style={styles.modal} onMouseDown={(e) => e.stopPropagation()}>
+        <div style={styles.header}>
+          <span style={styles.headerTitle}>Add Repository</span>
+          <button type="button" style={styles.closeBtn} onClick={onClose}>
+            &times;
+          </button>
+        </div>
+
+        <div style={styles.searchBox}>
+          <input
+            type="text"
+            placeholder="Search repositories..."
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            style={styles.searchInput}
+            autoFocus
+            onKeyDown={(e) => {
+              if (e.key === "Escape") onClose();
+            }}
+          />
+        </div>
+
+        <div style={styles.list}>
+          {loading && filtered.length === 0 && (
+            <div style={styles.statusRow}>Loading...</div>
+          )}
+          {!loading && filtered.length === 0 && (
+            <div style={styles.statusRow}>
+              {excludeKeys.length > 0 && repos.length > 0
+                ? "All matching repos are already in context"
+                : "No repositories found"}
+            </div>
+          )}
+          {filtered.map((r) => {
+            const key = r.full_name || `${r.owner}/${r.name}`;
+            return (
+              <button
+                key={r.id || key}
+                type="button"
+                style={styles.repoRow}
+                onClick={() => onSelect(r)}
+              >
+                <div style={styles.repoInfo}>
+                  <span style={styles.repoName}>{r.name}</span>
+                  <span style={styles.repoOwner}>{r.owner}</span>
+                </div>
+                <div style={styles.repoMeta}>
+                  {r.private && <span style={styles.privateBadge}>Private</span>}
+                  <span style={styles.branchHint}>{r.default_branch || "main"}</span>
+                </div>
+              </button>
+            );
+          })}
+          {loading && filtered.length > 0 && (
+            <div style={styles.statusRow}>Updating...</div>
+          )}
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+const styles = {
+  overlay: {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: "rgba(0, 0, 0, 0.6)",
+    zIndex: 10000,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  modal: {
+    width: 440,
+    maxHeight: "70vh",
+    backgroundColor: "#131316",
+    border: "1px solid #27272A",
+    borderRadius: 12,
+    display: "flex",
+    flexDirection: "column",
+    overflow: "hidden",
+    boxShadow: "0 12px 40px rgba(0,0,0,0.5)",
+  },
+  header: {
+    display: "flex",
+    justifyContent: "space-between",
+    alignItems: "center",
+    padding: "12px 14px",
+    borderBottom: "1px solid #27272A",
+    backgroundColor: "#18181B",
+  },
+  headerTitle: {
+    fontSize: 14,
+    fontWeight: 600,
+    color: "#E4E4E7",
+  },
+  closeBtn: {
+    width: 26,
+    height: 26,
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "transparent",
+    color: "#A1A1AA",
+    fontSize: 16,
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  searchBox: {
+    padding: "10px 12px",
+    borderBottom: "1px solid #27272A",
+  },
+  searchInput: {
+    width: "100%",
+    padding: "8px 10px",
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "#18181B",
+    color: "#E4E4E7",
+    fontSize: 13,
+    outline: "none",
+    fontFamily: "monospace",
+    boxSizing: "border-box",
+  },
+  list: {
+    flex: 1,
+    overflowY: "auto",
+    maxHeight: 360,
+  },
+  statusRow: {
+    padding: "16px 12px",
+    textAlign: "center",
+    fontSize: 12,
+    color: "#71717A",
+  },
+  repoRow: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    width: "100%",
+    padding: "10px 14px",
+    border: "none",
+    borderBottom: "1px solid rgba(39, 39, 42, 0.5)",
+    background: "transparent",
+    color: "#E4E4E7",
+    cursor: "pointer",
+    textAlign: "left",
+    transition: "background-color 0.1s",
+  },
+  repoInfo: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 2,
+    minWidth: 0,
+  },
+  repoName: {
+    fontSize: 13,
+    fontWeight: 600,
+    fontFamily: "monospace",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  repoOwner: {
+    fontSize: 11,
+    color: "#71717A",
+  },
+  repoMeta: {
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+    flexShrink: 0,
+  },
+  privateBadge: {
+    fontSize: 9,
+    padding: "1px 5px",
+    borderRadius: 8,
+    backgroundColor: "rgba(239, 68, 68, 0.12)",
+    color: "#F87171",
+    fontWeight: 600,
+    textTransform: "uppercase",
+  },
+  branchHint: {
+    fontSize: 10,
+    color: "#52525B",
+    fontFamily: "monospace",
+  },
+};

frontend/components/AssistantMessage.jsx

@@ -0,0 +1,116 @@
+import React from "react";
+import PlanView from "./PlanView.jsx";
+
+export default function AssistantMessage({ answer, plan, executionLog }) {
+  const styles = {
+    container: {
+      marginBottom: "20px",
+      padding: "20px",
+      backgroundColor: "#18181B", // Zinc-900
+      borderRadius: "12px",
+      border: "1px solid #27272A", // Zinc-800
+      color: "#F4F4F5", // Zinc-100
+      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+      boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
+    },
+    section: {
+      marginBottom: "20px",
+    },
+    lastSection: {
+      marginBottom: "0",
+    },
+    header: {
+      display: "flex",
+      alignItems: "center",
+      marginBottom: "12px",
+      paddingBottom: "8px",
+      borderBottom: "1px solid #3F3F46", // Zinc-700
+    },
+    title: {
+      fontSize: "12px",
+      fontWeight: "600",
+      textTransform: "uppercase",
+      letterSpacing: "0.05em",
+      color: "#A1A1AA", // Zinc-400
+      margin: 0,
+    },
+    content: {
+      fontSize: "14px",
+      lineHeight: "1.6",
+      whiteSpace: "pre-wrap",
+    },
+    executionList: {
+      listStyle: "none",
+      padding: 0,
+      margin: 0,
+      display: "flex",
+      flexDirection: "column",
+      gap: "8px",
+    },
+    executionStep: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "4px",
+      padding: "10px",
+      backgroundColor: "#09090B", // Zinc-950
+      borderRadius: "6px",
+      border: "1px solid #27272A",
+      fontSize: "13px",
+    },
+    stepNumber: {
+      fontSize: "11px",
+      fontWeight: "600",
+      color: "#10B981", // Emerald-500
+      textTransform: "uppercase",
+    },
+    stepSummary: {
+      color: "#D4D4D8", // Zinc-300
+      fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+    },
+  };
+
+  return (
+    <div className="chat-message-ai" style={styles.container}>
+      {/* Answer section */}
+      <section style={styles.section}>
+        <header style={styles.header}>
+          <h3 style={styles.title}>Answer</h3>
+        </header>
+        <div style={styles.content}>
+          <p style={{ margin: 0 }}>{answer}</p>
+        </div>
+      </section>
+
+      {/* Action Plan section */}
+      {plan && (
+        <section style={styles.section}>
+          <header style={styles.header}>
+            <h3 style={{ ...styles.title, color: "#D95C3D" }}>Action Plan</h3>
+          </header>
+          <div>
+            <PlanView plan={plan} />
+          </div>
+        </section>
+      )}
+
+      {/* Execution Log section (shown after execution) */}
+      {executionLog && (
+        <section style={styles.lastSection}>
+          <header style={styles.header}>
+            <h3 style={{ ...styles.title, color: "#10B981" }}>Execution Log</h3>
+          </header>
+          <div>
+            <ul style={styles.executionList}>
+              {executionLog.steps.map((s) => (
+                <li key={s.step_number} style={styles.executionStep}>
+                  <span style={styles.stepNumber}>Step {s.step_number}</span>
+                  <span style={styles.stepSummary}>{s.summary}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}

frontend/components/BranchPicker.jsx

@@ -0,0 +1,398 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+/**
+ * BranchPicker — Claude-Code-on-Web parity branch selector.
+ *
+ * Fetches branches from the new /api/repos/{owner}/{repo}/branches endpoint.
+ * Shows search, default branch badge, AI session branch highlighting.
+ *
+ * Fixes applied:
+ * - Dropdown portaled to document.body (avoids overflow:hidden clipping)
+ * - Branches cached per repo (no "No branches found" flash)
+ * - Shows "Loading..." only on first fetch, keeps stale data otherwise
+ */
+
+// Simple per-repo branch cache so reopening the dropdown is instant
+const branchCache = {};
+
+/**
+ * Props:
+ *   repo, currentBranch, defaultBranch, sessionBranches, onBranchChange
+ *     — standard branch-picker props
+ *
+ *   externalAnchorRef (optional) — a React ref pointing to an external DOM
+ *     element to anchor the dropdown to.  When provided:
+ *       - BranchPicker skips rendering its own trigger button
+ *       - the dropdown opens immediately on mount
+ *       - closing the dropdown calls onClose()
+ *
+ *   onClose (optional) — called when the dropdown is dismissed (outside
+ *     click or Escape).  Only meaningful with externalAnchorRef.
+ */
+export default function BranchPicker({
+  repo,
+  currentBranch,
+  defaultBranch,
+  sessionBranches = [],
+  onBranchChange,
+  externalAnchorRef,
+  onClose,
+}) {
+  const isExternalMode = !!externalAnchorRef;
+  const [open, setOpen] = useState(isExternalMode);
+  const [query, setQuery] = useState("");
+  const [branches, setBranches] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const triggerRef = useRef(null);
+  const dropdownRef = useRef(null);
+  const inputRef = useRef(null);
+
+  const branch = currentBranch || defaultBranch || "main";
+  const isAiSession = sessionBranches.includes(branch) && branch !== defaultBranch;
+
+  // The element used for dropdown positioning
+  const anchorRef = isExternalMode ? externalAnchorRef : triggerRef;
+
+  const cacheKey = repo ? `${repo.owner}/${repo.name}` : null;
+
+  // Seed from cache on mount / repo change
+  useEffect(() => {
+    if (cacheKey && branchCache[cacheKey]) {
+      setBranches(branchCache[cacheKey]);
+    }
+  }, [cacheKey]);
+
+  // Fetch branches from GitHub via backend
+  const fetchBranches = useCallback(async (searchQuery) => {
+    if (!repo) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const token = localStorage.getItem("github_token");
+      const headers = token ? { Authorization: `Bearer ${token}` } : {};
+      const params = new URLSearchParams({ per_page: "100" });
+      if (searchQuery) params.set("query", searchQuery);
+
+      const res = await fetch(
+        `/api/repos/${repo.owner}/${repo.name}/branches?${params}`,
+        { headers, cache: "no-cache" }
+      );
+      if (!res.ok) {
+        const errData = await res.json().catch(() => ({}));
+        const detail = errData.detail || `HTTP ${res.status}`;
+        console.warn("BranchPicker: fetch failed:", detail);
+        setError(detail);
+        return;
+      }
+      const data = await res.json();
+      const fetched = data.branches || [];
+      setBranches(fetched);
+
+      // Only cache the unfiltered result
+      if (!searchQuery && cacheKey) {
+        branchCache[cacheKey] = fetched;
+      }
+    } catch (err) {
+      console.warn("Failed to fetch branches:", err);
+    } finally {
+      setLoading(false);
+    }
+  }, [repo, cacheKey]);
+
+  // Fetch + focus when opened
+  useEffect(() => {
+    if (open) {
+      fetchBranches(query);
+      setTimeout(() => inputRef.current?.focus(), 50);
+    }
+  }, [open]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Debounced search
+  useEffect(() => {
+    if (!open) return;
+    const t = setTimeout(() => fetchBranches(query), 300);
+    return () => clearTimeout(t);
+  }, [query, open, fetchBranches]);
+
+  // Close on outside click
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e) => {
+      const inAnchor = anchorRef.current && anchorRef.current.contains(e.target);
+      const inDropdown = dropdownRef.current && dropdownRef.current.contains(e.target);
+      if (!inAnchor && !inDropdown) {
+        handleClose();
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [open]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const handleClose = useCallback(() => {
+    setOpen(false);
+    setQuery("");
+    onClose?.();
+  }, [onClose]);
+
+  const handleSelect = (branchName) => {
+    handleClose();
+    if (branchName !== branch) {
+      onBranchChange?.(branchName);
+    }
+  };
+
+  // Merge API branches with session branches (AI branches might not show in GitHub API)
+  const allBranches = [...branches];
+  for (const sb of sessionBranches) {
+    if (!allBranches.find((b) => b.name === sb)) {
+      allBranches.push({ name: sb, is_default: false, protected: false });
+    }
+  }
+
+  // Calculate portal position from anchor element
+  const getDropdownPosition = () => {
+    if (!anchorRef.current) return { top: 0, left: 0 };
+    const rect = anchorRef.current.getBoundingClientRect();
+    return {
+      top: rect.bottom + 4,
+      left: rect.left,
+    };
+  };
+
+  const pos = open ? getDropdownPosition() : { top: 0, left: 0 };
+
+  return (
+    <div style={styles.container}>
+      {/* Trigger button — hidden when using external anchor */}
+      {!isExternalMode && (
+        <button
+          ref={triggerRef}
+          type="button"
+          style={{
+            ...styles.trigger,
+            borderColor: isAiSession ? "rgba(59, 130, 246, 0.3)" : "#3F3F46",
+            color: isAiSession ? "#60a5fa" : "#E4E4E7",
+            backgroundColor: isAiSession ? "rgba(59, 130, 246, 0.05)" : "transparent",
+          }}
+          onClick={() => setOpen((v) => !v)}
+        >
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <line x1="6" y1="3" x2="6" y2="15" />
+            <circle cx="18" cy="6" r="3" />
+            <circle cx="6" cy="18" r="3" />
+            <path d="M18 9a9 9 0 0 1-9 9" />
+          </svg>
+          <span style={styles.branchName}>{branch}</span>
+          <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <polyline points="6 9 12 15 18 9" />
+          </svg>
+        </button>
+      )}
+
+      {/* Dropdown — portaled to document.body to escape overflow:hidden */}
+      {open && createPortal(
+        <div
+          ref={dropdownRef}
+          style={{
+            ...styles.dropdown,
+            top: pos.top,
+            left: pos.left,
+          }}
+        >
+          {/* Search input */}
+          <div style={styles.searchBox}>
+            <input
+              ref={inputRef}
+              type="text"
+              placeholder="Search branches..."
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              style={styles.searchInput}
+              onKeyDown={(e) => {
+                if (e.key === "Escape") {
+                  handleClose();
+                }
+              }}
+            />
+          </div>
+
+          {/* Branch list */}
+          <div style={styles.branchList}>
+            {loading && allBranches.length === 0 && (
+              <div style={styles.loadingRow}>Loading...</div>
+            )}
+
+            {!loading && error && (
+              <div style={styles.errorRow}>{error}</div>
+            )}
+
+            {!loading && !error && allBranches.length === 0 && (
+              <div style={styles.loadingRow}>No branches found</div>
+            )}
+
+            {allBranches.map((b) => {
+              const isDefault = b.is_default || b.name === defaultBranch;
+              const isAi = sessionBranches.includes(b.name);
+              const isCurrent = b.name === branch;
+
+              return (
+                <div
+                  key={b.name}
+                  style={{
+                    ...styles.branchRow,
+                    backgroundColor: isCurrent
+                      ? isAi
+                        ? "rgba(59, 130, 246, 0.10)"
+                        : "#27272A"
+                      : "transparent",
+                  }}
+                  onMouseDown={() => handleSelect(b.name)}
+                >
+                  <span style={{ opacity: isCurrent ? 1 : 0, width: 16, flexShrink: 0 }}>
+                    &#10003;
+                  </span>
+                  <span
+                    style={{
+                      flex: 1,
+                      fontFamily: "monospace",
+                      fontSize: 12,
+                      color: isAi ? "#60a5fa" : "#E4E4E7",
+                      whiteSpace: "nowrap",
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                    }}
+                  >
+                    {b.name}
+                  </span>
+                  {isDefault && (
+                    <span style={styles.defaultBadge}>default</span>
+                  )}
+                  {isAi && !isDefault && (
+                    <span style={styles.aiBadge}>AI</span>
+                  )}
+                  {b.protected && (
+                    <span style={styles.protectedBadge}>
+                      <svg width="8" height="8" viewBox="0 0 24 24" fill="currentColor">
+                        <path d="M12 1L3 5v6c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V5l-9-4z" />
+                      </svg>
+                    </span>
+                  )}
+                </div>
+              );
+            })}
+
+            {/* Subtle loading indicator when refreshing with cached data visible */}
+            {loading && allBranches.length > 0 && (
+              <div style={styles.loadingRow}>Updating...</div>
+            )}
+          </div>
+        </div>,
+        document.body
+      )}
+    </div>
+  );
+}
+
+const styles = {
+  container: {
+    position: "relative",
+  },
+  trigger: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "4px 8px",
+    borderRadius: 4,
+    border: "1px solid #3F3F46",
+    background: "transparent",
+    fontSize: 13,
+    cursor: "pointer",
+    fontFamily: "monospace",
+    maxWidth: 200,
+  },
+  branchName: {
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    maxWidth: 140,
+  },
+  dropdown: {
+    position: "fixed",
+    width: 280,
+    backgroundColor: "#1F1F23",
+    border: "1px solid #27272A",
+    borderRadius: 8,
+    boxShadow: "0 8px 24px rgba(0,0,0,0.6)",
+    zIndex: 9999,
+    overflow: "hidden",
+  },
+  searchBox: {
+    padding: "8px 10px",
+    borderBottom: "1px solid #27272A",
+  },
+  searchInput: {
+    width: "100%",
+    padding: "6px 8px",
+    borderRadius: 4,
+    border: "1px solid #3F3F46",
+    background: "#131316",
+    color: "#E4E4E7",
+    fontSize: 12,
+    outline: "none",
+    fontFamily: "monospace",
+    boxSizing: "border-box",
+  },
+  branchList: {
+    maxHeight: 260,
+    overflowY: "auto",
+  },
+  branchRow: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "7px 10px",
+    cursor: "pointer",
+    transition: "background-color 0.1s",
+    borderBottom: "1px solid rgba(39, 39, 42, 0.5)",
+  },
+  loadingRow: {
+    padding: "12px 10px",
+    textAlign: "center",
+    fontSize: 12,
+    color: "#71717A",
+  },
+  errorRow: {
+    padding: "12px 10px",
+    textAlign: "center",
+    fontSize: 11,
+    color: "#F59E0B",
+  },
+  defaultBadge: {
+    fontSize: 9,
+    padding: "1px 5px",
+    borderRadius: 8,
+    backgroundColor: "rgba(16, 185, 129, 0.15)",
+    color: "#10B981",
+    fontWeight: 600,
+    textTransform: "uppercase",
+    letterSpacing: "0.04em",
+    flexShrink: 0,
+  },
+  aiBadge: {
+    fontSize: 9,
+    padding: "1px 5px",
+    borderRadius: 8,
+    backgroundColor: "rgba(59, 130, 246, 0.15)",
+    color: "#60a5fa",
+    fontWeight: 700,
+    flexShrink: 0,
+  },
+  protectedBadge: {
+    color: "#F59E0B",
+    flexShrink: 0,
+    display: "flex",
+    alignItems: "center",
+  },
+};

frontend/components/ChatPanel.jsx

@@ -0,0 +1,686 @@
+// frontend/components/ChatPanel.jsx
+import React, { useEffect, useRef, useState } from "react";
+import AssistantMessage from "./AssistantMessage.jsx";
+import DiffStats from "./DiffStats.jsx";
+import DiffViewer from "./DiffViewer.jsx";
+import CreatePRButton from "./CreatePRButton.jsx";
+import StreamingMessage from "./StreamingMessage.jsx";
+import { SessionWebSocket } from "../utils/ws.js";
+
+// Helper to get headers (inline safety if utility is missing)
+const getHeaders = () => ({
+  "Content-Type": "application/json",
+  Authorization: `Bearer ${localStorage.getItem("github_token") || ""}`,
+});
+
+export default function ChatPanel({
+  repo,
+  defaultBranch = "main",
+  currentBranch, // do NOT default here; parent must pass the real one
+  onExecutionComplete,
+  sessionChatState,
+  onSessionChatStateChange,
+  sessionId,
+  onEnsureSession,
+  canChat = true, // readiness gate: false disables composer and shows blocker
+  chatBlocker = null, // { message: string, cta?: string, onCta?: () => void }
+}) {
+  // Initialize state from props or defaults
+  const [messages, setMessages] = useState(sessionChatState?.messages || []);
+  const [goal, setGoal] = useState("");
+  const [plan, setPlan] = useState(sessionChatState?.plan || null);
+
+  const [loadingPlan, setLoadingPlan] = useState(false);
+  const [executing, setExecuting] = useState(false);
+  const [status, setStatus] = useState("");
+
+  // Claude-Code-on-Web: WebSocket streaming + diff + PR
+  const [wsConnected, setWsConnected] = useState(false);
+  const [streamingEvents, setStreamingEvents] = useState([]);
+  const [diffData, setDiffData] = useState(null);
+  const [showDiffViewer, setShowDiffViewer] = useState(false);
+  const wsRef = useRef(null);
+
+  // Ref mirrors streamingEvents so WS callbacks avoid stale closures
+  const streamingEventsRef = useRef([]);
+  useEffect(() => { streamingEventsRef.current = streamingEvents; }, [streamingEvents]);
+
+  // Skip the session-sync useEffect reset when we just created a session
+  // (the parent already seeded the messages into chatBySession)
+  const skipNextSyncRef = useRef(false);
+
+  const messagesEndRef = useRef(null);
+  const prevMsgCountRef = useRef((sessionChatState?.messages || []).length);
+
+  // ---------------------------------------------------------------------------
+  // WebSocket connection management
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    // Clean up previous connection
+    if (wsRef.current) {
+      wsRef.current.close();
+      wsRef.current = null;
+      setWsConnected(false);
+    }
+
+    if (!sessionId) return;
+
+    const ws = new SessionWebSocket(sessionId, {
+      onConnect: () => setWsConnected(true),
+      onDisconnect: () => setWsConnected(false),
+      onMessage: (data) => {
+        if (data.type === "agent_message") {
+          setStreamingEvents((prev) => [...prev, data]);
+        } else if (data.type === "tool_use" || data.type === "tool_result") {
+          setStreamingEvents((prev) => [...prev, data]);
+        } else if (data.type === "diff_update") {
+          setDiffData(data.stats || data);
+        } else if (data.type === "session_restored") {
+          // Session loaded
+        }
+      },
+      onStatusChange: (newStatus) => {
+        if (newStatus === "waiting") {
+          // Always clear loading state when agent finishes
+          setLoadingPlan(false);
+
+          // Consolidate streaming events into a chat message (use ref to
+          // avoid stale closure — streamingEvents state would be stale here)
+          const events = streamingEventsRef.current;
+          if (events.length > 0) {
+            const textParts = events
+              .filter((e) => e.type === "agent_message")
+              .map((e) => e.content);
+            if (textParts.length > 0) {
+              const consolidated = {
+                from: "ai",
+                role: "assistant",
+                answer: textParts.join(""),
+                content: textParts.join(""),
+              };
+              setMessages((prev) => [...prev, consolidated]);
+            }
+            setStreamingEvents([]);
+          }
+        }
+      },
+      onError: (err) => {
+        console.warn("[ws] Error:", err);
+        setLoadingPlan(false);
+      },
+    });
+
+    ws.connect();
+    wsRef.current = ws;
+
+    return () => {
+      ws.close();
+    };
+  }, [sessionId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // ---------------------------------------------------------------------------
+  // 1) SESSION SYNC: Restore chat when branch, repo, OR session changes
+  // IMPORTANT: Do NOT depend on sessionChatState here (prevents prop/state loop)
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    // When send() just created a session, the parent seeded the messages
+    // into chatBySession already.  Skip the reset so we don't wipe
+    // the optimistic user message that was already rendered.
+    if (skipNextSyncRef.current) {
+      skipNextSyncRef.current = false;
+      return;
+    }
+
+    const nextMessages = sessionChatState?.messages || [];
+    const nextPlan = sessionChatState?.plan || null;
+
+    setMessages(nextMessages);
+    setPlan(nextPlan);
+
+    // Reset transient UI state on branch/repo/session switch
+    setGoal("");
+    setStatus("");
+    setLoadingPlan(false);
+    setExecuting(false);
+    setStreamingEvents([]);
+    setDiffData(null);
+
+    // Update msg count tracker so auto-scroll doesn't "jump" on switch
+    prevMsgCountRef.current = nextMessages.length;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentBranch, repo?.full_name, sessionId]);
+
+  // ---------------------------------------------------------------------------
+  // 2) PERSISTENCE: Save chat to Parent (no loop now because sync only on branch)
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    if (typeof onSessionChatStateChange === "function") {
+      // Avoid wiping parent state on mount
+      if (messages.length > 0 || plan) {
+        onSessionChatStateChange({ messages, plan });
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [messages, plan]);
+
+  // ---------------------------------------------------------------------------
+  // 3) AUTO-SCROLL: Only scroll when a message is appended (reduces flicker)
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    const curCount = messages.length + streamingEvents.length;
+    const prevCount = prevMsgCountRef.current;
+
+    // Only scroll when new messages are added
+    if (curCount > prevCount) {
+      prevMsgCountRef.current = curCount;
+      requestAnimationFrame(() => {
+        messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+      });
+    } else {
+      prevMsgCountRef.current = curCount;
+    }
+  }, [messages.length, streamingEvents.length]);
+
+  // ---------------------------------------------------------------------------
+  // HANDLERS
+  // ---------------------------------------------------------------------------
+  // ---------------------------------------------------------------------------
+  // Persist a message to the backend session (fire-and-forget)
+  // ---------------------------------------------------------------------------
+  const persistMessage = (sid, role, content) => {
+    if (!sid) return;
+    fetch(`/api/sessions/${sid}/message`, {
+      method: "POST",
+      headers: getHeaders(),
+      body: JSON.stringify({ role, content }),
+    }).catch(() => {}); // best-effort
+  };
+
+  const send = async () => {
+    if (!repo || !goal.trim()) return;
+
+    const text = goal.trim();
+
+    // Optimistic update (user bubble appears immediately)
+    const userMsg = { from: "user", role: "user", text, content: text };
+    setMessages((prev) => [...prev, userMsg]);
+
+    setLoadingPlan(true);
+    setStatus("");
+    setPlan(null);
+    setStreamingEvents([]);
+
+    // ------- Implicit session creation (Claude Code parity) -------
+    // Every chat must be backed by a session.  If none exists yet,
+    // create one on-demand before sending the plan request.
+    let sid = sessionId;
+    if (!sid && typeof onEnsureSession === "function") {
+      // Derive a short title from the first message
+      const sessionName = text.length > 60 ? text.slice(0, 57) + "..." : text;
+
+      // Tell the sync useEffect to skip the reset that would otherwise
+      // wipe the optimistic user message when activeSessionId changes.
+      skipNextSyncRef.current = true;
+
+      sid = await onEnsureSession(sessionName, [userMsg]);
+      if (!sid) {
+        // Session creation failed — continue without session
+        skipNextSyncRef.current = false;
+      }
+    }
+
+    // Persist user message to backend session
+    persistMessage(sid, "user", text);
+
+    // Always use HTTP for plan generation (the original reliable flow).
+    // WebSocket is only used for real-time streaming feedback display.
+    const effectiveBranch = currentBranch || defaultBranch || "HEAD";
+
+    try {
+      const res = await fetch("/api/chat/plan", {
+        method: "POST",
+        headers: getHeaders(),
+        body: JSON.stringify({
+          repo_owner: repo.owner,
+          repo_name: repo.name,
+          goal: text,
+          branch_name: effectiveBranch,
+        }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.detail || "Failed to generate plan");
+
+      setPlan(data);
+
+      // Extract summary from nested plan structure or top-level
+      const summary =
+        data.plan?.summary || data.summary || data.message ||
+        "Here is the proposed plan for your request.";
+
+      // Assistant response (Answer + Action Plan)
+      setMessages((prev) => [
+        ...prev,
+        {
+          from: "ai",
+          role: "assistant",
+          answer: summary,
+          content: summary,
+          plan: data,
+        },
+      ]);
+
+      // Persist assistant response to backend session
+      persistMessage(sid, "assistant", summary);
+
+      // Clear input only after success
+      setGoal("");
+    } catch (err) {
+      const msg = String(err?.message || err);
+      console.error(err);
+      setStatus(msg);
+      setMessages((prev) => [
+        ...prev,
+        { from: "ai", role: "system", content: `Error: ${msg}` },
+      ]);
+    } finally {
+      setLoadingPlan(false);
+    }
+  };
+
+  const execute = async () => {
+    if (!repo || !plan) return;
+
+    setExecuting(true);
+    setStatus("");
+
+    try {
+      // Guard: currentBranch might be missing if parent didn't pass it yet
+      const safeCurrent = currentBranch || defaultBranch || "HEAD";
+      const safeDefault = defaultBranch || "main";
+
+      // Sticky vs Hard Switch:
+      // - If on default branch -> undefined (backend creates new branch)
+      // - If already on AI branch -> currentBranch (backend updates existing)
+      const branch_name = safeCurrent === safeDefault ? undefined : safeCurrent;
+
+      const res = await fetch("/api/chat/execute", {
+        method: "POST",
+        headers: getHeaders(),
+        body: JSON.stringify({
+          repo_owner: repo.owner,
+          repo_name: repo.name,
+          plan,
+          branch_name,
+        }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.detail || "Execution failed");
+
+      setStatus(data.message || "Execution completed.");
+
+      const completionMsg = {
+        from: "ai",
+        role: "assistant",
+        answer: data.message || "Execution completed.",
+        content: data.message || "Execution completed.",
+        executionLog: data.executionLog,
+      };
+
+      // Show completion immediately (keeps old "Execution Log" section)
+      setMessages((prev) => [...prev, completionMsg]);
+
+      // Clear active plan UI
+      setPlan(null);
+
+      // Pass completionMsg upward for seeding branch history
+      if (typeof onExecutionComplete === "function") {
+        onExecutionComplete({
+          branch: data.branch || data.branch_name,
+          mode: data.mode,
+          commit_url: data.commit_url || data.html_url,
+          message: data.message,
+          completionMsg,
+          sourceBranch: safeCurrent,
+        });
+      }
+    } catch (err) {
+      console.error(err);
+      setStatus(String(err?.message || err));
+    } finally {
+      setExecuting(false);
+    }
+  };
+
+  // ---------------------------------------------------------------------------
+  // RENDER
+  // ---------------------------------------------------------------------------
+  const isOnSessionBranch = currentBranch && currentBranch !== defaultBranch;
+
+  return (
+    <div className="chat-container">
+      <style>{`
+        .chat-container { display: flex; flex-direction: column; height: 100%; }
+
+        .chat-messages {
+          flex: 1; overflow-y: auto;
+          padding: 20px;
+          display: flex; flex-direction: column; gap: 16px;
+        }
+
+        .chat-message-user {
+          align-self: flex-end;
+          background: #27272A;
+          color: #fff;
+          padding: 12px 16px;
+          border-radius: 10px;
+          max-width: 85%;
+          font-size: 14px;
+          line-height: 1.5;
+        }
+
+        /* Success System Message Styling */
+        .chat-msg-success {
+          align-self: flex-start;
+          width: 100%;
+          background: rgba(16, 185, 129, 0.10);
+          border: 1px solid rgba(16, 185, 129, 0.20);
+          color: #D1FAE5;
+          padding: 12px 16px;
+          border-radius: 10px;
+          display: flex;
+          gap: 12px;
+          font-size: 14px;
+        }
+        .success-icon { font-size: 18px; }
+        .success-link {
+          display: inline-block;
+          margin-top: 6px;
+          font-weight: 600;
+          color: #34D399;
+          text-decoration: none;
+        }
+        .success-link:hover { text-decoration: underline; }
+
+        .chat-input-box {
+          padding: 16px;
+          border-top: 1px solid #27272A;
+          background: #131316;
+        }
+
+        .chat-input-row { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; }
+
+        .chat-input {
+          flex: 1;
+          min-width: 200px;
+          background: #18181B;
+          border: 1px solid #27272A;
+          color: white;
+          padding: 10px 12px;
+          border-radius: 8px;
+          outline: none;
+          font-size: 14px;
+          font-family: inherit;
+          resize: none;
+          min-height: 40px;
+          max-height: 160px;
+          line-height: 1.4;
+        }
+
+        /* Enterprise controls (restored) */
+        .chat-btn {
+          height: 38px;
+          padding: 0 14px;
+          border-radius: 8px;
+          font-weight: 700;
+          cursor: pointer;
+          border: 1px solid transparent;
+          font-size: 13px;
+          white-space: nowrap;
+        }
+
+        /* Orange primary (old style) */
+        .chat-btn.primary { background: #D95C3D; color: #fff; }
+        .chat-btn.primary:hover { filter: brightness(0.98); }
+        .chat-btn.primary:disabled { opacity: 0.55; cursor: not-allowed; }
+
+        /* Secondary outline */
+        .chat-btn.secondary {
+          background: transparent;
+          border: 1px solid #3F3F46;
+          color: #A1A1AA;
+        }
+        .chat-btn.secondary:hover { background: rgba(255,255,255,0.04); }
+        .chat-btn.secondary:disabled { opacity: 0.55; cursor: not-allowed; }
+
+        .chat-empty-state {
+          text-align: center;
+          color: #52525B;
+          margin-top: 40px;
+          font-size: 14px;
+        }
+
+        /* WebSocket connection indicator */
+        .ws-indicator {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          font-size: 10px;
+          color: #71717A;
+          padding: 2px 6px;
+          border-radius: 4px;
+          background: rgba(24, 24, 27, 0.6);
+        }
+        .ws-dot {
+          width: 6px;
+          height: 6px;
+          border-radius: 50%;
+        }
+
+        @keyframes blink {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0; }
+        }
+      `}</style>
+
+      <div className="chat-messages">
+        {messages.map((m, idx) => {
+          // Success message (App.jsx injected)
+          if (m.isSuccess) {
+            return (
+              <div key={idx} className="chat-msg-success">
+                <div className="success-icon">🚀</div>
+                <div>
+                  <div style={{ whiteSpace: "pre-wrap" }}>{m.content}</div>
+                  {m.link && (
+                    <a href={m.link} target="_blank" rel="noreferrer" className="success-link">
+                      View Changes on GitHub &rarr;
+                    </a>
+                  )}
+                </div>
+              </div>
+            );
+          }
+
+          // User message
+          if (m.from === "user" || m.role === "user") {
+            return (
+              <div key={idx} className="chat-message-user">
+                <span>{m.text || m.content}</span>
+              </div>
+            );
+          }
+
+          // Assistant message (Answer / Plan / Execution Log)
+          return (
+            <div key={idx}>
+              <AssistantMessage
+                answer={m.answer || m.content}
+                plan={m.plan}
+                executionLog={m.executionLog}
+              />
+              {/* Diff stats indicator (Claude-Code-on-Web parity) */}
+              {m.diff && (
+                <DiffStats diff={m.diff} onClick={() => {
+                  setDiffData(m.diff);
+                  setShowDiffViewer(true);
+                }} />
+              )}
+            </div>
+          );
+        })}
+
+        {/* Streaming events (real-time agent output) */}
+        {streamingEvents.length > 0 && (
+          <div>
+            <StreamingMessage events={streamingEvents} />
+          </div>
+        )}
+
+        {loadingPlan && streamingEvents.length === 0 && (
+          <div className="chat-message-ai" style={{ color: "#A1A1AA", fontStyle: "italic", padding: "10px" }}>
+            Thinking...
+          </div>
+        )}
+
+        {!messages.length && !plan && !loadingPlan && streamingEvents.length === 0 && (
+          <div className="chat-empty-state">
+            <div className="chat-empty-icon">💬</div>
+            <p>Tell GitPilot what you want to do with this repository.</p>
+            <p style={{ fontSize: 12, color: "#676883", marginTop: 4 }}>
+              It will propose a safe step-by-step plan before any execution.
+            </p>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Diff stats bar (when agent has made changes) */}
+      {diffData && (
+        <div style={{
+          padding: "8px 16px",
+          borderTop: "1px solid #27272A",
+          background: "#18181B",
+        }}>
+          <DiffStats diff={diffData} onClick={() => setShowDiffViewer(true)} />
+        </div>
+      )}
+
+      <div className="chat-input-box">
+        {/* Readiness blocker banner */}
+        {!canChat && chatBlocker && (
+          <div style={{
+            fontSize: 12,
+            color: "#F59E0B",
+            background: "rgba(245, 158, 11, 0.08)",
+            border: "1px solid rgba(245, 158, 11, 0.2)",
+            borderRadius: 6,
+            padding: "8px 12px",
+            marginBottom: 8,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+          }}>
+            <span>{chatBlocker.message || "Chat is not ready yet."}</span>
+            {chatBlocker.cta && chatBlocker.onCta && (
+              <button
+                type="button"
+                onClick={chatBlocker.onCta}
+                style={{
+                  fontSize: 11,
+                  fontWeight: 600,
+                  color: "#F59E0B",
+                  background: "transparent",
+                  border: "1px solid rgba(245, 158, 11, 0.3)",
+                  borderRadius: 4,
+                  padding: "2px 8px",
+                  cursor: "pointer",
+                }}
+              >
+                {chatBlocker.cta}
+              </button>
+            )}
+          </div>
+        )}
+        {status && (
+          <div style={{ fontSize: 11, color: "#ffb3b7", marginBottom: 8 }}>
+            {status}
+          </div>
+        )}
+
+        <div className="chat-input-row">
+          <textarea
+            className="chat-input"
+            placeholder={wsConnected ? "Send feedback or instructions..." : "Describe the change you want to make..."}
+            value={goal}
+            rows={1}
+            onChange={(e) => {
+              setGoal(e.target.value);
+              e.target.style.height = "40px";
+              e.target.style.height = Math.min(e.target.scrollHeight, 160) + "px";
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" && !e.shiftKey) {
+                e.preventDefault();
+                if (!loadingPlan && !executing) send();
+              }
+            }}
+            disabled={!canChat || loadingPlan || executing}
+          />
+
+          {/* Always show both buttons (old UX) */}
+          <button
+            className="chat-btn primary"
+            type="button"
+            onClick={send}
+            disabled={!canChat || loadingPlan || executing || !goal.trim()}
+          >
+            {loadingPlan ? "Planning..." : wsConnected ? "Send" : "Generate plan"}
+          </button>
+
+          <button
+            className="chat-btn secondary"
+            type="button"
+            onClick={execute}
+            disabled={!plan || executing || loadingPlan}
+          >
+            {executing ? "Executing..." : "Approve & execute"}
+          </button>
+
+          {/* Create PR button (Claude-Code-on-Web parity) */}
+          {isOnSessionBranch && (
+            <CreatePRButton
+              repo={repo}
+              sessionId={sessionId}
+              branch={currentBranch}
+              defaultBranch={defaultBranch}
+              disabled={executing || loadingPlan}
+            />
+          )}
+        </div>
+
+        {/* WebSocket connection indicator */}
+        {sessionId && (
+          <div style={{ marginTop: 6, display: "flex", alignItems: "center", gap: 8 }}>
+            <span className="ws-indicator">
+              <span className="ws-dot" style={{
+                backgroundColor: wsConnected ? "#10B981" : "#EF4444",
+              }} />
+              {wsConnected ? "Live" : "Connecting..."}
+            </span>
+          </div>
+        )}
+      </div>
+
+      {/* Diff Viewer overlay */}
+      {showDiffViewer && (
+        <DiffViewer
+          diff={diffData}
+          onClose={() => setShowDiffViewer(false)}
+        />
+      )}
+    </div>
+  );
+}

frontend/components/ContextBar.jsx

@@ -0,0 +1,156 @@
+import React, { useCallback, useRef, useState } from "react";
+import BranchPicker from "./BranchPicker.jsx";
+
+/**
+ * ContextBar — horizontal repo chip bar for multi-repo workspace context.
+ *
+ * Uses CSS classes for hover-reveal X (Claude-style: subtle by default,
+ * visible on chip hover, red on X hover). Each chip owns its own remove
+ * button — removing one repo never affects the others.
+ */
+export default function ContextBar({
+  contextRepos,
+  activeRepoKey,
+  repoStateByKey,
+  onActivate,
+  onRemove,
+  onAdd,
+  onBranchChange,
+  mode, // workspace mode: "github", "local-git", "folder" (optional)
+}) {
+  if (!contextRepos || contextRepos.length === 0) return null;
+
+  return (
+    <div className="ctxbar">
+      {/* Workspace mode indicator */}
+      {mode && (
+        <span className="ctxbar-mode" title={`Workspace mode: ${mode}`}>
+          {mode === "github" ? "GH" : mode === "local-git" ? "Git" : "Dir"}
+        </span>
+      )}
+      <div className="ctxbar-scroll">
+        {contextRepos.map((entry) => {
+          const isActive = entry.repoKey === activeRepoKey;
+          return (
+            <RepoChip
+              key={entry.repoKey}
+              entry={entry}
+              isActive={isActive}
+              repoState={repoStateByKey?.[entry.repoKey]}
+              onActivate={() => onActivate(entry.repoKey)}
+              onRemove={() => onRemove(entry.repoKey)}
+              onBranchChange={(newBranch) =>
+                onBranchChange(entry.repoKey, newBranch)
+              }
+            />
+          );
+        })}
+
+        <button
+          type="button"
+          className="ctxbar-add"
+          onClick={onAdd}
+          title="Add repository to context"
+        >
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <line x1="12" y1="5" x2="12" y2="19" />
+            <line x1="5" y1="12" x2="19" y2="12" />
+          </svg>
+        </button>
+      </div>
+
+      <div className="ctxbar-meta">
+        {contextRepos.length} {contextRepos.length === 1 ? "repo" : "repos"}
+      </div>
+    </div>
+  );
+}
+
+function RepoChip({ entry, isActive, repoState, onActivate, onRemove, onBranchChange }) {
+  const [branchOpen, setBranchOpen] = useState(false);
+  const [hovered, setHovered] = useState(false);
+  const branchBtnRef = useRef(null);
+  const repo = entry.repo;
+  const branch = repoState?.currentBranch || entry.branch || repo?.default_branch || "main";
+  const defaultBranch = repoState?.defaultBranch || repo?.default_branch || "main";
+  const sessionBranches = repoState?.sessionBranches || [];
+  const displayName = repo?.name || entry.repoKey?.split("/")[1] || entry.repoKey;
+
+  const handleChipClick = useCallback(
+    (e) => {
+      if (e.target.closest("[data-chip-action]")) return;
+      onActivate();
+    },
+    [onActivate]
+  );
+
+  return (
+    <div
+      className={"ctxbar-chip" + (isActive ? " ctxbar-chip-active" : "")}
+      onClick={handleChipClick}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      title={isActive ? `Active (write): ${entry.repoKey}` : `Click to activate ${entry.repoKey}`}
+    >
+      {/* Active indicator bar */}
+      {isActive && <div className="ctxbar-chip-indicator" />}
+
+      {/* Repo name */}
+      <span className="ctxbar-chip-name">{displayName}</span>
+
+      {/* Separator dot */}
+      <span className="ctxbar-chip-dot" />
+
+      {/* Branch name — single click opens GitHub branch list */}
+      <button
+        ref={branchBtnRef}
+        type="button"
+        data-chip-action="branch"
+        className={"ctxbar-chip-branch" + (isActive ? " ctxbar-chip-branch-active" : "")}
+        onClick={(e) => {
+          e.stopPropagation();
+          setBranchOpen((v) => !v);
+        }}
+      >
+        {branch}
+      </button>
+
+      {/* Write badge for active repo */}
+      {isActive && <span className="ctxbar-chip-write">write</span>}
+
+      {/* Remove button: hidden by default, revealed on hover */}
+      <button
+        type="button"
+        data-chip-action="remove"
+        className={"ctxbar-chip-remove" + (hovered ? " ctxbar-chip-remove-visible" : "")}
+        onClick={(e) => {
+          e.stopPropagation();
+          onRemove();
+        }}
+        title={`Remove ${displayName} from context`}
+      >
+        <svg width="8" height="8" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+          <line x1="18" y1="6" x2="6" y2="18" />
+          <line x1="6" y1="6" x2="18" y2="18" />
+        </svg>
+      </button>
+
+      {/* BranchPicker in external-anchor mode: dropdown opens immediately,
+          positioned from the branch button, fetches all branches from GitHub */}
+      {branchOpen && (
+        <BranchPicker
+          repo={repo}
+          currentBranch={branch}
+          defaultBranch={defaultBranch}
+          sessionBranches={sessionBranches}
+          externalAnchorRef={branchBtnRef}
+          onBranchChange={(newBranch) => {
+            onBranchChange(newBranch);
+            setBranchOpen(false);
+          }}
+          onClose={() => setBranchOpen(false)}
+        />
+      )}
+    </div>
+  );
+}

frontend/components/CreatePRButton.jsx

@@ -0,0 +1,159 @@
+import React, { useState } from "react";
+
+/**
+ * CreatePRButton — Claude-Code-on-Web parity PR creation action.
+ *
+ * When clicked, pushes session changes to a new branch and opens a PR.
+ * Shows loading state and links to the created PR on GitHub.
+ */
+export default function CreatePRButton({
+  repo,
+  sessionId,
+  branch,
+  defaultBranch,
+  disabled,
+  onPRCreated,
+}) {
+  const [creating, setCreating] = useState(false);
+  const [prUrl, setPrUrl] = useState(null);
+  const [error, setError] = useState(null);
+
+  const handleCreate = async () => {
+    if (!repo || !branch || branch === defaultBranch) return;
+
+    setCreating(true);
+    setError(null);
+
+    try {
+      const token = localStorage.getItem("github_token");
+      const headers = {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      };
+
+      const owner = repo.full_name?.split("/")[0] || repo.owner;
+      const name = repo.full_name?.split("/")[1] || repo.name;
+
+      const res = await fetch(`/api/repos/${owner}/${name}/pulls`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          title: `[GitPilot] Changes from session ${sessionId ? sessionId.slice(0, 8) : branch}`,
+          head: branch,
+          base: defaultBranch || "main",
+          body: [
+            "## Summary",
+            "",
+            `Changes created by GitPilot AI assistant on branch \`${branch}\`.`,
+            "",
+            sessionId ? `Session ID: \`${sessionId}\`` : "",
+            "",
+            "---",
+            "*This PR was generated by [GitPilot](https://github.com/ruslanmv/gitpilot).*",
+          ]
+            .filter(Boolean)
+            .join("\n"),
+        }),
+      });
+
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.detail || "Failed to create PR");
+
+      const url = data.html_url || data.url;
+      setPrUrl(url);
+      onPRCreated?.({ pr_url: url, pr_number: data.number, branch });
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setCreating(false);
+    }
+  };
+
+  if (prUrl) {
+    return (
+      <a
+        href={prUrl}
+        target="_blank"
+        rel="noreferrer"
+        style={styles.prLink}
+      >
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          <circle cx="18" cy="18" r="3" />
+          <circle cx="6" cy="6" r="3" />
+          <path d="M13 6h3a2 2 0 0 1 2 2v7" />
+          <line x1="6" y1="9" x2="6" y2="21" />
+        </svg>
+        View PR on GitHub &rarr;
+      </a>
+    );
+  }
+
+  return (
+    <div>
+      <button
+        type="button"
+        style={{
+          ...styles.btn,
+          opacity: disabled || creating ? 0.55 : 1,
+          cursor: disabled || creating ? "not-allowed" : "pointer",
+        }}
+        onClick={handleCreate}
+        disabled={disabled || creating || !branch || branch === defaultBranch}
+        title={
+          !branch || branch === defaultBranch
+            ? "Create a session branch first"
+            : "Create a pull request from session changes"
+        }
+      >
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          <circle cx="18" cy="18" r="3" />
+          <circle cx="6" cy="6" r="3" />
+          <path d="M13 6h3a2 2 0 0 1 2 2v7" />
+          <line x1="6" y1="9" x2="6" y2="21" />
+        </svg>
+        {creating ? "Creating PR..." : "Create PR"}
+      </button>
+      {error && (
+        <div style={styles.error}>{error}</div>
+      )}
+    </div>
+  );
+}
+
+const styles = {
+  btn: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    height: 38,
+    padding: "0 14px",
+    borderRadius: 8,
+    border: "1px solid rgba(16, 185, 129, 0.3)",
+    background: "rgba(16, 185, 129, 0.08)",
+    color: "#10B981",
+    fontSize: 13,
+    fontWeight: 600,
+    cursor: "pointer",
+    whiteSpace: "nowrap",
+    transition: "background-color 0.15s",
+  },
+  prLink: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    height: 38,
+    padding: "0 14px",
+    borderRadius: 8,
+    background: "rgba(16, 185, 129, 0.10)",
+    color: "#10B981",
+    fontSize: 13,
+    fontWeight: 600,
+    textDecoration: "none",
+    whiteSpace: "nowrap",
+  },
+  error: {
+    fontSize: 11,
+    color: "#EF4444",
+    marginTop: 4,
+  },
+};

frontend/components/DiffStats.jsx

@@ -0,0 +1,59 @@
+import React from "react";
+
+/**
+ * DiffStats — Claude-Code-on-Web parity inline diff indicator.
+ *
+ * Clickable "+N -N in M files" badge that appears in agent messages.
+ * Clicking opens the DiffViewer overlay.
+ */
+export default function DiffStats({ diff, onClick }) {
+  if (!diff || (!diff.additions && !diff.deletions && !diff.files_changed)) {
+    return null;
+  }
+
+  return (
+    <button type="button" style={styles.container} onClick={onClick}>
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+        <path d="M12 3v18M3 12h18" opacity="0.3" />
+        <rect x="3" y="3" width="18" height="18" rx="2" />
+      </svg>
+      <span style={styles.additions}>+{diff.additions || 0}</span>
+      <span style={styles.deletions}>-{diff.deletions || 0}</span>
+      <span style={styles.files}>
+        in {diff.files_changed || (diff.files || []).length} file{(diff.files_changed || (diff.files || []).length) !== 1 ? "s" : ""}
+      </span>
+      <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" style={{ opacity: 0.5 }}>
+        <polyline points="9 18 15 12 9 6" />
+      </svg>
+    </button>
+  );
+}
+
+const styles = {
+  container: {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "5px 10px",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    backgroundColor: "rgba(24, 24, 27, 0.8)",
+    cursor: "pointer",
+    fontSize: 12,
+    fontFamily: "monospace",
+    color: "#A1A1AA",
+    transition: "border-color 0.15s, background-color 0.15s",
+    marginTop: 8,
+  },
+  additions: {
+    color: "#10B981",
+    fontWeight: 600,
+  },
+  deletions: {
+    color: "#EF4444",
+    fontWeight: 600,
+  },
+  files: {
+    color: "#71717A",
+  },
+};

frontend/components/DiffViewer.jsx

@@ -0,0 +1,263 @@
+import React, { useState } from "react";
+
+/**
+ * DiffViewer — Claude-Code-on-Web parity diff overlay.
+ *
+ * Shows a file list on the left and unified diff on the right.
+ * Green = additions, red = deletions. Additive component.
+ */
+export default function DiffViewer({ diff, onClose }) {
+  const [selectedFile, setSelectedFile] = useState(0);
+
+  if (!diff || !diff.files || diff.files.length === 0) {
+    return (
+      <div style={styles.overlay}>
+        <div style={styles.panel}>
+          <div style={styles.header}>
+            <span style={styles.headerTitle}>Diff Viewer</span>
+            <button type="button" style={styles.closeBtn} onClick={onClose}>
+              &times;
+            </button>
+          </div>
+          <div style={styles.emptyState}>No changes to display.</div>
+        </div>
+      </div>
+    );
+  }
+
+  const files = diff.files || [];
+  const currentFile = files[selectedFile] || files[0];
+
+  return (
+    <div style={styles.overlay}>
+      <div style={styles.panel}>
+        {/* Header */}
+        <div style={styles.header}>
+          <div style={styles.headerLeft}>
+            <span style={styles.headerTitle}>Diff Viewer</span>
+            <span style={styles.statBadge}>
+              <span style={{ color: "#10B981" }}>+{diff.additions || 0}</span>
+              {" "}
+              <span style={{ color: "#EF4444" }}>-{diff.deletions || 0}</span>
+              {" in "}
+              {diff.files_changed || files.length} files
+            </span>
+          </div>
+          <button type="button" style={styles.closeBtn} onClick={onClose}>
+            &times;
+          </button>
+        </div>
+
+        {/* Body */}
+        <div style={styles.body}>
+          {/* File list */}
+          <div style={styles.fileList}>
+            {files.map((f, idx) => (
+              <div
+                key={f.path}
+                style={{
+                  ...styles.fileItem,
+                  backgroundColor:
+                    idx === selectedFile ? "rgba(59, 130, 246, 0.10)" : "transparent",
+                  borderLeft:
+                    idx === selectedFile
+                      ? "2px solid #3B82F6"
+                      : "2px solid transparent",
+                }}
+                onClick={() => setSelectedFile(idx)}
+              >
+                <span style={styles.fileName}>{f.path}</span>
+                <span style={styles.fileStats}>
+                  <span style={{ color: "#10B981" }}>+{f.additions || 0}</span>
+                  {" "}
+                  <span style={{ color: "#EF4444" }}>-{f.deletions || 0}</span>
+                </span>
+              </div>
+            ))}
+          </div>
+
+          {/* Diff content */}
+          <div style={styles.diffContent}>
+            <div style={styles.diffPath}>{currentFile.path}</div>
+            <div style={styles.diffCode}>
+              {(currentFile.hunks || []).map((hunk, hi) => (
+                <div key={hi}>
+                  <div style={styles.hunkHeader}>{hunk.header || `@@ hunk ${hi + 1} @@`}</div>
+                  {(hunk.lines || []).map((line, li) => {
+                    let bg = "transparent";
+                    let color = "#D4D4D8";
+                    if (line.startsWith("+")) {
+                      bg = "rgba(16, 185, 129, 0.10)";
+                      color = "#6EE7B7";
+                    } else if (line.startsWith("-")) {
+                      bg = "rgba(239, 68, 68, 0.10)";
+                      color = "#FCA5A5";
+                    }
+                    return (
+                      <div
+                        key={li}
+                        style={{
+                          ...styles.diffLine,
+                          backgroundColor: bg,
+                          color,
+                        }}
+                      >
+                        {line}
+                      </div>
+                    );
+                  })}
+                </div>
+              ))}
+
+              {(!currentFile.hunks || currentFile.hunks.length === 0) && (
+                <div style={styles.diffPlaceholder}>
+                  Diff content will appear here when the agent modifies files.
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const styles = {
+  overlay: {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: "rgba(0, 0, 0, 0.7)",
+    zIndex: 200,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  panel: {
+    width: "90vw",
+    maxWidth: 1100,
+    height: "80vh",
+    backgroundColor: "#131316",
+    border: "1px solid #27272A",
+    borderRadius: 12,
+    display: "flex",
+    flexDirection: "column",
+    overflow: "hidden",
+  },
+  header: {
+    display: "flex",
+    justifyContent: "space-between",
+    alignItems: "center",
+    padding: "12px 16px",
+    borderBottom: "1px solid #27272A",
+    backgroundColor: "#18181B",
+  },
+  headerLeft: {
+    display: "flex",
+    alignItems: "center",
+    gap: 12,
+  },
+  headerTitle: {
+    fontSize: 14,
+    fontWeight: 600,
+    color: "#E4E4E7",
+  },
+  statBadge: {
+    fontSize: 12,
+    color: "#A1A1AA",
+  },
+  closeBtn: {
+    width: 28,
+    height: 28,
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "transparent",
+    color: "#A1A1AA",
+    fontSize: 18,
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  body: {
+    flex: 1,
+    display: "flex",
+    overflow: "hidden",
+  },
+  fileList: {
+    width: 240,
+    borderRight: "1px solid #27272A",
+    overflowY: "auto",
+    flexShrink: 0,
+  },
+  fileItem: {
+    padding: "8px 10px",
+    cursor: "pointer",
+    borderBottom: "1px solid rgba(39, 39, 42, 0.5)",
+    transition: "background-color 0.1s",
+  },
+  fileName: {
+    display: "block",
+    fontSize: 12,
+    fontFamily: "monospace",
+    color: "#E4E4E7",
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+  },
+  fileStats: {
+    display: "block",
+    fontSize: 10,
+    marginTop: 2,
+  },
+  diffContent: {
+    flex: 1,
+    overflow: "auto",
+    display: "flex",
+    flexDirection: "column",
+  },
+  diffPath: {
+    padding: "8px 12px",
+    fontSize: 12,
+    fontFamily: "monospace",
+    color: "#A1A1AA",
+    borderBottom: "1px solid #27272A",
+    backgroundColor: "#18181B",
+    position: "sticky",
+    top: 0,
+    zIndex: 1,
+  },
+  diffCode: {
+    padding: "4px 0",
+    fontFamily: "monospace",
+    fontSize: 12,
+    lineHeight: 1.6,
+  },
+  hunkHeader: {
+    padding: "4px 12px",
+    color: "#6B7280",
+    backgroundColor: "rgba(59, 130, 246, 0.05)",
+    fontSize: 11,
+    fontStyle: "italic",
+  },
+  diffLine: {
+    padding: "0 12px",
+    whiteSpace: "pre",
+  },
+  diffPlaceholder: {
+    padding: 20,
+    textAlign: "center",
+    color: "#52525B",
+    fontSize: 13,
+  },
+  emptyState: {
+    flex: 1,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    color: "#52525B",
+    fontSize: 14,
+  },
+};

frontend/components/EnvironmentEditor.jsx

@@ -0,0 +1,278 @@
+import React, { useState } from "react";
+import { createPortal } from "react-dom";
+
+/**
+ * EnvironmentEditor — Claude-Code-on-Web parity environment config modal.
+ *
+ * Allows setting name, network access level, and environment variables.
+ */
+export default function EnvironmentEditor({ environment, onSave, onDelete, onClose }) {
+  const [name, setName] = useState(environment?.name || "");
+  const [networkAccess, setNetworkAccess] = useState(environment?.network_access || "limited");
+  const [envVarsText, setEnvVarsText] = useState(
+    environment?.env_vars
+      ? Object.entries(environment.env_vars)
+          .map(([k, v]) => `${k}=${v}`)
+          .join("\n")
+      : ""
+  );
+
+  const handleSave = () => {
+    const envVars = {};
+    envVarsText
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line && line.includes("="))
+      .forEach((line) => {
+        const idx = line.indexOf("=");
+        const key = line.slice(0, idx).trim();
+        const val = line.slice(idx + 1).trim();
+        if (key) envVars[key] = val;
+      });
+
+    onSave({
+      id: environment?.id || null,
+      name: name.trim() || "Default",
+      network_access: networkAccess,
+      env_vars: envVars,
+    });
+  };
+
+  return createPortal(
+    <div style={styles.overlay} onMouseDown={(e) => { if (e.target === e.currentTarget) onClose(); }}>
+      <div style={styles.modal} onMouseDown={(e) => e.stopPropagation()}>
+        <div style={styles.header}>
+          <span style={styles.headerTitle}>
+            {environment?.id ? "Edit Environment" : "New Environment"}
+          </span>
+          <button type="button" style={styles.closeBtn} onClick={onClose}>
+            &times;
+          </button>
+        </div>
+
+        <div style={styles.body}>
+          {/* Name */}
+          <label style={styles.label}>Environment Name</label>
+          <input
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            placeholder="e.g. Development, Staging, Production"
+            style={styles.input}
+          />
+
+          {/* Network Access */}
+          <label style={styles.label}>Network Access</label>
+          <div style={styles.radioGroup}>
+            {[
+              { value: "limited", label: "Limited", desc: "Allowlisted domains only (package managers, APIs)" },
+              { value: "full", label: "Full", desc: "Unrestricted internet access" },
+              { value: "none", label: "None", desc: "Air-gapped — no external network" },
+            ].map((opt) => (
+              <label
+                key={opt.value}
+                style={{
+                  ...styles.radioItem,
+                  borderColor:
+                    networkAccess === opt.value ? "#3B82F6" : "#27272A",
+                  backgroundColor:
+                    networkAccess === opt.value
+                      ? "rgba(59, 130, 246, 0.05)"
+                      : "transparent",
+                }}
+              >
+                <input
+                  type="radio"
+                  name="network"
+                  value={opt.value}
+                  checked={networkAccess === opt.value}
+                  onChange={(e) => setNetworkAccess(e.target.value)}
+                  style={{ display: "none" }}
+                />
+                <div>
+                  <div style={{
+                    fontSize: 13,
+                    fontWeight: 500,
+                    color: networkAccess === opt.value ? "#E4E4E7" : "#A1A1AA",
+                  }}>
+                    {opt.label}
+                  </div>
+                  <div style={{ fontSize: 11, color: "#71717A", marginTop: 2 }}>
+                    {opt.desc}
+                  </div>
+                </div>
+              </label>
+            ))}
+          </div>
+
+          {/* Environment Variables */}
+          <label style={styles.label}>Environment Variables</label>
+          <textarea
+            value={envVarsText}
+            onChange={(e) => setEnvVarsText(e.target.value)}
+            placeholder={"NODE_ENV=development\nDEBUG=true\nAPI_KEY=your-key-here"}
+            rows={6}
+            style={styles.textarea}
+          />
+          <div style={{ fontSize: 10, color: "#52525B", marginTop: 4 }}>
+            One KEY=VALUE per line. Secrets are stored locally.
+          </div>
+        </div>
+
+        <div style={styles.footer}>
+          {onDelete && (
+            <button type="button" style={styles.deleteBtn} onClick={onDelete}>
+              Delete
+            </button>
+          )}
+          <div style={{ flex: 1 }} />
+          <button type="button" style={styles.cancelBtn} onClick={onClose}>
+            Cancel
+          </button>
+          <button type="button" style={styles.saveBtn} onClick={handleSave}>
+            Save
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+const styles = {
+  overlay: {
+    position: "fixed",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: "rgba(0, 0, 0, 0.6)",
+    zIndex: 10000,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  modal: {
+    width: 480,
+    maxHeight: "80vh",
+    backgroundColor: "#131316",
+    border: "1px solid #27272A",
+    borderRadius: 12,
+    display: "flex",
+    flexDirection: "column",
+    overflow: "hidden",
+  },
+  header: {
+    display: "flex",
+    justifyContent: "space-between",
+    alignItems: "center",
+    padding: "14px 16px",
+    borderBottom: "1px solid #27272A",
+    backgroundColor: "#18181B",
+  },
+  headerTitle: {
+    fontSize: 14,
+    fontWeight: 600,
+    color: "#E4E4E7",
+  },
+  closeBtn: {
+    width: 26,
+    height: 26,
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "transparent",
+    color: "#A1A1AA",
+    fontSize: 16,
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  body: {
+    padding: "16px",
+    overflowY: "auto",
+    flex: 1,
+  },
+  label: {
+    display: "block",
+    fontSize: 12,
+    fontWeight: 600,
+    color: "#A1A1AA",
+    marginBottom: 6,
+    marginTop: 14,
+  },
+  input: {
+    width: "100%",
+    padding: "8px 10px",
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "#18181B",
+    color: "#E4E4E7",
+    fontSize: 13,
+    outline: "none",
+    boxSizing: "border-box",
+  },
+  radioGroup: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 6,
+  },
+  radioItem: {
+    display: "flex",
+    alignItems: "flex-start",
+    gap: 10,
+    padding: "8px 10px",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    cursor: "pointer",
+    transition: "border-color 0.15s, background-color 0.15s",
+  },
+  textarea: {
+    width: "100%",
+    padding: "8px 10px",
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "#18181B",
+    color: "#E4E4E7",
+    fontSize: 12,
+    fontFamily: "monospace",
+    outline: "none",
+    resize: "vertical",
+    boxSizing: "border-box",
+  },
+  footer: {
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "12px 16px",
+    borderTop: "1px solid #27272A",
+  },
+  cancelBtn: {
+    padding: "6px 14px",
+    borderRadius: 6,
+    border: "1px solid #3F3F46",
+    background: "transparent",
+    color: "#A1A1AA",
+    fontSize: 12,
+    cursor: "pointer",
+  },
+  saveBtn: {
+    padding: "6px 14px",
+    borderRadius: 6,
+    border: "none",
+    background: "#3B82F6",
+    color: "#fff",
+    fontSize: 12,
+    fontWeight: 600,
+    cursor: "pointer",
+  },
+  deleteBtn: {
+    padding: "6px 14px",
+    borderRadius: 6,
+    border: "1px solid rgba(239, 68, 68, 0.3)",
+    background: "transparent",
+    color: "#EF4444",
+    fontSize: 12,
+    cursor: "pointer",
+  },
+};

frontend/components/EnvironmentSelector.jsx

@@ -0,0 +1,199 @@
+import React, { useEffect, useState } from "react";
+import EnvironmentEditor from "./EnvironmentEditor.jsx";
+
+/**
+ * EnvironmentSelector — Claude-Code-on-Web parity environment dropdown.
+ *
+ * Shows current environment name + gear icon. Gear opens the editor modal.
+ * Fetches environments from /api/environments.
+ */
+export default function EnvironmentSelector({ activeEnvId, onEnvChange }) {
+  const [envs, setEnvs] = useState([]);
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [editingEnv, setEditingEnv] = useState(null);
+
+  const fetchEnvs = async () => {
+    try {
+      const res = await fetch("/api/environments", { cache: "no-cache" });
+      if (!res.ok) return;
+      const data = await res.json();
+      setEnvs(data.environments || []);
+    } catch (err) {
+      console.warn("Failed to fetch environments:", err);
+    }
+  };
+
+  useEffect(() => {
+    fetchEnvs();
+  }, []);
+
+  const activeEnv =
+    envs.find((e) => e.id === activeEnvId) || envs[0] || { name: "Default", id: "default" };
+
+  const handleSave = async (config) => {
+    try {
+      const method = config.id ? "PUT" : "POST";
+      const url = config.id ? `/api/environments/${config.id}` : "/api/environments";
+      await fetch(url, {
+        method,
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(config),
+      });
+      await fetchEnvs();
+      setEditorOpen(false);
+      setEditingEnv(null);
+    } catch (err) {
+      console.warn("Failed to save environment:", err);
+    }
+  };
+
+  const handleDelete = async (envId) => {
+    try {
+      await fetch(`/api/environments/${envId}`, { method: "DELETE" });
+      await fetchEnvs();
+      if (activeEnvId === envId) {
+        onEnvChange?.(null);
+      }
+    } catch (err) {
+      console.warn("Failed to delete environment:", err);
+    }
+  };
+
+  return (
+    <div style={styles.container}>
+      <div style={styles.label}>ENVIRONMENT</div>
+      <div style={styles.row}>
+        <div style={styles.envCard}>
+          {/* Env selector */}
+          <select
+            value={activeEnv.id || "default"}
+            onChange={(e) => onEnvChange?.(e.target.value)}
+            style={styles.select}
+          >
+            {envs.map((env) => (
+              <option key={env.id} value={env.id}>
+                {env.name}
+              </option>
+            ))}
+          </select>
+
+          {/* Network badge */}
+          <span style={{
+            ...styles.networkBadge,
+            color: activeEnv.network_access === "full"
+              ? "#10B981"
+              : activeEnv.network_access === "none"
+              ? "#EF4444"
+              : "#F59E0B",
+          }}>
+            {activeEnv.network_access || "limited"}
+          </span>
+        </div>
+
+        {/* Gear icon */}
+        <button
+          type="button"
+          style={styles.gearBtn}
+          onClick={() => {
+            setEditingEnv(activeEnv);
+            setEditorOpen(true);
+          }}
+          title="Configure environment"
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <circle cx="12" cy="12" r="3" />
+            <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z" />
+          </svg>
+        </button>
+
+        {/* Add new */}
+        <button
+          type="button"
+          style={styles.gearBtn}
+          onClick={() => {
+            setEditingEnv(null);
+            setEditorOpen(true);
+          }}
+          title="Add environment"
+        >
+          +
+        </button>
+      </div>
+
+      {/* Editor modal */}
+      {editorOpen && (
+        <EnvironmentEditor
+          environment={editingEnv}
+          onSave={handleSave}
+          onDelete={editingEnv?.id ? () => handleDelete(editingEnv.id) : null}
+          onClose={() => {
+            setEditorOpen(false);
+            setEditingEnv(null);
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+const styles = {
+  container: {
+    padding: "10px 14px",
+  },
+  label: {
+    fontSize: 10,
+    fontWeight: 700,
+    letterSpacing: "0.08em",
+    color: "#71717A",
+    textTransform: "uppercase",
+    marginBottom: 6,
+  },
+  row: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+  },
+  envCard: {
+    flex: 1,
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "4px 8px",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    backgroundColor: "#18181B",
+    minWidth: 0,
+  },
+  select: {
+    flex: 1,
+    background: "transparent",
+    border: "none",
+    color: "#E4E4E7",
+    fontSize: 12,
+    fontWeight: 500,
+    outline: "none",
+    cursor: "pointer",
+    minWidth: 0,
+  },
+  networkBadge: {
+    fontSize: 9,
+    fontWeight: 600,
+    textTransform: "uppercase",
+    letterSpacing: "0.04em",
+    flexShrink: 0,
+  },
+  gearBtn: {
+    width: 28,
+    height: 28,
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    background: "transparent",
+    color: "#71717A",
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    fontSize: 14,
+    flexShrink: 0,
+  },
+};

frontend/components/FileTree.jsx

@@ -0,0 +1,307 @@
+import React, { useState, useEffect } from "react";
+
+/**
+ * Simple recursive file tree viewer with refresh support
+ * Fetches tree data directly using the API.
+ */
+export default function FileTree({ repo, refreshTrigger, branch }) {
+  const [tree, setTree] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [isSwitchingBranch, setIsSwitchingBranch] = useState(false);
+  const [error, setError] = useState(null);
+  const [localRefresh, setLocalRefresh] = useState(0);
+
+  useEffect(() => {
+    if (!repo) return;
+
+    // Determine if this is a branch switch (we already have data)
+    const hasExistingData = tree.length > 0;
+    if (hasExistingData) {
+      setIsSwitchingBranch(true);
+    } else {
+      setLoading(true);
+    }
+    setError(null);
+
+    // Construct headers manually
+    let headers = {};
+    try {
+      const token = localStorage.getItem("github_token");
+      if (token) {
+        headers = { Authorization: `Bearer ${token}` };
+      }
+    } catch (e) {
+      console.warn("Unable to read github_token", e);
+    }
+
+    // Add cache busting + selected branch ref
+    const refParam = branch ? `&ref=${encodeURIComponent(branch)}` : "";
+    const cacheBuster = `?_t=${Date.now()}${refParam}`;
+
+    let cancelled = false;
+
+    fetch(`/api/repos/${repo.owner}/${repo.name}/tree${cacheBuster}`, { headers })
+      .then(async (res) => {
+        if (!res.ok) {
+            const errData = await res.json().catch(() => ({}));
+            throw new Error(errData.detail || "Failed to load files");
+        }
+        return res.json();
+      })
+      .then((data) => {
+        if (cancelled) return;
+        if (data.files && Array.isArray(data.files)) {
+          setTree(buildTree(data.files));
+          setError(null);
+        } else {
+          setError("No files found in repository");
+        }
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError(err.message);
+        console.error("FileTree error:", err);
+      })
+      .finally(() => {
+        if (cancelled) return;
+        setIsSwitchingBranch(false);
+        setLoading(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [repo, branch, refreshTrigger, localRefresh]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const handleRefresh = () => {
+    setLocalRefresh(prev => prev + 1);
+  };
+
+  // Theme matching parent component
+  const theme = {
+    border: "#27272A",
+    textPrimary: "#EDEDED",
+    textSecondary: "#A1A1AA",
+    accent: "#D95C3D",
+    warningText: "#F59E0B",
+    warningBg: "rgba(245, 158, 11, 0.1)",
+    warningBorder: "rgba(245, 158, 11, 0.2)",
+  };
+
+  const styles = {
+    header: {
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "space-between",
+      padding: "8px 20px 8px 10px",
+      marginBottom: "8px",
+      borderBottom: `1px solid ${theme.border}`,
+    },
+    headerTitle: {
+      fontSize: "12px",
+      fontWeight: "600",
+      color: theme.textSecondary,
+      textTransform: "uppercase",
+      letterSpacing: "0.5px",
+    },
+    refreshButton: {
+      backgroundColor: "transparent",
+      border: `1px solid ${theme.border}`,
+      color: theme.textSecondary,
+      padding: "4px 8px",
+      borderRadius: "4px",
+      fontSize: "11px",
+      cursor: loading ? "not-allowed" : "pointer",
+      display: "flex",
+      alignItems: "center",
+      gap: "4px",
+      transition: "all 0.2s",
+      opacity: loading ? 0.5 : 1,
+    },
+    switchingBar: {
+      padding: "6px 20px",
+      fontSize: "11px",
+      color: theme.textSecondary,
+      backgroundColor: "rgba(59, 130, 246, 0.06)",
+      borderBottom: `1px solid ${theme.border}`,
+    },
+    loadingText: {
+      padding: "0 20px",
+      color: theme.textSecondary,
+      fontSize: "13px",
+    },
+    errorBox: {
+      padding: "12px 20px",
+      color: theme.warningText,
+      fontSize: "12px",
+      backgroundColor: theme.warningBg,
+      border: `1px solid ${theme.warningBorder}`,
+      borderRadius: "6px",
+      margin: "0 10px",
+    },
+    emptyText: {
+      padding: "0 20px",
+      color: theme.textSecondary,
+      fontSize: "13px",
+    },
+    treeContainer: {
+      fontSize: "13px",
+      color: theme.textSecondary,
+      padding: "0 10px 20px 10px",
+    },
+  };
+
+  return (
+    <div>
+      {/* Header with Refresh Button */}
+      <div style={styles.header}>
+        <span style={styles.headerTitle}>Files</span>
+        <button
+          type="button"
+          style={styles.refreshButton}
+          onClick={handleRefresh}
+          disabled={loading}
+          onMouseOver={(e) => {
+            if (!loading) {
+              e.currentTarget.style.backgroundColor = "rgba(255, 255, 255, 0.05)";
+            }
+          }}
+          onMouseOut={(e) => {
+            e.currentTarget.style.backgroundColor = "transparent";
+          }}
+        >
+          <svg
+            width="12"
+            height="12"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            style={{
+              transform: loading ? "rotate(360deg)" : "rotate(0deg)",
+              transition: "transform 0.6s ease",
+            }}
+          >
+            <path d="M21.5 2v6h-6M2.5 22v-6h6M2 11.5a10 10 0 0 1 18.8-4.3M22 12.5a10 10 0 0 1-18.8 4.2" />
+          </svg>
+          {loading ? "..." : "Refresh"}
+        </button>
+      </div>
+
+      {/* Branch switch indicator (shown above existing tree, doesn't clear it) */}
+      {isSwitchingBranch && (
+        <div style={styles.switchingBar}>Loading branch...</div>
+      )}
+
+      {/* Content */}
+      {loading && tree.length === 0 && (
+        <div style={styles.loadingText}>Loading files...</div>
+      )}
+
+      {!loading && !isSwitchingBranch && error && (
+        <div style={styles.errorBox}>{error}</div>
+      )}
+
+      {!loading && !isSwitchingBranch && !error && tree.length === 0 && (
+        <div style={styles.emptyText}>No files found</div>
+      )}
+
+      {tree.length > 0 && (
+        <div style={{
+          ...styles.treeContainer,
+          opacity: isSwitchingBranch ? 0.5 : 1,
+          transition: "opacity 0.15s ease",
+        }}>
+          {tree.map((node) => (
+            <TreeNode key={node.path} node={node} level={0} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Recursive Node Component
+function TreeNode({ node, level }) {
+  const [expanded, setExpanded] = useState(false);
+  const isFolder = node.children && node.children.length > 0;
+  
+  const icon = isFolder ? (expanded ? "📂" : "📁") : "📄";
+
+  return (
+    <div>
+      <div 
+        onClick={() => isFolder && setExpanded(!expanded)}
+        style={{ 
+          padding: "4px 0", 
+          paddingLeft: `${level * 12}px`,
+          cursor: isFolder ? "pointer" : "default",
+          display: "flex",
+          alignItems: "center",
+          gap: "6px",
+          color: isFolder ? "#EDEDED" : "#A1A1AA",
+          whiteSpace: "nowrap"
+        }}
+      >
+        <span style={{ fontSize: "14px", opacity: 0.7 }}>{icon}</span>
+        <span>{node.name}</span>
+      </div>
+      
+      {isFolder && expanded && (
+        <div>
+          {node.children.map(child => (
+            <TreeNode key={child.path} node={child} level={level + 1} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Helper to build tree structure from flat file list
+function buildTree(files) {
+  const root = [];
+  
+  files.forEach(file => {
+    const parts = file.path.split('/');
+    let currentLevel = root;
+    let currentPath = "";
+
+    parts.forEach((part, idx) => {
+      currentPath = currentPath ? `${currentPath}/${part}` : part;
+      
+      // Check if node exists at this level
+      let existingNode = currentLevel.find(n => n.name === part);
+      
+      if (!existingNode) {
+        const newNode = {
+          name: part,
+          path: currentPath,
+          type: idx === parts.length - 1 ? file.type : 'tree',
+          children: []
+        };
+        currentLevel.push(newNode);
+        existingNode = newNode;
+      }
+      
+      if (idx < parts.length - 1) {
+        currentLevel = existingNode.children;
+      }
+    });
+  });
+
+  // Sort folders first, then files
+  const sortNodes = (nodes) => {
+    nodes.sort((a, b) => {
+      const aIsFolder = a.children.length > 0;
+      const bIsFolder = b.children.length > 0;
+      if (aIsFolder && !bIsFolder) return -1;
+      if (!aIsFolder && bIsFolder) return 1;
+      return a.name.localeCompare(b.name);
+    });
+    nodes.forEach(n => {
+      if (n.children.length > 0) sortNodes(n.children);
+    });
+  };
+
+  sortNodes(root);
+  return root;
+}

frontend/components/FlowViewer.jsx

@@ -0,0 +1,659 @@
+import React, { useEffect, useState, useCallback, useRef } from "react";
+import ReactFlow, { Background, Controls, MiniMap } from "reactflow";
+import "reactflow/dist/style.css";
+
+/* ------------------------------------------------------------------ */
+/*  Node type → colour mapping                                        */
+/* ------------------------------------------------------------------ */
+const NODE_COLOURS = {
+  agent:      { border: "#ff7a3c", bg: "#20141a" },
+  router:     { border: "#6c8cff", bg: "#141828" },
+  tool:       { border: "#3a3b4d", bg: "#141821" },
+  tool_group: { border: "#3a3b4d", bg: "#141821" },
+  user:       { border: "#4caf88", bg: "#14211a" },
+  output:     { border: "#9c6cff", bg: "#1a1428" },
+};
+const DEFAULT_COLOUR = { border: "#3a3b4d", bg: "#141821" };
+
+function colourFor(type) {
+  return NODE_COLOURS[type] || DEFAULT_COLOUR;
+}
+
+const STYLE_COLOURS = {
+  single_task: "#6c8cff",
+  react_loop: "#ff7a3c",
+  crew_pipeline: "#4caf88",
+};
+
+const STYLE_LABELS = {
+  single_task: "Dispatch",
+  react_loop: "ReAct Loop",
+  crew_pipeline: "Pipeline",
+};
+
+/* ------------------------------------------------------------------ */
+/*  TopologyCard — single clickable topology card                      */
+/* ------------------------------------------------------------------ */
+function TopologyCard({ topology, isActive, onClick }) {
+  const styleColor = STYLE_COLOURS[topology.execution_style] || "#9a9bb0";
+  const agentCount = topology.agents_used?.length || 0;
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      style={{
+        ...cardStyles.card,
+        borderColor: isActive ? styleColor : "#1e1f30",
+        backgroundColor: isActive ? `${styleColor}0D` : "#0c0d14",
+      }}
+    >
+      <div style={cardStyles.cardTop}>
+        <span style={cardStyles.icon}>{topology.icon}</span>
+        <span
+          style={{
+            ...cardStyles.styleBadge,
+            color: styleColor,
+            borderColor: `${styleColor}40`,
+          }}
+        >
+          {STYLE_LABELS[topology.execution_style] || topology.execution_style}
+        </span>
+      </div>
+      <div
+        style={{
+          ...cardStyles.name,
+          color: isActive ? "#f5f5f7" : "#c3c5dd",
+        }}
+      >
+        {topology.name}
+      </div>
+      <div style={cardStyles.desc}>{topology.description}</div>
+      <div style={cardStyles.agentCount}>
+        {agentCount} agent{agentCount !== 1 ? "s" : ""}
+      </div>
+    </button>
+  );
+}
+
+const cardStyles = {
+  card: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 4,
+    padding: "10px 12px",
+    borderRadius: 8,
+    border: "1px solid #1e1f30",
+    cursor: "pointer",
+    textAlign: "left",
+    minWidth: 170,
+    maxWidth: 200,
+    flexShrink: 0,
+    transition: "border-color 0.2s, background-color 0.2s",
+  },
+  cardTop: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 6,
+  },
+  icon: {
+    fontSize: 18,
+  },
+  styleBadge: {
+    fontSize: 9,
+    fontWeight: 700,
+    textTransform: "uppercase",
+    letterSpacing: "0.05em",
+    padding: "1px 6px",
+    borderRadius: 4,
+    border: "1px solid",
+  },
+  name: {
+    fontSize: 12,
+    fontWeight: 600,
+    lineHeight: 1.3,
+  },
+  desc: {
+    fontSize: 10,
+    color: "#71717A",
+    lineHeight: 1.3,
+    overflow: "hidden",
+    display: "-webkit-box",
+    WebkitLineClamp: 2,
+    WebkitBoxOrient: "vertical",
+  },
+  agentCount: {
+    fontSize: 9,
+    color: "#52525B",
+    fontWeight: 600,
+    marginTop: 2,
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/*  TopologyPanel — card grid grouped by category                      */
+/* ------------------------------------------------------------------ */
+function TopologyPanel({
+  topologies,
+  activeTopology,
+  autoMode,
+  autoResult,
+  onSelect,
+  onToggleAuto,
+}) {
+  const systems = topologies.filter((t) => t.category === "system");
+  const pipelines = topologies.filter((t) => t.category === "pipeline");
+
+  return (
+    <div style={panelStyles.root}>
+      {/* Auto-detect toggle */}
+      <div style={panelStyles.autoRow}>
+        <button
+          type="button"
+          onClick={onToggleAuto}
+          style={{
+            ...panelStyles.autoBtn,
+            borderColor: autoMode ? "#ff7a3c" : "#27272A",
+            color: autoMode ? "#ff7a3c" : "#71717A",
+            backgroundColor: autoMode ? "rgba(255, 122, 60, 0.06)" : "transparent",
+          }}
+        >
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <circle cx="12" cy="12" r="10" />
+            <path d="M12 6v6l4 2" />
+          </svg>
+          Auto
+        </button>
+        {autoMode && autoResult && (
+          <span style={panelStyles.autoHint}>
+            Detected: {autoResult.icon} {autoResult.name}
+            {autoResult.confidence != null && (
+              <span style={{ opacity: 0.6 }}>
+                {" "}({Math.round(autoResult.confidence * 100)}%)
+              </span>
+            )}
+          </span>
+        )}
+      </div>
+
+      {/* System architectures */}
+      <div style={panelStyles.section}>
+        <div style={panelStyles.sectionLabel}>System Architectures</div>
+        <div style={panelStyles.cardRow}>
+          {systems.map((t) => (
+            <TopologyCard
+              key={t.id}
+              topology={t}
+              isActive={activeTopology === t.id}
+              onClick={() => onSelect(t.id)}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* Task pipelines */}
+      <div style={panelStyles.section}>
+        <div style={panelStyles.sectionLabel}>Task Pipelines</div>
+        <div style={panelStyles.cardRow}>
+          {pipelines.map((t) => (
+            <TopologyCard
+              key={t.id}
+              topology={t}
+              isActive={activeTopology === t.id}
+              onClick={() => onSelect(t.id)}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+const panelStyles = {
+  root: {
+    padding: "8px 16px 12px",
+    borderBottom: "1px solid #1e1f30",
+    backgroundColor: "#08090e",
+  },
+  autoRow: {
+    display: "flex",
+    alignItems: "center",
+    gap: 10,
+    marginBottom: 10,
+  },
+  autoBtn: {
+    display: "flex",
+    alignItems: "center",
+    gap: 5,
+    padding: "4px 10px",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    background: "transparent",
+    fontSize: 11,
+    fontWeight: 600,
+    cursor: "pointer",
+    transition: "border-color 0.15s, color 0.15s",
+  },
+  autoHint: {
+    fontSize: 11,
+    color: "#9a9bb0",
+  },
+  section: {
+    marginBottom: 8,
+  },
+  sectionLabel: {
+    fontSize: 9,
+    fontWeight: 700,
+    textTransform: "uppercase",
+    letterSpacing: "0.08em",
+    color: "#52525B",
+    marginBottom: 6,
+  },
+  cardRow: {
+    display: "flex",
+    gap: 8,
+    overflowX: "auto",
+    scrollbarWidth: "none",
+    paddingBottom: 2,
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/*  Main FlowViewer component                                          */
+/* ------------------------------------------------------------------ */
+export default function FlowViewer() {
+  const [nodes, setNodes] = useState([]);
+  const [edges, setEdges] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  // Topology state
+  const [topologies, setTopologies] = useState([]);
+  const [activeTopology, setActiveTopology] = useState(null);
+  const [topologyMeta, setTopologyMeta] = useState(null);
+
+  // Auto-detection state
+  const [autoMode, setAutoMode] = useState(false);
+  const [autoResult, setAutoResult] = useState(null);
+  const [autoTestMessage, setAutoTestMessage] = useState("");
+
+  const initialLoadDone = useRef(false);
+
+  /* ---------- Load topology list on mount ---------- */
+  useEffect(() => {
+    (async () => {
+      try {
+        const [topoRes, prefRes] = await Promise.all([
+          fetch("/api/flow/topologies"),
+          fetch("/api/settings/topology"),
+        ]);
+        if (topoRes.ok) {
+          const data = await topoRes.json();
+          setTopologies(data);
+        }
+        if (prefRes.ok) {
+          const { topology } = await prefRes.json();
+          if (topology) {
+            setActiveTopology(topology);
+          }
+        }
+      } catch (e) {
+        console.warn("Failed to load topologies:", e);
+      }
+      initialLoadDone.current = true;
+    })();
+  }, []);
+
+  /* ---------- Load graph when topology changes ---------- */
+  const loadGraph = useCallback(async (topologyId) => {
+    setLoading(true);
+    setError("");
+    try {
+      const url = topologyId
+        ? `/api/flow/current?topology=${encodeURIComponent(topologyId)}`
+        : "/api/flow/current";
+      const res = await fetch(url);
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || "Failed to load flow");
+
+      // Track topology metadata from response
+      if (data.topology_id) {
+        setTopologyMeta({
+          id: data.topology_id,
+          name: data.topology_name,
+          icon: data.topology_icon,
+          description: data.topology_description,
+          execution_style: data.execution_style,
+          agents_used: topologies.find((t) => t.id === data.topology_id)?.agents_used || [],
+        });
+      }
+
+      // Build ReactFlow nodes
+      const RFnodes = data.nodes.map((n, i) => {
+        const nodeType = n.type || "default";
+        const colour = colourFor(nodeType);
+        const d = n.data || {};
+
+        const label = d.label || n.label || n.id;
+        const description = d.description || n.description || "";
+        const model = d.model;
+        const mode = d.mode;
+
+        const pos = n.position || {
+          x: 50 + (i % 3) * 250,
+          y: 50 + Math.floor(i / 3) * 180,
+        };
+
+        return {
+          id: n.id,
+          data: {
+            label: (
+              <div style={{ textAlign: "center" }}>
+                <div style={{ fontWeight: 600, marginBottom: 2 }}>
+                  {label}
+                </div>
+                {model && (
+                  <div style={{ fontSize: 9, color: "#6c8cff", marginBottom: 2, fontFamily: "monospace" }}>
+                    {model}
+                  </div>
+                )}
+                {mode && (
+                  <div
+                    style={{
+                      fontSize: 9,
+                      color: mode === "read-only" ? "#4caf88" : mode === "git-ops" ? "#9c6cff" : "#ff7a3c",
+                      marginBottom: 2,
+                    }}
+                  >
+                    {mode}
+                  </div>
+                )}
+                <div style={{ fontSize: 10, color: "#9a9bb0", maxWidth: 160, lineHeight: 1.3 }}>
+                  {description}
+                </div>
+              </div>
+            ),
+          },
+          position: pos,
+          type: "default",
+          style: {
+            borderRadius: 12,
+            padding: "12px 16px",
+            border: `2px solid ${colour.border}`,
+            background: colour.bg,
+            color: "#f5f5f7",
+            fontSize: 13,
+            minWidth: 180,
+            maxWidth: 220,
+          },
+        };
+      });
+
+      // Build ReactFlow edges
+      const RFedges = data.edges.map((e) => ({
+        id: e.id,
+        source: e.source,
+        target: e.target,
+        label: e.label,
+        animated: e.animated !== false,
+        style: { stroke: "#7a7b8e", strokeWidth: 2 },
+        labelStyle: { fill: "#c3c5dd", fontSize: 11, fontWeight: 500 },
+        labelBgStyle: { fill: "#101117", fillOpacity: 0.9 },
+        ...(e.type === "bidirectional" && {
+          markerEnd: { type: "arrowclosed", color: "#7a7b8e" },
+          markerStart: { type: "arrowclosed", color: "#7a7b8e" },
+          animated: false,
+          style: { stroke: "#555670", strokeWidth: 1.5, strokeDasharray: "5 5" },
+        }),
+      }));
+
+      setNodes(RFnodes);
+      setEdges(RFedges);
+    } catch (e) {
+      console.error(e);
+      setError(e.message);
+    } finally {
+      setLoading(false);
+    }
+  }, [topologies]);
+
+  // Load graph whenever activeTopology changes
+  useEffect(() => {
+    loadGraph(activeTopology);
+  }, [activeTopology, loadGraph]);
+
+  /* ---------- Topology selection handler ---------- */
+  const handleTopologyChange = useCallback(
+    async (newTopologyId) => {
+      setActiveTopology(newTopologyId);
+      setAutoMode(false); // Manual selection disables auto
+      // Persist preference (fire-and-forget)
+      try {
+        await fetch("/api/settings/topology", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ topology: newTopologyId }),
+        });
+      } catch (e) {
+        console.warn("Failed to save topology preference:", e);
+      }
+    },
+    []
+  );
+
+  /* ---------- Auto-detection ---------- */
+  const handleToggleAuto = useCallback(() => {
+    setAutoMode((prev) => !prev);
+    if (!autoMode) {
+      setAutoResult(null);
+    }
+  }, [autoMode]);
+
+  const handleAutoClassify = useCallback(
+    async (message) => {
+      if (!message.trim()) return;
+      try {
+        const res = await fetch("/api/flow/classify", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ message }),
+        });
+        if (!res.ok) return;
+        const data = await res.json();
+        const recommendedId = data.recommended_topology;
+        const topo = topologies.find((t) => t.id === recommendedId);
+        setAutoResult({
+          id: recommendedId,
+          name: topo?.name || recommendedId,
+          icon: topo?.icon || "",
+          confidence: data.confidence,
+          alternatives: data.alternatives || [],
+        });
+        setActiveTopology(recommendedId);
+      } catch (e) {
+        console.warn("Auto-classify failed:", e);
+      }
+    },
+    [topologies]
+  );
+
+  // Debounced auto-classify when test message changes
+  useEffect(() => {
+    if (!autoMode || !autoTestMessage.trim()) return;
+    const t = setTimeout(() => handleAutoClassify(autoTestMessage), 500);
+    return () => clearTimeout(t);
+  }, [autoTestMessage, autoMode, handleAutoClassify]);
+
+  /* ---------- Render ---------- */
+  const activeStyleColor = STYLE_COLOURS[topologyMeta?.execution_style] || "#9a9bb0";
+
+  return (
+    <div className="flow-root">
+      {/* Header */}
+      <div className="flow-header">
+        <div>
+          <h1>Agent Workflow</h1>
+          <p>
+            Visual view of the multi-agent system that GitPilot uses to
+            plan and apply changes to your repositories.
+          </p>
+        </div>
+        <div style={{ display: "flex", alignItems: "center", gap: 10 }}>
+          {topologyMeta && (
+            <div style={{ display: "flex", alignItems: "center", gap: 8, fontSize: 12, color: "#9a9bb0" }}>
+              <span style={{ fontSize: 18 }}>{topologyMeta.icon}</span>
+              <span style={{ fontWeight: 600, color: "#e0e1f0" }}>{topologyMeta.name}</span>
+              <span
+                style={{
+                  padding: "2px 8px",
+                  borderRadius: 6,
+                  border: `1px solid ${activeStyleColor}40`,
+                  color: activeStyleColor,
+                  fontSize: 10,
+                  fontWeight: 700,
+                  textTransform: "uppercase",
+                }}
+              >
+                {STYLE_LABELS[topologyMeta.execution_style] || topologyMeta.execution_style}
+              </span>
+              <span>{topologyMeta.agents_used?.length || 0} agents</span>
+            </div>
+          )}
+          {loading && <span style={{ fontSize: 11, color: "#6c8cff" }}>Loading...</span>}
+        </div>
+      </div>
+
+      {/* Topology selector panel */}
+      {topologies.length > 0 && (
+        <TopologyPanel
+          topologies={topologies}
+          activeTopology={activeTopology}
+          autoMode={autoMode}
+          autoResult={autoResult}
+          onSelect={handleTopologyChange}
+          onToggleAuto={handleToggleAuto}
+        />
+      )}
+
+      {/* Auto-detection test input (shown when auto mode is on) */}
+      {autoMode && (
+        <div style={autoInputStyles.wrap}>
+          <div style={autoInputStyles.label}>
+            Test auto-detection: type a task description to see which topology is recommended
+          </div>
+          <input
+            type="text"
+            placeholder='e.g. "Fix the 403 error in auth middleware" or "Add a REST endpoint for users"'
+            value={autoTestMessage}
+            onChange={(e) => setAutoTestMessage(e.target.value)}
+            style={autoInputStyles.input}
+          />
+          {autoResult && autoResult.alternatives?.length > 0 && (
+            <div style={autoInputStyles.altRow}>
+              <span style={{ color: "#52525B", fontSize: 10 }}>Alternatives:</span>
+              {autoResult.alternatives.slice(0, 3).map((alt) => {
+                const altTopo = topologies.find((t) => t.id === alt.id);
+                return (
+                  <button
+                    key={alt.id}
+                    type="button"
+                    style={autoInputStyles.altBtn}
+                    onClick={() => handleTopologyChange(alt.id)}
+                  >
+                    {altTopo?.icon} {altTopo?.name || alt.id}
+                    <span style={{ opacity: 0.5 }}>
+                      {alt.confidence != null ? ` ${Math.round(alt.confidence * 100)}%` : ""}
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Description bar */}
+      {topologyMeta && topologyMeta.description && !autoMode && (
+        <div
+          style={{
+            padding: "8px 16px",
+            fontSize: 12,
+            color: "#9a9bb0",
+            background: "#0a0b12",
+            borderBottom: "1px solid #1e1f30",
+          }}
+        >
+          {topologyMeta.icon} {topologyMeta.description}
+        </div>
+      )}
+
+      {/* ReactFlow canvas */}
+      <div className="flow-canvas">
+        {error ? (
+          <div className="flow-error">
+            <div className="error-icon">!!!</div>
+            <div className="error-text">{error}</div>
+          </div>
+        ) : (
+          <ReactFlow nodes={nodes} edges={edges} fitView>
+            <Background color="#272832" gap={16} />
+            <MiniMap
+              nodeColor={(node) => {
+                const border = node.style?.border || "";
+                if (border.includes("#ff7a3c")) return "#ff7a3c";
+                if (border.includes("#6c8cff")) return "#6c8cff";
+                if (border.includes("#4caf88")) return "#4caf88";
+                if (border.includes("#9c6cff")) return "#9c6cff";
+                return "#3a3b4d";
+              }}
+              maskColor="rgba(0, 0, 0, 0.6)"
+            />
+            <Controls />
+          </ReactFlow>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const autoInputStyles = {
+  wrap: {
+    padding: "8px 16px 10px",
+    borderBottom: "1px solid #1e1f30",
+    backgroundColor: "#0c0d14",
+  },
+  label: {
+    fontSize: 10,
+    color: "#71717A",
+    marginBottom: 6,
+  },
+  input: {
+    width: "100%",
+    padding: "8px 12px",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    background: "#08090e",
+    color: "#e0e1f0",
+    fontSize: 12,
+    fontFamily: "monospace",
+    outline: "none",
+    boxSizing: "border-box",
+  },
+  altRow: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    marginTop: 6,
+    flexWrap: "wrap",
+  },
+  altBtn: {
+    padding: "2px 8px",
+    borderRadius: 4,
+    border: "1px solid #27272A",
+    background: "transparent",
+    color: "#9a9bb0",
+    fontSize: 10,
+    cursor: "pointer",
+  },
+};

frontend/components/Footer.jsx

@@ -0,0 +1,48 @@
+import React from "react";
+
+export default function Footer() {
+  return (
+    <footer className="gp-footer">
+      <div className="gp-footer-left">
+        <a
+          href="https://github.com/ruslanmv/gitpilot"
+          target="_blank"
+          rel="noopener noreferrer"
+          style={{
+            color: "inherit",
+            textDecoration: "none",
+            display: "flex",
+            alignItems: "center",
+            gap: "6px",
+            transition: "color 0.2s ease",
+          }}
+          onMouseOver={(e) => {
+            e.currentTarget.style.color = "#ff7a3c";
+          }}
+          onMouseOut={(e) => {
+            e.currentTarget.style.color = "#c3c5dd";
+          }}
+        >
+          ⭐ Star our GitHub project
+        </a>
+      </div>
+      <div className="gp-footer-right">
+        <span>© 2025 GitPilot</span>
+        <a
+          href="https://github.com/ruslanmv/gitpilot"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Docs
+        </a>
+        <a
+          href="https://github.com/ruslanmv/gitpilot"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          GitHub
+        </a>
+      </div>
+    </footer>
+  );
+}

frontend/components/LlmSettings.jsx

@@ -0,0 +1,775 @@
+import React, { useEffect, useState } from "react";
+import { testProvider } from "../utils/api";
+
+const PROVIDERS = ["ollabridge", "openai", "claude", "watsonx", "ollama"];
+
+const PROVIDER_LABELS = {
+  ollabridge: "OllaBridge Cloud",
+  openai: "OpenAI",
+  claude: "Claude",
+  watsonx: "Watsonx",
+  ollama: "Ollama",
+};
+
+const AUTH_MODES = [
+  { id: "device", label: "Device Pairing", icon: "\uD83D\uDCF1" },
+  { id: "apikey", label: "API Key", icon: "\uD83D\uDD11" },
+  { id: "local", label: "Local Trust", icon: "\uD83C\uDFE0" },
+];
+
+export default function LlmSettings() {
+  const [settings, setSettings] = useState(null);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+  const [savedMsg, setSavedMsg] = useState("");
+
+  const [modelsByProvider, setModelsByProvider] = useState({});
+  const [modelsError, setModelsError] = useState("");
+  const [loadingModelsFor, setLoadingModelsFor] = useState("");
+
+  const [testResult, setTestResult] = useState(null);
+  const [testing, setTesting] = useState(false);
+
+  // OllaBridge pairing state
+  const [authMode, setAuthMode] = useState("local");
+  const [pairCode, setPairCode] = useState("");
+  const [pairing, setPairing] = useState(false);
+  const [pairResult, setPairResult] = useState(null);
+
+  useEffect(() => {
+    const load = async () => {
+      try {
+        const res = await fetch("/api/settings");
+        const data = await res.json();
+        if (!res.ok) throw new Error(data.error || "Failed to load settings");
+        setSettings(data);
+      } catch (e) {
+        console.error(e);
+        setError(e.message);
+      }
+    };
+    load();
+  }, []);
+
+  const updateField = (section, field, value) => {
+    setSettings((prev) => ({
+      ...prev,
+      [section]: {
+        ...prev[section],
+        [field]: value,
+      },
+    }));
+  };
+
+  const handleSave = async () => {
+    setSaving(true);
+    setError("");
+    setSavedMsg("");
+    try {
+      const res = await fetch("/api/settings/llm", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(settings),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || "Failed to save settings");
+      setSettings(data);
+      setSavedMsg("Settings saved successfully!");
+      setTimeout(() => setSavedMsg(""), 3000);
+    } catch (e) {
+      console.error(e);
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const loadModelsForProvider = async (provider) => {
+    setModelsError("");
+    setLoadingModelsFor(provider);
+    try {
+      const res = await fetch(`/api/settings/models?provider=${provider}`);
+      const data = await res.json();
+      if (!res.ok || data.error) {
+        throw new Error(data.error || "Failed to load models");
+      }
+      setModelsByProvider((prev) => ({
+        ...prev,
+        [provider]: data.models || [],
+      }));
+    } catch (e) {
+      console.error(e);
+      setModelsError(e.message);
+    } finally {
+      setLoadingModelsFor("");
+    }
+  };
+
+  // OllaBridge device pairing
+  const handlePair = async () => {
+    if (!pairCode.trim()) return;
+    setPairing(true);
+    setPairResult(null);
+    try {
+      const baseUrl = settings?.ollabridge?.base_url || "https://ruslanmv-ollabridge.hf.space";
+      const res = await fetch("/api/ollabridge/pair", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ base_url: baseUrl, code: pairCode.trim() }),
+      });
+      const data = await res.json();
+      if (data.success) {
+        setPairResult({ ok: true, message: "Paired successfully!" });
+        if (data.token) {
+          updateField("ollabridge", "api_key", data.token);
+        }
+      } else {
+        setPairResult({ ok: false, message: data.error || "Pairing failed" });
+      }
+    } catch (e) {
+      setPairResult({ ok: false, message: e.message });
+    } finally {
+      setPairing(false);
+    }
+  };
+
+  const handleTestConnection = async () => {
+    setTesting(true);
+    setTestResult(null);
+    try {
+      const activeProvider = settings?.provider || "ollama";
+      const config = { provider: activeProvider };
+
+      // Add provider-specific config
+      if (activeProvider === "openai" && settings?.openai) {
+        config.openai = {
+          api_key: settings.openai.api_key,
+          base_url: settings.openai.base_url,
+          model: settings.openai.model,
+        };
+      } else if (activeProvider === "claude" && settings?.claude) {
+        config.claude = {
+          api_key: settings.claude.api_key,
+          base_url: settings.claude.base_url,
+          model: settings.claude.model,
+        };
+      } else if (activeProvider === "watsonx" && settings?.watsonx) {
+        config.watsonx = {
+          api_key: settings.watsonx.api_key,
+          project_id: settings.watsonx.project_id,
+          base_url: settings.watsonx.base_url,
+          model_id: settings.watsonx.model_id,
+        };
+      } else if (activeProvider === "ollama" && settings?.ollama) {
+        config.ollama = {
+          base_url: settings.ollama.base_url,
+          model: settings.ollama.model,
+        };
+      } else if (activeProvider === "ollabridge" && settings?.ollabridge) {
+        config.ollabridge = {
+          base_url: settings.ollabridge.base_url,
+          model: settings.ollabridge.model,
+          api_key: settings.ollabridge.api_key,
+        };
+      }
+
+      const result = await testProvider(config);
+      setTestResult(result);
+    } catch (err) {
+      setTestResult({ health: "error", warning: err.message || "Test failed" });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  if (!settings) {
+    return (
+      <div className="settings-root">
+        <h1>Admin / LLM Settings</h1>
+        <p className="settings-muted">Loading current configuration\u2026</p>
+      </div>
+    );
+  }
+
+  const { provider } = settings;
+  const availableModels = modelsByProvider[provider] || [];
+
+  return (
+    <div className="settings-root">
+      <h1>Admin / LLM Settings</h1>
+      <p className="settings-muted">
+        Choose which LLM provider GitPilot should use for planning and agent
+        workflows. Provider settings are stored on the server.
+      </p>
+
+      {/* ACTIVE PROVIDER */}
+      <div className="settings-card">
+        <label className="settings-label">Active provider</label>
+        <div className="settings-provider-tabs">
+          {PROVIDERS.map((p) => (
+            <button
+              key={p}
+              type="button"
+              className={
+                "settings-provider-tab" +
+                (provider === p ? " settings-provider-tab-active" : "")
+              }
+              onClick={() =>
+                setSettings((prev) => ({ ...prev, provider: p }))
+              }
+            >
+              {PROVIDER_LABELS[p] || p}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* ============================================================ */}
+      {/* OLLABRIDGE CLOUD                                              */}
+      {/* ============================================================ */}
+      {provider === "ollabridge" && (
+        <div className="settings-card">
+          <div className="settings-title">OllaBridge Cloud Configuration</div>
+          <div className="settings-hint" style={{ marginBottom: 12 }}>
+            Connect to OllaBridge Cloud or any OllaBridge instance for LLM
+            inference. No API key required for public endpoints.
+          </div>
+
+          {/* AUTH MODE TABS */}
+          <label className="settings-label">Authentication Mode</label>
+          <div className="ob-auth-tabs">
+            {AUTH_MODES.map((m) => (
+              <button
+                key={m.id}
+                type="button"
+                className={
+                  "ob-auth-tab" +
+                  (authMode === m.id ? " ob-auth-tab-active" : "")
+                }
+                onClick={() => setAuthMode(m.id)}
+              >
+                <span className="ob-auth-tab-icon">{m.icon}</span>
+                <span>{m.label}</span>
+              </button>
+            ))}
+          </div>
+
+          {/* DEVICE PAIRING MODE */}
+          {authMode === "device" && (
+            <div className="ob-auth-panel">
+              <div className="ob-auth-desc">
+                Enter the pairing code from your OllaBridge console and
+                click Pair.
+              </div>
+              <div className="ob-pair-row">
+                <input
+                  className="settings-input ob-pair-input"
+                  type="text"
+                  maxLength={9}
+                  placeholder="ABCD-1234"
+                  value={pairCode}
+                  onChange={(e) => setPairCode(e.target.value.toUpperCase())}
+                  onKeyDown={(e) => e.key === "Enter" && handlePair()}
+                />
+                <button
+                  type="button"
+                  className="ob-pair-btn"
+                  onClick={handlePair}
+                  disabled={pairing || !pairCode.trim()}
+                >
+                  {pairing ? (
+                    <span className="ob-pair-spinner" />
+                  ) : (
+                    "\uD83D\uDD17"
+                  )}{" "}
+                  Pair
+                </button>
+              </div>
+              {pairResult && (
+                <div
+                  className={
+                    "ob-pair-result " +
+                    (pairResult.ok
+                      ? "ob-pair-result-ok"
+                      : "ob-pair-result-err")
+                  }
+                >
+                  {pairResult.message}
+                </div>
+              )}
+            </div>
+          )}
+
+          {/* API KEY MODE */}
+          {authMode === "apikey" && (
+            <div className="ob-auth-panel">
+              <div className="ob-auth-desc">
+                Enter your OllaBridge API key or device token for authenticated
+                access.
+              </div>
+              <label className="settings-label">API Key / Device Token</label>
+              <input
+                className="settings-input"
+                type="password"
+                placeholder="Enter API key or device token"
+                value={settings.ollabridge?.api_key || ""}
+                onChange={(e) =>
+                  updateField("ollabridge", "api_key", e.target.value)
+                }
+              />
+            </div>
+          )}
+
+          {/* LOCAL TRUST MODE */}
+          {authMode === "local" && (
+            <div className="ob-auth-panel">
+              <div className="ob-auth-desc">
+                Connect to a local or trusted OllaBridge instance without
+                authentication. Ideal for local development or pre-configured
+                cloud endpoints.
+              </div>
+            </div>
+          )}
+
+          {/* BASE URL */}
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Base URL
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="https://ruslanmv-ollabridge.hf.space"
+            value={settings.ollabridge?.base_url || ""}
+            onChange={(e) =>
+              updateField("ollabridge", "base_url", e.target.value)
+            }
+          />
+          <div className="settings-hint">
+            Default: https://ruslanmv-ollabridge.hf.space (free, no key
+            needed)
+          </div>
+
+          {/* MODEL */}
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Model
+          </label>
+          <div className="ob-model-row">
+            <input
+              className="settings-input"
+              type="text"
+              placeholder="qwen2.5:1.5b"
+              value={settings.ollabridge?.model || ""}
+              onChange={(e) =>
+                updateField("ollabridge", "model", e.target.value)
+              }
+              style={{ flex: 1 }}
+            />
+            <button
+              type="button"
+              className="ob-fetch-btn"
+              onClick={() => loadModelsForProvider("ollabridge")}
+              disabled={loadingModelsFor === "ollabridge"}
+            >
+              {loadingModelsFor === "ollabridge" ? (
+                <span className="ob-pair-spinner" />
+              ) : (
+                "\uD83D\uDD04"
+              )}{" "}
+              Fetch Models
+            </button>
+          </div>
+
+          {availableModels.length > 0 && (
+            <>
+              <label className="settings-label" style={{ marginTop: 8 }}>
+                Available models
+              </label>
+              <select
+                className="settings-select"
+                value={settings.ollabridge?.model || ""}
+                onChange={(e) =>
+                  updateField("ollabridge", "model", e.target.value)
+                }
+              >
+                <option value="">-- select a model --</option>
+                {availableModels.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </>
+          )}
+
+          <div className="settings-hint" style={{ marginTop: 4 }}>
+            Examples: qwen2.5:1.5b, llama3, mistral, codellama,
+            deepseek-coder
+          </div>
+        </div>
+      )}
+
+      {/* OPENAI */}
+      {provider === "openai" && (
+        <div className="settings-card">
+          <div className="settings-title">OpenAI Configuration</div>
+
+          <label className="settings-label">API Key</label>
+          <input
+            className="settings-input"
+            type="password"
+            placeholder="sk-..."
+            value={settings.openai?.api_key || ""}
+            onChange={(e) => updateField("openai", "api_key", e.target.value)}
+          />
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Model
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="gpt-4o-mini"
+            value={settings.openai?.model || ""}
+            onChange={(e) => updateField("openai", "model", e.target.value)}
+          />
+
+          <button
+            type="button"
+            className="settings-load-btn"
+            onClick={() => loadModelsForProvider("openai")}
+            disabled={loadingModelsFor === "openai"}
+          >
+            {loadingModelsFor === "openai"
+              ? "Loading models\u2026"
+              : "Load available models"}
+          </button>
+
+          {availableModels.length > 0 && (
+            <>
+              <label className="settings-label" style={{ marginTop: 12 }}>
+                Choose from discovered models
+              </label>
+              <select
+                className="settings-select"
+                value={settings.openai?.model || ""}
+                onChange={(e) =>
+                  updateField("openai", "model", e.target.value)
+                }
+              >
+                <option value="">-- select a model --</option>
+                {availableModels.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </>
+          )}
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Base URL (optional)
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="Leave empty for default, or use Azure OpenAI endpoint"
+            value={settings.openai?.base_url || ""}
+            onChange={(e) => updateField("openai", "base_url", e.target.value)}
+          />
+          <div className="settings-hint">
+            Examples: gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini
+          </div>
+        </div>
+      )}
+
+      {/* CLAUDE */}
+      {provider === "claude" && (
+        <div className="settings-card">
+          <div className="settings-title">Claude Configuration</div>
+
+          <label className="settings-label">API Key</label>
+          <input
+            className="settings-input"
+            type="password"
+            placeholder="sk-ant-..."
+            value={settings.claude?.api_key || ""}
+            onChange={(e) => updateField("claude", "api_key", e.target.value)}
+          />
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Model
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="claude-sonnet-4-5"
+            value={settings.claude?.model || ""}
+            onChange={(e) => updateField("claude", "model", e.target.value)}
+          />
+
+          <button
+            type="button"
+            className="settings-load-btn"
+            onClick={() => loadModelsForProvider("claude")}
+            disabled={loadingModelsFor === "claude"}
+          >
+            {loadingModelsFor === "claude"
+              ? "Loading models\u2026"
+              : "Load available models"}
+          </button>
+
+          {availableModels.length > 0 && (
+            <>
+              <label className="settings-label" style={{ marginTop: 12 }}>
+                Choose from discovered models
+              </label>
+              <select
+                className="settings-select"
+                value={settings.claude?.model || ""}
+                onChange={(e) =>
+                  updateField("claude", "model", e.target.value)
+                }
+              >
+                <option value="">-- select a model --</option>
+                {availableModels.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </>
+          )}
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Base URL (optional)
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="Leave empty for default Anthropic endpoint"
+            value={settings.claude?.base_url || ""}
+            onChange={(e) => updateField("claude", "base_url", e.target.value)}
+          />
+          <div className="settings-hint">
+            Examples: claude-sonnet-4-5, claude-3.7-sonnet, claude-3-opus-20240229
+          </div>
+        </div>
+      )}
+
+      {/* WATSONX */}
+      {provider === "watsonx" && (
+        <div className="settings-card">
+          <div className="settings-title">IBM watsonx.ai Configuration</div>
+
+          <label className="settings-label">API Key</label>
+          <input
+            className="settings-input"
+            type="password"
+            placeholder="Your watsonx API key"
+            value={settings.watsonx?.api_key || ""}
+            onChange={(e) => updateField("watsonx", "api_key", e.target.value)}
+          />
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Project ID
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="Your watsonx project ID"
+            value={settings.watsonx?.project_id || ""}
+            onChange={(e) =>
+              updateField("watsonx", "project_id", e.target.value)
+            }
+          />
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Model ID
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="meta-llama/llama-3-3-70b-instruct"
+            value={settings.watsonx?.model_id || ""}
+            onChange={(e) =>
+              updateField("watsonx", "model_id", e.target.value)
+            }
+          />
+
+          <button
+            type="button"
+            className="settings-load-btn"
+            onClick={() => loadModelsForProvider("watsonx")}
+            disabled={loadingModelsFor === "watsonx"}
+          >
+            {loadingModelsFor === "watsonx"
+              ? "Loading models\u2026"
+              : "Load available models"}
+          </button>
+
+          {availableModels.length > 0 && (
+            <>
+              <label className="settings-label" style={{ marginTop: 12 }}>
+                Choose from discovered models
+              </label>
+              <select
+                className="settings-select"
+                value={settings.watsonx?.model_id || ""}
+                onChange={(e) =>
+                  updateField("watsonx", "model_id", e.target.value)
+                }
+              >
+                <option value="">-- select a model --</option>
+                {availableModels.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </>
+          )}
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Base URL
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="https://api.watsonx.ai/v1"
+            value={settings.watsonx?.base_url || ""}
+            onChange={(e) =>
+              updateField("watsonx", "base_url", e.target.value)
+            }
+          />
+          <div className="settings-hint">
+            Examples: meta-llama/llama-3-3-70b-instruct, ibm/granite-13b-chat-v2
+          </div>
+        </div>
+      )}
+
+      {/* OLLAMA */}
+      {provider === "ollama" && (
+        <div className="settings-card">
+          <div className="settings-title">Ollama Configuration</div>
+
+          <label className="settings-label">Base URL</label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="http://localhost:11434"
+            value={settings.ollama?.base_url || ""}
+            onChange={(e) => updateField("ollama", "base_url", e.target.value)}
+          />
+
+          <label className="settings-label" style={{ marginTop: 12 }}>
+            Model
+          </label>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="llama3"
+            value={settings.ollama?.model || ""}
+            onChange={(e) => updateField("ollama", "model", e.target.value)}
+          />
+
+          <button
+            type="button"
+            className="settings-load-btn"
+            onClick={() => loadModelsForProvider("ollama")}
+            disabled={loadingModelsFor === "ollama"}
+          >
+            {loadingModelsFor === "ollama"
+              ? "Loading models\u2026"
+              : "Load available models"}
+          </button>
+
+          {availableModels.length > 0 && (
+            <>
+              <label className="settings-label" style={{ marginTop: 12 }}>
+                Choose from discovered models
+              </label>
+              <select
+                className="settings-select"
+                value={settings.ollama?.model || ""}
+                onChange={(e) =>
+                  updateField("ollama", "model", e.target.value)
+                }
+              >
+                <option value="">-- select a model --</option>
+                {availableModels.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </>
+          )}
+
+          <div className="settings-hint">
+            Examples: llama3, mistral, codellama, phi3
+          </div>
+        </div>
+      )}
+
+      {modelsError && (
+        <div className="settings-error" style={{ marginTop: 8 }}>
+          {modelsError}
+        </div>
+      )}
+
+      <div className="settings-actions">
+        <button
+          onClick={handleTestConnection}
+          disabled={testing}
+          style={{
+            padding: "8px 16px",
+            background: "#2563EB",
+            color: "#fff",
+            border: "none",
+            borderRadius: "6px",
+            cursor: testing ? "not-allowed" : "pointer",
+            opacity: testing ? 0.6 : 1,
+            marginRight: "8px",
+          }}
+        >
+          {testing ? "Testing..." : "Test Connection"}
+        </button>
+        <button
+          className="settings-save-btn"
+          type="button"
+          onClick={handleSave}
+          disabled={saving}
+        >
+          {saving ? "Saving\u2026" : "Save settings"}
+        </button>
+        {savedMsg && <span className="settings-success">{savedMsg}</span>}
+        {error && <span className="settings-error">{error}</span>}
+        {testResult && (
+          <div style={{
+            marginTop: "12px",
+            padding: "10px 14px",
+            borderRadius: "6px",
+            background: testResult.health === "ok" ? "#0d3320" : "#3d1111",
+            border: `1px solid ${testResult.health === "ok" ? "#166534" : "#7f1d1d"}`,
+            fontSize: "13px",
+            width: "100%",
+          }}>
+            <span style={{ fontWeight: 600 }}>
+              {testResult.health === "ok" ? "\u2713 Connection successful" : "\u2717 Connection failed"}
+            </span>
+            {testResult.warning && (
+              <div style={{ marginTop: "4px", opacity: 0.8, fontSize: "12px" }}>
+                {testResult.warning}
+              </div>
+            )}
+            {testResult.model && (
+              <div style={{ marginTop: "4px", opacity: 0.7, fontSize: "12px" }}>
+                Model: {testResult.model}
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/components/LoginPage.jsx

@@ -0,0 +1,535 @@
+// frontend/components/LoginPage.jsx
+import React, { useState, useEffect, useRef } from "react";
+import { apiUrl, safeFetchJSON } from "../utils/api.js";
+
+/**
+ * GitPilot – Enterprise Agentic Login
+ * Theme: "Claude Code" / Anthropic Enterprise (Dark + Warm Orange)
+ */
+
+export default function LoginPage({ onAuthenticated }) {
+  // Auth State
+  const [authProcessing, setAuthProcessing] = useState(false);
+  const [error, setError] = useState("");
+  
+  // Mode State: 'loading' | 'web' (Has Secret) | 'device' (No Secret)
+  const [mode, setMode] = useState("loading");
+  
+  // Device Flow State
+  const [deviceData, setDeviceData] = useState(null);
+  const pollTimer = useRef(null);
+  const stopPolling = useRef(false); // Flag to safely stop async polling
+
+  // Web Flow State
+  const [missingClientId, setMissingClientId] = useState(false);
+  
+  // REF FIX: Prevents React StrictMode from running the auth exchange twice
+  const processingRef = useRef(false);
+
+  // 1. Initialization Effect
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+
+    // A. If returning from GitHub (Web Flow Callback)
+    if (code) {
+      if (!processingRef.current) {
+        processingRef.current = true;
+        setMode("web"); // Implicitly web mode if we have a code
+        consumeOAuthCallback(code, state);
+      }
+      return;
+    }
+
+    // B. Otherwise, check Server Capabilities to decide UI Mode
+    safeFetchJSON(apiUrl("/api/auth/status"))
+      .then((data) => {
+        setMode(data.mode === "web" ? "web" : "device");
+      })
+      .catch((err) => {
+        console.warn("Auth status check failed, defaulting to device flow:", err);
+        setMode("device");
+      });
+
+    // Cleanup polling on unmount
+    return () => {
+      stopPolling.current = true;
+      if (pollTimer.current) clearTimeout(pollTimer.current);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ===========================================================================
+  // WEB FLOW LOGIC (Standard OAuth2)
+  // ===========================================================================
+
+  async function consumeOAuthCallback(code, state) {
+    const expectedState = sessionStorage.getItem("gitpilot_oauth_state");
+    if (state && expectedState && expectedState !== state) {
+      console.warn("OAuth state mismatch - proceeding with caution.");
+    }
+
+    setAuthProcessing(true);
+    setError("");
+    window.history.replaceState({}, document.title, window.location.pathname);
+
+    try {
+      const data = await safeFetchJSON(apiUrl("/api/auth/callback"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code, state: state || "" }),
+      });
+
+      handleSuccess(data);
+    } catch (err) {
+      console.error("Login Error:", err);
+      setError(err instanceof Error ? err.message : "Login failed.");
+      setAuthProcessing(false);
+    }
+  }
+
+  async function handleSignInWithGitHub() {
+    setError("");
+    setMissingClientId(false);
+    setAuthProcessing(true);
+
+    try {
+      const data = await safeFetchJSON(apiUrl("/api/auth/url"));
+
+      if (data.state) {
+        sessionStorage.setItem("gitpilot_oauth_state", data.state);
+      }
+
+      window.location.href = data.authorization_url;
+    } catch (err) {
+      console.error("Auth Start Error:", err);
+      // Check for missing client ID (404/500 errors)
+      if (err.message && (err.message.includes('404') || err.message.includes('500'))) {
+        setMissingClientId(true);
+      } else {
+        setError(err instanceof Error ? err.message : "Could not start sign-in.");
+      }
+      setAuthProcessing(false);
+    }
+  }
+
+  // ===========================================================================
+  // DEVICE FLOW LOGIC (No Client Secret Required)
+  // ===========================================================================
+
+  const startDeviceFlow = async () => {
+    setError("");
+    setAuthProcessing(true);
+    stopPolling.current = false; // Reset stop flag
+
+    try {
+      const data = await safeFetchJSON(apiUrl("/api/auth/device/code"), { method: "POST" });
+
+      // Handle Errors
+      if (data.error) {
+        if (data.error.includes("400") || data.error.includes("Bad Request")) {
+           throw new Error("Device Flow is disabled in GitHub. Please go to your GitHub App Settings > 'General' > 'Identifying and authorizing users' and check the box 'Enable Device Flow'.");
+        }
+        throw new Error(data.error);
+      }
+
+      if (!data.device_code) throw new Error("Invalid device code response");
+
+      setDeviceData(data);
+      setAuthProcessing(false);
+
+      // Start Polling (Recursive Timeout Pattern)
+      pollDeviceToken(data.device_code, data.interval || 5);
+
+    } catch (err) {
+      setError(err.message);
+      setAuthProcessing(false);
+    }
+  };
+
+  const pollDeviceToken = async (deviceCode, interval) => {
+    if (stopPolling.current) return;
+
+    try {
+      const response = await fetch(apiUrl("/api/auth/device/poll"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ device_code: deviceCode })
+      });
+
+      // 1. Success (200)
+      if (response.status === 200) {
+        const data = await response.json();
+        handleSuccess(data);
+        return;
+      }
+
+      // 2. Pending (202) -> Continue Polling
+      if (response.status === 202) {
+        // Schedule next poll
+        pollTimer.current = setTimeout(
+            () => pollDeviceToken(deviceCode, interval),
+            interval * 1000
+        );
+        return;
+      }
+
+      // 3. Error (4xx/5xx) -> Stop Polling & Show Error
+      const errData = await response.json().catch(() => ({ error: "Unknown polling error" }));
+
+      // Special case: If it's just a 'slow_down' warning (sometimes 400), we just wait longer
+      if (errData.error === "slow_down") {
+          pollTimer.current = setTimeout(
+            () => pollDeviceToken(deviceCode, interval + 5),
+            (interval + 5) * 1000
+          );
+          return;
+      }
+
+      // Terminal errors
+      throw new Error(errData.error || `Polling failed: ${response.status}`);
+
+    } catch (e) {
+      console.error("Poll error:", e);
+      if (!stopPolling.current) {
+        setError(e.message || "Failed to connect to authentication server.");
+        setDeviceData(null); // Return to initial state
+      }
+    }
+  };
+
+  const handleManualCheck = async () => {
+    if (!deviceData?.device_code) return;
+
+    try {
+        const response = await fetch(apiUrl("/api/auth/device/poll"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: deviceData.device_code })
+        });
+
+        if (response.status === 200) {
+            const data = await response.json();
+            handleSuccess(data);
+        } else if (response.status === 202) {
+            // Visual feedback for pending state
+            const btn = document.getElementById("manual-check-btn");
+            if (btn) {
+                const originalText = btn.innerText;
+                btn.innerText = "Still Pending...";
+                btn.disabled = true;
+                setTimeout(() => {
+                    btn.innerText = originalText;
+                    btn.disabled = false;
+                }, 2000);
+            }
+        }
+    } catch (e) {
+        console.error("Manual check failed", e);
+    }
+  };
+
+  const handleCancelDeviceFlow = () => {
+    stopPolling.current = true;
+    if (pollTimer.current) clearTimeout(pollTimer.current);
+    setDeviceData(null);
+    setError("");
+  };
+
+  // ===========================================================================
+  // SHARED HELPERS
+  // ===========================================================================
+
+  function handleSuccess(data) {
+    stopPolling.current = true; // Ensure polling stops
+    if (pollTimer.current) clearTimeout(pollTimer.current);
+
+    if (!data.access_token || !data.user) {
+      setError("Server returned incomplete session data.");
+      return;
+    }
+
+    try {
+      localStorage.setItem("github_token", data.access_token);
+      localStorage.setItem("github_user", JSON.stringify(data.user));
+    } catch (e) {
+      console.warn("LocalStorage access denied:", e);
+    }
+
+    if (typeof onAuthenticated === "function") {
+      onAuthenticated({
+        access_token: data.access_token,
+        user: data.user,
+      });
+    }
+  }
+
+  // --- Design Token System ---
+  const theme = {
+    bg: "#131316",         
+    cardBg: "#1C1C1F",     
+    border: "#27272A",     
+    accent: "#D95C3D",     
+    accentHover: "#C44F32",
+    textPrimary: "#EDEDED",
+    textSecondary: "#A1A1AA",
+    font: '"Söhne", "Inter", -apple-system, sans-serif',
+  };
+
+  const styles = {
+    container: {
+      minHeight: "100vh",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      backgroundColor: theme.bg,
+      fontFamily: theme.font,
+      color: theme.textPrimary,
+      letterSpacing: "-0.01em",
+    },
+    card: {
+      backgroundColor: theme.cardBg,
+      width: "100%",
+      maxWidth: "440px",
+      borderRadius: "12px",
+      border: `1px solid ${theme.border}`,
+      boxShadow: "0 24px 48px -12px rgba(0, 0, 0, 0.6)",
+      padding: "48px 40px",
+      textAlign: "center",
+      position: "relative",
+    },
+    logoBadge: {
+      width: "48px",
+      height: "48px",
+      backgroundColor: "rgba(217, 92, 61, 0.15)",
+      color: theme.accent,
+      borderRadius: "10px",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      fontSize: "22px",
+      fontWeight: "700",
+      margin: "0 auto 32px auto",
+      border: "1px solid rgba(217, 92, 61, 0.2)",
+    },
+    h1: {
+      fontSize: "24px",
+      fontWeight: "600",
+      marginBottom: "12px",
+      color: theme.textPrimary,
+    },
+    p: {
+      fontSize: "14px",
+      color: theme.textSecondary,
+      lineHeight: "1.6",
+      marginBottom: "40px",
+    },
+    button: {
+      width: "100%",
+      height: "48px",
+      backgroundColor: theme.accent,
+      color: "#FFFFFF",
+      border: "none",
+      borderRadius: "8px",
+      fontSize: "14px",
+      fontWeight: "500",
+      cursor: (authProcessing || (mode === 'loading')) ? "not-allowed" : "pointer",
+      opacity: (authProcessing || (mode === 'loading')) ? 0.7 : 1,
+      transition: "background-color 0.2s ease",
+      display: "flex",
+      alignItems: "center",
+      justifyContent: "center",
+      gap: "10px",
+      boxShadow: "0 4px 12px rgba(217, 92, 61, 0.25)",
+    },
+    secondaryButton: {
+        backgroundColor: "transparent",
+        color: "#A1A1AA",
+        border: "1px solid #3F3F46",
+        padding: "8px 16px",
+        borderRadius: "6px",
+        fontSize: "12px",
+        cursor: "pointer",
+        marginTop: "16px",
+        minWidth: "100px"
+    },
+    errorBox: {
+      backgroundColor: "rgba(185, 28, 28, 0.15)",
+      border: "1px solid rgba(185, 28, 28, 0.3)",
+      color: "#FCA5A5",
+      padding: "12px",
+      borderRadius: "8px",
+      fontSize: "13px",
+      marginBottom: "24px",
+      textAlign: "left",
+    },
+    configCard: {
+      textAlign: "left",
+      backgroundColor: "#111",
+      border: "1px solid #333",
+      padding: "24px",
+      borderRadius: "8px",
+      marginBottom: "24px",
+    },
+    codeDisplay: {
+      backgroundColor: "#27272A",
+      color: theme.accent,
+      fontSize: "20px",
+      fontWeight: "700",
+      padding: "12px",
+      borderRadius: "6px",
+      textAlign: "center",
+      letterSpacing: "2px",
+      margin: "12px 0",
+      border: `1px dashed ${theme.accent}`,
+      cursor: "pointer",
+    },
+    footer: {
+      marginTop: "48px",
+      fontSize: "12px",
+      color: "#52525B",
+    }
+  };
+
+  // --- RENDER: Device Flow UI ---
+  const renderDeviceFlow = () => {
+    if (!deviceData) {
+      return (
+        <button
+          onClick={startDeviceFlow}
+          disabled={authProcessing}
+          style={styles.button}
+          onMouseOver={(e) => !authProcessing && (e.currentTarget.style.backgroundColor = theme.accentHover)}
+          onMouseOut={(e) => !authProcessing && (e.currentTarget.style.backgroundColor = theme.accent)}
+        >
+           {authProcessing ? "Connecting..." : "Sign in with GitHub"}
+        </button>
+      );
+    }
+
+    return (
+      <div style={styles.configCard}>
+        <h3 style={{marginTop:0, color: '#FFF', fontSize: '16px'}}>Authorize Device</h3>
+        <p style={{color: '#AAA', fontSize: '13px', marginBottom:'16px'}}>
+          GitPilot needs authorization to access your repositories.
+        </p>
+
+        <div style={{marginBottom: '16px'}}>
+          <div style={{color: '#AAA', fontSize: '12px', marginBottom: '4px'}}>1. Copy code:</div>
+          <div 
+            style={styles.codeDisplay}
+            onClick={() => {
+                navigator.clipboard.writeText(deviceData.user_code);
+            }}
+            title="Click to copy"
+          >
+            {deviceData.user_code}
+          </div>
+        </div>
+
+        <div>
+          <div style={{color: '#AAA', fontSize: '12px', marginBottom: '4px'}}>2. Paste at GitHub:</div>
+          <a 
+            href={deviceData.verification_uri} 
+            target="_blank" 
+            rel="noreferrer"
+            style={{
+                display: 'block',
+                backgroundColor: '#FFF',
+                color: '#000',
+                textDecoration: 'none',
+                padding: '10px',
+                borderRadius: '6px',
+                textAlign: 'center',
+                fontWeight: '600',
+                fontSize: '14px'
+            }}
+          >
+            Open Activation Page ↗
+          </a>
+        </div>
+        
+        <div style={{marginTop: '20px', fontSize: '12px', color: '#666', textAlign: 'center', display: 'flex', alignItems: 'center', justifyContent: 'center', gap: '8px'}}>
+           <span style={{animation: 'spin 1s linear infinite', display: 'inline-block'}}>↻</span> 
+           Waiting for authorization...
+           <style>{`@keyframes spin { 100% { transform: rotate(360deg); } }`}</style>
+        </div>
+
+        <div style={{textAlign: 'center', display: 'flex', gap: '10px', justifyContent: 'center'}}>
+            <button 
+                id="manual-check-btn"
+                onClick={handleManualCheck} 
+                style={styles.secondaryButton}
+            >
+                Check Status
+            </button>
+            <button 
+                onClick={handleCancelDeviceFlow} 
+                style={styles.secondaryButton}
+            >
+                Cancel
+            </button>
+        </div>
+      </div>
+    );
+  };
+
+  // --- RENDER: Config Error ---
+  if (missingClientId) {
+    return (
+      <div style={styles.container}>
+        <div style={styles.card}>
+          <div style={{...styles.logoBadge, color: "#F59E0B", backgroundColor: "rgba(245, 158, 11, 0.1)", borderColor: "rgba(245, 158, 11, 0.2)"}}>⚠️</div>
+          <h1 style={styles.h1}>Configuration Error</h1>
+          <p style={styles.p}>Could not connect to GitHub Authentication services.</p>
+          <button onClick={() => setMissingClientId(false)} style={{...styles.button, backgroundColor: "#3F3F46"}}>Retry</button>
+        </div>
+      </div>
+    );
+  }
+
+  // --- RENDER: Main ---
+  return (
+    <div style={styles.container}>
+      <div style={styles.card}>
+        <div style={styles.logoBadge}>GP</div>
+        
+        <h1 style={styles.h1}>GitPilot Enterprise</h1>
+        <p style={styles.p}>
+          Agentic AI workflow for your repositories.<br/>
+          Secure. Context-aware. Automated.
+        </p>
+
+        {error && <div style={styles.errorBox}>{error}</div>}
+
+        {mode === "loading" && (
+           <div style={{color: '#666', fontSize: '14px'}}>Initializing...</div>
+        )}
+
+        {mode === "web" && (
+          <button
+            onClick={handleSignInWithGitHub}
+            disabled={authProcessing}
+            style={styles.button}
+            onMouseOver={(e) => !authProcessing && (e.currentTarget.style.backgroundColor = theme.accentHover)}
+            onMouseOut={(e) => !authProcessing && (e.currentTarget.style.backgroundColor = theme.accent)}
+          >
+            {authProcessing ? "Connecting..." : (
+               <>
+                <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405 1.02 0 2.04.135 3 .405 2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z" /></svg>
+                Sign in with GitHub
+               </>
+            )}
+          </button>
+        )}
+
+        {mode === "device" && renderDeviceFlow()}
+
+        <div style={styles.footer}>
+          &copy; {new Date().getFullYear()} GitPilot Inc.
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/components/PlanView.jsx

@@ -0,0 +1,231 @@
+import React from "react";
+
+export default function PlanView({ plan }) {
+  if (!plan) return null;
+
+  // Calculate totals for each action type
+  const totals = { CREATE: 0, MODIFY: 0, DELETE: 0 };
+  plan.steps.forEach((step) => {
+    step.files.forEach((file) => {
+      totals[file.action] = (totals[file.action] || 0) + 1;
+    });
+  });
+
+  const theme = {
+    bg: "#18181B",
+    border: "#27272A",
+    textPrimary: "#EDEDED",
+    textSecondary: "#A1A1AA",
+    successBg: "rgba(16, 185, 129, 0.1)",
+    successText: "#10B981",
+    warningBg: "rgba(245, 158, 11, 0.1)",
+    warningText: "#F59E0B",
+    dangerBg: "rgba(239, 68, 68, 0.1)",
+    dangerText: "#EF4444",
+  };
+
+  const styles = {
+    container: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "20px",
+      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    },
+    header: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "8px",
+      paddingBottom: "16px",
+      borderBottom: `1px solid ${theme.border}`,
+    },
+    goal: {
+      fontSize: "14px",
+      fontWeight: "600",
+      color: theme.textPrimary,
+    },
+    summary: {
+      fontSize: "13px",
+      color: theme.textSecondary,
+      lineHeight: "1.5",
+    },
+    totals: {
+      display: "flex",
+      gap: "12px",
+      flexWrap: "wrap",
+    },
+    totalBadge: {
+      fontSize: "11px",
+      fontWeight: "500",
+      padding: "4px 8px",
+      borderRadius: "4px",
+      border: "1px solid transparent",
+    },
+    totalCreate: {
+      backgroundColor: theme.successBg,
+      color: theme.successText,
+      borderColor: "rgba(16, 185, 129, 0.2)",
+    },
+    totalModify: {
+      backgroundColor: theme.warningBg,
+      color: theme.warningText,
+      borderColor: "rgba(245, 158, 11, 0.2)",
+    },
+    totalDelete: {
+      backgroundColor: theme.dangerBg,
+      color: theme.dangerText,
+      borderColor: "rgba(239, 68, 68, 0.2)",
+    },
+    stepsList: {
+      listStyle: "none",
+      padding: 0,
+      margin: 0,
+      display: "flex",
+      flexDirection: "column",
+      gap: "24px",
+    },
+    step: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "8px",
+      position: "relative",
+    },
+    stepHeader: {
+      display: "flex",
+      alignItems: "baseline",
+      gap: "8px",
+      fontSize: "13px",
+      fontWeight: "600",
+      color: theme.textPrimary,
+    },
+    stepNumber: {
+      color: theme.textSecondary,
+      fontSize: "11px",
+      textTransform: "uppercase",
+      letterSpacing: "0.05em",
+    },
+    stepDescription: {
+      fontSize: "13px",
+      color: theme.textSecondary,
+      lineHeight: "1.5",
+      margin: 0,
+    },
+    fileList: {
+      marginTop: "8px",
+      display: "flex",
+      flexDirection: "column",
+      gap: "4px",
+      backgroundColor: "#131316",
+      padding: "8px 12px",
+      borderRadius: "6px",
+      border: `1px solid ${theme.border}`,
+    },
+    fileItem: {
+      display: "flex",
+      alignItems: "center",
+      gap: "10px",
+      fontSize: "12px",
+      fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+    },
+    actionBadge: {
+      padding: "2px 6px",
+      borderRadius: "4px",
+      fontSize: "10px",
+      fontWeight: "bold",
+      textTransform: "uppercase",
+      minWidth: "55px",
+      textAlign: "center",
+      letterSpacing: "0.02em",
+    },
+    path: {
+      color: "#D4D4D8",
+      whiteSpace: "nowrap",
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+    },
+    risks: {
+      marginTop: "8px",
+      fontSize: "12px",
+      color: theme.warningText,
+      backgroundColor: "rgba(245, 158, 11, 0.05)",
+      padding: "8px 12px",
+      borderRadius: "6px",
+      border: "1px solid rgba(245, 158, 11, 0.1)",
+      display: "flex",
+      gap: "6px",
+      alignItems: "flex-start",
+    },
+  };
+
+  const getActionStyle = (action) => {
+    switch (action) {
+      case "CREATE": return styles.totalCreate;
+      case "MODIFY": return styles.totalModify;
+      case "DELETE": return styles.totalDelete;
+      default: return {};
+    }
+  };
+
+  return (
+    <div style={styles.container}>
+      {/* Header & Summary */}
+      <div style={styles.header}>
+        <div style={styles.goal}>Goal: {plan.goal}</div>
+        <div style={styles.summary}>{plan.summary}</div>
+      </div>
+
+      {/* Totals Summary */}
+      <div style={styles.totals}>
+        {totals.CREATE > 0 && (
+          <span style={{ ...styles.totalBadge, ...styles.totalCreate }}>
+            {totals.CREATE} to create
+          </span>
+        )}
+        {totals.MODIFY > 0 && (
+          <span style={{ ...styles.totalBadge, ...styles.totalModify }}>
+            {totals.MODIFY} to modify
+          </span>
+        )}
+        {totals.DELETE > 0 && (
+          <span style={{ ...styles.totalBadge, ...styles.totalDelete }}>
+            {totals.DELETE} to delete
+          </span>
+        )}
+      </div>
+
+      {/* Steps List */}
+      <ol style={styles.stepsList}>
+        {plan.steps.map((s) => (
+          <li key={s.step_number} style={styles.step}>
+            <div style={styles.stepHeader}>
+              <span style={styles.stepNumber}>Step {s.step_number}</span>
+              <span>{s.title}</span>
+            </div>
+            <p style={styles.stepDescription}>{s.description}</p>
+
+            {/* Files List */}
+            {s.files && s.files.length > 0 && (
+              <div style={styles.fileList}>
+                {s.files.map((file, idx) => (
+                  <div key={idx} style={styles.fileItem}>
+                    <span style={{ ...styles.actionBadge, ...getActionStyle(file.action) }}>
+                      {file.action}
+                    </span>
+                    <span style={styles.path}>{file.path}</span>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {/* Risks */}
+            {s.risks && (
+              <div style={styles.risks}>
+                <span>⚠️</span>
+                <span>{s.risks}</span>
+              </div>
+            )}
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}

frontend/components/ProjectContextPanel.jsx

@@ -0,0 +1,572 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import FileTree from "./FileTree.jsx";
+import BranchPicker from "./BranchPicker.jsx";
+
+// --- INJECTED STYLES FOR ANIMATIONS ---
+const animationStyles = `
+  @keyframes highlight-pulse {
+    0% { background-color: rgba(59, 130, 246, 0.10); }
+    50% { background-color: rgba(59, 130, 246, 0.22); }
+    100% { background-color: transparent; }
+  }
+  .pulse-context {
+    animation: highlight-pulse 1.1s ease-out;
+  }
+`;
+
+/**
+ * ProjectContextPanel (Production-ready)
+ *
+ * Controlled component:
+ * - Branch source of truth is App.jsx:
+ * - defaultBranch (prod)
+ * - currentBranch (what user sees)
+ * - sessionBranches (list of all active AI session branches)
+ *
+ * Responsibilities:
+ * - Show project context + branch dropdown + AI badge/banner
+ * - Fetch access status + file count for the currentBranch
+ * - Trigger visual pulse on pulseNonce (Hard Switch)
+ */
+export default function ProjectContextPanel({
+  repo,
+  defaultBranch,
+  currentBranch,
+  sessionBranch, // Active session branch (optional, for specific highlighting)
+  sessionBranches = [], // List of all AI branches
+  onBranchChange,
+  pulseNonce,
+  onSettingsClick,
+}) {
+  const [appUrl, setAppUrl] = useState("");
+  const [fileCount, setFileCount] = useState(0);
+
+  const [isDropdownOpen, setIsDropdownOpen] = useState(false);
+
+  // Data Loading State
+  const [analyzing, setAnalyzing] = useState(false);
+  const [accessInfo, setAccessInfo] = useState(null);
+  const [treeError, setTreeError] = useState(null);
+
+  // Retry / Refresh Logic
+  const [refreshTrigger, setRefreshTrigger] = useState(0);
+  const [retryCount, setRetryCount] = useState(0);
+  const retryTimeoutRef = useRef(null);
+
+  // UX State
+  const [animateHeader, setAnimateHeader] = useState(false);
+  const [toast, setToast] = useState({ visible: false, title: "", msg: "" });
+
+  // Calculate effective default to prevent 'main' fallback errors
+  const effectiveDefaultBranch = defaultBranch || repo?.default_branch || "main";
+  const branch = currentBranch || effectiveDefaultBranch;
+
+  // Determine if we are currently viewing an AI Session branch
+  const isAiSession = (sessionBranches.includes(branch)) || (sessionBranch === branch && branch !== effectiveDefaultBranch);
+
+  // Fetch App URL on mount
+  useEffect(() => {
+    fetch("/api/auth/app-url")
+      .then((res) => res.json())
+      .then((data) => {
+        if (data.app_url) setAppUrl(data.app_url);
+      })
+      .catch((err) => console.error("Failed to fetch App URL:", err));
+  }, []);
+
+  // Hard Switch pulse: whenever App increments pulseNonce
+  useEffect(() => {
+    if (!pulseNonce) return;
+    setAnimateHeader(true);
+    const t = window.setTimeout(() => setAnimateHeader(false), 1100);
+    return () => window.clearTimeout(t);
+  }, [pulseNonce]);
+
+  // Main data fetcher (Access + Tree stats) for currentBranch
+  // Stale-while-revalidate: keep previous data visible during fetch
+  useEffect(() => {
+    if (!repo) return;
+
+    // Only show full "analyzing" spinner if we have no data yet
+    if (!accessInfo) setAnalyzing(true);
+    setTreeError(null);
+
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+
+    let headers = {};
+    try {
+      const token = localStorage.getItem("github_token");
+      if (token) headers = { Authorization: `Bearer ${token}` };
+    } catch (e) {
+      console.warn("Unable to read github_token:", e);
+    }
+
+    let cancelled = false;
+    const cacheBuster = `&_t=${Date.now()}&retry=${retryCount}`;
+
+    // A) Access Check (with Stale Cache Fix)
+    fetch(`/api/auth/repo-access?owner=${repo.owner}&repo=${repo.name}${cacheBuster}`, {
+      headers,
+      cache: "no-cache",
+    })
+      .then(async (res) => {
+        if (cancelled) return;
+        const data = await res.json().catch(() => ({}));
+
+        if (!res.ok) {
+          setAccessInfo({ can_write: false, app_installed: false, auth_type: "none" });
+          return;
+        }
+
+        setAccessInfo(data);
+
+        // Auto-retry if user has push access but App is not detected yet (Stale Cache)
+        if (data.can_write && !data.app_installed && retryCount === 0) {
+          retryTimeoutRef.current = setTimeout(() => {
+            setRetryCount(1);
+          }, 1000);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setAccessInfo({ can_write: false, app_installed: false, auth_type: "none" });
+      });
+
+    // B) Tree count for the selected branch
+    // Don't clear fileCount — keep stale value visible until new one arrives
+    const hadFileCount = fileCount > 0;
+    if (!hadFileCount) setAnalyzing(true);
+
+    fetch(`/api/repos/${repo.owner}/${repo.name}/tree?ref=${encodeURIComponent(branch)}&_t=${Date.now()}`, {
+      headers,
+      cache: "no-cache",
+    })
+      .then(async (res) => {
+        if (cancelled) return;
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+          setTreeError(data.detail || "Failed to load tree");
+          setFileCount(0);
+          return;
+        }
+        setFileCount(Array.isArray(data.files) ? data.files.length : 0);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setTreeError(err.message);
+        setFileCount(0);
+      })
+      .finally(() => { if (!cancelled) setAnalyzing(false); });
+
+    return () => {
+      cancelled = true;
+      if (retryTimeoutRef.current) clearTimeout(retryTimeoutRef.current);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [repo?.owner, repo?.name, branch, refreshTrigger, retryCount]);
+
+  const showToast = (title, msg) => {
+    setToast({ visible: true, title, msg });
+    setTimeout(() => setToast((prev) => ({ ...prev, visible: false })), 3000);
+  };
+
+  const handleManualSwitch = (targetBranch) => {
+    if (!targetBranch || targetBranch === branch) {
+      setIsDropdownOpen(false);
+      return;
+    }
+
+    // Local UI feedback (App.jsx will handle the actual state change)
+    const goingAi = sessionBranches.includes(targetBranch);
+    showToast(
+      goingAi ? "Context Switched" : "Switched to Production",
+      goingAi ? `Viewing AI Session: ${targetBranch}` : `Viewing ${targetBranch}.`
+    );
+
+    setIsDropdownOpen(false);
+    if (onBranchChange) onBranchChange(targetBranch);
+  };
+
+  const handleRefresh = () => {
+    setAnalyzing(true);
+    setRetryCount(0);
+    setRefreshTrigger((prev) => prev + 1);
+  };
+
+  const handleInstallClick = () => {
+    if (!appUrl) return;
+    const targetUrl = appUrl.endsWith("/") ? `${appUrl}installations/new` : `${appUrl}/installations/new`;
+    window.open(targetUrl, "_blank", "noopener,noreferrer");
+  };
+
+  // --- STYLES ---
+  const theme = useMemo(
+    () => ({
+      bg: "#131316",
+      border: "#27272A",
+      textPrimary: "#EDEDED",
+      textSecondary: "#A1A1AA",
+      accent: "#3b82f6",
+      warningBorder: "rgba(245, 158, 11, 0.2)",
+      warningText: "#F59E0B",
+      successColor: "#10B981",
+      cardBg: "#18181B",
+      aiBg: "rgba(59, 130, 246, 0.10)",
+      aiBorder: "rgba(59, 130, 246, 0.30)",
+      aiText: "#60a5fa",
+    }),
+    []
+  );
+
+  const styles = useMemo(
+    () => ({
+      container: {
+        height: "100%",
+        borderRight: `1px solid ${theme.border}`,
+        backgroundColor: theme.bg,
+        display: "flex",
+        flexDirection: "column",
+        fontFamily: '"Söhne", "Inter", sans-serif',
+        position: "relative",
+        overflow: "hidden",
+      },
+      header: {
+        padding: "16px 20px",
+        borderBottom: `1px solid ${theme.border}`,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        transition: "background-color 0.3s ease",
+      },
+      titleGroup: { display: "flex", alignItems: "center", gap: "8px" },
+      title: { fontSize: "13px", fontWeight: "600", color: theme.textPrimary },
+      repoBadge: {
+        backgroundColor: "#27272A",
+        color: theme.textSecondary,
+        fontSize: "11px",
+        padding: "2px 8px",
+        borderRadius: "12px",
+        border: `1px solid ${theme.border}`,
+        fontFamily: "monospace",
+      },
+      aiBadge: {
+        display: "flex",
+        alignItems: "center",
+        gap: "6px",
+        backgroundColor: theme.aiBg,
+        color: theme.aiText,
+        fontSize: "10px",
+        fontWeight: "bold",
+        padding: "2px 8px",
+        borderRadius: "12px",
+        border: `1px solid ${theme.aiBorder}`,
+        textTransform: "uppercase",
+        letterSpacing: "0.5px",
+      },
+      content: {
+        padding: "16px 20px 12px 20px",
+        display: "flex",
+        flexDirection: "column",
+        gap: "12px",
+      },
+      statRow: { display: "flex", justifyContent: "space-between", fontSize: "13px", marginBottom: "4px" },
+      label: { color: theme.textSecondary },
+      value: { color: theme.textPrimary, fontWeight: "500" },
+      dropdownContainer: { position: "relative" },
+      branchButton: {
+        display: "flex",
+        alignItems: "center",
+        gap: "6px",
+        padding: "4px 8px",
+        borderRadius: "4px",
+        border: `1px solid ${isAiSession ? theme.aiBorder : theme.border}`,
+        backgroundColor: isAiSession ? "rgba(59, 130, 246, 0.05)" : "transparent",
+        color: isAiSession ? theme.aiText : theme.textPrimary,
+        fontSize: "13px",
+        cursor: "pointer",
+        fontFamily: "monospace",
+      },
+      dropdownMenu: {
+        position: "absolute",
+        top: "100%",
+        left: 0,
+        marginTop: "4px",
+        width: "240px",
+        backgroundColor: "#1F1F23",
+        border: `1px solid ${theme.border}`,
+        borderRadius: "6px",
+        boxShadow: "0 4px 12px rgba(0,0,0,0.5)",
+        zIndex: 50,
+        display: isDropdownOpen ? "block" : "none",
+        overflow: "hidden",
+      },
+      dropdownItem: {
+        padding: "8px 12px",
+        fontSize: "13px",
+        color: theme.textSecondary,
+        cursor: "pointer",
+        display: "flex",
+        alignItems: "center",
+        gap: "8px",
+        borderBottom: `1px solid ${theme.border}`,
+      },
+      contextBanner: {
+        backgroundColor: theme.aiBg,
+        borderTop: `1px solid ${theme.aiBorder}`,
+        padding: "8px 20px",
+        fontSize: "11px",
+        color: theme.aiText,
+        display: "flex",
+        justifyContent: "space-between",
+        alignItems: "center",
+      },
+      toast: {
+        position: "absolute",
+        top: "16px",
+        right: "16px",
+        backgroundColor: "#18181B",
+        border: `1px solid ${theme.border}`,
+        borderLeft: `3px solid ${theme.accent}`,
+        borderRadius: "6px",
+        padding: "12px",
+        boxShadow: "0 4px 12px rgba(0,0,0,0.5)",
+        zIndex: 100,
+        minWidth: "240px",
+        transition: "all 0.3s cubic-bezier(0.16, 1, 0.3, 1)",
+        transform: toast.visible ? "translateX(0)" : "translateX(120%)",
+        opacity: toast.visible ? 1 : 0,
+      },
+      toastTitle: { fontSize: "13px", fontWeight: "bold", color: theme.textPrimary, marginBottom: "2px" },
+      toastMsg: { fontSize: "11px", color: theme.textSecondary },
+      refreshButton: {
+        marginTop: "8px",
+        height: "32px",
+        padding: "0 12px",
+        backgroundColor: "transparent",
+        color: theme.textSecondary,
+        border: `1px solid ${theme.border}`,
+        borderRadius: "6px",
+        fontSize: "12px",
+        cursor: analyzing ? "not-allowed" : "pointer",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: "6px",
+      },
+      settingsBtn: {
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: "28px",
+        height: "28px",
+        borderRadius: "6px",
+        border: `1px solid ${theme.border}`,
+        backgroundColor: "transparent",
+        color: theme.textSecondary,
+        cursor: "pointer",
+        padding: 0,
+        transition: "color 0.15s, border-color 0.15s",
+      },
+      treeWrapper: { flex: 1, overflow: "auto", borderTop: `1px solid ${theme.border}` },
+      installCard: {
+        marginTop: "8px",
+        padding: "12px",
+        borderRadius: "8px",
+        backgroundColor: theme.cardBg,
+        border: `1px solid ${theme.warningBorder}`,
+      },
+      installHeader: {
+        display: "flex",
+        alignItems: "center",
+        gap: "10px",
+        fontSize: "14px",
+        fontWeight: "600",
+        color: theme.textPrimary,
+      },
+      installText: {
+        fontSize: "13px",
+        color: theme.textSecondary,
+        lineHeight: "1.5",
+      },
+    }),
+    [analyzing, isAiSession, isDropdownOpen, theme, toast.visible]
+  );
+
+  // Determine status text
+  let statusText = "Checking...";
+  let statusColor = theme.textSecondary;
+  let showInstallCard = false;
+
+  if (!analyzing && accessInfo) {
+    if (accessInfo.app_installed) {
+      statusText = "Write Access ✓";
+      statusColor = theme.successColor;
+    } else if (accessInfo.can_write && retryCount === 0) {
+      statusText = "Verifying...";
+    } else if (accessInfo.can_write) {
+      statusText = "Push Access (No App)";
+      statusColor = theme.warningText;
+      showInstallCard = true;
+    } else {
+      statusText = "Read Only";
+      statusColor = theme.warningText;
+      showInstallCard = true;
+    }
+  }
+
+  if (!repo) {
+    return (
+      <div style={styles.container}>
+        <div style={styles.content}>Select a Repo</div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={styles.container}>
+      <style>{animationStyles}</style>
+
+      {/* TOAST */}
+      <div style={styles.toast}>
+        <div style={styles.toastTitle}>{toast.title}</div>
+        <div style={styles.toastMsg}>{toast.msg}</div>
+      </div>
+
+      {/* HEADER */}
+      <div style={styles.header} className={animateHeader ? "pulse-context" : ""}>
+        <div style={styles.titleGroup}>
+          <span style={styles.title}>Project context</span>
+          {isAiSession && (
+            <span style={styles.aiBadge}>
+              <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+                <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5" />
+              </svg>
+              AI Session
+            </span>
+          )}
+        </div>
+        <div style={{ display: "flex", alignItems: "center", gap: "6px" }}>
+          {!isAiSession && <span style={styles.repoBadge}>{repo.name}</span>}
+          {onSettingsClick && (
+            <button
+              type="button"
+              onClick={onSettingsClick}
+              title="Project settings"
+              style={styles.settingsBtn}
+            >
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+                <circle cx="12" cy="12" r="3" />
+                <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" />
+              </svg>
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* CONTENT */}
+      <div style={styles.content}>
+        {/* Branch selector (Claude-Code-on-Web parity — uses BranchPicker with search) */}
+        <div style={styles.statRow}>
+          <span style={styles.label}>Branch:</span>
+          <BranchPicker
+            repo={repo}
+            currentBranch={branch}
+            defaultBranch={effectiveDefaultBranch}
+            sessionBranches={sessionBranches}
+            onBranchChange={handleManualSwitch}
+          />
+        </div>
+
+        {/* Stats */}
+        <div style={styles.statRow}>
+          <span style={styles.label}>Files:</span>
+          <span style={styles.value}>{analyzing ? "…" : fileCount}</span>
+        </div>
+
+        <div style={styles.statRow}>
+          <span style={styles.label}>Status:</span>
+          <span style={{ ...styles.value, color: statusColor }}>{statusText}</span>
+        </div>
+
+        {/* Tree error (optional display) */}
+        {treeError && (
+          <div style={{ fontSize: 11, color: theme.warningText }}>
+            {treeError}
+          </div>
+        )}
+
+        {/* Refresh */}
+        <button type="button" style={styles.refreshButton} onClick={handleRefresh} disabled={analyzing}>
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            style={{
+              transform: analyzing ? "rotate(360deg)" : "rotate(0deg)",
+              transition: "transform 0.6s ease",
+            }}
+          >
+            <path d="M21.5 2v6h-6M2.5 22v-6h6M2 11.5a10 10 0 0 1 18.8-4.3M22 12.5a10 10 0 0 1-18.8 4.2" />
+          </svg>
+          {analyzing ? "Refreshing..." : "Refresh"}
+        </button>
+
+        {/* Install card */}
+        {showInstallCard && (
+          <div style={styles.installCard}>
+            <div style={styles.installHeader}>
+              <span>⚡</span>
+              <span>Enable Write Access</span>
+            </div>
+            <p style={{ ...styles.installText, margin: "8px 0" }}>
+              Install the GitPilot App to enable AI agent operations.
+            </p>
+            <p style={{ ...styles.installText, margin: "0 0 8px 0", fontSize: "11px", opacity: 0.7 }}>
+              Alternatively, use Folder or Local Git mode for local-first workflows without GitHub.
+            </p>
+            <button
+              type="button"
+              style={{
+                ...styles.refreshButton,
+                width: "100%",
+                backgroundColor: theme.accent,
+                color: "#fff",
+                border: "none",
+              }}
+              onClick={handleInstallClick}
+            >
+              Install App
+            </button>
+          </div>
+        )}
+      </div>
+
+      {/* Context banner */}
+      {isAiSession && (
+        <div style={styles.contextBanner}>
+          <span style={{ display: "flex", alignItems: "center", gap: "6px" }}>
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+              <circle cx="12" cy="12" r="10"></circle>
+              <line x1="12" y1="16" x2="12" y2="12"></line>
+              <line x1="12" y1="8" x2="12.01" y2="8"></line>
+            </svg>
+            You are viewing an AI Session branch.
+          </span>
+          <span style={{ textDecoration: "underline", cursor: "pointer" }} onClick={() => handleManualSwitch(effectiveDefaultBranch)}>
+            Return to {effectiveDefaultBranch}
+          </span>
+        </div>
+      )}
+
+      {/* File tree (branch-aware) */}
+      <div style={styles.treeWrapper}>
+        <FileTree repo={repo} refreshTrigger={refreshTrigger} branch={branch} />
+      </div>
+    </div>
+  );
+}

frontend/components/ProjectSettings/ContextTab.jsx

@@ -0,0 +1,352 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+
+export default function ContextTab({ owner, repo }) {
+  const [assets, setAssets] = useState([]);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [uploadHint, setUploadHint] = useState("");
+  const inputRef = useRef(null);
+
+  const canUse = useMemo(() => Boolean(owner && repo), [owner, repo]);
+
+  async function loadAssets() {
+    if (!canUse) return;
+    setError("");
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/context/assets`);
+      if (!res.ok) throw new Error(`Failed to list assets (${res.status})`);
+      const data = await res.json();
+      setAssets(data.assets || []);
+    } catch (e) {
+      setError(e?.message || "Failed to load assets");
+    }
+  }
+
+  useEffect(() => {
+    loadAssets();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [owner, repo]);
+
+  async function uploadFiles(fileList) {
+    if (!canUse) return;
+    const files = Array.from(fileList || []);
+    if (!files.length) return;
+
+    setBusy(true);
+    setError("");
+    setUploadHint(`Uploading ${files.length} file(s)...`);
+
+    try {
+      for (const f of files) {
+        const form = new FormData();
+        form.append("file", f);
+
+        const res = await fetch(
+          `/api/repos/${owner}/${repo}/context/assets/upload`,
+          { method: "POST", body: form }
+        );
+        if (!res.ok) {
+          const txt = await res.text().catch(() => "");
+          throw new Error(`Upload failed (${res.status}) ${txt}`);
+        }
+      }
+      setUploadHint("Upload complete. Refreshing list...");
+      await loadAssets();
+      setUploadHint("");
+    } catch (e) {
+      setError(e?.message || "Upload failed");
+      setUploadHint("");
+    } finally {
+      setBusy(false);
+      if (inputRef.current) inputRef.current.value = "";
+    }
+  }
+
+  async function deleteAsset(assetId) {
+    if (!canUse) return;
+    const ok = window.confirm("Delete this asset? This cannot be undone.");
+    if (!ok) return;
+
+    setBusy(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/repos/${owner}/${repo}/context/assets/${assetId}`,
+        { method: "DELETE" }
+      );
+      if (!res.ok) throw new Error(`Delete failed (${res.status})`);
+      await loadAssets();
+    } catch (e) {
+      setError(e?.message || "Delete failed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  function downloadAsset(assetId) {
+    if (!canUse) return;
+    window.open(
+      `/api/repos/${owner}/${repo}/context/assets/${assetId}/download`,
+      "_blank"
+    );
+  }
+
+  const empty = !assets || assets.length === 0;
+
+  return (
+    <div style={styles.wrap}>
+      <div style={styles.topRow}>
+        <div style={styles.left}>
+          <div style={styles.h1}>Project Context</div>
+          <div style={styles.h2}>
+            Upload documents, transcripts, screenshots, etc. (non-destructive,
+            additive).
+          </div>
+        </div>
+
+        <div style={styles.right}>
+          <input
+            ref={inputRef}
+            type="file"
+            multiple
+            disabled={!canUse || busy}
+            onChange={(e) => uploadFiles(e.target.files)}
+            style={styles.fileInput}
+          />
+          <button
+            style={styles.btn}
+            disabled={!canUse || busy}
+            onClick={() => inputRef.current?.click()}
+          >
+            Upload
+          </button>
+          <button
+            style={styles.btn}
+            disabled={!canUse || busy}
+            onClick={loadAssets}
+          >
+            Refresh
+          </button>
+        </div>
+      </div>
+
+      <div
+        style={styles.dropzone}
+        onDragOver={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+        }}
+        onDrop={(e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          if (busy) return;
+          uploadFiles(e.dataTransfer.files);
+        }}
+      >
+        <div style={styles.dropText}>
+          Drag & drop files here, or click <b>Upload</b>.
+        </div>
+        <div style={styles.dropSub}>
+          Tip: For audio/video, upload a transcript file too.
+        </div>
+      </div>
+
+      {uploadHint ? <div style={styles.hint}>{uploadHint}</div> : null}
+      {error ? <div style={styles.error}>{error}</div> : null}
+
+      <div style={styles.tableWrap}>
+        <div style={styles.tableHeader}>
+          <div style={{ ...styles.col, ...styles.colName }}>File</div>
+          <div style={{ ...styles.col, ...styles.colMeta }}>Type</div>
+          <div style={{ ...styles.col, ...styles.colMeta }}>Size</div>
+          <div style={{ ...styles.col, ...styles.colMeta }}>Indexed</div>
+          <div style={{ ...styles.col, ...styles.colActions }}>Actions</div>
+        </div>
+
+        {empty ? (
+          <div style={styles.empty}>
+            No context assets yet. Upload docs, transcripts, and screenshots to
+            improve planning quality.
+          </div>
+        ) : (
+          assets.map((a) => (
+            <div key={a.asset_id} style={styles.row}>
+              <div style={{ ...styles.col, ...styles.colName }}>
+                <div style={styles.fileName}>{a.filename}</div>
+                <div style={styles.small}>
+                  Added: {a.created_at || "-"} | Extracted:{" "}
+                  {Number(a.extracted_chars || 0).toLocaleString()} chars
+                </div>
+              </div>
+
+              <div style={{ ...styles.col, ...styles.colMeta }}>
+                <span style={styles.badge}>{a.mime || "unknown"}</span>
+              </div>
+
+              <div style={{ ...styles.col, ...styles.colMeta }}>
+                {formatBytes(a.size_bytes || 0)}
+              </div>
+
+              <div style={{ ...styles.col, ...styles.colMeta }}>
+                {a.indexed_chunks || 0} chunks
+              </div>
+
+              <div style={{ ...styles.col, ...styles.colActions }}>
+                <button
+                  style={styles.smallBtn}
+                  disabled={busy}
+                  onClick={() => downloadAsset(a.asset_id)}
+                >
+                  Download
+                </button>
+                <button
+                  style={{ ...styles.smallBtn, ...styles.dangerBtn }}
+                  disabled={busy}
+                  onClick={() => deleteAsset(a.asset_id)}
+                >
+                  Delete
+                </button>
+              </div>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
+
+function formatBytes(bytes) {
+  const b = Number(bytes || 0);
+  if (!b) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
+  let v = b;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i += 1;
+  }
+  return `${v.toFixed(v >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+const styles = {
+  wrap: { display: "flex", flexDirection: "column", gap: 12 },
+  topRow: {
+    display: "flex",
+    justifyContent: "space-between",
+    gap: 12,
+    alignItems: "flex-start",
+    flexWrap: "wrap",
+  },
+  left: { minWidth: 280 },
+  right: { display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap" },
+  h1: { fontSize: 14, fontWeight: 800, color: "#fff" },
+  h2: { fontSize: 12, color: "rgba(255,255,255,0.65)", marginTop: 4 },
+  fileInput: { display: "none" },
+  btn: {
+    background: "rgba(255,255,255,0.10)",
+    border: "1px solid rgba(255,255,255,0.18)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "8px 10px",
+    cursor: "pointer",
+    fontSize: 13,
+  },
+  dropzone: {
+    border: "1px dashed rgba(255,255,255,0.22)",
+    borderRadius: 12,
+    padding: 16,
+    background: "rgba(255,255,255,0.03)",
+  },
+  dropText: { color: "rgba(255,255,255,0.85)", fontSize: 13 },
+  dropSub: { color: "rgba(255,255,255,0.55)", fontSize: 12, marginTop: 6 },
+  hint: {
+    color: "rgba(255,255,255,0.75)",
+    fontSize: 12,
+    padding: "8px 10px",
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 10,
+    background: "rgba(255,255,255,0.03)",
+  },
+  error: {
+    color: "#ffb3b3",
+    fontSize: 12,
+    padding: "8px 10px",
+    border: "1px solid rgba(255,120,120,0.25)",
+    borderRadius: 10,
+    background: "rgba(255,80,80,0.08)",
+  },
+  tableWrap: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+  },
+  tableHeader: {
+    display: "grid",
+    gridTemplateColumns: "1.6fr 1fr 0.6fr 0.6fr 0.8fr",
+    gap: 0,
+    padding: "10px 12px",
+    background: "rgba(255,255,255,0.03)",
+    borderBottom: "1px solid rgba(255,255,255,0.10)",
+    fontSize: 12,
+    color: "rgba(255,255,255,0.65)",
+  },
+  row: {
+    display: "grid",
+    gridTemplateColumns: "1.6fr 1fr 0.6fr 0.6fr 0.8fr",
+    padding: "10px 12px",
+    borderBottom: "1px solid rgba(255,255,255,0.08)",
+    alignItems: "center",
+  },
+  col: { minWidth: 0 },
+  colName: {},
+  colMeta: { color: "rgba(255,255,255,0.75)", fontSize: 12 },
+  colActions: { display: "flex", gap: 8, justifyContent: "flex-end" },
+  fileName: {
+    color: "#fff",
+    fontSize: 13,
+    fontWeight: 700,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  small: {
+    color: "rgba(255,255,255,0.55)",
+    fontSize: 11,
+    marginTop: 4,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  badge: {
+    display: "inline-flex",
+    alignItems: "center",
+    padding: "2px 8px",
+    borderRadius: 999,
+    border: "1px solid rgba(255,255,255,0.16)",
+    background: "rgba(255,255,255,0.04)",
+    fontSize: 11,
+    color: "rgba(255,255,255,0.80)",
+    maxWidth: "100%",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  smallBtn: {
+    background: "rgba(255,255,255,0.08)",
+    border: "1px solid rgba(255,255,255,0.16)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "6px 8px",
+    cursor: "pointer",
+    fontSize: 12,
+  },
+  dangerBtn: {
+    border: "1px solid rgba(255,90,90,0.35)",
+    background: "rgba(255,90,90,0.10)",
+  },
+  empty: {
+    padding: 14,
+    color: "rgba(255,255,255,0.65)",
+    fontSize: 13,
+  },
+};

frontend/components/ProjectSettings/ConventionsTab.jsx

@@ -0,0 +1,151 @@
+import React, { useEffect, useMemo, useState } from "react";
+
+export default function ConventionsTab({ owner, repo }) {
+  const [content, setContent] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  const canUse = useMemo(() => Boolean(owner && repo), [owner, repo]);
+
+  async function load() {
+    if (!canUse) return;
+    setError("");
+    setBusy(true);
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/context`);
+      if (!res.ok) throw new Error(`Failed to load conventions (${res.status})`);
+      const data = await res.json();
+      // backend may return { context: "..."} or { conventions: "..."} depending on implementation
+      setContent(data.context || data.conventions || data.memory || data.text || "");
+    } catch (e) {
+      setError(e?.message || "Failed to load conventions");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function initialize() {
+    if (!canUse) return;
+    setError("");
+    setBusy(true);
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/context/init`, {
+        method: "POST",
+      });
+      if (!res.ok) {
+        const txt = await res.text().catch(() => "");
+        throw new Error(`Init failed (${res.status}) ${txt}`);
+      }
+      await load();
+    } catch (e) {
+      setError(e?.message || "Init failed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  useEffect(() => {
+    load();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [owner, repo]);
+
+  return (
+    <div style={styles.wrap}>
+      <div style={styles.topRow}>
+        <div>
+          <div style={styles.h1}>Project Conventions</div>
+          <div style={styles.h2}>
+            This is the project memory/conventions file used by GitPilot.
+          </div>
+        </div>
+        <div style={styles.actions}>
+          <button style={styles.btn} disabled={!canUse || busy} onClick={load}>
+            Refresh
+          </button>
+          <button
+            style={styles.btn}
+            disabled={!canUse || busy}
+            onClick={initialize}
+          >
+            Initialize
+          </button>
+        </div>
+      </div>
+
+      {error ? <div style={styles.error}>{error}</div> : null}
+
+      <div style={styles.box}>
+        {content ? (
+          <pre style={styles.pre}>{content}</pre>
+        ) : (
+          <div style={styles.empty}>
+            No conventions found yet. Click <b>Initialize</b> to create default
+            project memory if supported.
+          </div>
+        )}
+      </div>
+
+      <div style={styles.note}>
+        Editing conventions is intentionally not included here to keep this
+        feature additive/non-destructive. You can extend this later with an
+        explicit &quot;Edit&quot; mode.
+      </div>
+    </div>
+  );
+}
+
+const styles = {
+  wrap: { display: "flex", flexDirection: "column", gap: 12 },
+  topRow: {
+    display: "flex",
+    justifyContent: "space-between",
+    gap: 12,
+    alignItems: "flex-start",
+    flexWrap: "wrap",
+  },
+  actions: { display: "flex", gap: 8, flexWrap: "wrap" },
+  h1: { fontSize: 14, fontWeight: 800, color: "#fff" },
+  h2: { fontSize: 12, color: "rgba(255,255,255,0.65)", marginTop: 4 },
+  btn: {
+    background: "rgba(255,255,255,0.10)",
+    border: "1px solid rgba(255,255,255,0.18)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "8px 10px",
+    cursor: "pointer",
+    fontSize: 13,
+  },
+  error: {
+    color: "#ffb3b3",
+    fontSize: 12,
+    padding: "8px 10px",
+    border: "1px solid rgba(255,120,120,0.25)",
+    borderRadius: 10,
+    background: "rgba(255,80,80,0.08)",
+  },
+  box: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+    background: "rgba(0,0,0,0.22)",
+  },
+  pre: {
+    margin: 0,
+    padding: 12,
+    color: "rgba(255,255,255,0.85)",
+    fontSize: 12,
+    lineHeight: 1.35,
+    whiteSpace: "pre-wrap",
+    overflow: "auto",
+    maxHeight: 520,
+  },
+  empty: {
+    padding: 12,
+    color: "rgba(255,255,255,0.65)",
+    fontSize: 13,
+  },
+  note: {
+    color: "rgba(255,255,255,0.55)",
+    fontSize: 12,
+  },
+};

frontend/components/ProjectSettings/UseCaseTab.jsx

@@ -0,0 +1,637 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+
+export default function UseCaseTab({ owner, repo }) {
+  const [useCases, setUseCases] = useState([]);
+  const [selectedId, setSelectedId] = useState("");
+  const [useCase, setUseCase] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [draftTitle, setDraftTitle] = useState("New Use Case");
+  const [message, setMessage] = useState("");
+  const messagesEndRef = useRef(null);
+
+  const canUse = useMemo(() => Boolean(owner && repo), [owner, repo]);
+  const spec = useCase?.spec || {};
+
+  function scrollToBottom() {
+    requestAnimationFrame(() => {
+      messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+    });
+  }
+
+  async function loadUseCases() {
+    if (!canUse) return;
+    setError("");
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/use-cases`);
+      if (!res.ok) throw new Error(`Failed to list use cases (${res.status})`);
+      const data = await res.json();
+      const list = data.use_cases || [];
+      setUseCases(list);
+
+      // auto select active or first
+      const active = list.find((x) => x.is_active);
+      const nextId = active?.use_case_id || list[0]?.use_case_id || "";
+      if (!selectedId && nextId) setSelectedId(nextId);
+    } catch (e) {
+      setError(e?.message || "Failed to load use cases");
+    }
+  }
+
+  async function loadUseCase(id) {
+    if (!canUse || !id) return;
+    setError("");
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/use-cases/${id}`);
+      if (!res.ok) throw new Error(`Failed to load use case (${res.status})`);
+      const data = await res.json();
+      setUseCase(data.use_case || null);
+      scrollToBottom();
+    } catch (e) {
+      setError(e?.message || "Failed to load use case");
+    }
+  }
+
+  useEffect(() => {
+    loadUseCases();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [owner, repo]);
+
+  useEffect(() => {
+    if (!selectedId) return;
+    loadUseCase(selectedId);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedId]);
+
+  async function createUseCase() {
+    if (!canUse) return;
+    setBusy(true);
+    setError("");
+    try {
+      const res = await fetch(`/api/repos/${owner}/${repo}/use-cases`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ title: draftTitle || "New Use Case" }),
+      });
+      if (!res.ok) {
+        const txt = await res.text().catch(() => "");
+        throw new Error(`Create failed (${res.status}) ${txt}`);
+      }
+      const data = await res.json();
+      const id = data?.use_case?.use_case_id;
+      await loadUseCases();
+      if (id) setSelectedId(id);
+      setDraftTitle("New Use Case");
+    } catch (e) {
+      setError(e?.message || "Create failed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function sendMessage() {
+    if (!canUse || !selectedId) return;
+    const msg = (message || "").trim();
+    if (!msg) return;
+
+    setBusy(true);
+    setError("");
+
+    // optimistic UI: append user message immediately
+    setUseCase((prev) => {
+      if (!prev) return prev;
+      const next = { ...prev };
+      next.messages = Array.isArray(next.messages) ? [...next.messages] : [];
+      next.messages.push({ role: "user", content: msg, ts: new Date().toISOString() });
+      return next;
+    });
+    setMessage("");
+    scrollToBottom();
+
+    try {
+      const res = await fetch(
+        `/api/repos/${owner}/${repo}/use-cases/${selectedId}/chat`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ message: msg }),
+        }
+      );
+      if (!res.ok) {
+        const txt = await res.text().catch(() => "");
+        throw new Error(`Chat failed (${res.status}) ${txt}`);
+      }
+      const data = await res.json();
+      setUseCase(data.use_case || null);
+      await loadUseCases();
+      scrollToBottom();
+    } catch (e) {
+      setError(e?.message || "Chat failed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function finalizeUseCase() {
+    if (!canUse || !selectedId) return;
+    setBusy(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/repos/${owner}/${repo}/use-cases/${selectedId}/finalize`,
+        { method: "POST" }
+      );
+      if (!res.ok) {
+        const txt = await res.text().catch(() => "");
+        throw new Error(`Finalize failed (${res.status}) ${txt}`);
+      }
+      const data = await res.json();
+      setUseCase(data.use_case || null);
+      await loadUseCases();
+      alert(
+        "Use Case finalized and marked active.\n\nA Markdown export was saved in the repo workspace .gitpilot/context/use_cases/."
+      );
+    } catch (e) {
+      setError(e?.message || "Finalize failed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const activeId = useCases.find((x) => x.is_active)?.use_case_id;
+
+  return (
+    <div style={styles.wrap}>
+      <div style={styles.topRow}>
+        <div style={styles.left}>
+          <div style={styles.h1}>Use Case</div>
+          <div style={styles.h2}>
+            Guided chat to clarify requirements and produce a versioned spec.
+          </div>
+        </div>
+
+        <div style={styles.right}>
+          <input
+            value={draftTitle}
+            onChange={(e) => setDraftTitle(e.target.value)}
+            placeholder="New use case title..."
+            style={styles.titleInput}
+            disabled={!canUse || busy}
+          />
+          <button
+            style={styles.btn}
+            onClick={createUseCase}
+            disabled={!canUse || busy}
+          >
+            New
+          </button>
+          <button
+            style={styles.btn}
+            onClick={finalizeUseCase}
+            disabled={!canUse || busy || !selectedId}
+          >
+            Finalize
+          </button>
+          <button
+            style={styles.btn}
+            onClick={loadUseCases}
+            disabled={!canUse || busy}
+          >
+            Refresh
+          </button>
+        </div>
+      </div>
+
+      {error ? <div style={styles.error}>{error}</div> : null}
+
+      <div style={styles.grid}>
+        <div style={styles.sidebar}>
+          <div style={styles.sidebarTitle}>Use Cases</div>
+          <div style={styles.sidebarList}>
+            {useCases.length === 0 ? (
+              <div style={styles.sidebarEmpty}>
+                No use cases yet. Create one with <b>New</b>.
+              </div>
+            ) : (
+              useCases.map((uc) => (
+                <button
+                  key={uc.use_case_id}
+                  style={{
+                    ...styles.ucItem,
+                    ...(selectedId === uc.use_case_id ? styles.ucItemActive : {}),
+                  }}
+                  onClick={() => setSelectedId(uc.use_case_id)}
+                >
+                  <div style={styles.ucTitleRow}>
+                    <div style={styles.ucTitle}>
+                      {uc.title || "(untitled)"}
+                    </div>
+                    {uc.use_case_id === activeId ? (
+                      <span style={styles.activePill}>ACTIVE</span>
+                    ) : null}
+                  </div>
+                  <div style={styles.ucMeta}>
+                    Updated: {uc.updated_at || uc.created_at || "-"}
+                  </div>
+                </button>
+              ))
+            )}
+          </div>
+        </div>
+
+        <div style={styles.chatCol}>
+          <div style={styles.panelTitle}>Guided Chat</div>
+          <div style={styles.chatBox}>
+            {Array.isArray(useCase?.messages) && useCase.messages.length ? (
+              useCase.messages.map((m, idx) => (
+                <div
+                  key={idx}
+                  style={{
+                    ...styles.msg,
+                    ...(m.role === "user" ? styles.msgUser : styles.msgAsst),
+                  }}
+                >
+                  <div style={styles.msgRole}>
+                    {m.role === "user" ? "You" : "Assistant"}
+                  </div>
+                  <div style={styles.msgContent}>{m.content}</div>
+                </div>
+              ))
+            ) : (
+              <div style={styles.chatEmpty}>
+                Select a use case and start chatting. You can paste structured
+                info like:
+                <pre style={styles.pre}>
+{`Summary: ...
+Problem: ...
+Users: ...
+Requirements:
+- ...
+Acceptance Criteria:
+- ...`}
+                </pre>
+              </div>
+            )}
+            <div ref={messagesEndRef} />
+          </div>
+
+          <div style={styles.composer}>
+            <textarea
+              value={message}
+              onChange={(e) => setMessage(e.target.value)}
+              placeholder="Type your answer... (Shift+Enter for newline)"
+              style={styles.textarea}
+              disabled={!canUse || busy || !selectedId}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  sendMessage();
+                }
+              }}
+            />
+            <button
+              style={styles.sendBtn}
+              disabled={!canUse || busy || !selectedId}
+              onClick={sendMessage}
+            >
+              Send
+            </button>
+          </div>
+        </div>
+
+        <div style={styles.specCol}>
+          <div style={styles.panelTitle}>Spec Preview</div>
+          <div style={styles.specBox}>
+            <Section title="Title" value={spec.title || useCase?.title || ""} />
+            <Section title="Summary" value={spec.summary || ""} />
+            <Section title="Problem" value={spec.problem || ""} />
+            <Section title="Users / Personas" value={spec.users || ""} />
+            <ListSection title="Requirements" items={spec.requirements || []} />
+            <ListSection
+              title="Acceptance Criteria"
+              items={spec.acceptance_criteria || []}
+            />
+            <ListSection title="Constraints" items={spec.constraints || []} />
+            <ListSection title="Open Questions" items={spec.open_questions || []} />
+            <Section title="Notes" value={spec.notes || ""} />
+          </div>
+
+          <div style={styles.specFooter}>
+            <div style={styles.specHint}>
+              Finalize will save a Markdown spec and mark it ACTIVE for context.
+            </div>
+            <button
+              style={styles.primaryBtn}
+              disabled={!canUse || busy || !selectedId}
+              onClick={finalizeUseCase}
+            >
+              Finalize Spec
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Section({ title, value }) {
+  return (
+    <div style={styles.section}>
+      <div style={styles.sectionTitle}>{title}</div>
+      <div style={styles.sectionBody}>
+        {String(value || "").trim() ? (
+          <div style={styles.sectionText}>{value}</div>
+        ) : (
+          <div style={styles.sectionEmpty}>(empty)</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function ListSection({ title, items }) {
+  const list = Array.isArray(items) ? items : [];
+  return (
+    <div style={styles.section}>
+      <div style={styles.sectionTitle}>{title}</div>
+      <div style={styles.sectionBody}>
+        {list.length ? (
+          <ul style={styles.ul}>
+            {list.map((x, i) => (
+              <li key={i} style={styles.li}>
+                {x}
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <div style={styles.sectionEmpty}>(empty)</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const styles = {
+  wrap: { display: "flex", flexDirection: "column", gap: 12 },
+  topRow: {
+    display: "flex",
+    justifyContent: "space-between",
+    gap: 12,
+    alignItems: "flex-start",
+    flexWrap: "wrap",
+  },
+  left: { minWidth: 280 },
+  right: { display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap" },
+  h1: { fontSize: 14, fontWeight: 800, color: "#fff" },
+  h2: { fontSize: 12, color: "rgba(255,255,255,0.65)", marginTop: 4 },
+  titleInput: {
+    width: 260,
+    maxWidth: "70vw",
+    padding: "8px 10px",
+    borderRadius: 10,
+    border: "1px solid rgba(255,255,255,0.18)",
+    background: "rgba(0,0,0,0.25)",
+    color: "#fff",
+    fontSize: 13,
+    outline: "none",
+  },
+  btn: {
+    background: "rgba(255,255,255,0.10)",
+    border: "1px solid rgba(255,255,255,0.18)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "8px 10px",
+    cursor: "pointer",
+    fontSize: 13,
+  },
+  primaryBtn: {
+    background: "rgba(255,255,255,0.12)",
+    border: "1px solid rgba(255,255,255,0.22)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "8px 12px",
+    cursor: "pointer",
+    fontSize: 13,
+    fontWeight: 700,
+  },
+  error: {
+    color: "#ffb3b3",
+    fontSize: 12,
+    padding: "8px 10px",
+    border: "1px solid rgba(255,120,120,0.25)",
+    borderRadius: 10,
+    background: "rgba(255,80,80,0.08)",
+  },
+  grid: {
+    display: "grid",
+    gridTemplateColumns: "300px 1.2fr 0.9fr",
+    gap: 12,
+    alignItems: "stretch",
+  },
+  sidebar: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+    background: "rgba(255,255,255,0.02)",
+    display: "flex",
+    flexDirection: "column",
+    minHeight: 520,
+  },
+  sidebarTitle: {
+    padding: 10,
+    borderBottom: "1px solid rgba(255,255,255,0.10)",
+    fontSize: 12,
+    fontWeight: 800,
+    color: "rgba(255,255,255,0.85)",
+  },
+  sidebarList: {
+    padding: 8,
+    display: "flex",
+    flexDirection: "column",
+    gap: 8,
+    overflow: "auto",
+  },
+  sidebarEmpty: {
+    color: "rgba(255,255,255,0.65)",
+    fontSize: 12,
+    padding: 8,
+  },
+  ucItem: {
+    textAlign: "left",
+    background: "rgba(0,0,0,0.25)",
+    border: "1px solid rgba(255,255,255,0.12)",
+    color: "#fff",
+    borderRadius: 12,
+    padding: 10,
+    cursor: "pointer",
+  },
+  ucItemActive: {
+    border: "1px solid rgba(255,255,255,0.25)",
+    background: "rgba(255,255,255,0.06)",
+  },
+  ucTitleRow: { display: "flex", alignItems: "center", gap: 8 },
+  ucTitle: {
+    fontSize: 13,
+    fontWeight: 800,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+    flex: 1,
+  },
+  activePill: {
+    fontSize: 10,
+    fontWeight: 800,
+    padding: "2px 8px",
+    borderRadius: 999,
+    border: "1px solid rgba(120,255,180,0.30)",
+    background: "rgba(120,255,180,0.10)",
+    color: "rgba(200,255,220,0.95)",
+  },
+  ucMeta: {
+    marginTop: 6,
+    fontSize: 11,
+    color: "rgba(255,255,255,0.60)",
+  },
+  chatCol: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+    display: "flex",
+    flexDirection: "column",
+    background: "rgba(255,255,255,0.02)",
+    minHeight: 520,
+  },
+  specCol: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+    display: "flex",
+    flexDirection: "column",
+    background: "rgba(255,255,255,0.02)",
+    minHeight: 520,
+  },
+  panelTitle: {
+    padding: 10,
+    borderBottom: "1px solid rgba(255,255,255,0.10)",
+    fontSize: 12,
+    fontWeight: 800,
+    color: "rgba(255,255,255,0.85)",
+  },
+  chatBox: {
+    flex: 1,
+    overflow: "auto",
+    padding: 10,
+    display: "flex",
+    flexDirection: "column",
+    gap: 10,
+  },
+  chatEmpty: {
+    color: "rgba(255,255,255,0.65)",
+    fontSize: 12,
+    padding: 6,
+  },
+  pre: {
+    marginTop: 10,
+    padding: 10,
+    borderRadius: 10,
+    border: "1px solid rgba(255,255,255,0.12)",
+    background: "rgba(0,0,0,0.25)",
+    color: "rgba(255,255,255,0.8)",
+    overflow: "auto",
+    fontSize: 11,
+  },
+  msg: {
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    padding: 10,
+    background: "rgba(0,0,0,0.25)",
+  },
+  msgUser: {
+    border: "1px solid rgba(255,255,255,0.18)",
+    background: "rgba(255,255,255,0.04)",
+  },
+  msgAsst: {},
+  msgRole: {
+    fontSize: 11,
+    fontWeight: 800,
+    color: "rgba(255,255,255,0.70)",
+    marginBottom: 6,
+  },
+  msgContent: {
+    whiteSpace: "pre-wrap",
+    fontSize: 13,
+    color: "rgba(255,255,255,0.90)",
+    lineHeight: 1.35,
+  },
+  composer: {
+    borderTop: "1px solid rgba(255,255,255,0.10)",
+    padding: 10,
+    display: "flex",
+    gap: 10,
+    alignItems: "flex-end",
+  },
+  textarea: {
+    flex: 1,
+    minHeight: 52,
+    maxHeight: 120,
+    resize: "vertical",
+    padding: 10,
+    borderRadius: 12,
+    border: "1px solid rgba(255,255,255,0.18)",
+    background: "rgba(0,0,0,0.25)",
+    color: "#fff",
+    fontSize: 13,
+    outline: "none",
+  },
+  sendBtn: {
+    background: "rgba(255,255,255,0.12)",
+    border: "1px solid rgba(255,255,255,0.22)",
+    color: "#fff",
+    borderRadius: 12,
+    padding: "10px 12px",
+    cursor: "pointer",
+    fontSize: 13,
+    fontWeight: 800,
+  },
+  specBox: {
+    flex: 1,
+    overflow: "auto",
+    padding: 10,
+    display: "flex",
+    flexDirection: "column",
+    gap: 10,
+  },
+  specFooter: {
+    borderTop: "1px solid rgba(255,255,255,0.10)",
+    padding: 10,
+    display: "flex",
+    gap: 10,
+    alignItems: "center",
+    justifyContent: "space-between",
+  },
+  specHint: { fontSize: 12, color: "rgba(255,255,255,0.60)" },
+  section: {
+    border: "1px solid rgba(255,255,255,0.10)",
+    borderRadius: 12,
+    background: "rgba(0,0,0,0.22)",
+    overflow: "hidden",
+  },
+  sectionTitle: {
+    padding: "8px 10px",
+    borderBottom: "1px solid rgba(255,255,255,0.08)",
+    fontSize: 12,
+    fontWeight: 800,
+    color: "rgba(255,255,255,0.80)",
+    background: "rgba(255,255,255,0.02)",
+  },
+  sectionBody: { padding: "8px 10px" },
+  sectionText: {
+    whiteSpace: "pre-wrap",
+    fontSize: 12,
+    color: "rgba(255,255,255,0.90)",
+    lineHeight: 1.35,
+  },
+  sectionEmpty: { fontSize: 12, color: "rgba(255,255,255,0.45)" },
+  ul: { margin: 0, paddingLeft: 18 },
+  li: { color: "rgba(255,255,255,0.90)", fontSize: 12, lineHeight: 1.35 },
+};

frontend/components/ProjectSettingsModal.jsx

@@ -0,0 +1,230 @@
+import React, { useEffect, useMemo, useState } from "react";
+import ContextTab from "./ProjectSettings/ContextTab.jsx";
+import UseCaseTab from "./ProjectSettings/UseCaseTab.jsx";
+import ConventionsTab from "./ProjectSettings/ConventionsTab.jsx";
+import EnvironmentSelector from "./EnvironmentSelector.jsx";
+
+export default function ProjectSettingsModal({
+  owner,
+  repo,
+  isOpen,
+  onClose,
+  activeEnvId,
+  onEnvChange,
+}) {
+  const [activeTab, setActiveTab] = useState("context");
+
+  useEffect(() => {
+    if (!isOpen) return;
+    // reset to Context each time opened (safe default)
+    setActiveTab("context");
+  }, [isOpen]);
+
+  const title = useMemo(() => {
+    const repoLabel = owner && repo ? `${owner}/${repo}` : "Project";
+    return `Project Settings — ${repoLabel}`;
+  }, [owner, repo]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      style={styles.backdrop}
+      onMouseDown={(e) => {
+        // click outside closes
+        if (e.target === e.currentTarget) onClose?.();
+      }}
+    >
+      <div style={styles.modal} onMouseDown={(e) => e.stopPropagation()}>
+        <div style={styles.header}>
+          <div style={styles.headerLeft}>
+            <div style={styles.title}>{title}</div>
+            <div style={styles.subtitle}>
+              Manage context, use cases, and project conventions (additive only).
+            </div>
+          </div>
+          <button style={styles.closeBtn} onClick={onClose}>
+            ✕
+          </button>
+        </div>
+
+        <div style={styles.tabsRow}>
+          <TabButton
+            label="Context"
+            isActive={activeTab === "context"}
+            onClick={() => setActiveTab("context")}
+          />
+          <TabButton
+            label="Use Case"
+            isActive={activeTab === "usecase"}
+            onClick={() => setActiveTab("usecase")}
+          />
+          <TabButton
+            label="Conventions"
+            isActive={activeTab === "conventions"}
+            onClick={() => setActiveTab("conventions")}
+          />
+          <TabButton
+            label="Environment"
+            isActive={activeTab === "environment"}
+            onClick={() => setActiveTab("environment")}
+          />
+        </div>
+
+        <div style={styles.body}>
+          {activeTab === "context" && <ContextTab owner={owner} repo={repo} />}
+          {activeTab === "usecase" && <UseCaseTab owner={owner} repo={repo} />}
+          {activeTab === "conventions" && (
+            <ConventionsTab owner={owner} repo={repo} />
+          )}
+          {activeTab === "environment" && (
+            <div style={{ maxWidth: 480 }}>
+              <div style={{ marginBottom: 12, fontSize: 13, color: "rgba(255,255,255,0.65)" }}>
+                Select and configure the execution environment for agent operations.
+              </div>
+              <EnvironmentSelector
+                activeEnvId={activeEnvId}
+                onEnvChange={onEnvChange}
+              />
+            </div>
+          )}
+        </div>
+
+        <div style={styles.footer}>
+          <div style={styles.footerHint}>
+            Tip: Upload meeting notes/transcripts in Context, then finalize a Use
+            Case spec.
+          </div>
+          <button style={styles.primaryBtn} onClick={onClose}>
+            Done
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function TabButton({ label, isActive, onClick }) {
+  return (
+    <button
+      onClick={onClick}
+      style={{
+        ...styles.tabBtn,
+        ...(isActive ? styles.tabBtnActive : {}),
+      }}
+    >
+      {label}
+    </button>
+  );
+}
+
+const styles = {
+  backdrop: {
+    position: "fixed",
+    inset: 0,
+    background: "rgba(0,0,0,0.45)",
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "center",
+    zIndex: 9999,
+    padding: 16,
+  },
+  modal: {
+    width: "min(1100px, 96vw)",
+    height: "min(760px, 90vh)",
+    background: "#111",
+    border: "1px solid rgba(255,255,255,0.12)",
+    borderRadius: 12,
+    overflow: "hidden",
+    display: "flex",
+    flexDirection: "column",
+    boxShadow: "0 12px 40px rgba(0,0,0,0.35)",
+  },
+  header: {
+    padding: "14px 14px 10px",
+    display: "flex",
+    gap: 12,
+    alignItems: "flex-start",
+    justifyContent: "space-between",
+    borderBottom: "1px solid rgba(255,255,255,0.10)",
+    background: "linear-gradient(180deg, rgba(255,255,255,0.04), transparent)",
+  },
+  headerLeft: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 4,
+    minWidth: 0,
+  },
+  title: {
+    fontSize: 16,
+    fontWeight: 700,
+    color: "#fff",
+    lineHeight: 1.2,
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    maxWidth: "88vw",
+  },
+  subtitle: {
+    fontSize: 12,
+    color: "rgba(255,255,255,0.65)",
+  },
+  closeBtn: {
+    background: "transparent",
+    border: "1px solid rgba(255,255,255,0.18)",
+    color: "rgba(255,255,255,0.85)",
+    borderRadius: 10,
+    padding: "6px 10px",
+    cursor: "pointer",
+  },
+  tabsRow: {
+    display: "flex",
+    gap: 8,
+    padding: 10,
+    borderBottom: "1px solid rgba(255,255,255,0.10)",
+    background: "rgba(255,255,255,0.02)",
+  },
+  tabBtn: {
+    background: "transparent",
+    border: "1px solid rgba(255,255,255,0.14)",
+    color: "rgba(255,255,255,0.75)",
+    borderRadius: 999,
+    padding: "8px 12px",
+    cursor: "pointer",
+    fontSize: 13,
+  },
+  tabBtnActive: {
+    border: "1px solid rgba(255,255,255,0.28)",
+    color: "#fff",
+    background: "rgba(255,255,255,0.06)",
+  },
+  body: {
+    flex: 1,
+    overflow: "auto",
+    padding: 12,
+  },
+  footer: {
+    padding: 12,
+    borderTop: "1px solid rgba(255,255,255,0.10)",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: 12,
+    background: "rgba(255,255,255,0.02)",
+  },
+  footerHint: {
+    color: "rgba(255,255,255,0.6)",
+    fontSize: 12,
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  },
+  primaryBtn: {
+    background: "rgba(255,255,255,0.10)",
+    border: "1px solid rgba(255,255,255,0.20)",
+    color: "#fff",
+    borderRadius: 10,
+    padding: "8px 12px",
+    cursor: "pointer",
+  },
+};

frontend/components/RepoSelector.jsx

@@ -0,0 +1,269 @@
+import React, { useEffect, useState, useCallback } from "react";
+import { authFetch } from "../utils/api.js";
+
+export default function RepoSelector({ onSelect }) {
+  const [query, setQuery] = useState("");
+  const [repos, setRepos] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [status, setStatus] = useState("");
+  const [page, setPage] = useState(1);
+  const [hasMore, setHasMore] = useState(false);
+  const [totalCount, setTotalCount] = useState(null);
+
+  /**
+   * Fetch repositories with pagination and optional search
+   * @param {number} pageNum - Page number to fetch
+   * @param {boolean} append - Whether to append or replace results
+   * @param {string} searchQuery - Search query (uses current query if not provided)
+   */
+  const fetchRepos = useCallback(async (pageNum = 1, append = false, searchQuery = query) => {
+    // Set appropriate loading state
+    if (pageNum === 1) {
+      setLoading(true);
+      setStatus("");
+    } else {
+      setLoadingMore(true);
+    }
+
+    try {
+      // Build URL with query parameters
+      const params = new URLSearchParams();
+      params.append("page", pageNum);
+      params.append("per_page", "100");
+      if (searchQuery) {
+        params.append("query", searchQuery);
+      }
+
+      const url = `/api/repos?${params.toString()}`;
+      const res = await authFetch(url);
+      const data = await res.json();
+
+      if (!res.ok) {
+        throw new Error(data.detail || data.error || "Failed to load repositories");
+      }
+
+      // Update repositories - append or replace
+      if (append) {
+        setRepos((prev) => [...prev, ...data.repositories]);
+      } else {
+        setRepos(data.repositories);
+      }
+
+      // Update pagination state
+      setPage(pageNum);
+      setHasMore(data.has_more);
+      setTotalCount(data.total_count);
+
+      // Show status if no results
+      if (!append && data.repositories.length === 0) {
+        if (searchQuery) {
+          setStatus(`No repositories matching "${searchQuery}"`);
+        } else {
+          setStatus("No repositories found");
+        }
+      } else {
+        setStatus("");
+      }
+    } catch (err) {
+      console.error("Error fetching repositories:", err);
+      setStatus(err.message || "Failed to load repositories");
+    } finally {
+      setLoading(false);
+      setLoadingMore(false);
+    }
+  }, [query]);
+
+  /**
+   * Load more repositories (next page)
+   */
+  const loadMore = () => {
+    fetchRepos(page + 1, true);
+  };
+
+  /**
+   * Handle search - resets to page 1
+   */
+  const handleSearch = () => {
+    setPage(1);
+    fetchRepos(1, false, query);
+  };
+
+  /**
+   * Handle input change - trigger search on Enter key
+   */
+  const handleKeyDown = (e) => {
+    if (e.key === "Enter") {
+      handleSearch();
+    }
+  };
+
+  /**
+   * Clear search and show all repos
+   */
+  const clearSearch = () => {
+    setQuery("");
+    setPage(1);
+    fetchRepos(1, false, "");
+  };
+
+  // Initial load on mount
+  useEffect(() => {
+    fetchRepos(1, false, "");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /**
+   * Format repository count for display
+   */
+  const getCountText = () => {
+    if (totalCount !== null) {
+      // Search mode - show filtered count
+      return `${repos.length} of ${totalCount} repositories`;
+    } else {
+      // Pagination mode - show loaded count
+      return `${repos.length} ${repos.length === 1 ? "repository" : "repositories"}${hasMore ? "+" : ""}`;
+    }
+  };
+
+  return (
+    <div className="repo-search-box">
+      <div style={{ fontSize: "11px", opacity: 0.6, padding: "4px 8px", marginBottom: "8px" }}>
+        GitHub repos are optional. Use Folder or Local Git mode for local-first workflows.
+      </div>
+      {/* Search Header */}
+      <div className="repo-search-header">
+        <div className="repo-search-row">
+          <input
+            className="repo-search-input"
+            placeholder="Search repositories..."
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyDown}
+            disabled={loading}
+          />
+          <button
+            className="repo-search-btn"
+            onClick={handleSearch}
+            type="button"
+            disabled={loading}
+          >
+            {loading ? "..." : "Search"}
+          </button>
+        </div>
+
+        {/* Search Info Bar */}
+        {(query || repos.length > 0) && (
+          <div className="repo-info-bar">
+            <span className="repo-count">{getCountText()}</span>
+            {query && (
+              <button
+                className="repo-clear-btn"
+                onClick={clearSearch}
+                type="button"
+                disabled={loading}
+              >
+                Clear search
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+
+      {/* Status Message */}
+      {status && !loading && (
+        <div className="repo-status">
+          {status}
+        </div>
+      )}
+
+      {/* Repository List */}
+      <div className="repo-list">
+        {repos.map((r) => (
+          <button
+            key={r.id}
+            type="button"
+            className="repo-item"
+            onClick={() => onSelect(r)}
+          >
+            <div className="repo-item-content">
+              <span className="repo-name">{r.name}</span>
+              <span className="repo-owner">{r.owner}</span>
+            </div>
+            {r.private && (
+              <span className="repo-badge-private">Private</span>
+            )}
+          </button>
+        ))}
+
+        {/* Loading Indicator */}
+        {loading && repos.length === 0 && (
+          <div className="repo-loading">
+            <div className="repo-loading-spinner"></div>
+            <span>Loading repositories...</span>
+          </div>
+        )}
+
+        {/* Load More Button */}
+        {hasMore && !loading && repos.length > 0 && (
+          <button
+            type="button"
+            className="repo-load-more"
+            onClick={loadMore}
+            disabled={loadingMore}
+          >
+            {loadingMore ? (
+              <>
+                <div className="repo-loading-spinner-small"></div>
+                Loading more...
+              </>
+            ) : (
+              <>
+                Load more repositories
+                <span className="repo-load-more-count">({repos.length} loaded)</span>
+              </>
+            )}
+          </button>
+        )}
+
+        {/* All Loaded Message */}
+        {!hasMore && !loading && repos.length > 0 && (
+          <div className="repo-all-loaded">
+            ✓ All repositories loaded ({repos.length} total)
+          </div>
+        )}
+      </div>
+
+      {/* GitHub App Installation Notice */}
+      <div className="repo-github-notice">
+        <svg
+          className="repo-github-icon"
+          height="20"
+          width="20"
+          viewBox="0 0 16 16"
+          fill="currentColor"
+        >
+          <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+        </svg>
+
+        <div className="repo-github-notice-content">
+          <div className="repo-github-notice-title">
+            Repository missing?
+          </div>
+          <div className="repo-github-notice-text">
+            Install the{" "}
+            <a
+              href="https://github.com/apps/gitpilota"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="repo-github-link"
+            >
+              GitPilot GitHub App
+            </a>{" "}
+            to access private repositories.
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/components/SessionItem.jsx

@@ -0,0 +1,183 @@
+import React, { useState } from "react";
+
+/**
+ * SessionItem — a single row in the sessions sidebar.
+ *
+ * Shows status dot (pulsing/static), title, timestamp, message count.
+ * Claude-Code-on-Web parity: active=amber pulse, completed=green,
+ * failed=red, waiting=blue.
+ */
+export default function SessionItem({ session, isActive, onSelect, onDelete }) {
+  const [hovering, setHovering] = useState(false);
+
+  const status = session.status || "active";
+
+  const dotColor = {
+    active: "#F59E0B",
+    completed: "#10B981",
+    failed: "#EF4444",
+    waiting: "#3B82F6",
+    paused: "#6B7280",
+  }[status] || "#6B7280";
+
+  const isPulsing = status === "active";
+
+  const timeAgo = formatTimeAgo(session.updated_at);
+
+  // Prefer name (set from first user prompt) over generic fallback
+  const title =
+    session.name ||
+    (session.branch ? `${session.branch}` : `Session ${session.id?.slice(0, 8)}`);
+
+  return (
+    <div
+      style={{
+        ...styles.row,
+        backgroundColor: isActive
+          ? "rgba(59, 130, 246, 0.08)"
+          : hovering
+          ? "rgba(255,255,255,0.03)"
+          : "transparent",
+        borderLeft: isActive ? "2px solid #3B82F6" : "2px solid transparent",
+      }}
+      onClick={onSelect}
+      onMouseEnter={() => setHovering(true)}
+      onMouseLeave={() => setHovering(false)}
+    >
+      <style>{`
+        @keyframes session-pulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.4; }
+        }
+      `}</style>
+
+      {/* Status dot */}
+      <div
+        style={{
+          ...styles.dot,
+          backgroundColor: dotColor,
+          animation: isPulsing ? "session-pulse 1.5s ease-in-out infinite" : "none",
+        }}
+      />
+
+      {/* Content */}
+      <div style={styles.content}>
+        <div style={styles.title}>{title}</div>
+        <div style={styles.meta}>
+          {timeAgo}
+          {session.mode && (
+            <span style={{
+              ...styles.badge,
+              background: session.mode === "github" ? "#1e3a5f" : "#2d2d1f",
+              color: session.mode === "github" ? "#60a5fa" : "#d4d48a",
+            }}>
+              {session.mode === "github" ? "GH" : session.mode === "local-git" ? "Git" : "Dir"}
+            </span>
+          )}
+          {session.message_count > 0 && (
+            <span style={styles.badge}>{session.message_count} msgs</span>
+          )}
+        </div>
+      </div>
+
+      {/* Delete button (on hover) */}
+      {hovering && (
+        <button
+          type="button"
+          style={styles.deleteBtn}
+          onClick={(e) => {
+            e.stopPropagation();
+            onDelete?.();
+          }}
+          title="Delete session"
+        >
+          &times;
+        </button>
+      )}
+    </div>
+  );
+}
+
+function formatTimeAgo(isoStr) {
+  if (!isoStr) return "";
+  try {
+    const date = new Date(isoStr);
+    const now = new Date();
+    const diffMs = now - date;
+    const diffMin = Math.floor(diffMs / 60000);
+    if (diffMin < 1) return "just now";
+    if (diffMin < 60) return `${diffMin}m ago`;
+    const diffHr = Math.floor(diffMin / 60);
+    if (diffHr < 24) return `${diffHr}h ago`;
+    const diffDay = Math.floor(diffHr / 24);
+    return `${diffDay}d ago`;
+  } catch {
+    return "";
+  }
+}
+
+const styles = {
+  row: {
+    display: "flex",
+    alignItems: "center",
+    gap: 8,
+    padding: "8px 10px",
+    borderRadius: 6,
+    cursor: "pointer",
+    transition: "background-color 0.15s",
+    position: "relative",
+    marginBottom: 2,
+    animation: "session-fade-in 0.25s ease-out",
+  },
+  dot: {
+    width: 8,
+    height: 8,
+    borderRadius: "50%",
+    flexShrink: 0,
+  },
+  content: {
+    flex: 1,
+    minWidth: 0,
+    overflow: "hidden",
+  },
+  title: {
+    fontSize: 12,
+    fontWeight: 500,
+    color: "#E4E4E7",
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+  },
+  meta: {
+    fontSize: 10,
+    color: "#71717A",
+    marginTop: 2,
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+  },
+  badge: {
+    fontSize: 9,
+    background: "#27272A",
+    padding: "1px 5px",
+    borderRadius: 8,
+    color: "#A1A1AA",
+  },
+  deleteBtn: {
+    position: "absolute",
+    right: 6,
+    top: 6,
+    width: 18,
+    height: 18,
+    borderRadius: 3,
+    border: "none",
+    background: "rgba(239, 68, 68, 0.15)",
+    color: "#EF4444",
+    fontSize: 14,
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    lineHeight: 1,
+  },
+};

frontend/components/SessionSidebar.jsx

@@ -0,0 +1,181 @@
+import React, { useEffect, useRef, useState } from "react";
+import SessionItem from "./SessionItem.jsx";
+
+/**
+ * SessionSidebar — Claude-Code-on-Web parity.
+ *
+ * Shows a scrollable list of coding sessions with status indicators,
+ * timestamps, and a "New Session" button. Additive — does not modify
+ * any existing component.
+ */
+export default function SessionSidebar({
+  repo,
+  activeSessionId,
+  onSelectSession,
+  onNewSession,
+  onDeleteSession,
+  refreshNonce = 0,
+}) {
+  const [sessions, setSessions] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const pollRef = useRef(null);
+
+  const repoFullName = repo?.full_name || (repo ? `${repo.owner}/${repo.name}` : null);
+
+  // Fetch sessions
+  useEffect(() => {
+    if (!repoFullName) {
+      setSessions([]);
+      return;
+    }
+
+    let cancelled = false;
+
+    const fetchSessions = async () => {
+      setLoading(true);
+      try {
+        const token = localStorage.getItem("github_token");
+        const headers = token ? { Authorization: `Bearer ${token}` } : {};
+        const res = await fetch(`/api/sessions`, { headers, cache: "no-cache" });
+        if (!res.ok) return;
+        const data = await res.json();
+        if (cancelled) return;
+
+        // Filter to current repo
+        const filtered = (data.sessions || []).filter(
+          (s) => s.repo === repoFullName
+        );
+        setSessions(filtered);
+      } catch (err) {
+        console.warn("Failed to fetch sessions:", err);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+
+    fetchSessions();
+
+    // Poll every 15s for status updates
+    pollRef.current = setInterval(fetchSessions, 15000);
+
+    return () => {
+      cancelled = true;
+      if (pollRef.current) clearInterval(pollRef.current);
+    };
+  }, [repoFullName, refreshNonce]);
+
+  const handleDelete = async (sessionId) => {
+    try {
+      const token = localStorage.getItem("github_token");
+      const headers = token ? { Authorization: `Bearer ${token}` } : {};
+      await fetch(`/api/sessions/${sessionId}`, { method: "DELETE", headers });
+      setSessions((prev) => prev.filter((s) => s.id !== sessionId));
+      // Notify parent so it can clear the chat if this was the active session
+      onDeleteSession?.(sessionId);
+    } catch (err) {
+      console.warn("Failed to delete session:", err);
+    }
+  };
+
+  return (
+    <div style={styles.container}>
+      <style>{animStyles}</style>
+
+      {/* Header */}
+      <div style={styles.header}>
+        <span style={styles.label}>SESSIONS</span>
+        <button
+          type="button"
+          style={styles.newBtn}
+          onClick={onNewSession}
+          title="New session"
+        >
+          +
+        </button>
+      </div>
+
+      {/* Session list */}
+      <div style={styles.list}>
+        {loading && sessions.length === 0 && (
+          <div style={styles.empty}>Loading...</div>
+        )}
+
+        {!loading && sessions.length === 0 && (
+          <div style={styles.empty}>
+            No sessions yet.
+            <br />
+            <span style={{ fontSize: 11, opacity: 0.6 }}>
+              Your first message will create one automatically.
+            </span>
+          </div>
+        )}
+
+        {sessions.map((s) => (
+          <SessionItem
+            key={s.id}
+            session={s}
+            isActive={s.id === activeSessionId}
+            onSelect={() => onSelectSession?.(s)}
+            onDelete={() => handleDelete(s.id)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+const animStyles = `
+  @keyframes session-fade-in {
+    from { opacity: 0; transform: translateY(4px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+`;
+
+const styles = {
+  container: {
+    display: "flex",
+    flexDirection: "column",
+    borderTop: "1px solid #27272A",
+    flex: 1,
+    minHeight: 0,
+  },
+  header: {
+    display: "flex",
+    justifyContent: "space-between",
+    alignItems: "center",
+    padding: "10px 14px 6px",
+  },
+  label: {
+    fontSize: 10,
+    fontWeight: 700,
+    letterSpacing: "0.08em",
+    color: "#71717A",
+    textTransform: "uppercase",
+  },
+  newBtn: {
+    width: 22,
+    height: 22,
+    borderRadius: 4,
+    border: "1px dashed #3F3F46",
+    background: "transparent",
+    color: "#A1A1AA",
+    fontSize: 14,
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    lineHeight: 1,
+  },
+  list: {
+    flex: 1,
+    overflowY: "auto",
+    padding: "0 6px 8px",
+  },
+  empty: {
+    textAlign: "center",
+    color: "#52525B",
+    fontSize: 12,
+    padding: "20px 8px",
+    lineHeight: 1.5,
+  },
+};

frontend/components/SettingsModal.jsx

@@ -0,0 +1,270 @@
+import React, { useEffect, useState } from "react";
+
+export default function SettingsModal({ onClose }) {
+  const [settings, setSettings] = useState(null);
+  const [models, setModels] = useState([]);
+  const [modelsError, setModelsError] = useState(null);
+  const [loadingModels, setLoadingModels] = useState(false);
+  const [testResult, setTestResult] = useState(null); // { ok: bool, message: string }
+  const [testing, setTesting] = useState(false);
+
+  const loadSettings = async () => {
+    const res = await fetch("/api/settings");
+    const data = await res.json();
+    setSettings(data);
+  };
+
+  useEffect(() => {
+    loadSettings();
+  }, []);
+
+  const changeProvider = async (provider) => {
+    const res = await fetch("/api/settings/provider", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ provider }),
+    });
+    const data = await res.json();
+    setSettings(data);
+
+    // Reset models state when provider changes
+    setModels([]);
+    setModelsError(null);
+  };
+
+  const loadModels = async () => {
+    if (!settings) return;
+    setLoadingModels(true);
+    setModelsError(null);
+    try {
+      const res = await fetch(
+        `/api/settings/models?provider=${settings.provider}`
+      );
+      const data = await res.json();
+      if (data.error) {
+        setModelsError(data.error);
+        setModels([]);
+      } else {
+        setModels(data.models || []);
+      }
+    } catch (err) {
+      console.error(err);
+      setModelsError("Failed to load models");
+      setModels([]);
+    } finally {
+      setLoadingModels(false);
+    }
+  };
+
+  const currentModelForActiveProvider = () => {
+    if (!settings) return "";
+    const p = settings.provider;
+    if (p === "openai") return settings.openai?.model || "";
+    if (p === "claude") return settings.claude?.model || "";
+    if (p === "watsonx") return settings.watsonx?.model_id || "";
+    if (p === "ollama") return settings.ollama?.model || "";
+    return "";
+  };
+
+  const changeModel = async (model) => {
+    if (!settings) return;
+    const provider = settings.provider;
+
+    let payload = {};
+    if (provider === "openai") {
+      payload = {
+        openai: {
+          ...settings.openai,
+          model,
+        },
+      };
+    } else if (provider === "claude") {
+      payload = {
+        claude: {
+          ...settings.claude,
+          model,
+        },
+      };
+    } else if (provider === "watsonx") {
+      payload = {
+        watsonx: {
+          ...settings.watsonx,
+          model_id: model,
+        },
+      };
+    } else if (provider === "ollama") {
+      payload = {
+        ollama: {
+          ...settings.ollama,
+          model,
+        },
+      };
+    }
+
+    const res = await fetch("/api/settings/llm", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    const data = await res.json();
+    setSettings(data);
+  };
+
+  const testConnection = async () => {
+    if (!settings) return;
+    setTesting(true);
+    setTestResult(null);
+    try {
+      const res = await fetch(`/api/settings/test?provider=${settings.provider}`);
+      const data = await res.json();
+      if (!res.ok || data.error) {
+        setTestResult({ ok: false, message: data.error || data.detail || "Connection failed" });
+      } else {
+        setTestResult({ ok: true, message: data.message || "Connection successful" });
+      }
+    } catch (err) {
+      setTestResult({ ok: false, message: err.message || "Connection test failed" });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  if (!settings) return null;
+
+  const activeModel = currentModelForActiveProvider();
+
+  return (
+    <div className="modal-backdrop" onClick={onClose}>
+      <div className="modal" onClick={(e) => e.stopPropagation()}>
+        <div className="modal-header">
+          <div className="modal-title">Settings</div>
+          <button className="modal-close" type="button" onClick={onClose}>
+            ✕
+          </button>
+        </div>
+
+        <div style={{ fontSize: 13, color: "#c3c5dd" }}>
+          Select which LLM provider GitPilot should use for planning and chat.
+        </div>
+
+        <div className="provider-list">
+          {settings.providers.map((p) => (
+            <div
+              key={p}
+              className={
+                "provider-item" + (settings.provider === p ? " active" : "")
+              }
+            >
+              <div className="provider-name">{p}</div>
+              <button
+                type="button"
+                className="chat-btn secondary"
+                style={{ padding: "4px 8px", fontSize: 11 }}
+                onClick={() => changeProvider(p)}
+                disabled={settings.provider === p}
+              >
+                {settings.provider === p ? "Active" : "Use"}
+              </button>
+            </div>
+          ))}
+        </div>
+
+        {/* Models section */}
+        <div
+          style={{
+            marginTop: 16,
+            paddingTop: 12,
+            borderTop: "1px solid #2c2d46",
+            fontSize: 13,
+          }}
+        >
+          <div style={{ marginBottom: 6, color: "#c3c5dd" }}>
+            Active provider: <strong>{settings.provider}</strong>
+          </div>
+
+          <div style={{ display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap" }}>
+            <button
+              type="button"
+              className="chat-btn secondary"
+              style={{ padding: "4px 8px", fontSize: 11 }}
+              onClick={testConnection}
+              disabled={testing}
+            >
+              {testing ? "Testing…" : "Test Connection"}
+            </button>
+            <button
+              type="button"
+              className="chat-btn secondary"
+              style={{ padding: "4px 8px", fontSize: 11 }}
+              onClick={loadModels}
+              disabled={loadingModels}
+            >
+              {loadingModels ? "Loading…" : "Display models"}
+            </button>
+
+            {activeModel && (
+              <span style={{ fontSize: 12, color: "#9092b5" }}>
+                Current model: <code>{activeModel}</code>
+              </span>
+            )}
+          </div>
+
+          {modelsError && (
+            <div style={{ marginTop: 8, color: "#ff8080", fontSize: 12 }}>
+              {modelsError}
+            </div>
+          )}
+
+          {testResult && (
+            <div style={{
+              marginTop: 8,
+              padding: "6px 10px",
+              borderRadius: 6,
+              background: testResult.ok ? "#0d3320" : "#3d1111",
+              border: `1px solid ${testResult.ok ? "#166534" : "#7f1d1d"}`,
+              color: testResult.ok ? "#86efac" : "#fca5a5",
+              fontSize: 12,
+            }}>
+              {testResult.ok ? "✓ " : "✗ "}{testResult.message}
+            </div>
+          )}
+
+          {models.length > 0 && (
+            <div style={{ marginTop: 10 }}>
+              <label
+                style={{
+                  display: "block",
+                  marginBottom: 4,
+                  fontSize: 12,
+                  color: "#c3c5dd",
+                }}
+              >
+                Select model for {settings.provider}:
+              </label>
+              <select
+                style={{
+                  width: "100%",
+                  fontSize: 12,
+                  padding: "4px 6px",
+                  background: "#14152a",
+                  color: "#e6e8ff",
+                  border: "1px solid #2c2d46",
+                  borderRadius: 4,
+                }}
+                value={activeModel}
+                onChange={(e) => changeModel(e.target.value)}
+              >
+                <option value="">-- select a model --</option>
+                {models.map((m) => (
+                  <option key={m} value={m}>
+                    {m}
+                  </option>
+                ))}
+              </select>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/components/StreamingMessage.jsx

@@ -0,0 +1,182 @@
+import React from "react";
+
+/**
+ * StreamingMessage — Claude-Code-on-Web parity streaming renderer.
+ *
+ * Renders agent messages incrementally as they arrive via WebSocket.
+ * Shows tool use blocks (bash commands + output), explanatory text,
+ * and status indicators.
+ */
+export default function StreamingMessage({ events }) {
+  if (!events || events.length === 0) return null;
+
+  return (
+    <div style={styles.container}>
+      {events.map((evt, idx) => (
+        <StreamingEvent key={idx} event={evt} isLast={idx === events.length - 1} />
+      ))}
+    </div>
+  );
+}
+
+function StreamingEvent({ event, isLast }) {
+  const { type } = event;
+
+  if (type === "agent_message") {
+    return (
+      <div style={styles.textBlock}>
+        <span>{event.content}</span>
+        {isLast && <span style={styles.cursor}>|</span>}
+      </div>
+    );
+  }
+
+  if (type === "tool_use") {
+    return (
+      <div style={styles.toolBlock}>
+        <div style={styles.toolHeader}>
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <polyline points="4 17 10 11 4 5" />
+            <line x1="12" y1="19" x2="20" y2="19" />
+          </svg>
+          <span style={styles.toolName}>{event.tool || "terminal"}</span>
+        </div>
+        <div style={styles.toolInput}>
+          <code>$ {event.input}</code>
+        </div>
+      </div>
+    );
+  }
+
+  if (type === "tool_result") {
+    return (
+      <div style={styles.toolBlock}>
+        <div style={styles.toolOutput}>
+          <pre style={styles.toolOutputPre}>{event.output}</pre>
+        </div>
+      </div>
+    );
+  }
+
+  if (type === "status_change") {
+    const statusLabels = {
+      active: "Working...",
+      waiting: "Waiting for input",
+      completed: "Completed",
+      failed: "Failed",
+    };
+    return (
+      <div style={styles.statusLine}>
+        <div style={{
+          ...styles.statusDot,
+          backgroundColor: {
+            active: "#F59E0B",
+            waiting: "#3B82F6",
+            completed: "#10B981",
+            failed: "#EF4444",
+          }[event.status] || "#6B7280",
+        }} />
+        <span>{statusLabels[event.status] || event.status}</span>
+      </div>
+    );
+  }
+
+  if (type === "diff_update") {
+    return null; // Handled by DiffStats in parent
+  }
+
+  if (type === "error") {
+    return (
+      <div style={styles.errorBlock}>
+        {event.message}
+      </div>
+    );
+  }
+
+  return null;
+}
+
+const styles = {
+  container: {
+    display: "flex",
+    flexDirection: "column",
+    gap: 4,
+  },
+  textBlock: {
+    fontSize: 14,
+    lineHeight: 1.6,
+    color: "#D4D4D8",
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-word",
+  },
+  cursor: {
+    display: "inline-block",
+    animation: "blink 1s step-end infinite",
+    color: "#3B82F6",
+    fontWeight: 700,
+  },
+  toolBlock: {
+    margin: "4px 0",
+    borderRadius: 6,
+    border: "1px solid #27272A",
+    overflow: "hidden",
+  },
+  toolHeader: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "6px 10px",
+    backgroundColor: "#18181B",
+    fontSize: 11,
+    color: "#71717A",
+    fontFamily: "monospace",
+  },
+  toolName: {
+    fontWeight: 600,
+  },
+  toolInput: {
+    padding: "8px 10px",
+    backgroundColor: "#0D0D0F",
+    fontFamily: "monospace",
+    fontSize: 12,
+    color: "#10B981",
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-all",
+  },
+  toolOutput: {
+    padding: "8px 10px",
+    backgroundColor: "#0D0D0F",
+    maxHeight: 300,
+    overflowY: "auto",
+  },
+  toolOutputPre: {
+    margin: 0,
+    fontFamily: "monospace",
+    fontSize: 11,
+    color: "#A1A1AA",
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-all",
+  },
+  statusLine: {
+    display: "flex",
+    alignItems: "center",
+    gap: 6,
+    padding: "4px 0",
+    fontSize: 12,
+    color: "#71717A",
+    fontStyle: "italic",
+  },
+  statusDot: {
+    width: 6,
+    height: 6,
+    borderRadius: "50%",
+  },
+  errorBlock: {
+    padding: "8px 12px",
+    borderRadius: 6,
+    backgroundColor: "rgba(239, 68, 68, 0.08)",
+    border: "1px solid rgba(239, 68, 68, 0.2)",
+    color: "#FCA5A5",
+    fontSize: 13,
+  },
+};

frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>GitPilot</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="main.jsx"></script>
+  </body>
+</html>

frontend/main.jsx

@@ -0,0 +1,11 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App.jsx";
+import "./styles.css";
+import "./ollabridge.css";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

frontend/nginx.conf

@@ -0,0 +1,58 @@
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # DNS resolver for dynamic upstream resolution
+    # This allows nginx to start even if backend doesn't exist yet
+    resolver 127.0.0.11 valid=30s ipv6=off;
+
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;
+
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+
+    # Handle API requests - proxy to backend (docker-compose only)
+    # Uses variables to force runtime DNS resolution instead of startup
+    location /api/ {
+        # Use variable to force runtime DNS resolution
+        set $backend "backend:8000";
+        proxy_pass http://$backend;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_cache_bypass $http_upgrade;
+
+        # Handle backend connection errors gracefully
+        proxy_intercept_errors on;
+        error_page 502 503 504 = @backend_unavailable;
+    }
+
+    # Fallback for when backend is unavailable
+    location @backend_unavailable {
+        add_header Content-Type application/json;
+        return 503 '{"error": "Backend service unavailable. Configure VITE_BACKEND_URL in frontend or ensure backend container is running."}';
+    }
+
+    # Serve static files
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}

frontend/ollabridge.css

@@ -0,0 +1,222 @@
+/* ============================================================================
+   OLLABRIDGE CLOUD - Provider Tabs & Pairing UI
+   ============================================================================ */
+
+/* Provider selection tabs (replaces dropdown) */
+.settings-provider-tabs {
+  display: flex;
+  gap: 4px;
+  flex-wrap: wrap;
+  margin-top: 4px;
+}
+
+.settings-provider-tab {
+  border: 1px solid #272832;
+  outline: none;
+  background: #0a0b0f;
+  color: #9a9bb0;
+  border-radius: 8px;
+  padding: 8px 14px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  font-family: inherit;
+}
+
+.settings-provider-tab:hover {
+  background: #1a1b26;
+  color: #c3c5dd;
+  border-color: #3a3b4d;
+}
+
+.settings-provider-tab-active {
+  background: rgba(255, 122, 60, 0.12);
+  color: #ff7a3c;
+  border-color: #ff7a3c;
+  font-weight: 600;
+}
+
+.settings-provider-tab-active:hover {
+  background: rgba(255, 122, 60, 0.18);
+  color: #ff8b52;
+}
+
+/* Auth mode tabs (Device Pairing / API Key / Local Trust) */
+.ob-auth-tabs {
+  display: flex;
+  gap: 4px;
+  margin-top: 4px;
+  margin-bottom: 8px;
+}
+
+.ob-auth-tab {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border: 1px solid #272832;
+  outline: none;
+  background: #0a0b0f;
+  color: #9a9bb0;
+  border-radius: 8px;
+  padding: 7px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  font-family: inherit;
+  white-space: nowrap;
+}
+
+.ob-auth-tab:hover {
+  background: #1a1b26;
+  color: #c3c5dd;
+  border-color: #3a3b4d;
+}
+
+.ob-auth-tab-active {
+  background: rgba(59, 130, 246, 0.1);
+  color: #60a5fa;
+  border-color: #3B82F6;
+  font-weight: 600;
+}
+
+.ob-auth-tab-active:hover {
+  background: rgba(59, 130, 246, 0.15);
+}
+
+.ob-auth-tab-icon {
+  font-size: 14px;
+  line-height: 1;
+}
+
+/* Auth panel (content below tabs) */
+.ob-auth-panel {
+  padding: 12px;
+  background: #0a0b0f;
+  border: 1px solid #1e1f30;
+  border-radius: 8px;
+  margin-bottom: 4px;
+}
+
+.ob-auth-desc {
+  font-size: 12px;
+  color: #9a9bb0;
+  line-height: 1.5;
+  margin-bottom: 10px;
+}
+
+/* Pairing row */
+.ob-pair-row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.ob-pair-input {
+  flex: 1;
+  font-family: "SF Mono", Monaco, "Cascadia Code", monospace;
+  font-size: 16px !important;
+  letter-spacing: 2px;
+  text-align: center;
+  text-transform: uppercase;
+}
+
+.ob-pair-btn {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border: none;
+  outline: none;
+  background: #3B82F6;
+  color: #fff;
+  border-radius: 8px;
+  padding: 9px 16px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  white-space: nowrap;
+  font-family: inherit;
+}
+
+.ob-pair-btn:hover:not(:disabled) {
+  background: #4d93f7;
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(59, 130, 246, 0.3);
+}
+
+.ob-pair-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Pair spinner */
+.ob-pair-spinner {
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+
+/* Pair result feedback */
+.ob-pair-result {
+  margin-top: 8px;
+  padding: 8px 12px;
+  border-radius: 6px;
+  font-size: 12px;
+  font-weight: 500;
+  animation: fadeIn 0.3s ease;
+}
+
+.ob-pair-result-ok {
+  background: rgba(76, 175, 136, 0.12);
+  border: 1px solid rgba(76, 175, 136, 0.3);
+  color: #7cffb3;
+}
+
+.ob-pair-result-err {
+  background: rgba(255, 82, 82, 0.1);
+  border: 1px solid rgba(255, 82, 82, 0.3);
+  color: #ff8a8a;
+}
+
+/* Model row (input + fetch button) */
+.ob-model-row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.ob-fetch-btn {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  border: 1px solid #272832;
+  outline: none;
+  background: #1a1b26;
+  color: #c3c5dd;
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  white-space: nowrap;
+  font-family: inherit;
+}
+
+.ob-fetch-btn:hover:not(:disabled) {
+  background: #222335;
+  border-color: #3a3b4d;
+  color: #f5f5f7;
+  transform: translateY(-1px);
+}
+
+.ob-fetch-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}

frontend/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "gitpilot-frontend",
+  "version": "0.2.3",
+  "private": true,
+  "scripts": {
+    "dev": "vite --host",
+    "build": "vite build",
+    "vercel-build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-markdown": "^10.1.0",
+    "reactflow": "^11.11.4"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.0.0",
+    "vite": "^5.0.0"
+  }
+}

frontend/styles.css

@@ -0,0 +1,2825 @@
+:root {
+  color-scheme: dark;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text",
+    sans-serif;
+  background: #050608;
+  color: #f5f5f7;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  overflow: hidden;
+}
+
+/* Custom scrollbar styling - Claude Code style */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #272832;
+  border-radius: 4px;
+  transition: background 0.2s ease;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #3a3b4d;
+}
+
+/* App Root - Fixed height with footer accommodation */
+.app-root {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  background: radial-gradient(circle at top, #171823 0, #050608 55%);
+  color: #f5f5f7;
+  overflow: hidden;
+}
+
+/* Main content wrapper (sidebar + workspace) */
+.main-wrapper {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* Sidebar */
+.sidebar {
+  width: 320px;
+  padding: 16px 14px;
+  border-right: 1px solid #272832;
+  background: linear-gradient(180deg, #101117 0, #050608 100%);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  overflow-y: auto;
+  overflow-x: hidden;
+}
+
+/* User Profile Section */
+.user-profile {
+  margin-top: auto;
+  padding-top: 16px;
+  border-top: 1px solid #272832;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  animation: fadeIn 0.3s ease;
+}
+
+.user-profile-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.user-avatar {
+  width: 40px;
+  height: 40px;
+  border-radius: 10px;
+  border: 2px solid #272832;
+  transition: all 0.2s ease;
+}
+
+.user-avatar:hover {
+  border-color: #ff7a3c;
+  transform: scale(1.05);
+}
+
+.user-info {
+  flex: 1;
+  min-width: 0;
+}
+
+.user-name {
+  font-size: 13px;
+  font-weight: 600;
+  color: #f5f5f7;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.user-login {
+  font-size: 11px;
+  color: #9a9bb0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.btn-logout {
+  border: none;
+  outline: none;
+  background: #1a1b26;
+  color: #c3c5dd;
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  border: 1px solid #272832;
+}
+
+.btn-logout:hover {
+  background: #2a2b3c;
+  border-color: #ff7a3c;
+  color: #ff7a3c;
+  transform: translateY(-1px);
+}
+
+.logo-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  animation: fadeIn 0.3s ease;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.logo-square {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  background: #ff7a3c;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  color: #050608;
+  transition: transform 0.2s ease;
+}
+
+.logo-square:hover {
+  transform: scale(1.05);
+}
+
+.logo-title {
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.logo-subtitle {
+  font-size: 12px;
+  color: #a1a2b3;
+}
+
+/* Active context card */
+.sidebar-context-card {
+  padding: 10px 12px;
+  border-radius: 10px;
+  background: #151622;
+  border: 1px solid #272832;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  animation: slideIn 0.3s ease;
+}
+
+.sidebar-context-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.sidebar-context-close {
+  width: 22px;
+  height: 22px;
+  border-radius: 4px;
+  border: none;
+  background: transparent;
+  color: #71717a;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  transition: all 0.15s ease;
+}
+
+.sidebar-context-close:hover {
+  background: #272832;
+  color: #f5f5f7;
+}
+
+.sidebar-section-label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  color: #71717a;
+  text-transform: uppercase;
+}
+
+.sidebar-context-body {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.sidebar-context-repo {
+  font-size: 13px;
+  font-weight: 600;
+  color: #f5f5f7;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.sidebar-context-meta {
+  font-size: 11px;
+  color: #9a9bb0;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.sidebar-context-dot {
+  width: 3px;
+  height: 3px;
+  border-radius: 50%;
+  background: #4a4b5e;
+  display: inline-block;
+}
+
+.sidebar-context-actions {
+  display: flex;
+  gap: 6px;
+  margin-top: 2px;
+}
+
+.sidebar-context-btn {
+  border: none;
+  outline: none;
+  background: #1a1b26;
+  color: #9a9bb0;
+  border-radius: 6px;
+  padding: 4px 10px;
+  font-size: 11px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.15s ease;
+  border: 1px solid #272832;
+}
+
+.sidebar-context-btn:hover {
+  background: #222335;
+  color: #c3c5dd;
+  border-color: #3a3b4d;
+}
+
+/* Per-repo chip list in sidebar context card */
+.sidebar-repo-chips {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.sidebar-repo-chip {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  padding: 5px 6px 5px 8px;
+  border-radius: 6px;
+  border: 1px solid #272832;
+  background: #111220;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  transition: border-color 0.15s, background-color 0.15s;
+}
+
+.sidebar-repo-chip:hover {
+  border-color: #3a3b4d;
+  background: #1a1b2e;
+}
+
+.sidebar-repo-chip-active {
+  border-color: #3B82F6;
+  background: rgba(59, 130, 246, 0.06);
+}
+
+.sidebar-chip-name {
+  font-size: 12px;
+  font-weight: 600;
+  color: #c3c5dd;
+  font-family: monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  flex: 1;
+  min-width: 0;
+}
+
+.sidebar-repo-chip-active .sidebar-chip-name {
+  color: #f5f5f7;
+}
+
+.sidebar-chip-dot {
+  width: 2px;
+  height: 2px;
+  border-radius: 50%;
+  background: #4a4b5e;
+  flex-shrink: 0;
+}
+
+.sidebar-chip-branch {
+  font-size: 10px;
+  color: #71717a;
+  font-family: monospace;
+  flex-shrink: 0;
+}
+
+.sidebar-repo-chip-active .sidebar-chip-branch {
+  color: #60a5fa;
+}
+
+.sidebar-chip-write-badge {
+  font-size: 8px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: #4caf88;
+  padding: 0 4px;
+  border-radius: 3px;
+  border: 1px solid rgba(76, 175, 136, 0.25);
+  flex-shrink: 0;
+}
+
+/* Per-chip remove button: subtle by default, visible on hover */
+.sidebar-chip-remove {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border-radius: 3px;
+  border: none;
+  background: transparent;
+  color: #52525B;
+  cursor: pointer;
+  flex-shrink: 0;
+  padding: 0;
+  opacity: 0;
+  transition: opacity 0.15s, color 0.15s, background 0.15s;
+}
+
+.sidebar-repo-chip:hover .sidebar-chip-remove {
+  opacity: 1;
+}
+
+.sidebar-chip-remove:hover {
+  color: #f87171;
+  background: rgba(248, 113, 113, 0.1);
+}
+
+/* "clear all" link-style button */
+.sidebar-clear-all {
+  font-size: 9px;
+  color: #52525B;
+  width: auto;
+  height: auto;
+  padding: 2px 6px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.sidebar-clear-all:hover {
+  color: #f87171;
+  background: rgba(248, 113, 113, 0.08);
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateX(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* ContextBar — horizontal chip bar above workspace */
+.ctxbar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  border-bottom: 1px solid #1E1F23;
+  background-color: #0D0D10;
+  min-height: 40px;
+}
+
+.ctxbar-scroll {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.ctxbar-scroll::-webkit-scrollbar {
+  display: none;
+}
+
+.ctxbar-chip {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  padding: 4px 6px 4px 8px;
+  border-radius: 6px;
+  border: 1px solid #27272A;
+  background: #18181B;
+  cursor: pointer;
+  white-space: nowrap;
+  position: relative;
+  flex-shrink: 0;
+  transition: border-color 0.15s, background-color 0.15s;
+}
+
+.ctxbar-chip:hover {
+  border-color: #3a3b4d;
+  background: #1e1f30;
+}
+
+.ctxbar-chip-active {
+  border-color: #3B82F6;
+  background: rgba(59, 130, 246, 0.08);
+}
+
+.ctxbar-chip-indicator {
+  position: absolute;
+  left: 0;
+  top: 25%;
+  bottom: 25%;
+  width: 2px;
+  border-radius: 1px;
+  background-color: #3B82F6;
+}
+
+.ctxbar-chip-name {
+  font-size: 12px;
+  font-weight: 600;
+  font-family: monospace;
+  color: #A1A1AA;
+  max-width: 120px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.ctxbar-chip-active .ctxbar-chip-name {
+  color: #E4E4E7;
+}
+
+.ctxbar-chip-dot {
+  width: 2px;
+  height: 2px;
+  border-radius: 50%;
+  background: #4a4b5e;
+  flex-shrink: 0;
+}
+
+.ctxbar-chip-branch {
+  font-size: 10px;
+  font-family: monospace;
+  background: none;
+  border: 1px solid transparent;
+  border-radius: 3px;
+  padding: 1px 4px;
+  cursor: pointer;
+  color: #71717A;
+  transition: border-color 0.15s, color 0.15s;
+}
+
+.ctxbar-chip-branch:hover {
+  border-color: #3a3b4d;
+}
+
+.ctxbar-chip-branch-active {
+  color: #60a5fa;
+}
+
+.ctxbar-chip-write {
+  font-size: 8px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: #4caf88;
+  padding: 0 4px;
+  border-radius: 3px;
+  border: 1px solid rgba(76, 175, 136, 0.25);
+  flex-shrink: 0;
+}
+
+/* Hover-reveal remove button (Claude-style: hidden → visible on chip hover → red on X hover) */
+.ctxbar-chip-remove {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border-radius: 3px;
+  border: none;
+  background: transparent;
+  color: #52525B;
+  cursor: pointer;
+  flex-shrink: 0;
+  padding: 0;
+  opacity: 0;
+  transition: opacity 0.15s, color 0.15s, background 0.15s;
+}
+
+.ctxbar-chip-remove-visible,
+.ctxbar-chip:hover .ctxbar-chip-remove {
+  opacity: 1;
+}
+
+.ctxbar-chip-remove:hover {
+  color: #f87171;
+  background: rgba(248, 113, 113, 0.1);
+}
+
+.ctxbar-add {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: 6px;
+  border: 1px dashed #3F3F46;
+  background: transparent;
+  color: #71717A;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: border-color 0.15s, color 0.15s;
+}
+
+.ctxbar-add:hover {
+  border-color: #60a5fa;
+  color: #60a5fa;
+}
+
+.ctxbar-meta {
+  font-size: 10px;
+  color: #52525B;
+  white-space: nowrap;
+  flex-shrink: 0;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.ctxbar-branch-picker {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 100;
+  margin-top: 4px;
+}
+
+/* Legacy compat — kept for other uses */
+.sidebar-repo-info {
+  padding: 10px 12px;
+  border-radius: 10px;
+  background: #151622;
+  border: 1px solid #272832;
+  animation: slideIn 0.3s ease;
+}
+
+.sidebar-repo-name {
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.sidebar-repo-meta {
+  font-size: 11px;
+  color: #9a9bb0;
+  margin-top: 2px;
+}
+
+.settings-button {
+  border: none;
+  outline: none;
+  background: #1a1b26;
+  color: #f5f5f7;
+  border-radius: 8px;
+  padding: 8px 10px;
+  cursor: pointer;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.settings-button:hover {
+  background: #222335;
+  transform: translateY(-1px);
+}
+
+/* Repo search */
+.repo-search-box {
+  border-radius: 12px;
+  background: #101117;
+  border: 1px solid #272832;
+  padding: 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+/* Search header wrapper */
+.repo-search-header {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+/* Search row with input and button */
+.repo-search-row {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+
+/* Search input */
+.repo-search-input {
+  flex: 1;
+  border-radius: 7px;
+  padding: 8px 10px;
+  border: 1px solid #272832;
+  background: #050608;
+  color: #f5f5f7;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.repo-search-input:focus {
+  outline: none;
+  border-color: #ff7a3c;
+  background: #0a0b0f;
+  box-shadow: 0 0 0 3px rgba(255, 122, 60, 0.08);
+}
+
+.repo-search-input::placeholder {
+  color: #676883;
+}
+
+.repo-search-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Search button */
+.repo-search-btn {
+  border-radius: 7px;
+  border: none;
+  outline: none;
+  padding: 8px 14px;
+  background: #1a1b26;
+  color: #f5f5f7;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 500;
+  transition: all 0.2s ease;
+  white-space: nowrap;
+}
+
+.repo-search-btn:hover:not(:disabled) {
+  background: #222335;
+  transform: translateY(-1px);
+}
+
+.repo-search-btn:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.repo-search-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Info bar (shows count and clear button) */
+.repo-info-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 6px 10px;
+  background: #0a0b0f;
+  border: 1px solid #272832;
+  border-radius: 7px;
+  font-size: 11px;
+}
+
+.repo-count {
+  color: #9a9bb0;
+  font-weight: 500;
+}
+
+.repo-clear-btn {
+  padding: 3px 10px;
+  background: transparent;
+  border: 1px solid #272832;
+  border-radius: 5px;
+  color: #9a9bb0;
+  font-size: 11px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.repo-clear-btn:hover:not(:disabled) {
+  background: #1a1b26;
+  color: #c3c5dd;
+  border-color: #3a3b4d;
+}
+
+.repo-clear-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Status message */
+.repo-status {
+  padding: 8px 10px;
+  background: #1a1b26;
+  border: 1px solid #272832;
+  border-radius: 7px;
+  color: #9a9bb0;
+  font-size: 11px;
+  text-align: center;
+}
+
+/* Repository list */
+.repo-list {
+  max-height: 220px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding-right: 2px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+/* Custom scrollbar for repo list */
+.repo-list::-webkit-scrollbar {
+  width: 6px;
+}
+
+.repo-list::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.repo-list::-webkit-scrollbar-thumb {
+  background: #272832;
+  border-radius: 3px;
+}
+
+.repo-list::-webkit-scrollbar-thumb:hover {
+  background: #3a3b4d;
+}
+
+/* Repository item */
+.repo-item {
+  width: 100%;
+  text-align: left;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: #f5f5f7;
+  padding: 8px 8px;
+  border-radius: 7px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  transition: all 0.15s ease;
+  border: 1px solid transparent;
+}
+
+.repo-item:hover {
+  background: #1a1b26;
+  border-color: #272832;
+  transform: translateX(2px);
+}
+
+.repo-item-content {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1;
+  min-width: 0;
+}
+
+.repo-name {
+  font-size: 13px;
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.repo-owner {
+  font-size: 11px;
+  color: #8e8fac;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Private badge */
+.repo-badge-private {
+  padding: 2px 6px;
+  background: #1a1b26;
+  border: 1px solid #3a3b4d;
+  border-radius: 4px;
+  color: #9a9bb0;
+  font-size: 9px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+/* Loading states */
+.repo-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  padding: 30px 20px;
+  color: #9a9bb0;
+  font-size: 12px;
+}
+
+.repo-loading-spinner {
+  width: 24px;
+  height: 24px;
+  border: 2px solid #272832;
+  border-top-color: #ff7a3c;
+  border-radius: 50%;
+  animation: repo-spin 0.8s linear infinite;
+}
+
+.repo-loading-spinner-small {
+  width: 14px;
+  height: 14px;
+  border: 2px solid rgba(255, 122, 60, 0.3);
+  border-top-color: #ff7a3c;
+  border-radius: 50%;
+  animation: repo-spin 0.8s linear infinite;
+}
+
+@keyframes repo-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Load more button */
+.repo-load-more {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  width: 100%;
+  padding: 10px 12px;
+  margin: 4px 0;
+  background: #0a0b0f;
+  border: 1px solid #272832;
+  border-radius: 7px;
+  color: #c3c5dd;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.repo-load-more:hover:not(:disabled) {
+  background: #1a1b26;
+  border-color: #3a3b4d;
+  transform: translateY(-1px);
+}
+
+.repo-load-more:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.repo-load-more:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.repo-load-more-count {
+  color: #7779a0;
+  font-weight: 400;
+}
+
+/* All loaded message */
+.repo-all-loaded {
+  padding: 10px 12px;
+  margin: 4px 0;
+  background: rgba(124, 255, 179, 0.08);
+  border: 1px solid rgba(124, 255, 179, 0.2);
+  border-radius: 7px;
+  color: #7cffb3;
+  font-size: 11px;
+  text-align: center;
+  font-weight: 500;
+}
+
+/* GitHub App installation notice */
+.repo-github-notice {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 10px 12px;
+  background: #0a0b0f;
+  border: 1px solid #272832;
+  border-radius: 7px;
+  font-size: 11px;
+  line-height: 1.5;
+  margin-top: 4px;
+}
+
+.repo-github-icon {
+  flex-shrink: 0;
+  margin-top: 1px;
+  opacity: 0.6;
+  color: #9a9bb0;
+  width: 16px;
+  height: 16px;
+}
+
+.repo-github-notice-content {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.repo-github-notice-title {
+  color: #c3c5dd;
+  font-weight: 600;
+  font-size: 11px;
+}
+
+.repo-github-notice-text {
+  color: #9a9bb0;
+}
+
+.repo-github-link {
+  color: #ff7a3c;
+  text-decoration: none;
+  font-weight: 500;
+  transition: color 0.2s ease;
+}
+
+.repo-github-link:hover {
+  color: #ff8b52;
+  text-decoration: underline;
+}
+
+/* Focus visible for accessibility */
+.repo-item:focus-visible,
+.repo-search-btn:focus-visible,
+.repo-load-more:focus-visible,
+.repo-clear-btn:focus-visible {
+  outline: 2px solid #ff7a3c;
+  outline-offset: 2px;
+}
+
+/* Reduced motion support */
+@media (prefers-reduced-motion: reduce) {
+  .repo-item,
+  .repo-search-btn,
+  .repo-load-more,
+  .repo-clear-btn {
+    transition: none;
+  }
+
+  .repo-loading-spinner,
+  .repo-loading-spinner-small {
+    animation: none;
+  }
+}
+
+/* Mobile responsive adjustments */
+@media (max-width: 768px) {
+  .repo-search-input {
+    font-size: 16px; /* Prevents zoom on iOS */
+  }
+
+  .repo-item {
+    padding: 7px 7px;
+  }
+
+  .repo-name {
+    font-size: 12px;
+  }
+
+  .repo-owner {
+    font-size: 10px;
+  }
+}
+
+/* Workspace */
+.workspace {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  overflow: hidden;
+  min-height: 0;
+}
+
+.empty-state {
+  margin: auto;
+  max-width: 420px;
+  text-align: center;
+  color: #c3c5dd;
+  animation: fadeIn 0.5s ease;
+}
+
+.empty-bot {
+  font-size: 36px;
+  margin-bottom: 12px;
+  animation: bounce 2s ease infinite;
+}
+
+@keyframes bounce {
+  0%, 100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-10px);
+  }
+}
+
+.empty-state h1 {
+  font-size: 24px;
+  margin-bottom: 6px;
+}
+
+.empty-state p {
+  font-size: 14px;
+  color: #9a9bb0;
+}
+
+/* Workspace grid - Properly constrained */
+.workspace-grid {
+  display: grid;
+  grid-template-columns: 320px minmax(340px, 1fr);
+  height: 100%;
+  overflow: hidden;
+  flex: 1;
+  min-height: 0;
+}
+
+/* Panels */
+.panel-header {
+  height: 40px;
+  padding: 0 16px;
+  border-bottom: 1px solid #272832;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-size: 13px;
+  font-weight: 500;
+  color: #c3c5dd;
+  background: #0a0b0f;
+  flex-shrink: 0;
+}
+
+.badge {
+  padding: 2px 6px;
+  border-radius: 999px;
+  border: 1px solid #3a3b4d;
+  font-size: 10px;
+}
+
+/* Files */
+.files-panel {
+  border-right: 1px solid #272832;
+  background: #101117;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.files-list {
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: 6px 4px;
+  min-height: 0;
+}
+
+.files-item {
+  border: none;
+  outline: none;
+  width: 100%;
+  background: transparent;
+  color: #f5f5f7;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 12px;
+  transition: all 0.15s ease;
+}
+
+.files-item:hover {
+  background: #1a1b26;
+  transform: translateX(2px);
+}
+
+.files-item-active {
+  background: #2a2b3c;
+}
+
+.file-icon {
+  width: 16px;
+  flex-shrink: 0;
+}
+
+.file-path {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.files-empty {
+  padding: 10px 12px;
+  font-size: 12px;
+  color: #9a9bb0;
+}
+
+/* Chat panel */
+.editor-panel {
+  display: flex;
+  flex-direction: column;
+  background: #050608;
+}
+
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.chat-messages {
+  flex: 1;
+  padding: 12px 16px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  font-size: 13px;
+  min-height: 0;
+  scroll-behavior: smooth;
+}
+
+.chat-message-user {
+  margin-bottom: 16px;
+  animation: slideInRight 0.3s ease;
+}
+
+@keyframes slideInRight {
+  from {
+    opacity: 0;
+    transform: translateX(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.chat-message-ai {
+  margin-bottom: 16px;
+  animation: slideInLeft 0.3s ease;
+}
+
+@keyframes slideInLeft {
+  from {
+    opacity: 0;
+    transform: translateX(-20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.chat-message-ai span {
+  display: inline-block;
+  padding: 10px 14px;
+  border-radius: 12px;
+  max-width: 80%;
+  line-height: 1.5;
+}
+
+.chat-message-user span {
+  display: inline;
+  padding: 0;
+  border-radius: 0;
+  background: transparent;
+  border: none;
+  max-width: none;
+  line-height: inherit;
+}
+
+.chat-message-ai span {
+  background: #151622;
+  border: 1px solid #272832;
+}
+
+.chat-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 300px;
+  padding: 40px 20px;
+  text-align: center;
+}
+
+.chat-empty-icon {
+  font-size: 48px;
+  margin-bottom: 16px;
+  opacity: 0.6;
+  animation: pulse 2s ease infinite;
+}
+
+@keyframes pulse {
+  0%, 100% {
+    opacity: 0.6;
+  }
+  50% {
+    opacity: 0.8;
+  }
+}
+
+.chat-empty-state p {
+  margin: 0;
+  font-size: 13px;
+  color: #9a9bb0;
+  max-width: 400px;
+}
+
+.chat-input-box {
+  padding: 12px 16px;
+  border-top: 1px solid #272832;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  background: #050608;
+  flex-shrink: 0;
+  min-height: fit-content;
+  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.3);
+}
+
+.chat-input-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.chat-input {
+  flex: 1;
+  min-width: 200px;
+  border-radius: 8px;
+  padding: 10px 12px;
+  border: 1px solid #272832;
+  background: #0a0b0f;
+  color: #f5f5f7;
+  font-size: 13px;
+  line-height: 1.5;
+  transition: all 0.2s ease;
+}
+
+.chat-input:focus {
+  outline: none;
+  border-color: #ff7a3c;
+  background: #101117;
+  box-shadow: 0 0 0 3px rgba(255, 122, 60, 0.1);
+}
+
+.chat-input::placeholder {
+  color: #676883;
+}
+
+.chat-btn {
+  border-radius: 8px;
+  border: none;
+  outline: none;
+  padding: 10px 16px;
+  background: #ff7a3c;
+  color: #050608;
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 600;
+  transition: all 0.2s ease;
+  white-space: nowrap;
+  min-height: 40px;
+}
+
+.chat-btn:hover:not(:disabled) {
+  background: #ff8c52;
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(255, 122, 60, 0.3);
+}
+
+.chat-btn:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.chat-btn.secondary {
+  background: #1a1b26;
+  color: #f5f5f7;
+  border: 1px solid #272832;
+}
+
+.chat-btn.secondary:hover:not(:disabled) {
+  background: #222335;
+  border-color: #3a3b4d;
+}
+
+.chat-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Plan rendering */
+.plan-card {
+  border-radius: 12px;
+  background: #101117;
+  border: 1px solid #272832;
+  padding: 10px 12px;
+  margin-top: 6px;
+  animation: fadeIn 0.3s ease;
+}
+
+.plan-steps {
+  margin: 6px 0 0;
+  padding-left: 18px;
+  font-size: 12px;
+}
+
+.plan-steps li {
+  margin-bottom: 4px;
+}
+
+/* Modal */
+.modal-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 20;
+  animation: fadeIn 0.2s ease;
+}
+
+.modal {
+  background: #101117;
+  border-radius: 16px;
+  border: 1px solid #272832;
+  padding: 16px 18px;
+  width: 360px;
+  animation: scaleIn 0.3s ease;
+}
+
+@keyframes scaleIn {
+  from {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 10px;
+}
+
+.modal-title {
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.modal-close {
+  border: none;
+  outline: none;
+  background: transparent;
+  color: #9a9bb0;
+  cursor: pointer;
+  transition: color 0.2s ease;
+}
+
+.modal-close:hover {
+  color: #ff7a3c;
+}
+
+.provider-list {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin-top: 8px;
+}
+
+.provider-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 6px 8px;
+  border-radius: 8px;
+  background: #151622;
+  border: 1px solid #272832;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.provider-item:hover {
+  border-color: #3a3b4d;
+}
+
+.provider-item.active {
+  border-color: #ff7a3c;
+  background: rgba(255, 122, 60, 0.1);
+}
+
+.provider-name {
+  font-weight: 500;
+}
+
+.provider-badge {
+  font-size: 11px;
+  color: #9a9bb0;
+}
+
+/* Navigation */
+.main-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-top: 10px;
+  margin-bottom: 10px;
+}
+
+.nav-btn {
+  border: none;
+  outline: none;
+  background: transparent;
+  color: #9a9bb0;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 500;
+  padding: 8px 12px;
+  text-align: left;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.nav-btn:hover {
+  background: #1a1b26;
+  color: #c3c5dd;
+}
+
+.nav-btn-active {
+  background: #1a1b26;
+  color: #f5f5f7;
+  font-weight: 600;
+  border-left: 2px solid #ff7a3c;
+  padding-left: 10px;
+}
+
+/* Settings page */
+.settings-root {
+  padding: 20px 24px;
+  overflow-y: auto;
+  max-width: 800px;
+}
+
+.settings-root h1 {
+  margin-top: 0;
+  font-size: 24px;
+  margin-bottom: 8px;
+}
+
+.settings-muted {
+  font-size: 13px;
+  color: #9a9bb0;
+  margin-bottom: 20px;
+  line-height: 1.5;
+}
+
+.settings-card {
+  background: #101117;
+  border-radius: 12px;
+  border: 1px solid #272832;
+  padding: 14px 16px;
+  margin-bottom: 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  transition: all 0.2s ease;
+}
+
+.settings-card:hover {
+  border-color: #3a3b4d;
+}
+
+.settings-title {
+  font-size: 15px;
+  font-weight: 600;
+  margin-bottom: 4px;
+}
+
+.settings-label {
+  font-size: 12px;
+  color: #9a9bb0;
+  font-weight: 500;
+  margin-top: 4px;
+}
+
+.settings-input,
+.settings-select {
+  background: #050608;
+  border-radius: 8px;
+  border: 1px solid #272832;
+  padding: 8px 10px;
+  color: #f5f5f7;
+  font-size: 13px;
+  font-family: inherit;
+  transition: all 0.2s ease;
+}
+
+.settings-input:focus,
+.settings-select:focus {
+  outline: none;
+  border-color: #ff7a3c;
+  box-shadow: 0 0 0 3px rgba(255, 122, 60, 0.1);
+}
+
+.settings-input::placeholder {
+  color: #676883;
+}
+
+.settings-hint {
+  font-size: 11px;
+  color: #7a7b8e;
+  margin-top: -2px;
+}
+
+.settings-actions {
+  margin-top: 12px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.settings-save-btn {
+  background: #ff7a3c;
+  border-radius: 999px;
+  border: none;
+  outline: none;
+  padding: 9px 18px;
+  font-size: 13px;
+  cursor: pointer;
+  color: #050608;
+  font-weight: 600;
+  transition: all 0.2s ease;
+}
+
+.settings-save-btn:hover {
+  background: #ff8b52;
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(255, 122, 60, 0.3);
+}
+
+.settings-save-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
+}
+
+.settings-success {
+  font-size: 12px;
+  color: #7cffb3;
+  font-weight: 500;
+}
+
+.settings-error {
+  font-size: 12px;
+  color: #ff8a8a;
+  font-weight: 500;
+}
+
+/* Flow viewer */
+.flow-root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+}
+
+.flow-header {
+  padding: 16px 20px;
+  border-bottom: 1px solid #272832;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.flow-header h1 {
+  margin: 0;
+  font-size: 22px;
+  margin-bottom: 4px;
+}
+
+.flow-header p {
+  margin: 0;
+  font-size: 12px;
+  color: #9a9bb0;
+  max-width: 600px;
+  line-height: 1.5;
+}
+
+.flow-canvas {
+  flex: 1;
+  background: #050608;
+  position: relative;
+}
+
+.flow-error {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+}
+
+.error-icon {
+  font-size: 48px;
+}
+
+.error-text {
+  font-size: 14px;
+  color: #ff8a8a;
+}
+
+/* Assistant Message Sections */
+.gp-section {
+  margin-bottom: 16px;
+  border-radius: 12px;
+  background: #101117;
+  border: 1px solid #272832;
+  overflow: hidden;
+  animation: fadeIn 0.3s ease;
+}
+
+.gp-section-header {
+  padding: 8px 12px;
+  background: #151622;
+  border-bottom: 1px solid #272832;
+}
+
+.gp-section-header h3 {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: #c3c5dd;
+}
+
+.gp-section-content {
+  padding: 12px;
+}
+
+.gp-section-answer .gp-section-content p {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.6;
+  color: #f5f5f7;
+}
+
+.gp-section-plan {
+  background: #0a0b0f;
+}
+
+/* Plan View Enhanced */
+.plan-header {
+  margin-bottom: 12px;
+}
+
+.plan-goal {
+  font-size: 13px;
+  font-weight: 600;
+  margin-bottom: 4px;
+  color: #f5f5f7;
+}
+
+.plan-summary {
+  font-size: 12px;
+  color: #c3c5dd;
+  line-height: 1.5;
+}
+
+.plan-totals {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+  flex-wrap: wrap;
+}
+
+.plan-total {
+  padding: 4px 8px;
+  border-radius: 6px;
+  font-size: 11px;
+  font-weight: 500;
+  animation: fadeIn 0.3s ease;
+}
+
+.plan-total-create {
+  background: rgba(76, 175, 80, 0.15);
+  color: #81c784;
+  border: 1px solid rgba(76, 175, 80, 0.3);
+}
+
+.plan-total-modify {
+  background: rgba(33, 150, 243, 0.15);
+  color: #64b5f6;
+  border: 1px solid rgba(33, 150, 243, 0.3);
+}
+
+.plan-total-delete {
+  background: rgba(244, 67, 54, 0.15);
+  color: #e57373;
+  border: 1px solid rgba(244, 67, 54, 0.3);
+}
+
+.plan-step {
+  margin-bottom: 12px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid #1a1b26;
+}
+
+.plan-step:last-child {
+  border-bottom: none;
+  padding-bottom: 0;
+  margin-bottom: 0;
+}
+
+.plan-step-header {
+  margin-bottom: 6px;
+}
+
+.plan-step-description {
+  font-size: 12px;
+  color: #9a9bb0;
+  margin-bottom: 8px;
+}
+
+.plan-files {
+  list-style: none;
+  padding: 0;
+  margin: 8px 0;
+}
+
+.plan-file {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 0;
+}
+
+.gp-pill {
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+}
+
+.gp-pill-create {
+  background: rgba(76, 175, 80, 0.2);
+  color: #81c784;
+  border: 1px solid rgba(76, 175, 80, 0.4);
+}
+
+.gp-pill-modify {
+  background: rgba(33, 150, 243, 0.2);
+  color: #64b5f6;
+  border: 1px solid rgba(33, 150, 243, 0.4);
+}
+
+.gp-pill-delete {
+  background: rgba(244, 67, 54, 0.2);
+  color: #e57373;
+  border: 1px solid rgba(244, 67, 54, 0.4);
+}
+
+.plan-file-path {
+  font-size: 11px;
+  color: #c3c5dd;
+  font-family: "SF Mono", Monaco, "Cascadia Code", monospace;
+  background: #0a0b0f;
+  padding: 2px 6px;
+  border-radius: 4px;
+}
+
+.plan-step-risks {
+  margin-top: 8px;
+  padding: 6px 8px;
+  background: rgba(255, 152, 0, 0.1);
+  border-left: 2px solid #ff9800;
+  border-radius: 4px;
+  font-size: 11px;
+  color: #ffb74d;
+}
+
+.plan-risk-label {
+  font-weight: 600;
+}
+
+/* Execution Log */
+.execution-steps {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.execution-step {
+  padding: 8px;
+  margin-bottom: 6px;
+  background: #0a0b0f;
+  border-radius: 6px;
+  font-size: 11px;
+  font-family: "SF Mono", Monaco, "Cascadia Code", monospace;
+  white-space: pre-wrap;
+}
+
+.execution-step-number {
+  color: #ff7a3c;
+  font-weight: 600;
+  margin-right: 8px;
+}
+
+.execution-step-summary {
+  color: #c3c5dd;
+}
+
+/* Project Context Panel - Properly constrained */
+.gp-context {
+  padding: 12px;
+  height: 100%;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.gp-context-column {
+  background: #0a0b0f;
+  border-right: 1px solid #272832;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.gp-chat-column {
+  display: flex;
+  flex-direction: column;
+  background: #050608;
+  height: 100%;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.gp-card {
+  background: #101117;
+  border-radius: 12px;
+  border: 1px solid #272832;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.gp-card-header {
+  padding: 10px 12px;
+  background: #151622;
+  border-bottom: 1px solid #272832;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-shrink: 0;
+}
+
+.gp-card-header h2 {
+  margin: 0;
+  font-size: 14px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.gp-badge {
+  padding: 3px 8px;
+  border-radius: 999px;
+  background: #2a2b3c;
+  border: 1px solid #3a3b4d;
+  font-size: 11px;
+  color: #c3c5dd;
+  font-weight: 500;
+  transition: all 0.2s ease;
+}
+
+.gp-badge:hover {
+  border-color: #ff7a3c;
+}
+
+.gp-context-meta {
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border-bottom: 1px solid #272832;
+  flex-shrink: 0;
+  background: #0a0b0f;
+}
+
+.gp-context-meta-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+}
+
+.gp-context-meta-label {
+  color: #9a9bb0;
+  min-width: 60px;
+}
+
+.gp-context-meta-item strong {
+  color: #f5f5f7;
+  font-weight: 500;
+}
+
+/* File tree - Properly scrollable */
+.gp-context-tree {
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: hidden;
+  min-height: 0;
+  padding: 4px;
+}
+
+.gp-context-empty {
+  padding: 20px 12px;
+  text-align: center;
+  color: #9a9bb0;
+  font-size: 12px;
+}
+
+/* Footer - Fixed at bottom */
+.gp-footer {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  border-top: 1px solid #272832;
+  padding: 8px 20px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  font-size: 11px;
+  color: #9a9bb0;
+  background: #0a0b0f;
+  backdrop-filter: blur(10px);
+  z-index: 10;
+  box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.2);
+}
+
+.gp-footer-left {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-weight: 500;
+  color: #c3c5dd;
+}
+
+.gp-footer-right {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.gp-footer-right a {
+  color: #9a9bb0;
+  text-decoration: none;
+  transition: all 0.2s ease;
+}
+
+.gp-footer-right a:hover {
+  color: #ff7a3c;
+  transform: translateY(-1px);
+}
+
+/* Adjust app-root to account for fixed footer */
+.app-root > .main-wrapper {
+  padding-bottom: 32px; /* Space for fixed footer */
+}
+
+/* ============================================================================
+   LOGIN PAGE - Enterprise GitHub Authentication
+   ============================================================================ */
+
+.login-page {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: radial-gradient(circle at center, #171823 0%, #050608 70%);
+  padding: 20px;
+  animation: fadeIn 0.4s ease;
+}
+
+.login-container {
+  width: 100%;
+  max-width: 480px;
+  background: #101117;
+  border: 1px solid #272832;
+  border-radius: 24px;
+  padding: 40px 36px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.4);
+  animation: slideUp 0.5s ease;
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Header */
+.login-header {
+  text-align: center;
+  margin-bottom: 32px;
+}
+
+.login-logo {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.logo-icon {
+  width: 64px;
+  height: 64px;
+  border-radius: 16px;
+  background: linear-gradient(135deg, #ff7a3c 0%, #ff6b2b 100%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 28px;
+  color: #050608;
+  box-shadow: 0 8px 24px rgba(255, 122, 60, 0.3);
+  transition: transform 0.3s ease;
+}
+
+.logo-icon:hover {
+  transform: scale(1.05) rotate(3deg);
+}
+
+.login-title {
+  margin: 0;
+  font-size: 28px;
+  font-weight: 700;
+  color: #f5f5f7;
+  margin-bottom: 8px;
+  letter-spacing: -0.5px;
+}
+
+.login-subtitle {
+  margin: 0;
+  font-size: 14px;
+  color: #9a9bb0;
+  font-weight: 500;
+}
+
+/* Welcome Section */
+.login-welcome {
+  margin-bottom: 28px;
+  padding-bottom: 28px;
+  border-bottom: 1px solid #272832;
+}
+
+.login-welcome h2 {
+  margin: 0 0 12px 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.login-welcome p {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.6;
+  color: #c3c5dd;
+}
+
+/* Error Message */
+.login-error {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px 14px;
+  background: rgba(255, 82, 82, 0.1);
+  border: 1px solid rgba(255, 82, 82, 0.3);
+  border-radius: 10px;
+  color: #ff8a8a;
+  font-size: 13px;
+  margin-bottom: 20px;
+  animation: shake 0.4s ease;
+}
+
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-5px); }
+  75% { transform: translateX(5px); }
+}
+
+.login-error svg {
+  flex-shrink: 0;
+}
+
+/* Login Actions */
+.login-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  margin-bottom: 28px;
+}
+
+/* Buttons */
+.btn-primary,
+.btn-secondary,
+.btn-text {
+  border: none;
+  outline: none;
+  cursor: pointer;
+  font-family: inherit;
+  font-weight: 600;
+  transition: all 0.2s ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+}
+
+.btn-large {
+  padding: 14px 24px;
+  font-size: 15px;
+  border-radius: 12px;
+}
+
+.btn-primary {
+  background: linear-gradient(135deg, #ff7a3c 0%, #ff6b2b 100%);
+  color: #fff;
+  box-shadow: 0 4px 12px rgba(255, 122, 60, 0.25);
+}
+
+.btn-primary:hover:not(:disabled) {
+  transform: translateY(-2px);
+  box-shadow: 0 8px 20px rgba(255, 122, 60, 0.35);
+}
+
+.btn-primary:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.btn-primary:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.btn-secondary {
+  background: #1a1b26;
+  color: #f5f5f7;
+  border: 1px solid #3a3b4d;
+}
+
+.btn-secondary:hover {
+  background: #2a2b3c;
+  border-color: #4a4b5d;
+  transform: translateY(-1px);
+}
+
+.btn-text {
+  background: transparent;
+  color: #9a9bb0;
+  padding: 10px;
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.btn-text:hover {
+  color: #ff7a3c;
+}
+
+/* Button Spinner */
+.btn-spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Loading Spinner (Page) */
+.loading-spinner {
+  width: 48px;
+  height: 48px;
+  border: 4px solid #272832;
+  border-top-color: #ff7a3c;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+  margin: 0 auto;
+}
+
+/* Divider */
+.login-divider {
+  position: relative;
+  text-align: center;
+  margin: 8px 0;
+}
+
+.login-divider::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 0;
+  right: 0;
+  height: 1px;
+  background: #272832;
+}
+
+.login-divider span {
+  position: relative;
+  display: inline-block;
+  padding: 0 16px;
+  background: #101117;
+  color: #9a9bb0;
+  font-size: 12px;
+  font-weight: 500;
+}
+
+/* Form */
+.login-form {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  margin-bottom: 28px;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.form-group label {
+  font-size: 13px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.form-input {
+  background: #0a0b0f;
+  border: 1px solid #272832;
+  border-radius: 10px;
+  padding: 12px 14px;
+  color: #f5f5f7;
+  font-size: 14px;
+  font-family: "SF Mono", Monaco, monospace;
+  transition: all 0.2s ease;
+}
+
+.form-input:focus {
+  outline: none;
+  border-color: #ff7a3c;
+  box-shadow: 0 0 0 4px rgba(255, 122, 60, 0.1);
+}
+
+.form-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.form-input::placeholder {
+  color: #676883;
+}
+
+.form-hint {
+  font-size: 12px;
+  color: #9a9bb0;
+  line-height: 1.5;
+  margin: 0;
+}
+
+.form-link {
+  color: #ff7a3c;
+  text-decoration: none;
+  font-weight: 500;
+  transition: color 0.2s ease;
+}
+
+.form-link:hover {
+  color: #ff8b52;
+  text-decoration: underline;
+}
+
+.form-hint code {
+  background: #1a1b26;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-family: "SF Mono", Monaco, monospace;
+  font-size: 11px;
+  color: #ff7a3c;
+}
+
+/* Notice (for no auth configured) */
+.login-notice {
+  padding: 20px;
+  background: rgba(255, 152, 0, 0.1);
+  border: 1px solid rgba(255, 152, 0, 0.3);
+  border-radius: 12px;
+  margin-bottom: 28px;
+}
+
+.login-notice h3 {
+  margin: 0 0 12px 0;
+  font-size: 16px;
+  color: #ffb74d;
+}
+
+.login-notice p {
+  margin: 0 0 12px 0;
+  font-size: 13px;
+  color: #c3c5dd;
+  line-height: 1.6;
+}
+
+.login-notice ul {
+  margin: 0;
+  padding-left: 20px;
+  font-size: 13px;
+  color: #c3c5dd;
+  line-height: 1.8;
+}
+
+.login-notice code {
+  background: #1a1b26;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-family: "SF Mono", Monaco, monospace;
+  font-size: 12px;
+  color: #ff7a3c;
+}
+
+/* Features List */
+.login-features {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 20px 0;
+  border-top: 1px solid #272832;
+  border-bottom: 1px solid #272832;
+  margin-bottom: 20px;
+}
+
+.feature-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.feature-icon {
+  flex-shrink: 0;
+  width: 20px;
+  height: 20px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #7cffb3;
+}
+
+.feature-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.feature-text strong {
+  font-size: 13px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.feature-text span {
+  font-size: 12px;
+  color: #9a9bb0;
+}
+
+/* Footer */
+.login-footer {
+  text-align: center;
+}
+
+.login-footer p {
+  margin: 0;
+  font-size: 11px;
+  color: #7a7b8e;
+  line-height: 1.6;
+}/* ============================================================================
+   INSTALLATION MODAL - Claude Code Style
+   ============================================================================ */
+
+.install-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.7);
+  backdrop-filter: blur(8px);
+  z-index: 9999;
+  animation: fadeIn 0.2s ease;
+}
+
+.install-modal {
+  width: 480px;
+  max-width: 90vw;
+  background: #101117;
+  border: 1px solid #272832;
+  border-radius: 16px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);
+  animation: modalSlideIn 0.3s ease;
+  overflow: hidden;
+}
+
+@keyframes modalSlideIn {
+  from {
+    opacity: 0;
+    transform: translateY(-20px) scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+/* Modal Header */
+.install-modal-header {
+  padding: 32px 32px 24px;
+  text-align: center;
+  border-bottom: 1px solid #272832;
+}
+
+.install-modal-logo {
+  display: flex;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.logo-icon-large {
+  width: 56px;
+  height: 56px;
+  border-radius: 12px;
+  background: linear-gradient(135deg, #ff7a3c 0%, #ff6b2b 100%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 24px;
+  color: #050608;
+  box-shadow: 0 4px 16px rgba(255, 122, 60, 0.3);
+}
+
+.install-modal-title {
+  margin: 0 0 8px 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.install-modal-subtitle {
+  margin: 0;
+  font-size: 13px;
+  color: #9a9bb0;
+  line-height: 1.5;
+}
+
+/* Status Indicator */
+.install-status {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 12px 16px;
+  margin: 16px 24px;
+  border-radius: 8px;
+  font-size: 13px;
+  transition: all 0.2s ease;
+}
+
+.install-status-error {
+  background: rgba(255, 82, 82, 0.1);
+  border: 1px solid rgba(255, 82, 82, 0.3);
+  color: #ff8a8a;
+}
+
+.install-status-pending {
+  background: rgba(255, 152, 0, 0.1);
+  border: 1px solid rgba(255, 152, 0, 0.3);
+  color: #ffb74d;
+}
+
+.status-icon {
+  flex-shrink: 0;
+}
+
+.status-spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid rgba(255, 180, 77, 0.3);
+  border-top-color: #ffb74d;
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+
+/* Installation Steps */
+.install-steps {
+  padding: 24px 32px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.install-step {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.step-number {
+  flex-shrink: 0;
+  width: 28px;
+  height: 28px;
+  border-radius: 8px;
+  background: #1a1b26;
+  border: 1px solid #3a3b4d;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  font-weight: 600;
+  color: #ff7a3c;
+}
+
+.step-content h3 {
+  margin: 0 0 4px 0;
+  font-size: 14px;
+  font-weight: 600;
+  color: #f5f5f7;
+}
+
+.step-content p {
+  margin: 0;
+  font-size: 12px;
+  color: #9a9bb0;
+  line-height: 1.5;
+}
+
+/* Action Buttons */
+.install-modal-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 10px;
+  padding: 16px 24px;
+  border-top: 1px solid #272832;
+  background: #0a0b0f;
+}
+
+.btn-install-primary {
+  border: none;
+  outline: none;
+  background: #000;
+  color: #fff;
+  padding: 10px 18px;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  transition: all 0.2s ease;
+}
+
+.btn-install-primary:hover:not(:disabled) {
+  background: #1a1a1a;
+  transform: translateY(-1px);
+}
+
+.btn-install-primary:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.btn-install-primary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-check-status {
+  border: 1px solid #3a3b4d;
+  outline: none;
+  background: #1a1b26;
+  color: #f5f5f7;
+  padding: 10px 18px;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  transition: all 0.2s ease;
+}
+
+.btn-check-status:hover:not(:disabled) {
+  background: #2a2b3c;
+  border-color: #4a4b5d;
+}
+
+.btn-check-status:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-install-secondary {
+  border: 1px solid #3a3b4d;
+  outline: none;
+  background: transparent;
+  color: #c3c5dd;
+  padding: 10px 18px;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  transition: all 0.2s ease;
+}
+
+.btn-install-secondary:hover:not(:disabled) {
+  background: #1a1b26;
+  border-color: #4a4b5d;
+}
+
+.btn-install-secondary:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Footer */
+.install-modal-footer {
+  padding: 16px 32px 24px;
+  text-align: center;
+}
+
+.install-modal-footer p {
+  margin: 0;
+  font-size: 12px;
+  color: #7a7b8e;
+  line-height: 1.6;
+}
+
+.install-modal-footer strong {
+  color: #c3c5dd;
+  font-weight: 600;
+}
+
+/* Button spinner */
+.btn-spinner {
+  width: 14px;
+  height: 14px;
+  border: 2px solid rgba(255, 255, 255, 0.3);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Secondary primary-style button for "Load available models" */
+.settings-load-btn {
+  margin-top: 8px;
+
+  /* Make it hug the text, not full width */
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: auto !important;
+  min-width: 0;
+  align-self: flex-start;
+
+  /* Size: slightly smaller than Save but same family */
+  padding: 7px 14px;
+  border-radius: 999px;
+
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+
+  border: none;
+  outline: none;
+  cursor: pointer;
+
+  /* Match Save button color palette */
+  background: #ff7a3c;
+  color: #050608;
+
+  transition:
+    background 0.2s ease,
+    box-shadow 0.2s ease,
+    transform 0.15s ease,
+    opacity 0.2s ease;
+}
+
+.settings-load-btn:hover {
+  background: #ff8b52;
+  transform: translateY(-1px);
+  box-shadow: 0 3px 10px rgba(255, 122, 60, 0.28);
+}
+
+.settings-load-btn:active {
+  transform: translateY(0);
+  box-shadow: 0 1px 4px rgba(255, 122, 60, 0.25);
+}
+
+.settings-load-btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}

frontend/utils/api.js

@@ -0,0 +1,212 @@
+/**
+ * API utilities for authenticated requests
+ */
+
+/**
+ * Get backend URL from environment or use relative path (for local dev)
+ * - Production (Vercel): Uses VITE_BACKEND_URL env var (e.g., https://gitpilot-backend.onrender.com)
+ * - Development (local): Uses relative paths (proxied by Vite to localhost:8000)
+ */
+const BACKEND_URL = import.meta.env.VITE_BACKEND_URL || '';
+
+/**
+ * Check if backend URL is configured
+ * @returns {boolean} True if backend URL is set
+ */
+export function isBackendConfigured() {
+  return BACKEND_URL !== '' && BACKEND_URL !== undefined;
+}
+
+/**
+ * Get the configured backend URL
+ * @returns {string} Backend URL or empty string
+ */
+export function getBackendUrl() {
+  return BACKEND_URL;
+}
+
+/**
+ * Construct full API URL
+ * @param {string} path - API endpoint path (e.g., '/api/chat/plan')
+ * @returns {string} Full URL to API endpoint
+ */
+export function apiUrl(path) {
+  // Ensure path starts with /
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  return `${BACKEND_URL}${cleanPath}`;
+}
+
+/**
+ * Enhanced fetch with better error handling for JSON parsing
+ * @param {string} url - URL to fetch
+ * @param {Object} options - Fetch options
+ * @returns {Promise<any>} Parsed JSON response
+ */
+export async function safeFetchJSON(url, options = {}) {
+  try {
+    const response = await fetch(url, options);
+    const contentType = response.headers.get('content-type');
+
+    // Check if response is actually JSON
+    if (!contentType || !contentType.includes('application/json')) {
+      // If not JSON, it might be an HTML error page
+      const text = await response.text();
+
+      // Check if it looks like HTML (starts with <!doctype or <html)
+      if (text.trim().toLowerCase().startsWith('<!doctype') ||
+          text.trim().toLowerCase().startsWith('<html')) {
+        throw new Error(
+          `Backend not reachable. Received HTML instead of JSON. ` +
+          `${!isBackendConfigured() ? 'VITE_BACKEND_URL environment variable is not configured. ' : ''}` +
+          `Please check your backend configuration.`
+        );
+      }
+
+      // Try to return the text as-is if not HTML
+      throw new Error(`Unexpected response type: ${contentType || 'unknown'}. Response: ${text.substring(0, 100)}`);
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(data.detail || data.error || data.message || `Request failed with status ${response.status}`);
+    }
+
+    return data;
+  } catch (error) {
+    // Re-throw with better error message
+    if (error.message.includes('Failed to fetch') || error.message.includes('NetworkError')) {
+      throw new Error(
+        `Cannot connect to backend server. ` +
+        `${!isBackendConfigured() ? 'VITE_BACKEND_URL environment variable is not configured. ' : ''}` +
+        `Please check that the backend is running and accessible.`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get authorization headers with GitHub token
+ * @returns {Object} Headers object with Authorization if token exists
+ */
+export function getAuthHeaders() {
+  const token = localStorage.getItem('github_token');
+
+  if (!token) {
+    return {};
+  }
+
+  return {
+    'Authorization': `Bearer ${token}`,
+  };
+}
+
+/**
+ * Make an authenticated fetch request
+ * @param {string} url - API endpoint URL
+ * @param {Object} options - Fetch options
+ * @returns {Promise<Response>} Fetch response
+ */
+export async function authFetch(url, options = {}) {
+  const headers = {
+    ...getAuthHeaders(),
+    ...options.headers,
+  };
+
+  return fetch(url, {
+    ...options,
+    headers,
+  });
+}
+
+/**
+ * Make an authenticated JSON request
+ * @param {string} url - API endpoint URL
+ * @param {Object} options - Fetch options
+ * @returns {Promise<any>} Parsed JSON response
+ */
+export async function authFetchJSON(url, options = {}) {
+  const headers = {
+    'Content-Type': 'application/json',
+    ...getAuthHeaders(),
+    ...options.headers,
+  };
+
+  const response = await fetch(url, {
+    ...options,
+    headers,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ detail: 'Request failed' }));
+    throw new Error(error.detail || error.message || 'Request failed');
+  }
+
+  return response.json();
+}
+
+// ─── Redesigned API Endpoints ────────────────────────────
+
+/**
+ * Get normalized server status
+ */
+export async function fetchStatus() {
+  return safeFetchJSON(apiUrl("/api/status"));
+}
+
+/**
+ * Get detailed provider status
+ */
+export async function fetchProviderStatus() {
+  return safeFetchJSON(apiUrl("/api/providers/status"));
+}
+
+/**
+ * Test a provider configuration
+ */
+export async function testProvider(providerConfig) {
+  return safeFetchJSON(apiUrl("/api/providers/test"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(providerConfig),
+  });
+}
+
+/**
+ * Start a session by mode
+ */
+export async function startSession(sessionConfig) {
+  return safeFetchJSON(apiUrl("/api/session/start"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(sessionConfig),
+  });
+}
+
+/**
+ * Send a chat message (redesigned endpoint)
+ */
+export async function sendChatMessage(messageConfig) {
+  return safeFetchJSON(apiUrl("/api/chat/send"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(messageConfig),
+  });
+}
+
+/**
+ * Get workspace summary
+ */
+export async function fetchWorkspaceSummary(folderPath) {
+  const query = folderPath ? `?folder_path=${encodeURIComponent(folderPath)}` : "";
+  return safeFetchJSON(apiUrl(`/api/workspace/summary${query}`));
+}
+
+/**
+ * Run security scan on workspace
+ */
+export async function scanWorkspace(path) {
+  const query = path ? `?path=${encodeURIComponent(path)}` : "";
+  return safeFetchJSON(apiUrl(`/api/security/scan-workspace${query}`));
+}

frontend/utils/ws.js

@@ -0,0 +1,157 @@
+/**
+ * WebSocket client for real-time session streaming.
+ *
+ * Provides auto-reconnection, heartbeat, and event dispatching.
+ * Falls back gracefully — callers should always have an HTTP fallback.
+ */
+
+const WS_RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 16000];
+const HEARTBEAT_INTERVAL = 30000;
+const MAX_RECONNECT_ATTEMPTS = 5;
+// If a connection dies within this window it counts as unstable
+const MIN_STABLE_DURATION_MS = 3000;
+
+export class SessionWebSocket {
+  constructor(sessionId, { onMessage, onStatusChange, onError, onConnect, onDisconnect } = {}) {
+    this._sessionId = sessionId;
+    this._handlers = { onMessage, onStatusChange, onError, onConnect, onDisconnect };
+    this._ws = null;
+    this._reconnectAttempt = 0;
+    this._heartbeatTimer = null;
+    this._closed = false;
+    this._connectTime = 0;
+  }
+
+  connect() {
+    if (this._closed) return;
+
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const backendUrl = import.meta.env.VITE_BACKEND_URL || '';
+    let wsUrl;
+
+    if (backendUrl) {
+      // Production: replace http(s) with ws(s)
+      wsUrl = backendUrl.replace(/^http/, 'ws') + `/ws/sessions/${this._sessionId}`;
+    } else {
+      // Dev: same host
+      wsUrl = `${protocol}//${window.location.host}/ws/sessions/${this._sessionId}`;
+    }
+
+    this._ws = new WebSocket(wsUrl);
+
+    this._ws.onopen = () => {
+      this._connectTime = Date.now();
+      this._reconnectAttempt = 0;
+      this._startHeartbeat();
+      this._handlers.onConnect?.();
+    };
+
+    this._ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        this._dispatch(data);
+      } catch (e) {
+        console.warn('[ws] Failed to parse message:', e);
+      }
+    };
+
+    this._ws.onclose = (event) => {
+      this._stopHeartbeat();
+      this._handlers.onDisconnect?.(event);
+
+      if (!this._closed) {
+        // If connection died very quickly, count it as unstable
+        const lived = Date.now() - (this._connectTime || 0);
+        if (lived < MIN_STABLE_DURATION_MS) {
+          this._reconnectAttempt++;
+        }
+
+        if (this._reconnectAttempt < MAX_RECONNECT_ATTEMPTS) {
+          this._scheduleReconnect();
+        } else {
+          console.warn('[ws] Max reconnect attempts reached, giving up.');
+        }
+      }
+    };
+
+    this._ws.onerror = (error) => {
+      this._handlers.onError?.(error);
+    };
+  }
+
+  send(data) {
+    if (this._ws?.readyState === WebSocket.OPEN) {
+      this._ws.send(JSON.stringify(data));
+      return true;
+    }
+    return false;
+  }
+
+  sendMessage(content) {
+    return this.send({ type: 'user_message', content });
+  }
+
+  cancel() {
+    return this.send({ type: 'cancel' });
+  }
+
+  close() {
+    this._closed = true;
+    this._stopHeartbeat();
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+  }
+
+  get connected() {
+    return this._ws?.readyState === WebSocket.OPEN;
+  }
+
+  _dispatch(data) {
+    const { type } = data;
+
+    switch (type) {
+      case 'agent_message':
+      case 'tool_use':
+      case 'tool_result':
+      case 'diff_update':
+      case 'session_restored':
+      case 'message_received':
+        this._handlers.onMessage?.(data);
+        break;
+      case 'status_change':
+        this._handlers.onStatusChange?.(data.status);
+        break;
+      case 'error':
+        this._handlers.onError?.(new Error(data.message));
+        break;
+      case 'pong':
+        break;
+      default:
+        this._handlers.onMessage?.(data);
+    }
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._heartbeatTimer = setInterval(() => {
+      this.send({ type: 'ping' });
+    }, HEARTBEAT_INTERVAL);
+  }
+
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  _scheduleReconnect() {
+    const delay = WS_RECONNECT_DELAYS[
+      Math.min(this._reconnectAttempt, WS_RECONNECT_DELAYS.length - 1)
+    ];
+    this._reconnectAttempt++;
+    setTimeout(() => this.connect(), delay);
+  }
+}

frontend/vite.config.js

@@ -0,0 +1,22 @@
+// frontend/vite.config.js (Fixed)
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    // 💡 FIX: This tells Vite to bind to 0.0.0.0,
+    // making it reachable from the Windows host in WSL.
+    port: 5173,
+    host: true, // <--- Add this line
+    // Only proxy API requests when NOT running in Vercel dev
+    // (Vercel dev handles API routing to serverless functions)
+    proxy: process.env.VERCEL ? undefined : {
+      "/api": "http://localhost:8000",
+      "/ws": {
+        target: "ws://localhost:8000",
+        ws: true
+      }
+    }
+  }
+});

gitpilot/__init__.py

@@ -0,0 +1,5 @@
+"""GitPilot package."""
+
+from .version import __version__
+
+__all__ = ["__version__"]

gitpilot/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running gitpilot as a module: python -m gitpilot"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

gitpilot/_api_core.py

@@ -0,0 +1,2382 @@
+# gitpilot/_api_core.py -- Original API module (re-exported by api.py)
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from fastapi import FastAPI, Query, Path as FPath, Header, HTTPException, UploadFile, File
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from .version import __version__
+from .github_api import (
+    list_user_repos,
+    list_user_repos_paginated,  # Pagination support
+    search_user_repos,  # Search across all repos
+    get_repo_tree,
+    get_file,
+    put_file,
+    execution_context,
+    github_request,
+)
+from .github_app import check_repo_write_access
+from .settings import AppSettings, get_settings, set_provider, update_settings, LLMProvider
+from .agentic import (
+    generate_plan,
+    execute_plan,
+    PlanResult,
+    get_flow_definition,
+    dispatch_request,
+    create_pr_after_execution,
+)
+from .agent_router import route as route_request
+from . import github_issues
+from . import github_pulls
+from . import github_search
+from .session import SessionManager, Session
+from .hooks import HookManager, HookEvent
+from .permissions import PermissionManager, PermissionMode
+from .memory import MemoryManager
+from .context_vault import ContextVault
+from .use_case import UseCaseManager
+from .mcp_client import MCPClient
+from .plugins import PluginManager
+from .skills import SkillManager
+from .smart_model_router import ModelRouter, ModelRouterConfig
+from .topology_registry import (
+    list_topologies as _list_topologies,
+    get_topology_graph as _get_topology_graph,
+    classify_message as _classify_message,
+    get_saved_topology_preference,
+    save_topology_preference,
+)
+from .agent_teams import AgentTeam
+from .learning import LearningEngine
+from .cross_repo import CrossRepoAnalyzer
+from .predictions import PredictiveEngine
+from .security import SecurityScanner
+from .nl_database import NLQueryEngine, QueryDialect, SafetyLevel, TableSchema
+from .github_oauth import (
+    generate_authorization_url,
+    exchange_code_for_token,
+    validate_token,
+    initiate_device_flow,
+    poll_device_token,
+    AuthSession,
+    GitHubUser,
+)
+import os
+import logging
+from .model_catalog import list_models_for_provider
+
+# Optional A2A adapter (MCP ContextForge)
+from .a2a_adapter import router as a2a_router
+
+logger = logging.getLogger(__name__)
+
+# --- Phase 1 singletons ---
+_session_mgr = SessionManager()
+_hook_mgr = HookManager()
+_perm_mgr = PermissionManager()
+
+# --- Phase 2 singletons ---
+_mcp_client = MCPClient()
+_plugin_mgr = PluginManager()
+_skill_mgr = SkillManager()
+_model_router = ModelRouter()
+
+# --- Phase 3 singletons ---
+_agent_team = AgentTeam()
+_learning_engine = LearningEngine()
+_cross_repo = CrossRepoAnalyzer()
+_predictive_engine = PredictiveEngine()
+_security_scanner = SecurityScanner()
+_nl_engine = NLQueryEngine()
+
+app = FastAPI(
+    title="GitPilot API",
+    version=__version__,
+    description="Agentic AI assistant for GitHub repositories.",
+)
+
+# ==========================================================================
+# Optional A2A Adapter (MCP ContextForge)
+# ==========================================================================
+# This is feature-flagged and does not affect the existing UI/REST API unless
+# explicitly enabled.
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+if _env_bool("GITPILOT_ENABLE_A2A", False):
+    logger.info("A2A adapter enabled (mounting /a2a/* endpoints)")
+    app.include_router(a2a_router)
+else:
+    logger.info("A2A adapter disabled (set GITPILOT_ENABLE_A2A=true to enable)")
+
+# ============================================================================
+# CORS Configuration
+# ============================================================================
+# Enable CORS to allow frontend (local dev or Vercel) to connect to backend
+allowed_origins_str = os.getenv("CORS_ORIGINS", "http://localhost:5173")
+allowed_origins = [origin.strip() for origin in allowed_origins_str.split(",")]
+
+logger.info(f"CORS enabled for origins: {allowed_origins}")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def get_github_token(authorization: Optional[str] = Header(None)) -> Optional[str]:
+    """
+    Extract GitHub token from Authorization header.
+
+    Supports formats:
+    - Bearer <token>
+    - token <token>
+    - <token>
+    """
+    if not authorization:
+        return None
+
+    if authorization.startswith("Bearer "):
+        return authorization[7:]
+    elif authorization.startswith("token "):
+        return authorization[6:]
+    else:
+        return authorization
+
+
+# --- FIXED: Added default_branch to model ---
+class RepoSummary(BaseModel):
+    id: int
+    name: str
+    full_name: str
+    private: bool
+    owner: str
+    default_branch: str = "main"  # <--- CRITICAL FIX: Defaults to main, but can be master/dev
+
+
+class PaginatedReposResponse(BaseModel):
+    """Response model for paginated repository listing."""
+    repositories: List[RepoSummary]
+    page: int
+    per_page: int
+    total_count: Optional[int] = None
+    has_more: bool
+    query: Optional[str] = None
+
+
+class FileEntry(BaseModel):
+    path: str
+    type: str
+
+
+class FileTreeResponse(BaseModel):
+    files: List[FileEntry] = Field(default_factory=list)
+
+
+class FileContent(BaseModel):
+    path: str
+    encoding: str = "utf-8"
+    content: str
+
+
+class CommitRequest(BaseModel):
+    path: str
+    content: str
+    message: str
+
+
+class CommitResponse(BaseModel):
+    path: str
+    commit_sha: str
+    commit_url: Optional[str] = None
+
+
+class SettingsResponse(BaseModel):
+    provider: LLMProvider
+    providers: List[LLMProvider]
+    openai: dict
+    claude: dict
+    watsonx: dict
+    ollama: dict
+    langflow_url: str
+    has_langflow_plan_flow: bool
+
+
+class ProviderModelsResponse(BaseModel):
+    provider: LLMProvider
+    models: List[str] = Field(default_factory=list)
+    error: Optional[str] = None
+
+
+class ProviderUpdate(BaseModel):
+    provider: LLMProvider
+
+
+class ChatPlanRequest(BaseModel):
+    repo_owner: str
+    repo_name: str
+    goal: str
+    branch_name: Optional[str] = None
+
+
+class ExecutePlanRequest(BaseModel):
+    repo_owner: str
+    repo_name: str
+    plan: PlanResult
+    branch_name: Optional[str] = None
+
+
+class AuthUrlResponse(BaseModel):
+    authorization_url: str
+    state: str
+
+
+class AuthCallbackRequest(BaseModel):
+    code: str
+    state: str
+
+
+class TokenValidationRequest(BaseModel):
+    access_token: str
+
+
+class UserInfoResponse(BaseModel):
+    user: GitHubUser
+    authenticated: bool
+
+
+class RepoAccessResponse(BaseModel):
+    can_write: bool
+    app_installed: bool
+    auth_type: str
+
+
+# --- v2 Request/Response models ---
+
+class ChatRequest(BaseModel):
+    """Unified chat request for the conversational dispatcher."""
+    repo_owner: str
+    repo_name: str
+    message: str
+    branch_name: Optional[str] = None
+    auto_pr: bool = False
+    topology_id: Optional[str] = None  # Override topology for this request
+
+
+class IssueCreateRequest(BaseModel):
+    title: str
+    body: Optional[str] = None
+    labels: Optional[List[str]] = None
+    assignees: Optional[List[str]] = None
+    milestone: Optional[int] = None
+
+
+class IssueUpdateRequest(BaseModel):
+    title: Optional[str] = None
+    body: Optional[str] = None
+    state: Optional[str] = None
+    labels: Optional[List[str]] = None
+    assignees: Optional[List[str]] = None
+    milestone: Optional[int] = None
+
+
+class IssueCommentRequest(BaseModel):
+    body: str
+
+
+class PRCreateRequest(BaseModel):
+    title: str
+    head: str
+    base: str
+    body: Optional[str] = None
+    draft: bool = False
+
+
+class PRMergeRequest(BaseModel):
+    merge_method: str = "merge"
+    commit_title: Optional[str] = None
+    commit_message: Optional[str] = None
+
+
+class SearchRequest(BaseModel):
+    query: str
+    per_page: int = 30
+    page: int = 1
+
+
+# ============================================================================
+# Repository Endpoints - Enterprise Grade with Pagination & Search
+# ============================================================================
+
+@app.get("/api/repos", response_model=PaginatedReposResponse)
+async def api_list_repos(
+    query: Optional[str] = Query(None, description="Search query (searches across ALL repositories)"),
+    page: int = Query(1, ge=1, description="Page number (starts at 1)"),
+    per_page: int = Query(100, ge=1, le=100, description="Results per page (max 100)"),
+    authorization: Optional[str] = Header(None),
+):
+    """
+    List user repositories with enterprise-grade pagination and search.
+    Includes default_branch information for correct frontend routing.
+    """
+    token = get_github_token(authorization)
+
+    try:
+        if query:
+            # SEARCH MODE: Search across ALL repositories
+            result = await search_user_repos(
+                query=query,
+                page=page,
+                per_page=per_page,
+                token=token
+            )
+        else:
+            # PAGINATION MODE: Return repos page by page
+            result = await list_user_repos_paginated(
+                page=page,
+                per_page=per_page,
+                token=token
+            )
+
+        # --- FIXED: Mapping default_branch ---
+        repos = [
+            RepoSummary(
+                id=r["id"],
+                name=r["name"],
+                full_name=r["full_name"],
+                private=r["private"],
+                owner=r["owner"],
+                default_branch=r.get("default_branch", "main"),  # <--- CRITICAL FIX
+            )
+            for r in result["repositories"]
+        ]
+
+        return PaginatedReposResponse(
+            repositories=repos,
+            page=result["page"],
+            per_page=result["per_page"],
+            total_count=result.get("total_count"),
+            has_more=result["has_more"],
+            query=query,
+        )
+
+    except Exception as e:
+        logging.exception("Error fetching repositories")
+        return JSONResponse(
+            content={
+                "error": f"Failed to fetch repositories: {str(e)}",
+                "repositories": [],
+                "page": page,
+                "per_page": per_page,
+                "has_more": False,
+            },
+            status_code=500
+        )
+
+
+@app.get("/api/repos/all")
+async def api_list_all_repos(
+    query: Optional[str] = Query(None, description="Search query"),
+    authorization: Optional[str] = Header(None),
+):
+    """
+    Fetch ALL user repositories at once (no pagination).
+    Useful for quick searches, but paginated endpoint is preferred.
+    """
+    token = get_github_token(authorization)
+
+    try:
+        # Fetch all repositories (this will make multiple API calls)
+        all_repos = []
+        page = 1
+        max_pages = 15  # Safety limit: 1500 repos max (15 * 100)
+
+        while page <= max_pages:
+            result = await list_user_repos_paginated(
+                page=page,
+                per_page=100,
+                token=token
+            )
+
+            all_repos.extend(result["repositories"])
+
+            if not result["has_more"]:
+                break
+
+            page += 1
+
+        # Filter by query if provided
+        if query:
+            query_lower = query.lower()
+            all_repos = [
+                r for r in all_repos
+                if query_lower in r["name"].lower() or query_lower in r["full_name"].lower()
+            ]
+
+        # --- FIXED: Mapping default_branch ---
+        repos = [
+            RepoSummary(
+                id=r["id"],
+                name=r["name"],
+                full_name=r["full_name"],
+                private=r["private"],
+                owner=r["owner"],
+                default_branch=r.get("default_branch", "main"),  # <--- CRITICAL FIX
+            )
+            for r in all_repos
+        ]
+
+        return {
+            "repositories": repos,
+            "total_count": len(repos),
+            "query": query,
+        }
+
+    except Exception as e:
+        logging.exception("Error fetching all repositories")
+        return JSONResponse(
+            content={"error": f"Failed to fetch repositories: {str(e)}"},
+            status_code=500
+        )
+
+
+@app.get("/api/repos/{owner}/{repo}/tree", response_model=FileTreeResponse)
+async def api_repo_tree(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    ref: Optional[str] = Query(
+        None,
+        description="Git reference (branch, tag, or commit SHA). If omitted, defaults to HEAD.",
+    ),
+    authorization: Optional[str] = Header(None),
+):
+    """
+    Get the file tree for a repository.
+    Handles 'main' vs 'master' discrepancies and empty repositories gracefully.
+    """
+    token = get_github_token(authorization)
+
+    # Keep legacy behavior: missing/empty ref behaves like HEAD.
+    ref_value = (ref or "").strip() or "HEAD"
+
+    try:
+        tree = await get_repo_tree(owner, repo, token=token, ref=ref_value)
+        return FileTreeResponse(files=[FileEntry(**f) for f in tree])
+
+    except HTTPException as e:
+        if e.status_code == 409:
+            return FileTreeResponse(files=[])
+
+        if e.status_code == 404:
+            return JSONResponse(
+                status_code=404,
+                content={
+                    "detail": f"Ref '{ref_value}' not found. The repository might be using a different default branch (e.g., 'master')."
+                }
+            )
+
+        raise e
+
+
+@app.get("/api/repos/{owner}/{repo}/file", response_model=FileContent)
+async def api_get_file(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    path: str = Query(...),
+    authorization: Optional[str] = Header(None),
+):
+    token = get_github_token(authorization)
+    content = await get_file(owner, repo, path, token=token)
+    return FileContent(path=path, content=content)
+
+
+@app.post("/api/repos/{owner}/{repo}/file", response_model=CommitResponse)
+async def api_put_file(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    payload: CommitRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    token = get_github_token(authorization)
+    result = await put_file(
+        owner, repo, payload.path, payload.content, payload.message, token=token
+    )
+    return CommitResponse(**result)
+
+
+# ============================================================================
+# Settings Endpoints
+# ============================================================================
+
+@app.get("/api/settings", response_model=SettingsResponse)
+async def api_get_settings():
+    s: AppSettings = get_settings()
+    return SettingsResponse(
+        provider=s.provider,
+        providers=[LLMProvider.openai, LLMProvider.claude, LLMProvider.watsonx, LLMProvider.ollama],
+        openai=s.openai.model_dump(),
+        claude=s.claude.model_dump(),
+        watsonx=s.watsonx.model_dump(),
+        ollama=s.ollama.model_dump(),
+        langflow_url=s.langflow_url,
+        has_langflow_plan_flow=bool(s.langflow_plan_flow_id),
+    )
+
+
+@app.get("/api/settings/models", response_model=ProviderModelsResponse)
+async def api_list_models(provider: Optional[LLMProvider] = Query(None)):
+    """
+    Return the list of LLM models available for a provider.
+
+    If 'provider' is not given, use the currently active provider from settings.
+    """
+    s: AppSettings = get_settings()
+    effective_provider = provider or s.provider
+
+    models, error = list_models_for_provider(effective_provider, s)
+
+    return ProviderModelsResponse(
+        provider=effective_provider,
+        models=models,
+        error=error,
+    )
+
+
+@app.post("/api/settings/provider", response_model=SettingsResponse)
+async def api_set_provider(update: ProviderUpdate):
+    s = set_provider(update.provider)
+    return SettingsResponse(
+        provider=s.provider,
+        providers=[LLMProvider.openai, LLMProvider.claude, LLMProvider.watsonx, LLMProvider.ollama],
+        openai=s.openai.model_dump(),
+        claude=s.claude.model_dump(),
+        watsonx=s.watsonx.model_dump(),
+        ollama=s.ollama.model_dump(),
+        langflow_url=s.langflow_url,
+        has_langflow_plan_flow=bool(s.langflow_plan_flow_id),
+    )
+
+
+@app.put("/api/settings/llm", response_model=SettingsResponse)
+async def api_update_llm_settings(updates: dict):
+    """Update full LLM settings including provider-specific configs."""
+    s = update_settings(updates)
+    return SettingsResponse(
+        provider=s.provider,
+        providers=[LLMProvider.openai, LLMProvider.claude, LLMProvider.watsonx, LLMProvider.ollama],
+        openai=s.openai.model_dump(),
+        claude=s.claude.model_dump(),
+        watsonx=s.watsonx.model_dump(),
+        ollama=s.ollama.model_dump(),
+        langflow_url=s.langflow_url,
+        has_langflow_plan_flow=bool(s.langflow_plan_flow_id),
+    )
+
+
+# ============================================================================
+# Chat Endpoints
+# ============================================================================
+
+@app.post("/api/chat/plan", response_model=PlanResult)
+async def api_chat_plan(req: ChatPlanRequest, authorization: Optional[str] = Header(None)):
+    token = get_github_token(authorization)
+
+    # ✅ Added logging for branch_name received
+    logger.info(
+        "PLAN REQUEST: %s/%s | branch_name=%r",
+        req.repo_owner,
+        req.repo_name,
+        req.branch_name,
+    )
+
+    with execution_context(token, ref=req.branch_name):  # ✅ set ref context
+        full_name = f"{req.repo_owner}/{req.repo_name}"
+        plan = await generate_plan(req.goal, full_name, token=token, branch_name=req.branch_name)
+        return plan
+
+
+@app.post("/api/chat/execute")
+async def api_chat_execute(
+    req: ExecutePlanRequest,
+    authorization: Optional[str] = Header(None)
+):
+    token = get_github_token(authorization)
+
+    # ✅ FIX: use execution_context(token, ref=req.branch_name) so tool calls that rely on context
+    # never accidentally run on HEAD/default when branch_name is provided.
+    with execution_context(token, ref=req.branch_name):
+        full_name = f"{req.repo_owner}/{req.repo_name}"
+        result = await execute_plan(
+            req.plan, full_name, token=token, branch_name=req.branch_name
+        )
+        if isinstance(result, dict):
+            result.setdefault(
+                "mode",
+                "sticky" if req.branch_name else "hard-switch",
+            )
+        return result
+
+
+@app.get("/api/flow/current")
+async def api_get_flow(topology: Optional[str] = Query(None)):
+    """Return the agent flow definition as a graph.
+
+    If ``topology`` query param is provided, returns the graph for that
+    topology.  Otherwise falls back to the user's saved preference, and
+    finally to the legacy ``get_flow_definition()`` output for full
+    backward compatibility.
+    """
+    tid = topology or get_saved_topology_preference()
+    if tid:
+        return _get_topology_graph(tid)
+    # Legacy path — returns the original hardcoded graph
+    flow = await get_flow_definition()
+    return flow
+
+
+# ============================================================================
+# Topology Registry Endpoints (additive — no existing behaviour changed)
+# ============================================================================
+
+@app.get("/api/flow/topologies")
+async def api_list_topologies():
+    """Return lightweight summaries of all available topology presets."""
+    return _list_topologies()
+
+
+@app.get("/api/flow/topology/{topology_id}")
+async def api_get_topology(topology_id: str):
+    """Return the full flow graph for a specific topology."""
+    return _get_topology_graph(topology_id)
+
+
+class ClassifyRequest(BaseModel):
+    message: str
+
+
+@app.post("/api/flow/classify")
+async def api_classify_message(req: ClassifyRequest):
+    """Auto-detect the best topology for a given user message.
+
+    Returns the recommended topology, confidence score, and up to 4
+    alternatives ranked by relevance.
+    """
+    result = _classify_message(req.message)
+    return result.to_dict()
+
+
+class TopologyPrefRequest(BaseModel):
+    topology: str
+
+
+@app.get("/api/settings/topology")
+async def api_get_topology_pref():
+    """Return the user's saved topology preference (or null)."""
+    pref = get_saved_topology_preference()
+    return {"topology": pref}
+
+
+@app.post("/api/settings/topology")
+async def api_set_topology_pref(req: TopologyPrefRequest):
+    """Save the user's preferred topology."""
+    save_topology_preference(req.topology)
+    return {"status": "ok", "topology": req.topology}
+
+
+# ============================================================================
+# Conversational Chat Endpoint (v2 upgrade)
+# ============================================================================
+
+@app.post("/api/chat/message")
+async def api_chat_message(req: ChatRequest, authorization: Optional[str] = Header(None)):
+    """
+    Unified conversational endpoint.  The router analyses the message and
+    dispatches to the appropriate agent (issue, PR, search, review, learning,
+    or the existing plan+execute pipeline).
+    """
+    token = get_github_token(authorization)
+
+    logger.info(
+        "CHAT MESSAGE: %s/%s | message=%r | branch=%r",
+        req.repo_owner,
+        req.repo_name,
+        req.message[:80],
+        req.branch_name,
+    )
+
+    with execution_context(token, ref=req.branch_name):
+        full_name = f"{req.repo_owner}/{req.repo_name}"
+        result = await dispatch_request(
+            req.message, full_name, token=token, branch_name=req.branch_name,
+            topology_id=req.topology_id,
+        )
+
+        # If auto_pr is requested and execution completed, create PR
+        if (
+            req.auto_pr
+            and isinstance(result, dict)
+            and result.get("category") == "plan_execute"
+            and result.get("plan")
+        ):
+            result["auto_pr_hint"] = (
+                "Plan generated. Execute it first, then auto-PR will be created."
+            )
+
+        return result
+
+
+@app.post("/api/chat/execute-with-pr")
+async def api_chat_execute_with_pr(
+    req: ExecutePlanRequest,
+    authorization: Optional[str] = Header(None),
+):
+    """Execute a plan AND automatically create a pull request afterwards."""
+    token = get_github_token(authorization)
+
+    with execution_context(token, ref=req.branch_name):
+        full_name = f"{req.repo_owner}/{req.repo_name}"
+        result = await execute_plan(
+            req.plan, full_name, token=token, branch_name=req.branch_name,
+        )
+
+        if isinstance(result, dict) and result.get("status") == "completed":
+            branch = result.get("branch", req.branch_name)
+            if branch:
+                pr = await create_pr_after_execution(
+                    full_name,
+                    branch,
+                    req.plan.goal,
+                    result.get("executionLog", {}),
+                    token=token,
+                )
+                if pr:
+                    result["pull_request"] = {
+                        "number": pr.get("number"),
+                        "url": pr.get("html_url"),
+                        "title": pr.get("title"),
+                    }
+
+            result.setdefault(
+                "mode",
+                "sticky" if req.branch_name else "hard-switch",
+            )
+
+        return result
+
+
+# ============================================================================
+# Issue Endpoints (v2 upgrade)
+# ============================================================================
+
+@app.get("/api/repos/{owner}/{repo}/issues")
+async def api_list_issues(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    state: str = Query("open"),
+    labels: Optional[str] = Query(None),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """List issues for a repository."""
+    token = get_github_token(authorization)
+    issues = await github_issues.list_issues(
+        owner, repo, state=state, labels=labels,
+        per_page=per_page, page=page, token=token,
+    )
+    return {"issues": issues, "page": page, "per_page": per_page}
+
+
+@app.get("/api/repos/{owner}/{repo}/issues/{issue_number}")
+async def api_get_issue(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    issue_number: int = FPath(...),
+    authorization: Optional[str] = Header(None),
+):
+    """Get a single issue."""
+    token = get_github_token(authorization)
+    return await github_issues.get_issue(owner, repo, issue_number, token=token)
+
+
+@app.post("/api/repos/{owner}/{repo}/issues")
+async def api_create_issue(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    payload: IssueCreateRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    """Create a new issue."""
+    token = get_github_token(authorization)
+    return await github_issues.create_issue(
+        owner, repo, payload.title,
+        body=payload.body, labels=payload.labels,
+        assignees=payload.assignees, milestone=payload.milestone,
+        token=token,
+    )
+
+
+@app.patch("/api/repos/{owner}/{repo}/issues/{issue_number}")
+async def api_update_issue(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    issue_number: int = FPath(...),
+    payload: IssueUpdateRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    """Update an existing issue."""
+    token = get_github_token(authorization)
+    return await github_issues.update_issue(
+        owner, repo, issue_number,
+        title=payload.title, body=payload.body, state=payload.state,
+        labels=payload.labels, assignees=payload.assignees,
+        milestone=payload.milestone, token=token,
+    )
+
+
+@app.get("/api/repos/{owner}/{repo}/issues/{issue_number}/comments")
+async def api_list_issue_comments(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    issue_number: int = FPath(...),
+    authorization: Optional[str] = Header(None),
+):
+    """List comments on an issue."""
+    token = get_github_token(authorization)
+    return await github_issues.list_issue_comments(owner, repo, issue_number, token=token)
+
+
+@app.post("/api/repos/{owner}/{repo}/issues/{issue_number}/comments")
+async def api_add_issue_comment(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    issue_number: int = FPath(...),
+    payload: IssueCommentRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    """Add a comment to an issue."""
+    token = get_github_token(authorization)
+    return await github_issues.add_issue_comment(
+        owner, repo, issue_number, payload.body, token=token,
+    )
+
+
+# ============================================================================
+# Pull Request Endpoints (v2 upgrade)
+# ============================================================================
+
+@app.get("/api/repos/{owner}/{repo}/pulls")
+async def api_list_pulls(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    state: str = Query("open"),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """List pull requests."""
+    token = get_github_token(authorization)
+    prs = await github_pulls.list_pull_requests(
+        owner, repo, state=state, per_page=per_page, page=page, token=token,
+    )
+    return {"pull_requests": prs, "page": page, "per_page": per_page}
+
+
+@app.get("/api/repos/{owner}/{repo}/pulls/{pull_number}")
+async def api_get_pull(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    pull_number: int = FPath(...),
+    authorization: Optional[str] = Header(None),
+):
+    """Get a single pull request."""
+    token = get_github_token(authorization)
+    return await github_pulls.get_pull_request(owner, repo, pull_number, token=token)
+
+
+@app.post("/api/repos/{owner}/{repo}/pulls")
+async def api_create_pull(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    payload: PRCreateRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    """Create a new pull request."""
+    token = get_github_token(authorization)
+    return await github_pulls.create_pull_request(
+        owner, repo, title=payload.title, head=payload.head,
+        base=payload.base, body=payload.body, draft=payload.draft,
+        token=token,
+    )
+
+
+@app.put("/api/repos/{owner}/{repo}/pulls/{pull_number}/merge")
+async def api_merge_pull(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    pull_number: int = FPath(...),
+    payload: PRMergeRequest = ...,
+    authorization: Optional[str] = Header(None),
+):
+    """Merge a pull request."""
+    token = get_github_token(authorization)
+    return await github_pulls.merge_pull_request(
+        owner, repo, pull_number,
+        merge_method=payload.merge_method,
+        commit_title=payload.commit_title,
+        commit_message=payload.commit_message,
+        token=token,
+    )
+
+
+@app.get("/api/repos/{owner}/{repo}/pulls/{pull_number}/files")
+async def api_list_pr_files(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    pull_number: int = FPath(...),
+    authorization: Optional[str] = Header(None),
+):
+    """List files changed in a pull request."""
+    token = get_github_token(authorization)
+    return await github_pulls.list_pr_files(owner, repo, pull_number, token=token)
+
+
+# ============================================================================
+# Search Endpoints (v2 upgrade)
+# ============================================================================
+
+@app.get("/api/search/code")
+async def api_search_code(
+    q: str = Query(..., description="Search query"),
+    owner: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    language: Optional[str] = Query(None),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """Search for code across GitHub."""
+    token = get_github_token(authorization)
+    return await github_search.search_code(
+        q, owner=owner, repo=repo, language=language,
+        per_page=per_page, page=page, token=token,
+    )
+
+
+@app.get("/api/search/issues")
+async def api_search_issues(
+    q: str = Query(..., description="Search query"),
+    owner: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    state: Optional[str] = Query(None),
+    label: Optional[str] = Query(None),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """Search issues and pull requests."""
+    token = get_github_token(authorization)
+    return await github_search.search_issues(
+        q, owner=owner, repo=repo, state=state, label=label,
+        per_page=per_page, page=page, token=token,
+    )
+
+
+@app.get("/api/search/repositories")
+async def api_search_repositories(
+    q: str = Query(..., description="Search query"),
+    language: Optional[str] = Query(None),
+    sort: Optional[str] = Query(None),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """Search for repositories."""
+    token = get_github_token(authorization)
+    return await github_search.search_repositories(
+        q, language=language, sort=sort,
+        per_page=per_page, page=page, token=token,
+    )
+
+
+@app.get("/api/search/users")
+async def api_search_users(
+    q: str = Query(..., description="Search query"),
+    type_filter: Optional[str] = Query(None, alias="type"),
+    location: Optional[str] = Query(None),
+    language: Optional[str] = Query(None),
+    per_page: int = Query(30, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    authorization: Optional[str] = Header(None),
+):
+    """Search for GitHub users and organizations."""
+    token = get_github_token(authorization)
+    return await github_search.search_users(
+        q, type_filter=type_filter, location=location, language=language,
+        per_page=per_page, page=page, token=token,
+    )
+
+
+# ============================================================================
+# Route Analysis Endpoint (v2 upgrade)
+# ============================================================================
+
+@app.post("/api/chat/route")
+async def api_chat_route(payload: dict):
+    """Preview how a message would be routed without executing it.
+
+    Useful for the frontend to display which agent(s) will handle the request.
+    """
+    message = payload.get("message", "")
+    if not message:
+        return JSONResponse({"error": "message is required"}, status_code=400)
+
+    workflow = route_request(message)
+    return {
+        "category": workflow.category.value,
+        "agents": [a.value for a in workflow.agents],
+        "description": workflow.description,
+        "requires_repo_context": workflow.requires_repo_context,
+        "entity_number": workflow.entity_number,
+        "metadata": workflow.metadata,
+    }
+
+
+# ============================================================================
+# Authentication Endpoints (Web Flow + Device Flow)
+# ============================================================================
+
+@app.get("/api/auth/url", response_model=AuthUrlResponse)
+async def api_get_auth_url():
+    """
+    Generate GitHub OAuth authorization URL (Web Flow).
+    Requires Client Secret to be configured.
+    """
+    auth_url, state = generate_authorization_url()
+    return AuthUrlResponse(authorization_url=auth_url, state=state)
+
+
+@app.post("/api/auth/callback", response_model=AuthSession)
+async def api_auth_callback(request: AuthCallbackRequest):
+    """
+    Handle GitHub OAuth callback (Web Flow).
+    Exchange the authorization code for an access token.
+    """
+    try:
+        session = await exchange_code_for_token(request.code, request.state)
+        return session
+    except ValueError as e:
+        return JSONResponse(
+            {"error": str(e)},
+            status_code=400,
+        )
+
+
+@app.post("/api/auth/validate", response_model=UserInfoResponse)
+async def api_validate_token(request: TokenValidationRequest):
+    """
+    Validate a GitHub access token and return user information.
+    """
+    user = await validate_token(request.access_token)
+    if user:
+        return UserInfoResponse(user=user, authenticated=True)
+    return UserInfoResponse(
+        user=GitHubUser(login="", id=0, avatar_url=""),
+        authenticated=False,
+    )
+
+
+@app.post("/api/auth/device/code")
+async def api_device_code():
+    """
+    Start the device login flow (Step 1).
+    Does NOT require a client secret.
+    """
+    try:
+        data = await initiate_device_flow()
+        return data
+    except Exception as e:
+        return JSONResponse({"error": str(e)}, status_code=500)
+
+
+@app.post("/api/auth/device/poll")
+async def api_device_poll(payload: dict):
+    """
+    Poll GitHub to check if user authorized the device (Step 2).
+    """
+    device_code = payload.get("device_code")
+    if not device_code:
+        return JSONResponse({"error": "Missing device_code"}, status_code=400)
+
+    try:
+        session = await poll_device_token(device_code)
+        if session:
+            return session
+
+        return JSONResponse({"status": "pending"}, status_code=202)
+    except ValueError as e:
+        return JSONResponse({"error": str(e)}, status_code=400)
+
+
+@app.get("/api/auth/status")
+async def api_auth_status():
+    """
+    Smart check: Do we have a secret (Web Flow) or just ID (Device Flow)?
+    This tells the frontend which UI to render.
+    """
+    has_secret = bool(os.getenv("GITHUB_CLIENT_SECRET"))
+    has_id = bool(os.getenv("GITHUB_CLIENT_ID", "Iv23litmRp80Z6wmlyRn"))
+
+    return {
+        "mode": "web" if has_secret else "device",
+        "configured": has_id,
+        "oauth_configured": has_secret,
+        "pat_configured": bool(os.getenv("GITPILOT_GITHUB_TOKEN") or os.getenv("GITHUB_TOKEN")),
+    }
+
+
+@app.get("/api/auth/app-url")
+async def api_get_app_url():
+    """Get GitHub App installation URL."""
+    app_slug = os.getenv("GITHUB_APP_SLUG", "gitpilota")
+    app_url = f"https://github.com/apps/{app_slug}"
+    return {
+        "app_url": app_url,
+        "app_slug": app_slug,
+    }
+
+
+@app.get("/api/auth/installation-status")
+async def api_check_installation_status():
+    """Check if GitHub App is installed for the current user."""
+    pat_token = os.getenv("GITPILOT_GITHUB_TOKEN") or os.getenv("GITHUB_TOKEN")
+
+    if pat_token:
+        user = await validate_token(pat_token)
+        if user:
+            return {
+                "installed": True,
+                "access_token": pat_token,
+                "user": user,
+                "auth_type": "pat",
+            }
+
+    github_app_id = os.getenv("GITHUB_APP_ID", "2313985")
+    if not github_app_id:
+        return {
+            "installed": False,
+            "message": "GitHub authentication not configured.",
+            "auth_type": "none",
+        }
+
+    return {
+        "installed": False,
+        "message": "GitHub App not installed.",
+        "auth_type": "github_app",
+    }
+
+
+@app.get("/api/auth/repo-access", response_model=RepoAccessResponse)
+async def api_check_repo_access(
+    owner: str = Query(...),
+    repo: str = Query(...),
+    authorization: Optional[str] = Header(None),
+):
+    """
+    Check if we have write access to a repository via User token or GitHub App.
+
+    This endpoint helps the frontend determine if it should show
+    installation prompts or if the user already has sufficient permissions.
+    """
+    token = get_github_token(authorization)
+    access_info = await check_repo_write_access(owner, repo, user_token=token)
+
+    return RepoAccessResponse(
+        can_write=access_info["can_write"],
+        app_installed=access_info["app_installed"],
+        auth_type=access_info["auth_type"],
+    )
+
+
+# ============================================================================
+# Session Endpoints (Phase 1)
+# ============================================================================
+
+@app.get("/api/sessions")
+async def api_list_sessions():
+    """List all saved sessions."""
+    return {"sessions": _session_mgr.list_sessions()}
+
+
+@app.post("/api/sessions")
+async def api_create_session(payload: dict):
+    """Create a new session.
+
+    Accepts either legacy single-repo or multi-repo format:
+      Legacy: {"repo_full_name": "owner/repo", "branch": "main"}
+      Multi:  {"repos": [{full_name, branch, mode}], "active_repo": "owner/repo"}
+    """
+    repo = payload.get("repo_full_name", "")
+    branch = payload.get("branch")
+    name = payload.get("name")  # optional — derived from first user prompt
+    session = _session_mgr.create(repo_full_name=repo, branch=branch, name=name)
+
+    # Multi-repo context support
+    if payload.get("repos"):
+        session.repos = payload["repos"]
+        session.active_repo = payload.get("active_repo", repo)
+    elif repo:
+        session.repos = [{"full_name": repo, "branch": branch or "main", "mode": "write"}]
+        session.active_repo = repo
+
+    _session_mgr.save(session)
+    return {"session_id": session.id, "status": session.status}
+
+
+@app.get("/api/sessions/{session_id}")
+async def api_get_session(session_id: str):
+    """Get session details."""
+    session = _session_mgr.load(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {
+        "id": session.id,
+        "status": session.status,
+        "repo_full_name": session.repo_full_name,
+        "branch": session.branch,
+        "created_at": session.created_at,
+        "message_count": len(session.messages),
+        "checkpoint_count": len(session.checkpoints),
+        "repos": session.repos,
+        "active_repo": session.active_repo,
+    }
+
+
+@app.delete("/api/sessions/{session_id}")
+async def api_delete_session(session_id: str):
+    """Delete a session."""
+    deleted = _session_mgr.delete(session_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {"deleted": True}
+
+
+@app.patch("/api/sessions/{session_id}/context")
+async def api_update_session_context(session_id: str, payload: dict):
+    """Add, remove, or activate repos in a session's multi-repo context.
+
+    Actions:
+      {"action": "add", "repo_full_name": "owner/repo", "branch": "main"}
+      {"action": "remove", "repo_full_name": "owner/repo"}
+      {"action": "set_active", "repo_full_name": "owner/repo"}
+    """
+    session = _session_mgr.load(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    action = payload.get("action")
+    repo_name = payload.get("repo_full_name")
+    if not action or not repo_name:
+        raise HTTPException(status_code=400, detail="action and repo_full_name required")
+
+    if action == "add":
+        branch = payload.get("branch", "main")
+        if not any(r.get("full_name") == repo_name for r in session.repos):
+            session.repos.append({
+                "full_name": repo_name,
+                "branch": branch,
+                "mode": "read",
+            })
+        if not session.active_repo:
+            session.active_repo = repo_name
+    elif action == "remove":
+        session.repos = [r for r in session.repos if r.get("full_name") != repo_name]
+        if session.active_repo == repo_name:
+            session.active_repo = session.repos[0]["full_name"] if session.repos else None
+    elif action == "set_active":
+        if any(r.get("full_name") == repo_name for r in session.repos):
+            # Update mode flags
+            for r in session.repos:
+                r["mode"] = "write" if r.get("full_name") == repo_name else "read"
+            session.active_repo = repo_name
+        else:
+            raise HTTPException(status_code=400, detail="Repo not in session context")
+    else:
+        raise HTTPException(status_code=400, detail=f"Unknown action: {action}")
+
+    _session_mgr.save(session)
+    return {
+        "repos": session.repos,
+        "active_repo": session.active_repo,
+    }
+
+
+@app.post("/api/sessions/{session_id}/checkpoint")
+async def api_create_checkpoint(session_id: str, payload: dict):
+    """Create a checkpoint for a session."""
+    session = _session_mgr.load(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    label = payload.get("label", "checkpoint")
+    cp = _session_mgr.create_checkpoint(session, label=label)
+    return {"checkpoint_id": cp.id, "label": cp.label, "created_at": cp.created_at}
+
+
+# ============================================================================
+# Hooks Endpoints (Phase 1)
+# ============================================================================
+
+@app.get("/api/hooks")
+async def api_list_hooks():
+    """List registered hooks."""
+    return {"hooks": _hook_mgr.list_hooks()}
+
+
+@app.post("/api/hooks")
+async def api_register_hook(payload: dict):
+    """Register a new hook."""
+    from .hooks import HookDefinition
+    try:
+        hook = HookDefinition(
+            event=HookEvent(payload["event"]),
+            name=payload["name"],
+            command=payload.get("command"),
+            blocking=payload.get("blocking", False),
+            timeout=payload.get("timeout", 30),
+        )
+        _hook_mgr.register(hook)
+        return {"registered": True, "name": hook.name, "event": hook.event.value}
+    except (KeyError, ValueError) as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.delete("/api/hooks/{event}/{name}")
+async def api_unregister_hook(event: str, name: str):
+    """Unregister a hook by event and name."""
+    try:
+        _hook_mgr.unregister(HookEvent(event), name)
+        return {"unregistered": True}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# ============================================================================
+# Permissions Endpoints (Phase 1)
+# ============================================================================
+
+@app.get("/api/permissions")
+async def api_get_permissions():
+    """Get current permission policy."""
+    return _perm_mgr.to_dict()
+
+
+@app.put("/api/permissions/mode")
+async def api_set_permission_mode(payload: dict):
+    """Set the permission mode (normal, plan, auto)."""
+    mode_str = payload.get("mode", "normal")
+    try:
+        _perm_mgr.policy.mode = PermissionMode(mode_str)
+        return {"mode": _perm_mgr.policy.mode.value}
+    except ValueError:
+        raise HTTPException(status_code=400, detail=f"Invalid mode: {mode_str}")
+
+
+# ============================================================================
+# Project Context / Memory Endpoints (Phase 1)
+# ============================================================================
+
+@app.get("/api/repos/{owner}/{repo}/context")
+async def api_get_project_context(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+):
+    """Get project conventions and memory for a repository workspace."""
+    from pathlib import Path as StdPath
+    workspace_path = StdPath.home() / ".gitpilot" / "workspaces" / owner / repo
+    if not workspace_path.exists():
+        return {"conventions": "", "rules": [], "auto_memory": {}, "system_prompt": ""}
+    mgr = MemoryManager(workspace_path)
+    ctx = mgr.load_context()
+    return {
+        "conventions": ctx.conventions,
+        "rules": ctx.rules,
+        "auto_memory": ctx.auto_memory,
+        "system_prompt": ctx.to_system_prompt(),
+    }
+
+
+@app.post("/api/repos/{owner}/{repo}/context/init")
+async def api_init_project_context(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+):
+    """Initialize .gitpilot/ directory with template GITPILOT.md."""
+    from pathlib import Path as StdPath
+    workspace_path = StdPath.home() / ".gitpilot" / "workspaces" / owner / repo
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    mgr = MemoryManager(workspace_path)
+    md_path = mgr.init_project()
+    return {"initialized": True, "path": str(md_path)}
+
+
+@app.post("/api/repos/{owner}/{repo}/context/pattern")
+async def api_add_learned_pattern(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    payload: dict = ...,
+):
+    """Add a learned pattern to auto-memory."""
+    from pathlib import Path as StdPath
+    pattern = payload.get("pattern", "")
+    if not pattern:
+        raise HTTPException(status_code=400, detail="pattern is required")
+    workspace_path = StdPath.home() / ".gitpilot" / "workspaces" / owner / repo
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    mgr = MemoryManager(workspace_path)
+    mgr.add_learned_pattern(pattern)
+    return {"added": True, "pattern": pattern}
+
+
+# ============================================================================
+# Context Vault Endpoints (additive — Context + Use Case system)
+# ============================================================================
+
+def _workspace_path(owner: str, repo: str) -> Path:
+    """Resolve the local workspace path for a repo."""
+    return Path.home() / ".gitpilot" / "workspaces" / owner / repo
+
+
+@app.get("/api/repos/{owner}/{repo}/context/assets")
+async def api_list_context_assets(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+):
+    """List all uploaded context assets for a repository."""
+    vault = ContextVault(_workspace_path(owner, repo))
+    assets = vault.list_assets()
+    return {"assets": [a.to_dict() for a in assets]}
+
+
+@app.post("/api/repos/{owner}/{repo}/context/assets/upload")
+async def api_upload_context_asset(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    file: UploadFile = File(...),
+):
+    """Upload a file to the project context vault."""
+    vault = ContextVault(_workspace_path(owner, repo))
+    content = await file.read()
+    mime = file.content_type or ""
+    filename = file.filename or "upload"
+
+    try:
+        meta = vault.upload_asset(filename, content, mime=mime)
+        return {"asset": meta.to_dict()}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.delete("/api/repos/{owner}/{repo}/context/assets/{asset_id}")
+async def api_delete_context_asset(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    asset_id: str = FPath(...),
+):
+    """Delete a context asset."""
+    vault = ContextVault(_workspace_path(owner, repo))
+    vault.delete_asset(asset_id)
+    return {"deleted": True, "asset_id": asset_id}
+
+
+@app.get("/api/repos/{owner}/{repo}/context/assets/{asset_id}/download")
+async def api_download_context_asset(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    asset_id: str = FPath(...),
+):
+    """Download a raw context asset file."""
+    vault = ContextVault(_workspace_path(owner, repo))
+    asset_path = vault.get_asset_path(asset_id)
+    if not asset_path:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    filename = vault.get_asset_filename(asset_id)
+    return FileResponse(asset_path, filename=filename)
+
+
+# ============================================================================
+# Use Case Endpoints (additive — guided requirement clarification)
+# ============================================================================
+
+@app.get("/api/repos/{owner}/{repo}/use-cases")
+async def api_list_use_cases(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+):
+    """List all use cases for a repository."""
+    mgr = UseCaseManager(_workspace_path(owner, repo))
+    return {"use_cases": mgr.list_use_cases()}
+
+
+@app.post("/api/repos/{owner}/{repo}/use-cases")
+async def api_create_use_case(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    payload: dict = ...,
+):
+    """Create a new use case."""
+    title = payload.get("title", "New Use Case")
+    initial_notes = payload.get("initial_notes", "")
+    mgr = UseCaseManager(_workspace_path(owner, repo))
+    uc = mgr.create_use_case(title=title, initial_notes=initial_notes)
+    return {"use_case": uc.to_dict()}
+
+
+@app.get("/api/repos/{owner}/{repo}/use-cases/{use_case_id}")
+async def api_get_use_case(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    use_case_id: str = FPath(...),
+):
+    """Get a single use case with messages and spec."""
+    mgr = UseCaseManager(_workspace_path(owner, repo))
+    uc = mgr.get_use_case(use_case_id)
+    if not uc:
+        raise HTTPException(status_code=404, detail="Use case not found")
+    return {"use_case": uc.to_dict()}
+
+
+@app.post("/api/repos/{owner}/{repo}/use-cases/{use_case_id}/chat")
+async def api_use_case_chat(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    use_case_id: str = FPath(...),
+    payload: dict = ...,
+):
+    """Send a guided chat message and get assistant response + updated spec."""
+    message = payload.get("message", "")
+    if not message:
+        raise HTTPException(status_code=400, detail="message is required")
+    mgr = UseCaseManager(_workspace_path(owner, repo))
+    uc = mgr.chat(use_case_id, message)
+    if not uc:
+        raise HTTPException(status_code=404, detail="Use case not found")
+    return {"use_case": uc.to_dict()}
+
+
+@app.post("/api/repos/{owner}/{repo}/use-cases/{use_case_id}/finalize")
+async def api_finalize_use_case(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    use_case_id: str = FPath(...),
+):
+    """Finalize a use case: mark active, export markdown spec."""
+    mgr = UseCaseManager(_workspace_path(owner, repo))
+    uc = mgr.finalize(use_case_id)
+    if not uc:
+        raise HTTPException(status_code=404, detail="Use case not found")
+    return {"use_case": uc.to_dict()}
+
+
+# ============================================================================
+# MCP Endpoints (Phase 2)
+# ============================================================================
+
+@app.get("/api/mcp/servers")
+async def api_mcp_list_servers():
+    """List configured MCP servers and their connection status."""
+    return _mcp_client.to_dict()
+
+
+@app.post("/api/mcp/connect/{server_name}")
+async def api_mcp_connect(server_name: str):
+    """Connect to a named MCP server."""
+    try:
+        conn = await _mcp_client.connect(server_name)
+        return {
+            "connected": True,
+            "server": server_name,
+            "tools": [{"name": t.name, "description": t.description} for t in conn.tools],
+        }
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.post("/api/mcp/disconnect/{server_name}")
+async def api_mcp_disconnect(server_name: str):
+    """Disconnect from a named MCP server."""
+    await _mcp_client.disconnect(server_name)
+    return {"disconnected": True, "server": server_name}
+
+
+@app.post("/api/mcp/call")
+async def api_mcp_call_tool(payload: dict):
+    """Call a tool on a connected MCP server."""
+    server = payload.get("server", "")
+    tool_name = payload.get("tool", "")
+    params = payload.get("params", {})
+    if not server or not tool_name:
+        raise HTTPException(status_code=400, detail="server and tool are required")
+    conn = _mcp_client._connections.get(server)
+    if not conn:
+        raise HTTPException(status_code=404, detail=f"Not connected to server: {server}")
+    try:
+        result = await _mcp_client.call_tool(conn, tool_name, params)
+        return {"result": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ============================================================================
+# Plugin Endpoints (Phase 2)
+# ============================================================================
+
+@app.get("/api/plugins")
+async def api_list_plugins():
+    """List installed plugins."""
+    plugins = _plugin_mgr.list_installed()
+    return {"plugins": [p.to_dict() for p in plugins]}
+
+
+@app.post("/api/plugins/install")
+async def api_install_plugin(payload: dict):
+    """Install a plugin from a git URL or local path."""
+    source = payload.get("source", "")
+    if not source:
+        raise HTTPException(status_code=400, detail="source is required")
+    try:
+        info = _plugin_mgr.install(source)
+        return {"installed": True, "plugin": info.to_dict()}
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.delete("/api/plugins/{name}")
+async def api_uninstall_plugin(name: str):
+    """Uninstall a plugin by name."""
+    removed = _plugin_mgr.uninstall(name)
+    if not removed:
+        raise HTTPException(status_code=404, detail=f"Plugin not found: {name}")
+    return {"uninstalled": True, "name": name}
+
+
+# ============================================================================
+# Skills Endpoints (Phase 2)
+# ============================================================================
+
+@app.get("/api/skills")
+async def api_list_skills():
+    """List all available skills."""
+    return {"skills": _skill_mgr.list_skills()}
+
+
+@app.post("/api/skills/invoke")
+async def api_invoke_skill(payload: dict):
+    """Invoke a skill by name."""
+    name = payload.get("name", "")
+    context = payload.get("context", {})
+    if not name:
+        raise HTTPException(status_code=400, detail="name is required")
+    prompt = _skill_mgr.invoke(name, context)
+    if prompt is None:
+        raise HTTPException(status_code=404, detail=f"Skill not found: {name}")
+    return {"skill": name, "rendered_prompt": prompt}
+
+
+@app.post("/api/skills/reload")
+async def api_reload_skills():
+    """Reload skills from all sources."""
+    count = _skill_mgr.load_all()
+    return {"reloaded": True, "count": count}
+
+
+# ============================================================================
+# Vision Endpoints (Phase 2)
+# ============================================================================
+
+@app.post("/api/vision/analyze")
+async def api_vision_analyze(payload: dict):
+    """Analyze an image with a text prompt."""
+    from .vision import VisionAnalyzer
+    image_path = payload.get("image_path", "")
+    prompt = payload.get("prompt", "Describe this image.")
+    provider = payload.get("provider", "openai")
+    if not image_path:
+        raise HTTPException(status_code=400, detail="image_path is required")
+    try:
+        analyzer = VisionAnalyzer(provider=provider)
+        result = await analyzer.analyze_image(Path(image_path), prompt)
+        return result.to_dict()
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# ============================================================================
+# Model Router Endpoints (Phase 2)
+# ============================================================================
+
+@app.post("/api/model-router/select")
+async def api_model_select(payload: dict):
+    """Preview which model would be selected for a request."""
+    request = payload.get("request", "")
+    category = payload.get("category")
+    if not request:
+        raise HTTPException(status_code=400, detail="request is required")
+    selection = _model_router.select(request, category)
+    return {
+        "model": selection.model,
+        "tier": selection.tier.value,
+        "complexity": selection.complexity.value,
+        "provider": selection.provider,
+        "reason": selection.reason,
+    }
+
+
+@app.get("/api/model-router/usage")
+async def api_model_usage():
+    """Get model usage summary and budget status."""
+    return _model_router.get_usage_summary()
+
+
+# ============================================================================
+# Agent Teams Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/agent-teams/plan")
+async def api_team_plan(payload: dict):
+    """Split a complex task into parallel subtasks."""
+    task = payload.get("task", "")
+    if not task:
+        raise HTTPException(status_code=400, detail="task is required")
+    subtasks = _agent_team.plan_and_split(task)
+    return {"subtasks": [{"id": s.id, "title": s.title, "description": s.description} for s in subtasks]}
+
+
+@app.post("/api/agent-teams/execute")
+async def api_team_execute(payload: dict):
+    """Execute subtasks in parallel and merge results."""
+    task = payload.get("task", "")
+    if not task:
+        raise HTTPException(status_code=400, detail="task is required")
+    subtasks = _agent_team.plan_and_split(task)
+    result = await _agent_team.execute_parallel(subtasks)
+    return result.to_dict()
+
+
+# ============================================================================
+# Learning Engine Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/learning/evaluate")
+async def api_learning_evaluate(payload: dict):
+    """Evaluate an action outcome for learning."""
+    action = payload.get("action", "")
+    outcome = payload.get("outcome", {})
+    repo = payload.get("repo", "")
+    if not action:
+        raise HTTPException(status_code=400, detail="action is required")
+    evaluation = _learning_engine.evaluate_outcome(action, outcome, repo=repo)
+    return {
+        "action": evaluation.action,
+        "success": evaluation.success,
+        "score": evaluation.score,
+        "feedback": evaluation.feedback,
+    }
+
+
+@app.get("/api/learning/insights/{owner}/{repo}")
+async def api_learning_insights(owner: str = FPath(...), repo: str = FPath(...)):
+    """Get learned insights for a repository."""
+    repo_name = f"{owner}/{repo}"
+    insights = _learning_engine.get_repo_insights(repo_name)
+    return {
+        "repo": repo_name,
+        "patterns": insights.patterns,
+        "preferred_style": insights.preferred_style,
+        "success_rate": insights.success_rate,
+        "total_evaluations": insights.total_evaluations,
+    }
+
+
+@app.post("/api/learning/style")
+async def api_learning_set_style(payload: dict):
+    """Set preferred coding style for a repository."""
+    repo = payload.get("repo", "")
+    style = payload.get("style", {})
+    if not repo:
+        raise HTTPException(status_code=400, detail="repo is required")
+    _learning_engine.set_preferred_style(repo, style)
+    return {"repo": repo, "style": style}
+
+
+# ============================================================================
+# Cross-Repo Intelligence Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/cross-repo/dependencies")
+async def api_cross_repo_dependencies(payload: dict):
+    """Analyze dependencies from provided file contents."""
+    files = payload.get("files", {})
+    if not files:
+        raise HTTPException(status_code=400, detail="files dict is required (filename -> content)")
+    graph = _cross_repo.analyze_dependencies_from_files(files)
+    return graph.to_dict()
+
+
+@app.post("/api/cross-repo/impact")
+async def api_cross_repo_impact(payload: dict):
+    """Analyze impact of updating a package."""
+    files = payload.get("files", {})
+    package_name = payload.get("package", "")
+    new_version = payload.get("new_version")
+    if not package_name:
+        raise HTTPException(status_code=400, detail="package is required")
+    graph = _cross_repo.analyze_dependencies_from_files(files)
+    report = _cross_repo.impact_analysis(graph, package_name, new_version)
+    return report.to_dict()
+
+
+# ============================================================================
+# Predictions Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/predictions/suggest")
+async def api_predictions_suggest(payload: dict):
+    """Get proactive suggestions based on context."""
+    context = payload.get("context", "")
+    if not context:
+        raise HTTPException(status_code=400, detail="context is required")
+    suggestions = _predictive_engine.predict(context)
+    return {"suggestions": [s.to_dict() for s in suggestions]}
+
+
+@app.get("/api/predictions/rules")
+async def api_predictions_rules():
+    """List all prediction rules."""
+    return {"rules": _predictive_engine.list_rules()}
+
+
+# ============================================================================
+# Security Scanner Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/security/scan-file")
+async def api_security_scan_file(payload: dict):
+    """Scan a single file for security issues."""
+    file_path = payload.get("file_path", "")
+    if not file_path:
+        raise HTTPException(status_code=400, detail="file_path is required")
+    findings = _security_scanner.scan_file(file_path)
+    return {"findings": [f.to_dict() for f in findings], "count": len(findings)}
+
+
+@app.post("/api/security/scan-directory")
+async def api_security_scan_directory(payload: dict):
+    """Recursively scan a directory for security issues."""
+    directory = payload.get("directory", "")
+    if not directory:
+        raise HTTPException(status_code=400, detail="directory is required")
+    result = _security_scanner.scan_directory(directory)
+    return result.to_dict()
+
+
+@app.post("/api/security/scan-diff")
+async def api_security_scan_diff(payload: dict):
+    """Scan a git diff for security issues in added lines."""
+    diff_text = payload.get("diff", "")
+    if not diff_text:
+        raise HTTPException(status_code=400, detail="diff is required")
+    findings = _security_scanner.scan_diff(diff_text)
+    return {"findings": [f.to_dict() for f in findings], "count": len(findings)}
+
+
+# ============================================================================
+# Natural Language Database Endpoints (Phase 3)
+# ============================================================================
+
+@app.post("/api/nl-database/translate")
+async def api_nl_translate(payload: dict):
+    """Translate natural language to SQL."""
+    question = payload.get("question", "")
+    dialect = payload.get("dialect", "postgresql")
+    tables = payload.get("tables", [])
+    if not question:
+        raise HTTPException(status_code=400, detail="question is required")
+    engine = NLQueryEngine(dialect=QueryDialect(dialect))
+    for t in tables:
+        engine.add_table(TableSchema(
+            name=t["name"],
+            columns=t.get("columns", []),
+            primary_key=t.get("primary_key"),
+        ))
+    sql = engine.translate(question)
+    error = engine.validate_query(sql)
+    return {"question": question, "sql": sql, "valid": error is None, "error": error}
+
+
+@app.post("/api/nl-database/explain")
+async def api_nl_explain(payload: dict):
+    """Explain what a SQL query does in plain English."""
+    sql = payload.get("sql", "")
+    if not sql:
+        raise HTTPException(status_code=400, detail="sql is required")
+    explanation = _nl_engine.explain(sql)
+    return {"sql": sql, "explanation": explanation}
+
+
+# ============================================================================
+# Branch Listing Endpoint (Claude-Code-on-Web Parity)
+# ============================================================================
+
+class BranchInfo(BaseModel):
+    name: str
+    is_default: bool = False
+    protected: bool = False
+    commit_sha: Optional[str] = None
+
+
+class BranchListResponse(BaseModel):
+    repository: str
+    default_branch: str
+    page: int
+    per_page: int
+    has_more: bool
+    branches: List[BranchInfo]
+
+
+@app.get("/api/repos/{owner}/{repo}/branches", response_model=BranchListResponse)
+async def api_list_branches(
+    owner: str = FPath(...),
+    repo: str = FPath(...),
+    page: int = Query(1, ge=1),
+    per_page: int = Query(100, ge=1, le=100),
+    query: Optional[str] = Query(None, description="Substring filter"),
+    authorization: Optional[str] = Header(None),
+):
+    """List branches for a repository with optional search filtering."""
+    import httpx as _httpx
+
+    token = get_github_token(authorization)
+    if not token:
+        raise HTTPException(status_code=401, detail="GitHub token required")
+
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "gitpilot",
+    }
+    timeout = _httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=10.0)
+
+    async with _httpx.AsyncClient(
+        base_url="https://api.github.com", headers=headers, timeout=timeout
+    ) as client:
+        # Fetch repo info for default_branch
+        repo_resp = await client.get(f"/repos/{owner}/{repo}")
+        if repo_resp.status_code >= 400:
+            logging.warning(
+                "branches: repo lookup failed %s/%s → %s %s",
+                owner, repo, repo_resp.status_code, repo_resp.text[:200],
+            )
+            raise HTTPException(
+                status_code=repo_resp.status_code,
+                detail=f"Cannot access repository: {repo_resp.status_code}",
+            )
+
+        repo_data = repo_resp.json()
+        default_branch_name = repo_data.get("default_branch", "main")
+
+        # Fetch ALL branch pages (GitHub caps at 100 per page)
+        all_raw = []
+        current_page = page
+        while True:
+            branch_resp = await client.get(
+                f"/repos/{owner}/{repo}/branches",
+                params={"page": current_page, "per_page": per_page},
+            )
+            if branch_resp.status_code >= 400:
+                logging.warning(
+                    "branches: list failed %s/%s page=%s → %s %s",
+                    owner, repo, current_page, branch_resp.status_code, branch_resp.text[:200],
+                )
+                raise HTTPException(
+                    status_code=branch_resp.status_code,
+                    detail=f"Failed to list branches: {branch_resp.status_code}",
+                )
+
+            page_data = branch_resp.json() if isinstance(branch_resp.json(), list) else []
+            all_raw.extend(page_data)
+
+            # Check if there are more pages
+            link_header = branch_resp.headers.get("Link", "") or ""
+            if 'rel="next"' not in link_header or len(page_data) < per_page:
+                break
+            current_page += 1
+            # Safety: cap at 10 pages (1000 branches)
+            if current_page - page >= 10:
+                break
+
+    q = (query or "").strip().lower()
+
+    branches = []
+    for b in all_raw:
+        name = (b.get("name") or "").strip()
+        if not name:
+            continue
+        if q and q not in name.lower():
+            continue
+        branches.append(BranchInfo(
+            name=name,
+            is_default=(name == default_branch_name),
+            protected=bool(b.get("protected", False)),
+            commit_sha=(b.get("commit") or {}).get("sha"),
+        ))
+
+    # Sort: default branch first, then alphabetical
+    branches.sort(key=lambda x: (0 if x.is_default else 1, x.name.lower()))
+
+    return BranchListResponse(
+        repository=f"{owner}/{repo}",
+        default_branch=default_branch_name,
+        page=page,
+        per_page=per_page,
+        has_more=False,
+        branches=branches,
+    )
+
+
+# ============================================================================
+# Environment Configuration Endpoints (Claude-Code-on-Web Parity)
+# ============================================================================
+
+import json as _json
+_ENV_ROOT = Path.home() / ".gitpilot" / "environments"
+
+
+class EnvironmentConfig(BaseModel):
+    id: Optional[str] = None
+    name: str = "Default"
+    network_access: str = Field("limited", description="limited | full | none")
+    env_vars: dict = Field(default_factory=dict)
+
+
+class EnvironmentListResponse(BaseModel):
+    environments: List[EnvironmentConfig]
+
+
+@app.get("/api/environments", response_model=EnvironmentListResponse)
+async def api_list_environments():
+    """List all environment configurations."""
+    _ENV_ROOT.mkdir(parents=True, exist_ok=True)
+    envs = []
+    for path in sorted(_ENV_ROOT.glob("*.json")):
+        try:
+            data = _json.loads(path.read_text())
+            envs.append(EnvironmentConfig(**data))
+        except Exception:
+            continue
+    if not envs:
+        envs.append(EnvironmentConfig(id="default", name="Default", network_access="limited"))
+    return EnvironmentListResponse(environments=envs)
+
+
+@app.post("/api/environments")
+async def api_create_environment(config: EnvironmentConfig):
+    """Create a new environment configuration."""
+    import uuid
+    _ENV_ROOT.mkdir(parents=True, exist_ok=True)
+    config.id = config.id or uuid.uuid4().hex[:12]
+    path = _ENV_ROOT / f"{config.id}.json"
+    path.write_text(_json.dumps(config.model_dump(), indent=2))
+    return config.model_dump()
+
+
+@app.put("/api/environments/{env_id}")
+async def api_update_environment(env_id: str, config: EnvironmentConfig):
+    """Update an environment configuration."""
+    _ENV_ROOT.mkdir(parents=True, exist_ok=True)
+    path = _ENV_ROOT / f"{env_id}.json"
+    config.id = env_id
+    path.write_text(_json.dumps(config.model_dump(), indent=2))
+    return config.model_dump()
+
+
+@app.delete("/api/environments/{env_id}")
+async def api_delete_environment(env_id: str):
+    """Delete an environment configuration."""
+    path = _ENV_ROOT / f"{env_id}.json"
+    if path.exists():
+        path.unlink()
+        return {"deleted": True}
+    raise HTTPException(status_code=404, detail="Environment not found")
+
+
+# ============================================================================
+# Session Messages + Diff Endpoints (Claude-Code-on-Web Parity)
+# ============================================================================
+
+@app.post("/api/sessions/{session_id}/message")
+async def api_add_session_message(session_id: str, payload: dict):
+    """Add a message to a session's conversation history."""
+    try:
+        session = _session_mgr.load(session_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Session not found")
+    role = payload.get("role", "user")
+    content = payload.get("content", "")
+    session.add_message(role, content, **payload.get("metadata", {}))
+    _session_mgr.save(session)
+    return {"message_count": len(session.messages)}
+
+
+@app.get("/api/sessions/{session_id}/messages")
+async def api_get_session_messages(session_id: str):
+    """Get all messages for a session."""
+    try:
+        session = _session_mgr.load(session_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return {
+        "session_id": session.id,
+        "messages": [
+            {
+                "role": m.role,
+                "content": m.content,
+                "timestamp": m.timestamp,
+                "metadata": m.metadata,
+            }
+            for m in session.messages
+        ],
+    }
+
+
+@app.get("/api/sessions/{session_id}/diff")
+async def api_get_session_diff(session_id: str):
+    """Get diff stats for a session (placeholder for sandbox integration)."""
+    try:
+        session = _session_mgr.load(session_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Session not found")
+    diff = session.metadata.get("diff", {
+        "files_changed": 0,
+        "additions": 0,
+        "deletions": 0,
+        "files": [],
+    })
+    return {"session_id": session.id, "diff": diff}
+
+
+@app.post("/api/sessions/{session_id}/status")
+async def api_update_session_status(session_id: str, payload: dict):
+    """Update session status (active, completed, failed, waiting)."""
+    try:
+        session = _session_mgr.load(session_id)
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Session not found")
+    new_status = payload.get("status", "active")
+    if new_status not in ("active", "paused", "completed", "failed", "waiting"):
+        raise HTTPException(status_code=400, detail="Invalid status")
+    session.status = new_status
+    _session_mgr.save(session)
+    return {"session_id": session.id, "status": session.status}
+
+
+# ============================================================================
+# WebSocket Streaming Endpoint (Claude-Code-on-Web Parity)
+# ============================================================================
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+
+@app.websocket("/ws/sessions/{session_id}")
+async def session_websocket(websocket: WebSocket, session_id: str):
+    """
+    Real-time bidirectional communication for a coding session.
+
+    Server events:
+      { type: "agent_message", content: "..." }
+      { type: "tool_use", tool: "bash", input: "npm test" }
+      { type: "tool_result", tool: "bash", output: "All tests passed" }
+      { type: "diff_update", stats: { additions: N, deletions: N, files: N } }
+      { type: "status_change", status: "completed" }
+      { type: "error", message: "..." }
+
+    Client events:
+      { type: "user_message", content: "..." }
+      { type: "cancel" }
+    """
+    await websocket.accept()
+
+    # Verify session exists
+    try:
+        session = _session_mgr.load(session_id)
+    except FileNotFoundError:
+        await websocket.send_json({"type": "error", "message": "Session not found"})
+        await websocket.close()
+        return
+
+    # Send session history on connect
+    await websocket.send_json({
+        "type": "session_restored",
+        "session_id": session.id,
+        "status": session.status,
+        "message_count": len(session.messages),
+    })
+
+    try:
+        while True:
+            data = await websocket.receive_json()
+            event_type = data.get("type", "")
+
+            if event_type == "user_message":
+                content = data.get("content", "")
+                session.add_message("user", content)
+                _session_mgr.save(session)
+
+                # Acknowledge receipt
+                await websocket.send_json({
+                    "type": "message_received",
+                    "message_index": len(session.messages) - 1,
+                })
+
+                # Stream agent response (integration point for agentic.py)
+                await websocket.send_json({
+                    "type": "status_change",
+                    "status": "active",
+                })
+
+                # Agent processing hook — when the agent orchestrator is wired,
+                # replace this with actual streaming from agentic.py
+                try:
+                    repo_full = session.repo_full_name or ""
+                    parts = repo_full.split("/", 1)
+                    if len(parts) == 2 and content.strip():
+                        # Use canonical dispatcher signature
+                        result = await dispatch_request(
+                            user_request=content,
+                            repo_full_name=f"{parts[0]}/{parts[1]}",
+                            branch_name=session.branch,
+                        )
+                        answer = ""
+                        if isinstance(result, dict):
+                            answer = (
+                                result.get("result")
+                                or result.get("answer")
+                                or result.get("message")
+                                or result.get("summary")
+                                or (result.get("plan", {}) or {}).get("summary")
+                                or str(result)
+                            )
+                        else:
+                            answer = str(result)
+
+                        # Stream the response
+                        await websocket.send_json({
+                            "type": "agent_message",
+                            "content": answer,
+                        })
+
+                        session.add_message("assistant", answer)
+                        _session_mgr.save(session)
+                    else:
+                        await websocket.send_json({
+                            "type": "agent_message",
+                            "content": "Session is not connected to a repository.",
+                        })
+                except Exception as agent_err:
+                    logger.error(f"Agent error in WS session {session_id}: {agent_err}")
+                    await websocket.send_json({
+                        "type": "error",
+                        "message": str(agent_err),
+                    })
+
+                await websocket.send_json({
+                    "type": "status_change",
+                    "status": "waiting",
+                })
+
+            elif event_type == "cancel":
+                await websocket.send_json({
+                    "type": "status_change",
+                    "status": "waiting",
+                })
+
+            elif event_type == "ping":
+                await websocket.send_json({"type": "pong"})
+
+    except WebSocketDisconnect:
+        logger.info(f"WebSocket disconnected for session {session_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error for session {session_id}: {e}")
+        try:
+            await websocket.send_json({"type": "error", "message": str(e)})
+        except Exception:
+            pass
+
+
+# ============================================================================
+# Static Files & Frontend Serving (SPA Support)
+# ============================================================================
+
+STATIC_DIR = Path(__file__).resolve().parent / "web"
+ASSETS_DIR = STATIC_DIR / "assets"
+
+if ASSETS_DIR.exists():
+    app.mount("/assets", StaticFiles(directory=ASSETS_DIR), name="assets")
+
+if STATIC_DIR.exists():
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@app.get("/api/health")
+async def health_check():
+    """Health check endpoint for monitoring and diagnostics."""
+    return {"status": "healthy", "service": "gitpilot-backend"}
+
+
+@app.get("/healthz")
+async def healthz():
+    """Health check endpoint (Render/Kubernetes standard)."""
+    return {"status": "healthy", "service": "gitpilot-backend"}
+
+
+@app.get("/", include_in_schema=False)
+async def index():
+    """Serve the React App entry point."""
+    index_file = STATIC_DIR / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+    return JSONResponse(
+        {"message": "GitPilot UI not built. The static files directory is missing."},
+        status_code=500,
+    )
+
+
+@app.get("/{full_path:path}", include_in_schema=False)
+async def catch_all_spa_routes(full_path: str):
+    """
+    Catch-all route to serve index.html for frontend routing.
+    Excludes '/api' paths to ensure genuine API 404s are returned as JSON.
+    """
+    if full_path.startswith("api/"):
+        return JSONResponse({"detail": "Not Found"}, status_code=404)
+
+    index_file = STATIC_DIR / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+
+    return JSONResponse(
+        {"message": "GitPilot UI not built. The static files directory is missing."},
+        status_code=500,
+    )

gitpilot/a2a_adapter.py

@@ -0,0 +1,560 @@
+"""Optional A2A adapter for GitPilot (MCP ContextForge compatible).
+
+This module is feature-flagged. Nothing changes in GitPilot unless the main app
+mounts this router when GITPILOT_ENABLE_A2A=true.
+
+Supported protocols
+- JSON-RPC 2.0 (preferred)
+- ContextForge custom A2A envelope (fallback)
+
+Security model (recommended)
+- Gateway injects a shared secret:
+    X-A2A-Secret: <secret>
+  or
+    Authorization: Bearer <secret>
+
+- GitHub token (if needed) should be provided via:
+    X-Github-Token: <token>
+  (avoid passing tokens in JSON bodies to reduce leak risk in logs)
+
+Environment
+- GITPILOT_A2A_REQUIRE_AUTH=true
+- GITPILOT_A2A_SHARED_SECRET=<long random>
+- GITPILOT_A2A_MAX_BODY_MB=2
+- GITPILOT_A2A_ALLOW_GITHUB_TOKEN_IN_PARAMS=false
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from typing import Any, Dict, Optional, Tuple
+
+from fastapi import APIRouter, Header, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from .agentic import PlanResult, execute_plan, generate_plan, dispatch_request
+from .github_api import get_file, get_repo_tree, github_request, put_file
+from . import github_issues
+from . import github_pulls
+from . import github_search
+
+router = APIRouter(tags=["a2a"])
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw.strip())
+    except Exception:
+        return default
+
+
+def _extract_bearer(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    if value.startswith("Bearer "):
+        return value[7:]
+    if value.startswith("token "):
+        return value[6:]
+    return value
+
+
+def _get_trace_id(x_request_id: Optional[str]) -> str:
+    return (x_request_id or "").strip() or str(uuid.uuid4())
+
+
+def _require_gateway_secret(authorization: Optional[str], x_a2a_secret: Optional[str]) -> None:
+    require_auth = _env_bool("GITPILOT_A2A_REQUIRE_AUTH", True)
+    if not require_auth:
+        return
+
+    expected = os.getenv("GITPILOT_A2A_SHARED_SECRET", "").strip()
+    if not expected:
+        raise HTTPException(
+            status_code=500,
+            detail="A2A is enabled but GITPILOT_A2A_SHARED_SECRET is not set",
+        )
+
+    candidate = _extract_bearer(authorization) or (x_a2a_secret or "").strip()
+    if not candidate or candidate != expected:
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+def _split_full_name(repo_full_name: str) -> Tuple[str, str]:
+    if not repo_full_name or "/" not in repo_full_name:
+        raise HTTPException(status_code=400, detail="repo_full_name must be 'owner/repo'")
+    owner, repo = repo_full_name.split("/", 1)
+    owner, repo = owner.strip(), repo.strip()
+    if not owner or not repo:
+        raise HTTPException(status_code=400, detail="repo_full_name must be 'owner/repo'")
+    return owner, repo
+
+
+def _jsonrpc_error(id_value: Any, code: int, message: str, data: Any = None) -> Dict[str, Any]:
+    err: Dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        err["data"] = data
+    return {"jsonrpc": "2.0", "error": err, "id": id_value}
+
+
+def _jsonrpc_result(id_value: Any, result: Any) -> Dict[str, Any]:
+    return {"jsonrpc": "2.0", "result": result, "id": id_value}
+
+
+async def _dispatch(method: str, params: Dict[str, Any], github_token: Optional[str]) -> Any:
+    if method == "repo.connect":
+        repo_full_name = params.get("repo_full_name")
+        owner, repo = _split_full_name(str(repo_full_name))
+        info = await github_request(f"/repos/{owner}/{repo}", token=github_token)
+        return {
+            "repo": {
+                "id": info.get("id"),
+                "full_name": info.get("full_name"),
+                "private": info.get("private"),
+                "html_url": info.get("html_url"),
+            },
+            "default_branch": info.get("default_branch"),
+            "permissions": info.get("permissions"),
+        }
+
+    if method == "repo.tree":
+        repo_full_name = params.get("repo_full_name")
+        ref = (params.get("ref") or "").strip() or "HEAD"
+        owner, repo = _split_full_name(str(repo_full_name))
+        tree = await get_repo_tree(owner, repo, token=github_token, ref=ref)
+        return {"entries": tree, "ref": ref}
+
+    if method == "repo.read":
+        repo_full_name = params.get("repo_full_name")
+        path = params.get("path")
+        if not path:
+            raise HTTPException(status_code=400, detail="Missing required param: path")
+        owner, repo = _split_full_name(str(repo_full_name))
+        # NOTE: current get_file() reads from default branch/ref in this repo.
+        # You can extend github_api.get_file to accept ref and pass it here later.
+        content = await get_file(owner, repo, str(path), token=github_token)
+        return {"path": str(path), "content": content, "encoding": "utf-8"}
+
+    if method == "repo.write":
+        repo_full_name = params.get("repo_full_name")
+        path = params.get("path")
+        content = params.get("content")
+        message = params.get("message") or "Update via GitPilot A2A"
+        branch = params.get("branch") or params.get("branch_name")
+        if not path:
+            raise HTTPException(status_code=400, detail="Missing required param: path")
+        if content is None:
+            raise HTTPException(status_code=400, detail="Missing required param: content")
+        owner, repo = _split_full_name(str(repo_full_name))
+        result = await put_file(
+            owner,
+            repo,
+            str(path),
+            str(content),
+            str(message),
+            token=github_token,
+            branch=branch,
+        )
+        return result
+
+    if method == "plan.generate":
+        repo_full_name = params.get("repo_full_name")
+        goal = params.get("goal")
+        branch_name = params.get("branch") or params.get("branch_name")
+        if not goal:
+            raise HTTPException(status_code=400, detail="Missing required param: goal")
+        if not repo_full_name:
+            raise HTTPException(status_code=400, detail="Missing required param: repo_full_name")
+        plan = await generate_plan(str(goal), str(repo_full_name), token=github_token, branch_name=branch_name)
+        return plan.model_dump() if hasattr(plan, "model_dump") else plan
+
+    if method == "plan.execute":
+        repo_full_name = params.get("repo_full_name")
+        branch_name = params.get("branch") or params.get("branch_name")
+        plan_raw = params.get("plan")
+        if not repo_full_name:
+            raise HTTPException(status_code=400, detail="Missing required param: repo_full_name")
+        if plan_raw is None:
+            raise HTTPException(status_code=400, detail="Missing required param: plan")
+        if isinstance(plan_raw, PlanResult):
+            plan_obj = plan_raw
+        else:
+            try:
+                plan_obj = PlanResult.model_validate(plan_raw)  # pydantic v2
+            except Exception:
+                plan_obj = PlanResult.parse_obj(plan_raw)  # pydantic v1
+        result = await execute_plan(plan_obj, str(repo_full_name), token=github_token, branch_name=branch_name)
+        return result
+
+    if method == "repo.search":
+        query = params.get("query")
+        if not query:
+            raise HTTPException(status_code=400, detail="Missing required param: query")
+        result = await github_request(
+            "/search/repositories",
+            params={"q": str(query), "per_page": 20},
+            token=github_token,
+        )
+        items = (result or {}).get("items", []) if isinstance(result, dict) else []
+        return {
+            "repos": [
+                {
+                    "full_name": i.get("full_name"),
+                    "private": i.get("private"),
+                    "html_url": i.get("html_url"),
+                    "description": i.get("description"),
+                    "default_branch": i.get("default_branch"),
+                }
+                for i in items
+            ]
+        }
+
+    # --- v2 methods: issues, pulls, search, chat --------------------------
+
+    if method == "issue.list":
+        repo_full_name = params.get("repo_full_name")
+        owner, repo = _split_full_name(str(repo_full_name))
+        issues = await github_issues.list_issues(
+            owner, repo, state=params.get("state", "open"),
+            labels=params.get("labels"), per_page=params.get("per_page", 30),
+            token=github_token,
+        )
+        return {"issues": issues}
+
+    if method == "issue.get":
+        repo_full_name = params.get("repo_full_name")
+        issue_number = params.get("issue_number")
+        if not issue_number:
+            raise HTTPException(status_code=400, detail="Missing required param: issue_number")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_issues.get_issue(owner, repo, int(issue_number), token=github_token)
+
+    if method == "issue.create":
+        repo_full_name = params.get("repo_full_name")
+        title = params.get("title")
+        if not title:
+            raise HTTPException(status_code=400, detail="Missing required param: title")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_issues.create_issue(
+            owner, repo, str(title),
+            body=params.get("body"), labels=params.get("labels"),
+            assignees=params.get("assignees"), token=github_token,
+        )
+
+    if method == "issue.update":
+        repo_full_name = params.get("repo_full_name")
+        issue_number = params.get("issue_number")
+        if not issue_number:
+            raise HTTPException(status_code=400, detail="Missing required param: issue_number")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_issues.update_issue(
+            owner, repo, int(issue_number),
+            title=params.get("title"), body=params.get("body"),
+            state=params.get("state"), labels=params.get("labels"),
+            assignees=params.get("assignees"), token=github_token,
+        )
+
+    if method == "issue.comment":
+        repo_full_name = params.get("repo_full_name")
+        issue_number = params.get("issue_number")
+        body = params.get("body")
+        if not issue_number:
+            raise HTTPException(status_code=400, detail="Missing required param: issue_number")
+        if not body:
+            raise HTTPException(status_code=400, detail="Missing required param: body")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_issues.add_issue_comment(
+            owner, repo, int(issue_number), str(body), token=github_token,
+        )
+
+    if method == "pr.list":
+        repo_full_name = params.get("repo_full_name")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_pulls.list_pull_requests(
+            owner, repo, state=params.get("state", "open"),
+            per_page=params.get("per_page", 30), token=github_token,
+        )
+
+    if method == "pr.create":
+        repo_full_name = params.get("repo_full_name")
+        title = params.get("title")
+        head = params.get("head")
+        base = params.get("base")
+        if not title or not head or not base:
+            raise HTTPException(status_code=400, detail="Missing required params: title, head, base")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_pulls.create_pull_request(
+            owner, repo, title=str(title), head=str(head), base=str(base),
+            body=params.get("body"), token=github_token,
+        )
+
+    if method == "pr.merge":
+        repo_full_name = params.get("repo_full_name")
+        pull_number = params.get("pull_number")
+        if not pull_number:
+            raise HTTPException(status_code=400, detail="Missing required param: pull_number")
+        owner, repo = _split_full_name(str(repo_full_name))
+        return await github_pulls.merge_pull_request(
+            owner, repo, int(pull_number),
+            merge_method=params.get("merge_method", "merge"),
+            token=github_token,
+        )
+
+    if method == "search.code":
+        query = params.get("query")
+        if not query:
+            raise HTTPException(status_code=400, detail="Missing required param: query")
+        return await github_search.search_code(
+            str(query), owner=params.get("owner"), repo=params.get("repo"),
+            language=params.get("language"), per_page=params.get("per_page", 20),
+            token=github_token,
+        )
+
+    if method == "search.issues":
+        query = params.get("query")
+        if not query:
+            raise HTTPException(status_code=400, detail="Missing required param: query")
+        return await github_search.search_issues(
+            str(query), owner=params.get("owner"), repo=params.get("repo"),
+            state=params.get("state"), label=params.get("label"),
+            per_page=params.get("per_page", 20), token=github_token,
+        )
+
+    if method == "search.users":
+        query = params.get("query")
+        if not query:
+            raise HTTPException(status_code=400, detail="Missing required param: query")
+        return await github_search.search_users(
+            str(query), type_filter=params.get("type"),
+            location=params.get("location"), language=params.get("language"),
+            per_page=params.get("per_page", 20), token=github_token,
+        )
+
+    if method == "chat.message":
+        repo_full_name = params.get("repo_full_name")
+        message = params.get("message")
+        if not message:
+            raise HTTPException(status_code=400, detail="Missing required param: message")
+        if not repo_full_name:
+            raise HTTPException(status_code=400, detail="Missing required param: repo_full_name")
+        return await dispatch_request(
+            str(message), str(repo_full_name),
+            token=github_token,
+            branch_name=params.get("branch") or params.get("branch_name"),
+        )
+
+    raise HTTPException(status_code=404, detail=f"Unknown method: {method}")
+
+
+@router.get("/a2a/health")
+async def a2a_health() -> Dict[str, Any]:
+    return {"status": "ok", "ts": int(time.time())}
+
+
+@router.get("/a2a/manifest")
+async def a2a_manifest() -> Dict[str, Any]:
+    # Best-effort schemas (kept intentionally simple and stable)
+    return {
+        "name": "gitpilot",
+        "a2a_version": "1.0",
+        "protocols": ["jsonrpc-2.0", "a2a-envelope-1.0"],
+        "auth": {"type": "shared_secret", "header": "X-A2A-Secret"},
+        "rate_limits": {"hint": "apply gateway rate limiting; server enforces body size"},
+        "methods": {
+            "repo.connect": {
+                "params": {"repo_full_name": "string"},
+                "result": {"repo": "object", "default_branch": "string", "permissions": "object?"},
+            },
+            "repo.tree": {
+                "params": {"repo_full_name": "string", "ref": "string?"},
+                "result": {"entries": "array", "ref": "string"},
+            },
+            "repo.read": {
+                "params": {"repo_full_name": "string", "path": "string"},
+                "result": {"path": "string", "content": "string"},
+            },
+            "repo.write": {
+                "params": {
+                    "repo_full_name": "string",
+                    "path": "string",
+                    "content": "string",
+                    "message": "string?",
+                    "branch": "string?",
+                },
+                "result": "object",
+            },
+            "plan.generate": {
+                "params": {"repo_full_name": "string", "goal": "string", "branch": "string?"},
+                "result": "PlanResult",
+            },
+            "plan.execute": {
+                "params": {"repo_full_name": "string", "plan": "PlanResult", "branch": "string?"},
+                "result": "object",
+            },
+            "repo.search": {
+                "params": {"query": "string"},
+                "result": {"repos": "array"},
+            },
+            # v2 methods
+            "issue.list": {
+                "params": {"repo_full_name": "string", "state": "string?", "labels": "string?"},
+                "result": {"issues": "array"},
+            },
+            "issue.get": {
+                "params": {"repo_full_name": "string", "issue_number": "integer"},
+                "result": "object",
+            },
+            "issue.create": {
+                "params": {"repo_full_name": "string", "title": "string", "body": "string?", "labels": "array?", "assignees": "array?"},
+                "result": "object",
+            },
+            "issue.update": {
+                "params": {"repo_full_name": "string", "issue_number": "integer", "title": "string?", "body": "string?", "state": "string?"},
+                "result": "object",
+            },
+            "issue.comment": {
+                "params": {"repo_full_name": "string", "issue_number": "integer", "body": "string"},
+                "result": "object",
+            },
+            "pr.list": {
+                "params": {"repo_full_name": "string", "state": "string?"},
+                "result": "array",
+            },
+            "pr.create": {
+                "params": {"repo_full_name": "string", "title": "string", "head": "string", "base": "string", "body": "string?"},
+                "result": "object",
+            },
+            "pr.merge": {
+                "params": {"repo_full_name": "string", "pull_number": "integer", "merge_method": "string?"},
+                "result": "object",
+            },
+            "search.code": {
+                "params": {"query": "string", "owner": "string?", "repo": "string?", "language": "string?"},
+                "result": {"total_count": "integer", "items": "array"},
+            },
+            "search.issues": {
+                "params": {"query": "string", "owner": "string?", "repo": "string?", "state": "string?"},
+                "result": {"total_count": "integer", "items": "array"},
+            },
+            "search.users": {
+                "params": {"query": "string", "type": "string?", "location": "string?"},
+                "result": {"total_count": "integer", "items": "array"},
+            },
+            "chat.message": {
+                "params": {"repo_full_name": "string", "message": "string", "branch": "string?"},
+                "result": "object",
+            },
+        },
+    }
+
+
+async def _handle_invoke(
+    request: Request,
+    authorization: Optional[str],
+    x_a2a_secret: Optional[str],
+    x_github_token: Optional[str],
+    x_request_id: Optional[str],
+) -> JSONResponse:
+    trace_id = _get_trace_id(x_request_id)
+    _require_gateway_secret(authorization=authorization, x_a2a_secret=x_a2a_secret)
+
+    # Body size guard (helps protect from abuse)
+    max_mb = _env_int("GITPILOT_A2A_MAX_BODY_MB", 2)
+    cl = request.headers.get("content-length")
+    if cl:
+        try:
+            if int(cl) > max_mb * 1024 * 1024:
+                raise HTTPException(status_code=413, detail="Request entity too large")
+        except ValueError:
+            pass
+
+    started = time.time()
+    payload = await request.json()
+
+    github_token = _extract_bearer(x_github_token) or None
+    if not github_token:
+        github_token = _extract_bearer(authorization)
+
+    # JSON-RPC mode
+    if isinstance(payload, dict) and payload.get("jsonrpc") == "2.0" and "method" in payload:
+        rpc_id = payload.get("id")
+        method = payload.get("method")
+        params = payload.get("params") or {}
+        if not isinstance(params, dict):
+            return JSONResponse(_jsonrpc_error(rpc_id, -32602, "Invalid params"), status_code=400)
+
+        allow_in_params = _env_bool("GITPILOT_A2A_ALLOW_GITHUB_TOKEN_IN_PARAMS", False)
+        if allow_in_params and not github_token:
+            github_token = _extract_bearer(params.get("github_token"))
+
+        try:
+            result = await _dispatch(str(method), params, github_token)
+            resp = _jsonrpc_result(rpc_id, result)
+            return JSONResponse(resp, headers={"X-Trace-Id": trace_id})
+        except HTTPException as e:
+            resp = _jsonrpc_error(rpc_id, e.status_code, str(e.detail), {"trace_id": trace_id})
+            return JSONResponse(resp, status_code=200, headers={"X-Trace-Id": trace_id})
+        except Exception as e:
+            resp = _jsonrpc_error(rpc_id, -32000, "Server error", {"trace_id": trace_id, "error": str(e)})
+            return JSONResponse(resp, status_code=200, headers={"X-Trace-Id": trace_id})
+        finally:
+            _ = time.time() - started
+
+    # Custom envelope fallback
+    if isinstance(payload, dict) and payload.get("interaction_type"):
+        interaction_type = str(payload.get("interaction_type"))
+        parameters = payload.get("parameters") or {}
+        if not isinstance(parameters, dict):
+            raise HTTPException(status_code=400, detail="Invalid parameters")
+
+        if interaction_type == "query":
+            repo_full_name = parameters.get("repo_full_name")
+            goal = parameters.get("query") or parameters.get("goal")
+            params = {
+                "repo_full_name": repo_full_name,
+                "goal": goal,
+                "branch": parameters.get("branch") or parameters.get("branch_name"),
+            }
+            result = await _dispatch("plan.generate", params, github_token)
+            return JSONResponse(
+                {"response": result, "protocol_version": payload.get("protocol_version", "1.0")},
+                headers={"X-Trace-Id": trace_id},
+            )
+
+        raise HTTPException(status_code=404, detail=f"Unsupported interaction_type: {interaction_type}")
+
+    raise HTTPException(status_code=400, detail=f"Invalid A2A payload (trace_id={trace_id})")
+
+
+@router.post("/a2a/invoke")
+async def a2a_invoke(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    x_a2a_secret: Optional[str] = Header(None, alias="X-A2A-Secret"),
+    x_github_token: Optional[str] = Header(None, alias="X-Github-Token"),
+    x_request_id: Optional[str] = Header(None, alias="X-Request-Id"),
+) -> JSONResponse:
+    return await _handle_invoke(request, authorization, x_a2a_secret, x_github_token, x_request_id)
+
+
+@router.post("/a2a/v1/invoke")
+async def a2a_v1_invoke(
+    request: Request,
+    authorization: Optional[str] = Header(None),
+    x_a2a_secret: Optional[str] = Header(None, alias="X-A2A-Secret"),
+    x_github_token: Optional[str] = Header(None, alias="X-Github-Token"),
+    x_request_id: Optional[str] = Header(None, alias="X-Request-Id"),
+) -> JSONResponse:
+    # Alias for versioned clients. Keep behavior identical to /a2a/invoke.
+    return await _handle_invoke(request, authorization, x_a2a_secret, x_github_token, x_request_id)

gitpilot/agent_router.py

@@ -0,0 +1,284 @@
+# gitpilot/agent_router.py
+"""Intelligent Agent Router for GitPilot.
+
+Classifies user requests and delegates them to the appropriate specialised
+agent (or a pipeline of agents).  The router itself does **not** use an LLM;
+it relies on lightweight keyword / pattern matching so that routing is
+instantaneous and deterministic.
+
+The router returns a *WorkflowPlan* describing which agents should run and
+in what order.  The actual agent execution is handled by the orchestrator
+in ``agentic.py``.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+
+class AgentType(str, Enum):
+    """Available specialised agents."""
+
+    EXPLORER = "explorer"
+    PLANNER = "planner"
+    CODE_WRITER = "code_writer"
+    CODE_REVIEWER = "code_reviewer"
+    ISSUE_MANAGER = "issue_manager"
+    PR_MANAGER = "pr_manager"
+    SEARCH = "search"
+    LEARNING = "learning"
+    LOCAL_EDITOR = "local_editor"       # Phase 1: local file editing + shell
+    TERMINAL = "terminal"              # Phase 1: dedicated terminal agent
+
+
+class RequestCategory(str, Enum):
+    """High-level intent category inferred from the user request."""
+
+    PLAN_EXECUTE = "plan_execute"       # Existing explore -> plan -> execute workflow
+    ISSUE_MANAGEMENT = "issue_management"
+    PR_MANAGEMENT = "pr_management"
+    CODE_SEARCH = "code_search"
+    CODE_REVIEW = "code_review"
+    LEARNING = "learning"
+    CONVERSATIONAL = "conversational"   # Free-form chat / Q&A about the repo
+    LOCAL_EDIT = "local_edit"           # Phase 1: direct file editing with verification
+    TERMINAL = "terminal"              # Phase 1: shell command execution
+
+
+@dataclass
+class WorkflowPlan:
+    """Describes which agents to invoke and in what order."""
+
+    category: RequestCategory
+    agents: List[AgentType]
+    description: str
+    requires_repo_context: bool = True
+    # If the request mentions a specific issue/PR number, capture it.
+    entity_number: Optional[int] = None
+    # Additional metadata extracted from the request.
+    metadata: dict = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Pattern definitions (order matters -- first match wins)
+# ---------------------------------------------------------------------------
+
+_ISSUE_CREATE_RE = re.compile(
+    r"\b(create|open|new|file|add)\b.*\bissue\b", re.IGNORECASE
+)
+_ISSUE_UPDATE_RE = re.compile(
+    r"\b(update|modify|edit|change|close|reopen|label|assign|milestone)\b.*\bissue\b",
+    re.IGNORECASE,
+)
+_ISSUE_LIST_RE = re.compile(
+    r"\b(list|show|get|find|search)\b.*\bissues?\b", re.IGNORECASE
+)
+_ISSUE_COMMENT_RE = re.compile(
+    r"\b(comment|reply|respond)\b.*\bissue\b", re.IGNORECASE
+)
+_ISSUE_NUMBER_RE = re.compile(r"#(\d+)")
+
+_PR_CREATE_RE = re.compile(
+    r"\b(create|open|new|make)\b.*\b(pull request|pr|pull)\b", re.IGNORECASE
+)
+_PR_MERGE_RE = re.compile(
+    r"\b(merge|squash|rebase)\b.*\b(pull request|pr|pull)\b", re.IGNORECASE
+)
+_PR_REVIEW_RE = re.compile(
+    r"\b(review|approve|request changes)\b.*\b(pull request|pr|pull)\b",
+    re.IGNORECASE,
+)
+_PR_LIST_RE = re.compile(
+    r"\b(list|show|get|find)\b.*\b(pull requests?|prs?|pulls?)\b", re.IGNORECASE
+)
+
+_SEARCH_CODE_RE = re.compile(
+    r"\b(search|find|locate|grep|look for)\b.*\b(code|function|class|symbol|pattern|file)\b",
+    re.IGNORECASE,
+)
+_SEARCH_USER_RE = re.compile(
+    r"\b(search|find|who)\b.*\b(user|developer|org|organization|contributor)\b",
+    re.IGNORECASE,
+)
+_SEARCH_REPO_RE = re.compile(
+    r"\b(search|find|discover)\b.*\b(repo|repository|project)\b", re.IGNORECASE
+)
+
+_TERMINAL_RE = re.compile(
+    r"\b(run|execute|launch)\b.*\b(command|test|tests|script|build|lint|npm|pip|make|docker|pytest|cargo|go)\b",
+    re.IGNORECASE,
+)
+_LOCAL_EDIT_RE = re.compile(
+    r"\b(edit|modify|change|update|fix|write|rewrite|patch)\b.*\b(file|code|function|class|method|module|line|lines)\b",
+    re.IGNORECASE,
+)
+
+_REVIEW_RE = re.compile(
+    r"\b(review|analyze|audit|check|inspect)\b.*\b(code|quality|security|performance)\b",
+    re.IGNORECASE,
+)
+
+_LEARNING_RE = re.compile(
+    r"\b(how (do|can|to)|explain|what is|guide|tutorial|best practice|help with)\b",
+    re.IGNORECASE,
+)
+_GITHUB_TOPICS_RE = re.compile(
+    r"\b(actions?|workflow|ci/?cd|pages?|packages?|discussions?|authentication|deploy|release)\b",
+    re.IGNORECASE,
+)
+
+
+def _extract_issue_number(text: str) -> Optional[int]:
+    m = _ISSUE_NUMBER_RE.search(text)
+    if m:
+        return int(m.group(1))
+    # Also try "issue 42" / "issue number 42"
+    m2 = re.search(r"\bissue\s*(?:number\s*)?(\d+)\b", text, re.IGNORECASE)
+    return int(m2.group(1)) if m2 else None
+
+
+def _extract_pr_number(text: str) -> Optional[int]:
+    m = re.search(r"\b(?:pr|pull request|pull)\s*#?(\d+)\b", text, re.IGNORECASE)
+    return int(m.group(1)) if m else None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def route(user_request: str) -> WorkflowPlan:
+    """Classify *user_request* and return a ``WorkflowPlan``."""
+    text = user_request.strip()
+
+    # --- Issue management ------------------------------------------------
+    if _ISSUE_CREATE_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.ISSUE_MANAGEMENT,
+            agents=[AgentType.ISSUE_MANAGER],
+            description="Create a new GitHub issue",
+            entity_number=_extract_issue_number(text),
+            metadata={"action": "create"},
+        )
+    if _ISSUE_COMMENT_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.ISSUE_MANAGEMENT,
+            agents=[AgentType.ISSUE_MANAGER],
+            description="Comment on an issue",
+            entity_number=_extract_issue_number(text),
+            metadata={"action": "comment"},
+        )
+    if _ISSUE_UPDATE_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.ISSUE_MANAGEMENT,
+            agents=[AgentType.ISSUE_MANAGER],
+            description="Update an existing issue",
+            entity_number=_extract_issue_number(text),
+            metadata={"action": "update"},
+        )
+    if _ISSUE_LIST_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.ISSUE_MANAGEMENT,
+            agents=[AgentType.ISSUE_MANAGER],
+            description="List or search issues",
+            metadata={"action": "list"},
+        )
+
+    # --- PR management ---------------------------------------------------
+    if _PR_CREATE_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.PR_MANAGEMENT,
+            agents=[AgentType.PR_MANAGER],
+            description="Create a pull request",
+            metadata={"action": "create"},
+        )
+    if _PR_MERGE_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.PR_MANAGEMENT,
+            agents=[AgentType.PR_MANAGER],
+            description="Merge a pull request",
+            entity_number=_extract_pr_number(text),
+            metadata={"action": "merge"},
+        )
+    if _PR_REVIEW_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.PR_MANAGEMENT,
+            agents=[AgentType.CODE_REVIEWER, AgentType.PR_MANAGER],
+            description="Review a pull request",
+            entity_number=_extract_pr_number(text),
+            metadata={"action": "review"},
+        )
+    if _PR_LIST_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.PR_MANAGEMENT,
+            agents=[AgentType.PR_MANAGER],
+            description="List pull requests",
+            metadata={"action": "list"},
+        )
+
+    # --- Code search -----------------------------------------------------
+    if _SEARCH_USER_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.CODE_SEARCH,
+            agents=[AgentType.SEARCH],
+            description="Search for GitHub users or organisations",
+            requires_repo_context=False,
+            metadata={"search_type": "users"},
+        )
+    if _SEARCH_REPO_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.CODE_SEARCH,
+            agents=[AgentType.SEARCH],
+            description="Search for repositories",
+            requires_repo_context=False,
+            metadata={"search_type": "repositories"},
+        )
+    if _SEARCH_CODE_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.CODE_SEARCH,
+            agents=[AgentType.SEARCH],
+            description="Search for code in the repository",
+            metadata={"search_type": "code"},
+        )
+
+    # --- Terminal / shell commands ----------------------------------------
+    if _TERMINAL_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.TERMINAL,
+            agents=[AgentType.TERMINAL],
+            description="Run shell commands in the workspace",
+            metadata={"action": "execute"},
+        )
+
+    # --- Local file editing -----------------------------------------------
+    if _LOCAL_EDIT_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.LOCAL_EDIT,
+            agents=[AgentType.LOCAL_EDITOR],
+            description="Edit files directly in the local workspace",
+        )
+
+    # --- Code review -----------------------------------------------------
+    if _REVIEW_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.CODE_REVIEW,
+            agents=[AgentType.EXPLORER, AgentType.CODE_REVIEWER],
+            description="Analyse code quality and suggest improvements",
+        )
+
+    # --- Learning & guidance ---------------------------------------------
+    if _LEARNING_RE.search(text) or _GITHUB_TOPICS_RE.search(text):
+        return WorkflowPlan(
+            category=RequestCategory.LEARNING,
+            agents=[AgentType.LEARNING],
+            description="Provide guidance on GitHub features or best practices",
+            requires_repo_context=False,
+        )
+
+    # --- Default: existing plan+execute workflow -------------------------
+    return WorkflowPlan(
+        category=RequestCategory.PLAN_EXECUTE,
+        agents=[AgentType.EXPLORER, AgentType.PLANNER, AgentType.CODE_WRITER],
+        description="Explore repository, create plan, and execute changes",
+    )

gitpilot/agent_teams.py

@@ -0,0 +1,263 @@
+# gitpilot/agent_teams.py
+"""Parallel multi-agent execution on git worktrees.
+
+Coordinates multiple agents working on independent subtasks simultaneously.
+Each agent operates on its own git worktree to avoid conflicts, and a lead
+agent reviews and merges the results.
+
+Architecture inspired by the MapReduce pattern and the *divide-and-conquer*
+approach from distributed systems research (Dean & Ghemawat, 2004).
+
+Workflow::
+
+    User: "Add authentication to the API"
+    Lead agent splits → 4 subtasks
+    ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
+    │ Agent A:    │  │ Agent B:    │  │ Agent C:    │  │ Agent D:    │
+    │ User model  │  │ Middleware  │  │ Endpoints   │  │ Tests       │
+    │ worktree/a  │  │ worktree/b  │  │ worktree/c  │  │ worktree/d  │
+    └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘
+          └───────────┴───────────┴───────────┘
+                          │
+                    Lead reviews & merges
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class SubTaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class SubTask:
+    """A single subtask to be executed by one agent."""
+
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    title: str = ""
+    description: str = ""
+    assigned_agent: str = ""
+    files: List[str] = field(default_factory=list)
+    status: SubTaskStatus = SubTaskStatus.PENDING
+    result: str = ""
+    error: Optional[str] = None
+    worktree_path: Optional[Path] = None
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "assigned_agent": self.assigned_agent,
+            "files": self.files,
+            "status": self.status.value,
+            "result": self.result,
+            "error": self.error,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+        }
+
+
+@dataclass
+class TeamResult:
+    """Aggregated result from parallel agent execution."""
+
+    task: str
+    subtasks: List[SubTask] = field(default_factory=list)
+    merge_status: str = "pending"  # pending | merged | conflict | failed
+    conflicts: List[str] = field(default_factory=list)
+    summary: str = ""
+
+    @property
+    def all_completed(self) -> bool:
+        return all(s.status == SubTaskStatus.COMPLETED for s in self.subtasks)
+
+    @property
+    def any_failed(self) -> bool:
+        return any(s.status == SubTaskStatus.FAILED for s in self.subtasks)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "task": self.task,
+            "subtasks": [s.to_dict() for s in self.subtasks],
+            "merge_status": self.merge_status,
+            "conflicts": self.conflicts,
+            "summary": self.summary,
+            "all_completed": self.all_completed,
+            "any_failed": self.any_failed,
+        }
+
+
+class AgentTeam:
+    """Coordinate multiple agents working in parallel.
+
+    Usage::
+
+        team = AgentTeam(workspace_path=Path("/repo"))
+        subtasks = team.plan_and_split("Add auth system", num_agents=4)
+        result = await team.execute_parallel(subtasks, executor_fn=my_agent_fn)
+        merge = await team.merge_results(result)
+    """
+
+    def __init__(self, workspace_path: Optional[Path] = None) -> None:
+        self.workspace_path = workspace_path
+        self._worktrees: List[Path] = []
+
+    def plan_and_split(
+        self,
+        task: str,
+        num_agents: int = 4,
+        subtask_descriptions: Optional[List[Dict[str, str]]] = None,
+    ) -> List[SubTask]:
+        """Split a task into independent subtasks.
+
+        If ``subtask_descriptions`` is provided, use those directly.
+        Otherwise, create generic subtasks from the task description.
+        """
+        subtasks = []
+
+        if subtask_descriptions:
+            for i, desc in enumerate(subtask_descriptions):
+                subtasks.append(SubTask(
+                    title=desc.get("title", f"Subtask {i + 1}"),
+                    description=desc.get("description", ""),
+                    assigned_agent=desc.get("agent", f"agent_{i}"),
+                    files=desc.get("files", []),
+                ))
+        else:
+            # Generic split — the LLM would normally do this
+            for i in range(min(num_agents, 8)):
+                subtasks.append(SubTask(
+                    title=f"Part {i + 1} of {task}",
+                    description=f"Handle part {i + 1} of the task: {task}",
+                    assigned_agent=f"agent_{i}",
+                ))
+
+        return subtasks
+
+    async def execute_parallel(
+        self,
+        subtasks: List[SubTask],
+        executor_fn: Optional[Any] = None,
+    ) -> TeamResult:
+        """Execute subtasks in parallel.
+
+        ``executor_fn`` is an async callable(SubTask) -> str that runs the
+        agent logic for each subtask.  If not provided, subtasks are marked
+        as completed with a placeholder result.
+        """
+        result = TeamResult(task="parallel_execution", subtasks=subtasks)
+
+        async def _run_subtask(subtask: SubTask) -> None:
+            subtask.status = SubTaskStatus.RUNNING
+            subtask.started_at = datetime.now(timezone.utc).isoformat()
+            try:
+                if executor_fn:
+                    subtask.result = await executor_fn(subtask)
+                else:
+                    subtask.result = f"Completed: {subtask.title}"
+                subtask.status = SubTaskStatus.COMPLETED
+            except Exception as e:
+                subtask.status = SubTaskStatus.FAILED
+                subtask.error = str(e)
+                logger.error("Subtask %s failed: %s", subtask.id, e)
+            finally:
+                subtask.completed_at = datetime.now(timezone.utc).isoformat()
+
+        # Run all subtasks concurrently
+        await asyncio.gather(*[_run_subtask(st) for st in subtasks])
+
+        return result
+
+    async def merge_results(self, team_result: TeamResult) -> TeamResult:
+        """Merge results from parallel execution.
+
+        In a full implementation, this would:
+        1. Check for file conflicts between subtask outputs
+        2. Use git merge-tree for conflict detection
+        3. Have a lead agent resolve conflicts
+
+        For now, it aggregates results and detects file overlaps.
+        """
+        if team_result.any_failed:
+            team_result.merge_status = "failed"
+            failed = [s for s in team_result.subtasks if s.status == SubTaskStatus.FAILED]
+            team_result.summary = (
+                f"{len(failed)} subtask(s) failed: "
+                + ", ".join(f"{s.title} ({s.error})" for s in failed)
+            )
+            return team_result
+
+        # Detect file conflicts (same file modified by multiple agents)
+        file_owners: Dict[str, List[str]] = {}
+        for st in team_result.subtasks:
+            for f in st.files:
+                file_owners.setdefault(f, []).append(st.assigned_agent)
+
+        conflicts = [f for f, owners in file_owners.items() if len(owners) > 1]
+        team_result.conflicts = conflicts
+
+        if conflicts:
+            team_result.merge_status = "conflict"
+            team_result.summary = (
+                f"File conflicts detected in: {', '.join(conflicts)}. "
+                "Manual review required."
+            )
+        else:
+            team_result.merge_status = "merged"
+            completed = [s for s in team_result.subtasks if s.status == SubTaskStatus.COMPLETED]
+            team_result.summary = (
+                f"All {len(completed)} subtasks completed successfully. "
+                "No file conflicts detected."
+            )
+
+        return team_result
+
+    async def setup_worktrees(self, subtasks: List[SubTask], base_branch: str = "main") -> None:
+        """Create git worktrees for each subtask (requires workspace_path)."""
+        if not self.workspace_path:
+            return
+        for st in subtasks:
+            worktree_name = f"worktree-{st.id}"
+            worktree_path = self.workspace_path / ".worktrees" / worktree_name
+            branch_name = f"team/{st.id}"
+
+            proc = await asyncio.create_subprocess_exec(
+                "git", "worktree", "add", "-b", branch_name,
+                str(worktree_path), base_branch,
+                cwd=str(self.workspace_path),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await proc.communicate()
+            st.worktree_path = worktree_path
+            self._worktrees.append(worktree_path)
+
+    async def cleanup_worktrees(self) -> None:
+        """Remove all worktrees created by this team."""
+        if not self.workspace_path:
+            return
+        for wt in self._worktrees:
+            proc = await asyncio.create_subprocess_exec(
+                "git", "worktree", "remove", "--force", str(wt),
+                cwd=str(self.workspace_path),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            await proc.communicate()
+        self._worktrees.clear()