docs: cap Python to 3.12–3.13 and update all user-facing documentation

- Set requires-python to '>=3.12,<3.14' so pip/uv reject 3.14 upfront
- Add Python 3.13 classifier to pyproject.toml
- Update README: tabbed install, all 6 supported agents with links, new CLI commands
- Update CONTRIBUTING: expanded testing section, current project structure, prerequisites
- Update docs/contributing: prerequisites, test commands, snapshot commands, code style
- Update docs/index: all 6 agents in supported list and architecture diagram
- Add docs/troubleshooting.md: Windows (C++ Redistributable, PowerShell, PAIR mode),
  macOS/Linux (tmux, permissions), General (agent detection, locks, merges, reset)
- Remove all Python 3.14 workaround notes and --with-python flags from docs

Author: aorumbayev

CONTRIBUTING.md

@@ -5,15 +5,23 @@ developers working on the codebase. User documentation lives in `docs/`.
 
 ## Prerequisites
 
-- Python 3.12+
+- Python 3.12 – 3.13
 - `uv` for dependency management
 - A terminal that supports Textual (for running the TUI)
-- tmux (for PAIR mode testing)
+- tmux (for PAIR mode testing on macOS/Linux)
 - Git (for worktree functionality)
 
 ## Getting Started
 
-Clone the repo and execute:
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/aorumbayev/kagan.git
+cd kagan
+uv sync --dev
+```
+
+Run the app:
 
 ```bash
 uv run kagan
@@ -46,7 +54,7 @@ uv run poe check      # lint + typecheck + test
 ## Testing
 
 ```bash
-# All tests
+# All tests (parallel by default)
 uv run pytest tests/ -v
 
 # Single file
@@ -57,12 +65,22 @@ uv run pytest tests/features/test_agent_automation.py::TestIterationLoop -v
 
 # Single test
 uv run pytest tests/features/test_agent_automation.py::TestIterationLoop::test_complete_signal_moves_to_review -v
+
+# By marker
+uv run pytest -m unit -v              # Unit tests
+uv run pytest -m integration -v       # Integration tests
+uv run pytest -m e2e -v               # End-to-end tests
+uv run pytest -m "not slow" -v        # Exclude slow tests
+uv run pytest tests/ -n 0 -v          # Sequential (for debugging)
 ```
 
 ## UI Snapshots
 
+Snapshot tests must run sequentially (no parallel):
+
 ```bash
-UPDATE_SNAPSHOTS=1 uv run pytest tests/test_snapshots.py --snapshot-update
+uv run poe test-snapshot              # Run snapshot tests
+uv run poe test-snapshot-update       # Update snapshots
 ```
 
 ## Docs Preview
@@ -107,6 +125,9 @@ src/kagan/
 ├── lock.py             # Instance lock (single instance)
 ├── git_utils.py        # Git helper functions
 ├── keybindings.py      # Centralized keybinding registry (single file)
+├── builtin_agents.py   # Built-in agent definitions (Claude, OpenCode, Codex, Gemini, Kimi, Copilot)
+├── preflight.py        # Pre-flight checks and agent detection
+├── __main__.py         # CLI entry point (Click-based)
 ├── adapters/
 │   ├── db/             # SQLModel schema + repositories
 │   ├── git/            # Worktree/diff/merge adapters
@@ -139,16 +160,14 @@ src/kagan/
 │   ├── signals.py      # Agent completion signals parser
 │   ├── prompt.py       # Prompt building for AUTO mode
 │   ├── prompt_loader.py    # Template loading for prompts
+│   ├── installer.py    # Agent installation helpers
 │   └── config_resolver.py  # Agent config resolution
 ├── acp/                # Agent Control Protocol
