chore: patch project maps after stale backend test cleanup

Regenerate .pi-map*.md artifacts for source changes in: - apps/api/src/api/tool/tool_types_validation.py - apps/api/src/schemas/tool/tool_type.py - apps/api/tests/integration/test_tool_types_api_extended.py - and all affected test files from backend-frontend refactoring cleanup
2026-06-12 20:36:31 +00:00
parent c6073fe9d2
commit 7ef8b0eb36
188 changed files with 348 additions and 361 deletions
@@ -16,7 +16,7 @@ Frontend web application providing a React-based UI with code editing, terminal,
 - 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
 ## arch
-Modern React SPA built with Vite and TypeScript, served by nginx in a containerized multi-stage Docker build, using Vitest for testing and ESLint for code quality.
+Modern React SPA built with Vite and TypeScript, containerized via multi-stage Docker with nginx serving, featuring client-side routing and optimized static asset delivery.
 ## tags
 react, eslint, vite, typescript, dom, application, nginx, web
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/public

 ## role
-Static HTML prototype for UI/UX validation and stakeholder review of the workspace dashboard design before React implementation.
+Static frontend assets serving a standalone HTML preview/demo of the workspace dashboard UI without requiring the full application runtime.
 ## parent
 index: apps/web/.pi-map.index.md
 map: apps/web/.pi-map.md
@@ -4,11 +4,11 @@ dir: apps/web/public
 index: apps/web/public/.pi-map.index.md

 ## role
-Static HTML prototype for UI/UX validation and stakeholder review of the workspace dashboard design before React implementation.
+Static frontend assets serving a standalone HTML preview/demo of the workspace 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)
 ## arch
-Vanilla HTML/CSS mockup with JavaScript-driven view switching, using CSS Grid/Flexbox layout and class-based DOM manipulation for interactive state transitions.
+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.
 ## tags
 preview, static, html, css, mockup, headquarter, workspace, dashboard
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src

 ## role
-Frontend web application entry point and core infrastructure for a React-based collaborative development platform.
+Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions.
 ## parent
 index: apps/web/.pi-map.index.md
 map: apps/web/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/web/src
 index: apps/web/src/.pi-map.index.md

 ## role
-Frontend web application entry point and core infrastructure for a React-based collaborative development platform.
+Entry point and core infrastructure for a React web application handling routing, authentication, and shared type definitions.
 ## 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
 ## arch
-Modern React SPA with declarative routing (React Router), nested layout composition, protected route guards via authentication context, and centralized TypeScript domain modeling for multi-tenant workspace/project entities.
+Provider pattern wrapping React Router with nested route layouts, protected route guards via authentication/session providers, and centralized TypeScript type definitions for domain models.
 ## tags
 pages, styles, css, router, react, session, dom, project
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/api

 ## role
-Provides typed HTTP API client modules and interfaces for all backend communication in the web application, covering domains from authentication and user management to workspaces, tools, git, terminals, and real-time events.
+Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/api
 index: apps/web/src/api/.pi-map.index.md

 ## role
-Provides typed HTTP API client modules and interfaces for all backend communication in the web application, covering domains from authentication and user management to workspaces, tools, git, terminals, and real-time events.
+Provides typed HTTP API client modules for all backend communication in the web application, organized by domain entity.
 ## 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
@@ -14,7 +14,7 @@ Provides typed HTTP API client modules and interfaces for all backend communicat
 - 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 API client functions for managing cloud development tool instances and user sessions via REST endpoints. | 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, cloneMode: string, branch: string, newBranch: string, configProfileId: string, sshKeyIds: string[], workspaceId: 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
+- 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
@@ -26,9 +26,9 @@ Provides typed HTTP API client modules and interfaces for all backend communicat
 - 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
 ## arch
-Modular facade pattern with a centralized Axios client instance (client.ts) featuring cross-cutting concerns (auth redirect, retry logic), with each domain exposing isolated typed API function modules that map to REST endpoints; includes SSE for real-time events and mirrors backend domain boundaries.
+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.
 ## tags
