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.
fix: merge mobile terminal scroll detection improvements
2026-06-13 21:04:50 +00:00 · 2026-06-13 20:42:52 +00:00 · 2026-06-13 20:42:52 +00:00 · 2026-06-13 20:30:52 +00:00 · 2026-06-13 20:30:52 +00:00 · 2026-06-13 19:59:13 +00:00
268 changed files with 1952 additions and 1435 deletions
@@ -2,7 +2,7 @@
 dir: .claude
 ## role
-Configuration and instruction files for the Claude AI assistant integration.
+Configuration directory for Claude AI assistant integration and custom instructions.
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md
@@ -4,10 +4,10 @@ dir: .claude
 index: .claude/.pi-map.index.md
 ## role
-Configuration and instruction files for the Claude AI assistant integration.
+Configuration directory for Claude AI assistant integration and custom instructions.
 ## files
 ## arch
-Simple flat-file configuration storage with no complex architecture; contains prompt templates, system instructions, or context files used to guide Claude's behavior in this project.
+Project-specific AI tooling configuration using convention-based file organization for assistant context and behavior customization.
 ## tags
 -
 ## symbols
@@ -2,7 +2,7 @@
 dir: .claude/skills
 ## role
-Empty directory placeholder for future Claude Code skill definitions or custom AI-assisted workflows.
+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
@@ -4,10 +4,10 @@ dir: .claude/skills
 index: .claude/skills/.pi-map.index.md
 ## role
-Empty directory placeholder for future Claude Code skill definitions or custom AI-assisted workflows.
+Contains reusable AI skill definitions and prompt templates that configure Claude's specialized capabilities for specific development tasks.
 ## files
 ## arch
-None (no files present); likely intended for declarative skill modules using Claude's skill system pattern.
+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
@@ -8,7 +8,7 @@ Defines a workflow skill for triaging, organizing, and activating backlog tasks
 ## 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
-Skill-based workflow automation following a structured triage pipeline (scan → filter → prioritize → activate) with CLI tool integration for backlog management.
+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
@@ -2,7 +2,7 @@
 dir: .opencode
 ## role
-Configuration directory for the OpenCode AI coding assistant tool
+Hidden directory for OpenCode IDE/editor configuration and workspace metadata
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md
@@ -4,10 +4,10 @@ dir: .opencode
 index: .opencode/.pi-map.index.md
 ## role
-Configuration directory for the OpenCode AI coding assistant tool
+Hidden directory for OpenCode IDE/editor configuration and workspace metadata
 ## files
 ## arch
-Tool-specific configuration storage using standard dot-directory convention with likely JSON/YAML config files and optional workspace state/logs
+IDE-specific dot-directory pattern, no active code architecture; stores tool preferences and ephemeral state
 ## tags
 -
 ## symbols
@@ -2,7 +2,7 @@
 dir: .opencode/commands
 ## role
-Defines structured workflow commands and AI assistant stances for an experimental OpenSpec-based development system that guides changes through exploration, proposal, implementation, and archival phases.
+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
@@ -4,14 +4,14 @@ dir: .opencode/commands
 index: .opencode/commands/.pi-map.index.md
 ## role
-Defines structured workflow commands and AI assistant stances for an experimental OpenSpec-based development system that guides changes through exploration, proposal, implementation, and archival phases.
+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 declarative workflow definitions using a command pattern where each `.md` file specifies a distinct operational stance or phase (explore/propose/apply/archive) with embedded metadata, structured steps, and CLI integration points for progressive change lifecycle management.
+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
@@ -2,7 +2,7 @@
 dir: .opencode/skills
 ## role
-Contains reusable skill modules that provide specific capabilities or integrations for the OpenCode agent framework.
+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
@@ -4,10 +4,10 @@ dir: .opencode/skills
 index: .opencode/skills/.pi-map.index.md
 ## role
-Contains reusable skill modules that provide specific capabilities or integrations for the OpenCode agent framework.
+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 unit implementing standardized interfaces for dynamic discovery and loading by the agent core.
+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
@@ -2,7 +2,7 @@
 dir: .opencode/skills/openspec-apply-change
 ## role
-Provides a spec-driven AI skill that implements tasks from OpenSpec changes by applying structured modifications to a codebase.
+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
@@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-apply-change
 index: .opencode/skills/openspec-apply-change/.pi-map.index.md
 ## role
-Provides a spec-driven AI skill that implements tasks from OpenSpec changes by applying structured modifications to a codebase.
+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
-Skill-based modular architecture using markdown-defined capabilities with a workflow-driven pattern that separates specification parsing from implementation execution.
+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
@@ -2,7 +2,7 @@
 dir: .opencode/skills/openspec-archive-change
 ## role
-Provides a skill definition for archiving completed changes in an experimental workflow using the openspec CLI.
+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
@@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-archive-change
 index: .opencode/skills/openspec-archive-change/.pi-map.index.md
 ## role
-Provides a skill definition for archiving completed changes in an experimental workflow using the openspec CLI.
+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
-Single-file skill definition using markdown-based skill documentation pattern with CLI tool integration.
+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
@@ -2,7 +2,7 @@
 dir: .opencode/skills/openspec-explore
 ## role
-Defines a conversational AI skill that acts as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code.
+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
@@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-explore
 index: .opencode/skills/openspec-explore/.pi-map.index.md
 ## role
-Defines a conversational AI skill that acts as a thinking partner for exploring ideas, investigating problems, and clarifying requirements without implementing code.
+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
-Markdown-based skill definition using persona/role-prompting pattern with structured behavioral guidelines for non-implementation exploratory conversations.
+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
@@ -2,7 +2,7 @@
 dir: .opencode/skills/openspec-propose
 ## role
-Defines a structured workflow skill for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order.
+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
@@ -4,11 +4,11 @@ dir: .opencode/skills/openspec-propose
 index: .opencode/skills/openspec-propose/.pi-map.index.md
 ## role
-Defines a structured workflow skill for proposing new changes using the openspec CLI, generating proposal, design, and task artifacts in dependency order.
+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 structured workflow patterns for CLI-driven artifact generation and dependency-ordered execution.
+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
@@ -16,7 +16,7 @@ dir: .
 Trust boundary: index routes, map orients, source decides.
 ## role
-Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling.
+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
@@ -59,6 +59,9 @@ Infrastructure and deployment configuration for a self-hosted project management
 - 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
@@ -18,7 +18,7 @@ index: ./.pi-map.index.md
 Trust boundary: index routes, map orients, source decides.
 ## role
-Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling.
+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
@@ -31,7 +31,7 @@ Infrastructure and deployment configuration for a self-hosted project management
 - 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
-Containerized microservices architecture using Docker Compose with PostgreSQL/Redis data layer, Traefik reverse proxy for TLS termination, environment-based configuration pattern, and Makefile-driven development workflow.
+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
@@ -2,7 +2,7 @@
 dir: .stoneforge
 ## role
-Hidden system directory storing runtime state, configuration, and version-control metadata for the Stoneforge application.
+Internal configuration and state tracking directory for the Stoneforge application
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md
@@ -4,13 +4,13 @@ dir: .stoneforge
 index: .stoneforge/.pi-map.index.md
 ## role
-Hidden system directory storing runtime state, configuration, and version-control metadata for the Stoneforge application.
+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 flat-file storage with YAML-based configuration, dotfile-based state tracking, and standard Git ignore patterns.
+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
@@ -2,7 +2,7 @@
 dir: .stoneforge/sync
 ## role
-Distributed task coordination and ephemeral worker agent management for a multi-agent execution system.
+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
@@ -4,12 +4,12 @@ dir: .stoneforge/sync
 index: .stoneforge/sync/.pi-map.index.md
 ## role
-Distributed task coordination and ephemeral worker agent management for a multi-agent execution system.
+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 graph tracking, session-based worker lifecycle management, and decentralized worktree assignment.
+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
@@ -2,7 +2,7 @@
 dir: apps
 ## role
-Contains the main application entry points and executable modules for the project.
+Contains the main deployable application modules or entry points for the project.
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md
@@ -4,10 +4,10 @@ dir: apps
 index: apps/.pi-map.index.md
 ## role
-Contains the main application entry points and executable modules for the project.
+Contains the main deployable application modules or entry points for the project.
 ## files
 ## arch
-Follows a modular application structure with separate directories for each deployable application, typically using framework-specific patterns (e.g., MVC, MVVM, or component-based architecture depending on the stack).
+Modular monolith or microservices architecture with separate application boundaries, each potentially having its own configuration, dependencies, and lifecycle.
 ## tags
 -
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api
 ## role
-Backend API service that provides a self-hosted FastAPI server for managing development projects, git repositories, and containerized tools via Docker.
+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
@@ -4,7 +4,7 @@ dir: apps/api
 index: apps/api/.pi-map.index.md
 ## role
-Backend API service that provides a self-hosted FastAPI server for managing development projects, git repositories, and containerized tools via Docker.
+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
@@ -14,7 +14,7 @@ Backend API service that provides a self-hosted FastAPI server for managing deve
 - 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
-Modern Python async architecture using FastAPI with SQLAlchemy/alembic for PostgreSQL, uv for dependency management, multi-stage Docker builds with Cloudflare tunneling, and health-check orchestration for database readiness.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/alembic
 ## role
-Database migration tooling that manages schema versioning and changes for the API's PostgreSQL database using Alembic with async SQLAlchemy.
+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
@@ -4,16 +4,23 @@ dir: apps/api/alembic
 index: apps/api/alembic/.pi-map.index.md
 ## role
-Database migration tooling that manages schema versioning and changes for the API's PostgreSQL database using Alembic with async SQLAlchemy.
+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. | dep: alembic, sqlalchemy, sqlalchemy.ext.asyncio, logging.config, asyncio, src.config, src.models
+- 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
-Template-driven migration pattern using Alembic's declarative configuration with async engine setup, environment context management, and auto-generated revision scripts with upgrade/downgrade function pairs.
+Alembic migration framework with Mako templating for generating revision scripts, async SQLAlchemy engine configuration, and autogenerate capabilities for schema change tracking.
 ## tags
-sqlalchemy, alembic, database, migration, asyncio, config, src, env
+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
@@ -2,7 +2,7 @@
 dir: apps/api/alembic/versions
 ## role
-Database schema evolution management for the API application, tracking incremental changes to tables supporting users, authentication, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, and notifications.
+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
@@ -47,9 +47,11 @@ map: apps/api/alembic/.pi-map.md
 - 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
@@ -4,7 +4,7 @@ dir: apps/api/alembic/versions
 index: apps/api/alembic/versions/.pi-map.index.md
 ## role
-Database schema evolution management for the API application, tracking incremental changes to tables supporting users, authentication, projects, git repositories, tool types/instances, config profiles, workspaces, monitoring, and notifications.
+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
@@ -33,7 +33,7 @@ Database schema evolution management for the API application, tracking increment
 - 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 existing pi-agent data from Dockerfile templates to JSON-based manifest definitions | 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_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
@@ -44,16 +44,18 @@ Database schema evolution management for the API application, tracking increment
 - 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 Alembic migration pattern with merge migrations to reconcile divergent branches, using incremental revision files with upgrade/downgrade functions, idempotent operations, and occasional data migrations for schema transformations.
+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, key, alembic, downgrade, upgrade, constraint
+column, table, call:op.drop, downgrade, alembic, upgrade, key, call:sa.text
 ## symbols
 - upgrade
 - downgrade
@@ -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"],
@@ -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,
    )
@@ -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,
        },
    )
@@ -2,7 +2,7 @@
 dir: apps/api/src
 ## role
-Core application package that bootstraps and configures the Headquarter API FastAPI service with its infrastructure concerns.
+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
@@ -4,15 +4,15 @@ dir: apps/api/src
 index: apps/api/src/.pi-map.index.md
 ## role
-Core application package that bootstraps and configures the Headquarter API FastAPI service with its infrastructure concerns.
+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 using Pydantic with environment variable loading, database URL construction, and computed properties for service URLs and OAuth endpoints. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings
+- 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 | Configures async SQLAlchemy database engine and session factory, and provides retry logic for database initialization with Alembic migrations 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:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy
+- 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 configuration with Pydantic settings, async SQLAlchemy with Alembic migration integration, structured JSON logging with correlation ID tracking, and FastAPI middleware/routing setup.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api
 ## role
-Defines reusable API validation utilities and package structure for FastAPI router organization.
+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
@@ -4,12 +4,12 @@ dir: apps/api/src/api
 index: apps/api/src/api/.pi-map.index.md
 ## role
-Defines reusable API validation utilities and package structure for FastAPI router organization.
+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 shared Pydantic validators for cross-cutting API schema concerns, following separation of validation logic from route handlers.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/config
 ## role