-│   ├── agent.py        # ACP Agent class (JSON-RPC over subprocess)
-│   ├── protocol.py     # ACP protocol types
+│   ├── kagan_agent.py  # ACP Agent class (JSON-RPC over subprocess)
 │   ├── messages.py     # Textual messages for agent events
 │   ├── terminals.py    # Terminal management for agents
 │   ├── terminal.py     # Single terminal handling
 │   └── buffers.py      # Response buffering
-├── data/
-│   └── builtin_agents.py   # Built-in agent definitions (Claude, OpenCode)
 ├── styles/
 │   └── kagan.tcss      # ALL CSS here (no DEFAULT_CSS in Python!)
 └── ui/
@@ -161,10 +180,12 @@ src/kagan/
     │   │   ├── screen.py   # KanbanScreen implementation
     │   │   ├── focus.py    # Focus management helpers
     │   │   └── hints.py    # Keybinding hints
-    │   ├── planner/        # Planner screen (chat-first)
-    │   ├── welcome.py      # First-boot setup screen
-    │   ├── task_editor.py    # Task editor screen
-    │   └── troubleshooting/    # Pre-flight check failures
+    │   ├── planner/        # Planner screen (chat-first AI planner)
+    │   ├── welcome.py      # Project picker screen
+    │   ├── onboarding.py   # First-boot setup screen
+    │   ├── task_editor.py  # Task editor screen
+    │   ├── repo_picker.py  # Multi-repo selector
+    │   └── troubleshooting/ # Pre-flight check failure screen
     ├── widgets/
     │   ├── card.py         # TaskCard widget
     │   ├── column.py       # KanbanColumn widget
@@ -188,7 +209,10 @@ src/kagan/
         ├── description_editor.py   # Full-screen description editor
         ├── help.py             # Help modal
         ├── tmux_gateway.py     # Tmux gateway info modal
-        ├── duplicate_task.py # Duplicate task modal
+        ├── duplicate_task.py   # Duplicate task modal
+        ├── global_agent_picker.py  # Agent switcher modal
+        ├── agent_install.py    # Agent installation modal
+        ├── agent_choice.py     # Agent choice modal
         └── actions.py          # Modal action enums
 ```
 

README.md

@@ -34,20 +34,33 @@ Kagan is a terminal-based Kanban board that integrates AI agents to help you com
 
 ## Install
 
-```bash
-# Standard install (requires Python 3.12+)
-pip install kagan
+=== "UV (Recommended)"
 
-# Recommended: faster with uv
+```bash
 uv tool install kagan
+```
 
-# Or all-in-one (includes uv + Python if needed)
+=== "Mac / Linux"
+
+```bash
 curl -fsSL https://uvget.me/install.sh | bash -s -- kagan
 ```
 
+=== "Windows (PowerShell)"
+
+```powershell
+iwr -useb uvget.me/install.ps1 -OutFile install.ps1; .\install.ps1 kagan
+```
+
+=== "pip"
+
+```bash
+pip install kagan
+```
+
 ### Requirements
 
-- Python 3.12 or higher
+- Python 3.12 – 3.13
 - Git repository (for worktrees)
 - tmux (recommended on macOS/Linux for native PAIR terminal sessions)
 - VS Code or Cursor (supported PAIR launchers, especially on Windows)
@@ -59,16 +72,21 @@ curl -fsSL https://uvget.me/install.sh | bash -s -- kagan
 kagan              # Launch TUI (default command)
 kagan tui          # Launch TUI explicitly
 kagan mcp          # Run as MCP server
-kagan tools        # Stateless developer utilities
+kagan tools        # Stateless developer utilities (prompt enhancement)
 kagan update       # Check for and install updates