-call:api, tool, client.post, create, git, profile, client, get
+call:api, tool, client.post, create, git, profile, get, client
 ## symbols
 - createEventSource
 - probeEventStreamStatus
@@ -2,7 +2,7 @@
 dir: apps/web/src/components

 ## role
-Provides reusable, shared React UI components and utilities for building the web application's interface, including layout shells, data display states, iconography, routing guards, and feedback mechanisms.
+Reusable React UI components and authentication guards for the web application's frontend interface.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/components
 index: apps/web/src/components/.pi-map.index.md

 ## role
-Provides reusable, shared React UI components and utilities for building the web application's interface, including layout shells, data display states, iconography, routing guards, and feedback mechanisms.
+Reusable React UI components and authentication guards for the web application's frontend interface.
 ## files
 - app-shell.tsx | Renders the main application shell layout with navigation, session management, and responsive mobile/desktop views for a React Router-based app. | 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, ../state/session-operations, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./features/session/session-progress-panel, ./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
@@ -16,7 +16,7 @@ Provides reusable, shared React UI components and utilities for building the web
 - 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
 ## arch
-Component-based architecture with functional React patterns, emphasizing composability, type safety, and separation of concerns through presentational components, custom hooks integration, and utility modules for cross-cutting concerns like notifications and routing protection.
+Component-based React architecture using functional components with hooks, centralized type-safe utilities (icons, data states), composition patterns for layout (app-shell), and higher-order route protection for auth gating.
 ## tags
 toast, state, react, icon, code, event, editor, protected
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features

 ## role
-Reusable React components implementing specific business functionality and UI features for the web application.
+Contains reusable UI components that implement specific business features and user-facing functionality across 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
-Reusable React components implementing specific business functionality and UI features for the web application.
+Contains reusable UI components that implement specific business features and user-facing functionality across the web application.
 ## files
 ## arch
-Feature-based component organization with domain-specific subdirectories, likely combining presentational and container patterns with hooks for state management.
+Feature-based component organization with domain-specific groupings, likely using composition patterns, container/presentational separation, and integration with hooks/state management for feature logic.
 ## tags
 -
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/config-profiles

 ## role
-Provides a complete UI subsystem for managing configuration profiles through list, edit, and mobile-responsive views with CRUD operations.
+Provides a complete UI subsystem for managing configuration profiles with desktop and mobile views, supporting CRUD operations, profile relationships, and advanced configuration options.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/web/src/components/features/config-profiles
 index: apps/web/src/components/features/config-profiles/.pi-map.index.md

 ## role
-Provides a complete UI subsystem for managing configuration profiles through list, edit, and mobile-responsive views with CRUD operations.
+Provides a complete UI subsystem for managing configuration profiles with desktop and mobile views, supporting CRUD operations, profile relationships, and advanced configuration options.
 ## 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 CRUD interface for managing configuration profiles with list, detail, and edit views. | exp: ConfigProfilesMobileView | dep: ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../../icon, ../../../api/config-profiles, MobileListView, MobileDetailView, MobileEditView, MobileFAB, Icon, ConfigProfile, CreateConfigProfileRequest
 ## arch
-Compound component pattern with panel/sidebar/mobile view variants, form-based editor with nested array/object state management, and responsive design splitting desktop (sidebar+panel) from mobile (routed views).
+Compound component architecture with panel/sidebar split for desktop, dedicated mobile view with state-driven routing, shared state management across list/editor views, and form-based configuration with nested array/object handling for includes, env vars, files, and mounts.
 ## tags
 config, mobile, profiles, profile, view, editor, icon, list
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/git

 ## role
-React components providing Git repository management UI including commit, merge, branch operations, and file editing with syntax highlighting.
+Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -10,16 +10,13 @@ map: apps/web/src/components/features/.pi-map.md
 -
 ## files
 - commit-dialog.tsx