-Exposes REST API endpoints for managing user configuration profiles and settings.
+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
@@ -4,13 +4,13 @@ dir: apps/api/src/api/config
 index: apps/api/src/api/config/.pi-map.index.md
 ## role
-Exposes REST API endpoints for managing user configuration profiles and settings.
+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
-FastAPI router modules following domain-driven separation with CRUD patterns, validation logic, and automatic default initialization.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/project
 ## role
-Provides REST API endpoints for project and Git repository management in the backend service.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/system
 ## role
-Provides system-level API endpoints for monitoring, administration, and infrastructure interaction including dashboards, health checks, events, notifications, and container terminal access.
+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
@@ -4,7 +4,7 @@ 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, events, notifications, and container terminal access.
+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)
@@ -14,7 +14,7 @@ Provides system-level API endpoints for monitoring, administration, and infrastr
 - 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 modular router pattern with separate files per domain concern, combining REST endpoints, SSE streaming, WebSocket connections, and HTTP proxying; uses dependency injection for auth and integrates with Docker/container runtime for terminal and instance proxy features.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/tool
 ## role
-Provides FastAPI REST API endpoints and routers for managing the complete lifecycle of Docker-based tools, including type definitions, instances, sessions, and lifecycle operations.
+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
@@ -4,17 +4,17 @@ dir: apps/api/src/api/tool
 index: apps/api/src/api/tool/.pi-map.index.md
 ## role
-Provides FastAPI REST API endpoints and routers for managing the complete lifecycle of Docker-based tools, including type definitions, instances, sessions, and lifecycle operations.
+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 | API endpoint that retrieves 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
+- 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, checking required structure, verifying port exposure, and ensuring required variables are present. | 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, func:validate_required_variables(template: str, variables: list[str]) → None, raise:HTTPException | dep: re, yaml, fastapi, fastapi.HTTPException, fastapi.status
+- 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 composition pattern with separated concerns across CRUD operations, validation, lifecycle management, and proxying, aggregated through `__init__.py` for unified module interface.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/user
 ## role
-Provides user-facing API endpoints for authentication, profile management, and SSH key operations in a FastAPI backend application.
+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
@@ -4,14 +4,14 @@ dir: apps/api/src/api/user
 index: apps/api/src/api/user/.pi-map.index.md
 ## role
-Provides user-facing API endpoints for authentication, profile management, and SSH key operations in a FastAPI backend application.
+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 separate submodule files per domain concern (auth, SSH keys, users), aggregated via __init__.py, using OAuth2/OIDC external identity provider (Authentik) and encrypted key storage for cryptographic operations.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/api/workspace
 ## role
