debug: synthesize wheel events for mobile terminal touch scrolling

Replace manual scrollLines/SGR injection with synthetic WheelEvent
instances dispatched into xterm.js's .xterm-viewport. Keep the debug
overlay so we can verify whether the gesture is recognized and whether
the wheel event reaches xterm.js.

Quality gates: typecheck, lint clean.

.atl/.skill-registry.cache.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "c36b11ec5edebc02aa51b1113a7a11dc2559e812"
+  "fingerprint": "639c16d45210921c3c8ece071ef18bbe0c426ea2"
 }

.atl/skill-registry.md

@@ -1,14 +1,13 @@
-# Skill Registry — headquarter
+# Skill Registry — workspace
 
 <!-- Auto-generated by gentle-pi extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->
 
-Last updated: 2026-06-02
+Last updated: 2026-06-05
 
 ## Sources scanned
 
 - .opencode/skills
 - .claude/skills
-- /home/alex/.config/opencode/skills
 
 ## Contract
 
@@ -20,12 +19,11 @@ Last updated: 2026-06-02
 
 | Skill | Trigger / description | Scope | Path |
 | --- | --- | --- | --- |
-| `auto-commit` | Use when you are making multiple edits or completing significant work in a git repository to automatically create commits | user | `/home/alex/.config/opencode/skills/auto-commit/SKILL.md` |
-| `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-apply-change/SKILL.md` |
-| `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-archive-change/SKILL.md` |
-| `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-explore/SKILL.md` |
-| `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-propose/SKILL.md` |
-| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/home/alex/projects/headquarter/.claude/skills/sift-backlog/SKILL.md` |
+| `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/workspace/.opencode/skills/openspec-apply-change/SKILL.md` |
+| `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/workspace/.opencode/skills/openspec-archive-change/SKILL.md` |
+| `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/workspace/.opencode/skills/openspec-explore/SKILL.md` |
+| `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/workspace/.opencode/skills/openspec-propose/SKILL.md` |
+| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/workspace/.claude/skills/sift-backlog/SKILL.md` |
 
 ## Loading protocol
 

.claude/.pi-map.index.md

@@ -0,0 +1,20 @@
+# .claude (index)
+dir: .claude
+
+## role
+Configuration directory for Claude AI assistant integration and custom instructions.
+## parent
+index: ./.pi-map.index.md
+map: ./.pi-map.md
+## children
+- .claude/skills
+  index: .claude/skills/.pi-map.index.md
+  map: .claude/skills/.pi-map.md
+## files
+## links
+index: .claude/.pi-map.index.md
+map: .claude/.pi-map.md
+## workflows
+-
+## dirty
+-

.claude/.pi-map.md

@@ -0,0 +1,18 @@
+# .claude
+dir: .claude
+
+index: .claude/.pi-map.index.md
+
+## role
+Configuration directory for Claude AI assistant integration and custom instructions.
+## files
+## arch
+Project-specific AI tooling configuration using convention-based file organization for assistant context and behavior customization.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-

.claude/skills/.pi-map.index.md

@@ -0,0 +1,20 @@
+# .claude/skills (index)
+dir: .claude/skills
+
+## role
+Contains reusable AI skill definitions and prompt templates that configure Claude's specialized capabilities for specific development tasks.
+## parent
+index: .claude/.pi-map.index.md
+map: .claude/.pi-map.md
+## children
+- .claude/skills/sift-backlog
+  index: .claude/skills/sift-backlog/.pi-map.index.md
+  map: .claude/skills/sift-backlog/.pi-map.md
+## files
+## links
+index: .claude/skills/.pi-map.index.md
+map: .claude/skills/.pi-map.md
+## workflows
+-
+## dirty
+-

.claude/skills/.pi-map.md

@@ -0,0 +1,18 @@
+# .claude/skills
+dir: .claude/skills
+
+index: .claude/skills/.pi-map.index.md
+
+## role
+Contains reusable AI skill definitions and prompt templates that configure Claude's specialized capabilities for specific development tasks.
+## files
+## arch
+Modular skill-based architecture using declarative configuration files (likely YAML/JSON) to define context-specific behaviors, tool access patterns, and system prompts for different operational modes.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-

.claude/skills/sift-backlog/.pi-map.index.md

@@ -0,0 +1,19 @@
+# .claude/skills/sift-backlog (index)
+dir: .claude/skills/sift-backlog
+
+## role
+Defines a workflow skill for triaging, organizing, and activating backlog tasks into actionable plans using a custom CLI tool.
+## parent
+index: .claude/skills/.pi-map.index.md
+map: .claude/skills/.pi-map.md
+## children
+-
+## files
+- SKILL.md
+## links
+index: .claude/skills/sift-backlog/.pi-map.index.md
+map: .claude/skills/sift-backlog/.pi-map.md
+## workflows
+-
+## dirty
+-

.claude/skills/sift-backlog/.pi-map.md

@@ -0,0 +1,19 @@
+# .claude/skills/sift-backlog
+dir: .claude/skills/sift-backlog
+
+index: .claude/skills/sift-backlog/.pi-map.index.md
+
+## role
+Defines a workflow skill for triaging, organizing, and activating backlog tasks into actionable plans using a custom CLI tool.
+## files
+- SKILL.md | Defines a workflow skill for triaging, organizing, and activating backlog tasks into actionable plans using a custom CLI tool. | dep: sf (custom CLI tool), task management system, plan management system
+## arch
+Documentation-driven skill definition using structured markdown with command specifications, workflow stages, and integration patterns for Claude CLI tooling.
+## tags
+skill, defines, workflow, triaging, organizing, activating, backlog, tasks
+## symbols
+-
+## workflows
+-
+## dirty
+-

.gitignore

@@ -17,6 +17,7 @@ __pycache__/
 *.so
 .python-version
 .venv/
+.venv-test/
 venv/
 env/
 .pytest_cache/
@@ -48,8 +49,12 @@ apps/web/dist/
 # OS
 .DS_Store
 Thumbs.db
-
-# Local runtime state
-.atl/
+/.stoneforge/.worktrees/
+# Pi / agent cache
 .pi/
-swap-pane
+.atl/
+.sisyphus/
+.pi-lens/
+minerv3/
+.cache/
+openspec-audit-report.md

.opencode/.pi-map.index.md

@@ -0,0 +1,23 @@
+# .opencode (index)
+dir: .opencode
+
+## role
+Hidden directory for OpenCode IDE/editor configuration and workspace metadata
+## parent
+index: ./.pi-map.index.md
+map: ./.pi-map.md
+## children
+- .opencode/commands
+  index: .opencode/commands/.pi-map.index.md
+  map: .opencode/commands/.pi-map.md
+- .opencode/skills
+  index: .opencode/skills/.pi-map.index.md
+  map: .opencode/skills/.pi-map.md
+## files
+## links
+index: .opencode/.pi-map.index.md
+map: .opencode/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/.pi-map.md

@@ -0,0 +1,18 @@
+# .opencode
+dir: .opencode
+
+index: .opencode/.pi-map.index.md
+
+## role
+Hidden directory for OpenCode IDE/editor configuration and workspace metadata
+## files
+## arch
+IDE-specific dot-directory pattern, no active code architecture; stores tool preferences and ephemeral state
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/commands/.pi-map.index.md

@@ -0,0 +1,22 @@
+# .opencode/commands (index)
+dir: .opencode/commands
+
+## role
+Defines experimental workflow skills and AI assistant stances for an OpenSpec-based development system with structured change management.
+## parent
+index: .opencode/.pi-map.index.md
+map: .opencode/.pi-map.md
+## children
+-
+## files
+- opsx-apply.md
+- opsx-archive.md
+- opsx-explore.md
+- opsx-propose.md
+## links
+index: .opencode/commands/.pi-map.index.md
+map: .opencode/commands/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/commands/.pi-map.md

@@ -0,0 +1,22 @@
+# .opencode/commands
+dir: .opencode/commands
+
+index: .opencode/commands/.pi-map.index.md
+
+## role
+Defines experimental workflow skills and AI assistant stances for an OpenSpec-based development system with structured change management.
+## files
+- opsx-apply.md | Defines an experimental workflow skill for implementing tasks from an OpenSpec change through a structured, interactive process with CLI integration and progress tracking. | dep: openspec CLI, AskUserQuestion tool, filesystem (for reading context files)
+- opsx-archive.md | Defines a workflow for archiving completed changes in an experimental openspec-based development system | dep: openspec CLI, AskUserQuestion tool, Task tool, Skill tool, filesystem (mkdir, mv), JSON parsing
+- opsx-explore.md | Defines the "explore mode" stance for an AI assistant - a thinking/discovery mode for investigating problems and clarifying requirements without implementing code | dep: OpenSpec system
+- opsx-propose.md | Defines a workflow for proposing new changes in the openspec system by creating a change directory and generating all required artifacts (proposal.md, design.md, tasks.md) in dependency order | dep: openspec CLI, AskUserQuestion tool, TodoWrite tool, JSON parsing
+## arch
+Markdown-based command definitions using a workflow pattern with interactive CLI integration, progress tracking, and dependency-ordered artifact generation across explore/propose/apply/archive lifecycle phases.
+## tags
+opsx, defines, workflow, openspec, openspec cli, askuserquestion tool, explore, experimental
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/skills/.pi-map.index.md

@@ -0,0 +1,29 @@
+# .opencode/skills (index)
+dir: .opencode/skills
+
+## role
+Contains reusable AI skill modules that provide specialized capabilities for the OpenCode assistant.
+## parent
+index: .opencode/.pi-map.index.md
+map: .opencode/.pi-map.md
+## children
+- .opencode/skills/openspec-apply-change
+  index: .opencode/skills/openspec-apply-change/.pi-map.index.md
+  map: .opencode/skills/openspec-apply-change/.pi-map.md
+- .opencode/skills/openspec-archive-change
+  index: .opencode/skills/openspec-archive-change/.pi-map.index.md
+  map: .opencode/skills/openspec-archive-change/.pi-map.md
+- .opencode/skills/openspec-explore
+  index: .opencode/skills/openspec-explore/.pi-map.index.md
+  map: .opencode/skills/openspec-explore/.pi-map.md
+- .opencode/skills/openspec-propose
+  index: .opencode/skills/openspec-propose/.pi-map.index.md
+  map: .opencode/skills/openspec-propose/.pi-map.md
+## files
+## links
+index: .opencode/skills/.pi-map.index.md
+map: .opencode/skills/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/skills/.pi-map.md

@@ -0,0 +1,18 @@
+# .opencode/skills
+dir: .opencode/skills
+
+index: .opencode/skills/.pi-map.index.md
+
+## role
+Contains reusable AI skill modules that provide specialized capabilities for the OpenCode assistant.
+## files
+## arch
+Modular plugin-based architecture where each skill is a self-contained module with defined interfaces, enabling dynamic loading and composition of AI capabilities.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-apply-change/.pi-map.index.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-apply-change (index)
+dir: .opencode/skills/openspec-apply-change
+
+## role
+Defines an AI assistant skill that implements OpenSpec changes through a spec-driven workflow with structured planning, validation, and execution phases.
+## parent
+index: .opencode/skills/.pi-map.index.md
+map: .opencode/skills/.pi-map.md
+## children
+-
+## files
+- SKILL.md
+## links
+index: .opencode/skills/openspec-apply-change/.pi-map.index.md
+map: .opencode/skills/openspec-apply-change/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-apply-change/.pi-map.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-apply-change
+dir: .opencode/skills/openspec-apply-change
+
+index: .opencode/skills/openspec-apply-change/.pi-map.index.md
+
+## role
+Defines an AI assistant skill that implements OpenSpec changes through a spec-driven workflow with structured planning, validation, and execution phases.
+## files
+- SKILL.md | Defines an AI assistant skill for implementing tasks from an OpenSpec change using a spec-driven workflow | dep: openspec CLI, AskUserQuestion tool, filesystem access
+## arch
+Template-based skill definition using markdown documentation with structured workflow phases (planning, validation, execution) and integration points for external tools (OpenSpec CLI, OpenCode agent).
+## tags
+skill, defines, assistant, implementing, tasks, openspec, change, spec
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-archive-change/.pi-map.index.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-archive-change (index)
+dir: .opencode/skills/openspec-archive-change
+
+## role
+Provides a reusable automation skill for archiving completed experimental changes via the openspec CLI
+## parent
+index: .opencode/skills/.pi-map.index.md
+map: .opencode/skills/.pi-map.md
+## children
+-
+## files
+- SKILL.md
+## links
+index: .opencode/skills/openspec-archive-change/.pi-map.index.md
+map: .opencode/skills/openspec-archive-change/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-archive-change/.pi-map.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-archive-change
+dir: .opencode/skills/openspec-archive-change
+
+index: .opencode/skills/openspec-archive-change/.pi-map.index.md
+
+## role
+Provides a reusable automation skill for archiving completed experimental changes via the openspec CLI
+## files
+- SKILL.md | Defines a skill for archiving completed changes in an experimental workflow using the openspec CLI. | dep: openspec CLI, AskUserQuestion tool, Task tool, file system (mkdir, mv, read), JSON parsing
+## arch
+Skill-based modular automation pattern using markdown-defined CLI operations with structured metadata and command templates
+## tags
+skill, defines, archiving, completed, changes, experimental, workflow, openspec
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-explore/.pi-map.index.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-explore (index)
+dir: .opencode/skills/openspec-explore
+
+## role
+Defines a conversational AI skill/persona for "explore mode" that serves as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code.
+## parent
+index: .opencode/skills/.pi-map.index.md
+map: .opencode/skills/.pi-map.md
+## children
+-
+## files
+- SKILL.md
+## links
+index: .opencode/skills/openspec-explore/.pi-map.index.md
+map: .opencode/skills/openspec-explore/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-explore/.pi-map.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-explore
+dir: .opencode/skills/openspec-explore
+
+index: .opencode/skills/openspec-explore/.pi-map.index.md
+
+## role
+Defines a conversational AI skill/persona for "explore mode" that serves as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code.
+## files
+- SKILL.md | Defines a conversational AI skill/persona for "explore mode" - a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code. | dep: openspec CLI
+## arch
+Single-file skill definition using markdown-based persona specification with structured sections for description, usage guidelines, and behavioral constraints.
+## tags
+skill, defines, conversational, persona, explore, mode, thinking, partner
+## symbols
+-
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-propose/.pi-map.index.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-propose (index)
+dir: .opencode/skills/openspec-propose
+
+## role
+Provides a structured workflow skill for proposing new changes using the openspec CLI with artifact generation in dependency order.
+## parent
+index: .opencode/skills/.pi-map.index.md
+map: .opencode/skills/.pi-map.md
+## children
+-
+## files
+- SKILL.md
+## links
+index: .opencode/skills/openspec-propose/.pi-map.index.md
+map: .opencode/skills/openspec-propose/.pi-map.md
+## workflows
+-
+## dirty
+-

.opencode/skills/openspec-propose/.pi-map.md

@@ -0,0 +1,19 @@
+# .opencode/skills/openspec-propose
+dir: .opencode/skills/openspec-propose
+
+index: .opencode/skills/openspec-propose/.pi-map.index.md
+
+## role
+Provides a structured workflow skill for proposing new changes using the openspec CLI with artifact generation in dependency order.
+## files
+- SKILL.md | Defines a structured workflow for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order. | dep: openspec CLI, AskUserQuestion tool, TodoWrite tool
+## arch
+Template-based skill definition using markdown documentation with sequential artifact generation (proposal → design → tasks) following dependency ordering.
+## tags
+skill, defines, structured, workflow, proposing, new, changes, openspec
+## symbols
+-
+## workflows
+-
+## dirty
+-

.pi-map.index.md

@@ -0,0 +1,82 @@
+# . (index)
+dir: .
+
+## Project Map Protocol
+
+1. Read this protocol and the root `.pi-map.index.md` first.
+2. Use `index:` / `map:` references to open relevant directory indexes and maps.
+3. Load indexes before rich maps during task-start navigation.
+4. Read the local rich map and actual source before editing.
+5. Treat non-empty `## dirty` sections in either artifact as stale.
+6. If source and generated artifacts disagree, trust source.
+7. If map and index disagree, trust neither blindly; verify from source and regenerate the pair.
+8. After editing source, run `project_map_patch` for each changed file.
+9. Before broad architectural claims or final handoff, run `project_map_validate` when freshness matters.
+
+Trust boundary: index routes, map orients, source decides.
+
+## role
+Infrastructure and deployment configuration package for a self-hosted project management platform with OAuth2 authentication, providing containerized orchestration, environment templates, and development tooling.
+## parent
+-
+## children
+- .atl
+  index: .atl/.pi-map.index.md
+  map: .atl/.pi-map.md
+- .claude
+  index: .claude/.pi-map.index.md
+  map: .claude/.pi-map.md
+- .opencode
+  index: .opencode/.pi-map.index.md
+  map: .opencode/.pi-map.md
+- .pi
+  index: .pi/.pi-map.index.md
+  map: .pi/.pi-map.md
+- .sisyphus
+  index: .sisyphus/.pi-map.index.md
+  map: .sisyphus/.pi-map.md
+- .stoneforge
+  index: .stoneforge/.pi-map.index.md
+  map: .stoneforge/.pi-map.md
+- apps
+  index: apps/.pi-map.index.md
+  map: apps/.pi-map.md
+- docs
+  index: docs/.pi-map.index.md
+  map: docs/.pi-map.md
+- e2e
+  index: e2e/.pi-map.index.md
+  map: e2e/.pi-map.md
+- minerv3
+  index: minerv3/.pi-map.index.md
+  map: minerv3/.pi-map.md
+- openspec
+  index: openspec/.pi-map.index.md
+  map: openspec/.pi-map.md
+- scripts
+  index: scripts/.pi-map.index.md
+  map: scripts/.pi-map.md
+- tool-images
+  index: tool-images/.pi-map.index.md
+  map: tool-images/.pi-map.md
+- uploads
+  index: uploads/.pi-map.index.md
+  map: uploads/.pi-map.md
+## files
+- .env.example
+- .gitignore
+- AGENTS.md
+- CHANGELOG.md
+- Makefile
+- README.md
+- docker-compose.traefik.yml
+- docker-compose.yml
+- progress.md
+- swap-pane
+## links
+index: ./.pi-map.index.md
+map: ./.pi-map.md
+## workflows
+-
+## dirty
+-

.pi-map.md

@@ -0,0 +1,42 @@
+# .
+dir: .
+
+index: ./.pi-map.index.md
+
+## Project Map Protocol
+
+1. Read this protocol and the root `.pi-map.index.md` first.
+2. Use `index:` / `map:` references to open relevant directory indexes and maps.
+3. Load indexes before rich maps during task-start navigation.
+4. Read the local rich map and actual source before editing.
+5. Treat non-empty `## dirty` sections in either artifact as stale.
+6. If source and generated artifacts disagree, trust source.
+7. If map and index disagree, trust neither blindly; verify from source and regenerate the pair.
+8. After editing source, run `project_map_patch` for each changed file.
+9. Before broad architectural claims or final handoff, run `project_map_validate` when freshness matters.
+
+Trust boundary: index routes, map orients, source decides.
+
+## role
+Infrastructure and deployment configuration package for a self-hosted project management platform with OAuth2 authentication, providing containerized orchestration, environment templates, and development tooling.
+## files
+- .env.example | Provides a template of environment variables for configuring a Headquarter application with PostgreSQL, Redis, Authentik SSO, and Docker/Traefik deployment
+- .gitignore | Specifies files and directories for Git to ignore across a multi-language project with Python, Node, and custom tooling | dep: Git
+- AGENTS.md | Defines operational rules, workflows, and constraints for AI agents working within an OpenSpec-driven software development project. | dep: OpenSpec, superpowers, git, docker compose, conventional commits
+- CHANGELOG.md | Documents version history and notable changes for a Git-based project management web application
+- Makefile | Provides standard development commands for containerized web application lifecycle management via Docker Compose | dep: docker compose, alembic, pytest, ruff, mypy, playwright, npm, postgres, redis
+- README.md | A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication. | dep: FastAPI, SQLAlchemy, Pydantic, Alembic, python-jose, React, TypeScript, Vite, React Router, Docker, PostgreSQL, Traefik, Authentik, Git
+- docker-compose.traefik.yml | Deploys a multi-service web application (frontend, API, PostgreSQL, Redis) behind an existing Traefik reverse proxy with TLS termination and environment-configurable domains. | dep: docker, traefik, postgres, redis, authentik, docker-compose
+- docker-compose.yml | Defines a multi-service Docker Compose stack with PostgreSQL, Redis, API backend, and web frontend services for a "headquarter" application | dep: Docker, PostgreSQL, Redis, Vite, asyncpg, nginx
+- progress.md | Tracks completed and remaining tasks for a backend-frontend code refactoring project organized in 7 phases
+- swap-pane | Empty file with no functionality
+## arch
+Docker Compose-based microservices architecture with frontend/backend separation, PostgreSQL/Redis data layer, Traefik reverse proxy integration, and environment-driven configuration management following twelve-factor app principles.
+## tags
+docker, redis, git, application, postgresql, compose, traefik, project
+## symbols
+-
+## workflows
+-
+## dirty
+-

.stoneforge/.pi-map.index.md

@@ -0,0 +1,23 @@
+# .stoneforge (index)
+dir: .stoneforge
+
+## role
+Internal configuration and state tracking directory for the Stoneforge application
+## parent
+index: ./.pi-map.index.md
+map: ./.pi-map.md
+## children
+- .stoneforge/sync
+  index: .stoneforge/sync/.pi-map.index.md
+  map: .stoneforge/sync/.pi-map.md
+## files
+- .dashboard-opened
+- .gitignore
+- config.yaml
+## links
+index: .stoneforge/.pi-map.index.md
+map: .stoneforge/.pi-map.md
+## workflows
+-
+## dirty
+-

.stoneforge/.pi-map.md

@@ -0,0 +1,21 @@
+# .stoneforge
+dir: .stoneforge
+
+index: .stoneforge/.pi-map.index.md
+
+## role
+Internal configuration and state tracking directory for the Stoneforge application
+## files
+- .dashboard-opened | Stores timestamp and identifier data for tracking when a dashboard was opened
+- .gitignore | Specifies files and patterns for Git to ignore in version control
+- config.yaml | Configuration file for the Stoneforge application defining database, sync, playbook, identity, merge, workflow, and agent settings.
+## arch
+Simple dot-directory pattern storing metadata (.dashboard-opened), version control exclusions (.gitignore), and hierarchical YAML configuration (config.yaml) with domain-separated settings
+## tags
+config, stores, timestamp, identifier, data, tracking, dashboard, was
+## symbols
+-
+## workflows
+-
+## dirty
+-

.stoneforge/sync/.pi-map.index.md

@@ -0,0 +1,20 @@
+# .stoneforge/sync (index)
+dir: .stoneforge/sync
+
+## role
+Persists distributed task execution state by storing dependency graphs and ephemeral worker agent records for a collaborative workflow system.
+## parent
+index: .stoneforge/.pi-map.index.md
+map: .stoneforge/.pi-map.md
+## children
+-
+## files
+- dependencies.jsonl
+- elements.jsonl
+## links
+index: .stoneforge/sync/.pi-map.index.md
+map: .stoneforge/sync/.pi-map.md
+## workflows
+-
+## dirty
+-

.stoneforge/sync/.pi-map.md

@@ -0,0 +1,20 @@
+# .stoneforge/sync
+dir: .stoneforge/sync
+
+index: .stoneforge/sync/.pi-map.index.md
+
+## role
+Persists distributed task execution state by storing dependency graphs and ephemeral worker agent records for a collaborative workflow system.
+## files
+- dependencies.jsonl | Stores a sequence of dependency relationships between entities in JSON Lines format, tracking parent-child, blocking, and reply relationships with timestamps and creators.
+- elements.jsonl | Stores JSONL records of ephemeral worker agents with their session history, worktree assignments, and lifecycle metadata for a distributed task execution system.
+## arch
+Event-sourced JSONL append-only logs with entity-relationship modeling (parent-child, blocking, reply) and session-based worker lifecycle tracking.
+## tags
+stores, relationships, dependencies, elements, sequence, dependency, entities, json
+## symbols
+-
+## workflows
+-
+## dirty
+-

AGENTS.md

@@ -90,13 +90,6 @@ Before completion, report:
 
 Do not claim completion without verification evidence.
 
-## Git branch policy
-
-- **Default working branch:** `dev` — all commits and pushes target `dev` unless the user explicitly requests otherwise.
-- `main` is the stable/production branch; merge to `main` only when explicitly instructed.
-- After committing, push to `origin/dev`.
-- If `dev` does not exist locally, create it from `main` or fetch it from origin.
-
 ## Git workflow
 
 ### Branching strategy

CHANGELOG.md

@@ -21,7 +21,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **User Settings** - Theme selection, git identity, and preference management
 - **SSH Key Management** - Ed25519 key generation with secure storage
 - **Tool Types** - Built-in development tools (code-server, jupyter-notebook) with custom type support
-- **Config Profiles** - User-owned profile CRUD with includes, mounts, path validation, cycle detection, and default profile selection
 - **Comprehensive Documentation** - Architecture, API, deployment, and development guides
 
 ### Changed

apps/.pi-map.index.md

@@ -0,0 +1,23 @@
+# apps (index)
+dir: apps
+
+## role
+Contains the main deployable application modules or entry points for the project.
+## parent
+index: ./.pi-map.index.md
+map: ./.pi-map.md
+## children
+- apps/api
+  index: apps/api/.pi-map.index.md
+  map: apps/api/.pi-map.md
+- apps/web
+  index: apps/web/.pi-map.index.md
+  map: apps/web/.pi-map.md
+## files
+## links
+index: apps/.pi-map.index.md
+map: apps/.pi-map.md
+## workflows
+-
+## dirty
+-