- commit-panel.tsx
- file-editor.tsx
 - git-mount-editor.tsx
- git-toolbar.tsx
 - merge-dialog.tsx
 ## links
 index: apps/web/src/components/features/git/.pi-map.index.md
 map: apps/web/src/components/features/git/.pi-map.md
 ## workflows
 - change git behavior
-  read: commit-dialog.tsx, commit-panel.tsx, file-editor.tsx
+  read: commit-dialog.tsx, git-mount-editor.tsx, merge-dialog.tsx
 ## dirty
 -
@@ -4,27 +4,21 @@ dir: apps/web/src/components/features/git
 index: apps/web/src/components/features/git/.pi-map.index.md

 ## role
-React components providing Git repository management UI including commit, merge, branch operations, and file editing with syntax highlighting.
+Provides React UI components for Git repository operations including commit, merge, and mount configuration workflows.
 ## 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
- commit-panel.tsx | React component that displays git repository changes and provides a form to commit them with a message | exp: CommitPanel | dep: react, ../../../api/git-repositories, api/git-repositories
- file-editor.tsx | A React component that displays and edits repository files with view/edit modes, syntax highlighting, and git commit functionality | exp: FileEditor | dep: react, react-router-dom, ../../../api/client, ../../../state/auth, ../../code-editor, ./commit-dialog, ../../icon, ../../syntax-highlighter, ../../../utils/language, apiClient, useAuth, CodeEditor, CommitDialog, Icon, SyntaxHighlighter, detectLanguage
 - 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
- git-toolbar.tsx | React component providing a toolbar UI for Git repository operations including branch management, fetch/pull/push, merge, and status display with polling. | exp: GitToolbar | dep: react, ../../../api/git-repositories, ../../icon, ./merge-dialog
 - 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
 ## arch
-Feature-based component architecture with modular dialog/panel pattern, form-driven state management, and optimistic UI with polling for async git operations.
+Uses modal dialog pattern with form state management, loading/error/success state handling, and controlled inputs for Git-specific operations.
 ## tags
-git, react, commit, dialog, icon, editor, api, merge
+dialog, git, react, commit, icon, mount, merge, editor
 ## symbols
 - CommitDialog
- CommitPanel
- FileEditor
 - GitMountEditor
- GitToolbar
 - MergeDialog
 ## workflows
 - change git behavior
-  read: commit-dialog.tsx, commit-panel.tsx, file-editor.tsx
+  read: commit-dialog.tsx, git-mount-editor.tsx, merge-dialog.tsx
 ## dirty
 -
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/mobile

 ## role
-Provides a complete set of mobile-optimized UI components for building responsive, touch-friendly interfaces across list views, detail views, forms, navigation, modals, and specialized terminal experiences.
+Provides mobile-optimized UI components for a responsive web application, covering navigation, lists, detail views, forms, modals, and specialized terminal interfaces.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/components/features/mobile
 index: apps/web/src/components/features/mobile/.pi-map.index.md

 ## role
-Provides a complete set of mobile-optimized UI components for building responsive, touch-friendly interfaces across list views, detail views, forms, navigation, modals, and specialized terminal experiences.
+Provides mobile-optimized UI components for a responsive web application, covering navigation, lists, detail views, forms, modals, and specialized terminal interfaces.
 ## 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 button, title, edit/delete actions) and a field list supporting multiple value types (text, code, JSON, boolean). | exp: MobileDetailView | dep: ../../icon, react
@@ -16,7 +16,7 @@ Provides a complete set of mobile-optimized UI components for building responsiv
 - 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
 ## arch