-Provides FastAPI REST endpoints for workspace management, file operations, and git integration in user-scoped development environments.
+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
@@ -4,15 +4,15 @@ 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, and git integration in user-scoped development environments.
+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 | Defines API endpoints for listing tool instances associated with a specific workspace, verifying workspace ownership. | 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_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
+- 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 | Provides FastAPI CRUD endpoints for managing Git repository workspaces with nested and top-level URL structures, including listing, creating, updating, deleting, and syncing workspaces with instance count tracking. | 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.name.label("repo_name"), GitRepository.project_id, GitRepository.ssh_key_id.label("repo_ssh_key_id"), instance_count.label("instance_count"), ) .join(GitRepository, Workspace.repo_id == GitRepository.id) .where(Workspace.user_id == user_id) .order_by, call:GitRepository.name.label, call:GitRepository.ssh_key_id.label, 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: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
+- 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 router composition with domain-separated endpoint modules (files, git, instances, workspaces) using FastAPI dependency injection for workspace ownership verification and nested resource URL patterns.
+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
@@ -36,12 +36,11 @@ async def list_all_workspaces(
    result = await session.execute(
        select(
            Workspace,
-            GitRepository.name.label("repo_name"),
+            GitRepository,
            GitRepository.project_id,
            GitRepository.ssh_key_id.label("repo_ssh_key_id"),
            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_id": str(repo.id),
-            "repo_name": repo_name or "",
+            "repo_name": repo.name or "",
-            "repo_ssh_key_id": str(ssh_key_id) if ssh_key_id else None,
+            "repo_ssh_key_id": str(repo.ssh_key_id) if repo.ssh_key_id else None,
-            "project_id": str(project_id) if project_id else "",
+            "project_id": str(repo.project_id) if repo.project_id else "",
-            "project_name": "",
+            "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
    ]
@@ -2,7 +2,7 @@
 dir: apps/api/src/auth
 ## role
-Provides authentication and authorization infrastructure for the API, including OIDC/OAuth2 integration, session management, and FastAPI dependency injection.
+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
@@ -4,7 +4,7 @@ dir: apps/api/src/auth
 index: apps/api/src/auth/.pi-map.index.md
 ## role
-Provides authentication and authorization infrastructure for the API, including OIDC/OAuth2 integration, session management, and FastAPI dependency injection.
+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
@@ -12,7 +12,7 @@ Provides authentication and authorization infrastructure for the API, including
 - 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 utility package with separation of concerns across cookies, sessions, OIDC flows, and FastAPI dependencies; uses HMAC-SHA256 JWS-like tokens and external Authentik identity provider.
+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
@@ -2,7 +2,7 @@
 dir: apps/api/src/models
 ## role
-Provides the core database model layer with a centralized public API, defining SQLAlchemy base classes and reusable mixins for consistent schema patterns across the API application.
+Centralized database model definitions and shared infrastructure for the API's data layer.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/models
 index: apps/api/src/models/.pi-map.index.md
 ## role
-Provides the core database model layer with a centralized public API, defining SQLAlchemy base classes and reusable mixins for consistent schema patterns across the API application.
+Centralized database model definitions and shared infrastructure for the API's data layer.
 ## files
 - __init__.py | Re-exports model classes from submodules to provide a centralized public API for the src.models package | dep: src.models.base, src.models.config.config_profile, src.models.project.git_repository, src.models.project.project, src.models.project.workspace, src.models.system.health_check, src.models.system.instance_event, src.models.system.notification, src.models.system.terminal_session, src.models.tool.tool_definition_manifest, src.models.tool.tool_instance, src.models.tool.tool_type, src.models.user.ssh_key, src.models.user.user, src.models.user.user_config
 - base.py | Defines SQLAlchemy base model and reusable mixins for UUID primary keys and automatic timestamp tracking in database models. | exp: class:Base, class:UUIDPrimaryKeyMixin, class:TimestampMixin | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm
 ## arch
-Uses the declarative base pattern with mixin composition for cross-cutting concerns (UUIDs, timestamps), and a facade/aggregate module pattern via __init__.py re-exports to simplify imports for consumers.
+SQLAlchemy ORM with declarative base, mixin-based composition for cross-cutting concerns (UUIDs, timestamps), and explicit package-level re-exports for clean public API surface.
 ## tags
 models, src, base, project, system, user, mixin, tool
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/models/config
 ## role
-Provides SQLAlchemy ORM models for managing configuration profiles and their hierarchical includes in the API application.
+Provides SQLAlchemy ORM models for configuration profiles that manage environment variables, mounts, files, and git mounts with support for profile inheritance and user/project/tool associations.
 ## parent
 index: apps/api/src/models/.pi-map.index.md
 map: apps/api/src/models/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/models/config
 index: apps/api/src/models/config/.pi-map.index.md
 ## role
-Provides SQLAlchemy ORM models for managing configuration profiles and their hierarchical includes in the API application.
+Provides SQLAlchemy ORM models for configuration profiles that manage environment variables, mounts, files, and git mounts with support for profile inheritance and user/project/tool associations.
 ## files
 - __init__.py | Exports config model classes from a subpackage for simplified importing | dep: src.models.config.config_profile
 - config_profile.py | Defines SQLAlchemy ORM models for configuration profiles and their includes, storing environment variables, runtime hints, mounts, files, and git mounts with user/project/tool associations and self-referential inclusion relationships. | exp: class:ConfigProfile, class:ConfigProfileInclude | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.user, src.models (ToolType)
 ## arch
-Uses SQLAlchemy declarative ORM pattern with self-referential many-to-many relationships for profile inclusion, and associations to users, projects, and tools.
+Uses SQLAlchemy ORM with declarative base pattern, implementing self-referential many-to-many relationships for profile inclusion, association tables for user/project/tool ownership, and polymorphic-like configuration through profile inheritance rather than class inheritance.
 ## tags
 config, src, models, profile, sqlalchemy, init, orm, mounts
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/models/project
 ## role
-Defines the core data models for project-related entities (GitRepository, Project, Workspace) using SQLAlchemy ORM.
+Defines the core domain data models for project management, representing Git repositories, projects, and workspaces as SQLAlchemy ORM entities with their relationships.
 ## parent
 index: apps/api/src/models/.pi-map.index.md
 map: apps/api/src/models/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/api/src/models/project
 index: apps/api/src/models/project/.pi-map.index.md
 ## role
-Defines the core data models for project-related entities (GitRepository, Project, Workspace) using SQLAlchemy ORM.
+Defines the core domain data models for project management, representing Git repositories, projects, and workspaces as SQLAlchemy ORM entities with their relationships.
 ## files
 - __init__.py | Exports the three main project model classes (GitRepository, Project, Workspace) as the public API for the models.project package. | dep: src.models.project.git_repository, src.models.project.project, src.models.project.workspace
 - git_repository.py | Defines a SQLAlchemy ORM model for Git repositories with relationships to projects, users, and SSH keys. | exp: class:GitRepository | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.user, src.models.ssh_key
 - project.py | Defines a SQLAlchemy ORM model for a Project entity with relationships to users, Git repositories, and SSH keys. | exp: class:Project | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.user, src.models.GitRepository, src.models.SSHKey, src.models.user.User
 - workspace.py | Defines a SQLAlchemy ORM model for persistent writable Git repository clones associated with users. | exp: class:Workspace | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.user, src.models.GitRepository, src.models.user.User
 ## arch
-Standard SQLAlchemy ORM pattern with declarative models, package-level public API abstraction via __init__.py, and bidirectional relationships between entities.
+Standard SQLAlchemy ORM model layer with declarative base pattern, using __init__.py as a public API facade to expose the three main entity classes while keeping implementation details in separate modules.
 ## tags
 models, src, project, sqlalchemy, git, user, workspace, orm
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/models/system
 ## role
-Provides SQLAlchemy ORM models for system-level operational and audit data including health checks, instance events, notifications, and terminal sessions.
+Provides database persistence models for system-level operational concerns including health monitoring, audit logging, user notifications, and terminal session management.
 ## parent
 index: apps/api/src/models/.pi-map.index.md
 map: apps/api/src/models/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/api/src/models/system
 index: apps/api/src/models/system/.pi-map.index.md
 ## role
-Provides SQLAlchemy ORM models for system-level operational and audit data including health checks, instance events, notifications, and terminal sessions.
+Provides database persistence models for system-level operational concerns including health monitoring, audit logging, user notifications, and terminal session management.
 ## files
 - __init__.py | Exports system-related model classes from a package for convenient importing. | dep: src.models.system.health_check, src.models.system.instance_event, src.models.system.notification, src.models.system.terminal_session
 - health_check.py | Defines a SQLAlchemy ORM model for storing health check snapshots of tool instances with various status and probe fields. | exp: class:HealthCheck | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm, src.models.base
@@ -12,7 +12,7 @@ Provides SQLAlchemy ORM models for system-level operational and audit data inclu
 - notification.py | Defines a SQLAlchemy ORM model for storing user notifications with metadata, read/dismissed tracking, and polymorphic source references. | exp: class:Notification | dep: datetime, typing, uuid, sqlalchemy, sqlalchemy.orm, sqlalchemy.sql, src.models.base
 - terminal_session.py | Defines a SQLAlchemy database model for storing terminal session metadata with lifecycle tracking. | exp: class:TerminalSessionModel | dep: uuid, datetime, sqlalchemy, sqlalchemy.orm, src.models.base
 ## arch
-Standard SQLAlchemy declarative ORM pattern with timestamped base models, polymorphic relationships (notification sources), lifecycle state tracking, and audit fields (user attribution, status enums).
+Uses SQLAlchemy ORM declarative models with consistent patterns including timestamp tracking, JSON metadata columns, enum-based status fields, and polymorphic relationships for extensible source attribution.
 ## tags
 sqlalchemy, src, models, model, orm, system, notification, health
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/models/tool
 ## role
-Defines SQLAlchemy ORM models for managing tool definitions, instances, and types in a container-based deployment system.
+Database models for containerized tool lifecycle management, covering tool definitions, deployment instances, and categorization types.
 ## parent
 index: apps/api/src/models/.pi-map.index.md
 map: apps/api/src/models/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/api/src/models/tool
 index: apps/api/src/models/tool/.pi-map.index.md
 ## role
-Defines SQLAlchemy ORM models for managing tool definitions, instances, and types in a container-based deployment system.
+Database models for containerized tool lifecycle management, covering tool definitions, deployment instances, and categorization types.
 ## files
 - __init__.py | Exports the public API for the tool models module by re-exporting three key classes. | dep: src.models.tool.tool_definition_manifest, src.models.tool.tool_instance, src.models.tool.tool_type
 - tool_definition_manifest.py | Defines a SQLAlchemy ORM model for storing tool definition manifests that compile to Dockerfiles and Compose files, supporting both base definitions and tool-specific definitions with inheritance. | exp: class:ToolDefinitionManifest | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.user
- tool_instance.py | Defines a SQLAlchemy ORM model for tool instances that represent deployed tools with container/runtime metadata and relationships to users, projects, repositories, and workspaces. | exp: class:ToolInstance | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.project, src.models.user, src.models (ConfigProfile, GitRepository, Project, ToolType, User, Workspace)
+- tool_instance.py | Defines a SQLAlchemy ORM model for tool instances that represent deployed tools with container metadata, status tracking, and relationships to users, projects, workspaces, and other entities. | exp: class:ToolInstance | dep: uuid, datetime, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models, src.models.project, src.models.user, src.models (ConfigProfile, GitRepository, Project, ToolType, User, Workspace)
 - tool_type.py | Defines a SQLAlchemy ORM model for tool types that represent configurable categories of tools with deployment templates, manifest references, and metadata. | exp: class:ToolType | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.tool.tool_definition_manifest, src.models.user
 ## arch
-Domain-driven SQLAlchemy ORM models with inheritance patterns (base/tool-specific manifests), rich relationships (users, projects, repositories, workspaces), and template-based deployment abstractions.
+SQLAlchemy ORM with declarative models using inheritance hierarchies, relationship mappings, and polymorphic manifest compilation for Docker/Compose deployment.
 ## tags
 tool, models, src, sqlalchemy, orm, definition, manifest, base
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/models/user
 ## role
-Provides the core data models for user identity, authentication credentials, and personal configuration in the API's database layer.
+Provides SQLAlchemy ORM data models for user authentication, SSH key storage, and per-user configuration management.
 ## parent
 index: apps/api/src/models/.pi-map.index.md
 map: apps/api/src/models/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/api/src/models/user
 index: apps/api/src/models/user/.pi-map.index.md
 ## role
-Provides the core data models for user identity, authentication credentials, and personal configuration in the API's database layer.
+Provides SQLAlchemy ORM data models for user authentication, SSH key storage, and per-user configuration management.
 ## files
 - __init__.py | Exports the user-related model classes (SSHKey, User, UserConfig) from a package for convenient importing. | dep: src.models.user.ssh_key, src.models.user.user, src.models.user.user_config
 - ssh_key.py | Defines an SSHKey SQLAlchemy ORM model for storing encrypted SSH key pairs with user and optional project associations. | exp: class:SSHKey | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models.user
 - user.py | Defines a SQLAlchemy ORM model for a User entity with authentication fields and relationships to projects, SSH keys, and user configuration. | exp: class:User | dep: typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.project, src.models, src.models.SSHKey, src.models.UserConfig
 - user_config.py | Defines a SQLAlchemy model for storing per-user JSON configuration with typed property accessors for default profile IDs. | exp: class:UserConfig | dep: uuid, typing, sqlalchemy, sqlalchemy.orm, src.models.base, src.models.user
 ## arch
-Follows SQLAlchemy ORM declarative model pattern with package-level aggregation via __init__.py, using explicit table relationships (foreign keys, one-to-many associations) and a JSON-backed configuration store with typed property accessors.
+Classic SQLAlchemy ORM model package pattern with declarative models, explicit table relationships, and a package-level __init__.py facade for clean imports.
 ## tags
 user, src, models, sqlalchemy, sshkey, orm, model, ssh
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas
 ## role
-Defines Pydantic schemas for data validation, serialization, and API request/response models in the FastAPI application.
+Defines Pydantic schemas for data validation and serialization in the API layer.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
@@ -4,11 +4,11 @@ dir: apps/api/src/schemas
 index: apps/api/src/schemas/.pi-map.index.md
 ## role
-Defines Pydantic schemas for data validation, serialization, and API request/response models in the FastAPI application.
+Defines Pydantic schemas for data validation and serialization in the API layer.
 ## files
 - __init__.py | Empty file with no functionality
 ## arch
-Modular schema organization following FastAPI/Pydantic patterns, with empty __init__.py indicating package initialization for future schema modules.
+Standard Python package structure using __init__.py to mark the directory as an importable package, likely intended for request/response models following FastAPI/Pydantic patterns.
 ## tags
 init, empty, functionality
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas/config
 ## role
-Provides Pydantic validation schemas for configuration profile API endpoints, ensuring data integrity for mounts, git URLs, UUIDs, and file paths.
+Defines Pydantic validation schemas for configuration profile API request/response models with strict input validation.
 ## parent
 index: apps/api/src/schemas/.pi-map.index.md
 map: apps/api/src/schemas/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/schemas/config
 index: apps/api/src/schemas/config/.pi-map.index.md
 ## role
-Provides Pydantic validation schemas for configuration profile API endpoints, ensuring data integrity for mounts, git URLs, UUIDs, and file paths.
+Defines Pydantic validation schemas for configuration profile API request/response models with strict input validation.
 ## files
 - __init__.py | Re-exports Pydantic schemas for configuration profile operations from a submodule to provide a clean public API. | dep: src.schemas.config.config_profile
 - config_profile.py | Defines Pydantic request/response schemas for config profile API operations with validation for mounts, git URLs, UUIDs, and file paths. | exp: class:GitMountMapping, class:GitMountItem, class:MountItem, class:ConfigProfileCreate, class:ConfigProfileUpdate, class:ConfigProfileIncludeUpdate, class:ConfigProfileResponse, class:DefaultProfilesUpdate, class:ValidateGitUrlRequest, class:ValidateGitUrlResponse, func:_validate_uuid(v: str | None) → str | None, call:uuid.UUID, raise:ValueError | dep: uuid, pydantic, src.api.shared_validators
 ## arch
-Simple schema-as-code pattern using Pydantic models with field validators; clean public API via explicit re-exports in `__init__.py`.
+Standard Python package pattern using `__init__.py` re-exports to expose a clean public API from internal modules, with Pydantic-based schema-per-resource organization.
 ## tags
 profile, config, git, mount, update, validate, response, item
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas/project
 ## role
-Provides Pydantic data validation schemas for project-related API endpoints including projects, Git repositories, and SSH keys.
+Defines Pydantic data validation schemas for project-related API endpoints, serving as the contract layer between HTTP requests/responses and internal business logic.
 ## parent
 index: apps/api/src/schemas/.pi-map.index.md
 map: apps/api/src/schemas/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/api/src/schemas/project
 index: apps/api/src/schemas/project/.pi-map.index.md
 ## role
-Provides Pydantic data validation schemas for project-related API endpoints including projects, Git repositories, and SSH keys.
+Defines Pydantic data validation schemas for project-related API endpoints, serving as the contract layer between HTTP requests/responses and internal business logic.
 ## files
 - __init__.py | Re-exports Pydantic schema classes from submodules to provide a unified public API for the project schemas module | dep: src.schemas.project.git_repository, src.schemas.project.project, src.schemas.project.ssh_key
 - git_repository.py | Defines Pydantic request/response schemas for Git repository operations in an API. | exp: class:GitRepositoryCreate, class:URLParseRequest, class:URLParseResponse, class:GitRepositoryResponse, class:UpdateSSHKeyRequest, class:FileListResponse, class:FileContentResponse, class:BranchesResponse, class:FileUpdateRequest, class:FileUpdateResponse, class:StatusResponse, class:BranchCreateRequest, class:CheckoutRequest, class:CommitRequest, class:CommitResponse, class:FetchResponse, class:PullResponse, class:PushResponse, class:MergeRequest, class:MergeResponse | dep: uuid, datetime, pydantic
 - project.py | Defines Pydantic request/response schemas for project-related API operations. | exp: class:ProjectCreate, class:ProjectUpdate, class:ProjectResponse, class:SetDefaultSSHKeyRequest | dep: uuid, pydantic
 - ssh_key.py | Defines Pydantic schemas for SSH key creation, response, signing, and signature verification in an API. | exp: class:SSHKeyCreate, class:SSHKeyResponse, class:SignPayloadRequest, class:SignatureResponse, class:VerifySignatureRequest, class:VerifySignatureResponse | dep: uuid, datetime, pydantic
 ## arch
-Modular schema-per-domain pattern with clean separation of concerns, using Pydantic models for request/response validation and an `__init__.py` facade for unified public API access.
+Modular schema decomposition with submodule-per-domain pattern (project, git_repository, ssh_key) aggregated through __init__.py barrel exports, using Pydantic models for declarative validation and serialization.
 ## tags
 response, request, project, create, update, sshkey, pydantic, schemas
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas/system
 ## role
-Provides Pydantic schemas for system health monitoring endpoints in the API.
+Provides Pydantic schema definitions for system health monitoring API responses.
 ## parent
 index: apps/api/src/schemas/.pi-map.index.md
 map: apps/api/src/schemas/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/schemas/system
 index: apps/api/src/schemas/system/.pi-map.index.md
 ## role
-Provides Pydantic schemas for system health monitoring endpoints in the API.
+Provides Pydantic schema definitions for system health monitoring API responses.
 ## files
 - __init__.py | Re-exports health check schema classes from a submodule to provide a unified interface for the system schemas module. | dep: src.schemas.system.health
 - health.py | Defines Pydantic data models for health check API responses including database, disk, and overall system health status. | exp: class:DatabaseHealth, class:DiskHealth, class:HealthChecks, class:HealthResponse, class:DatabaseHealthResponse | dep: pydantic
 ## arch
-Simple submodule pattern with explicit re-exports in __init__.py, using Pydantic models for structured API response validation.
+Simple modular schema layer with submodule organization and re-export pattern for clean API surface.
 ## tags
 health, database, response, system, disk, check, schemas, init
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas/tool
 ## role
-Provides Pydantic data validation schemas for tool-related API operations including tool types and instances.
+Defines Pydantic data validation schemas for tool instance and tool type API operations in the API layer.
 ## parent
 index: apps/api/src/schemas/.pi-map.index.md
 map: apps/api/src/schemas/.pi-map.md
@@ -4,17 +4,18 @@ dir: apps/api/src/schemas/tool
 index: apps/api/src/schemas/tool/.pi-map.index.md
 ## role
-Provides Pydantic data validation schemas for tool-related API operations including tool types and instances.
+Defines Pydantic data validation schemas for tool instance and tool type API operations in the API layer.
 ## files
- __init__.py | Re-exports tool-related schema classes from submodules to provide a unified import interface for the tool schemas module. | dep: src.schemas.tool.tool_instance, src.schemas.tool.tool_type
+- __init__.py | Package initialization file that exposes tool-related schema classes for import convenience. | dep: src.schemas.tool.tool_instance, src.schemas.tool.tool_type
- tool_instance.py | Defines Pydantic request/response schemas for tool instance lifecycle operations (create and start). | exp: class:CreateInstanceRequest, class:StartInstanceRequest | dep: pydantic
+- tool_instance.py | Defines Pydantic request/response schemas for tool instance lifecycle operations (create, create-on-workspace, start). | exp: class:CreateInstanceRequest, class:CreateWorkspaceInstanceRequest, class:StartInstanceRequest | dep: pydantic
- tool_type.py | Defines Pydantic request/response schemas for creating, updating, and validating tool types with Docker compose/dockerfile/manifest definitions | exp: class:ToolTypeCreate, class:ToolTypeUpdate, class:ToolTypeResponse, class:ToolTypeValidateRequest | dep: uuid, datetime, pydantic, src.api.tool.tool_types_validation
+- tool_type.py | Defines Pydantic request/response schemas for tool type CRUD operations with conditional validation logic based on definition type (compose/dockerfile/manifest). | exp: class:ToolTypeCreate, class:ToolTypeUpdate, class:ToolTypeResponse, class:ToolTypeValidateRequest | dep: uuid, datetime, pydantic, src.api.tool.tool_types_validation
 ## arch
-Modular schema organization with submodule-per-entity pattern and unified re-export interface via `__init__.py`, following standard Python package structure for clean API imports.
+Standard Pydantic schema package pattern with type-specific conditional validation using discriminated unions or field validators based on definition type.
 ## tags
-tool, type, request, instance, schemas, create, pydantic, response
+tool, type, request, instance, create, schemas, pydantic, response
 ## symbols
 - CreateInstanceRequest
 - CreateWorkspaceInstanceRequest
 - StartInstanceRequest
 - ToolTypeCreate
 - ToolTypeUpdate
@@ -2,7 +2,7 @@
 dir: apps/api/src/schemas/user
 ## role
-Provides centralized Pydantic data validation schemas for user-related API requests and responses.
+Provides Pydantic data validation schemas for user-related API requests and responses.
 ## parent
 index: apps/api/src/schemas/.pi-map.index.md
 map: apps/api/src/schemas/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/api/src/schemas/user
 index: apps/api/src/schemas/user/.pi-map.index.md
 ## role
-Provides centralized Pydantic data validation schemas for user-related API requests and responses.
+Provides Pydantic data validation schemas for user-related API requests and responses.
 ## files
 - __init__.py | Re-exports user-related Pydantic schemas from submodules to provide a unified public API for the user schemas package. | dep: src.schemas.user.user, src.schemas.user.user_config
 - user.py | Defines Pydantic response and update schemas for user profile data | exp: class:UserProfileResponse, class:UserProfileUpdate | dep: uuid, pydantic
 - user_config.py | Defines Pydantic models for user configuration data transfer objects (response and update schemas). | exp: class:UserConfigResponse, class:UserConfigUpdate | dep: pydantic
 ## arch
-Modular package pattern with submodule separation of concerns (user profile vs. user config) and unified public API via `__init__.py` re-exports.
+Modular schema organization with submodule separation of concerns and unified package-level re-exports for clean imports.
 ## tags
 user, schemas, response, update, config, pydantic, profile, src
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/scripts
 ## role
-Provides utility scripts for administrative and setup tasks for the API application.
+Provides utility scripts for administrative and setup tasks for the API application, specifically database seeding.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/scripts
 index: apps/api/src/scripts/.pi-map.index.md
 ## role
-Provides utility scripts for administrative and setup tasks for the API application.
+Provides utility scripts for administrative and setup tasks for the API application, specifically database seeding.
 ## files
 - __init__.py | Marks the directory as a Python package and provides a docstring describing it as utility scripts for the API package.
 - seed.py | Seeds a development user into the database using SQLAlchemy async operations, with idempotency check to avoid duplicates. | exp: func:build_seed_user() → Mapping[str, str | None], func:seed_database(session: AsyncSession) → User, call:build_seed_user, call:session.scalar, call:select(User).where, call:User, call:session.add, call:session.commit, call:session.refresh, func:run() → None, call:SessionLocal, call:seed_database, call:print, call:str, func:main() → None, call:asyncio.run, call:run | dep: collections.abc, sqlalchemy, sqlalchemy.ext.asyncio, src.database, src.models.user, asyncio
 ## arch
-Simple procedural scripts using async SQLAlchemy for database operations, with idempotency guards for safe re-runs.
+Simple procedural script architecture with async SQLAlchemy database operations and idempotent initialization patterns.
 ## tags
 seed, user, database, sqlalchemy, package, init, call:build, call:session.scalar
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/seeds
 ## role
-Provides database seeding utilities for initializing built-in tool types in the API application.
+Provides database seeding utilities for initializing built-in tool type configurations in the API application.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/api/src/seeds
 index: apps/api/src/seeds/.pi-map.index.md
 ## role
-Provides database seeding utilities for initializing built-in tool types in the API application.
+Provides database seeding utilities for initializing built-in tool type configurations in the API application.
 ## files
 - __init__.py | Marks the directory as a Python package for database seeding utilities.
- builtin_tool_types.py | Seeds built-in Docker Compose-based tool types (VS Code Server, Jupyter Notebook, OpenCode) into a database with idempotent create-or-update logic. | exp: func:_table_exists(session, table_name: str) → bool, call:session.execute, call:text, call:result.scalar, func:seed_builtin_tool_types(), call:SessionLocal, call:_table_exists, call:logger.warning, call:session.scalar, call:select(ToolType).where, call:ToolType, call:tool_data.get, call:session.add, call:logger.info, call:session.commit | dep: logging, sqlalchemy, src.database, src.models
+- builtin_tool_types.py | Seeds built-in tool types (code-server, jupyter-notebook, opencode) into a database with upsert logic, creating or updating Docker Compose-based development environment templates. | exp: func:_table_exists(session, table_name: str) → bool, call:session.execute, call:text, call:result.scalar, func:seed_builtin_tool_types(), call:SessionLocal, call:_table_exists, call:logger.warning, call:session.scalar, call:select(ToolType).where, call:ToolType, call:tool_data.get, call:session.add, call:logger.info, call:session.commit | dep: logging, sqlalchemy, src.database, src.models
 ## arch
-Simple procedural seeding scripts with idempotent create-or-update logic using direct database operations, organized as a Python package with one seed module per entity type.
+Simple procedural seeding script using SQLAlchemy upsert operations to populate reference data for containerized development environment templates.
 ## tags
 tool, types, table, exists, builtin, call:tool, database, init
 ## symbols
@@ -103,11 +103,8 @@ services:
    image: node:20-slim
    container_name: {{TOOL_NAME}}
    working_dir: /workspace
    environment:
      - HOME=/tmp
    volumes:
      - {{REPO_PATH}}:/workspace
      - opencode_home:/tmp
    ports:
      - "3000:3000"
    command: >
@@ -125,10 +122,7 @@ services:
             exec tail -f /dev/null"
    stdin_open: true
    tty: true
-    restart: unless-stopped
+    restart: unless-stopped""",
 volumes:
  opencode_home:""",
                "required_variables": ["REPO_PATH", "TOOL_NAME"],
            },
        ]