apps/.pi-map.md

@@ -0,0 +1,18 @@
+# apps
+dir: apps
+
+index: apps/.pi-map.index.md
+
+## role
+Contains the main deployable application modules or entry points for the project.
+## files
+## arch
+Modular monolith or microservices architecture with separate application boundaries, each potentially having its own configuration, dependencies, and lifecycle.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-

apps/api/.dockerignore

@@ -0,0 +1,42 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Local env files
+.env
+.env.local
+
+# Alembic cache
+alembic/versions/__pycache__/
+
+# Pi lens cache
+.pi-lens/
+
+# Documentation
+docs/
+*.md
+
+# Scripts not needed in container
+scripts/

apps/api/.pi-map.index.md

@@ -0,0 +1,45 @@
+# apps/api (index)
+dir: apps/api
+
+## role
+Self-hosted FastAPI backend API that manages projects, git repositories, and development tools via Docker instances.
+## parent
+index: apps/.pi-map.index.md
+map: apps/.pi-map.md
+## children
+- apps/api/.pi-lens
+  index: apps/api/.pi-lens/.pi-map.index.md
+  map: apps/api/.pi-lens/.pi-map.md
+- apps/api/.pytest_cache
+  index: apps/api/.pytest_cache/.pi-map.index.md
+  map: apps/api/.pytest_cache/.pi-map.md
+- apps/api/.venv-test
+  index: apps/api/.venv-test/.pi-map.index.md
+  map: apps/api/.venv-test/.pi-map.md
+- apps/api/alembic
+  index: apps/api/alembic/.pi-map.index.md
+  map: apps/api/alembic/.pi-map.md
+- apps/api/src
+  index: apps/api/src/.pi-map.index.md
+  map: apps/api/src/.pi-map.md
+- apps/api/tests
+  index: apps/api/tests/.pi-map.index.md
+  map: apps/api/tests/.pi-map.md
+- apps/api/uploads
+  index: apps/api/uploads/.pi-map.index.md
+  map: apps/api/uploads/.pi-map.md
+## files
+- .dockerignore
+- Dockerfile
+- README.md
+- alembic.ini
+- pyproject.toml
+- uv.lock
+- wait-for-db.sh
+## links
+index: apps/api/.pi-map.index.md
+map: apps/api/.pi-map.md
+## workflows
+-
+## dirty
+-

apps/api/.pi-map.md

@@ -0,0 +1,25 @@
+# apps/api
+dir: apps/api
+
+index: apps/api/.pi-map.index.md
+
+## role
+Self-hosted FastAPI backend API that manages projects, git repositories, and development tools via Docker instances.
+## files
+- .dockerignore | Specifies files and directories to exclude from Docker build context to reduce image size and avoid copying unnecessary files into containers. | dep: Docker
+- Dockerfile | Multi-stage Docker build for a Python application with Docker socket access, Cloudflare tunneling, and database dependency waiting | dep: python:3.11-slim, gcc, libpq-dev, docker-ce-cli, docker-compose-plugin, cloudflared, uvicorn, pyproject.toml dependencies
+- README.md | Documentation for a self-hosted FastAPI backend API that manages projects, git repositories, and development tools via Docker instances. | dep: FastAPI, SQLAlchemy, PostgreSQL, asyncpg, Alembic, Docker, Docker Compose, Authentik, uvicorn, pytest, ruff, mypy
+- alembic.ini | Configuration file for Alembic database migration tool connecting to a PostgreSQL database with async driver | dep: alembic, sqlalchemy, asyncpg, PostgreSQL
+- pyproject.toml | Defines Python project metadata, dependencies, and tool configurations for a FastAPI-based backend API called "headquarter-api" | dep: fastapi, uvicorn, sqlalchemy, asyncpg, alembic, pydantic, pydantic-settings, python-multipart, httpx, structlog, cryptography, pytest, pytest-asyncio, mypy, ruff, aiosqlite
+- uv.lock | Lock file for the uv Python package manager that pins exact dependency versions and their artifact hashes for reproducible installations | dep: uv, Python 3.11+, aiosqlite, alembic, annotated-doc, annotated-types, anyio, ast-serialize, asyncpg, and many other PyPI packages
+- wait-for-db.sh | Wait for a PostgreSQL database to become available before executing a command, with configurable retry logic. | dep: nc (netcat), sh (POSIX shell), sleep
+## arch
+Async Python/FastAPI with PostgreSQL (Alembic migrations), multi-stage Docker deployment with Cloudflare tunneling, uv package management, and containerized service orchestration.
+## tags
+docker, alembic, python, database, fastapi, postgresql, asyncpg, uvicorn
+## symbols
+-
+## workflows
+-
+## dirty
+-

apps/api/alembic/.pi-map.index.md

@@ -0,0 +1,25 @@
+# apps/api/alembic (index)
+dir: apps/api/alembic
+
+## role
+Database migration infrastructure for the API application, providing version-controlled schema evolution with async SQLAlchemy support.
+## parent
+index: apps/api/.pi-map.index.md
+map: apps/api/.pi-map.md
+## children
+- apps/api/alembic/versions
+  index: apps/api/alembic/versions/.pi-map.index.md
+  map: apps/api/alembic/versions/.pi-map.md
+## files
+- env.py
+- script.py.mako
+## links
+index: apps/api/alembic/.pi-map.index.md
+map: apps/api/alembic/.pi-map.md
+## workflows
+- change alembic behavior
+  read: env.py, script.py.mako
+- explore alembic subdirectories
+  index: apps/api/alembic/versions/.pi-map.index.md
+## dirty
+-

apps/api/alembic/.pi-map.md

@@ -0,0 +1,30 @@
+# apps/api/alembic
+dir: apps/api/alembic
+
+index: apps/api/alembic/.pi-map.index.md
+
+## role
+Database migration infrastructure for the API application, providing version-controlled schema evolution with async SQLAlchemy support.
+## files
+- env.py | Configures Alembic database migration environment with async SQLAlchemy support for a project. | exp: func:run_migrations_offline() → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:do_run_migrations(connection: Connection) → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:run_async_migrations() → None, call:async_engine_from_config, call:config.get_section, call:connectable.connect, call:connection.run_sync, call:connectable.dispose, func:run_migrations_online() → None, call:asyncio.run, call:run_async_migrations | dep: logging.config, alembic, sqlalchemy, sqlalchemy.engine, sqlalchemy.ext.asyncio, src.config, src.models, asyncio
+- script.py.mako | Alembic database migration script template that generates upgrade/downgrade functions for SQLAlchemy schema migrations | dep: alembic, sqlalchemy
+## arch
+Alembic migration framework with Mako templating for generating revision scripts, async SQLAlchemy engine configuration, and autogenerate capabilities for schema change tracking.
+## tags
+migrations, run, sqlalchemy, async, alembic, call:context.configure, call:context.begin, transaction
+## symbols
+- run_migrations_offline
+- do_run_migrations
+- run_async_migrations
+- run_migrations_online
+- call:context.configure
+- call:context.begin_transaction
+- call:context.run_migrations
+- call:async_engine_from_config
+## workflows
+- change alembic behavior
+  read: env.py, script.py.mako
+- explore alembic subdirectories
+  index: apps/api/alembic/versions/.pi-map.index.md
+## dirty
+-

apps/api/alembic/versions/.pi-map.index.md

@@ -0,0 +1,69 @@
+# apps/api/alembic/versions (index)
+dir: apps/api/alembic/versions
+
+## role
+Manages incremental database schema evolution for the API application using Alembic migrations, tracking all table creations, column additions, relationship changes, and data transformations over the project's lifecycle.
+## parent
+index: apps/api/alembic/.pi-map.index.md
+map: apps/api/alembic/.pi-map.md
+## children
+-
+## files
+- 0001_initial_schema.py
+- 0002_refresh_tokens.py
+- 0003_user_configs.py
+- 0004_tool_types.py
+- 0005_ssh_keys_timestamps.py
+- 0006_tool_instances.py
+- 0007_instance_container_name.py
+- 0008_tool_type_category.py
+- 0009_tool_configs.py
+- 0010_tool_type_default_port.py
+- 0011_tool_instance_tunnel_fields.py
+- 0012_default_port_req.py
+- 0013_add_config_profiles.py
+- 0013_add_probe_result.py
+- 0014_add_profile_resolver_fields.py
+- 0014_merge_heads.py
+- 0015_single_interface.py
+- 069d3da4dc9b_add_ssh_key_id_to_config_profiles.py
+- 20260527160017_add_pi_agent_tool_type.py
+- 2026_05_22_add_clone_mode.py
+- 2026_05_23_remove_is_builtin.py
+- 2026_05_24_220141_add_startup_command.py
+- 2026_05_24_add_config_profiles.py
+- 2026_05_26_add_git_mounts.py
+- 2026_05_27_external_repos.py
+- 2026_05_28_add_monitoring_tables.py
+- 2026_05_28_add_terminal_sessions_table.py
+- 2026_05_28_add_tool_definition_manifests.py
+- 2026_05_28_drop_tool_configs_and_config_folders.py
+- 2026_05_29_add_notifications_table.py
+- 2026_05_29_add_ssh_key_ids_to_tool_instances.py
+- 2026_05_29_drop_ssh_key_id_from_config_profiles.py
+- 2026_05_29_fix_code_server_bind_addr.py
+- 2026_05_29_fix_code_server_bind_addr_port.py
+- 2026_05_29_fix_web_tool_bind_address.py
+- 2026_05_29_remove_lsio_command_override.py
+- 2026_05_29_remove_ssh_keys_mount_from_manifest.py
+- 2026_06_01_add_workspaces.py
+- 2026_06_13_make_clone_mode_nullable.py
+- 398082499c30_add_tool_config_fields.py
+- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py
+- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py
+- 8c6d1dbd4798_remove_pi_config_and_state_mounts_from_.py
+- 8ed7dd80973d_create_config_folders_table.py
+- af8512103d67_add_tool_type_fields.py
+- f3d2dc90ba3a_merge_single_interface_and_clone_mode.py
+## links
+index: apps/api/alembic/versions/.pi-map.index.md
+map: apps/api/alembic/versions/.pi-map.md
+## workflows
+- change versions behavior
+  read: 0001_initial_schema.py, 0002_refresh_tokens.py, 0003_user_configs.py
+- change versions CLI
+  read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
+- change versions config
+  read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
+## dirty
+-

apps/api/alembic/versions/.pi-map.md