-Follows a feature-based component architecture with consistent mobile-first design patterns including bottom sheets, floating action buttons, auto-hiding headers, virtual keyboard handling, and contextual action menus; each component is self-contained with configurable props for titles, actions, field types, and click handlers, suggesting a reusable component library pattern rather than business-logic containers.
+Feature-based component organization with compound mobile UI patterns (action sheets, FABs, bottom sheets, auto-hiding headers) that mirror native mobile app paradigms, using configurable props for customization and likely React Context or hooks for keyboard/virtual terminal state management.
 ## tags
 mobile, terminal, view, icon, header, react, sheet, action
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/notification

 ## role
-Provides notification UI components and event-to-toast bridging infrastructure for user-facing alerts and notifications.
+Provides notification UI components and event-to-toast bridging logic for the web application.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,7 +4,7 @@ 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 infrastructure for user-facing alerts and notifications.
+Provides notification UI components and event-to-toast bridging logic for the web application.
 ## 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
@@ -13,7 +13,7 @@ Provides notification UI components and event-to-toast bridging infrastructure f
 - 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
 ## arch
-React component-based architecture with event-driven toast bridging, responsive portal-based dropdowns, and severity-based conditional rendering with comprehensive Vitest test coverage.
+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.
 ## tags
 event, notification, call:use, toast, notifications, listener, react, item
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/project

 ## role
-Provides React components for project management UI including project cards, creation/editing dialogs, and repository settings with CRUD operations.
+Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,16 +4,16 @@ dir: apps/web/src/components/features/project
 index: apps/web/src/components/features/project/.pi-map.index.md

 ## role
-Provides React components for project management UI including project cards, creation/editing dialogs, and repository settings with CRUD operations.
+Provides UI components for managing projects and their Git repositories, including cards, dialogs, and settings tabs with CRUD operations.
 ## 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, @testing-library/jest-dom, ProjectCard, types
+- 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
 ## arch
-Feature-based component architecture with compound component patterns (card + dialog), test co-location, and separation of presentational components from business logic through dialog-based workflows.
+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.
 ## tags
 project, repositories, dialog, react, create, settings, icon, repository
 ## symbols
@@ -11,7 +11,7 @@ Provides UI components for managing development sessions including creation, lis
 - 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
 - session-progress-panel.tsx | Renders a panel displaying active and recently completed session operations with step-by-step progress indicators and dismissible notifications. | exp: func:SessionProgressPanel(), call:useSessionOperations, call:useEventContext, call:useEffect, call:updateOperationFromEvent, call:operations.filter, call:Date.now, call:visibleOperations.map, call:dismissOperation | dep: react, ../../../state/session-operations, ../../../state/events, ../../icon, useSessionOperations, useEventContext, Icon
 ## arch
-React component composition with feature-specific grouping, responsive design patterns (mobile/desktop layouts), and status-driven conditional rendering with delegated sub-components.
+Feature-based component architecture with compound component pattern (SessionCard/SessionList/SessionProgressPanel), controlled forms with validation, optimistic UI updates for inline editing, responsive design with mobile/desktop layout variants, and compound action menus using dropdowns/sheets.
 ## tags
 session, call:use, call:on, api, card, call:set, event, mobile
 ## symbols
@@ -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 across multiple categorized tabs.
+Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout.
 ## 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 across multiple categorized tabs.
+Provides the UI components for the application's settings interface, enabling users to configure preferences through a tabbed navigation layout.
 ## 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
 ## arch
-Tab-based layout using React Router outlet context for state sharing, with URL-driven navigation and sidebar-based tab switching pattern.
+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.
 ## 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 SSH key lifecycle management including creation and list operations with cryptographic signing/verification features.
+Provides UI components for managing SSH keys, 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,12 +4,12 @@ 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 SSH key lifecycle management including creation and list operations with cryptographic signing/verification features.
+Provides UI components for managing SSH keys, 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
 ## arch
-Feature-based component composition with form/list separation pattern, likely using React functional components with hooks for state management and API integration.
+Feature-based component organization with presentational components following single-responsibility pattern (form vs list separation).
 ## tags
 sshkey, form, list, create, ssh, icon, renders, keys
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/terminal

 ## role