@@ -2,7 +2,7 @@
 dir: apps/api/src/services
 ## role
-Initializes the services directory as a Python package for business logic modules.
+Marks the services directory as a Python package for business logic layer components.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
@@ -4,11 +4,11 @@ dir: apps/api/src/services
 index: apps/api/src/services/.pi-map.index.md
 ## role
-Initializes the services directory as a Python package for business logic modules.
+Provides a Python package namespace for organizing service-layer modules in the API application.
 ## files
 - __init__.py | Empty file with no functionality
 ## arch
-Standard Python package structure using empty __init__.py for namespace declaration.
+Standard Python package structure using __init__.py for directory-based module organization, following conventional layered architecture patterns.
 ## tags
 init, empty, functionality
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/config
 ## role
-Provides configuration profile resolution, validation, and CRUD operations for managing hierarchical, mergeable configuration with environment-aware overrides and Git integration.
+Provides configuration profile management with recursive resolution, validation, and access control for container environment setup.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
@@ -4,16 +4,16 @@ dir: apps/api/src/services/config
 index: apps/api/src/services/config/.pi-map.index.md
 ## role
-Provides configuration profile resolution, validation, and CRUD operations for managing hierarchical, mergeable configuration with environment-aware overrides and Git integration.
+Provides configuration profile management with recursive resolution, validation, and access control for container environment setup.
 ## files
 - __init__.py | Re-exports configuration profile resolution components from a subpackage to provide a unified public API. | dep: src.services.config.config_profile_resolver
