chore(project-map): regenerate .pi-map artifacts across the repo

2026-06-17 11:31:24 +00:00
parent 0dd5f2317b
commit 93da9b42a2
683 changed files with 5075 additions and 4965 deletions
@@ -2,7 +2,7 @@
 dir: apps/web

 ## role
-Frontend web application providing the browser-based user interface for the project, built with React/Vite and served via nginx.
+Frontend web application serving as the main user interface for the "Headquarter" project, built with React and Vite.
 ## parent
 index: apps/.pi-map.index.md
 map: apps/.pi-map.md
@@ -4,21 +4,21 @@ dir: apps/web
 index: apps/web/.pi-map.index.md

 ## role
-Frontend web application providing the browser-based user interface for the project, built with React/Vite and served via nginx.
+Frontend web application serving as the main user interface for the "Headquarter" project, built with React and Vite.
 ## files
- .env.example | Template file defining example environment variables for frontend API and application URL configuration
- .eslintrc.cjs | Configures ESLint for a TypeScript browser project with modern ECMAScript module support | dep: @typescript-eslint/parser, @typescript-eslint/eslint-plugin, eslint
- Dockerfile | Multi-stage Docker build for a Node.js/Vite frontend application served by nginx with non-root user security | dep: node:20-alpine, nginx:alpine, npm, wget
- index.html | Standard HTML entry point for a React/Vite application that loads a TypeScript root component | dep: Google Fonts (Inter, IBM Plex Mono), main.tsx entry module
- nginx.conf | Configures nginx as a web server for a single-page application with optimized caching, compression, and client-side routing support. | dep: nginx
- package-lock.json | Records exact dependency versions and resolved URLs for reproducible npm package installation in the "headquarter-web" React project. | dep: npm, @phosphor-icons/react, @types/prismjs, axios, prismjs, react, react-dom, react-router-dom, react-simple-code-editor, tailwindcss, xterm, xterm-addon-fit, xterm-addon-web-links, xterm-addon-webgl, @testing-library/jest-dom, @testing-library/react, @types/react, @types/react-dom, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, @vitejs/plugin-react, autoprefixer, eslint, jsdom, postcss, typescript, vite, vitest, @babel/core, @babel/runtime
- package.json | Configuration file for a React-based web application named "headquarter-web" built with Vite and TypeScript, featuring code editing, terminal, and routing capabilities. | dep: react, react-dom, react-router-dom, vite, typescript, tailwindcss, axios, prismjs, xterm, @phosphor-icons/react, react-simple-code-editor, vitest, eslint
- tsconfig.json | TypeScript configuration file for a React project using Vite with modern ES2020 target and bundler module resolution | dep: typescript, react, vite
- vite.config.ts | Configures Vite build tool for a React project with custom dev server port and Vitest test settings. | dep: vite, @vitejs/plugin-react
+- .env.example | Template file showing required environment variables for a Vite-based frontend application | dep: Vite
+- .eslintrc.cjs | Configures ESLint for a TypeScript browser project with modern ES2022 module support | dep: eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin
+- Dockerfile | Multi-stage Docker build for a Vite/Node.js frontend application, compiling static assets and serving them via nginx as a non-root user | dep: node:20-alpine, nginx:alpine, npm, wget
+- index.html | Serves as the entry point HTML file for a React application named "Headquarter" that loads a TypeScript module and uses Google Fonts. | dep: Google Fonts (Inter, IBM Plex Mono), React (implied by root div and main.tsx)
+- nginx.conf | Configures Nginx as a web server for a single-page application with gzip compression, client-side routing support, cache control for static assets, and a health check endpoint. | dep: nginx
+- package-lock.json | Auto-generated dependency lock file that records exact versions and resolved URLs of all npm packages for reproducible installs in the "headquarter-web" React web application. | dep: npm, Node.js, React, Vite, TailwindCSS, xterm, PrismJS, axios, react-router-dom, TypeScript, ESLint, Vitest, @testing-library/react, @phosphor-icons/react, react-simple-code-editor, jsdom, postcss, autoprefixer
+- package.json | Defines a React-based web application project named "headquarter-web" with configuration for building, development, testing, and linting using Vite and TypeScript. | dep: react, react-dom, react-router-dom, axios, tailwindcss, prismjs, xterm, @phosphor-icons/react, react-simple-code-editor, vite, typescript, vitest, eslint, @testing-library/react
+- tsconfig.json | Configures TypeScript compiler settings for a modern React project using Vite with ES modules | dep: TypeScript, Vite, React, DOM
+- vite.config.ts | Configures Vite build tool for a React project with custom dev server port and testing setup | dep: vite, @vitejs/plugin-react
 ## arch
-Modern SPA architecture using Vite for bundling, TypeScript for type safety, React for UI components, with containerized nginx deployment and environment-driven configuration.
+Modern SPA architecture using React with TypeScript, Vite for build tooling, Docker multi-stage builds with nginx static serving, and environment-based configuration.
 ## tags
-react, eslint, vite, typescript, dom, application, nginx, web
+react, vite, eslint, typescript, application, nginx, web, configures
 ## symbols
 -
 ## workflows
@@ -2,7 +2,7 @@
 dir: apps/web/public

 ## role
-Static frontend assets serving a standalone HTML preview/demo of the workspace dashboard UI without requiring the full application runtime.
+Static HTML mockup/prototype for demonstrating the Headquarter dashboard UI without requiring the full application runtime
 ## parent
 index: apps/web/.pi-map.index.md
 map: apps/web/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/web/public
 index: apps/web/public/.pi-map.index.md

 ## role
-Static frontend assets serving a standalone HTML preview/demo of the workspace dashboard UI without requiring the full application runtime.
+Static HTML mockup/prototype for demonstrating the Headquarter dashboard UI without requiring the full application runtime
 ## files
- preview.html | Static HTML/CSS UI mockup for a "Headquarter" workspace dashboard with interactive page preview switching between Home, Projects, and Settings views. | dep: Google Fonts (Inter, IBM Plex Mono)
+- preview.html | A static HTML UI preview/mockup for a "Headquarter" web application dashboard showing home and settings page layouts with a page switcher for demonstration | dep: Google Fonts (Inter, IBM Plex Mono)
 ## arch
-Self-contained static HTML prototype with vanilla CSS and JavaScript, using a simple view-switching pattern to simulate multi-page SPA navigation within a single file.
+Simple static HTML/CSS/JS prototype with client-side page switching via JavaScript, using inline styles and vanilla DOM manipulation for rapid UI demonstration
 ## tags
-preview, static, html, css, mockup, headquarter, workspace, dashboard
+preview, page, static, html, mockup, headquarter, web, application
 ## symbols
 -
 ## workflows
@@ -2,7 +2,7 @@
 dir: apps/web/src

 ## role
-Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend.
+Frontend web application entry point and routing layer for a React-based collaborative development platform.
 ## parent
 index: apps/web/.pi-map.index.md
 map: apps/web/.pi-map.md
@@ -4,15 +4,15 @@ dir: apps/web/src
 index: apps/web/src/.pi-map.index.md

 ## role
-Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend.
+Frontend web application entry point and routing layer for a React-based collaborative development platform.
 ## files
- main.tsx | Bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom
- router.tsx | Defines the React Router configuration for a web application with protected routes, nested layouts, and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage
- types.ts | Defines TypeScript type definitions for user sessions, projects, repositories, and workspaces in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos
+- main.tsx | Entry point that bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom
+- router.tsx | Defines the client-side routing configuration for a React application using nested routes with authentication protection and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage
+- types.ts | Defines TypeScript type declarations for session users, projects, workspaces, and repositories in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos
 ## arch
-Implements a modular React SPA architecture using React Router v6 with nested route layouts, protected route guards via authentication/session providers, and centralized TypeScript domain modeling for cross-cutting concerns.
+Modular React SPA with provider-based dependency injection, nested route guards for authentication/authorization, and centralized TypeScript type definitions.
 ## tags
-pages, styles, css, router, react, session, dom, project
+pages, styles, css, react, router, session, dom, project
 ## symbols
 - AppRouter
 - SessionUser
@@ -2,7 +2,7 @@
 dir: apps/web/src/api

 ## role
-Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity.
+Provides typed HTTP API client functions for all backend operations across the web frontend, organized by domain entity with centralized Axios configuration.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,29 +4,29 @@ dir: apps/web/src/api
 index: apps/web/src/api/.pi-map.index.md

 ## role
-Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity.
+Provides typed HTTP API client functions for all backend operations across the web frontend, organized by domain entity with centralized Axios configuration.
 ## files
- client.ts | Configures an Axios HTTP client with automatic 401 redirect handling and exponential backoff retry logic for transient network/server errors. | exp: apiClient, shouldSkipAuthRedirect | dep: axios
- config-profiles.ts | Defines TypeScript interfaces and API client functions for managing configuration profiles with environment variables, mounts, git mounts, file inclusions, and profile resolution. | exp: ConfigProfile, ConfigProfileMount, GitMountMapping, GitMount, ConfigProfileInclude, ResolvedProfile, ResolvedMount, CreateConfigProfileRequest, UpdateConfigProfileRequest, UpdateIncludesRequest, listConfigProfiles, getConfigProfile, createConfigProfile, updateConfigProfile, deleteConfigProfile, updateProfileIncludes, previewConfigProfile, resolveDefaultProfile, ValidateGitUrlResponse, validateGitUrl | dep: ./client, client
- dashboard.ts | Defines a TypeScript type and API function to fetch dashboard summary data from a backend endpoint. | exp: DashboardSummary, getDashboardSummary | dep: ./client
- events.ts | Provides utilities for establishing a Server-Sent Events connection and checking the event stream endpoint status. | exp: func:createEventSource() → EventSource, func:probeEventStreamStatus() → Promise<number | null>, call:setTimeout, call:controller.abort, call:fetch, call:clearTimeout
- git-repositories.ts | Provides a TypeScript API client module for managing Git repositories, branches, commits, and version control operations via HTTP endpoints. | exp: GitRepository, GitRepositoryCreate, URLParseResult, Branch, BranchesResponse, CommitHistoryEntry, CommitHistoryResponse, CommitDetail, GitStatus, CommitResponse, MergeResponse, func:parseGitUrl(url: string) → Promise<URLParseResult>, call:apiClient.post, func:listRepositories(projectId: string) → Promise<GitRepository[]>, func:listAllUserRepositories() → Promise<GitRepository[]>, func:createRepository(projectId: string, data: GitRepositoryCreate) → Promise<GitRepository>, call:apiClient.post, func:createExternalRepository(data: GitRepositoryCreate) → Promise<GitRepository>, func:deleteRepository(projectId: string, repoId: string) → Promise<void>, call:apiClient.delete, func:updateRepositorySshKey(projectId: string, repoId: string, sshKeyId: string | null) → Promise<GitRepository>, call:apiClient.patch, func:listRepositoryBranches(projectId: string, repoId: string) → Promise<BranchesResponse>, call:apiClient.get, func:getRepositoryHistory(projectId: string, repoId: string, branch: string, limit: number) → Promise<CommitHistoryResponse>, call:searchParams.set, call:String, call:searchParams.toString, call:apiClient.get, func:getCommitDetail(projectId: string, repoId: string, commitHash: string) → Promise<CommitDetail>, call:apiClient.get, func:getRepositoryStatus(projectId: string, repoId: string) → Promise<GitStatus>, call:apiClient.get, func:createBranch(projectId: string, repoId: string, name: string, baseBranch: string) → Promise<{ message: string; branch: string }>, call:apiClient.post, func:deleteBranch(projectId: string, repoId: string, branchName: string, force: boolean) → Promise<{ message: string }>, call:apiClient.delete, func:checkoutBranch(projectId: string, repoId: string, branch: string) → Promise<{ message: string; branch: string }>, call:apiClient.post, func:commitChanges(projectId: string, repoId: string, message: string, files: string[]) → Promise<CommitResponse>, call:apiClient.post, func:fetchRepository(projectId: string, repoId: string) → Promise<{ message: string }>, call:apiClient.post, func:pullRepository(projectId: string, repoId: string, branch: string) → Promise<{ message: string }>, call:apiClient.post, func:pushRepository(projectId: string, repoId: string, branch: string) → Promise<{ message: string }>, call:apiClient.post, func:mergeBranches(projectId: string, repoId: string, sourceBranch: string, targetBranch: string, message: string) → Promise<MergeResponse>, call:apiClient.post | dep: ./client, apiClient
- notifications.ts | Defines TypeScript interfaces and API client functions for fetching, reading, dismissing, and clearing user notifications. | exp: NotificationItem, NotificationListResponse, UnreadCountResponse, MarkAllReadResponse, ClearAllResponse, getNotifications, getUnreadCount, markNotificationRead, markAllNotificationsRead, dismissNotification, clearAllNotifications | dep: ./client, apiClient
- profile.ts | Provides API functions for fetching, updating, and uploading avatar for the current user's profile. | exp: UserProfile, ProfileUpdatePayload, getProfile, updateProfile, uploadAvatar | dep: ./client, ../types, apiClient, SessionUser
- projects.ts | Provides typed API functions for CRUD operations on projects via HTTP endpoints. | exp: ProjectCreateInput, ProjectUpdateInput, SetDefaultSSHKeyInput, listProjects, createProject, updateProject, deleteProject, setDefaultSSHKey | dep: ./client, ../types
- sessions.ts | Provides TypeScript API functions and interfaces for managing remote tool instances and sessions via HTTP requests. | exp: ToolInstance, Session, InstanceHealth, func:listInstances(projectId: string, repoId: string) → Promise<ToolInstance[]>, call:apiClient.get, func:createInstance(projectId: string, repoId: string, toolTypeId: string, displayName: string, workspaceId: string, configProfileId: string, sshKeyIds: string[]) → Promise<ToolInstance>, call:apiClient.post, func:startInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:startInstance, raise:error, func:stopInstance(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string }>, call:apiClient.post, func:restartInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:restartInstance, raise:error, func:deleteInstance(projectId: string, repoId: string, instanceId: string, force: boolean) → Promise<void>, call:apiClient.delete, func:getInstance(projectId: string, repoId: string, instanceId: string) → Promise<ToolInstance>, call:apiClient.get, func:getUserSessions() → Promise<Session[]>, call:apiClient.get, func:checkInstanceHealth(projectId: string, repoId: string, instanceId: string) → Promise<InstanceHealth>, call:apiClient.get, func:renameInstance(projectId: string, repoId: string, instanceId: string, displayName: string) → Promise<{ id: string; name: string; display_name: string }>, call:apiClient.patch, func:recreateInstanceTunnel(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string; url?: string }>, call:apiClient.post | dep: axios, ./client
- settings.ts | Defines user configuration interfaces and API functions for fetching and updating user settings via HTTP requests. | exp: UserConfig, UserConfigUpdate, getUserConfig, updateUserConfig | dep: ./client, apiClient
- ssh-keys.ts | Provides a TypeScript API client for SSH key management operations including listing, creating, deleting, and cryptographic signing/verification. | exp: SSHKey, SSHKeyCreate, SignPayloadRequest, SignatureResponse, VerifySignatureRequest, VerifySignatureResponse, func:listSSHKeys() → Promise<SSHKey[]>, func:createSSHKey(data: SSHKeyCreate) → Promise<SSHKey>, func:deleteSSHKey(keyId: string) → Promise<void>, call:apiClient.delete, func:signPayload(keyId: string, data: SignPayloadRequest) → Promise<SignatureResponse>, func:verifySignature(keyId: string, data: VerifySignatureRequest) → Promise<VerifySignatureResponse> | dep: ./client, apiClient
- terminal.ts | Provides a TypeScript API client module for managing remote terminal sessions (CRUD operations) on cloud instances via REST endpoints. | exp: TerminalSession, TerminalSessionListResponse, TerminalSessionCreateRequest, TerminalSessionCreateResponse, func:listTerminalSessions(instanceId: string) → Promise<TerminalSession[]>, call:apiClient.get, func:createTerminalSession(instanceId: string, name: string) → Promise<TerminalSessionCreateResponse>, call:apiClient.post, func:closeTerminalSession(instanceId: string, sessionId: string) → Promise<{ status: string; session_id: string }>, call:apiClient.delete, func:resetTerminalSession(instanceId: string, sessionId: string) → Promise<{ id: string; name: string; status: string }>, call:apiClient.post, func:renameTerminalSession(instanceId: string, sessionId: string, name: string) → Promise<{ id: string; name: string }>, call:apiClient.post | dep: ./client, client
- tool-definitions.ts | Defines TypeScript interfaces and API client functions for CRUD operations and compilation of tool definitions in a containerized tool management system. | exp: ToolDefinitionManifest, CreateToolDefinitionRequest, UpdateToolDefinitionRequest, CompileResult, listToolDefinitions, getToolDefinition, createToolDefinition, updateToolDefinition, deleteToolDefinition, compileToolDefinition | dep: ./client, apiClient
- tool-types.test.ts | Unit tests for tool type API operations including CRUD, validation, and field handling for dockerfile and compose definitions. | dep: vitest, ../api/tool-types, ../api/client
+- client.ts | Configures an Axios HTTP client with authentication redirect handling and automatic retry logic for transient network/server errors | exp: apiClient, shouldSkipAuthRedirect | dep: axios
+- config-profiles.ts | Defines TypeScript interfaces and API client functions for managing configuration profiles with environment variables, mounts, git mounts, files, and profile inheritance. | exp: ConfigProfile, ConfigProfileMount, GitMountMapping, GitMount, ConfigProfileInclude, ResolvedProfile, ResolvedMount, CreateConfigProfileRequest, UpdateConfigProfileRequest, UpdateIncludesRequest, listConfigProfiles, getConfigProfile, createConfigProfile, updateConfigProfile, deleteConfigProfile, updateProfileIncludes, previewConfigProfile, resolveDefaultProfile, ValidateGitUrlResponse, validateGitUrl | dep: ./client, apiClient
+- dashboard.ts | Defines a TypeScript type and API function to fetch dashboard summary data | exp: DashboardSummary, getDashboardSummary | dep: ./client
+- events.ts | Provides utilities for connecting to and checking the status of a server-sent events stream endpoint | exp: func:createEventSource() → EventSource, func:probeEventStreamStatus() → Promise<number | null>, call:setTimeout, call:controller.abort, call:fetch, call:clearTimeout
+- git-repositories.ts | Defines TypeScript interfaces and API client functions for Git repository management, branch operations, and version control actions (commit, push, pull, merge, etc.) | exp: GitRepository, GitRepositoryCreate, URLParseResult, Branch, BranchesResponse, CommitHistoryEntry, CommitHistoryResponse, CommitDetail, GitStatus, CommitResponse, MergeResponse, func:parseGitUrl(url: string) → Promise<URLParseResult>, call:apiClient.post, func:listRepositories(projectId: string) → Promise<GitRepository[]>, func:listAllUserRepositories() → Promise<GitRepository[]>, func:createRepository(projectId: string, data: GitRepositoryCreate) → Promise<GitRepository>, call:apiClient.post, func:createExternalRepository(data: GitRepositoryCreate) → Promise<GitRepository>, func:deleteRepository(projectId: string, repoId: string) → Promise<void>, call:apiClient.delete, func:updateRepositorySshKey(projectId: string, repoId: string, sshKeyId: string | null) → Promise<GitRepository>, call:apiClient.patch, func:listRepositoryBranches(projectId: string, repoId: string) → Promise<BranchesResponse>, call:apiClient.get, func:getRepositoryHistory(projectId: string, repoId: string, branch: string, limit: number) → Promise<CommitHistoryResponse>, call:searchParams.set, call:String, call:searchParams.toString, call:apiClient.get, func:getCommitDetail(projectId: string, repoId: string, commitHash: string) → Promise<CommitDetail>, call:apiClient.get, func:getRepositoryStatus(projectId: string, repoId: string) → Promise<GitStatus>, call:apiClient.get, func:createBranch(projectId: string, repoId: string, name: string, baseBranch: string) → Promise<{ message: string; branch: string }>, call:apiClient.post, func:deleteBranch(projectId: string, repoId: string, branchName: string, force: boolean) → Promise<{ message: string }>, call:apiClient.delete, func:checkoutBranch(projectId: string, repoId: string, branch: string) → Promise<{ message: string; branch: string }>, call:apiClient.post, func:commitChanges(projectId: string, repoId: string, message: string, files: string[]) → Promise<CommitResponse>, call:apiClient.post, func:fetchRepository(projectId: string, repoId: string) → Promise<{ message: string }>, call:apiClient.post, func:pullRepository(projectId: string, repoId: string, branch: string) → Promise<{ message: string }>, call:apiClient.post, func:pushRepository(projectId: string, repoId: string, branch: string) → Promise<{ message: string }>, call:apiClient.post, func:mergeBranches(projectId: string, repoId: string, sourceBranch: string, targetBranch: string, message: string) → Promise<MergeResponse>, call:apiClient.post | dep: ./client, apiClient
+- notifications.ts | Defines TypeScript interfaces and API functions for fetching, reading, dismissing, and clearing user notifications. | exp: NotificationItem, NotificationListResponse, UnreadCountResponse, MarkAllReadResponse, ClearAllResponse, getNotifications, getUnreadCount, markNotificationRead, markAllNotificationsRead, dismissNotification, clearAllNotifications | dep: ./client, apiClient
+- profile.ts | Provides API functions to fetch, update, and upload an avatar for the current user's profile. | exp: UserProfile, ProfileUpdatePayload, getProfile, updateProfile, uploadAvatar | dep: ./client, ../types, apiClient, SessionUser
+- projects.ts | Defines API client functions for CRUD operations on projects and setting default SSH keys. | exp: ProjectCreateInput, ProjectUpdateInput, SetDefaultSSHKeyInput, listProjects, createProject, updateProject, deleteProject, setDefaultSSHKey | dep: ./client, ../types, apiClient, Project, ProjectWithRepos
+- sessions.ts | Provides API client functions for managing tool instances and user sessions in a development environment platform. | exp: ToolInstance, Session, InstanceHealth, func:listInstances(projectId: string, repoId: string) → Promise<ToolInstance[]>, call:apiClient.get, func:createInstance(projectId: string, repoId: string, toolTypeId: string, displayName: string, workspaceId: string, configProfileId: string, sshKeyIds: string[]) → Promise<ToolInstance>, call:apiClient.post, func:startInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:startInstance, raise:error, func:stopInstance(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string }>, call:apiClient.post, func:restartInstance(projectId: string, repoId: string, instanceId: string, configProfileId: string, sshKeyIds: string[], retries) → Promise<{ status: string; url?: string }>, call:apiClient.post, call:setTimeout, call:restartInstance, raise:error, func:deleteInstance(projectId: string, repoId: string, instanceId: string, force: boolean) → Promise<void>, call:apiClient.delete, func:getInstance(projectId: string, repoId: string, instanceId: string) → Promise<ToolInstance>, call:apiClient.get, func:getUserSessions() → Promise<Session[]>, call:apiClient.get, func:checkInstanceHealth(projectId: string, repoId: string, instanceId: string) → Promise<InstanceHealth>, call:apiClient.get, func:renameInstance(projectId: string, repoId: string, instanceId: string, displayName: string) → Promise<{ id: string; name: string; display_name: string }>, call:apiClient.patch, func:recreateInstanceTunnel(projectId: string, repoId: string, instanceId: string) → Promise<{ status: string; url?: string }>, call:apiClient.post | dep: axios, ./client
+- settings.ts | Defines user configuration types and API functions for fetching and updating user settings via HTTP requests. | exp: UserConfig, UserConfigUpdate, getUserConfig, updateUserConfig | dep: ./client
+- ssh-keys.ts | Provides a TypeScript API client module for SSH key management operations including listing, creating, deleting, and cryptographic signing/verification. | exp: SSHKey, SSHKeyCreate, SignPayloadRequest, SignatureResponse, VerifySignatureRequest, VerifySignatureResponse, func:listSSHKeys() → Promise<SSHKey[]>, func:createSSHKey(data: SSHKeyCreate) → Promise<SSHKey>, func:deleteSSHKey(keyId: string) → Promise<void>, call:apiClient.delete, func:signPayload(keyId: string, data: SignPayloadRequest) → Promise<SignatureResponse>, func:verifySignature(keyId: string, data: VerifySignatureRequest) → Promise<VerifySignatureResponse> | dep: ./client, apiClient
+- terminal.ts | Provides a TypeScript API client for managing terminal sessions on remote instances via HTTP requests. | exp: TerminalSession, TerminalSessionListResponse, TerminalSessionCreateRequest, TerminalSessionCreateResponse, func:listTerminalSessions(instanceId: string) → Promise<TerminalSession[]>, call:apiClient.get, func:createTerminalSession(instanceId: string, name: string) → Promise<TerminalSessionCreateResponse>, call:apiClient.post, func:closeTerminalSession(instanceId: string, sessionId: string) → Promise<{ status: string; session_id: string }>, call:apiClient.delete, func:resetTerminalSession(instanceId: string, sessionId: string) → Promise<{ id: string; name: string; status: string }>, call:apiClient.post, func:renameTerminalSession(instanceId: string, sessionId: string, name: string) → Promise<{ id: string; name: string }>, call:apiClient.post | dep: ./client, apiClient
+- tool-definitions.ts | Defines TypeScript interfaces and API client functions for CRUD operations and compilation of tool definitions in a Docker-based tool management system. | exp: ToolDefinitionManifest, CreateToolDefinitionRequest, UpdateToolDefinitionRequest, CompileResult, listToolDefinitions, getToolDefinition, createToolDefinition, updateToolDefinition, deleteToolDefinition, compileToolDefinition | dep: ./client
+- tool-types.test.ts | Unit tests for tool type API CRUD operations including listing, creating, validating, updating, and deleting tool types with dockerfile and compose definitions | dep: vitest, ../api/tool-types, ../api/client
 - tool-types.ts | Defines TypeScript interfaces and API client functions for CRUD operations on tool types in a containerized deployment system. | exp: ReadinessProbe, ToolType, CreateToolTypeRequest, UpdateToolTypeRequest, listToolTypes, getToolType, createToolType, updateToolType, deleteToolType, validateToolType | dep: ./client, apiClient
 - workspace-files.ts | Provides an API client for listing, reading, and saving workspace files. | exp: FileEntry, func:listWorkspaceFiles(workspaceId: string, path: string) → Promise<FileEntry[]>, func:getWorkspaceFileContent(workspaceId: string, path: string) → Promise<string>, func:saveWorkspaceFile(workspaceId: string, path: string, content: string, commitMessage: string) → Promise<void>, call:apiClient.post | dep: ./client, apiClient