-Provides cross-platform terminal UI components with session management, special key input, and WebSocket-backed xterm.js integration for web-based terminal emulation.
+Provides cross-platform terminal UI components for desktop and mobile with session management, special key input, and xterm.js WebSocket connectivity.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/components/features/terminal
 index: apps/web/src/components/features/terminal/.pi-map.index.md

 ## role
-Provides cross-platform terminal UI components with session management, special key input, and WebSocket-backed xterm.js integration for web-based terminal emulation.
+Provides cross-platform terminal UI components for desktop and mobile with session management, special key input, and xterm.js WebSocket connectivity.
 ## 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
@@ -14,7 +14,7 @@ Provides cross-platform terminal UI components with session management, special
 - 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 | React component that renders an interactive xterm.js terminal with WebSocket connectivity, mobile touch support, flow control, heartbeat monitoring, and reconnection logic. | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys, React, use-special-keys hook
 ## arch
-Feature-based component architecture with platform-specific view splitting (desktop/mobile), compound component pattern for terminal controls, custom hook-driven WebSocket/xterm.js integration with heartbeat/reconnection logic, and Jest-tested tabbed session management.
+Component-based architecture with platform-specific view variants (Desktop/Mobile), shared session tabs state management, modular special key input panels, and a core terminal component handling WebSocket lifecycle with heartbeat/reconnection logic.
 ## tags
 terminal, special, keys, session, react, tabs, view, renders
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/tool-workshop

 ## role
-Provides a complete CRUD interface for managing tool types in a "Tool Workshop" feature with desktop and mobile views
+Provides a complete UI for managing custom tool types in a "Tool Workshop" interface with list, edit, and mobile-responsive views.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md
@@ -4,13 +4,13 @@ dir: apps/web/src/components/features/tool-workshop
 index: apps/web/src/components/features/tool-workshop/.pi-map.index.md

 ## role
-Provides a complete CRUD interface for managing tool types in a "Tool Workshop" feature with desktop and mobile views
+Provides a complete UI for managing custom tool types in a "Tool Workshop" interface with list, edit, and mobile-responsive views.
 ## 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 view for managing tool types with list, detail, and edit modes | exp: MobileView, ToolWorkshopMobileView | dep: ../mobile/mobile-list-view, ../mobile/mobile-detail-view, ../mobile/mobile-edit-view, ../mobile/mobile-fab, ../../../api/tool-types, ./ToolTypeEditorPanel, MobileListView, MobileDetailView, MobileEditView, MobileFAB, ToolType, ToolTypeFormState
 ## arch
-Split-pane layout with sidebar list navigation, detail/edit panel, and mobile-responsive view switching using conditional rendering patterns
+Uses a split-pane sidebar/detail panel pattern with dedicated mobile breakpoint handling, separating list navigation from form editing concerns across three specialized view components.
 ## tags
 tool, mobile, type, view, types, list, panel, editor
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/tool

 ## role
-Provides UI components for managing containerized development tools, including instance lifecycle operations, manifest editing, and workspace-integrated tool launching.
+Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, 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,7 +4,7 @@ dir: apps/web/src/components/features/tool
 index: apps/web/src/components/features/tool/.pi-map.index.md

 ## role
-Provides UI components for managing containerized development tools, including instance lifecycle operations, manifest editing, and workspace-integrated tool launching.
+Provides React components for managing container-based development tools, including instance lifecycle, manifest editing, 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
@@ -13,7 +13,7 @@ Provides UI components for managing containerized development tools, including i
 - 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
 - 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 composition with modal/bottom-sheet navigation patterns, real-time status integration, and form-driven configuration management with preview capabilities.
+Feature-based component architecture with modal/sheet UI patterns, form-driven configuration editing, and workspace-contextual tool orchestration with mobile-responsive navigation.
 ## tags
 tool, call:set, types, call:use, api, start, ssh, icon
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/workspace

 ## role