- config_profile_resolver.py | Resolves configuration profiles recursively with ordered include merging, cycle detection, and deterministic override rules for environment variables, runtime hints, files, mounts, and git mounts. | exp: class:ConfigProfileCycleError, class:ConfigProfileNotFoundError, class:ResolvedMount, class:ResolvedProfile, func:_detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → bool, func:_merge_env_vars(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_runtime_hints(base: dict[str, Any], overlay: dict[str, Any], overrides: dict[str, str], source_name: str) → dict[str, Any], call:dict, call:overlay.items, func:_merge_files(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_mounts(base: dict[str, ResolvedMount], overlay: list[dict[str, Any]], overrides: dict[str, str], source_name: str) → dict[str, ResolvedMount], call:dict, call:mount_data.get, call:files.items, call:ResolvedMount, func:_merge_git_mounts(base: list[dict[str, Any]], overlay: list[dict[str, Any]], source_name: str) → list[dict[str, Any]], call:list, call:enumerate, call:_normalize_git_mount_entry, call:dict, call:m.get, call:mount.get, call:existing.get, call:existing["mappings"].append, call:existing_sources.add, call:len, call:result.append, func:_normalize_git_mount_entry(entry: dict[str, Any]) → dict[str, Any], call:dict, call:entry.get, call:entry.pop, func:_resolve_profile_recursive(session: AsyncSession, profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → ResolvedProfile, call:_detect_cycle, call:" -> ".join, call:str, call:session.get, call:ResolvedProfile, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == profile_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_resolve_profile_recursive, call:result.included_profiles.append, call:_merge_env_vars, call:_merge_runtime_hints, call:_merge_files, call:_merge_mounts, call:included.mounts.values, call:_merge_git_mounts, raise:ConfigProfileCycleError, raise:ConfigProfileNotFoundError, func:resolve_profile(session: AsyncSession, profile_id: uuid.UUID) → ResolvedProfile, call:_resolve_profile_recursive, call:set, func:check_include_cycle(session: AsyncSession, profile_id: uuid.UUID, new_include_id) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, call:set, call:len, func:_check_from(current_id: uuid.UUID, target_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, func:apply_resolved_profile(instance_dir: str, resolved: ResolvedProfile, home_dir) → tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]], call:Path, call:dict, call:files.items, call:full_path.resolve().relative_to, call:instance_path.resolve, call:logger.warning, call:full_path.parent.mkdir, call:full_path.write_text, call:resolved.mounts.values, call:expand_container_path, call:expanded_target.lstrip("/").replace, call:mount_dir.mkdir, call:mount.files.items, call:mount_dir.resolve, call:os.path.join, call:volume_mounts.append, call:str, func:expand_container_path(path: str, home_dir: str) → str, call:path.startswith, call:os.path.join, func:resolved_profile_to_dict(resolved: ResolvedProfile) → dict[str, Any], call:str, call:resolved.mounts.values | dep: logging, os, uuid, dataclasses, typing, sqlalchemy, sqlalchemy.ext.asyncio, src.models, pathlib
+- config_profile_resolver.py | Resolves configuration profiles recursively with ordered includes, deterministic merge rules, and cycle protection for container environment setup. | exp: class:ConfigProfileCycleError, class:ConfigProfileNotFoundError, class:ResolvedMount, class:ResolvedProfile, func:_detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → bool, func:_merge_env_vars(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_runtime_hints(base: dict[str, Any], overlay: dict[str, Any], overrides: dict[str, str], source_name: str) → dict[str, Any], call:dict, call:overlay.items, func:_merge_files(base: dict[str, str], overlay: dict[str, str], overrides: dict[str, str], source_name: str) → dict[str, str], call:dict, call:overlay.items, func:_merge_mounts(base: dict[str, ResolvedMount], overlay: list[dict[str, Any]], overrides: dict[str, str], source_name: str) → dict[str, ResolvedMount], call:dict, call:mount_data.get, call:files.items, call:ResolvedMount, func:_merge_git_mounts(base: list[dict[str, Any]], overlay: list[dict[str, Any]], source_name: str) → list[dict[str, Any]], call:list, call:enumerate, call:_normalize_git_mount_entry, call:dict, call:m.get, call:mount.get, call:existing.get, call:existing["mappings"].append, call:existing_sources.add, call:len, call:result.append, func:_normalize_git_mount_entry(entry: dict[str, Any]) → dict[str, Any], call:dict, call:entry.get, call:entry.pop, func:_resolve_profile_recursive(session: AsyncSession, profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → ResolvedProfile, call:_detect_cycle, call:" -> ".join, call:str, call:session.get, call:ResolvedProfile, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == profile_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_resolve_profile_recursive, call:result.included_profiles.append, call:_merge_env_vars, call:_merge_runtime_hints, call:_merge_files, call:_merge_mounts, call:included.mounts.values, call:_merge_git_mounts, raise:ConfigProfileCycleError, raise:ConfigProfileNotFoundError, func:resolve_profile(session: AsyncSession, profile_id: uuid.UUID) → ResolvedProfile, call:_resolve_profile_recursive, call:set, func:check_include_cycle(session: AsyncSession, profile_id: uuid.UUID, new_include_id) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, call:set, call:len, func:_check_from(current_id: uuid.UUID, target_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) → list[uuid.UUID] | None, call:select(ConfigProfileInclude) .where(ConfigProfileInclude.profile_id == current_id) .order_by, call:session.execute, call:include_result.scalars().all, call:_check_from, func:apply_resolved_profile(instance_dir: str, resolved: ResolvedProfile, home_dir) → tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]], call:Path, call:dict, call:files.items, call:full_path.resolve().relative_to, call:instance_path.resolve, call:logger.warning, call:full_path.parent.mkdir, call:full_path.write_text, call:resolved.mounts.values, call:os.path.normpath, call:expand_container_path, call:expanded_target.lstrip("/").replace, call:mount_dir.mkdir, call:mount.files.items, call:mount_dir.resolve, call:volume_mounts.append, call:str, func:expand_container_path(path: str, home_dir: str) → str, call:path.startswith, call:os.path.join, func:resolved_profile_to_dict(resolved: ResolvedProfile) → dict[str, Any], call:str, call:resolved.mounts.values | dep: logging, os, uuid, dataclasses, typing, sqlalchemy, sqlalchemy.ext.asyncio, src.models, pathlib
 - crud_service.py | Provides CRUD operations for configuration profiles including validation, access control, size limits, and include cycle detection. | exp: func:calculate_profile_size(data: dict) → int, call:data.get("env_vars", {}).items, call:len, call:key.encode, call:str(value).encode, call:data.get("runtime_hints", {}).items, call:str(mount.get("target", "")).encode, call:str(mount.get("mode", "")).encode, call:mount.get("files", {}).items, call:path.encode, call:content.encode, call:data.get("files", {}).items, func:get_profile_with_includes(session: AsyncSession, profile_id: uuid.UUID) → ConfigProfile | None, call:session.execute, call:select(ConfigProfile) .where(ConfigProfile.id == profile_id) .options, call:selectinload, call:result.scalar_one_or_none, func:check_access(session: AsyncSession, user_id: uuid.UUID, project_id, tool_type_id) → None, call:session.get, raise:HTTPException, func:validate_git_mounts(session: AsyncSession, user_id: uuid.UUID, git_mounts: list[Any], project_id) → None, call:mount.get, call:remote_url.startswith, raise:HTTPException, func:profile_to_response(profile: ConfigProfile, includes) → dict, call:str, call:profile.created_at.isoformat, call:profile.updated_at.isoformat, func:get_or_create_user_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, func:validate_default_profiles(session: AsyncSession, user_id: uuid.UUID, default_profiles: dict[str, str]) → None, call:default_profiles.items, call:uuid.UUID, call:session.get, raise:HTTPException, func:create_profile(session: AsyncSession, user_id: uuid.UUID, data: Any) → ConfigProfile, call:session.execute, call:select(ConfigProfile) .where( ConfigProfile.user_id == user_id, ConfigProfile.name == data.name, ) .options, call:selectinload, call:existing.scalar_one_or_none, call:uuid.UUID, call:check_access, call:m.model_dump, call:hasattr, call:validate_git_mounts, call:calculate_profile_size, call:data.model_dump, call:ConfigProfile, call:session.add, call:session.commit, call:select(ConfigProfile) .where(ConfigProfile.id == profile.id) .options, call:result.scalar_one, raise:HTTPException, func:update_profile(session: AsyncSession, profile: ConfigProfile, data: Any) → ConfigProfile, call:data.model_dump, call:session.execute, call:select(ConfigProfile).where, call:existing.scalar_one_or_none, call:uuid.UUID, call:check_access, call:m.model_dump, call:hasattr, call:validate_git_mounts, call:profile_to_response, call:calculate_profile_size, call:update_data.items, call:isinstance, call:setattr, call:session.commit, call:select(ConfigProfile) .where(ConfigProfile.id == profile.id) .options, call:selectinload, call:result.scalar_one, raise:HTTPException, func:update_includes(session: AsyncSession, profile: ConfigProfile, included_ids: list[uuid.UUID], user_id: uuid.UUID) → ConfigProfile, call:session.get, call:check_include_cycle, call:" -> ".join, call:str, call:session.execute, call:select(ConfigProfileInclude).where, call:result.scalars().all, call:session.delete, call:session.flush, call:enumerate, call:ConfigProfileInclude, call:session.add, call:session.commit, call:select(ConfigProfile).where, call:result.scalar_one, raise:HTTPException | dep: uuid, typing, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, sqlalchemy.orm, src.models, src.models.project, src.services.config.config_profile_resolver
 - resolver_service.py | Resolves default configuration profiles for users/projects/tools and validates Git URLs with SSH key support. | exp: func:resolve_default_profile(session: AsyncSession, user_id: uuid.UUID, project_id: uuid.UUID, tool_type_id: uuid.UUID) → dict, call:select(ConfigProfile) .where(ConfigProfile.user_id == user_id) .where( (ConfigProfile.project_id.is_(None) & ConfigProfile.tool_type_id.is_(None)) | (ConfigProfile.project_id == project_id) | (ConfigProfile.tool_type_id == tool_type_id) | ( (ConfigProfile.project_id == project_id) & (ConfigProfile.tool_type_id == tool_type_id) ) ) .order_by, call:ConfigProfile.project_id.is_, call:ConfigProfile.tool_type_id.is_, call:session.execute, call:result.scalars().all, call:str, func:validate_git_url(session: AsyncSession, current_user_id: uuid.UUID, url: str, ssh_key_id: str | None) → ValidateGitUrlResponse, call:parse_git_url, call:url.strip, call:parse_result.get, call:ValidateGitUrlResponse, call:uuid.UUID, call:session.get, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:tempfile.mkstemp, call:os.write, call:private_key.encode, call:os.close, call:os.chmod, call:subprocess.run, call:os.path.exists, call:os.unlink, call:result.stderr.strip, call:stderr.lower, call:result.stdout.strip().split, call:line.strip, call:line.split, call:len, call:ref.startswith, call:branches.append | dep: logging, os, subprocess, uuid, typing, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.models, src.services.shared.ssh_keys, src.utils.git_url_parser, src.schemas.config, tempfile
 ## arch
-Layered service architecture with separation between resolution logic (recursive merge with cycle detection), CRUD operations (validation, access control, limits), and default resolution (user/project/tool scoping, Git/SSH integration), exposing a unified public API through `__init__.py` facade pattern.
+Layered service architecture with separation between resolution logic (recursive merge with cycle detection), CRUD operations (validation, access control, size limits), and default resolution (Git/SSH integration), exposed through a unified facade pattern via __init__.py.
 ## tags
-profile, call:, call:select, git, merge, call:str, call:session.execute, mounts
+profile, call:, call:select, merge, git, call:str, call:session.execute, cycle
 ## symbols
 - ConfigProfileCycleError
 - ConfigProfileNotFoundError
@@ -476,9 +476,19 @@ def apply_resolved_profile(
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(content)
-    # Stage mount files and prepare volume mounts
+    # Stage mount directories and prepare directory-level volume mounts.
    # Each ResolvedMount targets a container directory; we stage all of its
    # files under a single host directory and bind-mount that directory. This
    # keeps the target directory writable by the container user, instead of
    # having Docker create a root-owned parent directory when only individual
    # files are mounted.
    for mount in resolved.mounts.values():
-        expanded_target = expand_container_path(mount.target, home_dir)
+        if not mount.files:
            continue
        expanded_target = os.path.normpath(
            expand_container_path(mount.target, home_dir)
        )
        mount_dir = (
            instance_path / "mounts" / expanded_target.lstrip("/").replace("/", "_")
        )
@@ -494,16 +504,14 @@ def apply_resolved_profile(
            full_path.parent.mkdir(parents=True, exist_ok=True)
            full_path.write_text(content)
-            # Mount each file individually so sibling files from other mounts
+        volume_mounts.append(
-            # (e.g. git repo directories) are preserved.
+            {
-            file_target = os.path.join(expanded_target, file_path)
+                "source": str(mount_dir),
-            volume_mounts.append(
+                "target": expanded_target,
-                {
+                "type": "bind",
-                    "source": str(full_path),
+                "readonly": mount.mode in ("ro", "readonly"),
-                    "target": file_target,
+            }
-                    "type": "bind",
+        )
                }
            )
    return env_vars, files, volume_mounts, resolved.runtime_hints
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/docker
 ## role
-Provides Docker-based infrastructure services for container orchestration, configuration management, runtime operations, and secure tunneling to expose internal services.
+Provides Docker infrastructure services for container lifecycle management, compose orchestration, configuration deployment, and secure tunneling to expose internal services.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/api/src/services/docker
 index: apps/api/src/services/docker/.pi-map.index.md
 ## role
-Provides Docker-based infrastructure services for container orchestration, configuration management, runtime operations, and secure tunneling to expose internal services.
+Provides Docker infrastructure services for container lifecycle management, compose orchestration, configuration deployment, and secure tunneling to expose internal services.
 ## files
 - __init__.py | Package initialization file that exposes Docker-related service functions for container operations, compose management, configuration staging, and tunnel management. | dep: src.services.docker.compose, src.services.docker.config_staging, src.services.docker.container, src.services.docker.tunnel
 - compose.py | Generates, renders, and executes Docker Compose commands for container orchestration with volume sorting and template substitution. | exp: func:sort_volumes_by_specificity(volumes: list[str]) → list[str], call:vol.split, call:len, call:parts[1].rstrip, call:target.count, call:targets.append, call:Counter(targets).items, call:logger.warning, call:sorted, func:_target_depth(vol: str) → int, call:vol.split, call:len, call:parts[1].rstrip, call:target.count, func:render_compose_template(template: str, variables: dict[str, Any]) → str, call:variables.items, call:result.replace, call:str, func:write_compose_file(instance_dir: str, content: str) → str, call:Path, call:compose_path.write_text, call:str, func:execute_compose_command(compose_path: str, action: str, timeout, env_file) → tuple[int, str, str], call:Path, call:cmd.extend, call:cmd.append, call:subprocess.run, call:str, raise:ValueError | dep: logging, subprocess, collections, pathlib, typing, collections.Counter, pathlib.Path, typing.Any
@@ -12,7 +12,7 @@ Provides Docker-based infrastructure services for container orchestration, confi
 - container.py | Provides Docker container runtime queries and network management utilities via subprocess calls to the Docker CLI. | exp: func:get_container_id(instance_name: str) → str | None, call:instance_name.lower, call:subprocess.run, call:result.stdout.strip, call:ps_result.stdout.strip().splitlines, call:line.split, call:len, call:name.lower, func:get_container_name(instance_name: str) → str | None, call:subprocess.run, call:instance_name.lower, call:result.stdout.strip().lstrip, func:get_backend_network_name() → str, call:subprocess.run, call:result.stdout.strip().split, call:net.lower, func:connect_container_to_network(container_name: str, network_name) → bool, call:get_backend_network_name, call:subprocess.run, func:get_container_ip_on_network(container_id: str, network_name) → str | None, call:get_backend_network_name, call:subprocess.run, call:result.stdout.strip, func:is_container_on_network(container_id: str, network_name) → bool, call:get_backend_network_name, call:subprocess.run, func:get_container_status(container_id: str) → dict[str, Any], call:subprocess.run, call:result.stdout.strip().split, call:int, call:len, call:parts[1].isdigit, func:wait_for_container_running(container_id: str, timeout, interval) → dict[str, Any], call:time.time, call:get_container_status, call:time.sleep, func:get_container_logs(container_id: str, tail) → str, call:subprocess.run, call:str, func:find_free_port(start, end) → int, call:range, call:socket.socket, call:s.connect_ex, raise:RuntimeError | dep: logging, subprocess, time, typing, socket
 - tunnel.py | Manages Cloudflare tunnels by orchestrating cloudflared Docker containers to expose internal services via temporary public URLs. | exp: func:_tunnel_container_name(instance_name: str) → str, call:instance_name.lower, func:_ensure_image() → None, call:subprocess.run, call:result.stdout.strip, call:logger.info, call:logger.warning, func:_cleanup_stale_tunnel(tunnel_name: str) → None, call:subprocess.run, func:_get_tunnel_logs(tunnel_name: str) → tuple[str, str], call:subprocess.run, func:_get_tunnel_exit_code(tunnel_name: str) → int | None, call:subprocess.run, call:int, call:result.stdout.strip, func:start_tunnel(instance_name: str, container_port: int, timeout, target_url) → dict[str, str], call:_ensure_image, call:_tunnel_container_name, call:_cleanup_stale_tunnel, call:instance_name.lower, call:get_backend_network_name, call:logger.debug, call:" ".join, call:subprocess.run, call:proc.stdout.strip, call:re.compile, call:__import__("time").time, call:_get_tunnel_logs, call:url_pattern.search, call:match.group, call:_get_tunnel_exit_code, call:__import__("time").sleep, call:logger.info, raise:RuntimeError, func:stop_tunnel(instance_name: str) → None, call:_tunnel_container_name, call:_cleanup_stale_tunnel, call:logger.debug, func:recreate_tunnel(instance_name: str, container_port: int, target_url) → dict[str, str], call:stop_tunnel, call:start_tunnel, func:check_tunnel_health(url: str, timeout) → dict[str, Any], call:subprocess.run, call:int, call:result.stdout.strip, call:str(exc).lower, call:any | dep: logging, re, subprocess, typing, src.services.docker.container
 ## arch
-Modular service-oriented architecture with subprocess-based Docker CLI integration, Jinja2 templating for compose generation, path-traversal-safe file staging, and Cloudflare tunnel orchestration via containerized cloudflared.
+Subprocess-based CLI wrapper architecture around Docker/cloudflared tools with template rendering, path-traversal-safe file staging, and functional decomposition into single-responsibility modules.
 ## tags
 tunnel, container, call:subprocess.run, get, name, call:, network, call:result.stdout.strip
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/git
 ## role
-Provides git repository operations for workspace management including cloning, authentication, and common git commands
+Encapsulates all Git version control operations for workspace management, providing both synchronous and asynchronous interfaces for repository cloning, commit history, branch management, and remote operations with SSH authentication support.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/api/src/services/git
 index: apps/api/src/services/git/.pi-map.index.md
 ## role
-Provides git repository operations for workspace management including cloning, authentication, and common git commands
+Encapsulates all Git version control operations for workspace management, providing both synchronous and asynchronous interfaces for repository cloning, commit history, branch management, and remote operations with SSH authentication support.
 ## files
 - __init__.py | Exports the public API for the git services module by re-exporting key classes and functions from submodules. | dep: src.services.git.clone, src.services.git.git_operations, src.services.git.git_service
 - clone.py | Provides git repository cloning with optional SSH authentication, dirty state checking, and cleanup utilities | exp: func:clone_repository(remote_url: str, ssh_key_path: str | None, instance_dir: str, branch) → str, call:Path, call:clone_path.mkdir, call:os.environ.copy, call:str, call:logger.debug, call:subprocess.run, call:logger.error, raise:RuntimeError, func:check_dirty_state(clone_path: str) → tuple[bool, list[str]], call:subprocess.run, call:logger.warning, call:line.strip, call:result.stdout.split, call:len, func:remove_clone_directory(instance_dir: str) → None, call:Path, call:clone_path.exists, call:shutil.rmtree, call:logger.debug | dep: logging, os, subprocess, pathlib, shutil
@@ -12,7 +12,7 @@ Provides git repository operations for workspace management including cloning, a
 - git_service.py | Provides asynchronous and synchronous git operations (clone, fetch, pull, branch check) with SSH key support for workspace management. | exp: class:GitService | dep: asyncio, logging, os, subprocess, tempfile
 - operations.py | Provides git repository operations including cloning, initialization, remote validation, and branch listing with SSH key authentication support. | exp: func:get_repo_path(user_id: uuid.UUID, project_id: uuid.UUID, name: str) → str, call:Settings, call:os.path.join, call:str, func:build_provider_clone_url(owner: str, repo: str) → str, func:prepare_ssh_env(ssh_key: SSHKey | None) → tuple[dict, str] | None, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:tempfile.mkstemp, call:os.write, call:private_key.encode, call:os.close, call:os.chmod, func:preflight_remote_repository(remote_url: str, ssh_key) → None, call:prepare_ssh_env, call:subprocess.run, call:os.path.exists, call:os.unlink, call:logger.error, raise:HTTPException, func:clone_working_repository(remote_url: str, repo_path: str, ssh_key) → None, call:prepare_ssh_env, call:subprocess.run, call:os.path.exists, call:os.unlink, call:logger.error, raise:HTTPException, func:init_working_repository(repo_path: str) → None, call:subprocess.run, raise:HTTPException, func:list_remote_branches(remote_url: str, ssh_key) → tuple[list[str], str], call:prepare_ssh_env, call:subprocess.run, call:logger.warning, call:result.stdout.strip().split, call:line.split, call:len, call:ref.startswith, call:branches.append, call:str, call:os.path.exists, call:os.unlink, raise:RuntimeError | dep: logging, os, subprocess, uuid, fastapi, src.config, src.models, src.services.shared.ssh_keys, tempfile
 ## arch
-Layered service architecture with operation decomposition across specialized modules (clone, operations, git_operations, git_service), wrapping git CLI with async/sync variants and SSH key-based authentication
+Layered abstraction pattern with three implementation tiers: low-level CLI wrappers (git_operations.py, operations.py), mid-level service coordinators (git_service.py), and high-level specialized utilities (clone.py), unified through __init__.py re-exports to present a single public API surface.
 ## tags
 git, raise:runtime, error, run, call:self., clone, call:subprocess.run, ssh
 ## symbols
@@ -11,7 +11,7 @@ Provides infrastructure for managing tool instance lifecycle events, health moni
 - health_monitor.py | Background health monitor that periodically polls Docker container and tunnel health for tool instances, publishing state change events and notifications. | exp: class:HealthSnapshot, class:HealthMonitor, method:__init__(self, event_bus: InstanceEventBus) → None, method:start(self) → None, call:self._task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._poll_loop, method:stop(self) → None, call:self._task.done, call:self._task.cancel, call:self._last_known_state.clear, method:_poll_loop(self) → None, call:asyncio.sleep, call:self._run_check_cycle, call:logger.exception, method:_run_check_cycle(self) → None, call:SessionLocal, call:session.execute, call:select(ToolInstance).where, call:ToolInstance.status.in_, call:result.scalars().all, call:self._check_instance, method:_check_instance(self, session: AsyncSession, instance: ToolInstance) → None, call:logger.debug, call:get_container_status, call:logger.exception, call:str, call:get_correlation_id, call:check_tunnel_health, call:tunnel_result.get, call:HealthSnapshot, call:self._last_known_state.get, call:self._derive_status, call:self._snapshots_equal, call:self._handle_state_change, method:_derive_status(self, snapshot: HealthSnapshot, previous: HealthSnapshot | None, current_status: str | None) → str, method:_snapshots_equal(self, a: HealthSnapshot, b: HealthSnapshot) → bool, method:_handle_state_change(self, session: AsyncSession, instance: ToolInstance, previous: HealthSnapshot | None, snapshot: HealthSnapshot, new_status: str) → None, call:HealthCheck, call:session.add, call:session.commit, call:get_correlation_id, call:str, call:datetime.now(timezone.utc).isoformat, call:self._event_bus.publish, call:notification_service.create_notification, call:logger.exception | dep: asyncio, logging, uuid, dataclasses, datetime, sqlalchemy, sqlalchemy.ext.asyncio, src.database, src.models, src.services.shared.correlation, src.services.docker, src.services.shared.tunnel, src.services.instance.event_bus, src.services.shared.notification_service
 - lifecycle_hooks.py | Provides helpers to publish tool instance lifecycle events, persist audit records, and conditionally send user notifications. | exp: func:_derive_title(event_type: str) → str, call:mapping.get, call:event_type.replace("instance.", "").replace("_", " ").title, func:_should_notify(event_type: str, status: str | None) → bool, func:_build_payload(event_type: str, instance: ToolInstance, status, message, metadata) → InstanceEventPayload, call:str, call:datetime.now(timezone.utc).isoformat, call:get_correlation_id, func:_write_audit_row(session: AsyncSession, instance: ToolInstance, event_type: str, created_by, status, message, metadata) → InstanceEvent, call:InstanceEvent, call:event_type.replace, call:session.add, call:session.commit, func:publish_lifecycle_event(event_bus: InstanceEventBus, session: AsyncSession, instance: ToolInstance, event_type: str, created_by, status, message, metadata) → None, call:_build_payload, call:_write_audit_row, call:event_bus.publish, call:_should_notify, call:_derive_title, call:notification_service.create_notification, call:logger.exception, call:payload.get | dep: logging, uuid, datetime, sqlalchemy.ext.asyncio, src.models, src.services.shared.correlation, src.services.instance.event_bus, src.services.shared.notification_service
 ## arch
-Event-driven architecture using a singleton-typed in-memory pub/sub event bus with decoupled background health monitoring, lifecycle hook orchestration, and exception-isolated sync/async callback handling.
+Event-driven architecture using a singleton in-memory pub/sub event bus with typed messages, background polling workers, and lifecycle hooks that bridge domain events to persistence and notifications with exception isolation between sync/async handlers.
 ## tags
 call:self., instance, src, services, event, health, call:logger.exception, check
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/shared
 ## role
-Provides reusable, cross-cutting infrastructure services for the API including I/O safety, container operations, user notifications, request tracing, and workspace lifecycle management.
+Provides reusable, cross-cutting infrastructure services for security, I/O, container operations, and workspace management used throughout the API layer.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/api/src/services/shared
 index: apps/api/src/services/shared/.pi-map.index.md
 ## role
-Provides reusable, cross-cutting infrastructure services for the API including I/O safety, container operations, user notifications, request tracing, and workspace lifecycle management.
+Provides reusable, cross-cutting infrastructure services for security, I/O, container operations, and workspace management used throughout the API layer.
 ## files
 - __init__.py | Re-exports shared service classes and functions from a services package to provide a unified public API | dep: src.services.shared.correlation, src.services.shared.file_service, src.services.shared.notification_service, src.services.shared.permission_fixer, src.services.shared.readiness_probe, src.services.shared.ssh_keys, src.services.shared.tunnel, src.services.shared.workspace_manager, correlation, file_service, notification_service, permission_fixer, readiness_probe, ssh_keys, tunnel, workspace_manager
 - correlation.py | Provides async correlation ID tracking via context variables and FastAPI middleware for request tracing. | exp: class:CorrelationIdMiddleware, method:dispatch(self, request: Request, call_next), call:request.headers.get, call:str, call:uuid.uuid4, call:CORRELATION_ID.set, call:call_next, call:CORRELATION_ID.reset, func:get_correlation_id() → str, call:CORRELATION_ID.get, call:str, call:uuid.uuid4 | dep: contextvars, uuid, fastapi, starlette.middleware.base, fastapi.Request, starlette.middleware.base.BaseHTTPMiddleware
@@ -14,11 +14,11 @@ Provides reusable, cross-cutting infrastructure services for the API including I
 - readiness_probe.py | Executes a retryable readiness probe command inside a Docker container with configurable timeout and interval | exp: func:execute_probe(container_id: str, command: str, timeout, interval) → tuple[bool, list[str]], call:asyncio.get_event_loop().time, call:logs.append, call:logger.debug, call:subprocess.run, call:result.stdout.strip, call:result.stderr.strip, call:asyncio.sleep | dep: asyncio, logging, subprocess
 - ssh_keys.py | Decrypts and writes SSH key files to instance directories for container mounting, with optional ownership configuration and SSH config generation. | 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:_sanitize_filename(name: str) → str, call:re.sub, call:sanitized.strip, func:prepare_ssh_key_files(instance_dir: str, ssh_key, subdir, uid, gid, key_filename, write_config) → str, call:Path, call:ssh_dir.mkdir, call:_get_fernet, call:fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode, call:ssh_key.private_key_encrypted.encode, call:private_key_path.write_text, call:os.chmod, call:public_key_path.write_text, call:config_path.write_text, call:os.chown, call:logger.debug, call:logger.warning, call:os.getuid, call:str, func:write_ssh_config(ssh_dir: str, key_filenames: list[str], uid, gid) → None, call:Path, call:ssh_dir_path.mkdir, call:lines.append, call:"\n".join, call:config_path.write_text, call:os.chmod, call:os.chown, func:cleanup_ssh_key_files(instance_dir: str) → None, call:Path, call:ssh_dir.exists, call:ssh_dir.iterdir, call:file_path.unlink, call:ssh_dir.rmdir | dep: logging, os, re, pathlib, cryptography.fernet, src.config, base64, hashlib
 - tunnel.py | Re-exports Docker tunnel functions from a nested module for backward compatibility. | dep: src.services.docker.tunnel
- workspace_manager.py | Manages workspace lifecycle operations including creation, deletion, synchronization, and validation for git repository workspaces. | exp: class:SyncResult, class:WorkspaceHasInstancesError, method:__init__(self, instances: list[dict]) → None, call:super().__init__, call:len, class:WorkspaceManager, method:_workspace_path(self, repo_id: uuid.UUID, name: str) → str, call:os.path.join, call:str, method:create(self, repo: GitRepository, user_id: uuid.UUID, name: str, branch, session) → Workspace, call:self._workspace_path, call:os.path.dirname, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:logger.info, call:os.path.exists, call:logger.warning, call:shutil.rmtree, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.clone, call:self._make_world_writable, call:Workspace, call:datetime.now, raise:ValueError, method:delete(self, workspace: Workspace, force, session) → None, call:self._get_instances, call:self._stop_and_delete_instance, call:os.path.exists, call:shutil.rmtree, call:logger.info, call:session.delete, raise:ValueError, raise:WorkspaceHasInstancesError, method:sync(self, workspace: Workspace, session) → SyncResult, call:logger.info, call:session.get, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.fetch, call:GitService.branch_exists_remotely, call:SyncResult, call:GitService.pull, call:self._make_world_writable, call:datetime.now, method:_make_world_writable(self, path: str) → None, call:contextlib.suppress, call:os.chmod, call:os.walk, call:os.path.join, call:os.stat, method:_get_instances(self, workspace: Workspace, session: AsyncSession) → list[ToolInstance], call:session.execute, call:select(ToolInstance).where, call:list, call:result.scalars().all, method:_stop_and_delete_instance(self, instance: ToolInstance) → None, call:logger.warning | dep: contextlib, logging, os, shutil, stat, uuid, dataclasses, datetime, typing, sqlalchemy, src.models, src.services.git.git_service, src.services.shared.ssh_keys, sqlalchemy.ext.asyncio
+- workspace_manager.py | Manages Git workspace lifecycle operations including creation, deletion, sync, and migration of legacy tool instances into workspace-bound repositories. | exp: class:SyncResult, class:WorkspaceHasInstancesError, method:__init__(self, instances: list[dict]) → None, call:super().__init__, call:len, class:WorkspaceManager, method:_workspace_path(self, repo_id: uuid.UUID, name: str) → str, call:os.path.join, call:str, method:create(self, repo: GitRepository, user_id: uuid.UUID, name: str, branch, session) → Workspace, call:self._workspace_path, call:os.path.dirname, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:logger.info, call:os.path.exists, call:logger.warning, call:shutil.rmtree, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.clone, call:self._make_world_writable, call:Workspace, call:datetime.now, raise:ValueError, method:delete(self, workspace: Workspace, force, session) → None, call:self._get_instances, call:self._stop_and_delete_instance, call:os.path.exists, call:shutil.rmtree, call:logger.info, call:session.delete, raise:ValueError, raise:WorkspaceHasInstancesError, method:sync(self, workspace: Workspace, session) → SyncResult, call:logger.info, call:session.get, call:getattr, call:session.execute, call:select(SSHKey).where, call:result.scalar_one_or_none, call:_get_fernet, call:fernet.decrypt( ssh_key_obj.private_key_encrypted.encode() ).decode, call:ssh_key_obj.private_key_encrypted.encode, call:GitService.fetch, call:GitService.branch_exists_remotely, call:SyncResult, call:GitService.pull, call:self._make_world_writable, call:datetime.now, method:_make_world_writable(self, path: str) → None, call:contextlib.suppress, call:os.chmod, call:os.walk, call:os.path.join, call:os.stat, method:_get_instances(self, workspace: Workspace, session: AsyncSession) → list[ToolInstance], call:session.execute, call:select(ToolInstance).where, call:list, call:result.scalars().all, method:_stop_and_delete_instance(self, instance: ToolInstance, session: AsyncSession) → None, call:delete_tool_instance, call:logger.info, call:logger.error, method:ensure_instance_workspace(self, instance: ToolInstance, session: AsyncSession) → Workspace, call:session.get, call:self._workspace_name_exists, call:self._migrate_clone_into_workspace, call:self.create, call:session.add, call:session.commit, call:session.refresh, call:logger.info, raise:RuntimeError, method:_workspace_name_exists(self, session: AsyncSession, repo_id: uuid.UUID, name: str) → bool, call:session.execute, call:select(Workspace).where, call:result.scalar_one_or_none, method:_migrate_clone_into_workspace(self, instance: ToolInstance, repo: "GitRepository", session: AsyncSession, name: str) → Workspace, call:os.path.dirname, call:os.path.join, call:os.path.exists, call:self._workspace_path, call:os.makedirs, call:contextlib.suppress, call:os.chmod, call:shutil.rmtree, call:shutil.move, call:self._make_world_writable, call:Workspace, call:datetime.now, call:session.add, call:session.flush, raise:RuntimeError | dep: contextlib, logging, os, shutil, stat, uuid, dataclasses, datetime, typing, sqlalchemy, src.models, src.services.git.git_service, src.services.shared.ssh_keys, sqlalchemy.ext.asyncio, src.services.tool.instance_service
 ## arch
-Modular service-oriented architecture with async singletons, context variable-based state propagation, path traversal defense, Docker container exec abstraction, and strict ownership-based isolation boundaries.
+Modular utility services pattern with async singletons, context variables for request tracing, defensive security (path traversal/ownership isolation), Docker exec abstraction, and Git-backed workspace lifecycle management.
 ## tags
-error, get, key, call:self., src, call:ssh, at.is, call:session.execute
+error, workspace, call:self., get, key, src, call:session.execute, call:ssh
 ## symbols
 - CorrelationIdMiddleware
 - FileEntry
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/terminal
 ## role
-Provides backend WebSocket terminal session management with PTY-based interactive shells, lifecycle control, and real-time I/O streaming for remote terminal access.
+Provides WebSocket-connected terminal session management with PTY-based I/O for remote terminal access in the API server.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/api/src/services/terminal
 index: apps/api/src/services/terminal/.pi-map.index.md
 ## role
-Provides backend WebSocket terminal session management with PTY-based interactive shells, lifecycle control, and real-time I/O streaming for remote terminal access.
+Provides WebSocket-connected terminal session management with PTY-based I/O for remote terminal access in the API server.
 ## files
 - __init__.py | Package initialization file that exports the public API for a terminal services module | dep: src.services.terminal.terminal_manager, src.services.terminal.terminal_session
 - terminal_manager.py | Manages WebSocket-connected terminal sessions with lifecycle control, idle cleanup, database persistence, and per-instance session limits. | exp: class:MaxSessionsExceededError, method:__init__(self, instance_id: str, max_sessions) → None, call:super().__init__, class:TerminalManager, method:__init__(self) → None, call:self._start_idle_check, method:_start_idle_check(self) → None, call:self._idle_check_task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._idle_check_loop, method:_idle_check_loop(self) → None, call:asyncio.sleep, call:self._cleanup_idle_sessions, call:logger.error, method:_cleanup_idle_sessions(self) → None, call:list, call:self._sessions.items, call:session.is_idle, call:idle_keys.append, call:logger.info, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, method:_insert_db_session_row(self, session_id: str, instance_id: uuid.UUID, name: str) → None, call:SessionLocal, call:pg_insert(TerminalSessionModel) .values( id=uuid.UUID(session_id), instance_id=instance_id, name=name, status="active", created_at=datetime.now(timezone.utc), last_activity_at=datetime.now(timezone.utc), ) .on_conflict_do_nothing, call:uuid.UUID, call:datetime.now, call:db_session.execute, call:db_session.commit, call:logger.debug, call:logger.error, method:_mark_closed_in_db(self, session_id: str) → None, call:SessionLocal, call:db_session.get, call:uuid.UUID, call:datetime.now, call:db_session.commit, call:logger.debug, call:logger.error, method:_count_sessions_for_instance(self, instance_id_str: str) → int, call:sum, method:create_session(self, instance_id: uuid.UUID, container_id: str, startup_command, name, session_id) → TerminalSession, call:str, call:self._count_sessions_for_instance, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, call:logger.info, raise:MaxSessionsExceededError, method:get_or_create_session(self, instance_id: uuid.UUID, container_id: str, startup_command) → TerminalSession, call:self._start_idle_check, call:str, call:session.is_alive, call:logger.debug, call:session.close, call:logger.info, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, method:get_session(self, instance_id: str, session_id: str) → TerminalSession | None, call:self._sessions.get, call:self._sessions.items, method:_find_key_by_internal_id(self, instance_id: str, internal_session_id: str) → tuple[str, str] | None, call:self._sessions.items, method:get_sessions_for_instance(self, instance_id: str) → list[TerminalSession], call:self._sessions.items, method:close_session(self, instance_id: str, session_id: str) → None, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:logger.info, method:attach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.has_websockets, call:logger.debug, call:list, call:ws.close, call:session._websockets.clear, call:session.attach_websocket, call:session.get_buffer, call:websocket.send_bytes, method:detach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.detach_websocket, method:reset_session(self, instance_id: uuid.UUID, container_id: str, startup_command, session_id, name) → TerminalSession, call:str, call:logger.debug, call:self._sessions.pop, call:old_session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:uuid.uuid4, call:TerminalSession, call:new_session.start, call:self._insert_db_session_row, method:close_all(self) → None, call:list, call:self._sessions.values, call:self._sessions.clear, call:session.close, call:self._idle_check_task.done, call:self._idle_check_task.cancel | dep: asyncio, logging, uuid, datetime, fastapi, sqlalchemy.dialects.postgresql, src.database, src.models, src.services.terminal.terminal_session, fastapi.WebSocket
 - terminal_session.py | Manages a high-performance asyncio-native terminal session using PTY I/O with event-driven reads, output batching, and flow control for WebSocket delivery. | exp: class:TerminalSession, method:__init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command, name) → None, call:deque, call:set, call:time.time, call:self._generate_name, call:str, call:bytearray, call:asyncio.Lock, method:start(self, startup_command) → None, call:pty.openpty, call:self._set_terminal_size, call:logger.debug, call:asyncio.create_subprocess_exec, call:os.close, call:time.time, call:self._start_reading, method:_start_reading(self) → None, call:asyncio.get_event_loop, call:loop.add_reader, call:logger.debug, call:logger.error, method:_stop_reading(self) → None, call:asyncio.get_event_loop, call:loop.remove_reader, method:_on_fd_readable(self) → None, call:os.read, call:logger.debug, call:self._handle_eof, call:self._add_to_buffer, call:time.time, call:self._queue_output, method:_add_to_buffer(self, data: bytes) → None, call:self._output_buffer.append, call:len, call:self._output_buffer.popleft, method:_queue_output(self, data: bytes) → None, call:self._batch_buffer.extend, call:len, call:self._pause_output, call:asyncio.get_event_loop, call:loop.call_later, method:_flush_batch_sync(self) → None, call:self._batch_buffer.clear, call:bytes, call:set, call:list, call:asyncio.create_task, call:self._send_bytes, call:dead_sockets.add, method:_send_bytes(self, ws: Any, payload: bytes) → None, call:ws.send_bytes, call:self._websockets.discard, method:acknowledge_data(self, char_count: int) → None, call:max, call:self._resume_output, call:self._ack_timeout_handle.cancel, call:asyncio.get_event_loop, call:loop.call_later, method:_ack_timeout_fallback(self) → None, call:logger.warning, call:self._resume_output, method:_pause_output(self) → None, call:self._stop_reading, call:logger.debug, method:_resume_output(self) → None, call:self._start_reading, call:logger.debug, method:get_buffer(self) → bytes, call:b"".join, method:_handle_eof(self) → None, call:self._stop_reading, call:self.process._transport.close, call:set, call:self._websockets.clear, call:asyncio.create_task, call:ws.close, call:logger.info, method:write_input(self, data: bytes) → None, call:os.write, call:time.time, call:logger.debug, call:self._handle_eof, method:_set_terminal_size(self, cols: int, rows: int) → None, call:logger.warning, call:struct.pack, call:fcntl.ioctl, call:logger.debug, call:logger.error, method:resize(self, cols: int, rows: int) → None, call:logger.warning, call:logger.debug, call:self._set_terminal_size, call:os.kill, method:reset(self) → None, call:self.close, call:self._output_buffer.clear, call:self._websockets.clear, call:self._batch_buffer.clear, method:close(self) → None, call:self._stop_reading, call:self._batch_timer.cancel, call:self._ack_timeout_handle.cancel, call:os.close, call:self.process.kill, call:asyncio.wait_for, call:self.process.wait, method:is_alive(self) → bool, method:is_idle(self) → bool, call:time.time, method:attach_websocket(self, websocket: Any) → None, call:self._websockets.add, call:time.time, method:detach_websocket(self, websocket: Any) → None, call:self._websockets.discard, method:has_websockets(self) → bool, call:len, method:send_to_all(self, data: bytes) → None, call:set, call:ws.send_bytes, call:dead_sockets.add, call:self._websockets.discard, method:read_output(self) → bytes | dep: asyncio, logging, os, pty, signal, struct, fcntl, time, uuid, collections, typing, collections.deque
 ## arch
-Asyncio-native event-driven architecture with PTY subprocess I/O, batched output with flow control, session lifecycle management (idle cleanup, persistence, limits), and WebSocket message passing.
+Asyncio-native event-driven architecture with session lifecycle management, resource cleanup, output batching/flow control, and database persistence for scalable terminal multiplexing.
 ## tags
 call:self., session, call:logger.debug, idle, output, terminal, check, task
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/api/src/services/tool
 ## role
-Orchestrates Docker container lifecycle for tool instances with git repository mounting, configuration validation, and SSH tunnel management.
+Provides backend infrastructure for provisioning and managing isolated development tool instances with their dependencies and network access.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Developer	346b32236a	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.	2026-06-13 21:04:50 +00:00
Developer	8f7f682a92	fix: merge mobile terminal scroll detection improvements	2026-06-13 20:42:52 +00:00
Developer	2ece7074f6	fix: improve mobile terminal alternate-screen detection and scrolling - Revert touch-action: none on .xterm-viewport so xterm.js can fall back to its own viewport scrolling when the custom handler doesn't take over. - Detect alternate screen via reference equality (term.buffer.active === term.buffer.alternate) instead of the string, which could report normal buffer incorrectly. - Lower vertical-scroll activation threshold from 4px to 2px and only prevent default once a vertical gesture is recognized. - In normal buffer use term.scrollLines() so xterm.js handles the buffer scroll consistently; in alternate screen continue sending SGR 1006 mouse-wheel sequences to tmux/vim. Quality gates: typecheck, lint clean, npm test -- --run 87 passed.	2026-06-13 20:42:52 +00:00
Developer	c7ab2de25e	fix: merge mobile terminal scrolling improvements	2026-06-13 20:30:52 +00:00
Developer	c9b0259993	fix: route mobile terminal swipes to the terminal, not the page layout - Add touch-action: none and overscroll-behavior: none to mobile terminal page, content, wrapper, container, and xterm viewport so the browser never treats swipes as page/address-bar scrolling or pull-to-refresh. - Make .terminal-page.mobile fixed-position to prevent viewport layout scroll; keep the overlay toolbar as absolute with pointer-events only on interactive parts. - Rework the mobile touch handler in terminal.tsx: * Detect normal vs alternate buffer via term.buffer.active.type instead of measuring the DOM viewport, which was unreliable in tmux/vim. * Accumulate swipe distance and emit SGR 1006 mouse-wheel sequences in steps, so tmux pane scrolling tracks the gesture correctly. * Prevent default as soon as the swipe is recognized so the page does not start a competing scroll gesture. Quality gates: npm run typecheck, npm run lint clean, npm test -- --run 87 passed.	2026-06-13 20:30:52 +00:00
Developer	1f2c3dbe2a	fix: merge workspace project_name population	2026-06-13 19:59:13 +00:00
Developer	d247e44985	fix: include project_name in /workspaces list response - The top-level GET /workspaces endpoint was returning project_name as an empty string because the GitRepository.project relationship was not eager-loaded. - Select the full GitRepository entity and apply selectinload(project) so project_name is populated for every workspace row. Backend quality gates: python3 -m pytest 313 passed, 34 skipped.	2026-06-13 19:59:13 +00:00
Developer	d60dec9d62	fix: merge workspace project name visibility	2026-06-13 19:53:43 +00:00
Developer	4913cc7297	fix: make workspace project name visible on mobile and desktop cards - Move the project name below the workspace title row so it reads as a distinct line with a project icon. - Move the status badge into the title row next to the workspace name, preventing it from crowding the project label. - Add .workspace-title-row flex styles and update .workspace-project-name to display inline-flex with a brand-colored project icon. Quality gates: npm run typecheck, npm run lint clean, npm test -- --run 87 passed.	2026-06-13 19:53:43 +00:00
Developer	86360661e9	fix: merge nav sessions middle	2026-06-13 19:44:47 +00:00
Developer	1d09193652	fix: put Sessions back in the middle of nav on desktop and mobile - Reorder desktop sidebar so Sessions sits between spaces/tools groups: Home, Projects, Workspaces, Sessions, Tool Workshop, Config Profiles, Settings. - Reorder mobile bottom nav so Sessions is the center item: Home, Spaces, Sessions, Tools, Settings. - Workspace cards already display the owning project name; no extra change needed. Quality gates: npm run typecheck, npm run lint clean, npm test -- --run 87 passed.	2026-06-13 19:44:47 +00:00
Developer	4ced6141ae	feat: merge mobile Spaces nav and list views	2026-06-13 19:38:03 +00:00
Developer	530225d37c	feat: mobile Spaces nav and list-based project/workspace views - Combine Projects and Workspaces into a single 'Spaces' grouped mobile nav item that opens a bottom-sheet menu. - Add SpacesBottomSheet component with Projects/Workspaces options. - Extend MobileListView with optional renderItem prop for rich rows. - Redesign mobile ProjectsPage rows to show project description and repository chips. - Replace mobile WorkspacesPage list with compact WorkspaceCard grid, matching desktop card content. - Add mobile-list-* CSS and mobile-workspaces-list spacing. Quality gates: npm run typecheck, npm run lint clean, npm test -- --run 87 passed.	2026-06-13 19:32:16 +00:00
Developer	e6ab77d123	feat: merge workspace card redesign	2026-06-13 18:54:59 +00:00
Developer	4e1477c4be	feat: redesign workspace card header and layout - Swap workspace card header order: project name is now the primary eyebrow, workspace name is the bold title below it. - Restructure workspace card into clean top/body/actions sections with more whitespace and clearer hierarchy. - Replace cramped meta paragraphs with an inline meta row (repo, branch, instance count) and dedicated instance chip area. - Use icon-only ghost buttons for sync/delete to reduce visual noise; keep prominent Start Tool button. - Add top divider for actions, improve hover states, and make long names truncate gracefully. - Update mobile workspace list subtitle to project · workspace name. - Refresh workspaces.css with new card layout and responsive mobile rules. Quality gates: npm run typecheck clean, npm run lint clean, npm test -- --run 87 passed	2026-06-13 17:00:16 +00:00
Developer	2b5b8363ca	chore: merge completed OpenSpec archive	2026-06-13 14:39:33 +00:00
Developer	1e0f95f8bd	chore: archive completed OpenSpec changes Move the following audited-and-implemented changes into openspec/changes/archive/2026-06-12-completed-changes-archive/: - tool-config-mount-cleanup - config-profile-directory-mounts Update archive README count and project map index/files accordingly. openspec/changes/ now contains only the archive directory. Quality gates: pytest 313 passed/34 skipped, npm run typecheck/lint clean, npm test -- --run 87 passed	2026-06-13 14:24:30 +00:00
Developer	6a20c54da7	chore: merge project map patches	2026-06-13 14:15:30 +00:00
Developer	db6ae38568	chore: patch project maps for loading-overlay and orphaned session entries - Add loading-overlay.tsx to component maps - Remove orphaned session-progress-panel.tsx and session-operations.tsx entries - Refresh parent indexes after manual map edits Quality gates: pytest 313 passed/34 skipped, npm run typecheck/lint clean, npm test -- --run 87 passed	2026-06-13 12:31:35 +00:00
Developer	1e43ea48aa	Merge branch 'fix/compose-readonly-mounts' into dev	2026-06-13 12:12:12 +00:00
Developer	efe5e4ae50	fix: respect readonly flag on config-profile mounts in compose tool types - modify_compose_file now appends :ro when a config-profile volume entry has readonly=true, matching the manifest compiler behavior. - Add a guard for missing tool_type in prepare_manifest_instance. Quality gates: python3 -m pytest (313 passed, 34 skipped)	2026-06-13 12:12:12 +00:00
Developer	31f1ce00d3	Merge branch 'feat/config-profile-directory-mounts' into dev	2026-06-13 11:56:48 +00:00
Developer	d395aaf574	fix: stage config-profile mounts as directories so ~/.config stays writable - Switch apply_resolved_profile from per-file bind mounts to one directory-level bind mount per ResolvedMount target. - Stage all configured files under instance_dir/mounts/<sanitized_target> and bind-mount that directory, so Docker no longer creates a root-owned parent directory such as ~/.config. - Propagate read-only mode ('ro') as the 'readonly' flag on volume entries. - Update unit tests to expect directory-level mounts and add coverage for readonly/writable flags. Quality gates: python3 -m py_compile, pytest (313 passed, 34 skipped), npm run typecheck, npm run lint.	2026-06-13 11:56:48 +00:00
Developer	d78ca8a9d5	Merge branch 'chore/patch-project-maps' into dev	2026-06-13 11:40:03 +00:00
Developer	19291d6be9	chore: patch project maps after tool-config mount cleanup	2026-06-13 11:40:03 +00:00
Developer	5409ba2b13	Merge branch 'feat/tool-config-mount-cleanup' into dev	2026-06-13 11:35:55 +00:00
Developer	8bde9a213c	feat: remove config/state mounts from built-in tool configs - Remove pi_state and pi_config mounts from the pi-agent manifest. - Add Alembic data migration to strip those mounts from existing DB rows. - Remove opencode_home:/tmp volume and HOME=/tmp override from the opencode built-in compose template; config/state now belongs in config profiles. - Workspace and SSH key mounts remain unchanged. Quality gates: python3 -m py_compile, pytest (311 passed, 34 skipped), npm run typecheck, npm run lint	2026-06-13 11:35:55 +00:00
Developer	315cb33e3f	Merge branch 'chore/format-busy-overlay-followup' into dev	2026-06-13 11:19:22 +00:00
Developer	474843ffa6	chore: apply formatter to busy overlay files	2026-06-13 11:19:22 +00:00
Developer	766f7ff0d1	Merge branch 'feat/busy-container-overlays' into dev	2026-06-13 10:10:28 +00:00
Developer	f8b162ec5f	feat: busy container overlays for lifecycle actions Add a reusable LoadingOverlay component that dims and disables the container owning an in-flight action, with a spinning indicator and label. Apply it to: - SessionCard (when actionBusyId matches) - InstanceList cards (per busyInstanceId with action-specific labels) - CreateSessionForm (while submitting) - ToolStarter (while starting) Also add .icon-spin animation and position:relative to the relevant containers. Quality gates: npm run typecheck, npm run lint, npm test -- --run (87 passed).	2026-06-13 10:10:28 +00:00
Developer	8a8a9bc9e4	Merge branch 'remove/session-operations-center' into dev	2026-06-13 09:50:14 +00:00
Developer	61f9c52455	remove: session operations center and progress panel The bottom-right progress panel duplicated feedback already shown by toasts. Remove it and the operation-tracking state to simplify the UI: - Delete state/session-operations.tsx and session-progress-panel.tsx. - Remove SessionOperationsProvider/SessionProgressPanel from AppShell. - Remove startOperation/completeOperation calls from useInstanceActions and ToolStarter. - Remove SessionOperationsProvider wrapper from DashboardPage.test.tsx. - Remove .session-progress-panel CSS rules. - Format use-events.test.ts mock to match project lint rules. Quality gates: npm run typecheck, npm run lint, npm test -- --run (87 passed).	2026-06-13 09:50:14 +00:00
Developer	43d65840ea	Merge branch 'fix/progress-panel-sse-listeners' into dev	2026-06-13 09:30:45 +00:00
Developer	ad5a4b5000	fix: listen for named SSE events in progress panel The backend sends named lifecycle events (event: instance.health_changed), but useEvents only set es.onmessage, which only receives unnamed message events. Add explicit addEventListener registrations for all lifecycle event types so the progress panel receives updates and completes. Quality gates: npm run typecheck, npm run lint, npm test -- --run (87 passed).	2026-06-13 09:30:45 +00:00
Developer	73088b75ba	Merge branch 'fix/clone-mode-nullable-migration' into dev	2026-06-13 09:18:13 +00:00
Developer	f23fadf52b	fix(alembic): make tool_instances.clone_mode nullable The workspace-first cleanup removed clone_mode from the creation flow, so the API now inserts NULL. Align the database with the model by making clone_mode nullable. Apply with: cd apps/api && alembic upgrade head	2026-06-13 09:18:13 +00:00
Developer	9101033019	Merge branch 'fix/config-mount-permissions' into dev	2026-06-12 22:08:57 +00:00
Developer	72bf4ed962	fix: chown staged mount sources to container user Config-profile and git mounts staged under instance_dir were created by the API process (root), so when bind-mounted over ~/.config the container user could not write. Recursively chown staged sources to the resolved container uid/gid before compose up. Quality gates: python3 -m py_compile passed; ruff/pytest skipped (test tooling not available in this shell, helper smoke tested with a temporary directory).	2026-06-12 22:08:57 +00:00
Developer	3b772ac239	Merge branch 'chore/archive-completed-openspec-changes' into dev	2026-06-12 21:11:11 +00:00
Developer	8c1948d226	chore: archive final 4 completed OpenSpec changes Move the following completed changes from openspec/changes/ to openspec/changes/archive/2026-06-12-completed-changes-archive/: - multi-session-terminal-ux - reorganize-long-files - working-copies - workspace-first-ui Update parent and archive .pi-map*.md indexes to reflect the move and remove the transient active-changes-archive grouping. openspec/changes/ now contains only the archive/ directory.	2026-06-12 21:11:11 +00:00
Developer	43f3865f69	merge: chore/patch-project-maps	2026-06-12 20:36:39 +00:00
Developer	7ef8b0eb36	chore: patch project maps after stale backend test cleanup Regenerate .pi-map*.md artifacts for source changes in: - apps/api/src/api/tool/tool_types_validation.py - apps/api/src/schemas/tool/tool_type.py - apps/api/tests/integration/test_tool_types_api_extended.py - and all affected test files from backend-frontend refactoring cleanup	2026-06-12 20:36:31 +00:00