@@ -0,0 +1,76 @@
+# apps/api/alembic/versions
+dir: apps/api/alembic/versions
+
+index: apps/api/alembic/versions/.pi-map.index.md
+
+## role
+Manages incremental database schema evolution for the API application using Alembic migrations, tracking all table creations, column additions, relationship changes, and data transformations over the project's lifecycle.
+## files
+- 0001_initial_schema.py | Defines the initial database schema migration creating five tables (users, ssh_keys, projects, git_repositories, user_configs) with relationships, indexes, and constraints using Alembic. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.String, call:postgresql.UUID, call:sa.DateTime, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:op.f, call:sa.Text, call:sa.ForeignKeyConstraint, call:sa.Boolean, call:postgresql.JSONB, func:downgrade() → None, call:op.drop_table, call:op.drop_index, call:op.f | dep: alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
+- 0002_refresh_tokens.py | Alembic database migration that creates a refresh_tokens table with indexes for user authentication token management | exp: func:upgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:inspector.get_indexes, call:op.f, call:op.create_index, func:downgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:inspector.get_indexes, call:op.f, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0003_user_configs.py | Alembic database migration that creates a user_configs table with JSON configuration storage linked to users | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.JSON, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
+- 0004_tool_types.py | Alembic database migration that creates a tool_types table with metadata, templates, and versioning columns for a tool management system. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
+- 0005_ssh_keys_timestamps.py | Alembic database migration that adds created_at and updated_at timestamp columns to the ssh_keys table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.DateTime, call:sa.text, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0006_tool_instances.py | Alembic database migration that creates a tool_instances table with columns for tracking deployed tool instances, their status, container info, and foreign key relationships to tool_types, git_repositories, projects, and users. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Integer, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0007_instance_container_name.py | Alembic database migration that adds a nullable container_name column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0008_tool_type_category.py | Alembic database migration that adds `category` and `interfaces` columns to the `tool_types` table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0009_tool_configs.py | Alembic database migration that creates a tool_configs table with UUID keys, foreign key relationships, and indexes for storing user/project tool configuration settings. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
+- 0010_tool_type_default_port.py | Alembic database migration that adds a nullable default_port column to the tool_types table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0011_tool_instance_tunnel_fields.py | Alembic database migration that adds tunnel-related fields (public_url and tunnel_id) to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0012_default_port_req.py | Alembic database migration that populates null default_port values for existing tool types and then makes the column non-nullable | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.Integer, func:downgrade() → None, call:op.alter_column, call:sa.Integer | dep: typing, alembic, sqlalchemy
+- 0013_add_config_profiles.py | Alembic database migration that adds config profiles, includes, mounts tables and links tool instances to profiles with defensive idempotent checks | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:upgrade() → None, call:_table_exists, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:_index_exists, call:op.create_index, call:sa.Integer, call:_column_exists, call:op.add_column, call:_foreign_key_exists, call:op.create_foreign_key, func:downgrade() → None, call:op.drop_index, call:op.drop_constraint, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0013_add_probe_result.py | Alembic database migration that adds a JSON probe_result column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0014_add_profile_resolver_fields.py | Alembic database migration that adds profile resolver fields (project_id, tool_type_id, environment_variables, etc.) to config_profiles table and restructures config_mounts table (renaming mount_path to target_path, adding mode/files, removing content/source_profile_id). | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:_foreign_key_names_for_column(table_name: str, column_name: str) → list[str], call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, call:names.append, func:upgrade() → None, call:_column_exists, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.JSON, call:sa.Text, call:sa.Integer, call:sa.Boolean, call:_foreign_key_exists, call:op.create_foreign_key, call:_index_exists, call:op.create_index, call:op.alter_column, call:sa.String, call:_foreign_key_names_for_column, call:op.drop_constraint, call:op.drop_column, func:downgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.Text, call:op.drop_column, call:op.alter_column, call:op.drop_index, call:op.drop_constraint | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0014_merge_heads.py | Alembic merge migration that reconciles two divergent migration branches into a single history line | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
+- 0015_single_interface.py | Alembic database migration that replaces a JSON array `interfaces` column with `interface_type` string and `requires_port` boolean columns in the `tool_types` table, with dialect-specific data migration for PostgreSQL and SQLite. | exp: func:_get_dialect() → str, call:op.get_bind, func:upgrade() → None, call:_get_dialect, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Boolean, call:op.execute, call:op.alter_column, call:op.drop_column, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:_get_dialect, call:op.drop_constraint, call:op.add_column, call:sa.Column, call:postgresql.JSONB, call:sa.Text, call:op.execute, call:sa.JSON, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, postgresql (dialect)
+- 069d3da4dc9b_add_ssh_key_id_to_config_profiles.py | Alembic database migration that adds a nullable UUID foreign key column `ssh_key_id` to the `config_profiles` table referencing `ssh_keys.id` with SET NULL on delete | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Uuid, call:sa.ForeignKey, func:downgrade() → None, call:op.drop_column | dep: alembic, sqlalchemy
+- 20260527160017_add_pi_agent_tool_type.py | Alembic database migration that adds a "pi-agent" terminal-based coding tool type to a tool_types table with Docker configuration templates | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text("SELECT id FROM tool_types WHERE name = 'pi-agent'") ).fetchone, call:sa.text, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text | dep: json, typing, alembic, uuid, sqlalchemy
+- 2026_05_22_add_clone_mode.py | Alembic database migration that adds ssh_key_id foreign key to git_repositories table and clone_mode/branch columns to tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:op.create_foreign_key, call:sa.String, func:downgrade() → None, call:op.drop_column, call:op.drop_constraint | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 2026_05_23_remove_is_builtin.py | Alembic database migration to remove the `is_builtin` column from the `tool_types` table | exp: func:upgrade() → None, call:op.execute, func:downgrade() → None, call:op.add_column, call:sa.Column, call:sa.Boolean | dep: alembic, sqlalchemy
+- 2026_05_24_220141_add_startup_command.py | Alembic database migration that adds a nullable `startup_command` text column to the `tool_types` table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Text, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 2026_05_24_add_config_profiles.py | Alembic database migration that creates config_profiles and config_profile_includes tables with indexes, and adds a foreign key column to tool_instances for managing user configuration profiles. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:sa.Integer, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
+- 2026_05_26_add_git_mounts.py | Alembic database migration that adds a git_mounts JSON column to the config_profiles table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 2026_05_27_external_repos.py | Alembic database migration that makes project_id nullable in git_repositories table to support external repositories and expands alembic_version version_num column to 64 characters. | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.UUID, func:downgrade() → None, call:op.alter_column, call:sa.UUID, call:op.execute | dep: typing, alembic, sqlalchemy
+- 2026_05_28_add_monitoring_tables.py | Alembic database migration that creates monitoring tables (instance_events and health_checks) with indexes for tracking tool instance events and health checks | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.Boolean, call:sa.Integer, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_05_28_add_terminal_sessions_table.py | Alembic database migration that creates a terminal_sessions table with tracking columns and foreign key to tool_instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:op.f, func:downgrade() → None, call:op.drop_index, call:op.f, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_05_28_add_tool_definition_manifests.py | Alembic database migration that creates a tool_definition_manifests table, adds manifest-related columns to tool_types and tool_instances, and migrates the pi-agent tool from Dockerfile-based to manifest-based definitions with seed data. | exp: func:upgrade() → None, call:op.get_bind, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:sa.ForeignKeyConstraint, call:sa.CheckConstraint, call:conn.execute, call:sa.text, call:result.fetchone, call:op.add_column, call:op.create_foreign_key, call:op.drop_constraint, call:op.execute, call:json.dumps, call:str, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_column, call:op.drop_constraint, call:op.drop_table | dep: json, uuid, typing, alembic, sqlalchemy
+- 2026_05_28_drop_tool_configs_and_config_folders.py | Alembic database migration that drops `tool_configs` and `config_folders` tables with conditional existence checks and full downgrade recreation | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_table, func:downgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.Integer | dep: typing, alembic, sqlalchemy
+- 2026_05_29_add_notifications_table.py | Alembic database migration that creates a notifications table with user-linked, categorized, severity-graded messages supporting read/dismissed tracking and optimized querying indexes. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.text, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_05_29_add_ssh_key_ids_to_tool_instances.py | Alembic database migration that adds a JSON column named ssh_key_ids to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: alembic, sqlalchemy
+- 2026_05_29_drop_ssh_key_id_from_config_profiles.py | Alembic database migration that removes the ssh_key_id column from the config_profiles table | exp: func:upgrade() → None, call:op.drop_column, func:downgrade() → None, call:op.add_column, call:sa.Column, call:sa.Uuid, call:sa.ForeignKey | dep: alembic, sqlalchemy
+- 2026_05_29_fix_code_server_bind_addr.py | Alembic database migration that fixes code-server tool type compose templates by replacing deprecated `--bind-addr` flag with `--host` flag | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text(""" SELECT id, compose_template FROM tool_types WHERE name = 'code-server' AND compose_template LIKE '%--bind-addr%' """) ).fetchall, call:sa.text, call:compose_template.replace( "--bind-addr 0.0.0.0:8443", "--host 0.0.0.0" ).replace, call:print, func:downgrade() → None | dep: typing, alembic, sqlalchemy
+- 2026_05_29_fix_code_server_bind_addr_port.py | Alembic database migration that fixes code-server Docker compose templates and instance files by replacing broken `--host` flags with correct `--bind-addr 0.0.0.0:port` configurations | exp: func:_fix_tool_type_templates(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, default_port FROM tool_types WHERE name = 'code-server' AND compose_template LIKE '%--host%' """) ).fetchall, call:sa.text, call:compose_template.split, call:len, call:line.lstrip, call:new_lines.append, call:"\n".join, call:print, func:_fix_instance_compose_files(conn) → None, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:sa.text, call:print, call:conn.execute( sa.text(""" SELECT id, compose_path, tool_type_id FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:conn.execute( sa.text(""" SELECT default_port FROM tool_types WHERE id = :id """), {"id": tool_type_id}, ).fetchone, call:yaml.safe_load, call:data["services"].values, call:path.write_text, call:yaml.dump, func:upgrade() → None, call:op.get_bind, call:_fix_tool_type_templates, call:_fix_instance_compose_files, func:downgrade() → None | dep: typing, alembic, yaml, pathlib, sqlalchemy
+- 2026_05_29_fix_web_tool_bind_address.py | Alembic database migration that updates code-server and jupyter-notebook tool type compose templates to bind to 0.0.0.0 | exp: func:_fix_code_server_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'code-server' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:len, call:line.lstrip, call:new_lines.append, call:image_line.lstrip, call:new_lines.index, call:new_lines.insert, call:"\n".join, call:print, func:_fix_jupyter_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'jupyter-notebook' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:new_lines.append, call:len, call:line.lstrip, call:"\n".join, call:print, func:upgrade() → None, call:op.get_bind, call:_fix_code_server_compose, call:_fix_jupyter_compose, func:downgrade() → None | dep: typing, alembic, sqlalchemy
+- 2026_05_29_remove_lsio_command_override.py | Alembic database migration that removes broken command overrides containing --bind-addr or --host flags from LinuxServer.io code-server Docker Compose templates in both database tool_types records and on-disk instance compose files. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text(""" SELECT id, compose_template FROM tool_types WHERE name = 'code-server' """) ).fetchall, call:sa.text, call:yaml.safe_load, call:data["services"].values, call:svc.get, call:yaml.dump, call:print, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:conn.execute( sa.text(""" SELECT id, compose_path FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:path.write_text, func:downgrade() → None | dep: collections.abc, alembic, yaml, pathlib, sqlalchemy, pathlib.Path, information_schema
+- 2026_05_29_remove_ssh_keys_mount_from_manifest.py | Alembic database migration that removes (or restores) the ssh_keys mount from a JSON manifest stored in the tool_definition_manifests table for the pi-agent tool definition. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:any, call:m.get, call:mounts.append, call:json.dumps | dep: json, typing, alembic, sqlalchemy
+- 2026_06_01_add_workspaces.py | Alembic database migration that creates a workspaces table with foreign keys to git_repositories and users, adds indexes, and adds a workspace_id column to tool_instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, call:sa.UniqueConstraint, call:op.create_index, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_06_13_make_clone_mode_nullable.py | Alembic database migration that makes the `clone_mode` column in `tool_instances` table nullable to allow NULL values for new rows | exp: func:upgrade() → None, call:op.alter_column, call:sa.String, func:downgrade() → None, call:op.alter_column, call:sa.String | dep: alembic, sqlalchemy
+- 398082499c30_add_tool_config_fields.py | Alembic database migration that adds five new columns (port_override, start_command, working_directory, environment_variables, volumes) to the tool_configs table with a port range check constraint. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py | Alembic database migration that merges two parallel revision branches (removing is_builtin and adding config_profiles) into a single history line | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
+- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py | Alembic database migration that merges two divergent migration branches (profile resolver and workspaces) into a single head | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
+- 8c6d1dbd4798_remove_pi_config_and_state_mounts_from_.py | Alembic database migration that removes pi_state and pi_config mounts from the pi-agent manifest in upgrade, and restores them in downgrade | exp: func:_load_manifest(manifest_json), call:isinstance, call:json.loads, func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:m.get, call:mounts.append, call:json.dumps | dep: json, alembic, sqlalchemy
+- 8ed7dd80973d_create_config_folders_table.py | Alembic database migration that creates a config_folders table with user-owned configuration folders supporting JSONB file storage and project overrides | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.UniqueConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- af8512103d67_add_tool_type_fields.py | Alembic database migration that adds new columns (definition_type, dockerfile_template, build_context, readiness_probe) to the tool_types table with a CHECK constraint on definition_type. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- f3d2dc90ba3a_merge_single_interface_and_clone_mode.py | Alembic database migration that merges two prior revisions (single_interface and clone_mode) into a single migration path | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
+## arch
+Linear and branched migration pattern using Alembic's revision system with merge migrations to reconcile divergent branches; each migration is an imperative upgrade/downgrade script containing raw SQL/DDL operations, with some migrations including data seeding and dialect-specific logic (PostgreSQL/SQLite), but lacks consistent naming convention (mixed timestamp and numeric prefixes) indicating organic evolution rather than planned schema design.
+## tags
+column, table, call:op.drop, downgrade, alembic, upgrade, key, call:sa.text
+## symbols
+- upgrade
+- downgrade
+- _table_exists
+- _column_exists
+- _index_exists
+- _foreign_key_exists
+- _foreign_key_names_for_column
+- _get_dialect
+## workflows
+- change versions behavior
+  read: 0001_initial_schema.py, 0002_refresh_tokens.py, 0003_user_configs.py
+- change versions CLI
+  read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
+- change versions config
+  read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
+## dirty
+-

apps/api/alembic/versions/2026_05_28_add_tool_definition_manifests.py

@@ -232,20 +232,6 @@ def upgrade() -> None:
                             "writable": True,
                             "owner": "user",
                         },
-                        {
-                            "name": "pi_state",
-                            "target": "/tmp/.pi/agents",
-                            "source_type": "instance",
-                            "writable": True,
-                        },
-                        {
-                            "name": "pi_config",
-                            "target": "/home/user/.pi",
-                            "source_type": "git_mount",
-                            "git_mount_ref": "dotfiles",
-                            "writable": True,
-                            "owner": "user",
-                        },
                     ],
                     "runtime": {
                         "command": ["/bin/bash"],

apps/api/alembic/versions/2026_06_13_make_clone_mode_nullable.py

@@ -0,0 +1,35 @@
+"""make clone_mode nullable
+
+Revision ID: 2026_06_13_make_clone_mode_nullable
+Revises: 86cec91fdb00
+Create Date: 2026-06-13 10:00:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "2026_06_13_make_clone_mode_nullable"
+down_revision = "86cec91fdb00"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # The workspace-first cleanup no longer writes clone_mode; existing rows
+    # keep their value, but new rows may be NULL.
+    op.alter_column(
+        "tool_instances",
+        "clone_mode",
+        existing_type=sa.String(20),
+        nullable=True,
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        "tool_instances",
+        "clone_mode",
+        existing_type=sa.String(20),
+        nullable=False,
+    )

apps/api/alembic/versions/8c6d1dbd4798_remove_pi_config_and_state_mounts_from_.py

@@ -0,0 +1,112 @@
+"""remove pi config and state mounts from pi-agent manifest
+
+Revision ID: 8c6d1dbd4798
+Revises: 2026_06_13_make_clone_mode_nullable
+Create Date: 2026-06-13 11:21:25.983178
+"""
+
+import json
+
+from alembic import op
+import sqlalchemy as sa
+
+
+
+# revision identifiers, used by Alembic.
+revision = '8c6d1dbd4798'
+down_revision = '2026_06_13_make_clone_mode_nullable'
+branch_labels = None
+depends_on = None
+
+
+def _load_manifest(manifest_json):
+    return manifest_json if isinstance(manifest_json, dict) else json.loads(manifest_json)
+
+
+def upgrade() -> None:
+    """Remove pi_state and pi_config mounts from the pi-agent manifest."""
+    conn = op.get_bind()
+
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = _load_manifest(manifest_json)
+
+    mounts = manifest.get("mounts", [])
+    original_count = len(mounts)
+
+    filtered_mounts = [
+        m for m in mounts if m.get("name") not in ("pi_state", "pi_config")
+    ]
+
+    if len(filtered_mounts) < original_count:
+        manifest["mounts"] = filtered_mounts
+        conn.execute(
+            sa.text(
+                "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+            ),
+            {
+                "manifest": json.dumps(manifest),
+                "id": manifest_id,
+            },
+        )
+
+
+def downgrade() -> None:
+    """Restore pi_state and pi_config mounts to the pi-agent manifest."""
+    conn = op.get_bind()
+
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = _load_manifest(manifest_json)
+
+    mounts = manifest.get("mounts", [])
+    existing_names = {m.get("name") for m in mounts}
+
+    if "pi_state" not in existing_names:
+        mounts.append(
+            {
+                "name": "pi_state",
+                "target": "/tmp/.pi/agents",
+                "source_type": "instance",
+                "writable": True,
+            }
+        )
+
+    if "pi_config" not in existing_names:
+        mounts.append(
+            {
+                "name": "pi_config",
+                "target": "/home/user/.pi",
+                "source_type": "git_mount",
+                "git_mount_ref": "dotfiles",
+                "writable": True,
+                "owner": "user",
+            }
+        )
+
+    manifest["mounts"] = mounts
+    conn.execute(
+        sa.text(
+            "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+        ),
+        {
+            "manifest": json.dumps(manifest),
+            "id": manifest_id,
+        },
+    )

apps/api/src/.pi-map.index.md

@@ -0,0 +1,54 @@
+# apps/api/src (index)
+dir: apps/api/src
+
+## role
+Core API application package that initializes and configures the Headquarter FastAPI backend with database, authentication, logging, and middleware infrastructure.
+## parent
+index: apps/api/.pi-map.index.md
+map: apps/api/.pi-map.md
+## children
+- apps/api/src/api
+  index: apps/api/src/api/.pi-map.index.md
+  map: apps/api/src/api/.pi-map.md
+- apps/api/src/auth
+  index: apps/api/src/auth/.pi-map.index.md
+  map: apps/api/src/auth/.pi-map.md
+- apps/api/src/headquarter_api.egg-info
+  index: apps/api/src/headquarter_api.egg-info/.pi-map.index.md
+  map: apps/api/src/headquarter_api.egg-info/.pi-map.md
+- apps/api/src/models
+  index: apps/api/src/models/.pi-map.index.md
+  map: apps/api/src/models/.pi-map.md
+- apps/api/src/schemas
+  index: apps/api/src/schemas/.pi-map.index.md
+  map: apps/api/src/schemas/.pi-map.md
+- apps/api/src/scripts
+  index: apps/api/src/scripts/.pi-map.index.md
+  map: apps/api/src/scripts/.pi-map.md
+- apps/api/src/seeds
+  index: apps/api/src/seeds/.pi-map.index.md
+  map: apps/api/src/seeds/.pi-map.md
+- apps/api/src/services
+  index: apps/api/src/services/.pi-map.index.md
+  map: apps/api/src/services/.pi-map.md
+- apps/api/src/utils
+  index: apps/api/src/utils/.pi-map.index.md
+  map: apps/api/src/utils/.pi-map.md
+## files
+- __init__.py
+- config.py
+- database.py
+- logging_config.py
+- main.py
+## links
+index: apps/api/src/.pi-map.index.md
+map: apps/api/src/.pi-map.md
+## workflows
+- change src behavior
+  read: __init__.py, config.py, database.py
+- change src config
+  read: config.py, logging_config.py
+- explore src subdirectories
+  index: apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md, apps/api/src/headquarter_api.egg-info/.pi-map.index.md
+## dirty
+-

apps/api/src/.pi-map.md

@@ -0,0 +1,35 @@
+# apps/api/src
+dir: apps/api/src
+
+index: apps/api/src/.pi-map.index.md
+
+## role
+Core API application package that initializes and configures the Headquarter FastAPI backend with database, authentication, logging, and middleware infrastructure.
+## files
+- __init__.py | Marks the directory as a Python package for the Headquarter API.
+- config.py | Defines application configuration settings with environment-based overrides using Pydantic, including database URLs, service domains, OAuth/Authentik integration, JWT/session settings, and computed properties for environment-specific behavior. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings
+- database.py | Sets up async SQLAlchemy database engine and session factory, with retry logic for database connectivity testing and Alembic migration execution via subprocess. | exp: func:init_database(max_retries, retry_delay) → bool, call:range, call:engine.connect, call:test_conn.execute, call:text, call:test_conn.close, call:logger.info, call:asyncio.get_event_loop().run_in_executor, call:subprocess.run, call:os.path.dirname, call:os.path.abspath, call:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, os, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy
+- logging_config.py | Configures structured JSON logging with correlation ID injection, custom formatters, and HTTP request/exception middleware for a FastAPI application. | exp: class:CorrelationIdFilter, method:filter(self, record: logging.LogRecord) → bool, call:get_correlation_id, class:JSONFormatter, method:format(self, record: logging.LogRecord) → str, call:self.formatTime, call:record.getMessage, call:getattr, call:self.formatException, call:json.dumps, method:formatTime(self, record: logging.LogRecord, datefmt) → str, call:time.strftime, call:time.gmtime, class:RequestLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:time.time, call:logger.info, call:call_next, call:int, call:logger.error, call:type, call:traceback.format_exc, class:ExceptionLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:call_next, call:logger.critical, call:traceback.format_exc, func:configure_logging(level) → None, call:JSONFormatter, call:logging.StreamHandler, call:console_handler.setFormatter, call:console_handler.addFilter, call:CorrelationIdFilter, call:root_logger.setLevel, call:logging.getLogger("uvicorn").setLevel, call:logging.getLogger("uvicorn.access").setLevel, call:logging.getLogger("sqlalchemy.engine").setLevel, call:logger.info, call:logging.getLevelName | dep: json, logging, sys, time, traceback, collections.abc, fastapi, starlette.middleware.base, src.services.shared.correlation
+- main.py | Initializes and configures a FastAPI application for the "Headquarter API" with database setup, middleware, routing, and background services. | exp: func:_sanitize_validation_errors(errors), call:error.get, call:str, call:ctx.items, call:isinstance, call:type, call:sanitized.append, func:validation_exception_handler(request: Request, exc: RequestValidationError), call:exc.errors, call:logger.warning, call:_sanitize_validation_errors, call:JSONResponse, func:on_startup(), call:logger.info, call:init_database, call:logger.error, call:sys.exit, call:_health_monitor.start, call:seed_builtin_tool_types, func:on_shutdown(), call:logger.info, call:_health_monitor.stop | dep: logging, os, fastapi, fastapi.exceptions, fastapi.middleware.cors, fastapi.responses, fastapi.staticfiles, src.api.config, src.api.project, src.api.system, src.api.tool, src.api.user, src.api.workspace, src.config, src.models, src.database, src.logging_config, src.seeds.builtin_tool_types, src.services.instance, src.services.shared, sys, src.api.*
+## arch
+Layered architecture using Pydantic for environment-based configuration, async SQLAlchemy with Alembic migrations, structured JSON logging with correlation IDs, and FastAPI middleware/routing pattern for a service-oriented backend.
+## tags
+src, database, logging, call:logger.info, api, middleware, fastapi, filter
+## symbols
+- Settings
+- CorrelationIdFilter
+- JSONFormatter
+- RequestLoggingMiddleware
+- ExceptionLoggingMiddleware
+- build_database_url
+- init_database
+- filter
+## workflows
+- change src behavior
+  read: __init__.py, config.py, database.py
+- change src config
+  read: config.py, logging_config.py
+- explore src subdirectories
+  index: apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md, apps/api/src/headquarter_api.egg-info/.pi-map.index.md
+## dirty
+-

apps/api/src/api/.pi-map.index.md

@@ -0,0 +1,40 @@
+# apps/api/src/api (index)
+dir: apps/api/src/api
+
+## role
+Defines shared API infrastructure including reusable Pydantic validators for consistent input validation across API endpoints.
+## parent
+index: apps/api/src/.pi-map.index.md
+map: apps/api/src/.pi-map.md
+## children
+- apps/api/src/api/config
+  index: apps/api/src/api/config/.pi-map.index.md
+  map: apps/api/src/api/config/.pi-map.md
+- apps/api/src/api/project
+  index: apps/api/src/api/project/.pi-map.index.md
+  map: apps/api/src/api/project/.pi-map.md
+- apps/api/src/api/system
+  index: apps/api/src/api/system/.pi-map.index.md
+  map: apps/api/src/api/system/.pi-map.md
+- apps/api/src/api/tool
+  index: apps/api/src/api/tool/.pi-map.index.md
+  map: apps/api/src/api/tool/.pi-map.md
+- apps/api/src/api/user
+  index: apps/api/src/api/user/.pi-map.index.md
+  map: apps/api/src/api/user/.pi-map.md
+- apps/api/src/api/workspace
+  index: apps/api/src/api/workspace/.pi-map.index.md
+  map: apps/api/src/api/workspace/.pi-map.md
+## files
+- __init__.py
+- shared_validators.py
+## links
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## workflows
+- change api behavior
+  read: __init__.py, shared_validators.py
+- explore api subdirectories
+  index: apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md, apps/api/src/api/system/.pi-map.index.md
+## dirty
+-

apps/api/src/api/.pi-map.md

@@ -0,0 +1,30 @@
+# apps/api/src/api
+dir: apps/api/src/api
+
+index: apps/api/src/api/.pi-map.index.md
+
+## role
+Defines shared API infrastructure including reusable Pydantic validators for consistent input validation across API endpoints.
+## files
+- __init__.py | Marks the directory as a Python package for API routers.
+- shared_validators.py | Provides reusable Pydantic validator functions for API schema validation including mount paths, files, environment variables, and volume mounts. | exp: func:validate_mount_path(v: str | None) → str | None, call:v.startswith, raise:ValueError, func:validate_files(v: dict | None, max_size_bytes) → dict | None, call:v.items, call:path.startswith, call:len, call:content.encode, raise:ValueError, func:validate_env_vars(v: dict | None) → dict | None, call:isinstance, raise:ValueError, func:validate_volumes(v: list | None) → list | None, call:isinstance, call:enumerate, raise:ValueError
+## arch
+Modular utility package with functional validation helpers using Pydantic for declarative schema enforcement.
+## tags
+validate, raise:value, error, call:isinstance, mount, api, init, path
+## symbols
+- validate_mount_path
+- validate_files
+- validate_env_vars
+- validate_volumes
+- call:v.startswith
+- raise:ValueError
+- call:v.items
+- call:path.startswith
+## workflows
+- change api behavior
+  read: __init__.py, shared_validators.py
+- explore api subdirectories
+  index: apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md, apps/api/src/api/system/.pi-map.index.md
+## dirty
+-

apps/api/src/api/__init__.py

@@ -1,6 +1 @@
-from src.api.auth import router as auth_router
-from src.api.events import router as events_router
-from src.api.notifications import router as notifications_router
-from src.api.users import router as users_router
-
-__all__ = ["auth_router", "events_router", "notifications_router", "users_router"]
+"""API routers package."""

apps/api/src/api/config/.pi-map.index.md

@@ -0,0 +1,24 @@
+# apps/api/src/api/config (index)
+dir: apps/api/src/api/config
+
+## role
+Provides FastAPI API endpoints for managing user configuration settings and configuration profiles.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- config_profiles.py
+- user_config.py
+## links
+index: apps/api/src/api/config/.pi-map.index.md
+map: apps/api/src/api/config/.pi-map.md
+## workflows
+- change config behavior
+  read: __init__.py, config_profiles.py, user_config.py
+- change config config
+  read: config_profiles.py, user_config.py
+## dirty
+-

apps/api/src/api/config/.pi-map.md

@@ -0,0 +1,31 @@
+# apps/api/src/api/config
+dir: apps/api/src/api/config
+
+index: apps/api/src/api/config/.pi-map.index.md
+
+## role
+Provides FastAPI API endpoints for managing user configuration settings and configuration profiles.
+## files
+- __init__.py | Aggregates and exports configuration-related API routers for the config module. | dep: src.api.config.config_profiles, src.api.config.user_config
+- config_profiles.py | FastAPI router providing CRUD endpoints for user config profiles with includes, resolution, defaults, and git URL validation | exp: func:list_config_profiles(project_id, tool_type_id, current_user_id, session), call:select(ConfigProfile) .where(ConfigProfile.user_id == user_uuid) .options, call:selectinload, call:uuid.UUID, call:conditions.append, call:ConfigProfile.project_id.is_, call:ConfigProfile.tool_type_id.is_, call:query.where, call:or_, call:session.execute, call:result.scalars().all, call:profile_to_response, func:create_config_profile(data: ConfigProfileCreate, current_user_id, session), call:create_profile, call:logger.debug, call:profile_to_response, func:get_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:profile_to_response, raise:HTTPException, func:update_config_profile(profile_id: str, data: ConfigProfileUpdate, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:update_profile, call:logger.debug, call:profile_to_response, raise:HTTPException, func:delete_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:session.delete, call:session.commit, call:logger.debug, raise:HTTPException, func:update_profile_includes_endpoint(profile_id: str, data: ConfigProfileIncludeUpdate, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:update_includes, call:session.execute, call:select(ConfigProfileInclude).where, call:inc_result.scalars().all, call:logger.debug, call:profile_to_response, call:list, raise:HTTPException, func:preview_config_profile(profile_id: str, current_user_id, session), call:get_profile_with_includes, call:uuid.UUID, call:resolve_profile, call:resolved_profile_to_dict, raise:HTTPException, func:resolve_default_profile_endpoint(project_id, tool_type_id, current_user_id, session), call:resolve_default_profile, call:uuid.UUID, func:get_default_profiles_endpoint(user_id, session) → dict, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, func:set_default_profiles_endpoint(data: DefaultProfilesUpdate, user_id, session) → dict, call:validate_default_profiles, call:get_or_create_user_config, call:session.commit, call:session.refresh, func:get_default_profile_for_tool_type_endpoint(tool_type_id: str, user_id, session) → dict, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:user_config.default_profiles.get, func:validate_git_url_endpoint(data: ValidateGitUrlRequest, current_user_id, session) → ValidateGitUrlResponse, call:validate_git_url | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.auth.dependencies, src.models, src.schemas.config, src.services.config.config_profile_resolver, src.services.config.crud_service, src.services.config.resolver_service
+- user_config.py | Provides FastAPI endpoints to get and update the current user's configuration settings, creating a default config if none exists. | exp: func:_get_or_create_config(session: AsyncSession, user_id: uuid.UUID) → UserConfig, call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:UserConfig, call:session.add, call:session.commit, call:session.refresh, func:get_user_config(user_id, session) → UserConfigResponse, call:_get_user, call:_get_or_create_config, call:UserConfigResponse.model_validate, func:update_user_config(data: UserConfigUpdate, user_id, session) → UserConfigResponse, call:_get_user, call:_get_or_create_config, call:data.model_dump, call:logger.debug, call:session.commit, call:session.refresh, call:UserConfigResponse.model_validate | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.schemas.user
+## arch
+Modular FastAPI router pattern with separate route modules for distinct resource domains (user config vs config profiles), each implementing standard CRUD operations with validation and default initialization logic.
+## tags
+config, profile, get, user, includes, call:uuid.uuid, or, default
+## symbols
+- list_config_profiles
+- create_config_profile
+- get_config_profile
+- update_config_profile
+- delete_config_profile
+- update_profile_includes_endpoint
+- preview_config_profile
+- resolve_default_profile_endpoint
+## workflows
+- change config behavior
+  read: __init__.py, config_profiles.py, user_config.py
+- change config config
+  read: config_profiles.py, user_config.py
+## dirty
+-

apps/api/src/api/config/__init__.py

@@ -0,0 +1,6 @@
+"""Config API routers module."""
+
+from src.api.config.config_profiles import router as config_profiles_router
+from src.api.config.user_config import router as user_config_router
+
+__all__ = ["config_profiles_router", "user_config_router"]

apps/api/src/api/config/config_profiles.py

@@ -0,0 +1,300 @@
+"""Config profile API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models import ConfigProfile, ConfigProfileInclude, UserConfig
+from src.schemas.config import (
+    ConfigProfileCreate,
+    ConfigProfileIncludeUpdate,
+    ConfigProfileResponse,
+    ConfigProfileUpdate,
+    DefaultProfilesUpdate,
+    ValidateGitUrlRequest,
+    ValidateGitUrlResponse,
+)
+from src.services.config.config_profile_resolver import (
+    ConfigProfileCycleError,
+    resolve_profile,
+    resolved_profile_to_dict,
+)
+from src.services.config.crud_service import (
+    create_profile,
+    get_or_create_user_config,
+    get_profile_with_includes,
+    profile_to_response,
+    update_includes,
+    update_profile,
+    validate_default_profiles,
+)
+from src.services.config.resolver_service import (
+    resolve_default_profile,
+    validate_git_url,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
+
+
+@router.get("", response_model=list[ConfigProfileResponse])
+async def list_config_profiles(
+    project_id: str | None = Query(None, description="Filter by project compatibility"),
+    tool_type_id: str | None = Query(
+        None, description="Filter by tool type compatibility"
+    ),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """List config profiles, optionally filtered by compatibility."""
+    user_uuid = current_user_id
+    query = (
+        select(ConfigProfile)
+        .where(ConfigProfile.user_id == user_uuid)
+        .options(selectinload(ConfigProfile.includes))
+    )
+
+    if project_id or tool_type_id:
+        from sqlalchemy import or_
+
+        project_uuid = uuid.UUID(project_id) if project_id else None
+        tool_uuid = uuid.UUID(tool_type_id) if tool_type_id else None
+
+        conditions: list = []
+        conditions.append(
+            (ConfigProfile.project_id.is_(None))
+            & (ConfigProfile.tool_type_id.is_(None))
+        )
+        if project_uuid:
+            conditions.append(ConfigProfile.project_id == project_uuid)
+        if tool_uuid:
+            conditions.append(ConfigProfile.tool_type_id == tool_uuid)
+        if project_uuid and tool_uuid:
+            conditions.append(
+                (ConfigProfile.project_id == project_uuid)
+                & (ConfigProfile.tool_type_id == tool_uuid)
+            )
+
+        query = query.where(or_(*conditions))
+
+    result = await session.execute(query)
+    profiles = result.scalars().all()
+    return [profile_to_response(p) for p in profiles]
+
+
+@router.post(
+    "", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED
+)
+async def create_config_profile(
+    data: ConfigProfileCreate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Create a new config profile."""
+    profile = await create_profile(session, current_user_id, data)
+    logger.debug("Created config profile %s for user %s", profile.id, current_user_id)
+    return profile_to_response(profile)
+
+
+@router.get("/{profile_id}", response_model=ConfigProfileResponse)
+async def get_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Get a config profile by ID."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+    return profile_to_response(profile)
+
+
+@router.put("/{profile_id}", response_model=ConfigProfileResponse)
+async def update_config_profile(
+    profile_id: str,
+    data: ConfigProfileUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Update a config profile."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    profile = await update_profile(session, profile, data)
+    logger.debug("Updated config profile %s", profile.id)
+    return profile_to_response(profile)
+
+
+@router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Delete a config profile."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    await session.delete(profile)
+    await session.commit()
+
+    logger.debug("Deleted config profile %s", profile_id)
+    return None
+
+
+@router.put("/{profile_id}/includes", response_model=ConfigProfileResponse)
+async def update_profile_includes_endpoint(
+    profile_id: str,
+    data: ConfigProfileIncludeUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Update the ordered includes for a config profile."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    included_uuids = [uuid.UUID(inc_id) for inc_id in data.includes]
+    profile = await update_includes(session, profile, included_uuids, current_user_id)
+
+    inc_result = await session.execute(
+        select(ConfigProfileInclude).where(
+            ConfigProfileInclude.profile_id == profile.id
+        )
+    )
+    direct_includes = inc_result.scalars().all()
+
+    logger.debug("Updated includes for config profile %s", profile.id)
+    return profile_to_response(profile, list(direct_includes))
+
+
+@router.get("/{profile_id}/preview")
+async def preview_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Preview the resolved output of a config profile."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    try:
+        resolved = await resolve_profile(session, profile.id)
+    except ConfigProfileCycleError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+
+    return resolved_profile_to_dict(resolved)
+
+
+@router.get("/defaults/resolve")
+async def resolve_default_profile_endpoint(
+    project_id: str = Query(..., description="Project ID"),
+    tool_type_id: str = Query(..., description="Tool type ID"),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Resolve the default config profile for a project/tool combination."""
+    return await resolve_default_profile(
+        session,
+        current_user_id,
+        uuid.UUID(project_id),
+        uuid.UUID(tool_type_id),
+    )
+
+
+@router.get("/defaults")
+async def get_default_profiles_endpoint(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get all default profile mappings for the current user."""
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    user_config = result.scalar_one_or_none()
+    return {"default_profiles": user_config.default_profiles if user_config else {}}
+
+
+@router.put("/defaults")
+async def set_default_profiles_endpoint(
+    data: DefaultProfilesUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Set default profile mappings for the current user."""
+    await validate_default_profiles(session, user_id, data.default_profiles)
+    user_config = await get_or_create_user_config(session, user_id)
+    user_config.config = {
+        **user_config.config,
+        "default_profiles": data.default_profiles,
+    }
+    await session.commit()
+    await session.refresh(user_config)
+    return {"default_profiles": user_config.default_profiles}
+
+
+@router.get("/defaults/{tool_type_id}")
+async def get_default_profile_for_tool_type_endpoint(
+    tool_type_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get the default profile ID for a specific tool type."""
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    user_config = result.scalar_one_or_none()
+    profile_id = user_config.default_profiles.get(tool_type_id) if user_config else None
+    return {"tool_type_id": tool_type_id, "profile_id": profile_id}
+
+
+@router.post("/validate-git-url", response_model=ValidateGitUrlResponse)
+async def validate_git_url_endpoint(
+    data: ValidateGitUrlRequest,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ValidateGitUrlResponse:
+    """Validate a git remote URL and list available branches."""
+    return await validate_git_url(session, current_user_id, data.url, data.ssh_key_id)

apps/api/src/api/config/user_config.py

@@ -1,20 +1,22 @@
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
-from src.models.user import User
-from src.models.user_config import UserConfig
-from src.schemas.user_config import UserConfigResponse, UserConfigUpdate
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
+from src.models import UserConfig
+from src.schemas.user import UserConfigResponse, UserConfigUpdate
+
+logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/users/me", tags=["user-config"])
 
 
-
-async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> UserConfig:
+async def _get_or_create_config(
+    session: AsyncSession, user_id: uuid.UUID
+) -> UserConfig:
     """Get or create user config record.
 
     Args:
@@ -24,10 +26,12 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     Returns:
         The user's config, creating a new one if it doesn't exist.
     """
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user.id))
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
     config = result.scalar_one_or_none()
     if config is None:
-        config = UserConfig(user_id=user.id, config={})
+        config = UserConfig(user_id=user_id, config={})
         session.add(config)
         await session.commit()
         await session.refresh(config)
@@ -41,7 +45,7 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     description="Get the current user's configuration settings.",
 )
 async def get_user_config(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
     """Get the current user's configuration.
@@ -53,7 +57,8 @@ async def get_user_config(
     Returns:
         The user's configuration settings.
     """
-    config = await _get_or_create_config(session, user.id)
+    _user = await _get_user(session, user_id)
+    config = await _get_or_create_config(session, user_id)
     return UserConfigResponse.model_validate(config.config)
 
 
@@ -65,7 +70,7 @@ async def get_user_config(
 )
 async def update_user_config(
     data: UserConfigUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
     """Update the current user's configuration.
@@ -78,15 +83,16 @@ async def update_user_config(
     Returns:
         The updated user configuration.
     """
-    config = await _get_or_create_config(session, user.id)
+    _user = await _get_user(session, user_id)
+    config = await _get_or_create_config(session, user_id)
 
     # Merge updates
     update_data = data.model_dump(exclude_unset=True)
-    logger.info("Updating user config for user %s: %s", user.id, update_data)
+    logger.debug("Updating user config for user %s: %s", user_id, update_data)
     # SQLAlchemy JSON doesn't track dict mutations, so we replace the whole dict
     config.config = {**config.config, **update_data}
 
     await session.commit()
     await session.refresh(config)
-    logger.info("Updated config: %s", config.config)
+    logger.debug("Updated config: %s", config.config)
     return UserConfigResponse.model_validate(config.config)

apps/api/src/api/config_profiles.py

@@ -1,299 +0,0 @@
-"""Config profile API endpoints."""
-
-import logging
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import selectinload
-
-from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.config_include import ConfigInclude
-from src.models.config_mount import ConfigMount
-from src.models.config_profile import ConfigProfile
-from src.models.tool_type import ToolType
-from src.models.user_config import UserConfig
-from src.schemas.config_profile import (
-    ConfigIncludeCreate,
-    ConfigIncludeUpdate,
-    ConfigMountCreate,
-    ConfigMountUpdate,
-    ConfigProfileCreate,
-    ConfigProfileUpdate,
-    DefaultProfilesUpdate,
-)
-from src.services.config_profiles import (
-    check_duplicate_include,
-    check_duplicate_mount_path,
-    check_duplicate_name,
-    get_default_profile_for_tool_type,
-    get_default_profiles,
-    get_owned_profile,
-    include_to_dict,
-    list_includes_for_profile,
-    list_mounts_for_profile,
-    mount_to_dict,
-    profile_to_dict,
-    set_default_profiles,
-    validate_includes_no_cycle,
-)
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
-
-
-
-@router.get("")
-async def list_config_profiles(
-    tool_type_id: str | None = None,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    query = select(ConfigProfile).where(ConfigProfile.user_id == user_id)
-    if tool_type_id:
-        tool_type = await session.get(ToolType, uuid.UUID(tool_type_id))
-        if tool_type is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    result = await session.execute(query.order_by(ConfigProfile.name))
-    return {"profiles": [profile_to_dict(p) for p in result.scalars().all()]}
-
-
-@router.post("", status_code=status.HTTP_201_CREATED)
-async def create_config_profile(
-    data: ConfigProfileCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await check_duplicate_name(session, user_id, data.name)
-    profile = ConfigProfile(user_id=user_id, name=data.name, description=data.description)
-    session.add(profile)
-    await session.commit()
-    await session.refresh(profile)
-    return profile_to_dict(profile)
-
-
-@router.get("/defaults")
-async def get_default_profiles_endpoint(
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await get_default_profiles(session, user_id)
-
-
-@router.put("/defaults")
-async def set_default_profiles_endpoint(
-    data: DefaultProfilesUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await set_default_profiles(session, user_id, data.default_profiles)
-
-
-@router.get("/defaults/{tool_type_id}")
-async def get_default_profile_for_tool_type_endpoint(
-    tool_type_id: str,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await get_default_profile_for_tool_type(session, user_id, tool_type_id)
-
-
-@router.get("/{profile_id}")
-async def get_config_profile(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await session.get(
-        ConfigProfile,
-        profile_id,
-        options=[selectinload(ConfigProfile.includes), selectinload(ConfigProfile.mounts)],
-    )
-    if profile is None or profile.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config profile not found")
-    includes_data = []
-    for inc in profile.includes:
-        included_profile = await session.get(ConfigProfile, inc.included_profile_id)
-        includes_data.append(include_to_dict(inc, included_profile.name if included_profile else None))
-    return {
-        **profile_to_dict(profile),
-        "includes": includes_data,
-        "mounts": [mount_to_dict(m) for m in profile.mounts],
-    }
-
-
-@router.put("/{profile_id}")
-async def update_config_profile(
-    profile_id: uuid.UUID,
-    data: ConfigProfileUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    if data.name is not None:
-        await check_duplicate_name(session, user_id, data.name, exclude_id=profile_id)
-        profile.name = data.name
-    if data.description is not None:
-        profile.description = data.description
-    await session.commit()
-    await session.refresh(profile)
-    return profile_to_dict(profile)
-
-
-@router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def delete_config_profile(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    await session.delete(profile)
-    await session.commit()
-
-
-
-@router.get("/{profile_id}/includes")
-async def list_profile_includes(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    return await list_includes_for_profile(session, profile_id)
-
-
-@router.post("/{profile_id}/includes", status_code=status.HTTP_201_CREATED)
-async def add_profile_include(
-    profile_id: uuid.UUID,
-    data: ConfigIncludeCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    included_profile_id = uuid.UUID(data.included_profile_id)
-    if included_profile_id == profile_id:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="a profile cannot include itself")
-    included_profile = await session.get(ConfigProfile, included_profile_id)
-    if included_profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="included profile not found")
-    if included_profile.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="included profile does not belong to user")
-    await check_duplicate_include(session, profile_id, included_profile_id)
-    await validate_includes_no_cycle(session, profile_id, included_profile_id)
-    include = ConfigInclude(
-        profile_id=profile_id,
-        included_profile_id=included_profile_id,
-        order_index=data.order_index,
-    )
-    session.add(include)
-    await session.commit()
-    await session.refresh(include)
-    return include_to_dict(include, included_profile.name)
-
-
-@router.put("/{profile_id}/includes/{include_id}")
-async def update_profile_include(
-    profile_id: uuid.UUID,
-    include_id: uuid.UUID,
-    data: ConfigIncludeUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    include = await session.get(ConfigInclude, include_id)
-    if include is None or include.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="include not found")
-    include.order_index = data.order_index
-    await session.commit()
-    await session.refresh(include)
-    included_profile = await session.get(ConfigProfile, include.included_profile_id)
-    return include_to_dict(include, included_profile.name if included_profile else None)
-
-
-@router.delete("/{profile_id}/includes/{include_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_profile_include(
-    profile_id: uuid.UUID,
-    include_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    await get_owned_profile(profile_id, user_id, session)
-    include = await session.get(ConfigInclude, include_id)
-    if include is None or include.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="include not found")
-    await session.delete(include)
-    await session.commit()
-
-
-
-@router.get("/{profile_id}/mounts")
-async def list_profile_mounts(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    return await list_mounts_for_profile(session, profile_id)
-
-
-@router.post("/{profile_id}/mounts", status_code=status.HTTP_201_CREATED)
-async def add_profile_mount(
-    profile_id: uuid.UUID,
-    data: ConfigMountCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    await check_duplicate_mount_path(session, profile_id, data.target_path)
-    mount = ConfigMount(
-        profile_id=profile_id,
-        target_path=data.target_path,
-        mode=data.mode,
-        files=data.files,
-        order_index=data.order_index,
-    )
-    session.add(mount)
-    await session.commit()
-    await session.refresh(mount)
-    return mount_to_dict(mount)
-
-
-@router.put("/{profile_id}/mounts/{mount_id}")
-async def update_profile_mount(
-    profile_id: uuid.UUID,
-    mount_id: uuid.UUID,
-    data: ConfigMountUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    mount = await session.get(ConfigMount, mount_id)
-    if mount is None or mount.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="mount not found")
-    if data.target_path is not None:
-        await check_duplicate_mount_path(session, profile_id, data.target_path, exclude_id=mount_id)
-        mount.target_path = data.target_path
-    if data.files is not None:
-        mount.files = data.files
-    if data.order_index is not None:
-        mount.order_index = data.order_index
-    await session.commit()
-    await session.refresh(mount)
-    return mount_to_dict(mount)
-
-
-@router.delete("/{profile_id}/mounts/{mount_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_profile_mount(
-    profile_id: uuid.UUID,
-    mount_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    await get_owned_profile(profile_id, user_id, session)
-    mount = await session.get(ConfigMount, mount_id)
-    if mount is None or mount.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="mount not found")
-    await session.delete(mount)
-    await session.commit()

apps/api/src/api/git_repositories.py

@@ -1,290 +0,0 @@
-"""Git repository API endpoints."""
-
-import logging
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException, Response, status
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.auth.dependencies import get_current_user, get_db_session, get_owned_project
-from src.models.project import Project
-from src.models.user import User
-from src.schemas.git_repository import (
-    BranchCreateRequest,
-    CheckoutRequest,
-    CommitRequest,
-    CommitResponse,
-    FetchResponse,
-    FileContentResponse,
-    FileListResponse,
-    FileUpdateRequest,
-    FileUpdateResponse,
-    GitRepositoryCreate,
-    GitRepositoryResponse,
-    MergeRequest,
-    MergeResponse,
-    PullResponse,
-    PushResponse,
-    StatusResponse,
-    URLParseRequest,
-    URLParseResponse,
-)
-from src.services.git import control as git_control
-from src.services.git import files as git_files
-from src.services.git.repository import create_repository, delete_repository, list_repositories
-from src.utils.git_url_parser import parse_git_url
-
-router = APIRouter(prefix="/projects", tags=["git-repositories"])
-logger = logging.getLogger(__name__)
-
-
-@router.get("/{project_id}/repositories", response_model=list[GitRepositoryResponse])
-async def list_repositories_endpoint(
-    project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-):
-    return await list_repositories(session, project_id)
-
-
-@router.post("/{project_id}/repositories", response_model=GitRepositoryResponse, status_code=status.HTTP_201_CREATED)
-async def create_repository_endpoint(
-    project_id: uuid.UUID,
-    data: GitRepositoryCreate,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-):
-    return await create_repository(session, project_id, data, user)
-
-
-@router.delete("/{project_id}/repositories/{repo_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def delete_repository_endpoint(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-):
-    await delete_repository(session, repo_id, project_id)
-    return Response(status_code=status.HTTP_204_NO_CONTENT)
-
-
-@router.post("/repositories/parse-url", response_model=URLParseResponse)
-async def parse_repository_url(data: URLParseRequest) -> URLParseResponse:
-    return URLParseResponse(**parse_git_url(data.url))
-
-
-# History
-
-@router.get("/{project_id}/repositories/{repo_id}/history")
-async def get_repository_history(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    view: str = "graph",
-    branch: str | None = None,
-    limit: int = 100,
-    offset: int = 0,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    from src.utils.git_history import get_commit_history
-    from src.services.git.repository import get_repo_and_validate, ensure_repo_on_disk
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        return get_commit_history(repo.path, branch=branch, limit=limit, offset=offset)
-    except RuntimeError as e:
-        logger.warning("Git history failed for %s: %s", repo.path, str(e))
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Git history unavailable: {str(e)}",
-        ) from e
-
-
-@router.get("/{project_id}/repositories/{repo_id}/commits/{commit_hash}")
-async def get_repository_commit(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    commit_hash: str,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    from src.utils.git_history import get_commit_detail
-    from src.services.git.repository import get_repo_and_validate, ensure_repo_on_disk
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        return get_commit_detail(repo.path, commit_hash)
-    except RuntimeError as e:
-        logger.warning("Git commit detail failed for %s %s: %s", repo.path, commit_hash, str(e))
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Commit detail unavailable: {str(e)}",
-        ) from e
-
-
-# File browsing
-
-@router.get("/{project_id}/repositories/{repo_id}/files", response_model=FileListResponse)
-async def list_repository_files(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str = "main",
-    path: str = "",
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> FileListResponse:
-    return await git_files.list_files(session, project_id, repo_id, branch, path)
-
-
-@router.get("/{project_id}/repositories/{repo_id}/files/content", response_model=FileContentResponse)
-async def get_repository_file_content(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str,
-    path: str,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> FileContentResponse:
-    return await git_files.get_file(session, project_id, repo_id, branch, path)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/files/content", response_model=FileUpdateResponse)
-async def update_repository_file(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: FileUpdateRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> FileUpdateResponse:
-    return await git_files.update_file(session, project_id, repo_id, data, user)
-
-
-# Branches
-
-@router.get("/{project_id}/repositories/{repo_id}/branches")
-async def get_repository_branches(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await git_files.list_branches_with_validation(session, project_id, repo_id)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/branches")
-async def create_repository_branch(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: BranchCreateRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await git_control.create_branch_with_validation(session, project_id, repo_id, data)
-
-
-@router.delete("/{project_id}/repositories/{repo_id}/branches/{branch_name}")
-async def delete_repository_branch(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch_name: str,
-    force: bool = False,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await git_control.delete_branch_with_validation(session, project_id, repo_id, branch_name, force)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/checkout")
-async def checkout_repository_branch(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: CheckoutRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await git_control.checkout_branch_with_validation(session, project_id, repo_id, data)
-
-
-# Git control
-
-@router.get("/{project_id}/repositories/{repo_id}/status", response_model=StatusResponse)
-async def get_repository_status(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> StatusResponse:
-    return await git_control.get_status_with_validation(session, project_id, repo_id)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/commit", response_model=CommitResponse)
-async def commit_repository_changes(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: CommitRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> CommitResponse:
-    result = await git_control.commit_changes_with_validation(session, project_id, repo_id, data, user)
-    return CommitResponse(commit_hash=result["commit_hash"], message=result["message"])
-
-
-@router.post("/{project_id}/repositories/{repo_id}/fetch", response_model=FetchResponse)
-async def fetch_repository(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> FetchResponse:
-    return await git_control.fetch_with_validation(session, project_id, repo_id)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/pull", response_model=PullResponse)
-async def pull_repository(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str | None = None,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> PullResponse:
-    return await git_control.pull_with_validation(session, project_id, repo_id, branch)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/push", response_model=PushResponse)
-async def push_repository(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str | None = None,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> PushResponse:
-    return await git_control.push_with_validation(session, project_id, repo_id, branch)
-
-
-@router.post("/{project_id}/repositories/{repo_id}/merge", response_model=MergeResponse)
-async def merge_repository_branches(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: MergeRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> MergeResponse:
-    return await git_control.merge_with_validation(session, project_id, repo_id, data)

apps/api/src/api/project/.pi-map.index.md

@@ -0,0 +1,22 @@
+# apps/api/src/api/project (index)
+dir: apps/api/src/api/project
+
+## role
+Provides FastAPI REST API endpoints for project and Git repository management, serving as the HTTP interface layer for the project's core domain operations.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- git_repositories.py
+- projects.py
+## links
+index: apps/api/src/api/project/.pi-map.index.md
+map: apps/api/src/api/project/.pi-map.md
+## workflows
+- change project behavior
+  read: __init__.py, git_repositories.py, projects.py
+## dirty
+-

apps/api/src/api/project/__init__.py

@@ -0,0 +1,6 @@
+"""Project API routers module."""
+
+from src.api.project.git_repositories import router as git_repositories_router
+from src.api.project.projects import router as projects_router
+
+__all__ = ["git_repositories_router", "projects_router"]

apps/api/src/api/project/git_repositories.py

@@ -0,0 +1,500 @@
+import logging
+import os
+import shutil
+import uuid
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
+from src.models import GitRepository, SSHKey
+from src.schemas.project.git_repository import (
+    BranchCreateRequest,
+    BranchesResponse,
+    CheckoutRequest,
+    CommitRequest,
+    CommitResponse,
+    FetchResponse,
+    FileContentResponse,
+    FileListResponse,
+    FileUpdateRequest,
+    FileUpdateResponse,
+    GitRepositoryCreate,
+    GitRepositoryResponse,
+    MergeRequest,
+    MergeResponse,
+    PullResponse,
+    PushResponse,
+    StatusResponse,
+    UpdateSSHKeyRequest,
+    URLParseRequest,
+    URLParseResponse,
+)
+from src.services.git.operations import (
+    clone_working_repository,
+    get_repo_path,
+    init_working_repository,
+    list_remote_branches,
+    preflight_remote_repository,
+)
+from src.utils.git_control import (
+    checkout_branch,
+    commit_changes,
+    create_branch,
+    delete_branch,
+    fetch,
+    get_status,
+    merge,
+    pull,
+    push,
+)
+from src.utils.git_files import commit_file, get_file_content, list_branches, list_tree
+from src.utils.git_history import get_commit_detail, get_commit_history
+from src.utils.git_url_parser import parse_git_url
+
+router = APIRouter(prefix="/projects", tags=["git-repositories"])
+logger = logging.getLogger(__name__)
+
+
+async def _get_repo(
+    session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID
+) -> GitRepository:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    repo = await session.get(GitRepository, repo_id)
+    if repo is None or repo.project_id != project_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+    return repo
+
+
+async def _get_repo_on_disk(
+    session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, repo_id: uuid.UUID
+) -> GitRepository:
+    repo = await _get_repo(session, user_id, project_id, repo_id)
+    if not os.path.exists(repo.path):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+    return repo
+
+
+def _parse_remote_url(remote_url: str | None, force_original: bool) -> str | None:
+    if not remote_url or force_original:
+        return remote_url
+    parse_result = parse_git_url(remote_url)
+    if parse_result["needs_parsing"] and parse_result["base_url"]:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail={
+                "message": "The provided URL appears to be a browser URL, not a git clone URL",
+                "suggested_url": parse_result["base_url"],
+                "original_url": remote_url,
+                "error_code": "URL_NEEDS_PARSING",
+            },
+        )
+    return parse_result.get("base_url") or remote_url
+
+
+async def _commit_author(session: AsyncSession, user_id: uuid.UUID) -> tuple[str, str]:
+    user = await _get_user(session, user_id)
+    return user.name or "Unknown", user.email or "unknown@example.com"
+
+
+@router.get("/repositories", response_model=list[GitRepositoryResponse])
+async def list_user_repositories(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[GitRepository]:
+    """List all repositories owned by the user."""
+    result = await session.execute(select(GitRepository).where(GitRepository.owner_id == user_id))
+    return list(result.scalars().all())
+
+
+@router.post("/repositories/parse-url", response_model=URLParseResponse)
+async def parse_repository_url(data: URLParseRequest) -> URLParseResponse:
+    """Parse a git URL and detect if it's a browser URL that needs correction."""
+    return URLParseResponse(**parse_git_url(data.url))
+
+
+@router.post("/repositories", response_model=GitRepositoryResponse, status_code=status.HTTP_201_CREATED)
+async def create_external_repository(
+    data: GitRepositoryCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> GitRepository:
+    """Create a new external git repository (not tied to any project)."""
+    _user = await _get_user(session, user_id)
+    existing = await session.execute(
+        select(GitRepository).where(
+            GitRepository.project_id.is_(None),
+            GitRepository.owner_id == user_id,
+            GitRepository.name == data.name,
+        )
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="repository name already exists")
+    remote_url = _parse_remote_url(data.remote_url, data.force_original_url)
+    ssh_key_id, ssh_key = None, None
+    if data.ssh_key_id:
+        try:
+            ssh_key_id = uuid.UUID(data.ssh_key_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
+        ssh_key = await session.get(SSHKey, ssh_key_id)
+        if ssh_key is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        if ssh_key.user_id != user_id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user")
+    if remote_url:
+        preflight_remote_repository(remote_url, ssh_key)
+    repo = GitRepository(name=data.name, path="", project_id=None, owner_id=user_id, remote_url=remote_url, ssh_key_id=ssh_key_id)
+    session.add(repo)
+    await session.flush()
+    repo_path = f"/data/repos/external/{user_id}/{repo.id}"
+    repo.path = repo_path
+    if remote_url:
+        try:
+            clone_working_repository(remote_url, repo_path, ssh_key)
+            repo.is_mirror = False
+        except Exception as exc:
+            await session.rollback()
+            raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to clone repository: {exc}")
+    else:
+        init_working_repository(repo_path)
+        repo.is_mirror = False
+    await session.commit()
+    return repo
+
+
+@router.get("/{project_id}/repositories", response_model=list[GitRepositoryResponse])
+async def list_repositories(
+    project_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[GitRepository]:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    result = await session.execute(select(GitRepository).where(GitRepository.project_id == project_id))
+    return list(result.scalars().all())
+
+
+@router.delete("/{project_id}/repositories/{repo_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_repository(
+    project_id: uuid.UUID, repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> Response:
+    repo = await _get_repo(session, user_id, project_id, repo_id)
+    if os.path.exists(repo.path):
+        shutil.rmtree(repo.path)
+    await session.delete(repo)
+    await session.commit()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@router.post("/{project_id}/repositories", response_model=GitRepositoryResponse, status_code=status.HTTP_201_CREATED)
+async def create_repository(
+    project_id: uuid.UUID,
+    data: GitRepositoryCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> GitRepository:
+    """Create a new git repository in a project."""
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    existing = await session.execute(
+        select(GitRepository).where(GitRepository.project_id == project_id, GitRepository.name == data.name)
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="repository name already exists")
+    remote_url = _parse_remote_url(data.remote_url, data.force_original_url)
+    ssh_key_id, ssh_key = None, None
+    if data.ssh_key_id:
+        try:
+            ssh_key_id = uuid.UUID(data.ssh_key_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
+        ssh_key = await session.get(SSHKey, ssh_key_id)
+        if ssh_key is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        if ssh_key.user_id != user_id and ssh_key.project_id != project_id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user or project")
+    if remote_url:
+        preflight_remote_repository(remote_url, ssh_key)
+    repo_path = get_repo_path(user_id, project_id, data.name)
+    os.makedirs(os.path.dirname(repo_path), exist_ok=True)
+    if remote_url:
+        clone_working_repository(remote_url, repo_path, ssh_key)
+    else:
+        init_working_repository(repo_path)
+    repo = GitRepository(
+        name=data.name, path=repo_path, project_id=project_id, owner_id=user_id,
+        is_mirror=False, remote_url=remote_url, ssh_key_id=ssh_key_id,
+    )
+    session.add(repo)
+    await session.commit()
+    await session.refresh(repo)
+    return repo
+
+
+@router.patch("/{project_id}/repositories/{repo_id}/ssh-key", response_model=GitRepositoryResponse)
+async def update_repository_ssh_key(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: UpdateSSHKeyRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> GitRepository:
+    repo = await _get_repo(session, user_id, project_id, repo_id)
+    if data.ssh_key_id:
+        try:
+            ssh_key_id = uuid.UUID(data.ssh_key_id)
+        except ValueError:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
+        ssh_key = await session.get(SSHKey, ssh_key_id)
+        if ssh_key is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        if ssh_key.user_id != user_id and ssh_key.project_id != project_id:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user or project")
+        repo.ssh_key_id = ssh_key_id
+    else:
+        repo.ssh_key_id = None
+    await session.commit()
+    await session.refresh(repo)
+    return repo
+
+
+@router.get("/{project_id}/repositories/{repo_id}/history")
+async def get_repository_history(
+    project_id: uuid.UUID, repo_id: uuid.UUID,
+    view: str = "graph", branch: str | None = None, limit: int = 100, offset: int = 0,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        return get_commit_history(repo.path, branch=branch, limit=limit, offset=offset)
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
+
+
+@router.get("/{project_id}/repositories/{repo_id}/commits/{commit_hash}")
+async def get_repository_commit(
+    project_id: uuid.UUID, repo_id: uuid.UUID, commit_hash: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        return get_commit_detail(repo.path, commit_hash)
+    except (RuntimeError, ValueError) as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.get("/{project_id}/repositories/{repo_id}/files", response_model=FileListResponse)
+async def list_repository_files(
+    project_id: uuid.UUID, repo_id: uuid.UUID, branch: str = "main", path: str = "",
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> FileListResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        entries = list_tree(repo.path, branch=branch, path=path)
+        return FileListResponse(path=path, branch=branch, entries=[
+            {"name": e.name, "type": e.type, "path": e.path, "size": e.size, "mode": e.mode, "last_commit": e.last_commit}
+            for e in entries
+        ])
+    except RuntimeError as e:
+        logger.error("Failed to list files for repo %s: %s", repo_id, str(e))
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.get("/{project_id}/repositories/{repo_id}/files/content", response_model=FileContentResponse)
+async def get_repository_file_content(
+    project_id: uuid.UUID, repo_id: uuid.UUID, branch: str, path: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> FileContentResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        fc = get_file_content(repo.path, branch=branch, path=path)
+        return FileContentResponse(path=fc.path, branch=fc.branch, content=fc.content, size=fc.size,
+            encoding=fc.encoding, language=fc.language, is_binary=fc.is_binary, last_commit=fc.last_commit)
+    except FileNotFoundError:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="file not found")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.get("/{project_id}/repositories/{repo_id}/branches", response_model=BranchesResponse)
+async def get_repository_branches(
+    project_id: uuid.UUID, repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> BranchesResponse:
+    repo = await _get_repo(session, user_id, project_id, repo_id)
+    is_valid = os.path.isdir(os.path.join(repo.path, ".git")) or os.path.isfile(os.path.join(repo.path, "HEAD"))
+    if is_valid:
+        try:
+            branches, default_branch = list_branches(repo.path)
+            return BranchesResponse(branches=[
+                {"name": b.name, "is_default": b.is_default, "last_commit": b.last_commit} for b in branches
+            ], default_branch=default_branch)
+        except RuntimeError as e:
+            logger.error("Failed to list branches for repo %s: %s", repo_id, str(e))
+            raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e)) from e
+    if repo.remote_url:
+        ssh_key = await session.get(SSHKey, repo.ssh_key_id) if repo.ssh_key_id else None
+        try:
+            remote_branches, default_branch = list_remote_branches(repo.remote_url, ssh_key)
+            if remote_branches:
+                return BranchesResponse(branches=[
+                    {"name": b, "is_default": b == default_branch, "last_commit": None} for b in remote_branches
+                ], default_branch=default_branch)
+        except RuntimeError:
+            pass
+    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk — re-clone or re-create the repository")
+
+
+@router.post("/{project_id}/repositories/{repo_id}/files/content", response_model=FileUpdateResponse)
+async def update_repository_file(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: FileUpdateRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> FileUpdateResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    author_name, author_email = await _commit_author(session, user_id)
+    try:
+        commit_hash = commit_file(repo.path, data.branch, data.path, data.content, data.commit_message, author_name, author_email)
+        return FileUpdateResponse(commit_hash=commit_hash, message=data.commit_message, branch=data.branch)
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.get("/{project_id}/repositories/{repo_id}/status", response_model=StatusResponse)
+async def get_repository_status(
+    project_id: uuid.UUID, repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> StatusResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        s = get_status(repo.path)
+        return StatusResponse(branch=s.branch, modified=s.modified, added=s.added, deleted=s.deleted,
+            untracked=s.untracked, renamed=s.renamed, ahead=s.ahead, behind=s.behind)
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/branches")
+async def create_repository_branch(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: BranchCreateRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        create_branch(repo.path, data.name, data.base_branch)
+        return {"message": f"Branch '{data.name}' created", "branch": data.name}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.delete("/{project_id}/repositories/{repo_id}/branches/{branch_name}")
+async def delete_repository_branch(
+    project_id: uuid.UUID, repo_id: uuid.UUID, branch_name: str, force: bool = False,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        delete_branch(repo.path, branch_name, force)
+        return {"message": f"Branch '{branch_name}' deleted"}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/checkout")
+async def checkout_repository_branch(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: CheckoutRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        checkout_branch(repo.path, data.branch)
+        return {"message": f"Checked out branch '{data.branch}'", "branch": data.branch}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/commit", response_model=CommitResponse)
+async def commit_repository_changes(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: CommitRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> CommitResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    author_name, author_email = await _commit_author(session, user_id)
+    try:
+        commit_hash = commit_changes(repo.path, data.message, author_name, author_email, data.files)
+        return CommitResponse(commit_hash=commit_hash, message=data.message)
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/fetch", response_model=FetchResponse)
+async def fetch_repository(
+    project_id: uuid.UUID, repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> FetchResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        fetch(repo.path)
+        return FetchResponse(message="Fetched from remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/pull", response_model=PullResponse)
+async def pull_repository(
+    project_id: uuid.UUID, repo_id: uuid.UUID, branch: str | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> PullResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        pull(repo.path, branch)
+        return PullResponse(message="Pulled from remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/push", response_model=PushResponse)
+async def push_repository(
+    project_id: uuid.UUID, repo_id: uuid.UUID, branch: str | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> PushResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        push(repo.path, branch)
+        return PushResponse(message="Pushed to remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post("/{project_id}/repositories/{repo_id}/merge", response_model=MergeResponse)
+async def merge_repository_branches(
+    project_id: uuid.UUID, repo_id: uuid.UUID, data: MergeRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> MergeResponse:
+    repo = await _get_repo_on_disk(session, user_id, project_id, repo_id)
+    try:
+        commit_hash = merge(repo.path, data.source_branch, data.target_branch, data.message)
+        return MergeResponse(commit_hash=commit_hash, message=data.message or f"Merge {data.source_branch}")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))

apps/api/src/api/project/projects.py

@@ -3,25 +3,29 @@ import shutil
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session, get_owned_project
-from src.models.git_repository import GitRepository
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
+from src.models import GitRepository
 from src.models.project import Project
-from src.models.ssh_key import SSHKey
-from src.models.user import User
+from src.models import SSHKey
+from src.models import ToolInstance
 from src.schemas.project import (
     ProjectCreate,
-    ProjectUpdate,
     ProjectResponse,
+    ProjectUpdate,
     SetDefaultSSHKeyRequest,
 )
 
 router = APIRouter(prefix="/projects", tags=["projects"])
 
 
-
 @router.post(
     "",
     response_model=ProjectResponse,
@@ -31,7 +35,7 @@ router = APIRouter(prefix="/projects", tags=["projects"])
 )
 async def create_project(
     data: ProjectCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Create a new project.
@@ -44,6 +48,7 @@ async def create_project(
     Returns:
         The newly created project.
     """
+    user = await _get_user(session, user_id)
     project = Project(
         name=data.name,
         description=data.description,
@@ -58,25 +63,77 @@ async def create_project(
 
 @router.get(
     "",
-    response_model=list[ProjectResponse],
     summary="List all projects",
-    description="Retrieve all projects owned by the authenticated user.",
+    description="Retrieve all projects owned by the authenticated user with repositories and workspaces.",
 )
 async def list_projects(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> list[Project]:
+) -> list[dict]:
     """List all projects for the authenticated user.
 
-    Args:
-        user_id: ID of the authenticated user.
-        session: Database session.
-
-    Returns:
-        List of projects owned by the user.
+    Returns projects with nested repositories and workspaces for inline display.
     """
-    result = await session.execute(select(Project).where(Project.owner_id == user.id))
-    return list(result.scalars().all())
+    user = await _get_user(session, user_id)
+    result = await session.execute(
+        select(Project)
+        .where(Project.owner_id == user.id)
+        .order_by(Project.created_at.desc())
+    )
+    projects = result.scalars().all()
+
+    from src.models import Workspace
+
+    enriched = []
+    for project in projects:
+        repos_result = await session.execute(
+            select(GitRepository).where(GitRepository.project_id == project.id)
+        )
+        repositories = []
+        for repo in repos_result.scalars().all():
+            ws_result = await session.execute(
+                select(Workspace).where(Workspace.repo_id == repo.id)
+            )
+            workspaces = []
+            for ws in ws_result.scalars().all():
+                # Count instances
+                inst_result = await session.execute(
+                    select(func.count()).where(ToolInstance.workspace_id == ws.id)
+                )
+                instance_count = inst_result.scalar() or 0
+                workspaces.append(
+                    {
+                        "id": str(ws.id),
+                        "name": ws.name,
+                        "branch": ws.branch,
+                        "status": ws.status,
+                        "instance_count": instance_count,
+                    }
+                )
+
+            repositories.append(
+                {
+                    "id": str(repo.id),
+                    "name": repo.name,
+                    "remote_url": repo.remote_url,
+                    "workspaces": workspaces,
+                }
+            )
+
+        enriched.append(
+            {
+                "id": str(project.id),
+                "name": project.name,
+                "description": project.description,
+                "owner_id": str(project.owner_id),
+                "repositories": repositories,
+                "created_at": project.created_at.isoformat()
+                if project.created_at
+                else None,
+            }
+        )
+
+    return enriched
 
 
 @router.get(
@@ -87,8 +144,7 @@ async def list_projects(
 )
 async def get_project(
     project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Get a specific project by ID.
@@ -101,8 +157,8 @@ async def get_project(
     Returns:
         The requested project.
     """
-    return project
-
+    await _get_user(session, user_id)
+    return await _get_owned_project(project_id, user_id, session)
 
 
 @router.patch(
@@ -114,8 +170,7 @@ async def get_project(
 async def update_project(
     project_id: uuid.UUID,
     data: ProjectUpdate,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Update a project.
@@ -129,6 +184,8 @@ async def update_project(
     Returns:
         The updated project.
     """
+    await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     if data.name is not None:
         project.name = data.name
@@ -148,8 +205,7 @@ async def update_project(
 )
 async def delete_project(
     project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Response:
     """Delete a project and all its repositories.
@@ -162,9 +218,13 @@ async def delete_project(
     Returns:
         Empty response with 204 status code.
     """
+    await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     # Delete repositories from disk and database
-    result = await session.execute(select(GitRepository).where(GitRepository.project_id == project_id))
+    result = await session.execute(
+        select(GitRepository).where(GitRepository.project_id == project_id)
+    )
     repositories = result.scalars().all()
     for repo in repositories:
         if os.path.exists(repo.path):
@@ -185,8 +245,7 @@ async def delete_project(
 async def set_default_ssh_key(
     project_id: uuid.UUID,
     data: SetDefaultSSHKeyRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Set the default SSH key for a project.
@@ -200,6 +259,8 @@ async def set_default_ssh_key(
     Returns:
         The updated project.
     """
+    user = await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     ssh_key = await session.get(SSHKey, data.ssh_key_id)
     if ssh_key is None or ssh_key.user_id != user.id:

apps/api/src/api/system/.pi-map.index.md

@@ -0,0 +1,26 @@
+# apps/api/src/api/system (index)
+dir: apps/api/src/api/system
+
+## role
+Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, event streaming, notifications, and container terminal access.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- dashboard.py
+- events.py
+- health.py
+- instance_proxy.py
+- notifications.py
+- terminal.py
+## links
+index: apps/api/src/api/system/.pi-map.index.md
+map: apps/api/src/api/system/.pi-map.md
+## workflows
+- change system behavior
+  read: __init__.py, dashboard.py, events.py
+## dirty
+-

apps/api/src/api/system/.pi-map.md

@@ -0,0 +1,33 @@
+# apps/api/src/api/system
+dir: apps/api/src/api/system
+
+index: apps/api/src/api/system/.pi-map.index.md
+
+## role
+Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, event streaming, notifications, and container terminal access.
+## files
+- __init__.py | Aggregates and re-exports system API router modules from submodules for centralized access. | dep: src.api.system.dashboard, src.api.system.events, src.api.system.health, src.api.system.instance_proxy, src.api.system.notifications, src.api.system.terminal
+- dashboard.py | Provides a FastAPI endpoint that returns a dashboard summary with aggregated counts of projects, repositories, SSH keys, and recent activity for the authenticated user. | exp: func:get_dashboard_summary(user_id, session) → dict, call:session.execute, call:select(func.count()).select_from(Project).where, call:func.count, call:projects_result.scalar, call:select(func.count()).select_from(GitRepository).where, call:repos_result.scalar, call:select(func.count()).select_from(SSHKey).where, call:ssh_keys_result.scalar, call:select(Project) .where(Project.owner_id == user_id) .order_by(Project.created_at.desc()) .limit, call:Project.created_at.desc, call:recent_projects.scalars().all | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models.project, src.models (GitRepository, Project, SSHKey)
+- events.py | Implements an SSE streaming endpoint that delivers instance events to authenticated users with per-user connection limits and keep-alive pings. | exp: func:events_stream(request: Request, user_id) → StreamingResponse, call:_connection_counts.get, call:InstanceEventBus, call:asyncio.Queue, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait, call:event_bus.subscribe, call:asyncio.wait_for, call:queue.get, call:json.dumps, call:unsubscribe, call:max, call:_connection_counts.pop, call:StreamingResponse, call:event_generator, raise:HTTPException, func:event_generator() → AsyncGenerator[str, None], call:InstanceEventBus, call:asyncio.Queue, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait, call:event_bus.subscribe, call:asyncio.wait_for, call:queue.get, call:json.dumps, call:unsubscribe, call:max, call:_connection_counts.get, call:_connection_counts.pop, func:on_event(payload: InstanceEventPayload) → None, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait | dep: asyncio, contextlib, json, uuid, collections.abc, fastapi, fastapi.responses, src.auth.dependencies, src.services.instance.event_bus
+- health.py | Implements FastAPI health check endpoints for monitoring system status including database connectivity and disk space. | exp: func:health_check() → dict[str, Any], call:HealthChecks, call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealth, call:round, call:shutil.disk_usage, call:DiskHealth, call:HealthResponse( status=overall_status, timestamp=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), version="0.1.0", checks=checks, uptime_seconds=round(time.time() - _start_time, 2), ).model_dump, call:datetime.now(timezone.utc).isoformat().replace, call:time.time, func:health_check_db() → dict[str, Any], call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealthResponse( status="healthy", response_time_ms=round(db_time, 2), ).model_dump, call:round, call:DatabaseHealthResponse( status="unhealthy", response_time_ms=0.0, ).model_dump | dep: time, datetime, typing, fastapi, sqlalchemy, src.database, src.schemas.system, shutil
+- instance_proxy.py | Proxies HTTP requests from FastAPI endpoints to running containerized tool instances after verifying ownership and status. | exp: func:_proxy_request(request: Request, instance_id: uuid.UUID, path: str, user_id: uuid.UUID, session: AsyncSession) → Response, call:session.get, call:str, call:request.headers.items, call:key.lower, call:httpx.AsyncClient, call:request.body, call:client.request, call:logger.error, call:dict, call:response_headers.pop, call:Response, raise:HTTPException, func:proxy_to_instance(request: Request, instance_id: uuid.UUID, path, user_id, session) → Response, call:_proxy_request | dep: logging, uuid, httpx, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models
+- notifications.py | Defines FastAPI REST endpoints for managing user notifications (list, unread count, mark read, dismiss/clear) with support for muted categories from user config. | exp: class:NotificationItem, class:NotificationListResponse, class:UnreadCountResponse, class:MarkAllReadResponse, class:ClearAllResponse, func:_get_mute_categories(session: AsyncSession, user_id: uuid.UUID) → list[str], call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:config.config.get, call:isinstance, func:list_notifications(limit, offset, unread_only, user, session) → NotificationListResponse, call:_get_mute_categories, call:notification_service.list_notifications, call:NotificationListResponse, call:NotificationItem.model_validate, func:get_unread_count(user, session) → UnreadCountResponse, call:notification_service.get_unread_count, call:UnreadCountResponse, func:mark_notification_read(notification_id: uuid.UUID, user, session) → NotificationItem, call:notification_service.mark_read, call:NotificationItem.model_validate, raise:HTTPException, func:mark_all_read(user, session) → MarkAllReadResponse, call:notification_service.mark_all_read, call:MarkAllReadResponse, func:clear_all_notifications(user, session) → ClearAllResponse, call:notification_service.dismiss_all, call:ClearAllResponse, func:dismiss_notification(notification_id: uuid.UUID, user, session) → None, call:notification_service.dismiss, raise:HTTPException | dep: uuid, datetime, fastapi, pydantic, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.models, src.services.shared.notification_service, sqlalchemy
+- terminal.py | Provides WebSocket and HTTP endpoints for managing interactive terminal sessions attached to running Docker container tool instances, including session creation, attachment, input/output streaming, resize/reset control messages, and session listing. | exp: class:SessionRef, method:__init__(self, session, slot_session_id), func:terminal_websocket_default(websocket: WebSocket, instance_id: str, db_session) → None, call:_handle_terminal_websocket, func:terminal_websocket_specific(websocket: WebSocket, instance_id: str, session_id: str, db_session) → None, call:_handle_terminal_websocket, func:_handle_terminal_websocket(websocket: WebSocket, instance_id: str, target_session_id: str | None, db_session: AsyncSession) → None, call:logger.debug, call:websocket.accept, call:uuid.UUID, call:logger.error, call:websocket.close, call:_get_user_from_websocket, call:logger.warning, call:db_session.get, call:get_container_status, call:terminal_manager.get_or_create_session, call:terminal_manager.get_session, call:logger.info, call:terminal_manager.create_session, call:terminal_manager._find_key_by_internal_id, call:terminal_manager.attach_websocket, call:websocket.send_json, call:SessionRef, call:asyncio.create_task, call:_write_loop, call:_heartbeat_loop, call:asyncio.wait, call:len, call:task.cancel, call:str, call:suppress, call:terminal_manager.detach_websocket, func:_write_loop(session_ref: SessionRef, websocket, instance_id: str) → None, call:session.is_alive, call:asyncio.sleep, call:websocket.receive, call:session.write_input, call:text.startswith, call:json.loads, call:ctrl.get, call:logger.debug, call:session.resize, call:session.acknowledge_data, call:websocket.send_json, call:terminal_manager.reset_session, call:terminal_manager.attach_websocket, call:text.encode, func:_heartbeat_loop(websocket: WebSocket) → None, call:asyncio.sleep, call:websocket.send_json, func:_get_terminal_instance(instance_id: uuid.UUID, user_id: uuid.UUID, db_session: AsyncSession) → ToolInstance, call:db_session.get, raise:HTTPException, func:list_terminal_sessions(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.execute, call:select(TerminalSessionModel) .where(TerminalSessionModel.instance_id == instance_id) .where(TerminalSessionModel.status != "closed") .order_by, call:TerminalSessionModel.created_at.asc, call:result.scalars().all, call:terminal_manager.get_session, call:str, call:sessions.append, call:live_session.has_websockets, call:row.created_at.isoformat, call:row.last_activity_at.isoformat, func:create_terminal_session(instance_id: uuid.UUID, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:data.get, call:terminal_manager.create_session, raise:HTTPException, func:close_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:terminal_manager.close_session, raise:HTTPException, func:reset_specific_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:db_session.get, call:terminal_manager.reset_session, raise:HTTPException, func:rename_terminal_session(instance_id: uuid.UUID, session_id: str, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:data.get, call:isinstance, call:terminal_manager.get_session, call:str, call:db_session.get, call:uuid.UUID, call:db_session.commit, raise:HTTPException, func:reset_terminal_session(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:terminal_manager.reset_session, call:logger.info, call:str, call:logger.error, raise:HTTPException, func:_get_user_from_websocket(websocket: WebSocket, db_session: AsyncSession) → uuid.UUID | None, call:websocket.cookies.get, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str | dep: asyncio, json, logging, uuid, contextlib, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, starlette.websockets, src.auth.dependencies, src.models, src.services.terminal.terminal_manager, src.services.docker, src.auth.session, src.config, starlette
+## arch
+FastAPI router modules organized by domain concern with async/await patterns, SSE/WebSocket for real-time streaming, proxy pattern for container instance forwarding, and per-user authentication/authorization with connection limiting.
+## tags
+session, terminal, call:terminal, call:, src, get, response, websocket
+## symbols
+- NotificationItem
+- NotificationListResponse
+- UnreadCountResponse
+- MarkAllReadResponse
+- ClearAllResponse
+- SessionRef
+- get_dashboard_summary
+- events_stream
+## workflows
+- change system behavior
+  read: __init__.py, dashboard.py, events.py
+## dirty
+-

apps/api/src/api/system/__init__.py

@@ -0,0 +1,17 @@
+"""System API routers module."""
+
+from src.api.system.dashboard import router as dashboard_router
+from src.api.system.events import router as events_router
+from src.api.system.health import router as health_router
+from src.api.system.instance_proxy import router as instance_proxy_router
+from src.api.system.notifications import router as notifications_router
+from src.api.system.terminal import router as terminal_router
+
+__all__ = [
+    "dashboard_router",
+    "events_router",
+    "health_router",
+    "instance_proxy_router",
+    "notifications_router",
+    "terminal_router",
+]

apps/api/src/api/system/dashboard.py

@@ -5,9 +5,9 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.git_repository import GitRepository
+from src.models import GitRepository
 from src.models.project import Project
-from src.models.ssh_key import SSHKey
+from src.models import SSHKey
 
 router = APIRouter(prefix="/dashboard", tags=["dashboard"])
 

apps/api/src/api/system/events.py

@@ -10,7 +10,7 @@ from fastapi import APIRouter, Depends, HTTPException, Request, status
 from fastapi.responses import StreamingResponse
 
 from src.auth.dependencies import get_current_user_id
-from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+from src.services.instance.event_bus import InstanceEventBus, InstanceEventPayload
 
 router = APIRouter(prefix="/events", tags=["events"])
 

apps/api/src/api/system/health.py

@@ -4,12 +4,11 @@ import time
 from datetime import datetime, timezone
 from typing import Any
 
-from fastapi import APIRouter, status
+from fastapi import APIRouter
 from sqlalchemy import text
 
-from src.config import Settings
 from src.database import SessionLocal
-from src.schemas.health import (
+from src.schemas.system import (
     DatabaseHealth,
     DatabaseHealthResponse,
     DiskHealth,

apps/api/src/api/system/instance_proxy.py

@@ -8,8 +8,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
+from src.models import ToolInstance
+from src.models import ToolType
 
 logger = logging.getLogger(__name__)
 

apps/api/src/api/system/notifications.py

@@ -9,8 +9,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user, get_db_session
 from src.models.user import User
-from src.models.user_config import UserConfig
-from src.services.notification_service import notification_service
+from src.models import UserConfig
+from src.services.shared.notification_service import notification_service
 
 router = APIRouter(prefix="/notifications", tags=["notifications"])
 

apps/api/src/api/system/terminal.py

@@ -12,10 +12,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from starlette.websockets import WebSocketDisconnect
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.terminal_session import TerminalSessionModel
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
-from src.services.terminal_manager import MaxSessionsExceededError, terminal_manager
+from src.models import TerminalSessionModel
+from src.models import ToolInstance
+from src.models import ToolType
+from src.services.terminal.terminal_manager import MaxSessionsExceededError, terminal_manager
 
 router = APIRouter()
 logger = logging.getLogger(__name__)

apps/api/src/api/tool/.pi-map.index.md

@@ -0,0 +1,26 @@
+# apps/api/src/api/tool (index)
+dir: apps/api/src/api/tool
+
+## role
+Provides FastAPI REST API endpoints for managing Docker-based tools, including their definitions, types, instances, lifecycle operations, and active sessions.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- sessions.py
+- tool_definitions.py
+- tool_instances.py
+- tool_lifecycle.py
+- tool_types.py
+- tool_types_validation.py
+## links
+index: apps/api/src/api/tool/.pi-map.index.md
+map: apps/api/src/api/tool/.pi-map.md
+## workflows
+- change tool behavior
+  read: __init__.py, sessions.py, tool_definitions.py
+## dirty
+-

apps/api/src/api/tool/.pi-map.md

@@ -0,0 +1,33 @@
+# apps/api/src/api/tool
+dir: apps/api/src/api/tool
+
+index: apps/api/src/api/tool/.pi-map.index.md
+
+## role
+Provides FastAPI REST API endpoints for managing Docker-based tools, including their definitions, types, instances, lifecycle operations, and active sessions.
+## files
+- __init__.py | Aggregates and exports all tool-related API routers from submodules as a unified module interface. | dep: src.api.tool.sessions, src.api.tool.tool_definitions, src.api.tool.tool_instances, src.api.tool.tool_lifecycle, src.api.tool.tool_types
+- sessions.py | Provides a FastAPI endpoint to retrieve all active tool instances (sessions) for the currently authenticated user with related metadata. | exp: func:get_user_sessions(user_id, session) → dict, call:_get_user, call:session.execute, call:select(ToolInstance) .where(ToolInstance.owner_id == user_id) .where( ToolInstance.status.in_( ["running", "building", "pending", "stopped", "error"] ) ) .order_by, call:ToolInstance.status.in_, call:ToolInstance.created_at.desc, call:result.scalars().all, call:session.get, call:sessions.append, call:str, call:instance.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models (GitRepository, Project, ToolInstance, ToolType, Workspace)
+- tool_definitions.py | FastAPI router providing CRUD endpoints and manifest compilation for tool definition manifests stored in a database. | exp: class:CreateToolDefinitionRequest, class:UpdateToolDefinitionRequest, func:create_tool_definition(data: CreateToolDefinitionRequest, user_id, session) → dict, call:uuid.UUID, call:session.get, call:session.execute, call:select(ToolDefinitionManifest).where, call:existing.scalar_one_or_none, call:ToolDefinitionManifest, call:session.add, call:session.commit, call:session.refresh, call:logger.info, call:str, call:definition.created_at.isoformat, raise:HTTPException, func:list_tool_definitions(user_id, session, include_bases) → dict, call:select, call:query.where, call:ToolDefinitionManifest.is_base.is_, call:session.execute, call:query.order_by, call:ToolDefinitionManifest.created_at.desc, call:result.scalars().all, call:str, call:d.created_at.isoformat, func:get_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:str, call:definition.created_at.isoformat, call:definition.updated_at.isoformat, raise:HTTPException, func:update_tool_definition(definition_id: uuid.UUID, data: UpdateToolDefinitionRequest, user_id, session) → dict, call:session.get, call:session.commit, call:session.refresh, call:logger.info, call:str, call:definition.updated_at.isoformat, raise:HTTPException, func:delete_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:session.execute, call:select(ToolType).where, call:result.scalars().all, call:", ".join, call:session.delete, call:session.commit, call:logger.info, call:str, raise:HTTPException, func:compile_tool_definition(definition_id: uuid.UUID, user_id, session) → dict, call:session.get, call:dict, call:resolve_base, call:deep_merge, call:compile_dockerfile, call:compile_entrypoint, call:compute_image_tag, call:compile_compose, call:session.commit, call:str, raise:HTTPException | dep: logging, uuid, fastapi, pydantic, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.build.manifest_compiler
+- tool_instances.py | Provides FastAPI REST endpoints for managing tool instances including CRUD operations, logs, health checks, tunnel recreation, event history, and HTTP proxying to running containers. | exp: func:create_instance(project_id: uuid.UUID, repo_id: uuid.UUID, data: CreateInstanceRequest, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:create_tool_instance, call:str, call:instance.created_at.isoformat, raise:HTTPException, func:list_instances(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → list[dict], call:_get_user, call:_get_owned_project, call:session.execute, call:select(ToolInstance) .where(ToolInstance.repository_id == repo_id) .where(ToolInstance.owner_id == user_id) .order_by, call:ToolInstance.created_at.desc, call:result.scalars().all, call:str, call:i.created_at.isoformat, func:get_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_status, call:str, call:instance.created_at.isoformat, call:instance.last_started_at.isoformat, raise:HTTPException, func:rename_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:data.get("display_name", "").strip, call:rename_tool_instance, call:str, raise:HTTPException, func:get_instance_logs(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, tail, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_logs, raise:HTTPException, func:recreate_tunnel_endpoint(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:recreate_instance_tunnel, raise:HTTPException, func:check_instance_tunnel_health(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:session.get, call:get_container_status, call:instance.probe_result.get, call:"\n".join, call:check_tunnel_health, call:tunnel_health.get, raise:HTTPException, func:get_instance_events(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, limit, user_id, session) → list[dict], call:_get_user, call:_get_owned_project, call:session.get, call:session.execute, call:select(InstanceEvent) .where(InstanceEvent.instance_id == instance_id) .order_by(InstanceEvent.created_at.desc()) .limit, call:InstanceEvent.created_at.desc, call:result.scalars().all, call:str, call:row.created_at.isoformat, raise:HTTPException, func:proxy_to_instance(request: Request, project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, path, user_id, session) → Response, call:session.get, call:str, call:dict, call:headers.pop, call:httpx.AsyncClient, call:request.body, call:client.request, call:logger.error, call:response_headers.pop, call:Response, raise:HTTPException | dep: logging, uuid, httpx, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.docker, src.services.shared.tunnel, src.schemas.tool, src.services.tool.instance_service
+- tool_lifecycle.py | FastAPI router providing REST endpoints for managing Docker-based tool instance lifecycle operations (start, stop, restart, delete). | exp: func:start_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, data, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:start_tool_instance, raise:HTTPException, func:stop_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:stop_tool_instance, raise:HTTPException, func:restart_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:_get_owned_project, call:restart_tool_instance, raise:HTTPException, func:delete_instance(project_id: uuid.UUID, repo_id: uuid.UUID, instance_id: uuid.UUID, force, user_id, session) → None, call:_get_user, call:_get_owned_project, call:delete_tool_instance, call:str, call:detail.lower, raise:HTTPException | dep: logging, uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.schemas.tool, src.services.tool.instance_service
+- tool_types.py | Defines FastAPI routes for CRUD operations and validation of Docker tool types with compose/dockerfile/manifest definitions. | exp: func:_require_admin(user: User) → None, func:create_tool_type(data: ToolTypeCreate, user_id, session) → ToolType, call:_get_user, call:_require_admin, call:session.scalar, call:select(ToolType).where, call:ToolType, call:session.add, call:session.commit, call:session.refresh, raise:HTTPException, func:list_tool_types(user_id, session) → list[ToolType], call:_get_user, call:session.execute, call:select(ToolType).order_by, call:list, call:result.scalars().all, func:get_tool_type(tool_type_id: uuid.UUID, user_id, session) → ToolType, call:_get_user, call:session.get, raise:HTTPException, func:update_tool_type(tool_type_id: uuid.UUID, data: ToolTypeUpdate, user_id, session) → ToolType, call:_get_user, call:_require_admin, call:session.get, call:data.model_dump, call:update_data.get, call:validate_compose_yaml, call:check_port_exposed, call:validate_required_variables, call:update_data.items, call:setattr, call:session.commit, call:session.refresh, raise:HTTPException, func:validate_tool_type_template(data: ToolTypeValidateRequest, user_id, session) → dict, call:_get_user, call:errors.append, call:validate_compose_yaml, call:str, call:data.dockerfile_template.strip().startswith, call:len, func:validate_tool_type(tool_type_id: uuid.UUID, user_id, session) → dict, call:_get_user, call:session.get, call:errors.append, call:validate_compose_yaml, call:str, call:tool_type.dockerfile_template.strip().startswith, call:len, raise:HTTPException, func:delete_tool_type(tool_type_id: uuid.UUID, user_id, session) → None, call:_get_user, call:_require_admin, call:session.get, call:session.delete, call:session.commit, raise:HTTPException | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.api.tool.tool_types_validation, src.auth.dependencies, src.models, src.models.user, src.schemas.tool
+- tool_types_validation.py | Validates Docker Compose YAML templates by sanitizing template variables, parsing YAML structure, checking port exposure, and verifying required variables exist. | exp: func:sanitize_template_vars(template: str) → str, call:re.sub, func:validate_compose_yaml(template: str) → dict, call:sanitize_template_vars, call:yaml.safe_load, call:isinstance, raise:ValueError, func:check_port_exposed(parsed: dict, port: int) → bool, call:str, call:isinstance, call:parsed["services"].values, call:port_mapping.split, call:mapping.split, func:validate_required_variables(template: str, variables: list[str]) → None, raise:HTTPException | dep: re, yaml, fastapi
+## arch
+Modular FastAPI router organization with clear separation of concerns across CRUD operations, Docker lifecycle management, YAML/Compose validation, and container proxying/tunneling.
+## tags
+get, call:, tool, raise:httpexception, user, instance, call:str, call:session.get
+## symbols
+- CreateToolDefinitionRequest
+- UpdateToolDefinitionRequest
+- get_user_sessions
+- create_tool_definition
+- list_tool_definitions
+- get_tool_definition
+- update_tool_definition
+- delete_tool_definition
+## workflows
+- change tool behavior
+  read: __init__.py, sessions.py, tool_definitions.py
+## dirty
+-

apps/api/src/api/tool/__init__.py

@@ -0,0 +1,15 @@
+"""Tool API routers module."""
+
+from src.api.tool.sessions import sessions_router
+from src.api.tool.tool_definitions import router as tool_definitions_router
+from src.api.tool.tool_instances import router as tool_instances_router
+from src.api.tool.tool_lifecycle import router as tool_lifecycle_router
+from src.api.tool.tool_types import router as tool_types_router
+
+__all__ = [
+    "sessions_router",
+    "tool_definitions_router",
+    "tool_instances_router",
+    "tool_lifecycle_router",
+    "tool_types_router",
+]

apps/api/src/api/tool/sessions.py

@@ -0,0 +1,86 @@
+"""Sessions API endpoints (running instances for current user)."""
+
+import uuid
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
+from src.models import GitRepository
+from src.models import Project
+from src.models import ToolInstance
+from src.models import ToolType
+
+sessions_router = APIRouter(prefix="/users", tags=["sessions"])
+
+
+@sessions_router.get(
+    "/me/sessions",
+    summary="Get user sessions",
+    description="Get all active sessions (running instances) for the current user.",
+)
+async def get_user_sessions(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get all active sessions for the current user.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary containing list of active sessions with instance details.
+    """
+    _user = await _get_user(session, user_id)
+
+    result = await session.execute(
+        select(ToolInstance)
+        .where(ToolInstance.owner_id == user_id)
+        .where(
+            ToolInstance.status.in_(
+                ["running", "building", "pending", "stopped", "error"]
+            )
+        )
+        .order_by(ToolInstance.created_at.desc())
+    )
+    instances = result.scalars().all()
+
+    sessions = []
+    for instance in instances:
+        tool_type = await session.get(ToolType, instance.tool_type_id)
+        repo = await session.get(GitRepository, instance.repository_id)
+        project = await session.get(Project, instance.project_id)
+
+        workspace_name = None
+        if instance.workspace_id:
+            from src.models import Workspace as WorkspaceModel
+            workspace = await session.get(WorkspaceModel, instance.workspace_id)
+            if workspace:
+                workspace_name = workspace.name
+
+        sessions.append(
+            {
+                "id": str(instance.id),
+                "display_name": instance.display_name,
+                "tool_type_name": tool_type.name if tool_type else "unknown",
+                "tool_icon": tool_type.name if tool_type else "code",
+                "tool_type_interfaces": [tool_type.interface_type] if tool_type else [],
+                "repository_name": repo.name if repo else "unknown",
+                "repository_id": str(instance.repository_id),
+                "project_name": project.name if project else "unknown",
+                "project_id": str(instance.project_id),
+                "workspace_name": workspace_name,
+                "status": instance.status,
+                "url": instance.url,
+                "selected_config_profile_id": str(instance.selected_config_profile_id)
+                if instance.selected_config_profile_id
+                else None,
+                "created_at": instance.created_at.isoformat()
+                if instance.created_at
+                else None,
+            }
+        )
+
+    return {"sessions": sessions}

apps/api/src/api/tool/tool_definitions.py

@@ -9,9 +9,9 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_definition_manifest import ToolDefinitionManifest
-from src.models.tool_type import ToolType
-from src.services.manifest_compiler import (
+from src.models import ToolDefinitionManifest
+from src.models import ToolType
+from src.services.build.manifest_compiler import (
     compile_compose,
     compile_dockerfile,
     compile_entrypoint,
@@ -173,7 +173,7 @@ async def list_tool_definitions(
     """
     query = select(ToolDefinitionManifest)
     if not include_bases:
-        query = query.where(ToolDefinitionManifest.is_base == False)
+        query = query.where(ToolDefinitionManifest.is_base.is_(False))
 
     result = await session.execute(
         query.order_by(ToolDefinitionManifest.created_at.desc())

apps/api/src/api/tool/tool_instances.py

@@ -0,0 +1,419 @@
+"""Tool instance API endpoints."""
+
+import logging
+import uuid
+
+import httpx
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+    Request,
+    Response,
+    status,
+)
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
+from src.models import ToolInstance
+from src.services.docker import get_container_logs, get_container_status
+from src.services.shared.tunnel import check_tunnel_health
+from src.schemas.tool import CreateInstanceRequest
+from src.services.tool.instance_service import (
+    create_tool_instance,
+    recreate_instance_tunnel,
+    rename_tool_instance,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/projects", tags=["tool-instances"])
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/instances",
+    summary="Create tool instance",
+    description="Create a new tool instance for a repository.",
+)
+async def create_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: CreateInstanceRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        instance = await create_tool_instance(session, user_id, project_id, repo_id, data)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)
+        )
+    return {
+        "id": str(instance.id),
+        "name": instance.name,
+        "display_name": instance.display_name,
+        "tool_type_id": str(instance.tool_type_id),
+        "status": instance.status,
+        "workspace_id": str(instance.workspace_id) if instance.workspace_id else None,
+        "selected_config_profile_id": str(instance.selected_config_profile_id) if instance.selected_config_profile_id else None,
+        "created_at": instance.created_at.isoformat(),
+    }
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances",
+    summary="List instances",
+    description="List all tool instances for a repository.",
+)
+async def list_instances(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    result = await session.execute(
+        select(ToolInstance)
+        .where(ToolInstance.repository_id == repo_id)
+        .where(ToolInstance.owner_id == user_id)
+        .order_by(ToolInstance.created_at.desc())
+    )
+    instances = result.scalars().all()
+
+    return [
+        {"id": str(i.id), "name": i.name, "display_name": i.display_name,
+         "tool_type_id": str(i.tool_type_id), "status": i.status, "url": i.url,
+         "port": i.port, "container_id": i.container_id,
+         "created_at": i.created_at.isoformat() if i.created_at else None}
+        for i in instances
+    ]
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}",
+    summary="Get instance",
+    description="Get details for a specific tool instance.",
+)
+async def get_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    docker_status = None
+    if instance.container_id:
+        docker_status = get_container_status(instance.container_id)
+
+    return {
+        "id": str(instance.id),
+        "name": instance.name,
+        "display_name": instance.display_name,
+        "tool_type_id": str(instance.tool_type_id),
+        "status": instance.status,
+        "url": instance.url,
+        "public_url": instance.public_url,
+        "port": instance.port,
+        "container_id": instance.container_id,
+        "container_name": instance.container_name,
+        "compose_path": instance.compose_path,
+        "workspace_id": str(instance.workspace_id) if instance.workspace_id else None,
+        "selected_config_profile_id": str(instance.selected_config_profile_id) if instance.selected_config_profile_id else None,
+        "ssh_key_ids": instance.ssh_key_ids,
+        "created_at": instance.created_at.isoformat() if instance.created_at else None,
+        "last_started_at": instance.last_started_at.isoformat() if instance.last_started_at else None,
+        "docker_status": docker_status,
+    }
+
+
+@router.patch(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}",
+    summary="Rename instance",
+    description="Update the display name of a tool instance.",
+)
+async def rename_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    display_name = data.get("display_name", "").strip()
+    if not display_name:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="display_name is required",
+        )
+
+    try:
+        instance = await rename_tool_instance(
+            session, user_id, project_id, repo_id, instance_id, display_name
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)
+        )
+
+    return {
+        "id": str(instance.id),
+        "name": instance.name,
+        "display_name": instance.display_name,
+    }
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/logs",
+    summary="Get instance logs",
+    description="Get container logs for a tool instance.",
+)
+async def get_instance_logs(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    tail: int = 100,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    if not instance.container_id:
+        return {"logs": "No container running"}
+
+    logs = get_container_logs(instance.container_id, tail)
+    return {"logs": logs}
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/recreate-tunnel",
+    summary="Recreate tunnel",
+    description="Recreate the temporary Cloudflare tunnel for a running instance.",
+)
+async def recreate_tunnel_endpoint(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        return await recreate_instance_tunnel(
+            session, user_id, project_id, repo_id, instance_id
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)
+        )
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/health",
+    summary="Check instance health",
+    description="Check container and tunnel health for an instance.",
+)
+async def check_instance_tunnel_health(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    container_info = {"status": "not_found", "exit_code": None, "health": None}
+    if instance.container_id:
+        container_info = get_container_status(instance.container_id)
+
+    response = {
+        "healthy": False,
+        "container_status": container_info["status"],
+        "container_health": container_info["health"],
+        "tunnel_status": "not_applicable",
+        "tunnel_status_code": None,
+        "probe_status": "not_applicable",
+        "last_probe_output": None,
+        "error": None,
+    }
+    if instance.status == "probing":
+        response["probe_status"] = "pending"
+    elif instance.probe_result:
+        response["probe_status"] = "success" if instance.probe_result.get("success") else "failed"
+        response["last_probe_output"] = "\n".join(instance.probe_result.get("logs", []))
+    if instance.url and instance.status in ("running", "unhealthy"):
+        tunnel_health = check_tunnel_health(instance.url)
+        response["tunnel_status"] = tunnel_health["tunnel_status"]
+        response["tunnel_status_code"] = tunnel_health.get("status_code")
+        if tunnel_health.get("error"):
+            response["error"] = tunnel_health["error"]
+    container_healthy = container_info["status"] == "running"
+    if instance.url:
+        response["healthy"] = container_healthy and response["tunnel_status"] == "healthy"
+    else:
+        response["healthy"] = container_healthy
+    if not container_healthy:
+        response["error"] = f"Container is {container_info['status']}"
+        if container_info["exit_code"] is not None:
+            response["error"] += f" (exit code: {container_info['exit_code']})"
+    return response
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/events",
+    summary="Get instance events history",
+    description="Get lifecycle event history for a tool instance.",
+)
+async def get_instance_events(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    limit: int = 50,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    from sqlalchemy import select
+    from src.models import InstanceEvent
+
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    result = await session.execute(
+        select(InstanceEvent)
+        .where(InstanceEvent.instance_id == instance_id)
+        .order_by(InstanceEvent.created_at.desc())
+        .limit(limit)
+    )
+    rows = result.scalars().all()
+
+    return [
+        {
+            "id": str(row.id),
+            "event_type": row.event_type,
+            "status": row.status,
+            "message": row.message,
+            "metadata": row.event_metadata,
+            "created_at": row.created_at.isoformat() if row.created_at else None,
+        }
+        for row in rows
+    ]
+
+
+@router.api_route(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/proxy/{path:path}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+    summary="Proxy to instance",
+    description="Proxy HTTP requests to a running tool instance.",
+)
+async def proxy_to_instance(
+    request: Request,
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    path: str = "",
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> Response:
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    if instance.owner_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="not authorized to access this instance",
+        )
+
+    if instance.status != "running" or not instance.container_name:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="instance is not running",
+        )
+
+    target_url = f"http://{instance.container_name}:{instance.port}"
+    if path:
+        target_url += f"/{path}"
+
+    query_string = str(request.query_params)
+    if query_string:
+        target_url += f"?{query_string}"
+
+    headers = dict(request.headers)
+    headers.pop("host", None)
+    headers.pop("cookie", None)
+
+    try:
+        async with httpx.AsyncClient() as client:
+            body = await request.body()
+            response = await client.request(
+                method=request.method,
+                url=target_url,
+                headers=headers,
+                content=body,
+                follow_redirects=False,
+                timeout=30.0,
+            )
+    except Exception as exc:
+        logger.error("Proxy error: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"failed to reach instance: {exc}",
+        )
+
+    response_headers = dict(response.headers)
+    for header in ["content-encoding", "transfer-encoding", "connection"]:
+        response_headers.pop(header, None)
+
+    return Response(
+        content=response.content,
+        status_code=response.status_code,
+        headers=response_headers,
+    )

apps/api/src/api/tool/tool_lifecycle.py

@@ -0,0 +1,135 @@
+"""Tool instance lifecycle API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
+from src.schemas.tool import StartInstanceRequest
+from src.services.tool.instance_service import (
+    delete_tool_instance,
+    restart_tool_instance,
+    start_tool_instance,
+    stop_tool_instance,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/projects", tags=["tool-instances"])
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/start",
+    summary="Start instance",
+    description="Start a tool instance using Docker Compose.",
+)
+async def start_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    data: StartInstanceRequest | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        return await start_tool_instance(
+            session, user_id, project_id, repo_id, instance_id, data
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)
+        )
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/stop",
+    summary="Stop instance",
+    description="Stop a running tool instance.",
+)
+async def stop_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        return await stop_tool_instance(session, user_id, project_id, repo_id, instance_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/restart",
+    summary="Restart instance",
+    description="Restart a tool instance.",
+)
+async def restart_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        return await restart_tool_instance(
+            session, user_id, project_id, repo_id, instance_id
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)
+        )
+
+
+@router.delete(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}",
+    summary="Delete instance",
+    description="Delete a tool instance and remove its Docker containers and files.",
+)
+async def delete_instance(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    force: bool = False,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+    try:
+        await delete_tool_instance(
+            session, user_id, project_id, repo_id, instance_id, force
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc))
+    except RuntimeError as exc:
+        detail = str(exc)
+        if "uncommitted changes" in detail.lower():
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail={
+                    "message": "Repository has uncommitted changes",
+                    "changed_files": detail,
+                    "force_required": True,
+                },
+            )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=detail
+        )

apps/api/src/api/tool/tool_types.py

@@ -1,14 +1,18 @@
 import uuid
 
-import yaml
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
-from src.models.tool_type import ToolType
+from src.api.tool.tool_types_validation import (
+    check_port_exposed,
+    validate_compose_yaml,
+    validate_required_variables,
+)
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
+from src.models import ToolType
 from src.models.user import User
-from src.schemas.tool_type import (
+from src.schemas.tool import (
     ToolTypeCreate,
     ToolTypeResponse,
     ToolTypeUpdate,
@@ -38,7 +42,7 @@ async def _require_admin(user: User) -> None:
 )
 async def create_tool_type(
     data: ToolTypeCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Create a new tool type.
@@ -51,6 +55,7 @@ async def create_tool_type(
     Returns:
         The newly created tool type.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
 
     # Check for duplicate name
@@ -67,13 +72,16 @@ async def create_tool_type(
         description=data.description,
         default_port=data.default_port,
         definition_type=data.definition_type,
+        manifest_id=data.manifest_id,
         compose_template=data.compose_template,
         dockerfile_template=data.dockerfile_template,
         build_context=data.build_context,
         readiness_probe=data.readiness_probe,
+        startup_command=data.startup_command,
         required_variables=data.required_variables,
         category=data.category,
-        interfaces=data.interfaces,
+        interface_type=data.interface_type,
+        requires_port=data.requires_port,
         created_by_id=user.id,
     )
     session.add(tool_type)
@@ -89,7 +97,7 @@ async def create_tool_type(
     description="List all available tool types including built-in and custom ones.",
 )
 async def list_tool_types(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[ToolType]:
     """List all tool types.
@@ -101,6 +109,7 @@ async def list_tool_types(
     Returns:
         List of all tool types ordered by name.
     """
+    await _get_user(session, user_id)
     result = await session.execute(select(ToolType).order_by(ToolType.name))
     return list(result.scalars().all())
 
@@ -113,7 +122,7 @@ async def list_tool_types(
 )
 async def get_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Get a specific tool type by ID.
@@ -126,6 +135,7 @@ async def get_tool_type(
     Returns:
         The requested tool type.
     """
+    await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(
@@ -143,7 +153,7 @@ async def get_tool_type(
 async def update_tool_type(
     tool_type_id: uuid.UUID,
     data: ToolTypeUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Update a tool type.
@@ -157,6 +167,7 @@ async def update_tool_type(
     Returns:
         The updated tool type.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
 
     tool_type = await session.get(ToolType, tool_type_id)
@@ -165,16 +176,13 @@ async def update_tool_type(
             status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
         )
 
-    if tool_type.is_builtin:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="cannot modify built-in tool types",
-        )
+    # Built-in tool types can now be modified
 
     update_data = data.model_dump(exclude_unset=True)
 
     # Validate port if being updated
-    if "default_port" in update_data:
+    requires_port = update_data.get("requires_port", tool_type.requires_port)
+    if "default_port" in update_data and requires_port:
         new_port = update_data["default_port"]
         if new_port <= 0 or new_port > 65535:
             raise HTTPException(
@@ -188,62 +196,35 @@ async def update_tool_type(
             template = update_data.get("compose_template", tool_type.compose_template)
             if template:
                 try:
-                    parsed = yaml.safe_load(template)
-                except yaml.YAMLError:
-                    parsed = None
-
-                if parsed and isinstance(parsed, dict) and "services" in parsed:
-                    port_str = str(new_port)
-                    port_exposed = False
-                    for service_config in parsed["services"].values():
-                        if (
-                            isinstance(service_config, dict)
-                            and "ports" in service_config
-                        ):
-                            for port_mapping in service_config["ports"]:
-                                if (
-                                    isinstance(port_mapping, str)
-                                    and port_str in port_mapping
-                                ):
-                                    port_exposed = True
-                                    break
-                                elif (
-                                    isinstance(port_mapping, int)
-                                    and port_mapping == new_port
-                                ):
-                                    port_exposed = True
-                                    break
-                        if port_exposed:
-                            break
-
-                    if not port_exposed:
+                    parsed = validate_compose_yaml(template)
+                    if not check_port_exposed(parsed, new_port):
                         raise HTTPException(
                             status_code=status.HTTP_400_BAD_REQUEST,
                             detail=f"Port {new_port} is not exposed in the compose template",
                         )
+                except ValueError as e:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)
+                    )
 
     # Validate required variables for compose definitions
     definition_type = update_data.get("definition_type", tool_type.definition_type)
     if definition_type == "compose":
         if "required_variables" in update_data and "compose_template" in update_data:
-            template = update_data["compose_template"]
-            for var in update_data["required_variables"]:
-                placeholder = f"{{{{{var}}}}}"
-                if placeholder not in template:
-                    raise HTTPException(
-                        status_code=status.HTTP_400_BAD_REQUEST,
-                        detail=f"Required variable '{var}' not found in compose template",
-                    )
+            validate_required_variables(
+                update_data["compose_template"], update_data["required_variables"]
+            )
         elif "required_variables" in update_data:
             template = tool_type.compose_template
             if template:
-                for var in update_data["required_variables"]:
-                    placeholder = f"{{{{{var}}}}}"
-                    if placeholder not in template:
-                        raise HTTPException(
-                            status_code=status.HTTP_400_BAD_REQUEST,
-                            detail=f"Required variable '{var}' not found in compose template",
-                        )
+                validate_required_variables(template, update_data["required_variables"])
+
+    # When switching to manifest, clear legacy templates
+    if definition_type == "manifest":
+        if "manifest_id" in update_data:
+            tool_type.manifest_id = update_data["manifest_id"]
+        tool_type.compose_template = None
+        tool_type.dockerfile_template = None
 
     for field, value in update_data.items():
         setattr(tool_type, field, value)
@@ -260,7 +241,7 @@ async def update_tool_type(
 )
 async def validate_tool_type_template(
     data: ToolTypeValidateRequest,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
     """Validate a tool type template syntax.
@@ -273,6 +254,7 @@ async def validate_tool_type_template(
     Returns:
         Validation result with success status and any errors.
     """
+    await _get_user(session, user_id)
 
     errors = []
 
@@ -281,15 +263,9 @@ async def validate_tool_type_template(
             errors.append("Compose template is required")
         else:
             try:
-                parsed = yaml.safe_load(data.compose_template)
-                if not isinstance(parsed, dict):
-                    errors.append("Compose template must be a YAML mapping")
-                elif "services" not in parsed:
-                    errors.append("Compose template must contain 'services' key")
-                elif not parsed["services"]:
-                    errors.append("Compose template must define at least one service")
-            except yaml.YAMLError as e:
-                errors.append(f"Invalid YAML: {e}")
+                validate_compose_yaml(data.compose_template)
+            except ValueError as e:
+                errors.append(str(e))
 
     elif data.definition_type == "dockerfile":
         if not data.dockerfile_template:
@@ -297,8 +273,11 @@ async def validate_tool_type_template(
         elif not data.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
 
+    elif data.definition_type == "manifest":
+        pass  # Manifest validation is handled separately
+
     else:
-        errors.append("definition_type must be 'compose' or 'dockerfile'")
+        errors.append("definition_type must be 'compose', 'dockerfile', or 'manifest'")
 
     return {
         "valid": len(errors) == 0,
@@ -313,7 +292,7 @@ async def validate_tool_type_template(
 )
 async def validate_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
     """Validate a tool type's template syntax.
@@ -326,6 +305,7 @@ async def validate_tool_type(
     Returns:
         Validation result with success status and any errors.
     """
+    await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(
@@ -339,15 +319,9 @@ async def validate_tool_type(
             errors.append("Compose template is empty")
         else:
             try:
-                parsed = yaml.safe_load(tool_type.compose_template)
-                if not isinstance(parsed, dict):
-                    errors.append("Compose template must be a YAML mapping")
-                elif "services" not in parsed:
-                    errors.append("Compose template must contain 'services' key")
-                elif not parsed["services"]:
-                    errors.append("Compose template must define at least one service")
-            except yaml.YAMLError as e:
-                errors.append(f"Invalid YAML: {e}")
+                validate_compose_yaml(tool_type.compose_template)
+            except ValueError as e:
+                errors.append(str(e))
 
     elif tool_type.definition_type == "dockerfile":
         if not tool_type.dockerfile_template:
@@ -355,6 +329,10 @@ async def validate_tool_type(
         elif not tool_type.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
 
+    elif tool_type.definition_type == "manifest":
+        if not tool_type.manifest_id:
+            errors.append("Manifest reference is missing")
+
     return {
         "valid": len(errors) == 0,
         "errors": errors,
@@ -369,7 +347,7 @@ async def validate_tool_type(
 )
 async def delete_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
     """Delete a tool type.
@@ -382,6 +360,7 @@ async def delete_tool_type(
     Returns:
         None with 204 status code.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
 
     tool_type = await session.get(ToolType, tool_type_id)
@@ -390,11 +369,7 @@ async def delete_tool_type(
             status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
         )
 
-    if tool_type.is_builtin:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="cannot delete built-in tool types",
-        )
+    # Built-in tool types can now be deleted
 
     await session.delete(tool_type)
     await session.commit()

apps/api/src/api/tool/tool_types_validation.py

@@ -60,8 +60,14 @@ def check_port_exposed(parsed: dict, port: int) -> bool:
     for service_config in parsed["services"].values():
         if isinstance(service_config, dict) and "ports" in service_config:
             for port_mapping in service_config["ports"]:
-                if isinstance(port_mapping, str) and port_str in port_mapping:
-                    return True
+                if isinstance(port_mapping, str):
+                    # Port mappings can be "host:container", "ip:host:container",
+                    # "container", or ".../protocol". The container port is the
+                    # last numeric segment before any protocol suffix.
+                    mapping = port_mapping.split("/")[0]
+                    parts = mapping.split(":")
+                    if parts[-1] == port_str:
+                        return True
                 elif isinstance(port_mapping, int) and port_mapping == port:
                     return True
 

apps/api/src/api/tool_instances.py

@@ -1,286 +0,0 @@
-"""Tool instance API endpoints."""
-
-import logging
-import uuid
-
-import httpx
-from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.auth.dependencies import get_current_user, get_db_session, get_owned_project
-from src.models.git_repository import GitRepository
-from src.models.project import Project
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
-from src.models.user import User
-from src.schemas.tool_instance import CreateInstanceRequest
-from src.services import instance_lifecycle as lifecycle
-from src.services.docker import container as container_svc
-from src.services.docker import tunnel as tunnel_svc
-
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/projects", tags=["tool-instances"])
-async def _get_instance(session: AsyncSession, instance_id: uuid.UUID, repo_id: uuid.UUID) -> ToolInstance:
-    instance = await session.get(ToolInstance, instance_id)
-    if instance is None or instance.repository_id != repo_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="instance not found")
-    return instance
-async def _get_repo(session: AsyncSession, repo_id: uuid.UUID, project_id: uuid.UUID) -> GitRepository:
-    repo = await session.get(GitRepository, repo_id)
-    if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
-    return repo
-# ── Endpoints ──────────────────────────────────────────────────────────────
-
-@router.post("/{project_id}/repositories/{repo_id}/instances")
-async def create_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: CreateInstanceRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Create a new tool instance."""
-    repo = await _get_repo(session, repo_id, project_id)
-    tool_type = await session.get(ToolType, uuid.UUID(data.tool_type_id))
-    if tool_type is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-
-    selected_profile = None
-    if data.config_profile_id:
-        from src.models.config_profile import ConfigProfile
-        selected_profile = await session.get(ConfigProfile, uuid.UUID(data.config_profile_id))
-        if selected_profile is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config profile not found")
-        if selected_profile.user_id != user.id:
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="config profile does not belong to user")
-
-    instance = await lifecycle.create_new_instance(
-        session, project, repo, tool_type, user, data.display_name, selected_profile,
-        ssh_key_ids=data.ssh_key_ids or None,
-    )
-    return {
-        "id": str(instance.id),
-        "name": instance.name,
-        "display_name": instance.display_name,
-        "tool_type_id": str(instance.tool_type_id),
-        "status": instance.status,
-        "config_profile_id": str(instance.selected_profile_id) if instance.selected_profile_id else None,
-        "ssh_key_ids": instance.ssh_key_ids or [],
-        "created_at": instance.created_at.isoformat(),
-    }
-@router.get("/{project_id}/repositories/{repo_id}/instances")
-async def list_instances(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """List all tool instances for a repository."""
-    await _get_repo(session, repo_id, project_id)
-    from sqlalchemy import select
-    result = await session.execute(
-        select(ToolInstance)
-        .where(ToolInstance.repository_id == repo_id, ToolInstance.owner_id == user.id)
-        .order_by(ToolInstance.created_at.desc())
-    )
-    instances = []
-    for i in result.scalars().all():
-        tt = await session.get(ToolType, i.tool_type_id)
-        instances.append({
-            "id": str(i.id), "name": i.name, "display_name": i.display_name,
-            "tool_type_id": str(i.tool_type_id), "tool_type_name": tt.name if tt else "unknown",
-            "tool_type_interfaces": tt.interfaces if tt else [],
-            "status": i.status, "url": i.url, "port": i.port,
-            "config_profile_id": str(i.selected_profile_id) if i.selected_profile_id else None,
-            "created_at": i.created_at.isoformat(),
-        })
-    return {"instances": instances}
-@router.get("/{project_id}/repositories/{repo_id}/instances/{instance_id}")
-async def get_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Get a specific instance with real-time Docker status."""
-    from datetime import datetime
-    instance = await _get_instance(session, instance_id, repo_id)
-    if instance.container_id:
-        docker_status = container_svc.get_container_status(instance.container_id)
-        if docker_status == "running" and instance.status != "running":
-            instance.status = "running"
-            await session.commit()
-        elif docker_status == "exited" and instance.status == "running":
-            instance.status = "stopped"
-            instance.last_stopped_at = datetime.now()
-            await session.commit()
-    return {
-        "id": str(instance.id), "name": instance.name, "display_name": instance.display_name,
-        "tool_type_id": str(instance.tool_type_id), "status": instance.status,
-        "container_id": instance.container_id, "compose_path": instance.compose_path,
-        "url": instance.url, "port": instance.port,
-        "config_profile_id": str(instance.selected_profile_id) if instance.selected_profile_id else None,
-        "last_started_at": instance.last_started_at.isoformat() if instance.last_started_at else None,
-        "last_stopped_at": instance.last_stopped_at.isoformat() if instance.last_stopped_at else None,
-        "created_at": instance.created_at.isoformat(),
-    }
-@router.post("/{project_id}/repositories/{repo_id}/instances/{instance_id}/start")
-async def start_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Start a tool instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    return await lifecycle.start_existing_instance(session, instance, user, project_id)
-@router.post("/{project_id}/repositories/{repo_id}/instances/{instance_id}/stop")
-async def stop_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Stop a running tool instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    await lifecycle.stop_existing_instance(session, instance)
-    return {"status": instance.status}
-@router.post("/{project_id}/repositories/{repo_id}/instances/{instance_id}/restart")
-async def restart_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Restart a tool instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    return await lifecycle.restart_existing_instance(session, instance, user, project_id)
-@router.delete("/{project_id}/repositories/{repo_id}/instances/{instance_id}")
-async def delete_instance(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    """Delete a tool instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    await lifecycle.delete_existing_instance(session, instance)
-@router.get("/{project_id}/repositories/{repo_id}/instances/{instance_id}/logs")
-async def get_instance_logs(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    tail: int = 100,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Get container logs for an instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    if not instance.container_id:
-        return {"logs": "No container running"}
-    return {"logs": container_svc.get_container_logs(instance.container_id, tail)}
-@router.post("/{project_id}/repositories/{repo_id}/instances/{instance_id}/recreate-tunnel")
-async def recreate_tunnel_endpoint(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Recreate the temporary tunnel for an instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    if instance.status != "running":
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="instance must be running")
-
-    tool_type = await session.get(ToolType, instance.tool_type_id)
-    instance_port = tool_type.default_port if tool_type and tool_type.default_port else 8080
-
-    try:
-        tunnel_info = tunnel_svc.recreate_tunnel(
-            container_name=instance.container_name or instance.name,
-            port=instance_port,
-            old_pid=instance.tunnel_id,
-        )
-        instance.tunnel_id = tunnel_info["pid"]
-        instance.public_url = tunnel_info["url"]
-        instance.url = tunnel_info["url"]
-        await session.commit()
-        return {"status": "healthy", "url": instance.url}
-    except Exception as exc:
-        logger.exception("Failed to recreate tunnel")
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to recreate tunnel: {exc}")
-@router.get("/{project_id}/repositories/{repo_id}/instances/{instance_id}/health")
-async def check_instance_tunnel_health(
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    """Check tunnel health for an instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    if not instance.url or instance.status != "running":
-        return {"healthy": False, "status_code": None, "error": "instance not running"}
-    return tunnel_svc.check_tunnel_health(instance.url)
-@router.api_route(
-    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/proxy/{path:path}",
-    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
-)
-async def proxy_to_instance(
-    request: Request,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    instance_id: uuid.UUID,
-    path: str = "",
-    user: User = Depends(get_current_user),
-    session: AsyncSession = Depends(get_db_session),
-) -> Response:
-    """Proxy HTTP requests to a running tool instance."""
-    instance = await _get_instance(session, instance_id, repo_id)
-    if instance.owner_id != user.id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="not authorized")
-    if instance.status != "running" or not instance.container_name:
-        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="instance is not running")
-
-    target_url = f"http://{instance.container_name}:{instance.port}"
-    if path:
-        target_url += f"/{path}"
-    query = str(request.query_params)
-    if query:
-        target_url += f"?{query}"
-
-    headers = dict(request.headers)
-    headers.pop("host", None)
-    headers.pop("cookie", None)
-
-    try:
-        async with httpx.AsyncClient() as client:
-            body = await request.body()
-            response = await client.request(
-                method=request.method, url=target_url, headers=headers,
-                content=body, follow_redirects=False, timeout=30.0,
-            )
-    except Exception as exc:
-        logger.error("Proxy error: %s", exc)
-        raise HTTPException(status_code=status.HTTP_502_BAD_GATEWAY, detail=f"failed to reach instance: {exc}")
-
-    resp_headers = dict(response.headers)
-    for h in ["content-encoding", "transfer-encoding", "connection"]:
-        resp_headers.pop(h, None)
-    return Response(content=response.content, status_code=response.status_code, headers=resp_headers)

apps/api/src/api/user/.pi-map.index.md

@@ -0,0 +1,23 @@
+# apps/api/src/api/user (index)
+dir: apps/api/src/api/user
+
+## role
+Provides authentication, user profile management, and SSH key operations for the API backend.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- auth.py
+- ssh_keys.py
+- users.py
+## links
+index: apps/api/src/api/user/.pi-map.index.md
+map: apps/api/src/api/user/.pi-map.md
+## workflows
+- change user behavior
+  read: __init__.py, auth.py, ssh_keys.py
+## dirty
+-

apps/api/src/api/user/.pi-map.md

@@ -0,0 +1,30 @@
+# apps/api/src/api/user
+dir: apps/api/src/api/user
+
+index: apps/api/src/api/user/.pi-map.index.md
+
+## role
+Provides authentication, user profile management, and SSH key operations for the API backend.
+## files
+- __init__.py | Aggregates and exports user-related API routers from submodules for easy importing | dep: src.api.user.auth, src.api.user.ssh_keys, src.api.user.users
+- auth.py | Implements OAuth2/OIDC authentication endpoints for a FastAPI application using Authentik as the identity provider, including login initiation, callback handling, logout, and current user retrieval. | exp: func:get_db_session() → AsyncGenerator[AsyncSession, None], call:SessionLocal, func:login(next) → RedirectResponse, call:Settings, call:token_urlsafe, call:build_login_redirect_url, call:logger.debug, call:RedirectResponse, call:response.set_cookie, func:callback(code: str, state: str, auth_state, auth_next, session) → RedirectResponse, call:logger.debug, call:logger.warning, call:Settings, call:httpx.AsyncClient, call:exchange_code_for_tokens, call:logger.info, call:logger.error, call:fetch_user_info, call:str, call:user_info.get, call:session.scalar, call:select(User).where, call:User, call:session.add, call:session.commit, call:session.refresh, call:create_session_cookie, call:build_cookie_options, call:cast, call:bool, call:cookie_options.get, call:RedirectResponse, call:redirect_response.set_cookie, call:redirect_response.delete_cookie, raise:HTTPException, func:logout(response: Response) → dict[str, str], call:Settings, call:build_cookie_options, call:cast, call:bool, call:str, call:cookie_options.get, call:response.delete_cookie, func:me(session_cookie, session) → dict[str, Any], call:logger.debug, call:bool, call:logger.warning, call:Settings, call:decode_session_cookie, call:session.get, call:logger.info, call:str, raise:HTTPException | dep: logging, secrets, typing, httpx, fastapi, fastapi.responses, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.cookies, src.auth.oidc, src.auth.session, src.config, src.database, src.models.user
+- ssh_keys.py | Implements a FastAPI router for managing Ed25519 SSH key pairs, including generation, storage with encrypted private keys, listing, deletion, and cryptographic signing/verification operations. | exp: func:_get_fernet() → Fernet, call:Settings, call:hashlib.sha256(settings.session_secret.encode()).digest, call:settings.session_secret.encode, call:base64.urlsafe_b64encode, call:Fernet, func:generate_ssh_key_pair() → tuple[str, str], call:Ed25519PrivateKey.generate, call:private_key.public_key, call:private_key.private_bytes, call:serialization.NoEncryption, call:public_key.public_bytes, call:private_bytes.decode, call:public_bytes.decode, func:create_ssh_key(data: SSHKeyCreate, user_id, session) → SSHKey, call:_get_user, call:generate_ssh_key_pair, call:_get_fernet, call:fernet.encrypt(private_key.encode()).decode, call:private_key.encode, call:SSHKey, call:session.add, call:session.commit, call:session.refresh, func:list_ssh_keys(user_id, session) → list[SSHKey], call:_get_user, call:session.execute, call:select(SSHKey).where, call:list, call:result.scalars().all, func:delete_ssh_key(key_id: uuid.UUID, user_id, session) → None, call:_get_user, call:session.get, call:session.delete, call:session.commit, raise:HTTPException, func:sign_payload(key_id: uuid.UUID, data: SignPayloadRequest, user_id, session) → SignatureResponse, call:_get_user, call:session.get, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:serialization.load_ssh_private_key, call:private_key_pem.encode, call:private_key.sign, call:data.payload.encode, call:SignatureResponse, call:base64.b64encode(signature).decode, raise:HTTPException, func:verify_signature(key_id: uuid.UUID, data: VerifySignatureRequest, user_id, session) → VerifySignatureResponse, call:_get_user, call:session.get, call:serialization.load_ssh_public_key, call:ssh_key.public_key.encode, call:base64.b64decode, call:public_key.verify, call:data.payload.encode, call:VerifySignatureResponse, raise:HTTPException | dep: base64, uuid, cryptography.fernet, cryptography.hazmat.primitives, cryptography.hazmat.primitives.asymmetric.ed25519, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.config, src.models, src.schemas.project, hashlib, cryptography
+- users.py | Implements FastAPI endpoints for authenticated user profile management including retrieval, updates, and avatar uploads. | exp: func:get_profile(user_id, session) → User, call:_get_user, func:update_profile(data: UserProfileUpdate, user_id, session) → User, call:_get_user, call:len, call:data.name.strip, call:data.email.strip, call:session.commit, call:session.refresh, raise:HTTPException, func:upload_avatar(file: UploadFile, user_id, session) → User, call:_get_user, call:file.read, call:len, call:Path, call:old_path.exists, call:old_path.unlink, call:filename_part.split(".")[-1].lower, call:uuid.uuid4, call:file_path.write_bytes, call:session.commit, call:session.refresh, raise:HTTPException | dep: uuid, pathlib, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.schemas.user
+## arch
+Modular FastAPI router pattern with OAuth2/OIDC external identity provider integration, encrypted key storage, and file-based avatar handling.
+## tags
+user, get, call:, key, ssh, src, cookie, raise:httpexception
+## symbols
+- get_db_session
+- login
+- callback
+- logout
+- me
+- _get_fernet
+- generate_ssh_key_pair
+- create_ssh_key
+## workflows
+- change user behavior
+  read: __init__.py, auth.py, ssh_keys.py
+## dirty
+-

apps/api/src/api/user/__init__.py

@@ -0,0 +1,7 @@
+"""User API routers module."""
+
+from src.api.user.auth import router as auth_router
+from src.api.user.ssh_keys import router as ssh_keys_router
+from src.api.user.users import router as users_router
+
+__all__ = ["auth_router", "ssh_keys_router", "users_router"]

apps/api/src/api/user/ssh_keys.py

@@ -1,5 +1,5 @@
+import base64
 import uuid
-from datetime import datetime
 
 from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import serialization
@@ -8,21 +8,26 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
 from src.config import Settings
-from src.models.ssh_key import SSHKey
-from src.models.user import User
-from src.schemas.ssh_key import SSHKeyCreate, SSHKeyResponse
+from src.models import SSHKey
+from src.schemas.project import (
+    SSHKeyCreate,
+    SSHKeyResponse,
+    SignPayloadRequest,
+    SignatureResponse,
+    VerifySignatureRequest,
+    VerifySignatureResponse,
+)
 
 router = APIRouter(prefix="/ssh-keys", tags=["ssh-keys"])
 
 
-
 def _get_fernet() -> Fernet:
     """Generate a valid Fernet key from the session secret."""
     import base64
     import hashlib
-    
+
     settings = Settings()
     # Derive a 32-byte key from the session secret using SHA256
     key_bytes = hashlib.sha256(settings.session_secret.encode()).digest()
@@ -63,7 +68,7 @@ def generate_ssh_key_pair() -> tuple[str, str]:
 )
 async def create_ssh_key(
     data: SSHKeyCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> SSHKey:
     """Create a new SSH key pair.
@@ -76,6 +81,7 @@ async def create_ssh_key(
     Returns:
         The newly created SSH key with public key exposed.
     """
+    user = await _get_user(session, user_id)
     private_key, public_key = generate_ssh_key_pair()
 
     fernet = _get_fernet()
@@ -100,7 +106,7 @@ async def create_ssh_key(
     description="List all SSH keys for the authenticated user.",
 )
 async def list_ssh_keys(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[SSHKey]:
     """List all SSH keys for the authenticated user.
@@ -112,6 +118,7 @@ async def list_ssh_keys(
     Returns:
         List of SSH keys owned by the user.
     """
+    user = await _get_user(session, user_id)
     result = await session.execute(select(SSHKey).where(SSHKey.user_id == user.id))
     return list(result.scalars().all())
 
@@ -124,7 +131,7 @@ async def list_ssh_keys(
 )
 async def delete_ssh_key(
     key_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
     """Delete an SSH key.
@@ -137,9 +144,93 @@ async def delete_ssh_key(
     Returns:
         None with 204 status code.
     """
+    user = await _get_user(session, user_id)
     ssh_key = await session.get(SSHKey, key_id)
     if ssh_key is None or ssh_key.user_id != user.id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
 
     await session.delete(ssh_key)
     await session.commit()
+
+
+@router.post(
+    "/{key_id}/sign",
+    response_model=SignatureResponse,
+    summary="Sign payload",
+    description="Sign a payload using the SSH private key.",
+)
+async def sign_payload(
+    key_id: uuid.UUID,
+    data: SignPayloadRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> SignatureResponse:
+    """Sign a payload with an SSH key.
+
+    Args:
+        key_id: UUID of the SSH key to use for signing.
+        data: Sign request containing the payload string.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Base64-encoded Ed25519 signature.
+    """
+    user = await _get_user(session, user_id)
+    ssh_key = await session.get(SSHKey, key_id)
+    if ssh_key is None or ssh_key.user_id != user.id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
+
+    fernet = _get_fernet()
+    private_key_pem = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
+
+    private_key = serialization.load_ssh_private_key(
+        private_key_pem.encode(), password=None
+    )
+
+    signature = private_key.sign(data.payload.encode())
+    return SignatureResponse(signature=base64.b64encode(signature).decode())
+
+
+@router.post(
+    "/{key_id}/verify",
+    response_model=VerifySignatureResponse,
+    summary="Verify signature",
+    description="Verify a signature against a payload using the SSH public key.",
+)
+async def verify_signature(
+    key_id: uuid.UUID,
+    data: VerifySignatureRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> VerifySignatureResponse:
+    """Verify a signature with an SSH key's public key.
+
+    Args:
+        key_id: UUID of the SSH key to use for verification.
+        data: Verify request containing payload and base64-encoded signature.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Whether the signature is valid.
+    """
+    user = await _get_user(session, user_id)
+    ssh_key = await session.get(SSHKey, key_id)
+    if ssh_key is None or ssh_key.user_id != user.id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
+
+    public_key = serialization.load_ssh_public_key(ssh_key.public_key.encode())
+
+    try:
+        signature = base64.b64decode(data.signature)
+        public_key.verify(signature, data.payload.encode())
+        return VerifySignatureResponse(valid=True)
+    except Exception:
+        return VerifySignatureResponse(valid=False)

apps/api/src/api/user/users.py

@@ -2,13 +2,10 @@ import uuid
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
-from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
-from src.models.tool_instance import ToolInstance
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
 from src.models.user import User
-from src.schemas.tool_instance import SessionItemResponse, SessionListResponse
 from src.schemas.user import UserProfileResponse, UserProfileUpdate
 
 router = APIRouter(prefix="/users", tags=["users"])
@@ -26,7 +23,7 @@ MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
     description="Retrieve the profile of the currently authenticated user.",
 )
 async def get_profile(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Get the current user's profile.
@@ -38,7 +35,7 @@ async def get_profile(
     Returns:
         The user's profile information.
     """
-    return user
+    return await _get_user(session, user_id)
 
 
 @router.put(
@@ -49,7 +46,7 @@ async def get_profile(
 )
 async def update_profile(
     data: UserProfileUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Update the current user's profile.
@@ -62,6 +59,7 @@ async def update_profile(
     Returns:
         The updated user profile.
     """
+    user = await _get_user(session, user_id)
 
     if data.name is not None:
         if len(data.name.strip()) == 0:
@@ -90,7 +88,7 @@ async def update_profile(
 )
 async def upload_avatar(
     file: UploadFile,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Upload a profile avatar image.
@@ -103,6 +101,7 @@ async def upload_avatar(
     Returns:
         The updated user profile with new avatar URL.
     """
+    user = await _get_user(session, user_id)
 
     if file.content_type not in ALLOWED_CONTENT_TYPES:
         raise HTTPException(
@@ -137,41 +136,3 @@ async def upload_avatar(
     await session.commit()
     await session.refresh(user)
     return user
-
-
-@router.get(
-    "/me/sessions",
-    response_model=SessionListResponse,
-    summary="Get current user sessions",
-    description="Retrieve all tool instances (sessions) for the authenticated user.",
-)
-async def get_user_sessions(
-    user: User = Depends(get_current_user),
-    session: AsyncSession = Depends(get_db_session),
-) -> SessionListResponse:
-    """Return all tool instances for the current user with related names."""
-    result = await session.execute(
-        select(ToolInstance)
-        .where(ToolInstance.owner_id == user.id)
-        .order_by(ToolInstance.created_at.desc())
-    )
-    instances = result.scalars().all()
-
-    sessions = [
-        SessionItemResponse(
-            id=str(inst.id),
-            display_name=inst.display_name,
-            tool_type_name=inst.tool_type.display_name if inst.tool_type else "Unknown",
-            tool_icon=None,
-            tool_type_interfaces=inst.tool_type.interfaces if inst.tool_type else [],
-            repository_name=inst.repository.name if inst.repository else "Unknown",
-            repository_id=str(inst.repository_id),
-            project_name=inst.project.name if inst.project else "Unknown",
-            project_id=str(inst.project_id),
-            status=inst.status,
-            url=inst.url,
-        )
-        for inst in instances
-    ]
-
-    return SessionListResponse(sessions=sessions)

apps/api/src/api/workspace/.pi-map.index.md

@@ -0,0 +1,24 @@
+# apps/api/src/api/workspace (index)
+dir: apps/api/src/api/workspace
+
+## role
+Provides FastAPI REST endpoints for workspace management, file operations, git integration, and tool instance management within user workspaces.
+## parent
+index: apps/api/src/api/.pi-map.index.md
+map: apps/api/src/api/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- workspace_files.py
+- workspace_git.py
+- workspace_instances.py
+- workspaces.py
+## links
+index: apps/api/src/api/workspace/.pi-map.index.md
+map: apps/api/src/api/workspace/.pi-map.md
+## workflows
+- change workspace behavior
+  read: __init__.py, workspace_files.py, workspace_git.py
+## dirty
+-

apps/api/src/api/workspace/.pi-map.md

@@ -0,0 +1,31 @@
+# apps/api/src/api/workspace
+dir: apps/api/src/api/workspace
+
+index: apps/api/src/api/workspace/.pi-map.index.md
+
+## role
+Provides FastAPI REST endpoints for workspace management, file operations, git integration, and tool instance management within user workspaces.
+## files
+- __init__.py | Aggregates and re-exports workspace API router modules for centralized access | dep: src.api.workspace.workspace_files, src.api.workspace.workspace_git, src.api.workspace.workspace_instances, src.api.workspace.workspaces
+- workspace_files.py | Provides FastAPI endpoints for listing, reading, and writing files within user workspaces with optional git commit integration. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:list_files(workspace_id: uuid.UUID, path, user_id, session) → dict, call:_get_workspace, call:FileService, call:service.list_directory, raise:HTTPException, func:get_file_content(workspace_id: uuid.UUID, path: str, user_id, session) → dict, call:_get_workspace, call:FileService, call:service.read_file, raise:HTTPException, func:write_file(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:FileService, call:data.get("path", "").strip, call:data.get("message", "").strip, call:service.write_file, call:GitOperations, call:git.commit, raise:HTTPException | dep: uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.shared.file_service, sqlalchemy, src.services.git.git_operations
+- workspace_git.py | Provides FastAPI REST endpoints for git operations (status, branches, commit, push, pull, fetch, checkout, history) scoped to user workspaces. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:git_status(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.status, raise:HTTPException, func:git_branches(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.branches, raise:HTTPException, func:git_commit(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:data.get("message", "").strip, call:GitOperations, call:git.commit, raise:HTTPException, func:git_push(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.push, raise:HTTPException, func:git_pull(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.pull, raise:HTTPException, func:git_fetch(workspace_id: uuid.UUID, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.fetch, raise:HTTPException, func:git_checkout(workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_workspace, call:data.get("branch", "").strip, call:GitOperations, call:git.checkout, call:session.commit, raise:HTTPException, func:git_history(workspace_id: uuid.UUID, path, limit, user_id, session) → dict, call:_get_workspace, call:GitOperations, call:git.history, raise:HTTPException | dep: uuid, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.services.git.git_operations, sqlalchemy
+- workspace_instances.py | FastAPI router providing endpoints to create and list tool instances associated with a specific workspace. | exp: func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, user_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException, func:create_workspace_instance(workspace_id: uuid.UUID, data: CreateWorkspaceInstanceRequest, user_id, session) → dict, call:_get_workspace, call:session.get, call:CreateInstanceRequest, call:str, call:create_tool_instance, call:instance.created_at.isoformat, raise:HTTPException, func:list_workspace_instances(workspace_id: uuid.UUID, user_id, session) → list[dict], call:_get_workspace, call:session.execute, call:select(ToolInstance) .where(ToolInstance.workspace_id == workspace_id) .order_by, call:ToolInstance.created_at.desc, call:result.scalars().all, call:str, call:i.created_at.isoformat | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.schemas.tool, src.services.tool.instance_service
+- workspaces.py | FastAPI router providing CRUD endpoints for workspace management with nested and top-level URL structures, including listing, creating, updating, deleting, and syncing workspaces tied to Git repositories. | exp: func:list_all_workspaces(user_id, session) → list[dict], call:select(func.count(ToolInstance.id)) .where(ToolInstance.workspace_id == Workspace.id) .correlate(Workspace) .scalar_subquery, call:func.count, call:session.execute, call:select( Workspace, GitRepository, instance_count.label("instance_count"), ) .join(GitRepository, Workspace.repo_id == GitRepository.id) .options(selectinload(GitRepository.project)) .where(Workspace.user_id == user_id) .order_by, call:instance_count.label, call:selectinload, call:Workspace.created_at.desc, call:result.all, call:str, call:ws.last_sync_at.isoformat, call:ws.created_at.isoformat, call:ws.updated_at.isoformat, func:delete_workspace_top_level(workspace_id: uuid.UUID, force, user_id, session) → dict, call:session.get, call:WorkspaceManager, call:manager.delete, call:session.commit, call:session.rollback, call:logger.error, raise:HTTPException, func:create_workspace_top_level(data: dict, user_id, session) → dict, call:data.get("repo_id", "").strip, call:uuid.UUID, call:session.get, call:data.get("name", "").strip, call:data.get("branch", "main").strip, call:WorkspaceManager, call:manager.create, call:session.add, call:session.commit, call:session.rollback, call:logger.error, call:session.refresh, call:str, call:workspace.created_at.isoformat, raise:HTTPException, func:list_workspaces(project_id: uuid.UUID, repo_id: uuid.UUID, user_id, session) → list[dict], call:_get_repo, call:select(func.count(ToolInstance.id)) .where(ToolInstance.workspace_id == Workspace.id) .correlate(Workspace) .scalar_subquery, call:func.count, call:session.execute, call:select( Workspace, instance_count.label("instance_count"), ) .where(Workspace.repo_id == repo_id) .order_by, call:instance_count.label, call:Workspace.created_at.desc, call:result.all, call:str, call:ws.last_sync_at.isoformat, call:ws.created_at.isoformat, call:ws.updated_at.isoformat, func:create_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_repo, call:data.get("name", "").strip, call:data.get("branch", "main").strip, call:WorkspaceManager, call:manager.create, call:session.add, call:session.commit, call:session.rollback, call:logger.error, call:session.refresh, call:str, call:workspace.created_at.isoformat, raise:HTTPException, func:get_workspace_detail(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:session.execute, call:select(func.count(ToolInstance.id)).where, call:func.count, call:result.scalar, call:str, call:workspace.last_sync_at.isoformat, call:workspace.created_at.isoformat, call:workspace.updated_at.isoformat, func:update_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, data: dict, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:data.get("name", "").strip, call:data.get("branch", "").strip, call:session.commit, call:session.rollback, call:logger.error, call:str, raise:HTTPException, func:delete_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, force, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:WorkspaceManager, call:manager.delete, call:session.commit, call:session.rollback, call:logger.error, raise:HTTPException, func:sync_workspace(project_id: uuid.UUID, repo_id: uuid.UUID, workspace_id: uuid.UUID, user_id, session) → dict, call:_get_repo, call:_get_workspace, call:WorkspaceManager, call:manager.sync, call:session.commit, call:workspace.last_sync_at.isoformat, raise:HTTPException, func:_get_repo(session: AsyncSession, repo_id: uuid.UUID, project_id: uuid.UUID, user_id: uuid.UUID) → GitRepository, call:session.execute, call:select(GitRepository) .where( GitRepository.id == repo_id, GitRepository.project_id == project_id, ) .options, call:selectinload, call:result.scalar_one_or_none, raise:HTTPException, func:_get_workspace(session: AsyncSession, workspace_id: uuid.UUID, repo_id: uuid.UUID) → Workspace, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, raise:HTTPException | dep: logging, uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.auth.dependencies, src.models, src.services.shared.workspace_manager
+## arch
+Modular FastAPI router pattern with domain-driven separation (files, git, instances, workspaces) using nested URL structures and git-backed workspace synchronization.
+## tags
+workspace, get, raise:httpexception, call:, at.isoformat, git, call:select, call:data.get
+## symbols
+- _get_workspace
+- list_files
+- get_file_content
+- write_file
+- git_status
+- git_branches
+- git_commit
+- git_push
+## workflows
+- change workspace behavior
+  read: __init__.py, workspace_files.py, workspace_git.py
+## dirty
+-

apps/api/src/api/workspace/__init__.py

@@ -0,0 +1,17 @@
+"""Workspace API routers module."""
+
+from src.api.workspace.workspace_files import router as workspace_files_router
+from src.api.workspace.workspace_git import router as workspace_git_router
+from src.api.workspace.workspace_instances import router as workspace_instances_router
+from src.api.workspace.workspaces import (
+    all_workspaces_router,
+    router as workspaces_router,
+)
+
+__all__ = [
+    "all_workspaces_router",
+    "workspace_files_router",
+    "workspace_git_router",
+    "workspace_instances_router",
+    "workspaces_router",
+]

apps/api/src/api/workspace/workspace_files.py

@@ -6,8 +6,8 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.workspace import Workspace
-from src.services.file_service import FileService
+from src.models import Workspace
+from src.services.shared.file_service import FileService
 
 router = APIRouter(prefix="/workspaces/{workspace_id}/files")
 
@@ -103,7 +103,7 @@ async def write_file(
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
     if commit_message:
-        from src.services.git_operations import GitOperations
+        from src.services.git.git_operations import GitOperations
 
         git = GitOperations(workspace)
         try:

apps/api/src/api/workspace/workspace_git.py

@@ -6,8 +6,8 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.workspace import Workspace
-from src.services.git_operations import GitOperations
+from src.models import Workspace
+from src.services.git.git_operations import GitOperations
 
 router = APIRouter(prefix="/workspaces/{workspace_id}/git")
 

apps/api/src/api/workspace/workspace_instances.py

@@ -0,0 +1,120 @@
+"""Workspace instance API endpoints."""
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models import GitRepository
+from src.models import ToolInstance
+from src.models import Workspace
+from src.schemas.tool import CreateInstanceRequest, CreateWorkspaceInstanceRequest
+from src.services.tool.instance_service import create_tool_instance
+
+router = APIRouter(prefix="/workspaces/{workspace_id}/instances")
+
+
+async def _get_workspace(
+    session: AsyncSession,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> Workspace:
+    result = await session.execute(
+        select(Workspace).where(
+            Workspace.id == workspace_id,
+            Workspace.user_id == user_id,
+        )
+    )
+    workspace = result.scalar_one_or_none()
+    if not workspace:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    return workspace
+
+
+@router.post(
+    "/",
+    summary="Create instance from workspace",
+    description="Create a new tool instance mounted on this workspace.",
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_workspace_instance(
+    workspace_id: uuid.UUID,
+    data: CreateWorkspaceInstanceRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a tool instance directly on a workspace."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+
+    repo = await session.get(GitRepository, workspace.repo_id)
+    if repo is None:
+        raise HTTPException(status_code=404, detail="Repository not found")
+    if repo.project_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Repository is not associated with a project",
+        )
+
+    request = CreateInstanceRequest(
+        tool_type_id=data.tool_type_id,
+        display_name=data.display_name,
+        workspace_id=str(workspace.id),
+        config_profile_id=data.config_profile_id,
+        ssh_key_ids=data.ssh_key_ids,
+    )
+
+    try:
+        instance = await create_tool_instance(
+            session, user_id, repo.project_id, repo.id, request
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc))
+    except RuntimeError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(exc)
+        )
+
+    return {
+        "id": str(instance.id),
+        "name": instance.name,
+        "display_name": instance.display_name,
+        "tool_type_id": str(instance.tool_type_id),
+        "status": instance.status,
+        "workspace_id": str(instance.workspace_id) if instance.workspace_id else None,
+        "selected_config_profile_id": str(instance.selected_config_profile_id)
+        if instance.selected_config_profile_id
+        else None,
+        "created_at": instance.created_at.isoformat(),
+    }
+
+
+@router.get("/")
+async def list_workspace_instances(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    """List tool instances using this workspace."""
+    await _get_workspace(session, workspace_id, user_id)
+    result = await session.execute(
+        select(ToolInstance)
+        .where(ToolInstance.workspace_id == workspace_id)
+        .order_by(ToolInstance.created_at.desc())
+    )
+    instances = result.scalars().all()
+
+    return [
+        {
+            "id": str(i.id),
+            "name": i.name,
+            "display_name": i.display_name,
+            "status": i.status,
+            "tool_type_id": str(i.tool_type_id),
+            "url": i.url,
+            "port": i.port,
+            "created_at": i.created_at.isoformat() if i.created_at else None,
+        }
+        for i in instances
+    ]

apps/api/src/api/workspace/workspaces.py

@@ -9,10 +9,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.git_repository import GitRepository
-from src.models.tool_instance import ToolInstance
-from src.models.workspace import Workspace
-from src.services.workspace_manager import WorkspaceHasInstancesError, WorkspaceManager
+from src.models import GitRepository
+from src.models import ToolInstance
+from src.models import Workspace
+from src.services.shared.workspace_manager import WorkspaceHasInstancesError, WorkspaceManager
 
 logger = logging.getLogger(__name__)
 
@@ -36,12 +36,11 @@ async def list_all_workspaces(
     result = await session.execute(
         select(
             Workspace,
-            GitRepository.name.label("repo_name"),
-            GitRepository.project_id,
-            GitRepository.ssh_key_id.label("repo_ssh_key_id"),
+            GitRepository,
             instance_count.label("instance_count"),
         )
         .join(GitRepository, Workspace.repo_id == GitRepository.id)
+        .options(selectinload(GitRepository.project))
         .where(Workspace.user_id == user_id)
         .order_by(Workspace.created_at.desc())
     )
@@ -51,11 +50,11 @@ async def list_all_workspaces(
         {
             "id": str(ws.id),
             "name": ws.name,
-            "repo_id": str(ws.repo_id),
-            "repo_name": repo_name or "",
-            "repo_ssh_key_id": str(ssh_key_id) if ssh_key_id else None,
-            "project_id": str(project_id) if project_id else "",
-            "project_name": "",
+            "repo_id": str(repo.id),
+            "repo_name": repo.name or "",
+            "repo_ssh_key_id": str(repo.ssh_key_id) if repo.ssh_key_id else None,
+            "project_id": str(repo.project_id) if repo.project_id else "",
+            "project_name": repo.project.name if repo.project else "",
             "user_id": str(ws.user_id),
             "branch": ws.branch,
             "path": ws.path,
@@ -65,7 +64,7 @@ async def list_all_workspaces(
             "updated_at": ws.updated_at.isoformat() if ws.updated_at else None,
             "instance_count": count or 0,
         }
-        for ws, repo_name, project_id, ssh_key_id, count in rows
+        for ws, repo, count in rows
     ]
 
 

apps/api/src/api/workspace_instances.py

@@ -1,60 +0,0 @@
-"""Workspace instance API endpoints."""
-
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_instance import ToolInstance
-from src.models.workspace import Workspace
-
-router = APIRouter(prefix="/workspaces/{workspace_id}/instances")
-
-
-async def _get_workspace(
-    session: AsyncSession,
-    workspace_id: uuid.UUID,
-    user_id: uuid.UUID,
-) -> Workspace:
-    result = await session.execute(
-        select(Workspace).where(
-            Workspace.id == workspace_id,
-            Workspace.user_id == user_id,
-        )
-    )
-    workspace = result.scalar_one_or_none()
-    if not workspace:
-        raise HTTPException(status_code=404, detail="Workspace not found")
-    return workspace
-
-
-@router.get("/")
-async def list_workspace_instances(
-    workspace_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> list[dict]:
-    """List tool instances using this workspace."""
-    await _get_workspace(session, workspace_id, user_id)
-    result = await session.execute(
-        select(ToolInstance)
-        .where(ToolInstance.workspace_id == workspace_id)
-        .order_by(ToolInstance.created_at.desc())
-    )
-    instances = result.scalars().all()
-
-    return [
-        {
-            "id": str(i.id),
-            "name": i.name,
-            "display_name": i.display_name,
-            "status": i.status,
-            "tool_type_id": str(i.tool_type_id),
-            "url": i.url,
-            "port": i.port,
-            "created_at": i.created_at.isoformat() if i.created_at else None,
-        }
-        for i in instances
-    ]

apps/api/src/auth/.pi-map.index.md

@@ -0,0 +1,24 @@
+# apps/api/src/auth (index)
+dir: apps/api/src/auth
+
+## role
+Provides authentication and authorization infrastructure for the API using OIDC/OAuth2 with Authentik, session cookies, and FastAPI dependencies.
+## parent
+index: apps/api/src/.pi-map.index.md
+map: apps/api/src/.pi-map.md
+## children
+-
+## files
+- __init__.py
+- cookies.py
+- dependencies.py
+- oidc.py
+- session.py
+## links
+index: apps/api/src/auth/.pi-map.index.md
+map: apps/api/src/auth/.pi-map.md
+## workflows
+- change auth behavior
+  read: __init__.py, cookies.py, dependencies.py
+## dirty
+-

apps/api/src/auth/.pi-map.md

@@ -0,0 +1,31 @@
+# apps/api/src/auth
+dir: apps/api/src/auth
+
+index: apps/api/src/auth/.pi-map.index.md
+
+## role
+Provides authentication and authorization infrastructure for the API using OIDC/OAuth2 with Authentik, session cookies, and FastAPI dependencies.
+## files
+- __init__.py | Re-exports authentication utility functions from submodules to provide a unified public API for the auth package | dep: src.auth.cookies, src.auth.oidc, src.auth.session
+- cookies.py | Builds a dictionary of HTTP cookie options from application settings for secure cookie configuration. | exp: func:build_cookie_options(settings: Settings) → dict[str, str | bool | None] | dep: src.config, src.config.Settings
+- dependencies.py | Provides FastAPI dependency functions for database sessions, user authentication, and project authorization. | exp: func:get_db_session(), call:SessionLocal, func:get_current_user_id(session_cookie) → uuid.UUID, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str, raise:HTTPException, func:get_current_user(session_cookie, db_session) → User, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str, call:db_session.get, raise:HTTPException, func:_get_user(session: AsyncSession, user_id: uuid.UUID) → User, call:session.get, raise:HTTPException, func:_get_owned_project(project_id: uuid.UUID, user_id: uuid.UUID, session: AsyncSession) → "Project", call:session.get, raise:HTTPException | dep: uuid, typing, fastapi, sqlalchemy.ext.asyncio, src.auth.session, src.config, src.database, src.models.project, src.models.user, sqlalchemy
+- oidc.py | Implements OIDC/OAuth2 authentication flow with Authentik, including login URL construction, authorization code exchange for tokens, and user info retrieval. | exp: func:build_login_redirect_url(settings: Settings, redirect_uri: str, state: str) → str, call:urlencode, func:exchange_code_for_tokens(settings: Settings, code: str, redirect_uri: str, client: httpx.AsyncClient) → dict[str, str], call:client.post, call:response.raise_for_status, call:response.json, call:payload.get, func:fetch_user_info(settings: Settings, access_token: str, client: httpx.AsyncClient) → dict[str, Any], call:client.get, call:response.raise_for_status, call:response.json | dep: typing, urllib.parse, httpx, src.config
+- session.py | Implements creation and verification of signed session cookies using HMAC-SHA256 in a JWS-like format. | exp: func:_base64url_encode(data: bytes) → str, call:base64.urlsafe_b64encode(data).rstrip(b"=").decode, func:_base64url_decode(data: str) → bytes, call:len, call:base64.urlsafe_b64decode, func:create_session_cookie(settings: Settings, user_id: str) → str, call:int, call:(datetime.now(timezone.utc) + timedelta(hours=settings.session_ttl_hours)).timestamp, call:datetime.now, call:timedelta, call:_base64url_encode, call:json.dumps({"alg": "HS256", "typ": "session"}).encode, call:json.dumps(payload).encode, call:hmac.new( settings.session_secret.encode(), message.encode(), hashlib.sha256, ).digest, call:settings.session_secret.encode, call:message.encode, func:decode_session_cookie(settings: Settings, cookie_value: str) → dict[str, Any], call:cookie_value.split, call:len, call:hmac.new( settings.session_secret.encode(), message.encode(), hashlib.sha256, ).digest, call:settings.session_secret.encode, call:message.encode, call:_base64url_encode, call:hmac.compare_digest, call:_base64url_decode, call:json.loads, call:payload.get, call:int, call:datetime.now(timezone.utc).timestamp, raise:ValueError | dep: hmac, hashlib, json, base64, datetime, typing, src.config, src.config.Settings
+## arch
+Modular security layer with separation of concerns: protocol handling (OIDC), transport security (cookies/sessions), framework integration (dependencies), and clean public API (re-exports).
+## tags
+session, src, cookie, user, get, base64url, raise:httpexception, call:
+## symbols
+- build_cookie_options
+- get_db_session
+- get_current_user_id
+- get_current_user
+- _get_user
+- _get_owned_project
+- build_login_redirect_url
+- exchange_code_for_tokens
+## workflows
+- change auth behavior
+  read: __init__.py, cookies.py, dependencies.py
+## dirty
+-

apps/api/src/auth/dependencies.py

@@ -50,17 +50,25 @@ async def get_current_user(
     return user
 
 
-async def get_owned_project(
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
+
+async def _get_owned_project(
     project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    db_session: AsyncSession = Depends(get_db_session),
-) -> Project:
+    user_id: uuid.UUID,
+    session: AsyncSession,
+) -> "Project":
     """Fetch a project and verify ownership.
 
     Args:
-        project_id: UUID of the project (injected from path parameter).
-        user: The currently authenticated user.
-        db_session: Database session.
+        project_id: UUID of the project.
+        user_id: ID of the authenticated user.
+        session: Database session.
 
     Returns:
         The project if found and owned by the user.
@@ -68,9 +76,11 @@ async def get_owned_project(
     Raises:
         HTTPException: 404 if project not found, 403 if user is not the owner.
     """
-    project = await db_session.get(Project, project_id)
+    from src.models.project import Project
+
+    project = await session.get(Project, project_id)
     if project is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="project not found")
-    if project.owner_id != user.id:
+    if project.owner_id != user_id:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="not project owner")
     return project

apps/api/src/config.py

@@ -47,6 +47,11 @@ class Settings(BaseSettings):
     session_secret: str = "change-me-session-secret"
     session_ttl_hours: int = 24
 
+    # Internal JWT configuration (used for service-to-service tokens)
+    jwt_algorithm: str = "HS256"
+    access_token_ttl_minutes: int = 15
+    refresh_token_ttl_days: int = 7
+
     # Repository storage
     repo_base_path: str = "/data/repos"
     
@@ -122,7 +127,7 @@ class Settings(BaseSettings):
     @property
     def cookie_samesite(self) -> str:
         if self.app_env == "production":
-            return "none"
+            return "strict"
 
         return "lax"
 

apps/api/src/database.py

@@ -1,5 +1,6 @@
 import asyncio
 import logging
+import os
 import subprocess
 
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
@@ -54,10 +55,10 @@ async def init_database(
             result = await asyncio.get_event_loop().run_in_executor(
                 None,
                 lambda: subprocess.run(
-                    ["alembic", "upgrade", "head"],
+                    ["python3", "-m", "alembic", "upgrade", "head"],
                     capture_output=True,
                     text=True,
-                    cwd="/app",
+                    cwd=os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
                 ),
             )
 

apps/api/src/logging_config.py

@@ -10,7 +10,7 @@ from collections.abc import Callable
 from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
 
-from src.services.correlation import get_correlation_id
+from src.services.shared.correlation import get_correlation_id
 
 logger = logging.getLogger(__name__)
 

apps/api/src/main.py

@@ -6,20 +6,35 @@ from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
-from src.api.auth import router as auth_router
-from src.api.dashboard import router as dashboard_router
-from src.api.git_repositories import router as git_repositories_router
-from src.api.health import router as health_router
-from src.api.projects import router as projects_router
-from src.api.ssh_keys import router as ssh_keys_router
-from src.api.terminal import router as terminal_router
-from src.api.instance_proxy import router as instance_proxy_router
-from src.api.config_profiles import router as config_profiles_router
-from src.api.tool_instances import router as tool_instances_router
-from src.api.tool_types import router as tool_types_router
-from src.api.user_config import router as user_config_router
-from src.api.users import router as users_router
+
+from src.api.config import config_profiles_router, user_config_router
+from src.api.project import git_repositories_router, projects_router
+from src.api.system import (
+    dashboard_router,
+    events_router,
+    health_router,
+    instance_proxy_router,
+    notifications_router,
+    terminal_router,
+)
+from src.api.tool import (
+    sessions_router,
+    tool_definitions_router,
+    tool_instances_router,
+    tool_lifecycle_router,
+    tool_types_router,
+)
+from src.api.user import auth_router, ssh_keys_router, users_router
+from src.api.workspace import (
+    all_workspaces_router,
+    workspace_files_router,
+    workspace_git_router,
+    workspace_instances_router,
+    workspaces_router,
+)
 from src.config import Settings
+from src.models import Notification  # noqa: F401 – Alembic model discovery
+from src.models import TerminalSessionModel  # noqa: F401 – Alembic model discovery
 from src.database import init_database
 from src.logging_config import (
     ExceptionLoggingMiddleware,
@@ -27,6 +42,8 @@ from src.logging_config import (
     configure_logging,
 )
 from src.seeds.builtin_tool_types import seed_builtin_tool_types
+from src.services.instance import InstanceEventBus, HealthMonitor
+from src.services.shared import CorrelationIdMiddleware
 
 # Configure logging early
 log_level = os.getenv("LOG_LEVEL", "INFO").upper()
@@ -51,6 +68,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.add_middleware(CorrelationIdMiddleware)
 app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(ExceptionLoggingMiddleware)
 
@@ -100,6 +118,11 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
     )
 
 
+# Global services
+_event_bus = InstanceEventBus()
+_health_monitor = HealthMonitor(_event_bus)
+
+
 @app.on_event("startup")
 async def on_startup():
     logger.info("Starting up Headquarter API...")
@@ -112,11 +135,25 @@ async def on_startup():
 
         sys.exit(1)
 
-    # Seed built-in data
+    # Start background health monitor
+    _health_monitor.start()
+    logger.info("Health monitor started")
+
+    # Seed built-in tool types
     await seed_builtin_tool_types()
+    logger.info("Built-in tool types seeded")
+
     logger.info("Startup complete.")
 
 
+@app.on_event("shutdown")
+async def on_shutdown():
+    logger.info("Shutting down Headquarter API...")
+    _health_monitor.stop()
+    logger.info("Health monitor stopped")
+    logger.info("Shutdown complete.")
+
+
 app.include_router(health_router)
 app.include_router(auth_router)
 app.include_router(dashboard_router)
@@ -126,8 +163,18 @@ app.include_router(ssh_keys_router)
 app.include_router(git_repositories_router)
 app.include_router(user_config_router)
 app.include_router(tool_types_router)
+app.include_router(tool_definitions_router)
 app.include_router(config_profiles_router)
 app.include_router(tool_instances_router)
+app.include_router(tool_lifecycle_router)
+app.include_router(sessions_router)
 app.include_router(instance_proxy_router)
 app.include_router(terminal_router)
+app.include_router(events_router)
+app.include_router(notifications_router)
+app.include_router(all_workspaces_router)
+app.include_router(workspaces_router)
+app.include_router(workspace_files_router)
+app.include_router(workspace_git_router)
+app.include_router(workspace_instances_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")