-Provides React components for workspace UI features including creation, navigation, file management, Git integration, tool management, and settings display.
+Provides React UI components for workspace management, navigation, and detail views 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,7 +4,7 @@ dir: apps/web/src/components/features/workspace
 index: apps/web/src/components/features/workspace/.pi-map.index.md

 ## role
-Provides React components for workspace UI features including creation, navigation, file management, Git integration, tool management, and settings display.
+Provides React UI components for workspace management, navigation, and detail views in a web-based development environment.
 ## files
 - workspace-card.tsx | React card component that displays 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
@@ -13,11 +13,11 @@ Provides React components for workspace UI features including creation, navigati
 - 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-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 read-only workspace information in a settings panel on the workspace detail page. | exp: func:WorkspaceSettingsPanel({ workspace, }: WorkspaceSettingsPanelProps) | dep: ../../../types/workspace, react
+- 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
 ## arch
-Feature-based component composition with page-specific layout components (header, panels, tab bar) and functional sub-components, following a detail-page architecture with tabbed navigation and modal-based tool interactions.
+Feature-based component organization with page-specific composite components (header/detail/settings) and reusable atomic pieces (cards, chips, forms), following a panel/tab architecture for workspace detail layout.
 ## tags
 workspace, call:set, call:use, panel, git, branch, react, call:on
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/hooks

 ## role
-Provides reusable React custom hooks that encapsulate UI state management, side effects, API integrations, and domain-specific logic for the web application frontend.
+A collection of custom React hooks providing reusable state management, API integration, and UI behavior logic for the web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -20,7 +20,6 @@ map: apps/web/src/.pi-map.md
 - use-notifications.test.tsx
 - use-notifications.ts
 - use-projects.ts
- use-repo-workspace.ts
 - use-special-keys.ts
 - use-ssh-keys.ts
 - use-start-tool.ts
@@ -4,7 +4,7 @@ dir: apps/web/src/hooks
 index: apps/web/src/hooks/.pi-map.index.md

 ## role
-Provides reusable React custom hooks that encapsulate UI state management, side effects, API integrations, and domain-specific logic for the web application frontend.
+A collection of custom React hooks providing reusable state management, API integration, and UI behavior logic for the 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
@@ -17,7 +17,6 @@ Provides reusable React custom hooks that encapsulate UI state management, side
 - 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-repo-workspace.ts | A React custom hook that manages workspace state for a repository-based project, including loading project data, repositories, branches, git status, and tool types while synchronizing selection state with URL search parameters. | exp: Project, useRepoWorkspace | dep: react, react-router-dom, ../api/client, ../api/git-repositories, ../api/tool-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
@@ -32,9 +31,9 @@ Provides reusable React custom hooks that encapsulate UI state management, side
 - 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
 ## arch
-Layered utility hooks following React composition patterns, with separation between generic UI behavior hooks (async data, auto-hide, viewport, theme), infrastructure hooks (SSE, terminal, keyboard), and domain-specific data/operation hooks (workspace, git, SSH, projects, instances) that wrap API calls with loading/error states and optimistic updates.
+Follows a feature-based composition pattern where each hook encapsulates a specific domain concern (data fetching, CRUD operations, terminal/session management, UI interactions), often combining React state with API calls, side effects, and provider context integration.
 ## tags
-call:set, call:use, workspace, react, state, terminal, api, git
+call:set, call:use, workspace, react, state, terminal, api, callback
 ## symbols
 - useAsyncData
 - useAutoHide
@@ -2,7 +2,7 @@
 dir: apps/web/src/pages

 ## role
-Contains all top-level page components for the web application, serving as route endpoints that compose domain-specific UI for workspaces, projects, sessions, git, settings, and other core features.
+Contains top-level page components that serve as route endpoints for the web application, each rendering distinct feature areas of the developer workspace platform.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/pages
 index: apps/web/src/pages/.pi-map.index.md

 ## role