+kagan list         # List all projects with task counts
+kagan reset        # Reset data (interactive)
 kagan --help       # Show all options
 ```
 
 ## Supported AI CLIs
 
-- Claude Code
-- OpenCode
-- *More coming soon*
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic)
+- [OpenCode](https://opencode.ai/docs) (SST)
+- [Codex](https://github.com/openai/codex) (OpenAI)
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Google)
+- [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) (Moonshot AI)
+- [GitHub Copilot](https://github.com/github/copilot-cli) (GitHub)
 
 ## Documentation
 

docs/contributing.md

@@ -11,6 +11,13 @@ We welcome contributions to Kagan! This page provides quick links to get started
 | Pull Requests      | [GitHub PRs](https://github.com/aorumbayev/kagan/pulls)                          |
 | Discussions        | [GitHub Discussions](https://github.com/aorumbayev/kagan/discussions)            |
 
+## Prerequisites
+
+- Python 3.12 – 3.13
+- `uv` for dependency management
+- Git (for worktree functionality)
+- tmux (for PAIR mode testing on macOS/Linux)
+
 ## Development Setup
 
 ```bash
@@ -37,21 +44,23 @@ uv run poe check
 ## Code Style
 
 - Python 3.12+ with type annotations
-- Ruff for linting and formatting
+- Ruff for linting and formatting (line length 100)
 - CSS in `.tcss` files only (no `DEFAULT_CSS`)
 - All keybindings defined in `keybindings.py`
+- Use `from __future__ import annotations` in every file
 
 ## Testing
 
 ```bash
-uv run pytest tests/ -v              # All tests (parallel by default)
-uv run pytest tests/e2e/test_critical_flows.py  # Single test file
-uv run pytest tests/e2e/test_critical_flows.py::TestAutoTaskLifecycle::test_auto_full_lifecycle  # Single test function
-uv run pytest -m unit                # Unit tests only
-uv run pytest -m integration         # Integration tests
-uv run pytest -m e2e                 # End-to-end tests
-uv run pytest -m "not slow"          # Exclude slow tests
-uv run pytest tests/ -n 0            # Sequential (for debugging)
+uv run pytest tests/ -v                    # All tests (parallel by default)
+uv run pytest tests/features/ -v           # Feature tests
+uv run pytest -m unit -v                   # Unit tests only
+uv run pytest -m integration -v            # Integration tests
+uv run pytest -m e2e -v                    # End-to-end tests
+uv run pytest -m "not slow" -v             # Exclude slow tests
+uv run pytest tests/ -n 0 -v              # Sequential (for debugging)
+uv run poe test-snapshot                   # Snapshot tests (sequential only)
+uv run poe test-snapshot-update            # Update snapshots
 ```
 
 ## Docs Preview

docs/index.md

@@ -201,6 +201,10 @@ flowchart TB
     subgraph Agents["AI Agents"]
         Claude["Claude Code"]
         OpenCode["OpenCode"]
+        Codex["Codex"]
+        Gemini["Gemini CLI"]
+        Kimi["Kimi CLI"]
+        Copilot["GitHub Copilot"]
     end
 
     Agents --> Code
@@ -255,7 +259,9 @@ AUTO tasks have automatic state transitions driven by the agent. PAIR tasks are
 
 ## Supported AI CLIs
 