- workspace-git.ts | Provides a typed API client for git operations on remote workspaces via HTTP endpoints. | exp: GitStatus, Commit, func:getGitStatus(workspaceId: string) → Promise<GitStatus>, func:getGitBranches(workspaceId: string) → Promise<{ branches: string[]; current_branch: string }>, func:gitCommit(workspaceId: string, message: string) → Promise<void>, call:apiClient.post, func:gitPush(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitPull(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitFetch(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitCheckout(workspaceId: string, branch: string) → Promise<void>, call:apiClient.post, func:getGitHistory(workspaceId: string, path: string, limit: number) → Promise<Commit[]> | dep: ./client
- workspace-instances.ts | Provides API client functions to list and create workspace tool instances. | exp: func:listWorkspaceInstances(workspaceId: string) → Promise<ToolInstance[]>, func:createWorkspaceInstance(workspaceId: string, toolTypeId: string, displayName: string, configProfileId: string) → Promise<ToolInstance> | dep: ./client, ./sessions
- workspaces.ts | Provides an API client wrapper for CRUD operations and sync functionality on workspaces via HTTP endpoints. | exp: func:listWorkspaces(projectId: string, repoId: string) → Promise<Workspace[]>, call:workspaceUrl, func:listAllWorkspaces() → Promise<Workspace[]>, func:createWorkspace(projectId: string, repoId: string, data: CreateWorkspaceRequest) → Promise<Workspace>, call:workspaceUrl, func:createWorkspaceTopLevel(data: CreateWorkspaceRequest & { repo_id: string }) → Promise<Workspace>, func:getWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise<Workspace>, call:workspaceUrl, func:updateWorkspace(projectId: string, repoId: string, workspaceId: string, data: Partial<CreateWorkspaceRequest>) → Promise<Workspace>, call:workspaceUrl, func:deleteWorkspace(workspaceId: string, force) → Promise<{ status: string }>, func:syncWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise<SyncResult>, call:workspaceUrl | dep: ./client, ../types/workspace, apiClient, Workspace, CreateWorkspaceRequest, SyncResult
+- workspace-git.ts | Provides a typed API client for workspace git operations including status, branches, commits, push/pull/fetch, checkout, and history. | exp: GitStatus, Commit, func:getGitStatus(workspaceId: string) → Promise<GitStatus>, func:getGitBranches(workspaceId: string) → Promise<{ branches: string[]; current_branch: string }>, func:gitCommit(workspaceId: string, message: string) → Promise<void>, call:apiClient.post, func:gitPush(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitPull(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitFetch(workspaceId: string) → Promise<void>, call:apiClient.post, func:gitCheckout(workspaceId: string, branch: string) → Promise<void>, call:apiClient.post, func:getGitHistory(workspaceId: string, path: string, limit: number) → Promise<Commit[]> | dep: ./client
+- workspace-instances.ts | Provides API client functions for listing and creating workspace tool instances. | exp: func:listWorkspaceInstances(workspaceId: string) → Promise<ToolInstance[]>, func:createWorkspaceInstance(workspaceId: string, toolTypeId: string, displayName: string, configProfileId: string) → Promise<ToolInstance> | dep: ./client, ./sessions, apiClient, ToolInstance
+- workspaces.ts | Provides an API client for CRUD and sync operations on workspaces in a project/repository hierarchy. | exp: func:listWorkspaces(projectId: string, repoId: string) → Promise<Workspace[]>, call:workspaceUrl, func:listAllWorkspaces() → Promise<Workspace[]>, func:createWorkspace(projectId: string, repoId: string, data: CreateWorkspaceRequest) → Promise<Workspace>, call:workspaceUrl, func:createWorkspaceTopLevel(data: CreateWorkspaceRequest & { repo_id: string }) → Promise<Workspace>, func:getWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise<Workspace>, call:workspaceUrl, func:updateWorkspace(projectId: string, repoId: string, workspaceId: string, data: Partial<CreateWorkspaceRequest>) → Promise<Workspace>, call:workspaceUrl, func:deleteWorkspace(workspaceId: string, force) → Promise<{ status: string }>, func:syncWorkspace(projectId: string, repoId: string, workspaceId: string) → Promise<SyncResult>, call:workspaceUrl | dep: ./client, ../types/workspace, apiClient, Workspace, CreateWorkspaceRequest, SyncResult
 ## arch
-Modular facade pattern with a centralized Axios client (client.ts) featuring cross-cutting concerns (auth redirect, retry logic), consumed by domain-specific modules that export typed interfaces and thin API function wrappers.
+Modular facade pattern with domain-segregated modules (one per entity), shared base client with interceptors, consistent TypeScript interfaces for request/response types, and thin wrappers over RESTful endpoints.
 ## tags
 call:api, tool, client.post, create, git, profile, get, client
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components

 ## role
-Provides reusable, accessible UI primitives and layout components for a React web application, including shell layout, data states, icons, code editing, routing guards, and toast notifications.
+Reusable React UI components providing the application's shared visual elements, layout shell, authentication guards, and notification infrastructure.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,22 +4,22 @@ dir: apps/web/src/components
 index: apps/web/src/components/.pi-map.index.md

 ## role
-Provides reusable, accessible UI primitives and layout components for a React web application, including shell layout, data states, icons, code editing, routing guards, and toast notifications.
+Reusable React UI components providing the application's shared visual elements, layout shell, authentication guards, and notification infrastructure.
 ## files
- app-shell.tsx | Renders the main application shell layout with navigation, header, session management, and mobile-responsive behavior for a React Router-based SPA. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons
- code-editor.tsx | A React component that renders a syntax-highlighted code editor with line numbers using react-simple-code-editor. | exp: CodeEditor | dep: react, react-simple-code-editor, ../utils/language
+- app-shell.tsx | Provides the main application shell layout with navigation, session management, and responsive mobile/desktop rendering for a React application. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../utils/open-session, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons
+- code-editor.tsx | A React component that renders a syntax-highlighting code editor with line numbers using react-simple-code-editor. | exp: CodeEditor | dep: react, react-simple-code-editor, ../utils/language
 - data-states.tsx | Provides reusable React components for displaying loading, error, and empty data states in a UI. | exp: LoadingState, ErrorState, EmptyState | dep: ./icon, icon
- icon.tsx | Provides a centralized, type-safe React icon component that maps semantic names to Phosphor icons with configurable size, weight, color, and accessibility attributes. | exp: IconName, IconProps, Icon | dep: react, @phosphor-icons/react
- loading-overlay.tsx | Renders an accessible loading overlay with optional label that conditionally displays based on visibility prop | exp: func:LoadingOverlay({ visible, label }: LoadingOverlayProps) | dep: ./icon, icon
- protected-route.test.tsx | Tests a ProtectedRoute component that guards content based on authentication state | dep: @testing-library/react, react-router-dom, vitest, ./protected-route
- protected-route.tsx | Conditionally renders children or redirects to login based on authentication state | exp: ProtectedRoute | dep: react-router-dom, ../state/auth
- syntax-highlighter.tsx | Renders syntax-highlighted code blocks with optional line numbers and copy-to-clipboard functionality | exp: SyntaxHighlighter | dep: react, ./icon, ../utils/language, React, icon, language (utils)
+- icon.tsx | Provides a centralized, type-safe React icon component that maps semantic names to Phosphor icons with configurable size, weight, color, and accessibility properties. | exp: IconName, IconProps, Icon | dep: react, @phosphor-icons/react
+- loading-overlay.tsx | Renders an accessible loading overlay with optional label when visible prop is true | exp: func:LoadingOverlay({ visible, label }: LoadingOverlayProps) | dep: ./icon, icon
+- protected-route.test.tsx | Tests a ProtectedRoute component that guards private content based on authentication state | dep: @testing-library/react, react-router-dom, vitest, ./protected-route, ../state/auth
+- protected-route.tsx | A React component that conditionally renders children or redirects to login based on authentication state, preserving the intended destination URL. | exp: ProtectedRoute | dep: react-router-dom, ../state/auth
+- syntax-highlighter.tsx | Renders syntax-highlighted code blocks with optional line numbers, language badge, and copy-to-clipboard functionality. | exp: SyntaxHighlighter | dep: react, ./icon, ../utils/language, React, icon, language utilities
 - toast-rules.test.ts | Unit tests for mapping instance events to toast notification categories and severities | dep: vitest, ./toast-rules, ../types/events
- toast-rules.ts | Maps instance events to toast notifications with deduplication logic to prevent spam | exp: func:mapEventToCategory(event: InstanceEventPayload) → string, call:event.event.startsWith, func:mapEventToSeverity(event: InstanceEventPayload) → "info" | "warning" | "error" | "success", func:handleEventToast(event: InstanceEventPayload) → void, call:shouldShowToast, call:toast.info, call:toast.success, call:toast.warning, call:toast.error, func:clearToastDedup() → void, call:lastToastTime.clear | dep: ../state/toast, ../types/events, toast state module, InstanceEventPayload type
+- toast-rules.ts | Maps instance events to toast notifications with deduplication logic | exp: func:mapEventToCategory(event: InstanceEventPayload) → string, call:event.event.startsWith, func:mapEventToSeverity(event: InstanceEventPayload) → "info" | "warning" | "error" | "success", func:handleEventToast(event: InstanceEventPayload) → void, call:shouldShowToast, call:toast.info, call:toast.success, call:toast.warning, call:toast.error, func:clearToastDedup() → void, call:lastToastTime.clear | dep: ../state/toast, ../types/events, toast, InstanceEventPayload
 ## arch
-Component-based React architecture with functional components, composition patterns, and separation of concerns between presentation (UI rendering), logic (rules/hooks), and testing; integrates third-party libraries (react-simple-code-editor, Phosphor icons) and React Router for SPA navigation.
+Component-based architecture with functional React patterns, separation of presentational components (data states, icons, syntax highlighting) from behavioral logic (toast rules, protected routes), and centralized design abstractions (icon mapping, code editor wrapping).
 ## tags
-toast, icon, react, state, code, loading, event, editor
+toast, react, state, icon, code, loading, event, editor
 ## symbols
 - LoadingOverlay
 - mapEventToCategory
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features

 ## role
-Contains reusable React components that implement specific product features and user-facing functionality across the web application.
+Reusable UI feature components that compose domain-specific functionality for the web application.
 ## parent
 index: apps/web/src/components/.pi-map.index.md
 map: apps/web/src/components/.pi-map.md
@@ -4,10 +4,10 @@ dir: apps/web/src/components/features
 index: apps/web/src/components/features/.pi-map.index.md

 ## role
-Contains reusable React components that implement specific product features and user-facing functionality across the web application.
+Reusable UI feature components that compose domain-specific functionality for the web application.
 ## files
 ## arch
-Feature-based component organization with domain-specific groupings, likely combining presentational and container patterns with hooks for state management, following a modular architecture where each feature encapsulates its own UI, logic, and data fetching concerns.
+Feature-based component organization with domain-driven design patterns, likely combining presentational components with localized state and business logic.
 ## tags
 -
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/config-profiles

 ## role
-Provides UI components for managing Docker configuration profiles including creation, editing, listing, and mobile-responsive views.
+Provides UI components for managing configuration profiles (create, edit, list, delete) with support for desktop and mobile layouts.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,15 +4,15 @@ dir: apps/web/src/components/features/config-profiles
 index: apps/web/src/components/features/config-profiles/.pi-map.index.md

 ## role
-Provides UI components for managing Docker configuration profiles including creation, editing, listing, and mobile-responsive views.
+Provides UI components for managing configuration profiles (create, edit, list, delete) with support for desktop and mobile layouts.
 ## files
- ConfigProfileEditorPanel.tsx | React component that renders a form-based editor panel for creating and editing configuration profiles with support for includes, environment variables, runtime hints, files, and mounts. | exp: ConfigProfileEditorPanel | dep: ../../icon, ../git/git-mount-editor, ../../../api/config-profiles, ../../../types, ../../../api/tool-types, React, Icon, GitMountEditor, ConfigProfile, CreateConfigProfileRequest, ResolvedProfile, ProjectWithRepos, ToolType
- ConfigProfileListSidebar.tsx | Renders a sidebar component for listing, selecting, creating, and deleting configuration profiles with visual indicators for default status, scope, and includes. | exp: ConfigProfileListSidebar | dep: ../../icon, ../../../api/config-profiles, Icon, ConfigProfile
- ConfigProfilesMobileView.tsx | Renders a mobile-responsive view for managing configuration profiles with list, detail, edit, and preview states. | exp: ConfigProfilesMobileView | dep: react, ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../git/git-mount-editor, ../../icon, ../../../api/config-profiles, ../../../types, ../../../api/tool-types, mobile-list-view, mobile-detail-view, mobile-edit-view, mobile-fab, git-mount-editor, icon, config-profiles API types, types
+- ConfigProfileEditorPanel.tsx | Renders a form panel for creating or editing configuration profiles with includes, environment variables, files, mounts, and git mounts. | exp: ConfigProfileEditorPanel | dep: ../../icon, ../git/git-mount-editor, ../../../api/config-profiles, ../../../types, ../../../api/tool-types, Icon, GitMountEditor, config-profiles API types, ProjectWithRepos types, tool-types API
+- ConfigProfileListSidebar.tsx | Renders a sidebar UI component for listing, selecting, creating, and deleting configuration profiles with visual indicators for scope and metadata. | exp: ConfigProfileListSidebar | dep: ../../icon, ../../../api/config-profiles, React, Icon component, ConfigProfile type
+- ConfigProfilesMobileView.tsx | Renders a mobile-responsive view for managing configuration profiles with list, detail, edit, and preview states. | exp: ConfigProfilesMobileView | dep: react, ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../git/git-mount-editor, ../../icon, ../../../api/config-profiles, ../../../types, ../../../api/tool-types, mobile-list-view, mobile-detail-view, mobile-edit-view, mobile-fab, git-mount-editor, icon, config-profiles API types, project types, tool-types API
 ## arch
-Feature-based component composition with state-driven panels (list/detail/edit/preview), form-based editing, and responsive layout adaptation for mobile/desktop.
+Feature-based component composition with panel/sidebar split-view pattern, responsive mobile state machine (list/detail/edit/preview), and form-driven data editing for complex nested configuration objects.
 ## tags
-mobile, config, view, profiles, editor, profile, list, icon
+config, mobile, view, profiles, profile, editor, list, git
 ## symbols
 - ConfigProfileEditorPanel
 - ConfigProfileListSidebar
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/git

 ## role
-Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows.
+Provides Git repository management UI components for mounting, committing, and merging operations within the web application.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,15 +4,15 @@ dir: apps/web/src/components/features/git
 index: apps/web/src/components/features/git/.pi-map.index.md

 ## role
-Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows.
+Provides Git repository management UI components for mounting, committing, and merging operations within the web application.
 ## files
- commit-dialog.tsx | A React modal dialog component that displays a diff preview of file changes and allows users to enter a commit message to save those changes. | exp: CommitDialog | dep: react, ../../icon, icon
- git-mount-editor.tsx | A React component for editing Git repository mount configurations with URL validation, branch selection, and path mappings. | exp: GitMountEditor | dep: react, ../../icon, ../../../api/config-profiles, icon, config-profiles
- merge-dialog.tsx | A React modal dialog component that allows users to merge Git branches with source/target selection, optional commit message, and loading/error/success state handling. | exp: MergeDialog | dep: react, ../../../api/git-repositories, ../../icon, api/git-repositories, icon
+- commit-dialog.tsx | Renders a modal dialog for reviewing code diffs and entering a commit message before committing changes to a file. | exp: CommitDialog | dep: react, ../../icon
+- git-mount-editor.tsx | A React component that provides a UI for editing Git repository mounts with path mappings, including URL validation and branch selection. | exp: GitMountEditor | dep: react, ../../icon, ../../../api/config-profiles, icon, config-profiles API (validateGitUrl, GitMount, GitMountMapping types)
+- merge-dialog.tsx | A React modal dialog component that allows users to merge Git branches by selecting a source branch, optionally providing a commit message, and executing the merge operation. | exp: MergeDialog | dep: react, ../../../api/git-repositories, ../../icon
 ## arch
-Uses modal dialog pattern with form state management, loading/error/success state handling, and controlled inputs for Git-specific operations.
+React component-based architecture using modal dialog patterns for discrete Git workflows, with form-driven interfaces for repository configuration and branch operations.
 ## tags
-dialog, git, react, commit, icon, mount, merge, editor
+dialog, git, commit, merge, react, icon, mount, editor
 ## symbols
 - CommitDialog
 - GitMountEditor
@@ -6,20 +6,20 @@ index: apps/web/src/components/features/mobile/.pi-map.index.md
 ## role
 Provides a complete set of mobile-optimized UI components for CRUD operations, navigation, and terminal interfaces in a responsive web application.
 ## files
- mobile-action-sheet.tsx | Renders a mobile-optimized action sheet modal with title, configurable action buttons, and cancel option. | exp: MobileActionSheetItem, func:MobileActionSheet({ isOpen, onClose, title, actions, }: MobileActionSheetProps), call:useRef, call:useEffect, call:onClose, call:document.addEventListener, call:document.removeEventListener, call:e.stopPropagation, call:actions.map, call:action.onClick | dep: react, ../../icon, icon
- mobile-detail-view.tsx | A React component that renders a mobile-optimized detail view with a header, back/edit/delete actions, and a configurable list of typed fields. | exp: MobileDetailView | dep: ../../icon, React
- mobile-edit-view.tsx | A React component that renders a mobile-optimized form for editing records with configurable field types and save/cancel/delete actions. | exp: MobileEditView | dep: react
- mobile-fab.tsx | Renders a floating action button component for mobile with an add icon and configurable click handler and label. | exp: MobileFAB | dep: ../../icon, react, icon
- mobile-list-view.tsx | A reusable React component that renders a mobile-optimized list view with optional search, custom item rendering, and action buttons (duplicate/delete). | exp: MobileListView | dep: react, ../../icon, ../../../utils/icons, icon
- mobile-nav.tsx | Renders a mobile navigation bar with grouped items that trigger bottom sheets and standard links with active state highlighting | exp: MobileNav | dep: react, react-router-dom, ../../icon, ../tool/tools-bottom-sheet, ./spaces-bottom-sheet, ../../../utils/icons
+- mobile-action-sheet.tsx | Renders a mobile-optimized action sheet modal with a list of actions, optional icons, variant styling, and keyboard/overlay dismissal handling. | exp: MobileActionSheetItem, func:MobileActionSheet({ isOpen, onClose, title, actions, }: MobileActionSheetProps), call:useRef, call:useEffect, call:onClose, call:document.addEventListener, call:document.removeEventListener, call:e.stopPropagation, call:actions.map, call:action.onClick | dep: react, ../../icon, icon
+- mobile-detail-view.tsx | A React component that renders a mobile-optimized detail view with a header, back/edit/delete actions, and a configurable list of typed fields. | exp: MobileDetailView | dep: ../../icon, react, icon
+- mobile-edit-view.tsx | Renders a mobile-optimized form view for editing records with configurable field types and save/cancel/delete actions. | exp: MobileEditView | dep: react
+- mobile-fab.tsx | Renders a mobile floating action button with an add icon and customizable label | exp: MobileFAB | dep: ../../icon, React, Icon component
+- mobile-list-view.tsx | A reusable React component that renders a mobile-optimized list view with optional search, custom item rendering, and action buttons for duplicate/delete. | exp: MobileListView | dep: react, ../../icon, ../../../utils/icons, icon (local component), icons (local utils)
+- mobile-nav.tsx | Renders a mobile navigation bar with grouped items that open bottom sheets and standard items that use React Router links, including active state handling and session count badges. | exp: MobileNav | dep: react, react-router-dom, ../../icon, ../tool/tools-bottom-sheet, ./spaces-bottom-sheet, ../../../utils/icons, icon, tools-bottom-sheet, spaces-bottom-sheet, icons
 - mobile-page-header.tsx | Renders a mobile-only page header with optional back navigation and custom actions. | exp: func:MobilePageHeader({ title, showBack = true, actions }: MobilePageHeaderProps), call:useNavigate, call:useMobileViewport, call:navigate | dep: react-router-dom, ../../../hooks/use-mobile-viewport, ../../icon, use-mobile-viewport hook, Icon component
- mobile-terminal-header.tsx | Renders a mobile-responsive header for a terminal interface with navigation, title, connection status, font size controls, and close actions. | exp: MobileTerminalHeader | dep: react, ../../icon, icon
- mobile-terminal-wrapper.tsx | Wraps a terminal component with mobile-specific UI including auto-hiding header, virtual keyboard handling, and special keys interface. | exp: MobileTerminalWrapper | dep: react, ../terminal/terminal, ./mobile-terminal-header, ../terminal/special-keys-strip, ../terminal/special-keys-panel, ../../../hooks/use-mobile-viewport, ../../../hooks/use-virtual-keyboard, ../../../hooks/use-auto-hide, ../../../hooks/use-special-keys
+- mobile-terminal-header.tsx | Renders a mobile-responsive header for a terminal interface with navigation, status, and font size controls. | exp: MobileTerminalHeader | dep: react, ../../icon, icon
+- mobile-terminal-wrapper.tsx | Wraps a terminal component with mobile-specific UI including auto-hiding header, virtual keyboard handling, and special keys input panels. | exp: MobileTerminalWrapper | dep: react, ../terminal/terminal, ./mobile-terminal-header, ../terminal/special-keys-strip, ../terminal/special-keys-panel, ../../../hooks/use-mobile-viewport, ../../../hooks/use-virtual-keyboard, ../../../hooks/use-auto-hide, ../../../hooks/use-special-keys, React, TerminalComponent, MobileTerminalHeader, SpecialKeysStrip, SpecialKeysPanel, useMobileViewport, useVirtualKeyboard, useAutoHide, ModifierKey
 - spaces-bottom-sheet.tsx | Renders a mobile bottom sheet navigation menu for switching between "Projects" and "Workspaces" spaces with active state highlighting. | exp: SpacesBottomSheet | dep: react-router-dom, ../../icon, icon
 ## arch
-Feature-based component architecture using compound mobile patterns (bottom sheets, action sheets, FABs) with typed configurable props, consistent mobile-first design system, and specialized terminal wrapper with native-like behaviors (auto-hiding headers, virtual keyboard handling).
+Compound component pattern with feature-specific mobile wrappers that adapt desktop functionality to touch-friendly bottom sheets, action sheets, and specialized mobile views, using React Router for navigation and consistent mobile-first styling variants.
 ## tags
-mobile, terminal, sheet, react, icon, view, header, action
+mobile, sheet, react, view, terminal, icon, header, bottom
 ## symbols
 - MobileActionSheet
 - MobilePageHeader
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/notification

 ## role
-Provides notification UI components and event-to-toast bridging logic for the web application.
+Provides the complete notification UI system including toast notifications, notification center dropdown, and individual notification items with user preference filtering.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,18 +4,18 @@ dir: apps/web/src/components/features/notification
 index: apps/web/src/components/features/notification/.pi-map.index.md

 ## role
-Provides notification UI components and event-to-toast bridging logic for the web application.
+Provides the complete notification UI system including toast notifications, notification center dropdown, and individual notification items with user preference filtering.
 ## files
- event-toast-bridge.test.tsx | Tests that EventToastBridge correctly filters instance events based on user notification preferences (toast level and muted categories) before triggering toast notifications. | dep: vitest, @testing-library/react, ./event-toast-bridge, ../../../state/events, ../../../api/settings, ../../toast-rules, ../../../types/events, event-toast-bridge, useEventContext, getUserConfig, handleEventToast, InstanceEventPayload
- event-toast-bridge.tsx | Bridges event system to toast notifications by filtering events based on user config and processing them through toast rules | exp: func:EventToastBridge() → JSX.Element | null, call:useEventContext, call:useRef, call:useState, call:useEffect, call:getUserConfig() .then((c) => { setConfig({ notification_toast_level: c.notification_toast_level ?? "all", notification_mute_categories: c.notification_mute_categories ?? [], }); }) .catch, call:setConfig, call:window.addEventListener, call:window.removeEventListener, call:processedRef.current.has, call:processedRef.current.add, call:mapEventToCategory, call:mapEventToSeverity, call:config.notification_mute_categories.includes, call:handleEventToast | dep: react, ../../../state/events, ../../toast-rules, ../../../api/settings, useEventContext, toast-rules, settings api
- notification-center.test.tsx | Tests the NotificationCenter UI component's rendering, interactions, and API integration using Vitest and React Testing Library. | dep: vitest, @testing-library/react, ./notification-center, ../../../state/notifications, ../../../api/notifications, notification-center, notification-provider, notifications-api
- notification-center.tsx | Renders a notification bell icon with a dropdown panel showing notifications, supporting mobile and desktop responsive layouts via React portal. | exp: func:NotificationCenter({ isMobileTerminal = false, }: NotificationCenterProps), call:useNotifications, call:useMobileViewport, call:useRef, call:useState, call:useCallback, call:bellRef.current.getBoundingClientRect, call:setDropdownStyle, call:useEffect, call:updatePosition, call:dropdownRef.current.contains, call:bellRef.current?.contains, call:setIsDropdownOpen, call:document.addEventListener, call:window.addEventListener, call:document.removeEventListener, call:window.removeEventListener, call:refreshList, call:String, call:createPortal, call:notifications.map, call:markAllRead, call:clearAll | dep: react, react-dom, ../../../hooks/use-notifications, ../../../hooks/use-mobile-viewport, ./notification-item, ../../icon, use-notifications, use-mobile-viewport, notification-item, icon
- notification-item.test.tsx | Tests the NotificationItem React component for rendering, styling, and user interaction behaviors. | dep: vitest, @testing-library/react, ./notification-item
- notification-item.tsx | Renders a single notification item with expandable metadata, read/dismiss actions, and severity-based icon display. | exp: NotificationItemProps, func:NotificationItem({ notification, onMarkRead, onDismiss, }: NotificationItemProps), call:useState, call:Object.keys, call:formatRelativeTime, call:Object.entries(notification.metadata).map, call:key.replace, call:formatMetadataValue, call:setExpanded, call:onMarkRead, call:onDismiss | dep: react, ../../icon, ../../../utils/time, ../../../api/notifications, ../../../utils/icons, icon, time, notifications, icons
+- event-toast-bridge.test.tsx | Tests the EventToastBridge component's notification preference filtering logic, including toast level settings, category muting, and deduplication behavior. | dep: vitest, @testing-library/react, ./event-toast-bridge, ../../../state/events, ../../../api/settings, ../../toast-rules, ../../../types/events, event-toast-bridge component, useEventContext hook, getUserConfig API, handleEventToast utility
+- event-toast-bridge.tsx | Bridges events from an event context to toast notifications with user-configurable filtering by severity and category | exp: func:EventToastBridge() → JSX.Element | null, call:useEventContext, call:useRef, call:useState, call:useEffect, call:getUserConfig() .then((c) => { setConfig({ notification_toast_level: c.notification_toast_level ?? "all", notification_mute_categories: c.notification_mute_categories ?? [], }); }) .catch, call:setConfig, call:window.addEventListener, call:window.removeEventListener, call:processedRef.current.has, call:processedRef.current.add, call:mapEventToCategory, call:mapEventToSeverity, call:config.notification_mute_categories.includes, call:handleEventToast | dep: react, ../../../state/events, ../../toast-rules, ../../../api/settings, useEventContext, toast-rules, settings/api
+- notification-center.test.tsx | Tests the NotificationCenter React component's rendering, interactions, and API integration using Vitest and React Testing Library. | dep: vitest, @testing-library/react, ./notification-center, ../../../state/notifications, ../../../api/notifications, notification-center, notification-provider, notifications-api
+- notification-center.tsx | Renders a notification bell icon with a dropdown panel for viewing, managing, and dismissing notifications, supporting both desktop and mobile responsive layouts. | exp: func:NotificationCenter({ isMobileTerminal = false, }: NotificationCenterProps), call:useNotifications, call:useMobileViewport, call:useRef, call:useState, call:useCallback, call:bellRef.current.getBoundingClientRect, call:setDropdownStyle, call:useEffect, call:updatePosition, call:dropdownRef.current.contains, call:bellRef.current?.contains, call:setIsDropdownOpen, call:document.addEventListener, call:window.addEventListener, call:document.removeEventListener, call:window.removeEventListener, call:refreshList, call:String, call:createPortal, call:notifications.map, call:markAllRead, call:clearAll | dep: react, react-dom, ../../../hooks/use-notifications, ../../../hooks/use-mobile-viewport, ./notification-item, ../../icon, use-notifications, use-mobile-viewport, notification-item, icon
+- notification-item.test.tsx | Tests the NotificationItem React component for rendering, styling, and user interaction behavior. | dep: vitest, @testing-library/react, ./notification-item
+- notification-item.tsx | Renders a single notification item with expandable metadata, severity-based icons, read/dismiss actions, and relative time formatting. | exp: NotificationItemProps, func:NotificationItem({ notification, onMarkRead, onDismiss, }: NotificationItemProps), call:useState, call:Object.keys, call:formatRelativeTime, call:Object.entries(notification.metadata).map, call:key.replace, call:formatMetadataValue, call:setExpanded, call:onMarkRead, call:onDismiss | dep: react, ../../icon, ../../../utils/time, ../../../api/notifications, ../../../utils/icons, icon, time utils, notifications API, icons utils
 ## arch
-React component-based architecture with feature-based directory organization, using portals for dropdown rendering, event-driven toast bridging with user preference filtering, and severity-based visual states.
+Component-based React architecture with clear separation of concerns: bridge pattern for event-to-toast translation, compound component pattern for notification center UI, and granular single-responsibility components with comprehensive test coverage.
 ## tags
-event, notification, call:use, toast, notifications, listener, react, item
+event, notification, call:use, toast, listener, react, notifications, item
 ## symbols
 - EventToastBridge
 - NotificationCenter
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/profile

 ## role
-Provides a mobile-specific UI for users to view and edit their profile information.
+Provides a mobile-responsive user interface for editing user profile information and managing avatar uploads.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,11 +4,11 @@ dir: apps/web/src/components/features/profile
 index: apps/web/src/components/features/profile/.pi-map.index.md

 ## role
-Provides a mobile-specific UI for users to view and edit their profile information.
+Provides a mobile-responsive user interface for editing user profile information and managing avatar uploads.
 ## files
- ProfileMobileView.tsx | Renders a mobile-optimized profile editing form with avatar upload, name/email fields, and save/cancel functionality. | exp: ProfileMobileView | dep: react-router-dom, ../mobile/mobile-edit-view, ../../icon, ../../../api/profile
+- ProfileMobileView.tsx | Renders a mobile-optimized profile editing form with avatar upload, name/email fields, and save/cancel actions | exp: ProfileMobileView | dep: react-router-dom, ../mobile/mobile-edit-view, ../../icon, ../../../api/profile
 ## arch
-Single feature-focused component with form handling and file upload, likely using controlled inputs and local state management.
+Single-feature component with form state management, file upload handling, and responsive design patterns for mobile-first profile editing.
 ## tags
 mobile, profile, view, renders, optimized, editing, form, avatar
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/project

 ## role
-Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations.
+Provides UI components for managing projects, repositories, and workspaces in a web application.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -12,6 +12,7 @@ map: apps/web/src/components/features/.pi-map.md
 - ProjectCard.test.tsx
 - ProjectCard.tsx
 - ProjectDialog.tsx
+- ProjectListItem.tsx
 - repositories-settings-tab.test.tsx
 - repositories-settings-tab.tsx
 - repository-create-dialog.tsx
@@ -20,7 +21,7 @@ index: apps/web/src/components/features/project/.pi-map.index.md
 map: apps/web/src/components/features/project/.pi-map.md
 ## workflows
 - change project behavior
-  read: ProjectCard.tsx, ProjectDialog.tsx, repositories-settings-tab.tsx
+  read: ProjectCard.tsx, ProjectDialog.tsx, ProjectListItem.tsx
 - update project tests
  read: ProjectCard.test.tsx, repositories-settings-tab.test.tsx
 ## dirty
@@ -4,26 +4,28 @@ dir: apps/web/src/components/features/project
 index: apps/web/src/components/features/project/.pi-map.index.md

 ## role
-Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations.
+Provides UI components for managing projects, repositories, and workspaces in a web application.
 ## files
- ProjectCard.test.tsx | Unit tests for the ProjectCard component verifying rendering, workspace creation, and delete confirmation behavior. | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./ProjectCard, ../../../types, ProjectCard, types
- ProjectCard.tsx | Renders an expandable project card displaying project info, repositories, and associated workspaces with CRUD actions. | exp: ProjectCard | dep: ../../icon, ../workspace/workspace-create-form, ../../../types, Icon, WorkspaceCreateForm, ProjectWithRepos, WorkspaceSummary
- ProjectDialog.tsx | Renders a modal dialog for creating or editing a project with name/description inputs and cancel/submit actions. | exp: ProjectDialog | dep: ../../icon, React, icon
- repositories-settings-tab.test.tsx | Tests the RepositoriesSettingsTab component's repository creation flows including full URL cloning, owner/repo mode with SSH key selection, and SSH URL validation. | dep: @testing-library/react, vitest, ./repositories-settings-tab, ../../../api/git-repositories, ../../../api/ssh-keys, react-router-dom
- repositories-settings-tab.tsx | A React component that displays and manages Git repositories for a project, allowing users to list, create, and delete repositories. | exp: RepositoriesSettingsTab | dep: react, react-router-dom, ../../../api/git-repositories, ./repository-create-dialog, ../../icon
- repository-create-dialog.tsx | React dialog component for creating or cloning Git repositories with URL validation and SSH key selection. | exp: RepositoryCreateDialog | dep: react, ../../../api/git-repositories, ../../../api/ssh-keys, ../../icon
+- ProjectCard.test.tsx | Unit tests for the ProjectCard React component verifying rendering, workspace creation, and delete confirmation behavior. | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./ProjectCard, ../../../types, ProjectCard component, types
+- ProjectCard.tsx | Renders an expandable project card UI component displaying project info, repositories, and associated workspaces with CRUD actions. | exp: ProjectCard | dep: ../../icon, ../workspace/workspace-create-form, ../../../types, icon, workspace-create-form, types
+- ProjectDialog.tsx | Renders a modal dialog for creating or editing a project with name/description inputs and submit/cancel actions. | exp: ProjectDialog | dep: ../../icon, React, Icon
+- ProjectListItem.tsx | Renders a project list item with repositories, workspaces, and running sessions, including edit/delete actions and session management. | exp: ProjectListItem | dep: react, react-router-dom, ../../icon, ../../../api/sessions, ../../../utils/icons, ../../../types, ../../../utils/open-session
+- repositories-settings-tab.test.tsx | Tests the RepositoriesSettingsTab component's repository creation flows including full URL cloning, owner/repo mode with SSH key generation, SSH URL validation, and form error handling. | dep: @testing-library/react, vitest, ./repositories-settings-tab, ../../../api/git-repositories, ../../../api/ssh-keys, react-router-dom
+- repositories-settings-tab.tsx | React component that displays and manages Git repositories for a project, including listing, creating, and deleting repositories | exp: RepositoriesSettingsTab | dep: react, react-router-dom, ../../../api/git-repositories, ./repository-create-dialog, ../../icon
+- repository-create-dialog.tsx | A React dialog component for creating or cloning Git repositories with URL validation, SSH key selection, and support for both simple owner/repo and advanced URL modes. | exp: RepositoryCreateDialog | dep: react, ../../../api/git-repositories, ../../../api/ssh-keys, ../../icon
 ## arch
-React component-based architecture with feature-specific composition, dialog-based modals for forms, and comprehensive test coverage using unit tests for component behavior and user flows.
+React component-based architecture with feature-specific composition, separating presentation (cards/lists/dialogs) from business logic, using dialogs for modal CRUD operations and comprehensive unit testing for complex user flows.
 ## tags
-project, repositories, dialog, react, create, settings, icon, repository
+project, repositories, react, dialog, icon, create, settings, api
 ## symbols
 - ProjectCard
 - ProjectDialog
+- ProjectListItem
 - RepositoriesSettingsTab
 - RepositoryCreateDialog
 ## workflows
 - change project behavior
-  read: ProjectCard.tsx, ProjectDialog.tsx, repositories-settings-tab.tsx
+  read: ProjectCard.tsx, ProjectDialog.tsx, ProjectListItem.tsx
 - update project tests
  read: ProjectCard.test.tsx, repositories-settings-tab.test.tsx
 ## dirty
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/session

 ## role
-Provides UI components for managing development sessions including creation, listing, and interacting with individual sessions.
+Provides UI components for managing development sessions including creation, listing, and individual session display with status and actions.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,15 +4,15 @@ dir: apps/web/src/components/features/session
 index: apps/web/src/components/features/session/.pi-map.index.md

 ## role
-Provides UI components for managing development sessions including creation, listing, and interacting with individual sessions.
+Provides UI components for managing development sessions including creation, listing, and individual session display with status and actions.
 ## files
- create-session-form.tsx | A React form component for creating and starting a new development session with configurable project, repository, workspace, tool type, config profile, and SSH key options. | exp: CreateSessionForm | dep: react, ../../icon, ../../../api/sessions, ../../../types, ../../../api/git-repositories, ../../../api/tool-types, ../../../api/ssh-keys, ../../../api/config-profiles, ../../../api/workspaces, ../../../types/workspace, icon, sessions API, git-repositories API, tool-types API, ssh-keys API, config-profiles API, workspaces API, types
- session-card.tsx | Renders a card component displaying session information with status badges, inline rename editing, action buttons, and responsive mobile/desktop layouts including a dropdown options menu and mobile action sheet. | exp: SessionCardProps, func:SessionCard({ session, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, isBusy = false, tunnelHealth = null, }: SessionCardProps), call:useState, call:useRef, call:useMobileViewport, call:session.tool_type_interfaces?.includes, call:[ "running", "building", "starting", "probing", "pending", "unhealthy", ].includes, call:useEffect, call:optionsRef.current.contains, call:setOptionsOpen, call:document.addEventListener, call:document.removeEventListener, call:window.confirm, call:onDelete, call:setEditName, call:onRename, call:setIsEditingName, call:editName.trim, call:onOpen, call:new Date(session.created_at).toLocaleString, call:setShowActionSheet, call:onStart, call:onStop, call:onRecreateTunnel | dep: react, ../../../api/sessions, ../../icon, ../../../hooks/use-mobile-viewport, ../mobile/mobile-action-sheet
+- create-session-form.tsx | A React form component for creating and starting a new development session with configurable project, repository, workspace, tool type, config profile, and SSH key options. | exp: CreateSessionForm | dep: react, ../../icon, ../../loading-overlay, ../../../api/sessions, ../../../types, ../../../api/git-repositories, ../../../api/tool-types, ../../../api/ssh-keys, ../../../api/config-profiles, ../../../api/workspaces, ../../../types/workspace, icon, loading-overlay, sessions API, git-repositories API, tool-types API, ssh-keys API, config-profiles API, workspaces API, types
+- session-card.tsx | Renders a React card component displaying session information with status badges, inline rename editing, action buttons, and responsive mobile/desktop layouts including dropdown menus and action sheets. | exp: SessionCardProps, func:SessionCard({ session, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, isBusy = false, busyLabel = "Working...", tunnelHealth = null, }: SessionCardProps), call:useState, call:useRef, call:useMobileViewport, call:session.tool_type_interfaces?.includes, call:[ "running", "building", "starting", "probing", "pending", "unhealthy", ].includes, call:useEffect, call:optionsRef.current.contains, call:setOptionsOpen, call:document.addEventListener, call:document.removeEventListener, call:window.confirm, call:onDelete, call:setEditName, call:onRename, call:setIsEditingName, call:editName.trim, call:onOpen, call:new Date(session.created_at).toLocaleString, call:setShowActionSheet, call:onStart, call:onStop, call:onRecreateTunnel | dep: react, ../../../api/sessions, ../../icon, ../../../hooks/use-mobile-viewport, ../mobile/mobile-action-sheet, ../../loading-overlay
 - session-list.tsx | Renders a list of sessions grouped by active/recent status or as a flat grid, delegating to SessionCard for individual session display. | exp: SessionListProps, func:SessionList({ sessions, onOpen, onStart, onStop, onDelete, onRecreateTunnel, onRename, actionBusyId = null, tunnelHealth = {}, showGrouping = true, activeTitle = "Active Sessions", recentTitle = "Recent Sessions", maxRecent = 5, emptyMessage = "No sessions", }: SessionListProps), call:sessions.filter, call:activeStatuses.includes, call:sessions .filter((s) => recentStatuses.includes(s.status)) .slice, call:recentStatuses.includes, call:sessions.map, call:activeSessions.map, call:recentSessions.map | dep: ../../../api/sessions, ./session-card, Session, SessionCard, InstanceHealth
 ## arch
-Feature-based component architecture with compound component pattern (SessionCard/SessionList), controlled forms with validation, optimistic UI updates for inline editing, responsive design with mobile/desktop layout variants, and compound action menus using dropdowns/sheets.
+Presentational component pattern with feature-specific compound components (form, list, card) using responsive design and inline editing for CRUD session operations.
 ## tags
-session, call:use, call:on, api, card, call:set, event, mobile
+session, call:on, api, card, call:use, call:set, list, mobile
 ## symbols
 - SessionCard
 - SessionList
@@ -21,6 +21,7 @@ session, call:use, call:on, api, card, call:set, event, mobile
 - call:useState
 - call:useRef
 - call:useMobileViewport
+- call:session.tool_type_interfaces?.includes
 ## workflows
 - change session behavior
  read: create-session-form.tsx, session-card.tsx, session-list.tsx
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/settings

 ## role
-Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout.
+Provides the UI components for user-configurable application settings with tab-based navigation and form controls.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/web/src/components/features/settings
 index: apps/web/src/components/features/settings/.pi-map.index.md

 ## role
-Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout.
+Provides the UI components for user-configurable application settings with tab-based navigation and form controls.
 ## files
- GeneralSettingsTab.tsx | Renders a general settings tab with theme, git, editor, and notification preferences using shared outlet context | exp: GeneralSettingsTab | dep: react-router-dom, ../../icon, ../../../api/settings
- settings-tab-layout.tsx | Renders a tabbed settings layout with a sidebar navigation and active tab highlighting based on current URL path. | exp: SettingsTabLayout | dep: react, react-router-dom
+- GeneralSettingsTab.tsx | Renders a general settings tab with form controls for theme, git config, default editor, and notification preferences, wired to a parent-provided save handler. | exp: GeneralSettingsTab | dep: react-router-dom, ../../icon, ../../../api/settings
+- settings-tab-layout.tsx | Renders a settings page layout with a sidebar navigation of tabs and a content area for the active tab. | exp: SettingsTabLayout | dep: react, react-router-dom
 ## arch
-Uses a tabbed layout pattern with URL-based routing for navigation state, shared React context for data access, and compound component structure separating layout shell from content panels.
+Compound component pattern with a layout shell (sidebar + content area) and specialized tab content components, using controlled forms with parent-managed save handlers.
 ## tags
 settings, tab, general, layout, react, renders, router, dom
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/ssh-keys

 ## role
-Provides UI components for managing SSH keys, including creation and listing with cryptographic operations.
+Provides UI components for SSH key lifecycle management including creation and listing with cryptographic operations.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/web/src/components/features/ssh-keys
 index: apps/web/src/components/features/ssh-keys/.pi-map.index.md

 ## role
-Provides UI components for managing SSH keys, including creation and listing with cryptographic operations.
+Provides UI components for SSH key lifecycle management including creation and listing with cryptographic operations.
 ## files
- SSHKeyCreateForm.tsx | Renders a form for creating/generating a new SSH key with name input and submit button. | exp: SSHKeyCreateForm | dep: ../../icon, React, Icon component
- SSHKeyList.tsx | Renders a list of SSH keys with signing and verification capabilities | exp: SSHKeyList | dep: ../../icon, ../../data-states, ../../../api/ssh-keys, Icon, EmptyState, ErrorState, SSHKey type
+- SSHKeyCreateForm.tsx | Renders a form for creating/generating a new SSH key with name input and submit button | exp: SSHKeyCreateForm | dep: ../../icon, React, icon
+- SSHKeyList.tsx | Renders a list of SSH keys with signing and signature verification capabilities | exp: SSHKeyList | dep: ../../icon, ../../data-states, ../../../api/ssh-keys, icon, data-states, api/ssh-keys
 ## arch
-Feature-based component organization with presentational components following single-responsibility pattern (form vs list separation).
+Feature-based component organization with form/list pattern separation, each component handling distinct user workflows (creation vs. management/verification).
 ## tags
-sshkey, form, list, create, ssh, icon, renders, keys
+sshkey, form, list, ssh, create, icon, keys, renders
 ## symbols
 - SSHKeyCreateForm
 - SSHKeyList
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/terminal

 ## role
-Provides a cross-platform terminal emulator interface with WebSocket backend connectivity, supporting multiple sessions, special key input, and responsive desktop/mobile layouts.
+Provides responsive, cross-platform terminal UI components with session management, virtual special keys, and WebSocket-backed xterm.js integration for web-based terminal access.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,19 +4,19 @@ dir: apps/web/src/components/features/terminal
 index: apps/web/src/components/features/terminal/.pi-map.index.md

 ## role
-Provides a cross-platform terminal emulator interface with WebSocket backend connectivity, supporting multiple sessions, special key input, and responsive desktop/mobile layouts.
+Provides responsive, cross-platform terminal UI components with session management, virtual special keys, and WebSocket-backed xterm.js integration for web-based terminal access.
 ## files
- DesktopTerminalView.tsx | Renders a desktop-optimized terminal view with session tabs, fullscreen mode, font controls, and reset confirmation dialog | exp: DesktopTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../../api/terminal, React, TerminalComponent, TerminalSessionTabs, TerminalSession type
- MobileTerminalView.tsx | Renders a mobile-optimized terminal interface with toolbar, session tabs, terminal output, and special keys input controls. | exp: MobileTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../icon, ./special-keys-strip, ./special-keys-panel, ../../../hooks/use-special-keys, ../../../api/terminal
- special-keys-panel.tsx | Renders an overlay panel of special keyboard keys (Home, End, F1-F12, etc.) that sends terminal escape sequences when clicked, with optional modifier key support. | exp: SpecialKeysPanel | dep: react, ../../../hooks/use-special-keys, React, use-special-keys hook
- special-keys-strip.tsx | Renders a strip of buttons for sending special keyboard keys (Esc, Tab, arrows, etc.) with optional modifier support for a terminal interface. | exp: SpecialKeysStrip | dep: react, ../../../hooks/use-special-keys, React, use-special-keys hook
- terminal-session-tabs.test.tsx | Tests a React component that renders interactive terminal session tabs with selection, close confirmation, renaming, creation limits, and status indicators. | dep: @testing-library/react, vitest, ./terminal-session-tabs
- terminal-session-tabs.tsx | Renders a tabbed interface for managing multiple terminal sessions with selection, creation, renaming, and close confirmation features. | exp: TerminalSessionInfo, TerminalSessionTabsProps, TerminalSessionTabs | dep: react, React
- terminal.tsx | A React component that renders an interactive terminal emulator using xterm.js, connecting to a WebSocket backend with features like mobile touch scrolling, font resizing, flow control, heartbeat monitoring, and automatic reconnection. | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys
+- DesktopTerminalView.tsx | Renders a desktop terminal view with session tabs, fullscreen controls, and multiple terminal instances | exp: DesktopTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../../api/terminal
+- MobileTerminalView.tsx | Renders a mobile-optimized terminal interface with session tabs, toolbar controls, special keys input, and keyboard-aware layout adjustments. | exp: MobileTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../icon, ./special-keys-strip, ./special-keys-panel, ../../../hooks/use-special-keys, ../../../api/terminal, terminal, terminal-session-tabs, icon, special-keys-strip, special-keys-panel, use-special-keys, api/terminal
+- special-keys-panel.tsx | Renders an overlay panel of special keyboard keys (Home, End, F1-F12, Ctrl+C, etc.) that sends terminal sequences when clicked and supports modifier key combinations. | exp: SpecialKeysPanel | dep: react, ../../../hooks/use-special-keys, React, use-special-keys hook
+- special-keys-strip.tsx | Renders a strip of virtual special keys (Esc, Tab, Ctrl, Alt, arrows, etc.) for sending terminal key sequences with optional modifier support. | exp: SpecialKeysStrip | dep: react, ../../../hooks/use-special-keys, use-special-keys hook
+- terminal-session-tabs.test.tsx | Tests a React terminal session tabs component for rendering, selection, closing with confirmation, renaming, session limits, and connection status display. | dep: @testing-library/react, vitest, ./terminal-session-tabs
+- terminal-session-tabs.tsx | Renders an interactive tab bar for managing multiple terminal sessions with selection, renaming, closing, and creation capabilities | exp: TerminalSessionInfo, TerminalSessionTabsProps, TerminalSessionTabs | dep: react, React, useState, useRef, useCallback
+- terminal.tsx | A React terminal component that provides an interactive xterm.js-based terminal with WebSocket connectivity, mobile touch support, and session management. | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys, React
 ## arch
-Component-based architecture with platform-specific view variants (Desktop/Mobile), compound component pattern for terminal subsystems (tabs, special keys, xterm.js integration), and WebSocket-based real-time communication with reconnection and heartbeat monitoring.
+Component-based architecture with platform-specific view layers (desktop/mobile), modular special keys subsystems (strip/overlay panel), tab-based session management with React state, and xterm.js integration via WebSocket abstraction with touch/mobile adaptations.
 ## tags
-terminal, special, keys, session, react, tabs, view, renders
+terminal, special, keys, session, tabs, react, view, strip
 ## symbols
 - DesktopTerminalView
 - MobileTerminalView
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/tool-workshop

 ## role
-Provides a complete UI for managing custom tool types (compose, dockerfile, manifest) in a workshop interface with list, edit, and mobile-responsive views.
+Provides the UI components for a "Tool Workshop" feature that allows users to create, edit, list, and manage tool type definitions across desktop and mobile interfaces.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,15 +4,15 @@ dir: apps/web/src/components/features/tool-workshop
 index: apps/web/src/components/features/tool-workshop/.pi-map.index.md

 ## role
-Provides a complete UI for managing custom tool types (compose, dockerfile, manifest) in a workshop interface with list, edit, and mobile-responsive views.
+Provides the UI components for a "Tool Workshop" feature that allows users to create, edit, list, and manage tool type definitions across desktop and mobile interfaces.
 ## files
- ToolTypeEditorPanel.tsx | Renders a form panel for creating or editing tool types with support for compose, dockerfile, and manifest definition types | exp: ToolTypeFormState, ToolTypeEditorPanel | dep: ../../icon, ../tool/manifest-editor, ../../../api/tool-types, ../../../api/tool-definitions, React, Icon, ManifestEditor
- ToolTypeListSidebar.tsx | Renders a sidebar component for listing, selecting, creating, and deleting tool types in a "Tool Workshop" interface. | exp: ToolTypeListSidebar | dep: ../../icon, ../../../api/tool-types, React, Icon component, ToolType type
- ToolWorkshopMobileView.tsx | Renders a mobile-responsive workshop interface for managing tool types with list, detail, and edit views. | exp: MobileView, ToolWorkshopMobileView | dep: react, ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../tool/manifest-editor, ../../icon, ../../../api/tool-types, ./ToolTypeEditorPanel, ../../../api/tool-definitions, mobile-list-view, mobile-detail-view, mobile-edit-view, mobile-fab, manifest-editor, icon, tool-types, tool-definitions
+- ToolTypeEditorPanel.tsx | Renders a form panel for creating or editing tool type definitions with support for compose, dockerfile, and manifest definition types. | exp: ToolTypeFormState, ToolTypeEditorPanel | dep: ../../icon, ../tool/manifest-editor, ../../../api/tool-types, ../../../api/tool-definitions, React, Icon, ManifestEditor, ToolType, ToolDefinitionManifest
+- ToolTypeListSidebar.tsx | Renders a sidebar listing tool types with selection, creation, and deletion capabilities | exp: ToolTypeListSidebar | dep: ../../icon, ../../../api/tool-types, react, icon component, tool-types API type
+- ToolWorkshopMobileView.tsx | Renders a mobile-responsive three-view (list/detail/edit) interface for managing tool types in a Tool Workshop, with conditional form fields based on definition type and interface type. | exp: MobileView, ToolWorkshopMobileView | dep: react, ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../tool/manifest-editor, ../../icon, ../../../api/tool-types, ./ToolTypeEditorPanel, ../../../api/tool-definitions, mobile-list-view, mobile-detail-view, mobile-edit-view, mobile-fab, manifest-editor, icon, tool-types, tool-definitions
 ## arch
-Feature-based component composition with split-pane layout (sidebar + editor panel), responsive mobile adaptation, and CRUD operations for tool type definitions.
+Follows a split-pane layout pattern with sidebar list + detail/editor panels, using a mobile-specific three-view navigation variant; components are feature-scoped with prop-driven data flow and conditional rendering based on definition/interface type enums.
 ## tags
-tool, mobile, view, type, types, editor, list, workshop
+tool, mobile, type, view, types, editor, list, panel
 ## symbols
 - ToolTypeFormState
 - ToolTypeEditorPanel
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/tool

 ## role
-Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, and workspace-integrated tool launching.
+Provides UI components for managing containerized development tools, including instance lifecycle management, manifest configuration, and workspace-integrated tool launching.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,18 +4,18 @@ dir: apps/web/src/components/features/tool
 index: apps/web/src/components/features/tool/.pi-map.index.md

 ## role
-Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, and workspace-integrated tool launching.
+Provides UI components for managing containerized development tools, including instance lifecycle management, manifest configuration, and workspace-integrated tool launching.
 ## files
- instance-list.tsx | Displays and manages a list of tool instances with CRUD operations, real-time status updates, and configuration profile selection. | exp: InstanceList | dep: react, react-router-dom, ../../icon, ../../../api/sessions, ../../../api/tool-types, ../session/create-session-form, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/events, ../../../state/sessions, icon, api/sessions, api/tool-types, api/config-profiles, api/ssh-keys, state/events, state/sessions
- manifest-editor.tsx | A React component that provides a form-based UI for editing container tool definition manifests with fields for base images, packages, user config, environment variables, scripts, mounts, and runtime settings, including compilation preview functionality. | exp: ManifestEditor | dep: react, ../../icon, ../../../utils/errors, ../../../api/tool-definitions, icon, errors, tool-definitions
- start-tool-fab.tsx | A floating action button component that opens a modal to select a workspace and start a tool. | exp: func:StartToolFAB(), call:useState, call:setOpen, call:setWorkspacesLoading, call:listAllWorkspaces, call:setWorkspaces, call:setSelectedWorkspace, call:e.stopPropagation, call:workspaces.find, call:workspaces.map | dep: react, ../../icon, ./tool-starter, ../../../types/workspace, ../../../api/workspaces, icon, tool-starter, workspaces api, workspace types
- start-tool-modal.tsx | Renders a modal dialog for selecting a tool type and optional config profile to start on a workspace. | exp: StartToolModalProps, func:StartToolModal({ workspace, onClose, onStart, }: StartToolModalProps), call:useState, call:useAsyncData, call:e.preventDefault, call:setError, call:setSubmitting, call:onStart, call:onClose, call:e.stopPropagation, call:setToolTypeId, call:toolTypes?.map, call:setConfigProfileId | dep: react, ../../icon, ../../../api/tool-types, ../../../hooks/use-async-data, ../../../types/workspace, icon, tool-types, use-async-data, workspace
- tool-starter.tsx | A React component that provides a workspace-first UI for selecting tool types, config profiles, and SSH keys to create and start a new tool instance/session. | exp: ToolStarterProps, func:ToolStarter({ workspace, onStarted, onCancel, }: ToolStarterProps), call:useSessions, call:useSessionOperations, call:useState, call:useEffect, call:listToolTypes, call:setToolTypes, call:setToolTypesError, call:setToolTypesLoading, call:load, call:setProfiles, call:setSelectedProfileId, call:setProfilesLoading, call:listConfigProfiles, call:data.find, call:listSSHKeys, call:setSshKeys, call:setSelectedSshKeyIds, call:console.error, call:setSshKeysLoading, call:sshKeys.find, call:useCallback, call:setError, call:setStarting, call:createInstance, call:displayName.trim, call:startInstance, call:addOrUpdateSession, call:startOperation, call:onStarted, call:setSelectedToolTypeId, call:toolTypes.find, call:setDisplayName, call:toolTypes.map, call:setNameEdited, call:profiles.map, call:sshKeys.map, call:selectedSshKeyIds.includes, call:prev.filter | dep: react, ../../icon, ../../../api/tool-types, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/sessions, ../../../state/session-operations, ../../../types/workspace, ../../../api/sessions, icon, tool-types, config-profiles, ssh-keys, sessions, session-operations, workspace
+- instance-list.tsx | React component that displays and manages a list of tool instances with CRUD operations, real-time status updates, and configuration profile selection. | exp: InstanceList | dep: react, react-router-dom, ../../icon, ../../loading-overlay, ../../../api/sessions, ../../../api/tool-types, ../session/create-session-form, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/events, ../../../state/sessions
+- manifest-editor.tsx | A React component that provides a form-based UI for editing container manifest configurations including base images, packages, environment variables, scripts, mounts, and runtime settings, with live preview generation capability. | exp: ManifestEditor | dep: react, ../../icon, ../../../utils/errors, ../../../api/tool-definitions, icon, errors utils, tool-definitions API
+- start-tool-fab.tsx | Renders a floating action button that opens a modal to select a workspace and start a tool. | exp: func:StartToolFAB(), call:useState, call:setOpen, call:setWorkspacesLoading, call:listAllWorkspaces, call:setWorkspaces, call:setSelectedWorkspace, call:e.stopPropagation, call:workspaces.find, call:workspaces.map | dep: react, ../../icon, ./tool-starter, ../../../types/workspace, ../../../api/workspaces, icon, tool-starter, workspace types, workspaces api
+- start-tool-modal.tsx | React modal component for selecting a tool type and optional config profile to start a tool on a workspace | exp: StartToolModalProps, func:StartToolModal({ workspace, onClose, onStart, }: StartToolModalProps), call:useState, call:useAsyncData, call:e.preventDefault, call:setError, call:setSubmitting, call:onStart, call:onClose, call:e.stopPropagation, call:setToolTypeId, call:toolTypes?.map, call:setConfigProfileId | dep: react, ../../icon, ../../../api/tool-types, ../../../hooks/use-async-data, ../../../types/workspace
+- tool-starter.tsx | React component for starting a tool instance within a workspace with configurable tool types, profiles, and SSH keys | exp: ToolStarterProps, func:ToolStarter({ workspace, onStarted, onCancel, }: ToolStarterProps), call:useSessions, call:useState, call:useEffect, call:listToolTypes, call:setToolTypes, call:setToolTypesError, call:setToolTypesLoading, call:load, call:setProfiles, call:setSelectedProfileId, call:setProfilesLoading, call:listConfigProfiles, call:data.find, call:listSSHKeys, call:setSshKeys, call:setSelectedSshKeyIds, call:console.error, call:setSshKeysLoading, call:sshKeys.find, call:useCallback, call:setError, call:setStarting, call:createInstance, call:displayName.trim, call:startInstance, call:addOrUpdateSession, call:onStarted, call:setSelectedToolTypeId, call:toolTypes.find, call:setDisplayName, call:toolTypes.map, call:setNameEdited, call:profiles.map, call:sshKeys.map, call:selectedSshKeyIds.includes, call:prev.filter | dep: react, ../../icon, ../../loading-overlay, ../../../api/tool-types, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/sessions, ../../../types/workspace, ../../../api/sessions, icon, loading-overlay, tool-types, config-profiles, ssh-keys, sessions, workspace types, sessions api
 - tools-bottom-sheet.tsx | Renders a mobile bottom sheet navigation menu for tools with active route highlighting | exp: ToolsBottomSheet | dep: react-router-dom, ../../icon, icon
 ## arch
-Feature-based component architecture with modal/sheet UI patterns, form-driven configuration editing, and workspace-contextual tool orchestration with mobile-responsive navigation.
+Feature-based React component architecture with modal/bottom-sheet mobile-responsive patterns, form-driven configuration editing with live preview, and workspace-contextual tool orchestration.
 ## tags
-tool, call:set, types, call:use, api, start, ssh, icon
+call:set, tool, types, start, call:use, ssh, react, loading
 ## symbols
 - StartToolFAB
 - StartToolModal
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/workspace

 ## role
-Provides the complete UI component suite for workspace management, including creation, detail viewing, file editing, Git operations, tool management, and settings.
+Provides UI components for workspace management, navigation, and operations in a web-based development environment.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,22 +4,22 @@ dir: apps/web/src/components/features/workspace
 index: apps/web/src/components/features/workspace/.pi-map.index.md

 ## role
-Provides the complete UI component suite for workspace management, including creation, detail viewing, file editing, Git operations, tool management, and settings.
+Provides UI components for workspace management, navigation, and operations in a web-based development environment.
 ## files
 - workspace-card.tsx | React component that renders a card displaying workspace information with status, metadata, and action buttons. | exp: WorkspaceCardProps, func:WorkspaceCard({ workspace, loading = false, onStartTool, onSync, onDelete, }: WorkspaceCardProps), call:onStartTool, call:onSync, call:onDelete | dep: react-router-dom, ../../icon, ./workspace-instance-chips, ../../../types/workspace
- workspace-create-form.tsx | React form component for creating workspaces with cascading project/repository/branch selectors and support for both contextual and standalone modes | exp: WorkspaceCreateFormProps, func:WorkspaceCreateForm({ onSubmit, onCancel, defaultProjectId, defaultRepoId, }: WorkspaceCreateFormProps), call:Boolean, call:useState, call:useGitRepo, call:useEffect, call:git.branches.includes, call:setSelectedBranch, call:setIsNewBranch, call:useCallback, call:listProjects, call:setProjects, call:setSelectedProject, call:setError, call:setFetchingProjects, call:loadProjects, call:setRepos, call:setSelectedRepo, call:listRepositories, call:loadRepos, call:setNewBranchName, call:e.preventDefault, call:name.trim, call:newBranchName.trim, call:setSubmitting, call:createWorkspaceTopLevel, call:onSubmit, call:projects.map, call:repos.map, call:setName, call:handleBranchChange, call:git.branches.map | dep: react, ../../icon, ../../../api/projects, ../../../api/git-repositories, ../../../api/workspaces, ../../../hooks/use-git-repo, ../../../types, icon, api/projects, api/git-repositories, api/workspaces, hooks/use-git-repo, types
- workspace-detail-header.tsx | Renders a header component for a workspace detail page showing breadcrumb navigation and branch information. | exp: WorkspaceDetailHeaderProps, func:WorkspaceDetailHeader({ workspace, }: WorkspaceDetailHeaderProps) | dep: ../../icon, react
- workspace-file-panel.tsx | Renders a file browser and editor panel with Git integration for a workspace detail page. | exp: func:WorkspaceFilePanel({ workspaceId }: WorkspaceFilePanelProps), call:useWorkspaceFiles, call:useWorkspaceGit, call:useState, call:setSelectedPath, call:setIsEditing, call:setEditContent, call:navigateTo, call:loadFile, call:currentPath.split("/").slice(0, -1).join, call:saveFile, call:setCommitMessage, call:commit, call:entries.map, call:handleSelect | dep: react, ../../icon, ../../../hooks/use-workspace-files, ../../../hooks/use-workspace-git, ../../../api/workspace-files
- workspace-git-panel.tsx | Renders a Git panel for a workspace detail page that displays branch selection and commit history. | exp: func:WorkspaceGitPanel({ workspaceId }: WorkspaceGitPanelProps), call:useWorkspaceGit, call:checkout, call:branches.map, call:history.map, call:commit.hash.slice | dep: ../../../hooks/use-workspace-git, react, use-workspace-git hook
- workspace-header.tsx | Renders a workspace header component displaying project info with navigation links to history and settings pages. | exp: WorkspaceHeader | dep: react-router-dom, ../../icon, icon
+- workspace-create-form.tsx | A React form component for creating workspaces with cascading project/repository/branch selectors and support for both contextual (pre-selected) and standalone modes. | exp: WorkspaceCreateFormProps, func:WorkspaceCreateForm({ onSubmit, onCancel, defaultProjectId, defaultRepoId, }: WorkspaceCreateFormProps), call:Boolean, call:useState, call:useGitRepo, call:useEffect, call:git.branches.includes, call:setSelectedBranch, call:setIsNewBranch, call:useCallback, call:listProjects, call:setProjects, call:setSelectedProject, call:setError, call:setFetchingProjects, call:loadProjects, call:setRepos, call:setSelectedRepo, call:listRepositories, call:loadRepos, call:setNewBranchName, call:e.preventDefault, call:name.trim, call:newBranchName.trim, call:setSubmitting, call:createWorkspaceTopLevel, call:onSubmit, call:projects.map, call:repos.map, call:setName, call:handleBranchChange, call:git.branches.map | dep: react, ../../icon, ../../../api/projects, ../../../api/git-repositories, ../../../api/workspaces, ../../../hooks/use-git-repo, ../../../types, icon component, projects API, git-repositories API, workspaces API, use-git-repo hook
+- workspace-detail-header.tsx | Renders a header component for a workspace detail page showing breadcrumb navigation and branch information. | exp: WorkspaceDetailHeaderProps, func:WorkspaceDetailHeader({ workspace, }: WorkspaceDetailHeaderProps) | dep: ../../icon, icon
+- workspace-file-panel.tsx | Renders a file browser and editor panel for a workspace with integrated Git status and operations toolbar. | exp: func:WorkspaceFilePanel({ workspaceId }: WorkspaceFilePanelProps), call:useWorkspaceFiles, call:useWorkspaceGit, call:useState, call:setSelectedPath, call:setIsEditing, call:setEditContent, call:navigateTo, call:loadFile, call:currentPath.split("/").slice(0, -1).join, call:saveFile, call:setCommitMessage, call:commit, call:entries.map, call:handleSelect | dep: react, ../../icon, ../../../hooks/use-workspace-files, ../../../hooks/use-workspace-git, ../../../api/workspace-files
+- workspace-git-panel.tsx | Renders a Git panel for a workspace detail page showing branch selector and commit history. | exp: func:WorkspaceGitPanel({ workspaceId }: WorkspaceGitPanelProps), call:useWorkspaceGit, call:checkout, call:branches.map, call:history.map, call:commit.hash.slice | dep: ../../../hooks/use-workspace-git, react, use-workspace-git hook
+- workspace-header.tsx | Renders a workspace header component displaying project info, current repository, and navigation links to history and settings pages. | exp: WorkspaceHeader | dep: react-router-dom, ../../icon, icon
 - workspace-instance-chips.tsx | Displays running tool instances for a workspace as clickable status chips with external links. | exp: func:WorkspaceInstanceChips({ workspaceId, }: WorkspaceInstanceChipsProps), call:useState, call:useEffect, call:listWorkspaceInstances, call:setInstances, call:setLoading, call:load, call:instances.map, call:e.stopPropagation | dep: react, ../../../api/workspace-instances, ../../../api/sessions
- workspace-settings-panel.tsx | Displays a read-only settings panel showing workspace information details | exp: func:WorkspaceSettingsPanel({ workspace, }: WorkspaceSettingsPanelProps) | dep: ../../../types/workspace, React, Workspace type
- workspace-tab-bar.tsx | Renders desktop and mobile tab bar components for workspace navigation with files, git, tools, and settings tabs. | exp: WorkspaceTab, func:WorkspaceTabBar({ active, onChange }: WorkspaceTabBarProps), call:TABS.map, call:onChange, func:WorkspaceMobileTabBar({ active, onChange, }: WorkspaceTabBarProps), call:TABS.map, call:onChange | dep: ../../icon, react
- workspace-tools-panel.tsx | Renders a tools management panel for a workspace that displays running tool instances and allows starting new tools via a modal | exp: func:WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps), call:useWorkspaceInstances, call:useState, call:setShowModal, call:instances.map, call:e.stopPropagation, call:refresh | dep: react, ../../icon, ../tool/tool-starter, ../../../hooks/use-workspace-instances, ../../../types/workspace, icon, tool-starter, use-workspace-instances, workspace types
+- workspace-settings-panel.tsx | Displays a read-only settings panel showing workspace information for a workspace detail page. | exp: func:WorkspaceSettingsPanel({ workspace, }: WorkspaceSettingsPanelProps) | dep: ../../../types/workspace, React, types/workspace
+- workspace-tab-bar.tsx | Renders a tab bar navigation component for workspace detail pages with desktop and mobile variants. | exp: WorkspaceTab, func:WorkspaceTabBar({ active, onChange }: WorkspaceTabBarProps), call:TABS.map, call:onChange, func:WorkspaceMobileTabBar({ active, onChange, }: WorkspaceTabBarProps), call:TABS.map, call:onChange | dep: ../../icon, icon
+- workspace-tools-panel.tsx | Renders a tools management panel for a workspace that displays running tool instances and provides a modal to start new tools. | exp: func:WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps), call:useWorkspaceInstances, call:useState, call:setShowModal, call:instances.map, call:e.stopPropagation, call:refresh | dep: react, ../../icon, ../tool/tool-starter, ../../../hooks/use-workspace-instances, ../../../types/workspace
 ## arch
-Feature-based component organization with compound page pattern (header/tab-bar/panels), form abstraction for creation, and modal-driven tool management with responsive mobile/desktop tab navigation.
+Feature-based component architecture with compound UI pattern - specialized sub-components (header, panels, forms, navigation) compose into complete workspace views, using container/presentational separation with integrated Git tooling and multi-modal workspace interactions.
 ## tags
-workspace, call:set, call:use, panel, git, branch, react, call:on
+workspace, call:set, call:use, panel, git, branch, call:on, header
 ## symbols
 - WorkspaceCard
 - WorkspaceCreateForm
@@ -2,7 +2,7 @@
 dir: apps/web/src/hooks

 ## role
-Provides reusable React custom hooks that encapsulate stateful logic, side effects, and API interactions for the web application's UI components, covering data fetching, terminal management, workspace operations, notifications, and mobile-specific behaviors.
+A collection of custom React hooks that encapsulate domain-specific business logic, API interactions, and UI state management for a cloud workspace/terminal IDE web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,34 +4,34 @@ dir: apps/web/src/hooks
 index: apps/web/src/hooks/.pi-map.index.md

 ## role
-Provides reusable React custom hooks that encapsulate stateful logic, side effects, and API interactions for the web application's UI components, covering data fetching, terminal management, workspace operations, notifications, and mobile-specific behaviors.
+A collection of custom React hooks that encapsulate domain-specific business logic, API interactions, and UI state management for a cloud workspace/terminal IDE web application.
 ## files
- use-async-data.ts | A custom React hook that manages asynchronous data fetching with loading, error, and ready states, plus a manual reload capability. | exp: func:useAsyncData(fetcher: () => Promise<T>, deps: React.DependencyList) → UseAsyncDataResult<T>, call:useState, call:useCallback, call:setStatus, call:setError, call:fetcher, call:setData, call:load, call:useEffect | dep: react
- use-auto-hide.ts | A React custom hook that automatically hides an element after a specified timeout and provides manual controls for showing, hiding, and toggling visibility. | exp: func:useAutoHide(options: AutoHideOptions), call:useState, call:useRef, call:Date.now, call:useCallback, call:setIsVisible, call:clearTimeout, call:setTimeout, call:hide, call:show, call:useEffect | dep: react
- use-config-profiles.ts | A React custom hook that manages CRUD operations, form state, drag-and-drop ordering, and cyclic dependency prevention for configuration profiles. | exp: useConfigProfiles | dep: react, ../utils/errors, ../api/config-profiles, ../api/projects, ../api/tool-types, ../types
- use-events.test.ts | Tests a React hook that manages Server-Sent Events (SSE) connections with automatic reconnection, backoff, and error handling | dep: vitest, @testing-library/react, ./use-events, ../api/events, use-events hook
- use-events.ts | React hook that manages a Server-Sent Events connection with automatic exponential backoff reconnection, lifecycle event handling, and authentication redirect on 401 errors. | exp: UseEventsReturn, func:useEvents() → UseEventsReturn, call:useState, call:useRef, call:useCallback, call:clearTimeout, call:createEventSource, call:setConnected, call:setError, call:setReconnectCount, call:JSON.parse, call:setEvents, call:es.addEventListener, call:es.close, call:Math.min, call:Math.pow, call:Math.random, call:setTimeout, call:probeEventStreamStatus, call:window.location.assign, call:connect, call:useEffect, call:esRef.current.close | dep: react, ../api/events, ../types/events
- use-git-repo.ts | A custom React hook that centralizes all git repository operations (branch management, status tracking, commit history, and git actions) into a reusable interface for components. | exp: GitStatus, UseGitRepoResult, func:useGitRepo(projectId: string | undefined, repoId: string | undefined) → UseGitRepoResult, call:useState, call:useCallback, call:setLoading, call:setError, call:fn, call:extractError, call:withLoading, call:listRepositoryBranches, call:setBranches, call:data.branches.map, call:setDefaultBranch, call:getRepositoryStatus, call:setStatus, call:getRepositoryHistory, call:setHistory, call:getCommitDetail, call:setCommitDetail, call:commitChanges, call:refreshStatus, call:pushRepository, call:pullRepository, call:fetchRepository, call:checkoutBranch, call:refreshBranches, call:createBranch, call:deleteBranch, call:mergeBranches, call:refreshHistory, call:useEffect, raise:err | dep: react, ../api/git-repositories
- use-instance-actions.ts | A React custom hook that manages instance/session actions including opening, starting, stopping, deleting, force-deleting, recreating tunnels, and renaming with loading states and dirty delete handling. | exp: func:useInstanceActions(options: UseInstanceActionsOptions) → UseInstanceActionsReturn, call:useSessions, call:useState, call:useRef, call:useCallback, call:tabRefs.current.get, call:existing.focus, call:session.tool_type_interfaces?.includes, call:window.open, call:tabRefs.current.set, call:setLoadingSessionId, call:startInstance, call:onRefresh, call:stopInstance, call:deleteInstance, call:setDirtyDeleteSession, call:setDirtyDeleteFiles, call:removeSession, call:recreateInstanceTunnel, call:alert, call:newName.trim, call:renameInstance | dep: react, ../api/sessions, ../state/sessions
- use-mobile-viewport.ts | A React hook that tracks whether the viewport width is below a mobile breakpoint (768px) | exp: func:useMobileViewport(), call:useState, call:useEffect, call:setIsMobile, call:window.addEventListener, call:window.removeEventListener | dep: react
- use-notifications.test.tsx | Tests the useNotifications custom React hook with mocked API calls, covering optimistic updates, polling behavior, and error handling. | dep: vitest, @testing-library/react, ./use-notifications, ../state/notifications, ../api/notifications, use-notifications
- use-notifications.ts | Custom React hook that provides access to notification state and ensures it's used within a NotificationProvider | exp: func:useNotifications(), call:useContext, raise:Error | dep: react, ../state/notifications
- use-projects.ts | Custom React hook for managing project CRUD operations, workspace management, and dialog state for a project management UI | exp: useProjects | dep: react, ../api/projects, ../api/workspaces, ./use-async-data, ../types
- use-special-keys.ts | Maps special keys and modifier+character combinations to ANSI escape sequences for terminal input simulation. | exp: SpecialKey, ModifierKey, func:getSequenceWithModifier(key: SpecialKey, activeModifier: ModifierKey | null) → { sequence: string; clearModifier: boolean } | null, call:char.toLowerCase, func:applyModifierToChar(char: string, modifier: ModifierKey) → string | null, call:char.toLowerCase
- use-ssh-keys.ts | A React custom hook that manages SSH key operations including listing, generating, deleting, signing payloads, and verifying signatures. | exp: useSSHKeys | dep: react, ../api/ssh-keys, ./use-async-data
- use-start-tool.ts | React hook for managing the state and API calls to create and start a tool instance on a workspace. | exp: UseStartToolResult, func:useStartTool() → UseStartToolResult, call:useState, call:useCallback, call:setStarting, call:setError, call:createInstance, call:startInstance | dep: react, ../api/sessions, ../types/workspace
- use-terminal-page.ts | Manages terminal page state including sessions, keyboard shortcuts, fullscreen mode, mobile viewport handling, and terminal lifecycle operations. | exp: useTerminalPage | dep: react, react-router-dom, ../components/features/terminal/terminal, ../components/features/terminal/terminal-session-tabs, ./use-mobile-viewport, ./use-auto-hide, ./use-virtual-keyboard, ./use-terminal-sessions, ../api/terminal, ./use-special-keys, use-mobile-viewport, use-auto-hide, use-virtual-keyboard, use-terminal-sessions, terminal, terminal-session-tabs, api/terminal, api/sessions, use-special-keys
- use-terminal-sessions.ts | React custom hook that manages terminal session state (CRUD operations, active session tracking) for a given instance | exp: UseTerminalSessionsResult, func:useTerminalSessions(instanceId: string) → UseTerminalSessionsResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listTerminalSessions, call:setSessions, call:setActiveSessionId, call:createTerminalSession, call:closeTerminalSession, call:prev.filter, call:renameTerminalSession, call:prev.map, call:resetTerminalSession, call:loadSessions, call:useEffect | dep: react, ../api/terminal
- use-theme.ts | React hook that fetches user theme preference on mount and applies it to the document root element via data-theme attribute | exp: func:useTheme(), call:useEffect, call:getUserConfig, call:document.documentElement.removeAttribute, call:document.documentElement.setAttribute | dep: react, ../api/settings
- use-tool-workshop.ts | Custom React hook that manages state and operations for a tool workshop UI, including CRUD operations for tool types and tool definitions with form handling and validation. | exp: useToolWorkshop | dep: react, ../utils/errors, ../api/tool-types, ../api/tool-definitions, ../components/features/tool-workshop/ToolTypeEditorPanel
- use-virtual-keyboard.ts | React hook that detects virtual keyboard open/close state and measures its height on mobile devices | exp: func:useVirtualKeyboard(), call:useState, call:useCallback, call:setState, call:useEffect, call:visualViewport.addEventListener, call:window.addEventListener, call:updateKeyboardState, call:visualViewport.removeEventListener, call:window.removeEventListener | dep: react
- use-workspace-actions.ts | Provides a React hook that encapsulates workspace CRUD operations with loading state management and user confirmation dialogs for destructive actions. | exp: UseWorkspaceActionsResult, func:useWorkspaceActions() → UseWorkspaceActionsResult, call:useState, call:useCallback, call:createWorkspace, call:setLoadingId, call:deleteWorkspace, call:onRefresh, call:window.confirm, call:instances.map((i) => `- ${i.name}`).join, call:syncWorkspace, call:updateWorkspace, raise:err | dep: react, ../api/workspaces, ../types/workspace
- use-workspace-files.ts | Custom React hook for managing workspace file operations including listing, loading, saving, and navigating files. | exp: UseWorkspaceFilesResult, func:useWorkspaceFiles(workspaceId: string) → UseWorkspaceFilesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceFiles, call:setEntries, call:setCurrentPath, call:setContent, call:getWorkspaceFileContent, call:saveWorkspaceFile, call:refresh, call:useEffect | dep: react, ../api/workspace-files
- use-workspace-git.ts | Custom React hook that provides git operations and state management for a workspace | exp: UseWorkspaceGitResult, func:useWorkspaceGit(workspaceId: string) → UseWorkspaceGitResult, call:useState, call:useCallback, call:setLoading, call:setError, call:Promise.all, call:getGitStatus, call:getGitBranches, call:getGitHistory, call:setStatus, call:setBranches, call:setCurrentBranch, call:setHistory, call:gitCommit, call:refresh, call:gitPush, call:gitPull, call:gitFetch, call:gitCheckout, call:useEffect | dep: react, ../api/workspace-git
- use-workspace-instances.ts | Custom React hook for managing workspace instances with CRUD operations, loading states, and error handling. | exp: UseWorkspaceInstancesResult, func:useWorkspaceInstances(workspaceId: string) → UseWorkspaceInstancesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceInstances, call:setInstances, call:createWorkspaceInstance, call:refresh, call:useEffect | dep: react, ../api/workspace-instances, ../api/sessions
- use-workspaces.ts | Custom React hook that fetches and manages workspace data with loading and error states. | exp: UseWorkspacesResult, func:useWorkspaces(projectId: string, repoId: string) → UseWorkspacesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaces, call:listAllWorkspaces, call:setWorkspaces, call:useEffect, call:refresh | dep: react, ../api/workspaces, ../types/workspace
+- use-async-data.ts | A custom React hook that manages asynchronous data fetching with loading, error, and success states. | exp: func:useAsyncData(fetcher: () => Promise<T>, deps: React.DependencyList) → UseAsyncDataResult<T>, call:useState, call:useCallback, call:setStatus, call:setError, call:fetcher, call:setData, call:load, call:useEffect | dep: react
+- use-auto-hide.ts | React hook that automatically hides UI elements after a period of inactivity, with manual controls to show/hide/toggle visibility. | exp: func:useAutoHide(options: AutoHideOptions), call:useState, call:useRef, call:Date.now, call:useCallback, call:setIsVisible, call:clearTimeout, call:setTimeout, call:hide, call:show, call:useEffect | dep: react
+- use-config-profiles.ts | React custom hook for managing configuration profiles with CRUD operations, profile inclusion with cycle detection, drag-and-drop reordering, and form state management. | exp: useConfigProfiles | dep: react, ../utils/errors, ../api/config-profiles, ../api/projects, ../api/tool-types, ../types
+- use-events.test.ts | Tests a React hook that manages Server-Sent Events (SSE) connections with automatic reconnection, backoff, and error handling | dep: vitest, @testing-library/react, ./use-events, ../api/events, use-events hook, ../api/events module
+- use-events.ts | Manages a Server-Sent Events (SSE) connection with exponential backoff reconnection, lifecycle event listening, and authentication redirect handling in a React hook. | exp: UseEventsReturn, func:useEvents() → UseEventsReturn, call:useState, call:useRef, call:useCallback, call:clearTimeout, call:createEventSource, call:setConnected, call:setError, call:setReconnectCount, call:JSON.parse, call:setEvents, call:es.addEventListener, call:es.close, call:Math.min, call:Math.pow, call:Math.random, call:setTimeout, call:probeEventStreamStatus, call:window.location.assign, call:connect, call:useEffect, call:esRef.current.close | dep: react, ../api/events, ../types/events
+- use-git-repo.ts | A React custom hook that centralizes git repository operations including branch management, status tracking, commit history, and remote actions for a given project/repo ID pair. | exp: GitStatus, UseGitRepoResult, func:useGitRepo(projectId: string | undefined, repoId: string | undefined) → UseGitRepoResult, call:useState, call:useCallback, call:setLoading, call:setError, call:fn, call:extractError, call:withLoading, call:listRepositoryBranches, call:setBranches, call:data.branches.map, call:setDefaultBranch, call:getRepositoryStatus, call:setStatus, call:getRepositoryHistory, call:setHistory, call:getCommitDetail, call:setCommitDetail, call:commitChanges, call:refreshStatus, call:pushRepository, call:pullRepository, call:fetchRepository, call:checkoutBranch, call:refreshBranches, call:createBranch, call:deleteBranch, call:mergeBranches, call:refreshHistory, call:useEffect, raise:err | dep: react, ../api/git-repositories
+- use-instance-actions.ts | A React custom hook that manages instance actions (start, stop, delete, rename, recreate tunnel, open) with loading states and dirty delete handling. | exp: func:useInstanceActions(options: UseInstanceActionsOptions) → UseInstanceActionsReturn, call:useSessions, call:useState, call:useCallback, call:openSession, call:setLoadingSessionId, call:startInstance, call:onRefresh, call:stopInstance, call:deleteInstance, call:setDirtyDeleteSession, call:setDirtyDeleteFiles, call:removeSession, call:recreateInstanceTunnel, call:alert, call:newName.trim, call:renameInstance | dep: react, ../api/sessions, ../state/sessions, ../utils/open-session
+- use-mobile-viewport.ts | Custom React hook that returns a boolean indicating whether the viewport width is below a mobile breakpoint (768px) | exp: func:useMobileViewport(), call:useState, call:useEffect, call:setIsMobile, call:window.addEventListener, call:window.removeEventListener | dep: react
+- use-notifications.test.tsx | Tests a React hook for managing notifications with optimistic updates, polling, and error handling. | dep: vitest, @testing-library/react, ./use-notifications, ../state/notifications, ../api/notifications, use-notifications, NotificationProvider, notifications API
+- use-notifications.ts | Custom React hook that provides access to notification context with runtime validation that it's used within a provider | exp: func:useNotifications(), call:useContext, raise:Error | dep: react, ../state/notifications
+- use-projects.ts | Custom React hook that manages project CRUD operations, workspace synchronization, and UI state for a project management interface | exp: useProjects | dep: react, ../api/projects, ../api/workspaces, ./use-async-data, ../types
+- use-special-keys.ts | Provides ANSI escape sequences and modifier key mappings for terminal special key handling in a React hook or terminal emulator. | exp: SpecialKey, ModifierKey, func:getSequenceWithModifier(key: SpecialKey, activeModifier: ModifierKey | null) → { sequence: string; clearModifier: boolean } | null, call:char.toLowerCase, func:applyModifierToChar(char: string, modifier: ModifierKey) → string | null, call:char.toLowerCase
+- use-ssh-keys.ts | React custom hook that manages SSH key CRUD operations, cryptographic signing/verification, and clipboard functionality with async state handling. | exp: useSSHKeys | dep: react, ../api/ssh-keys, ./use-async-data
+- use-start-tool.ts | React hook that manages the state and API calls for creating and starting a tool instance on a workspace. | exp: UseStartToolResult, func:useStartTool() → UseStartToolResult, call:useState, call:useCallback, call:setStarting, call:setError, call:createInstance, call:startInstance | dep: react, ../api/sessions, ../types/workspace
+- use-terminal-page.ts | Custom React hook that orchestrates terminal page state, session management, keyboard shortcuts, mobile UX, and fullscreen behavior for a multi-session terminal interface. | exp: useTerminalPage | dep: react, react-router-dom, ../components/features/terminal/terminal, ../components/features/terminal/terminal-session-tabs, ./use-mobile-viewport, ./use-auto-hide, ./use-virtual-keyboard, ./use-terminal-sessions, ../api/terminal, ./use-special-keys, use-mobile-viewport, use-auto-hide, use-virtual-keyboard, use-terminal-sessions, use-special-keys, terminal, terminal-session-tabs, sessions API
+- use-terminal-sessions.ts | Custom React hook that manages terminal session state (CRUD operations, active session tracking, loading/error handling) for a given instance. | exp: UseTerminalSessionsResult, func:useTerminalSessions(instanceId: string) → UseTerminalSessionsResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listTerminalSessions, call:setSessions, call:setActiveSessionId, call:createTerminalSession, call:closeTerminalSession, call:prev.filter, call:renameTerminalSession, call:prev.map, call:resetTerminalSession, call:loadSessions, call:useEffect | dep: react, ../api/terminal
+- use-theme.ts | React hook that fetches user theme preference on mount and applies it to the document root element | exp: func:useTheme(), call:useEffect, call:getUserConfig, call:document.documentElement.removeAttribute, call:document.documentElement.setAttribute | dep: react, ../api/settings
+- use-tool-workshop.ts | A React custom hook that manages state and operations for a tool workshop UI, including CRUD operations for tool types and tool definitions with form handling and validation. | exp: useToolWorkshop | dep: react, ../utils/errors, ../api/tool-types, ../api/tool-definitions, ../components/features/tool-workshop/ToolTypeEditorPanel
+- use-virtual-keyboard.ts | A React hook that detects and tracks virtual keyboard state (open/closed, height, viewport height) on mobile devices using Visual Viewport API with fallback for older browsers. | exp: func:useVirtualKeyboard(), call:useState, call:useCallback, call:setState, call:useEffect, call:visualViewport.addEventListener, call:window.addEventListener, call:updateKeyboardState, call:visualViewport.removeEventListener, call:window.removeEventListener | dep: react
+- use-workspace-actions.ts | Provides a React hook that wraps workspace CRUD API operations with loading state management and user confirmation dialogs for destructive/conflicting actions. | exp: UseWorkspaceActionsResult, func:useWorkspaceActions() → UseWorkspaceActionsResult, call:useState, call:useCallback, call:createWorkspace, call:setLoadingId, call:deleteWorkspace, call:onRefresh, call:window.confirm, call:instances.map((i) => `- ${i.name}`).join, call:syncWorkspace, call:updateWorkspace, raise:err | dep: react, ../api/workspaces, ../types/workspace
+- use-workspace-files.ts | React custom hook that manages workspace file operations including listing, loading, saving, and navigating files. | exp: UseWorkspaceFilesResult, func:useWorkspaceFiles(workspaceId: string) → UseWorkspaceFilesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceFiles, call:setEntries, call:setCurrentPath, call:setContent, call:getWorkspaceFileContent, call:saveWorkspaceFile, call:refresh, call:useEffect | dep: react, ../api/workspace-files
+- use-workspace-git.ts | Provides a React custom hook that encapsulates workspace Git operations including status, branches, history, and actions like commit/push/pull/checkout. | exp: UseWorkspaceGitResult, func:useWorkspaceGit(workspaceId: string) → UseWorkspaceGitResult, call:useState, call:useCallback, call:setLoading, call:setError, call:Promise.all, call:getGitStatus, call:getGitBranches, call:getGitHistory, call:setStatus, call:setBranches, call:setCurrentBranch, call:setHistory, call:gitCommit, call:refresh, call:gitPush, call:gitPull, call:gitFetch, call:gitCheckout, call:useEffect | dep: react, ../api/workspace-git
+- use-workspace-instances.ts | React hook that manages workspace instance state with CRUD operations for listing, refreshing, and creating tool instances within a workspace. | exp: UseWorkspaceInstancesResult, func:useWorkspaceInstances(workspaceId: string) → UseWorkspaceInstancesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaceInstances, call:setInstances, call:createWorkspaceInstance, call:refresh, call:useEffect | dep: react, ../api/workspace-instances, ../api/sessions
+- use-workspaces.ts | Custom React hook that fetches and manages workspace data with loading and error states | exp: UseWorkspacesResult, func:useWorkspaces(projectId: string, repoId: string) → UseWorkspacesResult, call:useState, call:useCallback, call:setLoading, call:setError, call:listWorkspaces, call:listAllWorkspaces, call:setWorkspaces, call:useEffect, call:refresh | dep: react, ../api/workspaces, ../types/workspace
 ## arch
-Follows a custom hook composition pattern where each hook encapsulates a single domain concern (data fetching, CRUD operations, UI state, device detection), often combining useState/useEffect/useCallback with SWR-style async data management, and layering higher-level hooks (use-terminal-page) from lower-level ones (use-mobile-viewport, use-virtual-keyboard).
+Layered custom hook architecture following React patterns—composing useState/useEffect for async operations, context integration, optimistic updates, polling, and mobile-responsive behaviors; each hook typically isolates a single domain concern (workspaces, terminals, git, notifications, etc.) with consistent loading/error state patterns.
 ## tags
 call:set, call:use, workspace, react, state, terminal, api, callback
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/pages

 ## role
-Contains top-level page components that render the main UI views for the web application, each corresponding to a distinct route and feature area.
+Contains all top-level page components for the web application, serving as the routing endpoints that compose the UI for each distinct feature area.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,30 +4,30 @@ dir: apps/web/src/pages
 index: apps/web/src/pages/.pi-map.index.md

 ## role
-Contains top-level page components that render the main UI views for the web application, each corresponding to a distinct route and feature area.
+Contains all top-level page components for the web application, serving as the routing endpoints that compose the UI for each distinct feature area.
 ## files
- ConfigProfilesPage.tsx | Renders a configuration profiles management page with responsive desktop/mobile layouts for creating, editing, previewing, and organizing config profiles. | exp: ConfigProfilesPage | dep: react, ../components/data-states, ../hooks/use-mobile-viewport, ../hooks/use-config-profiles, ../components/features/config-profiles/ConfigProfileListSidebar, ../components/features/config-profiles/ConfigProfileEditorPanel, ../components/features/config-profiles/ConfigProfilesMobileView, use-mobile-viewport, use-config-profiles, data-states, ConfigProfileListSidebar, ConfigProfileEditorPanel, ConfigProfilesMobileView
- DashboardPage.test.tsx | Unit tests for the DashboardPage component verifying overview loading and error retry behavior | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./DashboardPage, ../state/sessions, DashboardPage, SessionsProvider
- DashboardPage.tsx | Renders a dashboard homepage that displays workspace overview, active/recent sessions, summary statistics, and polling health checks for running instances. | exp: HomePage | dep: react, react-router-dom, ../api/dashboard, ../api/sessions, ../components/data-states, ../components/features/session/session-list, ../hooks/use-instance-actions, ../state/sessions
- GitHistoryPage.tsx | Renders a Git commit history page with branch selection, commit list with graph visualization, and a detail panel showing commit metadata, stats, and diffs. | exp: GitHistoryPage | dep: react, react-router-dom, ../api/git-repositories, ../components/data-states, ../components/icon, ../hooks/use-async-data
- GitRepositoriesPage.tsx | Displays and manages a project's Git repositories with CRUD operations including listing, creating, navigating to history, and deleting with confirmation | exp: GitRepositoriesPage | dep: react, react-router-dom, ../api/git-repositories, ../components/data-states, ../components/icon, ../components/features/project/repository-create-dialog, ../hooks/use-async-data
- PlaceholderPage.tsx | Exports three simple React page components (PlaceholderPage, NotFoundPage, LoginRedirectPage) for a frontend scaffold. | exp: PlaceholderPage, NotFoundPage, LoginRedirectPage | dep: ../components/icon, React
- ProfilePage.tsx | A React component that renders a responsive profile page with form editing, avatar upload, and save functionality for both mobile and desktop viewports. | exp: ProfilePage | dep: react, ../api/profile, ../components/data-states, ../components/icon, ../components/features/profile/ProfileMobileView, ../state/auth, ../hooks/use-async-data, ../hooks/use-mobile-viewport
- ProjectSettingsPage.tsx | Renders a project settings page with tabbed navigation for general settings, repositories, and members, including project data fetching, editing, and deletion capabilities. | exp: ProjectSettingsPage | dep: react, react-router-dom, ../components/features/settings/settings-tab-layout, ../components/features/project/repositories-settings-tab, ../api/client, ../types
- ProjectsPage.test.tsx | Unit tests for the ProjectsPage component covering loading, empty, error, create, edit, and delete states with API mocking. | dep: @testing-library/react, react-router-dom, vitest, ./ProjectsPage, ../api/projects, ProjectsPage
- ProjectsPage.tsx | Renders a responsive projects management page with separate mobile and desktop layouts, supporting project CRUD operations, repository management, and workspace actions. | exp: ProjectsPage | dep: react, ../components/data-states, ../components/icon, ../hooks/use-mobile-viewport, ../components/features/project/ProjectCard, ../components/features/project/ProjectDialog, ../components/features/project/repository-create-dialog, ../components/features/mobile/mobile-list-view, ../components/features/mobile/mobile-fab, ../hooks/use-projects, ../types, use-mobile-viewport, use-projects, data-states, icon, ProjectCard, ProjectDialog, RepositoryCreateDialog, MobileListView, MobileFAB
- SessionsPage.tsx | Renders a sessions management page that displays, polls health for, and handles CRUD operations on development environment sessions with dirty delete confirmation. | exp: SessionsPage | dep: react, ../api/sessions, ../api/settings, ../components/data-states, ../components/features/session/session-list, ../components/features/session/session-card, ../hooks/use-instance-actions, ../state/sessions
- SettingsPage.tsx | A React settings page component that loads, displays, and manages user configuration with tabbed navigation and nested outlet for child routes. | exp: SettingsPage | dep: react, react-router-dom, ../api/settings, ../components/data-states, ../hooks/use-async-data, ../components/features/settings/GeneralSettingsTab
- SshKeysPage.tsx | React page component for managing SSH keys including generation, listing, signing, verification, and deletion | exp: SSHKeysPage | dep: react-router-dom, ../components/data-states, ../hooks/use-ssh-keys, ../components/features/ssh-keys/SSHKeyCreateForm, ../components/features/ssh-keys/SSHKeyList
- TerminalPage.tsx | Renders a responsive terminal page that switches between mobile and desktop views based on device type, managing terminal sessions and their interactions. | exp: TerminalPage | dep: react, ../hooks/use-terminal-page, ../components/features/terminal/MobileTerminalView, ../components/features/terminal/DesktopTerminalView, useTerminalPage hook, MobileTerminalView, DesktopTerminalView
- ToolWorkshopPage.tsx | Renders a responsive tool workshop page with list and editor views for managing tool types, handling loading/error states and mobile/desktop layouts | exp: ToolWorkshopPage | dep: ../components/data-states, ../hooks/use-mobile-viewport, ../hooks/use-tool-workshop, ../components/features/tool-workshop/ToolTypeListSidebar, ../components/features/tool-workshop/ToolTypeEditorPanel, ../components/features/tool-workshop/ToolWorkshopMobileView, react, use-mobile-viewport, use-tool-workshop, data-states, ToolTypeListSidebar, ToolTypeEditorPanel, ToolWorkshopMobileView
- WorkspaceDetailPage.test.tsx | Tests the WorkspaceDetailPage component rendering and tab switching behavior | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./WorkspaceDetailPage, @testing-library/jest-dom, WorkspaceDetailPage, use-workspaces, use-workspace-files, use-workspace-git, use-workspace-instances, use-mobile-viewport
- WorkspaceDetailPage.tsx | Renders a workspace detail page with tab-based navigation for files, git, tools, and settings panels, with mobile-responsive layout. | exp: func:WorkspaceDetailPage(), call:useParams, call:useState, call:useMobileViewport, call:useWorkspaces, call:workspaces.find | dep: react, react-router-dom, ../hooks/use-workspaces, ../hooks/use-mobile-viewport, ../components/features/workspace/workspace-detail-header, ../components/features/workspace/workspace-tab-bar, ../components/features/workspace/workspace-file-panel, ../components/features/workspace/workspace-git-panel, ../components/features/workspace/workspace-tools-panel, ../components/features/workspace/workspace-settings-panel, use-workspaces, use-mobile-viewport, workspace-detail-header, workspace-tab-bar, workspace-file-panel, workspace-git-panel, workspace-tools-panel, workspace-settings-panel
- WorkspacesPage.tsx | Renders a responsive workspaces management page with mobile and desktop views supporting listing, creating, viewing details, syncing, deleting, and starting tools for workspaces. | exp: func:WorkspacesPage(), call:useMobileViewport, call:useState, call:useWorkspaces, call:useWorkspaceActions, call:actions.delete, call:actions.sync, call:setMobileView, call:refresh, call:setStartWorkspace, call:handleDelete, call:setSelectedWorkspace, call:workspaces.map, call:e.stopPropagation, call:setShowCreate | dep: react, ../components/icon, ../hooks/use-mobile-viewport, ../hooks/use-workspaces, ../hooks/use-workspace-actions, ../components/features/workspace/workspace-card, ../components/features/workspace/workspace-create-form, ../components/features/mobile/mobile-detail-view, ../components/features/mobile/mobile-fab, ../components/features/tool/tool-starter, ../types/workspace
+- ConfigProfilesPage.tsx | Renders a configuration profiles management page with responsive desktop/mobile layouts for listing, editing, creating, and previewing config profiles. | exp: ConfigProfilesPage | dep: react, ../components/data-states, ../hooks/use-mobile-viewport, ../hooks/use-config-profiles, ../components/features/config-profiles/ConfigProfileListSidebar, ../components/features/config-profiles/ConfigProfileEditorPanel, ../components/features/config-profiles/ConfigProfilesMobileView, use-mobile-viewport, use-config-profiles, data-states, ConfigProfileListSidebar, ConfigProfileEditorPanel, ConfigProfilesMobileView
+- DashboardPage.test.tsx | Tests the DashboardPage (HomePage) component's rendering, loading states, error handling, and retry functionality. | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./DashboardPage, ../state/sessions, @testing-library/jest-dom, ../api/dashboard, ../api/sessions, ../api/projects, ../api/git-repositories, ../api/tool-types
+- DashboardPage.tsx | Renders a workspace dashboard page that displays summary statistics, active sessions with health polling, and recent sessions with management actions. | exp: HomePage | dep: react, react-router-dom, ../api/dashboard, ../api/sessions, ../components/data-states, ../components/features/session/session-list, ../hooks/use-instance-actions, ../state/sessions
+- GitHistoryPage.tsx | Renders a Git commit history page with branch selection, commit list with graph visualization, and a detail panel showing commit metadata, stats, and diff. | exp: GitHistoryPage | dep: react, react-router-dom, ../api/git-repositories, ../components/data-states, ../components/icon, ../hooks/use-async-data
+- GitRepositoriesPage.tsx | Displays and manages a list of Git repositories for a project with CRUD operations, loading states, and navigation to history. | exp: GitRepositoriesPage | dep: react, react-router-dom, ../api/git-repositories, ../components/data-states, ../components/icon, ../components/features/project/repository-create-dialog, ../hooks/use-async-data
+- PlaceholderPage.tsx | Provides three reusable React page components for placeholder content, 404 errors, and login redirects with external authentication. | exp: PlaceholderPage, NotFoundPage, LoginRedirectPage | dep: ../components/icon, react
+- ProfilePage.tsx | A React component that renders a responsive profile page allowing users to view and edit their profile information (name, email) and upload an avatar, with separate mobile and desktop layouts. | exp: ProfilePage | dep: react, ../api/profile, ../components/data-states, ../components/icon, ../components/features/profile/ProfileMobileView, ../state/auth, ../hooks/use-async-data, ../hooks/use-mobile-viewport
+- ProjectSettingsPage.tsx | Renders a project settings page with tabbed navigation for general settings, repositories, and members, including project data fetching and CRUD operations. | exp: ProjectSettingsPage | dep: react, react-router-dom, ../components/features/settings/settings-tab-layout, ../components/features/project/repositories-settings-tab, ../api/client, ../types
+- ProjectsPage.test.tsx | Unit tests for the ProjectsPage component covering loading, empty, error, create, edit, and delete project flows | dep: @testing-library/react, react-router-dom, vitest, ./ProjectsPage, ../api/projects
+- ProjectsPage.tsx | Renders a responsive projects management page with separate mobile and desktop views supporting CRUD operations, repository management, and workspace actions. | exp: ProjectsPage | dep: react, ../components/data-states, ../components/icon, ../hooks/use-mobile-viewport, ../components/features/project/ProjectCard, ../components/features/project/ProjectListItem, ../components/features/project/ProjectDialog, ../components/features/project/repository-create-dialog, ../components/features/mobile/mobile-list-view, ../components/features/mobile/mobile-fab, ../hooks/use-projects, ../state/sessions, ../types
+- SessionsPage.tsx | A React page component that displays and manages user sessions with health polling, last session tracking, and dirty delete confirmation handling. | exp: SessionsPage | dep: react, ../api/sessions, ../api/settings, ../components/data-states, ../components/features/session/session-list, ../components/features/session/session-card, ../hooks/use-instance-actions, ../state/sessions
+- SettingsPage.tsx | A React settings page component that loads user configuration, manages tab-based navigation, and provides configuration state to child routes via Outlet context. | exp: SettingsPage | dep: react, react-router-dom, ../api/settings, ../components/data-states, ../hooks/use-async-data, ../components/features/settings/GeneralSettingsTab
+- SshKeysPage.tsx | Renders a settings page for managing SSH keys including generation, listing, signing, verification, and deletion operations. | exp: SSHKeysPage | dep: react-router-dom, ../components/data-states, ../hooks/use-ssh-keys, ../components/features/ssh-keys/SSHKeyCreateForm, ../components/features/ssh-keys/SSHKeyList
+- TerminalPage.tsx | Renders a responsive terminal page that conditionally displays mobile or desktop terminal views based on device type, managing terminal sessions and their interactions through a custom hook. | exp: TerminalPage | dep: react, ../hooks/use-terminal-page, ../components/features/terminal/MobileTerminalView, ../components/features/terminal/DesktopTerminalView
+- ToolWorkshopPage.tsx | Renders a responsive tool workshop page for managing tool types with desktop sidebar/editor layout and mobile view switching | exp: ToolWorkshopPage | dep: ../components/data-states, ../hooks/use-mobile-viewport, ../hooks/use-tool-workshop, ../components/features/tool-workshop/ToolTypeListSidebar, ../components/features/tool-workshop/ToolTypeEditorPanel, ../components/features/tool-workshop/ToolWorkshopMobileView, react, use-mobile-viewport, use-tool-workshop, data-states, ToolTypeListSidebar, ToolTypeEditorPanel, ToolWorkshopMobileView
+- WorkspaceDetailPage.test.tsx | Tests the WorkspaceDetailPage component's rendering and tab switching behavior | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./WorkspaceDetailPage, @testing-library/jest-dom, WorkspaceDetailPage, use-workspaces, use-workspace-files, use-workspace-git, use-workspace-instances, use-mobile-viewport
+- WorkspaceDetailPage.tsx | Renders a workspace detail page with tabbed navigation for files, git, tools, and settings panels, with mobile-responsive layout. | exp: func:WorkspaceDetailPage(), call:useParams, call:useState, call:useMobileViewport, call:useWorkspaces, call:workspaces.find | dep: react, react-router-dom, ../hooks/use-workspaces, ../hooks/use-mobile-viewport, ../components/features/workspace/workspace-detail-header, ../components/features/workspace/workspace-tab-bar, ../components/features/workspace/workspace-file-panel, ../components/features/workspace/workspace-git-panel, ../components/features/workspace/workspace-tools-panel, ../components/features/workspace/workspace-settings-panel, use-workspaces, use-mobile-viewport, workspace-detail-header, workspace-tab-bar, workspace-mobile-tab-bar, workspace-file-panel, workspace-git-panel, workspace-tools-panel, workspace-settings-panel
+- WorkspacesPage.tsx | Renders a responsive workspaces management page with separate mobile and desktop layouts for listing, creating, viewing, and managing workspaces. | exp: func:WorkspacesPage(), call:useMobileViewport, call:useState, call:useWorkspaces, call:useWorkspaceActions, call:actions.delete, call:actions.sync, call:setMobileView, call:refresh, call:setStartWorkspace, call:handleDelete, call:setSelectedWorkspace, call:workspaces.map, call:e.stopPropagation, call:setShowCreate | dep: react, ../components/icon, ../hooks/use-mobile-viewport, ../hooks/use-workspaces, ../hooks/use-workspace-actions, ../components/features/workspace/workspace-card, ../components/features/workspace/workspace-create-form, ../components/features/mobile/mobile-detail-view, ../components/features/mobile/mobile-fab, ../components/features/tool/tool-starter, ../types/workspace
 ## arch
-Route-based page organization with responsive mobile/desktop layout patterns, tabbed navigation for complex pages, polling/health-check mechanisms for live data, and CRUD operations with loading/error/empty states throughout.
+Follows a page-based routing architecture with responsive mobile/desktop split patterns, tabbed navigation for complex pages, and feature-specific data fetching with loading/error states; most pages use custom hooks for business logic and separate layout components for device-specific rendering.
 ## tags
-page, components, workspace, features, mobile, react, hooks, settings
+page, components, workspace, features, mobile, react, settings, hooks
 ## symbols
 - WorkspaceDetailPage
 - WorkspacesPage
@@ -2,7 +2,7 @@
 dir: apps/web/src/state

 ## role
-Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, and user feedback.
+Centralized React state management package providing context-based global state for authentication, real-time events, notifications, sessions, and UI feedback across the web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,17 +4,17 @@ dir: apps/web/src/state
 index: apps/web/src/state/.pi-map.index.md

 ## role
-Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, and user feedback.
+Centralized React state management package providing context-based global state for authentication, real-time events, notifications, sessions, and UI feedback across the web application.
 ## files
- auth.tsx | Provides React authentication context for managing user session state with login status, user data, and session refresh/logout operations. | exp: AuthProvider, useAuth | dep: react, ../api/client, ../types
- events.tsx | Creates a React context provider for real-time event data with connection status and reconnection tracking | exp: func:EventProvider({ children }: { children: React.ReactNode }), call:useEvents, call:useMemo, func:useEventContext(), call:useContext | dep: react, ../hooks/use-events, ../types/events
- notifications.tsx | Provides a React context provider that manages notification state with optimistic updates, polling, and dropdown-aware fetching. | exp: NotificationContextValue, NotificationContext, func:NotificationProvider({ children, }: { children: React.ReactNode; }), call:useState, call:useRef, call:useCallback, call:getUnreadCount, call:setUnreadCount, call:clearInterval, call:console.error, call:setIsLoading, call:getNotifications, call:setNotifications, call:fetchUnreadCount, call:setInterval, call:fetchList, call:useEffect, call:stopPolling, call:startPolling, call:document.addEventListener, call:document.removeEventListener, call:currentNotifications.find, call:currentNotifications.map, call:new Date().toISOString, call:Math.max, call:setError, call:markNotificationRead, call:markAllNotificationsRead, call:currentNotifications.filter, call:dismissNotification, call:clearAllNotifications | dep: react, ../api/notifications, React
- sessions.tsx | Provides a React context that manages user sessions state with server polling, local CRUD operations, and loading/error handling. | exp: SessionsContextType, SessionsProvider, useSessions | dep: react, ../api/sessions
- toast.tsx | Implements a React toast notification system with context-based state management, auto-dismiss timers, and imperative API shortcuts. | exp: ToastSeverity, ToastItem, toast, func:ToastProvider({ children }: { children: React.ReactNode }), call:useState, call:useRef, call:useCallback, call:setToasts, call:prev.filter, call:timersRef.current.get, call:clearTimeout, call:timersRef.current.delete, call:Date.now, call:setTimeout, call:removeToast, call:timersRef.current.set, call:useEffect, call:addToast, func:useToast(), call:useContext, raise:Error | dep: react, React
+- auth.tsx | Provides React authentication context with session state management, user data, and auth operations (refresh/logout). | exp: AuthProvider, useAuth | dep: react, ../api/client, ../types
+- events.tsx | Creates a React context provider for real-time instance events with connection status and reconnect tracking | exp: func:EventProvider({ children }: { children: React.ReactNode }), call:useEvents, call:useMemo, func:useEventContext(), call:useContext | dep: react, ../hooks/use-events, ../types/events
+- notifications.tsx | Provides a React context that manages notification state with optimistic updates, polling, and visibility-aware fetching for a notification dropdown UI. | exp: NotificationContextValue, NotificationContext, func:NotificationProvider({ children, }: { children: React.ReactNode; }), call:useState, call:useRef, call:useCallback, call:getUnreadCount, call:setUnreadCount, call:clearInterval, call:console.error, call:setIsLoading, call:getNotifications, call:setNotifications, call:fetchUnreadCount, call:setInterval, call:fetchList, call:useEffect, call:stopPolling, call:startPolling, call:document.addEventListener, call:document.removeEventListener, call:currentNotifications.find, call:currentNotifications.map, call:new Date().toISOString, call:Math.max, call:setError, call:markNotificationRead, call:markAllNotificationsRead, call:currentNotifications.filter, call:dismissNotification, call:clearAllNotifications | dep: react, ../api/notifications, React
+- sessions.tsx | Provides a React context for managing user sessions with server polling, local state updates, and CRUD operations. | exp: SessionsContextType, SessionsProvider, useSessions | dep: react, ../api/sessions
+- toast.tsx | Provides a React toast notification system with context-based state management, auto-dismiss timers, and imperative API access. | exp: ToastSeverity, ToastItem, toast, func:ToastProvider({ children }: { children: React.ReactNode }), call:useState, call:useRef, call:useCallback, call:setToasts, call:prev.filter, call:timersRef.current.get, call:clearTimeout, call:timersRef.current.delete, call:Date.now, call:setTimeout, call:removeToast, call:timersRef.current.set, call:useEffect, call:addToast, func:useToast(), call:useContext, raise:Error | dep: react, React
 ## arch
-React Context API pattern with separate providers per domain, combining optimistic updates, server polling, event-driven state synchronization, and imperative APIs for cross-cutting concerns.
+React Context pattern with provider/consumer model, each module implementing independent singleton contexts with imperative APIs, optimistic updates, polling-based synchronization, and side-effect management via useEffect hooks.
 ## tags
-call:use, context, toast, provider, react, call:set, notification
+call:use, context, toast, call:set, notification, react, provider, notifications
 ## symbols
 - EventProvider
 - useEventContext
@@ -23,6 +23,7 @@ call:use, context, toast, provider, react, call:set, notification
 - useToast
 - AuthProvider
 - useAuth
+- call:useEvents
 ## workflows
 - change state behavior
  read: auth.tsx, events.tsx, notifications.tsx
@@ -2,7 +2,7 @@
 dir: apps/web/src/styles

 ## role
-Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, utility classes, and component-specific styles.
+Centralizes the visual design system and styling infrastructure for the web application, providing theme-aware CSS tokens, global styles, component patterns, and utility classes used across the frontend.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,16 +4,16 @@ dir: apps/web/src/styles
 index: apps/web/src/styles/.pi-map.index.md

 ## role
-Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, utility classes, and component-specific styles.
+Centralizes the visual design system and styling infrastructure for the web application, providing theme-aware CSS tokens, global styles, component patterns, and utility classes used across the frontend.
 ## files
- global.css | Defines global CSS styles for a web application shell layout, navigation, cards, forms, dialogs, settings pages, and responsive design patterns. | dep: CSS custom properties (CSS variables: --border, --panel, --brand, --muted, --ink, --bg, --danger, --success, --warning, --font-size-xs, --font-size-sm, --space-2, --space-3, --space-4, --space-5)
- syntax-highlight.css | Stylesheet for a syntax highlighting component with toolbar, line numbers, code display, and Prism.js theme integration | dep: Prism.js
- tokens.css | Defines a comprehensive CSS design token system with light/dark themes, spacing scales, breakpoints, and fluid typography for a web application.
- utilities.css | Provides a comprehensive CSS utility system for responsive layouts, terminal interfaces, and UI components with mobile-first design patterns. | dep: CSS custom properties (--space-*, --border, --bg, --muted, --success, --text, --brand, --danger, --danger-light), xterm.js (terminal library)
+- global.css | Global CSS stylesheet defining the visual design system, layout structure, and component styles for a web application shell with responsive navigation, cards, forms, dialogs, and settings pages.
+- syntax-highlight.css | Stylesheet providing CSS for a syntax highlighting component with line numbers, toolbar, and Prism.js token color integration. | dep: CSS custom properties (var(--panel), var(--border), var(--bg), var(--muted), var(--ink), var(--brand)), Prism.js (for token classes)
+- tokens.css | Defines a comprehensive CSS design system with custom properties for colors, spacing, typography, shadows, and layout tokens supporting both light and dark themes.
+- utilities.css | Provides a comprehensive CSS utility framework with responsive layout, typography, spacing, and component-specific styles for a web application including terminal, session management, and form interfaces. | dep: CSS custom properties (variables), xterm.js (terminal integration), webkit-box (multiline truncation)
 ## arch
-Token-driven CSS architecture using CSS custom properties for themeable design system with mobile-first responsive utilities, separate component-specific stylesheets, and light/dark mode support.
+CSS custom property (variable) driven design system with theme switching (light/dark), utility-first CSS patterns, modular separation of concerns (tokens/globals/components/utilities), and responsive design with mobile-first breakpoints.
 ## tags
-space, global, css, design, danger, syntax, defines, web
+var(, css, global, layout, component, syntax, tokens, stylesheet
 ## symbols
 -
 ## workflows
@@ -2,7 +2,7 @@
 dir: apps/web/src/styles/pages

 ## role
-Contains page-specific CSS stylesheets for individual application views in the web frontend, providing scoped styling for distinct feature areas.
+Contains page-specific CSS stylesheets for individual application views in the web frontend, providing scoped visual styling for distinct feature pages and their UI components.
 ## parent
 index: apps/web/src/styles/.pi-map.index.md
 map: apps/web/src/styles/.pi-map.md
@@ -4,18 +4,18 @@ dir: apps/web/src/styles/pages
 index: apps/web/src/styles/pages/.pi-map.index.md

 ## role
-Contains page-specific CSS stylesheets for individual application views in the web frontend, providing scoped styling for distinct feature areas.
+Contains page-specific CSS stylesheets for individual application views in the web frontend, providing scoped visual styling for distinct feature pages and their UI components.
 ## files
- git-history.css | Stylesheet for a Git history visualization page with commit list, branch selector, and detail panel layout | dep: CSS custom properties (var(--border), var(--panel), var(--ink), var(--brand), var(--muted))
- projects.css | Stylesheet for a projects page UI featuring expandable project toggles, repository listings, workspace grids, and repository creation radio controls. | dep: CSS custom properties (variables)
- sessions.css | Stylesheet for session management UI components including cards, dropdowns, forms, and responsive mobile layouts. | dep: CSS custom properties/variables (var(--border), var(--panel), var(--text), var(--space-*), var(--danger), var(--color-border))
- ssh-keys.css | Styles a responsive SSH key list component that stacks vertically on mobile and switches to horizontal layout on larger screens | dep: CSS custom properties (var(--space-3), var(--space-2), var(--space-4), var(--bg), var(--border))
- workspace-detail.css | Stylesheet for a workspace detail page with tabbed interface including files, git, tools, and settings views, plus a workspace creation form | dep: CSS custom properties (variables for colors, spacing, typography)
- workspaces.css | Stylesheet for a workspaces management page featuring responsive grid layout, workspace cards with status badges, instance chips, and mobile adaptations. | dep: CSS custom properties (design tokens: --space-*, --border, --panel, --brand, --ink, --muted, --bg, --success, --warning, --danger, --font-size-*)
+- git-history.css | Stylesheet for a Git history visualization page with commit list, graph display, and detail panel. | dep: CSS custom properties (var(--border), var(--radius-md), var(--panel), var(--ink), var(--brand), var(--muted), var(--radius-sm), var(--radius-lg))
+- projects.css | Stylesheet for a projects management UI page with repositories, workspaces, and tool links | dep: CSS custom properties (variables)
+- sessions.css | Stylesheet for a sessions management UI component with responsive mobile layout, dropdown menus, and form elements | dep: CSS custom properties (var(--border), var(--panel), var(--text), var(--space-*), var(--danger), var(--bg)), CSS animations
+- ssh-keys.css | Provides responsive CSS styling for an SSH key list component, stacking vertically on mobile and switching to horizontal layout on larger screens | dep: CSS custom properties (var(--space-3), var(--space-2), var(--space-4), var(--bg), var(--radius-md))
+- workspace-detail.css | Stylesheet for a workspace detail page with responsive tabs, file browser, git integration, tools, and settings UI | dep: CSS custom properties (design tokens), IBM Plex Mono font
+- workspaces.css | Stylesheet for a workspaces page featuring a responsive grid of workspace cards with status badges, instance chips, and action buttons.
 ## arch
-Modular CSS architecture with page-level style separation, responsive design patterns using media queries for mobile adaptation, and component-scoped styling organized by feature domain rather than shared component library.
+Modular page-scoped CSS architecture with responsive design patterns (mobile-first breakpoints, flex/grid layouts), component-oriented styling for specific UI elements (cards, lists, forms, tabs), and status-driven visual states (badges, chips).
 ## tags
-var(, workspace, stylesheet, space, git, page, detail, history
+var(, stylesheet, git, page, detail, radius, workspaces, responsive
 ## symbols
 -
 ## workflows
@@ -2,7 +2,7 @@
 dir: apps/web/src/test

 ## role
-Provides shared testing infrastructure and configuration for the web application's test suite
+Provides testing infrastructure and configuration for the web application
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/web/src/test
 index: apps/web/src/test/.pi-map.index.md

 ## role
-Provides shared testing infrastructure and configuration for the web application's test suite
+Provides testing infrastructure and configuration for the web application
 ## files
- setup.ts | Configures Vitest testing environment with Jest DOM matchers for enhanced DOM assertions | dep: @testing-library/jest-dom/vitest
+- setup.ts | Imports jest-dom matchers for Vitest to enable DOM assertion methods in tests | dep: @testing-library/jest-dom/vitest
 ## arch
-Minimal utility layer using Vitest with Jest DOM matchers for browser-like DOM assertion capabilities
+Minimal test setup layer using Vitest with jest-dom integration for DOM assertions
 ## tags
-dom, vitest, jest, setup, configures, testing, environment, matchers
+dom, jest, vitest, setup, matchers, enable, assertion, methods
 ## symbols
 -
 ## workflows
@@ -2,7 +2,7 @@
 dir: apps/web/src/types

 ## role
-Provides shared TypeScript type definitions for event-driven communication and workspace management across the web application.
+Provides shared TypeScript type definitions for event-driven and workspace-related data structures across the web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,12 +4,12 @@ dir: apps/web/src/types
 index: apps/web/src/types/.pi-map.index.md

 ## role
-Provides shared TypeScript type definitions for event-driven communication and workspace management across the web application.
+Provides shared TypeScript type definitions for event-driven and workspace-related data structures across the web application.
 ## files
- events.ts | Defines TypeScript interfaces for instance event metadata and payload structures used in event-driven system communication. | exp: InstanceEventMetadata, InstanceEventPayload
+- events.ts | Defines TypeScript interfaces for instance event metadata and payload structures used in an event-driven system. | exp: InstanceEventMetadata, InstanceEventPayload
 - workspace.ts | Defines TypeScript interfaces for workspace data models, requests, and sync results in a workspace management feature. | exp: Workspace, CreateWorkspaceRequest, SyncResult
 ## arch
-Pure type declaration layer using TypeScript interfaces for compile-time contracts, with no runtime logic or dependencies.
+Pure type declaration package using interface-based contracts with no runtime logic, following a centralized type repository pattern for cross-module consistency.
 ## tags
 workspace, event, instance, metadata, payload, sync, defines, typescript
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/utils

 ## role
-Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative time formatting across the web application.
+Provides shared utility functions for error handling, icons, syntax highlighting, session management, and time formatting across the web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -12,6 +12,7 @@ map: apps/web/src/.pi-map.md
 - errors.ts
 - icons.ts
 - language.ts
+- open-session.ts
 - time.ts
 ## links
 index: apps/web/src/utils/.pi-map.index.md
@@ -4,25 +4,26 @@ dir: apps/web/src/utils
 index: apps/web/src/utils/.pi-map.index.md

 ## role
-Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative time formatting across the web application.
+Provides shared utility functions for error handling, icons, syntax highlighting, session management, and time formatting across the web application.
 ## files
- errors.ts | Extracts a human-readable error message from an unknown error object, specifically handling axios-style errors with string or array detail fields | exp: extractErrorMessage
- icons.ts | Re-exports the IconName type from the icon component for external consumption | dep: ../components/icon
- language.ts | Maps file extensions to Prism.js language identifiers and provides utilities for syntax highlighting with lazy language loading. | exp: detectLanguage, highlightCode, loadLanguage | dep: prismjs
- time.ts | Formats a date string into a human-readable relative time string (e.g., "2h ago", "3d ago") | exp: func:formatRelativeTime(dateStr: string) → string, call:Math.max, call:Math.floor, call:now.getTime, call:date.getTime
+- errors.ts | Extracts human-readable error messages from API errors, handling Axios-style response structures with string or array detail formats | exp: extractErrorMessage
+- icons.ts | Re-exports the IconName type from the icon component for external use. | dep: ../components/icon
+- language.ts | Maps file extensions to Prism.js language identifiers and provides utilities for syntax highlighting with dynamic language loading. | exp: detectLanguage, highlightCode, loadLanguage | dep: prismjs
+- open-session.ts | Opens a browser tab/window for a given session, reusing existing tabs if available | exp: func:openSession(session: Session) → void, call:tabRefs.get, call:existing.focus, call:session.tool_type_interfaces?.includes, call:window.open, call:tabRefs.set | dep: ../api/sessions, Session type from ../api/sessions
+- time.ts | Formats a date string as a human-readable relative time string (e.g., "2h ago", "3d ago") | exp: func:formatRelativeTime(dateStr: string) → string, call:Math.max, call:Math.floor, call:now.getTime, call:date.getTime
 ## arch
-Lightweight functional utilities organized by domain concern with no internal dependencies, using pattern matching (error types), lazy loading (language imports), and pure string/date transformations.
+Lightweight functional utilities with no internal dependencies between files, using TypeScript type exports and dynamic imports for code splitting.
 ## tags
-time, language, error, message, errors, string, relative, human
+time, language, session, open, call:tab, error, api, errors
 ## symbols
+- openSession
 - formatRelativeTime
 - extractErrorMessage
 - detectLanguage
 - highlightCode
 - loadLanguage
- call:Math.max
- call:Math.floor
- call:now.getTime
+- call:tabRefs.get
+- call:existing.focus
 ## workflows
 - change utils behavior
  read: errors.ts, icons.ts, language.ts