-Contains all top-level page components for the web application, serving as route endpoints that compose domain-specific UI for workspaces, projects, sessions, git, settings, and other core features.
+Contains top-level page components that serve as route endpoints for the web application, each rendering distinct feature areas of the developer workspace platform.
 ## files
 - ConfigProfilesPage.tsx | Renders a responsive configuration profiles management page with sidebar list and editor panel for desktop, and a dedicated mobile view for creating, editing, and managing 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
 - DashboardPage.test.tsx | Tests the DashboardPage (HomePage) component's rendering, loading states, and error handling with retry functionality | dep: @testing-library/jest-dom/vitest, @testing-library/react, react-router-dom, vitest, ./DashboardPage, ../state/sessions, ../state/session-operations, ../api/dashboard, ../api/sessions, ../api/projects, ../api/git-repositories, ../api/tool-types
@@ -25,7 +25,7 @@ Contains all top-level page components for the web application, serving as route
 - 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 separate mobile (list/detail/create views) and desktop (grid with cards) layouts, supporting CRUD operations and tool launching. | 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:workspaces.find, 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-list-view, ../components/features/mobile/mobile-detail-view, ../components/features/mobile/mobile-fab, ../components/features/tool/tool-starter, ../types/workspace
 ## arch
-Follows a page-based routing architecture with responsive mobile/desktop split layouts, tabbed navigation patterns, CRUD-heavy screens with polling/health checks, and test coverage for critical pages using API mocking.
+Follows a React Router-based page-level architecture with responsive dual-layout patterns (mobile/desktop), tabbed navigation, CRUD operations with API integration, polling mechanisms, and nested outlet routing for complex settings/workspace detail views.
 ## tags
 page, components, workspace, features, react, mobile, settings, hooks
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/state

 ## role
-Centralized React state management layer providing application-wide contexts for authentication, real-time events, notifications, session operations, user sessions, and toast notifications.
+Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,7 +4,7 @@ dir: apps/web/src/state
 index: apps/web/src/state/.pi-map.index.md

 ## role
-Centralized React state management layer providing application-wide contexts for authentication, real-time events, notifications, session operations, user sessions, and toast notifications.
+Centralized client-side state management layer providing React context providers for core application concerns including authentication, real-time data, notifications, background operations, and user feedback.
 ## 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
@@ -13,7 +13,7 @@ Centralized React state management layer providing application-wide contexts for
 - 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
 ## arch
-Context-based state architecture using React Context API with providers for dependency injection, combining optimistic updates, server polling, event-driven updates, and imperative APIs for cross-cutting concerns.
+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 like toast notifications.
 ## tags
 call:use, context, toast, provider, react, call:set, notification, operations
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/styles

 ## role
-Houses the complete CSS styling system for a web application, providing global styles, design tokens, syntax highlighting, and utility classes.
+Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, syntax highlighting, and utility classes.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/web/src/styles
 index: apps/web/src/styles/.pi-map.index.md

 ## role
-Houses the complete CSS styling system for a web application, providing global styles, design tokens, syntax highlighting, and utility classes.
+Provides the complete visual design system and styling foundation for the web application, encompassing global styles, theme tokens, syntax highlighting, and utility classes.
 ## 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 responsive CSS utility system including layout primitives, mobile-first breakpoints, terminal styling, session management UI, and touch-target accessibility patterns for a web application. | dep: CSS custom properties (var(--space-*), var(--border), var(--bg), var(--primary), var(--danger), etc.), xterm.js (terminal rendering)
 ## arch