-- **Claude Code** (Anthropic)
-- **OpenCode** (open source)
-
-Coming soon: Gemini, Codex, and more.
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** (Anthropic)
+- **[OpenCode](https://opencode.ai/docs)** (SST)
+- **[Codex](https://github.com/openai/codex)** (OpenAI)
+- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** (Google)
+- **[Kimi CLI](https://github.com/MoonshotAI/kimi-cli)** (Moonshot AI)
+- **[GitHub Copilot](https://github.com/github/copilot-cli)** (GitHub)

docs/troubleshooting.md

@@ -0,0 +1,132 @@
+# Troubleshooting
+
+Common issues and solutions when running Kagan.
+
+## Windows
+
+### Microsoft Visual C++ Redistributable
+
+Some Python packages used by Kagan include native extensions that require the
+Microsoft Visual C++ Redistributable. If you see build errors mentioning missing
+`vcruntime` or `cl.exe`, install the redistributable:
+
+**Download:** [Microsoft Visual C++ Redistributable](https://go.microsoft.com/fwlink/?LinkID=135170)
+
+After installing, restart your terminal and retry the Kagan installation.
+
+### Windows Installation (PowerShell)
+
+The recommended way to install Kagan on Windows is with the all-in-one installer that
+bundles `uv` and a compatible Python version:
+
+```powershell
+iwr -useb uvget.me/install.ps1 -OutFile install.ps1; .\install.ps1 kagan
+```
+
+Alternatively, if you already have `uv` and Python 3.12+ installed:
+
+```powershell
+uv tool install kagan
+```
+
+### PAIR Mode on Windows
+
+Windows does not support tmux natively. Kagan defaults to VS Code as the PAIR terminal
+backend on Windows. You can also use Cursor:
+
+```toml
+[general]
+default_pair_terminal_backend = "vscode"  # or "cursor"
+```
+
+Make sure `code` (VS Code) or `cursor` is available in your PATH.
+
+## macOS / Linux
+
+### tmux Not Found
+
+PAIR mode defaults to tmux on macOS and Linux. Install it:
+
+```bash
+# macOS
+brew install tmux
+
+# Debian / Ubuntu
+sudo apt install tmux
+
+# Fedora / RHEL
+sudo dnf install tmux
+```
+
+Alternatively, switch to VS Code or Cursor as the PAIR backend:
+
+```toml
+[general]
+default_pair_terminal_backend = "vscode"
+```
+
+### Permission Denied on Install Script
+
+If the `curl` install script fails with a permission error:
+
+```bash
+curl -fsSL https://uvget.me/install.sh | bash -s -- kagan
+```
+
+Try running with explicit permission:
+
+```bash
+curl -fsSL https://uvget.me/install.sh -o install.sh && chmod +x install.sh && ./install.sh kagan
+```
+
+## General
+
+### Agent Not Detected
+
+Kagan auto-detects installed AI CLI agents on startup. If your agent is not detected:
+
+1. Make sure the agent's CLI binary is in your `PATH`
+2. Run `which claude`, `which opencode`, `which gemini`, etc. to verify
+3. Restart your terminal after installing an agent
+4. Check the Debug Log (++f12++) for detection details
+
+### Instance Lock Error
+
+Kagan enforces one instance per repository. If you see "instance locked":
+
+1. Close any other running Kagan instances for the same repo
+2. If the lock is stale (e.g. after a crash), use `kagan reset` to clean up
+3. Or delete the lock file manually from the XDG data directory
+
+### Merge Conflicts
+
+If a merge fails in REVIEW:
+
+1. Kagan shows merge readiness (Ready / At Risk / Blocked) before you merge
+2. Use the resolve action in Task Details to open a terminal in the merge worktree
+3. Fix conflicts manually, then retry the merge
+4. Consider enabling `serialize_merges = true` in config to reduce conflicts when running
+   multiple parallel agents
+
+### Small Terminal Window
+
+Kagan requires a minimum terminal size of 80 columns by 20 rows. If the UI looks broken,
+resize your terminal window or reduce the font size.
+
+### Database Reset
+
+If you need a fresh start:
+
+```bash
+# Interactive reset (choose what to reset)
+kagan reset
+
+# Nuclear reset (removes all data)
+kagan reset --force
+```
+
+Data is stored in XDG-compliant locations:
+
+- Database: `~/.local/share/kagan/kagan.db`
+- Config: `~/.config/kagan/config.toml`
+- Worktrees: system temp directory (e.g., `/var/tmp/kagan/worktrees/`)

mkdocs.yml

@@ -103,4 +103,5 @@ nav:
   - Multi-Repo Guide: multi-repo-guide.md
   - Keyboard Shortcuts: keybindings.md
   - Configuration: config.md
+  - Troubleshooting: troubleshooting.md
   - Contributing: contributing.md