-Layered CSS architecture using design tokens (tokens.css), global base styles (global.css), component-specific styles (syntax-highlight.css), and utility-first responsive utilities (utilities.css) with light/dark theme support and mobile-first breakpoints.
+CSS custom properties-based design token architecture with light/dark theme support, mobile-first responsive breakpoint system, utility-first CSS patterns, and modular separation of concerns across global, component-specific, token, and utility layers.
 ## tags
 space, var(, global, css, web, application, syntax, defines
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/styles/pages

 ## role
-Contains page-specific CSS stylesheets for distinct application views in the web frontend.
+Contains page-specific CSS stylesheets for individual application views in the web frontend.
 ## parent
 index: apps/web/src/styles/.pi-map.index.md
 map: apps/web/src/styles/.pi-map.md
@@ -11,7 +11,6 @@ map: apps/web/src/styles/.pi-map.md
 ## files
 - git-history.css
 - projects.css
- repo-workspace.css
 - sessions.css
 - ssh-keys.css
 - workspace-detail.css
@@ -4,19 +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 distinct application views in the web frontend.
+Contains page-specific CSS stylesheets for individual application views in the web frontend.
 ## 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)
- repo-workspace.css | Stylesheet for a repository workspace UI with git integration, file management, and code editing components | dep: CSS custom properties (variables), IBM Plex Mono font
 - 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 page featuring a responsive grid of workspace cards with status badges, hover effects, and mobile adaptations. | dep: CSS custom properties (var(--space-*), var(--border), var(--panel), var(--muted), var(--success), var(--warning), var(--danger))
 ## arch
-Modular page-scoped styling architecture with responsive design patterns (mobile-first breakpoints, grid/flex layouts, component-based organization) and consistent UI system conventions (cards, tabs, forms, badges, hover states).
+Modular page-scoped styling using dedicated CSS files per route/page, with responsive design patterns (mobile-first breakpoints, grid/flex layouts) and component-oriented class naming.
 ## tags
-var(, workspace, stylesheet, git, space, page, detail, history
+var(, workspace, stylesheet, space, git, page, detail, history
 ## symbols
 -
 ## workflows
@@ -8,7 +8,7 @@ Provides shared 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
 ## arch
-Minimal utility module pattern - single configuration file exporting Vitest setup with Jest DOM matchers integration
+Minimal utility layer using Vitest with Jest DOM matchers for browser-like DOM assertion capabilities
 ## tags
 dom, vitest, jest, setup, configures, testing, environment, matchers
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/types

 ## role
-Defines shared TypeScript type definitions and interfaces for data models used across the web application.
+Provides shared TypeScript type definitions for event-driven communication and workspace management 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
-Defines shared TypeScript type definitions and interfaces for data models used across the web application.
+Provides shared TypeScript type definitions for event-driven communication and workspace management 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
 - workspace.ts | Defines TypeScript interfaces for workspace data models, requests, and sync results in a workspace management feature. | exp: Workspace, CreateWorkspaceRequest, SyncResult
 ## arch
-Simple barrel-style type package with domain-oriented interface modules (events, workspace) for compile-time type safety and API contract enforcement.
+Pure type declaration layer using TypeScript interfaces for compile-time contracts, with no runtime logic or dependencies.
 ## tags
 workspace, event, instance, metadata, payload, sync, defines, typescript
 ## symbols
@@ -2,7 +2,7 @@
 dir: apps/web/src/utils

 ## role
-Shared utility functions providing cross-cutting concerns for error handling, icon types, syntax highlighting, and time formatting across the web application.
+Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative time formatting across the web application.
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md
@@ -4,14 +4,14 @@ dir: apps/web/src/utils
 index: apps/web/src/utils/.pi-map.index.md

 ## role
-Shared utility functions providing cross-cutting concerns for error handling, icon types, syntax highlighting, and time formatting across the web application.
+Provides shared utility functions for error handling, icon type definitions, syntax highlighting language mapping, and relative 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
 ## arch
-Flat barrel-style utility module with pure functions, lazy loading for heavy dependencies (Prism), and thin abstraction layers over third-party libraries.
+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.
 ## tags
 time, language, error, message, errors, string, relative, human
 ## symbols